diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 7324baa1d3..92c8b47456 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -197,16 +197,45 @@ jobs:
 
       - uses: swatinem/rust-cache@v2
         with:
-          shared-key: "ci-check-v3-${{ runner.os }}-no-cargo-bin-v1"
+          shared-key: "ci-check-v5-${{ runner.os }}-no-cargo-bin-v1"
           cache-bin: false
           # PR caches are scoped to merge refs; trusted main pushes own shared
           # refreshes and retain completed dependency builds after late test failures.
           save-if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
           cache-on-failure: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
 
+      # rust-cache prunes the workspace target directory before saving it, so
+      # native libraries stored under target need an independent cache lifecycle.
+      - name: Restore Sherpa native libraries
+        id: sherpa-native-cache
+        uses: actions/cache/restore@v5
+        with:
+          path: target/sherpa-onnx-prebuilt
+          key: sherpa-onnx-v1-${{ runner.os }}-${{ runner.arch }}-1.13.4-static
+
+      - name: Repair missing Sherpa native state
+        shell: bash
+        run: |
+          if ! find target/sherpa-onnx-prebuilt -type f \
+            \( -name 'sherpa-onnx-c-api.lib' -o -name 'libsherpa-onnx-c-api.a' \) \
+            -print -quit 2>/dev/null | grep -q .; then
+            rm -rf target/sherpa-onnx-prebuilt
+            cargo clean -p sherpa-onnx-sys
+          fi
+
       - name: Check compilation
         run: cargo check --locked --workspace
 
+      - name: Save Sherpa native libraries
+        if: >-
+          github.event_name == 'push' &&
+          github.ref == 'refs/heads/main' &&
+          steps.sherpa-native-cache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v5
+        with:
+          path: target/sherpa-onnx-prebuilt
+          key: sherpa-onnx-v1-${{ runner.os }}-${{ runner.arch }}-1.13.4-static
+
       # The installer is intentionally excluded from the root Cargo workspace,
       # so the workspace check above cannot catch drift in its shared Rust APIs.
       - name: Check installer compilation
@@ -249,6 +278,61 @@ jobs:
       - name: Run search tool tests
         run: "cargo test --locked -p tool-runtime --lib search::"
 
+  # ── DeepSeek Harness bridge: profile packaging on Windows ──────────
+  # `prepare:dsh-profile` runs from `frontend:build-all` / official desktop
+  # packaging, not from desktop:dev or cargo check. Until this job existed,
+  # its first Windows execution ever was a release build, and it failed there
+  # (`spawnSync npm ENOENT`: npm is a `.cmd` shim Node will not spawn without
+  # a shell). This job is the cheapest thing that exercises the whole
+  # packaging path — npm install, tsc, `npm pack`, tar, tree copy — on the
+  # platform whose path and process rules differ.
+  dsh-profile-windows:
+    name: DSH Profile Packaging (windows-latest)
+    runs-on: windows-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version-file: package.json
+          package-manager-cache: false
+
+      - name: Build the bridge profile
+        run: node scripts/prepare-dsh-profile.mjs
+
+      - name: Verify the profile is complete and stamped
+        shell: bash
+        run: |
+          set -euo pipefail
+          root=packages/dsh-acp/dist-profile
+          for path in \
+            "$root/.bitfun-bridge.json" \
+            "$root/cordis.patch.yml" \
+            "$root/package.json" \
+            "$root/lib/app.js" \
+            "$root/node_modules/@agentclientprotocol/sdk/package.json" \
+            "$root/node_modules/@deepseek-ai/dsh-agent-spine-demo/package.json"
+          do
+            [ -f "$path" ] || { echo "::error::missing $path"; exit 1; }
+          done
+          # A vendored tree copied with a broken separator filter drags
+          # node_modules along; the profile resolves those from the user's own
+          # dsh installation and must ship none of its own beyond the two above.
+          nested=$(find "$root/lib" "$root/presets" -name node_modules -o -name '*.map' || true)
+          if [ -n "$nested" ]; then
+            echo "::error::profile carries files it must not ship:"
+            echo "$nested"
+            exit 1
+          fi
+          node -e '
+            const stamp = require("./packages/dsh-acp/dist-profile/.bitfun-bridge.json");
+            if (stamp.profile !== "bitfun-acp") throw new Error("wrong profile name: " + stamp.profile);
+            if (!/^[0-9a-f]{64}$/.test(stamp.content)) throw new Error("no content digest");
+            process.stdout.write(`profile ${stamp.profile} @ ${stamp.bridge}, min dsh ${stamp.minDshVersion}\n`);
+          '
+
   # ── Frontend: build ────────────────────────────────────────────────
   frontend-build:
     name: Frontend Build
@@ -306,6 +390,9 @@ jobs:
       - name: Validate theme visual governance contract
         run: pnpm run theme:visual-contract
 
+      - name: Validate WebKit compatibility gate
+        run: pnpm run verify:webkit-compatibility:test
+
       - name: Lint web UI
         run: pnpm run lint:web
 
diff --git a/.github/workflows/desktop-package.yml b/.github/workflows/desktop-package.yml
index 27c5af5b03..a88dd8401c 100644
--- a/.github/workflows/desktop-package.yml
+++ b/.github/workflows/desktop-package.yml
@@ -7,9 +7,21 @@ on:
   workflow_dispatch:
     inputs:
       tag_name:
-        description: "Tag name to build (e.g. v0.2.0). Leave empty to build from HEAD."
+        description: "Release tag (stable: v0.2.18, beta: v0.2.18-beta.1)."
         required: false
         type: string
+      checkout_ref:
+        description: "Commit, branch, or tag to build. Defaults to tag_name, then HEAD."
+        required: false
+        type: string
+      release_channel:
+        description: "Immutable update channel compiled into the Desktop artifact."
+        required: false
+        default: stable
+        type: choice
+        options:
+          - stable
+          - beta
       upload_to_release:
         description: "Upload built artifacts to the release specified by tag_name."
         required: false
@@ -26,8 +38,8 @@ permissions:
   packages: write
 
 concurrency:
-  group: desktop-package-${{ github.event.release.tag_name || inputs.tag_name || github.sha }}
-  cancel-in-progress: true
+  group: desktop-package-${{ (github.event.release.prerelease || inputs.release_channel == 'beta') && 'beta' || github.event.release.tag_name || inputs.tag_name || github.sha }}
+  cancel-in-progress: false
 
 jobs:
   # ── Resolve version info ───────────────────────────────────────────
@@ -39,9 +51,12 @@ jobs:
       release_tag: ${{ steps.meta.outputs.release_tag }}
       upload_to_release: ${{ steps.meta.outputs.upload_to_release }}
       checkout_ref: ${{ steps.meta.outputs.checkout_ref }}
+      release_channel: ${{ steps.meta.outputs.release_channel }}
       relay_image_only: ${{ steps.meta.outputs.relay_image_only }}
     steps:
       - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
 
       - name: Resolve version metadata
         id: meta
@@ -51,6 +66,8 @@ jobs:
           GITHUB_SHA: ${{ github.sha }}
           RELEASE_TAG_NAME: ${{ github.event.release.tag_name }}
           INPUT_TAG_NAME: ${{ inputs.tag_name }}
+          INPUT_CHECKOUT_REF: ${{ inputs.checkout_ref }}
+          INPUT_RELEASE_CHANNEL: ${{ inputs.release_channel }}
           INPUT_UPLOAD_TO_RELEASE: ${{ inputs.upload_to_release }}
           INPUT_RELAY_IMAGE_ONLY: ${{ inputs.relay_image_only }}
         run: |
@@ -61,13 +78,21 @@ jobs:
             VERSION="${TAG#v}"
             UPLOAD="true"
             CHECKOUT_REF="${TAG}"
+            if [[ "${{ github.event.release.prerelease }}" == "true" ]]; then
+              CHANNEL="beta"
+            else
+              CHANNEL="stable"
+            fi
           elif [[ -n "${INPUT_TAG_NAME}" ]]; then
             TAG="${INPUT_TAG_NAME}"
             VERSION="${TAG#v}"
+            CHANNEL="${INPUT_RELEASE_CHANNEL:-stable}"
             # A one-off image backfill must use the workflow branch: an older
             # tag does not contain Dockerfile.release or this publishing job.
             if [[ "${INPUT_RELAY_IMAGE_ONLY}" == "true" ]]; then
               CHECKOUT_REF="${GITHUB_SHA}"
+            elif [[ -n "${INPUT_CHECKOUT_REF}" ]]; then
+              CHECKOUT_REF="${INPUT_CHECKOUT_REF}"
             else
               CHECKOUT_REF="${TAG}"
             fi
@@ -81,12 +106,32 @@ jobs:
             TAG="v${VERSION}"
             UPLOAD="false"
             CHECKOUT_REF="${GITHUB_SHA}"
+            CHANNEL="${INPUT_RELEASE_CHANNEL:-stable}"
+          fi
+
+          node --input-type=module -e \
+            "import { validateReleaseVersion } from './scripts/release-channel.mjs'; validateReleaseVersion(process.argv[1], process.argv[2]);" \
+            "${CHANNEL}" "${VERSION}"
+
+          git fetch origin main --tags --force
+          CHECKOUT_SHA="$(git rev-parse "${CHECKOUT_REF}^{commit}")"
+          if [[ "${GITHUB_REPOSITORY}" == "GCWing/BitFun" ]] && \
+             ! git merge-base --is-ancestor "${CHECKOUT_SHA}" origin/main; then
+            echo "Ref ${CHECKOUT_REF} (${CHECKOUT_SHA}) is not part of the protected main history." >&2
+            exit 1
           fi
+          TAG_SHA="$(git rev-parse --verify --quiet "${TAG}^{commit}" || true)"
+          if [[ -n "${TAG_SHA}" && "${TAG_SHA}" != "${CHECKOUT_SHA}" ]]; then
+            echo "Existing tag ${TAG} points to ${TAG_SHA}, not requested commit ${CHECKOUT_SHA}." >&2
+            exit 1
+          fi
+          CHECKOUT_REF="${CHECKOUT_SHA}"
 
           echo "version=$VERSION"          >> "$GITHUB_OUTPUT"
           echo "release_tag=$TAG"          >> "$GITHUB_OUTPUT"
           echo "upload_to_release=$UPLOAD" >> "$GITHUB_OUTPUT"
           echo "checkout_ref=$CHECKOUT_REF" >> "$GITHUB_OUTPUT"
+          echo "release_channel=$CHANNEL"  >> "$GITHUB_OUTPUT"
           echo "relay_image_only=${INPUT_RELAY_IMAGE_ONLY:-false}" >> "$GITHUB_OUTPUT"
 
   # ── Build per platform ─────────────────────────────────────────────
@@ -98,12 +143,14 @@ jobs:
     env:
       NODE_OPTIONS: --max-old-space-size=6144
       BITFUN_ENABLE_UPDATER_ARTIFACTS: ${{ needs.prepare.outputs.upload_to_release }}
-      TAURI_UPDATER_ENDPOINT: https://github.com/GCWing/BitFun/releases/latest/download/latest.json
+      BITFUN_RELEASE_CHANNEL: ${{ needs.prepare.outputs.release_channel }}
+      TAURI_UPDATER_ENDPOINT: ${{ github.repository != 'GCWing/BitFun' && needs.prepare.outputs.release_channel == 'beta' && format('https://github.com/{0}/releases/download/channel-beta/latest.json', github.repository) || '' }}
+      TAURI_UPDATER_FALLBACK_ENDPOINT: ${{ github.repository != 'GCWing/BitFun' && needs.prepare.outputs.release_channel == 'beta' && format('https://github.com/{0}/releases/download/channel-beta/latest.json', github.repository) || '' }}
       TAURI_UPDATER_PUBKEY: ${{ secrets.TAURI_UPDATER_PUBKEY }}
       # Same trust root, compiled into the Desktop binary so one-click relay
       # deploy can verify the signed checksum locally and hand the remote host
       # a hash it does not have to trust the mirror for.
-      BITFUN_RELEASE_PUBKEY: ${{ secrets.TAURI_UPDATER_PUBKEY }}
+      BITFUN_RELEASE_PUBKEY: ${{ secrets.BITFUN_RELEASE_PUBKEY || secrets.TAURI_UPDATER_PUBKEY }}
       TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
       TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
 
@@ -233,12 +280,35 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Configure Apple Developer ID signing and notarization
+        if: runner.os == 'macOS'
+        shell: bash
+        env:
+          APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
+          APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
+          APPLE_SIGNING_IDENTITY: ${{ secrets.APPLE_SIGNING_IDENTITY }}
+          APPLE_API_ISSUER: ${{ secrets.APPLE_API_ISSUER }}
+          APPLE_API_KEY: ${{ secrets.APPLE_API_KEY }}
+          APPLE_API_PRIVATE_KEY: ${{ secrets.APPLE_API_PRIVATE_KEY }}
+          KEYCHAIN_PASSWORD: ${{ secrets.KEYCHAIN_PASSWORD }}
+          BITFUN_REQUIRE_APPLE_SIGNING: ${{ needs.prepare.outputs.upload_to_release }}
+        run: bash scripts/ci/setup-macos-signing.sh
+
+      - name: Project beta build version
+        if: needs.prepare.outputs.release_channel == 'beta'
+        run: node scripts/set-build-version.mjs --version "${{ needs.prepare.outputs.version }}"
+
       - name: Verify release version metadata
         run: node scripts/verify-release-version-sync.mjs --version "${{ needs.prepare.outputs.version }}"
 
       - name: Build desktop app
         run: ${{ matrix.platform.build_command }}
 
+      - name: Verify Apple signature and notarization
+        if: runner.os == 'macOS'
+        shell: bash
+        run: bash scripts/ci/verify-macos-signing.sh "${{ matrix.platform.target }}"
+
       - name: Verify AppImage fcitx5 GTK module
         if: runner.os == 'Linux'
         shell: bash
@@ -258,7 +328,9 @@ jobs:
   linux-binaries:
     name: Linux CLI and Relay Server
     needs: prepare
-    if: needs.prepare.outputs.relay_image_only != 'true'
+    if: >-
+      needs.prepare.outputs.relay_image_only != 'true' &&
+      needs.prepare.outputs.release_channel == 'stable'
     uses: ./.github/workflows/linux-binaries.yml
     secrets:
       release_signing_key: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
@@ -276,7 +348,8 @@ jobs:
     needs: [prepare, linux-binaries]
     if: >-
       always() &&
-      (needs.prepare.outputs.upload_to_release == 'true' ||
+      ((needs.prepare.outputs.upload_to_release == 'true' &&
+        needs.prepare.outputs.release_channel == 'stable') ||
        needs.prepare.outputs.relay_image_only == 'true') &&
       (needs.prepare.outputs.relay_image_only == 'true' ||
        needs.linux-binaries.result == 'success')
@@ -348,7 +421,7 @@ jobs:
           RELEASE_TAG: ${{ needs.prepare.outputs.release_tag }}
           RELEASE_VERSION: ${{ needs.prepare.outputs.version }}
           IMAGE_ONLY: ${{ needs.prepare.outputs.relay_image_only }}
-          RELEASE_PRERELEASE: ${{ github.event.release.prerelease }}
+          RELEASE_CHANNEL: ${{ needs.prepare.outputs.release_channel }}
         run: |
           set -euo pipefail
           asset_version="${RELEASE_VERSION%%+*}"
@@ -363,7 +436,7 @@ jobs:
               if [[ "${RELEASE_TAG}" == "${latest_release}" ]]; then
                 echo "${IMAGE}:latest"
               fi
-            elif [[ "${RELEASE_PRERELEASE:-false}" != "true" ]]; then
+            elif [[ "${RELEASE_CHANNEL}" == "stable" ]]; then
               # The normal release workflow can create the GitHub Release only
               # after packaging, so it cannot rely on /releases/latest yet.
               echo "${IMAGE}:latest"
@@ -469,8 +542,9 @@ jobs:
       always() &&
       needs.prepare.outputs.upload_to_release == 'true' &&
       needs.package.result == 'success' &&
-      needs.linux-binaries.result == 'success' &&
-      needs.publish-relay-image.result == 'success'
+      (needs.prepare.outputs.release_channel == 'beta' ||
+       (needs.linux-binaries.result == 'success' &&
+        needs.publish-relay-image.result == 'success'))
     runs-on: ubuntu-latest
     env:
       REQUIRED_UPDATER_PLATFORMS: windows-x86_64,darwin-x86_64,darwin-aarch64,linux-x86_64,linux-aarch64
@@ -487,6 +561,7 @@ jobs:
           merge-multiple: true
 
       - name: Download Linux binary artifacts
+        if: needs.prepare.outputs.release_channel == 'stable'
         uses: actions/download-artifact@v7
         with:
           pattern: bitfun-linux-${{ needs.prepare.outputs.release_tag }}-*
@@ -494,19 +569,24 @@ jobs:
           merge-multiple: true
 
       - name: Download Relay image descriptor
+        if: needs.prepare.outputs.release_channel == 'stable'
         uses: actions/download-artifact@v7
         with:
           name: bitfun-relay-image-${{ needs.prepare.outputs.release_tag }}
           path: relay-image-assets
 
       - name: List release assets
+        env:
+          RELEASE_CHANNEL: ${{ needs.prepare.outputs.release_channel }}
         run: |
           echo "Release assets:"
           find release-assets -type f | sort
-          echo "Linux CLI and Relay Server assets:"
-          find linux-release-assets -type f | sort
-          echo "Relay image descriptor:"
-          find relay-image-assets -type f | sort
+          if [[ "${RELEASE_CHANNEL}" == "stable" ]]; then
+            echo "Linux CLI and Relay Server assets:"
+            find linux-release-assets -type f | sort
+            echo "Relay image descriptor:"
+            find relay-image-assets -type f | sort
+          fi
 
       - name: Prepare versioned Windows installer
         run: |
@@ -538,7 +618,7 @@ jobs:
             --manual-assets-dir release-manual-assets \
             --version "${{ needs.prepare.outputs.version }}" \
             --tag "${{ needs.prepare.outputs.release_tag }}" \
-            --repo "GCWing/BitFun" \
+            --repo "${{ github.repository }}" \
             --out release-updater-assets/latest.json \
             --required-platforms "${REQUIRED_UPDATER_PLATFORMS}"
 
@@ -551,6 +631,7 @@ jobs:
             --required-manual-platforms "windows-x86_64"
 
       - name: Generate Linux binaries manifest
+        if: needs.prepare.outputs.release_channel == 'stable'
         run: |
           node scripts/generate-linux-binaries-manifest.mjs \
             --assets-dir linux-release-assets \
@@ -586,9 +667,11 @@ jobs:
 
           # Publish the public key alongside the signatures: a signature nobody
           # can fetch a key for is not verifiable.
-          printf '%s' "${BITFUN_SIGNING_PUBKEY}" | base64 -d >release-assets/minisign.pub
+          node scripts/write-minisign-public-key.mjs \
+            --out release-assets/minisign.pub
 
-      - name: Stage uniquely named release assets
+      - name: Stage stable release assets
+        if: needs.prepare.outputs.release_channel == 'stable'
         shell: bash
         run: |
           set -euo pipefail
@@ -617,10 +700,34 @@ jobs:
             relay-image-assets/relay-image.json \
             relay-image-assets/relay-image.json.sig
 
+      - name: Stage beta release assets
+        if: needs.prepare.outputs.release_channel == 'beta'
+        shell: bash
+        run: |
+          set -euo pipefail
+          shopt -s globstar
+          node scripts/stage-github-release-assets.mjs \
+            --out-dir release-upload-assets \
+            release-updater-assets/* \
+            release-manual-assets/*.exe \
+            release-manual-assets/*.exe.sig \
+            release-assets/**/*.AppImage \
+            release-assets/**/*.AppImage.sig \
+            release-assets/**/*.deb \
+            release-assets/**/*.deb.sig \
+            release-assets/**/*.dmg \
+            release-assets/**/*.dmg.sig \
+            release-assets/**/*.rpm \
+            release-assets/**/*.rpm.sig \
+            release-assets/minisign.pub
+
       - name: Upload to release
         uses: softprops/action-gh-release@v3
         with:
           tag_name: ${{ needs.prepare.outputs.release_tag }}
+          target_commitish: ${{ needs.prepare.outputs.checkout_ref }}
+          prerelease: ${{ needs.prepare.outputs.release_channel == 'beta' }}
+          name: ${{ needs.prepare.outputs.release_channel == 'beta' && format('BitFun {0} Beta', needs.prepare.outputs.version) || format('BitFun {0}', needs.prepare.outputs.version) }}
           generate_release_notes: true
           files: release-upload-assets/*
           fail_on_unmatched_files: true
@@ -628,7 +735,7 @@ jobs:
       - name: Verify published updater manifest
         run: |
           curl -fsSL --retry 5 --retry-delay 3 \
-            "https://github.com/GCWing/BitFun/releases/download/${{ needs.prepare.outputs.release_tag }}/latest.json" \
+            "https://github.com/${{ github.repository }}/releases/download/${{ needs.prepare.outputs.release_tag }}/latest.json" \
             -o latest.published.json
           node scripts/verify-tauri-latest-json.mjs \
             --manifest latest.published.json \
@@ -638,6 +745,7 @@ jobs:
             --check-urls true
 
       - name: Verify published Linux binaries manifest
+        if: needs.prepare.outputs.release_channel == 'stable'
         run: |
           curl -fsSL --retry 5 --retry-delay 3 \
             "https://github.com/GCWing/BitFun/releases/download/${{ needs.prepare.outputs.release_tag }}/linux-binaries.json" \
@@ -649,6 +757,7 @@ jobs:
           done < <(jq -r '.platforms[].cli.url' linux-binaries.published.json)
 
       - name: Verify published Relay image descriptor
+        if: needs.prepare.outputs.release_channel == 'stable'
         run: |
           curl -fsSL --retry 5 --retry-delay 3 \
             "https://github.com/GCWing/BitFun/releases/download/${{ needs.prepare.outputs.release_tag }}/relay-image.json" \
@@ -660,16 +769,88 @@ jobs:
             "https://github.com/GCWing/BitFun/releases/download/${{ needs.prepare.outputs.release_tag }}/relay-image.json.sig" \
             -o /dev/null
 
+      - name: Resolve beta channel promotion
+        id: beta-channel
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_CHANNEL: ${{ needs.prepare.outputs.release_channel }}
+        run: |
+          set -euo pipefail
+          channel_status="$(curl -sS --retry 5 --retry-delay 3 \
+            --output channel.release.json \
+            --write-out '%{http_code}' \
+            -H "Authorization: Bearer ${GH_TOKEN}" \
+            -H 'Accept: application/vnd.github+json' \
+            -H 'X-GitHub-Api-Version: 2022-11-28' \
+            "https://api.github.com/repos/${GITHUB_REPOSITORY}/releases/tags/channel-beta")"
+          case "${channel_status}" in
+            200)
+              echo "channel_exists=true" >>"$GITHUB_OUTPUT"
+              curl -fsSL --retry 5 --retry-delay 3 \
+                "https://github.com/${GITHUB_REPOSITORY}/releases/download/channel-beta/latest.json" \
+                -o current.beta.json
+              ;;
+            404)
+              echo "channel_exists=false" >>"$GITHUB_OUTPUT"
+              if [[ "${RELEASE_CHANNEL}" == "stable" ]]; then
+                echo "promote=false" >>"$GITHUB_OUTPUT"
+                echo "No beta channel exists; stable release does not need to create one."
+                exit 0
+              fi
+              ;;
+            *)
+              echo "Could not inspect channel-beta release (GitHub API returned ${channel_status})." >&2
+              exit 1
+              ;;
+          esac
+          args=(--candidate latest.published.json --github-output "$GITHUB_OUTPUT")
+          if [[ -s current.beta.json ]]; then
+            args+=(--current current.beta.json)
+          fi
+          node scripts/plan-channel-promotion.mjs "${args[@]}"
+
+      - name: Publish beta channel manifest
+        if: steps.beta-channel.outputs.promote == 'true'
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+          CHECKOUT_REF: ${{ needs.prepare.outputs.checkout_ref }}
+          CHANNEL_EXISTS: ${{ steps.beta-channel.outputs.channel_exists }}
+        run: |
+          set -euo pipefail
+          if [[ "${CHANNEL_EXISTS}" != "true" ]]; then
+            gh release create channel-beta \
+              --repo "${GITHUB_REPOSITORY}" \
+              --target "${CHECKOUT_REF}" \
+              --prerelease \
+              --title "BitFun Beta Update Channel" \
+              --notes "Mutable updater pointer. Installable beta releases use immutable version tags."
+          fi
+          mkdir -p beta-channel
+          cp latest.published.json beta-channel/latest.json
+          gh release upload channel-beta beta-channel/latest.json \
+            --repo "${GITHUB_REPOSITORY}" \
+            --clobber
+          curl -fsSL --retry 5 --retry-delay 3 \
+            "https://github.com/${GITHUB_REPOSITORY}/releases/download/channel-beta/latest.json" \
+            -o channel-beta.published.json
+          test "$(jq -r '.version' channel-beta.published.json)" = \
+            "${{ steps.beta-channel.outputs.candidate_version }}"
+
       # Nudge the openbitfun.com mirror to sync now instead of on its next
       # 10-minute cron tick. Until the mirror has these bytes, CN clients have
       # only the GitHub origin to fall back to. Best effort: the cron run is
       # still the source of truth, so a failed or unconfigured ping never fails
-      # the release. Receiver setup: scripts/openbitfun-release-sync.sh.
+      # the release. Receiver: scripts/openbitfun-release-sync.sh.
+      # Host restore: deploy/openbitfun-host/README.md.
       - name: Request openbitfun mirror sync
+        if: github.repository == 'GCWing/BitFun'
         continue-on-error: true
         env:
           SYNC_WEBHOOK_URL: ${{ secrets.OPENBITFUN_SYNC_WEBHOOK_URL }}
           RELEASE_TAG: ${{ needs.prepare.outputs.release_tag }}
+          RELEASE_CHANNEL: ${{ needs.prepare.outputs.release_channel }}
         run: |
           set -euo pipefail
           if [[ -z "${SYNC_WEBHOOK_URL:-}" ]]; then
@@ -678,6 +859,6 @@ jobs:
           fi
           curl -fsSL -X POST --retry 3 --retry-delay 5 --max-time 30 \
             -H 'Content-Type: application/json' \
-            -d "{\"tag\":\"${RELEASE_TAG}\"}" \
+            -d "{\"tag\":\"${RELEASE_TAG}\",\"channel\":\"${RELEASE_CHANNEL}\"}" \
             "${SYNC_WEBHOOK_URL}" >/dev/null
           echo "Mirror sync requested for ${RELEASE_TAG}."
diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml
index 2af1483c06..e80dd0751b 100644
--- a/.github/workflows/nightly.yml
+++ b/.github/workflows/nightly.yml
@@ -68,6 +68,11 @@ jobs:
     if: needs.check-changes.outputs.should_build == 'true'
     env:
       NODE_OPTIONS: --max-old-space-size=6144
+      BITFUN_RELEASE_CHANNEL: nightly
+      # Nightly does not publish a Tauri latest.json feed yet. Preserve its
+      # existing stable updater endpoints until that publishing path exists.
+      TAURI_UPDATER_ENDPOINT: https://github.com/GCWing/BitFun/releases/latest/download/latest.json
+      TAURI_UPDATER_FALLBACK_ENDPOINT: https://openbitfun.com/release/latest.json
       # Nightly relay archives are signed too (linux-binaries.yml receives the
       # key), so nightly Desktop needs the same trust root to verify them.
       BITFUN_RELEASE_PUBKEY: ${{ secrets.TAURI_UPDATER_PUBKEY }}
@@ -176,28 +181,8 @@ jobs:
           set -euo pipefail
 
           echo "Patching version to $NIGHTLY_VERSION"
-
-          # Patch package.json
-          node -e "
-            const fs = require('fs');
-            const pkg = JSON.parse(fs.readFileSync('package.json', 'utf-8'));
-            pkg.version = process.env.NIGHTLY_VERSION.split('+')[0];
-            fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\n');
-            for (const file of ['BitFun-Installer/package.json', 'BitFun-Installer/package-lock.json']) {
-              const data = JSON.parse(fs.readFileSync(file, 'utf-8'));
-              data.version = pkg.version;
-              if (data.packages?.['']) data.packages[''].version = pkg.version;
-              fs.writeFileSync(file, JSON.stringify(data, null, 2) + '\n');
-            }
-          "
-
-          # Patch Cargo workspace version (semver: nightly suffix uses hyphen)
-          # Cargo.toml only accepts: MAJOR.MINOR.PATCH or MAJOR.MINOR.PATCH-PRE
-          CARGO_VERSION="$(echo "$NIGHTLY_VERSION" | sed 's/+.*//')"
-          sed -i.bak "s/^version = \".*\" # x-release-please-version/version = \"${CARGO_VERSION}\" # x-release-please-version/" Cargo.toml
-          rm -f Cargo.toml.bak
-          sed -i.bak "0,/^version = \".*\"/s//version = \"${CARGO_VERSION}\"/" BitFun-Installer/src-tauri/Cargo.toml
-          rm -f BitFun-Installer/src-tauri/Cargo.toml.bak
+          ASSET_VERSION="${NIGHTLY_VERSION%%+*}"
+          node scripts/set-build-version.mjs --version "$ASSET_VERSION"
 
           echo "package.json version: $(jq -r '.version' package.json)"
           echo "Cargo.toml version:   $(grep 'x-release-please-version' Cargo.toml)"
@@ -466,7 +451,8 @@ jobs:
 
           # Publish the public key alongside the signatures: a signature nobody
           # can fetch a key for is not verifiable.
-          printf '%s' "${BITFUN_SIGNING_PUBKEY}" | base64 -d >release-assets/minisign.pub
+          node scripts/write-minisign-public-key.mjs \
+            --out release-assets/minisign.pub
 
       - name: Create nightly release
         uses: softprops/action-gh-release@v3
diff --git a/.gitignore b/.gitignore
index 95806da18c..6b2f0197e4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -22,6 +22,8 @@ dist-ssr
 
 # Build outputs - Rust/Tauri
 target/
+sdk/typescript/src/internal/wire/
+sdk/typescript/src/internal/wire-validators.ts
 **/target/
 /.targets/
 # The deployable Rust services use the workspace lockfile for reproducible
diff --git a/AGENTS-CN.md b/AGENTS-CN.md
index 093cce57d1..3bf286f4fc 100644
--- a/AGENTS-CN.md
+++ b/AGENTS-CN.md
@@ -12,7 +12,7 @@ BitFun 是一个由 Rust workspace 与 React 前端组成的项目。
 2. 日常开发使用下方主要产品循环；surface 专属的替代命令由最近的应用指南维护。
 3. 修改 Rust 文件后，优先使用 `pnpm run fmt:rs`，只格式化已改动或已暂存的 `.rs` 文件。只有在你明确需要更大范围格式化时才使用 `cargo fmt`。
 4. 改完后从离改动最近的 `AGENTS.md` 选择 focused 验证命令；下方仓库级验证章节只维护跨模块检查原则。
-5. Rust workspace 依赖应在根清单中统一版本，而由消费 crate 按自身职责声明所需 feature；仅测试所需的 feature 应放入 `dev-dependencies`，受 crate feature 控制的服务能力应只在对应 feature 中启用。禁止使用 `tokio/full` 绕过依赖边界设计。
+5. Rust workspace 依赖应在根清单中统一版本，而由消费 crate 按自身职责声明所需 feature；仅测试所需的 feature 应放入 `dev-dependencies`，受 crate feature 控制的服务能力应只在对应 feature 中启用。第三方依赖的默认 feature 若不是所有 consumer 的稳定契约，应在 `[workspace.dependencies]` 统一关闭，成员只增加自身需要的切片。仓内 crate 的 `default` 已由边界契约保证为空时，不在每条依赖边重复写 `default-features = false`；ACP 这类有意保留兼容默认的 crate 仍由窄 consumer 显式关闭。被单独复制到 Docker 构建上下文的 manifest 无法继承 workspace 根，必须继续维护显式版本和默认策略。禁止使用 `tokio/full` 绕过依赖边界设计。
 
 ## 分层模块索引
 
@@ -128,13 +128,72 @@ await api.invoke('your_command', { request: { ... } });
 - 桌面端专属集成应放在 `src/apps/desktop`，再通过类型化能力接口回流；需要事件投递时，使用已有生产 transport adapter。
 - 在共享 core 中避免使用 `tauri::AppHandle` 等宿主 API；优先使用 `bitfun_events::EventEmitter` 等共享抽象。
 
-### 远程兼容
-
-- 新增功能时，从一开始就要考虑远程工作区和远程控制同步适配。只支持本地的行为很容易让远程场景功能缺失。
-- 如果某个功能无法合理支持远程工作区，必须做能力屏蔽，或展示明确的不支持提示，不能让它以通用错误的形式失败。
-- 每个桌面端 Tauri 命令都必须在
- `src/apps/desktop/src/api/remote_workspace_policy.rs` 中声明远程工作区策略；
- 该文件的契约测试会拒绝没有显式策略的新命令，并禁止 legacy-unaudited 存量清单增长。
+### 远程场景
+
+BitFun 不是只在本地运行的桌面应用：工作区、执行这一轮的 runtime、以及正在操作的人，
+可能分别位于三台机器。下面四种场景是每次改动都要一并覆盖的一等目标，不是事后再补的适配。
+
+| 场景 | 含义 | 设计入口 |
+|---|---|---|
+| 远程工作区 | 当前工作区位于 SSH 主机、跳板机链路或 Docker 容器；文件、终端、搜索和 Agent 子进程都必须在那一侧执行 | [remote-workspace-transport.md](docs/architecture/remote-workspace-transport.md)、[remote-workspaces.md](docs/features/remote-workspaces.md) |
+| 远程控制 | 手机端 mobile web，或飞书 / Telegram / 微信 Bot，通过 Remote Connect relay 驱动 Desktop 或 CLI 宿主上的会话 | [`src/mobile-web`](src/mobile-web/AGENTS.md)、[services-integrations](src/crates/services/services-integrations/AGENTS.md) 的 `remote_connect`、[relay-service](src/crates/services/relay-service/AGENTS.md) |
+| 多端互控（Peer Device Mode） | 同账号的一台设备成为另一台的数据平面：控制端外壳仍在本地，invoke 和事件来自 peer | [peer-device-mode.md](docs/architecture/peer-device-mode.md)、[peer-device README](src/web-ui/src/infrastructure/peer-device/README.md) |
+| Dispatch 分离任务 | 控制端把持久化任务提交到另一台 BitFun 宿主后即可断开；目标端拥有 job、session、worktree、事件日志和权限信箱 | [detached-task-dispatch.md](docs/architecture/detached-task-dispatch.md) |
+
+四种场景共同适用的规则：
+
+- 远程路径要和功能一起设计。默认 UI、进程和文件系统在同一台机器上的能力属于未完成，
+  而不是“第一阶段”。
+- 不支持要显式暴露。确实无法支持时，应屏蔽入口或返回明确的不支持状态；静默回落本地、
+  假成功、空载荷和通用错误都算回归，其中回落本地还会把本地内容泄露给远端控制方。
+- 阻塞式交互必须可以远程应答。新增的权限确认、对话框和选择器都要经既有的 dialog /
+  权限信箱编排送达当前操作端；只能靠桌面窗口解除的阻塞会让远程控制和 Dispatch 任务死锁。
+- 要能扛断线。远程形态会重连、按 cursor 重放并重新 hydrate，因此优先使用可恢复 cursor
+  和幂等变更，不要依赖“客户端恰好在线”才存在的状态。
+- 远程工作区路径在任何客户端 OS 上都是 POSIX 路径。不得用宿主 `std::path` 语义切分或
+  拼接，也不得把控制端的路径直接拿到 peer 宿主上复用。
+
+各场景的具体约束：
+
+- **远程工作区**：每个桌面端 Tauri 命令都必须在
+  [`remote_workspace_policy.rs`](src/apps/desktop/src/api/remote_workspace_policy.rs)
+  中声明策略；该文件的契约测试会拒绝没有显式策略的新命令，并禁止 `LegacyUnaudited`
+  存量清单增长。
+- **远程控制**：mobile web 和 IM Bot 是通过 `RemoteCommand` wire 协议和 bot command
+  router / menu 触达会话的，不走 Web UI。新增或迁移会话级能力时——工作区与助手选择、
+  会话生命周期、模式、模型、审批、附件——要同步扩展这些形态，或让它们给出明确的
+  不支持回复。
+- **多端互控**：产品命令默认代理到 peer 执行。必须留在控制端的命令（窗口装饰、更新器、
+  账号身份、本地 OS 自动化）要在三份保持同步的清单中一起禁用：
+  [`peer_host_invoke.rs`](src/apps/desktop/src/api/peer_host_invoke.rs)、
+  [`deny.rs`](src/apps/cli/src/peer_host/deny.rs) 和
+  [`peer-device-adapter.ts`](src/web-ui/src/infrastructure/api/adapters/peer-device-adapter.ts)。
+  改动 session、account 或 hydrate 路径前，先读 peer-device README 的 invariants。
+- **Dispatch 分离任务**：任务在目标端以 CLI delivery profile 无界面运行，没有交互宿主，
+  也不保证控制端在线。控制端只是观察者，不是 runtime 或文件系统代理。不要引入依赖提交方
+  常驻的行为；dispatch 协议版本和目标端必备 capability 属于兼容契约——新的目标端要求要走
+  协商 capability，而不是默认假设。
+
+改动说明中要写清楚在哪些远程场景下验证过。只跑本地测试不能作为远程行为的证据。
+
+### 升级兼容性
+
+用户是原地升级的，而上述远程场景经常让两个不同版本的 BitFun 连在同一条链路上。
+任何改动都必须保证已有安装在升级后无需手工修复即可继续工作。
+
+- **落盘结构会被新旧两侧代码同时读取。** 配置、设置、会话、连接配置、worktree 和
+  dispatch 记录：新增字段要带默认值，反序列化要保持容错，绝不重新定义或收窄已经落盘
+  字段的语义。旧数据给不出的字段，不能变成必填。
+- **不要用删除或重置用户数据的方式来“恢复”解析不了的内容。** 应保留记录、降级功能并
+  给出明确状态。凭证缺失、配置读不出、超时或主机离线，都不构成丢弃会话、工作区或连接
+  的理由；销毁性删除只能是用户的显式操作。
+- **跨版本边界要协商，不能假设。** Peer HostInvoke、dispatch 协议、relay 与 mobile web、
+  IM Bot，对面都是你控制不了的构建版本。要先声明 capability 再使用——包版本相同不等于
+  行为相同——并且要让旧版本一侧留在可用路径上，而不是直接判失败。
+- **改名就是一次迁移。** 在所有受支持的对端都不可能再发送旧名称、旧 id 或旧结构之前，
+  必须继续兼容读取；被改名对象所引用的数据（vault 条目、工作区指针）要一并迁移。
+- **用测试证明。** 要覆盖旧数据反序列化和旧载荷往返，而不只是新结构。只验证当前代码
+  自己写出的数据，不算升级兼容性覆盖。
 
 ### Agent loop 行为
 
diff --git a/AGENTS.md b/AGENTS.md
index 3494a30943..0fb6666158 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -18,8 +18,15 @@ Repository rule: **keep product logic platform-agnostic, then expose it through
 5. Workspace Rust dependencies own compatible versions, not broad capability
    unions. Each crate must select the dependency features it actually uses;
    keep test-only features in dev-dependencies and attach feature-gated service
-   capabilities to the owning crate feature. `tokio/full` is forbidden in the
-   root workspace and workspace members.
+   capabilities to the owning crate feature. Disable third-party defaults in
+   `[workspace.dependencies]` when they are not part of every consumer's
+   contract; members inherit that policy and add only their needed slices. For
+   internal crates whose guarded `default` is empty, do not repeat
+   `default-features = false` on every edge. Narrow consumers of an intentional
+   compatibility default, such as ACP, must still disable it explicitly.
+   Manifests copied into a standalone Docker build context must keep explicit
+   versions and default policy because they cannot inherit the workspace root.
+   `tokio/full` is forbidden in the root workspace and workspace members.
 
 ## Layered Module Index
 
@@ -145,14 +152,94 @@ await api.invoke('your_command', { request: { ... } });
 - Desktop-only host adapters belong in `src/apps/desktop`, then flow through typed capability interfaces and, when event delivery is needed, the production transport adapter.
 - In shared core, avoid host-specific APIs such as `tauri::AppHandle`; use shared abstractions such as `bitfun_events::EventEmitter`.
 
-### Remote compatibility
-
-- When adding features, consider remote workspace and remote control synchronization support from the start. Local-only behavior can silently leave remote scenarios incomplete.
-- If a feature cannot reasonably support remote workspaces, gate it or show a clear unsupported-state message instead of letting it fail with a generic error.
-- Every desktop Tauri command must declare its remote-workspace policy in
- `src/apps/desktop/src/api/remote_workspace_policy.rs`; the contract test there
- rejects new commands without an explicit policy and forbids growing the
- legacy-unaudited backlog.
+### Remote scenarios
+
+BitFun is not a local-only desktop app. The workspace, the runtime that executes
+a turn, and the person driving it can each sit on a different machine. Treat the
+four scenarios below as first-class targets of every change, not as a later port.
+
+| Scenario | What it means | Design entry point |
+|---|---|---|
+| Remote workspace | The active workspace lives on an SSH host, a jump-host chain, or a Docker container; files, terminal, search, and Agent subprocesses must execute there | [remote-workspace-transport.md](docs/architecture/remote-workspace-transport.md), [remote-workspaces.md](docs/features/remote-workspaces.md) |
+| Remote control | Mobile web, or a Feishu / Telegram / WeChat bot, drives a session on a Desktop or CLI host through the Remote Connect relay | [`src/mobile-web`](src/mobile-web/AGENTS.md), `remote_connect` in [services-integrations](src/crates/services/services-integrations/AGENTS.md), [relay-service](src/crates/services/relay-service/AGENTS.md) |
+| Peer Device Mode | One same-account device becomes the data plane of another: the controller shell stays local, invokes and events come from the peer | [peer-device-mode.md](docs/architecture/peer-device-mode.md), [peer-device README](src/web-ui/src/infrastructure/peer-device/README.md) |
+| Detached Dispatch | A controller submits a durable job to another BitFun host and may then disconnect; the target owns the job, session, worktree, event log, and permission mailbox | [detached-task-dispatch.md](docs/architecture/detached-task-dispatch.md) |
+
+Rules that apply to all four:
+
+- Design the remote path together with the feature. A capability that assumes UI,
+  process, and filesystem share one machine is incomplete, not "phase one".
+- Degrade loudly. When a scenario cannot be supported, gate the entry point or
+  return a clear unsupported state. Silent local fallback, fake success, empty
+  payloads, and generic errors are all regressions; local fallback additionally
+  leaks local content to a remote controller.
+- Keep blocking interaction answerable from a distance. New permission prompts,
+  dialogs, and pickers must reach the driving surface through the existing dialog
+  and permission-mailbox orchestration. A turn that only the desktop window can
+  unblock deadlocks remote control and dispatch jobs.
+- Survive disconnect. Remote surfaces reconnect, replay by cursor, and re-hydrate,
+  so prefer resumable cursors and idempotent mutations over state that exists only
+  while a client happens to be attached.
+- Remote workspace paths are POSIX on every client OS. Do not split or join them
+  with host `std::path` semantics, and do not reuse a controller-side path on a
+  peer host.
+
+Per-scenario obligations:
+
+- **Remote workspace**: every desktop Tauri command declares its policy in
+  [`remote_workspace_policy.rs`](src/apps/desktop/src/api/remote_workspace_policy.rs).
+  The contract test there rejects new commands without an explicit policy and
+  forbids growing the `LegacyUnaudited` backlog.
+- **Remote control**: mobile web and IM bots reach sessions through the
+  `RemoteCommand` wire protocol and the bot command router / menu, not through the
+  Web UI. When a session-level capability is added or moved — workspace or
+  assistant selection, session lifecycle, mode, model, approval, attachment —
+  extend those surfaces or make them answer with an explicit unsupported reply.
+- **Peer Device Mode**: product commands are proxied to the peer by default. A
+  command that must stay on the controller (window chrome, updater, account
+  identity, local OS automation) has to be denied in all three lists that are kept
+  in sync: [`peer_host_invoke.rs`](src/apps/desktop/src/api/peer_host_invoke.rs),
+  [`deny.rs`](src/apps/cli/src/peer_host/deny.rs), and
+  [`peer-device-adapter.ts`](src/web-ui/src/infrastructure/api/adapters/peer-device-adapter.ts).
+  Read the peer-device README invariants before changing session, account, or
+  hydrate paths.
+- **Detached Dispatch**: jobs run headless on the target under the CLI delivery
+  profile, with no interactive host and no guaranteed controller connection. The
+  controller is an observer, never a runtime or filesystem proxy. Do not add
+  behavior that requires a live submitter, and treat the dispatch protocol version
+  and required target capabilities as a compatibility contract — a new target-side
+  requirement needs a negotiated capability, not an assumption.
+
+State which remote scenarios a change was exercised in. Local-only tests are not
+evidence of remote behavior.
+
+### Upgrade compatibility
+
+Users upgrade in place, and the remote scenarios above routinely put two
+different BitFun versions on the same connection. Every change must keep
+existing installs working without manual repair.
+
+- **Persisted shapes are read by older and newer code.** Config, settings,
+  sessions, connection profiles, worktree and dispatch records: add fields with
+  defaults, keep deserialization tolerant, and never repurpose or narrow the
+  meaning of a field that is already on disk. A field old data cannot supply
+  must not become required.
+- **Never delete or reset user data to recover from something you cannot
+  parse.** Keep the record, degrade the feature, and surface a clear state.
+  Missing credentials, an unreadable profile, a timeout, or an offline host are
+  not reasons to drop a session, workspace, or connection. Destructive removal
+  stays an explicit user action.
+- **Cross-version boundaries negotiate; they do not assume.** Peer HostInvoke,
+  the dispatch protocol, relay and mobile web, and IM bots all talk to a build
+  you do not control. Advertise a capability and check it before using it —
+  package version equality is not evidence of behavior — and keep the older
+  side on a working path instead of failing it.
+- **A rename is a migration.** Keep reading the old name, id, or record shape
+  until no supported peer can still send it, and migrate referenced data
+  (vault entries, workspace pointers) together with the thing being renamed.
+- **Prove it with tests.** Cover legacy deserialization and an old-payload
+  round trip, not just the new shape. A test that only exercises data written
+  by the current code is not upgrade coverage.
 
 ### Agent loop behavior
 
diff --git a/BitFun-Installer/package-lock.json b/BitFun-Installer/package-lock.json
index 08ffb33d52..56699761f0 100644
--- a/BitFun-Installer/package-lock.json
+++ b/BitFun-Installer/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "bitfun-installer",
-  "version": "0.2.17",
+  "version": "0.2.18",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "bitfun-installer",
-      "version": "0.2.17",
+      "version": "0.2.18",
       "dependencies": {
         "@tauri-apps/api": "^2.10.1",
         "@tauri-apps/plugin-dialog": "^2.6.0",
diff --git a/BitFun-Installer/package.json b/BitFun-Installer/package.json
index 7f9d1759c0..0b34ccd0ca 100644
--- a/BitFun-Installer/package.json
+++ b/BitFun-Installer/package.json
@@ -1,6 +1,6 @@
 {
   "name": "bitfun-installer",
-  "version": "0.2.17",
+  "version": "0.2.18",
   "private": true,
   "type": "module",
   "description": "BitFun Custom Installer - Modern branded installation experience",
diff --git a/BitFun-Installer/src-tauri/Cargo.toml b/BitFun-Installer/src-tauri/Cargo.toml
index 55d8d2525a..dddb579468 100644
--- a/BitFun-Installer/src-tauri/Cargo.toml
+++ b/BitFun-Installer/src-tauri/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "bitfun-installer"
-version = "0.2.17"
+version = "0.2.18"
 authors = ["BitFun Team"]
 edition = "2021"
 description = "BitFun Custom Installer - Modern branded installation experience"
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 993d6a26c0..5cb107a01a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -58,6 +58,7 @@ pnpm install
 ```bash
 # Desktop (recommended for daily development)
 pnpm run desktop:dev                # full hot-reload: Vite HMR + Rust auto-rebuild & restart
+pnpm run prepare:dsh-profile        # optional: compile the DeepSeek Harness bridge for local sessions
 
 # Desktop (lightweight preview, no Rust auto-rebuild)
 pnpm run desktop:preview:debug      # reuse pre-built binary + Vite HMR; Rust changes require manual restart
diff --git a/CONTRIBUTING_CN.md b/CONTRIBUTING_CN.md
index 6b6b268c18..444f59fb3b 100644
--- a/CONTRIBUTING_CN.md
+++ b/CONTRIBUTING_CN.md
@@ -55,6 +55,7 @@ pnpm install
 ```bash
 # Desktop（日常开发推荐）
 pnpm run desktop:dev                # 完整热更新：Vite HMR + Rust 自动重编译并重启
+pnpm run prepare:dsh-profile        # 可选：编译 DeepSeek Harness 桥，供本地会话使用
 
 # Desktop（轻量预览，无 Rust 自动重编译）
 pnpm run desktop:preview:debug      # 复用预构建二进制 + Vite HMR；Rust 改动需手动重启
diff --git a/Cargo.lock b/Cargo.lock
index ede08203e7..5b8850e053 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -85,7 +85,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b957d8391ac3933e2a940446171c508d2b8ffc386d8fa7d0b9c936a2575b463e"
 dependencies = [
  "anyhow",
- "derive_more 2.1.1",
+ "derive_more",
  "schemars 1.2.2",
  "serde",
  "serde_json",
@@ -550,6 +550,17 @@ dependencies = [
  "zbus 5.18.0",
 ]
 
+[[package]]
+name = "auto-launch"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1f012b8cc0c850f34117ec8252a44418f2e34a2cf501de89e29b241ae5f79471"
+dependencies = [
+ "dirs 4.0.0",
+ "thiserror 1.0.69",
+ "winreg 0.10.1",
+]
+
 [[package]]
 name = "autocfg"
 version = "1.5.1"
@@ -748,7 +759,7 @@ dependencies = [
 
 [[package]]
 name = "bitfun-acp"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "agent-client-protocol",
  "async-trait",
@@ -759,11 +770,14 @@ dependencies = [
  "bitfun-events",
  "chrono",
  "dashmap",
+ "dirs 6.0.0",
  "futures",
  "log",
+ "semver",
  "serde",
  "serde_json",
  "sha2",
+ "tar",
  "tokio",
  "tokio-util",
  "uuid",
@@ -771,11 +785,11 @@ dependencies = [
 
 [[package]]
 name = "bitfun-agent-content"
-version = "0.2.17"
+version = "0.2.18"
 
 [[package]]
 name = "bitfun-agent-runtime"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "async-trait",
  "bitfun-agent-stream",
@@ -801,12 +815,13 @@ dependencies = [
 
 [[package]]
 name = "bitfun-agent-runtime-ipc"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "async-trait",
  "bitfun-events",
  "bitfun-product-domains",
  "bitfun-runtime-ports",
+ "bitfun-transport",
  "dunce",
  "fs2",
  "serde",
@@ -821,7 +836,7 @@ dependencies = [
 
 [[package]]
 name = "bitfun-agent-stream"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -841,7 +856,7 @@ dependencies = [
 
 [[package]]
 name = "bitfun-agent-tools"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "async-trait",
  "bitfun-core-types",
@@ -854,7 +869,7 @@ dependencies = [
 
 [[package]]
 name = "bitfun-ai-adapters"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "anyhow",
  "apple-native-keyring-store",
@@ -873,7 +888,7 @@ dependencies = [
  "keyring-core",
  "libc",
  "log",
- "reqwest 0.13.4",
+ "reqwest",
  "serde",
  "serde_json",
  "sha2",
@@ -888,7 +903,7 @@ dependencies = [
 
 [[package]]
 name = "bitfun-app-server"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "agent-client-protocol",
  "anyhow",
@@ -897,23 +912,19 @@ dependencies = [
  "bitfun-app-server-client",
  "bitfun-app-server-protocol",
  "bitfun-core",
- "bitfun-events",
  "bitfun-product-domains",
  "bitfun-runtime-ports",
- "futures",
  "log",
  "serde",
  "serde_json",
  "tokio",
- "tokio-util",
  "tracing",
- "ts-rs",
  "url",
 ]
 
 [[package]]
 name = "bitfun-app-server-client"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "agent-client-protocol",
  "anyhow",
@@ -924,7 +935,7 @@ dependencies = [
 
 [[package]]
 name = "bitfun-app-server-protocol"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "agent-client-protocol",
  "bitfun-core-types",
@@ -938,7 +949,7 @@ dependencies = [
 
 [[package]]
 name = "bitfun-claude-code-adapter"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "bitfun-product-domains",
  "bitfun-services-core",
@@ -957,7 +968,7 @@ dependencies = [
 
 [[package]]
 name = "bitfun-cli"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "anyhow",
  "arboard",
@@ -980,7 +991,6 @@ dependencies = [
  "chrono",
  "clap",
  "crossterm",
- "dashmap",
  "dirs 6.0.0",
  "dunce",
  "flate2",
@@ -991,17 +1001,17 @@ dependencies = [
  "libc",
  "minisign-verify",
  "once_cell",
- "portable-pty",
+ "portable-pty 0.8.1",
+ "portable-pty 0.9.0",
  "pulldown-cmark",
  "ratatui",
- "reqwest 0.13.4",
+ "reqwest",
  "serde",
  "serde_json",
  "sha2",
  "shlex 1.3.0",
  "similar",
  "syntect",
- "syntect-tui",
  "tar",
  "tempfile",
  "thiserror 2.0.19",
@@ -1018,7 +1028,7 @@ dependencies = [
 
 [[package]]
 name = "bitfun-codex-adapter"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "bitfun-product-domains",
  "bitfun-services-core",
@@ -1035,7 +1045,7 @@ dependencies = [
 
 [[package]]
 name = "bitfun-core"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -1049,6 +1059,7 @@ dependencies = [
  "bitfun-claude-code-adapter",
  "bitfun-codex-adapter",
  "bitfun-core-types",
+ "bitfun-dsh-adapter",
  "bitfun-events",
  "bitfun-external-sources",
  "bitfun-harness",
@@ -1061,7 +1072,6 @@ dependencies = [
  "bitfun-services-core",
  "bitfun-services-integrations",
  "bitfun-tool-packs",
- "bitfun-transport",
  "chrono",
  "chrono-tz",
  "cron",
@@ -1074,21 +1084,14 @@ dependencies = [
  "fs2",
  "futures",
  "hex",
- "htmd",
  "image 0.25.10",
  "include_dir",
  "indexmap 2.14.0",
- "lazy_static",
- "legible",
  "log",
  "md5",
- "napi-derive-ohos",
- "napi-ohos",
  "notify",
- "once_cell",
- "parking_lot",
  "regex",
- "reqwest 0.13.4",
+ "reqwest",
  "rusqlite",
  "semver",
  "serde",
@@ -1096,25 +1099,22 @@ dependencies = [
  "serde_yaml",
  "sha2",
  "similar",
- "tauri",
  "tempfile",
  "terminal-core",
  "thiserror 2.0.19",
  "tokio",
- "tokio-stream",
  "tokio-tungstenite",
  "tokio-util",
  "tool-runtime",
  "tower-http",
  "ts-rs",
  "unic-langid",
- "urlencoding",
  "uuid",
 ]
 
 [[package]]
 name = "bitfun-core-types"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "serde",
  "serde_json",
@@ -1123,12 +1123,11 @@ dependencies = [
 
 [[package]]
 name = "bitfun-desktop"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "alloc-no-stdlib",
  "alloc-stdlib",
  "anyhow",
- "arboard",
  "async-trait",
  "atspi",
  "axum",
@@ -1164,14 +1163,12 @@ dependencies = [
  "leptess",
  "libc",
  "log",
- "napi-derive-ohos",
- "napi-ohos",
  "objc2 0.6.4",
  "objc2-app-kit",
  "objc2-foundation",
  "objc2-vision",
  "regex",
- "reqwest 0.13.4",
+ "reqwest",
  "resvg",
  "screenshots",
  "semver",
@@ -1183,10 +1180,15 @@ dependencies = [
  "tar",
  "tauri",
  "tauri-build",
+ "tauri-plugin-autostart",
+ "tauri-plugin-dialog",
  "tauri-plugin-fs",
- "tauri-plugin-global-shortcut",
  "tauri-plugin-log",
+ "tauri-plugin-notification",
  "tauri-plugin-opener",
+ "tauri-plugin-single-instance",
+ "tauri-plugin-updater",
+ "tauri-plugin-window-state",
  "tempfile",
  "thiserror 2.0.19",
  "time",
@@ -1203,9 +1205,26 @@ dependencies = [
  "zstd",
 ]
 
+[[package]]
+name = "bitfun-dsh-adapter"
+version = "0.2.18"
+dependencies = [
+ "async-trait",
+ "bitfun-plugin-runtime-client",
+ "bitfun-product-domains",
+ "bitfun-runtime-ports",
+ "hex",
+ "serde",
+ "serde_json",
+ "serde_yaml",
+ "sha2",
+ "tokio",
+ "urlencoding",
+]
+
 [[package]]
 name = "bitfun-events"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -1219,7 +1238,7 @@ dependencies = [
 
 [[package]]
 name = "bitfun-external-sources"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "bitfun-product-domains",
  "futures",
@@ -1229,7 +1248,7 @@ dependencies = [
 
 [[package]]
 name = "bitfun-harness"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "async-trait",
  "thiserror 2.0.19",
@@ -1238,7 +1257,7 @@ dependencies = [
 
 [[package]]
 name = "bitfun-miniapp-market-server"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "anyhow",
  "axum",
@@ -1250,7 +1269,7 @@ dependencies = [
 
 [[package]]
 name = "bitfun-miniapp-market-service"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "anyhow",
  "axum",
@@ -1260,7 +1279,7 @@ dependencies = [
  "hex",
  "image 0.25.10",
  "rand 0.8.7",
- "reqwest 0.13.4",
+ "reqwest",
  "semver",
  "serde",
  "serde_json",
@@ -1274,14 +1293,13 @@ dependencies = [
  "tower-http",
  "tracing",
  "url",
- "urlencoding",
  "uuid",
  "zip 4.6.1",
 ]
 
 [[package]]
 name = "bitfun-opencode-adapter"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "async-trait",
  "bitfun-plugin-runtime-client",
@@ -1309,18 +1327,17 @@ dependencies = [
 
 [[package]]
 name = "bitfun-page-function-runtime"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "rquickjs",
  "serde",
  "serde_json",
  "thiserror 2.0.19",
- "tokio",
 ]
 
 [[package]]
 name = "bitfun-plugin-runtime-client"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "async-trait",
  "bitfun-runtime-ports",
@@ -1329,7 +1346,7 @@ dependencies = [
 
 [[package]]
 name = "bitfun-product-capabilities"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "async-trait",
  "bitfun-agent-runtime",
@@ -1342,7 +1359,7 @@ dependencies = [
 
 [[package]]
 name = "bitfun-product-domains"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "dirs 6.0.0",
  "hex",
@@ -1359,7 +1376,7 @@ dependencies = [
 
 [[package]]
 name = "bitfun-relay-server"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "anyhow",
  "axum",
@@ -1376,7 +1393,7 @@ dependencies = [
 
 [[package]]
 name = "bitfun-relay-service"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "aes-gcm",
  "anyhow",
@@ -1405,7 +1422,7 @@ dependencies = [
 
 [[package]]
 name = "bitfun-runtime-ports"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -1420,7 +1437,7 @@ dependencies = [
 
 [[package]]
 name = "bitfun-runtime-services"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -1435,7 +1452,7 @@ dependencies = [
 
 [[package]]
 name = "bitfun-sdk-host"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "async-trait",
  "bitfun-agent-runtime",
@@ -1448,18 +1465,21 @@ dependencies = [
  "tokio",
  "tokio-util",
  "tracing",
+ "ts-rs",
  "uuid",
 ]
 
 [[package]]
 name = "bitfun-sdk-host-app"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "anyhow",
  "async-trait",
  "bitfun-agent-runtime",
  "bitfun-core",
  "bitfun-sdk-host",
+ "bitfun-services-core",
+ "bitfun-transport",
  "futures-util",
  "rustls",
  "serde_json",
@@ -1472,7 +1492,7 @@ dependencies = [
 
 [[package]]
 name = "bitfun-server"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "agent-client-protocol",
  "anyhow",
@@ -1498,7 +1518,7 @@ dependencies = [
 
 [[package]]
 name = "bitfun-services-core"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -1534,7 +1554,7 @@ dependencies = [
 
 [[package]]
 name = "bitfun-services-integrations"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "aes",
  "aes-gcm",
@@ -1572,7 +1592,8 @@ dependencies = [
  "oxc",
  "qrcode",
  "rand 0.8.7",
- "reqwest 0.13.4",
+ "regex",
+ "reqwest",
  "rmcp",
  "russh",
  "russh-keys",
@@ -1589,7 +1610,6 @@ dependencies = [
  "sse-stream",
  "ssh_config",
  "tar",
- "tauri",
  "tempfile",
  "terminal-core",
  "thiserror 2.0.19",
@@ -1610,7 +1630,7 @@ dependencies = [
 
 [[package]]
 name = "bitfun-skin-market-server"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "anyhow",
  "axum",
@@ -1622,7 +1642,7 @@ dependencies = [
 
 [[package]]
 name = "bitfun-skin-market-service"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "anyhow",
  "axum",
@@ -1632,7 +1652,7 @@ dependencies = [
  "hex",
  "hmac",
  "image 0.25.10",
- "reqwest 0.13.4",
+ "reqwest",
  "semver",
  "serde",
  "serde_json",
@@ -1651,7 +1671,7 @@ dependencies = [
 
 [[package]]
 name = "bitfun-static-hook-support"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "bitfun-product-domains",
  "bitfun-services-core",
@@ -1664,7 +1684,7 @@ dependencies = [
 
 [[package]]
 name = "bitfun-tool-call-jsonrepair"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "serde",
  "serde_json",
@@ -1672,23 +1692,25 @@ dependencies = [
 
 [[package]]
 name = "bitfun-tool-packs"
-version = "0.2.17"
+version = "0.2.18"
 
 [[package]]
 name = "bitfun-transport"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "anyhow",
  "async-trait",
  "bitfun-events",
  "log",
+ "serde",
  "serde_json",
  "tauri",
+ "thiserror 2.0.19",
 ]
 
 [[package]]
 name = "bitfun-webdriver"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "anyhow",
  "axum",
@@ -1714,18 +1736,6 @@ dependencies = [
  "windows-core 0.61.2",
 ]
 
-[[package]]
-name = "bitvec"
-version = "1.1.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ddcec3d12c579d40898fe0a9a358a803c23e9c52ca3c425707f81c9436211837"
-dependencies = [
- "funty",
- "radium",
- "tap",
- "wyz",
-]
-
 [[package]]
 name = "blake2"
 version = "0.10.6"
@@ -1804,30 +1814,6 @@ dependencies = [
  "cipher",
 ]
 
-[[package]]
-name = "borsh"
-version = "1.8.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a88b7ea17d208c4193f2c1e6de3c35fe71f98c96982d5ced308bdcc749ff6e1f"
-dependencies = [
- "borsh-derive",
- "bytes",
- "cfg_aliases 0.2.2",
-]
-
-[[package]]
-name = "borsh-derive"
-version = "1.8.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d8f347189c62a579b8cd5f80714efa178f52e461dc2e6d701d264f5ff22e566c"
-dependencies = [
- "once_cell",
- "proc-macro-crate 3.5.0",
- "proc-macro2",
- "quote",
- "syn 2.0.119",
-]
-
 [[package]]
 name = "brotli"
 version = "8.0.4"
@@ -1875,40 +1861,6 @@ version = "3.20.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
 
-[[package]]
-name = "byte-unit"
-version = "5.2.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4a813de7f2bbedb7dce265b64f1cf5908ebe4d56281ece8d847e98113788b9b0"
-dependencies = [
- "rust_decimal",
- "schemars 1.2.2",
- "serde",
- "utf8-width",
-]
-
-[[package]]
-name = "bytecheck"
-version = "0.6.12"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "23cdc57ce23ac53c931e88a43d06d070a6fd142f2617be5855eb75efc9beb1c2"
-dependencies = [
- "bytecheck_derive",
- "ptr_meta",
- "simdutf8",
-]
-
-[[package]]
-name = "bytecheck_derive"
-version = "0.6.12"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3db406d29fbcd95542e92559bed4d8ad92636d1ca8b3b72ede10b4bcc010e659"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn 1.0.109",
-]
-
 [[package]]
 name = "bytemuck"
 version = "1.25.2"
@@ -2370,12 +2322,6 @@ version = "0.9.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c2459377285ad874054d797f3ccebf984978aa39129f6eafde5cdc8315b612f8"
 
-[[package]]
-name = "convert_case"
-version = "0.4.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6245d59a3e82a7fc217c5828a6692dbc6dfb63a0c8c90495621f7b9d79704a0e"
-
 [[package]]
 name = "convert_case"
 version = "0.6.0"
@@ -2394,15 +2340,6 @@ dependencies = [
  "unicode-segmentation",
 ]
 
-[[package]]
-name = "convert_case"
-version = "0.11.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "affbf0190ed2caf063e3def54ff444b449371d55c58e513a95ab98eca50adb49"
-dependencies = [
- "unicode-segmentation",
-]
-
 [[package]]
 name = "cookie"
 version = "0.18.1"
@@ -2656,23 +2593,6 @@ dependencies = [
  "typenum",
 ]
 
-[[package]]
-name = "cssparser"
-version = "0.29.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f93d03419cb5950ccfd3daf3ff1c7a36ace64609a1a8746d493df1ca0afde0fa"
-dependencies = [
- "cssparser-macros 0.6.1",
- "dtoa-short",
- "itoa",
- "matches",
- "phf 0.10.1",
- "proc-macro2",
- "quote",
- "smallvec",
- "syn 1.0.109",
-]
-
 [[package]]
 name = "cssparser"
 version = "0.36.0"
@@ -2740,38 +2660,12 @@ dependencies = [
  "memchr",
 ]
 
-[[package]]
-name = "ctor"
-version = "0.2.9"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "32a2785755761f3ddc1492979ce1e48d2c00d09311c39e4466429188f3dd6501"
-dependencies = [
- "quote",
- "syn 2.0.119",
-]
-
-[[package]]
-name = "ctor"
-version = "0.8.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "352d39c2f7bef1d6ad73db6f5160efcaed66d94ef8c6c573a8410c00bf909a98"
-dependencies = [
- "ctor-proc-macro",
- "dtor",
-]
-
 [[package]]
 name = "ctor"
 version = "1.0.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e9bb72bb94fdc1bd619f4c18cc91ecf6302aeb333d31b3c6ec0bb841cd920209"
 
-[[package]]
-name = "ctor-proc-macro"
-version = "0.0.7"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "52560adf09603e58c9a7ee1fe1dcb95a16927b17c127f0ac02d6e768a0e25bc1"
-
 [[package]]
 name = "ctr"
 version = "0.9.2"
@@ -2814,12 +2708,6 @@ dependencies = [
  "syn 2.0.119",
 ]
 
-[[package]]
-name = "custom_error"
-version = "1.9.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4f8a51dd197fa6ba5b4dc98a990a43cc13693c23eb0089ebb0fcc1f04152bca6"
-
 [[package]]
 name = "dark-light"
 version = "1.1.1"
@@ -3048,19 +2936,6 @@ dependencies = [
  "syn 2.0.119",
 ]
 
-[[package]]
-name = "derive_more"
-version = "0.99.20"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6edb4b64a43d977b8e99788fe3a04d483834fba1215a7e02caa415b626497f7f"
-dependencies = [
- "convert_case 0.4.0",
- "proc-macro2",
- "quote",
- "rustc_version",
- "syn 2.0.119",
-]
-
 [[package]]
 name = "derive_more"
 version = "2.1.1"
@@ -3248,21 +3123,6 @@ dependencies = [
  "tendril 0.4.3",
 ]
 
-[[package]]
-name = "dom_query"
-version = "0.27.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "521e380c0c8afb8d9a1e83a1822ee03556fc3e3e7dbc1fd30be14e37f9cb3f89"
-dependencies = [
- "bit-set",
- "cssparser 0.36.0",
- "foldhash 0.2.0",
- "html5ever 0.38.0",
- "precomputed-hash",
- "selectors 0.36.1",
- "tendril 0.5.1",
-]
-
 [[package]]
 name = "dom_query"
 version = "0.28.0"
@@ -3320,21 +3180,6 @@ dependencies = [
  "dtoa",
 ]
 
-[[package]]
-name = "dtor"
-version = "0.3.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f1057d6c64987086ff8ed0fd3fbf377a6b7d205cc7715868cd401705f715cbe4"
-dependencies = [
- "dtor-proc-macro",
-]
-
-[[package]]
-name = "dtor-proc-macro"
-version = "0.0.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f678cf4a922c215c63e0de95eb1ff08a958a81d47e485cf9da1e27bf6305cfa5"
-
 [[package]]
 name = "dunce"
 version = "1.0.5"
@@ -3654,17 +3499,6 @@ version = "0.1.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7360491ce676a36bf9bb3c56c1aa791658183a54d2744120f27285738d90465a"
 
-[[package]]
-name = "fancy-regex"
-version = "0.16.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "998b056554fbe42e03ae0e152895cd1a7e1002aec800fdc6635d20270260c46f"
-dependencies = [
- "bit-set",
- "regex-automata",
- "regex-syntax",
-]
-
 [[package]]
 name = "fast-float2"
 version = "0.2.3"
@@ -3916,12 +3750,6 @@ dependencies = [
  "libc",
 ]
 
-[[package]]
-name = "funty"
-version = "2.0.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e6d5a32815ae3f33302d95fdcb2ce17862f8c65363dcfd29360480ba1001fc9c"
-
 [[package]]
 name = "futf"
 version = "0.1.5"
@@ -4186,26 +4014,6 @@ dependencies = [
  "windows-link 0.2.1",
 ]
 
-[[package]]
-name = "getopts"
-version = "0.2.24"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cfe4fbac503b8d1f88e6676011885f34b7174f46e59956bba534ba83abded4df"
-dependencies = [
- "unicode-width 0.2.0",
-]
-
-[[package]]
-name = "getrandom"
-version = "0.1.16"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8fc3cb4d91f53b50155bdcfd23f6a4c39ae1969c2ae85982b135750cccaf5fce"
-dependencies = [
- "cfg-if",
- "libc",
- "wasi 0.9.0+wasi-snapshot-preview1",
-]
-
 [[package]]
 name = "getrandom"
 version = "0.2.17"
@@ -4215,7 +4023,7 @@ dependencies = [
  "cfg-if",
  "js-sys",
  "libc",
- "wasi 0.11.1+wasi-snapshot-preview1",
+ "wasi",
  "wasm-bindgen",
 ]
 
@@ -4387,28 +4195,10 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e4eba85ea1d0a966a983acd07deee566e67395d2d96b6fb39e62b5a833f1eb0b"
 
 [[package]]
-name = "global-hotkey"
-version = "0.7.0"
+name = "globset"
+version = "0.4.19"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b9247516746aa8e53411a0db9b62b0e24efbcf6a76e0ba73e5a91b512ddabed7"
-dependencies = [
- "crossbeam-channel",
- "keyboard-types",
- "objc2 0.6.4",
- "objc2-app-kit",
- "once_cell",
- "serde",
- "thiserror 2.0.19",
- "windows-sys 0.59.0",
- "x11rb",
- "xkeysym",
-]
-
-[[package]]
-name = "globset"
-version = "0.4.19"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e47d37d2ae4464254884b60ab7071be2b876a9c35b696bd018ddcc76847309cd"
+checksum = "e47d37d2ae4464254884b60ab7071be2b876a9c35b696bd018ddcc76847309cd"
 dependencies = [
  "aho-corasick",
  "bstr",
@@ -4728,18 +4518,6 @@ dependencies = [
  "phf 0.13.1",
 ]
 
-[[package]]
-name = "html5ever"
-version = "0.29.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3b7410cae13cbc75623c98ac4cbfd1f0bedddf3227afc24f370cf0f50a44a11c"
-dependencies = [
- "log",
- "mac",
- "markup5ever 0.14.1",
- "match_token",
-]
-
 [[package]]
 name = "html5ever"
 version = "0.36.1"
@@ -4909,9 +4687,9 @@ dependencies = [
 
 [[package]]
 name = "ico"
-version = "0.4.0"
+version = "0.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cc50b891e4acf8fe0e71ef88ec43ad82ee07b3810ad09de10f1d01f072ed4b98"
+checksum = "3e795dff5605e0f04bff85ca41b51a96b83e80b281e96231bcaaf1ac35103371"
 dependencies = [
  "byteorder",
  "png 0.17.16",
@@ -5165,6 +4943,15 @@ dependencies = [
  "cfb 0.7.3",
 ]
 
+[[package]]
+name = "infer"
+version = "0.22.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f4200d433cbd5178df7797c9c2e75b348b728e39631cf14520d1e2fc424201f4"
+dependencies = [
+ "cfb 0.14.0",
+]
+
 [[package]]
 name = "inotify"
 version = "0.11.4"
@@ -5238,6 +5025,15 @@ dependencies = [
  "windows-sys 0.48.0",
 ]
 
+[[package]]
+name = "ioctl-rs"
+version = "0.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f7970510895cee30b3e9128319f2cefd4bde883a39f38baa279567ba3a7eb97d"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "ipnet"
 version = "2.12.0"
@@ -5485,12 +5281,24 @@ version = "3.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "863726d7afb6bc2590eeff7135d923545e5e964f004c2ccf8716c25e70a86f08"
 dependencies = [
- "jsonptr",
+ "jsonptr 0.6.3",
  "serde",
  "serde_json",
  "thiserror 1.0.69",
 ]
 
+[[package]]
+name = "json-patch"
+version = "4.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7421438de105a0827e44fadd05377727847d717c80ce29a229f85fd04c427b72"
+dependencies = [
+ "jsonptr 0.7.1",
+ "serde",
+ "serde_json",
+ "thiserror 2.0.19",
+]
+
 [[package]]
 name = "jsonptr"
 version = "0.6.3"
@@ -5501,6 +5309,16 @@ dependencies = [
  "serde_json",
 ]
 
+[[package]]
+name = "jsonptr"
+version = "0.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a5a3cc660ba5d72bce0b3bb295bf20847ccbb40fd423f3f05b61273672e561fe"
+dependencies = [
+ "serde",
+ "serde_json",
+]
+
 [[package]]
 name = "jsonrpcmsg"
 version = "0.1.2"
@@ -5566,18 +5384,6 @@ dependencies = [
  "libc",
 ]
 
-[[package]]
-name = "kuchikiki"
-version = "0.8.8-speedreader"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "02cb977175687f33fa4afa0c95c112b987ea1443e5a51c8f8ff27dc618270cc2"
-dependencies = [
- "cssparser 0.29.6",
- "html5ever 0.29.1",
- "indexmap 2.14.0",
- "selectors 0.24.0",
-]
-
 [[package]]
 name = "kurbo"
 version = "0.13.1"
@@ -5732,16 +5538,6 @@ dependencies = [
  "windows-link 0.2.1",
 ]
 
-[[package]]
-name = "libloading"
-version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "754ca22de805bb5744484a5b151a9e1a8e837d5dc232c2d7d8c2e3492edc8b60"
-dependencies = [
- "cfg-if",
- "windows-link 0.2.1",
-]
-
 [[package]]
 name = "libm"
 version = "0.2.16"
@@ -5796,12 +5592,6 @@ dependencies = [
  "vcpkg",
 ]
 
-[[package]]
-name = "linked-hash-map"
-version = "0.5.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0717cef1bc8b636c6e1c1bbdefc09e6322da8a9321966e8928ef80d20f7f770f"
-
 [[package]]
 name = "linux-raw-sys"
 version = "0.4.15"
@@ -5845,9 +5635,6 @@ name = "log"
 version = "0.4.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
-dependencies = [
- "value-bag",
-]
 
 [[package]]
 name = "lopdf"
@@ -5912,6 +5699,20 @@ version = "0.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c41e0c4fef86961ac6d6f8a82609f55f31b05e4fce149ac5710e439df7619ba4"
 
+[[package]]
+name = "mac-notification-sys"
+version = "0.6.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fd604973958ddcc11b561193c0fb96ba146506ef2f231ef2e7c35fd2cbc9beca"
+dependencies = [
+ "cc",
+ "log",
+ "objc2 0.6.4",
+ "objc2-foundation",
+ "time",
+ "uuid",
+]
+
 [[package]]
 name = "mac_address"
 version = "1.1.8"
@@ -5931,20 +5732,6 @@ dependencies = [
  "libc",
 ]
 
-[[package]]
-name = "markup5ever"
-version = "0.14.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c7a7213d12e1864c0f002f52c2923d4556935a43dec5e71355c2760e0f6e7a18"
-dependencies = [
- "log",
- "phf 0.11.3",
- "phf_codegen 0.11.3",
- "string_cache 0.8.9",
- "string_cache_codegen 0.5.4",
- "tendril 0.4.3",
-]
-
 [[package]]
 name = "markup5ever"
 version = "0.36.1"
@@ -5990,17 +5777,6 @@ dependencies = [
  "xml5ever",
 ]
 
-[[package]]
-name = "match_token"
-version = "0.1.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "88a9689d8d44bf9964484516275f5cd4c9b59457a6940c1d5d0ecbb94510a36b"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn 2.0.119",
-]
-
 [[package]]
 name = "matchers"
 version = "0.2.0"
@@ -6010,12 +5786,6 @@ dependencies = [
  "regex-automata",
 ]
 
-[[package]]
-name = "matches"
-version = "0.1.10"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2532096657941c2fea9c289d370a250971c689d4f143798ff67113ec042024a5"
-
 [[package]]
 name = "matchit"
 version = "0.8.4"
@@ -6071,6 +5841,15 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "memoffset"
+version = "0.6.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5aa361d4faea93603064a027415f07bd8e1d5c88c9fbf68bf56a285428fd79ce"
+dependencies = [
+ "autocfg",
+]
+
 [[package]]
 name = "memoffset"
 version = "0.7.1"
@@ -6144,7 +5923,7 @@ checksum = "30d65c71f1ce40ab09135ce117d742b9f8a19ff91a41a8b57ed50bc2de59c427"
 dependencies = [
  "libc",
  "log",
- "wasi 0.11.1+wasi-snapshot-preview1",
+ "wasi",
  "windows-sys 0.61.2",
 ]
 
@@ -6160,9 +5939,9 @@ dependencies = [
 
 [[package]]
 name = "muda"
-version = "0.17.2"
+version = "0.19.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7c9fec5a4e89860383d778d10563a605838f8f0b2f9303868937e5ff32e86177"
+checksum = "1dd04e60bc0b07438a6771710ee1698f98f6ebbc7f89b61264af1563b8aeb878"
 dependencies = [
  "crossbeam-channel",
  "dpi",
@@ -6173,67 +5952,10 @@ dependencies = [
  "objc2-core-foundation",
  "objc2-foundation",
  "once_cell",
- "png 0.17.16",
+ "png 0.18.1",
  "serde",
  "thiserror 2.0.19",
- "windows-sys 0.60.2",
-]
-
-[[package]]
-name = "napi-build-ohos"
-version = "1.2.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "617bcd176a3dc3d96c0acad112a482f592242d6fba6773a9eb8d90e042a35260"
-
-[[package]]
-name = "napi-derive-backend-ohos"
-version = "1.2.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5b06bf282ab442eed04c89f8a833bd06d4cf22f18654f50d848449db9e94438a"
-dependencies = [
- "convert_case 0.11.0",
- "proc-macro2",
- "quote",
- "semver",
- "syn 2.0.119",
-]
-
-[[package]]
-name = "napi-derive-ohos"
-version = "1.2.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "419b1721d9f21d76c1a5cb38e2628211cb786b5efb9e1dd2fc049ba1cb938e47"
-dependencies = [
- "convert_case 0.11.0",
- "ctor 1.0.11",
- "napi-derive-backend-ohos",
- "proc-macro2",
- "quote",
- "syn 2.0.119",
-]
-
-[[package]]
-name = "napi-ohos"
-version = "1.2.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fe1a014105134b7889e85f5ab6f8ec5240db43ed37e6c4a38bd7b4a164b345e0"
-dependencies = [
- "bitflags 2.11.1",
- "ctor 1.0.11",
- "futures",
- "napi-build-ohos",
- "napi-sys-ohos",
- "nohash-hasher",
- "rustc-hash 2.1.3",
-]
-
-[[package]]
-name = "napi-sys-ohos"
-version = "1.2.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "266964b97e57f3ca023ed13e7c78d4c8f3900aa00466bbeb8cb7746653cabc5f"
-dependencies = [
- "libloading 0.9.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -6251,6 +5973,12 @@ dependencies = [
  "thiserror 1.0.69",
 ]
 
+[[package]]
+name = "ndk-context"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "27b02d87554356db9e9a873add8782d4ea6e3e58ea071a9adb9a2e8ddb884a8b"
+
 [[package]]
 name = "ndk-sys"
 version = "0.6.0+11769913"
@@ -6295,6 +6023,20 @@ version = "1.0.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "650eef8c711430f1a879fdd01d4745a7deea475becfb90269c06775983bbf086"
 
+[[package]]
+name = "nix"
+version = "0.25.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f346ff70e7dbfd675fe90590b92d59ef2de15a8779ae305ebcbfd3f0caf59be4"
+dependencies = [
+ "autocfg",
+ "bitflags 1.3.2",
+ "cfg-if",
+ "libc",
+ "memoffset 0.6.5",
+ "pin-utils",
+]
+
 [[package]]
 name = "nix"
 version = "0.26.4"
@@ -6333,18 +6075,6 @@ dependencies = [
  "memoffset 0.9.1",
 ]
 
-[[package]]
-name = "nodrop"
-version = "0.1.14"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "72ef4a56884ca558e5ddb05a1d1e7e1bfd9a68d9ed024c21704cc98872dae1bb"
-
-[[package]]
-name = "nohash-hasher"
-version = "0.2.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2bf50223579dc7cdcfb3bfcacf7069ff68243f8c363f62ffa99cf000a6b9c451"
-
 [[package]]
 name = "nom"
 version = "7.1.3"
@@ -6388,6 +6118,20 @@ dependencies = [
  "windows-sys 0.60.2",
 ]
 
+[[package]]
+name = "notify-rust"
+version = "4.18.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c5b4c1b4f2aa9f25f63a7a49d3dd0ed567b3670da15330a66b29434be899b891"
+dependencies = [
+ "futures-lite",
+ "log",
+ "mac-notification-sys",
+ "serde",
+ "tauri-winrt-notification",
+ "zbus 5.18.0",
+]
+
 [[package]]
 name = "notify-types"
 version = "2.1.0"
@@ -6596,26 +6340,9 @@ checksum = "d49e936b501e5c5bf01fda3a9452ff86dc3ea98ad5f283e1455153142d97518c"
 dependencies = [
  "bitflags 2.11.1",
  "block2 0.6.2",
- "libc",
  "objc2 0.6.4",
- "objc2-cloud-kit",
- "objc2-core-data",
  "objc2-core-foundation",
  "objc2-core-graphics",
- "objc2-core-image",
- "objc2-core-text",
- "objc2-core-video",
- "objc2-foundation",
- "objc2-quartz-core",
-]
-
-[[package]]
-name = "objc2-av-foundation"
-version = "0.3.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "478ae33fcac9df0a18db8302387c666b8ef08a3e2d62b510ca4fc278a384b6c0"
-dependencies = [
- "objc2 0.6.4",
  "objc2-foundation",
 ]
 
@@ -6630,35 +6357,12 @@ dependencies = [
  "objc2-foundation",
 ]
 
-[[package]]
-name = "objc2-core-audio"
-version = "0.3.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e1eebcea8b0dbff5f7c8504f3107c68fc061a3eb44932051c8cf8a68d969c3b2"
-dependencies = [
- "dispatch2",
- "objc2 0.6.4",
- "objc2-core-audio-types",
- "objc2-core-foundation",
-]
-
-[[package]]
-name = "objc2-core-audio-types"
-version = "0.3.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5a89f2ec274a0cf4a32642b2991e8b351a404d290da87bb6a9a9d8632490bd1c"
-dependencies = [
- "bitflags 2.11.1",
- "objc2 0.6.4",
-]
-
 [[package]]
 name = "objc2-core-data"
 version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0b402a653efbb5e82ce4df10683b6b28027616a2715e90009947d50b8dd298fa"
 dependencies = [
- "bitflags 2.11.1",
  "objc2 0.6.4",
  "objc2-foundation",
 ]
@@ -6709,31 +6413,6 @@ dependencies = [
  "objc2-foundation",
 ]
 
-[[package]]
-name = "objc2-core-media"
-version = "0.3.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "05ec576860167a15dd9fce7fbee7512beb4e31f532159d3482d1f9c6caedf31d"
-dependencies = [
- "bitflags 2.11.1",
- "dispatch2",
- "objc2 0.6.4",
- "objc2-core-audio",
- "objc2-core-audio-types",
- "objc2-core-foundation",
- "objc2-core-video",
-]
-
-[[package]]
-name = "objc2-core-ml"
-version = "0.3.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "201b055e6acfa0f9f15568255d3f03ce2b54bc86d1814442dc69138e36813e18"
-dependencies = [
- "objc2 0.6.4",
- "objc2-foundation",
-]
-
 [[package]]
 name = "objc2-core-text"
 version = "0.3.2"
@@ -6746,19 +6425,6 @@ dependencies = [
  "objc2-core-graphics",
 ]
 
-[[package]]
-name = "objc2-core-video"
-version = "0.3.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d425caf1df73233f29fd8a5c3e5edbc30d2d4307870f802d18f00d83dc5141a6"
-dependencies = [
- "bitflags 2.11.1",
- "objc2 0.6.4",
- "objc2-core-foundation",
- "objc2-core-graphics",
- "objc2-io-surface",
-]
-
 [[package]]
 name = "objc2-encode"
 version = "4.1.0"
@@ -6787,17 +6453,6 @@ dependencies = [
  "objc2-core-foundation",
 ]
 
-[[package]]
-name = "objc2-image-io"
-version = "0.3.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "32b0446e98cf4a784cc7a0177715ff317eeaa8463841c616cfc78aa4f953c4ea"
-dependencies = [
- "objc2 0.6.4",
- "objc2-core-foundation",
- "objc2-core-graphics",
-]
-
 [[package]]
 name = "objc2-io-kit"
 version = "0.3.2"
@@ -6824,13 +6479,15 @@ dependencies = [
 ]
 
 [[package]]
-name = "objc2-javascript-core"
+name = "objc2-osa-kit"
 version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2a1e6550c4caed348956ce3370c9ffeca70bb1dbed4fa96112e7c6170e074586"
+checksum = "f112d1746737b0da274ef79a23aac283376f335f4095a083a267a082f21db0c0"
 dependencies = [
+ "bitflags 2.11.1",
  "objc2 0.6.4",
- "objc2-core-foundation",
+ "objc2-app-kit",
+ "objc2-foundation",
 ]
 
 [[package]]
@@ -6845,17 +6502,6 @@ dependencies = [
  "objc2-foundation",
 ]
 
-[[package]]
-name = "objc2-security"
-version = "0.3.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "709fe137109bd1e8b5a99390f77a7d8b2961dafc1a1c5db8f2e60329ad6d895a"
-dependencies = [
- "bitflags 2.11.1",
- "objc2 0.6.4",
- "objc2-core-foundation",
-]
-
 [[package]]
 name = "objc2-ui-kit"
 version = "0.3.2"
@@ -6893,17 +6539,9 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "bfc194758a2d5d7540b1ad283bfb9ca318ec608991892326e95b428230b2689b"
 dependencies = [
- "block2 0.6.2",
  "objc2 0.6.4",
- "objc2-av-foundation",
  "objc2-core-foundation",
- "objc2-core-graphics",
- "objc2-core-image",
- "objc2-core-media",
- "objc2-core-ml",
- "objc2-core-video",
  "objc2-foundation",
- "objc2-image-io",
 ]
 
 [[package]]
@@ -6918,162 +6556,6 @@ dependencies = [
  "objc2-app-kit",
  "objc2-core-foundation",
  "objc2-foundation",
- "objc2-javascript-core",
- "objc2-security",
-]
-
-[[package]]
-name = "ohos-arkui-binding"
-version = "0.1.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9352f0db69271fc23fb565ad1f034c2118a9ea9c727ece344834b451fe2c2865"
-dependencies = [
- "bitflags 2.11.1",
- "napi-ohos",
- "napi-sys-ohos",
- "ohos-arkui-sys",
- "ohos-xcomponent-binding",
- "ohos-xcomponent-sys",
- "ohos_enum_macro 0.0.2",
-]
-
-[[package]]
-name = "ohos-arkui-sys"
-version = "0.0.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1a19176486bbe46d33830aca4213b07bb46c745200118e57106639db4962e1c3"
-dependencies = [
- "napi-sys-ohos",
-]
-
-[[package]]
-name = "ohos-display-binding"
-version = "0.0.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "157fe09232fd0af55ed9207d30b47a5f5ff7f84a0673a3b47f65acb7bbc9b8a9"
-dependencies = [
- "ohos-display-sys",
- "ohos_enum_macro 0.0.1",
-]
-
-[[package]]
-name = "ohos-display-sys"
-version = "0.0.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fe9e1bba4d94159d0a65f1b4e748c148d4bce7930912c424522693f1837dad77"
-
-[[package]]
-name = "ohos-ime-binding"
-version = "0.1.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0b69f3e94816c243aaba0e55f230f87edc19e33c0f9397bfa56c64acb54f776a"
-dependencies = [
- "ohos-input-method-sys",
- "ohos_enum_macro 0.1.0",
-]
-
-[[package]]
-name = "ohos-input-method-sys"
-version = "0.1.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "225be105b169f45a2bca86498988c1877568d82542c013b345d605eb915e48ae"
-
-[[package]]
-name = "ohos-resource-manager-binding"
-version = "0.2.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "33793d5fc06cf356b3d25aa6228785e62c9f2a0e913a2c285b1eb8efb7185b5e"
-dependencies = [
- "napi-ohos",
- "ohos-resource-manager-sys",
-]
-
-[[package]]
-name = "ohos-resource-manager-sys"
-version = "0.2.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "97398d3f86b80279f062bd872e04be851fc9e0eb1dba4dcaabef872201517ff6"
-dependencies = [
- "napi-sys-ohos",
-]
-
-[[package]]
-name = "ohos-web-binding"
-version = "0.1.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b1ed1f2ba96b92179128f6b18ea5a0dd879210e483f7dcab51200219cbfa4a58"
-dependencies = [
- "bitflags 2.11.1",
- "ohos-web-sys",
- "ohos_enum_macro 0.0.2",
-]
-
-[[package]]
-name = "ohos-web-sys"
-version = "0.0.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "aa646f3223c2bc90a400641c3a5cda4b350387ffda1a904b8bfb3db92b81ecbc"
-
-[[package]]
-name = "ohos-xcomponent-binding"
-version = "0.2.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6c5a9bb0fd157dc702863fe6b5e15b91a4ffdc08b4c47d57d080adcc73c36fa8"
-dependencies = [
- "napi-derive-ohos",
- "napi-ohos",
- "napi-sys-ohos",
- "ohos-xcomponent-sys",
- "ohos_enum_macro 0.0.2",
- "raw-window-handle",
-]
-
-[[package]]
-name = "ohos-xcomponent-sys"
-version = "0.0.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5613209329ff61bc8695871ef985d57fc59ea4d55263e2c2395d8810d063575e"
-dependencies = [
- "ohos-arkui-sys",
-]
-
-[[package]]
-name = "ohos_enum_macro"
-version = "0.0.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b0ee769776099c824423d1686e21b5fd13b464d374d60f7cc25c48c1c836ede1"
-dependencies = [
- "convert_case 0.6.0",
- "proc-macro2",
- "quote",
- "regex",
- "syn 2.0.119",
-]
-
-[[package]]
-name = "ohos_enum_macro"
-version = "0.0.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b4bacd60b52be93024c446f27645d795ab71eb2243bb4c5d87b6238a35341fbd"
-dependencies = [
- "convert_case 0.6.0",
- "proc-macro2",
- "quote",
- "regex",
- "syn 2.0.119",
-]
-
-[[package]]
-name = "ohos_enum_macro"
-version = "0.1.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2fc1544b50988de3d636f971135e66c40479ef68e30ef09b15fb911763aab077"
-dependencies = [
- "convert_case 0.6.0",
- "proc-macro2",
- "quote",
- "regex",
- "syn 2.0.119",
 ]
 
 [[package]]
@@ -7127,33 +6609,6 @@ dependencies = [
  "libc",
 ]
 
-[[package]]
-name = "openharmony-ability"
-version = "0.3.0"
-source = "git+https://github.com/harmony-contrib/openharmony-ability.git?rev=295a276a699ba2352addc69b8cacb6acd3be6ab1#295a276a699ba2352addc69b8cacb6acd3be6ab1"
-dependencies = [
- "futures-channel",
- "http",
- "napi-derive-ohos",
- "napi-ohos",
- "ohos-arkui-binding",
- "ohos-display-binding",
- "ohos-ime-binding",
- "ohos-resource-manager-binding",
- "ohos-web-binding",
- "ohos-xcomponent-binding",
-]
-
-[[package]]
-name = "openharmony-ability-derive"
-version = "0.3.0"
-source = "git+https://github.com/harmony-contrib/openharmony-ability.git?rev=295a276a699ba2352addc69b8cacb6acd3be6ab1#295a276a699ba2352addc69b8cacb6acd3be6ab1"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn 2.0.119",
-]
-
 [[package]]
 name = "openssl-probe"
 version = "0.1.6"
@@ -7214,6 +6669,20 @@ dependencies = [
  "pin-project-lite",
 ]
 
+[[package]]
+name = "osakit"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "732c71caeaa72c065bb69d7ea08717bd3f4863a4f451402fc9513e29dbd5261b"
+dependencies = [
+ "objc2 0.6.4",
+ "objc2-foundation",
+ "objc2-osa-kit",
+ "serde",
+ "serde_json",
+ "thiserror 2.0.19",
+]
+
 [[package]]
 name = "outref"
 version = "0.5.2"
@@ -7808,36 +7277,6 @@ version = "2.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
 
-[[package]]
-name = "phf"
-version = "0.8.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3dfb61232e34fcb633f43d12c58f83c1df82962dcdfa565a4e866ffc17dafe12"
-dependencies = [
- "phf_shared 0.8.0",
-]
-
-[[package]]
-name = "phf"
-version = "0.10.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fabbf1ead8a5bcbc20f5f8b939ee3f5b0f6f281b6ad3468b84656b658b455259"
-dependencies = [
- "phf_macros 0.10.0",
- "phf_shared 0.10.0",
- "proc-macro-hack",
-]
-
-[[package]]
-name = "phf"
-version = "0.11.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1fd6780a80ae0c52cc120a26a1a42c1ae51b247a253e4e06113d23d2c2edd078"
-dependencies = [
- "phf_macros 0.11.3",
- "phf_shared 0.11.3",
-]
-
 [[package]]
 name = "phf"
 version = "0.12.1"
@@ -7869,26 +7308,6 @@ dependencies = [
  "serde",
 ]
 
-[[package]]
-name = "phf_codegen"
-version = "0.8.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cbffee61585b0411840d3ece935cce9cb6321f01c45477d30066498cd5e1a815"
-dependencies = [
- "phf_generator 0.8.0",
- "phf_shared 0.8.0",
-]
-
-[[package]]
-name = "phf_codegen"
-version = "0.11.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "aef8048c789fa5e851558d709946d6d79a8ff88c0440c587967f8e94bfb1216a"
-dependencies = [
- "phf_generator 0.11.3",
- "phf_shared 0.11.3",
-]
-
 [[package]]
 name = "phf_codegen"
 version = "0.13.1"
@@ -7899,36 +7318,6 @@ dependencies = [
  "phf_shared 0.13.1",
 ]
 
-[[package]]
-name = "phf_generator"
-version = "0.8.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "17367f0cc86f2d25802b2c26ee58a7b23faeccf78a396094c13dced0d0182526"
-dependencies = [
- "phf_shared 0.8.0",
- "rand 0.7.3",
-]
-
-[[package]]
-name = "phf_generator"
-version = "0.10.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5d5285893bb5eb82e6aaf5d59ee909a06a16737a8970984dd7746ba9283498d6"
-dependencies = [
- "phf_shared 0.10.0",
- "rand 0.8.7",
-]
-
-[[package]]
-name = "phf_generator"
-version = "0.11.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3c80231409c20246a13fddb31776fb942c38553c51e871f8cbd687a4cfb5843d"
-dependencies = [
- "phf_shared 0.11.3",
- "rand 0.8.7",
-]
-
 [[package]]
 name = "phf_generator"
 version = "0.13.1"
@@ -7949,33 +7338,6 @@ dependencies = [
  "phf_shared 0.14.0",
 ]
 
-[[package]]
-name = "phf_macros"
-version = "0.10.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "58fdf3184dd560f160dd73922bea2d5cd6e8f064bf4b13110abd81b03697b4e0"
-dependencies = [
- "phf_generator 0.10.0",
- "phf_shared 0.10.0",
- "proc-macro-hack",
- "proc-macro2",
- "quote",
- "syn 1.0.109",
-]
-
-[[package]]
-name = "phf_macros"
-version = "0.11.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f84ac04429c13a7ff43785d75ad27569f2951ce0ffd30a3321230db2fc727216"
-dependencies = [
- "phf_generator 0.11.3",
- "phf_shared 0.11.3",
- "proc-macro2",
- "quote",
- "syn 2.0.119",
-]
-
 [[package]]
 name = "phf_macros"
 version = "0.13.1"
@@ -8002,40 +7364,13 @@ dependencies = [
  "syn 2.0.119",
 ]
 
-[[package]]
-name = "phf_shared"
-version = "0.8.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c00cf8b9eafe68dde5e9eaa2cef8ee84a9336a47d566ec55ca16589633b65af7"
-dependencies = [
- "siphasher 0.3.11",
-]
-
-[[package]]
-name = "phf_shared"
-version = "0.10.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b6796ad771acdc0123d2a88dc428b5e38ef24456743ddb1744ed628f9815c096"
-dependencies = [
- "siphasher 0.3.11",
-]
-
-[[package]]
-name = "phf_shared"
-version = "0.11.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "67eabc2ef2a60eb7faa00097bd1ffdb5bd28e62bf39990626a582201b7a754e5"
-dependencies = [
- "siphasher 1.0.3",
-]
-
 [[package]]
 name = "phf_shared"
 version = "0.12.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "06005508882fb681fd97892ecff4b7fd0fee13ef1aa569f8695dae7ab9099981"
 dependencies = [
- "siphasher 1.0.3",
+ "siphasher",
 ]
 
 [[package]]
@@ -8044,7 +7379,7 @@ version = "0.13.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e57fef6bc5981e38c2ce2d63bfa546861309f875b8a75f092d1d54ae2d64f266"
 dependencies = [
- "siphasher 1.0.3",
+ "siphasher",
 ]
 
 [[package]]
@@ -8053,7 +7388,7 @@ version = "0.14.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c6fd9027e2d9319be6349febd1db4e8d02aa544921200c9b777720ac34a3aa89"
 dependencies = [
- "siphasher 1.0.3",
+ "siphasher",
 ]
 
 [[package]]
@@ -8244,9 +7579,30 @@ checksum = "3d20d5497ef88037a52ff98267d066e7f11fcc5e99bbfbd58a42336193aacec3"
 name = "portable-atomic-util"
 version = "0.2.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c2a106d1259c23fac8e543272398ae0e3c0b8d33c88ed73d0cc71b0f1d902618"
+checksum = "c2a106d1259c23fac8e543272398ae0e3c0b8d33c88ed73d0cc71b0f1d902618"
+dependencies = [
+ "portable-atomic",
+]
+
+[[package]]
+name = "portable-pty"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "806ee80c2a03dbe1a9fb9534f8d19e4c0546b790cde8fd1fea9d6390644cb0be"
 dependencies = [
- "portable-atomic",
+ "anyhow",
+ "bitflags 1.3.2",
+ "downcast-rs",
+ "filedescriptor",
+ "lazy_static",
+ "libc",
+ "log",
+ "nix 0.25.1",
+ "serial",
+ "shared_library",
+ "shell-words",
+ "winapi",
+ "winreg 0.10.1",
 ]
 
 [[package]]
@@ -8374,12 +7730,6 @@ dependencies = [
  "version_check",
 ]
 
-[[package]]
-name = "proc-macro-hack"
-version = "0.5.20+deprecated"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dc375e1527247fe1a97d8b7156678dfe7c1af2fc075c9a4db3690ecd2a148068"
-
 [[package]]
 name = "proc-macro2"
 version = "1.0.107"
@@ -8389,26 +7739,6 @@ dependencies = [
  "unicode-ident",
 ]
 
-[[package]]
-name = "ptr_meta"
-version = "0.1.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0738ccf7ea06b608c10564b31debd4f5bc5e197fc8bfe088f68ae5ce81e7a4f1"
-dependencies = [
- "ptr_meta_derive",
-]
-
-[[package]]
-name = "ptr_meta_derive"
-version = "0.1.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "16b845dbfca988fa33db069c0e230574d15a3088f147a87b64c7589eb662c9ac"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn 1.0.109",
-]
-
 [[package]]
 name = "pulldown-cmark"
 version = "0.11.3"
@@ -8416,18 +7746,10 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "679341d22c78c6c649893cbd6c3278dcbe9fc4faa62fea3a9296ae2b50c14625"
 dependencies = [
  "bitflags 2.11.1",
- "getopts",
  "memchr",
- "pulldown-cmark-escape",
  "unicase",
 ]
 
-[[package]]
-name = "pulldown-cmark-escape"
-version = "0.11.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "007d8adb5ddab6f8e3f491ac63566a7d5002cc7ed73901f72057943fa71ae1ae"
-
 [[package]]
 name = "pulp"
 version = "0.22.3"
@@ -8540,7 +7862,7 @@ dependencies = [
  "getrandom 0.4.3",
  "lru-slab",
  "rand 0.10.2",
- "rand_pcg 0.10.2",
+ "rand_pcg",
  "ring",
  "rustc-hash 2.1.3",
  "rustls",
@@ -8587,26 +7909,6 @@ version = "6.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
 
-[[package]]
-name = "radium"
-version = "0.7.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dc33ff2d4973d518d823d61aa239014831e521c75da58e3df4840d3f47749d09"
-
-[[package]]
-name = "rand"
-version = "0.7.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6a6b1679d49b24bbfe0c803429aa1874472f50d9b363131f0e89fc356b544d03"
-dependencies = [
- "getrandom 0.1.16",
- "libc",
- "rand_chacha 0.2.2",
- "rand_core 0.5.1",
- "rand_hc",
- "rand_pcg 0.2.1",
-]
-
 [[package]]
 name = "rand"
 version = "0.8.7"
@@ -8639,16 +7941,6 @@ dependencies = [
  "rand_core 0.10.1",
 ]
 
-[[package]]
-name = "rand_chacha"
-version = "0.2.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f4c8ed856279c9737206bf725bf36935d8666ead7aa69b52be55af369d193402"
-dependencies = [
- "ppv-lite86",
- "rand_core 0.5.1",
-]
-
 [[package]]
 name = "rand_chacha"
 version = "0.3.1"
@@ -8669,15 +7961,6 @@ dependencies = [
  "rand_core 0.9.5",
 ]
 
-[[package]]
-name = "rand_core"
-version = "0.5.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "90bde5296fc891b0cef12a6d03ddccc162ce7b2aff54160af9338f8d40df6d19"
-dependencies = [
- "getrandom 0.1.16",
-]
-
 [[package]]
 name = "rand_core"
 version = "0.6.4"
@@ -8702,24 +7985,6 @@ version = "0.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69"
 
-[[package]]
-name = "rand_hc"
-version = "0.2.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ca3129af7b92a17112d59ad498c6f81eaf463253766b90396d39ea7a39d6613c"
-dependencies = [
- "rand_core 0.5.1",
-]
-
-[[package]]
-name = "rand_pcg"
-version = "0.2.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "16abd0c1b639e9eb4d7c50c0b8100b0d0f849be2349829c740fe8e6eb4816429"
-dependencies = [
- "rand_core 0.5.1",
-]
-
 [[package]]
 name = "rand_pcg"
 version = "0.10.2"
@@ -8751,7 +8016,6 @@ dependencies = [
  "lru",
  "paste",
  "strum 0.26.3",
- "time",
  "unicode-segmentation",
  "unicode-truncate",
  "unicode-width 0.2.0",
@@ -8895,50 +8159,6 @@ version = "1.9.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ba39f3699c378cd8970968dcbff9c43159ea4cfbd88d43c00b22f2ef10a435d2"
 
-[[package]]
-name = "rend"
-version = "0.4.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "71fe3824f5629716b1589be05dacd749f6aa084c87e00e016714a8cdfccc997c"
-dependencies = [
- "bytecheck",
-]
-
-[[package]]
-name = "reqwest"
-version = "0.12.28"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "eddd3ca559203180a307f12d114c268abf583f59b03cb906fd0b3ff8646c1147"
-dependencies = [
- "base64 0.22.1",
- "bytes",
- "futures-core",
- "futures-util",
- "http",
- "http-body",
- "http-body-util",
- "hyper",
- "hyper-util",
- "js-sys",
- "log",
- "percent-encoding",
- "pin-project-lite",
- "serde",
- "serde_json",
- "serde_urlencoded",
- "sync_wrapper",
- "tokio",
- "tokio-util",
- "tower",
- "tower-http",
- "tower-service",
- "url",
- "wasm-bindgen",
- "wasm-bindgen-futures",
- "wasm-streams 0.4.2",
- "web-sys",
-]
-
 [[package]]
 name = "reqwest"
 version = "0.13.4"
@@ -8978,7 +8198,7 @@ dependencies = [
  "url",
  "wasm-bindgen",
  "wasm-bindgen-futures",
- "wasm-streams 0.5.0",
+ "wasm-streams",
  "web-sys",
 ]
 
@@ -9006,6 +8226,30 @@ dependencies = [
  "subtle",
 ]
 
+[[package]]
+name = "rfd"
+version = "0.16.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a15ad77d9e70a92437d8f74c35d99b4e4691128df018833e99f90bcd36152672"
+dependencies = [
+ "block2 0.6.2",
+ "dispatch2",
+ "glib-sys",
+ "gobject-sys",
+ "gtk-sys",
+ "js-sys",
+ "log",
+ "objc2 0.6.4",
+ "objc2-app-kit",
+ "objc2-core-foundation",
+ "objc2-foundation",
+ "raw-window-handle",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "web-sys",
+ "windows-sys 0.60.2",
+]
+
 [[package]]
 name = "rgb"
 version = "0.8.53"
@@ -9029,35 +8273,6 @@ dependencies = [
  "windows-sys 0.52.0",
 ]
 
-[[package]]
-name = "rkyv"
-version = "0.7.46"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2297bf9c81a3f0dc96bc9521370b88f054168c29826a75e89c55ff196e7ed6a1"
-dependencies = [
- "bitvec",
- "bytecheck",
- "bytes",
- "hashbrown 0.12.3",
- "ptr_meta",
- "rend",
- "rkyv_derive",
- "seahash",
- "tinyvec",
- "uuid",
-]
-
-[[package]]
-name = "rkyv_derive"
-version = "0.7.46"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "84d7b42d4b8d06048d3ac8db0eb31bcb942cbeb709f0b5f2b2ebde398d3038f5"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn 1.0.109",
-]
-
 [[package]]
 name = "rmcp"
 version = "1.8.0"
@@ -9072,7 +8287,7 @@ dependencies = [
  "oauth2",
  "pastey",
  "pin-project-lite",
- "reqwest 0.13.4",
+ "reqwest",
  "rmcp-macros",
  "schemars 1.2.2",
  "serde",
@@ -9354,23 +8569,6 @@ dependencies = [
  "ordered-multimap",
 ]
 
-[[package]]
-name = "rust_decimal"
-version = "1.42.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "be2a24f50780bc85f09cc6ac299bdf1424302742d77221106859c9d8b102126a"
-dependencies = [
- "arrayvec",
- "borsh",
- "bytes",
- "num-traits",
- "rand 0.8.7",
- "rkyv",
- "serde",
- "serde_json",
- "wasm-bindgen",
-]
-
 [[package]]
 name = "rustc-hash"
 version = "1.1.0"
@@ -9641,12 +8839,6 @@ dependencies = [
  "sha2",
 ]
 
-[[package]]
-name = "seahash"
-version = "4.1.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1c107b6f4780854c8b126e228ea8869f4d7b71260f962fefb57b996b8959ba6b"
-
 [[package]]
 name = "sec1"
 version = "0.7.3"
@@ -9703,24 +8895,6 @@ dependencies = [
  "libc",
 ]
 
-[[package]]
-name = "selectors"
-version = "0.24.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0c37578180969d00692904465fb7f6b3d50b9a2b952b87c23d0e2e5cb5013416"
-dependencies = [
- "bitflags 1.3.2",
- "cssparser 0.29.6",
- "derive_more 0.99.20",
- "fxhash",
- "log",
- "phf 0.8.0",
- "phf_codegen 0.8.0",
- "precomputed-hash",
- "servo_arc 0.2.0",
- "smallvec",
-]
-
 [[package]]
 name = "selectors"
 version = "0.35.0"
@@ -9729,33 +8903,14 @@ checksum = "93fdfed56cd634f04fe8b9ddf947ae3dc493483e819593d2ba17df9ad05db8b2"
 dependencies = [
  "bitflags 2.11.1",
  "cssparser 0.36.0",
- "derive_more 2.1.1",
- "log",
- "new_debug_unreachable",
- "phf 0.13.1",
- "phf_codegen 0.13.1",
- "precomputed-hash",
- "rustc-hash 2.1.3",
- "servo_arc 0.4.3",
- "smallvec",
-]
-
-[[package]]
-name = "selectors"
-version = "0.36.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c5d9c0c92a92d33f08817311cf3f2c29a3538a8240e94a6a3c622ce652d7e00c"
-dependencies = [
- "bitflags 2.11.1",
- "cssparser 0.36.0",
- "derive_more 2.1.1",
+ "derive_more",
  "log",
  "new_debug_unreachable",
  "phf 0.13.1",
- "phf_codegen 0.13.1",
+ "phf_codegen",
  "precomputed-hash",
  "rustc-hash 2.1.3",
- "servo_arc 0.4.3",
+ "servo_arc",
  "smallvec",
 ]
 
@@ -9767,14 +8922,14 @@ checksum = "8adfa1c298912827b8a28b223b3b874357397ae706e6190acd9bf28cee99114d"
 dependencies = [
  "bitflags 2.11.1",
  "cssparser 0.37.0",
- "derive_more 2.1.1",
+ "derive_more",
  "log",
  "new_debug_unreachable",
  "phf 0.13.1",
- "phf_codegen 0.13.1",
+ "phf_codegen",
  "precomputed-hash",
  "rustc-hash 2.1.3",
- "servo_arc 0.4.3",
+ "servo_arc",
  "smallvec",
 ]
 
@@ -9993,6 +9148,48 @@ dependencies = [
  "unsafe-libyaml",
 ]
 
+[[package]]
+name = "serial"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a1237a96570fc377c13baa1b88c7589ab66edced652e43ffb17088f003db3e86"
+dependencies = [
+ "serial-core",
+ "serial-unix",
+ "serial-windows",
+]
+
+[[package]]
+name = "serial-core"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f46209b345401737ae2125fe5b19a77acce90cd53e1658cda928e4fe9a64581"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "serial-unix"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f03fbca4c9d866e24a459cbca71283f545a37f8e3e002ad8c70593871453cab7"
+dependencies = [
+ "ioctl-rs",
+ "libc",
+ "serial-core",
+ "termios",
+]
+
+[[package]]
+name = "serial-windows"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "15c6d3b776267a75d31bbdfd5d36c0ca051251caafc285827052bc53bcdc8162"
+dependencies = [
+ "libc",
+ "serial-core",
+]
+
 [[package]]
 name = "serial2"
 version = "0.2.37"
@@ -10026,16 +9223,6 @@ dependencies = [
  "syn 2.0.119",
 ]
 
-[[package]]
-name = "servo_arc"
-version = "0.2.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d52aa42f8fdf0fed91e5ce7f23d8138441002fa31dca008acf47e6fd4721f741"
-dependencies = [
- "nodrop",
- "stable_deref_trait",
-]
-
 [[package]]
 name = "servo_arc"
 version = "0.4.3"
@@ -10213,12 +9400,6 @@ dependencies = [
  "log",
 ]
 
-[[package]]
-name = "siphasher"
-version = "0.3.11"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "38b58827f4464d87d377d175e90bf58eb00fd8716ff0a62f80356b5e61555d0d"
-
 [[package]]
 name = "siphasher"
 version = "1.0.3"
@@ -10524,19 +9705,6 @@ dependencies = [
  "float-cmp",
 ]
 
-[[package]]
-name = "string_cache"
-version = "0.8.9"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bf776ba3fa74f83bf4b63c3dcbbf82173db2632ed8452cb2d891d33f459de70f"
-dependencies = [
- "new_debug_unreachable",
- "parking_lot",
- "phf_shared 0.11.3",
- "precomputed-hash",
- "serde",
-]
-
 [[package]]
 name = "string_cache"
 version = "0.9.0"
@@ -10550,18 +9718,6 @@ dependencies = [
  "serde",
 ]
 
-[[package]]
-name = "string_cache_codegen"
-version = "0.5.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c711928715f1fe0fe509c53b43e993a9a557babc2d0a3567d0a3006f1ac931a0"
-dependencies = [
- "phf_generator 0.11.3",
- "phf_shared 0.11.3",
- "proc-macro2",
- "quote",
-]
-
 [[package]]
 name = "string_cache_codegen"
 version = "0.6.1"
@@ -10647,7 +9803,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "695b5790b3131dafa99b3bbfd25a216edb3d216dad9ca208d4657bfb8f2abc3d"
 dependencies = [
  "kurbo",
- "siphasher 1.0.3",
+ "siphasher",
 ]
 
 [[package]]
@@ -10721,30 +9877,15 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "656b45c05d95a5704399aeef6bd0ddec7b2b3531b7c9e900abbf7c4d2190c925"
 dependencies = [
  "bincode",
- "fancy-regex",
  "flate2",
  "fnv",
  "once_cell",
  "onig",
- "plist",
  "regex-syntax",
  "serde",
  "serde_derive",
- "serde_json",
  "thiserror 2.0.19",
  "walkdir",
- "yaml-rust",
-]
-
-[[package]]
-name = "syntect-tui"
-version = "3.0.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "24486acfb54bfcae77f45784cb59254e14454949a44f9d0b62613a699619c210"
-dependencies = [
- "custom_error",
- "ratatui",
- "syntect",
 ]
 
 [[package]]
@@ -10783,14 +9924,16 @@ dependencies = [
 
 [[package]]
 name = "tao"
-version = "0.35.3"
-source = "git+https://github.com/richerfu/tao?branch=feat-ohos-webview#9d51be24a7189f80407f12c322c95fccde98e215"
+version = "0.36.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e9fa4618f999c4249db1681cba0a19b890718f274de7fa93c445d46bd3a8a999"
 dependencies = [
  "bitflags 2.11.1",
  "block2 0.6.2",
  "core-foundation 0.10.1",
  "core-graphics 0.25.0",
  "crossbeam-channel",
+ "dbus",
  "dispatch2",
  "dlopen2",
  "dpi",
@@ -10801,18 +9944,17 @@ dependencies = [
  "libc",
  "log",
  "ndk",
+ "ndk-context",
  "ndk-sys",
  "objc2 0.6.4",
  "objc2-app-kit",
  "objc2-foundation",
  "objc2-ui-kit",
  "once_cell",
- "openharmony-ability",
- "openharmony-ability-derive",
  "parking_lot",
  "percent-encoding",
  "raw-window-handle",
- "tao-macros 0.1.3",
+ "tao-macros",
  "unicode-segmentation",
  "url",
  "windows 0.61.3",
@@ -10821,16 +9963,6 @@ dependencies = [
  "x11-dl",
 ]
 
-[[package]]
-name = "tao-macros"
-version = "0.1.3"
-source = "git+https://github.com/richerfu/tao?branch=feat-ohos-webview#9d51be24a7189f80407f12c322c95fccde98e215"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn 2.0.119",
-]
-
 [[package]]
 name = "tao-macros"
 version = "0.1.4"
@@ -10842,12 +9974,6 @@ dependencies = [
  "syn 2.0.119",
 ]
 
-[[package]]
-name = "tap"
-version = "1.0.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "55937e1799185b12863d447f42597ed69d9928686b8d88a1df17376a097d8369"
-
 [[package]]
 name = "tar"
 version = "0.4.46"
@@ -10867,8 +9993,9 @@ checksum = "61c41af27dd6d1e27b1b16b489db798443478cef1f06a660c96db617ba5de3b1"
 
 [[package]]
 name = "tauri"
-version = "2.8.5"
-source = "git+https://github.com/richerfu/tauri?branch=feat%2Fopen-harmony#c818cc1de4eae70a14273cf8a4f81283987a42b7"
+version = "2.11.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "667b20e2726d572dea2de7370da16e188eb06008faf9a92fab7cdc46791190b5"
 dependencies = [
  "anyhow",
  "bytes",
@@ -10891,12 +10018,10 @@ dependencies = [
  "objc2-foundation",
  "objc2-ui-kit",
  "objc2-web-kit",
- "openharmony-ability",
- "openharmony-ability-derive",
  "percent-encoding",
  "plist",
  "raw-window-handle",
- "reqwest 0.12.28",
+ "reqwest",
  "serde",
  "serde_json",
  "serde_repr",
@@ -10906,12 +10031,11 @@ dependencies = [
  "tauri-macros",
  "tauri-runtime",
  "tauri-runtime-wry",
- "tauri-utils 2.7.0",
+ "tauri-utils",
  "thiserror 2.0.19",
  "tokio",
  "tray-icon",
  "url",
- "urlpattern",
  "webkit2gtk",
  "webview2-com",
  "window-vibrancy",
@@ -10920,35 +10044,35 @@ dependencies = [
 
 [[package]]
 name = "tauri-build"
-version = "2.4.1"
-source = "git+https://github.com/richerfu/tauri?branch=feat%2Fopen-harmony#c818cc1de4eae70a14273cf8a4f81283987a42b7"
+version = "2.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bc9ce40b16101cb6ea63d3e221567affd1c3a9205f95d7bc574941a10636b632"
 dependencies = [
  "anyhow",
  "cargo_toml",
  "dirs 6.0.0",
  "glob",
  "heck 0.5.0",
- "json-patch",
- "napi-build-ohos",
+ "json-patch 3.0.1",
  "schemars 0.8.22",
  "semver",
  "serde",
  "serde_json",
- "tauri-utils 2.7.0",
+ "tauri-utils",
  "tauri-winres",
- "toml 0.9.12+spec-1.1.0",
  "walkdir",
 ]
 
 [[package]]
 name = "tauri-codegen"
-version = "2.4.0"
-source = "git+https://github.com/richerfu/tauri?branch=feat%2Fopen-harmony#c818cc1de4eae70a14273cf8a4f81283987a42b7"
+version = "2.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "08279169ff42f8fc45a1dbc9dcae888893ba95288142e5880c59b93a26d2cfc5"
 dependencies = [
  "base64 0.22.1",
  "brotli",
  "ico",
- "json-patch",
+ "json-patch 3.0.1",
  "plist",
  "png 0.17.16",
  "proc-macro2",
@@ -10958,7 +10082,7 @@ dependencies = [
  "serde_json",
  "sha2",
  "syn 2.0.119",
- "tauri-utils 2.7.0",
+ "tauri-utils",
  "thiserror 2.0.19",
  "time",
  "url",
@@ -10968,15 +10092,16 @@ dependencies = [
 
 [[package]]
 name = "tauri-macros"
-version = "2.4.0"
-source = "git+https://github.com/richerfu/tauri?branch=feat%2Fopen-harmony#c818cc1de4eae70a14273cf8a4f81283987a42b7"
+version = "2.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e8b394794f399a421811d06966343e7933fcae92d59f5180b9388d1174497a45"
 dependencies = [
  "heck 0.5.0",
  "proc-macro2",
  "quote",
  "syn 2.0.119",
  "tauri-codegen",
- "tauri-utils 2.7.0",
+ "tauri-utils",
 ]
 
 [[package]]
@@ -10991,19 +10116,53 @@ dependencies = [
  "schemars 0.8.22",
  "serde",
  "serde_json",
- "tauri-utils 2.9.3",
+ "tauri-utils",
  "walkdir",
 ]
 
+[[package]]
+name = "tauri-plugin-autostart"
+version = "2.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "459383cebc193cdd03d1ba4acc40f2c408a7abce419d64bdcd2d745bc2886f70"
+dependencies = [
+ "auto-launch",
+ "serde",
+ "serde_json",
+ "tauri",
+ "tauri-plugin",
+ "thiserror 2.0.19",
+]
+
+[[package]]
+name = "tauri-plugin-dialog"
+version = "2.7.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b2d3c1dbe38037e7f590cdf2492594d5ceebe031e7bc7e827509b22a999d2940"
+dependencies = [
+ "log",
+ "raw-window-handle",
+ "rfd",
+ "serde",
+ "serde_json",
+ "tauri",
+ "tauri-plugin",
+ "tauri-plugin-fs",
+ "thiserror 2.0.19",
+ "url",
+]
+
 [[package]]
 name = "tauri-plugin-fs"
-version = "2.4.4"
+version = "2.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "47df422695255ecbe7bac7012440eddaeefd026656171eac9559f5243d3230d9"
+checksum = "b7ecc274121aca0c036a2b42d1cbe83d368d348f54e0bb8a735c2b1548e8f371"
 dependencies = [
  "anyhow",
  "dunce",
  "glob",
+ "log",
+ "objc2-foundation",
  "percent-encoding",
  "schemars 0.8.22",
  "serde",
@@ -11011,54 +10170,57 @@ dependencies = [
  "serde_repr",
  "tauri",
  "tauri-plugin",
- "tauri-utils 2.9.3",
+ "tauri-utils",
  "thiserror 2.0.19",
- "toml 0.9.12+spec-1.1.0",
+ "toml 1.1.4+spec-1.1.0",
  "url",
 ]
 
 [[package]]
-name = "tauri-plugin-global-shortcut"
-version = "2.3.1"
+name = "tauri-plugin-log"
+version = "2.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "424af23c7e88d05e4a1a6fc2c7be077912f8c76bd7900fd50aa2b7cbf5a2c405"
+checksum = "6792296e6f389268016c77db21ebae1fc0568f2fccf88b1ec7e2ea71330afb4c"
 dependencies = [
- "global-hotkey",
+ "android_logger",
+ "fern",
  "log",
+ "objc2 0.6.4",
+ "objc2-foundation",
  "serde",
  "serde_json",
+ "serde_repr",
+ "swift-rs",
  "tauri",
  "tauri-plugin",
  "thiserror 2.0.19",
+ "time",
 ]
 
 [[package]]
-name = "tauri-plugin-log"
-version = "2.7.1"
+name = "tauri-plugin-notification"
+version = "2.3.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d5709c792b8630290b5d9811a1f8fe983dd925fc87c7fc7f4923616458cd00b6"
+checksum = "01fc2c5ff41105bd1f7242d8201fdf3efd70749b82fa013a17f2126357d194cc"
 dependencies = [
- "android_logger",
- "byte-unit",
- "fern",
  "log",
- "objc2 0.6.4",
- "objc2-foundation",
+ "notify-rust",
+ "rand 0.9.5",
  "serde",
  "serde_json",
  "serde_repr",
- "swift-rs",
  "tauri",
  "tauri-plugin",
  "thiserror 2.0.19",
  "time",
+ "url",
 ]
 
 [[package]]
 name = "tauri-plugin-opener"
-version = "2.5.2"
+version = "2.5.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c26b72571d25dee25667940027114e60f569fc3974f8cefbe50c2cbc5fd65e3b"
+checksum = "17e1bea14edce6b793a04e2417e3fd924b9bc4faae83cdee7d714156cceeed29"
 dependencies = [
  "dunce",
  "glob",
@@ -11076,10 +10238,74 @@ dependencies = [
  "zbus 5.18.0",
 ]
 
+[[package]]
+name = "tauri-plugin-single-instance"
+version = "2.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b3214becf9ef5783c0ae99a3bb25adf5353a7a16ebf53e74b909e29205735c6c"
+dependencies = [
+ "serde",
+ "serde_json",
+ "tauri",
+ "thiserror 2.0.19",
+ "tokio",
+ "tracing",
+ "windows-sys 0.60.2",
+ "zbus 5.18.0",
+]
+
+[[package]]
+name = "tauri-plugin-updater"
+version = "2.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "806d9dac662c2e4594ff03c647a552f2c9bd544e7d0f683ec58f872f952ce4af"
+dependencies = [
+ "base64 0.22.1",
+ "dirs 6.0.0",
+ "flate2",
+ "futures-util",
+ "http",
+ "infer 0.19.0",
+ "log",
+ "minisign-verify",
+ "osakit",
+ "percent-encoding",
+ "reqwest",
+ "rustls",
+ "semver",
+ "serde",
+ "serde_json",
+ "tar",
+ "tauri",
+ "tauri-plugin",
+ "tempfile",
+ "thiserror 2.0.19",
+ "time",
+ "tokio",
+ "url",
+ "windows-sys 0.60.2",
+ "zip 4.6.1",
+]
+
+[[package]]
+name = "tauri-plugin-window-state"
+version = "2.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "73736611e14142408d15353e21e3cca2f12a3cfb523ad0ce85999b6d2ef1a704"
+dependencies = [
+ "bitflags 2.11.1",
+ "log",
+ "serde",
+ "serde_json",
+ "tauri",
+ "tauri-plugin",
+ "thiserror 2.0.19",
+]
+
 [[package]]
 name = "tauri-runtime"
-version = "2.8.0"
-source = "git+https://github.com/richerfu/tauri?branch=feat%2Fopen-harmony#c818cc1de4eae70a14273cf8a4f81283987a42b7"
+version = "2.11.3"
+source = "git+https://github.com/tauri-apps/tauri.git?rev=7cc68e74ff6981f5c50a52a67d56c5eb2d227188#7cc68e74ff6981f5c50a52a67d56c5eb2d227188"
 dependencies = [
  "cookie",
  "dpi",
@@ -11089,11 +10315,10 @@ dependencies = [
  "objc2 0.6.4",
  "objc2-ui-kit",
  "objc2-web-kit",
- "openharmony-ability",
  "raw-window-handle",
  "serde",
  "serde_json",
- "tauri-utils 2.7.0",
+ "tauri-utils",
  "thiserror 2.0.19",
  "url",
  "webkit2gtk",
@@ -11103,8 +10328,8 @@ dependencies = [
 
 [[package]]
 name = "tauri-runtime-wry"
-version = "2.8.1"
-source = "git+https://github.com/richerfu/tauri?branch=feat%2Fopen-harmony#c818cc1de4eae70a14273cf8a4f81283987a42b7"
+version = "2.11.4"
+source = "git+https://github.com/tauri-apps/tauri.git?rev=7cc68e74ff6981f5c50a52a67d56c5eb2d227188#7cc68e74ff6981f5c50a52a67d56c5eb2d227188"
 dependencies = [
  "gtk",
  "http",
@@ -11112,14 +10337,13 @@ dependencies = [
  "log",
  "objc2 0.6.4",
  "objc2-app-kit",
- "objc2-foundation",
  "once_cell",
  "percent-encoding",
  "raw-window-handle",
  "softbuffer",
  "tao",
  "tauri-runtime",
- "tauri-utils 2.7.0",
+ "tauri-utils",
  "url",
  "webkit2gtk",
  "webview2-com",
@@ -11127,60 +10351,21 @@ dependencies = [
  "wry",
 ]
 
-[[package]]
-name = "tauri-utils"
-version = "2.7.0"
-source = "git+https://github.com/richerfu/tauri?branch=feat%2Fopen-harmony#c818cc1de4eae70a14273cf8a4f81283987a42b7"
-dependencies = [
- "anyhow",
- "brotli",
- "cargo_metadata",
- "ctor 0.2.9",
- "dunce",
- "glob",
- "html5ever 0.29.1",
- "http",
- "infer",
- "json-patch",
- "kuchikiki",
- "log",
- "memchr",
- "phf 0.11.3",
- "proc-macro2",
- "quote",
- "regex",
- "schemars 0.8.22",
- "semver",
- "serde",
- "serde-untagged",
- "serde_json",
- "serde_with",
- "swift-rs",
- "thiserror 2.0.19",
- "toml 0.9.12+spec-1.1.0",
- "url",
- "urlpattern",
- "uuid",
- "walkdir",
-]
-
 [[package]]
 name = "tauri-utils"
 version = "2.9.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3e176a18e67764923c4f1ce66f25ae4abe5f688384d5eb1a0fa6c77f3d90f887"
+source = "git+https://github.com/tauri-apps/tauri.git?rev=7cc68e74ff6981f5c50a52a67d56c5eb2d227188#7cc68e74ff6981f5c50a52a67d56c5eb2d227188"
 dependencies = [
  "anyhow",
+ "brotli",
  "cargo_metadata",
- "ctor 0.8.0",
- "dom_query 0.27.0",
+ "ctor",
+ "dom_query 0.28.0",
  "dunce",
  "glob",
- "html5ever 0.29.1",
  "http",
- "infer",
- "json-patch",
- "kuchikiki",
+ "infer 0.22.0",
+ "json-patch 4.2.0",
  "log",
  "memchr",
  "phf 0.13.1",
@@ -11200,6 +10385,7 @@ dependencies = [
  "url",
  "urlpattern",
  "uuid",
+ "walkdir",
 ]
 
 [[package]]
@@ -11213,6 +10399,17 @@ dependencies = [
  "toml 1.1.4+spec-1.1.0",
 ]
 
+[[package]]
+name = "tauri-winrt-notification"
+version = "0.7.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ed071c670382e85fc2f48ae706492d8c338f4f89bf72520d32f8abfe880aade"
+dependencies = [
+ "thiserror 2.0.19",
+ "windows 0.61.3",
+ "windows-version",
+]
+
 [[package]]
 name = "tempfile"
 version = "3.27.0"
@@ -11257,7 +10454,7 @@ dependencies = [
 
 [[package]]
 name = "terminal-core"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -11270,7 +10467,8 @@ dependencies = [
  "futures",
  "libc",
  "log",
- "portable-pty",
+ "portable-pty 0.8.1",
+ "portable-pty 0.9.0",
  "rand 0.8.7",
  "serde",
  "serde_json",
@@ -11282,6 +10480,15 @@ dependencies = [
  "win32job",
 ]
 
+[[package]]
+name = "termios"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d5d9cf598a6d7ce700a4e6a9199da127e6819a61e64b68609683cc9a01b5683a"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "tesseract-plumbing"
 version = "0.8.0"
@@ -11678,7 +10885,7 @@ checksum = "7d56353a2a665ad0f41a421187180aab746c8c325620617ad883a99a1cbe66d2"
 
 [[package]]
 name = "tool-runtime"
-version = "0.2.17"
+version = "0.2.18"
 dependencies = [
  "anydoc",
  "bitfun-agent-tools",
@@ -11837,9 +11044,9 @@ dependencies = [
 
 [[package]]
 name = "tray-icon"
-version = "0.21.3"
+version = "0.24.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a5e85aa143ceb072062fc4d6356c1b520a51d636e7bc8e77ec94be3608e5e80c"
+checksum = "045979e3f037cd18ad1cb2a419dfda133c5c29c9f3453370079f2255d46c257e"
 dependencies = [
  "crossbeam-channel",
  "dirs 6.0.0",
@@ -11851,10 +11058,10 @@ dependencies = [
  "objc2-core-graphics",
  "objc2-foundation",
  "once_cell",
- "png 0.17.16",
+ "png 0.18.1",
  "serde",
  "thiserror 2.0.19",
- "windows-sys 0.60.2",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -11948,27 +11155,6 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
-[[package]]
-name = "unic-char-property"
-version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a8c57a407d9b6fa02b4795eb81c5b6652060a15a7903ea981f3d723e6c0be221"
-dependencies = [
- "unic-char-range",
-]
-
-[[package]]
-name = "unic-char-range"
-version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0398022d5f700414f6b899e10b8348231abf9173fa93144cbc1a43b9793c1fbc"
-
-[[package]]
-name = "unic-common"
-version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "80d7ff825a6a654ee85a63e80f92f054f904f21e7d12da4e22f9834a4aaa35bc"
-
 [[package]]
 name = "unic-langid"
 version = "0.9.6"
@@ -11987,26 +11173,6 @@ dependencies = [
  "tinystr",
 ]
 
-[[package]]
-name = "unic-ucd-ident"
-version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e230a37c0381caa9219d67cf063aa3a375ffed5bf541a452db16e744bdab6987"
-dependencies = [
- "unic-char-property",
- "unic-char-range",
- "unic-ucd-version",
-]
-
-[[package]]
-name = "unic-ucd-version"
-version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "96bd2f2237fe450fcd0a1d2f5f4e91711124f7857ba2e964247776ebeeb7b0c4"
-dependencies = [
- "unic-common",
-]
-
 [[package]]
 name = "unicase"
 version = "2.9.0"
@@ -12146,13 +11312,13 @@ checksum = "daf8dba3b7eb870caf1ddeed7bc9d2a049f3cfdfae7cb521b087cc33ae4c49da"
 
 [[package]]
 name = "urlpattern"
-version = "0.3.0"
+version = "0.6.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "70acd30e3aa1450bc2eece896ce2ad0d178e9c079493819301573dae3c37ba6d"
+checksum = "df16f50ef4cc145211879a3867ba757076b25dfee812040dcb0658bd9ae7904b"
 dependencies = [
+ "icu_properties",
  "regex",
  "serde",
- "unic-ucd-ident",
  "url",
 ]
 
@@ -12171,7 +11337,7 @@ dependencies = [
  "pico-args",
  "roxmltree",
  "simplecss",
- "siphasher 1.0.3",
+ "siphasher",
  "strict-num",
  "svgtypes",
  "tiny-skia-path",
@@ -12184,12 +11350,6 @@ version = "0.7.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "09cc8ee72d2a9becf2f2febe0205bbed8fc6615b7cb429ad062dc7b7ddd036a9"
 
-[[package]]
-name = "utf8-width"
-version = "0.1.9"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "159a7cadce548703edd50d24069bc294c5415ecab0a480e0cd1ca06d112dc94a"
-
 [[package]]
 name = "utf8_iter"
 version = "1.0.4"
@@ -12220,12 +11380,6 @@ version = "0.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ba73ea9cf16a25df0c8caa16c51acb937d5712a8429db78a3ee29d5dcacd3a65"
 
-[[package]]
-name = "value-bag"
-version = "1.13.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "068e763e8279de7ab94b6afebded2cb701678af094feb1c12ccb061b4783c1be"
-
 [[package]]
 name = "vcpkg"
 version = "0.2.15"
@@ -12302,12 +11456,6 @@ dependencies = [
  "try-lock",
 ]
 
-[[package]]
-name = "wasi"
-version = "0.9.0+wasi-snapshot-preview1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cccddf32554fecc6acb585f82a32a72e28b48f8c4c1883ddfeeeaa96f7d8e519"
-
 [[package]]
 name = "wasi"
 version = "0.11.1+wasi-snapshot-preview1"
@@ -12378,19 +11526,6 @@ dependencies = [
  "unicode-ident",
 ]
 
-[[package]]
-name = "wasm-streams"
-version = "0.4.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "15053d8d85c7eccdbefef60f06769760a563c7f0a9d6902a13d35c7800b0ad65"
-dependencies = [
- "futures-util",
- "js-sys",
- "wasm-bindgen",
- "wasm-bindgen-futures",
- "web-sys",
-]
-
 [[package]]
 name = "wasm-streams"
 version = "0.5.0"
@@ -12505,9 +11640,9 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "075474b12bcb3d2e3d4546580e9de478eeeead668a1761e2a8860c836b7ef297"
 dependencies = [
  "phf 0.13.1",
- "phf_codegen 0.13.1",
- "string_cache 0.9.0",
- "string_cache_codegen 0.6.1",
+ "phf_codegen",
+ "string_cache",
+ "string_cache_codegen",
 ]
 
 [[package]]
@@ -13398,8 +12533,9 @@ checksum = "1ffae5123b2d3fc086436f8834ae3ab053a283cfac8fe0a0b8eaae044768a4c4"
 
 [[package]]
 name = "wry"
-version = "0.55.1"
-source = "git+https://github.com/richerfu/wry#ae8b21b592ff65074381cb8a71f0fd1bb787fac0"
+version = "0.56.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1730ab21a962e7ff44df17d20804572beee66d998afc7fcbc3f846a3a12dbda7"
 dependencies = [
  "base64 0.22.1",
  "block2 0.6.2",
@@ -13423,13 +12559,11 @@ dependencies = [
  "objc2-ui-kit",
  "objc2-web-kit",
  "once_cell",
- "openharmony-ability",
- "openharmony-ability-derive",
  "percent-encoding",
  "raw-window-handle",
  "sha2",
  "soup3",
- "tao-macros 0.1.4",
+ "tao-macros",
  "thiserror 2.0.19",
  "url",
  "webkit2gtk",
@@ -13441,15 +12575,6 @@ dependencies = [
  "x11-dl",
 ]
 
-[[package]]
-name = "wyz"
-version = "0.5.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "05f360fc0b24296329c78fda852a1e9ae82de9cf7b27dae4b7f62f118f77b9ed"
-dependencies = [
- "tap",
-]
-
 [[package]]
 name = "x11"
 version = "2.21.0"
@@ -13573,15 +12698,6 @@ dependencies = [
  "lzma-sys",
 ]
 
-[[package]]
-name = "yaml-rust"
-version = "0.4.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "56c1936c4cc7a1c9ab21a1ebb602eb942ba868cbd44a99cb7cdc5892335e1c85"
-dependencies = [
- "linked-hash-map",
-]
-
 [[package]]
 name = "yoke"
 version = "0.8.3"
@@ -14050,13 +13166,3 @@ dependencies = [
  "syn 2.0.119",
  "winnow 1.0.4",
 ]
-
-[[patch.unused]]
-name = "openharmony-ability"
-version = "1.0.0-beta.0"
-source = "git+https://github.com/harmony-contrib/openharmony-ability.git#7603be9ef4a0bf7c0eaa5d23e821f21b28254d5c"
-
-[[patch.unused]]
-name = "openharmony-ability-derive"
-version = "1.0.0-beta.0"
-source = "git+https://github.com/harmony-contrib/openharmony-ability.git#7603be9ef4a0bf7c0eaa5d23e821f21b28254d5c"
diff --git a/Cargo.toml b/Cargo.toml
index 2ecc9115a2..5747a1b31a 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -18,6 +18,7 @@ members = [
     "src/crates/assembly/external-sources",
     "src/crates/adapters/ai-adapters",
     "src/crates/adapters/opencode-adapter",
+    "src/crates/adapters/dsh-adapter",
     "src/crates/adapters/claude-code-adapter",
     "src/crates/adapters/codex-adapter",
     "src/crates/adapters/static-hook-support",
@@ -54,7 +55,7 @@ resolver = "2"
 
 # Shared package metadata — single source of truth for version
 [workspace.package]
-version = "0.2.17" # x-release-please-version
+version = "0.2.18" # x-release-please-version
 authors = ["BitFun Team"]
 edition = "2021"
 
@@ -79,10 +80,10 @@ undocumented_unsafe_blocks = "warn"
 [workspace.dependencies]
 # Async runtime
 tokio = { version = "1.52", default-features = false }
-tokio-stream = "0.1.18"
+tokio-stream = { version = "0.1.18", default-features = false }
 tokio-util = "0.7.18"
 async-trait = "0.1.89"
-futures = "0.3.31"
+futures = { version = "0.3.31", default-features = false, features = ["std"] }
 futures-util = "0.3.31"
 
 # Serialization
@@ -102,12 +103,12 @@ thiserror = "2"
 
 # Logging
 log = "0.4"
-tracing = "0.1"
+tracing = { version = "0.1", default-features = false, features = ["std"] }
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 
 # Utilities
 uuid = { version = "1.0", features = ["v4", "serde"] }
-chrono = { version = "0.4", features = ["serde", "clock"] }
+chrono = { version = "0.4", default-features = false, features = ["serde", "clock", "std"] }
 chrono-tz = "0.10.4"
 cron = "0.15.0"
 # Tauri 2.9.2 utilities conflict with time 0.3.48 on current stable Rust.
@@ -133,7 +134,7 @@ encoding_rs = "0.8.35"
 url = "2"
 
 # HTTP client
-reqwest = { version = "0.13.4", default-features = false, features = ["http2", "json", "stream", "multipart", "query", "form"] }
+reqwest = { version = "0.13.4", default-features = false }
 semver = "1.0"
 
 # Debug Log HTTP Server
@@ -171,9 +172,8 @@ clap = { version = "4.6.1", features = ["derive"] }
 crossterm = "0.28"
 ratatui = "0.29"
 unicode-width = "0.2"
-pulldown-cmark = "0.11"
-syntect = { version = "5", default-features = false, features = ["default-syntaxes", "default-themes", "regex-fancy"] }
-syntect-tui = "3.0"
+pulldown-cmark = { version = "0.11", default-features = false }
+syntect = { version = "5", default-features = false, features = ["default-syntaxes", "default-themes", "regex-onig"] }
 once_cell = "1"
 libc = "0.2"
 arboard = "3"
@@ -195,7 +195,7 @@ similar = "2.5"
 urlencoding = "2.1"
 oxc = { version = "0.138.0", default-features = false, features = ["ast_visit", "codegen", "semantic", "transformer"] }
 oxc-parse = { package = "oxc", version = "0.138.0", default-features = false }
-rquickjs = { version = "0.9", default-features = false, features = ["classes", "properties", "macro"] }
+sqlx = { version = "0.8", default-features = false }
 
 # Tauri (desktop only)
 tauri = { git = "https://github.com/richerfu/tauri", branch = "feat/open-harmony", features = [] }
@@ -224,10 +224,10 @@ foreign-types = "0.5"
 dispatch = "0.2"
 block2 = "0.6"
 objc2 = "0.6"
-objc2-foundation = "0.3"
-objc2-app-kit = "0.3"
-objc2-vision = { version = "0.3.2", features = ["VNRecognizeTextRequest", "VNRequest", "VNObservation", "VNRequestHandler", "VNUtils", "VNTypes", "objc2-core-foundation"] }
-objc2-web-kit = { version = "0.3", features = ["WKWebView", "WKSnapshotConfiguration", "WKPDFConfiguration", "block2", "objc2-app-kit"] }
+objc2-foundation = { version = "0.3", default-features = false }
+objc2-app-kit = { version = "0.3", default-features = false }
+objc2-vision = { version = "0.3.2", default-features = false }
+objc2-web-kit = { version = "0.3", default-features = false }
 tempfile = "3"
 webview2-com = "0.38"
 windows = "0.61"
@@ -257,7 +257,7 @@ local-ip-address = "0.6"
 hostname = "0.4"
 
 # QR code generation
-qrcode = "0.14"
+qrcode = { version = "0.14", default-features = false }
 
 # WebSocket client
 tokio-tungstenite = { version = "0.29", features = ["rustls-tls-native-roots"] }
diff --git a/deploy/README.md b/deploy/README.md
new file mode 100644
index 0000000000..eb5be9ff77
--- /dev/null
+++ b/deploy/README.md
@@ -0,0 +1,13 @@
+# Deploy runbooks
+
+Production origin restore and product deploys for the current OpenBitFun host
+(`ssh lwb`).
+
+| Directory | Use |
+| --- | --- |
+| [openbitfun-host/](openbitfun-host/README.md) | New-host restore: website, release mirror, Relay Nginx, New API boundary |
+| [miniapp-market/](miniapp-market/README.md) | MiniApp market only |
+| [skin-market/](skin-market/README.md) | Skin market only |
+
+An Agent that is asked to move or rebuild the server starts at
+`openbitfun-host/AGENTS.md`.
diff --git a/deploy/openbitfun-host/AGENTS.md b/deploy/openbitfun-host/AGENTS.md
new file mode 100644
index 0000000000..faf33e5ff5
--- /dev/null
+++ b/deploy/openbitfun-host/AGENTS.md
@@ -0,0 +1,14 @@
+# OpenBitFun production host
+
+This directory is the restore entry for the current production origin
+(`ssh lwb`). Read [README.md](README.md) before changing cron, Nginx, the
+release mirror, Relay, the website, New API, or either market.
+
+This is a **move of an existing origin**, not a green-field install. Do not
+re-run the export/import steps against the live `lwb` host. Do not invent a
+second copy of `scripts/openbitfun-release-sync.sh`. Cron must run the in-repo
+script from the BitFun checkout.
+
+MiniApp and Skin markets have their own runbooks. Do not mix their checkouts,
+secrets, or Compose projects with this host index. Do not generate new market
+secrets when the old `market.env` files still exist.
diff --git a/deploy/openbitfun-host/README.md b/deploy/openbitfun-host/README.md
new file mode 100644
index 0000000000..4288347a15
--- /dev/null
+++ b/deploy/openbitfun-host/README.md
@@ -0,0 +1,487 @@
+# OpenBitFun 生产源站恢复手册
+
+给换机后的人和 AI Agent：clone BitFun 之后按本文把当前 `ssh lwb` 这台源站
+搬到新机器。命令默认从 BitFun 仓库根目录执行。
+
+这是 **已有源站搬迁**，不是从零装一套空服务。不要对仍在服务的 `lwb` 重跑
+clone、`crontab` 整表安装、市场 first-install 或空 volume 的 `deploy.sh`。
+
+不要再发明一份脱离仓库的同步脚本副本。历史上的
+`/root/repos/BitFun-AutoUpdate/` 只是旧主机上的运行拷贝，换机后不要重建。
+当前源站只靠 cron，不必恢复 webhook listener。
+
+## Agent 先读这个
+
+1. 根目录 `AGENTS.md`，再读本文件。
+2. MiniApp / Skin 分别只走它们自己的手册，不要从本目录重建那两个容器。
+3. 不要 `cat`、下载或打印 `/etc/bitfun-*/market.env`、New API 数据目录、账号密码。
+4. 不要在 `/root/repos/BitFun` 或 `/root/repos/BitFun-Website` 上跑 `git clean`。
+   共享 BitFun checkout 上也禁止无确认的 `git reset --hard`（与 MiniApp 手册一致）。
+   该 checkout 里可能有 Relay 的未跟踪 `.env`。
+5. 本机 Nginx 只听 80。HTTPS 在前面的云 WAF / 负载均衡终止，不要在这台机器上
+   擅自申请 Let's Encrypt 或改 443。
+6. 未知 Host 必须落到 `00-default-server.conf` 的 404，不能落到 New API 或 Relay。
+7. 每步失败立刻停。先做旧机只读导出，再在新机导入。
+
+## 这台机器上有什么
+
+| 产品 | 公网 | 源站 | 仓库内入口 |
+| --- | --- | --- | --- |
+| 官网 + 下载页 | `https://openbitfun.com/` 、`/download` | Nginx → `BitFun-Website/dist` | 本文「官网」 |
+| Release 镜像 | `https://openbitfun.com/release/` | cron → `/srv/bitfun-release` | 本文「Release 镜像」；脚本在 `scripts/openbitfun-release-sync.sh` |
+| Relay | `https://remote.openbit.fun/relay` | `bitfun-relay:9700` | `src/apps/relay-server/README.md` + 本文 Nginx |
+| MiniApp 市场 | `https://market.openbitfun.com/miniapp/` | `127.0.0.1:9710` | [../miniapp-market/README.md](../miniapp-market/README.md) |
+| Skin 市场 | `https://market.openbitfun.com/skin/` | `127.0.0.1:9720` | [../skin-market/README.md](../skin-market/README.md) |
+| New API | `https://api.openbit.fun/` | `0.0.0.0:33292` | **不在 BitFun 仓库**。见本文「New API」 |
+
+当前生产 SSH 别名是 `lwb`（root）。下文旧机用 `OLD_HOST=lwb`，新机用
+`NEW_HOST`。换机后可以把 `lwb` 指到新主机，但导出/导入期间必须同时能 SSH
+到两台。
+
+生产路径约定：
+
+| 路径 | 用途 |
+| --- | --- |
+| `/root/repos/BitFun` | BitFun checkout。Relay 静态页和同步脚本从这里读 |
+| `/root/repos/BitFun-Website` | 官网独立仓库 `GCWing/BitFun-Website` |
+| `/srv/bitfun-release` | GitHub Release 镜像（禁止放进 Website `dist/`） |
+| `/srv/bitfun-miniapp-market` | MiniApp 专用 checkout / 数据 / 备份 |
+| `/srv/bitfun-skin-market` | Skin 专用 checkout / 数据 / 备份 |
+| `/etc/bitfun-miniapp-market/market.env` | MiniApp secrets，`root:root` `0600` |
+| `/etc/bitfun-skin-market/market.env` | Skin secrets，`root:root` `0600` |
+| `/root/repos/new_api_bak` | New API 镜像 tar + `data/` 卷。BitFun 不管 |
+
+Git remote 不要混用：
+
+- **换机新 clone** `https://github.com/GCWing/BitFun.git` 之后，唯一 remote 是
+  `origin`，跟踪 `origin/main`。
+- **当前仍在服务的 `lwb`** 是 `origin=bobleer/BitFun`、
+  `upstream=GCWing/BitFun`。只在这台旧机上才使用 `upstream`。
+
+脚本里的 `OPENBITFUN_BASE_URL` 写死为 `https://openbitfun.com/release`。
+域名变了要改 `scripts/openbitfun-release-sync.sh`，不能只改 Nginx。
+
+## A. 旧机只读导出
+
+在能 SSH 到旧机的机器上执行。默认 `OLD_HOST=lwb`。导出目录在旧机
+`/root/bitfun-host-export`，不要写进 Website `dist/` 或 BitFun checkout。
+
+```bash
+OLD_HOST=lwb
+ssh "$OLD_HOST" 'set -eu
+EXPORT=/root/bitfun-host-export
+rm -rf "$EXPORT"
+install -d -m 0700 "$EXPORT"
+
+git -C /root/repos/BitFun remote -v >"$EXPORT/bitfun.remotes"
+git -C /root/repos/BitFun rev-parse HEAD >"$EXPORT/bitfun.rev"
+git -C /root/repos/BitFun-Website rev-parse HEAD >"$EXPORT/website.rev"
+git -C /srv/bitfun-miniapp-market/app rev-parse HEAD >"$EXPORT/miniapp.rev"
+git -C /srv/bitfun-skin-market/app rev-parse HEAD >"$EXPORT/skin.rev"
+crontab -l >"$EXPORT/root.crontab"
+uname -a >"$EXPORT/uname.txt"
+docker ps --format "{{.Names}} {{.Image}} {{.Status}}" >"$EXPORT/docker.ps"
+node -v >"$EXPORT/node.version" 2>/dev/null || true
+
+docker run --rm \
+  -v relay-server_relay-db:/data \
+  -v "$EXPORT":/backup \
+  alpine tar czf /backup/relay-server_relay-db.tar.gz -C /data .
+docker run --rm \
+  -v relay-server_room-web:/data \
+  -v "$EXPORT":/backup \
+  alpine tar czf /backup/relay-server_room-web.tar.gz -C /data .
+
+test -s "$EXPORT/bitfun.rev"
+test -s "$EXPORT/relay-server_relay-db.tar.gz"
+test -s "$EXPORT/relay-server_room-web.tar.gz"
+ls -la "$EXPORT"'
+```
+
+然后把导出目录、Release 镜像、市场数据、New API 和 secrets **拷到新机**。
+`rsync` 不要加 `-v` 去扫 `market.env` 内容。
+
+```bash
+OLD_HOST=lwb
+NEW_HOST=new-openbitfun   # 换成新机器 SSH 别名
+ssh "$NEW_HOST" 'install -d -m 0700 /root/bitfun-host-export /root/repos /srv'
+
+rsync -aH --numeric-ids "$OLD_HOST:/root/bitfun-host-export/" \
+  "$NEW_HOST:/root/bitfun-host-export/"
+rsync -aH --numeric-ids "$OLD_HOST:/srv/bitfun-release/" \
+  "$NEW_HOST:/srv/bitfun-release/"
+rsync -aH --numeric-ids \
+  "$OLD_HOST:/srv/bitfun-miniapp-market/" \
+  "$NEW_HOST:/srv/bitfun-miniapp-market/"
+rsync -aH --numeric-ids \
+  "$OLD_HOST:/srv/bitfun-skin-market/" \
+  "$NEW_HOST:/srv/bitfun-skin-market/"
+rsync -aH --numeric-ids \
+  "$OLD_HOST:/etc/bitfun-miniapp-market/" \
+  "$NEW_HOST:/etc/bitfun-miniapp-market/"
+rsync -aH --numeric-ids \
+  "$OLD_HOST:/etc/bitfun-skin-market/" \
+  "$NEW_HOST:/etc/bitfun-skin-market/"
+rsync -aH --numeric-ids \
+  "$OLD_HOST:/root/repos/new_api_bak/" \
+  "$NEW_HOST:/root/repos/new_api_bak/"
+```
+
+验收：新机上 `test -s /root/bitfun-host-export/relay-server_relay-db.tar.gz`、
+`test -d /srv/bitfun-release/0.2.18`、`test -f /etc/bitfun-miniapp-market/market.env`。
+不要 `cat` 任何 `market.env`。
+
+## B. 新机导入
+
+下面 `ssh` 目标都是 `$NEW_HOST`。先装 Docker、Nginx、cron，再按顺序做。
+每块做完就跑该块验证。
+
+### 1. 基础软件和 Node
+
+生产官网构建用 **Node v20.20.2**，装在 `/root/.nvm`。非交互 SSH 默认不加载
+nvm，所以每条 `npm` 命令都要先 `source`。
+
+```bash
+NEW_HOST=new-openbitfun
+ssh "$NEW_HOST" 'set -eu
+export DEBIAN_FRONTEND=noninteractive
+apt-get update
+apt-get install -y docker.io nginx cron rsync curl ca-certificates python3
+systemctl enable --now docker nginx cron
+command -v docker
+command -v nginx
+systemctl is-active cron
+
+export NVM_DIR="$HOME/.nvm"
+if [ ! -s "$NVM_DIR/nvm.sh" ]; then
+  curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
+fi
+# shellcheck disable=SC1091
+. "$NVM_DIR/nvm.sh"
+nvm install 20.20.2
+nvm alias default 20.20.2
+node -v
+test "$(node -v)" = "v20.20.2"'
+```
+
+### 2. BitFun checkout
+
+新机从 **GCWing/BitFun** clone，只用 `origin`。checkout 导出记录的 commit，
+不要猜 `upstream/main`。
+
+```bash
+NEW_HOST=new-openbitfun
+ssh "$NEW_HOST" 'set -eu
+BITFUN_REV="$(cat /root/bitfun-host-export/bitfun.rev)"
+test -n "$BITFUN_REV"
+if [ ! -d /root/repos/BitFun/.git ]; then
+  git clone https://github.com/GCWing/BitFun.git /root/repos/BitFun
+fi
+cd /root/repos/BitFun
+git remote -v
+git fetch origin
+git checkout --detach "$BITFUN_REV"
+test "$(git rev-parse HEAD)" = "$BITFUN_REV"
+test -x scripts/openbitfun-release-sync.sh'
+```
+
+`git remote -v` 应只有 `origin → github.com/GCWing/BitFun.git`。
+
+### 3. Nginx 兜底（先拆 Ubuntu default）
+
+新装 Nginx 自带 `sites-enabled/default`，也是 `default_server`。不删掉的话，
+未知 Host 不会落到市场手册里的 404 兜底。
+
+```bash
+NEW_HOST=new-openbitfun
+ssh "$NEW_HOST" 'set -eu
+rm -f /etc/nginx/sites-enabled/default
+install -m 0644 \
+  /root/repos/BitFun/deploy/miniapp-market/nginx-default-server.conf \
+  /etc/nginx/sites-available/00-default-server.conf
+ln -sfn /etc/nginx/sites-available/00-default-server.conf \
+  /etc/nginx/sites-enabled/00-default-server.conf
+nginx -t
+systemctl reload nginx
+code="$(curl -sS -o /dev/null -w "%{http_code}" \
+  -H "Host: unconfigured.openbitfun.com" http://127.0.0.1/)"
+test "$code" = "404"'
+```
+
+### 4. Release 镜像
+
+先用旧机 rsync 过来的目录（保留 0.2.14 起的多版本，供旧 Desktop / Dispatch），
+再跑一次 in-repo 同步补最新版。不要对空目录只 sync 一次就当完成。
+
+Windows 网页安装包文件名以 GitHub `latest.json` 的 `manual_installers` 为准
+（现在是 `BitFun_${version}_windows-x86_64-installer.exe`）。不要再写死
+`bitfun-installer.exe`。
+
+`release-sync.cron` **就是这台机器的整份 root crontab**。`crontab` 该文件会
+替换所有 root cron。先备份，确认没有其它任务再装。
+
+```bash
+NEW_HOST=new-openbitfun
+ssh "$NEW_HOST" 'set -eu
+test -d /srv/bitfun-release
+test -f /srv/bitfun-release/downloads.json
+touch /var/log/bitfun-release-sync.log
+chmod 644 /var/log/bitfun-release-sync.log
+crontab -l > /root/bitfun-host-export/new-host.crontab.bak 2>/dev/null || true
+crontab /root/repos/BitFun/deploy/openbitfun-host/release-sync.cron
+crontab -l
+/root/repos/BitFun/scripts/openbitfun-release-sync.sh
+python3 -c "import json; print(json.load(open(\"/srv/bitfun-release/downloads.json\"))[\"version\"])"'
+```
+
+`downloads.json` 的 `version` 必须等于
+`https://github.com/GCWing/BitFun/releases/latest/download/latest.json` 的
+`version`。日志里若再出现 `Failed to download bitfun-installer.exe`，说明跑到了
+旧脚本，停下来改 cron，不要手工改清单。
+
+锁文件默认是 `/var/lock/bitfun-release-sync.lock`，不要再指向
+`/root/repos/BitFun-AutoUpdate/sync.lock`，也不要放进 `/srv/bitfun-release`
+（该目录由 Nginx `/release/` 对外提供）。
+
+可选 beta：
+
+```bash
+BITFUN_RELEASE_CHANNEL=beta /root/repos/BitFun/scripts/openbitfun-release-sync.sh
+```
+
+### 5. 官网
+
+官网不在 BitFun 里。源码是 `https://github.com/GCWing/BitFun-Website`。
+`npm run build` 会清空 `dist/`，所以 Release 镜像绝不能放进 `dist/release`。
+
+```bash
+NEW_HOST=new-openbitfun
+ssh "$NEW_HOST" 'set -eu
+WEBSITE_REV="$(cat /root/bitfun-host-export/website.rev)"
+test -n "$WEBSITE_REV"
+if [ ! -d /root/repos/BitFun-Website/.git ]; then
+  git clone https://github.com/GCWing/BitFun-Website.git /root/repos/BitFun-Website
+fi
+cd /root/repos/BitFun-Website
+git fetch origin
+git checkout --detach "$WEBSITE_REV"
+export NVM_DIR="$HOME/.nvm"
+# shellcheck disable=SC1091
+. "$NVM_DIR/nvm.sh"
+nvm use 20.20.2
+npm install
+npm run build
+test -f dist/index.html
+install -m 0644 \
+  /root/repos/BitFun/deploy/openbitfun-host/nginx-openbit.fun.conf \
+  /etc/nginx/sites-available/openbit.fun
+ln -sfn /etc/nginx/sites-available/openbit.fun /etc/nginx/sites-enabled/openbit.fun
+nginx -t
+systemctl reload nginx
+curl -fsS -o /dev/null -w "%{http_code}\n" \
+  -H "Host: openbitfun.com" http://127.0.0.1/'
+```
+
+更新官网：在 Website 仓库拉代码后只跑 `npm run build`，不要动 `/srv/bitfun-release`。
+
+### 6. Relay
+
+必须先恢复两个 volume，再启动容器。先跑 `deploy.sh` 会建空卷，账号、同步和
+Pages 资产都会丢。不要在空库上用 `relay-admin` 新建用户来“代替”恢复。
+
+当前生产 `.env` 只有镜像开关（`BITFUN_USE_CN_MIRROR` 等）。新机用
+`BITFUN_MIRROR=auto`，让 `deploy.sh` 按主机网络自己选。不要写死
+`--global-mirror`。不要 `cat` 旧 `.env`。
+
+```bash
+NEW_HOST=new-openbitfun
+ssh "$NEW_HOST" 'set -eu
+EXPORT=/root/bitfun-host-export
+test -s "$EXPORT/relay-server_relay-db.tar.gz"
+test -s "$EXPORT/relay-server_room-web.tar.gz"
+
+docker volume create relay-server_relay-db
+docker volume create relay-server_room-web
+docker run --rm \
+  -v relay-server_relay-db:/data \
+  -v "$EXPORT":/backup \
+  alpine tar xzf /backup/relay-server_relay-db.tar.gz -C /data
+docker run --rm \
+  -v relay-server_room-web:/data \
+  -v "$EXPORT":/backup \
+  alpine tar xzf /backup/relay-server_room-web.tar.gz -C /data
+
+cd /root/repos/BitFun/src/apps/relay-server
+BITFUN_MIRROR=auto bash deploy.sh
+install -m 0644 \
+  /root/repos/BitFun/deploy/openbitfun-host/nginx-remote.openbit.fun.conf \
+  /etc/nginx/sites-available/remote.openbit.fun
+ln -sfn /etc/nginx/sites-available/remote.openbit.fun \
+  /etc/nginx/sites-enabled/remote.openbit.fun
+nginx -t
+systemctl reload nginx
+
+curl -fsS http://127.0.0.1:9700/health
+curl -fsS -o /dev/null -w "%{http_code}\n" \
+  -H "Host: remote.openbit.fun" http://127.0.0.1/relay/health
+docker exec bitfun-relay /app/relay-admin --db /app/data/bitfun_relay.db list-users'
+```
+
+`list-users` 必须能看到旧机已有账号（当前是 `bowen628`、`wgq@2012`）。
+若只有空表，停下来，不要 `add-user`。
+
+### 7. MiniApp / Skin（搬迁，不是首次安装）
+
+不要跑市场手册里的「从 `market.env.example` 生成新 secret」。旧
+`market.env`、SQLite、artifacts 已经 rsync 过来。
+
+1. 确认 `/etc/bitfun-*-market/market.env` 权限仍是 `root:root` `0600`，不要打开文件。
+2. 确认 `/srv/bitfun-*-market/{data,artifacts,backups}` 在。
+3. 专用 checkout 回到导出的 commit，再按对应手册 **只 recreate 容器**，不要
+   当绿场初始化。
+4. Skin 仍从 MiniApp 专用 checkout 的契约出发，不要用 `/root/repos/BitFun`
+   当 Skin 的运行 checkout。
+5. 按市场手册安装它们自己的 Nginx 与 backup timer。
+
+```bash
+NEW_HOST=new-openbitfun
+ssh "$NEW_HOST" 'set -eu
+MINIAPP_REV="$(cat /root/bitfun-host-export/miniapp.rev)"
+SKIN_REV="$(cat /root/bitfun-host-export/skin.rev)"
+test -n "$MINIAPP_REV"
+test -n "$SKIN_REV"
+stat -c "%U:%G %a %n" /etc/bitfun-miniapp-market/market.env \
+  /etc/bitfun-skin-market/market.env
+test -f /srv/bitfun-miniapp-market/data/market.sqlite
+test -f /srv/bitfun-skin-market/data/market.sqlite
+git -C /srv/bitfun-miniapp-market/app checkout --detach "$MINIAPP_REV"
+git -C /srv/bitfun-skin-market/app checkout --detach "$SKIN_REV"
+test "$(git -C /srv/bitfun-miniapp-market/app rev-parse HEAD)" = "$MINIAPP_REV"
+test "$(git -C /srv/bitfun-skin-market/app rev-parse HEAD)" = "$SKIN_REV"'
+```
+
+然后只按：
+
+- MiniApp：[../miniapp-market/README.md](../miniapp-market/README.md) 的构建 /
+  recreate / 验证，不要走「初次开放市场」生成新 OAuth。
+- Skin：[../skin-market/README.md](../skin-market/README.md) 同样只 recreate。
+
+### 8. New API
+
+这是改过的 `new-api` 镜像，**BitFun clone 恢复不了**。旧机事实：
+
+- 镜像：`new-api:v1.0.0-rc.14-openbitfun-mod`
+- 离线包：`/root/repos/new_api_bak/new-api-v1.0.0-rc.14-openbitfun-mod.tar`
+- 数据：`/root/repos/new_api_bak/data` → 容器 `/data`
+- 启动：`/root/repos/new_api_bak/start.sh`（宿主 `33292` → 容器 `3000`）
+
+```bash
+NEW_HOST=new-openbitfun
+ssh "$NEW_HOST" 'set -eu
+test -f /root/repos/new_api_bak/new-api-v1.0.0-rc.14-openbitfun-mod.tar
+test -d /root/repos/new_api_bak/data
+/root/repos/new_api_bak/load_image.sh
+/root/repos/new_api_bak/start.sh
+install -m 0644 \
+  /root/repos/BitFun/deploy/openbitfun-host/nginx-api.openbit.fun.conf \
+  /etc/nginx/sites-available/api.openbit.fun
+ln -sfn /etc/nginx/sites-available/api.openbit.fun \
+  /etc/nginx/sites-enabled/api.openbit.fun
+nginx -t
+systemctl reload nginx
+docker inspect --format "{{.State.Status}}" new-api'
+```
+
+没有 tar 和 data 就不要猜镜像、不要空库上线。
+
+### 9. 一次性对齐本目录的 Nginx
+
+若前面分步已装过官网 / Relay / API vhost，这一节只用来核对文件是否与仓库一致。
+先 `nginx -t` 再 reload。市场 vhost 仍按市场手册安装，不要用本目录文件覆盖
+`market.openbitfun.com.conf`。
+
+```bash
+NEW_HOST=new-openbitfun
+ssh "$NEW_HOST" 'set -eu
+rm -f /etc/nginx/sites-enabled/default
+install -m 0644 \
+  /root/repos/BitFun/deploy/miniapp-market/nginx-default-server.conf \
+  /etc/nginx/sites-available/00-default-server.conf
+ln -sfn /etc/nginx/sites-available/00-default-server.conf \
+  /etc/nginx/sites-enabled/00-default-server.conf
+install -m 0644 \
+  /root/repos/BitFun/deploy/openbitfun-host/nginx-openbit.fun.conf \
+  /etc/nginx/sites-available/openbit.fun
+ln -sfn /etc/nginx/sites-available/openbit.fun /etc/nginx/sites-enabled/openbit.fun
+install -m 0644 \
+  /root/repos/BitFun/deploy/openbitfun-host/nginx-remote.openbit.fun.conf \
+  /etc/nginx/sites-available/remote.openbit.fun
+ln -sfn /etc/nginx/sites-available/remote.openbit.fun \
+  /etc/nginx/sites-enabled/remote.openbit.fun
+install -m 0644 \
+  /root/repos/BitFun/deploy/openbitfun-host/nginx-api.openbit.fun.conf \
+  /etc/nginx/sites-available/api.openbit.fun
+ln -sfn /etc/nginx/sites-available/api.openbit.fun \
+  /etc/nginx/sites-enabled/api.openbit.fun
+nginx -t
+systemctl reload nginx'
+```
+
+### 10. 切 DNS / WAF
+
+本机没有 443。把云 WAF / 负载均衡的源站指到新机器后，再跑公网验收。
+
+## 整机验收
+
+在源站本机用 `Host` 头打 80，不要依赖这台机器能否解析公网 DNS。
+
+```bash
+NEW_HOST=new-openbitfun
+ssh "$NEW_HOST" 'set -eu
+curl -fsS -o /dev/null -w "openbitfun.com/ %{http_code}\n" \
+  -H "Host: openbitfun.com" http://127.0.0.1/
+python3 - <<PY
+import json, urllib.request
+req = urllib.request.Request(
+    "http://127.0.0.1/release/downloads.json",
+    headers={"Host": "openbitfun.com"},
+)
+with urllib.request.urlopen(req, timeout=15) as resp:
+    data = json.load(resp)
+print("downloads.json", data["version"])
+PY
+curl -fsS -o /dev/null -w "remote /relay/health %{http_code}\n" \
+  -H "Host: remote.openbit.fun" http://127.0.0.1/relay/health
+curl -fsS -o /dev/null -w "unknown host %{http_code}\n" \
+  -H "Host: unconfigured.openbitfun.com" http://127.0.0.1/
+docker ps --format "{{.Names}} {{.Status}}"
+crontab -l
+docker exec bitfun-relay /app/relay-admin --db /app/data/bitfun_relay.db list-users'
+```
+
+预期：官网 200；`downloads.json` 版本等于 GitHub latest；Relay health 200；
+未知 Host 404；`bitfun-relay` healthy；cron 指向
+`/root/repos/BitFun/scripts/openbitfun-release-sync.sh`；`list-users` 含旧账号。
+
+公网验收（从能解析 DNS 的机器）：
+
+- `https://openbitfun.com/download` 显示的版本 = `downloads.json`
+- `https://openbitfun.com/release/latest.json` 与 GitHub latest 同版本
+- `https://remote.openbit.fun/relay/health`
+- `https://market.openbitfun.com/miniapp/api/v1/health`
+- `https://market.openbitfun.com/skin/`（按 Skin 手册）
+
+## 日常更新（不是换机）
+
+在 **当前 `lwb`** 上，GCWing 叫 `upstream`。在按本文新 clone 的机器上，GCWing
+叫 `origin`。先 `git remote -v` 再选命令。
+
+| 要做的事 | 怎么做 |
+| --- | --- |
+| 更新 BitFun 源码 | 先 `cp -a src/apps/relay-server/.env /tmp/relay-server.env.bak`（若存在）。`git fetch` 对应 remote，再 `git merge --ff-only <remote>/main`。不要默认 `reset --hard`，不要 `git clean`。 |
+| 更新 Relay | 源码更新后 `cd src/apps/relay-server && BITFUN_MIRROR=auto bash deploy.sh`。账号 volume 会留下。 |
+| 更新 Release 镜像脚本 | 只改仓库里的 `scripts/openbitfun-release-sync.sh`。cron 已经跑这份文件。 |
+| 更新官网 | 在 `BitFun-Website` 拉代码，`source ~/.nvm/nvm.sh && nvm use 20.20.2 && npm run build`。 |
+| 更新市场 | 只用对应市场手册。 |
+
+更新 BitFun 源码**不会**自动更新官网、New API 或市场容器。
diff --git a/deploy/openbitfun-host/nginx-api.openbit.fun.conf b/deploy/openbitfun-host/nginx-api.openbit.fun.conf
new file mode 100644
index 0000000000..6235a961dc
--- /dev/null
+++ b/deploy/openbitfun-host/nginx-api.openbit.fun.conf
@@ -0,0 +1,27 @@
+server {
+    listen 80;
+    listen [::]:80;
+
+    server_name api.openbit.fun api.openbitfun.com;
+
+    # Allow larger payloads for AI streaming APIs (default nginx limit is 1m)
+    client_max_body_size 100m;
+
+    location / {
+        proxy_pass http://127.0.0.1:33292;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # WebSocket / SSE support
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+
+        # Streaming / long timeout
+        proxy_buffering off;
+        proxy_read_timeout 1200s;
+        proxy_send_timeout 1200s;
+    }
+}
diff --git a/deploy/openbitfun-host/nginx-openbit.fun.conf b/deploy/openbitfun-host/nginx-openbit.fun.conf
new file mode 100644
index 0000000000..55d8fe4b11
--- /dev/null
+++ b/deploy/openbitfun-host/nginx-openbit.fun.conf
@@ -0,0 +1,31 @@
+server {
+    listen 80;
+    listen [::]:80;
+
+    server_name openbit.fun www.openbit.fun openbitfun.com www.openbitfun.com;
+
+    root /root/repos/BitFun-Website/dist;
+    index index.html;
+
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    # Release mirror. Lives OUTSIDE the website dist because `npm run build`
+    # empties dist/ and would delete the mirrored installers and manifests.
+    # Written by scripts/openbitfun-release-sync.sh (cron, every 10 min).
+    # `^~` keeps the immutable-cache regex location below from matching these.
+    location ^~ /release/ {
+        alias /srv/bitfun-release/;
+        autoindex off;
+    }
+
+    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|mp4|webm|woff|woff2|ttf|eot)$ {
+        expires 30d;
+        add_header Cache-Control "public, immutable";
+    }
+
+    gzip on;
+    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
+    gzip_min_length 1024;
+}
diff --git a/deploy/openbitfun-host/nginx-remote.openbit.fun.conf b/deploy/openbitfun-host/nginx-remote.openbit.fun.conf
new file mode 100644
index 0000000000..f6a5e5b509
--- /dev/null
+++ b/deploy/openbitfun-host/nginx-remote.openbit.fun.conf
@@ -0,0 +1,65 @@
+server {
+    listen 80;
+    listen [::]:80;
+
+    server_name remote.openbit.fun remote.openbitfun.com;
+
+    # ── Homepage static files (exact match, served before proxy) ──
+    location = / {
+        root /root/repos/BitFun/src/apps/relay-server/static/homepage;
+        try_files /index.html =404;
+    }
+
+    location = /i18n.json {
+        root /root/repos/BitFun/src/apps/relay-server/static/homepage;
+    }
+
+    location = /i18n.shared.json {
+        root /root/repos/BitFun/src/apps/relay-server/static/homepage;
+    }
+
+    # ── Redirect /relay → /relay/ ──
+    location = /relay {
+        return 301 /relay/;
+    }
+
+    # ── With /relay prefix: strip prefix, proxy to relay server ──
+    # For clients configured with https://remote.openbit.fun/relay
+    location /relay/ {
+        proxy_pass http://127.0.0.1:9700/;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+
+        proxy_buffering off;
+        proxy_read_timeout 130s;
+        proxy_send_timeout 130s;
+        proxy_connect_timeout 10s;
+        client_max_body_size 100m;
+    }
+
+    # ── Without prefix: proxy directly to relay server ──
+    # For clients configured with https://remote.openbit.fun
+    location / {
+        proxy_pass http://127.0.0.1:9700;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+
+        proxy_buffering off;
+        proxy_read_timeout 130s;
+        proxy_send_timeout 130s;
+        proxy_connect_timeout 10s;
+        client_max_body_size 100m;
+    }
+}
diff --git a/deploy/openbitfun-host/release-sync.cron b/deploy/openbitfun-host/release-sync.cron
new file mode 100644
index 0000000000..b45557d510
--- /dev/null
+++ b/deploy/openbitfun-host/release-sync.cron
@@ -0,0 +1,6 @@
+# This file is the entire root crontab for the OpenBitFun origin.
+# Installing it replaces every root cron job. Back up `crontab -l` first.
+# Install with:
+#   crontab /root/repos/BitFun/deploy/openbitfun-host/release-sync.cron
+# Requires /root/repos/BitFun checked out and /srv/bitfun-release created.
+*/10 * * * * /root/repos/BitFun/scripts/openbitfun-release-sync.sh >> /var/log/bitfun-release-sync.log 2>&1
diff --git a/docs/architecture/agent-runtime-deployment-design.md b/docs/architecture/agent-runtime-deployment-design.md
index bb8c5c5214..0bacb6376c 100644
--- a/docs/architecture/agent-runtime-deployment-design.md
+++ b/docs/architecture/agent-runtime-deployment-design.md
@@ -4,9 +4,9 @@
 
 Agent Runtime 的模块职责见 [`agent-runtime-services-design.md`](agent-runtime-services-design.md)，公开 SDK 见
 [`agent-sdk-product-architecture.md`](agent-sdk-product-architecture.md)，第三方 JS/TS 进程见
-[`extensions/plugin-runtime-design.md`](extensions/plugin-runtime-design.md)。Rich Client 的 App Server 协议、Embedded/Shared Host
-和 transport 提案见 [`app-server-architecture.md`](app-server-architecture.md)。该提案通过架构评审前，当前部署和调用路径以本文及
-已接线代码为准。
+[`extensions/plugin-runtime-design.md`](extensions/plugin-runtime-design.md)。Rich Client 的 Embedded direct-runtime 决策、App Server 协议
+和 Shared transport 提案见 [`app-server-architecture.md`](app-server-architecture.md)。Embedded 迁移完成前，当前调用路径以本文及
+已接线代码为准；Shared transport 未通过独立评审前继续使用 v17。
 
 ## 1. 决策与当前状态
 
@@ -19,7 +19,7 @@ flowchart TB
   Desktop["Desktop GUI"] --> DesktopAdapter["Desktop / Tauri adapter"]
   Web["Web UI"] --> WebAS["loopback WebSocket App Server"]
   TUI["Interactive TUI"] --> Backend["TuiBackend"]
-  Backend -->|"Embedded"| EmbeddedAS["in-process App Server"]
+  Backend -->|"Embedded current"| EmbeddedAS["in-process App Server"]
   Backend -->|"--shared"| SharedIPC["private Runtime IPC v17"]
   Other["Headless CLI · ACP · Peer Host · SDK Host"] --> Adapter["独立 first-party adapters"]
   DesktopAdapter --> API["Agent Runtime API / owner ports"]
@@ -40,42 +40,52 @@ flowchart LR
   Runtime -. "injects Runtime API and owner ports" .-> Host
 ```
 
-两张图中的实线表示当前业务请求，虚线只表示启动期构造与依赖注入。
+Current 图只表示已经接线的业务请求路径；下方 composition 图中的虚线只表示启动期构造与依赖注入。
 
-### 1.2 Proposed Rich Client target
+### 1.2 Approved Embedded target
 
 ```mermaid
 flowchart TB
-  Rich["Desktop GUI · Web UI · Interactive TUI"] --> Host["Rich Client Host"]
-  Host --> Client["App Server client"]
-  Client --> Transport["Host-selected Embedded / Shared transport"]
-  Transport --> AppServer["App Server"]
-  Other["Headless CLI · ACP · Peer Host"] --> Adapter["独立 first-party adapters"]
-  SDK["Public Agent SDK"] --> SDKHost["SDK Host adapter"]
-  AppServer --> API["Agent Runtime API / owner ports"]
-  Adapter --> API
-  SDKHost --> API
+  TUI["Embedded interactive TUI"] --> Composition["TuiBackend composition"]
+  Composition --> RuntimePort["TuiRuntimePort"]
+  RuntimePort --> Direct["DirectRuntimeTuiRuntime"]
+  Direct --> API["Agent Runtime API / owner ports"]
+  Composition --> Management["owner service/provider interfaces"]
+  API --> Owners["Session / Tool / Permission / MCP owners"]
+```
+
+这是已批准但尚未交付的 Embedded direct-runtime 目标，属于 Phase 5；在 Host 完成迁移和验证前，Current 图中的 Embedded App Server 路径保持不变。
+
+### 1.3 Optional Shared App Server proposal
+
+```mermaid
+flowchart LR
+  C1["Shared Rich Client 1"] --> Transport["candidate private Pipe / UDS"]
+  C2["Shared Rich Client 2"] --> Transport
+  Transport --> Host["Shared App Server Host"]
+  Host --> Runtime["one Agent Runtime owner"]
+  Runtime --> Storage["Workspace / Session storage"]
 ```
 
-该图是待评审目标，不是当前调用链。Shared App Server 只有达到 v17 的连接治理、安全、恢复、取消、限制、性能和回滚门槛后，
-才可替换 compatibility transport；评审也可以决定保留 private v17 作为 Shared TUI 的物理 wire。
+这是 Phase 6 的待评审提案，不是当前 Shared TUI 的必经链路，也不改变 Current 图中的 private Runtime IPC v17。只有完成连接治理、安全、恢复、取消、限制、性能和回滚门槛后，才可评审是否替换 v17；评审也可以决定长期保留 v17。
 
-### 1.3 Current implementation facts
+### 1.4 Current implementation facts
 
 | 范围 | 当前状态 |
 |---|---|
-| Embedded Desktop GUI | 继续使用 Desktop 事件投影和 Tauri adapter；按实际打开的本机 workspace 延迟取得并持有 Embedded ownership，不增加后台进程；目标迁入同进程私有 App Server |
-| Embedded interactive TUI | 已组装同进程私有 App Server，通过 in-memory transport、`AppServerClient` 和 `AppServerTuiBackend` 完成当前核心聊天、Session 与 Phase 3/4 管理面路径 |
+| Embedded Desktop GUI | 当前继续使用 Desktop 事件投影和 Tauri adapter；按实际打开的本机 workspace 延迟取得并持有 Embedded ownership，不增加后台进程；Embedded direct Runtime 是后续 Host/infrastructure 目标，不在此处宣称已接线 |
+| Embedded interactive TUI | 当前仍通过同进程私有 App Server、in-memory transport、`AppServerClient` 和 `AppServerTuiBackend`；目标切换为 backend composition，由 `DirectRuntimeTuiRuntime` 直接调用 `AgentRuntime` typed API |
 | Embedded Headless CLI/Peer Host | 保留各自独立 Runtime adapter、展示和断流策略；不因交互式 TUI 迁移而强制使用 App Server |
 | ACP/SDK Host | 使用同一个 Runtime 事件入口的 session-scoped 订阅；各自协议和进程生命周期保持独立 |
 | Runtime ownership | Desktop、CLI、ACP、SDK Host 和现有 Server agent bootstrap 共用 Core owner；Embedded 取得共享锁，Shared TUI 取得独占锁，同一 workspace 上两种 deployment 互斥 |
 | Session 写入 | BitFun Runtime 的持久化 Session 由 `SessionManager` 管理；同一存储位置中的同一 Session 同时只允许一个本机进程写入，list/view 等只读操作不受影响 |
 | 当前 HTTP Server | 已组装 Embedded Runtime 和 `BitfunAppServer`，每个 `/ws` 连接通过 WebSocket transport 运行一条 App Server connection；当前固定 loopback、单用户且缺少连接级身份与作用域绑定，不构成远程或多用户 Server API |
 | Shared local IPC | 未发布的 v17 本机协议已有 discovery、实例锁、严格握手、Session 控制权、有界事件流和 cleanup；唯一 consumer 是第一方交互式 TUI compatibility adapter；是否由 Shared App Server 替换仍待评审与等价证据 |
-| Shared TUI | `bitfun --shared` / `bitfun chat --shared` 可列出、创建、恢复 Session，删除未被控制的空闲非当前 Session，通过 `/fork` 从完整历史或选中提示词之前创建分支，重命名当前 Session，读取 transcript，通过 **View subagents** 只读查看当前根 Session 的子会话并定向取消子会话活动 Turn，切换当前 Session 的 Agent mode/model，通过 `/reload [skills|instructions]` 刷新声明式上下文，通过 `/compact` 或 `/summarize` 压缩当前 Session 上下文，在 Turn 空闲时通过 `/diff` 读取 Runtime 绑定工作区的只读差异，提交/取消 Turn，处理 Permission 和 UserInput；Model、Skill、Subagent、MCP、External Source V1 和 Hook 管理由 Shared CLI Host 显式装配 App Server 的具体 `AppManagementService` 保留；Account/Settings Sync、Worktree 和后续 External Application V2 未由当前 Shared Host 提供，默认仍是 Embedded |
+| Shared TUI | `bitfun --shared` / `bitfun chat --shared` 可列出、创建、恢复 Session，删除未被控制的空闲非当前 Session，通过 `/fork` 从完整历史或选中提示词之前创建分支，重命名当前 Session，读取 transcript，通过 **View subagents** 只读查看当前根 Session 的子会话并定向取消子会话活动 Turn，切换当前 Session 的 Agent mode/model，通过 `/reload [skills|instructions]` 刷新声明式上下文，通过 `/compact` 或 `/summarize` 压缩当前 Session 上下文，在 Turn 空闲时通过 `/diff` 读取 Runtime 绑定工作区的只读差异，提交/取消 Turn，处理 Permission 和 UserInput；当前管理面具体接线为 `SharedTuiBackend -> concrete AppManagementService -> existing product owners`，其中 `AppManagementService` 是现有 owner 上的 adapter；按 domain 拆分 owner service/provider 是 Phase 5 的后续工作；Account/Settings Sync、Worktree 和后续 External Application V2 未由当前 Shared Host 提供，默认仍是 Embedded |
 | Shared GUI/Headless/ACP/SDK Host/Remote | 未交付，也不会由 `--shared` 隐式启用；Replay、Observer、通用 Controller transfer 和 Session archive 同样不在当前协议中 |
 
-因此当前交付的是 Embedded TUI App Server 与一条窄的、显式启用的 Shared TUI compatibility deployment，不是通用本机 Server。
+因此当前交付的是 Embedded TUI App Server 与一条窄的、显式启用的 Shared TUI compatibility deployment；
+下一步将先把 Embedded TUI 切换为 direct Runtime adapter，不把它扩展成通用本机 Server。
 具体 `EventQueue` 仍由 Core 产品装配；当前 Shared IPC 只把 TUI 必需的强类型操作和事件映射到同一个 Runtime owner，
 没有公开协议承诺。是否以 App Server Shared transport 替换并删除它，由行为等价、性能、安全和回滚证据决定。
 
@@ -86,7 +96,8 @@ flowchart TB
 | Agent Runtime | 负责 Session、Turn、Tool、MCP、Permission、Hook、事件和持久化行为的既有模块 | 进程名、Server 或 SDK |
 | Embedded deployment | Runtime 与调用入口位于同一 Rust 进程 | 简化版 Runtime |
 | Shared deployment | 同一 Runtime 由一个本机进程承载，多个第一方 Client 通过私有 IPC 使用 | 新 Runtime、公开 Server 或 Agent SDK |
-| Embedded App Server | 与 Rich Client Host 同进程的私有 App Server 实例和 in-memory transport | Runtime 直连、后台进程或网络 Server |
+| Embedded direct Runtime | Host 通过稳定 Rust typed facade 调用同进程 Runtime owner | 第二套 Runtime、Core singleton 直连或 App Server wire |
+| Embedded App Server | 当前 TUI 使用、仅作迁移前基线的同进程 App Server 实例和 in-memory transport | Embedded 的目标默认路径、后台进程或网络 Server；Phase 5 切换后删除 |
 | Shared App Server | 独立本机 Host 承载、由多个已认证 Rich Client 通过受控 transport 使用的 App Server | 公网 API 或每个 Client 一个 Runtime |
 | Agent SDK Host | 将公开 SDK 合同映射到 Runtime API 的私有进程/adapter | CLI、Shared deployment 或 Plugin Host |
 | Plugin Host | 运行 Node/Bun 和第三方插件代码的受监督子进程 | Agent Runtime 或 Rust IPC client |
@@ -106,19 +117,26 @@ flowchart TB
 
   Desktop["Desktop GUI"] --> DesktopAdapter["Desktop / Tauri adapter"]
   Web["Web UI"] --> AppServer["loopback WebSocket App Server"]
-  EmbeddedTUI["Embedded TUI"] --> AppServer
+  EmbeddedTUI["Embedded TUI"] --> EmbeddedCurrent["in-process App Server · current"]
+  EmbeddedTUI -. "target" .-> Composition["TuiBackend composition"]
+  Composition --> RuntimePort["TuiRuntimePort"]
+  RuntimePort --> DirectRuntime["DirectRuntimeTuiRuntime"]
+  Composition --> Management["owner service/provider interfaces"]
   DesktopAdapter --> API
   AppServer --> API
+  DirectRuntime --> API
   SharedCompat["Shared Runtime IPC · temporary compatibility"] --> API
   Headless["Headless / ACP adapters"] --> API
   SDK["SDK Host adapter"] --> API
   Remote["Remote adapter"] --> API
 ```
 
-当前复用的是 Runtime API、权威事实和 owner；Web 与 Embedded TUI 额外复用 App Server wire，Shared TUI 使用 private v17，Desktop
-仍使用自己的 adapter。第 1.2 节目标只有通过评审并完成迁移后才扩大 App Server 复用范围。各入口不复用 renderer、CLI 参数、SDK
-wire、远程认证或平台窗口生命周期。任何新能力必须先进入既有 Runtime owner，再由 App Server 或需要它的独立 adapter 映射，禁止
-在 Embedded、Shared 或其他入口复制业务实现。
+当前复用的是 Runtime API、权威事实和 owner；Web 额外使用 App Server wire，Embedded TUI
+当前使用 App Server、目标改为 direct Runtime adapter，Shared TUI 的共同 Runtime 行为使用
+private v17。TUI 管理面由 composition 按 domain 注入 owner service/provider，不随 Runtime
+port 进入 Shared wire。各入口不复用 renderer、CLI 参数、SDK wire、远程认证或平台窗口生命周期。
+任何新能力必须先进入既有 Runtime 或 owner service，再由 App Server、direct adapter 或其他独立
+adapter 映射，禁止在 Embedded、Shared 或其他入口复制业务实现。
 
 ### 3.1 Embedded 事件交付
 
@@ -126,9 +144,11 @@ wire、远程认证或平台窗口生命周期。任何新能力必须先进入
 flowchart LR
   Queue["EventQueue"] --> Owner["Core product event queue owner"]
   Owner -->|"injects read-only AgentEventSource"| Runtime["Agent Runtime API"]
-  Runtime --> AppServer["Embedded App Server"]
-  AppServer --> TUI["Interactive TUI client"]
-  AppServer --> GUI["Desktop GUI client · target"]
+  Runtime --> AppServer["App Server · Web/Shared when needed"]
+  Runtime --> Direct["Embedded direct Runtime adapter"]
+  AppServer --> TUI["Rich Client connection"]
+  Direct --> TUIEmbedded["Embedded TUI client"]
+  AppServer --> GUI["Desktop/Web client"]
   Runtime --> Exec["Headless adapter"]
   Runtime --> Peer["Peer fanout adapter"]
   Runtime --> ACP["ACP adapter"]
@@ -136,7 +156,8 @@ flowchart LR
 ```
 
 - Core product assembly 创建事件 source，并维持旧消费队列的排空 task；第一方产品入口不再获得第二个订阅 API。
-- App Server server 从注入的 `AgentEventSource` 转发 Rich Client 权威事件；Rich Client 不得从 `AgentRuntime` 或 Core `EventQueue` 旁路订阅。
+- App Server server 从注入的 `AgentEventSource` 转发需要连接边界的 Rich Client 权威事件；这些 client 不得绕过 App Server 订阅 Core `EventQueue`。
+- Phase 5 的 Embedded direct adapter 将通过 `AgentRuntime` 提供的 typed event/Permission subscription 直接订阅同一 Runtime owner，再映射为 `TuiRuntimePort` semantic event；它不得创建第二个 Core `EventQueue` owner 或把 Runtime 内部 receiver 暴露给 TUI。
 - Headless CLI、Peer Host、ACP 和 SDK Host 从各自独立 Runtime adapter 订阅，不能直接持有 Core-specific event source。
 - `bitfun-core` 的旧 event-source/builder API 仅保留为 deprecated 源码兼容 facade；它们委托给同一个 Core owner，不形成第二套运行时或第一方调用路径。
 - 各 adapter 继续拥有自己的失败投影：TUI 标记当前视图不可信，Headless CLI 返回非成功终态，Peer Host 中断其拥有的 turns，ACP 取消 turn 并返回协议错误，SDK Host 终结 Query 并提供 `RestartHost` recovery。
@@ -145,7 +166,7 @@ flowchart LR
   持久化 replay/resume：重连后的旧 cursor 不能继续消费，client 必须重新 initialize 并执行权威 sync。
 - Shared Runtime IPC v17 不复用 App Server cursor。它按自己的有界队列规则处理 lag/closed：Agent 流失效后 fail closed；Permission lag
   尝试从 Runtime 的 pending 集合重建，重建失败或流关闭时取消当前 Turn 并退出。任何路径都不能把流失效伪装成透明恢复。
-- 这条链路仍全部位于当前 Embedded 进程；Rich Client 使用 private in-memory transport，不增加 SDK Host、跨进程 IPC 或后台进程依赖。
+- 当前旧 Embedded App Server 链路位于 Embedded 进程；direct-runtime 目标会删除 private in-memory transport、App Server task/thread 和其 JSON-RPC 编解码，不增加 SDK Host、跨进程 IPC 或后台进程依赖。
 
 ## 4. Process View · Level 1
 
@@ -284,13 +305,13 @@ sequenceDiagram
 - v15 为后代 transcript 读取增加 `required_settled_turn_ids` 一致性前置条件：Runtime 必须确认这些 Turn 已由 owner 持久化为终态，否则返回 `outcome_unknown`，由 TUI 在同一绝对期限内退避重试；TUI 只保留事件投影和该读屏障，不合并或重写权威 transcript。后代取消同时携带用户实际看到的 `expected_active_turn_id`，并在 owner 锁内拒绝已经切换的 Turn，避免迟到操作取消后续执行。lineage 查询和 transcript 读取是每连接至多一个的可抢占推测读取；更新的请求会取消旧读取，使后代取消和 Session 切换不会排在慢 transcript I/O 之后。该行为不放宽 controller 校验，不引入 observer 或通用多路复用。
 - v16 增加只读、workspace-scoped main Agent 摘要，用于 Shared TUI 与 Runtime host 的 selector 投影一致。启动页以 Runtime 启动工作区查询且不取得 Session lease；已有 Session 由 Runtime owner 解析其执行工作区并要求当前 controller。响应只包含逻辑 ID、描述、可选固定 model ID 与 ecosystem-neutral 的 external-source 分类；发现、审批、冲突消解、generation 与执行仍由既有 Agent Registry 和 external-source owner 负责，不经 IPC 暴露安装、变更、激活、Subagent 管理或 runtime lifecycle API。
 - v17 扩展原子 restore，使响应带回 Runtime Session state；增加结构化 Session usage、等待指定 Turn settlement，以及记录本地命令
-  transcript turn 的 operation。它只补齐当前 Shared TUI 与 `TuiBackend` 的行为等价，没有增加 replay、observer、通用 controller
-  transfer、多 Session multiplex 或公开 SDK 能力。
+  transcript turn 的 operation。它补齐当前 Shared TUI 的行为，并为 Phase 5 将冻结的 `TuiRuntimePort` 提供 operation 基线；没有增加
+  replay、observer、通用 controller transfer、多 Session multiplex 或公开 SDK 能力。
 - 一个连接最多控制一个 Session、同时最多提交一个活动 Turn；一个 Session 同时只有一个 controller。create/restore/fork 在完整结果通过大小检查后才原子切换控制权，失败时保留原 Session。fork 只接受当前 controller 的空闲 Session；无选中 Turn 时复制到最新持久化 Turn，指定 `before_turn_id` 时只复制该 Turn 之前的历史。活动 Turn 期间不能切换或 fork Session，也不能修改其名称、Agent mode 或 model；删除只作用于非当前且未被任何连接控制的 Session。
 - Submit 与手动 context compaction 都使用调用方已有的 `turn_id` 标识不确定结果；若操作超时，返回 `outcome_unknown`、关闭连接并按该 ID 取消。手动 compaction 要求当前 controller 且 Session 空闲，由 Core 通过与普通对话 Turn 共用的原子准入路径创建一个可审计 maintenance Turn，并在取得所有权后读取压缩上下文：planning 阶段允许取消，atomic commit 开始后忽略晚到取消并保持 Processing 直至终态持久化完成。maintenance Turn 保留在权威 transcript 中但不进入模型上下文，live/restored payload 使用同一 compression ID 和 `applied` 事实；commit 后的持久化故障发布明确失败终态而不是遗留 Processing。断连取消只有得到确认后才释放 Session 控制权；无法确认时继续隔离该 Session，直到 Runtime 进程退出。
 - Session delete/rename 和 Agent mode/model update 复用既有 Runtime 端口和校验，Runtime 对最终结果保持权威并拒绝无效目标。它们都是有副作用操作；发送前编码或 frame 上限失败表示请求未执行，连接仍可使用。rename 写入失败时恢复旧 metadata：确认恢复后返回明确失败，无法确认时返回 `outcome_unknown`。Shared Client 在请求写入后响应超时或丢失连接时也返回 `outcome_unknown` 并断开连接。两种情况都不自动重试：rename 由用户恢复 Session 并核对当前值；delete 由用户重新打开 `/sessions` 核对目标是否仍存在。模型目录以及完整 Agent/Subagent 管理仍是同版本第一方产品事实，不加入 IPC；v16 的 main Agent 摘要只是 host-owned selector 所需的最小只读投影。
 - 声明式上下文 reload 只失效当前 Session 的 instructions 缓存，并按目标复用 Skill Registry 刷新；它可在活动 Turn 中执行但不改写该 Turn，generation 保护保证下一条消息重建上下文。它不引入 watcher、热替换或第二套 Runtime owner。
-- v17 保留 `update current Session model` operation 及其 controller/idle/unknown-outcome 合同，但模型目录和默认值不进入该 wire。Phase 3 移除 TUI controller 对本机产品配置 owner 的直连后，`SharedTuiBackend` 通过 Host 显式注入的具体 `AppManagementService` 保留模型选择和配置；该 capability 只描述当前本机 Shared CLI adapter，不伪装成 v17 或 Remote capability。
+- v17 保留 `update current Session model` operation 及其 controller/idle/unknown-outcome 合同，但模型目录和默认值不进入该 wire。Phase 3 移除 TUI controller 对本机产品配置 owner 的直连后，`SharedTuiBackend` 通过其持有的具体 `AppManagementService` 保留模型选择和配置；Phase 5 再拆成 Host 注入的 owner service/provider adapter。该 capability 只描述当前本机 Shared CLI adapter，不伪装成 v17 或 Remote capability。
 - Agent 事件流 lag/closed 后 fail closed；Permission lag 先从 Runtime 权威 pending 集合重建，重建失败或流关闭时取消当前 Turn 并退出。路由到父 Session 的嵌套 Permission 与 AskUserQuestion 复用现有 TUI 交互，不新增第二套 UI 状态。
 - Windows Shared Runtime 在初始化前把自身放入 kill-on-close Job；Unix 仅在应用内优雅退出路径中通过受管子进程组回收后代。Runtime 被 `SIGTERM`、`SIGKILL` 或崩溃直接终止后的 Unix 后代回收不在当前保证内。两者都只负责生命周期，不是安全沙箱。
 - 最后一个连接离开后等待 30 秒再退出；新连接会取消 idle 退出。退出只删除自己发布的 discovery；Unix 下继任 owner 会在持有实例锁后清理同一 identity 的陈旧 socket。
@@ -313,7 +334,8 @@ flowchart LR
 
 | 路径 | 数据边界 | 性能约束 |
 |---|---|---|
-| Embedded Rich Client | `AppServerClient` 通过 private in-memory transport 调用同进程 App Server | 不初始化跨进程 IPC 或后台进程；保持与 Shared 相同的 JSON-RPC、DTO、错误和事件语义，编解码成本通过测量优化而不增加直连旁路 |
+| Embedded Rich Client（目标） | TUI backend composition 通过 `TuiRuntimePort` 和 owner service/provider adapter 调用同进程 Agent Runtime | 不初始化 App Server client/server、in-memory transport、跨进程 IPC 或后台进程；Runtime port 保持与 Shared/Web 相同的行为、错误、权限和事件语义，但不要求共享 JSON-RPC；管理 capability 单独按 provider 可用性验证 |
+| Embedded App Server（当前迁移基线） | 迁移前由旧 `AppServerClient` 通过 private in-memory transport 调用同进程 App Server | 仅在 Phase 5 切换前有效；切换到 direct adapter 后删除，不保留回滚路径 |
 | Embedded non-Rich Client | Headless、ACP、Peer 和 SDK Host 的独立 adapter 以 Rust 类型调用 Runtime API | 不因 Rich Client 合同承担 App Server wire；保持各自协议和生命周期 |
 | Shared request | Client 将 operation 编码一次并写入一个长度前缀 frame | 请求保持 128 KiB 上限；业务层只接收类型化 operation |
 | Shared response/event | Server 将结果或事件编码一次后写出 | 响应/事件保持 8 MiB 上限；超限使事件流明确失效，不能无界分配 |
@@ -355,56 +377,82 @@ flowchart TB
 
 ```mermaid
 flowchart LR
-  TUI["Interactive TUI"] --> Backend["TuiBackend"]
-  Backend -->|"Embedded"| Client["AppServerClient"]
-  Client --> Memory["in-memory transport"]
-  Memory --> AppServer["BitfunAppServer"]
-  Backend -->|"Shared compatibility"| IPC["adapters/agent-runtime-ipc v17"]
+  TUI["Interactive TUI · Phase 5 target"] --> Composition["TuiBackend composition"]
+  Composition --> Port["TuiRuntimePort"]
+  Port -->|"Embedded default"| Direct["DirectRuntimeTuiRuntime"]
+  Direct --> Runtime["AgentRuntime typed API"]
+  Composition --> Management["owner service/provider interfaces"]
+  Port -->|"Shared compatibility"| SharedAdapter["SharedIpcTuiRuntime"]
+  SharedAdapter --> IPC["adapters/agent-runtime-ipc v17"]
   IPC --> Handler["CLI Shared handler"]
-  AppServer --> Runtime["execution/agent-runtime / owners"]
   Handler --> Runtime
 ```
 
-CLI Host 负责命令解析、TUI 状态、错误文案、App Server 组装和 transport 生命周期；`TuiBackend` 隔离当前 Shared compatibility adapter。
-App Server 或私有 IPC 只负责协议、连接控制和类型映射；Agent Runtime 与 owner 负责 Session 校验、持久化和权威结果。
-TUI 业务代码不根据部署形态复制业务分支，Shared 达到 App Server 语义等价后替换 compatibility adapter。
+第二张图只描述已批准但尚未交付的 Phase 5 TUI composition 目标。当前生产接线仍以第一张图为准：
+Embedded 使用 `AppServerTuiBackend`，Shared 使用 `SharedTuiBackend -> Runtime IPC v17`。Phase 5 中，
+CLI Host 将负责命令解析、TUI 状态、错误文案、direct Runtime adapter 选择和生命周期；
+backend composition 将由 `TuiRuntimePort` 承载共同 Runtime 行为，并按 domain 注入 owner service/provider
+接口承载管理面。Direct adapter 负责 typed request/result/event 映射，Shared adapter 负责私有 IPC
+的协议与连接控制；Agent Runtime 与 owner 负责 Session 校验、持久化和权威结果。TUI 业务代码
+不根据部署形态复制业务分支，Shared 是否替换 v17 仍按独立门槛决定。这里不定义一个总括性的
+`TuiManagementPort`。
 
 - CLI 不依赖 SDK Host，GUI/TUI 也不依赖公开 SDK package。
-- 交互式 TUI 的启动页和会话页复用 app-local `TuiBackend`；Embedded backend 使用正式 `AppServerClient`，Shared backend 暂时映射 private Runtime IPC v17。TUI 不直接依赖 Rust Runtime SDK、Core/Service owner 或 IPC operation。
+- Phase 5 完成后，交互式 TUI 的启动页和会话页将复用 app-local backend composition；Embedded Runtime 调用使用 `DirectRuntimeTuiRuntime`，Shared Runtime 调用经 `SharedIpcTuiRuntime` 映射 private Runtime IPC v17。TUI 不直接依赖 Rust Runtime SDK、Core/Service owner 或 IPC operation。
+- 管理面由 composition 按 domain 直接注入 owner-owned 的稳定 service/provider trait；原始接口若暴露内部类型，或需要 TUI DTO、权限/上下文和 capability 裁剪，才抽取薄 facade。不得创建 `TuiManagementPort` 总接口，也不得把 App Server 的 `AppManagementService` 原样迁入 CLI/TUI。
+- Web 当前独立使用自己的 loopback WebSocket App Server Host，不进入 TUI backend composition。Shared 当前只有 private Runtime IPC v17；Shared App Server 只存在于第 1.3 节的 Phase 6 candidate 图中。
 - Headless CLI 和 Peer Host 使用同一 Runtime 订阅入口，但分别保留确定性退出与 Peer fanout 语义；共享订阅入口不等于共享 renderer 或产品生命周期。
-- TUI 不是 Server；Embedded Host 在同进程组装私有 App Server，是否连接 Shared deployment 是部署选择，不改变 TUI 的 renderer/键位职责或 App Server 行为合同。
+- TUI 不是 Server；Phase 5 目标中的 Embedded Host 在同进程直接调用 Runtime，是否连接 Shared deployment 是部署选择，不改变 TUI 的 renderer/键位职责或行为合同。
 - Agent SDK Host 只服务外部 SDK 合同，不成为第一方 rich-client 的通用底座。
 - Headless CLI 默认继续 Embedded；CI 或测试可保持独立进程和独立 workspace，不承担后台实例成本。
-- Tauri 仍负责窗口和桌面能力，并逐步收窄为 App Server Host adapter；未来它可以管理 Shared process 的启动/重连，但不拥有 Agent Runtime 业务生命周期。
+- Tauri 仍负责窗口和桌面能力，并逐步收窄为 product Host adapter；Embedded 产品请求可由 direct Runtime adapter 承载，需要连接边界时再使用 App Server，未来也可以管理 Shared process 的启动/重连，但不拥有 Agent Runtime 业务生命周期。
 
 ### 5.2 Physical View
 
+#### 5.2.1 Current production
+
 ```mermaid
 flowchart TB
-  subgraph Embedded["默认 Embedded"]
-    TUI["Interactive TUI"] --> AppServer["private in-process App Server"]
+  subgraph Embedded["Embedded · current"]
+    TUI["Interactive TUI"] --> AppServer["in-process App Server"]
     AppServer --> Runtime["in-process Agent Runtime"]
     Headless["Headless / CI"] --> Runtime
   end
-  subgraph Shared["显式 --shared"]
+  subgraph Shared["Shared · current explicit --shared"]
     Clients["one or more TUI processes"] -->|"Named Pipe / UDS · current compatibility"| SharedRuntime["Shared Runtime Host process"]
   end
   Runtime --> Data["workspace + Session storage"]
   SharedRuntime --> Data
 ```
 
-默认交互式 TUI、Headless CLI 和 CI 保持 Embedded；交互式 TUI 通过 private in-process App Server，Headless/CI 保留独立 adapter。
-只有显式 `--shared` 的交互式 TUI 进入 Shared；同一 workspace 的两种部署互斥。多开 TUI 增加 Client 进程和有界连接，
-不按 Client 数量复制 Runtime、Session owner 或 Plugin Host。
+当前默认交互式 TUI 通过同进程 App Server，Headless CLI 和 CI 通过各自 adapter 调用同进程
+Runtime。只有显式 `--shared` 的交互式 TUI 进入 Shared；同一 workspace 的两种部署互斥。
+多开 TUI 增加 Client 进程和有界连接，不按 Client 数量复制 Runtime、Session owner 或 Plugin Host。
+
+#### 5.2.2 Approved Phase 5 Embedded target
+
+```mermaid
+flowchart LR
+  TUI["Embedded interactive TUI"] --> Direct["Direct Runtime adapter · not yet delivered"]
+  Direct --> Runtime["in-process Agent Runtime"]
+  Runtime --> Data["workspace + Session storage"]
+```
+
+Phase 5 只把 Embedded interactive TUI 从当前 App Server 一次性切到 direct Runtime adapter，并删除
+旧 in-process App Server；Headless/CI 保留独立 adapter，Shared 继续使用前一张 Current 图中的
+private Runtime IPC v17。旧 App Server 不作为回滚配置保留。
+
+### 5.3 Scenario (+1) · Phase 5 target: rename current Session
 
-### 5.3 Scenario (+1) · Rename current Session
+该场景将尚未交付的 Embedded direct adapter 与当前 Shared v17 行为放在同一等价目标中；它不表示
+Embedded Phase 5 已完成。
 
 ```mermaid
 sequenceDiagram
   participant U as User
   participant T as TUI adapter
   participant B as TuiBackend
-  participant E as Embedded App Server adapter
+  participant E as Embedded direct Runtime adapter
   participant S as Shared Runtime IPC v17 adapter
   participant R as Agent Runtime
 
@@ -412,8 +460,8 @@ sequenceDiagram
   T->>T: trim + require idle Session
   T->>B: typed TuiBackend request
   alt Embedded
-    B->>E: typed App Server request
-    E->>R: owner port call
+    B->>E: typed Runtime request
+    E->>R: AgentRuntime method
     R->>R: validate ownership + persist
     R-->>E: applied / failed / outcome_unknown
     E-->>B: mapped typed result
@@ -430,14 +478,14 @@ sequenceDiagram
 
 Embedded 和 Shared 最终调用同一 `AgentRuntime::rename_session`。Runtime 只有在确认旧名称已保留时才返回明确失败；持久化恢复无法确认时，两种部署都返回 `outcome_unknown`。Shared 还会在请求已发送但权威响应丢失时返回该结果并关闭连接。用户恢复 Session、检查当前名称后再决定是否重试。
 
-### 5.4 Scenario (+1) · Delete an idle Session
+### 5.4 Scenario (+1) · Phase 5 target: delete an idle Session
 
 ```mermaid
 sequenceDiagram
   participant U as User
   participant T as TUI adapter
   participant B as TuiBackend
-  participant E as Embedded App Server adapter
+  participant E as Embedded direct Runtime adapter
   participant S as Shared Runtime IPC v17 adapter
   participant R as Agent Runtime
 
@@ -445,8 +493,8 @@ sequenceDiagram
   T->>T: reject current or active target
   T->>B: typed TuiBackend request
   alt Embedded
-    B->>E: typed App Server request
-    E->>R: owner port call
+    B->>E: typed Runtime request
+    E->>R: AgentRuntime method
     R->>R: existing delete owner
     R-->>E: applied / failed / outcome_unknown
     E-->>B: mapped typed result
@@ -509,18 +557,18 @@ Session/Turn、事件恢复、Permission/UserInput、Controller、配置管理
 | [Codex App Server](https://developers.openai.com/codex/app-server/) | App Server 为 rich client 和 remote TUI 提供 JSON-RPC；自动化继续使用 SDK；WebSocket transport 仍是实验性接口 | Rich Client 使用 App Server，自动化/公开 SDK 保持独立，并为 Shared 入口保留有界本机 transport | 不复制其完整 schema，也不把实验性远程 transport 当作已交付公网 API |
 | [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/typescript) | Agent loop 由长期运行的 CLI 子进程承载，并提供 `startup()` 预热以减少首次请求成本 | 长期 Shared 交互可以复用已启动进程，空闲后回收 | Embedded Rich Client 不增加子进程，多 TUI 也不映射为多个 Runtime |
 
-三种产品说明了不同部署的有效边界：稳定 Rich Client 合同可以同时承载进程内和多客户端 transport，长期子进程适合 Shared
+三种产品说明了不同部署的有效边界：稳定产品行为合同可以分别映射到进程内 direct adapter 和多客户端 transport，长期子进程适合 Shared
 交互或语言 SDK，独立强类型 adapter 适合 Headless/ACP 等非 Rich Client。BitFun 采用混合部署，不把 App Server 强制成所有入口的
 公共底座；当前也没有为了追赶功能表一次性增加 Session/Tool/Permission 超集。
 
 ## 9. 不变量
 
 - 只有一套 Agent Runtime 业务实现；部署差异不能产生第二套 Session、Tool、Permission 或 MCP owner。
-- 当前入口使用第 1.1 节列出的 adapter；若第 1.2 节目标通过评审并迁移完成，Desktop GUI、Web UI 和交互式 TUI 才统一使用 App Server。
+- 当前入口使用第 1.1 节列出的 adapter；Embedded TUI 的下一步是从 App Server 切换到 direct Runtime adapter，Web/需要连接边界的 Rich Client 继续使用 App Server。
 - Client、窗口、Session 或 workspace 数量不会自动等量增加 Runtime 或 Plugin Host 进程。
 - 当前 Shared Runtime IPC 是第一方 TUI 的 private compatibility transport，不成为公开 SDK、Remote、Peer、HTTP 或浏览器协议；是否由 App Server Shared transport 替换仍待评审。
-- Shared TUI 的 Model、Skill、Subagent、MCP、External Source V1 和 Hook 管理暂由 CLI Host 显式装配的 App Server `AppManagementService` 承接；Account/Settings Sync、Worktree 和后续 External Application V2 未由当前 Shared Host 提供并返回 typed unsupported。这不扩展 v17，不改变 Shared Runtime 对 Session/chat 的权威性，也不能用于 Remote workspace 的控制端本机回退。MCP service 的进程状态和 tool registry 只属于当前 CLI 进程，不即时重配已经运行的 Shared Runtime Host；跨进程 MCP 管理需要单独的同步/restart contract。
-- 默认 GUI/TUI/Headless CLI、ACP 与 SDK Host 保持 Embedded；只有交互式 TUI 的显式 `--shared` 选择 Shared。互斥按 `workspace + product` 生效，不再按入口名称缩窄。
+- Shared TUI 的 Model、Skill、Subagent、MCP、External Source V1 和 Hook 管理当前由 `SharedTuiBackend` 委托其持有的具体 `AppManagementService`；Phase 5 再拆成 CLI Host 显式装配的 owner service/provider adapter。这些管理 capability 不进入 Phase 5 的 `TuiRuntimePort` 或 v17 wire。Account/Settings Sync、Worktree 和后续 External Application V2 未由当前 Shared Host 提供并返回 typed unsupported。这不扩展 v17，不改变 Shared Runtime 对 Session/chat 的权威性，也不能用于 Remote workspace 的控制端本机回退。MCP service 的进程状态和 tool registry 只属于当前 CLI 进程，不即时重配已经运行的 Shared Runtime Host；跨进程 MCP 管理需要单独的同步/restart contract。
+- 默认 GUI/TUI/Headless CLI、ACP 与 SDK Host 保持 Embedded；Phase 5 完成后，只有 Embedded TUI 产品请求切换为直接调用同进程 Runtime，并删除旧 Embedded App Server。Desktop direct Runtime 是独立的已批准迁移步骤，不由 TUI Phase 5 的完成状态代替；Headless CLI、ACP 与 SDK Host 继续使用各自 adapter。只有交互式 TUI 的显式 `--shared` 选择 Shared。互斥按 `workspace + product` 生效，不再按入口名称缩窄。
 - Account/session cloud sync 仍使用既有 Core compatibility 边界，不属于 Shared Runtime 支持。
 - Remote workspace 的文件、凭据、进程和 Runtime 位于目标执行域，禁止静默回落本机。
 - 未经真实 consumer 验证的接口不进入 wire；当前 wire 只包含表中列出的 Shared TUI 操作。
diff --git a/docs/architecture/agent-runtime-services-design.md b/docs/architecture/agent-runtime-services-design.md
index 9c9c5b28d4..671b5a611c 100644
--- a/docs/architecture/agent-runtime-services-design.md
+++ b/docs/architecture/agent-runtime-services-design.md
@@ -68,7 +68,7 @@ Agent Runtime API 的逻辑归属与物理部署分离：相同归属模块可
 私有 SDK Host 或目标机器 Runtime 中。任何 Rust 部署都只管理自己进程树内的服务与 Node/Bun Plugin Host；不能因为多个
 GUI/TUI/Remote Client 连接就复制 Runtime 状态模块，或按 Client/Workspace 创建 Plugin Host。
 
-Rust Runtime SDK 以 `AGENT_RUNTIME_SDK_API_VERSION` 标记兼容边界。当前接口版本为 v5 preview：
+Rust Runtime SDK 以 `AGENT_RUNTIME_SDK_API_VERSION` 标记兼容边界。当前接口版本为 v6 preview：
 小版本更新允许增加可选 builder hook、有默认实现的端口方法或注册表查询能力，但不得向外部可用
 Rust 结构体字面量（struct literal）构造的 DTO 直接增加字段，也不得改变既有端口语义、错误分类、session / turn 标识含义或
 默认 feature 依赖。任何需要调用方改写现有嵌入代码的变更，必须提升接口版本并提供兼容迁移路径。
@@ -83,6 +83,12 @@ v3 为 `AgentDialogTurnRequest` 增加来源无关的 `execution` 事实。现
 v4 将活动 Turn 的文本 steer 纳入 `AgentDialogTurnPort`，复用同一个 Runtime owner 和精确 Session/Turn
 身份校验；默认端口实现仍返回 `NotAvailable`，未选择该能力的 provider 不需要建立第二套 queue 或 transport。
 
+v6 将完整 Rust Runtime SDK 从空默认编译面移入 `agent-runtime` owner feature。现有 Rust embedder
+迁移时在 `bitfun-agent-runtime` 依赖上显式选择 `features = ["agent-runtime"]`；启用后 `sdk` 模块、
+公开路径和运行时行为保持不变。只消费 DeepResearch 编号或 Hook 设置的调用方应分别选择
+`deep-research` 或 `native-hook-settings`，不需要继承完整 Runtime。仓库内最小 SDK example 通过
+`required-features = ["agent-runtime"]` 明确记录这一版本边界。
+
 只要外部调用方仍必须导入 `bitfun-core`、启用 `product-full`、持有具体服务管理器、读取产品命令
 注册表、理解 ACP/内部端口或依赖全局可变状态，公开 SDK 发布边界就不成立。公开 SDK 的完整
 术语、能力等价和版本要求以 [`agent-sdk-product-architecture.md`](agent-sdk-product-architecture.md) 为准。
@@ -426,7 +432,7 @@ impl AgentRuntime {
 该 Rust 接口是内部产品入口复用的当前形态，不是公开 Python/TypeScript SDK 的目标 API。它必须只接收
 已组装的类型化部件，不负责创建
 文件系统、终端、MCP、AI 客户端、Remote 提供方或产品命令。
-当前 v4 preview 接口以 message / attachment / metadata、默认标准执行目标和活动 Turn 文本 steer 作为最小输入形态；若把
+当前 v6 preview 接口以 message / attachment / metadata、默认标准执行目标和活动 Turn 文本 steer 作为最小输入形态；若把
 model-round cancellation token、结构化 AgentInput 或更复杂的事件游标纳入公开 SDK，
 必须分别评审 Rust Runtime SDK、SDK Host protocol 和公开 SDK API 的版本，并保留旧路径兼容。
 
diff --git a/docs/architecture/agent-sdk-product-architecture.md b/docs/architecture/agent-sdk-product-architecture.md
index 5d72ba2275..4e6024a2c4 100644
--- a/docs/architecture/agent-sdk-product-architecture.md
+++ b/docs/architecture/agent-sdk-product-architecture.md
@@ -11,8 +11,12 @@
 
 本文只记录长期产品心智、架构边界和发布门槛。当前代码中的
 `agent-runtime::sdk` 是供 BitFun 内部入口和受控 Rust 嵌入使用的低层 Rust Runtime SDK；
-`interfaces/sdk-host` 与 `apps/sdk-host` 是本地协议和独立 Host 进程的实现候选。它们都不是已经发布的
-Python/TypeScript BitFun Agent SDK，也不能据此宣称公开 SDK 已交付。
+`interfaces/sdk-host` 与 `apps/sdk-host` 是本地协议和独立 Host 进程的实现候选；`sdk/typescript` 是仓库内私有的
+TypeScript 垂直切片，用于验证 managed Host、Query、显式 Session、取消、终态和错误语义。其 internal wire 类型与
+runtime validator 均由 Rust Host 协议生成，不构成公开 API。该切片对 Query 事件、终态聚合、JSON-RPC pending request
+和载体写队列分别设置条目与字节预算；Windows Host 通过 `services-core` 的 kill-on-close Job Object owner 持有后代进程，
+Unix managed client 通过独立进程组回收 Host 树。Python binding、平台原生 Host 包、安装与签名链路尚未交付，握手仍返回
+`not_delivered`，因此不能据此宣称公开或 Preview SDK 已交付。
 
 ## 1. 最终决策
 
@@ -247,6 +251,18 @@ flowchart LR
 | Python/TypeScript SDK | 管理或连接匹配 Host，提供一致公开 API | 要求用户安装 `bitfun` CLI；暴露内部 wire DTO |
 | `CoreRuntimeOwnership` | 第一方 Rust 入口选择 Embedded/Shared，并把本机 workspace lease 注入 Coordinator | 进入公开 SDK/wire；成为 Session 单写或 Server 路由 owner |
 
+通讯能力按“协议机械层、载体、产品协议”三层拆分：
+
+| 层次 | 共享 owner | 保留在使用方的职责 |
+|---|---|---|
+| 协议无关机械层 | `adapters/transport` 的 Rust 有界 JSON，以及同目录 TypeScript `MessageTransport`、有界 `WebSocketMessageTransport`、JSON-RPC request correlation | 不拥有业务 method、DTO、认证、Session/Query 生命周期或恢复策略；单一消费者的 length-prefix framing 留在 private IPC owner |
+| 载体 | stdio、Named Pipe/UDS、WebSocket adapter 实现统一的消息收发与背压边界 | 各 Host 继续拥有 endpoint、具体 framing、Origin/认证、重连和方向性限额策略 |
+| 产品协议 | SDK Host、private Runtime IPC 和 App Server 分别拥有自己的 wire 与行为合同 | 不因复用 JSON-RPC/消息机械能力而合并业务协议、controller/lease 或 Runtime owner |
+
+因此“复用通讯层”不等于建立万能 wire：stdio、IPC 和 WebSocket 共享有界编解码、消息收发、request correlation
+等机械能力，但 SDK Host、Shared TUI IPC 与 Web App Server 仍是同级 adapter。任何载体超限、背压失败或无法确认的
+请求结果都由对应产品 adapter 投影成自己的错误与清理语义；通用通讯层不能替它们决定自动重试或生命周期。
+
 ### 5.2 一次 Query 的运行时序
 
 ```mermaid
diff --git a/docs/architecture/app-server-architecture.md b/docs/architecture/app-server-architecture.md
index 765d7afc61..8cf3a63e62 100644
--- a/docs/architecture/app-server-architecture.md
+++ b/docs/architecture/app-server-architecture.md
@@ -1,42 +1,61 @@
 # App Server 架构设计
 
-> 状态：Proposed target；关键决策与替换门槛尚待架构评审。
+> 状态：Embedded direct-runtime 已确定为下一步实现方向；Shared App Server 仍是待评审提案。
 >
-> 基线日期：2026-08-05。
+> 基线日期：2026-08-13。
 >
-> 本文记录 BitFun Rich Client 与产品后端之间的候选 App Server 边界，不是已批准的权威架构。具体 TUI 迁移阶段、接口盘点和当前缺口见
+> 本文记录 Embedded direct-runtime 决策，以及需要连接边界时的 App Server 约束和 Shared transport 提案。具体 TUI 迁移阶段、接口盘点和当前缺口见
 > [`tui-app-server-decoupling-refactor-plan.md`](../plans/tui-app-server-decoupling-refactor-plan.md)；Agent Runtime 的进程、所有权和实例隔离见
 > [`agent-runtime-deployment-design.md`](agent-runtime-deployment-design.md)；产品 owner 与分层依赖见
-> [`product-architecture.md`](product-architecture.md)。评审完成前，当前调用路径以已接线代码和上述稳定架构文档为准。
-
-## 1. Proposed decision
-
-当前首选候选是用 App Server 统一第一方 Rich Client 的产品后端接口。它尚未批准；下列约束只描述该候选被选中后的目标状态：
-
-- Desktop GUI、Web UI 和交互式 TUI 都是 App Server Rich Client。
-- Rich Client 的 Embedded deployment 也必须经过 App Server；它创建同进程私有 App Server，并通过私有 in-memory transport 连接。
-- Embedded 不表示直连 Runtime，也不要求独立后台进程、网络监听或跨客户端实例发现。
-- Embedded 与 Shared 复用同一 App Server client、协议版本、method、DTO、类型化错误、能力发现、事件和取消语义。
-- Embedded 与 Shared 只在 transport、App Server 实例所有权、客户端数量、连接治理和资源生命周期上不同。
-- Headless CLI/CI、ACP、Peer Host 和公开 Agent SDK 不是 Rich Client，不因该候选被强制改用 App Server；它们继续使用各自经评审的 adapter。
-- App Server 是协议适配层，不接管 Agent Runtime、Service 或 Product Domain 的业务所有权。
-
-若选择该候选，不能用“Embedded 位于同一进程”作为 Rich Client 绕过 App Server 的理由，也不能用“统一 GUI/TUI 接口”把所有自动化和外部协议强制收敛到 App Server。
-
-### 1.1 Alternatives under review
+> [`product-architecture.md`](product-architecture.md)。迁移完成前，当前调用路径仍以已接线代码为准；Shared transport 未通过独立评审前继续使用 v17。
+
+## 1. Decision and remaining proposal
+
+本次重构采用候选 B/C 的受限组合：**Embedded deployment 直接调用同进程
+Agent Runtime 的 typed API；需要进程间或网络边界的 Rich Client 才使用 App
+Server**。因此，Rich Client 这一产品分类不再意味着所有部署都必须经过同一
+wire。
+
+- Embedded Host 直接持有产品组装得到的 `AgentRuntime` 和必要的 owner/provider
+  facade，通过 Rust 类型调用 Runtime 方法；不创建 `BitfunAppServer`、
+  `AppServerClient` 或 in-memory transport。
+- Embedded TUI 仍只依赖 app-local backend composition。TUI 不直接依赖 Runtime、Core
+  singleton、具体 Service 实现或私有 IPC operation；composition 内部由窄的
+  `TuiRuntimePort` 承载跨 Embedded/Shared 的 Runtime 行为，并由
+  `DirectRuntimeTuiRuntime` 完成 direct request/result/event/error 映射。
+- Model、Skill、Subagent、MCP、Account、Settings Sync、Worktree、External Source 和
+  Hook 等管理面不进入 `TuiRuntimePort`，也不定义总括性的 `TuiManagementPort`。它们由
+  backend composition 按 domain 直接注入 owner-owned 的稳定 service/provider trait；只有
+  原始接口暴露内部类型，或需要 TUI DTO、权限/上下文和 capability 裁剪时，才增加最薄的
+  owner/provider facade。`AppManagementService` 继续是 App Server wiring，不原样迁移到 CLI。
+- Web UI / WebSocket Host 继续使用 App Server，因为它们需要连接、transport、
+  认证、作用域和事件转发边界。
+- Shared TUI 继续使用 private Runtime IPC v17，直到 Shared App Server 通过
+  独立的鉴权、controller/lease、恢复、取消、背压、限制、性能和回滚门槛；本次
+  Embedded 重构不自动替换或删除 v17。
+- Headless CLI/CI、ACP、Peer Host 和公开 Agent SDK 继续使用各自经评审的
+  adapter，不因 Rich Client 的 App Server 合同被强制改用 App Server。
+- App Server 仍是协议适配层，不接管 Agent Runtime、Service 或 Product Domain
+  的业务所有权。直接 Runtime adapter 也只能调用既有 owner，不得复制业务状态。
+
+Embedded 直调不是绕过安全或行为合同。它省略的是进程内无意义的 wire 和连接治理，
+仍必须传递明确的 workspace、execution domain、权限和 request context，并复用同一
+Runtime owner、错误语义、事件语义和持久化规则。
+
+### 1.1 Decision rationale and remaining alternatives
 
 | 候选 | 结构 | 收益 | 成本与风险 | 采用门槛 |
 | --- | --- | --- | --- | --- |
-| A. App Server-first Rich Clients（当前首选） | Desktop、Web、Embedded/Shared TUI 复用一个 wire 与 typed client | 跨 Rich Client 合同和 fixture 最集中 | Embedded 编解码与 runtime/thread 成本；Desktop/Web 迁移面大；Shared 必须重新交付连接治理 | 真实 Desktop/TUI consumer、跨 transport parity、性能和安全门槛全部通过 |
-| B. Deployment-specific product adapters | Desktop、Web、Embedded TUI、Shared TUI 各保留窄 adapter，共享 owner ports | 每个 Host 可按自身生命周期优化，迁移风险较低 | DTO、错误、恢复和行为 fixture 可能分叉；跨入口一致性需额外治理 | 证明长期重复成本低于统一 wire 成本，并建立跨 adapter 行为合同 |
-| C. Shared Runtime use cases with separate wires | 提取稳定用例/结果，Embedded 使用 Rust adapter，Shared 保留 v17 或后继 wire，Web 使用 App Server | 业务语义集中，同时允许 deployment-specific framing、安全和性能 | 需要清晰区分 use-case DTO 与 wire DTO；client 不能假装同一协议 | 证明共享 use case 不泄漏 Runtime 实现，并分别验证每条 wire 的故障语义 |
+| A. App Server-first Rich Clients | Desktop、Web、Embedded/Shared TUI 复用一个 wire 与 typed client | 跨 Rich Client 合同和 fixture 最集中 | Embedded 编解码与 runtime/thread 成本；Shared 必须重新交付连接治理 | 仅适用于确实需要进程/网络边界的 Host；不再作为 Embedded 默认方案 |
+| B. Deployment-specific product adapters（Embedded 采用） | Embedded 直接调用 Runtime API；Web/Remote/Shared 按部署选择 transport adapter，共享 owner ports | 消除同进程编解码和 server task，保持 Host 生命周期简单 | DTO、错误、恢复和行为 fixture 可能分叉；需要统一行为合同 | Direct adapter 无 owner 复制，且通过跨入口行为等价测试 |
+| C. Shared Runtime use cases with separate wires（保留） | 提取稳定用例/结果，Embedded 使用 Rust adapter，Shared 保留 v17 或后继 wire，Web 使用 App Server | 业务语义集中，同时允许 deployment-specific framing、安全和性能 | 需要清晰区分 use-case DTO 与 wire DTO；client 不能假装同一协议 | Shared transport 只有通过独立门槛后才可替换 v17 |
 
-评审可以选择 A、B、C 或其受限组合。已有 `TuiBackend`、App Server 和 v17 是评估证据，不自动决定最终架构。
+Embedded 已选择 B/C 的受限组合，A 不再是 Embedded 默认方案。Shared 仍可选择经门槛验证的 App Server transport，或把 private v17/后继协议保留为部署专用 wire；已有 DTO 或 adapter 不能替代该评审。
 
 ### 1.2 Costs of the preferred candidate
 
-- Embedded Rich Client 需要承担 App Server client/server、JSON-RPC 编解码、事件队列和专用 runtime/thread 的启动、内存与延迟成本；必须以基准证明该成本可接受。
-- 迁移期会同时维护 App Server 与 Runtime IPC v17 两条 wire；新增核心用例需保持 `TuiBackend` 行为等价，不能让双写期形成两个业务 owner。
+- Embedded direct adapter 需要维护 Runtime typed API 与 TUI-facing contract 的映射；必须以行为 fixture 证明它没有复制 Session、Permission、Config 或 capability 状态。
+- 迁移前继续使用现有 Embedded App Server 作为行为基线；Phase 5 切换到 direct-runtime 后删除旧路径，不保留回滚 adapter，也不能在 direct adapter 返回 unsupported 后静默回退。
 - Shared App Server 需要重新交付 v17 已有的 framing、方向性 limits、鉴权、实例身份、controller/lease、断连取消、未知结果和空闲退出，不能只复用 method/DTO。
 - Desktop 迁移必须划清 controller-local capability、Tauri 生命周期和工作区 Host capability；Web/Remote 扩展还需要独立的认证、授权和多租户资源治理。
 
@@ -46,18 +65,30 @@
 
 | 范围 | 当前状态 | 目标 |
 | --- | --- | --- |
-| Embedded TUI | 已创建私有 `BitfunAppServer`，通过 in-memory transport 连接 `AppServerClient` | 完成剩余管理面迁移和行为等价验证 |
-| Shared TUI | 仍通过私有 Runtime IPC v17 连接独立 Runtime Host | App Server Shared transport 达到可靠性等价后迁移 |
-| Desktop GUI | 主要仍使用 Tauri command 和桌面事件投影 | Tauri 收窄为 Host adapter，产品请求统一进入 App Server |
+| Embedded TUI | 当前仍通过私有 `BitfunAppServer`、in-memory transport 和 `AppServerClient` 运行 | 切换为 backend composition，由 `TuiRuntimePort`、同进程 `AgentRuntime` 和 owner service/provider 直接提供用例 |
+| Shared TUI | 仍通过私有 Runtime IPC v17 连接独立 Runtime Host | 保留 v17；是否迁入 Shared App Server 由可靠性、安全、性能和回滚证据决定 |
+| Desktop GUI | 主要仍使用 Tauri command 和桌面事件投影 | Embedded 时使用 direct Runtime adapter；需要连接边界时使用 App Server，Tauri 保留平台能力 |
 | Web Host | 当前 Server 已组装 Embedded Runtime，WebSocket 直接承载 `BitfunAppServer`；仅适用于 loopback 单用户模式 | 补齐连接身份、作用域绑定和 Host allowlist 后才能扩展部署范围 |
 | App Server protocol/client | 已拆为 behavior-light crate，已有版本、能力、限制、错误和部分事件恢复类型 | 补齐 Host 注入能力、可靠性语义及跨 transport 合同测试 |
 | App Server server | 已注册 app、agent、session、permission、TUI/workspace、git、config 和 i18n handler | 按真实 owner 和 Host 装配收窄能力，不以已存在 DTO 代替可用性证据 |
 
-Shared TUI 继续使用 Runtime IPC 是当前 compatibility boundary。只有候选 A 获批且替换门槛通过后，才迁移或删除该 IPC；候选 B/C 可能将 private v17 或后继协议保留为受控的长期物理 wire。
+Shared TUI 继续使用 Runtime IPC 是当前 compatibility boundary。Embedded direct-runtime
+迁移不改变该边界。只有 Shared App Server 通过替换门槛后，才评审迁移或删除 v17；候选
+B/C 允许将 private v17 或后继协议保留为受控的长期物理 wire。
 
-### 1.4 Decision and replacement gates
+### 1.4 Migration and replacement gates
 
-在满足下列门槛前，不得把候选 A 标记为 approved，也不得用 Shared App Server 替换 v17：
+Embedded direct-runtime 完成迁移前必须满足：
+
+| 门槛 | 必需证据 |
+| --- | --- |
+| Typed facade 与 owner | direct adapter 只调用稳定 Runtime/owner-provider facade；不暴露内部类型，不复制 Session、Permission、Config、capability 或事件状态 |
+| 上下文与能力 | workspace、execution domain、permission、remote facts 和 capability 来自真实 Host/Runtime 组装；不从 UI 猜测，不静默本机回退 |
+| 行为与事件 | 请求结果、事件顺序、pending Permission、取消、`unsupported`、lag/closed 和 `outcome_unknown` 与既有行为合同等价 |
+| 生命周期与性能 | 不创建 App Server client/server、in-memory transport 或额外 Runtime；订阅和任务可回收，并记录启动、延迟和内存对比 |
+| 迁移与删除 | 同一 TUI fixture 覆盖 direct 与旧 App Server；升级/降级读取兼容，旧路径仅作为迁移基线并在切换后删除 |
+
+Shared App Server 只有满足以下连接治理门槛后才可替换 v17：
 
 | 门槛 | 必需证据 |
 | --- | --- |
@@ -67,7 +98,7 @@ Shared TUI 继续使用 Runtime IPC 是当前 compatibility boundary。只有候
 | 事件恢复 | 明确 snapshot/replay owner、连接内 cursor、跨连接是否持久化、lag/closed/invalidation 和 resync 行为 |
 | 取消与未知结果 | disconnect/shutdown 取消、迟到响应、operation identity、`outcome_unknown` 查询/恢复和禁止盲重试 |
 | Host capability | Desktop local effect 与工作区 capability 边界、provider 注入、Remote unsupported 和 Web/Remote auth 已定稿 |
-| 生命周期与性能 | discovery、startup、idle exit、crash cleanup、延迟、吞吐、内存和 Embedded thread/runtime 成本有预算与测量 |
+| 生命周期与性能 | discovery、startup、idle exit、crash cleanup、延迟、吞吐和内存有预算与测量 |
 | 迁移与回滚 | 同一第一方 consumer 完成 opt-in 双栈 parity；升级/降级和 v17 rollback 可重复验证；删除条件有明确 owner 批准 |
 
 ## 2. 问题与目标
@@ -80,14 +111,14 @@ GUI、Web 和 TUI 若分别围绕 Tauri command、WebSocket route、CLI/Core 直
 - UI 组件与 Tauri、Core singleton 或私有 Runtime IPC 绑定，无法验证跨入口行为等价。
 - “handler 已存在”“DTO 已生成”或“能力被硬编码为 available”被误当成端到端能力已交付。
 
-App Server 的目标是提供一个可版本化、可生成 client、可跨 Embedded/Shared transport 验证的 Rich Client 合同，同时保持业务 owner 平台无关。它统一的是产品后端行为，不统一 GUI/TUI renderer、布局、键位、窗口、终端或 controller-local effect。
+BitFun 的目标是让 direct adapter 与连接型 App Server adapter 共享可验证的产品后端行为合同，同时保持业务 owner 平台无关。App Server 为需要连接边界的 Host 提供可版本化、可生成 client 的 wire；它不再是 Embedded 的统一 transport，也不统一 GUI/TUI renderer、布局、键位、窗口、终端或 controller-local effect。
 
 ## 3. 范围与非目标
 
 本文范围包括：
 
 - Rich Client 的请求、响应、notification、错误、取消和恢复合同。
-- Embedded、Shared 和 WebSocket Host 的 transport 与生命周期边界。
+- Embedded direct adapter、Shared/WebSocket transport 与 Host 生命周期边界。
 - Host 能力、transport limit、身份和执行域的协商。
 - Desktop/Tauri、Web 和 TUI 的接入规则。
 - App Server crate、Runtime owner 和产品装配之间的依赖方向。
@@ -99,17 +130,18 @@ App Server 的目标是提供一个可版本化、可生成 client、可跨 Embe
 - 强制 Headless CLI/CI、ACP、Peer Host 或公开 Agent SDK 使用 App Server。
 - 统一 GUI 与 TUI 的状态机、renderer、布局、主题键或键位模型。
 - 把 WebSocket transport 宣称为已具备多用户或公网安全性的公开 API。
-- 不允许临时兼容路径在没有明确决策、维护责任、版本规则和退出条件的情况下意外变成永久协议。若最终选择候选 B/C，应把保留的 Shared wire 明确定义为正式的部署专用协议，而不是继续称为临时兼容路径。
+- 不把缺少维护责任、版本规则和退出条件的临时兼容路径默认为永久协议；若保留 Shared wire，应将其明确定义为正式的部署专用协议。
 
 ## 4. 术语
 
 | 名词 | 含义 | 不等于 |
 | --- | --- | --- |
-| App Server | 将版本化 Rich Client wire 映射到 Runtime API、Service 和 Product Domain owner 的协议适配层 | 业务 owner、通用 RPC 总线、必然独立的进程 |
+| App Server | 将版本化 Rich Client wire 映射到 Runtime API、Service 和 Product Domain owner 的协议适配层；只用于需要该边界的 Host | 业务 owner、通用 RPC 总线、Embedded 的必经路径 |
 | App Server Client | 只依赖 wire contract、由 Host 提供 transport 的类型化客户端 | Runtime SDK、Server 构造器、UI 状态 owner |
 | Rich Client | 需要持续会话、交互事件和产品管理面的第一方 GUI/Web/TUI | Headless automation、ACP、公开 SDK |
-| Host | 组装 App Server、选择 transport、注入能力并管理生命周期的产品入口 | 新业务层、普通用户必须管理的 Server 产品 |
-| Embedded App Server | 与 Rich Client Host 位于同一 OS 进程的私有 App Server 实例 | Runtime 直连、网络 Server、共享后台进程 |
+| Host | 组装 direct Runtime adapter 或 App Server、选择 transport、注入能力并管理生命周期的产品入口 | 新业务层、普通用户必须管理的 Server 产品 |
+| Embedded direct Runtime | 与 Rich Client Host 同进程、由 `AgentRuntime` typed API 和 owner/provider facade 提供用例的部署方式 | 第二套 Runtime、App Server wire、跨进程后台服务 |
+| Embedded App Server | 迁移前 TUI 使用的同进程私有 App Server 实例和 in-memory transport | Embedded 的目标默认路径、网络 Server、共享后台进程；Phase 5 完成后删除 |
 | Shared App Server | 由独立本机 Host 承载、允许多个已认证第一方 client 使用的 App Server 实例 | 公网 API、Agent SDK Host、每个 client 一个 Runtime |
 | Runtime owner | 持有 Session、Turn、Permission、Tool/MCP、Hook、事件和持久化事实的既有模块 | App Server handler 或 UI read model |
 | Host capability | 当前 Host 确实组装并允许调用的产品能力 | schema 中存在的方法全集 |
@@ -128,16 +160,25 @@ flowchart LR
   GUI --> Host["Host adapter"]
   Web --> Host
   TUI --> Host
-  Host --> Client["App Server Client"]
+  Host --> Route{"Deployment route"}
+  Route -->|"Embedded direct · approved target"| Direct["Direct Runtime adapter"]
+  Route -->|"Web / candidate Shared · Phase 6"| Client["App Server Client"]
   Client --> Transport["Host-selected transport"]
   Transport --> Server["App Server"]
-  Server --> API["Runtime API / owner ports"]
+  Direct --> API["Runtime API / owner ports"]
+  Server --> API
   API --> Owners["Runtime · Services · Product Domains"]
 ```
 
-依赖和调用方向始终从入口流向 owner。Host 负责 transport 认证、连接作用域、capability/allowlist 和平台能力；App Server handler
-负责 method 合同校验、handler 注册、DTO 转换和 Runtime/domain error 到 wire error 的映射。业务一致性、权限上限、持久化和权威状态
-仍由对应 owner 提交。
+依赖和调用方向始终从入口流向 owner。Embedded Host 负责 direct adapter 的 context
+构造、能力选择和生命周期；需要连接边界的 Host 负责 transport 认证、连接作用域、
+capability/allowlist 和平台能力。App Server handler 负责 method 合同校验、handler
+注册、DTO 转换和 Runtime/domain error 到 wire error 的映射。业务一致性、权限上限、
+持久化和权威状态仍由对应 owner 提交。
+
+图中的 Web 分支是当前 loopback WebSocket App Server 路径；Shared 分支仅表示 Phase 6
+candidate，不是当前或已批准的必经链路。当前 Shared TUI 仍只使用 private Runtime IPC v17，
+Web 也不经过 TUI backend composition。
 
 ### 5.1 四层合同
 
@@ -148,37 +189,51 @@ flowchart LR
 | Host 合同 | transport、可用能力、限制、身份、作用域、生命周期和 controller-local provider | 复制业务规则或权威状态 |
 | Owner 合同 | Runtime/Service/Product Domain 的业务事实、校验和提交 | JSON-RPC、Tauri、WebSocket、Ratatui |
 
-行为合同是 Embedded 与 Shared 等价的核心。仅复用 JSON 字段但在断连、超时、事件落后或权限上表现不同，不算统一 App Server 接口。
+行为合同是 Embedded direct-runtime 与 Shared wire 等价的核心；迁移前的 Embedded App Server
+仅作为 direct-runtime 切换前的行为基线，不构成迁移后的第三条运行路径。其中，Phase 5 将引入的
+`TuiRuntimePort` 是 Shared IPC operation 集合在 TUI 侧的窄语义边界；管理 service/provider
+不是 Shared Runtime wire 的组成部分。行为合同不要求三者共享 JSON；只要 Runtime port
+在断连、超时、事件落后、权限、取消和 unknown outcome 上保持明确且可验证的语义，
+即可共享同一 Runtime 用例合同。管理面按各自 service/provider 的可用性单独验证。
 
-## 6. Embedded deployment
+## 6. Phase 5 Embedded interactive TUI target
 
-Embedded Rich Client 的标准路径是：
+本节只定义交互式 TUI 的 Phase 5 目标路径。它不描述 Desktop 或 Web 的迁移完成状态；
+Desktop direct Runtime 是独立的已批准迁移步骤，尚未实施。
 
 ```text
-Rich Client
+Embedded interactive TUI
   -> Host adapter
-  -> AppServerClient
-  -> private in-memory transport
-  -> private App Server instance
+  -> TuiBackend composition
+  -> TuiRuntimePort -> DirectRuntimeTuiRuntime -> AgentRuntime typed API
+  -> owner-owned service/provider interfaces (management only)
   -> Runtime API / owners
 ```
 
 Embedded Host 必须：
 
-1. 组装 Runtime 和 App Server，并将同一 owner 的端口注入 server。
-2. 创建方向固定的私有 in-memory transport pair。
-3. 通过正式 App Server Client 完成 initialize、请求、事件和 shutdown。
-4. 保证 server task/thread 在 Host 退出时被取消并回收。
-5. 使用与 Shared 相同的 schema、错误和行为测试。
-
-Embedded 可以省略只对跨进程多客户端有意义的机制：endpoint discovery、进程 token、外部实例锁、多客户端 controller lease 和空闲后台退出。省略这些机制不能改变请求结果、事件顺序、取消结果或 capability 语义。
-
-进程内 transport 仍可能执行 JSON-RPC 编解码。该成本是候选 A 必须测量的工程取舍；只有基准、资源预算和真实 consumer 证明可接受后，
-才能把强制经过 App Server 作为批准约束。允许评估 transport buffer、生成代码和批量事件优化，但不能用未经验证的性能假设提前排除候选 B/C。
+1. 从产品组装结果取得唯一的 `AgentRuntime` 和必要的 owner/provider facade。
+2. 通过稳定 Rust Runtime API 构造 typed request，补齐 workspace、execution domain、
+   permission 和 remote facts；不得从 UI 或全局环境猜测这些事实。
+3. 将 `AgentRuntime` 的事件/Permission receiver 映射为 `TuiRuntimePort` 可消费的
+    semantic event，
+    不创建第二个 Core `EventQueue` 订阅或第二份 read model 权威状态。
+4. 将 Runtime/domain error 映射为 Runtime port 或对应 owner service 的 TUI error，保留 `unsupported`、取消、
+   `outcome_unknown` 等可观察语义。
+5. 在 Host 退出时取消并回收由 direct adapter 创建的订阅和任务，并使用与 Shared
+   和 Web 路径相同的行为 fixture。
+
+Embedded 可以省略只对跨进程多客户端有意义的机制：endpoint discovery、进程 token、
+外部实例锁、多客户端 controller lease、frame 编解码和空闲后台退出。省略这些机制
+不能改变请求结果、事件顺序、取消结果、权限边界或 capability 语义。
+
+迁移窗口内可以用现有 Embedded App Server 与 direct adapter 做行为对照，但不保留可选的
+rollback adapter，也不得在 direct adapter 返回 unsupported 后静默回退。完成 direct-runtime
+行为、性能和升级兼容验证后，Phase 5 必须删除旧路径。
 
 ## 7. Shared deployment
 
-Shared deployment 由一个本机 App Server Host 承载一个 Runtime owner，多个第一方 Rich Client 通过受控 Pipe、UDS 或等价私有 transport 连接：
+当前 Shared deployment 由独立 Runtime Host 通过 private Runtime IPC v17 服务交互式 TUI，不运行 App Server。若后续采用 Shared App Server，则目标拓扑为一个本机 App Server Host 承载一个 Runtime owner，多个第一方 Rich Client 通过受控 Pipe、UDS 或等价私有 transport 连接：
 
 ```mermaid
 flowchart LR
@@ -190,7 +245,7 @@ flowchart LR
   R --> D["Workspace and Session storage"]
 ```
 
-Shared Host 在基础 App Server 合同之外必须提供：
+采用 App Server 的 Shared Host 在基础 App Server 合同之外必须提供：
 
 - 安全 endpoint discovery、实例身份和同用户认证材料。
 - initialize-first 握手、协议版本和 client identity 校验。
@@ -206,24 +261,32 @@ Shared Host 在基础 App Server 合同之外必须提供：
 
 ## 8. Desktop GUI 与 Tauri
 
-Desktop 的目标调用路径是：
+Desktop 的调用路径按部署选择：
 
 ```text
 React UI
   -> frontend infrastructure / generated App Server client
   -> Desktop Host transport adapter
-  -> Embedded or Shared App Server
+  -> App Server（Web/Shared 或明确需要连接边界时）
+
+Embedded Desktop 的同进程产品请求可以走：
+
+React UI
+  -> frontend infrastructure
+  -> Desktop direct Runtime adapter
+  -> Runtime API / owner ports
 ```
 
-Tauri 继续拥有窗口、菜单、系统托盘、文件选择器、剪贴板、通知和进程级生命周期。Session、Turn、Workspace、Permission、Config、MCP、Skill、Hook 等产品后端能力必须迁入 App Server。
+Tauri 继续拥有窗口、菜单、系统托盘、文件选择器、剪贴板、通知和进程级生命周期。Session、Turn、Workspace、Permission、Config、MCP、Skill、Hook 等产品后端能力必须迁入既有 Runtime/owner；Embedded 时由 direct adapter 调用，需要连接边界时再由 App Server 做协议适配。
 
 迁移规则：
 
 - UI 组件不得直接调用 Tauri API；调用进入前端 infrastructure/adapter。
-- Tauri command 若只承载产品后端用例，应由 App Server method 替代并逐步删除。
-- 必须由桌面原生 API 完成的 client-local capability 保留 Host-native 实现；需要与工作区或 Runtime 交互时拆成 App Server 数据流和本地 effect 两段。
-- Tauri event bridge 只能投递 App Server typed notification 或桌面专属事件，不能形成第二套 Runtime 事件语义。
-- Desktop Host 可在 Embedded 与 Shared 之间切换，但 UI 和生成 client 不包含 Runtime 直连分支。
+- Tauri command 若只承载产品后端用例，应由稳定 Runtime typed facade 或需要连接边界时的 App Server method 替代并逐步删除。
+- 必须由桌面原生 API 完成的 client-local capability 保留 Host-native 实现；需要与工作区或 Runtime 交互时拆成 direct/App Server 数据流和本地 effect 两段。
+- Tauri event bridge 只能投递 direct Runtime/App Server typed notification 或桌面专属事件，不能形成第二套 Runtime 事件语义。
+- Desktop Host 可在 direct Embedded 与 Shared/App Server 之间切换，但 UI 不包含部署分支；
+  route 选择留在 Host/infrastructure。
 
 ## 9. Web 与远程 Host
 
@@ -263,7 +326,7 @@ WebSocket 是 App Server 的一种 transport，不是另一套业务 API。Web H
 
 ## 11. 事件、恢复与取消
 
-权威 Runtime 事件通过同一 App Server connection 以 typed notification 发送。Host 不得让 client 绕过 App Server 直接订阅 Core `EventQueue`，也不得用有损 frontend projection 替代权威事件流。
+需要连接边界的 client 通过其 App Server connection 接收 typed Runtime notification；Embedded direct adapter 则通过 Runtime typed subscription 订阅同一权威 owner。App Server client 不得绕过连接直接订阅 Core `EventQueue`，direct adapter 也不得持有 Core queue receiver 或创建第二个事件 owner；两条路径都不得用有损 frontend projection 替代权威事件流。
 
 每个事件流至少需要：
 
@@ -307,7 +370,7 @@ App Server 是完整产品控制面，安全决策必须绑定到连接和业务
 | 资源治理 | 连接、请求、frame、队列、并发、速率和任务生命周期有界 |
 | 远程边界 | 凭据、文件、进程和 Runtime 留在目标执行域；禁止本地 fallback |
 
-Embedded 的私有 transport 可以依赖同进程构造身份，但仍必须传递明确的 Host/connection context，不能让 handler 从全局环境猜测调用主体。
+Embedded direct invocation 可以依赖同进程构造身份，但仍必须传递明确的 Host/request context，不能让 adapter 或 owner 从全局环境猜测调用主体。App Server connection 继续使用显式 connection context。
 
 ## 14. Crate 与所有权边界
 
@@ -325,6 +388,13 @@ Embedded 的私有 transport 可以依赖同进程构造身份，但仍必须传
 - server wiring 可以依赖生产 handler 所需的明确 owner feature，但禁止选择 `bitfun-core/product-full`。
 - 新 domain 只能增加真实 handler 所需的最窄 owner feature，并通过边界检查证明依赖方向。
 - protocol DTO 不复制 Runtime 内部对象；只暴露 Rich Client 需要的稳定字段和 read model。
+- `app-server-protocol` 是 TypeScript wire schema 的唯一导出 owner；`app-server/ts`
+  仅保留为兼容转发。owner 对象到 wire read model 的转换留在 server adapter，不能为了
+  生成类型把 Core、Agent Runtime 或 Service 实现依赖下沉到 protocol。
+- `app-server::schema` 只保留对 protocol 类型的兼容 re-export；正式 typed client 由
+  `app-server-client` 单独拥有，server crate 不维护第二套隐藏 client。该 re-export 保证
+  已有平铺类型路径和 wire shape，不承诺保留 server-only 的 inherent/`From` 转换 helper；
+  这些内部调用应迁到 server adapter 或稳定 contract 方法。
 - transport 实现留在 Host/adapter 边界，generic role/transport helper 保持 schema-free。
 - App Server 不持有第二份 Session、Permission、Config 或 capability 权威状态。
 
@@ -332,13 +402,28 @@ Embedded 的私有 transport 可以依赖同进程构造身份，但仍必须传
 
 迁移按行为闭环推进，不按 method 数量推进：
 
-1. **锁定合同基础**：稳定 protocol/client crate、版本、错误、能力、限制和事件 envelope；增加 Embedded contract test。
-2. **完成 Embedded TUI**：所有交互式 TUI 产品请求经 `TuiBackend -> AppServerClient`；移除 Core、Runtime SDK、Service singleton 和 Runtime IPC 的 TUI-facing 依赖。
-3. **迁移 Desktop GUI**：按 Session/Turn/Permission、Workspace、Config/MCP/Extension 等垂直切片迁移；每片完成后删除重复 Tauri DTO/handler。
-4. **补齐 Shared 语义**：把 authentication、instance identity、controller/lease、framing、背压、断连取消、idle exit、event recovery 和 `outcome_unknown` 纳入 App Server Host/transport。
-5. **评审 Shared TUI 迁移**：候选 A 获批且 1.4 节门槛通过后，才用同一 client/schema 替换 Runtime IPC compatibility adapter；旧 wire 仅在 rollback 窗口结束并获得 owner 批准后删除。若选择 B/C，则记录 v17 的长期 owner、版本和删除条件。
-6. **收紧 Web Host**：由 Host 注入 allowlist、作用域和真实 limits；完成安全绑定前保持 loopback 单用户限制。
-7. **删除旁路**：移除 Rich Client 的 Core/Runtime 直连、重复事件投影和无生产消费方的旧 route。
+ 1. **锁定 Runtime 行为合同**：按当前 Shared IPC v17 operation 集合冻结窄
+   `TuiRuntimePort`，稳定 Runtime request/response/event 类型、错误、能力、取消和事件语义；
+   为 direct Embedded 和 Shared 增加同一 Runtime 行为 fixture，迁移前可用旧 App Server 建立行为基线。
+ 2. **拆分 TUI backend composition**：将当前单体 `TuiBackend` 拆为 `TuiRuntimePort` 与按
+   domain 注入的 owner service/provider 接口；不定义总括性的 `TuiManagementPort`。管理 service
+   能直接复用稳定 owner trait 的直接注入；只有需要 TUI DTO、权限/上下文或 capability 裁剪时
+   才增加薄 facade。
+ 3. **迁移 Embedded TUI**：实现 `DirectRuntimeTuiRuntime`，将 Runtime 调用从
+   `AppServerTuiBackend` 移出；再移除 in-memory transport、Embedded `BitfunAppServer`、
+   server thread 和 TUI-facing App Server client 依赖。管理面使用 owner-owned service/provider，
+   不把具体 `AppManagementService` 原样搬入 CLI/TUI。
+4. **迁移 Desktop GUI**：Embedded 时使用 direct Runtime adapter；Web/Shared 或需要连接治理
+   的场景保留 App Server。Tauri 继续承载平台能力与生命周期。
+5. **补齐 Shared 语义**：把 authentication、instance identity、controller/lease、framing、
+   背压、断连取消、idle exit、event recovery 和 `outcome_unknown` 纳入 App Server Host/transport。
+6. **评审 Shared TUI 迁移**：Shared App Server 只有通过 1.4 节门槛后才可替换 Runtime IPC
+   compatibility adapter；v17 是否删除由独立评审和验证证据决定。若选择 B/C，
+   记录 v17 的长期 owner、版本和删除条件。
+7. **收紧 Web Host**：由 Host 注入 allowlist、作用域和真实 limits；完成安全绑定前保持 loopback
+   单用户限制。
+8. **删除旁路**：移除 Rich Client 的重复 Runtime 事件投影、旧 Embedded App Server route 和
+   无生产消费方的兼容代码。
 
 迁移期间不得在 App Server 返回 unsupported 后静默调用旧 Tauri/Core/IPC 路径。需要暂存旧路径时，必须由 Host 在启动时明确选择完整 adapter，且 UI 只看到一个 `TuiBackend` 或 frontend infrastructure 接口。
 
@@ -347,7 +432,11 @@ Embedded 的私有 transport 可以依赖同进程构造身份，但仍必须传
 ### 16.1 必需验证
 
 - protocol serialization、版本上下界、未知字段和类型化错误合同测试。
-- 同一用例在 Embedded in-memory 与 Shared process transport 上的行为等价测试。
+- 同一用例在 Embedded direct-runtime、Shared process transport 和 WebSocket App Server（适用时）
+  的行为等价测试；迁移前旧 Embedded App Server 仅用于建立基线，不作为持续测试路径。
+- `TuiRuntimePort` coverage：当前 Shared IPC v17 的每个 Runtime operation 都有对应的
+  port 行为测试；管理 service/provider 则单独验证 capability、权限、unsupported 和 Remote
+  fail-closed，不以 Runtime port parity 代替管理面验证。
 - Host capability/provider/allowlist 组合测试，以及真实 transport limit 测试。
 - request identity、取消、断连、超时和 `outcome_unknown` 测试。
 - 事件顺序、lag、invalidated、cursor/snapshot resync 和慢 client 测试。
@@ -356,26 +445,36 @@ Embedded 的私有 transport 可以依赖同进程构造身份，但仍必须传
 - Cargo 依赖闭包和 `product-full` 禁止规则。
 - TypeScript/Rust client 生成结果与 schema 一致性检查。
 
-### 16.2 完成定义
-
-若选择候选 A，只有同时满足以下条件，App Server Rich Client 架构才算完成：
-
-1. Desktop GUI、Web UI 和交互式 TUI 的产品后端请求与订阅均经过 App Server。
-2. Embedded 与 Shared 使用同一 client、method、DTO、错误和事件恢复合同，UI 不包含部署分支。
-3. Shared transport 达到现有 Runtime IPC 的鉴权、lease、取消、背压、限制、失效和生命周期等价。
-4. capability 和 limits 来自 Host 的真实装配与 transport，不再由通用 handler 无条件硬编码。
-5. Rich Client 不直接依赖 Core singleton、Runtime SDK、Tauri 业务 command 或私有 Runtime IPC。
-6. App Server handler 不持有业务权威状态，不复制 owner 校验和策略。
-7. Remote workspace 和多用户连接具有明确身份、作用域、授权和 fail-closed 行为。
-8. 重复 Tauri/Web/IPC DTO、旧 handler 和事件旁路已删除，或有明确的兼容期限与删除证据。
-9. 上述合同、行为、安全、依赖和跨入口测试全部通过。
-
-## 17. Proposed constraints and open decisions
-
-### 17.1 Proposed target constraints
-
-- 若候选 A 获批，Rich Client Embedded 必须经过私有 in-process App Server。
-- Embedded 和 Shared 只有部署与连接治理差异，不产生第二套产品行为。
+### 16.2 TUI/App Server 解耦完成定义
+
+只有交互式 TUI 同时满足以下条件，TUI/App Server 解耦才算完成；这一定义不涵盖
+Desktop 的独立 direct Runtime 迁移：
+
+1. Embedded TUI 的产品请求和订阅经过 `TuiAgentClient` 的 backend composition；Runtime
+   行为经过 `TuiRuntimePort -> DirectRuntimeTuiRuntime`，管理能力经过对应 owner service/provider，
+   TUI view/reducer 不执行 backend I/O。
+2. direct adapter 只调用既有 Runtime API、owner-owned service/provider 和必要的薄 facade，
+   不复制 Session、Permission、Config、capability 或事件权威状态，也不定义 `TuiManagementPort`。
+3. Embedded direct-runtime 与 Shared v17 的行为合同覆盖请求结果、事件顺序、
+   取消、权限、unsupported、断连和 unknown outcome。
+4. capability、作用域和 remote facts 来自真实 Host/Runtime 组装；Remote workspace 不存在
+   controller-local fallback。
+5. Embedded 不创建 App Server client/server、in-memory transport 或额外 Runtime 进程；
+   direct adapter 的任务和订阅在 Host 退出时可回收。
+6. App Server 仍可被 Web/Shared Host 使用，且 handler 不持有业务权威状态或复制 owner 策略。
+7. 旧 Embedded App Server 路径已删除且不再作为 rollback adapter；70 方法单体 `TuiBackend`
+   不再作为稳定接口边界。
+8. Shared transport 若要替换 v17，仍需单独满足鉴权、lease、取消、背压、限制、失效和生命周期
+   等价门槛。
+9. 上述合同、行为、安全、依赖、升级兼容和跨入口测试全部通过。
+
+## 17. Constraints and open decisions
+
+### 17.1 Accepted target constraints
+
+- Embedded 默认直接调用同进程 Runtime typed API；只有需要连接/进程边界的 Rich Client 才经过 App Server。
+- Embedded direct-runtime 和 Shared 只有适配与连接治理差异，不产生第二套产品行为；旧
+  Embedded App Server 仅是迁移前基线。
 - App Server 只映射 owner，不成为 Session、Turn、Permission、Tool/MCP、Config 或事件 owner。
 - Host capability 必须由真实装配、授权和 transport 共同决定。
 - 事件丢失、断连和未知副作用结果必须显式可见，不能用轮询或盲重试掩盖。
@@ -391,4 +490,7 @@ Embedded 的私有 transport 可以依赖同进程构造身份，但仍必须传
 - Desktop client-local capability 的请求方向：App Server 反向 request、Host provider port，或显式两段式工作流。
 - Web/Remote 的认证凭据来源、刷新、撤销和多租户资源配额。
 
-这些待决项会影响候选选择，不能被实现默认值或迁移进度替代。评审结论必须记录所选候选、拒绝其他候选的理由、门槛 owner、验证证据和回滚/删除条件；在此之前，当前 Embedded App Server 与 Shared v17 路径都保持有效。
+这些待决项会影响 Shared transport 的选择，不能被实现默认值或迁移进度替代。Shared 评审结论必须记录
+所选 transport、拒绝其他方案的理由、门槛 owner、验证证据和回滚/删除条件。Embedded direct-runtime
+迁移完成后，旧 Embedded App Server 必须删除且不保留回滚路径；WebSocket App Server 与 Shared v17
+按各自部署合同继续有效。
diff --git a/docs/architecture/cli-product-line-design.md b/docs/architecture/cli-product-line-design.md
index a4492d158a..2c793f3086 100644
--- a/docs/architecture/cli-product-line-design.md
+++ b/docs/architecture/cli-product-line-design.md
@@ -213,7 +213,7 @@ CLI 只消费 typed summary 与 typed action：
 | 变更范围 | 最小验证 |
 | --- | --- |
 | TUI state/input/render | focused reducer/input/render test + `cargo test -p bitfun-cli` |
-| Agent Runtime SDK/port | `cargo test -p bitfun-agent-runtime` + owner focused test |
+| Agent Runtime SDK/port | `cargo test -p bitfun-agent-runtime --no-default-features --features agent-runtime --lib` + owner focused test |
 | Shared IPC | protocol round-trip、controller/idle、timeout/outcome-unknown、disconnect cancel |
 | Core turn/tool | 权限 allow/ask/deny、取消、事件、上下文、持久化恢复 |
 | `exec` output | stdout/stderr、单一最终状态、session conflict、Ctrl+C、Patch |
diff --git a/docs/architecture/extensions/plugin-runtime-design.md b/docs/architecture/extensions/plugin-runtime-design.md
index bcaada2a78..968f4d8b67 100644
--- a/docs/architecture/extensions/plugin-runtime-design.md
+++ b/docs/architecture/extensions/plugin-runtime-design.md
@@ -281,11 +281,11 @@ plugin、Hook、完整 Client 或 TUI 插件入口。与其独立的 standalone
 
 当前 Rust 边界调整至少运行：
 
-- `cargo test -p bitfun-runtime-ports --test plugin_runtime_contracts`
-- `cargo test -p bitfun-runtime-ports --test plugin_runtime_diagnostics_contracts`
+- `cargo test --locked -p bitfun-runtime-ports --no-default-features --features plugin-runtime --test plugin_runtime_contracts plugin_runtime_contracts`
+- `cargo test --locked -p bitfun-runtime-ports --no-default-features --features plugin-runtime --test plugin_runtime_contracts plugin_runtime_diagnostics_contracts`
 - `cargo test -p bitfun-plugin-runtime-client`
 - `cargo test -p bitfun-opencode-adapter --test opencode_source_adapter`
-- `cargo test -p bitfun-core plugin_runtime::tests --lib`
+- `cargo test -p bitfun-core --no-default-features --features plugin-runtime --lib plugin_runtime::tests`
 - `node scripts/check-core-boundaries.mjs`
 
 目标 Plugin Host 还必须使用固定版本真实 fixture 验证：
diff --git a/docs/architecture/i18n.md b/docs/architecture/i18n.md
index 4d43ae96b4..3783df3b8a 100644
--- a/docs/architecture/i18n.md
+++ b/docs/architecture/i18n.md
@@ -52,6 +52,14 @@ Do not edit generated files manually.
 Shared contract does not mean shared bundle. Smaller product shapes must not pay
 for Web UI resource size.
 
+The backend follows the same split at compile time. `LocaleId`, locale aliases,
+fallback facts, metadata, and model-facing language copy are feature-free Core
+contracts. Fluent parsing, backend bundles, `I18nService`, and its global mutable
+state are enabled only by the Core `i18n-runtime` owner feature. A host that
+initializes or updates the backend service must select that feature explicitly;
+`product-full` and App Server do so, while contract-only Core consumers do not
+compile Fluent.
+
 ## Lookup And Override Order
 
 Resource intent has three layers:
diff --git a/docs/architecture/peer-device-mode.md b/docs/architecture/peer-device-mode.md
index f2dfb2b35d..cfbbdbed72 100644
--- a/docs/architecture/peer-device-mode.md
+++ b/docs/architecture/peer-device-mode.md
@@ -12,6 +12,72 @@ A's workspace list, sessions, assistants, chat, and tools behave like using
 BitFun on B's machine. The authority is **B's live local BitFun state** via
 HostInvoke / DeviceEvent fan-out — not a merged cloud session history.
 
+## Attachment vs rendered surface
+
+Two concepts, deliberately independent:
+
+| | Attachment | Rendered surface |
+|---|---|---|
+| What it is | A live control link to a peer | The one device this window draws |
+| How many | Any number, concurrently | Exactly one |
+| Ends when | Explicit disconnect, peer offline, logout | Replaced by the next switch |
+| Effect on the peer's agent | Keeps it running and fanning out | None |
+
+This split is what makes several devices usable at once: dispatch a turn on B,
+switch the UI back to A, dispatch another turn on A, and both keep running.
+The frontend entry points are `switchToDevice` / `switchToLocal` /
+`disconnectDevice` on `PeerDeviceContext`; the sidebar `DeviceSurfaceSwitcher`
+lists this machine plus every online peer.
+
+Two rules follow, and both are load-bearing:
+
+- **A surface switch never mutates the device being left.** Everything in
+  `resetProductSurface()` is frontend-only. Sending `terminal_shutdown_all` or
+  `lsp_close_workspace` during a switch lands on the *previous* transport and
+  kills work an agent there still depends on.
+- **Product events are routed by their source device.** The controller re-emits
+  peer DeviceEvents under their original event name, so with peers attached in
+  the background one bus carries several agent streams. The desktop controller
+  tags each re-emitted payload with `__bitfunSourceDeviceId`
+  (`remote_connect_api::PEER_EVENT_SOURCE_KEY`; non-object payloads are wrapped
+  under `__bitfunSourcePayload`), and `deviceSurfaceRouting.ts` — applied inside
+  `TauriTransportAdapter.listen` — delivers a surface-scoped event only when its
+  producing device is the rendered one. Untagged events are local by definition.
+  Control-plane events (`account://…`, window chrome, updater) are never scoped
+  and always pass.
+
+### Surface identity and activation
+
+The rendered device is a first-class `DeviceSurfaceId` (`local` or a peer
+device id), not an implicit property of one mutable global transport. Cache,
+request, capability, workspace, session-state-machine, processing-status,
+pending-message, and composer-draft identity includes that surface. FlowChat
+and workspace state are stored in per-surface containers: switching selects a
+container immediately, then reconciles it with its host; it does not erase the
+container belonging to the device being left.
+
+Every surface activation creates a monotonic epoch and `AbortSignal`.
+Product invokes capture that epoch, including through `ApiClient`; a response
+or retry that outlives it raises `SurfaceChangedError` and is abandoned as
+control flow. Controller-plane commands are exempt because their authority
+remains the controller regardless of the rendered surface. Transport/event
+routing and container selection commit synchronously in `activateSurface` so
+no observer can see B's state while requests still target A.
+
+`PeerDeviceSurfaceController` serializes activation outside React. Rapid
+requests coalesce to the last target, a committed-but-superseded hydrate is
+invalidated before the next target proceeds, and a real activation failure
+rolls back to the previously rendered reachable surface. Separately,
+`PeerConnectionManager` owns each attachment's
+`connecting`/`ready`/`degraded`/`lost` lifecycle, keepalive and bounded backoff;
+React only subscribes to snapshots. Attachment disposal is the only operation
+that discards a peer's cached surface state.
+
+Because the local surface can now miss its own events while another device is
+rendered, snapshot reconciliation is no longer Peer-only: after this window's
+first surface switch, `isSurfaceReconcileEnabled()` keeps the repair loop
+running for whichever surface is rendered, local included.
+
 ## Cloud account sync vs Peer Remote
 
 | Concern | Account cloud sync | Peer Device Mode |
@@ -38,8 +104,12 @@ FS) and must not be mixed with Peer Device Mode.
 ## Boundaries
 
 - Not SSH `WorkspaceKind.Remote` (local session mirror + remote FS).
-- Enter via Account Login → Online Devices → click peer.
-- Exit via sidebar Peer Remote status row `Disconnect` (device name + disconnect).
+- Switch via the sidebar device switcher, or Account Login → Online Devices →
+  click a device. Both list this machine, so returning to it is a switch like
+  any other.
+- Selecting this machine only changes what is rendered; peers stay attached and
+  keep working. `Disconnect` in the switcher is the separate, explicit action
+  that ends a peer's control link and cancels the work it runs for us.
 - Local-only commands (window chrome, updater, account login/logout, peer
   control plane) never execute on the peer on behalf of a controller.
 - Unsupported or denied commands fail loudly; they must not fall back to the
@@ -65,6 +135,9 @@ FS) and must not be mixed with Peer Device Mode.
   only when the initial `peer_mode_ping` advertises
   `idempotent_dialog_submit`, so mixed-version peers remain single-shot.
   Other mutations remain single-shot because a timed-out outcome is unknown.
+  Identity-based Session rollback is sent only when `peer_mode_ping` advertises
+  `targeted_session_rollback`; older peers fail explicitly and never fall back
+  to controller-local files, history, or the removed numeric rollback command.
   The desktop `account_device_rpc` command enforces the requested deadline
   around the native HTTP future; the controller's Promise deadline is not
   merely a UI timer. Failed session-list loads leave the spinner and expose an
@@ -168,6 +241,9 @@ and may represent a different operating system.
   `src/apps/cli/src/account_sync.rs`.
 - Frontend mode + transport: `src/web-ui/src/infrastructure/peer-device/`,
   `adapters/peer-device-adapter.ts`
+- Surface routing / switcher: `deviceSurfaceRouting.ts`,
+  `deviceSurfaceReconcile.ts`, `deviceActivity.ts`,
+  `DeviceSurfaceSwitcher.tsx`, `useAccountDeviceRoster.ts`
 - Peer directory picker: `pickWorkspaceDirectory.ts`, `PeerDirectoryBrowser.tsx`,
   `PeerDirectoryPickerHost.tsx`
 
diff --git a/docs/architecture/product-architecture.md b/docs/architecture/product-architecture.md
index 9c171546ba..769e414cbb 100644
--- a/docs/architecture/product-architecture.md
+++ b/docs/architecture/product-architecture.md
@@ -20,10 +20,10 @@
 Headless CLI 与各产品入口的统一心智见
 [`agent-sdk-product-architecture.md`](agent-sdk-product-architecture.md)；多个 GUI/TUI/Remote/CLI/SDK 实例共存时的 Agent Runtime 部署、
 状态共享、隔离、容量与 Plugin Host 关系见
-[`agent-runtime-deployment-design.md`](agent-runtime-deployment-design.md)；Desktop GUI、Web UI 和交互式 TUI 的统一产品后端协议、
-Embedded/Shared App Server 边界及迁移约束见
-[`app-server-architecture.md`](app-server-architecture.md)。该专题当前是待评审的目标提案；在决策门槛通过前，当前调用路径和稳定
-owner 边界仍以本文及已接线代码为准。其他已批准的详细设计与本文件冲突时，以本文件为准。
+[`agent-runtime-deployment-design.md`](agent-runtime-deployment-design.md)；Desktop GUI、Web UI 和交互式 TUI 的产品后端边界、
+Embedded direct-runtime、Shared App Server 及迁移约束见
+[`app-server-architecture.md`](app-server-architecture.md)。Embedded direct-runtime 已确定为下一步实现方向；Shared App Server
+仍是待评审提案。在迁移或决策门槛通过前，当前调用路径和稳定 owner 边界仍以本文及已接线代码为准。其他已批准的详细设计与本文件冲突时，以本文件为准。
 
 Cargo feature、第三方依赖 owner、测试目标和本地/CI 验证分工见
 [`rust-build-dependency-boundaries.md`](rust-build-dependency-boundaries.md)。该文档补充本架构的构建视图，不改变本文定义的运行时 owner 和分层依赖方向。
@@ -308,9 +308,9 @@ flowchart LR
 
 ### 2.4 Physical View · Level 0
 
-Physical View 展示当前可执行单元到设备、主机和存储的映射。Desktop、CLI、ACP 和 SDK Host 使用 Embedded Runtime；
-Embedded 交互式 TUI 已在同一 CLI 进程内通过私有 App Server 使用 Runtime，交互式 TUI 也可以显式连接当前 Shared Runtime IPC。
-Desktop GUI 的 App Server 迁移尚未完成。当前 loopback Web Server 已承载 Embedded Runtime 和 WebSocket App Server；Relay Server
+Physical View 展示当前生产环境中可执行单元到设备、主机和存储的映射。Desktop、CLI、ACP 和 SDK Host 使用 Embedded Runtime；
+Embedded 交互式 TUI 当前仍在同一 CLI 进程内通过私有 App Server 使用 Runtime；交互式 TUI 也可以显式连接当前 Shared Runtime IPC。
+Desktop GUI 当前仍使用 Tauri adapter；独立 direct Runtime 迁移尚未实施。当前 loopback Web Server 已承载 Embedded Runtime 和 WebSocket App Server；Relay Server
 不承载 Agent Runtime。
 
 ```mermaid
@@ -374,8 +374,8 @@ flowchart LR
 
 | Deployment unit | Main contents |
 |---|---|
-| Desktop App | Web UI、Tauri Host、embedded Agent Runtime；Rich Client App Server 迁移尚未完成 |
-| CLI App | 交互式 TUI 通过 private in-process App Server 使用 Embedded Runtime；Headless、Peer 保留独立 adapter；可显式使用 Shared TUI |
+| Desktop App | Web UI、Tauri Host、embedded Agent Runtime；当前 Desktop 产品请求使用现有 Tauri adapter |
+| CLI App | 交互式 TUI 当前通过 in-process App Server 使用 Embedded Runtime；Headless、Peer 保留独立 adapter；可显式使用 Shared TUI |
 | Shared Runtime | 私有本机 IPC；当前只有交互式 TUI consumer；是否迁入 Shared App Server transport 仍待评审与等价证据 |
 | ACP | Embedded Agent Runtime、ACP 协议生命周期 |
 | SDK Host | 私有跨进程 adapter；公开 SDK 产品尚未交付 |
@@ -423,11 +423,19 @@ flowchart TB
 ## 3. 接口边界
 
 BitFun 只保留四个稳定业务接口边界；工具、事件和权限作为归属子接口被复用，不在插件层重复定义。App Server
-是 Agent Runtime API 和其他 owner 接口面向当前 Web/Embedded TUI 以及候选 Rich Client 目标的版本化 wire adapter，不新增第五个
-业务 owner 或能力分类。是否扩大到全部 Rich Client 由 4.2 节所述评审决定。本文使用
+是 Agent Runtime API 和其他 owner 接口面向当前 Web/Embedded TUI，以及未来确实需要连接边界的 Rich Client 的版本化 wire adapter，不新增第五个
+业务 owner 或能力分类。Embedded TUI 的目标改为 direct Runtime adapter；Shared 是否使用 App Server 由 4.3 节所述评审决定。本文使用
 “接口”描述可被调用或依赖的能力面；只有描述跨进程消息封装、结构化 schema、序列化对象或强兼容约束时才使用
 “契约”；只读状态视图表示从权威状态派生出的查询结果。
 
+Phase 5 将为 Embedded/Shared TUI 冻结窄的 `TuiRuntimePort`，其范围按 Shared IPC v17
+实际承载的 Session、Turn、Permission/UserInput、Workspace、lineage、usage/settlement、
+model/mode 更新、agent mode catalog 和事件订阅确定。Model/Skill/Subagent/MCP、Account、
+Settings Sync、Worktree、External Source 和 Hook 等管理面不组成一个 `TuiManagementPort`，
+也不因为存在 TUI 用例就进入 Shared Runtime wire；它们由 TUI backend composition 按 domain
+直接依赖 owner-owned 的稳定 service/provider trait。只有需要 TUI DTO、权限/上下文适配、
+内部类型隔离或 capability 裁剪时，才增加薄 facade。
+
 | 接口边界 | 谁使用 | 提供 | 不包含 |
 |---|---|---|---|
 | Agent Runtime API | App Server、Headless CLI、ACP、Server、Remote、SDK 等 adapter | Query、Session、Tool/MCP、Permission、Hook、Event、Usage | UI、Rich Client wire、协议和具体服务实现 |
@@ -476,21 +484,29 @@ handler，不构成生产消费完整流程。
 client 或未来 CLI/HarmonyOS 计划，不能证明同名 Rust transport adapter 已接入；未接入实现应删除，待端到端
 调用链确定后再按宿主边界实现。
 
+多个已接入载体重复使用的协议无关机械能力是例外：有界 JSON 编码与消息大小校验、消息级背压和 JSON-RPC request
+correlation 可以由 `adapters/transport` 统一持有。仅 private Runtime IPC 使用的 length-prefix framing 仍留在该协议 owner，
+待第二个当前消费者共享相同语义后再评估抽取。该基础层只接受 bytes/message 与调用方提供的
+限额，不得知道 App Server、private Runtime IPC、SDK Host 的 method/DTO，也不得决定认证、controller/lease、重连、
+自动重试或业务生命周期。stdio、Named Pipe/UDS、WebSocket 仍由各 Host 选择具体 framing 和安全策略；复用机械层
+不能被解释成这些入口共享同一 wire 或同一 Runtime 进程。
+
 ### 3.2 宿主通信契约与 Tauri 薄适配
 
 前后端契约按能力语义归属，不按 Tauri command 名称归属。稳定的请求、响应、状态事实和类型化错误放在对应
 `contracts/*`、Agent Runtime API 或能力归属模块。当前 Desktop GUI 仍使用 Tauri adapter，Web UI 使用 loopback WebSocket
-App Server，Embedded TUI 使用 in-process App Server，Shared TUI 通过 `TuiBackend` 映射 private Runtime IPC v17。待评审目标是让
-Desktop GUI、Web UI 和交互式 TUI 复用同一 Rich Client App Server 行为与 wire contract；Tauri 和各 Rich Client Host 负责
-transport、平台能力及生命周期。ACP、Headless CLI、Peer Host 与公开 SDK 继续由各自 adapter 映射到稳定 owner 接口，不因该目标
-复用 App Server wire。该规则降低框架耦合，但不要求把 controller-local Desktop DTO 搬进共享 crate。
+App Server，Embedded TUI 当前使用 in-process App Server，Shared TUI 通过 `TuiBackend` 映射 private Runtime IPC v17。目标是让
+Embedded GUI/TUI 通过 Host-owned direct adapter 调用 Runtime typed API，需要连接边界的 Web/Shared Rich Client 使用 App Server；
+Tauri 和各 Rich Client Host 负责 adapter、transport、平台能力及生命周期。ACP、Headless CLI、Peer Host 与公开 SDK 继续由各自
+adapter 映射到稳定 owner 接口，不因该目标复用 App Server wire。该规则降低框架耦合，但不要求把 controller-local Desktop DTO
+搬进共享 crate。
 
 | 层 | 允许 | 禁止 |
 |---|---|---|
 | 能力归属模块 / Agent Runtime API | 字段明确的请求和响应、状态事实、权限/取消规则、与框架无关的用例方法 | `tauri::State`、`AppHandle`、窗口/菜单对象、command 宏、HTTP/WebSocket/ACP/SDK Host 消息结构 |
-| Desktop Tauri / proposed App Server Host adapter | 当前组装 Tauri adapter；目标组装 transport、注入真实 capability 与平台 provider、管理窗口和桌面生命周期、投递 App Server typed notification 或桌面专属事件 | 复制业务校验、持有第二份权威状态、在目标迁移完成后为同一能力保留第二条 Runtime 旁路、把 Tauri 类型传入下层 |
+| Desktop Tauri / product Host adapter | 当前组装 Tauri adapter；目标按部署组装 direct Runtime adapter 或 App Server transport、注入真实 capability 与平台 provider、管理窗口和桌面生命周期、投递 typed Runtime/App Server notification 或桌面专属事件 | 复制业务校验、持有第二份权威状态、在目标迁移完成后为同一能力保留第二条 Runtime 旁路、把 Tauri 类型传入下层 |
 | Server / Remote adapter | 路由鉴权、协议消息、连接生命周期、流量控制与取消转换 | 为同一能力另建业务含义不同的 DTO 或 handler |
-| GUI / Web / TUI frontend | 当前依赖各自 infrastructure 或 `TuiBackend`；目标依赖生成的 App Server client、稳定读模型和 Host-local capability adapter；各自保留渲染状态 | 在 UI component/view 中直接依赖 Runtime/Core/Service、公开 Python/TypeScript SDK、Tauri 业务 command 或私有 Shared IPC |
+| GUI / Web / TUI frontend | 当前依赖各自 infrastructure 或 `TuiBackend`；目标依赖 frontend/app infrastructure，由其组合 `TuiRuntimePort`、owner service/provider adapter 和需要时的 App Server client；各自保留渲染状态 | 在 UI component/view 中直接依赖 Runtime/Core/Service、公开 Python/TypeScript SDK、Tauri 业务 command 或私有 Shared IPC |
 
 本文其他章节和历史设计中出现的“Runtime SDK”，如果指 `agent-runtime::sdk`，统一称为
 **Rust Runtime SDK（当前 preview）**；它是共享 **Agent Runtime API** 的当前 Rust 入口。只有
@@ -538,8 +554,9 @@ Desktop command 使用的序列化对象继续留在 `src/apps/desktop`；即使
 
 ## 4. 运行协作细节
 
-本节在 Process View Level 0 之下展开产品入口、插件调用和平台能力。Current 图只描述当前已接线请求路径；Proposed target 图
-描述待评审方向。两者都只描述组件协作，不构成新的 4+1 视图。
+本节在 Process View Level 0 之下展开产品入口、插件调用和平台能力。Current 图只描述当前已接线请求路径；Approved Embedded target
+和 Optional Shared proposal 分别描述已批准但未交付的 Embedded direct-runtime，以及仍待评审的 Shared App Server。三者都只描述组件协作，
+不构成新的 4+1 视图。
 
 ### 4.1 Current product entry paths
 
@@ -548,7 +565,7 @@ flowchart LR
   Desktop["Desktop GUI"] --> Tauri["Desktop / Tauri adapter"]
   Web["Web UI"] --> WebHost["loopback WebSocket App Server"]
   TUI["Interactive TUI"] --> Backend["TuiBackend"]
-  Backend -->|"Embedded"| EmbeddedAS["in-process App Server"]
+  Backend -->|"Embedded current"| EmbeddedAS["in-process App Server"]
   Backend -->|"--shared"| SharedIPC["private Runtime IPC v17"]
   Other["Headless CLI · ACP · Server · Remote"] --> Adapter["独立入口适配器"]
   SDK["Rust Runtime SDK / SDK Host preview"] --> SDKAdapter["独立 SDK adapter"]
@@ -561,43 +578,52 @@ flowchart LR
   API --> Runtime["共享 Runtime"]
 ```
 
-当前 Embedded TUI 核心路径经过 App Server，Shared TUI 则由 `TuiBackend` compatibility adapter 映射到 private Runtime IPC v17。
-Desktop GUI 尚未完成 App Server 迁移；当前 loopback Web Host 已通过 WebSocket 承载 App Server。Headless CLI/CI、ACP、Peer Host
-和 SDK Host 保留独立 adapter。所有路径最终消费同一 Runtime API 或 owner port，部署选择不能进入业务 owner。
+当前 Embedded TUI 核心路径经过 in-process App Server，Shared TUI 通过 private Runtime IPC v17；Web UI 通过 loopback WebSocket App Server，
+Desktop GUI 通过 Tauri adapter。Headless CLI/CI、ACP、Peer Host 和 SDK Host 保留独立 adapter。所有路径最终消费同一 Runtime API 或 owner
+port，部署选择不能进入业务 owner。目标路径不在本图中展开。
 
 Server bootstrap 和产品组装只创建对象并注入依赖，不是客户端请求的第二条旁路：
 
 ```mermaid
 flowchart LR
-  Assembly["产品组装"] -. "constructs" .-> Host["Host-owned App Server + transport"]
+  Assembly["产品组装"] -. "constructs" .-> Host["Host-owned adapter + transport when needed"]
   Assembly -. "constructs" .-> Runtime["Runtime / owner implementations"]
   Runtime -. "injects owner ports" .-> Host
 ```
 
 图中的虚线全部表示启动期 composition；业务请求仍只沿前一张 Current 图中的实线进入 Runtime API 或 owner port。
 
-### 4.2 Proposed target product entry paths
+### 4.2 Approved Embedded target
 
 ```mermaid
 flowchart LR
-  Rich["Desktop GUI · Web UI · Interactive TUI"] --> Host["Rich Client Host"]
-  Host --> Client["App Server client"]
-  Client --> Transport["Host-selected transport"]
-  Transport --> AppServer["App Server"]
-  Other["Headless CLI · ACP · Peer Host"] --> Adapter["独立入口适配器"]
-  SDK["Public Agent SDK"] --> SDKHost["SDK Host"]
-  AppServer --> API["Runtime API / owner ports"]
-  Adapter --> API
-  SDKHost --> API
+  TUI["Embedded interactive TUI"] --> Composition["TuiBackend composition"]
+  Composition --> RuntimePort["TuiRuntimePort"]
+  RuntimePort --> DirectRuntime["Direct Runtime adapter"]
+  DirectRuntime --> API["Runtime API / owner ports"]
+  Composition --> Management["owner service/provider adapters"]
   API --> Runtime["共享 Runtime"]
 ```
 
-提案目标是让 Desktop GUI、Web UI 和交互式 TUI 复用 App Server 行为与 wire contract，并让 Embedded/Shared 只在 Host 与
-transport 层不同。是否用 Shared App Server 替换 v17，仍取决于鉴权、实例身份、controller/lease、事件恢复、取消、限制、性能和
-回滚门槛；目标图不表示这些能力已经交付。各入口仍各自拥有 renderer、平台能力和生命周期。Headless CLI/CI、ACP、Peer Host 和
-公开 SDK 不共享 App Server wire。
+这是已批准但尚未交付的 Embedded direct-runtime 目标，属于 Phase 5。迁移完成前，Embedded TUI 继续使用 Current 图中的 in-process
+App Server；管理能力按 domain 由 composition 注入 owner service/provider，不组成 `TuiManagementPort`。
+
+### 4.3 Optional Shared App Server proposal
+
+```mermaid
+flowchart LR
+  C1["Shared Rich Client 1"] --> Transport["candidate private Pipe / UDS"]
+  C2["Shared Rich Client 2"] --> Transport
+  Transport --> Host["Shared App Server Host"]
+  Host --> Runtime["one Agent Runtime owner"]
+  Runtime --> Storage["Workspace / Session storage"]
+```
+
+这是 Phase 6 的待评审提案，不是当前 Shared TUI 的必经链路，也不改变 Current 图中的 private Runtime IPC v17。只有完成鉴权、实例身份、
+controller/lease、事件恢复、取消、限制、性能和回滚门槛后，才可评审是否替换 v17；评审也可以决定长期保留 v17。Web UI 不经过 TUI
+composition，而是继续通过自己的 loopback WebSocket App Server 入口。
 
-### 4.3 插件调用
+### 4.4 插件调用
 
 ```mermaid
 flowchart LR
@@ -614,7 +640,7 @@ flowchart LR
   Adapter["生态 adapter"] --> Provider["能力 Provider"] --> Owner["能力归属模块"]
 ```
 
-### 4.4 平台能力
+### 4.5 平台能力
 
 ```mermaid
 flowchart LR
@@ -625,7 +651,7 @@ flowchart LR
 
 关键规则：
 
-- Current 产品请求遵循 4.1 节；4.2 节的 Rich Client App Server 统一路径只有在相应 Host 完成迁移和验证后才成为当前路径。
+- Current 产品请求遵循 4.1 节；4.2 节的 Embedded direct 路径只有在相应 Host 完成迁移和验证后才成为当前路径，Shared App Server 分支还需独立评审。
   其他产品入口先经过自己的 adapter，再消费 Agent Runtime API、owner port 和只读视图；公开 SDK 只多一层 SDK Host 跨进程适配。
   Agent Runtime API 是一组小而明确的用例接口，不是必须实例化的总入口；adapter 可以调用对应归属模块的少量接口，
   但不能访问内部状态、绕过既有编排或复制业务规则。任何入口都不直接调用 Plugin Host。
@@ -649,7 +675,7 @@ flowchart LR
   可以选择下层提供方，但不能依赖 app crate；需要同时被独立应用和嵌入式模式复用的实现必须下沉到可复用 owner，
   再由各 app 和 assembly 组合。
 
-### 4.5 名词与定义归属
+### 4.6 名词与定义归属
 
 全仓人工维护文档、AGENTS、README 和代码注释遵守以下规则：
 
@@ -820,6 +846,7 @@ flowchart LR
 | Desktop | 使用 `product-full`；Settings 从现有来源目录和 integration policy 生成简短应用概览，具体审批与冲突仍进入 Tool、Agent、MCP 或 Hook owner | 可执行能力在事实所在 Host 运行；Safe Mode 只阻止新调用，不改来源、不取消正在运行的调用 |
 | CLI / TUI | 使用显式 Core owner closure：`agent-runtime` 基线、实际 service owner（包括 Remote Connect、DeepResearch、LSP、external/plugin source 与 SSH）以及九组 `tools-*`；`/extensions` 只提供状态、启停和刷新，`/hooks`、`/tools`、`/agent` 和 `/mcp` 处理各自能力 | `agent-runtime` 不再隐式携带完整 MCP/Remote/Browser/Web/Git/LSP/模型目录闭包；非交互不等待权限输入，生态解析仍在适配器，远程能力未接入时不回退本机 |
 | ACP | 使用 `DeliveryProfile::Acp`、Runtime Parts、`agent-runtime` 基线、所需 service owner 与九组 `tools-*`，但不选择 CLI 的 plugin runtime 和 Remote Connect owner | load 成功后才发布活动状态；close 排空后再卸载；完整历史、Canvas 工具物化、兼容指令来源和配置仍由 Core/ACP 管理；未选择的能力不得借 Cargo feature union 偶然出现 |
+| SDK Host（preview） | 使用 `DeliveryProfile::Sdk`、Runtime Parts 和与当前本机协议能力一致的显式 Core owner closure；TLS provider 由 Host 进程入口安装 | 当前协议不暴露远程 workspace/SSH 执行，因此不选择 Remote Connect、SSH 或 Function Agent owner；未来远程 SDK 必须复用 Server/Remote 的认证和执行域，不能回退到本机执行 |
 | Peer / Server | Peer Host 执行真实工作区操作；通用 HTTP Server 未绑定可信 workspace owner 时明确返回不支持 | 控制端不替远端发现或执行；loopback 单用户边界不扩展到远程/多用户；SSH Remote 未接入时返回不支持 |
 | Web / Mobile Web | 依赖现有后端入口 | 不持有插件执行单元，也不能据空 profile 宣称独立能力 |
 | HarmonyOS 手机 Remote | phone-only ArkTS 远程入口 | 不等于 HarmonyOS PC 本地 Runtime、CLI/TUI 或 GUI |
diff --git a/docs/architecture/remote-workspace-transport.md b/docs/architecture/remote-workspace-transport.md
index bd2bb5cb2f..669a78269b 100644
--- a/docs/architecture/remote-workspace-transport.md
+++ b/docs/architecture/remote-workspace-transport.md
@@ -138,6 +138,26 @@ omit an entry or follow a link outside the selected tree.
 Host bind mounts are not path-translated. A host path is visible only at the
 path mounted inside the container.
 
+Workspace-facing file requests are scoped by the remote connection id together
+with the POSIX workspace path whenever that id is known. A path alone is only a
+legacy compatibility fallback: the same path may exist on multiple SSH hosts,
+so new browse and search callers must carry the session or workspace connection
+id through the platform adapter. One product surface must use the same scope for
+directory browsing and filename search instead of consulting mutable global
+workspace state between requests.
+An explicit connection id is exact target identity, not a best-effort hint. If
+that connection is unavailable or does not own the requested path, the request
+fails without reading the controller filesystem or another registered host.
+
+Recursive remote filename searches publish cancellable progress as matches are
+discovered. Product surfaces render those partial results before traversal
+completes and preserve a distinct error state; a transport or routing failure
+must not be presented as an empty search result.
+The transport adapter advertises whether command-scoped search events reach the
+current surface. Peer Device controllers without a negotiated search-event
+contract use the response-based command on the peer host; they never fall back
+to searching the controller filesystem.
+
 ## Authentication and secrets
 
 Supported target methods are password, private key, private key plus OpenSSH
diff --git a/docs/architecture/rust-build-dependency-boundaries.md b/docs/architecture/rust-build-dependency-boundaries.md
index 8815f04bd4..6d30313b5a 100644
--- a/docs/architecture/rust-build-dependency-boundaries.md
+++ b/docs/architecture/rust-build-dependency-boundaries.md
@@ -47,17 +47,29 @@ Cargo 会统一同一 package 在依赖图中的 feature；workspace dependency
 
 ### 3.2 产品入口显式选择 Core 能力
 
-`src/apps/*`、`src/crates/interfaces/*` 和 installer app 直接依赖 `bitfun-core` 时必须同时：
-
-1. 设置 `default-features = false`；
-2. 声明非空 `features` 列表。
+`src/apps/*`、`src/crates/interfaces/*` 和 installer app 直接依赖 `bitfun-core` 时必须声明非空
+`features` 列表。Core 的 `default` 由 Core 自身和边界检查保证为空，因此仓内 consumer 不重复声明
+`default-features = false`；能力边界仍由 consumer 的显式 feature 集合决定。
 
 入口应选择真实需要的 owner feature；`product-full` 只能描述确实需要完整产品装配的兼容入口，不能作为尚未完成 feature/owner 分解时的占位解法。缩小某个产品的 capability 集合时必须从实际 construction/command path 反推，并保留行为等价或明确 unsupported-state 测试。
 
+Core library 的默认 feature 集合为空；完整产品必须显式选择 `product-full`。若 interface crate 以多个
+公开角色复用一条 optional Core dependency，则 dependency 声明本身保持无 feature，每个角色 feature
+分别激活 Core 并选择自己的非空 owner 闭包；兼容默认值只能组合这些已评审角色，不能重新引入
+`product-full`。每个角色必须独立编译，产品消费者还要显式关闭该 interface crate 的默认 feature 并选择
+真实使用的角色，避免 workspace feature union 掩盖边界缺口。
+
 Core 的 `agent-runtime` 只承载 Agent 生命周期基线和明确的基线工具，不得再次把 MCP、Remote Connect、模型目录、Browser/Web、Git/LSP 或产品工具组藏成 capability union。具体 service 由同名 owner feature 选择，内置工具由 `tools-*` 选择；`product-full` 显式相加全部 owner，CLI/ACP 等窄入口则按真实命令与构造路径列出自己的闭包。
 
+执行层的 `bitfun-agent-runtime` 自身也保持空默认：完整生命周期由 `agent-runtime` 选择，DeepResearch 纯编号由 `deep-research` 选择，原生 Hook 配置解析与进程执行分别由 `native-hook-settings`、`native-hook-runtime` 选择。叶能力仍留在原 owner crate 内，不为依赖收敛新建 DTO/runtime crate；完整产品必须显式恢复真实 owner，不能依赖 workspace feature union 偶然补齐。
+
 Owner feature 不等于“无前置依赖”。当实现确实调用较低层基线时，依赖必须按 `owner → baseline` 显式组合，禁止反向把 owner 藏回基线：例如 Core MCP 工具桥和 Remote Connect 依赖 Agent 生命周期，Workspace Search 依赖本地 Workspace Runtime。每个新增或调整后的 owner 闭包都必须单独 `cargo check`，避免被 Desktop/CLI 的 feature union 偶然补齐。
 
+只为已经启用的 optional dependency 增加子能力时，使用 Cargo 的弱依赖转发
+`dependency?/feature`，并把 modifier 与 runtime owner 分开命名和看护。modifier 单独启用不得激活
+runtime dependency；真实产品入口必须同时显式选择 owner 与 modifier。不要为了复用一个子 feature
+把完整 adapter、service 或 tool runtime 拉回窄闭包。
+
 Function Agent 的 Git/AI 适配由 `function-agents` 选择，MiniApp 的 domain/runtime/market
 闭包由 `tools-miniapp` 选择；不得再通过一个通用 `product-domains` Core feature 把两者、
 Plugin Source 和完整 domain feature 集合一起带回 Agent Runtime。产品装配计划若声明了当前
@@ -72,19 +84,42 @@ Plugin Source 和完整 domain feature 集合一起带回 Agent Runtime。产品
 ### 3.3 Workspace dependency 只提供共同底座
 
 - workspace 声明负责版本和真正跨产品共享的最小 feature；
+- 第三方依赖的默认 feature 若不是每个 consumer 的稳定契约，在 workspace 声明统一关闭；成员继承该策略，
+  只增加自身实际使用的 feature，不在各 manifest 重复 `default-features = false`；
+- 仓内 crate 的空默认值由被依赖 crate 拥有并由边界检查锁定，consumer 不重复关闭；只有 ACP 这类有意保留
+  非空兼容默认的 crate，窄 consumer 才必须显式关闭默认值并选择角色；
+- 被 Docker 等独立构建上下文单独复制的 manifest 无法继承 workspace 根，继续显式声明版本与默认策略；
 - runtime、HTTP、TLS、crypto、codec 等产品特定 feature 留给实际 app/service/adapter owner；
 - `full` feature 只有在所有真实消费者都需要且更窄集合不能稳定维护时才允许；
 - target-specific dependency 放在最接近平台实现的 owner，不因单一平台需求污染跨平台 crate；
 - 修改共享 dependency feature 视为构建影响变更，必须检查真实产品组合的 feature graph。
 
-### 3.4 Reqwest TLS 后端由客户端 owner 选择
+### 3.4 Reqwest 能力由客户端 owner 选择
 
-- workspace 级 `reqwest` 只统一版本以及跨产品共享的 HTTP、序列化和流能力，不启用 TLS 后端；
-- 真正创建 HTTPS client 的 app、service 或 adapter 必须在自身依赖声明中显式选择 `reqwest/rustls`，只使用 `reqwest::Url` 的 contract/assembly 路径不加载 TLS；
-- capability crate 的每个 Reqwest owner feature 必须独立带齐 `reqwest/rustls`，不能依赖 `product-full` 或其他 feature 的 Cargo feature-union 偶然补齐；
+- workspace 级 `reqwest` 只统一版本并关闭默认 feature，不替任何客户端选择 HTTP/2、序列化、表单、流、代理或 TLS 能力；
+- 真正创建 client 的 app、service 或 adapter 必须在自身依赖声明中显式选择实际使用的 Reqwest feature 和 `reqwest/rustls`；只使用 `reqwest::Url` 的 contract/assembly 路径不加载传输能力；
+- capability crate 的每个 Reqwest owner feature 必须独立带齐自己的数据/传输 feature 与 `reqwest/rustls`，不能依赖 `product-full` 或其他 feature 的 Cargo feature-union 偶然补齐；
 - 边界检查以 Cargo metadata 的解码结果看护全部直接 consumer，并检查 resolved Reqwest feature union，防止传递依赖重新激活 Native TLS；
 - 不并列启用 native-tls 兼容栈。只有真实产品场景无法由 Rustls 平台证书验证承载时，才以明确行为证据评审替换方案，而不是重新叠加第二后端。
 
+### 3.5 稳定契约 crate 按消费能力切片
+
+稳定 DTO、port 和纯契约继续由原 contract/execution crate 拥有；当同一 crate 的公开表面覆盖多个互不相关的
+能力域时，优先在原 crate 内用 additive owner feature 隔离源码和可选依赖，不为了构建数字迁移 runtime owner
+或复制公共类型。feature 关闭时 API 不可见是明确的编译期契约变化；feature 开启后必须保留原公开路径、序列化
+形状和错误语义。
+
+- contract crate 的 `default` 保持空并由目标 crate 的边界契约看护；consumer 继承该空默认值，只选择实际
+  消费的切片，不在每条 normal/dev/build/target dependency edge 重复关闭 default features；
+- feature 名描述稳定能力，例如 Agent API、workspace/terminal/remote/Git port、协议 bridge 或 Computer Use
+  contract，不描述某个临时调用方、PR 或测试；
+- 不提供 `full`、`service-ports`、`all-contracts` 等重新合并全部表面的 umbrella。只有多个 owner 共同消费且
+  无法合理拆开的稳定复合类型可以保留一个窄 aggregate，并明确列出其组成；
+- 同一依赖的 Cargo feature 会在完整图中相加，因此窄 consumer 必须独立 `cargo check/test`。完整产品构建
+  只能证明组合闭包可用，不能证明单个 consumer 的声明完整；
+- 边界检查看护目标 crate 的空默认、feature surface、consumer edge 及强/弱 feature 转发；不得依赖包名文本
+  而漏掉 rename、optional、dev/build 或 target-specific edge。
+
 ## 4. 依赖 owner 与准入检查
 
 第三方库应位于调用外部系统或实现具体能力的最低合理 owner：
@@ -95,6 +130,13 @@ Plugin Source 和完整 domain feature 集合一起带回 Agent Runtime。产品
 - DTO、事件和端口属于 contracts，保持行为轻量且不得依赖上层；
 - Assembly 选择和连接 capability，不实现具体 adapter、OS 或 service 细节；
 - app 只拥有入口、平台生命周期和产品呈现，不复制可复用服务逻辑。
+- 稳定 contract 与具体运行时实现位于同一 crate 时，优先用单一 owner feature 隔离实现依赖；不得为
+  feature-free DTO、fallback 或纯事实强拉解析器、全局状态、网络或 host adapter。
+- 平台 host 已直接拥有的 adapter 不通过 Assembly facade 二次依赖或 re-export；上层只共享稳定
+  contract，具体 emitter/transport 由真实 host 直接构造。
+- Services Core 的 feature-free surface 只保留同步稳定 contract、JSONC 和路径规范化；诊断脱敏、
+  Diff 计算和异步 workspace 文本读取分别由 `diagnostics`、`diff`、`workspace-text-runtime` owner
+  选择。Assembly 可用同名 feature 保留兼容 facade，但不得把这些实现依赖放回默认闭包。
 
 新增依赖或显著扩大已有依赖 feature 时，PR 描述至少给出：
 
diff --git a/docs/development/i18n.md b/docs/development/i18n.md
index 5e254900a2..b77828eab9 100644
--- a/docs/development/i18n.md
+++ b/docs/development/i18n.md
@@ -41,7 +41,7 @@ pnpm run i18n:audit
 | Web UI i18n runtime or namespace loading | `pnpm run i18n:contract:test && pnpm run type-check:web && pnpm --dir src/web-ui run test:run src/infrastructure/i18n/core/I18nService.test.ts` |
 | Mobile Web i18n runtime | `pnpm --dir src/mobile-web run type-check` |
 | Installer frontend i18n runtime | `pnpm --dir BitFun-Installer run type-check` |
-| Backend i18n runtime | `cargo test -p bitfun-core i18n -- --nocapture` |
+| Backend i18n runtime | `cargo test -p bitfun-core --no-default-features --features i18n-runtime --lib i18n -- --nocapture` |
 
 Do not add process-only execution plans to version control. Keep durable rules
 in this file and `docs/architecture/i18n.md`; keep temporary rollout notes out
diff --git a/docs/development/releasing.md b/docs/development/releasing.md
new file mode 100644
index 0000000000..c1b7909b88
--- /dev/null
+++ b/docs/development/releasing.md
@@ -0,0 +1,63 @@
+# Release Channels
+
+BitFun packages use an immutable build-time release channel. End users do not
+switch channels at runtime.
+
+## Stable
+
+Stable releases continue to be driven by a version bump on `main`. The
+`Release On Version Bump` workflow creates `vMAJOR.MINOR.PATCH` and dispatches
+`Desktop Package` with the default `stable` channel.
+
+## Beta
+
+Run `Desktop Package` manually with:
+
+- `tag_name`: the immutable release tag, for example `v0.2.18-beta.1`;
+- `checkout_ref`: the commit or branch to build when the tag does not exist;
+- `release_channel`: `beta`;
+- `upload_to_release`: disabled for internal Actions artifacts, enabled for a
+  public GitHub pre-release.
+
+Beta versions target the next stable version. If stable is `0.2.17`, the first
+candidate is `0.2.18-beta.1`, not `0.2.17-beta.1`. Do not use SemVer build
+metadata in a published package version; the release already records the Git
+commit separately.
+
+Public beta assets are stored on the immutable version tag. After every asset
+and signature is verified, the workflow updates only the `latest.json` asset on
+the `channel-beta` pre-release. Beta Desktop builds read that pointer and fall
+back to `https://openbitfun.com/release/beta/latest.json`.
+The beta release contains Desktop and Installer assets only. CLI and Relay
+floating releases remain stable-only.
+
+The selected ref must resolve to a commit in the protected `main` history. The
+workflow pins that SHA before dispatching platform jobs and rejects an existing
+release tag if it points somewhere else. Configure the signing secrets and the
+public beta approval policy so untrusted pull-request code cannot access them.
+This protected-history requirement applies to the canonical `GCWing/BitFun`
+repository; forks may run packaging from their own test branches. A fork beta
+uses that fork's `channel-beta` release as both updater origins, so it cannot
+silently consume or mutate the canonical beta channel.
+
+A stable release promotes the beta pointer only when its version is not older
+than the current beta. This lets beta users move from `0.2.18-beta.N` to
+`0.2.18` without allowing a late workflow to roll the channel backward.
+
+Beta and stable currently share the same bundle identity and data directories.
+Installing beta replaces stable; side-by-side installation is not supported.
+
+## Mirror
+
+The mirror script defaults to stable. Run a separate beta sync with:
+
+```bash
+BITFUN_RELEASE_CHANNEL=beta scripts/openbitfun-release-sync.sh
+```
+
+The beta invocation writes below `/release/beta` and intentionally skips the
+stable-only CLI and Relay floating manifests.
+
+Production cron must run this in-repo script from the BitFun checkout. Do not
+create a detached copy. Host paths, Nginx, and the rest of the origin restore
+steps live in [`deploy/openbitfun-host/README.md`](../../deploy/openbitfun-host/README.md).
diff --git a/docs/development/ui-testids-CN.md b/docs/development/ui-testids-CN.md
index 3691485092..38ff31dc63 100644
--- a/docs/development/ui-testids-CN.md
+++ b/docs/development/ui-testids-CN.md
@@ -182,6 +182,7 @@
 | Chat 输入可编辑区域 | `chat-input-textarea` | 富文本可编辑区域。 |
 | Chat 发送按钮 | `chat-input-send-btn` | 输入有效时的发送动作。 |
 | Chat 取消按钮 | `chat-input-cancel-btn` | 存在时用于取消进行中的发送/生成。 |
+| Chat 继续中断任务按钮 | `chat-input-continue-interrupted-btn` | 输入框为空时继续最近一个可恢复的中断 Turn。 |
 | Chat 输入工作区条 | `chat-input-workspace-strip` | composer 上方的活动工作区条。 |
 | Chat 输入目标切换器 | `chat-input-target-switcher` | 目标/模式切换器。 |
 | Chat 输入图片条 | `chat-input-image-strip` | 已附加图片条。 |
diff --git a/docs/development/ui-testids.md b/docs/development/ui-testids.md
index ce11e0d619..8f00a6ffdb 100644
--- a/docs/development/ui-testids.md
+++ b/docs/development/ui-testids.md
@@ -183,6 +183,7 @@ Avoid adding IDs to these surfaces unless there is a clear automated workflow.
 | Chat input editable region | `chat-input-textarea` | Rich text editable region. |
 | Chat send button | `chat-input-send-btn` | Send action when input is valid. |
 | Chat cancel button | `chat-input-cancel-btn` | Cancels in-progress send/generation when present. |
+| Chat continue interrupted button | `chat-input-continue-interrupted-btn` | Resumes the latest recoverably interrupted turn when the composer is empty. |
 | Chat input workspace strip | `chat-input-workspace-strip` | Active workspace strip above composer. |
 | Chat input target switcher | `chat-input-target-switcher` | Target/mode switcher. |
 | Chat input image strip | `chat-input-image-strip` | Attached image strip. |
diff --git a/docs/features/session-runtime-usage-report-design.md b/docs/features/session-runtime-usage-report-design.md
index 08d32d3cd9..2c423febd9 100644
--- a/docs/features/session-runtime-usage-report-design.md
+++ b/docs/features/session-runtime-usage-report-design.md
@@ -689,8 +689,8 @@ Risk and drift controls:
 
 Required verification before merging P0:
 
-- `cargo check -p bitfun-core`
-- `cargo test -p bitfun-core session_usage -- --nocapture`
+- `cargo check -p bitfun-core --no-default-features --features agent-runtime`
+- `cargo test -p bitfun-core --no-default-features --features agent-runtime --lib session_usage -- --nocapture`
 - Focused CLI command tests or manual CLI smoke if no existing helper test harness exists.
 - `pnpm run lint:web`
 - `pnpm run type-check:web`
@@ -1038,8 +1038,8 @@ Risks and mitigations:
 
 Verification:
 
-- `cargo test -p bitfun-core session_usage -- --nocapture` once tests exist.
-- `cargo check -p bitfun-core`.
+- `cargo test -p bitfun-core --no-default-features --features agent-runtime --lib session_usage -- --nocapture` once tests exist.
+- `cargo check -p bitfun-core --no-default-features --features agent-runtime`.
 - DTO tests for workspace identity, report scope, in-progress reports, cache-unavailable coverage, and redaction metadata.
 
 ### Task 2: Non-model-visible local report item
diff --git a/docs/performance/01-compile-performance.md b/docs/performance/01-compile-performance.md
index e84c31ea5d..f0996738b0 100644
--- a/docs/performance/01-compile-performance.md
+++ b/docs/performance/01-compile-performance.md
@@ -1,8 +1,8 @@
 # BitFun 编译与依赖治理计划
 
-> 最近核实：2026-08-10
+> 最近核实：2026-08-14
 >
-> 实现复核基线：`gcwing/main@e63084bc5`
+> 实现复核基线：`gcwing/main@76f8b89e2`
 >
 > 性能 A/B 基线：`gcwing/main@1f538b96d`
 >
@@ -16,9 +16,14 @@
 
 | 结论 | 说明 |
 |---|---|
-| 服务测试链接拓扑已收敛 | Services 两个 crate 的集成 target 总数从 33 降到 25；选中的 `local-storage`、MCP、基础 SSH 闭包从 16 个集成 executable 降到 8 个 |
-| Agent Runtime 基线不再隐藏全量 capability union | `bitfun-core/agent-runtime` 只保留生命周期和基础工具 owner；MCP、Remote Connect、Browser/Web、Git、模型目录等由产品入口显式组合，三平台 normal/build 闭包各减少 105–110 个版本化 package instance |
-| 完整产品行为和闭包保持 | `product-full` 显式组合全部 owner，Windows normal/build 闭包保持 570；CLI 保持 649。ACP 只退出未选择的隐含能力，Windows/macOS/Linux 分别减少 10/13/22 |
+| 集成测试链接拓扑已收敛 | Services 两个 crate 的集成 target 总数从 33 降到 25；External Sources 的 adapter/assembly target 从 22 降到 7；五个 Contracts/AI/Assembly crate 又从 28 降到 10，feature、平台和外部系统失败域保持独立 |
+| Agent Runtime 基线不再隐藏重型 capability | `bitfun-core/agent-runtime` 只保留生命周期和基础工具 owner；文档转换与订阅认证也改为产品显式 modifier。在最新主线 A/B 中，三平台 normal/build 闭包进一步减少 69/64/110 个版本化 package instance |
+| App Server 不继承未消费能力 | App Server 保持现有 Agent/Git/外部来源 handler 边界，不再因 Core 基线携带文档转换和本地订阅凭据，三平台闭包减少 61/56/78 |
+| SDK Host 使用显式能力闭包 | SDK Host 保留当前本机协议和工具能力，但不再通过 `product-full` 携带协议未暴露的 Remote Connect、SSH、Function Agent 等能力；Windows/macOS/Linux normal/build 闭包减少 66/68/76 |
+| Core 默认值不再代表完整产品 | Core library 的默认 feature 集合为空，能力内部实现依赖回到实际 owner；最新三平台 feature-free 闭包继续减少 30/31/31 个 package instance |
+| ACP 按实际宿主拆分角色 | 兼容默认值仍为 client + server；Desktop 只选择 client，CLI 选择两者。Desktop 独立构建不再编译 ACP 的 4,211 行 server/runtime 源码，产品协议与远程行为不变 |
+| 完整产品行为保持 | `product-full` 显式组合全部 capability owner；Core 自身不再携带 Desktop host transport而减少 1 个 package，Desktop 闭包不变。CLI 显式保留原先实际生效的 Oniguruma 高亮后端，ACP 默认组合保持原能力 |
+| 默认 feature 责任已集中 | 仓内空默认由被依赖 crate 和边界检查负责；workspace member 的 `default-features = false` 从 70 处降到 6 处，仅保留 ACP 两个窄 consumer 与 Relay 独立 Docker 上下文的 4 处必要声明。第三方默认策略尽可能回到 workspace 根，根 lock 只删除 11 个 package、无新增 |
 | Installer 删除未使用的直接能力 | 独立 manifest 的直接 dependency 从 18 降到 10，Windows normal/build 闭包减少 6；不把 Installer 并入根 workspace，本 PR 按要求不提交其生成 lockfile |
 | focused test 仍保持精确 | 同 owner、feature、平台和进程语义的源文件进入分组 target；使用 `--test <target> <module>::<filter>` 运行单模块 |
 
@@ -44,7 +49,9 @@
 
 ## 3. 当前基线
 
-### 3.1 服务层测试拓扑
+### 3.1 集成测试链接拓扑
+
+#### Services
 
 本轮只合并 owner 和运行边界相同的测试。`session_write_lock_contracts` 依赖当前测试 executable 启动异常退出子进程，因此继续保持独立；不同 feature 的服务测试也不合并。
 
@@ -72,6 +79,24 @@ clean/rebuild，表中为均值。时间是方向性证据，不是硬阈值。
 MCP 的 2→1 candidate 也做过同口径 A/B，但冷构建和 owner 重建均无可区分的提速；streamable HTTP
 测试还拥有真实 loopback TCP/SSE/超时失败域，因此最终继续保持两个 target，不计入本轮收益。
 
+#### External Sources adapters 与 assembly
+
+同一 crate 内、相同依赖和运行边界的静态来源合同通过 wrapper target 收敛；测试正文逐字迁移，仍可用
+`--test <target> <module>::` 聚焦到单个来源模块。OpenCode 的 MCP 子进程、受管插件服务和 Node 脚本
+runtime 分别保留独立 target，避免为了减少链接次数混合不同环境、超时和故障语义。
+
+| 范围 | 变更前 target | 变更后 target | 集成测试数 |
+|---|---:|---:|---:|
+| OpenCode adapter | 8 | 4 | 130 |
+| Claude Code adapter | 4 | 1 | 51 |
+| Codex adapter | 3 | 1 | 47 |
+| External Sources assembly | 7 | 1 | 30 |
+| 合计 | 22 | 7 | 258 |
+
+这部分只减少 15 个重复链接的 test executable；未新增 dependency、feature 或 CI 命令，也不以当前证据
+宣称 wall-clock 提速。Cargo 边界检查锁定显式 target、wrapper-only root、leaf 唯一引用和 crate-level cfg，
+避免后续新增测试静默绕过分组拓扑。
+
 可重复确认的产物变化如下；`test executable` 包含每个 crate 的 lib test harness，因此比 integration
 target 多 1。PDB 大小会随工具链变化，只比较同次 A/B：
 
@@ -80,6 +105,26 @@ target 多 1。PDB 大小会随工具链变化，只比较同次 A/B：
 | local-storage | 13 → 6 | 25.2 → 19.2 MiB | 135.7 → 91.9 MiB |
 | 基础 Remote SSH | 3 → 2 | 3.9 → 2.8 MiB | 53.5 → 43.8 MiB |
 
+#### Contracts、AI adapters 与 Product Assembly
+
+五个纯合同/组装 owner 使用显式 wrapper target；AI 的纯协议测试与真实 loopback SSE 测试继续分成两个
+失败域，Product Domains 的默认、Plugin Source、External Sources、Function Agent 与 MiniApp 也继续按
+owner feature 分开。270 个 integration tests 不变，模块过滤仍可聚焦单个 leaf：
+
+| 范围 | 变更前 target | 变更后 target | 集成测试数 |
+|---|---:|---:|---:|
+| `core-types` | 4 | 1 | 10 |
+| `runtime-ports` | 5 | 1 | 21 |
+| `product-domains` | 9 | 5 | 179 |
+| `ai-adapters` | 7 | 2 | 29 |
+| `product-capabilities` | 3 | 1 | 31 |
+| 合计 | 28 | 10 | 270 |
+
+对应五个 lib test harness 的 test executable 总数从 33 降到 15；workspace integration target 从
+91 降到 73。该变化减少 18 次重复链接，但单叶变更会重链所属分组，因此这里只报告确定的拓扑收益，
+不在缺少同机多轮 A/B 时宣称 wall-clock 提速。边界检查锁定 exact leaf、owner feature 和空
+`required-features` 的默认 target，避免以后用 `product-full` 扩大测试闭包。
+
 ### 3.2 依赖与 feature
 
 闭包使用 `cargo tree -e normal,build` 按目标平台统计版本化 package instance；它衡量进入编译图的
@@ -94,26 +139,247 @@ package/version，不等同于实际秒数。路径 package 因 A/B worktree 路
 | Desktop | 792 → 792 | 807 → 807 | 892 → 892 | 完整产品继续使用既有跨平台截图行为，本轮不以扩大根 lock 依赖宇宙换取单平台闭包下降 |
 | Installer | 333 → 327 | — | — | Windows 独立 workspace；直接 dependency 18 → 10 |
 
+下表前五项延续 `gcwing/main@734e5b05f` 的已核实 A/B，SDK Host 行以
+`gcwing/main@22f5411e7` 为变更前基线。三平台 target 分别为 `x86_64-pc-windows-msvc`、
+`aarch64-apple-darwin` 和 `x86_64-unknown-linux-gnu`；计数先移除 Cargo tree 的重复展示标记
+`(*)`，再按 package/version 去重：
+
+| 本轮闭包 | Windows | macOS | Linux | 行为边界 |
+|---|---:|---:|---:|---|
+| Core `agent-runtime` | 343 → 274 | 330 → 266 | 375 → 265 | 文档扩展识别保留；转换和本地订阅凭据明确不可用 |
+| App Server | 490 → 429 | 477 → 421 | 508 → 430 | 现有 handler/DTO 保持，未消费的两个能力退出 |
+| Core `product-full` | 570 → 570 | 557 → 557 | 601 → 601 | 显式恢复 `document-read` 与 `subscription-auth` |
+| CLI | 649 → 649 | 649 → 649 | 672 → 672 | 显式保持原有能力 |
+| ACP | 589 → 587 | 574 → 572 | 594 → 592 | 保持原有能力，同时退出 Reqwest 未使用的 `mime_guess`/`unicase` |
+| SDK Host | 578 → 512 | 565 → 497 | 609 → 533 | 保留本机 SDK profile、九组工具 owner、外部静态来源和 ring TLS；退出未暴露的 Remote Connect、SSH、Function Agent 与完整产品附属能力 |
+
+本轮没有新增 crate 或第三方 package；SDK Host 只把已有测试依赖 `rustls` 调整为进程入口实际使用的
+normal dependency，根 lock package 集合不变。前两类收益来自 `anydoc` 及其文档解析/压缩依赖，
+以及订阅凭据的 keyring/加密/本地存储依赖；SDK Host 的收益来自未公开远程能力对应的
+SSH、密钥和连接子图退出。完整产品 package 集合不变，
+因此这里只报告依赖图收敛，不宣称 `product-full` wall-clock 提速。
+
+以下是以 `gcwing/main@3d8ee4bc0` 为变更前基线、使用同样三个 target triple 和去重口径复算的最新 A/B：
+
+| 最新闭包 | Windows | macOS | Linux | 行为边界 |
+|---|---:|---:|---:|---|
+| Core `--no-default-features` | 104 → 102 | 93 → 91 | 92 → 90 | 删除 Core 不再消费的 `tokio-stream`、`urlencoding` 直接边 |
+| Core `product-full` | 570 → 570 | 557 → 557 | 601 → 601 | 完整产品仍从真实 adapter/service owner 获得两项依赖 |
+| CLI | 649 → 643 | 649 → 642 | 672 → 665 | 删除未调用的 `syntect-tui`/`dashmap`；显式保留既有 Oniguruma 高亮后端 |
+| Desktop | 792 → 790 | 807 → 805 | 892 → 887 | 删除从未注册、没有调用方的 global-shortcut 插件和 ACL |
+| MiniApp Market | 205 → 204 | 208 → 207 | 206 → 205 | 删除服务从未消费的 `urlencoding` 直接边 |
+| Page Function tests | 38 → 35 | 38 → 35 | 38 → 35 | 删除同步 Rust 测试未使用的 dev-only Tokio 闭包 |
+
+以下继续以 `gcwing/main@7345619ac` 为变更前基线，记录 Core 默认值与 ACP 角色边界收敛。三平台、
+依赖类型与去重口径与上表一致：
+
+| 本轮闭包 | Windows | macOS | Linux | 行为边界 |
+|---|---:|---:|---:|---|
+| Core 隐式默认 | 570 → 93 | 557 → 82 | 601 → 81 | library 默认不再冒充完整产品；只保留 feature-free facade 与 build dependency |
+| Core `--no-default-features` | 102 → 93 | 91 → 82 | 90 → 81 | 四条 Core 直接边退出并回到实际 owner；package 集合净减 9 |
+| Core `product-full` | 570 → 570 | 557 → 557 | 601 → 601 | Desktop/Server 等完整产品入口仍显式恢复全部能力 |
+| ACP 默认兼容组合 | 587 → 587 | 572 → 572 | 592 → 592 | 默认仍精确组合 client + server，独立 ACP 测试与外部兼容行为不缩小 |
+| Desktop | 790 → 790 | 805 → 805 | 887 → 887 | package 集合不变；ACP 仅编译 client 模块，server/runtime 4,211 行退出该 package build |
+| CLI | 643 → 643 | 642 → 642 | 665 → 665 | 显式选择 ACP client + server，既有 CLI-hosted server 行为不变 |
+
+ACP 两个新角色的当前独立闭包为 client 397/390/391、server 533/518/539（Windows/macOS/Linux）。
+它们不能直接相加：Cargo 会对共同依赖去重。该拆分的确定收益是 Desktop 独立构建不再编译 ACP server
+模块，而不是 Desktop package 数下降；因此不宣称完整 Desktop wall-clock 提速。
+
+Core 空闭包减少的 9 个 package instance 主要来自 `base64` 与 `futures` 的独有子图；`regex` 和
+`tokio-util` 的 Core 直接边虽然已经移除，但 package 仍由 feature-free contracts/services 路径传递保留。
+因此本轮证明的是 direct owner 边界收敛，不能把四条 direct edge 都描述成 package 完全退出。
+
+Core 的 bare/default 编译契约本轮发生了有意变化：仓内产品消费者此前已经全部关闭默认 feature 并显式
+选择 owner，因此运行行为不变；仓外若有 path/git consumer 依赖旧的隐式完整表面，需要显式选择
+`product-full`，或改为列出实际使用的 owner。该迁移属于编译期契约变化，不能描述成对未知外部 consumer
+完全无影响。
+
+Syntect 不能机械地只删适配层：旧 feature union 同时启用 `regex-fancy` 与 `regex-onig` 时，实际由
+Oniguruma 后端处理。当前 manifest 直接选择 `regex-onig`，因此运行后端、默认 syntax/theme 和
+Syntect→Ratatui 样式转换保持不变，同时让未生效的 fancy 后端与未消费的 YAML loader 退出。
+
 Package instance 会低估“同一个大 crate 少编译了多少 feature 代码”。在 Windows
 `agent-runtime` 闭包中，`bitfun-services-integrations` 的 Cargo active feature 从 61 个降到 6 个，
 只保留 `workspace-search` 及其 5 个直接依赖 feature；`bitfun-product-domains` 从 13 个降到 5 个，
 只保留 Agent Runtime 实际使用的 external-subagent contract slice。Function Agent、MiniApp、
 Plugin Source 由各自 owner 选择，完整产品仍经 `product-full` 显式恢复。
 
-根 `Cargo.lock` 与实现复核基线保持一致，package 记录不增加；Installer 自己生成的
-`BitFun-Installer/src-tauri/Cargo.lock` 本 PR 不提交。
+上一轮根 `Cargo.lock` 从 1176 降到 1169，精确删除 `syntect-tui`、`custom_error`、`fancy-regex`、
+`yaml-rust`、`linked-hash-map`、`tauri-plugin-global-shortcut` 和 `global-hotkey`；没有新增、升级或
+降级 package。本轮 feature/角色边界调整保持该 lockfile 字节不变，也没有新增第三方 package。
+Installer 自己生成的 `BitFun-Installer/src-tauri/Cargo.lock` 不提交。
+
+以下以 `gcwing/main@a4e06cae3` 为变更前基线，完成 Core feature-free 依赖基线的剩余 owner
+收敛。统计仍使用相同三个 target triple、`normal,build` 边和版本化 package instance 去重口径：
+
+| 最新闭包 | Windows | macOS | Linux | 行为边界 |
+|---|---:|---:|---:|---|
+| Core `--no-default-features` | 93 → 63 | 82 → 51 | 81 → 50 | Fluent runtime、Tool Contracts、host transport、诊断/Diff 实现与非基线 Tokio 子图退出；locale/config/path 稳定契约保留 |
+| Core `product-full` | 570 → 569 | 557 → 556 | 601 → 600 | 显式恢复 I18n、Agent 与全部产品 owner；仅不再经 Core 携带 Desktop host transport |
+| Desktop | 790 → 790 | 805 → 805 | 887 → 887 | Desktop 原本已直接拥有 transport，完整宿主依赖图和行为不变 |
+| Services Core feature-free | 22 → 15 | 22 → 15 | 22 → 15 | Regex、Similar 与 Tokio 全部退出；只保留同步稳定 contract、JSONC 与路径规范化 |
+| Codex Adapter | 79 → 72 | 78 → 71 | 78 → 71 | 只使用同步 workspace path contract，不再继承 Services Core 的文本实现依赖 |
+| Static Hook Support | 72 → 65 | 73 → 66 | 72 → 65 | feature-free Services Core 依赖边不再携带未消费的文本实现依赖 |
+| Claude Code Adapter | 85 → 82 | 84 → 81 | 84 → 81 | Markdown owner 仍保留 Regex；Diff 与 Tokio 退出 |
+| OpenCode Adapter | 141 → 140 | 140 → 139 | 140 → 139 | 既有 Markdown/Tokio owner 保留，仅未消费的 Similar 退出 |
+
+Core 的直接 Tokio capability 从 `fs/io-util/macros/net/rt/sync/time` 收敛为 `fs/sync`；异步宏、
+网络以及产品 runtime 能力由现有 `agent-runtime`、`browser-control`、`debug-log`、`lsp` owner
+显式选择。feature-free Core 仍通过 `bitfun-services-core/json-io` 获得其原子 JSON 写入所需的
+`rt/time`，测试使用的多线程运行时只留在 dev-dependency。`runtime-ports/permission` 没有被机械移出：`GlobalConfig` 与项目权限文件公开 DTO
+确实在 feature-free facade 中使用它，继续保留比制造条件 API 更符合契约稳定性。
+
+Services Core 的 feature-free profile 进一步不再依赖 Tokio。同步路径规范化仍可直接使用；异步受限
+workspace 读取由 `workspace-text-runtime` 选择，诊断日志脱敏与本地 Diff 分别由独立 owner feature
+选择。Core 继续通过同名 feature 保留原 facade，`product-full` 显式组合两者，避免把依赖收敛变成
+完整产品的源码或行为回归。
+
+本轮有意收紧了数项编译期契约。直接使用 feature-free Core 的仓外 consumer 若调用
+`I18nService`，必须显式选择 `i18n-runtime`；旧的
+`bitfun_core::infrastructure::events::TransportEmitter` 导入路径不再提供，host adapter 应直接从
+`bitfun-transport` 导入。直接依赖 feature-free `bitfun-services-core` 的 consumer 若调用诊断脱敏、
+本地 Diff 或异步 workspace 文本 API，必须分别选择 `diagnostics`、`diff` 或
+`workspace-text-runtime`；通过 Core 兼容 facade 调用前两者时选择同名 Core feature。仓内真实 consumer
+已全部迁移，完整产品的运行时事件、翻译和服务行为不变，但这些源码迁移不能描述为对未知外部
+consumer 零影响。
+
+该轮结束时根 lock package 为 1169，新增、升级、降级 package 均为 0。由于 Core 删除本地
+`bitfun-transport` 直接边，`Cargo.lock` 的 Core dependency record 同步删除这一行；这是依赖边
+收敛，不是 package 集合增长，也不通过保留无 owner 的 optional dependency 伪造字节不变。
+
+以下以 `gcwing/main@aeb8099ae` 为变更前基线，继续收敛两个稳定契约 crate 的源码与依赖可见面。
+统计仍使用 `x86_64-pc-windows-msvc`、`aarch64-apple-darwin`、`x86_64-unknown-linux-gnu`，并按
+`cargo tree -e normal,build --no-dedupe` 的版本化 package instance 去重：
+
+| 契约/消费闭包 | Windows | macOS | Linux | 边界结果 |
+|---|---:|---:|---:|---|
+| Runtime Ports feature-free | 21 → 13 | 21 → 13 | 21 → 13 | Agent API、服务端口、插件与脚本端口按 owner feature 退出；common marker/结果契约保留 |
+| Tool Contracts feature-free | 25 → 18 | 25 → 18 | 25 → 18 | ACP/MCP bridge、Computer Use 与 element-token 源码按独立 feature 退出 |
+| Terminal Core | 94 → 92 | 82 → 80 | 81 → 79 | 只选择 terminal port，不再编译无关 Session/Git/Remote workspace 表面 |
+| Plugin Runtime Client | 22 → 16 | 22 → 16 | 22 → 16 | 只选择 plugin-runtime contract，不再继承完整 Runtime Ports 表面 |
+| Tool Runtime | 78 → 78 | 66 → 66 | 65 → 65 | 真实 owner 仍消费稳定 handle 组合，package 闭包不变 |
+| ACP client | 385 → 385 | 378 → 378 | 379 → 379 | 依赖重叠使 package 数不变；组合闭包启用 ACP bridge 与 Core 所需 Computer Use contract，不启用 MCP/element-token |
+| ACP server | 522 → 522 | 507 → 507 | 528 → 528 | 组合闭包启用 Core 所需 Computer Use/MCP contract，不继承 ACP client bridge 或 element-token |
+
+Package instance 会低估同一 crate 内源码切片的收益。Runtime Ports 变更前约 6,045 行源码全部进入任意
+consumer；当前 feature-free 非测试表面约 314 行，约 95% 的 Agent/服务/plugin/script 端口源码退出最小编译。
+Tool Contracts 约 6,846 行源码中，ACP/MCP bridge、Computer Use 与 element-token 共约 2,861 行
+（41.8%）由各自 feature 控制。这里报告的是解析、类型检查和增量重编译输入收敛；没有重复的冷/热构建
+样本，因此不宣称完整产品 wall-clock 提速。完整产品和真实 owner 显式恢复原 API，runtime ownership、
+wire shape 与行为不变。
+
+`bitfun-agent-runtime` 的直接 Runtime Ports 边也不再选择其源码未消费的 `remote-exec-port` 与
+`tool-runtime-handles`；Core 的 `agent-runtime` owner 仍显式选择二者，因为具体 assembly 路径确实使用这些句柄。
+
+这次切片包含有意的编译期可见性收紧：直接依赖 Runtime Ports 或 Tool Contracts 的仓外 consumer 需要
+显式选择所用 port/bridge/Computer Use/element-token feature。启用相应 owner 后原公开路径保持不变，
+仓内 consumer 已逐项闭合；不能把 feature-free 构建下的源码不可见描述为对未知外部 consumer 零影响。
+
+本轮没有新增、升级或降级第三方 package，根 `Cargo.lock` 保持字节不变；也没有新增 CI job、矩阵或命令。
+Runtime Ports 的 owner-specific integration targets 保持彼此独立，避免为了减少 executable 数重新制造
+feature union。
+
+以下以 `gcwing/main@a4d944e5b` 为变更前基线，统一默认 feature 的责任位置。该主线相对前次测量
+没有 Cargo 输入变化；统计继续使用同样三个
+target triple 和 `normal,build` 版本化 package instance 去重口径；它只描述编译图，不直接代表墙钟时间：
+
+| 闭包 | Windows | macOS | Linux | 结果 |
+|---|---:|---:|---:|---|
+| Core feature-free | 63 → 63 | 51 → 51 | 50 → 50 | 空默认与显式 owner feature 不变；只删除 consumer 侧冗余开关 |
+| Core `product-full` | 569 → 569 | 556 → 556 | 600 → 600 | 完整产品 owner 集合与运行能力不变 |
+| CLI | 642 → 640 | 641 → 639 | 664 → 662 | Markdown 只使用 parser，退出未消费的 `getopts` 与 HTML renderer |
+| Desktop | 790 → 790 | 805 → 793 | 887 → 887 | BitFun 的 macOS Objective-C 直接依赖边按实际 imports 选择 feature；Tauri/wry 等第三方仍合并自身所需 feature |
+| Relay Service | 190 → 190 | 193 → 193 | 192 → 192 | 独立 Docker manifest 保持显式版本与默认策略，闭包不变 |
+| Services Integrations feature-free | 26 → 26 | 28 → 28 | 27 → 27 | Qrcode 的 PNG/SVG 能力仍由 `remote-connect` owner 显式选择 |
+
+workspace member 中显式 `default-features = false` 从 70 处降到 6 处：62 个仓内空默认重复声明删除，
+MiniApp/Skin Market 的 2 个 SQLx 声明改为继承 workspace 根策略。剩余 6 处中，两处是 Desktop/CLI 对 ACP
+的必要例外，因为 ACP 有意保留 `client + server` 兼容默认，而两个产品入口必须分别选择 client-only 和
+双角色；另 4 处属于 Relay Server、Relay Service 和 Page Function Runtime，它们会被 Docker 单独复制、
+无法继承 workspace 根，因此继续显式声明 Tokio、SQLx 与 RquickJS 的默认策略。
+
+第三方默认收敛只处理有源码与构建证据的依赖：Futures 保留 `std`，Tracing 保留 `std`，Chrono 保留
+`serde + clock + std`；Tokio Stream 的真实 consumer 只使用 feature-free 的 Receiver/iter wrappers；
+Remote Connect 显式选择 qrcode 的 `image + svg`；Pulldown-Cmark 不启用 CLI 未使用的命令行/HTML renderer；
+BitFun 的 macOS Objective-C binding 直接依赖边只选择源码导入的类型和所需 `std`；Cargo 的最终
+feature union 仍包含 Tauri、wry、notification、updater 等第三方路径的需求。根 `Cargo.lock` 从 1169
+降到 1158，新增 package 为 0；删除项仅来自
+Pulldown-Cmark 的 `getopts`/HTML escape 子图和未使用的 Objective-C framework binding。未关闭 Axum、Tauri、
+Clap、Tracing Subscriber、Notify 等默认即产品契约或缺少独立收益证据的依赖。
 
 | 状态 | 范围 | 处理结论 |
 |---|---|---|
 | 已稳定 | 根 `Cargo.lock`、Reqwest Rustls 单栈、workspace Tokio 最小基线 | 不重复治理 |
-| 本轮完成 | Core Agent Runtime capability、Installer 未使用直接依赖 | 以真实入口 closure 收敛，不建立新的产品 umbrella，也不扩大根依赖宇宙 |
-| 当前不动 | App Server / Server | 只为保持现有 handler 编译显式声明其已消费的 Core owner；不在改造稳定前继续拆其生产路径 |
+| 本轮完成 | Core 空默认与 capability-local 工具依赖、ACP client/server 角色、Core Agent Runtime capability、文档转换与订阅认证 modifier、SDK Host 显式 owner closure、Installer/CLI/Desktop/Core/MiniApp Market/Page Function 未使用直接依赖 | 以真实入口 closure 收敛，不建立新的产品 umbrella；根 lock 不增加 package |
+| 本轮完成 | App Server schema owner | wire DTO 与 TypeScript 导出收敛到 protocol；server 只保留 handler 与 owner-to-wire 转换，正式 client 继续由独立 client crate 持有 |
 | 明确保留 | Desktop screenshots backend | 替换方案必须同时保持三平台坐标/权限/区域捕获语义且不增加根 lock package；当前候选不满足 |
 | 明确保留 | `portable-pty 0.8/0.9` | 非 OHOS 与 OHOS 的平台兼容选择，不为去重破坏 |
 
 重复版本数量只用于发现候选，不能直接转化为治理任务。`oxc`、`rquickjs`、vendored `git2`、`sherpa-onnx` 等重依赖都有真实 capability owner；只有某个产品入口不消费对应能力时，才允许让它退出该入口的构建图。
 
-### 3.3 CI 与本地验证
+以下以 `gcwing/main@d1d1dd9e8` 为变更前基线，把 `bitfun-agent-runtime` 内部长期共存的完整 Runtime、
+DeepResearch 纯编号和原生 Hook 配置/执行拆成同 crate 的 owner feature。没有新增 crate 或兼容 `full`
+umbrella；统计仍按三个既定 target triple、`normal,build` 版本化 package instance 去重：
+
+| 闭包 | Windows | macOS | Linux | 边界结果 |
+|---|---:|---:|---:|---|
+| Agent Runtime feature-free | 76 → 1 | 79 → 1 | 78 → 1 | 空默认只保留 crate 本身；所有运行时源码和第三方依赖由 owner feature 选择 |
+| Agent Runtime `agent-runtime` | 76 → 76 | 79 → 79 | 78 → 78 | 完整 Runtime API、Hook 执行和依赖闭包保持不变 |
+| Agent Runtime `native-hook-settings` | 76 → 10 | 79 → 10 | 78 → 10 | Hook 配置解析不再编译进程执行、Session、Tool 和 Runtime Services |
+| Services Integrations `deep-research` | 77 → 36 | 80 → 38 | 79 → 37 | 只保留纯编号、WorkspaceFS port 与报告 IO；完整 Agent Runtime 退出 |
+| Services Integrations `hook-import` | 121 → 89 | 112 → 79 | 111 → 78 | 只复用 Hook settings contract；Session/Agent lifecycle 退出 |
+| Core `product-full` | 569 → 569 | 556 → 556 | 600 → 600 | 完整产品显式恢复全部真实 owner，package 闭包不缩水 |
+
+测试闭包也按真实 owner 收敛：Agent Runtime 的 DeepResearch target 在 `normal,build,dev` 口径从
+`76/79/78` 降到 `6/6/6`，Hook settings target 降到 `10/10/10`；Services DeepResearch 测试从
+`80/85/85` 降到 `44/48/47`。为保持 feature 与进程失败域，Agent Runtime 显式 integration target 从
+5 个增为 7 个：DeepResearch 与 Hook settings 各自独立，Unix Hook 子进程测试继续独立；没有把这些
+focused target 加进 CI，也没有新增 job、矩阵或仓库级命令。
+
+该轮同时修复 DeepResearch post-turn IO 的既有远程路径错误：Core 现在把当前 session 注入的
+`WorkspaceFileSystem` 传给 Services Integrations，本地和 Remote SSH 都通过同一 provider 读取报告、
+引用表并写回 sidecar；远程逻辑路径不再被 Windows host 当成本机 `Path` 探测。provider 缺失时明确
+跳过并记录 warning，不允许回退到宿主文件系统。纯编号算法、报告内容、sidecar schema 和本地
+best-effort 行为保持不变。路径拼接语义也由 `WorkspaceFileSystem` provider 持有：本地 provider
+继承宿主路径规则，Remote SSH 对绝对、home 和相对 workspace root 均保持 POSIX 分隔符。
+
+`bitfun-services-integrations::deep_research::run_for_session_workspace` 与
+`try_renumber_research_report` 的公开函数签名现在要求显式传入 `WorkspaceFileSystem`；仓内唯一生产
+调用者已迁移。这是为消除远程路径宿主回退而做的有意源码契约收紧，不能描述为对未知的仓外 path/git
+consumer 零影响。完整 Rust Runtime SDK 同时将兼容版本提升为 v6：仓外 embedder 需要在
+`bitfun-agent-runtime` 依赖上显式选择 `agent-runtime`；启用后原 `sdk` 公开路径和行为保持不变。
+
+这里仍只报告依赖图和 focused-test 输入，不宣称完整产品 wall-clock 提速。根 `Cargo.lock` package
+集合与字节均不变，新增/升级/降级 package 为 0；`.github` 和 `ci.yml` 不变。
+
+### 3.3 App Server TypeScript schema owner
+
+变更前，Web `gen:types` 先编译 protocol，再编译完整 `bitfun-app-server`，后者会把
+Core、Agent Runtime 和具体 Service handler 闭包带入前端类型生成。最新同代码状态的
+Frontend Build 样本中，`gen:types` 约 430 秒，占 `build:web` 约 484 秒的 88.8%；其中
+protocol 导出约 42.58 秒，App Server 导出约 6 分 26 秒。单次 CI 样本只用于定位热点，
+不能独立证明合入后的 wall-clock 收益。
+
+本轮将 behavior-light wire DTO 和 TS derive 统一到 `bitfun-app-server-protocol`，server 端
+保留 Core/Runtime/Service owner 到 wire read model 的显式转换。既有 `app-server::schema`
+继续兼容 re-export，`bitfun-app-server/ts` 继续兼容转发；隐藏且无生产 consumer 的第二套
+client 删除，正式 client 仍由 `bitfun-app-server-client` 拥有。兼容面是已有平铺类型路径、
+method 和 wire shape；旧 server-only inherent/`From` helper 不是版本化公共 SDK，仓内调用已
+迁入 adapter 或稳定 contract 方法。三平台
+`normal,build,dev` 版本化 package instance 去重结果如下：
+
+| TS 导出闭包 | Windows | macOS | Linux |
+|---|---:|---:|---:|
+| 变更前：完整 App Server | 433 | 429 | 437 |
+| 变更后：App Server Protocol | 153 | 159 | 159 |
+| 收敛 | -280 | -270 | -278 |
+
+Web 实际引用的 19 个直接类型及其递归导入闭包保持生成内容字节一致；不再把 95 个历史
+导出文件全部视为兼容面。根 `Cargo.lock` package 集合和版本不变，只从 App Server package
+记录删除不再直接消费的依赖边；`.github`、CI job 和矩阵均不变。
+
+### 3.4 CI 与本地验证
 
 - 现有 CI 已覆盖 workspace check、Core/Desktop lib、平台敏感 owner 测试和独立 runtime/CLI 验证；本轮不新增 job、矩阵或 changed-path 分类器。
 - CI 不负责穷举所有测试；新增验证只有具备独立 owner、平台矩阵或失败归因价值时才进入既有流水线，否则由最近模块的 focused command 维护。
@@ -131,9 +397,15 @@ Plugin Source 由各自 owner 选择，完整产品仍经 `product-full` 显式
 | CI 拓扑 | Rust job 不再等待完整前端构建，自建 Tauri 检查所需资源目录 |
 | 依赖收敛 | Desktop 直接 image 版本和 Reqwest TLS 双栈已治理 |
 | Agent Runtime 闭包 | Core 基线不再暗带具体 capability；完整产品和 CLI 显式保持原能力，ACP 退出未选择闭包 |
+| Core/ACP 默认与角色 | Core 默认 feature 为空；ACP 默认精确保持 client + server，Desktop client-only、CLI 双角色均由现有边界检查锁定 |
+| 重型可选能力 | 文档转换和本地订阅凭据由弱 modifier 细化已有 runtime owner；Core 基线和 App Server 退出未消费闭包 |
 | Installer 闭包 | 删除 8 个未使用直接 dependency；独立 workspace 和发布生命周期不变，本 PR 不提交其生成 lockfile |
-| Agent Runtime 测试 | 28 个 integration executable 已收敛为 5 个职责/平台 target |
+| SDK Host 闭包 | 从 `product-full` 改为与当前协议/构造路径一致的显式 Core owner closure；保留 ring TLS 初始化，本机 SDK 行为不变，未交付的远程执行能力不再进入构建图 |
+| Agent Runtime 测试 | 28 个 integration executable 已完成职责聚合；当前 7 个 target 中，DeepResearch、Hook settings 与 Hook 子进程按 feature/进程失败域独立，其余保持聚合 |
 | Services 测试 | 两个服务 crate 使用显式 target；选中闭包少 8 个 integration executable，进程/feature/external-system 边界保持独立 |
+| External Sources 测试 | 四个 adapter/assembly crate 从 22 个 target 收敛到 7 个；MCP、插件服务和脚本 runtime 继续独立 |
+| Contracts/AI/Assembly 测试 | 五个 crate 从 28 个 target 收敛到 10 个；AI loopback 与纯协议、Product Domains 各 owner feature 保持独立 |
+| 未使用直接依赖 | 删除 CLI/Desktop/Core/MiniApp Market/Page Function 的失效直接边；保留 Syntect 实际 Oniguruma 后端，根 lock 只减 7 个 package |
 
 内置 Agent 内容已经移到无第三方依赖的 `bitfun-agent-content`，减少了 Core build-script 工作；
 但 Core 仍直接依赖该 crate。没有足够产品收益前，不为消除这一编译指纹引入动态 provider、
@@ -147,7 +419,7 @@ Plugin Source 由各自 owner 选择，完整产品仍经 `product-full` 显式
 |---|---|
 | CI 收敛 | 先积累多次相同 owner 的 step wall-clock、cache hit/miss 和失败历史；只有能证明收益且不会静默缩小覆盖时再独立设计 |
 | Desktop 截图后端 | 新候选同时满足三平台行为等价、区域捕获无性能回退、系统依赖可 feature-gate，且根 lock package 不增加 |
-| App Server / Server | 当前改造合入并稳定后，重新锁定最新生产调用链和可信 owner 边界 |
+| App Server / Server | 观察 protocol 单一 schema owner 合入后的 Frontend Build 样本；没有新的生产 owner 或稳定行为收益前，不继续拆 handler 路径 |
 | 其他产品入口重型 capability | 证明入口不消费该能力，具备 typed unsupported/fallback 行为，并能让一个真实重依赖子图退出 |
 | 重复 native/sys 库版本 | 同一 owner 能升级收敛且三平台打包/ABI 有证据；不因版本数字重复强行 patch |
 
diff --git a/docs/plans/core-decomposition-plan.md b/docs/plans/core-decomposition-plan.md
index 9a0f0af315..69faf6c53c 100644
--- a/docs/plans/core-decomposition-plan.md
+++ b/docs/plans/core-decomposition-plan.md
@@ -25,7 +25,7 @@
 | CLI / Desktop / ACP | CLI 与 ACP 已分别提交对应 `DeliveryProfile`、消费 Runtime Parts/SDK，并选择经过评审的 Core owner feature closure；Desktop 仍启用 `bitfun-core/product-full`，主交互已消费由现有 owner 构造的窄口径 SDK 接口 | 三个入口仍复用单一 Core runtime owner；完整 Desktop profile 和剩余兼容操作仍需逐项迁移 |
 | Server | 当前生产路由只形成 health/info/ping 基线 | 没有插件状态或独立产品组装完整流程 |
 | Server / Remote / Web / Mobile Web / SDK profile | 当前为空计划、未接入入口或仅有 preview 测试 | 不得据枚举值宣称产品能力已交付 |
-| Agent Runtime SDK | 已有无 `bitfun-core` 依赖的 v3 preview 接口和 smoke test | 发布边界仍需真实嵌入方证明 |
+| Agent Runtime SDK | 已有无 `bitfun-core` 依赖的 v6 preview 接口和 smoke test | 发布边界仍需真实嵌入方证明 |
 | 插件运行时 | 现有路径只覆盖 BitFun 原生包和 OpenCode custom tool 静态名称预览 | 不能据通用消息结构或静态候选扩张稳定 ABI |
 | Relay | room/device 状态、account/sync 存储、asset store 与 HTTP/WebSocket router 已归属 `services/relay-service`，standalone 与 embedded 入口同向消费；embedded bind、静态 fallback 和任务生命周期由 Desktop 窄宿主端口持有 | Cargo metadata 门禁覆盖 workspace、独立 manifest、normal/build/dev 依赖及 optional/target 变体；宿主归位已完成并由生命周期与边界测试保护 |
 | CLI CI | 独立 Linux job 运行 CLI test，通用三平台 workspace check 覆盖 CLI 编译；Linux PTY 与 Windows ConPTY 有启动页生命周期及本地确定性流式模型夹具驱动的活动 turn 进程测试，发布归档上传前校验 SHA-256 并解压执行 | 参数/序列化/前置失败和组装已有 focused contract；本地模型 HTTP 403 授权拒绝、流中断后的重试失败、Linux PTY/Windows ConPTY Chat resize/取消、`exec` Ctrl+C 及 Patch I/O 失败已有分层回归，真实供应商审批交互、macOS 活动 PTY 与 OS 级终端故障注入仍需补齐 |
@@ -129,7 +129,7 @@ Core 只为插件兼容提供已有 owner 的窄接口：真实工具、类型
 | 文档与仓库边界 | `pnpm run check:repo-hygiene`，`node --test scripts/check-core-boundaries.test.mjs`，`node scripts/check-core-boundaries.mjs` |
 | 入口 profile 迁移 | 对应 app 的 check/test、入口级 smoke、profile/服务可用性断言、旧路径等价用例 |
 | Relay 共享 owner / Cargo 方向 | standalone 与 embedded focused tests、Cargo 依赖方向失败用例、Desktop 宿主启停/失败回滚/静态缓存行为测试 |
-| Agent Runtime / SDK | `cargo test -p bitfun-agent-runtime`，最小 no-`bitfun-core` 嵌入测试 |
+| Agent Runtime / SDK | `cargo test -p bitfun-agent-runtime --no-default-features --features agent-runtime --lib`，最小 no-`bitfun-core` 嵌入测试 |
 | 插件首个执行切片 | runtime ports、`PluginRuntimeClient`、生态 adapter、`ScriptToolRuntime`、Plugin Host 与真实固定 fixture 的端到端调用 |
 | CLI | `cargo check -p bitfun-cli`，`cargo test -p bitfun-cli`，结构化协议和 package smoke |
 
diff --git a/docs/plans/tui-app-server-decoupling-refactor-plan.md b/docs/plans/tui-app-server-decoupling-refactor-plan.md
index dbd5dfc96d..3f0b96f22b 100644
--- a/docs/plans/tui-app-server-decoupling-refactor-plan.md
+++ b/docs/plans/tui-app-server-decoupling-refactor-plan.md
@@ -1,8 +1,8 @@
 # TUI 与 App Server 解耦重构计划
 
-> 状态：Phase 0-4 已完成当前定义的边界、协议基础、核心聊天、配置管理和外部集成接口迁移；Phase 5 Shared App Server 目标待评审。
+> 状态：Phase 0-4 已完成当前定义的边界、协议基础、核心聊天、配置管理和外部集成接口迁移；Phase 5 Embedded direct-runtime 迁移待实现，Shared App Server 目标待评审。
 >
-> 当前状态基线：2026-08-09。一次性的运行证据保留在对应 PR/Actions 记录中；本文不绑定会因 rebase 失效的提交 SHA。
+> 当前状态基线：2026-08-13。一次性的运行证据保留在对应 PR/Actions 记录中；本文不绑定会因 rebase 失效的提交 SHA。
 >
 > 本文只记录当前差距、阶段和完成证据。稳定架构约束见相邻架构文档；Phase 0 的历史盘点已失效，不再作为当前能力清单。
 
@@ -18,8 +18,8 @@
 本计划只迁移交互式 TUI 的产品后端调用：
 
 1. TUI 保留终端输入、状态、渲染和 controller-local effect。
-2. TUI 通过 app-local `TuiBackend` 使用产品后端，不直接依赖 Core、Runtime 实现、Service、全局 singleton 或私有 IPC operation。
-3. Embedded TUI 使用 `AppServerTuiBackend`；Shared TUI 在 Shared App Server 交付前使用 `SharedTuiBackend` compatibility adapter。
+2. TUI 当前通过 app-local `TuiBackend` 使用产品后端；Phase 5 再把它拆成 Runtime port 与按 domain 注入的管理接口。`TuiAgentClient` 不直接依赖 Core、Runtime 实现、具体 Service、全局 singleton 或私有 IPC operation；view/reducer 也不执行 backend I/O。
+3. Embedded TUI 当前使用 `AppServerTuiBackend`；Shared TUI 当前使用 `SharedTuiBackend` 映射 private Runtime IPC v17。Phase 5 才引入 `TuiRuntimePort`、`DirectRuntimeTuiRuntime` 和 Shared IPC Runtime adapter，并把管理用例移到 backend composition 的 owner service/provider 接口。
 4. App Server 只适配稳定合同，不接管 Runtime、Service 或 Product Domain 的业务所有权。
 5. Headless `exec`、ACP、Peer Host 和公开 SDK 保留各自经评审的 adapter。
 
@@ -38,7 +38,7 @@
 当前 head 有两条交互式 TUI 后端路径：
 
 ```text
-Embedded TUI
+Embedded TUI（当前）
   -> TuiAgentClient
   -> TuiBackend
   -> AppServerTuiBackend
@@ -56,62 +56,93 @@ Shared TUI (--shared)
   -> Runtime API / owners
 ```
 
-两条路径统一的是 TUI 可见的行为端口。Shared compatibility adapter 会把 Runtime IPC 的结果和事件映射为 `TuiBackend` 使用的类型，但它没有运行 `BitfunAppServer`，也不是 Shared App Server transport。
+当前两条路径共用的是包含 Runtime 与管理方法的单体 `TuiBackend`。`AppServerTuiBackend`
+把 Embedded 请求委托给 App Server client；`SharedTuiBackend` 把 Session/chat 请求映射到
+private Runtime IPC v17，并直接持有具体 `AppManagementService` 承接 Host-local 管理能力。
+Phase 3/4 已让 controller 使用 typed backend API，不代表 Phase 5 的 port 拆分或 adapter 接线已经完成。
 
-Phase 3 已将 Mode/Model、Skill、Subagent 和 MCP 管理面迁移到 `TuiBackend` 的 owner-specific typed API。Phase 4 进一步迁移了 External Source、native/external Hook、Account、Settings Sync 和 Worktree 管理面。具体 DTO/owner 适配由 App Server 的 `AppManagementService` 持有，并由 Host 显式装配；Embedded TUI 经 App Server 访问既有 owner，TUI controller 不再直接访问这些 compatibility owner。
+### 2.2 Approved Embedded target
 
-Shared 的 Session/chat/mode authority 继续映射 v17；Host 实际提供的本机管理 capability 由 `SharedTuiBackend` 委托同一个具体 management service。当前 Shared Host 提供 Phase 4 的 External Source V1 和 Hook 管理，但不注入 Account/Settings Sync 或 Worktree owner；这些能力返回 typed unsupported。Remote workspace 对所有 controller-local management capability fail closed，不回落到控制端本机。Phase 4 完成表示接口边界已迁移，不表示所有 deployment 的 capability 完全相同。Phase 4 之后新增的 External Application V2 控制面目前只在 Embedded App Server 接线，Shared Runtime 明确 unsupported，不重新打开 Phase 4 的旧 owner 直连预算。
+Phase 5 将当前单体 backend 拆成下面的 app-local composition：
 
-### 2.2 Proposed target
+```text
+TuiAgentClient
+  -> TuiBackend composition
+     -> TuiRuntimePort
+        -> DirectRuntimeTuiRuntime
+        -> SharedIpcTuiRuntime
+     -> owner-owned service/provider interfaces (management only)
+```
+
+这是已批准但尚未交付的 Phase 5 目标。`TuiRuntimePort` 将只覆盖 Embedded 和 Shared
+都需要、且当前 private Runtime IPC v17 已经承载的 Runtime 行为：initialize/health、
+Session、Turn、Permission/UserInput、shell、compact/undo/redo/reload、usage/settlement、
+workspace reference/diff、lineage、fork、当前 Session 的 model/mode 更新、agent mode
+catalog 和事件订阅。Phase 5 完成后，`DirectRuntimeTuiRuntime` 将 direct Runtime 映射到
+该 port，Shared IPC adapter 将 v17 的结果和事件映射到同一组 TUI semantic types；后者
+不运行 `BitfunAppServer`，也不是 Shared App Server transport。
+
+Model catalog/CRUD、Skill、Subagent、MCP、Account、Settings Sync、Worktree、External
+Source 和 Hook 不因为被 TUI 使用就进入 `TuiRuntimePort`，也不需要一个总括性的
+`TuiManagementPort`。backend composition 按 domain 注入各 owner 已有的稳定 service/provider
+trait；Embedded 直接使用同进程 owner service，Shared 使用 Host-local service/provider
+adapter。只有原始 service 接口暴露内部类型、无法表达 TUI 所需的权限/上下文/unsupported，
+或需要跨部署稳定 DTO 时，才在 owning crate 或 adapter 内增加最薄的 facade。不得把
+`AppManagementService` 整体搬入 direct adapter，也不得让 controller/view 直接依赖具体
+service 实现。缺少 provider 的 Shared/Remote 场景返回 typed unsupported，禁止静默回落控制端本机。
+
+Phase 3 已将 Mode/Model、Skill、Subagent 和 MCP 管理面迁移到 TUI-facing typed API。Phase 4 进一步迁移了 External Source、native/external Hook、Account、Settings Sync 和 Worktree 管理面。当前这些方法仍位于单体 `TuiBackend`；Embedded 经 App Server 的 `AppManagementService` wiring 调用 owner，Shared 则由 `SharedTuiBackend` 委托其持有的具体 `AppManagementService`。Phase 5 将按 owner 归属把管理用例拆到 service/provider 接口，不建立管理总接口；TUI controller 仍不直接访问 compatibility owner。
+
+Phase 5 中，`DirectRuntimeTuiRuntime` 将实现 `TuiRuntimePort`，可以依赖 Rust Runtime SDK 暴露的稳定 typed facade，但不得把 Runtime 内部类型、Core singleton 或事件队列 owner 暴露给 TUI。管理面 backend 可以直接调用 owner-owned 的稳定 service/provider trait；若该接口暴露内部类型，或需要 TUI-specific DTO、权限、上下文和 capability 裁剪，才在 owning crate 抽取薄 facade。不得把 `AppManagementService` 原样搬到 CLI，也不得由 direct adapter 复制其业务状态或策略。
+
+当前 Shared 的 Session/chat/mode authority 由 `SharedTuiBackend` 映射 v17；Phase 5 完成后才由 Shared IPC Runtime adapter 实现 `TuiRuntimePort`。Host 实际提供的本机管理 capability 当前由 `SharedTuiBackend` 委托具体 `AppManagementService`，Phase 5 再改为 backend composition 按 domain 调用 Host-local service/provider adapter。当前 Shared Host 提供 Phase 4 的 External Source V1 和 Hook 管理，但不注入 Account/Settings Sync 或 Worktree owner；这些能力返回 typed unsupported。Remote workspace 对所有 controller-local management capability fail closed，不回落到控制端本机。Phase 4 完成表示 typed API 和 wiring 已迁移，不表示所有 deployment 的 capability 完全相同，也不表示 Phase 5 已完成。Phase 4 之后新增的 External Application V2 控制面目前只在 Embedded App Server 接线，Shared Runtime 明确 unsupported，不重新打开 Phase 4 的旧 owner 直连预算。
 
-若 [App Server 目标架构](../architecture/app-server-architecture.md) 通过评审，交互式 Rich Client 的目标路径为：
+### 2.3 Optional Shared App Server proposal
+
+Web 当前继续通过自己的 loopback WebSocket App Server 入口，不经过 TUI composition：
 
 ```text
-TUI renderer / input / state / local effects
-                    |
-                    v
-              TuiBackend trait
-                    |
-                    v
-          AppServerTuiBackend adapter
-                    |
-                    v
-              AppServerClient
-                    |
-         Host-selected transport
-          /                     \
- in-memory Embedded       controlled Shared local
-          \                     /
-                    v
-               App Server
-                    |
-                    v
- Runtime API / Services / Product Domain owners
+Web UI -> Web Host -> loopback WebSocket App Server
+       -> Runtime API / owner ports
+
+Shared Rich Client（Phase 6 candidate）
+  -> AppServerClient
+  -> candidate private Pipe / UDS
+  -> Shared App Server Host
+  -> Runtime API / owner ports
 ```
 
-Shared Runtime IPC v17 在 Shared App Server 的鉴权、实例身份、controller/lease、事件恢复、断连取消、`outcome_unknown`、frame 限制和空闲退出达到行为等价前继续保留。是否最终删除 v17 由等价测试、性能数据、真实 Rich Client 消费方和回滚证据决定，不能只依据 schema 相同或 adapter 已存在。
+Shared App Server 仍是 Phase 6 待评审提案，不是 Phase 5 的既定结果。Private Runtime IPC
+v17 在候选 transport 的鉴权、实例身份、controller/lease、事件恢复、断连取消、
+`outcome_unknown`、frame 限制和空闲退出达到行为等价前继续保留；评审也可以决定长期保留
+v17。Embedded direct-runtime 不替换 v17，也不要求 direct facade 与 wire DTO 相同；两者只需
+满足同一行为合同。
 
 ## 3. 当前能力矩阵
 
 状态定义：
 
 - **已交付**：生产 handler/client 已接线，并被当前 Embedded TUI 路径使用。
-- **兼容映射**：Shared TUI 通过 Runtime IPC v17 和 `SharedTuiBackend` 提供等价 TUI 用例，但没有经过 App Server wire。
+- **兼容映射**：Shared TUI 通过 Runtime IPC v17 和 `SharedTuiBackend` 提供与 Embedded 对照的 TUI Runtime 用例，但没有经过 App Server wire。
 - **部分交付**：已有合同或 handler，但 Host 能力、恢复、安全或 TUI 调用路径仍不完整。
 - **未迁移**：当前 TUI 仍使用既有 compatibility owner 路径，或尚无生产接口。
 - **本地保留**：属于 TUI 或 controller-local effect，不迁移。
 
+本矩阵的 Embedded 列记录 Phase 5 之前的 App Server 基线。Phase 5 完成后，Runtime 用例由
+`DirectRuntimeTuiRuntime` 调用 Runtime typed facade；管理用例由 backend composition 调用
+对应 owner service/provider。表中的行为合同和 Shared 对照场景保持不变。
+
 ### 3.1 核心聊天与 Session
 
 | TUI 用例 | Embedded App Server | Shared v17 compatibility | 当前结论 |
 | --- | --- | --- | --- |
 | 初始化、版本、健康 | `app/initialize`、`app/health` | adapter 根据 v17 握手结果合成 TUI-facing initialize/health | Embedded 已交付；Shared 尚不是 App Server connection |
 | Agent、Permission 事件 | `agent/event`、`agent/permissionEvent` | IPC 事件桥映射为 `AppServerEvent` | 两边均可驱动当前核心 TUI；底层恢复合同不同 |
-| Config 事件 | `config/event` | 当前 Shared bridge 不投影 Config 事件 | Embedded 已接线；Shared 的 TUI-facing 管理 capability 来自 Host 装配的 App Server management service，不代表 v17 已有 Config 事件 |
+| Config 事件 | `config/event` | 当前 Shared bridge 不投影 Config 事件 | Embedded 已接线；Shared 的 TUI-facing 管理 capability 当前由 `SharedTuiBackend` 委托其具体 `AppManagementService`，不代表 v17 已有 Config 事件；Phase 5 再拆成 owner service/provider adapter |
 | 流失效与重同步 | `app/eventStreamState`、`app/syncEvents`、`session/sync` | adapter 投影 connection-local cursor、invalidation/resync 和 closed | 已有连接内 cursor/sync；没有跨连接持久 replay/resume |
 | Session list/create/sync | `agent/listSessions`、`agent/createSession`、`session/sync` | list/create/atomic restore operation | 已交付；sync 包含 Runtime 状态、transcript、workspace binding 和 pending Permission |
 | Session delete/rename/fork | typed App Server methods | v17 controller-scoped operations | 已交付或兼容映射；Shared 继续执行 controller/idle 规则 |
-| Model/mode update | `session/updateModel`、`session/updateMode` | v17 current-controller operations | Session update wire 已覆盖；Embedded 与 Shared 都经 typed 管理 API 取得目录/defaults，Shared 的目录来自 Host 装配的 App Server management service |
+| Model/mode update | `session/updateModel`、`session/updateMode` | v17 current-controller operations | Session update wire 已覆盖；当前 Embedded 经 `AppServerTuiBackend` 提交，Shared 经 `SharedTuiBackend -> Runtime IPC v17` 提交；Phase 5 完成后再分别由 Direct/Shared Runtime adapter 实现 `TuiRuntimePort` |
 | Submit/cancel/steer | typed Agent methods | v17 Turn operations | 已交付或兼容映射 |
 | User Shell/UserInput | `agent/runUserShellCommand`、`agent/submitUserAnswers` | v17 typed operations | 已交付或兼容映射；执行和权限仍由 Runtime owner 持有 |
 | Permission pending/respond | typed Permission methods/events | v17 pending/respond and event stream | 已交付或兼容映射 |
@@ -131,14 +162,14 @@ Shared Runtime IPC v17 在 Shared App Server 的鉴权、实例身份、controll
 
 | Domain | 当前状态 | 当前结论 / 后续 |
 | --- | --- | --- |
-| Mode/Model 管理 | Embedded 经 typed mode catalog 和 model list/get/add/update/delete/default API；read DTO 只含 secret configured metadata，mutation 使用 preserve/replace/clear | Phase 3 已完成；Shared mode catalog 来自 Runtime Host，model 管理由 Host 装配的 App Server management service 转发，Session model mutation 仍由 v17 owner 提交 |
-| Skill/Subagent | TUI 经 typed list/toggle API 消费 visible/manageable read model；App Server management service 委托既有 registry owner | Phase 3 已完成；Embedded 与 Shared 共用具体 service，Shared capability 明确属于本机 CLI compatibility scope |
-| MCP | 当前 TUI 用例经 typed catalog/status/toggle/add/delete/external decision/conflict API；read projection 与 Debug 输出不暴露凭据 | Phase 3 已完成当前定义；Shared 通过当前 CLI 进程的本地 MCP compatibility service 保留迁移前管理行为。该 service 的 MCP 进程状态和 tool registry 不会即时重配已经运行的 Shared Runtime Host；要取得 Host 侧新状态仍需显式的同步/restart contract，不能把本地 toggle 描述成 v17 远端控制 |
-| External Source/Tool/Command/Agent | TUI 经 typed snapshot/control/review、conflict choice、command expansion 和事件接口消费既有 owner；后续 External Application V2 snapshot/review/action 已在 Embedded 接线 | Phase 4 当前定义已完成；Shared 保留 V1 本机 compatibility，V2 明确 unsupported，Remote 不回落本机 |
-| Hooks | TUI 经 typed native overview 与 external snapshot/plan/apply/mutate API 消费既有 owner | Phase 4 已完成；native user hooks、compiled-in `post_call_hooks` 和 external hook catalog 继续分离，Remote 明确 unsupported |
+| Mode/Model 管理 | Embedded App Server 提供 typed mode catalog 和 model list/get/add/update/delete/default API；read DTO 只含 secret configured metadata，mutation 使用 preserve/replace/clear | Phase 3 已完成 typed API 与 wiring；Shared mode catalog 来自 Runtime Host，model 目录/管理由 `SharedTuiBackend` 持有的具体 `AppManagementService` 提供，Session model mutation 由 `SharedTuiBackend` 提交给 v17 owner；Phase 5 再拆分 owner service/provider 与 Runtime port |
+| Skill/Subagent | 当前 `TuiBackend` 提供 typed list/toggle API 和 visible/manageable read model；Embedded 经 App Server wiring，Shared 由 `SharedTuiBackend` 委托其具体 `AppManagementService` | Phase 3 已完成 typed API 与 wiring；Shared capability 明确属于本机 CLI compatibility scope，Phase 5 再拆成 owner service/provider adapter |
+| MCP | 当前 `TuiBackend` 提供 typed catalog/status/toggle/add/delete/external decision/conflict API；read projection 与 Debug 输出不暴露凭据 | Phase 3 已完成当前定义；Shared 由 `SharedTuiBackend` 委托当前 CLI 进程的具体 `AppManagementService`，以本地 MCP compatibility service 保留迁移前管理行为。该 service 的 MCP 进程状态和 tool registry 不会即时重配已经运行的 Shared Runtime Host；要取得 Host 侧新状态仍需显式的同步/restart contract，不能把本地 toggle 描述成 v17 远端控制 |
+| External Source/Tool/Command/Agent | 当前 `TuiBackend` 提供 typed snapshot/control/review、conflict choice、command expansion 和事件接口；Embedded 经 App Server wiring，Shared V1 由 `SharedTuiBackend` 委托其具体 `AppManagementService` | Phase 4 当前定义已完成；Shared 保留 V1 本机 compatibility，V2 明确 unsupported，Remote 不回落本机；Phase 5 再拆成 owner service/provider adapter |
+| Hooks | 当前 `TuiBackend` 提供 typed native overview 与 external snapshot/plan/apply/mutate API；Embedded 经 App Server wiring，Shared 由 `SharedTuiBackend` 委托其具体 `AppManagementService` | Phase 4 已完成 typed API 与 wiring；native user hooks、compiled-in `post_call_hooks` 和 external hook catalog 继续分离，Remote 明确 unsupported；Phase 5 再拆成 owner service/provider adapter |
 | Account/Settings Sync | typed snapshot/login/finalize/logout 与 sync start/snapshot/cancel/local-changed 已接线；凭据不进入 read model 或 Debug 输出 | Phase 4 接口迁移已完成；Embedded Host 注入共享 `AccountRuntime`，App Server 直接做 domain-to-wire 适配；当前 Shared Host 未注入并返回 typed unsupported |
 | Worktree | typed repository status、bind/release 和 operation identity 已接线 | Phase 4 接口迁移已完成；Embedded Host 注入 Worktree owner，当前 Shared Host 与 Remote workspace 明确 unsupported |
-| Desktop/Web Host 安全 | WebSocket Host 仅为 loopback 单用户；Desktop 尚未迁移为 App Server Host | Host allowlist、身份/作用域、真实 limits 与平台 capability provider |
+| Desktop/Web Host 安全 | WebSocket Host 仅为 loopback 单用户；Desktop 当前仍使用 Tauri adapter，独立 direct Runtime 迁移尚未实施 | Host allowlist、身份/作用域、真实 limits 与平台 capability provider |
 
 ### 3.4 本地保留
 
@@ -164,7 +195,7 @@ Shared Runtime IPC v17 在 Shared App Server 的鉴权、实例身份、controll
 | `src/crates/interfaces/app-server-protocol` | behavior-light method、DTO、wire error、event envelope 和角色定义 |
 | `src/crates/interfaces/app-server-client` | 类型化请求、事件分发和 host-supplied transport 抽象 |
 | `src/crates/interfaces/app-server` | server 生命周期、生产 handler 注册、Runtime/domain 与 wire 转换、错误映射 |
-| `src/apps/cli` | `TuiBackend`、Embedded/Shared adapter 选择、transport 和进程生命周期、TUI-local effect |
+| `src/apps/cli` | 当前拥有 `TuiAgentClient`、单体 `TuiBackend`、`AppServerTuiBackend`、`SharedTuiBackend`、transport 和进程生命周期、TUI-local effect；Phase 5 再引入 Runtime port 与按 domain 注入的 owner service/provider composition |
 | Runtime/Service/Product Domain owners | Session、Turn、Permission、Workspace、配置和其他业务权威事实 |
 
 边界规则：
@@ -173,6 +204,10 @@ Shared Runtime IPC v17 在 Shared App Server 的鉴权、实例身份、controll
 - `bitfun-app-server` 可依赖生产 handler 所需的明确 owner feature，但禁止选择 `bitfun-core/product-full`。
 - Host 负责 transport、认证、作用域、真实 capability/limits、平台能力和进程生命周期。
 - handler 只做合同校验、DTO 转换和错误映射，不持有第二份业务权威状态。
+- Phase 5 引入的 `TuiRuntimePort` 只抽取 Embedded/Shared 共同需要的 Runtime 行为；不定义总括性的 `TuiManagementPort`。
+- Phase 5 将管理面按 domain 拆到 owner-owned 的稳定 service/provider trait；只有需要 DTO、权限/上下文
+  适配或 capability 裁剪时才增加薄 facade，不能把具体 service 实现或 `AppManagementService`
+  整体暴露给 TUI。
 - DTO 提取不代表 Runtime owner 迁移。
 
 ## 5. 分阶段状态
@@ -183,17 +218,18 @@ Shared Runtime IPC v17 在 Shared App Server 的鉴权、实例身份、controll
 | --- | --- | --- | --- | --- |
 | Phase 0：边界 | `TuiBackend`、behavior-light protocol/client crate、source/Cargo guard 已建立 | Core boundary tests 和 dependency checks | 已完成 | [PR #2034 checks](https://github.com/GCWing/BitFun/pull/2034/checks) |
 | Phase 1：协议基础 | initialize/health、typed events、connection-local cursor、resync、稳定错误和 Embedded connection 已接线 | App Server protocol/client/server focused tests | 已完成 | [PR #2034 checks](https://github.com/GCWing/BitFun/pull/2034/checks) |
-| Phase 2：核心聊天 | Embedded 核心用例经 App Server；Shared 经同一 `TuiBackend` 映射 v17；TUI 核心不引用 Runtime SDK/IPC operation | CLI、App Server、Runtime IPC 和 boundary focused tests | 已完成当前定义 | [PR #2034 checks](https://github.com/GCWing/BitFun/pull/2034/checks) |
+| Phase 2：核心聊天（旧路径） | Embedded 核心用例经 App Server；Shared 经同一 `TuiBackend` 映射 v17；TUI 核心不引用 Runtime SDK/IPC operation | CLI、App Server、Runtime IPC 和 boundary focused tests | 已完成当前定义，作为迁移基线 | [PR #2034 checks](https://github.com/GCWing/BitFun/pull/2034/checks) |
 | Phase 3：配置管理 | TUI controller 不再访问 config/registry/MCP compatibility owner；secret-safe typed APIs 完成，CLI Host adapter 可保留显式 compatibility forwarding | owner tests、App Server contract tests、CLI behavior tests | 已完成当前定义 | 本变更的 protocol/client/server/CLI focused tests 与 Core boundary checks |
 | Phase 4：外部集成 | External Source、Hook、Account、Settings Sync、Worktree 管理面经 typed backend；remote 不回落本机 | owner/remote/security contract tests | 已完成当前定义 | [PR #2146 checks](https://github.com/GCWing/BitFun/pull/2146/checks)、zero-budget contract 与 Core boundary checks |
-| Phase 5：Shared App Server | Shared Host 达到 v17 治理等价，opt-in 双栈验证完成，并有回滚与删除证据 | 跨 transport parity、故障、性能和安全测试 | 未开始，目标待评审 | - |
+| Phase 5：Embedded direct-runtime | `TuiRuntimePort` 与 owner service/provider 接入边界拆分完成；Embedded TUI 删除 App Server client/server 与 in-memory transport，改用 direct Runtime adapter；管理面不进入 Shared IPC，旧路径随切换删除 | Runtime port 对 Shared v17 operation 的覆盖测试；direct-runtime 与 Shared v17 的 Runtime 行为测试；各管理 service/provider 的 capability/unsupported 测试 | 待实现 | - |
+| Phase 6：Shared App Server | Shared Host 达到 v17 治理等价，opt-in 双栈验证完成，并有回滚与删除证据 | 跨 transport parity、故障、性能和安全测试 | 未开始，目标待评审 | - |
 
 ### 5.1 Phase 0-2 已交付摘要
 
-- `TuiAgentClient`、Startup 和 `ChatMode` 只消费 app-local `TuiBackend`。
-- Embedded Host 在专用 OS 线程的 current-thread Tokio runtime + `LocalSet` 中运行 private `BitfunAppServer`，TUI 保持在原多线程 runtime。
-- `AppServerTuiBackend` 通过正式 `AppServerClient` 和 in-memory transport 完成核心用例。
-- `SharedTuiBackend` 将相同用例映射到 private Runtime IPC v17；TUI client/controller 不引用 IPC operation。
+- `TuiAgentClient`、Startup 和 `ChatMode` 只消费 app-local `TuiBackend`；Runtime 调用和管理调用均不下沉到 view/reducer。
+- Embedded Host 当前在专用 OS 线程的 current-thread Tokio runtime + `LocalSet` 中运行 private `BitfunAppServer`，TUI 保持在原多线程 runtime；这是 direct-runtime 迁移前的基线。
+- `AppServerTuiBackend` 通过正式 `AppServerClient` 和 in-memory transport 完成核心用例，后续由 direct Runtime composition 替换。
+- `SharedTuiBackend` 将相同 Runtime 行为映射到 private Runtime IPC v17；TUI client/controller 不引用 IPC operation。将这些方法抽取为 Runtime port 属于 Phase 5。
 - App Server 核心 handler 覆盖 sync、turn、Permission、revert、context、usage、settlement、Workspace 和 lineage；Config 事件也已在 Embedded connection 接线。
 - Runtime IPC v17 为当前 parity 增加 restore Runtime 状态、usage、settlement 和本地命令 transcript 记录；没有增加 replay、observer、通用 controller transfer 或公开 SDK 能力。
 - capability 声明列出当前注册方法，但 Host-specific availability 和方向性 limits 仍是后续收紧项。
@@ -215,8 +251,8 @@ Shared Runtime IPC v17 在 Shared App Server 的鉴权、实例身份、controll
 
 - `app-server-protocol` 提供 Mode、Model、Skill、Subagent 和 MCP 的 owner-specific DTO 与 method；model read model 不返回 secret 值，model mutation 使用 preserve/replace/clear 语义。
 - App Server 由 Host 显式注入具体 `AppManagementService`，按 `tui.modes`、`tui.models`、`tui.skills`、`tui.subagents` 和 `tui.mcp` 发布真实 availability；service 缺失或 unavailable 时返回带 capability id 的 structured unsupported。
-- `AppManagementService` 位于 App Server server wiring，复用现有 config、registry、MCP 和 external-source owner，不成为第二个业务 owner；Startup 与 Chat controller 只经 `TuiAgentClient -> TuiBackend` 调用这些管理用例。
-- `SharedTuiBackend` 继续映射 v17 mode catalog，并将 Model、Skill、Subagent 和 MCP 管理委托 Host 装配的具体 App Server management service。v17 不承载这些目录、CRUD 或 defaults；Shared 发布的是 adapter-scoped 本地 capability，current-Session model update 仍按 v17 controller/idle/outcome-unknown 合同提交给 Runtime Host。Shared MCP service 的运行态只属于当前 CLI 进程，不宣称可以即时控制已经运行的 Shared Runtime Host。
+- `AppManagementService` 位于 App Server server wiring，复用现有 config、registry、MCP 和 external-source owner，不成为第二个业务 owner；Startup 与 Chat controller 只调用 `TuiBackend` 的 typed 方法。Phase 5 才把这些方法按 domain 拆到 owner service/provider，且不会建立 direct TUI 的总管理接口。
+- `SharedTuiBackend` 继续映射 v17 mode catalog，并将 Model、Skill、Subagent 和 MCP 管理委托其持有的具体 `AppManagementService`。v17 不承载这些目录、CRUD 或 defaults；Shared 发布的是 adapter-scoped 本地 capability，current-Session model update 仍按 v17 的 controller/idle/outcome-unknown 合同提交给 Runtime Host。Phase 5 再以 owner service/provider adapter 和 Shared IPC Runtime adapter 替换这段单体 wiring。Shared MCP service 的运行态只属于当前 CLI 进程，不宣称可以即时控制已经运行的 Shared Runtime Host。
 - Core boundary budgets 已移除 Phase 3 owner 直连债务，并要求 Startup 的 Subagent 管理继续使用 typed backend。
 
 ### 5.3 Phase 4
@@ -235,14 +271,23 @@ Shared Runtime IPC v17 在 Shared App Server 的鉴权、实例身份、controll
 交付摘要：
 
 - `app-server-protocol`、client 和 production handlers 已提供 External Source、native/external Hook、Account、Settings Sync 与 Worktree 的 owner-specific typed API；side-effecting 请求使用 operation identity，External Source 与 Hook mutation 保留 owner revision/stale 合同，Settings Sync 提供显式取消与 snapshot。
-- `TuiAgentClient`、Startup 和 Chat controller 只经 `TuiBackend` 调用这些用例。Phase 4 涉及的 `bitfun_core`、account/account-sync compatibility marker 已从 controller 文件移除，对应 Core boundary budget 固定为零。
+- `TuiAgentClient`、Startup 和 Chat controller 只经单体 `TuiBackend` 的 typed API 调用这些用例；Embedded 由 `AppServerTuiBackend` 委托 App Server wiring，Shared 由 `SharedTuiBackend` 委托 v17 或其具体 `AppManagementService`。Phase 4 涉及的 `bitfun_core`、account/account-sync compatibility marker 已从 controller 文件移除，对应 Core boundary budget 固定为零；Runtime port 与按 domain 的 management composition 仍留给 Phase 5。
 - Embedded Host 显式注入共享 `AccountRuntime` 并启用 App Server 内建的本机 Worktree 映射；App Server management service 直接适配 owner，不定义 `AccountManagementHost` 或持有第二份账户、同步、外部来源、Hook、Worktree 权威状态。CLI 的窄 `AccountRuntimeHost` 只实现 daemon、Relay/Peer 路由宿主效果，Session 备份通过独立端口读取 Agent Runtime compatibility owner。
 - Shared adapter 只发布 Host 实际可用的 capability。External Source V1 与 Hook 管理可使用当前本机 compatibility service；Account/Settings Sync、Worktree、Remote workspace 和后续未接线的 External Application V2 返回 typed unsupported，不静默回落本机。
-- Phase 4 未扩展 private Runtime IPC v17，也未改变 Phase 5 的评审门槛。
+- Phase 4 未扩展 private Runtime IPC v17，也未改变 Phase 6 的 Shared transport 评审门槛。
 
 ### 5.4 Phase 5
 
-Phase 5 不以“删除 v17”为起点。建议顺序：
+Embedded direct-runtime Phase 5 建议顺序：
+
+1. 按当前 Shared IPC v17 operation 集合冻结窄 `TuiRuntimePort`，定义统一的 TUI semantic request/result/event/error；direct facade 与 v17 wire 不要求共享 DTO。
+2. 将当前包含 Runtime 和管理面方法的单体 `TuiBackend` 拆为 backend composition：Runtime 调用进入 `TuiRuntimePort`，Model/Skill/Subagent/MCP/Account/Settings/Worktree/External Source/Hook 按 domain 进入各自 owner service/provider 接口；不创建 `TuiManagementPort` 总接口。
+3. 逐项检查管理 service 的暴露面：能直接复用稳定 owner-owned trait 的直接注入；暴露内部类型或需要 TUI DTO、权限/上下文、capability 裁剪的，才抽取最薄 facade。`AppManagementService` 仅保留为 App Server wiring，不原样迁入 CLI。
+4. 为 `DirectRuntimeTuiRuntime` 和 Shared IPC adapter 实现 Runtime port；再将 Embedded Host 从 `EmbeddedAppServerHost` 切换为 direct Runtime Host，删除 in-memory transport、App Server thread 和 initialize/health wire handshake。
+5. 按 Chat、Session、Permission/UserInput、Workspace、Config/Management 垂直切片迁移并验证事件订阅、pending Permission、取消、unknown outcome、workspace/execution binding、错误映射和 Host shutdown 回收。
+6. 完成 direct Runtime 的性能、升级兼容和跨入口行为验证后删除旧 App Server；不保留 rollback adapter，direct adapter 不支持的能力必须返回 typed unsupported。
+
+Shared App Server Phase 6 不以“删除 v17”为起点。建议顺序：
 
 1. 在 Shared Host 中增加默认关闭的 App Server local transport。
 2. 两条 transport 复用同一 Host-scoped connection authority、controller registry、Session 事件过滤、operation identity/deadline/cancel 和未知结果登记。
@@ -278,19 +323,19 @@ Phase 0-2 的具体命令结果和 CI 状态保留在 [PR #2034 checks](https://
 | Workspace | binding、references、diff、remote facts |
 | Lineage | tree、descendant transcript、settlement、targeted cancellation |
 | Failure | unsupported、lag、invalidated、disconnect、deadline、`outcome_unknown` |
-| Deployment | Embedded App Server 与 Shared v17 compatibility 的 TUI behavior parity |
+| Deployment | 当前覆盖 Embedded App Server 与 Shared v17 compatibility；Phase 5 切换到 direct-runtime 并删除旧 Embedded App Server |
 
-Shared App Server 实现后，同一 fixture 必须增加 Embedded App Server、Shared App Server 和 v17 rollback 三方验证，直到 v17 被正式保留或删除。
+Embedded direct-runtime 实现后，同一 fixture 必须覆盖 direct Runtime 和 Shared v17；迁移前可用旧 Embedded App Server 建立基线，但不维护第三条回滚路径。Shared App Server 实现后再增加候选 transport 路径。
 
 ## 7. 完成定义
 
 只有同时满足以下条件，才能宣布 TUI/App Server 解耦完成：
 
-1. Phase 3/4 当前定义的管理面已迁移；后续新增 capability 也不得绕过 `TuiBackend` 或恢复旧 owner 直连。
-2. TUI 产品请求和订阅只经过 `TuiBackend`，TUI view/reducer 不执行 backend I/O。
-3. protocol/client 和 TUI-facing 依赖闭包不包含 Core、Runtime/Service 实现、`product-full` 或 private IPC operation。
-4. capability、limits、身份和作用域来自真实 Host/transport，而不是通用 protocol 默认值。
-5. 事件、断线、恢复、权限、取消和 unknown outcome 有明确合同与故障测试。
+1. Phase 3/4 当前定义的管理面已迁移；Phase 5 direct-runtime 已完成；后续新增 capability 也不得绕过 backend composition 或恢复旧 owner 直连。
+2. TUI 产品请求和订阅经过 `TuiAgentClient` 的 backend composition；Runtime 行为经过 `TuiRuntimePort`，管理能力经过对应 owner service/provider，TUI view/reducer 不执行 backend I/O。
+3. protocol/client 和 TUI-facing 依赖闭包不包含 Core、Runtime/Service 实现、`product-full` 或 private IPC operation；只有 CLI Host/backend composition 可以按 owner 注入已审核的 service/provider。
+4. capability、limits、身份和作用域来自真实 Host/transport，而不是通用 protocol 默认值；管理 service/provider 缺失时返回 typed unsupported。
+5. 事件、断线、恢复、权限、取消和 unknown outcome 有明确合同与故障测试；Runtime port 的每个 Shared v17 operation 都有对应覆盖证据。
 6. remote workspace 不存在 controller-local fallback。
-7. 重复 DTO、无效 handler 和无生产消费方的旁路已删除。
-8. 若采用 Shared App Server，迁移满足 Phase 5 的双栈、回滚、性能、安全和删除门槛；否则文档明确 v17 是保留的私有 compatibility transport。
+7. 重复 DTO、无效 handler、70 方法单体管理 trait 和无生产消费方的旁路已删除或不再属于稳定边界。
+8. 旧 Embedded App Server 已删除且不再作为 rollback adapter；若采用 Shared App Server，迁移满足 Phase 6 的双栈、回滚、性能、安全和删除门槛；否则文档明确 v17 是保留的私有 compatibility transport。
diff --git a/package-lock.json b/package-lock.json
index cbf6d89c91..6391fa184c 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "BitFun",
-  "version": "0.2.17",
+  "version": "0.2.18",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "BitFun",
-      "version": "0.2.17",
+      "version": "0.2.18",
       "hasInstallScript": true,
       "dependencies": {
         "jszip": "^3.10.1",
diff --git a/package.json b/package.json
index 0db6d92f86..75de5e8667 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "BitFun",
   "private": true,
-  "version": "0.2.17",
+  "version": "0.2.18",
   "type": "module",
   "engines": {
     "node": ">=22.12.0"
@@ -36,8 +36,11 @@
     "theme:color-audit:cli": "node scripts/audit-cli-theme-colors.mjs",
     "theme:color-audit:all": "pnpm run theme:color-audit && pnpm run theme:color-audit:mobile && pnpm run theme:color-audit:installer && pnpm run theme:color-audit:cli",
     "theme:color-audit:test": "node --test scripts/audit-theme-colors.test.mjs scripts/audit-cli-theme-colors.test.mjs",
+    "motion:audit": "node scripts/audit-web-motion.mjs",
     "theme:visual-contract": "node scripts/validate-theme-visual-contract.mjs",
     "appearance:contract-audit": "node scripts/audit-appearance-contracts.mjs",
+    "flowchat:log:analyze": "node scripts/diagnostics/analyze-flowchat-log.mjs",
+    "flowchat:log:analyze:test": "node --test scripts/diagnostics/analyze-flowchat-log.test.mjs",
     "check:repo-hygiene": "node scripts/check-repo-hygiene.mjs && node scripts/update-models-dev-snapshot.mjs --check",
     "models-dev:check": "node scripts/update-models-dev-snapshot.mjs --check",
     "models-dev:update": "node scripts/update-models-dev-snapshot.mjs",
@@ -46,6 +49,7 @@
     "check:core-boundaries": "node scripts/check-core-boundaries.mjs",
     "check:core-boundaries:test": "node --test scripts/check-core-boundaries.test.mjs",
     "check:github-config": "pnpm --dir src/web-ui exec node ../../scripts/check-github-config.mjs && node --test scripts/check-github-config.test.mjs",
+    "test:release-packaging": "node --test scripts/release-channel.test.mjs scripts/desktop-tauri-build.test.mjs scripts/version-generation.test.mjs scripts/tauri-release-manifest.test.mjs",
     "fmt:rs": "node scripts/format-changed-rust.mjs",
     "lint:rs": "cargo clippy --workspace --exclude bitfun-desktop --all-targets",
     "lint:rs:desktop": "pnpm run prepare:mobile-web && cargo clippy -p bitfun-desktop --all-targets",
@@ -57,7 +61,9 @@
     "build": "pnpm run build:web",
     "build:frontend-only": "pnpm run appearance:contract-audit && node scripts/build-web-parallel.mjs --skip-gen-types && pnpm run verify:monaco-assets && pnpm run prepare:mobile-web",
     "verify:monaco-assets": "node scripts/verify-monaco-assets.cjs",
-    "build:web": "pnpm run appearance:contract-audit && node scripts/build-web-parallel.mjs && pnpm run verify:monaco-assets",
+    "verify:webkit-compatibility": "node scripts/verify-webkit-compatibility.cjs",
+    "verify:webkit-compatibility:test": "node --test scripts/verify-webkit-compatibility.test.mjs",
+    "build:web": "pnpm run appearance:contract-audit && node scripts/build-web-parallel.mjs && pnpm run verify:monaco-assets && pnpm run verify:webkit-compatibility",
     "build:mobile-web": "pnpm --dir src/mobile-web build",
     "build:miniapp-market": "pnpm --dir src/miniapp-market-web build",
     "type-check:miniapp-market": "pnpm --dir src/miniapp-market-web type-check",
@@ -66,6 +72,7 @@
     "type-check:skin-market": "pnpm --dir src/skin-market-web type-check",
     "test:skin-market": "pnpm --dir src/skin-market-web test",
     "prepare:mobile-web": "node scripts/mobile-web-build.cjs",
+    "prepare:dsh-profile": "node scripts/prepare-dsh-profile.mjs",
     "frontend:build-all": "node scripts/frontend-build-all.mjs",
     "preview": "pnpm --dir src/web-ui preview",
     "desktop:dev": "node scripts/dev.cjs desktop",
diff --git a/packages/dsh-acp/.gitignore b/packages/dsh-acp/.gitignore
new file mode 100644
index 0000000000..659e82c0fb
--- /dev/null
+++ b/packages/dsh-acp/.gitignore
@@ -0,0 +1,5 @@
+node_modules/
+lib/
+dist-profile/
+.sessions/
+.env
diff --git a/packages/dsh-acp/NOTICE.md b/packages/dsh-acp/NOTICE.md
new file mode 100644
index 0000000000..9c9b4dcba2
--- /dev/null
+++ b/packages/dsh-acp/NOTICE.md
@@ -0,0 +1,30 @@
+# Third-party notices
+
+This package is a fork of parts of [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness),
+which is distributed under the MIT License. Copyright (c) DeepSeek.
+
+| File here | Upstream source | Relationship |
+| --- | --- | --- |
+| `src/codec.ts` | `packages/acp/acp/src/codec.ts` (`@deepseek-ai/dsh-acp`) | verbatim copy |
+| `src/bridge.ts` | `packages/acp/acp/src/index.ts` (`@deepseek-ai/dsh-acp`) | session, turn, approval, and teardown machinery kept; the `session/event` dispatch replaced |
+| `src/app.ts` | `packages/examples/acp-demo/src/index.ts` (`@deepseek-ai/dsh-acp-demo`) | composition kept; the transport swapped for `src/bridge.ts` |
+| `src/bin.ts` | `packages/examples/acp-demo/src/bin.ts` (`@deepseek-ai/dsh-acp-demo`) | copy with a different bin name |
+| `cordis.yml` | `examples/acp-agent/cordis.yml` | trimmed for an IDE launch |
+
+The MIT License text ships with the upstream project; this fork carries the same
+terms.
+
+## Why fork rather than depend
+
+`@deepseek-ai/dsh-acp` is automation-only by design. Its `session/event` handler
+publishes committed assistant text and nothing else:
+
+> Emit only committed assistant text. Raw chunks, reasoning, tools, plans,
+> titles, and retry markers are presentation or trace data and stay off the
+> automation wire.
+
+There is no configuration flag that changes this, so an IDE client sees no tool
+cards, no reasoning, and no plan — and receives permission requests for tool
+calls it was never told about. This fork exists to publish exactly that withheld
+data. Upstreaming it as a verbosity level in `@deepseek-ai/dsh-acp` remains the
+better long-term outcome.
diff --git a/packages/dsh-acp/README.md b/packages/dsh-acp/README.md
new file mode 100644
index 0000000000..6e735a9429
--- /dev/null
+++ b/packages/dsh-acp/README.md
@@ -0,0 +1,133 @@
+# @bitfun/dsh-acp
+
+An Agent Client Protocol server for [DeepSeek Harness](https://github.com/deepseek-ai)
+(`dsh`), written for an IDE rather than for automation.
+
+The harness ships no ACP entry point of its own. The published
+`@deepseek-ai/dsh-acp` is an automation surface: it deliberately withholds tool
+calls, reasoning, and mode selection, because a script does not need to watch an
+agent think. An IDE needs exactly those, so BitFun ships this bridge and runs it
+inside the harness the user already installed.
+
+## For users
+
+Three steps, and BitFun stores none of your DeepSeek configuration:
+
+1. Install the harness — `npm install -g @deepseek-ai/dsh` (BitFun's agent
+   settings page has a one-click button that runs the same thing). It is a Node
+   program and needs **Node 20.12 or newer** — its own toolchain targets Node 22
+   LTS. dsh declares no `engines`, so npm installs it onto an older Node without
+   complaint and it then fails to boot with a `SyntaxError` about
+   `util.parseEnv`; BitFun checks the version up front and says so instead.
+2. Configure a model and an API key inside dsh, e.g. through `dsh web`'s Models
+   page. That writes `~/.dsh/settings.yaml` and `~/.dsh/.credentials.yaml`.
+3. Pick **DeepSeek Harness** in BitFun and start a session.
+
+The model and the key stay where you put them. This bridge reads them through
+the harness's own `dsh-settings-file`, `dsh-credentials-local`, and
+`dsh-agent-default-model` services, so switching models in dsh switches them in
+BitFun too. BitFun writes no DeepSeek credentials of its own.
+
+## How BitFun launches it
+
+BitFun runs `dsh --profile bitfun-acp`. A dsh profile is just a directory under
+`$DSH_HOME/profiles/`, and BitFun materializes this one on first use — see
+`src/crates/interfaces/acp/src/client/dsh_profile.rs`.
+
+```
+$DSH_HOME/profiles/bitfun-acp/
+  package.json            dsh.profile.bundles: []  — an empty root, so the
+                          harness's default tool rows cannot leak into a
+                          preset that asked to be minimal
+  cordis.patch.yml        generated from cordis.yml; the whole file as one
+                          `insert:` layer over that empty root
+  lib/**                  the compiled bridge
+  presets/**              the modes the session offers
+  node_modules/           only what the harness closure does NOT already carry
+  .bitfun-bridge.json     build stamp; BitFun re-syncs when it changes
+```
+
+Everything else resolves out of the user's own dsh: on every launch the harness
+symlinks its entire dependency closure into `$DSH_HOME/profiles/node_modules`,
+which ordinary Node parent-directory lookup finds from inside the profile. That
+is why this package vendors almost nothing and never installs a second copy of
+the harness.
+
+A remote workspace works the same way: BitFun packs the profile above into a tar
+stream and extracts it into `$DSH_HOME/profiles/bitfun-acp/` on that host over
+the session's own transport — no SFTP, so container connections are covered too
+— and skips the upload when the stamp there already matches. `dsh` itself, the
+models, and the key are the remote host's, exactly as they are locally. Steps 1
+and 2 above therefore have to have been done on that host — including the Node
+version, which the same probe checks — and BitFun says so if they were not.
+
+## Reopening a conversation
+
+The bridge advertises ACP's `loadSession` capability, so closing a session and
+clicking it again reopens the one that was there instead of quietly starting a
+blank one. Without it a client has only `session/new` to fall back on, and the
+reopened conversation loses its history, its context, and the mode it ran under
+— it comes back under the roster default and switchable again.
+
+`session/load` resumes the stored session out of the harness's own persistence
+(`$DSH_HOME/acp-sessions/<project>/<session-id>/`), replays its events to the
+client as `session/update` notifications, and answers with the session's mode.
+Three consequences worth knowing:
+
+- **The stored mode wins over the roster default.** Which preset a session ran
+  under is read back from its own log, so a conversation started in `minimal`
+  reopens in `minimal` however the default has moved since.
+- **A conversation that has started comes back locked.** The mode picker shrinks
+  to the one mode in force, because the composition is already baked into the
+  transcript — the same rule a live session follows after its first turn.
+- **A session belongs to the directory it was created in.** Loading it against
+  another `cwd` is refused rather than answered with a session whose sandbox
+  boundary points somewhere else.
+
+`node scripts/smoke.mjs --load <session-id>` drives exactly this path against a
+real installation; the id is a directory name under the path above, and `--cwd`
+has to name the workspace the session was created in.
+
+## Development
+
+```sh
+npm ci                               # the pinned harness toolchain
+npm run build                        # tsc -> lib/
+node scripts/build-profile.mjs       # lib/ + presets -> dist-profile/
+node scripts/smoke.mjs               # drive the profile over real ACP
+npm test                             # vitest
+```
+
+`pnpm run prepare:dsh-profile` from the repository root does the install and
+both build steps. Official `desktop:build` ships `dist-profile/` as a Tauri
+resource; `desktop:dev` and `cargo check` do not compile it. A failure during
+packaging fails the desktop build: an app that silently ships no bridge is
+indistinguishable from a working one until a user starts a DeepSeek session.
+`BITFUN_SKIP_DSH_PROFILE=1` opts out on purpose.
+
+Every `@deepseek-ai/*` dependency is pinned to the **`0.1.0-rc.6`** train — the
+set npm's `next` dist-tag points at. Half of these packages still carry a
+`latest` of `0.0.1-rc.1`, so an unpinned install mixes two trains and disagrees
+with itself; that is worth knowing before loosening a range. They are
+`devDependencies` because they are compile-time only: at runtime the profile
+resolves them from the user's own dsh.
+
+This package is **not** a pnpm workspace member and carries its own
+`package-lock.json`, so installing the harness is the desktop bundle build's
+cost rather than every contributor's `pnpm install`.
+
+To work against a local [deepseek-harness](https://github.com/deepseek-ai)
+checkout instead of the pinned versions, run `node scripts/link-local-dsh.mjs`
+— it symlinks the checkout into `node_modules`, and the build then leaves that
+tree alone.
+
+## Layout
+
+| Path | What it is |
+| --- | --- |
+| `src/app.ts` | the cordis plugin: config schema and ACP stdio transport |
+| `src/bridge.ts` | session lifecycle, prompts, tool calls, permissions |
+| `src/codec.ts` | harness events ⇄ ACP notifications |
+| `src/tool-view.ts` | how a tool call is titled and rendered |
+| `cordis.yml` | the composition; the profile patch is generated from it |
+| `presets/` | the modes a session can switch between |
diff --git a/packages/dsh-acp/cordis.yml b/packages/dsh-acp/cordis.yml
new file mode 100644
index 0000000000..1232076c72
--- /dev/null
+++ b/packages/dsh-acp/cordis.yml
@@ -0,0 +1,195 @@
+# The IDE-facing ACP server composition — the HOST plane.
+#
+# Trimmed from deepseek-harness/examples/acp-agent/cordis.yml: the snapshot
+# harness hooks, the Claude/Codex hook bridges (they need a hooks.json that has
+# no meaning for an IDE launch), and the workflow/ralph/fork tools are dropped.
+#
+# What a session's MODEL sees — its persona, its tools, its prompt sections —
+# is not here. Those rows live in ./presets/<id>/agent.cordis.yml, one
+# composition per mode, and the client picks one per session through the
+# `mode` session config option. A preset layer can only ADD registrations, so anything
+# model-facing left in this file would appear in every mode and make the
+# minimal one a lie. What stays here is what a preset must not own: the model
+# route, the sandbox and approval stack, the registries the preset rows resolve,
+# persistence, and the transport.
+#
+# Stdout carries ACP JSON-RPC, so this tree has no console logger and no HMR.
+#
+# WHICH model runs and WHICH key it uses are not decided here. Both come from
+# the harness the user already installed and configured: `$DSH_HOME/settings.yaml`
+# (what dsh's web Models page writes) and `$DSH_HOME/.credentials.yaml`, read
+# through the two provider rows below. Nothing about an account is stored in
+# this repository, and BitFun never asks for a key of its own.
+
+# User-settings document ($DSH_HOME/settings.yaml, hot-reloaded): its
+# `llm-deepseek:` / `llm-pi-ai:` sections override the adapter rows below
+# without a restart. Same row as the dsh-base bundle mounts.
+- id: settings
+  name: '@deepseek-ai/dsh-settings-file'
+
+# Credential sources: inherited environment over the managed
+# $DSH_HOME/.credentials.yaml, with project and user .env fallbacks. Adapters
+# resolve references per request; nothing is materialized into this process's
+# environment. A user who signed in through dsh is already signed in here.
+- id: credentials
+  name: '@deepseek-ai/dsh-credentials-local'
+
+# The model a session starts on when the client names none. The values here are
+# only the floor: a saved selection in the settings document wins, which is how
+# "pick your model in dsh" carries into an IDE session.
+- id: agent-default-model
+  name: '@deepseek-ai/dsh-agent-default-model'
+  config:
+    provider: deepseek-official
+    model: deepseek-v4-flash
+
+# The DeepSeek adapter: full thinking at max effort on every request, so the
+# bridge has reasoning to publish as agent_thought_chunk. No key, endpoint, or
+# model list is inlined — all three resolve per request from the settings
+# document over this entry, with the key coming from the credential store.
+- id: llm-deepseek
+  name: '@deepseek-ai/dsh-llm-deepseek'
+  config:
+    thinking: enabled
+    reasoningEffort: max
+
+# The pi-ai multi-provider twin, mounted dormant: zero routes until an
+# `llm-pi-ai:` settings section supplies provider profiles, then those routes
+# register live. Composed so that a user who configured a non-DeepSeek provider
+# in dsh finds it here too.
+- id: llm-pi-ai
+  name: '@deepseek-ai/dsh-llm-pi-ai'
+
+# Bash AND the filesystem tools are confined to the workspace; anything wider
+# asks. DSH_PERMISSION_MODE overrides the default for a deployment that wants
+# read-only or full access.
+- id: sandbox
+  name: '@deepseek-ai/dsh-sandbox-local'
+
+- id: sandbox-policy
+  name: '@deepseek-ai/dsh-sandbox-policy'
+  config:
+    mode: !!js "process.env.DSH_PERMISSION_MODE ?? 'workspace-write'"
+    workspaceRoot: !!js process.cwd()
+
+# Managed child-process groups for the bash executor and the ripgrep-backed
+# discovery tools.
+- id: subprocess
+  name: '@deepseek-ai/dsh-subprocess-local'
+
+- id: bash
+  name: '@deepseek-ai/dsh-bash-sandbox'
+  config:
+    timeoutMs: 60000
+
+# The managed `DSH_*` environment every model shell call inherits. Host-plane
+# because it is injected — resolution happens before any session exists — and
+# because both the standard and minimal shells read the one registry.
+- id: shell-env
+  name: '@deepseek-ai/dsh-shell-env'
+
+# `ask` is the whole point of running over ACP rather than the SDK's JSON-RPC
+# transport: each question travels to the client as session/request_permission,
+# attached to a tool call the client has already been shown.
+- id: approval
+  name: '@deepseek-ai/dsh-user-approval'
+  config:
+    policy: !!js "process.env.DSH_PERMISSION_MODE === 'danger-full-access' ? 'never' : 'ask'"
+
+# The app: agent spine + preset roster + JSONL persistence + the IDE protocol
+# bridge. Loaded from source; the Loader resolves this specifier against this
+# file's directory, and the roster's root against the package directory.
+#
+# Every spine gate below is off because the preset owns that half: the spine
+# keeps its registries (tools, skills, goals, jobs, agents, loop) and hands the
+# model-facing plugins to ./presets. `persona` is likewise absent — each preset
+# carries its own through `@deepseek-ai/dsh-persona`.
+# `provider`/`model` are deliberately absent: each session starts on
+# `agent-default-model`'s live selection, so the model chosen in dsh is the
+# model an IDE session runs. Sessions live under the harness home rather than
+# beside whatever project happens to be open — an ACP client launches this
+# adapter with the USER's workspace as the working directory.
+- id: acp-agent
+  name: './src/app.ts'
+  config:
+    reasoning: true
+    persistenceRoot: !!js "process.env.DSH_ACP_SESSIONS_ROOT ?? dshHomePath('acp-sessions')"
+    defaultPreset: !!js "process.env.DSH_ACP_PRESET ?? 'standard'"
+    workspaceContext: false
+    toolBash: false
+    toolJobs: false
+    goals: false
+    skills:
+      enabled: false
+
+# Replay-aware request pressure; the routed adapter supplies model capacity.
+- id: token-meter
+  name: '@deepseek-ai/dsh-token-meter'
+
+# Summarize an older range after measured pressure or a canonical provider
+# overflow. Ratios scale against the routed model's context window.
+- id: compaction-basic
+  name: '@deepseek-ai/dsh-compaction-basic'
+  config:
+    thresholdRatio: 0.8
+    retainRatio: 0.08
+    maxTokens: 8192
+    compactionRetries: 1
+
+# Projection registry backing the subagent catalog surfaces.
+- id: session-projection
+  name: '@deepseek-ai/dsh-session-projection'
+
+- id: subagent
+  name: '@deepseek-ai/dsh-subagent'
+
+- id: subagent-spawn-in-process
+  name: '@deepseek-ai/dsh-subagent-spawn-in-process'
+  config:
+    providerName: spawn
+
+# Host-plane, unlike the delegation TOOLS in ./presets: this registers a
+# continuable setup on the subagent singleton rather than a tool an agent calls,
+# and the setup list is not scope-aware — one copy per mounted preset would
+# register `report` more than once and throw.
+- id: tool-subagent-report
+  name: '@deepseek-ai/dsh-tool-subagent-report'
+
+# The skill catalog and its local-root discovery. Whether a session's model can
+# CALL them is the preset's choice (`@deepseek-ai/dsh-tool-skill`).
+- id: skills
+  name: '@deepseek-ai/dsh-skill'
+
+- id: skill-filesystem
+  name: '@deepseek-ai/dsh-skill-filesystem'
+
+# Persisted same-session goals: the service and its round driver are host-plane
+# (the driver injects `agents`/`sessions`, which resolve before any session
+# exists); the preset contributes `@deepseek-ai/dsh-tool-goal`.
+- id: goals
+  name: '@deepseek-ai/dsh-goal'
+
+- id: goal-round-driver
+  name: '@deepseek-ai/dsh-goal-round-driver'
+
+# The TypeScript code runtime the `code` preset presents its catalog through.
+# Composed here so that preset fails at mount naming its row, rather than at the
+# model's first `run_code`. The worker-thread plugin IS the `codeRuntime`
+# service (it extends the base class), so composing `dsh-code-runtime` beside it
+# would register the service twice and fail the boot.
+- id: code-runtime
+  name: '@deepseek-ai/dsh-code-runtime-worker-thread'
+
+# Identical repeat calls trigger advisory context, never a block.
+- id: repeat-tool-reminder
+  name: '@deepseek-ai/dsh-repeat-tool-reminder'
+
+# The filesystem stack rides the SAME sandbox policy as bash; read-before-edit
+# composes orthogonally on top.
+- id: fs-sandbox
+  name: '@deepseek-ai/dsh-fs-sandbox'
+  config:
+    cwd: !!js process.cwd()
+
+- id: fs-observation-policy
+  name: '@deepseek-ai/dsh-fs-observation-policy'
diff --git a/packages/dsh-acp/package-lock.json b/packages/dsh-acp/package-lock.json
new file mode 100644
index 0000000000..b9ddaa86cb
--- /dev/null
+++ b/packages/dsh-acp/package-lock.json
@@ -0,0 +1,5759 @@
+{
+  "name": "@bitfun/dsh-acp",
+  "version": "0.0.1",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "@bitfun/dsh-acp",
+      "version": "0.0.1",
+      "license": "MIT",
+      "dependencies": {
+        "@agentclientprotocol/sdk": "0.25.1",
+        "@deepseek-ai/dsh-agent-spine-demo": "0.1.0-rc.6"
+      },
+      "bin": {
+        "dsh-acp-ide": "lib/bin.js"
+      },
+      "devDependencies": {
+        "@deepseek-ai/cordis": "4.0.1",
+        "@deepseek-ai/cordis-plugin-loader": "1.0.2",
+        "@deepseek-ai/dsh-agent": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-agent-default-model": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-agent-instructions": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-agent-loop": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-agent-loop-testkit": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-agent-presets": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-agent-tool-presentation": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-app-boot": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-bash-sandbox": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-code-runtime": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-code-runtime-worker-thread": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-compaction-basic": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-credentials-local": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-fs-observation-policy": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-fs-sandbox": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-goal": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-goal-round-driver": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm-deepseek": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm-pi-ai": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-persona": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-repeat-tool-reminder": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-sandbox-local": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-sandbox-policy": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-session-checkpoint-policy": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-session-persistence-jsonl": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-session-projection": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-session-query-sqlite": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-settings-file": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-shell-env": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-skill": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-skill-filesystem": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-subagent": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-subagent-spawn-in-process": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-subprocess-local": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-terminal": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-terminal-bash": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-token-meter": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-tool-bash": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-tool-bash-persistent": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-tool-fs": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-tool-fs-search": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-tool-goal": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-tool-jobs": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-tool-skill": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-tool-str-replace-editor": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-tool-subagent": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-tool-subagent-control": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-tool-subagent-report": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-tool-todo": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-tools": "0.1.0-rc.6",
+        "@deepseek-ai/dsh-user-approval": "0.1.0-rc.6",
+        "@deepseek-ai/schemastery": "3.18.1",
+        "tsx": "4.20.3",
+        "typescript": "5.9.2",
+        "vitest": "3.2.4"
+      },
+      "engines": {
+        "node": "^22.19.0 || >=24.0.0"
+      }
+    },
+    "node_modules/@agentclientprotocol/sdk": {
+      "version": "0.25.1",
+      "resolved": "https://registry.npmjs.org/@agentclientprotocol/sdk/-/sdk-0.25.1.tgz",
+      "integrity": "sha512-jx2rF3bdpGwZ75Q/meyEDLLbYmbtxk82Uh9hDCdxDvcEedBnNSF5hZAnL/kJR5VNz56JqwOmqnAqasC84MwwkQ==",
+      "license": "Apache-2.0",
+      "peerDependencies": {
+        "zod": "^3.25.0 || ^4.0.0"
+      }
+    },
+    "node_modules/@anthropic-ai/sdk": {
+      "version": "0.91.1",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/sdk/-/sdk-0.91.1.tgz",
+      "integrity": "sha512-LAmu761tSN9r66ixvmciswUj/ZC+1Q4iAfpedTfSVLeswRwnY3n2Nb6Tsk+cLPP28aLOPWeMgIuTuCcMC6W/iw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "json-schema-to-ts": "^3.1.1"
+      },
+      "bin": {
+        "anthropic-ai-sdk": "bin/cli"
+      },
+      "peerDependencies": {
+        "zod": "^3.25.0 || ^4.0.0"
+      },
+      "peerDependenciesMeta": {
+        "zod": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@aws-crypto/sha256-browser": {
+      "version": "5.2.0",
+      "resolved": "https://registry.npmjs.org/@aws-crypto/sha256-browser/-/sha256-browser-5.2.0.tgz",
+      "integrity": "sha512-AXfN/lGotSQwu6HNcEsIASo7kWXZ5HYWvfOmSNKDsEqC4OashTp8alTmaz+F7TC2L083SFv5RdB+qU3Vs1kZqw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@aws-crypto/sha256-js": "^5.2.0",
+        "@aws-crypto/supports-web-crypto": "^5.2.0",
+        "@aws-crypto/util": "^5.2.0",
+        "@aws-sdk/types": "^3.222.0",
+        "@aws-sdk/util-locate-window": "^3.0.0",
+        "@smithy/util-utf8": "^2.0.0",
+        "tslib": "^2.6.2"
+      }
+    },
+    "node_modules/@aws-crypto/sha256-js": {
+      "version": "5.2.0",
+      "resolved": "https://registry.npmjs.org/@aws-crypto/sha256-js/-/sha256-js-5.2.0.tgz",
+      "integrity": "sha512-FFQQyu7edu4ufvIZ+OadFpHHOt+eSTBaYaki44c+akjg7qZg9oOQeLlk77F6tSYqjDAFClrHJk9tMf0HdVyOvA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@aws-crypto/util": "^5.2.0",
+        "@aws-sdk/types": "^3.222.0",
+        "tslib": "^2.6.2"
+      },
+      "engines": {
+        "node": ">=16.0.0"
+      }
+    },
+    "node_modules/@aws-crypto/supports-web-crypto": {
+      "version": "5.2.0",
+      "resolved": "https://registry.npmjs.org/@aws-crypto/supports-web-crypto/-/supports-web-crypto-5.2.0.tgz",
+      "integrity": "sha512-iAvUotm021kM33eCdNfwIN//F77/IADDSs58i+MDaOqFrVjZo9bAal0NK7HurRuWLLpF1iLX7gbWrjHjeo+YFg==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "tslib": "^2.6.2"
+      }
+    },
+    "node_modules/@aws-crypto/util": {
+      "version": "5.2.0",
+      "resolved": "https://registry.npmjs.org/@aws-crypto/util/-/util-5.2.0.tgz",
+      "integrity": "sha512-4RkU9EsI6ZpBve5fseQlGNUWKMa1RLPQ1dnjnQoe07ldfIzcsGb5hC5W0Dm7u423KWzawlrpbjXBrXCEv9zazQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@aws-sdk/types": "^3.222.0",
+        "@smithy/util-utf8": "^2.0.0",
+        "tslib": "^2.6.2"
+      }
+    },
+    "node_modules/@aws-sdk/client-bedrock-runtime": {
+      "version": "3.1048.0",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/client-bedrock-runtime/-/client-bedrock-runtime-3.1048.0.tgz",
+      "integrity": "sha512-u+NT61JZEkRFtpL0CAw1N1dwxnaLgwVXQl/zjJxTGgLyS/jTIdg2SdoEoCTHxgDyCnqa1HEi9QOoE9/pYRNpOQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@aws-crypto/sha256-browser": "5.2.0",
+        "@aws-crypto/sha256-js": "5.2.0",
+        "@aws-sdk/core": "^3.974.11",
+        "@aws-sdk/credential-provider-node": "^3.972.42",
+        "@aws-sdk/eventstream-handler-node": "^3.972.16",
+        "@aws-sdk/middleware-eventstream": "^3.972.12",
+        "@aws-sdk/middleware-websocket": "^3.972.19",
+        "@aws-sdk/token-providers": "3.1048.0",
+        "@aws-sdk/types": "^3.973.8",
+        "@smithy/core": "^3.24.2",
+        "@smithy/fetch-http-handler": "^5.4.2",
+        "@smithy/node-http-handler": "^4.7.2",
+        "@smithy/types": "^4.14.1",
+        "tslib": "^2.6.2"
+      },
+      "engines": {
+        "node": ">=20.0.0"
+      }
+    },
+    "node_modules/@aws-sdk/core": {
+      "version": "3.977.7",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/core/-/core-3.977.7.tgz",
+      "integrity": "sha512-I88Iov89NVmjSmJLKSv7Cn9M2J+a2942OkA8nZCbz+sl4ZeY4zEOcoLOrbt1GRfQ8zEQKnjAJdXixA3J/p1fDQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@aws-sdk/types": "^3.974.3",
+        "@aws-sdk/xml-builder": "^3.972.38",
+        "@aws/lambda-invoke-store": "^0.3.0",
+        "@smithy/core": "^3.31.1",
+        "@smithy/signature-v4": "^5.6.12",
+        "@smithy/types": "^4.16.1",
+        "bowser": "^2.11.0",
+        "tslib": "^2.6.2"
+      },
+      "engines": {
+        "node": ">=20.0.0"
+      }
+    },
+    "node_modules/@aws-sdk/credential-provider-env": {
+      "version": "3.972.68",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-env/-/credential-provider-env-3.972.68.tgz",
+      "integrity": "sha512-2a20A/IdNOwUvaDq91iqqS7BA0XlNMfW3iLGZGZLJv0EbUqhSxB0PIx4rQQqssvWj1uXImb3/UCCdHz/+1dOiA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@aws-sdk/core": "^3.977.7",
+        "@aws-sdk/types": "^3.974.3",
+        "@smithy/core": "^3.31.1",
+        "@smithy/types": "^4.16.1",
+        "tslib": "^2.6.2"
+      },
+      "engines": {
+        "node": ">=20.0.0"
+      }
+    },
+    "node_modules/@aws-sdk/credential-provider-http": {
+      "version": "3.972.70",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-http/-/credential-provider-http-3.972.70.tgz",
+      "integrity": "sha512-0yRem2Fs52r/Nn6UAqIlpjexfaYj8ziEozOe9tamtAVT/5bzFLKx8O2r7MaRqgS3hGKHIa1Jij9nKHSsNnb04A==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@aws-sdk/core": "^3.977.7",
+        "@aws-sdk/types": "^3.974.3",
+        "@smithy/core": "^3.31.1",
+        "@smithy/fetch-http-handler": "^5.6.13",
+        "@smithy/node-http-handler": "^4.9.13",
+        "@smithy/types": "^4.16.1",
+        "tslib": "^2.6.2"
+      },
+      "engines": {
+        "node": ">=20.0.0"
+      }
+    },
+    "node_modules/@aws-sdk/credential-provider-http/node_modules/@smithy/node-http-handler": {
+      "version": "4.11.0",
+      "resolved": "https://registry.npmjs.org/@smithy/node-http-handler/-/node-http-handler-4.11.0.tgz",
+      "integrity": "sha512-ssHIZsadPUA3lGdnoByxfnjtb9xPYQLvdfJRLKIwxOoa6tO1suG4sLFSsgd7D/CsvYd8QbBIuKTImuJha5l6aQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@smithy/core": "^3.33.0",
+        "@smithy/types": "^4.17.0",
+        "tslib": "^2.6.2"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      }
+    },
+    "node_modules/@aws-sdk/credential-provider-ini": {
+      "version": "3.973.13",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-ini/-/credential-provider-ini-3.973.13.tgz",
+      "integrity": "sha512-2M39DE02XpYYaSWYk/4AsImXYUU/1L2xmTMLUpMMWq7DfLv191/vCRy3baKtdr45AkJQyVgSjmuVOLm15SwrRQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@aws-sdk/core": "^3.977.7",
+        "@aws-sdk/credential-provider-env": "^3.972.68",
+        "@aws-sdk/credential-provider-http": "^3.972.70",
+        "@aws-sdk/credential-provider-login": "^3.972.75",
+        "@aws-sdk/credential-provider-process": "^3.972.68",
+        "@aws-sdk/credential-provider-sso": "^3.973.12",
+        "@aws-sdk/credential-provider-web-identity": "^3.972.74",
+        "@aws-sdk/nested-clients": "^3.997.42",
+        "@aws-sdk/types": "^3.974.3",
+        "@smithy/core": "^3.31.1",
+        "@smithy/credential-provider-imds": "^4.4.16",
+        "@smithy/types": "^4.16.1",
+        "tslib": "^2.6.2"
+      },
+      "engines": {
+        "node": ">=20.0.0"
+      }
+    },
+    "node_modules/@aws-sdk/credential-provider-login": {
+      "version": "3.972.75",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-login/-/credential-provider-login-3.972.75.tgz",
+      "integrity": "sha512-jaTESuJlQsoUZ44f/i2puyPt8VlF/dMMJ9HM3cStYtk7eKX4N9UWi83OLixUkoOJH3BwWlPLCq9YIK9nfWhVBg==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@aws-sdk/core": "^3.977.7",
+        "@aws-sdk/nested-clients": "^3.997.42",
+        "@aws-sdk/types": "^3.974.3",
+        "@smithy/core": "^3.31.1",
+        "@smithy/types": "^4.16.1",
+        "tslib": "^2.6.2"
+      },
+      "engines": {
+        "node": ">=20.0.0"
+      }
+    },
+    "node_modules/@aws-sdk/credential-provider-node": {
+      "version": "3.972.79",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-node/-/credential-provider-node-3.972.79.tgz",
+      "integrity": "sha512-RIw5dof1EHkWubrZzPC941CDtnFG1iAXsxbFgLkhdYZXHc4icU13c/uxSMI0J5eUx9bxa7LjfpdjfClBB1QsDA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@aws-sdk/credential-provider-env": "^3.972.68",
+        "@aws-sdk/credential-provider-http": "^3.972.70",
+        "@aws-sdk/credential-provider-ini": "^3.973.13",
+        "@aws-sdk/credential-provider-process": "^3.972.68",
+        "@aws-sdk/credential-provider-sso": "^3.973.12",
+        "@aws-sdk/credential-provider-web-identity": "^3.972.74",
+        "@aws-sdk/types": "^3.974.3",
+        "@smithy/core": "^3.31.1",
+        "@smithy/credential-provider-imds": "^4.4.16",
+        "@smithy/types": "^4.16.1",
+        "tslib": "^2.6.2"
+      },
+      "engines": {
+        "node": ">=20.0.0"
+      }
+    },
+    "node_modules/@aws-sdk/credential-provider-process": {
+      "version": "3.972.68",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-process/-/credential-provider-process-3.972.68.tgz",
+      "integrity": "sha512-nLP3Pda2MQTFJ25hKBMmUuB9Uv+bTZQNlufbeCwklP549Vwnkd8bRLJoCKp5k6xjmdyptrPrOfGOhN0mKuca8A==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@aws-sdk/core": "^3.977.7",
+        "@aws-sdk/types": "^3.974.3",
+        "@smithy/core": "^3.31.1",
+        "@smithy/types": "^4.16.1",
+        "tslib": "^2.6.2"
+      },
+      "engines": {
+        "node": ">=20.0.0"
+      }
+    },
+    "node_modules/@aws-sdk/credential-provider-sso": {
+      "version": "3.973.12",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-sso/-/credential-provider-sso-3.973.12.tgz",
+      "integrity": "sha512-EmgyyHn+f9WCcelp3L/vci+LGbX8GigWaVphRArjVo5Pktkr9YnLy/mQ6VDkDyBD72dtfRNTgHmD2ts4rTDXKQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@aws-sdk/core": "^3.977.7",
+        "@aws-sdk/nested-clients": "^3.997.42",
+        "@aws-sdk/token-providers": "3.1108.0",
+        "@aws-sdk/types": "^3.974.3",
+        "@smithy/core": "^3.31.1",
+        "@smithy/types": "^4.16.1",
+        "tslib": "^2.6.2"
+      },
+      "engines": {
+        "node": ">=20.0.0"
+      }
+    },
+    "node_modules/@aws-sdk/credential-provider-sso/node_modules/@aws-sdk/token-providers": {
+      "version": "3.1108.0",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/token-providers/-/token-providers-3.1108.0.tgz",
+      "integrity": "sha512-rI80zxDxGJ6904eC/YbjkdjY6JdaZvQ01kOmrMvw7cFQGIHo27fhnIVbMSVDS4T6foQImjxYSRoOu/uSJscXDw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@aws-sdk/core": "^3.977.7",
+        "@aws-sdk/nested-clients": "^3.997.42",
+        "@aws-sdk/types": "^3.974.3",
+        "@smithy/core": "^3.31.1",
+        "@smithy/types": "^4.16.1",
+        "tslib": "^2.6.2"
+      },
+      "engines": {
+        "node": ">=20.0.0"
+      }
+    },
+    "node_modules/@aws-sdk/credential-provider-web-identity": {
+      "version": "3.972.74",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-web-identity/-/credential-provider-web-identity-3.972.74.tgz",
+      "integrity": "sha512-0YfczxGXF3RjGj8z7QG/Ho2HnLGKDHfPSHiTs47UU1U/+mmwISDN+rvGKt2zh+3FX8NdT4xd95LGBGyhQw2dgQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@aws-sdk/core": "^3.977.7",
+        "@aws-sdk/nested-clients": "^3.997.42",
+        "@aws-sdk/types": "^3.974.3",
+        "@smithy/core": "^3.31.1",
+        "@smithy/types": "^4.16.1",
+        "tslib": "^2.6.2"
+      },
+      "engines": {
+        "node": ">=20.0.0"
+      }
+    },
+    "node_modules/@aws-sdk/eventstream-handler-node": {
+      "version": "3.972.32",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/eventstream-handler-node/-/eventstream-handler-node-3.972.32.tgz",
+      "integrity": "sha512-rlbmsMG7ZNgrVhWSqqXpq6y9hfiREyzCg3CNTk9UK+AoP7+65kOkqpWmqwLfV1UrRSHATdLnZF2rt9ZTUxYQJA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@aws-sdk/types": "^3.974.3",
+        "@smithy/core": "^3.31.1",
+        "@smithy/types": "^4.16.1",
+        "tslib": "^2.6.2"
+      },
+      "engines": {
+        "node": ">=20.0.0"
+      }
+    },
+    "node_modules/@aws-sdk/middleware-eventstream": {
+      "version": "3.972.27",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-eventstream/-/middleware-eventstream-3.972.27.tgz",
+      "integrity": "sha512-M7Ay1VpBpf/YFfic9kkjwE3wyCh4G0gEM4RypRXYm7aPjyfqi+D8FEYMR2E3IqbvN+qi2rEFYAiwWL0XHtQYdQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@aws-sdk/types": "^3.974.3",
+        "@smithy/core": "^3.31.1",
+        "@smithy/types": "^4.16.1",
+        "tslib": "^2.6.2"
+      },
+      "engines": {
+        "node": ">=20.0.0"
+      }
+    },
+    "node_modules/@aws-sdk/middleware-websocket": {
+      "version": "3.972.50",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-websocket/-/middleware-websocket-3.972.50.tgz",
+      "integrity": "sha512-gdcWRbmIf1dWA/prf44Bnnzgqj+AbsXX2yfhZhOQLwSm7NfKIYPmkRlPqP0CTepHzjxMIBdWBDdtQB+Y/dFUeg==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@aws-sdk/core": "^3.977.7",
+        "@aws-sdk/types": "^3.974.3",
+        "@smithy/core": "^3.31.1",
+        "@smithy/fetch-http-handler": "^5.6.13",
+        "@smithy/signature-v4": "^5.6.12",
+        "@smithy/types": "^4.16.1",
+        "tslib": "^2.6.2"
+      },
+      "engines": {
+        "node": ">= 14.0.0"
+      }
+    },
+    "node_modules/@aws-sdk/nested-clients": {
+      "version": "3.997.42",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/nested-clients/-/nested-clients-3.997.42.tgz",
+      "integrity": "sha512-XWRyon2MTHXD/zMoo0Mbge6Vwf+iE0qQaM/RyGO6NfZ9WukCFiQL27nQVZjYy2JwSIg+iXZxKOX95OBXqlSM4w==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@aws-sdk/core": "^3.977.7",
+        "@aws-sdk/signature-v4-multi-region": "^3.996.44",
+        "@aws-sdk/types": "^3.974.3",
+        "@smithy/core": "^3.31.1",
+        "@smithy/fetch-http-handler": "^5.6.13",
+        "@smithy/node-http-handler": "^4.9.13",
+        "@smithy/types": "^4.16.1",
+        "tslib": "^2.6.2"
+      },
+      "engines": {
+        "node": ">=20.0.0"
+      }
+    },
+    "node_modules/@aws-sdk/nested-clients/node_modules/@smithy/node-http-handler": {
+      "version": "4.11.0",
+      "resolved": "https://registry.npmjs.org/@smithy/node-http-handler/-/node-http-handler-4.11.0.tgz",
+      "integrity": "sha512-ssHIZsadPUA3lGdnoByxfnjtb9xPYQLvdfJRLKIwxOoa6tO1suG4sLFSsgd7D/CsvYd8QbBIuKTImuJha5l6aQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@smithy/core": "^3.33.0",
+        "@smithy/types": "^4.17.0",
+        "tslib": "^2.6.2"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      }
+    },
+    "node_modules/@aws-sdk/signature-v4-multi-region": {
+      "version": "3.996.44",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/signature-v4-multi-region/-/signature-v4-multi-region-3.996.44.tgz",
+      "integrity": "sha512-ZSfQ35Qn4MhSY+A0Whyr+KBx+wJKZUyBsOrjB2pSHOafRzbFe47T8XcXM8hZqUAC69qnqIy0C9ArxTuud0CC2w==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@aws-sdk/types": "^3.974.3",
+        "@smithy/signature-v4": "^5.6.12",
+        "@smithy/types": "^4.16.1",
+        "tslib": "^2.6.2"
+      },
+      "engines": {
+        "node": ">=20.0.0"
+      }
+    },
+    "node_modules/@aws-sdk/token-providers": {
+      "version": "3.1048.0",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/token-providers/-/token-providers-3.1048.0.tgz",
+      "integrity": "sha512-k0y/GcuesuSfWyUM0WamrGyeZmltRYaPbHO82UDA6mZ/doB+FOHKutikPAtSXMn/hDz970cF+iRuuiYO9VEbAA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@aws-sdk/core": "^3.974.11",
+        "@aws-sdk/nested-clients": "^3.997.9",
+        "@aws-sdk/types": "^3.973.8",
+        "@smithy/core": "^3.24.2",
+        "@smithy/types": "^4.14.1",
+        "tslib": "^2.6.2"
+      },
+      "engines": {
+        "node": ">=20.0.0"
+      }
+    },
+    "node_modules/@aws-sdk/types": {
+      "version": "3.974.3",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/types/-/types-3.974.3.tgz",
+      "integrity": "sha512-ECAqfpNsef+7MO8qtR0h9KcFIBAygaE7Cm6UOiQl+ft+uVap+1G7bNEjs4mdJE2OnA4m6k7i8peH8uGIAsOMGw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@smithy/types": "^4.16.1",
+        "tslib": "^2.6.2"
+      },
+      "engines": {
+        "node": ">=20.0.0"
+      }
+    },
+    "node_modules/@aws-sdk/util-locate-window": {
+      "version": "3.965.9",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/util-locate-window/-/util-locate-window-3.965.9.tgz",
+      "integrity": "sha512-wB/ho7pTJKqWz3WYDt2ZWDWI8bxQpN/xwf+5ZQ1zWaj+HDY9B8Fn434i6qZ6j6ZG3aCiIJtZaQVqwajx5xYsQA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "tslib": "^2.6.2"
+      },
+      "engines": {
+        "node": ">=20.0.0"
+      }
+    },
+    "node_modules/@aws-sdk/xml-builder": {
+      "version": "3.972.38",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/xml-builder/-/xml-builder-3.972.38.tgz",
+      "integrity": "sha512-grf7mzfVxBS5AlsuTvBN7uDpzqohFww9fRPCO+EBSUdvtsYMcPSKdz54h/7XiscqNcUM1Ae1MF7JLHmiYYuzbQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@smithy/types": "^4.16.1",
+        "tslib": "^2.6.2"
+      },
+      "engines": {
+        "node": ">=20.0.0"
+      }
+    },
+    "node_modules/@aws/lambda-invoke-store": {
+      "version": "0.3.0",
+      "resolved": "https://registry.npmjs.org/@aws/lambda-invoke-store/-/lambda-invoke-store-0.3.0.tgz",
+      "integrity": "sha512-sl4Bm6yiMNYrZKkqqDFWN0UfnWhlS8ivKxrYl+6t0gCLrqr8y3B2IqZZbFRkfaVVp7C/baApyh71P+LeE1A2sQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=18.0.0"
+      }
+    },
+    "node_modules/@babel/runtime": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.29.7.tgz",
+      "integrity": "sha512-Nq8OhGWiZIZGV6hLHoyAKLLcJihP/xFeBMGJoUrxTX2psI8dCifzLhZISFb+VWS3wFMRDmCGw5R+dOySCqPLhw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@deepseek-ai/cordis": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/cordis/-/cordis-4.0.1.tgz",
+      "integrity": "sha512-YBdskTU2Po1kru3GgcUWUbkTsPMA9LkSQDAY8rBkFJeajdgcQad3QPJZE26JyK99Xb6HaASvoXg2DSUTeN/0Nw==",
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/cosmokit": "^1.8.2",
+        "@standard-schema/spec": "^1.1.0"
+      },
+      "bin": {
+        "cordis": "bin.js"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis-plugin-include": "^1.0.6",
+        "@deepseek-ai/cordis-plugin-loader": "^1.0.2"
+      },
+      "peerDependenciesMeta": {
+        "@deepseek-ai/cordis-plugin-include": {
+          "optional": true
+        },
+        "@deepseek-ai/cordis-plugin-loader": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@deepseek-ai/cordis-plugin-group": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/cordis-plugin-group/-/cordis-plugin-group-1.0.1.tgz",
+      "integrity": "sha512-E1NThkFB3jn3TCqa6Oc++1zQHqLejF3W2wDwv2BlL3UEmgtBXL1K1j1koc+j676RuiOXtJkUJlPcOntRGKLWBQ==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/cordis-plugin-loader": "^1.0.2"
+      }
+    },
+    "node_modules/@deepseek-ai/cordis-plugin-include": {
+      "version": "1.0.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/cordis-plugin-include/-/cordis-plugin-include-1.0.6.tgz",
+      "integrity": "sha512-i1VXrZCbv6tk/iUgedCNjrxxArbWT3IvRZGB5sdqJ3ectnihivXXQbRZ8JJ73DSmAPvlMGmrbtjFAfm10yvXRg==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "@deepseek-ai/cosmokit": "^1.8.2",
+        "js-yaml": "^4.1.0"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/cordis-plugin-loader": "^1.0.2"
+      }
+    },
+    "node_modules/@deepseek-ai/cordis-plugin-loader": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/cordis-plugin-loader/-/cordis-plugin-loader-1.0.2.tgz",
+      "integrity": "sha512-RIW9hoVyhYDWdCI9BsvtZccPde1ECLC4OAxupwowGTak78vwVTVdb3HezTSOK1Y1/Ax3Ru0LA1pYOB04CnTxIQ==",
+      "devOptional": true,
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/cosmokit": "^1.8.2"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "node-addon-require-builtin": "^0.1.4"
+      },
+      "peerDependenciesMeta": {
+        "node-addon-require-builtin": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@deepseek-ai/cordis-plugin-timer": {
+      "version": "1.1.3",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/cordis-plugin-timer/-/cordis-plugin-timer-1.1.3.tgz",
+      "integrity": "sha512-IOkey1VNmJwYa5U8bksyMOnM7mtirqjjbWLr3xA8QybLMK0sMooG3a6iJwtvd8P3MFwo3FQibEg+JPixp37MEw==",
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "@deepseek-ai/cosmokit": "^1.8.2"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1"
+      }
+    },
+    "node_modules/@deepseek-ai/cosmokit": {
+      "version": "1.8.2",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/cosmokit/-/cosmokit-1.8.2.tgz",
+      "integrity": "sha512-muBOKtSrUKU5m/xpq8ZXWL6hQ/jgd4PhU2PqH97bcxIiLEJfNwZOGQEx4t/aS/GgxRAR+ra9pMHPMtTHU4sqqA==",
+      "license": "MIT"
+    },
+    "node_modules/@deepseek-ai/dsh-agent": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-agent/-/dsh-agent-0.1.0-rc.6.tgz",
+      "integrity": "sha512-vtqq2pWTrzn0dKfj5kREZRpP82AwtGjGx9V1lYnKvF+Uc/a8zyWbSvjDE7V1d3YQAQJzs2cWO31hURWDekDXIA==",
+      "license": "MIT",
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-scope": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-typert-protocol": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-agent-default-model": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-agent-default-model/-/dsh-agent-default-model-0.1.0-rc.6.tgz",
+      "integrity": "sha512-5Fl15p5mHVMlp69Ea0qeS81ej1Bt9vSJtCed+gjvzkKzv5y3VbJQ8PPBV34F1rTSyhTtjj5Q7TuDugQI5ZpjfA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-settings": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-agent-instructions": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-agent-instructions/-/dsh-agent-instructions-0.1.0-rc.6.tgz",
+      "integrity": "sha512-RCd3UWJI7b3X6EUnxnqwOFiMWh1PzRRg9GrVt4G0tVNDIxeYX+RF2FTbOrslIOkOCZxG3BlI2M/bZ6yQmB4Vwg==",
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-fs": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-agent-loop": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-agent-loop/-/dsh-agent-loop-0.1.0-rc.6.tgz",
+      "integrity": "sha512-yShuKIMW360H14L4y13j3gz3Ix1s/3lwEEpfJW4hnFAE09h9Z4yJA7UfTQmQdzMRMnuj4uWFPw0e0BbapnkFuw==",
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-scope": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session-persistence": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-agent-loop-testkit": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-agent-loop-testkit/-/dsh-agent-loop-testkit-0.1.0-rc.6.tgz",
+      "integrity": "sha512-VOjQp3OdEhiQuwruaXdMBchZ/y/8pw5sGXhKB6MmMHxsydsmnm4ew5IISwtopufx419/OomRzijkd85glpG8Vw==",
+      "dev": true,
+      "license": "MIT",
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-agent-presets": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-agent-presets/-/dsh-agent-presets-0.1.0-rc.6.tgz",
+      "integrity": "sha512-LtDz0TYE7YNhJOhMDZ8s45xQG57bWF4F1SN3tjYDosaBdINIRTxJ0O80BC+KeliqFDw071ZNOzTUEelwEAIx7w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1",
+        "js-yaml": "^4.1.0"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/cordis-plugin-include": "^1.0.6",
+        "@deepseek-ai/cordis-plugin-loader": "^1.0.2",
+        "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-atomic-write": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-scope": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-agent-spine-demo": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-agent-spine-demo/-/dsh-agent-spine-demo-0.1.0-rc.6.tgz",
+      "integrity": "sha512-urMS7CReaddhybJZCaPA8oI4VbD/A+62mLTOb2E4b8EKgZ55sMsOGfpkMZmFIs9nqJqxdFUmcxPXWKVMVtpb5w==",
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/cordis-plugin-timer": "^1.1.3",
+        "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-agent-instructions": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-agent-loop": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-goal": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-goal-round-driver": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-jobs-local": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm-retry": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-scope": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session-title": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-shell-env": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-skill": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-skill-filesystem": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-tool-bash": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-tool-goal": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-tool-jobs": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-tool-skill": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-agent-tool-presentation": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-agent-tool-presentation/-/dsh-agent-tool-presentation-0.1.0-rc.6.tgz",
+      "integrity": "sha512-Ysg45g0qnteB6w7krUBRXQ6SFbc8L+laPZTS2y15FFTLueruJaANBLIgnorEtj2bIJYF2Lq0fKH5v0wPNNrlXw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-anonymous-user-id": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-anonymous-user-id/-/dsh-anonymous-user-id-0.1.0-rc.6.tgz",
+      "integrity": "sha512-+K/+tQzuDlmvKhoudB7qVMJMNF/p1+GTRQkkPA3JHIQM5yHj7AUYY8oMLROTvUivs8XWtkNyEP1/c6nPwrHazQ==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-brand": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-app-boot": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-app-boot/-/dsh-app-boot-0.1.0-rc.6.tgz",
+      "integrity": "sha512-97Xb2wB0cuFMmbvW7/95pfMTyXwUNQxW/ROx19OdjS6PgHQNA28ZADZ19FgZmofguxzWuDD0lJPc1SWkSGLYcg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "js-yaml": "^4.2.0"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/cordis-plugin-group": "^1.0.1",
+        "@deepseek-ai/cordis-plugin-hmr": "^1.0.16",
+        "@deepseek-ai/cordis-plugin-include": "^1.0.6",
+        "@deepseek-ai/cordis-plugin-loader": "^1.0.2",
+        "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-launch-environment": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6"
+      },
+      "peerDependenciesMeta": {
+        "@deepseek-ai/cordis-plugin-hmr": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-atomic-write": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-atomic-write/-/dsh-atomic-write-0.1.0-rc.6.tgz",
+      "integrity": "sha512-Ot/2aygDzWuN4ypUkDJA6MpSlGbcvzzKnWAms0lg+2WUtPZr7O0cGb83K3TEO2NoAu0LJfVxlbo8Eya3tDaFtw==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-attachment": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-attachment/-/dsh-attachment-0.1.0-rc.6.tgz",
+      "integrity": "sha512-3P6N17NQ8jqSQGzeCs+svCIqArU8oq0YmgEAo+axN9aVuUDferWU4DLRSX59UGpmyldX4LQn81toA+c+DqMcHg==",
+      "license": "MIT",
+      "peer": true,
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-brand": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-bash-local": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-bash-local/-/dsh-bash-local-0.1.0-rc.6.tgz",
+      "integrity": "sha512-YAc5W9uR7sN1Rrobp6fQlCaOdHqCWatTktV68UsoDuOJs5eM3nWEUUUVN8jdZCIDZhktT5hqbhe3+DzOX3Xg1w==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-shell": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-subprocess": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-timeout": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-bash-sandbox": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-bash-sandbox/-/dsh-bash-sandbox-0.1.0-rc.6.tgz",
+      "integrity": "sha512-TNLRriAjpEUrJplrI0BmZtAtntIkV5usYiKylJGPlGUfWWnJkLR0zL9gioyXW3kncHBVSnb+YTuf+7FnDVeVHQ==",
+      "dev": true,
+      "license": "MIT",
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-bash-local": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-sandbox": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-sandbox-policy": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-shell": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-brand": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-brand/-/dsh-brand-0.1.0-rc.6.tgz",
+      "integrity": "sha512-E8j9Nby24qP4rfrdcfc7bpt1CHpGT3tYmycOJJkEOH4ptIdT1m2ro9nmnSd5CWYukTr64A77vjm2WGqHRI92UA==",
+      "license": "MIT",
+      "peer": true,
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-code-runtime": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-code-runtime/-/dsh-code-runtime-0.1.0-rc.6.tgz",
+      "integrity": "sha512-aw8D4IOeMo11A3uxQeE4LFoW3bvaQnVkGFqqtS+lsINDARrOCJHXLUgecoKpys+Lc5erZZ4UQDnymJmL4OCcKA==",
+      "license": "MIT",
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-code-runtime-worker-thread": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-code-runtime-worker-thread/-/dsh-code-runtime-worker-thread-0.1.0-rc.6.tgz",
+      "integrity": "sha512-I2YX2ZSeQnQrSJGffM2upL+7y7vGsLwKv478gesusgYtT0kH/MOcszO9ZpnV8sIqvlkgzvWgBhXzniGHWh40ZA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-code-runtime": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-timeout": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-commands": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-commands/-/dsh-commands-0.1.0-rc.6.tgz",
+      "integrity": "sha512-dq1GZmGTPXEGG01ksZ6Jj6DxAkzAbg+nepvfnM/P74d6EUcsFsEy7CfS18n0VJ6/2Wp0xOWsQyyuFElqbynO7w==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "zod": "^4.4.3"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-brand": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-scope": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-typert-protocol": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-compaction": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-compaction/-/dsh-compaction-0.1.0-rc.6.tgz",
+      "integrity": "sha512-Uu8qgrHom13gdwwxAnqmNuWM8MqafkRlhjQMMJYmaMVVxjEUewSJ6lwtMbUEBR5ViLsfv4pTm5TnhxNCjedBUw==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-brand": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-commands": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-compaction-basic": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-compaction-basic/-/dsh-compaction-basic-0.1.0-rc.6.tgz",
+      "integrity": "sha512-sqfFPBy1SqsOmaWro/GOAcDkrryjsmJLU/M+V4HZakoE7hLyGVhMElrRG5E5OlplIl2Akntc+YYwX36kDfEItw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-commands": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-compaction": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-compaction-tool-result-pruner": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-token-meter": "^0.1.0-rc.6"
+      },
+      "peerDependenciesMeta": {
+        "@deepseek-ai/dsh-compaction-tool-result-pruner": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-credentials": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-credentials/-/dsh-credentials-0.1.0-rc.6.tgz",
+      "integrity": "sha512-zyYRs3A9gxfZjZfONzJdMhM0Gzbslpha+FGYkLDRAozgPj0N7mZdE+Qflx2V4WNrCnsSjuvOW0HFBxWtSRUTUw==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-brand": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-credentials-local": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-credentials-local/-/dsh-credentials-local-0.1.0-rc.6.tgz",
+      "integrity": "sha512-DSDcC1i8hd3Ynyr6MTPFoEdAsxcmZSLo68IPBPvaPGHZ+rCX8XDAjghWvXrNkLtkjms0ngNVPJS3rNMRcJFq0w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1",
+        "chokidar": "^4.0.3",
+        "yaml": "^2.9.0"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-atomic-write": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-credentials": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-launch-environment": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-fs": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-fs/-/dsh-fs-0.1.0-rc.6.tgz",
+      "integrity": "sha512-OTkwb4QsZgmjtA/8ZEPh1FapmrBr3N989/G4Wmo1JkAvKbMxkYty6LxjckOawTTz7GJTfUoZCrw9uopDfIMMNw==",
+      "license": "MIT",
+      "peer": true,
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-brand": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-sandbox": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-fs-local": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-fs-local/-/dsh-fs-local-0.1.0-rc.6.tgz",
+      "integrity": "sha512-zP0OW474s7tvzEVQnBBTGL6Jrv/YyQXt4nswIbc3Aqr9JyHSfhZ/5IJoipZqfYXLS3ISWMhrF2npRg8L1NGsIQ==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1",
+        "koffi": "^3.1.0"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-fs": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-fs-observation-policy": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-fs-observation-policy/-/dsh-fs-observation-policy-0.1.0-rc.6.tgz",
+      "integrity": "sha512-EiBMACBVmVEs0fDFkbVH6OwXrVDp9GrTG8c62vGBfuljZvRNv6yVwS+SDblboJrIPcp67axxHRVPOEy7z1CUKQ==",
+      "dev": true,
+      "license": "MIT",
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-fs": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-fs-sandbox": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-fs-sandbox/-/dsh-fs-sandbox-0.1.0-rc.6.tgz",
+      "integrity": "sha512-NLUeuZkeQVNPIpUute6TW4Ts1et6XxLkQIOxunL5T9mXwizp+tcdCeNjBW6XMiG6gvpECA+IA3amFCvbVSXtXw==",
+      "dev": true,
+      "license": "MIT",
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-fs": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-fs-local": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-sandbox": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-sandbox-policy": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-goal": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-goal/-/dsh-goal-0.1.0-rc.6.tgz",
+      "integrity": "sha512-cONQOvFqZmjtw5HSgbXJ5/8rZ2gHqdf69ONhH21cLFu5jJKVy9YbLt42SlD2sdGMv/co9nN8Kt9bWQiZ/96VbQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1",
+        "zod": "^4.4.3"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-brand": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-scope": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session-projection": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-typert-protocol": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-goal-round-driver": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-goal-round-driver/-/dsh-goal-round-driver-0.1.0-rc.6.tgz",
+      "integrity": "sha512-+tpbRXZ3nq/C2btBxyFC88RU0IC0H39JY1WyL07fq3j24AWS5jZb9/05gEJPyoyaIDkV/Li4dJVCdJH4VaF9Fw==",
+      "license": "MIT",
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-goal": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-home-paths": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-home-paths/-/dsh-home-paths-0.1.0-rc.6.tgz",
+      "integrity": "sha512-gIiUBmqB3L8inFr+hvjZv2/i6EVJOHIHCHg7bBFVhcl4HDK94+8wUCXTLGy80tcuISzIQiIaLuJq/NhSmV9Amw==",
+      "license": "MIT",
+      "peer": true,
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-invariants": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-invariants/-/dsh-invariants-0.1.0-rc.6.tgz",
+      "integrity": "sha512-WfEfOi99a4cpOugRAHTBSTnesLieu3ist1q9PXDXFBHX++K1rAl9+sB7YrdnbB8LH0UOY532gS9xJUYU6w0SLw==",
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-jobs": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-jobs/-/dsh-jobs-0.1.0-rc.6.tgz",
+      "integrity": "sha512-fmyvSOVsNObmRnciuH57ZntuCSb0gflRleCeQx1ToGHRoGrR4Ndnstx33SuIXUQt6OSUhD2w2WKQTReXogpnSQ==",
+      "license": "MIT",
+      "peer": true,
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-brand": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-jobs-local": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-jobs-local/-/dsh-jobs-local-0.1.0-rc.6.tgz",
+      "integrity": "sha512-vnCcHPjvXLQq2i80No61oKF/165+OvEC2iUBmVTxl6ka87yNECwYf4nrspHKqP9HbVWndtNP0lGgrnz7bo0XCw==",
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-jobs": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-scope": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-timeout": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-launch-environment": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-launch-environment/-/dsh-launch-environment-0.1.0-rc.6.tgz",
+      "integrity": "sha512-tTRJ1464PJUDe1Em1qq0mfdgGREzGGWo3JSqP6xeYDoX+MRXVP9/ChsZ5k6VBMjARAxw0HGBf7WR6VcupHbMZg==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-llm": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-llm/-/dsh-llm-0.1.0-rc.6.tgz",
+      "integrity": "sha512-kuFGC8bHlzGTwlRxQhXjf3CYWl8M4NzH+EYIkrW8rri4iMc9W53xrdvkil5No/DUlMm8g1u7GdeiWYFy0TMvtA==",
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-attachment": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-brand": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-timeout": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-llm-deepseek": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-llm-deepseek/-/dsh-llm-deepseek-0.1.0-rc.6.tgz",
+      "integrity": "sha512-Md9ik1e8tmrKcL2aRpif8qdndl9TObbfHodj6CeVlkrL9y+PEghVPZqOYtnuRcv4/e0nVSIJsUw2gFvaL+T40Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1",
+        "eventsource-parser": "^3.1.0"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-anonymous-user-id": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-credentials": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-launch-environment": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-timeout": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-llm-pi-ai": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-llm-pi-ai/-/dsh-llm-pi-ai-0.1.0-rc.6.tgz",
+      "integrity": "sha512-5RvzkpVCYLg9A3IGdm04px7XOaF/xikuMLe2toBY4A0qtJraXiZtUN1QBOL9i6u7DTOLG9oHP/USsbWRpyI+1Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1",
+        "@earendil-works/pi-ai": "^0.82.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-attachment": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-credentials": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-launch-environment": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-timeout": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-llm-retry": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-llm-retry/-/dsh-llm-retry-0.1.0-rc.6.tgz",
+      "integrity": "sha512-HdjBWcQ6spwA8B5dScRhndLQNiKoQTkq36O+kmJ80B9V4z08K5XrJwAInH9cCxJ91CqNzx/sxCdDds0oZDH1Pw==",
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-brand": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-timeout": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-output-retention": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-output-retention/-/dsh-output-retention-0.1.0-rc.6.tgz",
+      "integrity": "sha512-3TQJxGqjotWrvNKI+Da8nIDjzpKZEGpImeMBp7EklfO0CDbiXA5B0Ms39zBniWkWr1lvbm2iJiYERY5uDeP6og==",
+      "license": "MIT",
+      "peer": true,
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-persona": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-persona/-/dsh-persona-0.1.0-rc.6.tgz",
+      "integrity": "sha512-rY5AVVopkS9vJl+hGHGQP0nSwzxawubRvEKo4JZmGK7bKZlvevRvj8bd2wLNhTx54jppz+u0iEUq/fqG5k9Mvg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-repeat-tool-reminder": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-repeat-tool-reminder/-/dsh-repeat-tool-reminder-0.1.0-rc.6.tgz",
+      "integrity": "sha512-iN9FjWXL8e/IrxTFmybTKDqtB6obV5jt6ao2I3EQWOhQ0GVfXBuz1SY6Yx7gILQXWsCUeGRu1ltLyywdubpJcw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-sandbox": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-sandbox/-/dsh-sandbox-0.1.0-rc.6.tgz",
+      "integrity": "sha512-SLZjuivQQKHTx4H7xlsjraEGGMIEA8BYOwvlm/9uZBrBrlttMU+d8Ne6QYpDcOwIEubL8mvrWRg8j3rtY3lVyA==",
+      "license": "MIT",
+      "peer": true,
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-sandbox-local": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-sandbox-local/-/dsh-sandbox-local-0.1.0-rc.6.tgz",
+      "integrity": "sha512-W0CehRbWqAaHAYFw24wvYLlGxxJr2OlQQlFH/p1QbeNKtHzZ+6pgjksyFotgHdzOycNnVoBjb92RbQPfJhJZ9A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/dsh-sandbox-windows-acl": "^0.1.0-rc.6",
+        "@deepseek-ai/node-addon-landlock-run": "^0.1.1",
+        "@deepseek-ai/schemastery": "^3.18.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-sandbox": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-sandbox-policy": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-sandbox-policy/-/dsh-sandbox-policy-0.1.0-rc.6.tgz",
+      "integrity": "sha512-XEB7+pJZVPWmZXv27EX/4V/1noVLUF5ZHyy3EY5tC4XtEyayWKtvHL4y9OTLIYhlU4Ualv5ag8s5ueGGq3ID8Q==",
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-sandbox": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-sandbox-windows-acl": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-sandbox-windows-acl/-/dsh-sandbox-windows-acl-0.1.0-rc.6.tgz",
+      "integrity": "sha512-/L1TUOQMsJe8B2v1pJpTaLwkvMQIwrjlUg4+6yx2flU7AyycjFzlKwmzQQzo19/evkiqO88mLgod3FiLhqxEvA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "koffi": "^3.1.0"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-scope": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-scope/-/dsh-scope-0.1.0-rc.6.tgz",
+      "integrity": "sha512-UlDLV4syLoJinNg9imhXrSAHrdaTa5Ff8gg46rzjFJGPUOhAk3DZff0hryT5OhrBi0A5Tj92qVpg2pRVvxnUzQ==",
+      "license": "MIT",
+      "peer": true,
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-session": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-session/-/dsh-session-0.1.0-rc.6.tgz",
+      "integrity": "sha512-8tu8I6VWC7050GAUXWhcEWQw4pakALQc8TlhKr52m7Y4+kIKeNt3FBgP86PaGPBtpK0p5zUPRQNkFpzZbBdxyw==",
+      "license": "MIT",
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-brand": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-scope": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-typert-protocol": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-session-checkpoint-policy": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-session-checkpoint-policy/-/dsh-session-checkpoint-policy-0.1.0-rc.6.tgz",
+      "integrity": "sha512-wdWNyS/95wI3QB9SHeeeQ9HDIWeFQKInI54Wqlw35H+bGGjGZE92nx9QiqiiosoxHedQFBdA0TKgON4EIoxCgg==",
+      "dev": true,
+      "license": "MIT",
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session-persistence": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-session-persistence": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-session-persistence/-/dsh-session-persistence-0.1.0-rc.6.tgz",
+      "integrity": "sha512-AbNBe+IYCbZqSHqOACVdj8QTynm2HZ0cThrEuI6nGMtlWLYLx6lzZ1rgO/56Av9mIScjyTBGJAIKhEYaMTBG9g==",
+      "license": "MIT",
+      "peer": true,
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-brand": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-timeout": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-session-persistence-jsonl": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-session-persistence-jsonl/-/dsh-session-persistence-jsonl-0.1.0-rc.6.tgz",
+      "integrity": "sha512-US9Q4b5CZJPRRqa/M+WESL5VAOLjfYWjdzb3TQ/7zmpR4/+EQWCOFA9CtDSMh4t1oFOQBjz2+YJJcGu59MKHDA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1",
+        "koffi": "^3.1.0"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session-persistence": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-session-projection": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-session-projection/-/dsh-session-projection-0.1.0-rc.6.tgz",
+      "integrity": "sha512-DYLALBPdEI1LZjJ4B6rdGdGY4gy+iR2+5Xh2xJoAGa/pTyN5Z55TNfvuMJrmeRBjAuDXNUQpmURbvos5rJ4veg==",
+      "license": "MIT",
+      "dependencies": {
+        "zod": "^4.4.3"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-session-query": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-session-query/-/dsh-session-query-0.1.0-rc.6.tgz",
+      "integrity": "sha512-bGzRrZnWuXDUtAmwkRxT74Nuc4PLQJmJ4IeGgSSTIGJ9JQCNbvVjr4ZWDWg+D/PvbZwh9mpYJspDZdUP42eWAA==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-brand": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session-persistence": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session-title": "^0.1.0-rc.6"
+      },
+      "peerDependenciesMeta": {
+        "@deepseek-ai/dsh-session-persistence": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-session-query-sqlite": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-session-query-sqlite/-/dsh-session-query-sqlite-0.1.0-rc.6.tgz",
+      "integrity": "sha512-sbeOPAAJetQbvgyFB7zVANSlJPjNgEGxiixin/DI9TcXHcUqq3nrPgS+1iI+WJjD6/zhHdIticeEayuWXtORdA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session-persistence": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session-query": "^0.1.0-rc.6"
+      },
+      "peerDependenciesMeta": {
+        "@deepseek-ai/dsh-session-persistence": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-session-title": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-session-title/-/dsh-session-title-0.1.0-rc.6.tgz",
+      "integrity": "sha512-RHV1ujuomvQB63HPI/n25c2/2It5XQ7zNQKozSqYOPQw7AIr16PT9iFqC7sCQ4l2gAY5GI3FbI1cQgHzjHNOag==",
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1",
+        "zod": "^4.4.3"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-brand": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session-projection": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-settings": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-settings/-/dsh-settings-0.1.0-rc.6.tgz",
+      "integrity": "sha512-5ZlH2FNRU0kkdcCoEJohvdb2fiNnxM+iZqN3icbR3WQbMm8RPRrXlZlps5YUaQKPRbNRHA2LkOXW998QRlhHcA==",
+      "license": "MIT",
+      "peer": true,
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-brand": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/schemastery": "^3.18.1"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-settings-file": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-settings-file/-/dsh-settings-file-0.1.0-rc.6.tgz",
+      "integrity": "sha512-OgwvP/dTlrWd8MRhjJbeolMJHDdyjLtvd+gS3z2mvCGDmNkkf0RxcB/8o2uoqe97iuklTWmy6cCws6dlmnDL+g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1",
+        "chokidar": "^4.0.3",
+        "yaml": "^2.9.0"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-atomic-write": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-settings": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-shell": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-shell/-/dsh-shell-0.1.0-rc.6.tgz",
+      "integrity": "sha512-l/pcwbdpM+Zgp2AzH0kH0z7bPU7L3k4uG1t5Du1V5ilk70tyMSxz2upNfAbjkDHZZZO18LTs33aq+zRWHX1CUg==",
+      "license": "MIT",
+      "peer": true,
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-sandbox": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-subprocess": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-shell-env": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-shell-env/-/dsh-shell-env-0.1.0-rc.6.tgz",
+      "integrity": "sha512-znxHFSqduw8U/AxKSO8SgSt703Bl+irRzTU0ukJT+ySlnyAwSAg8sZHLo5ZlEt5K8BdWhxz8Vc5jibOtJPB3ZQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session-persistence": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-shell": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-skill": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-skill/-/dsh-skill-0.1.0-rc.6.tgz",
+      "integrity": "sha512-VyRlCOASIRuTflKwn4NvbdAXxSPnnLJ+RAQUI4GK5pOtPwI2DhJrbovqpyp5kNAkZMsqvIeHWu5PcCEJ+FpQ2w==",
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-scope": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-skill-filesystem": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-skill-filesystem/-/dsh-skill-filesystem-0.1.0-rc.6.tgz",
+      "integrity": "sha512-NCgz8lCAdvd0oSGIF0EKg1OXfIC7x9r0an7mgC19F0DGzYZJe5ve6AwEYpSvKITE3V8W4NbUzLKyyZG3VH5QtQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1",
+        "chokidar": "^5.0.0",
+        "yaml": "^2.4.2"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-fs": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-skill": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-skill-filesystem/node_modules/chokidar": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-5.0.0.tgz",
+      "integrity": "sha512-TQMmc3w+5AxjpL8iIiwebF73dRDF4fBIieAqGn9RGCWaEVwQ6Fb2cGe31Yns0RRIzii5goJ1Y7xbMwo1TxMplw==",
+      "license": "MIT",
+      "dependencies": {
+        "readdirp": "^5.0.0"
+      },
+      "engines": {
+        "node": ">= 20.19.0"
+      },
+      "funding": {
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-skill-filesystem/node_modules/readdirp": {
+      "version": "5.1.1",
+      "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-5.1.1.tgz",
+      "integrity": "sha512-Kko+Y5XQ6fM+Ce3dq3m9YGxnacYZYl9cA1wZjaF3Vbry2L3i1qVg8+CAgNPsXRArPMUMCaOR7oa9Nqntc43JKA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 20.19.0"
+      },
+      "funding": {
+        "type": "individual",
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-spill": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-spill/-/dsh-spill-0.1.0-rc.6.tgz",
+      "integrity": "sha512-reV4utwd3E5LgiNrsaqh6i6zxHboVyrrL1ilALRukDbMxSyup1vuSRh+4CPxSUh9YcoToFJ6jz2Zmlsw755g1w==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-brand": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-subagent": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-subagent/-/dsh-subagent-0.1.0-rc.6.tgz",
+      "integrity": "sha512-vROmBDAlaFAzzSlTBOlvg/7fO55zxhUztnLtB3lKmN5RevrNQBjTsbeIMDQ8ow5ZplxEOnLU+sikFoA5JaoH8A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "zod": "^4.4.3"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-agent-presets": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-brand": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-jobs": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-sandbox": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-sandbox-policy": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-scope": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session-persistence": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session-projection": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session-projection-cache": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-user-approval": "^0.1.0-rc.6"
+      },
+      "peerDependenciesMeta": {
+        "@deepseek-ai/dsh-agent-presets": {
+          "optional": true
+        },
+        "@deepseek-ai/dsh-jobs": {
+          "optional": true
+        },
+        "@deepseek-ai/dsh-sandbox": {
+          "optional": true
+        },
+        "@deepseek-ai/dsh-sandbox-policy": {
+          "optional": true
+        },
+        "@deepseek-ai/dsh-session-persistence": {
+          "optional": true
+        },
+        "@deepseek-ai/dsh-session-projection": {
+          "optional": true
+        },
+        "@deepseek-ai/dsh-session-projection-cache": {
+          "optional": true
+        },
+        "@deepseek-ai/dsh-user-approval": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-subagent-in-process-driver": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-subagent-in-process-driver/-/dsh-subagent-in-process-driver-0.1.0-rc.6.tgz",
+      "integrity": "sha512-KK8Ep4PeSyrM3YQdcZhetXsiBd+bliKu6NWWKyTh60LobKtVNREfPBlqRfzc0mU0ZIKD4VEC7RfuJaqvz4UlPw==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-subagent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-subagent-spawn-in-process": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-subagent-spawn-in-process/-/dsh-subagent-spawn-in-process-0.1.0-rc.6.tgz",
+      "integrity": "sha512-62mtUEr5megxVy6CwQCdZVq5MCSt+kMw74ns5m7PK0PlZTWcxQVBQHNdfkE9sX4Cageu7YTvciUJuH8amm6bsQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-subagent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-subagent-in-process-driver": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-subprocess": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-subprocess/-/dsh-subprocess-0.1.0-rc.6.tgz",
+      "integrity": "sha512-nZaZRjSnE1he+GAd14vURAH7n3Fw5eGx3nzMbkB96Y6Qx+oQB/7PTuXxKVxlCh8TSfMJTf851ahwWb1eALjKlw==",
+      "license": "MIT",
+      "peer": true,
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-subprocess-local": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-subprocess-local/-/dsh-subprocess-local-0.1.0-rc.6.tgz",
+      "integrity": "sha512-D2daTRaprE25ti1Ra69eURPwLULpnRyUHqAGtcMHddcjNIsZ4yR0DGinYOsgoRymzu3t02qLxyoio05atSViRw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "dependencies": {
+        "node-pty": "^1.1.0"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-subprocess": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-timeout": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-system-prompt": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-system-prompt/-/dsh-system-prompt-0.1.0-rc.6.tgz",
+      "integrity": "sha512-E7g+XChh4q4/wX++v56z1pV4SA1Rtz42xkznLPPi9FlXrrzJxwHMOUzBZ9Rz3Y1kLhQ++HJG3ZatmNx3rjFilg==",
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-scope": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-terminal": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-terminal/-/dsh-terminal-0.1.0-rc.6.tgz",
+      "integrity": "sha512-riHLAQhXJJ2TT9XrDWGMgJf21RBqQgSZdEVvG4+xGEf9NZWcoszxdp+KW7rpwfrKuuD70p8RHCPGW4gCQPA+/A==",
+      "dev": true,
+      "license": "MIT",
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-brand": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-terminal-bash": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-terminal-bash/-/dsh-terminal-bash-0.1.0-rc.6.tgz",
+      "integrity": "sha512-KRR/b/qqKO+sf6yc0xPC64LCZ+SQgTAnEMSO7gNXQ4BeAIzUbeKYfeVYiG6XZRbQ6al6o5sWIbZ0lUt3pHGdXw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-sandbox": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-sandbox-policy": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-subprocess": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-terminal": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-timeout": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-timeout/-/dsh-timeout-0.1.0-rc.6.tgz",
+      "integrity": "sha512-CUean0fAnfsJVszFEip7PsU/S26W+JfDFfsza2dCtlw8n6xlkbHA9Gjxdk2aTwqDGCgXEPkRW7mYkdJ0n6FR7w==",
+      "license": "MIT",
+      "peer": true,
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-token-meter": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-token-meter/-/dsh-token-meter-0.1.0-rc.6.tgz",
+      "integrity": "sha512-qU5FT4n1RJXP3Ss8NJ5TTvPo8rZ6cxcrCedp1t0sTAj93SGssAanq47voSmznPP52nwz/SLeunznAIT0jhbsZQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1",
+        "zod": "^4.4.3"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-compaction": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session-projection": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-tool-bash": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-tool-bash/-/dsh-tool-bash-0.1.0-rc.6.tgz",
+      "integrity": "sha512-yzo/xPCObiFe+OU0e8E5nVOGpW6mp9vx/3q+MHQ0aqEbqrqHUfVMGPobfDAd/I1Ja/9Nag5NIvHpI2Hwx7lACg==",
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-jobs": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-sandbox": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-sandbox-policy": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-shell": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-shell-env": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-user-approval": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-tool-bash-persistent": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-tool-bash-persistent/-/dsh-tool-bash-persistent-0.1.0-rc.6.tgz",
+      "integrity": "sha512-bsM1RHwkpNRAy0zufIDNUWxeiuGngc+R35RZ20gbWM878rHOZVuicy4MG8NKhzqGLqMD4NuDoNfjtDUkZHC48A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-terminal": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-timeout": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-tool-fs": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-tool-fs/-/dsh-tool-fs-0.1.0-rc.6.tgz",
+      "integrity": "sha512-bJfo8cCacX3WBygG8GbIlGz3jQ15MyIv4htGCjKpIIRHrXHSAelNtzceO2xQ21/9BkXrvg+i50mqySOcKQ0b3w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1",
+        "diff": "^9.0.0"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-attachment": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-fs": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-sandbox": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-sandbox-policy": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-user-approval": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-tool-fs-search": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-tool-fs-search/-/dsh-tool-fs-search-0.1.0-rc.6.tgz",
+      "integrity": "sha512-MUu9QF2Du8F6zdFP5rPEti9LKr/IyCYLM24XbaeuZZCrbq6Q1Rf9sng3v5bD9TlT+Wm+uXv3AqPX+8r8gcdqIQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1",
+        "@vscode/ripgrep": "^1.18.0"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-output-retention": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-spill": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-subprocess": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-timeout": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-tool-goal": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-tool-goal/-/dsh-tool-goal-0.1.0-rc.6.tgz",
+      "integrity": "sha512-5rYb1wWJa2HfCxi1JNMkPJwN0upoblJEVlnV+omTx4ZDGekg2dyfftaQdFH9cwiW576is8bAUgPE9Rd0sZCAzw==",
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-goal": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-tool-jobs": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-tool-jobs/-/dsh-tool-jobs-0.1.0-rc.6.tgz",
+      "integrity": "sha512-mcftmyHx2bq8u5Qwo7znysa3vOKO86ccJvgEZqfDV7S+UhOGbPDue7psyx1/jD/5fbK+653JbxQ8ds9wsLkiPw==",
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-jobs": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-output-retention": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-tool-skill": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-tool-skill/-/dsh-tool-skill-0.1.0-rc.6.tgz",
+      "integrity": "sha512-AebSfHSt6j0PXuN3yK9+X4aC6tHSnFdm2hZglII7aEHr/lL9UbynPb3NTumh6thXZ9Earvwhf9JdOxHMsjHqfw==",
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-skill": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-tool-str-replace-editor": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-tool-str-replace-editor/-/dsh-tool-str-replace-editor-0.1.0-rc.6.tgz",
+      "integrity": "sha512-Kv+zA9ZQCn85VLfox2WVvNI/iU6e3ml4gPLqXiKMC027/iwmGHTcRMKOlDNnwydFTJOucNs8wW4Ac3FafCn3gA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-fs": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-sandbox": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-sandbox-policy": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-tool-subagent": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-tool-subagent/-/dsh-tool-subagent-0.1.0-rc.6.tgz",
+      "integrity": "sha512-yK+ETLxDZhtwc19uqv5yAVzq3x/i2hjV9p67Or1a+s9Eqs+eu+ZJJk5hQ/2JeRiJet2otOC4zzOkYb/UVSBFyA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-jobs": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-subagent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-tool-subagent-control": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-tool-subagent-control/-/dsh-tool-subagent-control-0.1.0-rc.6.tgz",
+      "integrity": "sha512-zoVt+uV8yyg1dAuIMydtz/AfARZPkjFOXQLd90a3Bj8GdxpE3tdaR6ZIv3xD39Grxe2vRz4gOZEJ9qth3O+s9g==",
+      "dev": true,
+      "license": "MIT",
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-subagent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-tool-subagent-report": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-tool-subagent-report/-/dsh-tool-subagent-report-0.1.0-rc.6.tgz",
+      "integrity": "sha512-DqnJ6yJ0wO35jdcpCSuogbx/PC4xE8wrcVxXPvSw9I59p/8nROsfwB9UXuJoilp/wenREUoTi0X8+5ZOVSRLqw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-subagent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-tool-todo": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-tool-todo/-/dsh-tool-todo-0.1.0-rc.6.tgz",
+      "integrity": "sha512-ll9xmgkrV6nsxjEZn5+YkNwQei7WrMMisnbr9mAKmqN5vpyOVHXisLvKdiASEmgpm4rsicnR8Y0wcBUfbeJTxA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1",
+        "zod": "^4.4.3"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session-projection": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-tools": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-tools/-/dsh-tools-0.1.0-rc.6.tgz",
+      "integrity": "sha512-Tu08EPK3JyK0iNjH4FGzu/1uADynNSS6SmwOLdfytUN0YNqwNuKFSt2OJUg19famNlTgy992DcHfDu0T+gLXFg==",
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-code-runtime": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-scope": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-user-approval": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-typert-protocol": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-typert-protocol/-/dsh-typert-protocol-0.1.0-rc.6.tgz",
+      "integrity": "sha512-weWzN8r01YCkoDCAM7BsKw2YhRrD4zL8N2SAZu9hovYtXSq8xHXsP4Zh8RLYIlYcuotjyff/6hic+0TJPd14YA==",
+      "license": "MIT",
+      "peer": true,
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/dsh-user-approval": {
+      "version": "0.1.0-rc.6",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/dsh-user-approval/-/dsh-user-approval-0.1.0-rc.6.tgz",
+      "integrity": "sha512-9rnkSDGOpu2XUeGwbPeTzVUTFWTND1PMPM5L/ZQPptV5yyZlQiNxM2rCC6OdL+ZVerwxEqrRhZIQn/KVtQfKag==",
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/schemastery": "^3.18.1"
+      },
+      "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-brand": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-scope": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6"
+      }
+    },
+    "node_modules/@deepseek-ai/node-addon-landlock-run": {
+      "version": "0.1.1",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/node-addon-landlock-run/-/node-addon-landlock-run-0.1.1.tgz",
+      "integrity": "sha512-aHGhlQJEutfobKM/4K59SERbT7RmQdD2oMKzD8Bne/Ps7TeT8AweCN+dpdfuxQhMNbFcJMymrgPnID0WYQ30Tw==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=20"
+      },
+      "optionalDependencies": {
+        "@deepseek-ai/node-addon-landlock-run-linux-arm64": "0.1.1",
+        "@deepseek-ai/node-addon-landlock-run-linux-x64": "0.1.1"
+      }
+    },
+    "node_modules/@deepseek-ai/node-addon-landlock-run-linux-arm64": {
+      "version": "0.1.1",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/node-addon-landlock-run-linux-arm64/-/node-addon-landlock-run-linux-arm64-0.1.1.tgz",
+      "integrity": "sha512-lYY2RbcPW4rGRM5hVJbrXlvLqyBxeJBjBqvt+QTHTU+GtfUVVjTODKa4e3CRwMQoCEpOjoARdQBHbN7HvE72WQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/@deepseek-ai/node-addon-landlock-run-linux-x64": {
+      "version": "0.1.1",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/node-addon-landlock-run-linux-x64/-/node-addon-landlock-run-linux-x64-0.1.1.tgz",
+      "integrity": "sha512-OHAzPW2Coe/iYobAJAAA8CeVrBoKV4BnNHsgwvXwOfishxkUVSWSvdyxrZPiwYRXutpIGVrSo9zV3WOQy2euBA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/@deepseek-ai/schemastery": {
+      "version": "3.18.1",
+      "resolved": "https://registry.npmjs.org/@deepseek-ai/schemastery/-/schemastery-3.18.1.tgz",
+      "integrity": "sha512-Qn0FCSwCQnpnj6SB31I6i2sIKgKWnkbJM8O0EU91Gv2UsYVvtZTl6IA0sCwk2e2MZf5S8w5hpq9QkeVvK9qwxg==",
+      "license": "MIT",
+      "dependencies": {
+        "@deepseek-ai/cosmokit": "^1.8.2",
+        "@standard-schema/spec": "^1.1.0"
+      }
+    },
+    "node_modules/@earendil-works/pi-ai": {
+      "version": "0.82.1",
+      "resolved": "https://registry.npmjs.org/@earendil-works/pi-ai/-/pi-ai-0.82.1.tgz",
+      "integrity": "sha512-3WFYRhEp3lQB3444EhPMBcM7zSaEUE3eJgHOR7s4081NLqbw/FsWilIKWXSua0Gv3sRr7m9xMidR3pPDE7jI/A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@anthropic-ai/sdk": "0.91.1",
+        "@aws-sdk/client-bedrock-runtime": "3.1048.0",
+        "@google/genai": "1.52.0",
+        "@mistralai/mistralai": "2.2.6",
+        "@opentelemetry/api": "1.9.0",
+        "@smithy/node-http-handler": "4.7.3",
+        "http-proxy-agent": "7.0.2",
+        "https-proxy-agent": "7.0.6",
+        "openai": "6.26.0",
+        "partial-json": "0.1.7",
+        "typebox": "1.1.38"
+      },
+      "bin": {
+        "pi-ai": "dist/cli.js"
+      },
+      "engines": {
+        "node": ">=22.19.0"
+      }
+    },
+    "node_modules/@esbuild/aix-ppc64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.25.12.tgz",
+      "integrity": "sha512-Hhmwd6CInZ3dwpuGTF8fJG6yoWmsToE+vYgD4nytZVxcu1ulHpUQRAB1UJ8+N1Am3Mz4+xOByoQoSZf4D+CpkA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.25.12.tgz",
+      "integrity": "sha512-VJ+sKvNA/GE7Ccacc9Cha7bpS8nyzVv0jdVgwNDaR4gDMC/2TTRc33Ip8qrNYUcpkOHUT5OZ0bUcNNVZQ9RLlg==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.25.12.tgz",
+      "integrity": "sha512-6AAmLG7zwD1Z159jCKPvAxZd4y/VTO0VkprYy+3N2FtJ8+BQWFXU+OxARIwA46c5tdD9SsKGZ/1ocqBS/gAKHg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.25.12.tgz",
+      "integrity": "sha512-5jbb+2hhDHx5phYR2By8GTWEzn6I9UqR11Kwf22iKbNpYrsmRB18aX/9ivc5cabcUiAT/wM+YIZ6SG9QO6a8kg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.25.12.tgz",
+      "integrity": "sha512-N3zl+lxHCifgIlcMUP5016ESkeQjLj/959RxxNYIthIg+CQHInujFuXeWbWMgnTo4cp5XVHqFPmpyu9J65C1Yg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.25.12.tgz",
+      "integrity": "sha512-HQ9ka4Kx21qHXwtlTUVbKJOAnmG1ipXhdWTmNXiPzPfWKpXqASVcWdnf2bnL73wgjNrFXAa3yYvBSd9pzfEIpA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.25.12.tgz",
+      "integrity": "sha512-gA0Bx759+7Jve03K1S0vkOu5Lg/85dou3EseOGUes8flVOGxbhDDh/iZaoek11Y8mtyKPGF3vP8XhnkDEAmzeg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.25.12.tgz",
+      "integrity": "sha512-TGbO26Yw2xsHzxtbVFGEXBFH0FRAP7gtcPE7P5yP7wGy7cXK2oO7RyOhL5NLiqTlBh47XhmIUXuGciXEqYFfBQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.25.12.tgz",
+      "integrity": "sha512-lPDGyC1JPDou8kGcywY0YILzWlhhnRjdof3UlcoqYmS9El818LLfJJc3PXXgZHrHCAKs/Z2SeZtDJr5MrkxtOw==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.25.12.tgz",
+      "integrity": "sha512-8bwX7a8FghIgrupcxb4aUmYDLp8pX06rGh5HqDT7bB+8Rdells6mHvrFHHW2JAOPZUbnjUpKTLg6ECyzvas2AQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ia32": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.25.12.tgz",
+      "integrity": "sha512-0y9KrdVnbMM2/vG8KfU0byhUN+EFCny9+8g202gYqSSVMonbsCfLjUO+rCci7pM0WBEtz+oK/PIwHkzxkyharA==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-loong64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.25.12.tgz",
+      "integrity": "sha512-h///Lr5a9rib/v1GGqXVGzjL4TMvVTv+s1DPoxQdz7l/AYv6LDSxdIwzxkrPW438oUXiDtwM10o9PmwS/6Z0Ng==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-mips64el": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.25.12.tgz",
+      "integrity": "sha512-iyRrM1Pzy9GFMDLsXn1iHUm18nhKnNMWscjmp4+hpafcZjrr2WbT//d20xaGljXDBYHqRcl8HnxbX6uaA/eGVw==",
+      "cpu": [
+        "mips64el"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ppc64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.25.12.tgz",
+      "integrity": "sha512-9meM/lRXxMi5PSUqEXRCtVjEZBGwB7P/D4yT8UG/mwIdze2aV4Vo6U5gD3+RsoHXKkHCfSxZKzmDssVlRj1QQA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-riscv64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.25.12.tgz",
+      "integrity": "sha512-Zr7KR4hgKUpWAwb1f3o5ygT04MzqVrGEGXGLnj15YQDJErYu/BGg+wmFlIDOdJp0PmB0lLvxFIOXZgFRrdjR0w==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-s390x": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.25.12.tgz",
+      "integrity": "sha512-MsKncOcgTNvdtiISc/jZs/Zf8d0cl/t3gYWX8J9ubBnVOwlk65UIEEvgBORTiljloIWnBzLs4qhzPkJcitIzIg==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.25.12.tgz",
+      "integrity": "sha512-uqZMTLr/zR/ed4jIGnwSLkaHmPjOjJvnm6TVVitAa08SLS9Z0VM8wIRx7gWbJB5/J54YuIMInDquWyYvQLZkgw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.25.12.tgz",
+      "integrity": "sha512-xXwcTq4GhRM7J9A8Gv5boanHhRa/Q9KLVmcyXHCTaM4wKfIpWkdXiMog/KsnxzJ0A1+nD+zoecuzqPmCRyBGjg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.25.12.tgz",
+      "integrity": "sha512-Ld5pTlzPy3YwGec4OuHh1aCVCRvOXdH8DgRjfDy/oumVovmuSzWfnSJg+VtakB9Cm0gxNO9BzWkj6mtO1FMXkQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.25.12.tgz",
+      "integrity": "sha512-fF96T6KsBo/pkQI950FARU9apGNTSlZGsv1jZBAlcLL1MLjLNIWPBkj5NlSz8aAzYKg+eNqknrUJ24QBybeR5A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.25.12.tgz",
+      "integrity": "sha512-MZyXUkZHjQxUvzK7rN8DJ3SRmrVrke8ZyRusHlP+kuwqTcfWLyqMOE3sScPPyeIXN/mDJIfGXvcMqCgYKekoQw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openharmony-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.25.12.tgz",
+      "integrity": "sha512-rm0YWsqUSRrjncSXGA7Zv78Nbnw4XL6/dzr20cyrQf7ZmRcsovpcRBdhD43Nuk3y7XIoW2OxMVvwuRvk9XdASg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/sunos-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.25.12.tgz",
+      "integrity": "sha512-3wGSCDyuTHQUzt0nV7bocDy72r2lI33QL3gkDNGkod22EsYl04sMf0qLb8luNKTOmgF/eDEDP5BFNwoBKH441w==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.25.12.tgz",
+      "integrity": "sha512-rMmLrur64A7+DKlnSuwqUdRKyd3UE7oPJZmnljqEptesKM8wx9J8gx5u0+9Pq0fQQW8vqeKebwNXdfOyP+8Bsg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-ia32": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.25.12.tgz",
+      "integrity": "sha512-HkqnmmBoCbCwxUKKNPBixiWDGCpQGVsrQfJoVGYLPT41XWF8lHuE5N6WhVia2n4o5QK5M4tYr21827fNhi4byQ==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.25.12.tgz",
+      "integrity": "sha512-alJC0uCZpTFrSL0CCDjcgleBXPnCrEAhTBILpeAp7M/OFgoqtAetfBzX0xM00MUsVVPpVjlPuMbREqnZCXaTnA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@google/genai": {
+      "version": "1.52.0",
+      "resolved": "https://registry.npmjs.org/@google/genai/-/genai-1.52.0.tgz",
+      "integrity": "sha512-gwSvbpiN/17O9TbsqSsE/OzZcpv5Fo4RQjdngGgogtuB9RsyJ8ZHhX5KjHj1bp5N9snN2eK8LDGXSaWW2hof8Q==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "google-auth-library": "^10.3.0",
+        "p-retry": "^4.6.2",
+        "protobufjs": "^7.5.4",
+        "ws": "^8.18.0"
+      },
+      "engines": {
+        "node": ">=20.0.0"
+      },
+      "peerDependencies": {
+        "@modelcontextprotocol/sdk": "^1.25.2"
+      },
+      "peerDependenciesMeta": {
+        "@modelcontextprotocol/sdk": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@jridgewell/sourcemap-codec": {
+      "version": "1.5.5",
+      "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz",
+      "integrity": "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@koromix/koffi-darwin-arm64": {
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/@koromix/koffi-darwin-arm64/-/koffi-darwin-arm64-3.1.5.tgz",
+      "integrity": "sha512-IpqITl2fJi3QN9bTtNnygWPdK7ScSjw3xtGu8e6feYGvimCysu+spgI5KyeslY2jTnqxGS9xr8pLAbLhGJ8edA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "funding": {
+        "url": "https://liberapay.com/Koromix"
+      }
+    },
+    "node_modules/@koromix/koffi-darwin-x64": {
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/@koromix/koffi-darwin-x64/-/koffi-darwin-x64-3.1.5.tgz",
+      "integrity": "sha512-4Tia4BS5EV/+vN9eIrdToanVe+U/2VqTZCBgOzoUbPKjgky51eqM+3J4qdRUvmYJohcJNPob5/hsxeItUZrl1g==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "funding": {
+        "url": "https://liberapay.com/Koromix"
+      }
+    },
+    "node_modules/@koromix/koffi-freebsd-arm64": {
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/@koromix/koffi-freebsd-arm64/-/koffi-freebsd-arm64-3.1.5.tgz",
+      "integrity": "sha512-bP94uzseFO79NG3flpU3WxfyvltD+jzC/kN8FDZLi8J0VUZNW1Wmu8yq87KEzjX1qT9KyX4Y+elVbGqHXHTv2Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "funding": {
+        "url": "https://liberapay.com/Koromix"
+      }
+    },
+    "node_modules/@koromix/koffi-freebsd-ia32": {
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/@koromix/koffi-freebsd-ia32/-/koffi-freebsd-ia32-3.1.5.tgz",
+      "integrity": "sha512-raFXXAPHzvCQWhaoMUF+Cc2ZWgg2UBU0RVoowHZhaw9nQYPC1pERcPRH+JA+SNIN6g4d2GFW6uPFc+QbUhsagA==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "funding": {
+        "url": "https://liberapay.com/Koromix"
+      }
+    },
+    "node_modules/@koromix/koffi-freebsd-x64": {
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/@koromix/koffi-freebsd-x64/-/koffi-freebsd-x64-3.1.5.tgz",
+      "integrity": "sha512-h6RyBZmPMBIDWTABkJIhzDdYwSnYAJvTacHpEjbT55Arkmw1H15Rl7CFtXuEuBrqh+uivoCrRgA6vszl9CsJ9g==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "funding": {
+        "url": "https://liberapay.com/Koromix"
+      }
+    },
+    "node_modules/@koromix/koffi-linux-arm64": {
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/@koromix/koffi-linux-arm64/-/koffi-linux-arm64-3.1.5.tgz",
+      "integrity": "sha512-u0vCmKPu4yQDhl/ri1J6U3vDnvYtYjoZaIWb+oMbRXhVZeiqdE53MGPb+q2A7Dj2n9IbYloAfEICQbL6l0pmiQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://liberapay.com/Koromix"
+      }
+    },
+    "node_modules/@koromix/koffi-linux-ia32": {
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/@koromix/koffi-linux-ia32/-/koffi-linux-ia32-3.1.5.tgz",
+      "integrity": "sha512-Xa5JbumWglwPVZgrJcLhqyC1wCWlfm7+C00p3FuOTNGp0qoYuf2/tOoAh0/q7+taVm30cMopu/6lRHwdmF6I/w==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://liberapay.com/Koromix"
+      }
+    },
+    "node_modules/@koromix/koffi-linux-loong64": {
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/@koromix/koffi-linux-loong64/-/koffi-linux-loong64-3.1.5.tgz",
+      "integrity": "sha512-F3i2CeTcqVBUQiSRUBSEzX1VgtXmLLiZb/ouZtXHkWpTLhJNd9TH7s3CizTofci0VRqlKdexGUYhK5vzPDAAHA==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://liberapay.com/Koromix"
+      }
+    },
+    "node_modules/@koromix/koffi-linux-riscv64": {
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/@koromix/koffi-linux-riscv64/-/koffi-linux-riscv64-3.1.5.tgz",
+      "integrity": "sha512-2TgQuzy+4PfDg+rw3kOmN6lywEWdzKT3eaLPbOp0b/9DaN7CLBJ/QIR5GhGsMNpeI30zU0YzFeYFxoVoJ/LqFw==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://liberapay.com/Koromix"
+      }
+    },
+    "node_modules/@koromix/koffi-linux-x64": {
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/@koromix/koffi-linux-x64/-/koffi-linux-x64-3.1.5.tgz",
+      "integrity": "sha512-2yaIg/1V0m4CiAUMzG4CIlWmq1WJ+QBMlFfaGr9su+OH5fuIqC7V3BbMiB03IwIl1VofIZO5JA4Db4lID8tpbw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://liberapay.com/Koromix"
+      }
+    },
+    "node_modules/@koromix/koffi-openbsd-ia32": {
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/@koromix/koffi-openbsd-ia32/-/koffi-openbsd-ia32-3.1.5.tgz",
+      "integrity": "sha512-8/OXd+u9omMooykhvdJPEP7u6FFzzrrFo9gOmSHc9/DPt3XkVYOtSsE97PDk6zYaAzwIYHSKjHvIXsfFwFc7sg==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "funding": {
+        "url": "https://liberapay.com/Koromix"
+      }
+    },
+    "node_modules/@koromix/koffi-openbsd-x64": {
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/@koromix/koffi-openbsd-x64/-/koffi-openbsd-x64-3.1.5.tgz",
+      "integrity": "sha512-SpeqldKkuDk2aTj5PVWumy7eq6Tr2GtBPAOI1NiDHhg8xe433KraxrA9V9UjEd+1+kSGJQGR04nQByN3MPA9PQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "funding": {
+        "url": "https://liberapay.com/Koromix"
+      }
+    },
+    "node_modules/@koromix/koffi-win32-arm64": {
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/@koromix/koffi-win32-arm64/-/koffi-win32-arm64-3.1.5.tgz",
+      "integrity": "sha512-uej3YAEKAhlfVPoIo5sOwtxhTLRVJ01LgtWrKGpnnAQU3C+Ilmaxdh+Oc2xc1G3NK30N5eCVJpyO9r3pjKC6Vw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "funding": {
+        "url": "https://liberapay.com/Koromix"
+      }
+    },
+    "node_modules/@koromix/koffi-win32-ia32": {
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/@koromix/koffi-win32-ia32/-/koffi-win32-ia32-3.1.5.tgz",
+      "integrity": "sha512-d42jv2f4PwtJGNJS19Xfn/BRtGsBNNVkw0O0K5tkIGI+yNq4MnPTSUsaGbDIkCLNsCgk/LFqAaE8BExyCdrujA==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "funding": {
+        "url": "https://liberapay.com/Koromix"
+      }
+    },
+    "node_modules/@koromix/koffi-win32-x64": {
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/@koromix/koffi-win32-x64/-/koffi-win32-x64-3.1.5.tgz",
+      "integrity": "sha512-Pyo1WEHEP6Ek2NEn2pquwJzSPLOdY4vymoPSz0an1DgvFWSkOyBYYkGVoxL1ajfj5I1pPdXysYqixtVTzAtOfQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "funding": {
+        "url": "https://liberapay.com/Koromix"
+      }
+    },
+    "node_modules/@mistralai/mistralai": {
+      "version": "2.2.6",
+      "resolved": "https://registry.npmjs.org/@mistralai/mistralai/-/mistralai-2.2.6.tgz",
+      "integrity": "sha512-W8pX7zHxjJvMIpw8JMxeJEleapXX0Q9NPszdNzqkM3MIEoIGPObdodujj+WHteXEvGfaP/AMwlNyRfEzSY6dQQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@opentelemetry/semantic-conventions": "^1.40.0",
+        "ws": "^8.18.0",
+        "zod": "^3.25.0 || ^4.0.0",
+        "zod-to-json-schema": "^3.25.0"
+      },
+      "peerDependencies": {
+        "@opentelemetry/api": "^1.9.0"
+      },
+      "peerDependenciesMeta": {
+        "@opentelemetry/api": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@napi-rs/lzma-linux-x64-gnu": {
+      "version": "1.5.1",
+      "resolved": "https://registry.npmjs.org/@napi-rs/lzma-linux-x64-gnu/-/lzma-linux-x64-gnu-1.5.1.tgz",
+      "integrity": "sha512-oTXEIha4SsuXdTA4Iyskj0kpdx2yVXdhd75c2v3xGrHFfVMsbhTPZU/nMPL4sWKo4pBHm3aucLaqGlF696dTyQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^22.20 || ^24.12 || >=25"
+      }
+    },
+    "node_modules/@opentelemetry/api": {
+      "version": "1.9.0",
+      "resolved": "https://registry.npmjs.org/@opentelemetry/api/-/api-1.9.0.tgz",
+      "integrity": "sha512-3giAOQvZiH5F9bMlMiv8+GSPMeqg0dbaeo58/0SlA9sxSqZhnUtxzX9/2FzyhS9sWQf5S0GJE0AKBrFqjpeYcg==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=8.0.0"
+      }
+    },
+    "node_modules/@opentelemetry/semantic-conventions": {
+      "version": "1.43.0",
+      "resolved": "https://registry.npmjs.org/@opentelemetry/semantic-conventions/-/semantic-conventions-1.43.0.tgz",
+      "integrity": "sha512-eSYWTm620tTk45EKSedaUL8MFYI8hW164hIXsgIHyxu3VobUB3fFCu5t0hQby6OoWRPsG1KkKUG2M5UadiLiVg==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=14"
+      }
+    },
+    "node_modules/@protobufjs/aspromise": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/@protobufjs/aspromise/-/aspromise-1.1.2.tgz",
+      "integrity": "sha512-j+gKExEuLmKwvz3OgROXtrJ2UG2x8Ch2YZUxahh+s1F2HZ+wAceUNLkvy6zKCPVRkU++ZWQrdxsUeQXmcg4uoQ==",
+      "dev": true,
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@protobufjs/base64": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/@protobufjs/base64/-/base64-1.1.2.tgz",
+      "integrity": "sha512-AZkcAA5vnN/v4PDqKyMR5lx7hZttPDgClv83E//FMNhR2TMcLUhfRUBHCmSl0oi9zMgDDqRUJkSxO3wm85+XLg==",
+      "dev": true,
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@protobufjs/codegen": {
+      "version": "2.0.5",
+      "resolved": "https://registry.npmjs.org/@protobufjs/codegen/-/codegen-2.0.5.tgz",
+      "integrity": "sha512-zgXFLzW3Ap33e6d0Wlj4MGIm6Ce8O89n/apUaGNB/jx+hw+ruWEp7EwGUshdLKVRCxZW12fp9r40E1mQrf/34g==",
+      "dev": true,
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@protobufjs/eventemitter": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/@protobufjs/eventemitter/-/eventemitter-1.1.1.tgz",
+      "integrity": "sha512-vW1GmwMZNnL+gMRaovlh9yZX74kc+TTU3FObkkurpMaRtBfLP3ldjS9KQWlwZgraRE0+dheEEoAxdzcJQ8eXZg==",
+      "dev": true,
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@protobufjs/fetch": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/@protobufjs/fetch/-/fetch-1.1.1.tgz",
+      "integrity": "sha512-GpptLrs57adMSuHi3VNj0mAF8dwh36LMaYF6XyJ6JMWlVsc+t42tm1HSEDmOs3A8fC9yyeisgLhsTVQokOZ0zw==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "@protobufjs/aspromise": "^1.1.1"
+      }
+    },
+    "node_modules/@protobufjs/float": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/@protobufjs/float/-/float-1.0.2.tgz",
+      "integrity": "sha512-Ddb+kVXlXst9d+R9PfTIxh1EdNkgoRe5tOX6t01f1lYWOvJnSPDBlG241QLzcyPdoNTsblLUdujGSE4RzrTZGQ==",
+      "dev": true,
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@protobufjs/path": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/@protobufjs/path/-/path-1.1.2.tgz",
+      "integrity": "sha512-6JOcJ5Tm08dOHAbdR3GrvP+yUUfkjG5ePsHYczMFLq3ZmMkAD98cDgcT2iA1lJ9NVwFd4tH/iSSoe44YWkltEA==",
+      "dev": true,
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@protobufjs/pool": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/@protobufjs/pool/-/pool-1.1.0.tgz",
+      "integrity": "sha512-0kELaGSIDBKvcgS4zkjz1PeddatrjYcmMWOlAuAPwAeccUrPHdUqo/J6LiymHHEiJT5NrF1UVwxY14f+fy4WQw==",
+      "dev": true,
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@protobufjs/utf8": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/@protobufjs/utf8/-/utf8-1.1.2.tgz",
+      "integrity": "sha512-b1UQwcEZ4yCnMCD8DAL1VlbvBJE9/IX4FTIp7BG1xYpf29SLazLSrqUkj4w7Y5y7cCVP6E5tcqqcI0xemPkHug==",
+      "dev": true,
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@rollup/rollup-android-arm-eabi": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.62.4.tgz",
+      "integrity": "sha512-RrPokAb7dmbxFoeO3TloqHyOjgye8RkBhSqmp4aJMIex4c9r46ZstPnleDQOq1t46VOVjwIuwNogIqbodV1Vvg==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ]
+    },
+    "node_modules/@rollup/rollup-android-arm64": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.62.4.tgz",
+      "integrity": "sha512-JKuJc+pnpks2pjy7L/N3v/cAkZxYlnmuZoD840ldbMI5KDbC4iO9NKwPKYdjYFCMAIIlBzYSFHxIJVYzRo2/8A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ]
+    },
+    "node_modules/@rollup/rollup-darwin-arm64": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.62.4.tgz",
+      "integrity": "sha512-krw5uS2STmvJ02x0uTXHbqQNuz+9eZ1iw+qXk9dmW2gvV4jV7O2hEoOnuhFrpOPiel1mBFtqbxYZZtC46hXLOw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@rollup/rollup-darwin-x64": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.62.4.tgz",
+      "integrity": "sha512-wsTxtgApb4PrOsNJIm0FZ1h3WvCC+k9uxLJ4ad75hgoS4NiRes2SoJFlDAyMwiUY8IssDqGcHbXuN0sx1tfF1A==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@rollup/rollup-freebsd-arm64": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.62.4.tgz",
+      "integrity": "sha512-GUOnQlyZe3yAXhWOtOMsn5Qkrv5E5mZXa0thbARWi5Ei2szlVXJFQhddZ4HbAzh8q92w5twp+CQvs/eFanz9YQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ]
+    },
+    "node_modules/@rollup/rollup-freebsd-x64": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.62.4.tgz",
+      "integrity": "sha512-/Y7f3QuxjzPKsjA/rfEDa3+0vXqyjmJ50Ln8dPpCmWkKTrUoWHG1cWhTqaAMLob2m2nESWuC7yGrREz019Ztqg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm-gnueabihf": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.62.4.tgz",
+      "integrity": "sha512-81wiiX3v7aqy+T+bT61TJ78yJjRquqFFTTbAPt08imfQQzkPIW8t6aJbkTagtCCrXMNc9D66+geqlK7ydLPNqA==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm-musleabihf": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.62.4.tgz",
+      "integrity": "sha512-9kmDIvNZqdoHOBZgNtpTBeLWYO/LVipM3H/j62P8848/l/VPEQL6N3uxU9pvP1oZAsXyC2MEnFP3ovRjo7WYNQ==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm64-gnu": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.62.4.tgz",
+      "integrity": "sha512-CcnXHWnXg69g+DX5VWL3FHts3qMRN2uVEHX+BZvGLdd07/gXkn3ePjYtO1LDJvxkGKVHMclKBRa1QUTH+6toYQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm64-musl": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.62.4.tgz",
+      "integrity": "sha512-iFOibiHnTRuhrWLlRsOQFdZJJIa7S8OwkneJr4ocALP16u5yk6lWLINFwhHaEqBFMsKDUZofLkGos7+CPzGB3g==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-loong64-gnu": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.62.4.tgz",
+      "integrity": "sha512-XnWYMI7euHlb5a871xPja+Gm7DRCFU+FGRrtS2sMq9N8FvqtpagUy6gD4YOemC5MRk9xbh8+jYMEJbigFQwsgA==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-loong64-musl": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.62.4.tgz",
+      "integrity": "sha512-qGDAlO0U8xedCcsdRm9oaoQY8DAx/QT7uIxJWhCdx0ceIWX783UC9QSYkdpzAe29wNiVfp24+bZdQmn49o45SQ==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-ppc64-gnu": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.62.4.tgz",
+      "integrity": "sha512-ru4H6ezD7ysA5EiEK6qkkaEb4modH8CTej6kUy/gQi20u3kB3G7Zn8snXXkeJSCOFKG/rbPPtM/+9Wgas1961w==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-ppc64-musl": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.62.4.tgz",
+      "integrity": "sha512-2W4MO5WQVJnbJaZdvDb9rhBDuFU1nKIepPFpJUBsTh2k1YY2g+ODViaWuyOAjQ5cOP7NvrvLzt3wvHOoiAvc7w==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-riscv64-gnu": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.62.4.tgz",
+      "integrity": "sha512-+fxjfuoAmVMCYV5QyjoIpu0cp5DOiOTeqYFk1AVaxGr+/ravWLX89XfQmptsoWcaVy/TGf2hexzbUOrCQIL1CQ==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-riscv64-musl": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.62.4.tgz",
+      "integrity": "sha512-jTn8JfHGL4djjFxPuM06LmNUJDsst2jeVlsd9OmIH6zc5sC9K6rIuO4YajXatLUpBmBKl6b35ro1QZocLi+tcA==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-s390x-gnu": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.62.4.tgz",
+      "integrity": "sha512-oCJCJL4pXsoDcP2QZ+JVlPTIRc6266zsIaeJJsWImmF7HO0W8nb6HuSgZlMWxJwaPf8ehbSw8yo0EUw925hKsA==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-x64-gnu": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.62.4.tgz",
+      "integrity": "sha512-W69hukhZ3KKNRCaMIEzKvcFye42hh0FE1+YoYaf5+Ikacuftoco6yO/xouz0hc5d5W/s3yBro5jRiuEE/Q5vUw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-x64-musl": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.62.4.tgz",
+      "integrity": "sha512-qiXbGG2jkjXhzXpsFZSR2Xpb8DN/UaxYsbb/STbuR/6fpaDgRmmaq1B/LmtF2wQFOFOSsK2jdE0RZ3a0zHn4QA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-openbsd-x64": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.62.4.tgz",
+      "integrity": "sha512-nWeM//hxv8mIo6jD7Hu4o48DVmV9pbV6gsKaWU+4NFyqHoPKwrkRiZGLKUhOBk8qNmDmpwFtPKg80Bo/Tn4xiQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ]
+    },
+    "node_modules/@rollup/rollup-openharmony-arm64": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.62.4.tgz",
+      "integrity": "sha512-s62SQ/vgsRSvMwDkOEfTqfgASF0f26ZNaQuTA6Aok5lrikf89yI2W0gFHvZb2Jpgc6N8JnOKZgCK2iciO3CsxQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-arm64-msvc": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.62.4.tgz",
+      "integrity": "sha512-J6wGf8TVGbXJq+HH+ttTvrcfNKPbuZecV6KT1B8I18BC5IURUh5kl4Yl5OEP5eFIUoI5BWxCsyYMhFsDx8kekw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-ia32-msvc": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.62.4.tgz",
+      "integrity": "sha512-zmfrQd/0wu6oJs8Vq8KwY/YtsKSsLtKe/HwAP4Wqy8LhWjeT55fHRAkOhYQ12wI3ayS4Tt12d5CDRD7N96SAYQ==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-x64-gnu": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.62.4.tgz",
+      "integrity": "sha512-qPzHqdj9rfUD+w79dtE07zi/kFwKyCJqplp5K5ygeLTp7jLpAoc16OAH39HSmRC9UpozaecsleI8uAdEj6v2yw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-x64-msvc": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.62.4.tgz",
+      "integrity": "sha512-zD6NdeWEByGE9QF9vCrlJ5YQB4oq9q91kPZS37Jwj5hOkvR1lTBSpsKhKDw4IJtbQ35LsTS1HD9DZYGKIshU1Q==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@smithy/core": {
+      "version": "3.33.0",
+      "resolved": "https://registry.npmjs.org/@smithy/core/-/core-3.33.0.tgz",
+      "integrity": "sha512-uKbkxgqLyepQDZoq8aRSdUqD1ID//rOqG96ixBhp++O7vBtmwYM6fwldGhr9HJP0iYrdc7GP/AlgzPWEZIrNRg==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@smithy/types": "^4.17.0",
+        "tslib": "^2.6.2"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      }
+    },
+    "node_modules/@smithy/credential-provider-imds": {
+      "version": "4.5.0",
+      "resolved": "https://registry.npmjs.org/@smithy/credential-provider-imds/-/credential-provider-imds-4.5.0.tgz",
+      "integrity": "sha512-2jsPi+7Zv2hSzD9IXR9D7DTqSn7mv4XalzRm+bESh53jiaUS3NKEUbpQFTJP0HhQy9qzZvluxQ3yS24zdRrqsA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@smithy/core": "^3.32.0",
+        "@smithy/types": "^4.17.0",
+        "tslib": "^2.6.2"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      }
+    },
+    "node_modules/@smithy/fetch-http-handler": {
+      "version": "5.7.0",
+      "resolved": "https://registry.npmjs.org/@smithy/fetch-http-handler/-/fetch-http-handler-5.7.0.tgz",
+      "integrity": "sha512-W/exA8T0LEzCQtJ02w4IzaEQPIspgarqZprb7W8FwnYiDowgCrjl2fTQ6FvuSSUnJORuepBF81abmBJwqh+0XQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@smithy/core": "^3.32.0",
+        "@smithy/types": "^4.17.0",
+        "tslib": "^2.6.2"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      }
+    },
+    "node_modules/@smithy/is-array-buffer": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/@smithy/is-array-buffer/-/is-array-buffer-2.2.0.tgz",
+      "integrity": "sha512-GGP3O9QFD24uGeAXYUjwSTXARoqpZykHadOmA8G5vfJPK0/DC67qa//0qvqrJzL1xc8WQWX7/yc7fwudjPHPhA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "tslib": "^2.6.2"
+      },
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
+    "node_modules/@smithy/node-http-handler": {
+      "version": "4.7.3",
+      "resolved": "https://registry.npmjs.org/@smithy/node-http-handler/-/node-http-handler-4.7.3.tgz",
+      "integrity": "sha512-/jPhevcTFPMVl6KNjbaI47iOg1zxC7IsnX4PQDGVZKMFceOXtB8IEYaB7a9VvkP/3oC60WzTeKocvSI7vLT0vA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@smithy/core": "^3.24.3",
+        "@smithy/types": "^4.14.2",
+        "tslib": "^2.6.2"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      }
+    },
+    "node_modules/@smithy/signature-v4": {
+      "version": "5.7.0",
+      "resolved": "https://registry.npmjs.org/@smithy/signature-v4/-/signature-v4-5.7.0.tgz",
+      "integrity": "sha512-hCynhm22wMJ8wTF9crcwu8mxggtUrSLLJgDcGUvYFBqpofxycYJCGKOMYg4xtPPFtgNiDJSYmhsWLTrcU/g59Q==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@smithy/core": "^3.32.0",
+        "@smithy/types": "^4.17.0",
+        "tslib": "^2.6.2"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      }
+    },
+    "node_modules/@smithy/types": {
+      "version": "4.17.0",
+      "resolved": "https://registry.npmjs.org/@smithy/types/-/types-4.17.0.tgz",
+      "integrity": "sha512-Aw4joiM0ZdErpo39lCj8phT2lxoiKZV+KZzBxnnQhWVtU2Is/WffQSL04uUWRcXUse9Ln8vXZK6V/FwqRVnQpg==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "tslib": "^2.6.2"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      }
+    },
+    "node_modules/@smithy/util-buffer-from": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/@smithy/util-buffer-from/-/util-buffer-from-2.2.0.tgz",
+      "integrity": "sha512-IJdWBbTcMQ6DA0gdNhh/BwrLkDR+ADW5Kr1aZmd4k3DIF6ezMV4R2NIAmT08wQJ3yUK82thHWmC/TnK/wpMMIA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@smithy/is-array-buffer": "^2.2.0",
+        "tslib": "^2.6.2"
+      },
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
+    "node_modules/@smithy/util-utf8": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/@smithy/util-utf8/-/util-utf8-2.3.0.tgz",
+      "integrity": "sha512-R8Rdn8Hy72KKcebgLiv8jQcQkXoLMOGGv5uI1/k0l+snqkOzQ1R0ChUBCxWMlBsFMekWjq0wRudIweFs7sKT5A==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@smithy/util-buffer-from": "^2.2.0",
+        "tslib": "^2.6.2"
+      },
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
+    "node_modules/@standard-schema/spec": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/@standard-schema/spec/-/spec-1.1.0.tgz",
+      "integrity": "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==",
+      "license": "MIT"
+    },
+    "node_modules/@types/chai": {
+      "version": "5.2.3",
+      "resolved": "https://registry.npmjs.org/@types/chai/-/chai-5.2.3.tgz",
+      "integrity": "sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/deep-eql": "*",
+        "assertion-error": "^2.0.1"
+      }
+    },
+    "node_modules/@types/deep-eql": {
+      "version": "4.0.2",
+      "resolved": "https://registry.npmjs.org/@types/deep-eql/-/deep-eql-4.0.2.tgz",
+      "integrity": "sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@types/estree": {
+      "version": "1.0.9",
+      "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.9.tgz",
+      "integrity": "sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@types/node": {
+      "version": "26.2.0",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-26.2.0.tgz",
+      "integrity": "sha512-5IviulTZeRNp2vAJ514cc/HUlY5nZ9fCbq9DMyC52BrhFZACo3nI0R7qBxhQmo/d27NFe96ur/b7Wwxklda+kg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~8.3.0"
+      }
+    },
+    "node_modules/@types/retry": {
+      "version": "0.12.0",
+      "resolved": "https://registry.npmjs.org/@types/retry/-/retry-0.12.0.tgz",
+      "integrity": "sha512-wWKOClTTiizcZhXnPY4wikVAwmdYHp8q6DmC+EJUzAMsycb7HB32Kh9RN4+0gExjmPmZSAQjgURXIGATPegAvA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@vitest/expect": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-3.2.4.tgz",
+      "integrity": "sha512-Io0yyORnB6sikFlt8QW5K7slY4OjqNX9jmJQ02QDda8lyM6B5oNgVWoSoKPac8/kgnCUzuHQKrSLtu/uOqqrig==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/chai": "^5.2.2",
+        "@vitest/spy": "3.2.4",
+        "@vitest/utils": "3.2.4",
+        "chai": "^5.2.0",
+        "tinyrainbow": "^2.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/mocker": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-3.2.4.tgz",
+      "integrity": "sha512-46ryTE9RZO/rfDd7pEqFl7etuyzekzEhUbTW3BvmeO/BcCMEgq59BKhek3dXDWgAj4oMK6OZi+vRr1wPW6qjEQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/spy": "3.2.4",
+        "estree-walker": "^3.0.3",
+        "magic-string": "^0.30.17"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "msw": "^2.4.9",
+        "vite": "^5.0.0 || ^6.0.0 || ^7.0.0-0"
+      },
+      "peerDependenciesMeta": {
+        "msw": {
+          "optional": true
+        },
+        "vite": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@vitest/pretty-format": {
+      "version": "3.2.7",
+      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-3.2.7.tgz",
+      "integrity": "sha512-KUHlwqVu0sRlhCdyPdQ/wBoTfRahjUky1MubOmYw9fWfIZy1gNoHpuaaQBPAaMaVYdQYHJLurzj8ECCj5OwTqA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tinyrainbow": "^2.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/runner": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-3.2.4.tgz",
+      "integrity": "sha512-oukfKT9Mk41LreEW09vt45f8wx7DordoWUZMYdY/cyAk7w5TWkTRCNZYF7sX7n2wB7jyGAl74OxgwhPgKaqDMQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/utils": "3.2.4",
+        "pathe": "^2.0.3",
+        "strip-literal": "^3.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/snapshot": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-3.2.4.tgz",
+      "integrity": "sha512-dEYtS7qQP2CjU27QBC5oUOxLE/v5eLkGqPE0ZKEIDGMs4vKWe7IjgLOeauHsR0D5YuuycGRO5oSRXnwnmA78fQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/pretty-format": "3.2.4",
+        "magic-string": "^0.30.17",
+        "pathe": "^2.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/snapshot/node_modules/@vitest/pretty-format": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-3.2.4.tgz",
+      "integrity": "sha512-IVNZik8IVRJRTr9fxlitMKeJeXFFFN0JaB9PHPGQ8NKQbGpfjlTx9zO4RefN8gp7eqjNy8nyK3NZmBzOPeIxtA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tinyrainbow": "^2.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/spy": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-3.2.4.tgz",
+      "integrity": "sha512-vAfasCOe6AIK70iP5UD11Ac4siNUNJ9i/9PZ3NKx07sG6sUxeag1LWdNrMWeKKYBLlzuK+Gn65Yd5nyL6ds+nw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tinyspy": "^4.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/utils": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-3.2.4.tgz",
+      "integrity": "sha512-fB2V0JFrQSMsCo9HiSq3Ezpdv4iYaXRG1Sx8edX3MwxfyNn83mKiGzOcH+Fkxt4MHxr3y42fQi1oeAInqgX2QA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/pretty-format": "3.2.4",
+        "loupe": "^3.1.4",
+        "tinyrainbow": "^2.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/utils/node_modules/@vitest/pretty-format": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-3.2.4.tgz",
+      "integrity": "sha512-IVNZik8IVRJRTr9fxlitMKeJeXFFFN0JaB9PHPGQ8NKQbGpfjlTx9zO4RefN8gp7eqjNy8nyK3NZmBzOPeIxtA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tinyrainbow": "^2.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vscode/ripgrep": {
+      "version": "1.18.0",
+      "resolved": "https://registry.npmjs.org/@vscode/ripgrep/-/ripgrep-1.18.0.tgz",
+      "integrity": "sha512-ns5lWe44tSfbTMbVUsyB+I1819PVSw4AdpgK0RNkzfWfwy6+3IUNSxwSrfTno1/oWaS/hERNz+XLWVyga2aJBQ==",
+      "dev": true,
+      "license": "MIT",
+      "optionalDependencies": {
+        "@vscode/ripgrep-darwin-arm64": "1.18.0",
+        "@vscode/ripgrep-darwin-x64": "1.18.0",
+        "@vscode/ripgrep-linux-arm": "1.18.0",
+        "@vscode/ripgrep-linux-arm64": "1.18.0",
+        "@vscode/ripgrep-linux-ia32": "1.18.0",
+        "@vscode/ripgrep-linux-ppc64": "1.18.0",
+        "@vscode/ripgrep-linux-riscv64": "1.18.0",
+        "@vscode/ripgrep-linux-s390x": "1.18.0",
+        "@vscode/ripgrep-linux-x64": "1.18.0",
+        "@vscode/ripgrep-win32-arm64": "1.18.0",
+        "@vscode/ripgrep-win32-ia32": "1.18.0",
+        "@vscode/ripgrep-win32-x64": "1.18.0"
+      }
+    },
+    "node_modules/@vscode/ripgrep-darwin-arm64": {
+      "version": "1.18.0",
+      "resolved": "https://registry.npmjs.org/@vscode/ripgrep-darwin-arm64/-/ripgrep-darwin-arm64-1.18.0.tgz",
+      "integrity": "sha512-r3ktHSvbFycQNF6sl7sNDPocpsI7J+mEzh1IaZFkY0spm3k2Z9t8hPAeOK7+p0l6p6/swkQC14XWX01low+94Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@vscode/ripgrep-darwin-x64": {
+      "version": "1.18.0",
+      "resolved": "https://registry.npmjs.org/@vscode/ripgrep-darwin-x64/-/ripgrep-darwin-x64-1.18.0.tgz",
+      "integrity": "sha512-25b4gWbL138dGuQU244ebCKKc0q05ULBMoFSz9oAEUHNeqK/lOJViDS7DRvbDazzAzSEdan391Znks/R5mkaTQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@vscode/ripgrep-linux-arm": {
+      "version": "1.18.0",
+      "resolved": "https://registry.npmjs.org/@vscode/ripgrep-linux-arm/-/ripgrep-linux-arm-1.18.0.tgz",
+      "integrity": "sha512-GDAvufNDHu8zqLEmXstalQF0Wh6wQvdsBi/Vg3Yi3CK4a8XoFXqqXVEHEZ9xQz3t0NfoSEc9JbvK9DDS6FxyxQ==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@vscode/ripgrep-linux-arm64": {
+      "version": "1.18.0",
+      "resolved": "https://registry.npmjs.org/@vscode/ripgrep-linux-arm64/-/ripgrep-linux-arm64-1.18.0.tgz",
+      "integrity": "sha512-lQ/5zTG++U0E3IhVgS4EPTTn/U4okncaRMM5GOFfOYZywS4nuD31GhkHbNYlDk5CuDC68+hYJ0/eQeyCKJDA+g==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@vscode/ripgrep-linux-ia32": {
+      "version": "1.18.0",
+      "resolved": "https://registry.npmjs.org/@vscode/ripgrep-linux-ia32/-/ripgrep-linux-ia32-1.18.0.tgz",
+      "integrity": "sha512-YWLkSUtFd4Jh5EepIhA9RJSfv3uMAVMo+2rBIGHPBnvgLrZciIs2cDKei1/p6Wc/aCzUoHyMAg2R6tw4ZCBKGg==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@vscode/ripgrep-linux-ppc64": {
+      "version": "1.18.0",
+      "resolved": "https://registry.npmjs.org/@vscode/ripgrep-linux-ppc64/-/ripgrep-linux-ppc64-1.18.0.tgz",
+      "integrity": "sha512-quXVY8fwQ8O/lvU1yrSqSl3jlUzysRSb+AfUfCL/tRtphxsKlFvPAejryZ6vg4Bgvn8XL74xb4qMCDmWgYrT5w==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@vscode/ripgrep-linux-riscv64": {
+      "version": "1.18.0",
+      "resolved": "https://registry.npmjs.org/@vscode/ripgrep-linux-riscv64/-/ripgrep-linux-riscv64-1.18.0.tgz",
+      "integrity": "sha512-f5kBQBrWfQt8Q7OhSORuNDei5dkYagBj3y4jImSUXGMy8B/Ke7SltSRcUtjPv166FAFfHCAmWuZp3+cWnX2/Vw==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@vscode/ripgrep-linux-s390x": {
+      "version": "1.18.0",
+      "resolved": "https://registry.npmjs.org/@vscode/ripgrep-linux-s390x/-/ripgrep-linux-s390x-1.18.0.tgz",
+      "integrity": "sha512-rTOcJFGGcl2c07RUOWUo4U1ndnemKhY6A9hnMB18uk7jSgJc0d/QLBGWMWpumdtoJtpizn/wIv5mXIisJukusQ==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@vscode/ripgrep-linux-x64": {
+      "version": "1.18.0",
+      "resolved": "https://registry.npmjs.org/@vscode/ripgrep-linux-x64/-/ripgrep-linux-x64-1.18.0.tgz",
+      "integrity": "sha512-mQ3bVrUpnD2vs7QT0vX90Lt0cnUq467uFtEktIdsJJmW296RoSULRGqWgzG1AKxyBpNDD6l4ZO4qKf6SgyC23Q==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@vscode/ripgrep-win32-arm64": {
+      "version": "1.18.0",
+      "resolved": "https://registry.npmjs.org/@vscode/ripgrep-win32-arm64/-/ripgrep-win32-arm64-1.18.0.tgz",
+      "integrity": "sha512-vfTIjq1OHnzUjxZcHVQAMbnggp8dpGf+0QKFOZHwWPqFwXxQC8eCWM+5NUdoJ6yrElCeMzoUTXoK/LdZaniB+Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@vscode/ripgrep-win32-ia32": {
+      "version": "1.18.0",
+      "resolved": "https://registry.npmjs.org/@vscode/ripgrep-win32-ia32/-/ripgrep-win32-ia32-1.18.0.tgz",
+      "integrity": "sha512-//rfAE+BOw5AC2EMmepmiE36jUuevtQYNQqqlw1s3m9FlRxjxEut97RkRPHAu9BG4mSojatZx+kXZXNdyI9caQ==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@vscode/ripgrep-win32-x64": {
+      "version": "1.18.0",
+      "resolved": "https://registry.npmjs.org/@vscode/ripgrep-win32-x64/-/ripgrep-win32-x64-1.18.0.tgz",
+      "integrity": "sha512-KNPvtElldqILHdnAetujPaowkNbpqJy3ssIGGN6F6Kve9Qi+nNLI2DN01O83JjCEVQbCzl8Ov3QZ9Eov3BR8Dg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/agent-base": {
+      "version": "7.1.4",
+      "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-7.1.4.tgz",
+      "integrity": "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 14"
+      }
+    },
+    "node_modules/argparse": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
+      "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==",
+      "devOptional": true,
+      "license": "Python-2.0"
+    },
+    "node_modules/assertion-error": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-2.0.1.tgz",
+      "integrity": "sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/base64-js": {
+      "version": "1.5.1",
+      "resolved": "https://registry.npmjs.org/base64-js/-/base64-js-1.5.1.tgz",
+      "integrity": "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
+      "license": "MIT"
+    },
+    "node_modules/bignumber.js": {
+      "version": "9.3.1",
+      "resolved": "https://registry.npmjs.org/bignumber.js/-/bignumber.js-9.3.1.tgz",
+      "integrity": "sha512-Ko0uX15oIUS7wJ3Rb30Fs6SkVbLmPBAKdlm7q9+ak9bbIeFf0MwuBsQV6z7+X768/cHsfg+WlysDWJcmthjsjQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "*"
+      }
+    },
+    "node_modules/bowser": {
+      "version": "2.14.1",
+      "resolved": "https://registry.npmjs.org/bowser/-/bowser-2.14.1.tgz",
+      "integrity": "sha512-tzPjzCxygAKWFOJP011oxFHs57HzIhOEracIgAePE4pqB3LikALKnSzUyU4MGs9/iCEUuHlAJTjTc5M+u7YEGg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/buffer-equal-constant-time": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/buffer-equal-constant-time/-/buffer-equal-constant-time-1.0.1.tgz",
+      "integrity": "sha512-zRpUiDwd/xk6ADqPMATG8vc9VPrkck7T07OIx0gnjmJAnHnTVXNQG3vfvWNuiZIkwu9KrKdA1iJKfsfTVxE6NA==",
+      "dev": true,
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/cac": {
+      "version": "6.7.14",
+      "resolved": "https://registry.npmjs.org/cac/-/cac-6.7.14.tgz",
+      "integrity": "sha512-b6Ilus+c3RrdDk+JhLKUAQfzzgLEPy6wcXqS7f/xe1EETvsDP6GORG7SFuOs6cID5YkqchW/LXZbX5bc8j7ZcQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/chai": {
+      "version": "5.3.3",
+      "resolved": "https://registry.npmjs.org/chai/-/chai-5.3.3.tgz",
+      "integrity": "sha512-4zNhdJD/iOjSH0A05ea+Ke6MU5mmpQcbQsSOkgdaUMJ9zTlDTD/GYlwohmIE2u0gaxHYiVHEn1Fw9mZ/ktJWgw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "assertion-error": "^2.0.1",
+        "check-error": "^2.1.1",
+        "deep-eql": "^5.0.1",
+        "loupe": "^3.1.0",
+        "pathval": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/check-error": {
+      "version": "2.1.3",
+      "resolved": "https://registry.npmjs.org/check-error/-/check-error-2.1.3.tgz",
+      "integrity": "sha512-PAJdDJusoxnwm1VwW07VWwUN1sl7smmC3OKggvndJFadxxDRyFJBX/ggnu/KE4kQAB7a3Dp8f/YXC1FlUprWmA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 16"
+      }
+    },
+    "node_modules/chokidar": {
+      "version": "4.0.3",
+      "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-4.0.3.tgz",
+      "integrity": "sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "readdirp": "^4.0.1"
+      },
+      "engines": {
+        "node": ">= 14.16.0"
+      },
+      "funding": {
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
+    "node_modules/data-uri-to-buffer": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/data-uri-to-buffer/-/data-uri-to-buffer-4.0.1.tgz",
+      "integrity": "sha512-0R9ikRb668HB7QDxT1vkpuUBtqc53YyAwMwGeUFKRojY/NWKvdZ+9UYtRfGmhqNbRkTSVpMbmyhXipFFv2cb/A==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 12"
+      }
+    },
+    "node_modules/debug": {
+      "version": "4.4.3",
+      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
+      "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ms": "^2.1.3"
+      },
+      "engines": {
+        "node": ">=6.0"
+      },
+      "peerDependenciesMeta": {
+        "supports-color": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/deep-eql": {
+      "version": "5.0.2",
+      "resolved": "https://registry.npmjs.org/deep-eql/-/deep-eql-5.0.2.tgz",
+      "integrity": "sha512-h5k/5U50IJJFpzfL6nO9jaaumfjO/f2NjK/oYB2Djzm4p9L+3T9qWpZqZ2hAbLPuuYq9wrU08WQyBTL5GbPk5Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/diff": {
+      "version": "9.0.0",
+      "resolved": "https://registry.npmjs.org/diff/-/diff-9.0.0.tgz",
+      "integrity": "sha512-svtcdpS8CgJyqAjEQIXdb3OjhFVVYjzGAPO8WGCmRbrml64SPw/jJD4GoE98aR7r25A0XcgrK3F02yw9R/vhQw==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=0.3.1"
+      }
+    },
+    "node_modules/ecdsa-sig-formatter": {
+      "version": "1.0.11",
+      "resolved": "https://registry.npmjs.org/ecdsa-sig-formatter/-/ecdsa-sig-formatter-1.0.11.tgz",
+      "integrity": "sha512-nagl3RYrbNv6kQkeJIpt6NJZy8twLB/2vtz6yN9Z4vRKHN4/QZJIEbqohALSgwKdnksuY3k5Addp5lg8sVoVcQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "safe-buffer": "^5.0.1"
+      }
+    },
+    "node_modules/es-module-lexer": {
+      "version": "1.7.0",
+      "resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-1.7.0.tgz",
+      "integrity": "sha512-jEQoCwk8hyb2AZziIOLhDqpm5+2ww5uIE6lkO/6jcOCusfk6LhMHpXXfBLXTZ7Ydyt0j4VoUQv6uGNYbdW+kBA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/esbuild": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.25.12.tgz",
+      "integrity": "sha512-bbPBYYrtZbkt6Os6FiTLCTFxvq4tt3JKall1vRwshA3fdVztsLAatFaZobhkBC8/BrPetoa0oksYoKXoG4ryJg==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.25.12",
+        "@esbuild/android-arm": "0.25.12",
+        "@esbuild/android-arm64": "0.25.12",
+        "@esbuild/android-x64": "0.25.12",
+        "@esbuild/darwin-arm64": "0.25.12",
+        "@esbuild/darwin-x64": "0.25.12",
+        "@esbuild/freebsd-arm64": "0.25.12",
+        "@esbuild/freebsd-x64": "0.25.12",
+        "@esbuild/linux-arm": "0.25.12",
+        "@esbuild/linux-arm64": "0.25.12",
+        "@esbuild/linux-ia32": "0.25.12",
+        "@esbuild/linux-loong64": "0.25.12",
+        "@esbuild/linux-mips64el": "0.25.12",
+        "@esbuild/linux-ppc64": "0.25.12",
+        "@esbuild/linux-riscv64": "0.25.12",
+        "@esbuild/linux-s390x": "0.25.12",
+        "@esbuild/linux-x64": "0.25.12",
+        "@esbuild/netbsd-arm64": "0.25.12",
+        "@esbuild/netbsd-x64": "0.25.12",
+        "@esbuild/openbsd-arm64": "0.25.12",
+        "@esbuild/openbsd-x64": "0.25.12",
+        "@esbuild/openharmony-arm64": "0.25.12",
+        "@esbuild/sunos-x64": "0.25.12",
+        "@esbuild/win32-arm64": "0.25.12",
+        "@esbuild/win32-ia32": "0.25.12",
+        "@esbuild/win32-x64": "0.25.12"
+      }
+    },
+    "node_modules/estree-walker": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz",
+      "integrity": "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.0"
+      }
+    },
+    "node_modules/eventsource-parser": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/eventsource-parser/-/eventsource-parser-3.1.1.tgz",
+      "integrity": "sha512-EKN1vKAMcZ8MlYMpaNuxN6R9yakzH6uajHcHVTqWJzvu5pWw9DyhbP35HH8MVBQ+dZjAfDxk+A8NiR9KWaXiyQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18.0.0"
+      }
+    },
+    "node_modules/expect-type": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/expect-type/-/expect-type-1.4.0.tgz",
+      "integrity": "sha512-KfYbmpRm0VbLjEvVa9yGwCi9GI34xvi7A/HXYWQO65CSD2u3MczUJSuwXKFIxlGsgBQizV9q5J9NHj4VG0n+pA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=12.0.0"
+      }
+    },
+    "node_modules/extend": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/extend/-/extend-3.0.2.tgz",
+      "integrity": "sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/fdir": {
+      "version": "6.5.0",
+      "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz",
+      "integrity": "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "peerDependencies": {
+        "picomatch": "^3 || ^4"
+      },
+      "peerDependenciesMeta": {
+        "picomatch": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/fetch-blob": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/fetch-blob/-/fetch-blob-3.2.0.tgz",
+      "integrity": "sha512-7yAQpD2UMJzLi1Dqv7qFYnPbaPx7ZfFK6PiIxQ4PfkGPyNyl2Ugx+a/umUonmKqjhM4DnfbMvdX6otXq83soQQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/jimmywarting"
+        },
+        {
+          "type": "paypal",
+          "url": "https://paypal.me/jimmywarting"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "node-domexception": "^1.0.0",
+        "web-streams-polyfill": "^3.0.3"
+      },
+      "engines": {
+        "node": "^12.20 || >= 14.13"
+      }
+    },
+    "node_modules/formdata-polyfill": {
+      "version": "4.0.10",
+      "resolved": "https://registry.npmjs.org/formdata-polyfill/-/formdata-polyfill-4.0.10.tgz",
+      "integrity": "sha512-buewHzMvYL29jdeQTVILecSaZKnt/RJWjoZCF5OW60Z67/GmSLBkOFM7qh1PI3zFNtJbaZL5eQu1vLfazOwj4g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "fetch-blob": "^3.1.2"
+      },
+      "engines": {
+        "node": ">=12.20.0"
+      }
+    },
+    "node_modules/fsevents": {
+      "version": "2.3.3",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
+      "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
+    "node_modules/gaxios": {
+      "version": "7.3.1",
+      "resolved": "https://registry.npmjs.org/gaxios/-/gaxios-7.3.1.tgz",
+      "integrity": "sha512-kB3rzJV7d9juLZh8/56QTXCwQfxyhdOMdyYk1HdQKFtF8TJTDTZQJtixWIwXdE9Jji91mC41DUNpjleo4L4eAQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "extend": "^3.0.2",
+        "https-proxy-agent": "^7.0.1",
+        "node-fetch": "^3.3.2"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/gcp-metadata": {
+      "version": "8.1.2",
+      "resolved": "https://registry.npmjs.org/gcp-metadata/-/gcp-metadata-8.1.2.tgz",
+      "integrity": "sha512-zV/5HKTfCeKWnxG0Dmrw51hEWFGfcF2xiXqcA3+J90WDuP0SvoiSO5ORvcBsifmx/FoIjgQN3oNOGaQ5PhLFkg==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "gaxios": "^7.0.0",
+        "google-logging-utils": "^1.0.0",
+        "json-bigint": "^1.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/get-tsconfig": {
+      "version": "4.14.2",
+      "resolved": "https://registry.npmjs.org/get-tsconfig/-/get-tsconfig-4.14.2.tgz",
+      "integrity": "sha512-XpwZALwwl/BaKTAyC6+c5T8y6kCg2jk+XGqOVrKIQmW49pNypYLMRjCUXqa28tQgJlhS2RlzP7sc+Rx7W6qsfw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "resolve-pkg-maps": "^1.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/privatenumber/get-tsconfig?sponsor=1"
+      }
+    },
+    "node_modules/google-auth-library": {
+      "version": "10.9.1",
+      "resolved": "https://registry.npmjs.org/google-auth-library/-/google-auth-library-10.9.1.tgz",
+      "integrity": "sha512-i1ydyHrqcIxXkWh/uBmVkzCvIuq5yiK2ATndIe5XxKholrG/MTYP9xGYka4sQhrbIAgGjL2B6NOE7rFaiF3fXw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "base64-js": "^1.3.0",
+        "ecdsa-sig-formatter": "^1.0.11",
+        "gaxios": "^7.1.4",
+        "gcp-metadata": "8.1.2",
+        "google-logging-utils": "1.1.3",
+        "jws": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/google-logging-utils": {
+      "version": "1.1.3",
+      "resolved": "https://registry.npmjs.org/google-logging-utils/-/google-logging-utils-1.1.3.tgz",
+      "integrity": "sha512-eAmLkjDjAFCVXg7A1unxHsLf961m6y17QFqXqAXGj/gVkKFrEICfStRfwUlGNfeCEjNRa32JEWOUTlYXPyyKvA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=14"
+      }
+    },
+    "node_modules/http-proxy-agent": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/http-proxy-agent/-/http-proxy-agent-7.0.2.tgz",
+      "integrity": "sha512-T1gkAiYYDWYx3V5Bmyu7HcfcvL7mUrTWiM6yOfa3PIphViJ/gFPbvidQ+veqSOHci/PxBcDabeUNCzpOODJZig==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "agent-base": "^7.1.0",
+        "debug": "^4.3.4"
+      },
+      "engines": {
+        "node": ">= 14"
+      }
+    },
+    "node_modules/https-proxy-agent": {
+      "version": "7.0.6",
+      "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-7.0.6.tgz",
+      "integrity": "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "agent-base": "^7.1.2",
+        "debug": "4"
+      },
+      "engines": {
+        "node": ">= 14"
+      }
+    },
+    "node_modules/js-tokens": {
+      "version": "9.0.1",
+      "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-9.0.1.tgz",
+      "integrity": "sha512-mxa9E9ITFOt0ban3j6L5MpjwegGz6lBQmM1IJkWeBZGcMxto50+eWdjC/52xDbS2vy0k7vIMK0Fe2wfL9OQSpQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/js-yaml": {
+      "version": "4.3.1",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.1.tgz",
+      "integrity": "sha512-CY6crGq313MX8GkwvB7tzgp99vjQxY1++5y10/BKN/GUfHqWaOGQMNZkBvqSzsZKWk/ijwHlWzzkLulsGHhjWQ==",
+      "devOptional": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/puzrin"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/nodeca"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "argparse": "^2.0.1"
+      },
+      "bin": {
+        "js-yaml": "bin/js-yaml.js"
+      }
+    },
+    "node_modules/json-bigint": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/json-bigint/-/json-bigint-1.0.0.tgz",
+      "integrity": "sha512-SiPv/8VpZuWbvLSMtTDU8hEfrZWg/mH/nV/b4o0CYbSxu1UIQPLdwKOCIyLQX+VIPO5vrLX3i8qtqFyhdPSUSQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "bignumber.js": "^9.0.0"
+      }
+    },
+    "node_modules/json-schema-to-ts": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/json-schema-to-ts/-/json-schema-to-ts-3.1.1.tgz",
+      "integrity": "sha512-+DWg8jCJG2TEnpy7kOm/7/AxaYoaRbjVB4LFZLySZlWn8exGs3A4OLJR966cVvU26N7X9TWxl+Jsw7dzAqKT6g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/runtime": "^7.18.3",
+        "ts-algebra": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=16"
+      }
+    },
+    "node_modules/jwa": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/jwa/-/jwa-2.0.1.tgz",
+      "integrity": "sha512-hRF04fqJIP8Abbkq5NKGN0Bbr3JxlQ+qhZufXVr0DvujKy93ZCbXZMHDL4EOtodSbCWxOqR8MS1tXA5hwqCXDg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "buffer-equal-constant-time": "^1.0.1",
+        "ecdsa-sig-formatter": "1.0.11",
+        "safe-buffer": "^5.0.1"
+      }
+    },
+    "node_modules/jws": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/jws/-/jws-4.0.1.tgz",
+      "integrity": "sha512-EKI/M/yqPncGUUh44xz0PxSidXFr/+r0pA70+gIYhjv+et7yxM+s29Y+VGDkovRofQem0fs7Uvf4+YmAdyRduA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "jwa": "^2.0.1",
+        "safe-buffer": "^5.0.1"
+      }
+    },
+    "node_modules/koffi": {
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/koffi/-/koffi-3.1.5.tgz",
+      "integrity": "sha512-XVwwrxg0Ca6IEUQF4YtGIU4XN0LSselFYpYvgfhh8wafCunhEEx5hPr7LZhp5QyeFA/LcRsKHTqncCdjWjWAlg==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://liberapay.com/Koromix"
+      },
+      "optionalDependencies": {
+        "@koromix/koffi-darwin-arm64": "3.1.5",
+        "@koromix/koffi-darwin-x64": "3.1.5",
+        "@koromix/koffi-freebsd-arm64": "3.1.5",
+        "@koromix/koffi-freebsd-ia32": "3.1.5",
+        "@koromix/koffi-freebsd-x64": "3.1.5",
+        "@koromix/koffi-linux-arm64": "3.1.5",
+        "@koromix/koffi-linux-ia32": "3.1.5",
+        "@koromix/koffi-linux-loong64": "3.1.5",
+        "@koromix/koffi-linux-riscv64": "3.1.5",
+        "@koromix/koffi-linux-x64": "3.1.5",
+        "@koromix/koffi-openbsd-ia32": "3.1.5",
+        "@koromix/koffi-openbsd-x64": "3.1.5",
+        "@koromix/koffi-win32-arm64": "3.1.5",
+        "@koromix/koffi-win32-ia32": "3.1.5",
+        "@koromix/koffi-win32-x64": "3.1.5"
+      }
+    },
+    "node_modules/long": {
+      "version": "5.3.2",
+      "resolved": "https://registry.npmjs.org/long/-/long-5.3.2.tgz",
+      "integrity": "sha512-mNAgZ1GmyNhD7AuqnTG3/VQ26o760+ZYBPKjPvugO8+nLbYfX6TVpJPseBvopbdY+qpZ/lKUnmEc1LeZYS3QAA==",
+      "dev": true,
+      "license": "Apache-2.0"
+    },
+    "node_modules/loupe": {
+      "version": "3.2.1",
+      "resolved": "https://registry.npmjs.org/loupe/-/loupe-3.2.1.tgz",
+      "integrity": "sha512-CdzqowRJCeLU72bHvWqwRBBlLcMEtIvGrlvef74kMnV2AolS9Y8xUv1I0U/MNAWMhBlKIoyuEgoJ0t/bbwHbLQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/magic-string": {
+      "version": "0.30.21",
+      "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.21.tgz",
+      "integrity": "sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/sourcemap-codec": "^1.5.5"
+      }
+    },
+    "node_modules/ms": {
+      "version": "2.1.3",
+      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
+      "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/nanoid": {
+      "version": "3.3.18",
+      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.18.tgz",
+      "integrity": "sha512-DTg4MJbGMWkfi6VZFdNt2/caMbQy4Ou+Op/hJQvGEWcnVfoA1QA+xzRKAzw9jD6+GVOOeYr/mIcuDSdug6F6+w==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "bin": {
+        "nanoid": "bin/nanoid.cjs"
+      },
+      "engines": {
+        "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
+      }
+    },
+    "node_modules/node-addon-api": {
+      "version": "7.1.1",
+      "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-7.1.1.tgz",
+      "integrity": "sha512-5m3bsyrjFWE1xf7nz7YXdN4udnVtXK6/Yfgn5qnahL6bCkf2yKt4k3nuTKAtT4r3IG8JNR2ncsIMdZuAzJjHQQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/node-domexception": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/node-domexception/-/node-domexception-1.0.0.tgz",
+      "integrity": "sha512-/jKZoMpw0F8GRwl4/eLROPA3cfcXtLApP0QzLmUT/HuPCZWyB7IY9ZrMeKw2O/nFIqPQB3PVM9aYm0F312AXDQ==",
+      "deprecated": "Use your platform's native DOMException instead",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/jimmywarting"
+        },
+        {
+          "type": "github",
+          "url": "https://paypal.me/jimmywarting"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.5.0"
+      }
+    },
+    "node_modules/node-fetch": {
+      "version": "3.3.2",
+      "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-3.3.2.tgz",
+      "integrity": "sha512-dRB78srN/l6gqWulah9SrxeYnxeddIG30+GOqK/9OlLVyLg3HPnr6SqOWTWOXKRwC2eGYCkZ59NNuSgvSrpgOA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "data-uri-to-buffer": "^4.0.0",
+        "fetch-blob": "^3.1.4",
+        "formdata-polyfill": "^4.0.10"
+      },
+      "engines": {
+        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/node-fetch"
+      }
+    },
+    "node_modules/node-pty": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/node-pty/-/node-pty-1.1.0.tgz",
+      "integrity": "sha512-20JqtutY6JPXTUnL0ij1uad7Qe1baT46lyolh2sSENDd4sTzKZ4nmAFkeAARDKwmlLjPx6XKRlwRUxwjOy+lUg==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "dependencies": {
+        "node-addon-api": "^7.1.0"
+      }
+    },
+    "node_modules/openai": {
+      "version": "6.26.0",
+      "resolved": "https://registry.npmjs.org/openai/-/openai-6.26.0.tgz",
+      "integrity": "sha512-zd23dbWTjiJ6sSAX6s0HrCZi41JwTA1bQVs0wLQPZ2/5o2gxOJA5wh7yOAUgwYybfhDXyhwlpeQf7Mlgx8EOCA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "openai": "bin/cli"
+      },
+      "peerDependencies": {
+        "ws": "^8.18.0",
+        "zod": "^3.25 || ^4.0"
+      },
+      "peerDependenciesMeta": {
+        "ws": {
+          "optional": true
+        },
+        "zod": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/p-retry": {
+      "version": "4.6.2",
+      "resolved": "https://registry.npmjs.org/p-retry/-/p-retry-4.6.2.tgz",
+      "integrity": "sha512-312Id396EbJdvRONlngUx0NydfrIQ5lsYu0znKVUzVvArzEIt08V1qhtyESbGVd1FGX7UKtiFp5uwKZdM8wIuQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/retry": "0.12.0",
+        "retry": "^0.13.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/partial-json": {
+      "version": "0.1.7",
+      "resolved": "https://registry.npmjs.org/partial-json/-/partial-json-0.1.7.tgz",
+      "integrity": "sha512-Njv/59hHaokb/hRUjce3Hdv12wd60MtM9Z5Olmn+nehe0QDAsRtRbJPvJ0Z91TusF0SuZRIvnM+S4l6EIP8leA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/pathe": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/pathe/-/pathe-2.0.3.tgz",
+      "integrity": "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/pathval": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/pathval/-/pathval-2.0.1.tgz",
+      "integrity": "sha512-//nshmD55c46FuFw26xV/xFAaB5HF9Xdap7HJBBnrKdAd6/GxDBaNA1870O79+9ueg61cZLSVc+OaFlfmObYVQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 14.16"
+      }
+    },
+    "node_modules/picocolors": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
+      "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/picomatch": {
+      "version": "4.0.5",
+      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.5.tgz",
+      "integrity": "sha512-RvwwcruNjI1ncT5xRakeyS9Lf8lcItv34KD+aif+VH9kduAyfYBipGh12274xtenIPZ119/R9BdTBa8gAwSh0A==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/jonschlinkert"
+      }
+    },
+    "node_modules/postcss": {
+      "version": "8.5.26",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.26.tgz",
+      "integrity": "sha512-u82N74LFzG8ca+dD8puPnplTXoGH4fTPpVGuIbt36G3qvNlkvfD0lEAZSxaly3KX8TS/L1A1gsCEmvKmBcVbkQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/postcss/"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/postcss"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "nanoid": "^3.3.17",
+        "picocolors": "^1.1.1",
+        "source-map-js": "^1.2.1"
+      },
+      "engines": {
+        "node": "^10 || ^12 || >=14"
+      }
+    },
+    "node_modules/protobufjs": {
+      "version": "7.6.5",
+      "resolved": "https://registry.npmjs.org/protobufjs/-/protobufjs-7.6.5.tgz",
+      "integrity": "sha512-/FPD0nUc9jH6rfFjji9IBqOz4pcSE3CsT1m7Ep6Mdb0LxSUMj8hgl6GomOvZzpNpAqqGaXA0P3VSrZLFzIhQrw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "@protobufjs/aspromise": "^1.1.2",
+        "@protobufjs/base64": "^1.1.2",
+        "@protobufjs/codegen": "^2.0.5",
+        "@protobufjs/eventemitter": "^1.1.1",
+        "@protobufjs/fetch": "^1.1.1",
+        "@protobufjs/float": "^1.0.2",
+        "@protobufjs/path": "^1.1.2",
+        "@protobufjs/pool": "^1.1.0",
+        "@protobufjs/utf8": "^1.1.1",
+        "@types/node": ">=13.7.0",
+        "long": "^5.3.2"
+      },
+      "engines": {
+        "node": ">=12.0.0"
+      }
+    },
+    "node_modules/readdirp": {
+      "version": "4.1.2",
+      "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-4.1.2.tgz",
+      "integrity": "sha512-GDhwkLfywWL2s6vEjyhri+eXmfH6j1L7JE27WhqLeYzoh/A3DBaYGEj2H/HFZCn/kMfim73FXxEJTw06WtxQwg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 14.18.0"
+      },
+      "funding": {
+        "type": "individual",
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
+    "node_modules/resolve-pkg-maps": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/resolve-pkg-maps/-/resolve-pkg-maps-1.0.0.tgz",
+      "integrity": "sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/privatenumber/resolve-pkg-maps?sponsor=1"
+      }
+    },
+    "node_modules/retry": {
+      "version": "0.13.1",
+      "resolved": "https://registry.npmjs.org/retry/-/retry-0.13.1.tgz",
+      "integrity": "sha512-XQBQ3I8W1Cge0Seh+6gjj03LbmRFWuoszgK9ooCpwYIrhhoO80pfq4cUkU5DkknwfOfFteRwlZ56PYOGYyFWdg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 4"
+      }
+    },
+    "node_modules/rollup": {
+      "version": "4.62.4",
+      "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.62.4.tgz",
+      "integrity": "sha512-RXOqwaPsBGjMNMa4sQjDjHieHEZDFoj/Rdr46l2MU5DfEs16wHJPC2RPTPHWhNl+M3aI472LLqFkFKut4SblOg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "1.0.9"
+      },
+      "bin": {
+        "rollup": "dist/bin/rollup"
+      },
+      "engines": {
+        "node": ">=18.0.0",
+        "npm": ">=8.0.0"
+      },
+      "optionalDependencies": {
+        "@napi-rs/lzma-linux-x64-gnu": "1.5.1",
+        "@rollup/rollup-android-arm-eabi": "4.62.4",
+        "@rollup/rollup-android-arm64": "4.62.4",
+        "@rollup/rollup-darwin-arm64": "4.62.4",
+        "@rollup/rollup-darwin-x64": "4.62.4",
+        "@rollup/rollup-freebsd-arm64": "4.62.4",
+        "@rollup/rollup-freebsd-x64": "4.62.4",
+        "@rollup/rollup-linux-arm-gnueabihf": "4.62.4",
+        "@rollup/rollup-linux-arm-musleabihf": "4.62.4",
+        "@rollup/rollup-linux-arm64-gnu": "4.62.4",
+        "@rollup/rollup-linux-arm64-musl": "4.62.4",
+        "@rollup/rollup-linux-loong64-gnu": "4.62.4",
+        "@rollup/rollup-linux-loong64-musl": "4.62.4",
+        "@rollup/rollup-linux-ppc64-gnu": "4.62.4",
+        "@rollup/rollup-linux-ppc64-musl": "4.62.4",
+        "@rollup/rollup-linux-riscv64-gnu": "4.62.4",
+        "@rollup/rollup-linux-riscv64-musl": "4.62.4",
+        "@rollup/rollup-linux-s390x-gnu": "4.62.4",
+        "@rollup/rollup-linux-x64-gnu": "4.62.4",
+        "@rollup/rollup-linux-x64-musl": "4.62.4",
+        "@rollup/rollup-openbsd-x64": "4.62.4",
+        "@rollup/rollup-openharmony-arm64": "4.62.4",
+        "@rollup/rollup-win32-arm64-msvc": "4.62.4",
+        "@rollup/rollup-win32-ia32-msvc": "4.62.4",
+        "@rollup/rollup-win32-x64-gnu": "4.62.4",
+        "@rollup/rollup-win32-x64-msvc": "4.62.4",
+        "fsevents": "~2.3.2"
+      }
+    },
+    "node_modules/safe-buffer": {
+      "version": "5.2.1",
+      "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz",
+      "integrity": "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
+      "license": "MIT"
+    },
+    "node_modules/siginfo": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/siginfo/-/siginfo-2.0.0.tgz",
+      "integrity": "sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/source-map-js": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
+      "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/stackback": {
+      "version": "0.0.2",
+      "resolved": "https://registry.npmjs.org/stackback/-/stackback-0.0.2.tgz",
+      "integrity": "sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/std-env": {
+      "version": "3.10.0",
+      "resolved": "https://registry.npmjs.org/std-env/-/std-env-3.10.0.tgz",
+      "integrity": "sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/strip-literal": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/strip-literal/-/strip-literal-3.1.0.tgz",
+      "integrity": "sha512-8r3mkIM/2+PpjHoOtiAW8Rg3jJLHaV7xPwG+YRGrv6FP0wwk/toTpATxWYOW0BKdWwl82VT2tFYi5DlROa0Mxg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "js-tokens": "^9.0.1"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/antfu"
+      }
+    },
+    "node_modules/tinybench": {
+      "version": "2.9.0",
+      "resolved": "https://registry.npmjs.org/tinybench/-/tinybench-2.9.0.tgz",
+      "integrity": "sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/tinyexec": {
+      "version": "0.3.2",
+      "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-0.3.2.tgz",
+      "integrity": "sha512-KQQR9yN7R5+OSwaK0XQoj22pwHoTlgYqmUscPYoknOoWCWfj/5/ABTMRi69FrKU5ffPVh5QcFikpWJI/P1ocHA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/tinyglobby": {
+      "version": "0.2.17",
+      "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.17.tgz",
+      "integrity": "sha512-wXR/dYpcqKmfWpEdZjiKJOwCNFndD0DMnrW/cYjVGttEkBfVgcLFHoNrlj47mjOVic9yyNu65alsgF4NQyTa2g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "fdir": "^6.5.0",
+        "picomatch": "^4.0.4"
+      },
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/SuperchupuDev"
+      }
+    },
+    "node_modules/tinypool": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/tinypool/-/tinypool-1.1.1.tgz",
+      "integrity": "sha512-Zba82s87IFq9A9XmjiX5uZA/ARWDrB03OHlq+Vw1fSdt0I+4/Kutwy8BP4Y/y/aORMo61FQ0vIb5j44vSo5Pkg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^18.0.0 || >=20.0.0"
+      }
+    },
+    "node_modules/tinyrainbow": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/tinyrainbow/-/tinyrainbow-2.0.0.tgz",
+      "integrity": "sha512-op4nsTR47R6p0vMUUoYl/a+ljLFVtlfaXkLQmqfLR1qHma1h/ysYk4hEXZ880bf2CYgTskvTa/e196Vd5dDQXw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
+    "node_modules/tinyspy": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/tinyspy/-/tinyspy-4.0.4.tgz",
+      "integrity": "sha512-azl+t0z7pw/z958Gy9svOTuzqIk6xq+NSheJzn5MMWtWTFywIacg2wUlzKFGtt3cthx0r2SxMK0yzJOR0IES7Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
+    "node_modules/ts-algebra": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/ts-algebra/-/ts-algebra-2.0.0.tgz",
+      "integrity": "sha512-FPAhNPFMrkwz76P7cdjdmiShwMynZYN6SgOujD1urY4oNm80Ou9oMdmbR45LotcKOXoy7wSmHkRFE6Mxbrhefw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/tslib": {
+      "version": "2.8.1",
+      "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
+      "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
+      "dev": true,
+      "license": "0BSD"
+    },
+    "node_modules/tsx": {
+      "version": "4.20.3",
+      "resolved": "https://registry.npmjs.org/tsx/-/tsx-4.20.3.tgz",
+      "integrity": "sha512-qjbnuR9Tr+FJOMBqJCW5ehvIo/buZq7vH7qD7JziU98h6l3qGy0a/yPFjwO+y0/T7GFpNgNAvEcPPVfyT8rrPQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "esbuild": "~0.25.0",
+        "get-tsconfig": "^4.7.5"
+      },
+      "bin": {
+        "tsx": "dist/cli.mjs"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      }
+    },
+    "node_modules/typebox": {
+      "version": "1.1.38",
+      "resolved": "https://registry.npmjs.org/typebox/-/typebox-1.1.38.tgz",
+      "integrity": "sha512-pZ0aQPmMmXoUvSbeuWf/Hzsc+avNw/Zd6VeE8CFgkVGWyuHPJvqeJJDeJqLve+K70LvjYIoleGcoJHPT17cWoA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/typescript": {
+      "version": "5.9.2",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.2.tgz",
+      "integrity": "sha512-CWBzXQrc/qOkhidw1OzBTQuYRbfyxDXJMVJ1XNwUHGROVmuaeiEm3OslpZ1RV96d7SKKjZKrSJu3+t/xlw3R9A==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
+    "node_modules/undici-types": {
+      "version": "8.3.0",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-8.3.0.tgz",
+      "integrity": "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/vite": {
+      "version": "7.3.6",
+      "resolved": "https://registry.npmjs.org/vite/-/vite-7.3.6.tgz",
+      "integrity": "sha512-4XP60spRGjSZFf1qYH+dJIkK2znL3zQfl9KkOV9MkkRR/3Dls0dxaBsQPTloEc5BLXWPL9vsOxopxyKoMmDueg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "esbuild": "^0.27.0 || ^0.28.0",
+        "fdir": "^6.5.0",
+        "picomatch": "^4.0.3",
+        "postcss": "^8.5.6",
+        "rollup": "^4.43.0",
+        "tinyglobby": "^0.2.15"
+      },
+      "bin": {
+        "vite": "bin/vite.js"
+      },
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      },
+      "funding": {
+        "url": "https://github.com/vitejs/vite?sponsor=1"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      },
+      "peerDependencies": {
+        "@types/node": "^20.19.0 || >=22.12.0",
+        "jiti": ">=1.21.0",
+        "less": "^4.0.0",
+        "lightningcss": "^1.21.0",
+        "sass": "^1.70.0",
+        "sass-embedded": "^1.70.0",
+        "stylus": ">=0.54.8",
+        "sugarss": "^5.0.0",
+        "terser": "^5.16.0",
+        "tsx": "^4.8.1",
+        "yaml": "^2.4.2"
+      },
+      "peerDependenciesMeta": {
+        "@types/node": {
+          "optional": true
+        },
+        "jiti": {
+          "optional": true
+        },
+        "less": {
+          "optional": true
+        },
+        "lightningcss": {
+          "optional": true
+        },
+        "sass": {
+          "optional": true
+        },
+        "sass-embedded": {
+          "optional": true
+        },
+        "stylus": {
+          "optional": true
+        },
+        "sugarss": {
+          "optional": true
+        },
+        "terser": {
+          "optional": true
+        },
+        "tsx": {
+          "optional": true
+        },
+        "yaml": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/vite-node": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/vite-node/-/vite-node-3.2.4.tgz",
+      "integrity": "sha512-EbKSKh+bh1E1IFxeO0pg1n4dvoOTt0UDiXMd/qn++r98+jPO1xtJilvXldeuQ8giIB5IkpjCgMleHMNEsGH6pg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "cac": "^6.7.14",
+        "debug": "^4.4.1",
+        "es-module-lexer": "^1.7.0",
+        "pathe": "^2.0.3",
+        "vite": "^5.0.0 || ^6.0.0 || ^7.0.0-0"
+      },
+      "bin": {
+        "vite-node": "vite-node.mjs"
+      },
+      "engines": {
+        "node": "^18.0.0 || ^20.0.0 || >=22.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/aix-ppc64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.2.tgz",
+      "integrity": "sha512-XExcO+dvLKvVtNTibSTBej1NCAbaGhWn9Ww1ZPx80qsahhPFe/8jgWP0IchNe0F3HwkU7n8ejhH8bjonqht8mQ==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/android-arm": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.2.tgz",
+      "integrity": "sha512-kXXoiPVVGQcnIYGOeaovwOURpniDBpSq4A03qkQ+BMQqtGG6HYap3xne9C1O1yo4TR3qxlCX5IqqmX6fFo2Lqg==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/android-arm64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.2.tgz",
+      "integrity": "sha512-5YfKeeI8qWfBZIX+u2xZC3Zlb3Os/gLS2sbEKM+I4ZOcsWmHS2WLysCcQZDAFRslDUU5Oiq44gf6PYN1vGwG5A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/android-x64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.2.tgz",
+      "integrity": "sha512-O387ite7SzUyCcy3JQX4P4bLtEA7bLLkx+esve5JHnyYfNTxcVpXZo9jhdB0lTKN44gztELTdU7nS8Nr16Fs1Q==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/darwin-arm64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.2.tgz",
+      "integrity": "sha512-n4KqkOQrraxHJcgjM1RvwbigfQKIKJVpM7xp+KsxiyUSrRdIXnt73VhrPAx0fV44hgfmIVKjxMN9J1t5jySVkw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/darwin-x64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.2.tgz",
+      "integrity": "sha512-uq6suIWYP37qzGddBKPw5QEQPi6HiLGsO7UmkpfyaYNQ3D+rN6w6WfwH+nuqcGXWvawGwxOEroO4YGnFh95azw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.2.tgz",
+      "integrity": "sha512-n+I0BTSRIoy+d6RPKnEVwql5UwBJolytvY4mAOIEJorKlqgPII8ix6slVVrfZ5Tnj7glIZvloylbB/EJPMWEXw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/freebsd-x64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.2.tgz",
+      "integrity": "sha512-78XJTJkvPs0kz2w61301PJjXl4g7q3JqiYMZ/M/yVI73EHBrCRTgkhu9oqG7vPqq+a/yadEW8aD+agKlk5xrmg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-arm": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.2.tgz",
+      "integrity": "sha512-XlDnu2q5yoqems+xay6wSAcg9DDD7K9RLKZEBOMZm3ckNpJBvOX20tSfby8KfrrhINDyv9V2YVZKY/SpoGJI8w==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-arm64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.2.tgz",
+      "integrity": "sha512-pW4AC0P3it8c7do9MVM4p51FzHzdM/TZrerurgRcHJ2WTa1VQ1CIq18xncfpBJw4ojkiZZrKW2yIBWBP92j6Ug==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-ia32": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.2.tgz",
+      "integrity": "sha512-CYbnj78HsIeA+DhgUKgFCfvNsTHFhMMrinUrMZpDXJXKN8T3XViTZ/+wtHeVxEWY8ewSzTFN+nRmSwO2tZaLUQ==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-loong64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.2.tgz",
+      "integrity": "sha512-buwkd8nsph4R+ajRvw0qM5Hja/TXQow3ptzWO2EbG/cqcIkHloRrdlBtQlshyYGTNFvfkfJ5tpPLVkY4DtsPfQ==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-mips64el": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.2.tgz",
+      "integrity": "sha512-ZVykbDyk7519VwiNb9Lcj9m8XM6v5V9uKPvrEMkkEedVewf+0itkhahp4HDpgERXhwLRpWFypsGbG/J8s0QjJA==",
+      "cpu": [
+        "mips64el"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-ppc64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.2.tgz",
+      "integrity": "sha512-CAXl+Dtd9UUuJd8pKKdwh6MLm3MUMiqMPmhZ3tTSXPqfyQ3vDl6R5hZdZ/kYojK4ofXtdfSv1tFq8XzWx3heNQ==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-riscv64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.2.tgz",
+      "integrity": "sha512-GeXCej4IQtU1B+QlDV8W/RRvbzI3O/Stss+/bCXv4lZls5WGRtu2a+3JkA3i4qIUlMXpcHebWpF8AkJhATowuA==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-s390x": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.2.tgz",
+      "integrity": "sha512-3H1weTYZPxt/WOhByszQZybS9w5lKzUn1FDMsgEChbHWQwHYQQRfBxgCcZvPhjHfKyJjIievvMmEUawJrdY9Dg==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-x64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.2.tgz",
+      "integrity": "sha512-4xTZr1FUmSoQW4XIWmit3tzQrUTZM+N3P0XV8xROKYF50XfI7xeO90+1bZvNwxIufQ9hDQVRJH5YhgPVF8A/HQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/netbsd-arm64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.2.tgz",
+      "integrity": "sha512-sSATRjPeDBg3pdgHoQfoYBob11Kk1FGa9lui5RIHZCoCkJa9QKlvl3/vKz2usCmYYjs7ymJR/2Nnsqe+Hjt5nw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/netbsd-x64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.2.tgz",
+      "integrity": "sha512-lqnzCV+mM0gIADaKihiCg6ifgfU2L3h5E33rNQBN1Y4MaVGnzryzmvvf7UHxprpQdE8hpqLolJ9Rl+SkIRDpyw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/openbsd-arm64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.2.tgz",
+      "integrity": "sha512-AL2qJILH7lNjrDmCQDvdxMfAUIv8KMNZOvrwAQ8i8//ntL9FflhOyMJ8OZSMBb8/AWXe3/5v5S20y3zCoZWKoQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/openbsd-x64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.2.tgz",
+      "integrity": "sha512-QtiuPytchRyC4rwUKhexJdQKvDuZ6hWloi3igqPQNUJCS1/v9EiO3UTOXR6A3FoMo4fnAKbWJdqaIwhOzh8qEw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/openharmony-arm64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.2.tgz",
+      "integrity": "sha512-WkhYDmpTjLvGlScA1rwjRUmhl4k8oXR3cIbtqWmELgU/dFeHHlEllxDvdWcNJV9rbzCexB5vz8gtNewWLgCT7Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/sunos-x64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.2.tgz",
+      "integrity": "sha512-GPMSkTOtMnv2U2F8gxe4Io6qmVs+YKyp832Etqqxr0hFngmXQ3rzwytelm3GIn7T4VviRUlf3sOgBOiTdvaf7g==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/win32-arm64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.2.tgz",
+      "integrity": "sha512-PIhhEkE9uPBleRBrQEJpUn7MBnibZzbGzYWPmY3x+YoVg/95zbjB4CxPPOQ8l5tYYM4mMaCthF8/1DIfBQQyWQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/win32-ia32": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.2.tgz",
+      "integrity": "sha512-YmJbfTlvU7Sdn9BB+4PRES4oB6pxgS37MAONj+hBr/cpXS1aBPKXxNnDbu+QCWPj0o9dgyxeq79g6c5P8KeuYA==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/win32-x64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.2.tgz",
+      "integrity": "sha512-5ebpxr3nWMzrL/rnUI755Jkuee0bHL/Gq0WTF9lvcpv73wAp5eu8MfBUgWK9bhWvZjj7yX8etf/8tI8Ney695g==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/esbuild": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.2.tgz",
+      "integrity": "sha512-HKVLS8dvII+xoKW9kmqxbRKrnWEXfJJr/FZhhJmiqIB0e053QNYFqOBouTMO/k5sID4MvCiUCvv8b9M4h32wIA==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.28.2",
+        "@esbuild/android-arm": "0.28.2",
+        "@esbuild/android-arm64": "0.28.2",
+        "@esbuild/android-x64": "0.28.2",
+        "@esbuild/darwin-arm64": "0.28.2",
+        "@esbuild/darwin-x64": "0.28.2",
+        "@esbuild/freebsd-arm64": "0.28.2",
+        "@esbuild/freebsd-x64": "0.28.2",
+        "@esbuild/linux-arm": "0.28.2",
+        "@esbuild/linux-arm64": "0.28.2",
+        "@esbuild/linux-ia32": "0.28.2",
+        "@esbuild/linux-loong64": "0.28.2",
+        "@esbuild/linux-mips64el": "0.28.2",
+        "@esbuild/linux-ppc64": "0.28.2",
+        "@esbuild/linux-riscv64": "0.28.2",
+        "@esbuild/linux-s390x": "0.28.2",
+        "@esbuild/linux-x64": "0.28.2",
+        "@esbuild/netbsd-arm64": "0.28.2",
+        "@esbuild/netbsd-x64": "0.28.2",
+        "@esbuild/openbsd-arm64": "0.28.2",
+        "@esbuild/openbsd-x64": "0.28.2",
+        "@esbuild/openharmony-arm64": "0.28.2",
+        "@esbuild/sunos-x64": "0.28.2",
+        "@esbuild/win32-arm64": "0.28.2",
+        "@esbuild/win32-ia32": "0.28.2",
+        "@esbuild/win32-x64": "0.28.2"
+      }
+    },
+    "node_modules/vitest": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/vitest/-/vitest-3.2.4.tgz",
+      "integrity": "sha512-LUCP5ev3GURDysTWiP47wRRUpLKMOfPh+yKTx3kVIEiu5KOMeqzpnYNsKyOoVrULivR8tLcks4+lga33Whn90A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/chai": "^5.2.2",
+        "@vitest/expect": "3.2.4",
+        "@vitest/mocker": "3.2.4",
+        "@vitest/pretty-format": "^3.2.4",
+        "@vitest/runner": "3.2.4",
+        "@vitest/snapshot": "3.2.4",
+        "@vitest/spy": "3.2.4",
+        "@vitest/utils": "3.2.4",
+        "chai": "^5.2.0",
+        "debug": "^4.4.1",
+        "expect-type": "^1.2.1",
+        "magic-string": "^0.30.17",
+        "pathe": "^2.0.3",
+        "picomatch": "^4.0.2",
+        "std-env": "^3.9.0",
+        "tinybench": "^2.9.0",
+        "tinyexec": "^0.3.2",
+        "tinyglobby": "^0.2.14",
+        "tinypool": "^1.1.1",
+        "tinyrainbow": "^2.0.0",
+        "vite": "^5.0.0 || ^6.0.0 || ^7.0.0-0",
+        "vite-node": "3.2.4",
+        "why-is-node-running": "^2.3.0"
+      },
+      "bin": {
+        "vitest": "vitest.mjs"
+      },
+      "engines": {
+        "node": "^18.0.0 || ^20.0.0 || >=22.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "@edge-runtime/vm": "*",
+        "@types/debug": "^4.1.12",
+        "@types/node": "^18.0.0 || ^20.0.0 || >=22.0.0",
+        "@vitest/browser": "3.2.4",
+        "@vitest/ui": "3.2.4",
+        "happy-dom": "*",
+        "jsdom": "*"
+      },
+      "peerDependenciesMeta": {
+        "@edge-runtime/vm": {
+          "optional": true
+        },
+        "@types/debug": {
+          "optional": true
+        },
+        "@types/node": {
+          "optional": true
+        },
+        "@vitest/browser": {
+          "optional": true
+        },
+        "@vitest/ui": {
+          "optional": true
+        },
+        "happy-dom": {
+          "optional": true
+        },
+        "jsdom": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/web-streams-polyfill": {
+      "version": "3.3.3",
+      "resolved": "https://registry.npmjs.org/web-streams-polyfill/-/web-streams-polyfill-3.3.3.tgz",
+      "integrity": "sha512-d2JWLCivmZYTSIoge9MsgFCZrt571BikcWGYkjC1khllbTeDlGqZ2D8vD8E/lJa8WGWbb7Plm8/XJYV7IJHZZw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/why-is-node-running": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/why-is-node-running/-/why-is-node-running-2.3.0.tgz",
+      "integrity": "sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "siginfo": "^2.0.0",
+        "stackback": "0.0.2"
+      },
+      "bin": {
+        "why-is-node-running": "cli.js"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/ws": {
+      "version": "8.21.3",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.3.tgz",
+      "integrity": "sha512-201TZ/kPWxoPr/OKWjquZR1SWKXcvxdH+e1xrx89b3YbmzLMFCLfnaG1HFIgWzJOEWZ7MvpK++odZufgYR50Rw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.0.0"
+      },
+      "peerDependencies": {
+        "bufferutil": "^4.0.1",
+        "utf-8-validate": ">=5.0.2"
+      },
+      "peerDependenciesMeta": {
+        "bufferutil": {
+          "optional": true
+        },
+        "utf-8-validate": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/yaml": {
+      "version": "2.9.0",
+      "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz",
+      "integrity": "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==",
+      "license": "ISC",
+      "bin": {
+        "yaml": "bin.mjs"
+      },
+      "engines": {
+        "node": ">= 14.6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/eemeli"
+      }
+    },
+    "node_modules/zod": {
+      "version": "4.4.3",
+      "resolved": "https://registry.npmjs.org/zod/-/zod-4.4.3.tgz",
+      "integrity": "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/colinhacks"
+      }
+    },
+    "node_modules/zod-to-json-schema": {
+      "version": "3.25.2",
+      "resolved": "https://registry.npmjs.org/zod-to-json-schema/-/zod-to-json-schema-3.25.2.tgz",
+      "integrity": "sha512-O/PgfnpT1xKSDeQYSCfRI5Gy3hPf91mKVDuYLUHZJMiDFptvP41MSnWofm8dnCm0256ZNfZIM7DSzuSMAFnjHA==",
+      "dev": true,
+      "license": "ISC",
+      "peerDependencies": {
+        "zod": "^3.25.28 || ^4"
+      }
+    }
+  }
+}
diff --git a/packages/dsh-acp/package.json b/packages/dsh-acp/package.json
new file mode 100644
index 0000000000..a8e3ecc576
--- /dev/null
+++ b/packages/dsh-acp/package.json
@@ -0,0 +1,116 @@
+{
+  "name": "@bitfun/dsh-acp",
+  "version": "0.0.1",
+  "private": true,
+  "description": "IDE-oriented Agent Client Protocol server for DeepSeek Harness: publishes tool calls, reasoning, and plans that the automation-only @deepseek-ai/dsh-acp deliberately withholds",
+  "license": "MIT",
+  "type": "module",
+  "main": "lib/app.js",
+  "types": "lib/types/app.d.ts",
+  "bin": {
+    "dsh-acp-ide": "lib/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/types/app.d.ts",
+      "default": "./lib/app.js"
+    },
+    "./bridge": {
+      "types": "./lib/types/bridge.d.ts",
+      "default": "./lib/bridge.js"
+    },
+    "./bin": {
+      "types": "./lib/types/bin.d.ts",
+      "default": "./lib/bin.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/**/*.js",
+    "lib/types/**/*.d.ts",
+    "cordis.yml",
+    "presets/**/*.yml"
+  ],
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "scripts": {
+    "link:dsh": "node scripts/link-local-dsh.mjs",
+    "build": "tsc -p tsconfig.build.json",
+    "start": "node --import tsx src/bin.ts --config ./cordis.yml",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "0.25.1",
+    "@deepseek-ai/dsh-agent-spine-demo": "0.1.0-rc.6"
+  },
+  "comment:dependencies": [
+    "Every @deepseek-ai/* below is pinned to the 0.1.0-rc.6 train, the set npm dist-tag `next` points at.",
+    "(`latest` still points at 0.0.1-rc.1 for half of them, which is why a mixed install disagrees with itself.)",
+    "devDependencies are compile-time only: at runtime the profile resolves them out of the user own dsh",
+    "installation, which symlinks its whole closure into $DSH_HOME/profiles/node_modules on every launch.",
+    "This package is deliberately NOT a pnpm workspace member and carries its own package-lock.json, so that",
+    "installing the harness is the desktop bundle build cost alone rather than every contributor install."
+  ],
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.1",
+    "@deepseek-ai/cordis-plugin-loader": "1.0.2",
+    "@deepseek-ai/dsh-agent": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-agent-default-model": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-agent-instructions": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-agent-loop": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-agent-loop-testkit": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-agent-presets": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-agent-tool-presentation": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-app-boot": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-bash-sandbox": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-code-runtime": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-code-runtime-worker-thread": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-compaction-basic": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-credentials-local": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-fs-observation-policy": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-fs-sandbox": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-goal": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-goal-round-driver": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm-deepseek": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm-pi-ai": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-persona": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-repeat-tool-reminder": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-sandbox-local": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-sandbox-policy": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-session": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-session-checkpoint-policy": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-session-projection": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-session-query-sqlite": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-settings-file": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-shell-env": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-skill": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-skill-filesystem": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-subagent": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-subagent-spawn-in-process": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-subprocess-local": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-terminal": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-terminal-bash": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-token-meter": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-tool-bash": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-tool-bash-persistent": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-tool-fs": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-tool-fs-search": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-tool-goal": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-tool-jobs": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-tool-skill": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-tool-str-replace-editor": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-tool-subagent": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-tool-subagent-control": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-tool-subagent-report": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-tool-todo": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-user-approval": "0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "3.18.1",
+    "tsx": "4.20.3",
+    "typescript": "5.9.2",
+    "vitest": "3.2.4"
+  }
+}
diff --git a/packages/dsh-acp/presets/code/agent.cordis.yml b/packages/dsh-acp/presets/code/agent.cordis.yml
new file mode 100644
index 0000000000..85175b7ce1
--- /dev/null
+++ b/packages/dsh-acp/presets/code/agent.cordis.yml
@@ -0,0 +1,95 @@
+# The `code` agent preset: the standard coding agent, presented as Code Mode.
+#
+# Adapted from deepseek-harness/apps/cli/config/agent-presets/code (MIT,
+# Copyright (c) DeepSeek — see ../../NOTICE.md).
+#
+# Everything in `standard` is here unchanged. What is added is the
+# `tool-presentation` row: instead of one tool call per action, the model writes
+# a TypeScript program against a generated SDK and `run_code` executes it, so a
+# sequence that would be five round trips becomes one.
+#
+# The tool registry itself stays on the host plane — the agent loop's scheduler
+# is its consumer — so what this preset owns is the PRESENTATION of that
+# registry for agents joined to it. A `standard` session runs beside a `code`
+# one in the same process, each seeing its own catalog.
+#
+# Note for IDE clients: in this mode the client sees `run_code` calls rather
+# than one card per file read or shell command. That is the trade this preset
+# makes, and it is why it is not the default.
+
+# ── identity ────────────────────────────────────────────────────────────────
+
+- id: persona
+  name: '@deepseek-ai/dsh-persona'
+  config:
+    text: |-
+      You are a coding assistant powered by the {{model}} model. Your working directory is {{cwd}}. Your bash tool runs under a file sandbox — a `[sandbox: file access denied …]` result is policy, not a command bug.
+
+      Verify your work by running the code or tests. Keep answers brief and factual.
+
+- id: agent-instructions
+  name: '@deepseek-ai/dsh-agent-instructions'
+  config:
+    maxBytes: 65536
+
+# ── shell ───────────────────────────────────────────────────────────────────
+
+- id: tool-bash
+  name: '@deepseek-ai/dsh-tool-bash'
+
+# ── filesystem ──────────────────────────────────────────────────────────────
+
+- id: tool-fs
+  name: '@deepseek-ai/dsh-tool-fs'
+
+- id: tool-fs-search
+  name: '@deepseek-ai/dsh-tool-fs-search'
+  config:
+    sampleOverCapGlobResults: true
+
+# ── background jobs ─────────────────────────────────────────────────────────
+
+- id: tool-jobs
+  name: '@deepseek-ai/dsh-tool-jobs'
+
+# ── skills and goals ────────────────────────────────────────────────────────
+
+- id: tool-skill
+  name: '@deepseek-ai/dsh-tool-skill'
+
+- id: tool-goal
+  name: '@deepseek-ai/dsh-tool-goal'
+
+# ── delegation ──────────────────────────────────────────────────────────────
+
+- id: tool-subagent-control
+  name: '@deepseek-ai/dsh-tool-subagent-control'
+
+- id: tool-subagent-list-agents
+  name: '@deepseek-ai/dsh-tool-subagent-control/list-agents'
+
+- id: tool-subagent
+  name: '@deepseek-ai/dsh-tool-subagent'
+  config:
+    provider: spawn
+    toolName: subagent
+    backgroundMode: continuable
+    maxDepth: 1
+
+# ── planning ────────────────────────────────────────────────────────────────
+
+- id: tool-todo
+  name: '@deepseek-ai/dsh-tool-todo'
+  config:
+    allowParallelInProgress: true
+
+# ── presentation ────────────────────────────────────────────────────────────
+
+# Code Mode for agents on this preset. The row waits for the host's
+# `codeRuntime` rather than assuming it: a deployment that composes no
+# TypeScript runtime fails this preset at mount, naming this id, instead of at
+# the first request.
+- id: tool-presentation
+  name: '@deepseek-ai/dsh-agent-tool-presentation'
+  config:
+    mode: code
diff --git a/packages/dsh-acp/presets/code/preset.yml b/packages/dsh-acp/presets/code/preset.yml
new file mode 100644
index 0000000000..fc0836f479
--- /dev/null
+++ b/packages/dsh-acp/presets/code/preset.yml
@@ -0,0 +1,3 @@
+name: PTC 模式
+description: 具备标准模式的全部能力，并通过 Code Mode SDK 呈现工具，让模型用一个 TypeScript 程序组合多步操作。
+order: 2
diff --git a/packages/dsh-acp/presets/minimal/agent.cordis.yml b/packages/dsh-acp/presets/minimal/agent.cordis.yml
new file mode 100644
index 0000000000..2967d1e3f5
--- /dev/null
+++ b/packages/dsh-acp/presets/minimal/agent.cordis.yml
@@ -0,0 +1,58 @@
+# The `minimal` agent preset: a fixed-prompt, two-tool coding-agent composition.
+#
+# Adapted from deepseek-harness/apps/cli/config/agent-presets/minimal (MIT,
+# Copyright (c) DeepSeek — see ../../NOTICE.md). One deliberate change: the
+# upstream preset shadows the host filesystem with a bare `dsh-fs-local`, which
+# would put the editor outside the sandbox this deployment answers permission
+# requests from. Here the editor resolves the HOST's sandboxed `fs`, so a write
+# beyond the workspace still reaches the ACP client as a permission request.
+#
+# The persona is the complete system prompt, so global identity, tool guidance,
+# and later assembly listeners cannot add prompt text. Runtime context snapshots
+# are suppressed, and the model composes only persistent `bash` and
+# `str_replace_editor`. Context compaction still runs — it is host-plane here.
+
+- id: persona
+  name: '@deepseek-ai/dsh-persona'
+  config:
+    text: You are a helpful software engineer assistant.
+    complete: true
+    includeRuntimeContext: false
+
+# The PTY registry is an agent-owned service, so it lives in an entry-local
+# realm. The backend still consumes the host sandbox policy and subprocess
+# implementation, while the tool registers into the host tool catalog.
+- id: persistent-shell
+  name: cordis:group
+  group: true
+  isolate:
+    terminals: true
+  config:
+    - id: pty
+      name: '@deepseek-ai/dsh-terminal'
+
+    - id: terminal-bash
+      name: '@deepseek-ai/dsh-terminal-bash'
+      config:
+        timeoutMs: 300000
+
+    - id: persistent-bash
+      name: '@deepseek-ai/dsh-tool-bash-persistent'
+      config:
+        timeoutMs: 300000
+        description: |-
+          Run commands in a bash shell
+          * When invoking this tool, the contents of the "command" parameter does NOT need to be XML-escaped.
+          * You don't have access to the internet via this tool.
+          * You do have access to a mirror of common linux and python packages via apt and pip.
+          * State is persistent across command calls and discussions with the user.
+          * To inspect a particular line range of a file, e.g. lines 10-25, try 'sed -n 10,25p /path/to/the/file'.
+          * Please avoid commands that may produce a very large amount of output.
+          * Please run long lived commands in the background, e.g. 'sleep 10 &' or start a server in the background.
+
+# Registers into the host `tools` registry and provides nothing, so it needs no
+# realm. It requires absolute paths and reads the host's sandboxed `fs`.
+- id: str-replace-editor
+  name: '@deepseek-ai/dsh-tool-str-replace-editor'
+  config:
+    maxOutputChars: 16000
diff --git a/packages/dsh-acp/presets/minimal/preset.yml b/packages/dsh-acp/presets/minimal/preset.yml
new file mode 100644
index 0000000000..026cee1181
--- /dev/null
+++ b/packages/dsh-acp/presets/minimal/preset.yml
@@ -0,0 +1,3 @@
+name: 极简模式
+description: 仅提供持久 bash 与 str_replace_editor 的双工具编码 Agent，系统提示固定且不注入运行时上下文。
+order: 3
diff --git a/packages/dsh-acp/presets/standard/agent.cordis.yml b/packages/dsh-acp/presets/standard/agent.cordis.yml
new file mode 100644
index 0000000000..74f90259db
--- /dev/null
+++ b/packages/dsh-acp/presets/standard/agent.cordis.yml
@@ -0,0 +1,97 @@
+# The `standard` agent preset: the full IDE coding agent.
+#
+# Adapted from deepseek-harness/apps/cli/config/agent-presets/standard (MIT,
+# Copyright (c) DeepSeek — see ../../NOTICE.md). The CLI's rows for surfaces an
+# IDE launch does not compose are dropped: pwsh, plan mode, the ask-user and web
+# tools, workflows/ralph, and the codex/claude-code subagent products.
+#
+# This file is an AGENT-PLANE composition. `dsh-agent-presets` mounts it ONCE
+# per process under a standing scope, and every session naming this preset joins
+# it by scope parentage. The host composition (../../cordis.yml) keeps what a
+# preset must not own: the registries themselves, the model route, the sandbox
+# and approval stack, persistence, and the ACP transport.
+#
+# A row that PROVIDES a service must sit inside a group carrying an `isolate`
+# realm, or it publishes into the process-global root realm where a second
+# preset registering the same name collides. Every row below only registers into
+# host registries (tools, prompt sections, skills), so none needs a realm.
+
+# ── identity ────────────────────────────────────────────────────────────────
+
+# `{{model}}` and `{{cwd}}` resolve from the agent's own route and the cwd the
+# ACP client supplied at session/new.
+- id: persona
+  name: '@deepseek-ai/dsh-persona'
+  config:
+    text: |-
+      You are a coding assistant powered by the {{model}} model. Your working directory is {{cwd}}. Your bash tool runs under a file sandbox — a `[sandbox: file access denied …]` result is policy, not a command bug.
+
+      Verify your work by running the code or tests. Keep answers brief and factual.
+
+- id: agent-instructions
+  name: '@deepseek-ai/dsh-agent-instructions'
+  config:
+    maxBytes: 65536
+
+# ── shell ───────────────────────────────────────────────────────────────────
+
+# The model-facing tool only. Its executor (`bash-sandbox`) and the environment
+# registry (`shell-env`) are host-plane.
+- id: tool-bash
+  name: '@deepseek-ai/dsh-tool-bash'
+
+# ── filesystem ──────────────────────────────────────────────────────────────
+
+# Both register into the host `tools` registry and provide nothing. The `fs`
+# service and its observation policy stay in the host composition.
+- id: tool-fs
+  name: '@deepseek-ai/dsh-tool-fs'
+
+- id: tool-fs-search
+  name: '@deepseek-ai/dsh-tool-fs-search'
+  config:
+    sampleOverCapGlobResults: true
+
+# ── background jobs ─────────────────────────────────────────────────────────
+
+# Only the model-facing controls; the task registry is host-plane because
+# `tool-bash` above resolves it with `ctx.get` and would not see a realm here.
+- id: tool-jobs
+  name: '@deepseek-ai/dsh-tool-jobs'
+
+# ── skills and goals ────────────────────────────────────────────────────────
+
+# The skill registry, its filesystem provider, and the goal service all live in
+# the host composition; these rows are the model-facing halves.
+- id: tool-skill
+  name: '@deepseek-ai/dsh-tool-skill'
+
+- id: tool-goal
+  name: '@deepseek-ai/dsh-tool-goal'
+
+# ── delegation ──────────────────────────────────────────────────────────────
+
+# The `subagents` registry, the spawn backend, and `tool-subagent-report` are
+# host-plane singletons; this preset contributes the tools that resolve them.
+- id: tool-subagent-control
+  name: '@deepseek-ai/dsh-tool-subagent-control'
+
+- id: tool-subagent-list-agents
+  name: '@deepseek-ai/dsh-tool-subagent-control/list-agents'
+
+- id: tool-subagent
+  name: '@deepseek-ai/dsh-tool-subagent'
+  config:
+    provider: spawn
+    toolName: subagent
+    backgroundMode: continuable
+    maxDepth: 1
+
+# ── planning ────────────────────────────────────────────────────────────────
+
+# `todo_write` replaces the logged whole list for later model requests; the ACP
+# bridge republishes each write as a plan update.
+- id: tool-todo
+  name: '@deepseek-ai/dsh-tool-todo'
+  config:
+    allowParallelInProgress: true
diff --git a/packages/dsh-acp/presets/standard/preset.yml b/packages/dsh-acp/presets/standard/preset.yml
new file mode 100644
index 0000000000..2f346ac707
--- /dev/null
+++ b/packages/dsh-acp/presets/standard/preset.yml
@@ -0,0 +1,3 @@
+name: 标准模式
+description: 功能完整的编码 Agent：文件读写与检索、沙箱 Shell、后台任务、Skills、目标、子代理与 todo 计划。
+order: 1
diff --git a/packages/dsh-acp/scripts/build-profile.mjs b/packages/dsh-acp/scripts/build-profile.mjs
new file mode 100644
index 0000000000..b770c08cbc
--- /dev/null
+++ b/packages/dsh-acp/scripts/build-profile.mjs
@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+/**
+ * Package the built bridge as a DeepSeek Harness PROFILE, so an IDE launch is
+ * `dsh --profile <name>` against the harness the user already installed.
+ *
+ * A profile is just a directory under `$DSH_HOME/profiles/`: a `package.json`
+ * naming its bundle layers and a `cordis.patch.yml` holding entries. This
+ * script writes one whose bundle list is EMPTY, which makes our composition the
+ * whole tree — no in-box bundle contributes rows, so a mode like `minimal`
+ * stays exactly as narrow as its preset says. The launcher rewrites a profile's
+ * `cordis.yml` to an empty root on every boot, which is why the composition
+ * ships as the patch layer instead.
+ *
+ * Nothing here installs a second copy of the harness. Every `@deepseek-ai/dsh-*`
+ * row resolves from the user's own dsh through `$DSH_HOME/profiles/node_modules`,
+ * the flat fallback the launcher maintains (one symlink per package in the
+ * installation's dependency closure). Only the two packages OUTSIDE that
+ * closure are vendored here.
+ *
+ * Usage: `node scripts/build-profile.mjs [--from-local] [--out <dir>]`
+ * `--from-local` copies the vendored packages out of this package's own
+ * node_modules (a linked harness checkout) instead of fetching the pinned
+ * versions from the registry; use it offline, and expect a checkout's version
+ * rather than the pinned one.
+ */
+
+import { createHash } from 'node:crypto'
+import { execFileSync } from 'node:child_process'
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { basename, dirname, join, relative, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+
+/** The profile directory BitFun materializes this build into. */
+export const PROFILE_NAME = 'bitfun-acp'
+
+/**
+ * The oldest `@deepseek-ai/dsh` this build is known to boot against. The bridge
+ * compiles against harness APIs; an older installation resolves the closure to
+ * packages this code predates, and the failure would otherwise surface as a
+ * module or service error with no hint about the cause.
+ */
+const MIN_DSH_VERSION = '0.1.0-rc.6'
+
+/**
+ * The only two runtime packages the harness installation does NOT already
+ * expose: the ACP wire SDK (not a harness dependency at all) and the agent
+ * spine, which ships as an examples package outside the `dsh` closure. Pinned,
+ * because they must agree with the harness train named above.
+ */
+const VENDORED = {
+  '@agentclientprotocol/sdk': '0.25.1',
+  '@deepseek-ai/dsh-agent-spine-demo': '0.1.0-rc.6',
+}
+
+/** Basename of the build stamp BitFun compares before re-materializing. */
+const STAMP_FILENAME = '.bitfun-bridge.json'
+
+const { values } = parseArgs({
+  args: process.argv.slice(2),
+  options: { out: { type: 'string' }, 'from-local': { type: 'boolean' } },
+  strict: true,
+})
+
+const OUT = resolve(PACKAGE_ROOT, values.out ?? 'dist-profile')
+
+/**
+ * Turn the leaf `cordis.yml` into a profile patch layer.
+ *
+ * The transform is textual on purpose: every comment in that file explains why
+ * a row is where it is, and re-serializing through a YAML parser would drop all
+ * of it. Indenting the whole document under one `- insert:` is exactly the
+ * shape the in-box bundles use.
+ * @param source - the contents of cordis.yml.
+ * @returns the patch document.
+ */
+function toPatchLayer(source) {
+  const body = source
+    // The app row is loaded from source in development and from the emitted
+    // tree here; the Loader resolves both against the profile directory.
+    .replace(/^(\s*name:\s*)'\.\/src\/app\.ts'/m, "$1'./lib/app.js'")
+    .split('\n')
+    // Blank lines stay blank rather than becoming trailing whitespace.
+    .map(line => line === '' ? '' : `    ${line}`)
+    .join('\n')
+  return `# GENERATED by scripts/build-profile.mjs from cordis.yml — do not edit.\n`
+    + `#\n`
+    + `# The profile's own patch layer, applied over an empty root: with no bundles\n`
+    + `# in package.json, these rows ARE the tree.\n`
+    + `- insert:\n${body}`
+}
+
+/**
+ * Copy a directory into the output, skipping what never ships.
+ * @param from - absolute source directory.
+ * @param to - absolute destination directory.
+ */
+function copyTree(from, to) {
+  cpSync(from, to, {
+    recursive: true,
+    dereference: true,
+    filter: source => {
+      // `basename`, not a hand-rolled slice on '/': a Windows path separates on
+      // '\', where slicing on '/' yields the whole path and matches nothing.
+      const base = basename(source)
+      return base !== 'node_modules' && base !== '.git' && !base.endsWith('.map')
+    },
+  })
+}
+
+/**
+ * Place one vendored package under the profile's own node_modules.
+ *
+ * Its transitive dependencies are NOT vendored: Node's parent walk continues
+ * past the profile into `$DSH_HOME/profiles/node_modules`, where the harness
+ * installation's closure already provides them.
+ * @param name - the package name.
+ * @param version - the pinned version, used when fetching from the registry.
+ */
+function vendor(name, version) {
+  const destination = join(OUT, 'node_modules', name)
+  mkdirSync(dirname(destination), { recursive: true })
+  if (values['from-local'] === true) {
+    copyTree(join(PACKAGE_ROOT, 'node_modules', name), destination)
+    return
+  }
+  const staging = mkdtempSync(join(tmpdir(), 'dsh-acp-vendor-'))
+  try {
+    // Both commands run IN the staging directory so no argument ever carries an
+    // absolute path. That is not tidiness: `npm` on Windows is a `.cmd` shim,
+    // which Node refuses to spawn without a shell since CVE-2024-27980, and a
+    // shell then re-splits every argument — an unquoted `C:\Users\...` path
+    // would break on its first space. Keeping the arguments to bare package
+    // names and one filename sidesteps quoting altogether, and also keeps a
+    // drive letter away from `tar -f`, which GNU tar reads as a remote host.
+    const packed = execFileSync(
+      'npm',
+      ['pack', `${name}@${version}`, '--silent'],
+      { cwd: staging, encoding: 'utf8', shell: process.platform === 'win32' },
+    )
+      .split(/\r?\n/)
+      .map(line => line.trim())
+      .filter(line => line !== '')
+      .at(-1)
+    if (packed === undefined) {
+      throw new Error(`npm pack ${name}@${version} named no tarball on stdout`)
+    }
+    execFileSync('tar', ['-xzf', packed], { cwd: staging })
+    copyTree(join(staging, 'package'), destination)
+  } finally {
+    rmSync(staging, { recursive: true, force: true })
+  }
+}
+
+/**
+ * Hash every file in the output so BitFun can tell one build from another.
+ *
+ * A version string is not enough: during development the bridge's version
+ * stands still while its code changes, and a stale profile on disk would look
+ * current. Paths are sorted so the digest does not depend on directory order,
+ * and recorded with '/' so the same sources hash the same on every build host
+ * rather than once per path separator.
+ * @param root - the output directory, already fully written except the stamp.
+ * @returns a hex digest over every path and its bytes.
+ */
+function hashTree(root) {
+  const files = []
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const path = join(dir, entry.name)
+      if (entry.isDirectory()) walk(path)
+      else files.push([relative(root, path).split(sep).join('/'), path])
+    }
+  }
+  walk(root)
+  const digest = createHash('sha256')
+  for (const [key, path] of files.sort((a, b) => a[0] < b[0] ? -1 : 1)) {
+    digest.update(key)
+    digest.update('\0')
+    digest.update(readFileSync(path))
+  }
+  return digest.digest('hex')
+}
+
+const manifest = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8'))
+try {
+  statSync(join(PACKAGE_ROOT, 'lib', 'app.js'))
+} catch {
+  throw new Error('lib/app.js is missing; run `npm run build` (tsc -p tsconfig.build.json) first')
+}
+
+rmSync(OUT, { recursive: true, force: true })
+mkdirSync(OUT, { recursive: true })
+
+// A hand-written profile manifest is enough: the launcher only reads
+// `dsh.profile.bundles` from it, and tolerates the section being absent. An
+// empty list is deliberate — see the module comment.
+writeFileSync(join(OUT, 'package.json'), `${JSON.stringify({
+  name: `dsh-profile-${PROFILE_NAME}`,
+  version: manifest.version,
+  private: true,
+  type: 'module',
+  dependencies: {},
+  dsh: { profile: { bundles: [] } },
+}, undefined, 2)}\n`)
+
+writeFileSync(
+  join(OUT, 'cordis.patch.yml'),
+  toPatchLayer(readFileSync(join(PACKAGE_ROOT, 'cordis.yml'), 'utf8')),
+)
+
+copyTree(join(PACKAGE_ROOT, 'lib'), join(OUT, 'lib'))
+copyTree(join(PACKAGE_ROOT, 'presets'), join(OUT, 'presets'))
+for (const [name, version] of Object.entries(VENDORED)) vendor(name, version)
+
+writeFileSync(join(OUT, STAMP_FILENAME), `${JSON.stringify({
+  bridge: manifest.version,
+  content: hashTree(OUT),
+  minDshVersion: MIN_DSH_VERSION,
+  profile: PROFILE_NAME,
+}, undefined, 2)}\n`)
+
+process.stdout.write(`build-profile: wrote ${relative(PACKAGE_ROOT, OUT)} (profile ${PROFILE_NAME})\n`)
diff --git a/packages/dsh-acp/scripts/link-local-dsh.mjs b/packages/dsh-acp/scripts/link-local-dsh.mjs
new file mode 100644
index 0000000000..ee0967ac42
--- /dev/null
+++ b/packages/dsh-acp/scripts/link-local-dsh.mjs
@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+/**
+ * Populate this package's node_modules by symlinking a local deepseek-harness
+ * checkout.
+ *
+ * This is the OPTIONAL developer path. The ordinary build installs the pinned
+ * `0.1.0-rc.6` train from this package's own `package-lock.json`; link against
+ * a checkout when you are changing the harness and the bridge together, and
+ * `scripts/prepare-dsh-profile.mjs` will then leave the linked tree alone.
+ *
+ * Usage: `node scripts/link-local-dsh.mjs [--repo <path-to-deepseek-harness>]`
+ * or set DSH_REPO. Falls back to sibling checkouts of this repository.
+ */
+
+import { mkdirSync, readFileSync, readdirSync, rmSync, symlinkSync, statSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+
+/** Harness packages that must resolve from this package's own node_modules. */
+const HARNESS_PACKAGES = [
+  // Imported by src/.
+  '@deepseek-ai/cordis',
+  '@deepseek-ai/schemastery',
+  '@deepseek-ai/dsh-agent',
+  '@deepseek-ai/dsh-agent-instructions',
+  '@deepseek-ai/dsh-agent-presets',
+  '@deepseek-ai/dsh-agent-spine-demo',
+  '@deepseek-ai/dsh-app-boot',
+  '@deepseek-ai/dsh-llm',
+  '@deepseek-ai/dsh-session',
+  '@deepseek-ai/dsh-session-checkpoint-policy',
+  '@deepseek-ai/dsh-session-persistence-jsonl',
+  '@deepseek-ai/dsh-session-query-sqlite',
+  '@deepseek-ai/dsh-tools',
+  '@deepseek-ai/dsh-user-approval',
+  // Named by cordis.yml — the HOST plane. The Loader resolves these against the
+  // config directory.
+  '@deepseek-ai/dsh-agent-default-model',
+  '@deepseek-ai/dsh-bash-sandbox',
+  '@deepseek-ai/dsh-code-runtime',
+  '@deepseek-ai/dsh-code-runtime-worker-thread',
+  '@deepseek-ai/dsh-compaction-basic',
+  '@deepseek-ai/dsh-credentials-local',
+  '@deepseek-ai/dsh-fs-observation-policy',
+  '@deepseek-ai/dsh-fs-sandbox',
+  '@deepseek-ai/dsh-goal',
+  '@deepseek-ai/dsh-goal-round-driver',
+  '@deepseek-ai/dsh-llm-deepseek',
+  '@deepseek-ai/dsh-llm-pi-ai',
+  '@deepseek-ai/dsh-settings-file',
+  '@deepseek-ai/dsh-repeat-tool-reminder',
+  '@deepseek-ai/dsh-sandbox-local',
+  '@deepseek-ai/dsh-sandbox-policy',
+  '@deepseek-ai/dsh-session-projection',
+  '@deepseek-ai/dsh-shell-env',
+  '@deepseek-ai/dsh-skill',
+  '@deepseek-ai/dsh-skill-filesystem',
+  '@deepseek-ai/dsh-subagent',
+  '@deepseek-ai/dsh-subagent-spawn-in-process',
+  '@deepseek-ai/dsh-subprocess-local',
+  '@deepseek-ai/dsh-token-meter',
+  '@deepseek-ai/dsh-tool-subagent-report',
+  // Named by presets/*/agent.cordis.yml — the AGENT plane. `dsh-agent-presets`
+  // resolves a preset row against the preset directory, which is inside this
+  // package, so these must resolve from here too.
+  '@deepseek-ai/dsh-agent-tool-presentation',
+  '@deepseek-ai/dsh-persona',
+  '@deepseek-ai/dsh-terminal',
+  '@deepseek-ai/dsh-terminal-bash',
+  '@deepseek-ai/dsh-tool-bash',
+  '@deepseek-ai/dsh-tool-bash-persistent',
+  '@deepseek-ai/dsh-tool-fs',
+  '@deepseek-ai/dsh-tool-fs-search',
+  '@deepseek-ai/dsh-tool-goal',
+  '@deepseek-ai/dsh-tool-jobs',
+  '@deepseek-ai/dsh-tool-skill',
+  '@deepseek-ai/dsh-tool-str-replace-editor',
+  '@deepseek-ai/dsh-tool-subagent',
+  '@deepseek-ai/dsh-tool-subagent-control',
+  '@deepseek-ai/dsh-tool-todo',
+  // Used only by the test suite. The Loader is a runtime dependency of the app
+  // (through dsh-app-boot), but the preset specs mount it themselves, so it has
+  // to resolve from here as well.
+  '@deepseek-ai/cordis-plugin-loader',
+  '@deepseek-ai/dsh-agent-loop',
+  '@deepseek-ai/dsh-agent-loop-testkit',
+]
+
+/** Third-party packages taken from the harness checkout's own install. */
+const VENDOR_PACKAGES = [
+  '@agentclientprotocol/sdk',
+  'tsx',
+  'typescript',
+  'vitest',
+]
+
+/** Directory globs (one level of `*` each) that hold harness workspace members. */
+const WORKSPACE_GLOBS = [
+  'vendor/*',
+  'packages/*/*',
+  'apps/*',
+  'native/landlock-run',
+  'native/landlock-run/packages/*',
+]
+
+/**
+ * Find the harness checkout to link against.
+ * @param explicit - a `--repo` value or DSH_REPO, when supplied.
+ * @returns the absolute path of a directory that looks like deepseek-harness.
+ */
+function resolveHarnessRepo(explicit) {
+  const candidates = explicit === undefined
+    ? [
+        resolve(PACKAGE_ROOT, '../../../deepseek-harness'),
+        resolve(PACKAGE_ROOT, '../../../../deepseek-harness'),
+        resolve(PACKAGE_ROOT, '../../../../../deepseek-harness'),
+      ]
+    : [resolve(process.cwd(), explicit)]
+  for (const candidate of candidates) {
+    try {
+      const manifest = JSON.parse(readFileSync(join(candidate, 'package.json'), 'utf8'))
+      if (manifest.name === '@deepseek-ai/dsh-root') return candidate
+    } catch {
+      // Not a harness checkout; try the next candidate.
+    }
+  }
+  throw new Error(
+    `no deepseek-harness checkout found (looked at ${candidates.join(', ')}); `
+    + 'pass --repo <path> or set DSH_REPO',
+  )
+}
+
+/**
+ * Index every workspace member of the harness checkout by package name.
+ * @param repo - the harness checkout root.
+ * @returns a map from package name to its absolute directory.
+ */
+function indexWorkspace(repo) {
+  const index = new Map()
+  const dirs = []
+  for (const glob of WORKSPACE_GLOBS) {
+    const parts = glob.split('/')
+    let level = [repo]
+    for (const part of parts) {
+      const next = []
+      for (const base of level) {
+        if (part !== '*') {
+          next.push(join(base, part))
+          continue
+        }
+        let entries = []
+        try {
+          entries = readdirSync(base, { withFileTypes: true })
+        } catch {
+          continue
+        }
+        for (const entry of entries) {
+          if (entry.isDirectory() && !entry.name.startsWith('.')) next.push(join(base, entry.name))
+        }
+      }
+      level = next
+    }
+    dirs.push(...level)
+  }
+  for (const dir of dirs) {
+    try {
+      const manifest = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'))
+      if (typeof manifest.name === 'string') index.set(manifest.name, dir)
+    } catch {
+      // Not a package directory.
+    }
+  }
+  return index
+}
+
+/**
+ * Replace `linkPath` with a symlink to `target`, creating scope directories.
+ * @param linkPath - absolute path of the link to (re)create.
+ * @param target - absolute path the link points at.
+ */
+function relink(linkPath, target) {
+  mkdirSync(dirname(linkPath), { recursive: true })
+  rmSync(linkPath, { recursive: true, force: true })
+  symlinkSync(target, linkPath, 'dir')
+}
+
+const { values } = parseArgs({
+  args: process.argv.slice(2),
+  options: { repo: { type: 'string' } },
+  strict: true,
+})
+
+const repo = resolveHarnessRepo(values.repo ?? process.env.DSH_REPO)
+const workspace = indexWorkspace(repo)
+const nodeModules = join(PACKAGE_ROOT, 'node_modules')
+const missing = []
+
+for (const name of HARNESS_PACKAGES) {
+  const dir = workspace.get(name)
+  if (dir === undefined) {
+    missing.push(`${name} (no workspace member with that name in ${repo})`)
+    continue
+  }
+  relink(join(nodeModules, name), dir)
+}
+
+for (const name of VENDOR_PACKAGES) {
+  const dir = join(repo, 'node_modules', name)
+  try {
+    statSync(dir)
+  } catch {
+    missing.push(`${name} (not installed at ${dir}; run pnpm install in the harness checkout)`)
+    continue
+  }
+  relink(join(nodeModules, name), dir)
+}
+
+// The harness checkout's .bin shims are relative to their own realpath, so a
+// single link gives this package working `vitest`/`tsx`/`tsc` executables.
+relink(join(nodeModules, '.bin'), join(repo, 'node_modules', '.bin'))
+
+if (missing.length > 0) {
+  process.stderr.write(`link-local-dsh: ${missing.length} dependency(ies) could not be linked:\n`)
+  for (const line of missing) process.stderr.write(`  - ${line}\n`)
+  process.exit(1)
+}
+
+process.stdout.write(
+  `link-local-dsh: linked ${HARNESS_PACKAGES.length + VENDOR_PACKAGES.length} packages from ${repo}\n`,
+)
diff --git a/packages/dsh-acp/scripts/smoke.mjs b/packages/dsh-acp/scripts/smoke.mjs
new file mode 100644
index 0000000000..ca374c5dd6
--- /dev/null
+++ b/packages/dsh-acp/scripts/smoke.mjs
@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+/**
+ * Boot smoke check: spawn the adapter exactly as an IDE would, complete the ACP
+ * handshake, open a session, and report what came back.
+ *
+ * This is the cheap half of end-to-end — it contacts no provider, because one
+ * is only reached on `session/prompt`. Pass `--prompt "<text>"` to also drive
+ * one real turn and print every session update; that half needs a DeepSeek key
+ * the harness can resolve, which is any of `DEEPSEEK_API_KEY` in this
+ * environment, `$DSH_HOME/.credentials.yaml` (what dsh's Models page writes),
+ * or a `.env` fallback. This script asserts none of them: the credential chain
+ * belongs to the composition, and a missing key surfaces as a failed turn.
+ *
+ * Permission requests are answered `allow-once`, or `reject-once` with
+ * `--reject` — enough to exercise both branches of the approval path.
+ *
+ * `--cancel-after <ms>` interrupts the turn mid-flight and then sends a second
+ * prompt, so a session that cancels but cannot continue fails loudly.
+ *
+ * `--mode <id>` sets the session's mode config option before that prompt,
+ * switching the agent preset. It stays in the credential-free half: a mode
+ * switch is answered by the bridge and never reaches the provider.
+ *
+ * `--load <sessionId>` reopens a stored session instead of starting one, which
+ * is what an IDE does after a restart: the run then prints the replayed history
+ * and the mode the session comes back locked to. The id is a dsh session id —
+ * a directory name under `$DSH_HOME/acp-sessions/<project>/` — and `--cwd` must
+ * name the workspace it was created in.
+ *
+ * Usage: `node scripts/smoke.mjs [--mode code] [--load <id>] [--prompt "…"] [--reject] [--cancel-after 3000]`
+ */
+
+import { spawn } from 'node:child_process'
+import { dirname, resolve } from 'node:path'
+import { Readable, Writable } from 'node:stream'
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+import { ClientSideConnection, ndJsonStream, PROTOCOL_VERSION } from '@agentclientprotocol/sdk'
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+
+const { values } = parseArgs({
+  args: process.argv.slice(2),
+  options: {
+    prompt: { type: 'string' },
+    load: { type: 'string' },
+    mode: { type: 'string' },
+    profile: { type: 'string' },
+    cwd: { type: 'string' },
+    reject: { type: 'boolean' },
+    'cancel-after': { type: 'string' },
+  },
+  strict: true,
+})
+
+/** Which option this run answers every permission request with. */
+const PERMISSION_CHOICE = values.reject === true ? 'reject-once' : 'allow-once'
+
+/** The workspace the session opens against — an IDE passes the user's project. */
+const WORKSPACE = resolve(process.cwd(), values.cwd ?? PACKAGE_ROOT)
+
+// Two launch routes, one composition. `--profile` is what BitFun ships: the
+// user's installed `dsh` boots the materialized profile under $DSH_HOME, and
+// every harness package resolves from that installation. Without it, this runs
+// the working copy through tsx, which is the development loop.
+const launch = values.profile === undefined
+  ? { command: process.execPath, args: ['--import', 'tsx', 'src/bin.ts', '--config', './cordis.yml'] }
+  : { command: 'dsh', args: ['--profile', values.profile] }
+
+const child = spawn(
+  launch.command,
+  launch.args,
+  { cwd: PACKAGE_ROOT, stdio: ['pipe', 'pipe', 'inherit'] },
+)
+
+const stream = ndJsonStream(
+  Writable.toWeb(child.stdin),
+  Readable.toWeb(child.stdout),
+)
+
+/** Print one session update in a single readable line. */
+function describe(update) {
+  const kind = update.sessionUpdate
+  if (kind === 'tool_call' || kind === 'tool_call_update') {
+    const label = update.title === undefined ? '' : ` ${update.title}`
+    return `${kind} ${update.toolCallId}${label} [${update.status ?? '-'}]`
+  }
+  if (kind === 'agent_message_chunk' || kind === 'agent_thought_chunk') {
+    return `${kind} ${JSON.stringify(update.content.text ?? '')}`
+  }
+  if (kind === 'plan') return `plan ${update.entries.map(entry => `${entry.status}:${entry.content}`).join(' | ')}`
+  if (kind === 'config_option_update') {
+    return `config_option_update ${describeOptions(update.configOptions)}`
+  }
+  return kind
+}
+
+/** Print a config option set the way a client's picker would show it. */
+function describeOptions(configOptions) {
+  if (configOptions === undefined || configOptions.length === 0) return '(none)'
+  return configOptions.map(option => {
+    const values = option.type === 'select'
+      ? option.options.map(value => (value.value === option.currentValue ? `[${value.value}]` : value.value)).join(' ')
+      : String(option.currentValue)
+    return `${option.id}(${option.category ?? '-'}): ${values}`
+  }).join(' | ')
+}
+
+const client = new ClientSideConnection(() => ({
+  sessionUpdate(params) {
+    process.stdout.write(`  update: ${describe(params.update)}\n`)
+    return Promise.resolve()
+  },
+  requestPermission(params) {
+    process.stdout.write(
+      `  permission: ${params.toolCall.toolCallId} (${params.toolCall.title ?? '?'}) -> ${PERMISSION_CHOICE}\n`,
+    )
+    return Promise.resolve({ outcome: { outcome: 'selected', optionId: PERMISSION_CHOICE } })
+  },
+}), stream)
+
+let failed = false
+try {
+  const initialized = await client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+  process.stdout.write(`initialize: ${JSON.stringify(initialized.agentInfo)} v${initialized.protocolVersion}\n`)
+  process.stdout.write(`loadSession capability: ${String(initialized.agentCapabilities?.loadSession === true)}\n`)
+
+  // `--load` is the reopen path an IDE takes on restart: the session comes back
+  // from storage with its history replayed as updates and its mode already
+  // fixed, instead of a blank session under the roster default.
+  const session = values.load === undefined
+    ? await client.newSession({ cwd: WORKSPACE, mcpServers: [] })
+    : { sessionId: values.load, ...await client.loadSession({ sessionId: values.load, cwd: WORKSPACE, mcpServers: [] }) }
+  const sessionId = session.sessionId
+  process.stdout.write(`${values.load === undefined ? 'newSession' : 'loadSession'}: ${sessionId}\n`)
+  process.stdout.write(`modes: ${describeOptions(session.configOptions)}\n`)
+
+  if (values.mode !== undefined) {
+    const switched = await client.setSessionConfigOption({
+      sessionId,
+      configId: 'agent-preset',
+      value: values.mode,
+    })
+    process.stdout.write(`mode ${values.mode}: ${describeOptions(switched.configOptions)}\n`)
+  }
+
+  if (values.prompt !== undefined) {
+    const pending = client.prompt({ sessionId, prompt: [{ type: 'text', text: values.prompt }] })
+    if (values['cancel-after'] !== undefined) {
+      await new Promise(resolve => setTimeout(resolve, Number(values['cancel-after'])))
+      process.stdout.write('cancel: sent\n')
+      await client.cancel({ sessionId })
+    }
+    const result = await pending
+    process.stdout.write(`prompt: ${result.stopReason}\n`)
+
+    if (values['cancel-after'] !== undefined) {
+      // The point of the cancel probe: the session must still take work.
+      const next = await client.prompt({ sessionId, prompt: [{ type: 'text', text: 'say OK and nothing else' }] })
+      process.stdout.write(`prompt after cancel: ${next.stopReason}\n`)
+    }
+  }
+} catch (error) {
+  failed = true
+  process.stdout.write(`FAILED: ${String(error)}\n`)
+}
+
+child.stdin.end()
+await new Promise(resolve => child.once('exit', resolve))
+process.exit(failed ? 1 : 0)
diff --git a/packages/dsh-acp/src/app.ts b/packages/dsh-acp/src/app.ts
new file mode 100644
index 0000000000..03a7b3d03e
--- /dev/null
+++ b/packages/dsh-acp/src/app.ts
@@ -0,0 +1,200 @@
+/**
+ * The IDE-facing ACP server app: the default agent spine
+ * ({@link @deepseek-ai/dsh-agent-spine-demo}), JSONL session persistence, and the
+ * {@link @bitfun/dsh-acp/bridge} protocol bridge, owned through one ordered
+ * lifecycle so ACP sessions quiesce before persistence detaches.
+ *
+ * Forked from `@deepseek-ai/dsh-acp-demo`
+ * (deepseek-harness/packages/examples/acp-demo/src/index.ts, MIT).
+ * Copyright (c) DeepSeek. See ../NOTICE.md. The only change is the transport:
+ * this app mounts the IDE bridge instead of the automation-only one.
+ *
+ * It writes nothing to stdout, pre-creates no agents, and leaves adapters,
+ * executors, and optional tools to the leaf `cordis.yml`, which must likewise
+ * avoid stdout loggers. Named exports are required so Loader retains this
+ * plugin's `Config` schema.
+ *
+ * @module @bitfun/dsh-acp
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import z from '@deepseek-ai/schemastery'
+import AgentPresets from '@deepseek-ai/dsh-agent-presets'
+import * as agentCore from '@deepseek-ai/dsh-agent-spine-demo'
+import * as workspaceContext from '@deepseek-ai/dsh-agent-instructions'
+import ToolRuntime, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools'
+import JsonlSessionPersistence, {
+  JsonlCompressionSchema,
+  type JsonlCompression,
+} from '@deepseek-ai/dsh-session-persistence-jsonl'
+import * as sessionCheckpointPolicy from '@deepseek-ai/dsh-session-checkpoint-policy'
+import SqliteSessionQueryEngine from '@deepseek-ai/dsh-session-query-sqlite'
+import * as acp from './bridge.ts'
+
+export const name = 'acp-ide-app'
+const DEFAULT_PERSISTENCE_ROOT = './.sessions'
+const DEFAULT_PRESET = 'standard'
+
+/**
+ * The shipped preset roster: `<package>/presets`, resolved from this module
+ * rather than from `process.cwd()`. An ACP client launches the adapter with the
+ * USER's workspace as the working directory, so a relative root would look for
+ * presets inside whatever project happens to be open.
+ *
+ * `../presets` is correct from both `src/app.ts` and the built `lib/app.js`.
+ */
+const SHIPPED_PRESET_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../presets')
+
+/**
+ * App config: the swappable per-deployment values. `provider` and `model`
+ * configure each agent the ACP bridge creates at `session/new`; `persona` is the
+ * deployment persona (forwarded to the system-prompt plugin); `toolOrder` is the
+ * explicit model-facing tool order; `tools` is the tool registry's config;
+ * `persistenceRoot` is the JSONL backend's directory.
+ */
+export interface Config {
+  /**
+   * Provider route for ACP-created agents. Omitted, each session starts on the
+   * deployment's default selection (`ctx.agentDefaultModel`), which is what the
+   * harness's own settings document configures.
+   */
+  provider?: string
+  /** Model name for ACP-created agents (must have a registered adapter); see {@link Config.provider}. */
+  model?: string
+  /** Publish model reasoning as `agent_thought_chunk` updates. Defaults to `true`. */
+  reasoning?: boolean
+  /** Bundled agent-loop concurrency cap; `1` is serial and omission uses its default. */
+  maxParallelToolCalls?: number
+  /** Deployment persona (the system-prompt plugin's `persona` config). */
+  persona?: string
+  /** Explicit model-facing tool order (the system-prompt plugin's `toolOrder` config). */
+  toolOrder?: string[]
+  /** Tool-registry config — its presentation `mode` (forwarded through agent-spine-demo). */
+  tools?: ToolsConfig
+  /** DeepSeek Harness home directory exposed to bash and used for local skill discovery. */
+  dshHome?: string
+  /** Fallback session-title limits forwarded through agent-spine-demo. */
+  sessionTitle?: NonNullable<agentCore.Config['sessionTitle']>
+  /** Directory for JSONL sessions and the derived query index. Defaults to `./.sessions`. */
+  persistenceRoot?: string
+  /**
+   * Preset an ACP session composes when the client picks none. Must name a
+   * directory under {@link SHIPPED_PRESET_ROOT} or the user preset root.
+   * Defaults to `standard`.
+   */
+  defaultPreset?: string
+  /**
+   * Also scan `<dshHome>/.agent-presets`, so a user can drop in their own mode
+   * beside the shipped three. Defaults to `true`.
+   */
+  userPresets?: boolean
+  /** Write delta-chunk runs as packed storage rows (the JSONL backend's `packChunks`). Defaults to `true`. */
+  packChunks?: boolean
+  /** JSONL artifact encoding; defaults to checksummed Zstandard frames. */
+  persistenceCompression?: JsonlCompression
+  /** Controls automatic AGENTS.md/CLAUDE.md loading; configure a byte budget or set `false`. */
+  workspaceContext: agentCore.Config['workspaceContext']
+  /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-spine-demo. */
+  skills?: agentCore.SkillConfig
+  /** Model-facing bash tool config forwarded through agent-core. */
+  toolBash?: NonNullable<agentCore.Config['toolBash']>
+  /** Process-local background-job admission config forwarded through agent-core. */
+  jobs?: NonNullable<agentCore.Config['jobs']>
+  /** Generic background-job controls forwarded through agent-core; set false to omit their tools. */
+  toolJobs?: NonNullable<agentCore.Config['toolJobs']>
+  /** Persisted same-session goals; owner defaults enable them, or false disables the stack and tools. */
+  goals?: agentCore.GoalConfig | false
+}
+
+export const Config: z<Config> = z.object({
+  provider: z.string(),
+  model: z.string(),
+  reasoning: z.boolean().default(true),
+  maxParallelToolCalls: z.number().step(1).min(1),
+  persona: z.string(),
+  // The array default is forced to undefined: ABSENT means "lexicographic
+  // order" (the owning dsh-system-prompt schema does the same), while
+  // schemastery's native [] default would read as an invalid configured list.
+  toolOrder: z.array(z.string()).default(undefined as unknown as string[]),
+  tools: ToolRuntime.Config,
+  dshHome: z.string(),
+  sessionTitle: agentCore.SessionTitleConfigSchema,
+  persistenceRoot: z.string().default(DEFAULT_PERSISTENCE_ROOT),
+  defaultPreset: z.string().default(DEFAULT_PRESET),
+  userPresets: z.boolean().default(true),
+  packChunks: z.boolean().default(true),
+  persistenceCompression: JsonlCompressionSchema,
+  workspaceContext: z.union([z.const(false), workspaceContext.Config]).required(),
+  skills: agentCore.SkillConfigSchema,
+  toolBash: agentCore.ToolBashConfigSchema,
+  jobs: agentCore.JobsConfigSchema,
+  toolJobs: z.union([z.const(false), agentCore.ToolJobsConfigSchema]),
+  goals: z.union([z.const(false), agentCore.GoalConfigSchema]),
+})
+
+/**
+ * Compose the spine with the IDE ACP transport. The agent-spine-demo bundle
+ * pre-creates NO agents (its `agents` list defaults to `[]`) and carries the
+ * deployment `persona`; the JSONL backend and derived query index persist under
+ * `persistenceRoot`; the ACP bridge owns stdout for JSON-RPC and creates one
+ * agent per `session/new` from the provider/model pair. The composite effect
+ * unloads in reverse order, keeping checkpoint and persistence listeners
+ * attached until ACP agents have flushed their closing events. No logger, no
+ * `hmr` — stdout stays pure.
+ * @param ctx - the Cordis context this app mounts into.
+ * @param config - the deployment's provider, model, persona, and persistence selection.
+ */
+export async function apply(ctx: Context, config: Config): Promise<void> {
+  const goals = config.goals ?? {}
+  const persistenceRoot = config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT
+  // A client that closes this process's stdin has ended the conversation: the
+  // IDE quit, or it tore the adapter down. This lives in the app rather than in
+  // a bin script because `dsh --profile` boots the composition directly and
+  // never runs one — both launch routes must shut down the same way. Disposing
+  // the ROOT (not just this plugin) drains the whole tree in reverse, so ACP
+  // sessions quiesce before persistence detaches.
+  ctx.effect(() => {
+    const close = (): void => {
+      void ctx.root.fiber.dispose().then(() => { process.exit(0) })
+    }
+    process.stdin.on('end', close)
+    return () => void process.stdin.off('end', close)
+  }, 'acp-ide.stdin-close')
+  await ctx.effect(async function* () {
+    const spine = ctx.plugin(agentCore, { ...agentCore.pickSpineConfig(config), goals })
+    await spine
+    yield spine.dispose
+    // Before the transport, because the bridge composes every agent it creates
+    // from a preset and a missing roster would leave each session on the empty
+    // global tool layer.
+    const presets = ctx.plugin(AgentPresets, {
+      default: config.defaultPreset ?? DEFAULT_PRESET,
+      roots: [{ path: SHIPPED_PRESET_ROOT, trust: 'system' }],
+      includeUserRoot: config.userPresets ?? true,
+    })
+    await presets
+    yield presets.dispose
+    const persistence = ctx.plugin(JsonlSessionPersistence, {
+      root: persistenceRoot,
+      ...config.packChunks !== undefined ? { packChunks: config.packChunks } : {},
+      ...config.persistenceCompression === undefined ? {} : { compression: config.persistenceCompression },
+    })
+    await persistence
+    yield persistence.dispose
+    const checkpoint = ctx.plugin(sessionCheckpointPolicy)
+    await checkpoint
+    yield checkpoint.dispose
+    const query = ctx.plugin(SqliteSessionQueryEngine, { path: join(persistenceRoot, 'session-query.db') })
+    await query
+    yield query.dispose
+    const transport = ctx.plugin(acp, {
+      ...config.provider === undefined ? {} : { provider: config.provider },
+      ...config.model === undefined ? {} : { model: config.model },
+      ...config.reasoning === undefined ? {} : { reasoning: config.reasoning },
+    })
+    await transport
+    yield transport.dispose
+  }, 'acp-ide.composition')
+}
diff --git a/packages/dsh-acp/src/bin.ts b/packages/dsh-acp/src/bin.ts
new file mode 100644
index 0000000000..043ef154d7
--- /dev/null
+++ b/packages/dsh-acp/src/bin.ts
@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * Boot an IDE-facing ACP stdio server from `cordis.yml`; usage is
+ * `dsh-acp-ide [--config path]`, defaulting to `./cordis.yml`. Shared env
+ * loading, Loader guards, snapshot config selection, and settled-tree boot live
+ * in dsh-app-boot. Stdout is reserved for JSON-RPC, so diagnostics go only to
+ * stderr.
+ *
+ * Forked from `@deepseek-ai/dsh-acp-demo/bin`
+ * (deepseek-harness/packages/examples/acp-demo/src/bin.ts, MIT).
+ * Copyright (c) DeepSeek. See ../NOTICE.md.
+ *
+ * @module @bitfun/dsh-acp/bin
+ */
+
+import { parseArgs } from 'node:util'
+import { boot, installFailLoud, loadEnv, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
+
+const NAME = 'dsh-acp-ide'
+
+installFailLoud(NAME)
+const snapshotMode = process.env['DSH_SNAPSHOT']
+if (snapshotMode !== 'replay') loadEnv(NAME)
+const { values } = parseArgs({
+  args: process.argv.slice(2),
+  options: { config: { type: 'string', short: 'c' } },
+  strict: true,
+})
+await boot(NAME, resolveConfigPath(values.config ?? './cordis.yml', snapshotMode))
+// Shutdown on stdin close belongs to the app plugin, not to this script: the
+// same composition also boots under `dsh --profile`, which runs no bin at all.
diff --git a/packages/dsh-acp/src/bridge.ts b/packages/dsh-acp/src/bridge.ts
new file mode 100644
index 0000000000..d1f36d22ab
--- /dev/null
+++ b/packages/dsh-acp/src/bridge.ts
@@ -0,0 +1,951 @@
+/**
+ * IDE-oriented Agent Client Protocol server over JSON-RPC stdio.
+ *
+ * Forked from `@deepseek-ai/dsh-acp`
+ * (deepseek-harness/packages/acp/acp/src/index.ts, MIT).
+ * Copyright (c) DeepSeek. See ../NOTICE.md.
+ *
+ * The upstream bridge is automation-only by design: it carries prompt text,
+ * committed assistant text, cancellation, and one-shot permission decisions,
+ * and deliberately keeps tool calls, reasoning, and plans off the wire as
+ * "presentation or trace data". An IDE is exactly the client that needs that
+ * presentation data, so this fork keeps upstream's session, turn, and teardown
+ * machinery verbatim and replaces only the `session/event` dispatch with a full
+ * translation to ACP session updates.
+ *
+ * @module @bitfun/dsh-acp/bridge
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import { randomUUID } from 'node:crypto'
+import { isAbsolute } from 'node:path'
+import { Readable, Writable } from 'node:stream'
+import Schema from '@deepseek-ai/schemastery'
+import { createUserMessage, errorChain } from '@deepseek-ai/dsh-llm'
+import {
+  AgentSideConnection,
+  ndJsonStream,
+  PROTOCOL_VERSION,
+  RequestError,
+  type Agent as AcpAgent,
+  type AuthenticateRequest,
+  type CancelNotification,
+  type InitializeRequest,
+  type InitializeResponse,
+  type LoadSessionRequest,
+  type LoadSessionResponse,
+  type NewSessionRequest,
+  type NewSessionResponse,
+  type PlanEntry,
+  type PromptRequest,
+  type PromptResponse,
+  type SessionConfigOption,
+  type SessionConfigSelectOption,
+  type SessionNotification,
+  type SetSessionConfigOptionRequest,
+  type SetSessionConfigOptionResponse,
+  type StopReason,
+  type Stream,
+  type ToolCallUpdate,
+} from '@agentclientprotocol/sdk'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+// The roster itself is read through `ctx.get`; only the stored-preset resolver
+// is a value here. This import also carries the `agent-preset/selected`
+// session-event declaration the switch below logs and the resolver reads back.
+import { resolveSessionPreset, type AgentPreset } from '@deepseek-ai/dsh-agent-presets'
+import {
+  SessionId, type SessionEvent, type SessionHeader, type TurnEndReason,
+} from '@deepseek-ai/dsh-session'
+// Side-effect type import: declaration-merges the approval waterfall answered below.
+import type {} from '@deepseek-ai/dsh-user-approval'
+import { acpPromptToText, promptHasUnsupportedContent, turnEndToStopReason } from './codec.ts'
+import { parseToolArguments, toolKind, toolLocations, toolOutcome } from './tool-view.ts'
+
+export const name = 'acp-ide'
+/** The bridge creates and owns agents; every other concern is carried by the agent composition. */
+export const inject = ['agents']
+
+/**
+ * The single continuable-subagent teardown the bridge needs. Declared
+ * structurally so this package does not depend on the subagent seam for one
+ * shutdown hook; an absent service means nothing continuable was materialized.
+ */
+interface ContinuableDrain {
+  /**
+   * Close admission below exact host-owned parents, then dispose only their
+   * continuable descendants child-first.
+   */
+  drainContinuableDescendants(parents: readonly Agent[]): Promise<void>
+}
+
+/**
+ * The deployment's default model selection, declared structurally for the same
+ * reason as {@link ContinuableDrain}: the bridge reads it when its own config
+ * pins no provider/model, but does not depend on the settings seam to exist. A
+ * composition without the service falls back to this plugin's config.
+ */
+interface DefaultModelSource {
+  /** The provider/model a new agent should start on, live at call time. */
+  currentSelection(): { provider?: string; model?: string }
+}
+
+/**
+ * The stored-session reads `session/load` needs, declared structurally for the
+ * same reason as {@link ContinuableDrain}. A deployment composed without
+ * durable persistence simply has nothing to load, and the bridge answers that
+ * as a protocol error rather than depending on the storage seam to exist.
+ */
+interface SessionArchive {
+  /**
+   * One stored session's header and full event log. This is the authoritative
+   * read rather than a listing: it waits for a just-disposed session's final
+   * drain, which is exactly the session a client reopens first.
+   */
+  inspect(id: SessionId): Promise<{
+    readonly meta: SessionHeader
+    readonly events: readonly SessionEvent[]
+  }>
+}
+
+/** Preserve invalid-parameter detail in the SDK wire error message. */
+function invalidParams(detail: string): RequestError {
+  return RequestError.invalidParams(undefined, detail)
+}
+
+/** Preserve failed-turn detail; plain handler errors become a generic wire internal error. */
+function internalError(detail: string): RequestError {
+  return RequestError.internalError(undefined, detail)
+}
+
+/** Plugin config: the provider/model selection used for each ACP-created agent. */
+export interface AcpConfig {
+  /** Provider route for created agents; omitted defers to the deployment default. */
+  provider?: string
+  /** Model name for created agents; omitted defers to the deployment default. */
+  model?: string
+  /**
+   * Publish `agent_thought_chunk` updates for model reasoning. Clients that
+   * render reasoning inline want this; leave it off for a quieter wire.
+   * Defaults to `true`.
+   */
+  reasoning?: boolean
+  /** Runtime-only transport override; production uses stdio. */
+  stream?: Stream
+}
+
+export const Config: Schema<AcpConfig> = Schema.object({
+  provider: Schema.string(),
+  model: Schema.string(),
+  reasoning: Schema.boolean().default(true),
+})
+
+/** What this bridge already told the client about one tool call. */
+interface PublishedCall {
+  title: string
+  rawInput: unknown
+}
+
+/** Per-session protocol state. */
+interface SessionRecord {
+  agent: Agent
+  /** Exact owned-agent disposer; resolves after registry, loop, and session teardown. */
+  dispose: () => Promise<void>
+  /**
+   * `turn:step` keys whose committed assistant text was already streamed as
+   * deltas, so the committed message is not published a second time.
+   */
+  streamedText: Set<string>
+  /** The same de-duplication ledger for reasoning. */
+  streamedReasoning: Set<string>
+  /**
+   * Tool calls this bridge has published a `tool_call` update for, so the
+   * approval hook can tell a client-visible call from one it must announce.
+   */
+  published: Map<string, PublishedCall>
+  /**
+   * The agent preset this session is composed from, absent when the deployment
+   * composes no roster. Tracked here so the mode picker can report what is
+   * already running without re-reading the scope chain.
+   */
+  presetId: string | undefined
+  /**
+   * Tail of this session's preset switches. Two `session/set_config_option`
+   * requests must not recompose concurrently: the second one's blank-session
+   * check has to see the first one's result, not the state it raced past.
+   */
+  presetSwitch: Promise<void> | undefined
+  /** Whether the client has been told the mode is now fixed, so it is said once. */
+  presetLockPublished: boolean
+  /** In-flight prompt and its captured turn number for exact settlement. */
+  inflight: {
+    resolve: (reason: StopReason) => void
+    reject: (error: Error) => void
+    messageId: string
+    turn: number | undefined
+    /** The correlated turn's ending, set at turn/end and settled at whole-agent idle. */
+    endReason: TurnEndReason | undefined
+  } | undefined
+}
+
+/** Key a streaming ledger entry by the model round that produced it. */
+function stepKey(turn: number, step: number): string {
+  return `${turn}:${step}`
+}
+
+/**
+ * The session config option the preset roster is offered under.
+ *
+ * ACP has no command channel to the agent — a client's slash menu inserts the
+ * command as ordinary prompt text, so a mode chosen that way arrives glued to
+ * the user's own message. A config option of category `mode` is the channel the
+ * spec provides for exactly this: the client renders it as a picker next to its
+ * composer and sends the choice on its own request.
+ */
+const PRESET_CONFIG_ID = 'agent-preset'
+
+/**
+ * Why the picker is down to one entry, in the client's own words.
+ *
+ * Doubles as the error a late `session/set_config_option` is refused with, so a
+ * client that asks anyway is told the same thing its UI already showed.
+ */
+const PRESET_LOCKED = 'This conversation has already started, so its mode is fixed. '
+  + 'Start a new session to pick another mode.'
+
+/**
+ * Whether a session may still change its preset.
+ *
+ * A started conversation's history was produced under its preset's tools, so
+ * swapping now would leave logged tool calls the new composition cannot make.
+ * The roster states the rule and leaves the check to its caller.
+ * @param session - the agent's session.
+ * @returns true while no turn has started.
+ */
+function sessionBlank(session: Agent['session']): boolean {
+  return !session.events.some(event => event.type === 'turn/start')
+}
+
+/**
+ * One roster entry as a selectable value of the mode option.
+ * @param preset - the roster entry.
+ * @returns its id as the value, with whatever prose the preset carries.
+ */
+function presetValue(preset: AgentPreset): SessionConfigSelectOption {
+  return {
+    value: preset.id,
+    name: preset.name ?? preset.id,
+    ...preset.description === undefined ? {} : { description: preset.description },
+  }
+}
+
+/**
+ * Mount the IDE-facing ACP server.
+ * @param ctx - Cordis context carrying the agent factory and session events.
+ * @param config - Initial provider/model selection and optional test transport.
+ */
+export function apply(ctx: Context, config: AcpConfig): void {
+  // ACP handlers execute outside this plugin's injection scope, so capture the
+  // injected service during apply rather than reading it lazily in a callback.
+  const agents = ctx.agents
+  // The preset roster is optional. A deployment that keeps every model-facing
+  // plugin in its host composition has no modes to offer, and this bridge then
+  // behaves exactly as it did before they existed.
+  const presets = ctx.get('agentPresets')
+  const logger = ctx.logger
+  const sessions = new Map<SessionId, SessionRecord>()
+  const publishReasoning = config.reasoning ?? true
+  let closed = false
+  let conn: AgentSideConnection
+
+  /** Return the bridge-owned record for an agent, rejecting same-id impostors. */
+  const ownedRecord = (agent: Agent): SessionRecord | undefined => {
+    const record = sessions.get(agent.session.id)
+    return record?.agent === agent ? record : undefined
+  }
+
+  const assertOpen = (): void => {
+    if (closed) throw internalError('the ACP bridge has been disposed')
+  }
+
+  const requireSession = (sessionId: SessionId): SessionRecord => {
+    const record = sessions.get(sessionId)
+    if (record === undefined) throw invalidParams(`unknown session: ${sessionId}`)
+    return record
+  }
+
+  /** Send a protocol update without letting a disconnected client fail an agent turn. */
+  const notify = (notification: SessionNotification): void => {
+    /* v8 ignore next 3 -- only a transport write failure reaches this guard. */
+    void conn.sessionUpdate(notification).catch((error: unknown) => {
+      logger.warn(`acp: session/update failed: ${String(error)}`)
+    })
+  }
+
+  /** Send one update for a bridge-owned session. */
+  const update = (record: SessionRecord, payload: SessionNotification['update']): void => {
+    notify({ sessionId: record.agent.session.id, update: payload })
+  }
+
+  /**
+   * The session's mode picker: the roster as one `select` config option.
+   *
+   * Broken presets are withheld — the roster keeps them so their directory
+   * stays visible to an author, but offering one would advertise a choice every
+   * attempt refuses. A locked session is published with only the mode in force,
+   * which is the client-generic way to say "this cannot be changed": a client
+   * disables a picker it has nothing left to pick from, and an agent that does
+   * allow mid-conversation switching keeps its full list and stays switchable.
+   * @param record - the session.
+   * @param locked - whether the mode is already fixed; read off the session by default.
+   * @returns the one option, or nothing when this deployment composes no roster.
+   */
+  const presetOptions = async (
+    record: SessionRecord, locked = !sessionBlank(record.agent.session),
+  ): Promise<SessionConfigOption[]> => {
+    if (presets === undefined) return []
+    const roster = await presets.list()
+    const current = record.presetId
+    const offered = roster
+      .filter(preset => preset.broken === undefined)
+      .filter(preset => !locked || preset.id === current)
+    const currentValue = current ?? offered[0]?.id
+    if (currentValue === undefined || offered.length === 0) return []
+    return [{
+      type: 'select',
+      id: PRESET_CONFIG_ID,
+      name: 'Mode',
+      category: 'mode',
+      ...locked ? { description: PRESET_LOCKED } : {},
+      currentValue,
+      options: offered.map(presetValue),
+    }]
+  }
+
+  const settlePrompt = (record: SessionRecord, reason: StopReason): void => {
+    const inflight = record.inflight
+    if (inflight === undefined) return
+    record.inflight = undefined
+    inflight.resolve(reason)
+  }
+
+  const rejectFromError = (
+    inflight: NonNullable<SessionRecord['inflight']>,
+    reason: Extract<TurnEndReason, { kind: 'error' }>,
+  ): void => {
+    inflight.reject(internalError(`turn failed: ${reason.error.message}`))
+  }
+
+  /**
+   * Announce a tool call to the client. Idempotent per call id so the approval
+   * hook can safely re-announce a call whose `tool/call` event it did not see.
+   */
+  const publishToolCall = (
+    record: SessionRecord, callId: string, toolName: string, rawInput: unknown,
+  ): PublishedCall => {
+    const existing = record.published.get(callId)
+    if (existing !== undefined) return existing
+    const published: PublishedCall = { title: toolName, rawInput }
+    record.published.set(callId, published)
+    update(record, {
+      sessionUpdate: 'tool_call',
+      toolCallId: callId,
+      // The harness tool name IS the title: a client matches it against its own
+      // tool vocabulary to render a native card, and a prettified label would
+      // only make that match guess.
+      title: toolName,
+      kind: toolKind(toolName),
+      status: 'pending',
+      rawInput,
+      locations: toolLocations(rawInput),
+    })
+    return published
+  }
+
+  /**
+   * Translate one harness session event to the ACP wire. Everything the
+   * upstream automation bridge withholds — streaming text, reasoning, tool
+   * calls, tool results, and plans — is published here.
+   */
+  const publishEvent = (record: SessionRecord, event: SessionEvent): void => {
+    switch (event.type) {
+      case 'assistant/chunk': {
+        const { turn, step, chunk } = event.data
+        const key = stepKey(turn, step)
+        if (chunk.type === 'text-delta') {
+          if (chunk.text.length === 0) return
+          record.streamedText.add(key)
+          update(record, { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: chunk.text } })
+        } else if (chunk.type === 'reasoning-delta') {
+          if (chunk.text.length === 0) return
+          record.streamedReasoning.add(key)
+          if (publishReasoning) {
+            update(record, { sessionUpdate: 'agent_thought_chunk', content: { type: 'text', text: chunk.text } })
+          }
+        }
+        return
+      }
+
+      case 'assistant/message': {
+        const { turn, step, message } = event.data
+        const key = stepKey(turn, step)
+        // A step that streamed deltas already published this text; only a
+        // non-streaming route (or a replayed round) reaches the client here.
+        const emitText = !record.streamedText.has(key)
+        const emitReasoning = publishReasoning && !record.streamedReasoning.has(key)
+        for (const block of message.content) {
+          if (block.type === 'text' && block.text.length > 0 && emitText) {
+            update(record, { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: block.text } })
+          } else if (block.type === 'reasoning' && block.text.length > 0 && emitReasoning) {
+            update(record, { sessionUpdate: 'agent_thought_chunk', content: { type: 'text', text: block.text } })
+          } else if (block.type === 'image') {
+            update(record, {
+              sessionUpdate: 'agent_message_chunk',
+              content: { type: 'text', text: `[image attachment ${block.attachment.attachmentId}]` },
+            })
+          }
+        }
+        return
+      }
+
+      case 'tool/call': {
+        const { callId, name: toolName, arguments: args } = event.data
+        publishToolCall(record, callId, toolName, parseToolArguments(args))
+        return
+      }
+
+      case 'tool/result': {
+        const outcome = toolOutcome(event.data.message, event.data.error !== undefined)
+        if (outcome.callId === undefined) return
+        record.published.delete(outcome.callId)
+        update(record, {
+          sessionUpdate: 'tool_call_update',
+          toolCallId: outcome.callId,
+          status: outcome.isError ? 'failed' : 'completed',
+          content: outcome.content,
+          rawOutput: event.data.message as unknown,
+        })
+        return
+      }
+
+      case 'todo/write': {
+        const entries: PlanEntry[] = event.data.todos.map(todo => ({
+          content: todo.content,
+          // The harness todo list carries no priority; ACP requires one, and a
+          // flat `medium` is the honest rendering of "unranked".
+          priority: 'medium',
+          status: todo.status,
+        }))
+        update(record, { sessionUpdate: 'plan', entries })
+        return
+      }
+
+      case 'turn/start': {
+        // The first turn fixes the mode: from here on the history was produced
+        // under this composition's tools, and a later swap would leave logged
+        // tool calls the new composition cannot make. Republishing the picker
+        // shrunk to the mode in force is how the client learns that — said once,
+        // because every later turn would say the same thing.
+        if (presets === undefined || record.presetLockPublished) return
+        record.presetLockPublished = true
+        // Locked is asserted rather than read: whether this very event is
+        // already in `session.events` is the session's business, not the
+        // bridge's, and the answer here is known.
+        void presetOptions(record, true).then(configOptions => {
+          if (closed || configOptions.length === 0) return
+          if (sessions.get(record.agent.session.id) !== record) return
+          update(record, { sessionUpdate: 'config_option_update', configOptions })
+        }, (error: unknown) => {
+          logger.warn(`acp: failed to publish the fixed agent preset: ${String(error)}`)
+        })
+        return
+      }
+
+      case 'step/end': {
+        const key = stepKey(event.data.turn, event.data.step)
+        record.streamedText.delete(key)
+        record.streamedReasoning.delete(key)
+        return
+      }
+
+      case 'turn/end': {
+        record.streamedText.clear()
+        record.streamedReasoning.clear()
+        record.published.clear()
+        return
+      }
+
+      default:
+        // Every other harness event is internal bookkeeping with no ACP
+        // counterpart; a client reconstructs round structure from the updates
+        // above.
+        return
+    }
+  }
+
+  /**
+   * Republish a resumed session's history so the client renders the
+   * conversation it is reopening.
+   *
+   * Replay is the client's only source for a loaded session: `session/load`
+   * returns no transcript, so everything the IDE shows above the composer comes
+   * from these updates. What is withheld is what would double up or lie —
+   * `assistant/chunk` deltas are already committed into `assistant/message`,
+   * and `turn/start` would announce a mode lock the load response itself
+   * carries. Non-user `user/message` entries (plugin reminders, tool feedback)
+   * are agent-internal input, not something the user typed.
+   * @param record - the resumed session, already registered.
+   */
+  const replayHistory = (record: SessionRecord): void => {
+    for (const event of record.agent.session.events) {
+      try {
+        if (event.type === 'user/message') {
+          if (event.data.source.kind !== 'user') continue
+          for (const block of event.data.content) {
+            if (block.type !== 'text' || block.text.length === 0) continue
+            update(record, { sessionUpdate: 'user_message_chunk', content: { type: 'text', text: block.text } })
+          }
+          continue
+        }
+        if (event.type === 'assistant/chunk' || event.type === 'turn/start') continue
+        publishEvent(record, event)
+      } catch (error: unknown) {
+        // One unrenderable historical event costs its card, not the reopened
+        // conversation.
+        logger.warn(`acp: failed to replay ${event.type}: ${String(error)}`)
+      }
+    }
+  }
+
+  ctx.on('session/event', (session, event: SessionEvent) => {
+    const record = sessions.get(session.header.id)
+    if (record === undefined || record.agent.session !== session) return
+    try {
+      publishEvent(record, event)
+    } catch (error: unknown) {
+      // A presentation-mapping failure must never break turn settlement below:
+      // the client loses one card, not the answer.
+      logger.warn(`acp: failed to publish ${event.type}: ${String(error)}`)
+    } finally {
+      const inflight = record.inflight
+      if (inflight !== undefined && event.type === 'turn/end' && inflight.turn === event.data.turn) {
+        if (event.data.reason.kind === 'error') {
+          // Model failures surface immediately as prompt errors; ordinary
+          // endings wait for whole-agent idle below.
+          record.inflight = undefined
+          rejectFromError(inflight, event.data.reason)
+        } else {
+          inflight.endReason = event.data.reason
+        }
+      }
+    }
+  })
+
+  ctx.on('agent/inbox/claimed', ({ agent, message, turn }) => {
+    const record = ownedRecord(agent)
+    const inflight = record?.inflight
+    if (inflight !== undefined && inflight.messageId === message.id) inflight.turn = turn
+  })
+
+  ctx.on('agent/error', ({ agent, turn, error }) => {
+    const record = ownedRecord(agent)
+    const inflight = record?.inflight
+    if (record === undefined || inflight === undefined || inflight.turn === turn) return
+    record.inflight = undefined
+    inflight.reject(internalError(`turn failed: ${errorChain(error)}`))
+  })
+
+  // Permission requests reach the client attached to a tool call it has already
+  // been shown. The harness appends `tool/call` before the scheduler prepares
+  // the call (agent-loop `tool-calls.ts`), so the card exists by the time this
+  // runs; `publishToolCall` re-announces it anyway rather than trusting that
+  // ordering, because a permission prompt against an unknown call id is exactly
+  // the failure that leaves an IDE waiting for a card that never arrives.
+  ctx.on('approval/request', (request, next) => {
+    const record = ownedRecord(request.agent)
+    if (record === undefined || request.callId === undefined) return next()
+    const callId = request.callId
+    const published = publishToolCall(record, callId, request.toolName, {})
+    const toolCall: ToolCallUpdate = {
+      toolCallId: callId,
+      title: published.title,
+      kind: toolKind(published.title),
+      status: 'pending',
+      rawInput: published.rawInput,
+    }
+    return conn.requestPermission({
+      sessionId: record.agent.session.id,
+      toolCall,
+      options: [
+        { optionId: 'allow-once', name: 'Allow once', kind: 'allow_once' },
+        { optionId: 'reject-once', name: 'Reject', kind: 'reject_once' },
+      ],
+    }).then(({ outcome }) => {
+      if (outcome.outcome === 'cancelled') return 'cancelled'
+      if (outcome.optionId !== 'allow-once') return 'rejected'
+      // Granted: the call is about to run, so move the card out of `pending`.
+      // `tool/result` settles it to completed or failed.
+      update(record, { sessionUpdate: 'tool_call_update', toolCallId: callId, status: 'in_progress' })
+      return 'allowed-once'
+    })
+  })
+
+  const makeAgent = (connection: AgentSideConnection): AcpAgent => {
+    conn = connection
+    return {
+      initialize(_params: InitializeRequest): Promise<InitializeResponse> {
+        // Single-version agent: the spec's "same version if supported, else
+        // the latest supported" both resolve to this server's one version.
+        return Promise.resolve({
+          protocolVersion: PROTOCOL_VERSION,
+          agentInfo: { name: 'dsh-acp-ide', version: '0.0.1' },
+          agentCapabilities: {
+            // Reopening a conversation is the IDE's normal case, and the
+            // harness persists every session it runs: without this, a client
+            // has no way to say "continue that one" and starts a blank session
+            // whose history and mode are gone.
+            loadSession: true,
+            promptCapabilities: { image: false, audio: false, embeddedContext: false },
+          },
+          authMethods: [],
+        })
+      },
+
+      authenticate(_params: AuthenticateRequest): Promise<void> {
+        return Promise.resolve()
+      },
+
+      async newSession(params: NewSessionRequest): Promise<NewSessionResponse> {
+        assertOpen()
+        validateSessionParams(params)
+        const sessionId = SessionId(randomUUID())
+        // Resolved before creation so the session header records the exact id
+        // that was composed, not the alias `undefined` stands for: the roster's
+        // default is a hot-reloaded setting, and a resumed session must rebuild
+        // the composition its turns actually ran under.
+        const composed = presets === undefined ? undefined : (await presets.resolve()).id
+        const handle = await agents.create({
+          sessionId,
+          meta: { cwd: params.cwd, ...composed === undefined ? {} : { agentPreset: composed } },
+          agentOptions: agentOptions(ctx, config),
+          // Composition belongs in `setup`, which the factory awaits before the
+          // agent is published: a preset that fails to mount rolls the whole
+          // creation back rather than yielding a session on the empty global
+          // tool layer.
+          ...presets === undefined || composed === undefined ? {} : {
+            setup: async (agentCtx: Context) => void await presets.mount(agentCtx, composed),
+          },
+        })
+        /* v8 ignore next 4 -- a real stdio close can race an in-flight create. */
+        if (closed) {
+          await handle.dispose()
+          throw internalError('connection closed during session/new')
+        }
+        const record: SessionRecord = {
+          agent: handle.agent,
+          dispose: () => handle.dispose(),
+          streamedText: new Set(),
+          streamedReasoning: new Set(),
+          published: new Map(),
+          presetId: composed,
+          presetSwitch: undefined,
+          presetLockPublished: false,
+          inflight: undefined,
+        }
+        sessions.set(sessionId, record)
+        // Carried by the response rather than announced afterwards: a client
+        // registers its update handler for a session only once `session/new`
+        // has returned, so anything published before that can be dropped.
+        const configOptions = await presetOptions(record, false)
+        return { sessionId, ...configOptions.length === 0 ? {} : { configOptions } }
+      },
+
+      /**
+       * Reopen a persisted session: resume its agent and replay its history.
+       *
+       * The session is rebuilt from storage under the preset its turns actually
+       * ran on ({@link resolveSessionPreset} reads the log, not just the
+       * creation header), because a resumed conversation's tool calls have to
+       * stay ones the mounted composition can still make. That also settles the
+       * mode picker: a session with turns comes back locked, exactly as it was
+       * when the client last saw it.
+       *
+       * An unknown id is refused with an invalid-parameter error rather than
+       * silently answered with an empty session, so a client can fall back to
+       * `session/new` and know that is what happened.
+       */
+      async loadSession(params: LoadSessionRequest): Promise<LoadSessionResponse> {
+        assertOpen()
+        validateSessionParams(params)
+        const sessionId = SessionId(params.sessionId)
+        // Already live — a second load of the same session must not resume a
+        // rival agent on top of the running one. Replaying is still right: the
+        // client asked for the transcript.
+        const live = sessions.get(sessionId)
+        if (live !== undefined) {
+          replayHistory(live)
+          const configOptions = await presetOptions(live)
+          return configOptions.length === 0 ? {} : { configOptions }
+        }
+
+        const archive = ctx.get('sessionPersistence') as SessionArchive | undefined
+        if (archive === undefined) throw invalidParams('this deployment persists no sessions')
+        // Absent, unreadable, and written-by-an-incompatible-format all mean the
+        // same thing to a client — this conversation cannot be reopened — and
+        // saying so as an invalid parameter is what lets it fall back to
+        // `session/new` knowing why.
+        const inspected = await archive.inspect(sessionId).catch((error: unknown) => {
+          throw invalidParams(`cannot load session ${sessionId}: ${errorChain(error)}`)
+        })
+        if (inspected.meta.cwd !== params.cwd) {
+          throw invalidParams(
+            `session ${sessionId} belongs to "${inspected.meta.cwd ?? '(none)'}", not "${params.cwd}"`,
+          )
+        }
+        const composed = presets === undefined
+          ? undefined
+          : resolveSessionPreset({ header: inspected.meta, events: inspected.events })
+        const handle = await agents.resume({
+          resumeSessionId: sessionId,
+          agentOptions: agentOptions(ctx, config),
+          ...presets === undefined || composed === undefined ? {} : {
+            setup: async (agentCtx: Context) => void await presets.mount(agentCtx, composed),
+          },
+        })
+        /* v8 ignore next 4 -- a real stdio close can race an in-flight resume. */
+        if (closed) {
+          await handle.dispose()
+          throw internalError('connection closed during session/load')
+        }
+        const record: SessionRecord = {
+          agent: handle.agent,
+          dispose: () => handle.dispose(),
+          streamedText: new Set(),
+          streamedReasoning: new Set(),
+          published: new Map(),
+          presetId: composed,
+          presetSwitch: undefined,
+          // A session with turns is already locked, and the response below says
+          // so; only a session reopened before its first turn can still be
+          // told, by the `turn/start` that starts it.
+          presetLockPublished: !sessionBlank(handle.agent.session),
+          inflight: undefined,
+        }
+        sessions.set(sessionId, record)
+        replayHistory(record)
+        const configOptions = await presetOptions(record)
+        return configOptions.length === 0 ? {} : { configOptions }
+      },
+
+      /**
+       * Choose the session's mode.
+       *
+       * Refused once the conversation has started, for the same reason the
+       * picker is down to one entry by then: the turns already logged ran on the
+       * current preset's tools.
+       */
+      async setSessionConfigOption(
+        params: SetSessionConfigOptionRequest,
+      ): Promise<SetSessionConfigOptionResponse> {
+        assertOpen()
+        const record = requireSession(SessionId(params.sessionId))
+        if (params.configId !== PRESET_CONFIG_ID) {
+          throw invalidParams(`unknown config option: ${params.configId}`)
+        }
+        if (presets === undefined) throw invalidParams('this deployment offers no modes')
+        if (typeof params.value !== 'string') {
+          throw invalidParams(`"${PRESET_CONFIG_ID}" is a select option, not a boolean`)
+        }
+        const id = params.value
+        const swap = async (): Promise<SessionConfigOption[]> => {
+          const target = (await presets.list()).find(preset => preset.id === id)
+          if (target === undefined) throw invalidParams(`unknown mode: ${id}`)
+          if (target.broken !== undefined) {
+            throw invalidParams(`mode "${id}" cannot be used: ${target.broken}`)
+          }
+          // Asking for the mode already in force is not a switch, so it is
+          // answered even on a locked session: it changes nothing either way.
+          if (record.presetId === target.id) return await presetOptions(record)
+          // Re-read inside the queue: a switch ahead of this one may have run,
+          // and a conversation may have started, since this request arrived.
+          if (!sessionBlank(record.agent.session)) throw invalidParams(PRESET_LOCKED)
+          try {
+            const preset = await presets.recompose(record.agent.ctx, target.id)
+            // Logged only after the swap committed, and appended rather than
+            // written back into the creation header: every later turn runs under
+            // this composition, so a resumed session must rebuild it rather than
+            // the one the session was created with.
+            record.agent.session.append('agent-preset/selected', { agentPreset: preset.id })
+            record.presetId = preset.id
+          } catch (error: unknown) {
+            // A rejected recompose leaves the previous composition mounted, so
+            // the session stays usable and the user can pick again.
+            throw internalError(`failed to switch to "${id}": ${errorChain(error)}`)
+          }
+          return await presetOptions(record)
+        }
+        const queued = record.presetSwitch ?? Promise.resolve()
+        const turn = queued.then(swap)
+        record.presetSwitch = turn.then(() => undefined, () => undefined)
+        return { configOptions: await turn }
+      },
+
+      async prompt(params: PromptRequest): Promise<PromptResponse> {
+        assertOpen()
+        const record = requireSession(SessionId(params.sessionId))
+        if (record.inflight !== undefined) {
+          throw invalidParams('a prompt is already in flight for this session')
+        }
+        if (promptHasUnsupportedContent(params.prompt)) {
+          throw invalidParams('only text and resource_link prompt content is supported')
+        }
+        const text = acpPromptToText(params.prompt)
+        if (text.trim().length === 0) throw invalidParams('empty prompt')
+
+        // Not driving a retired agent is this bridge's contract: an
+        // agent-loop-only reload disposes the loop's agents while the bridge
+        // record survives, so validate the record against the live registry
+        // before sending — a disposed machine would accept the item silently.
+        if (ctx.agents.get(record.agent.id) !== record.agent) {
+          throw internalError('prompt was not queued: the agent was disposed outside the bridge')
+        }
+        const message = createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'user' } })
+        const stopReason = await new Promise<StopReason>((resolve, reject) => {
+          // Arm the slot before followup() so a listener-driven synchronous
+          // turn cannot slip past correlation; a synchronous followup()
+          // failure (invalid input) must free the slot again or the session
+          // would reject every later prompt as already in flight.
+          const inflight: NonNullable<SessionRecord['inflight']> = {
+            resolve, reject, messageId: message.id, turn: undefined, endReason: undefined,
+          }
+          record.inflight = inflight
+          try {
+            record.agent.followup(message)
+            /* v8 ignore start -- future-proofing guard, see above */
+          } catch (error: unknown) {
+            record.inflight = undefined
+            const detail = error instanceof Error ? error.message : String(error)
+            throw internalError(`prompt was not queued: ${detail}`)
+          }
+          /* v8 ignore stop */
+          // Settlement waits for whole-agent idle: a correlated turn/end arms
+          // `endReason`, while a turnless slot (admission discarded the
+          // prompt) stays cancelled. Other producers may run further turns
+          // before quiescence; the prompt settles only when the agent stops.
+          void record.agent.whenIdle().then(() => {
+            if (record.inflight !== inflight) return
+            record.inflight = undefined
+            const end = inflight.endReason
+            if (end === undefined) {
+              inflight.resolve('cancelled')
+            } else {
+              // Token-limit and other non-terminal endings are not prompt-level
+              // stop reasons; only normal quiescence reports end_turn.
+              inflight.resolve(end.kind === 'max-tokens' ? 'end_turn' : turnEndToStopReason(end))
+            }
+          })
+        })
+        return { stopReason }
+      },
+
+      cancel(params: CancelNotification): Promise<void> {
+        const record = sessions.get(SessionId(params.sessionId))
+        if (record === undefined) return Promise.resolve()
+        record.agent.cancel({ kind: 'user' })
+        settlePrompt(record, 'cancelled')
+        return Promise.resolve()
+      },
+    }
+  }
+
+  /* v8 ignore next 4 -- production stdio wiring; tests inject config.stream. */
+  const stream: Stream = config.stream ?? ndJsonStream(
+    Writable.toWeb(process.stdout) as WritableStream<Uint8Array>,
+    Readable.toWeb(process.stdin) as ReadableStream<Uint8Array>,
+  )
+  conn = new AgentSideConnection(makeAgent, stream)
+
+  let quiescing: Promise<void> | undefined
+  const quiesce = (): Promise<void> => {
+    if (quiescing !== undefined) return quiescing
+    closed = true
+    const records = [...sessions.values()]
+    sessions.clear()
+    // Stop the bridge's own work before any await: a descendant drain can block
+    // on persistence or scoped cleanup, and the top-level agents must not keep
+    // running model and tool calls for its whole duration.
+    for (const record of records) {
+      record.agent.cancel({ kind: 'user' })
+      settlePrompt(record, 'cancelled')
+    }
+    quiescing = (async () => {
+      // Continuable subagents outlive the turn that started them, and their
+      // Activations own descendant teardown. Drain only these sessions' forests
+      // child-first BEFORE disposing the top-level agents, so no descendant is
+      // left holding a runtime its owner already released.
+      const subagents = ctx.get('subagents') as ContinuableDrain | undefined
+      if (subagents !== undefined) {
+        try {
+          await subagents.drainContinuableDescendants(records.map(record => record.agent))
+        } catch (error: unknown) {
+          logger.warn(`acp: continuable subagent teardown failed: ${String(error)}`)
+        }
+      }
+      const disposals = await Promise.allSettled(records.map(record => record.dispose()))
+      const failures: unknown[] = []
+      for (const result of disposals) {
+        if (result.status === 'rejected') failures.push(result.reason as unknown)
+      }
+      if (failures.length > 0) {
+        const detail = failures.map(failure => errorChain(failure)).join('; ')
+        throw new AggregateError(
+          failures,
+          `ACP agent teardown failed for ${failures.length} session(s): ${detail}`,
+        )
+      }
+    })()
+    return quiescing
+  }
+
+  /* v8 ignore start -- production transport rejection and teardown failure. */
+  void conn.closed
+    .catch((error: unknown) => {
+      logger.warn(`acp: connection closed with an error: ${String(error)}`)
+    })
+    .then(quiesce)
+    .catch((error: unknown) => {
+      logger.warn(`acp: connection-close teardown failed: ${String(error)}`)
+    })
+  /* v8 ignore stop */
+
+  ctx.effect(() => quiesce, 'acp.connection')
+}
+
+/**
+ * Build per-agent options without assigning absent optional fields.
+ *
+ * Plugin config wins where it is set; anything it leaves open comes from the
+ * deployment's default selection, read HERE rather than captured at `apply` so
+ * that a model chosen in the harness's settings after this process started
+ * takes effect on the next session.
+ * @param ctx - the plugin context, source of the optional default-model service.
+ * @param config - ACP provider/model configuration.
+ * @returns the resolved fields only.
+ */
+function agentOptions(ctx: Context, config: AcpConfig): { provider?: string; model?: string } {
+  const fallback = (ctx.get('agentDefaultModel') as DefaultModelSource | undefined)?.currentSelection()
+  const provider = config.provider ?? fallback?.provider
+  const model = config.model ?? fallback?.model
+  return {
+    ...provider !== undefined ? { provider } : {},
+    ...model !== undefined ? { model } : {},
+  }
+}
+
+/** Reject session features outside this bridge's contract. */
+function validateSessionParams(params: NewSessionRequest | LoadSessionRequest): void {
+  if (!isAbsolute(params.cwd)) throw invalidParams(`cwd must be an absolute path: ${params.cwd}`)
+  if (params.additionalDirectories !== undefined && params.additionalDirectories.length > 0) {
+    throw invalidParams('additionalDirectories is not supported')
+  }
+  if (params.mcpServers.length > 0) throw invalidParams('mcpServers is not supported')
+}
diff --git a/packages/dsh-acp/src/codec.ts b/packages/dsh-acp/src/codec.ts
new file mode 100644
index 0000000000..ea086993b5
--- /dev/null
+++ b/packages/dsh-acp/src/codec.ts
@@ -0,0 +1,70 @@
+/**
+ * Pure translation between the harness lifecycle and the ACP wire.
+ *
+ * Forked verbatim from `@deepseek-ai/dsh-acp`
+ * (deepseek-harness/packages/acp/acp/src/codec.ts, MIT).
+ * Copyright (c) DeepSeek. See ../NOTICE.md.
+ *
+ * @module @bitfun/dsh-acp/codec
+ */
+
+import type { ContentBlock as AcpContentBlock, StopReason } from '@agentclientprotocol/sdk'
+import type { TurnEndReason } from '@deepseek-ai/dsh-session'
+
+/**
+ * Map a harness turn ending to ACP's terminal reason vocabulary.
+ * @param reason - harness turn outcome.
+ * @returns the closest legal ACP stop reason.
+ */
+export function turnEndToStopReason(reason: TurnEndReason): StopReason {
+  switch (reason.kind) {
+    case 'completed':
+      return 'end_turn'
+    case 'max-tokens':
+      return 'max_tokens'
+    // `cancelled` is reserved for explicit client cancellation (`session/cancel`)
+    // and disposal, both settled out of band; a turn aborted by a hook or
+    // another owner is ordinary quiescence and reports `end_turn`.
+    case 'aborted':
+      return 'end_turn'
+    case 'interrupted':
+      return 'cancelled'
+    case 'blocked':
+    case 'error':
+      return 'end_turn'
+    default:
+      return 'end_turn'
+  }
+}
+
+/**
+ * Flatten an ACP prompt's baseline blocks to text. Text blocks concatenate
+ * verbatim; resource links become explicit textual references so a baseline
+ * client can point at files without the bridge silently dropping that context.
+ * @param prompt - supported ACP prompt blocks.
+ * @returns text in wire order, with resource links rendered as bracketed references.
+ */
+export function acpPromptToText(prompt: readonly AcpContentBlock[]): string {
+  return prompt.flatMap((block): string[] => {
+    switch (block.type) {
+      case 'text':
+        return [block.text]
+      case 'resource_link':
+        return [`\n[resource_link name=${JSON.stringify(block.name)} uri=${JSON.stringify(block.uri)}]\n`]
+      default:
+        return []
+    }
+  }).join('')
+}
+
+/**
+ * Whether a prompt carries content beyond the ACP baseline. The spec requires
+ * every agent to accept `text` and `resource_link`; richer inline payloads
+ * (image, audio, embedded resource) are optional capabilities this bridge does
+ * not advertise, so they are rejected rather than silently dropped.
+ * @param prompt - ACP prompt blocks to inspect.
+ * @returns `true` when any block is neither `text` nor `resource_link`.
+ */
+export function promptHasUnsupportedContent(prompt: readonly AcpContentBlock[]): boolean {
+  return prompt.some(block => block.type !== 'text' && block.type !== 'resource_link')
+}
diff --git a/packages/dsh-acp/src/tool-view.ts b/packages/dsh-acp/src/tool-view.ts
new file mode 100644
index 0000000000..a011fdabd2
--- /dev/null
+++ b/packages/dsh-acp/src/tool-view.ts
@@ -0,0 +1,159 @@
+/**
+ * Presentation mapping from harness tool vocabulary to the ACP tool-call shape
+ * an IDE renders. This is the part `@deepseek-ai/dsh-acp` deliberately omits:
+ * its wire is automation-only, so it publishes no tool identity at all.
+ *
+ * @module @bitfun/dsh-acp/tool-view
+ */
+
+import type { ToolCallContent, ToolCallLocation, ToolKind } from '@agentclientprotocol/sdk'
+import type { ContentBlock, ToolResultMessage } from '@deepseek-ai/dsh-llm'
+
+/**
+ * Harness tool name to the ACP kind vocabulary. Exact names only: a client's
+ * icon and grouping should never hinge on a substring accident, and an
+ * unrecognized tool is honestly `other` rather than mis-labelled.
+ */
+const TOOL_KINDS: Readonly<Record<string, ToolKind>> = {
+  ask_user_question: 'other',
+  bash: 'execute',
+  create_goal: 'other',
+  edit: 'edit',
+  exit_plan_mode: 'switch_mode',
+  get_goal: 'other',
+  glob: 'search',
+  grep: 'search',
+  interrupt_agent: 'other',
+  job_kill: 'other',
+  job_list: 'other',
+  job_output: 'other',
+  list_agents: 'other',
+  lsp: 'search',
+  pwsh: 'execute',
+  ralph: 'other',
+  read: 'read',
+  read_image: 'read',
+  report: 'other',
+  run_code: 'execute',
+  send_message: 'other',
+  session_event_read: 'search',
+  session_event_search: 'search',
+  session_event_trace: 'search',
+  session_search: 'search',
+  session_trace: 'search',
+  skill: 'other',
+  str_replace_editor: 'edit',
+  subagent: 'other',
+  subagent_fork: 'other',
+  terminal_close: 'execute',
+  terminal_list: 'other',
+  terminal_open: 'execute',
+  terminal_read: 'read',
+  terminal_send: 'execute',
+  terminal_signal: 'execute',
+  todo_write: 'other',
+  update_goal: 'other',
+  web_fetch: 'fetch',
+  web_search: 'search',
+  workflow: 'other',
+  write: 'edit',
+}
+
+/**
+ * Classify a harness tool for the client's tool card.
+ * @param name - the harness tool name as registered with `ctx.tools`.
+ * @returns the ACP kind, defaulting to `other` for tools this bridge has not seen.
+ */
+export function toolKind(name: string): ToolKind {
+  return TOOL_KINDS[name] ?? 'other'
+}
+
+/**
+ * Decode the model's raw argument string. The harness carries arguments as the
+ * provider emitted them, so a truncated or malformed call must still produce a
+ * card: an unparseable payload is surfaced as the literal text instead of
+ * failing the update.
+ * @param args - the raw JSON string from `tool/call`.
+ * @returns the parsed object, or the original string when it is not JSON.
+ */
+export function parseToolArguments(args: string): unknown {
+  if (args.length === 0) return {}
+  try {
+    return JSON.parse(args)
+  } catch {
+    return args
+  }
+}
+
+/** Argument keys, in priority order, that name the file a tool acts on. */
+const PATH_KEYS = ['file_path', 'path', 'notebook_path', 'filePath']
+
+/**
+ * Extract the file locations a tool call touches so the client can offer
+ * "follow along" navigation.
+ * @param input - the parsed tool arguments.
+ * @returns one location when the arguments name a path, otherwise none.
+ */
+export function toolLocations(input: unknown): ToolCallLocation[] {
+  if (typeof input !== 'object' || input === null) return []
+  const record = input as Record<string, unknown>
+  for (const key of PATH_KEYS) {
+    const value = record[key]
+    if (typeof value !== 'string' || value.length === 0) continue
+    const line = record['offset'] ?? record['line']
+    return [{ path: value, ...typeof line === 'number' ? { line } : {} }]
+  }
+  return []
+}
+
+/** The harness tool-result payload a client can render, lifted out of the message. */
+export interface ToolOutcome {
+  /** The call this result settles, taken from the result block or the message source. */
+  callId: string | undefined
+  /** Renderable result blocks in wire order. */
+  content: ToolCallContent[]
+  /** Whether the tool reported failure, from the result block or the event's error field. */
+  isError: boolean
+}
+
+/**
+ * Render one harness content block for a tool card.
+ * @param block - a block from the tool-result payload.
+ * @returns the ACP content entry, or undefined for blocks with no client rendering.
+ */
+function renderBlock(block: ContentBlock): ToolCallContent | undefined {
+  switch (block.type) {
+    case 'text':
+      return { type: 'content', content: { type: 'text', text: block.text } }
+    case 'reasoning':
+      return { type: 'content', content: { type: 'text', text: block.text } }
+    case 'image':
+      return {
+        type: 'content',
+        content: { type: 'text', text: `[image attachment ${block.attachment.attachmentId}]` },
+      }
+    default:
+      return undefined
+  }
+}
+
+/**
+ * Lift the renderable outcome out of a harness `tool/result` payload.
+ * @param message - the tool-result message the harness appended.
+ * @param hasError - whether the event carried a structured error alongside the message.
+ * @returns the call correlation, rendered content, and failure flag.
+ */
+export function toolOutcome(message: ToolResultMessage, hasError: boolean): ToolOutcome {
+  const block = message.content.find(entry => entry.type === 'tool-result')
+  const content = block === undefined
+    ? []
+    : block.content.flatMap(entry => {
+      const rendered = renderBlock(entry)
+      return rendered === undefined ? [] : [rendered]
+    })
+  return {
+    callId: block?.toolCallId ?? message.source.callId,
+    content,
+    isError: hasError || block?.isError === true,
+  }
+}
diff --git a/packages/dsh-acp/tests/approval-order.spec.ts b/packages/dsh-acp/tests/approval-order.spec.ts
new file mode 100644
index 0000000000..be72b24bc4
--- /dev/null
+++ b/packages/dsh-acp/tests/approval-order.spec.ts
@@ -0,0 +1,113 @@
+/**
+ * A permission prompt must never reference a tool call the client has not been
+ * shown — that mismatch is what leaves an IDE waiting for a card that never
+ * arrives, and then for a turn that never settles.
+ */
+
+import { afterEach, describe, expect, it } from 'vitest'
+import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import ApprovalService from '@deepseek-ai/dsh-user-approval'
+import { makeBridgeHarness, waitForEvents, type BridgeHarness, type OrderedEvent } from './harness.ts'
+
+/** The tool-call ids each timeline entry refers to, for order assertions. */
+function timeline(events: readonly OrderedEvent[]): string[] {
+  return events.map((event) => {
+    if (event.kind === 'permission') return `permission:${event.request.toolCall.toolCallId}`
+    if (event.update.sessionUpdate === 'tool_call') return `tool_call:${event.update.toolCallId}`
+    if (event.update.sessionUpdate === 'tool_call_update') {
+      return `tool_call_update:${event.update.toolCallId}:${event.update.status ?? ''}`
+    }
+    return event.update.sessionUpdate
+  })
+}
+
+describe('ACP approval ordering', () => {
+  let harness: BridgeHarness | undefined
+
+  afterEach(async () => {
+    await harness?.dispose()
+    harness = undefined
+  })
+
+  /** Open a session with the approval waterfall mounted. */
+  async function openSession(): Promise<Agent> {
+    harness = await makeBridgeHarness()
+    await harness.ctx.plugin(ApprovalService)
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
+    const agent = harness.ctx.agents.get(SessionId(sessionId))
+    if (agent === undefined) throw new Error('missing agent')
+    agent.session.append('turn/start', { turn: 1 })
+    agent.session.append('step/start', { turn: 1, step: 0 })
+    return agent
+  }
+
+  it('shows the tool card before asking permission for it', async () => {
+    const agent = await openSession()
+    const callId = CallId('call-approve')
+    // The agent loop appends tool/call before the scheduler prepares the call,
+    // so this is the real production order.
+    agent.session.append('tool/call', {
+      turn: 1, step: 0, callId, name: 'bash', arguments: JSON.stringify({ command: 'rm -rf build' }),
+    })
+    await waitForEvents(harness!, 1)
+    harness!.onPermission = () => ({ outcome: { outcome: 'selected', optionId: 'allow-once' } })
+
+    await expect(harness!.ctx.approval.request({ agent, toolName: 'bash', callId })).resolves.toBe('allowed-once')
+
+    expect(timeline(harness!.orderedEvents)).toEqual([
+      'tool_call:call-approve',
+      'permission:call-approve',
+      'tool_call_update:call-approve:in_progress',
+    ])
+    expect(harness!.permissionRequests[0]).toMatchObject({
+      sessionId: agent.session.id,
+      toolCall: { toolCallId: 'call-approve', title: 'bash', kind: 'execute', status: 'pending' },
+      options: [
+        { optionId: 'allow-once', kind: 'allow_once' },
+        { optionId: 'reject-once', kind: 'reject_once' },
+      ],
+    })
+    expect(harness!.permissionRequests[0]?.toolCall.rawInput).toEqual({ command: 'rm -rf build' })
+  })
+
+  it('announces a call the client was never told about before asking', async () => {
+    const agent = await openSession()
+    harness!.onPermission = () => ({ outcome: { outcome: 'selected', optionId: 'reject-once' } })
+
+    await expect(harness!.ctx.approval.request({ agent, toolName: 'write', callId: CallId('call-unseen') }))
+      .resolves.toBe('rejected')
+
+    // Rejected calls stay pending: the harness reports no tool/result for them.
+    expect(timeline(harness!.orderedEvents)).toEqual(['tool_call:call-unseen', 'permission:call-unseen'])
+    expect(harness!.updates[0]).toMatchObject({
+      sessionUpdate: 'tool_call', toolCallId: 'call-unseen', title: 'write', kind: 'edit', status: 'pending',
+    })
+  })
+
+  it('announces the call once across the event and the approval hook', async () => {
+    const agent = await openSession()
+    const callId = CallId('call-once')
+    agent.session.append('tool/call', {
+      turn: 1, step: 0, callId, name: 'edit', arguments: JSON.stringify({ file_path: '/repo/a.ts' }),
+    })
+    await waitForEvents(harness!, 1)
+    harness!.onPermission = () => ({ outcome: { outcome: 'selected', optionId: 'allow-once' } })
+    await harness!.ctx.approval.request({ agent, toolName: 'edit', callId })
+
+    expect(timeline(harness!.orderedEvents).filter(entry => entry.startsWith('tool_call:')))
+      .toEqual(['tool_call:call-once'])
+    // The re-announcement must not overwrite the arguments the event carried.
+    expect(harness!.permissionRequests[0]?.toolCall.rawInput).toEqual({ file_path: '/repo/a.ts' })
+  })
+
+  it('leaves foreign and identity-less requests to the rest of the waterfall', async () => {
+    const agent = await openSession()
+    await expect(harness!.ctx.approval.request({ agent, toolName: 'bash' })).resolves.toBe('unavailable')
+    expect(harness!.permissionRequests).toHaveLength(0)
+    expect(harness!.updates).toHaveLength(0)
+  })
+})
diff --git a/packages/dsh-acp/tests/fixtures/plugins/contribute.js b/packages/dsh-acp/tests/fixtures/plugins/contribute.js
new file mode 100644
index 0000000000..20157bb599
--- /dev/null
+++ b/packages/dsh-acp/tests/fixtures/plugins/contribute.js
@@ -0,0 +1,17 @@
+// A preset row: registers one model-facing tool named from config, so a test
+// can read a session's composition off its tool list.
+//
+// Import-free on purpose — the Loader resolves a composition row through Node's
+// ESM resolver, which cannot see this package's TypeScript sources.
+export const name = 'contribute'
+export const inject = ['tools']
+
+export function apply(ctx, config) {
+  ctx.effect(() => ctx.tools.register({
+    name: config.tool,
+    description: `fixture tool ${config.tool}`,
+    parameters: { type: 'object', properties: {}, additionalProperties: false },
+    output: { schema: { type: 'string' }, render: (_args, value) => [{ type: 'text', text: String(value) }] },
+    execute: () => Promise.resolve(config.tool),
+  }))
+}
diff --git a/packages/dsh-acp/tests/fixtures/presets/alpha/agent.cordis.yml b/packages/dsh-acp/tests/fixtures/presets/alpha/agent.cordis.yml
new file mode 100644
index 0000000000..a614459c27
--- /dev/null
+++ b/packages/dsh-acp/tests/fixtures/presets/alpha/agent.cordis.yml
@@ -0,0 +1,5 @@
+# The default fixture mode: one tool, named after the preset.
+- id: alpha-tool
+  name: ../../plugins/contribute.js
+  config:
+    tool: alpha
diff --git a/packages/dsh-acp/tests/fixtures/presets/alpha/preset.yml b/packages/dsh-acp/tests/fixtures/presets/alpha/preset.yml
new file mode 100644
index 0000000000..baad117978
--- /dev/null
+++ b/packages/dsh-acp/tests/fixtures/presets/alpha/preset.yml
@@ -0,0 +1,3 @@
+name: Alpha mode
+description: the fixture default
+order: 1
diff --git a/packages/dsh-acp/tests/fixtures/presets/beta/agent.cordis.yml b/packages/dsh-acp/tests/fixtures/presets/beta/agent.cordis.yml
new file mode 100644
index 0000000000..f863e47626
--- /dev/null
+++ b/packages/dsh-acp/tests/fixtures/presets/beta/agent.cordis.yml
@@ -0,0 +1,5 @@
+# The mode a test switches TO: a disjoint tool set, so a recompose is visible.
+- id: beta-tool
+  name: ../../plugins/contribute.js
+  config:
+    tool: beta
diff --git a/packages/dsh-acp/tests/fixtures/presets/beta/preset.yml b/packages/dsh-acp/tests/fixtures/presets/beta/preset.yml
new file mode 100644
index 0000000000..fd31deadb2
--- /dev/null
+++ b/packages/dsh-acp/tests/fixtures/presets/beta/preset.yml
@@ -0,0 +1,3 @@
+name: Beta mode
+description: the fixture alternative
+order: 2
diff --git a/packages/dsh-acp/tests/fixtures/presets/broken/preset.yml b/packages/dsh-acp/tests/fixtures/presets/broken/preset.yml
new file mode 100644
index 0000000000..5e40795aeb
--- /dev/null
+++ b/packages/dsh-acp/tests/fixtures/presets/broken/preset.yml
@@ -0,0 +1,6 @@
+# A roster row the deployment must fix: the directory occupies the id but
+# carries no `agent.cordis.yml`, so discovery reports it broken. It exists to
+# prove the mode picker withholds a choice every attempt would refuse.
+name: Broken mode
+description: the fixture nobody can compose
+order: 3
diff --git a/packages/dsh-acp/tests/harness.ts b/packages/dsh-acp/tests/harness.ts
new file mode 100644
index 0000000000..7ec8a50c8f
--- /dev/null
+++ b/packages/dsh-acp/tests/harness.ts
@@ -0,0 +1,281 @@
+/**
+ * In-memory ACP transport fixture over the real agent factory and loop.
+ *
+ * Adapted from `deepseek-harness/packages/acp/acp/tests/harness.ts` (MIT,
+ * copyright (c) DeepSeek); see ../NOTICE.md. The only substantive change is the
+ * plugin under test — `../src/bridge.ts` instead of `@deepseek-ai/dsh-acp` —
+ * plus `orderedEvents`, which records session updates and permission requests
+ * on one timeline so a test can assert their relative order.
+ */
+
+import { dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { Context } from '@deepseek-ai/cordis'
+import Loader from '@deepseek-ai/cordis-plugin-loader'
+import AgentPresets from '@deepseek-ai/dsh-agent-presets'
+import {
+  ClientSideConnection,
+  ndJsonStream,
+  type Agent as AcpAgent,
+  type Client,
+  type RequestPermissionRequest,
+  type RequestPermissionResponse,
+  type SessionNotification,
+  type Stream,
+} from '@agentclientprotocol/sdk'
+import { type GenerateOptions, LlmAdapter, type StreamChunk } from '@deepseek-ai/dsh-llm'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
+import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
+import * as AcpPlugin from '../src/bridge.ts'
+import type { AcpConfig } from '../src/bridge.ts'
+
+/** Scripted adapter for protocol tests. */
+class MockAdapter extends LlmAdapter {
+  readonly requests: GenerateOptions[] = []
+  private readonly script: (StreamChunk[] | 'hang')[]
+
+  constructor(script: (StreamChunk[] | 'hang')[]) {
+    super()
+    this.script = script
+  }
+
+  override providerInfo(provider: string) {
+    if (provider !== 'mock') throw new Error(`MockAdapter: unknown provider ${provider}`)
+    return { id: 'mock', name: 'Mock' }
+  }
+
+  override listModels(provider: string) {
+    return Promise.resolve(provider === 'mock' ? [{ provider: 'mock', id: 'mock', name: 'Mock' }] : [])
+  }
+
+  async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    this.requests.push(options)
+    const entry = this.script.shift()
+    if (entry === undefined) throw new Error('MockAdapter: script exhausted')
+    if (entry === 'hang') {
+      yield { type: 'block-start', index: 0, blockType: 'text' }
+      yield { type: 'text-delta', index: 0, text: 'partial' }
+      await new Promise<void>((_resolve, reject) => {
+        if (options.signal?.aborted) {
+          reject(new Error('aborted'))
+          return
+        }
+        options.signal?.addEventListener('abort', () => { reject(new Error('aborted')) }, { once: true })
+      })
+      return
+    }
+    for (const chunk of entry) {
+      if (options.signal?.aborted) throw new Error('aborted')
+      yield chunk
+    }
+  }
+}
+
+/** Scripted text response ending in a clean stop. */
+export function textResponse(text: string): StreamChunk[] {
+  return [
+    { type: 'block-start', index: 0, blockType: 'text' },
+    ...Array.from(text, (char): StreamChunk => ({ type: 'text-delta', index: 0, text: char })),
+    { type: 'block-end', index: 0, block: { type: 'text', text } },
+    { type: 'usage', usage: { inputTokens: 5, outputTokens: text.length } },
+    { type: 'finish', reason: { kind: 'stop' } },
+  ]
+}
+
+/**
+ * The fixture preset roster: `alpha` and `beta`, each contributing one tool
+ * named after itself, so a test can read a session's composition off its tool
+ * list and see a recompose replace it.
+ */
+export const PRESET_FIXTURES = join(dirname(fileURLToPath(import.meta.url)), 'fixtures', 'presets')
+
+/** Scripted response that fails after publishing an uncommitted partial chunk. */
+export function errorResponse(message: string): StreamChunk[] {
+  return [
+    { type: 'block-start', index: 0, blockType: 'text' },
+    { type: 'text-delta', index: 0, text: 'partial' },
+    { type: 'finish', reason: { kind: 'error', failure: { message, code: 'PROVIDER_ERROR' } } },
+  ]
+}
+
+export type CapturedUpdate = SessionNotification['update']
+
+/**
+ * One entry on the client-observed timeline. Session updates and permission
+ * requests arrive over the same connection, so recording them together is the
+ * only way to assert that a tool card precedes the prompt that references it.
+ */
+export type OrderedEvent =
+  | { kind: 'update'; update: CapturedUpdate }
+  | { kind: 'permission'; request: RequestPermissionRequest }
+
+export interface BridgeHarness {
+  ctx: Context
+  client: ClientSideConnection
+  adapter: MockAdapter
+  updates: CapturedUpdate[]
+  sessionUpdates: { sessionId: string; update: CapturedUpdate }[]
+  permissionRequests: RequestPermissionRequest[]
+  /** Updates and permission requests interleaved in arrival order. */
+  orderedEvents: OrderedEvent[]
+  onPermission: (request: RequestPermissionRequest) => RequestPermissionResponse
+  closeClientTransport: () => Promise<void>
+  acpFiber: Awaited<ReturnType<Context['plugin']>>
+  /** The AgentLoop fiber, so a test can reload the loop out from under the bridge. */
+  loopFiber: Awaited<ReturnType<Context['plugin']>>
+  dispose: () => Promise<void>
+}
+
+type AcpConfigOverrides = { [K in keyof AcpConfig]?: AcpConfig[K] | undefined }
+
+/** Build the bridge and a connected SDK client over cross-wired byte streams. */
+export async function makeBridgeHarness(options: {
+  script?: (StreamChunk[] | 'hang')[]
+  config?: AcpConfigOverrides
+  persona?: string
+  /**
+   * Mount the {@link PRESET_FIXTURES} roster with this default, so the bridge
+   * composes sessions from a preset and offers the modes as a session config
+   * option. Omitted, no roster is published and the bridge takes its no-modes
+   * path.
+   */
+  presets?: { default: string }
+  /**
+   * Mount durable JSONL persistence under this root, so a session outlives its
+   * agent and `session/load` has something to resume. Omitted, the deployment
+   * persists nothing and the bridge takes its no-archive path.
+   */
+  persistenceRoot?: string
+} = {}): Promise<BridgeHarness> {
+  const adapter = new MockAdapter(options.script ?? [])
+  const ctx = new Context()
+  await mountAgentLoopTestDependencies(ctx, { systemPrompt: { persona: options.persona ?? '' } })
+  // Before the loop, as the app composes it: the coordinator captures a
+  // session's header from `session/created`, which the first agent emits.
+  if (options.persistenceRoot !== undefined) {
+    await ctx.plugin(JsonlSessionPersistence, { root: options.persistenceRoot })
+  }
+  const loopFiber = await ctx.plugin(AgentLoop, { agents: [] })
+  ctx.llm.registerAdapter(['mock'], adapter)
+  if (options.presets !== undefined) {
+    // Before the bridge: it captures the roster during `apply`, exactly as the
+    // app's composition orders them.
+    ctx.baseUrl = pathToFileURL(PRESET_FIXTURES).href + '/'
+    await ctx.plugin(Loader)
+    await ctx.plugin(AgentPresets, {
+      default: options.presets.default,
+      roots: [{ path: PRESET_FIXTURES, trust: 'system' as const }],
+      includeUserRoot: false,
+    })
+  }
+
+  const agentToClient = new TransformStream<Uint8Array, Uint8Array>()
+  const clientToAgent = new TransformStream<Uint8Array, Uint8Array>()
+  const clientToAgentWriter = clientToAgent.writable.getWriter()
+  const clientOutput = new WritableStream<Uint8Array>({
+    write: chunk => clientToAgentWriter.write(chunk),
+  })
+  const agentStream: Stream = ndJsonStream(agentToClient.writable, clientToAgent.readable)
+  const clientStream: Stream = ndJsonStream(clientOutput, agentToClient.readable)
+
+  const updates: CapturedUpdate[] = []
+  const sessionUpdates: { sessionId: string; update: CapturedUpdate }[] = []
+  const permissionRequests: RequestPermissionRequest[] = []
+  const orderedEvents: OrderedEvent[] = []
+  const harness: BridgeHarness = {
+    ctx,
+    adapter,
+    updates,
+    sessionUpdates,
+    permissionRequests,
+    orderedEvents,
+    onPermission: () => ({ outcome: { outcome: 'cancelled' } }),
+    client: undefined as unknown as ClientSideConnection,
+    acpFiber: undefined as unknown as BridgeHarness['acpFiber'],
+    loopFiber,
+    closeClientTransport: async () => { await clientToAgentWriter.close() },
+    dispose: async () => { await ctx.fiber.dispose() },
+  }
+
+  const makeClient = (_agent: AcpAgent): Client => ({
+    sessionUpdate(params: SessionNotification): Promise<void> {
+      updates.push(params.update)
+      sessionUpdates.push({ sessionId: params.sessionId, update: params.update })
+      orderedEvents.push({ kind: 'update', update: params.update })
+      return Promise.resolve()
+    },
+    requestPermission(params: RequestPermissionRequest): Promise<RequestPermissionResponse> {
+      permissionRequests.push(params)
+      orderedEvents.push({ kind: 'permission', request: params })
+      return Promise.resolve(harness.onPermission(params))
+    },
+  })
+
+  const config = { stream: agentStream, ...options.config } as AcpConfig
+  if (!(options.config && 'provider' in options.config)) config.provider = 'mock'
+  if (!(options.config && 'model' in options.config)) config.model = 'mock'
+  harness.acpFiber = await ctx.plugin({
+    name: 'acp-ide-test',
+    inject: [...AcpPlugin.inject],
+    apply: (inner: Context) => { AcpPlugin.apply(inner, config) },
+  })
+  harness.client = new ClientSideConnection(makeClient, clientStream)
+  return harness
+}
+
+/**
+ * Wait until the client has observed at least `count` timeline entries.
+ * @param harness - the fixture whose client timeline is polled.
+ * @param count - the number of entries to wait for.
+ */
+export async function waitForEvents(harness: BridgeHarness, count: number): Promise<void> {
+  const deadline = Date.now() + 2000
+  while (harness.orderedEvents.length < count) {
+    if (Date.now() > deadline) {
+      throw new Error(`timed out waiting for ${count} client events (saw ${harness.orderedEvents.length})`)
+    }
+    await new Promise(resolve => setTimeout(resolve, 5))
+  }
+}
+
+/**
+ * Wait until the client has observed `count` session updates of one kind.
+ *
+ * `waitForEvents` counts everything the session has produced, so a finished
+ * prompt already satisfies it. That makes it useless for waiting on a
+ * notification the bridge publishes off the back of an event rather than as
+ * part of the prompt reply — the wait returns at once and the assertion races
+ * the notification. Wait for the notification itself instead.
+ * @param harness - the fixture whose updates are polled.
+ * @param kind - the `sessionUpdate` discriminant to count.
+ * @param count - the number of such updates to wait for.
+ */
+export async function waitForUpdates<K extends CapturedUpdate['sessionUpdate']>(
+  harness: BridgeHarness, kind: K, count: number,
+): Promise<void> {
+  const deadline = Date.now() + 2000
+  while (updatesOfKind(harness, kind).length < count) {
+    if (Date.now() > deadline) {
+      throw new Error(
+        `timed out waiting for ${count} ${kind} update(s) `
+        + `(saw ${updatesOfKind(harness, kind).length})`,
+      )
+    }
+    await new Promise(resolve => setTimeout(resolve, 5))
+  }
+}
+
+/**
+ * Collect every session update of one kind that the client has observed.
+ * @param harness - the fixture to read.
+ * @param kind - the `sessionUpdate` discriminator to keep.
+ * @returns the matching updates in arrival order.
+ */
+export function updatesOfKind<K extends CapturedUpdate['sessionUpdate']>(
+  harness: BridgeHarness, kind: K,
+): Extract<CapturedUpdate, { sessionUpdate: K }>[] {
+  return harness.updates.filter(
+    (update): update is Extract<CapturedUpdate, { sessionUpdate: K }> => update.sessionUpdate === kind,
+  )
+}
diff --git a/packages/dsh-acp/tests/lifecycle.spec.ts b/packages/dsh-acp/tests/lifecycle.spec.ts
new file mode 100644
index 0000000000..a173ec6152
--- /dev/null
+++ b/packages/dsh-acp/tests/lifecycle.spec.ts
@@ -0,0 +1,79 @@
+/**
+ * Regression cover for the upstream machinery this fork keeps verbatim: prompt
+ * settlement, cancellation, and the single in-flight slot. Where behavior
+ * intentionally diverges — a streaming client sees deltas, including a failed
+ * turn's partial text — the test says so.
+ */
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import { errorResponse, makeBridgeHarness, textResponse, type BridgeHarness } from './harness.ts'
+
+/** All published assistant text, concatenated in arrival order. */
+function messageText(harness: BridgeHarness): string {
+  return harness.updates.flatMap(update => (
+    update.sessionUpdate === 'agent_message_chunk' && update.content.type === 'text'
+      ? [update.content.text]
+      : []
+  )).join('')
+}
+
+describe('ACP prompt lifecycle', () => {
+  let harness: BridgeHarness | undefined
+
+  afterEach(async () => {
+    await harness?.dispose()
+    harness = undefined
+  })
+
+  async function newSession(): Promise<string> {
+    if (harness === undefined) throw new Error('missing harness')
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    return (await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })).sessionId
+  }
+
+  it('streams a whole turn and settles it as end_turn', async () => {
+    harness = await makeBridgeHarness({ script: [textResponse('answer')] })
+    const sessionId = await newSession()
+    await expect(harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] }))
+      .resolves.toEqual({ stopReason: 'end_turn' })
+    await vi.waitFor(() => { expect(messageText(harness!)).toBe('answer') })
+    // Character deltas, not one committed blob: this is the streaming an IDE
+    // renders live, and the commit must not duplicate it.
+    expect(harness.updates.filter(update => update.sessionUpdate === 'agent_message_chunk')).toHaveLength(6)
+  })
+
+  it('rejects a failed turn but keeps the partial text it already streamed', async () => {
+    harness = await makeBridgeHarness({ script: [errorResponse('provider boom')] })
+    const sessionId = await newSession()
+    await expect(harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] }))
+      .rejects.toThrow(/turn failed: provider boom/)
+    // Deliberate divergence from the automation bridge, which withholds every
+    // uncommitted chunk: a live client has already shown these characters, and
+    // the prompt rejection is what tells it the turn failed.
+    expect(messageText(harness)).toBe('partial')
+  })
+
+  it('permits one in-flight prompt and continues the session after a cancel', async () => {
+    harness = await makeBridgeHarness({ script: ['hang', textResponse('second')] })
+    const sessionId = await newSession()
+    const first = harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'one' }] })
+    await vi.waitFor(() => { expect(harness!.ctx.agents.get(SessionId(sessionId))?.status).toBe('running') })
+    await expect(harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'two' }] }))
+      .rejects.toThrow(/already in flight/)
+
+    await harness.client.cancel({ sessionId })
+    await expect(first).resolves.toEqual({ stopReason: 'cancelled' })
+    await expect(harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'again' }] }))
+      .resolves.toEqual({ stopReason: 'end_turn' })
+    await vi.waitFor(() => { expect(messageText(harness!)).toContain('second') })
+  })
+
+  it('refuses a prompt for an unknown session', async () => {
+    harness = await makeBridgeHarness()
+    await newSession()
+    await expect(harness.client.prompt({ sessionId: 'nope', prompt: [{ type: 'text', text: 'go' }] }))
+      .rejects.toThrow(/unknown session/)
+  })
+})
diff --git a/packages/dsh-acp/tests/preset-modes.spec.ts b/packages/dsh-acp/tests/preset-modes.spec.ts
new file mode 100644
index 0000000000..9f26103090
--- /dev/null
+++ b/packages/dsh-acp/tests/preset-modes.spec.ts
@@ -0,0 +1,172 @@
+/**
+ * Modes: the preset roster a session is composed from, offered to the client as
+ * a `mode` session config option and fixed once the conversation starts.
+ *
+ * The switch is driven the way a client's composer picker drives it — through
+ * `session/set_config_option` — and the result is read off the session's tool
+ * list rather than off anything the bridge reports about itself.
+ */
+
+import { afterEach, describe, expect, it } from 'vitest'
+import { PROTOCOL_VERSION, type SessionConfigOption } from '@agentclientprotocol/sdk'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import {
+  makeBridgeHarness, textResponse, updatesOfKind, waitForUpdates, type BridgeHarness,
+} from './harness.ts'
+
+/** The tools a session's model can call, i.e. what its preset composed. */
+function toolNames(harness: BridgeHarness, sessionId: string): string[] {
+  const agent = harness.ctx.agents.get(SessionId(sessionId))
+  if (agent === undefined) throw new Error(`no agent for session ${sessionId}`)
+  return harness.ctx.tools.schemas(agent).map(schema => schema.name).sort()
+}
+
+/** Every preset the session has been switched to, in order. */
+function selections(harness: BridgeHarness, sessionId: string): unknown[] {
+  const agent = harness.ctx.agents.get(SessionId(sessionId))
+  if (agent === undefined) throw new Error(`no agent for session ${sessionId}`)
+  return agent.session.events
+    .filter(event => event.type === 'agent-preset/selected')
+    .map(event => (event as { data: { agentPreset: string } }).data.agentPreset)
+}
+
+/** The one mode option, asserted to be a select so its values can be read. */
+function modeOption(configOptions: SessionConfigOption[] | null | undefined): Extract<
+  SessionConfigOption, { type: 'select' }
+> {
+  const [option, ...rest] = configOptions ?? []
+  expect(rest).toEqual([])
+  if (option?.type !== 'select') throw new Error(`expected one select option, got ${JSON.stringify(configOptions)}`)
+  return option
+}
+
+/** The values a client's picker would list, in roster order. */
+function modeValues(configOptions: SessionConfigOption[] | null | undefined): string[] {
+  return modeOption(configOptions).options.map(value => ('value' in value ? value.value : value.group))
+}
+
+describe('agent-preset modes', () => {
+  let harness: BridgeHarness | undefined
+
+  afterEach(async () => {
+    await harness?.dispose()
+    harness = undefined
+  })
+
+  it('composes the default preset and offers the roster with session/new', async () => {
+    harness = await makeBridgeHarness({ presets: { default: 'alpha' } })
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const session = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
+
+    expect(toolNames(harness, session.sessionId)).toEqual(['alpha'])
+    const option = modeOption(session.configOptions)
+    expect(option.id).toBe('agent-preset')
+    expect(option.category).toBe('mode')
+    expect(option.currentValue).toBe('alpha')
+    // `broken` is withheld: offering it would advertise a choice every attempt
+    // refuses. Nothing says the mode is fixed yet, because it is not.
+    expect(option.options).toEqual([
+      { value: 'alpha', name: 'Alpha mode', description: 'the fixture default' },
+      { value: 'beta', name: 'Beta mode', description: 'the fixture alternative' },
+    ])
+    expect(option.description).toBeUndefined()
+  })
+
+  it('recomposes a blank session, without a model turn', async () => {
+    harness = await makeBridgeHarness({ presets: { default: 'alpha' } })
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
+
+    const result = await harness.client.setSessionConfigOption({
+      sessionId, configId: 'agent-preset', value: 'beta',
+    })
+
+    // The exchange is a control, not a turn: the model is never asked.
+    expect(harness.adapter.requests).toHaveLength(0)
+    expect(toolNames(harness, sessionId)).toEqual(['beta'])
+    expect(selections(harness, sessionId)).toEqual(['beta'])
+    // The response carries the whole set, so the picker re-renders from it.
+    expect(modeOption(result.configOptions).currentValue).toBe('beta')
+    expect(modeValues(result.configOptions)).toEqual(['alpha', 'beta'])
+  })
+
+  it('answers a repeat of the session\'s own mode without recomposing', async () => {
+    harness = await makeBridgeHarness({ presets: { default: 'alpha' } })
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
+
+    const result = await harness.client.setSessionConfigOption({
+      sessionId, configId: 'agent-preset', value: 'alpha',
+    })
+
+    expect(modeOption(result.configOptions).currentValue).toBe('alpha')
+    expect(selections(harness, sessionId)).toEqual([])
+    expect(toolNames(harness, sessionId)).toEqual(['alpha'])
+  })
+
+  it('refuses an option, a mode, and a value type it does not have', async () => {
+    harness = await makeBridgeHarness({ presets: { default: 'alpha' } })
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
+
+    await expect(harness.client.setSessionConfigOption({
+      sessionId, configId: 'thought-level', value: 'high',
+    })).rejects.toThrow(/unknown config option: thought-level/)
+    await expect(harness.client.setSessionConfigOption({
+      sessionId, configId: 'agent-preset', value: 'gamma',
+    })).rejects.toThrow(/unknown mode: gamma/)
+    await expect(harness.client.setSessionConfigOption({
+      sessionId, configId: 'agent-preset', value: 'broken',
+    })).rejects.toThrow(/cannot be used/)
+    await expect(harness.client.setSessionConfigOption({
+      sessionId, configId: 'agent-preset', type: 'boolean', value: true,
+    })).rejects.toThrow(/select option, not a boolean/)
+
+    expect(toolNames(harness, sessionId)).toEqual(['alpha'])
+    expect(selections(harness, sessionId)).toEqual([])
+  })
+
+  it('fixes the mode once the conversation has started, and says so once', async () => {
+    harness = await makeBridgeHarness({
+      presets: { default: 'alpha' },
+      script: [textResponse('hi'), textResponse('again')],
+    })
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
+    await harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'hello' }] })
+
+    await expect(harness.client.setSessionConfigOption({
+      sessionId, configId: 'agent-preset', value: 'beta',
+    })).rejects.toThrow(/already started/)
+
+    expect(toolNames(harness, sessionId)).toEqual(['alpha'])
+    expect(selections(harness, sessionId)).toEqual([])
+    // The picker was shrunk to the mode in force, which is how a client learns
+    // to disable it without knowing anything about presets.
+    await waitForUpdates(harness, 'config_option_update', 1)
+    const [locked, ...repeats] = updatesOfKind(harness, 'config_option_update')
+    expect(modeValues(locked?.configOptions)).toEqual(['alpha'])
+    expect(modeOption(locked?.configOptions).description).toMatch(/already started/)
+
+    // A second turn does not say it again.
+    await harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'more' }] })
+    expect(repeats).toEqual([])
+    expect(updatesOfKind(harness, 'config_option_update')).toHaveLength(1)
+  })
+
+  it('offers nothing when the deployment has no roster', async () => {
+    harness = await makeBridgeHarness({ script: [textResponse('ok')] })
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const session = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
+
+    expect(session.configOptions ?? []).toEqual([])
+    await expect(harness.client.setSessionConfigOption({
+      sessionId: session.sessionId, configId: 'agent-preset', value: 'beta',
+    })).rejects.toThrow(/offers no modes/)
+
+    // A turn still runs, and still announces nothing about modes.
+    await harness.client.prompt({ sessionId: session.sessionId, prompt: [{ type: 'text', text: 'hi' }] })
+    expect(harness.adapter.requests).toHaveLength(1)
+    expect(updatesOfKind(harness, 'config_option_update')).toEqual([])
+  })
+})
diff --git a/packages/dsh-acp/tests/round-trip.spec.ts b/packages/dsh-acp/tests/round-trip.spec.ts
new file mode 100644
index 0000000000..a1fb8a8ea7
--- /dev/null
+++ b/packages/dsh-acp/tests/round-trip.spec.ts
@@ -0,0 +1,116 @@
+/**
+ * The whole path in one test: a model asks for a tool, the loop appends
+ * `tool/call`, the scheduler asks for approval, the tool runs, and the client
+ * sees a card that opens before the prompt and closes after the result.
+ *
+ * The hand-driven specs assert each mapping in isolation; this one is the only
+ * place the ORDER is a fact about the production loop rather than about how a
+ * test appended events.
+ */
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk'
+import { CallId, type StreamChunk } from '@deepseek-ai/dsh-llm'
+import { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
+import ApprovalService from '@deepseek-ai/dsh-user-approval'
+import { makeBridgeHarness, textResponse, type BridgeHarness } from './harness.ts'
+
+/** One scripted model step that calls `write` and stops for its result. */
+const CALL_WRITE: StreamChunk[] = [
+  { type: 'block-start', index: 0, blockType: 'tool-call' },
+  {
+    type: 'block-end',
+    index: 0,
+    block: {
+      type: 'tool-call',
+      id: CallId('call-write'),
+      name: 'write',
+      arguments: JSON.stringify({ file_path: '/repo/notes.md', content: 'hi' }),
+    },
+  },
+  { type: 'finish', reason: { kind: 'tool-calls' } },
+]
+
+describe('ACP tool-call round trip', () => {
+  let harness: BridgeHarness | undefined
+
+  afterEach(async () => {
+    await harness?.dispose()
+    harness = undefined
+  })
+
+  it('opens the card, asks, runs, and closes it — in that order', async () => {
+    harness = await makeBridgeHarness({ script: [CALL_WRITE, textResponse('written')] })
+    await harness.ctx.plugin(ApprovalService)
+    harness.ctx.tools.register(defineContentToolFixture({
+      name: 'write',
+      description: 'write a file',
+      parameters: { file_path: { type: 'string' }, content: { type: 'string' } },
+      execute: () => Promise.resolve([{ type: 'text', text: 'wrote 2 bytes' }]),
+    }))
+    // The production ask path: the scheduler waterfalls `tools/pre-execute`
+    // before dispatch, and an `ask` decision routes through ctx.approval.
+    harness.ctx.on('tools/pre-execute', () => Promise.resolve({ kind: 'ask', reason: 'test policy' }))
+    harness.onPermission = () => ({ outcome: { outcome: 'selected', optionId: 'allow-once' } })
+
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
+    const result = await harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'write notes' }] })
+    expect(result.stopReason).toBe('end_turn')
+
+    await vi.waitFor(() => {
+      expect(harness!.orderedEvents.some(event => event.kind === 'update'
+        && event.update.sessionUpdate === 'tool_call_update'
+        && event.update.status === 'completed')).toBe(true)
+    })
+
+    const trace = harness.orderedEvents.flatMap((event) => {
+      if (event.kind === 'permission') return [`permission:${event.request.toolCall.toolCallId}`]
+      const update = event.update
+      if (update.sessionUpdate === 'tool_call') return [`open:${update.toolCallId}:${update.status ?? ''}`]
+      if (update.sessionUpdate === 'tool_call_update') return [`${update.status}:${update.toolCallId}`]
+      return []
+    })
+    expect(trace).toEqual([
+      'open:call-write:pending',
+      'permission:call-write',
+      'in_progress:call-write',
+      'completed:call-write',
+    ])
+
+    const permission = harness.permissionRequests[0]
+    expect(permission?.toolCall).toMatchObject({ title: 'write', kind: 'edit' })
+    expect(permission?.toolCall.rawInput).toEqual({ file_path: '/repo/notes.md', content: 'hi' })
+
+    const completed = harness.updates.find(update => update.sessionUpdate === 'tool_call_update'
+      && update.status === 'completed')
+    expect(completed).toMatchObject({
+      content: [{ type: 'content', content: { type: 'text', text: 'wrote 2 bytes' } }],
+    })
+  })
+
+  it('closes the card as failed when the user rejects the call', async () => {
+    harness = await makeBridgeHarness({ script: [CALL_WRITE, textResponse('stopped')] })
+    await harness.ctx.plugin(ApprovalService)
+    harness.ctx.tools.register(defineContentToolFixture({
+      name: 'write',
+      description: 'write a file',
+      parameters: { file_path: { type: 'string' }, content: { type: 'string' } },
+      execute: () => Promise.reject(new Error('must not run')),
+    }))
+    harness.ctx.on('tools/pre-execute', () => Promise.resolve({ kind: 'ask', reason: 'test policy' }))
+    harness.onPermission = () => ({ outcome: { outcome: 'selected', optionId: 'reject-once' } })
+
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
+    await harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'write notes' }] })
+
+    await vi.waitFor(() => {
+      expect(harness!.updates.some(update => update.sessionUpdate === 'tool_call_update')).toBe(true)
+    })
+    const settled = harness.updates.filter(update => update.sessionUpdate === 'tool_call_update')
+    // A rejection never reaches `in_progress`; the denial arrives as the result.
+    expect(settled.map(update => update.status)).toEqual(['failed'])
+    expect(settled[0]).toMatchObject({ toolCallId: 'call-write' })
+  })
+})
diff --git a/packages/dsh-acp/tests/session-load.spec.ts b/packages/dsh-acp/tests/session-load.spec.ts
new file mode 100644
index 0000000000..5e390fea3f
--- /dev/null
+++ b/packages/dsh-acp/tests/session-load.spec.ts
@@ -0,0 +1,160 @@
+/**
+ * Reopening a persisted conversation: `session/load` resumes the stored
+ * session, replays its history to the client, and brings back the mode it ran
+ * under — the three things an IDE loses when a reopen silently becomes a new
+ * session.
+ *
+ * The conversation under test is seeded OUTSIDE the bridge and then left to go
+ * cold, which is what a client restart actually looks like from the agent's
+ * side: nothing about the session is still in memory when the load arrives.
+ */
+
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { afterEach, describe, expect, it } from 'vitest'
+import { PROTOCOL_VERSION, RequestError, type SessionConfigOption } from '@agentclientprotocol/sdk'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import {
+  makeBridgeHarness, textResponse, updatesOfKind, waitForUpdates, type BridgeHarness,
+} from './harness.ts'
+
+/** The one mode option, asserted to be a select so its values can be read. */
+function modeOption(configOptions: SessionConfigOption[] | null | undefined): Extract<
+  SessionConfigOption, { type: 'select' }
+> {
+  const [option, ...rest] = configOptions ?? []
+  expect(rest).toEqual([])
+  if (option?.type !== 'select') throw new Error(`expected one select option, got ${JSON.stringify(configOptions)}`)
+  return option
+}
+
+/** The text of every update of one kind, in arrival order. */
+function textsOfKind(
+  harness: BridgeHarness, kind: 'user_message_chunk' | 'agent_message_chunk',
+): string[] {
+  return updatesOfKind(harness, kind)
+    .map(update => (update.content.type === 'text' ? update.content.text : ''))
+}
+
+/**
+ * Seed one persisted conversation and let it go cold.
+ * @param harness - the fixture whose registry and roster compose the agent.
+ * @param cwd - the working directory the session is created in.
+ * @param prompt - the user text the scripted model answers.
+ * @returns the persisted session id, with no live agent left behind.
+ */
+async function seedColdSession(
+  harness: BridgeHarness, cwd: string, prompt: string,
+): Promise<string> {
+  const sessionId = SessionId(randomUUID())
+  const presets = harness.ctx.get('agentPresets')
+  if (presets === undefined) throw new Error('the fixture roster is required to seed a session')
+  const handle = await harness.ctx.agents.create({
+    sessionId,
+    meta: { cwd, agentPreset: 'alpha' },
+    agentOptions: { provider: 'mock', model: 'mock' },
+    setup: async (agentCtx) => void await presets.mount(agentCtx, 'alpha'),
+  })
+  handle.agent.followup(createUserMessage({
+    content: [{ type: 'text', text: prompt }],
+    source: { kind: 'user' },
+  }))
+  await handle.agent.whenIdle()
+  // Disposal is what makes this a COLD load: the agent, its session, and the
+  // loop state are gone, and only the durable log remains.
+  await handle.dispose()
+  return sessionId
+}
+
+describe('session/load', () => {
+  let harness: BridgeHarness | undefined
+  let root: string | undefined
+
+  afterEach(async () => {
+    await harness?.dispose()
+    harness = undefined
+    if (root !== undefined) await rm(root, { recursive: true, force: true })
+    root = undefined
+  })
+
+  it('advertises the capability', async () => {
+    harness = await makeBridgeHarness()
+    const result = await harness.client.initialize({
+      protocolVersion: PROTOCOL_VERSION, clientCapabilities: {},
+    })
+
+    expect(result.agentCapabilities?.loadSession).toBe(true)
+  })
+
+  it('resumes a cold session with its history, mode, and context', async () => {
+    root = await mkdtemp(join(tmpdir(), 'dsh-acp-load-'))
+    harness = await makeBridgeHarness({
+      script: [textResponse('stored answer'), textResponse('second answer')],
+      presets: { default: 'beta' },
+      persistenceRoot: root,
+    })
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const cwd = process.cwd()
+    const sessionId = await seedColdSession(harness, cwd, 'stored question')
+    expect(harness.ctx.agents.get(SessionId(sessionId))).toBeUndefined()
+
+    const loaded = await harness.client.loadSession({ sessionId, cwd, mcpServers: [] })
+
+    // The transcript the client renders comes only from replay.
+    await waitForUpdates(harness, 'agent_message_chunk', 1)
+    expect(textsOfKind(harness, 'user_message_chunk')).toEqual(['stored question'])
+    expect(textsOfKind(harness, 'agent_message_chunk')).toEqual(['stored answer'])
+    // The stored preset wins over the roster default (`beta`), and a session
+    // whose conversation has started comes back with the mode fixed.
+    const option = modeOption(loaded.configOptions)
+    expect(option.currentValue).toBe('alpha')
+    expect(option.options).toEqual([
+      { value: 'alpha', name: 'Alpha mode', description: 'the fixture default' },
+    ])
+    expect(option.description).toContain('already started')
+    const resumed = harness.ctx.agents.get(SessionId(sessionId))
+    expect(resumed).toBeDefined()
+    expect(harness.ctx.tools.schemas(resumed!).map(schema => schema.name)).toEqual(['alpha'])
+
+    // Context, not just presentation: the next prompt carries the stored turn.
+    const response = await harness.client.prompt({
+      sessionId, prompt: [{ type: 'text', text: 'follow-up' }],
+    })
+
+    expect(response.stopReason).toBe('end_turn')
+    const request = harness.adapter.requests.at(-1)
+    const sent = JSON.stringify(request?.messages ?? [])
+    expect(sent).toContain('stored question')
+    expect(sent).toContain('stored answer')
+  })
+
+  it('refuses a session it has never stored', async () => {
+    root = await mkdtemp(join(tmpdir(), 'dsh-acp-load-'))
+    harness = await makeBridgeHarness({ persistenceRoot: root })
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+
+    // Refused rather than answered with a blank session: a client that is told
+    // "no such session" can fall back to session/new and know it did.
+    await expect(harness.client.loadSession({
+      sessionId: randomUUID(), cwd: process.cwd(), mcpServers: [],
+    })).rejects.toThrow(RequestError)
+  })
+
+  it('refuses a session stored for another directory', async () => {
+    root = await mkdtemp(join(tmpdir(), 'dsh-acp-load-'))
+    harness = await makeBridgeHarness({
+      script: [textResponse('stored answer')],
+      presets: { default: 'alpha' },
+      persistenceRoot: root,
+    })
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const sessionId = await seedColdSession(harness, process.cwd(), 'stored question')
+
+    await expect(harness.client.loadSession({
+      sessionId, cwd: tmpdir(), mcpServers: [],
+    })).rejects.toThrow(RequestError)
+  })
+})
diff --git a/packages/dsh-acp/tests/tool-events.spec.ts b/packages/dsh-acp/tests/tool-events.spec.ts
new file mode 100644
index 0000000000..596b72603b
--- /dev/null
+++ b/packages/dsh-acp/tests/tool-events.spec.ts
@@ -0,0 +1,242 @@
+/** The presentation data this fork exists to publish: tool cards, plans, text. */
+
+import { afterEach, describe, expect, it } from 'vitest'
+import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk'
+import { CallId, createAssistantMessage, createToolResultMessage } from '@deepseek-ai/dsh-llm'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import { makeBridgeHarness, updatesOfKind, waitForEvents, type BridgeHarness } from './harness.ts'
+
+/** Surface-eligible events must declare how they enter the ordered surface. */
+const SURFACE = { surfaceOp: 'append' } as const
+
+/** The provenance every scripted assistant message carries in these tests. */
+const PROVENANCE = { provider: 'mock', model: 'mock' } as const
+
+describe('ACP session-event publication', () => {
+  let harness: BridgeHarness | undefined
+
+  afterEach(async () => {
+    await harness?.dispose()
+    harness = undefined
+  })
+
+  /** Open a session and hand back its live agent, ready to append events to. */
+  async function openSession(config?: { reasoning?: boolean }): Promise<Agent> {
+    harness = await makeBridgeHarness(config === undefined ? {} : { config })
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
+    const agent = harness.ctx.agents.get(SessionId(sessionId))
+    if (agent === undefined) throw new Error('missing agent')
+    agent.session.append('turn/start', { turn: 1 })
+    agent.session.append('step/start', { turn: 1, step: 0 })
+    return agent
+  }
+
+  it('publishes a tool call as a pending card and its result as completed', async () => {
+    const agent = await openSession()
+    const callId = CallId('call-1')
+    agent.session.append('tool/call', {
+      turn: 1,
+      step: 0,
+      callId,
+      name: 'read',
+      arguments: JSON.stringify({ file_path: '/repo/src/main.ts', offset: 40 }),
+    })
+    agent.session.append('tool/result', {
+      turn: 1,
+      step: 0,
+      message: createToolResultMessage({
+        callId, content: [{ type: 'text', text: 'file body' }], isError: false,
+      }),
+    }, SURFACE)
+    await waitForEvents(harness!, 2)
+
+    expect(updatesOfKind(harness!, 'tool_call')[0]).toMatchObject({
+      sessionUpdate: 'tool_call',
+      toolCallId: 'call-1',
+      title: 'read',
+      kind: 'read',
+      status: 'pending',
+      rawInput: { file_path: '/repo/src/main.ts', offset: 40 },
+      locations: [{ path: '/repo/src/main.ts', line: 40 }],
+    })
+    expect(updatesOfKind(harness!, 'tool_call_update')[0]).toMatchObject({
+      sessionUpdate: 'tool_call_update',
+      toolCallId: 'call-1',
+      status: 'completed',
+      content: [{ type: 'content', content: { type: 'text', text: 'file body' } }],
+    })
+  })
+
+  it('maps each harness tool name to its ACP kind', async () => {
+    const agent = await openSession()
+    const cases = [
+      { name: 'bash', kind: 'execute' },
+      { name: 'edit', kind: 'edit' },
+      { name: 'grep', kind: 'search' },
+      { name: 'web_fetch', kind: 'fetch' },
+      { name: 'todo_write', kind: 'other' },
+      { name: 'a_tool_nobody_registered', kind: 'other' },
+    ]
+    cases.forEach((entry, index) => {
+      agent.session.append('tool/call', {
+        turn: 1, step: 0, callId: CallId(`call-${index}`), name: entry.name, arguments: '{}',
+      })
+    })
+    await waitForEvents(harness!, cases.length)
+
+    expect(updatesOfKind(harness!, 'tool_call').map(update => ({
+      name: update.title, kind: update.kind,
+    }))).toEqual(cases)
+  })
+
+  it('reports a failed tool call as failed and carries the raw result', async () => {
+    const agent = await openSession()
+    const callId = CallId('call-boom')
+    agent.session.append('tool/call', {
+      turn: 1, step: 0, callId, name: 'bash', arguments: JSON.stringify({ command: 'false' }),
+    })
+    agent.session.append('tool/result', {
+      turn: 1,
+      step: 0,
+      message: createToolResultMessage({
+        callId, content: [{ type: 'text', text: 'exit status 1' }], isError: true,
+      }),
+      error: { name: 'ToolError', code: 'EXIT_STATUS' },
+    }, SURFACE)
+    await waitForEvents(harness!, 2)
+
+    const settled = updatesOfKind(harness!, 'tool_call_update')[0]
+    expect(settled).toMatchObject({ toolCallId: 'call-boom', status: 'failed' })
+    expect(settled?.rawOutput).toMatchObject({ content: [{ type: 'tool-result', toolCallId: 'call-boom' }] })
+  })
+
+  it('keeps a tool call whose arguments are not JSON', async () => {
+    const agent = await openSession()
+    agent.session.append('tool/call', {
+      turn: 1, step: 0, callId: CallId('call-partial'), name: 'bash', arguments: '{"command": "ec',
+    })
+    await waitForEvents(harness!, 1)
+
+    expect(updatesOfKind(harness!, 'tool_call')[0]).toMatchObject({
+      toolCallId: 'call-partial', kind: 'execute', rawInput: '{"command": "ec', locations: [],
+    })
+  })
+
+  it('streams deltas and does not repeat them when the message commits', async () => {
+    const agent = await openSession()
+    agent.session.append('assistant/chunk', {
+      turn: 1, step: 0, chunk: { type: 'reasoning-delta', index: 0, text: 'thinking' },
+    })
+    agent.session.append('assistant/chunk', {
+      turn: 1, step: 0, chunk: { type: 'text-delta', index: 0, text: 'hel' },
+    })
+    agent.session.append('assistant/chunk', {
+      turn: 1, step: 0, chunk: { type: 'text-delta', index: 0, text: 'lo' },
+    })
+    agent.session.append('assistant/message', {
+      turn: 1,
+      step: 0,
+      message: createAssistantMessage({
+        source: PROVENANCE,
+        content: [{ type: 'reasoning', text: 'thinking' }, { type: 'text', text: 'hello' }],
+      }),
+    }, SURFACE)
+    await waitForEvents(harness!, 3)
+
+    expect(updatesOfKind(harness!, 'agent_message_chunk').map(update => update.content))
+      .toEqual([{ type: 'text', text: 'hel' }, { type: 'text', text: 'lo' }])
+    expect(updatesOfKind(harness!, 'agent_thought_chunk').map(update => update.content))
+      .toEqual([{ type: 'text', text: 'thinking' }])
+  })
+
+  it('publishes a committed message that never streamed', async () => {
+    const agent = await openSession()
+    agent.session.append('assistant/message', {
+      turn: 1,
+      step: 0,
+      message: createAssistantMessage({ source: PROVENANCE, content: [{ type: 'text', text: 'whole answer' }] }),
+    }, SURFACE)
+    await waitForEvents(harness!, 1)
+
+    expect(updatesOfKind(harness!, 'agent_message_chunk').map(update => update.content))
+      .toEqual([{ type: 'text', text: 'whole answer' }])
+  })
+
+  it('re-publishes committed text for a later step of the same turn', async () => {
+    const agent = await openSession()
+    agent.session.append('assistant/chunk', {
+      turn: 1, step: 0, chunk: { type: 'text-delta', index: 0, text: 'streamed' },
+    })
+    agent.session.append('step/end', { turn: 1, step: 0 })
+    agent.session.append('step/start', { turn: 1, step: 1 })
+    agent.session.append('assistant/message', {
+      turn: 1,
+      step: 1,
+      message: createAssistantMessage({ source: PROVENANCE, content: [{ type: 'text', text: 'second step' }] }),
+    }, SURFACE)
+    await waitForEvents(harness!, 2)
+
+    expect(updatesOfKind(harness!, 'agent_message_chunk').map(update => update.content))
+      .toEqual([{ type: 'text', text: 'streamed' }, { type: 'text', text: 'second step' }])
+  })
+
+  it('withholds reasoning when the deployment turns it off', async () => {
+    const agent = await openSession({ reasoning: false })
+    agent.session.append('assistant/chunk', {
+      turn: 1, step: 0, chunk: { type: 'reasoning-delta', index: 0, text: 'private' },
+    })
+    agent.session.append('assistant/chunk', {
+      turn: 1, step: 0, chunk: { type: 'text-delta', index: 0, text: 'public' },
+    })
+    agent.session.append('assistant/message', {
+      turn: 1,
+      step: 0,
+      message: createAssistantMessage({
+        source: PROVENANCE,
+        content: [{ type: 'reasoning', text: 'private' }, { type: 'text', text: 'public' }],
+      }),
+    }, SURFACE)
+    await waitForEvents(harness!, 1)
+
+    expect(updatesOfKind(harness!, 'agent_thought_chunk')).toHaveLength(0)
+    expect(updatesOfKind(harness!, 'agent_message_chunk').map(update => update.content))
+      .toEqual([{ type: 'text', text: 'public' }])
+  })
+
+  it('republishes each todo write as a plan', async () => {
+    const agent = await openSession()
+    agent.session.append('todo/write', {
+      todos: [
+        { content: 'read the failing test', status: 'completed' },
+        { content: 'fix the parser', status: 'in_progress' },
+        { content: 'run the suite', status: 'pending' },
+      ],
+    })
+    await waitForEvents(harness!, 1)
+
+    expect(updatesOfKind(harness!, 'plan')[0]).toEqual({
+      sessionUpdate: 'plan',
+      entries: [
+        { content: 'read the failing test', priority: 'medium', status: 'completed' },
+        { content: 'fix the parser', priority: 'medium', status: 'in_progress' },
+        { content: 'run the suite', priority: 'medium', status: 'pending' },
+      ],
+    })
+  })
+
+  it('keeps harness bookkeeping events off the wire', async () => {
+    const agent = await openSession()
+    agent.session.append('step/end', { turn: 1, step: 0 })
+    agent.session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    agent.session.append('turn/start', { turn: 2 })
+    agent.session.append('step/start', { turn: 2, step: 0 })
+    agent.session.append('assistant/chunk', {
+      turn: 2, step: 0, chunk: { type: 'text-delta', index: 0, text: 'next turn' },
+    })
+    await waitForEvents(harness!, 1)
+
+    expect(harness!.updates.map(update => update.sessionUpdate)).toEqual(['agent_message_chunk'])
+  })
+})
diff --git a/packages/dsh-acp/tsconfig.build.json b/packages/dsh-acp/tsconfig.build.json
new file mode 100644
index 0000000000..5736159eab
--- /dev/null
+++ b/packages/dsh-acp/tsconfig.build.json
@@ -0,0 +1,21 @@
+// Emit configuration for `lib/`. The base config type-checks src, tests, and
+// scripts with `noEmit`; this one compiles src alone, because tests and build
+// scripts are not part of what ships.
+//
+// `rewriteRelativeImportExtensions` (inherited) is what makes the `./bridge.ts`
+// import style in src/ legal here: TypeScript rewrites those specifiers to
+// `./bridge.js` on the way out, so the emitted tree is plain Node ESM with no
+// loader hook.
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "rootDir": "src",
+    "outDir": "lib",
+    "declaration": true,
+    "declarationDir": "lib/types",
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src"]
+}
diff --git a/packages/dsh-acp/tsconfig.json b/packages/dsh-acp/tsconfig.json
new file mode 100644
index 0000000000..37d4009701
--- /dev/null
+++ b/packages/dsh-acp/tsconfig.json
@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023", "DOM"],
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "allowImportingTsExtensions": true,
+    "rewriteRelativeImportExtensions": true,
+    "erasableSyntaxOnly": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "strict": true,
+    "exactOptionalPropertyTypes": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src", "tests", "scripts"]
+}
diff --git a/patches/mdast-util-gfm-autolink-literal@2.0.1.patch b/patches/mdast-util-gfm-autolink-literal@2.0.1.patch
new file mode 100644
index 0000000000..df6196ae29
--- /dev/null
+++ b/patches/mdast-util-gfm-autolink-literal@2.0.1.patch
@@ -0,0 +1,49 @@
+diff --git a/lib/index.js b/lib/index.js
+index c5ca771c24dd914e342f791716a822431ee32b3a..1b159d4cff7588581de342796858811c340a48f4 100644
+--- a/lib/index.js
++++ b/lib/index.js
+@@ -132,7 +132,7 @@ function transformGfmAutolinkLiterals(tree) {
+     tree,
+     [
+       [/(https?:\/\/|www(?=\.))([-.\w]+)([^ \t\r\n]*)/gi, findUrl],
+-      [/(?<=^|\s|\p{P}|\p{S})([-.\w+]+)@([-\w]+(?:\.[-\w]+)+)/gu, findEmail]
++      [/(^|[\s\p{P}\p{S}])([-.\w+]+)@([-\w]+(?:\.[-\w]+)+)/gu, findEmail]
+     ],
+     {ignore: ['link', 'linkReference']}
+   )
+@@ -189,27 +189,29 @@ function findUrl(_, protocol, domain, path, match) {
+ /**
+  * @type {ReplaceFunction}
+  * @param {string} _
++ * @param {string} prefix
+  * @param {string} atext
+  * @param {string} label
+- * @param {RegExpMatchObject} match
+- * @returns {Link | false}
++ * @returns {Array<PhrasingContent> | Link | false}
+  */
+-function findEmail(_, atext, label, match) {
++function findEmail(_, prefix, atext, label) {
+   if (
+-    // Not an expected previous character.
+-    !previous(match, true) ||
++    // An email should not follow a slash.
++    prefix === '/' ||
+     // Label ends in not allowed character.
+     /[-\d_]$/.test(label)
+   ) {
+     return false
+   }
+
+-  return {
++  const result = {
+     type: 'link',
+     title: null,
+     url: 'mailto:' + atext + '@' + label,
+     children: [{type: 'text', value: atext + '@' + label}]
+   }
++
++  return prefix ? [{type: 'text', value: prefix}, result] : result
+ }
+
+ /**
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 68c561f17b..c484022174 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -4,6 +4,11 @@ settings:
   autoInstallPeers: true
   excludeLinksFromLockfile: false
 
+patchedDependencies:
+  mdast-util-gfm-autolink-literal@2.0.1:
+    hash: 23ece47d024ddb26beb830db75c7075ea8820bc730565a8e59895957253e5707
+    path: patches/mdast-util-gfm-autolink-literal@2.0.1.patch
+
 importers:
 
   .:
@@ -92,6 +97,15 @@ importers:
         specifier: ^7.0.4
         version: 7.3.1(@types/node@22.19.7)(jiti@2.6.1)(sass@1.97.3)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
 
+  sdk/typescript:
+    devDependencies:
+      '@types/node':
+        specifier: 22.19.7
+        version: 22.19.7
+      typescript:
+        specifier: ~5.8.3
+        version: 5.8.3
+
   src/miniapp-market-web:
     dependencies:
       '@phosphor-icons/react':
@@ -335,8 +349,8 @@ importers:
         specifier: ^15.6.6
         version: 15.6.6(react@18.3.1)
       react-virtuoso:
-        specifier: ^4.14.1
-        version: 4.18.1(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+        specifier: ^4.18.11
+        version: 4.18.11(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
       rehype-katex:
         specifier: ^7.0.1
         version: 7.0.1
@@ -4672,8 +4686,8 @@ packages:
     peerDependencies:
       react: '>= 0.14.0'
 
-  react-virtuoso@4.18.1:
-    resolution: {integrity: sha512-KF474cDwaSb9+SJ380xruBB4P+yGWcVkcu26HtMqYNMTYlYbrNy8vqMkE+GpAApPPufJqgOLMoWMFG/3pJMXUA==}
+  react-virtuoso@4.18.11:
+    resolution: {integrity: sha512-Qeeq9vqa5seCxACvzbQTUeq3s2/Bu+VlwOMF0jfy3E/ZKHLiXWwJpXBhv2rckqYkvm1XRVFLCBMCmqCU8JNEJg==}
     peerDependencies:
       react: '>=16 || >=17 || >= 18 || >= 19'
       react-dom: '>=16 || >=17 || >= 18 || >=19'
@@ -9663,7 +9677,7 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  mdast-util-gfm-autolink-literal@2.0.1:
+  mdast-util-gfm-autolink-literal@2.0.1(patch_hash=23ece47d024ddb26beb830db75c7075ea8820bc730565a8e59895957253e5707):
     dependencies:
       '@types/mdast': 4.0.4
       ccount: 2.0.1
@@ -9711,7 +9725,7 @@ snapshots:
   mdast-util-gfm@3.1.0:
     dependencies:
       mdast-util-from-markdown: 2.0.2
-      mdast-util-gfm-autolink-literal: 2.0.1
+      mdast-util-gfm-autolink-literal: 2.0.1(patch_hash=23ece47d024ddb26beb830db75c7075ea8820bc730565a8e59895957253e5707)
       mdast-util-gfm-footnote: 2.1.0
       mdast-util-gfm-strikethrough: 2.0.0
       mdast-util-gfm-table: 2.0.0
@@ -10650,7 +10664,7 @@ snapshots:
       react: 18.3.1
       refractor: 3.6.0
 
-  react-virtuoso@4.18.1(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
+  react-virtuoso@4.18.11(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
     dependencies:
       react: 18.3.1
       react-dom: 18.3.1(react@18.3.1)
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index d49e3153d8..4629dab91f 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -1,7 +1,11 @@
 packages:
+  - "sdk/typescript"
   - "src/web-ui"
   - "src/mobile-web"
   - "src/miniapp-market-web"
   - "src/skin-market-web"
   - "BitFun-Installer"
   - "tests/e2e"
+
+patchedDependencies:
+  mdast-util-gfm-autolink-literal@2.0.1: patches/mdast-util-gfm-autolink-literal@2.0.1.patch
diff --git a/scripts/audit-web-motion.mjs b/scripts/audit-web-motion.mjs
new file mode 100644
index 0000000000..1638e16b77
--- /dev/null
+++ b/scripts/audit-web-motion.mjs
@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+
+const repositoryRoot = path.resolve(import.meta.dirname, '..');
+const sourceRoot = path.join(repositoryRoot, 'src/web-ui/src');
+const sourceExtensions = new Set(['.css', '.scss', '.ts', '.tsx']);
+const styleExtensions = new Set(['.css', '.scss']);
+const excludedRoots = new Set([
+  path.join(sourceRoot, 'generated'),
+  path.join(sourceRoot, 'component-library/preview'),
+]);
+
+function isAuditedSourceFile(file) {
+  const name = path.basename(file);
+  return sourceExtensions.has(path.extname(name))
+    && !/\.(?:test|spec)\.(?:ts|tsx)$/.test(name);
+}
+
+async function collectFiles(directory) {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const nested = await Promise.all(entries.map(async entry => {
+    const absolutePath = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      return excludedRoots.has(absolutePath) ? [] : collectFiles(absolutePath);
+    }
+    return isAuditedSourceFile(absolutePath) ? [absolutePath] : [];
+  }));
+  return nested.flat();
+}
+
+function lineNumberAt(source, index) {
+  return source.slice(0, index).split('\n').length;
+}
+
+function relativePath(file) {
+  return path.relative(repositoryRoot, file);
+}
+
+function findMatches(source, expression) {
+  return [...source.matchAll(expression)].map(match => ({
+    index: match.index ?? 0,
+    value: match[0],
+    groups: match.slice(1),
+  }));
+}
+
+function withoutComments(source) {
+  return source
+    .replace(/\/\*[\s\S]*?\*\//g, comment => comment.replace(/[^\n]/g, ' '))
+    .replace(/(^|\s)\/\/[^\n]*/g, comment => comment.replace(/[^\n]/g, ' '));
+}
+
+function printLocations(title, locations, limit = 80) {
+  console.log(`\n${title}: ${locations.length}`);
+  locations.slice(0, limit).forEach(location => {
+    console.log(`  ${location.file}:${location.line}${location.detail ? ` (${location.detail})` : ''}`);
+  });
+  if (locations.length > limit) {
+    console.log(`  ... ${locations.length - limit} more`);
+  }
+}
+
+const files = await collectFiles(sourceRoot);
+const transitionAll = [];
+const scaleZero = [];
+const smoothScroll = [];
+const unguardedInfinite = [];
+const keyframes = new Map();
+let interactiveHandlers = 0;
+let motionOptIns = 0;
+
+for (const file of files) {
+  const source = await readFile(file, 'utf8');
+  const searchableSource = withoutComments(source);
+  const fileName = relativePath(file);
+  const extension = path.extname(file);
+
+  if (extension === '.tsx') {
+    interactiveHandlers += findMatches(searchableSource, /\bon(?:Click|DoubleClick|ContextMenu|PointerDown|MouseDown|KeyDown)\s*=/g).length;
+    motionOptIns += findMatches(searchableSource, /\bdata-motion\s*=/g).length;
+  }
+
+  for (const match of findMatches(searchableSource, /\btransition\s*:\s*all\b/g)) {
+    transitionAll.push({ file: fileName, line: lineNumberAt(source, match.index) });
+  }
+  for (const match of findMatches(searchableSource, /\bscale\(\s*0(?:\.0+)?\s*\)/g)) {
+    scaleZero.push({ file: fileName, line: lineNumberAt(source, match.index) });
+  }
+  for (const match of findMatches(searchableSource, /\bbehavior\s*:\s*['"]smooth['"]/g)) {
+    smoothScroll.push({ file: fileName, line: lineNumberAt(source, match.index) });
+  }
+
+  if (!styleExtensions.has(extension)) continue;
+
+  for (const match of findMatches(searchableSource, /@(?:-webkit-)?keyframes\s+([\w-]+)/g)) {
+    const name = match.groups[0];
+    const definitions = keyframes.get(name) ?? [];
+    definitions.push({ file: fileName, line: lineNumberAt(source, match.index) });
+    keyframes.set(name, definitions);
+  }
+
+  const hasInfiniteAnimation = /\banimation(?:-[\w-]+)?\s*:[^;{}]*\binfinite\b/.test(searchableSource);
+  const hasReducedMotionRule = /@media\s*\([^)]*prefers-reduced-motion\s*:\s*reduce[^)]*\)/.test(searchableSource);
+  if (hasInfiniteAnimation && !hasReducedMotionRule) {
+    unguardedInfinite.push({ file: fileName, line: 1 });
+  }
+}
+
+const duplicateKeyframes = [...keyframes.entries()]
+  .filter(([, definitions]) => definitions.length > 1)
+  .sort((left, right) => right[1].length - left[1].length);
+
+console.log('BitFun Web UI motion inventory');
+console.log(`Scanned ${files.length} source files under src/web-ui/src.`);
+console.log(`Interactive handler attributes: ${interactiveHandlers}`);
+console.log(`Explicit data-motion opt-ins: ${motionOptIns}`);
+printLocations('transition: all', transitionAll);
+printLocations('scale(0)', scaleZero);
+printLocations('JavaScript smooth scrolling (verify keyboard and reduced-motion paths)', smoothScroll);
+printLocations('Files with infinite animation and no local reduced-motion rule', unguardedInfinite);
+
+console.log(`\nDuplicate global keyframe names: ${duplicateKeyframes.length}`);
+duplicateKeyframes.slice(0, 40).forEach(([name, definitions]) => {
+  console.log(`  ${name}: ${definitions.length}`);
+  definitions.forEach(definition => console.log(`    ${definition.file}:${definition.line}`));
+});
+if (duplicateKeyframes.length > 40) {
+  console.log(`  ... ${duplicateKeyframes.length - 40} more`);
+}
+
+console.log('\nThis command is an inventory, not a pass/fail gate. Review intent before changing layout transitions or virtualized content.');
diff --git a/scripts/check-build-prereqs.test.mjs b/scripts/check-build-prereqs.test.mjs
index ef12f4a175..72cfded6d2 100644
--- a/scripts/check-build-prereqs.test.mjs
+++ b/scripts/check-build-prereqs.test.mjs
@@ -12,7 +12,11 @@ const repoRoot = path.resolve(
 );
 const scriptPath = path.join(repoRoot, 'scripts/check-build-prereqs.mjs');
 
-function createTestRoot({ nodeModules = false, mobileWebDist = false, sherpaOnnx = null } = {}) {
+function createTestRoot({
+  nodeModules = false,
+  mobileWebDist = false,
+  sherpaOnnx = null,
+} = {}) {
   const root = mkdtempSync(path.join(tmpdir(), 'bitfun-build-prereqs-'));
 
   if (nodeModules) {
@@ -129,6 +133,21 @@ test('fails when mobile-web dist is missing', (t) => {
   assert.match(result.stderr, /Fix: pnpm run prepare:mobile-web/);
 });
 
+test('does not require the DeepSeek profile for cargo check', (t) => {
+  const root = createTestRoot({
+    nodeModules: true,
+    mobileWebDist: true,
+    sherpaOnnx: ['sherpa-onnx-v1.13.4-osx-arm64-static-lib'],
+  });
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+
+  const result = runCheck(root, { sherpaEnv: '' });
+
+  assert.equal(result.status, 0);
+  assert.doesNotMatch(result.stderr, /dsh bridge profile/);
+  assert.doesNotMatch(result.stderr, /prepare:dsh-profile/);
+});
+
 test('warns when sherpa-onnx prebuilt dir does not exist (first build)', (t) => {
   const root = createTestRoot({ nodeModules: true, mobileWebDist: true });
   t.after(() => rmSync(root, { recursive: true, force: true }));
@@ -165,6 +184,7 @@ test('--fix runs fix commands, re-verifies, and exits 0 when errors resolved', (
   assert.match(result.stdout, /Attempting fixes/);
   assert.match(result.stdout, /\$ pnpm install/);
   assert.match(result.stdout, /\$ pnpm run prepare:mobile-web/);
+  assert.doesNotMatch(result.stdout, /prepare:dsh-profile/);
   assert.match(result.stdout, /Re-checking prerequisites/);
   assert.match(result.stdout, /All errors resolved/);
 });
diff --git a/scripts/check-core-boundaries.test.mjs b/scripts/check-core-boundaries.test.mjs
index 8eb356677b..9f5b3bd30e 100644
--- a/scripts/check-core-boundaries.test.mjs
+++ b/scripts/check-core-boundaries.test.mjs
@@ -20,16 +20,30 @@ import {
 } from './core-boundaries/cargo-dependency-boundaries.mjs';
 import {
   checkCliIntegrationTestTopology,
+  checkExternalSourceIntegrationTestTopologies,
   checkServicesCoreIntegrationTestTopology,
   checkServicesIntegrationsIntegrationTestTopology,
+  claudeCodeAdapterIntegrationTestTargets,
   cliIntegrationTestTargets,
+  codexAdapterIntegrationTestTargets,
+  externalSourcesIntegrationTestTargets,
+  opencodeAdapterIntegrationTestTargets,
   validateExplicitIntegrationTestTopology,
 } from './core-boundaries/explicit-test-topology.mjs';
 import { crateLayoutRules } from './core-boundaries/rules/crate-layout.mjs';
 import {
+  capabilityContractDependencyRules,
   coreClosedFeatureProfileRules,
   coreProductFullFeatureAssemblyRule,
+  guardedEmptyInternalDefaultManifestPaths,
+  optionalDependencyFeatureOwnerRules,
 } from './core-boundaries/rules/feature-rules.mjs';
+import {
+  agentRuntimeRootPublicModules,
+  forbiddenContentRules,
+  publicApiAllowlistRules,
+  requiredContentRules,
+} from './core-boundaries/rules/source-rules.mjs';
 
 const ENTRYPOINT = new URL('./check-core-boundaries.mjs', import.meta.url);
 const MODULES = [
@@ -50,6 +64,345 @@ const MODULES = [
 
 const TEST_ROOT = join('C:', 'repo');
 
+test('App Server TypeScript capability is owned by the protocol crate', () => {
+  const appServerTs = coreClosedFeatureProfileRules.find(
+    (rule) => rule.manifestPath === 'src/crates/interfaces/app-server/Cargo.toml'
+      && rule.featureName === 'ts',
+  );
+  assert.deepEqual(appServerTs?.requiredFeatureRefs, [
+    'bitfun-app-server-protocol/ts',
+  ]);
+  assert.equal(appServerTs?.exact, true);
+
+  const protocolTs = coreClosedFeatureProfileRules.find(
+    (rule) => rule.manifestPath === 'src/crates/interfaces/app-server-protocol/Cargo.toml'
+      && rule.featureName === 'ts',
+  );
+  assert.deepEqual(protocolTs?.requiredFeatureRefs, [
+    'bitfun-core-types/ts',
+    'bitfun-product-domains/ts',
+    'bitfun-runtime-ports/ts',
+    'dep:ts-rs',
+  ]);
+  assert.equal(protocolTs?.exact, true);
+});
+
+test('Agent Runtime leaf capabilities have one managed feature and source contract', async () => {
+  const rule = capabilityContractDependencyRules.find(
+    (candidate) => candidate.packageName === 'bitfun-agent-runtime',
+  );
+  assert.ok(rule, 'bitfun-agent-runtime must be a managed capability target');
+  assert.deepEqual(Object.keys(rule.featureProfiles).sort(), [
+    'agent-runtime',
+    'deep-research',
+    'default',
+    'native-hook-runtime',
+    'native-hook-settings',
+  ]);
+  assert.equal(rule.consumers.size, 10);
+  assert.ok(
+    guardedEmptyInternalDefaultManifestPaths.includes(
+      'src/crates/execution/agent-runtime/Cargo.toml',
+    ),
+  );
+  assert.ok(requiredContentRules.some(
+    (sourceRule) => sourceRule.path === 'src/crates/execution/agent-runtime/src/lib.rs'
+      && sourceRule.reason.includes('leaf capability modules'),
+  ));
+  const publicApiRule = publicApiAllowlistRules.find(
+    (sourceRule) => sourceRule.path === 'src/crates/execution/agent-runtime/src/lib.rs',
+  );
+  assert.ok(publicApiRule, 'bitfun-agent-runtime root must have a closed public module allowlist');
+  assert.deepEqual(
+    new Set(publicApiRule.allowedSymbols),
+    new Set(agentRuntimeRootPublicModules),
+  );
+  const flatRootRule = forbiddenContentRules.find(
+    (sourceRule) => sourceRule.path === 'src/crates/execution/agent-runtime/src/lib.rs'
+      && sourceRule.reason.includes('flat feature-owned module wrapper'),
+  );
+  assert.ok(flatRootRule, 'bitfun-agent-runtime root must reject non-wrapper source lines');
+  const rootSource = await readFile(
+    new URL('../src/crates/execution/agent-runtime/src/lib.rs', import.meta.url),
+    'utf8',
+  );
+  assert.equal(flatRootRule.patterns[0].regex.test(rootSource), false);
+  for (const mutation of [
+    '#[doc(hidden)] pub mod accidental_feature_free_api;',
+    'pub union AccidentalFeatureFreeApi { value: u64 }',
+    'const DOC: &str = "{";\npub mod accidental_feature_free_api;',
+  ]) {
+    assert.equal(
+      flatRootRule.patterns[0].regex.test(`${rootSource}\n${mutation}`),
+      true,
+      `Agent Runtime root must reject mutation: ${mutation}`,
+    );
+  }
+});
+
+test('Core and ACP defaults preserve their explicit assembly contracts', async () => {
+  const [coreManifest, acpManifest] = await Promise.all([
+    readFile(new URL('../src/crates/assembly/core/Cargo.toml', import.meta.url), 'utf8'),
+    readFile(new URL('../src/crates/interfaces/acp/Cargo.toml', import.meta.url), 'utf8'),
+  ]);
+
+  assert.deepEqual(parseManifestFeatures(coreManifest).default, []);
+  assert.deepEqual(
+    new Set(parseManifestFeatures(acpManifest).default),
+    new Set(['client', 'server']),
+  );
+});
+
+test('consumers do not repeat guarded empty internal defaults', async () => {
+  const cargoBoundaries = await import(
+    './core-boundaries/cargo-dependency-boundaries.mjs'
+  );
+  assert.equal(
+    typeof cargoBoundaries.findRedundantInternalDefaultFeatureDisables,
+    'function',
+  );
+
+  const emptyOwner = {
+    ...packageAt('empty-owner', 'src/crates/contracts/empty-owner/Cargo.toml'),
+    features: { default: [] },
+  };
+  const compatibilityOwner = {
+    ...packageAt('compatibility-owner', 'src/crates/interfaces/compatibility-owner/Cargo.toml'),
+    features: { default: ['client', 'server'] },
+  };
+  const unguardedEmptyOwner = {
+    ...packageAt('unguarded-empty-owner', 'src/crates/contracts/unguarded-empty-owner/Cargo.toml'),
+    features: { default: [] },
+  };
+  const consumer = packageAt('consumer', 'src/apps/consumer/Cargo.toml', [
+    pathDependency('src/crates/contracts/empty-owner', {
+      name: 'empty-owner',
+      usesDefaultFeatures: false,
+    }),
+    pathDependency('src/crates/interfaces/compatibility-owner', {
+      name: 'compatibility-owner',
+      usesDefaultFeatures: false,
+    }),
+    pathDependency('src/crates/contracts/unguarded-empty-owner', {
+      name: 'unguarded-empty-owner',
+      usesDefaultFeatures: false,
+    }),
+  ]);
+
+  const violations = cargoBoundaries.findRedundantInternalDefaultFeatureDisables(
+    [emptyOwner, compatibilityOwner, unguardedEmptyOwner, consumer],
+    {
+      root: TEST_ROOT,
+      guardedManifests: ['src/crates/contracts/empty-owner/Cargo.toml'],
+    },
+  );
+  assert.equal(violations.length, 1);
+  assert.match(violations[0].message, /empty-owner.*redundant/);
+});
+
+test('guarded internal defaults stay explicitly empty', async () => {
+  const cargoBoundaries = await import(
+    './core-boundaries/cargo-dependency-boundaries.mjs'
+  );
+  const manifestPath = 'src/crates/contracts/empty-owner/Cargo.toml';
+  const owner = {
+    ...packageAt('empty-owner', manifestPath),
+    features: { default: [] },
+  };
+  assert.deepEqual(
+    cargoBoundaries.findGuardedInternalDefaultFeatureViolations(
+      [owner],
+      { root: TEST_ROOT, guardedManifests: [manifestPath] },
+    ),
+    [],
+  );
+
+  owner.features.default = ['expanded'];
+  const violations = cargoBoundaries.findGuardedInternalDefaultFeatureViolations(
+    [owner],
+    { root: TEST_ROOT, guardedManifests: [manifestPath] },
+  );
+  assert.equal(violations.length, 1);
+  assert.match(violations[0].message, /guarded default feature must stay explicitly empty/);
+});
+
+test('portable contract crates expose only capability-local feature slices', async () => {
+  const [runtimePortsManifest, agentToolsManifest] = await Promise.all([
+    readFile(new URL('../src/crates/contracts/runtime-ports/Cargo.toml', import.meta.url), 'utf8'),
+    readFile(new URL('../src/crates/execution/tool-contracts/Cargo.toml', import.meta.url), 'utf8'),
+  ]);
+
+  const runtimePortFeatures = parseManifestFeatures(runtimePortsManifest);
+  assert.deepEqual(runtimePortFeatures.default, []);
+  assert.deepEqual(
+    new Set(Object.keys(runtimePortFeatures)),
+    new Set([
+      'default',
+      'agent-api',
+      'git-port',
+      'permission',
+      'plugin-runtime',
+      'remote-exec-port',
+      'remote-workspace-ports',
+      'runtime-event-port',
+      'script-tool-runtime',
+      'terminal-port',
+      'tool-runtime-handles',
+      'ts',
+      'workspace-ports',
+    ]),
+  );
+  assert.deepEqual(runtimePortFeatures['agent-api'], ['dep:bitfun-core-types']);
+  assert.deepEqual(runtimePortFeatures['plugin-runtime'], []);
+  assert.deepEqual(runtimePortFeatures['script-tool-runtime'], []);
+  assert.deepEqual(new Set(runtimePortFeatures['workspace-ports']), new Set(['dep:anyhow', 'dep:tokio-util']));
+  assert.deepEqual(runtimePortFeatures['terminal-port'], ['dep:tokio']);
+  assert.deepEqual(runtimePortFeatures['remote-exec-port'], ['dep:tokio']);
+  assert.deepEqual(
+    new Set(runtimePortFeatures['tool-runtime-handles']),
+    new Set([
+      'workspace-ports',
+      'terminal-port',
+      'remote-exec-port',
+    ]),
+  );
+
+  const agentToolFeatures = parseManifestFeatures(agentToolsManifest);
+  assert.deepEqual(agentToolFeatures.default, []);
+  assert.deepEqual(agentToolFeatures['acp-bridge'], []);
+  assert.deepEqual(agentToolFeatures['computer-use-contract'], []);
+  assert.deepEqual(agentToolFeatures['element-token'], []);
+  assert.deepEqual(agentToolFeatures['mcp-bridge'], []);
+});
+
+test('runtime-port capability source gates protect modules and public exports', async () => {
+  const { requiredContentRules } = await import(
+    './core-boundaries/rules/source/required-rules.mjs'
+  );
+  const sourceRule = requiredContentRules.find(
+    (rule) => rule.path === 'src/crates/contracts/runtime-ports/src/lib.rs'
+      && rule.reason.includes('capability features'),
+  );
+  const patterns = sourceRule?.patterns.map(({ regex }) => regex.source).join('\n') ?? '';
+
+  for (const [feature, moduleName] of [
+    ['workspace-ports', 'workspace_ports'],
+    ['terminal-port', 'terminal_port'],
+    ['remote-exec-port', 'remote_exec_port'],
+    ['remote-workspace-ports', 'remote_workspace_ports'],
+    ['runtime-event-port', 'runtime_event_port'],
+    ['git-port', 'git_port'],
+    ['tool-runtime-handles', 'tool_runtime_handles'],
+  ]) {
+    assert.match(patterns, new RegExp(`${feature}.*mod ${moduleName}`));
+    assert.match(patterns, new RegExp(`${feature}.*pub use ${moduleName}`));
+  }
+});
+
+test('runtime-ports async dependencies stay behind their exact port owners', () => {
+  const ownerRule = optionalDependencyFeatureOwnerRules.find(
+    (rule) => rule.crateName === 'runtime-ports',
+  );
+  const ownersByDependency = new Map(
+    ownerRule.dependencies.map((dependency) => [
+      dependency.depName,
+      new Set(dependency.ownerFeatures),
+    ]),
+  );
+
+  assert.deepEqual(
+    ownersByDependency.get('anyhow'),
+    new Set(['workspace-ports']),
+  );
+  assert.deepEqual(
+    ownersByDependency.get('tokio-util'),
+    new Set(['workspace-ports']),
+  );
+  assert.deepEqual(
+    ownersByDependency.get('tokio'),
+    new Set(['remote-exec-port', 'terminal-port']),
+  );
+});
+
+test('Core feature-free dependencies stay attached to their exact runtime owners', () => {
+  const coreOwnerRule = optionalDependencyFeatureOwnerRules.find(
+    (rule) => rule.crateName === 'core',
+  );
+  const ownersByDependency = new Map(
+    coreOwnerRule.dependencies.map((dependency) => [
+      dependency.depName,
+      new Set(dependency.ownerFeatures),
+    ]),
+  );
+
+  assert.deepEqual(ownersByDependency.get('base64'), new Set(['agent-runtime', 'dispatch-store']));
+  assert.deepEqual(ownersByDependency.get('futures'), new Set(['agent-runtime']));
+  assert.deepEqual(ownersByDependency.get('regex'), new Set(['agent-runtime']));
+  assert.deepEqual(
+    ownersByDependency.get('bitfun-agent-tools'),
+    new Set(['agent-runtime', 'local-storage', 'mcp-runtime']),
+  );
+  assert.deepEqual(ownersByDependency.get('fluent-bundle'), new Set(['i18n-runtime']));
+  assert.deepEqual(ownersByDependency.get('unic-langid'), new Set(['i18n-runtime']));
+  assert.deepEqual(
+    ownersByDependency.get('tokio-util'),
+    new Set(['agent-runtime', 'debug-log']),
+  );
+});
+
+test('Services Core feature-free dependencies stay behind exact text and async IO owners', () => {
+  const ownerRule = optionalDependencyFeatureOwnerRules.find(
+    (rule) => rule.crateName === 'services-core',
+  );
+  const ownersByDependency = new Map(
+    ownerRule.dependencies.map((dependency) => [
+      dependency.depName,
+      new Set(dependency.ownerFeatures),
+    ]),
+  );
+
+  assert.deepEqual(
+    ownersByDependency.get('regex'),
+    new Set(['diagnostics', 'filesystem', 'local-storage', 'markdown', 'workspace-instructions']),
+  );
+  assert.deepEqual(ownersByDependency.get('similar'), new Set(['diff', 'local-storage']));
+  assert.deepEqual(
+    ownersByDependency.get('tokio'),
+    new Set([
+      'diff',
+      'filesystem',
+      'json-io',
+      'local-storage',
+      'lsp',
+      'permission',
+      'process-runtime',
+      'workspace-instructions',
+      'workspace-runtime',
+      'workspace-text-runtime',
+    ]),
+  );
+});
+
+test('Services Core text runtime features keep independent exact owner profiles', () => {
+  const profiles = new Map(
+    coreClosedFeatureProfileRules
+      .filter((rule) => rule.manifestPath === 'src/crates/services/services-core/Cargo.toml')
+      .map((rule) => [rule.featureName, rule.requiredFeatureRefs]),
+  );
+
+  assert.deepEqual(profiles.get('diagnostics'), ['dep:regex']);
+  assert.deepEqual(profiles.get('diff'), [
+    'dep:similar',
+    'dep:tokio',
+    'tokio/rt',
+    'tokio/time',
+  ]);
+  assert.deepEqual(profiles.get('workspace-text-runtime'), [
+    'dep:tokio',
+    'tokio/rt',
+  ]);
+});
+
 function parseManifestFeatures(manifest) {
   const section = manifest.match(/^\[features\]\s*$([\s\S]*?)(?=^\[|(?![\s\S]))/m)?.[1] ?? '';
   const features = {};
@@ -97,6 +450,61 @@ function pathDependency(repoCratePath, options = {}) {
   };
 }
 
+const RUNTIME_PORT_FEATURE_PROFILES = {
+  default: [],
+  'agent-api': ['dep:bitfun-core-types'],
+  'git-port': [],
+  permission: ['dep:bitfun-product-domains'],
+  'plugin-runtime': [],
+  'remote-exec-port': ['dep:tokio'],
+  'remote-workspace-ports': [],
+  'runtime-event-port': [],
+  'script-tool-runtime': [],
+  'terminal-port': ['dep:tokio'],
+  'tool-runtime-handles': ['workspace-ports', 'terminal-port', 'remote-exec-port'],
+  ts: [
+    'dep:ts-rs',
+    'agent-api',
+    'permission',
+    'bitfun-core-types/ts',
+    'bitfun-product-domains?/ts',
+  ],
+  'workspace-ports': ['dep:anyhow', 'dep:tokio-util'],
+};
+
+const AGENT_TOOL_FEATURE_PROFILES = {
+  default: [],
+  'acp-bridge': [],
+  'computer-use-contract': [],
+  'element-token': [],
+  'mcp-bridge': [],
+};
+
+function capabilityPackage(name, repoManifestPath, featureProfiles) {
+  return {
+    ...packageAt(name, repoManifestPath),
+    features: structuredClone(featureProfiles),
+  };
+}
+
+function agentToolsCapabilityPackage() {
+  return {
+    ...capabilityPackage(
+      'bitfun-agent-tools',
+      'src/crates/execution/tool-contracts/Cargo.toml',
+      AGENT_TOOL_FEATURE_PROFILES,
+    ),
+    dependencies: [pathDependency('src/crates/contracts/runtime-ports', {
+      name: 'bitfun-runtime-ports',
+      usesDefaultFeatures: false,
+    })],
+  };
+}
+
+function findTestCapabilityViolations(finder, packages, rules) {
+  return finder(packages, rules, { root: TEST_ROOT });
+}
+
 function integrationTarget(name, sourcePath, requiredFeatures = []) {
   return {
     kind: ['test'],
@@ -255,6 +663,216 @@ test('service integration tests keep their reviewed explicit target topology', (
   assert.deepEqual(checkServicesIntegrationsIntegrationTestTopology(repositoryRoot), []);
 });
 
+test('contract and AI adapter tests keep reviewed feature and failure-domain topology', async () => {
+  const repositoryRoot = fileURLToPath(new URL('..', import.meta.url));
+  const topology = await import('./core-boundaries/explicit-test-topology.mjs');
+
+  assert.deepEqual(topology.coreTypesIntegrationTestTargets, [
+    {
+      name: 'core_type_contracts',
+      path: 'tests/core_type_contracts.rs',
+      leaves: [
+        'tests/core_type_contracts/lsp_contracts.rs',
+        'tests/core_type_contracts/session_contracts.rs',
+        'tests/core_type_contracts/session_usage_contracts.rs',
+        'tests/core_type_contracts/surface_contracts.rs',
+      ],
+      forbidRequiredFeatures: true,
+    },
+  ]);
+  assert.deepEqual(topology.runtimePortsIntegrationTestTargets, [
+    {
+      name: 'plugin_runtime_contracts',
+      path: 'tests/runtime_port_contracts.rs',
+      leaves: [
+        'tests/runtime_port_contracts/plugin_runtime_contracts.rs',
+        'tests/runtime_port_contracts/plugin_runtime_diagnostics_contracts.rs',
+      ],
+      requiredFeatures: ['plugin-runtime'],
+    },
+    {
+      name: 'git_port_contracts',
+      path: 'tests/git_port_contracts.rs',
+      requiredFeatures: ['git-port'],
+    },
+    {
+      name: 'script_tool_port_contracts',
+      path: 'tests/script_tool_port_contracts.rs',
+      requiredFeatures: ['script-tool-runtime'],
+    },
+    {
+      name: 'session_store_contracts',
+      path: 'tests/session_store_contracts.rs',
+      requiredFeatures: ['workspace-ports'],
+    },
+  ]);
+  assert.deepEqual(topology.productDomainsIntegrationTestTargets, [
+    {
+      name: 'product_domain_contracts',
+      path: 'tests/product_domain_contracts.rs',
+      leaves: [
+        'tests/product_domain_contracts/canvas_contracts.rs',
+        'tests/product_domain_contracts/tool_permission_contracts.rs',
+      ],
+      forbidRequiredFeatures: true,
+    },
+    {
+      name: 'external_source_contracts',
+      path: 'tests/external_source_contracts.rs',
+      leaves: [
+        'tests/external_source_contracts/external_hook_catalog_contracts.rs',
+        'tests/external_source_contracts/external_hook_contribution_contracts.rs',
+        'tests/external_source_contracts/external_source_contracts.rs',
+        'tests/external_source_contracts/workspace_reference_contracts.rs',
+      ],
+      requiredFeatures: ['external-sources'],
+    },
+    {
+      name: 'function_agent_contracts',
+      path: 'tests/function_agent_contracts.rs',
+      requiredFeatures: ['function-agents'],
+    },
+    {
+      name: 'miniapp_contracts',
+      path: 'tests/miniapp_contracts.rs',
+      requiredFeatures: ['miniapp'],
+    },
+    {
+      name: 'plugin_source_contracts',
+      path: 'tests/plugin_source_contracts.rs',
+      requiredFeatures: ['plugin-source'],
+    },
+  ]);
+  assert.deepEqual(topology.aiAdaptersIntegrationTestTargets, [
+    {
+      name: 'ai_protocol_contracts',
+      path: 'tests/ai_protocol_contracts.rs',
+      leaves: [
+        'tests/ai_protocol_contracts/model_selector.rs',
+        'tests/ai_protocol_contracts/openai_empty_content_parts.rs',
+      ],
+      forbidRequiredFeatures: true,
+    },
+    {
+      name: 'ai_stream_contracts',
+      path: 'tests/ai_stream_contracts.rs',
+      leaves: [
+        'tests/ai_stream_contracts/common.rs',
+        'tests/ai_stream_contracts/stream_processor_anthropic.rs',
+        'tests/ai_stream_contracts/stream_processor_openai.rs',
+        'tests/ai_stream_contracts/stream_processor_tool_arguments.rs',
+        'tests/ai_stream_contracts/stream_replay_regressions.rs',
+        'tests/ai_stream_contracts/stream_test_harness.rs',
+      ],
+      forbidRequiredFeatures: true,
+    },
+  ]);
+  assert.deepEqual(topology.productCapabilitiesIntegrationTestTargets, [
+    {
+      name: 'product_capability_contracts',
+      path: 'tests/product_capability_contracts.rs',
+      leaves: [
+        'tests/product_capability_contracts/plugin_product_shape.rs',
+        'tests/product_capability_contracts/product_capabilities.rs',
+        'tests/product_capability_contracts/product_sdk_assembly.rs',
+      ],
+      forbidRequiredFeatures: true,
+    },
+  ]);
+  assert.deepEqual(topology.checkBuildGraphContractIntegrationTestTopologies(repositoryRoot), []);
+
+  const widenedOwnerErrors = validateExplicitIntegrationTestTopology({
+    manifestText: [
+      '[package]',
+      'autotests = false',
+      '[[test]]',
+      'name = "external_source_contracts"',
+      'path = "tests/external_source_contracts.rs"',
+      'required-features = ["product-full"]',
+    ].join('\n'),
+    expectedTargets: [{
+      name: 'external_source_contracts',
+      path: 'tests/external_source_contracts.rs',
+      requiredFeatures: ['external-sources'],
+    }],
+    topLevelRustFiles: ['tests/external_source_contracts.rs'],
+    rootSources: new Map([[
+      'tests/external_source_contracts.rs',
+      '#![cfg(feature = "product-full")]\n',
+    ]]),
+    leafRustFiles: [],
+    leafSources: new Map(),
+  });
+  assert.match(widenedOwnerErrors.join('\n'), /required-features.*external-sources/);
+});
+
+test('external source integration tests keep reviewed owner and process boundaries', () => {
+  const repositoryRoot = fileURLToPath(new URL('..', import.meta.url));
+
+  assert.deepEqual(opencodeAdapterIntegrationTestTargets, [
+    { name: 'opencode_mcp_adapter', path: 'tests/opencode_mcp_adapter.rs' },
+    { name: 'opencode_source_adapter', path: 'tests/opencode_source_adapter.rs' },
+    {
+      name: 'opencode_static_source_contracts',
+      path: 'tests/opencode_static_source_contracts.rs',
+      leaves: [
+        'tests/opencode_static_source_contracts/hook_source.rs',
+        'tests/opencode_static_source_contracts/opencode_command_adapter.rs',
+        'tests/opencode_static_source_contracts/opencode_skill_roots.rs',
+        'tests/opencode_static_source_contracts/opencode_subagent_adapter.rs',
+        'tests/opencode_static_source_contracts/opencode_workspace_references.rs',
+      ],
+      forbidRequiredFeatures: true,
+    },
+    { name: 'tool_source_contracts', path: 'tests/tool_source_contracts.rs' },
+  ]);
+  assert.deepEqual(claudeCodeAdapterIntegrationTestTargets, [
+    {
+      name: 'claude_code_source_contracts',
+      path: 'tests/claude_code_source_contracts.rs',
+      leaves: [
+        'tests/claude_code_source_contracts/command_source.rs',
+        'tests/claude_code_source_contracts/hook_source.rs',
+        'tests/claude_code_source_contracts/mcp_source.rs',
+        'tests/claude_code_source_contracts/subagent_source.rs',
+      ],
+      forbidRequiredFeatures: true,
+    },
+  ]);
+  assert.deepEqual(codexAdapterIntegrationTestTargets, [
+    {
+      name: 'codex_source_contracts',
+      path: 'tests/codex_source_contracts.rs',
+      leaves: [
+        'tests/codex_source_contracts/hook_source.rs',
+        'tests/codex_source_contracts/mcp_source.rs',
+        'tests/codex_source_contracts/subagent_source.rs',
+      ],
+      forbidRequiredFeatures: true,
+    },
+  ]);
+  assert.deepEqual(externalSourcesIntegrationTestTargets, [
+    {
+      name: 'external_source_coordination_contracts',
+      path: 'tests/external_source_coordination_contracts.rs',
+      leaves: [
+        'tests/external_source_coordination_contracts/control_plane.rs',
+        'tests/external_source_coordination_contracts/coordinator_contracts.rs',
+        'tests/external_source_coordination_contracts/hook_coordinator.rs',
+        'tests/external_source_coordination_contracts/mcp_coordinator.rs',
+        'tests/external_source_coordination_contracts/subagent_coordinator.rs',
+        'tests/external_source_coordination_contracts/tool_coordinator_contracts.rs',
+        'tests/external_source_coordination_contracts/workspace_reference.rs',
+      ],
+      forbidRequiredFeatures: true,
+    },
+  ]);
+  assert.deepEqual(
+    checkExternalSourceIntegrationTestTopologies(repositoryRoot),
+    [],
+  );
+});
+
 test('runtime-services test support is absent from ordinary library builds', async () => {
   const [manifest, library] = await Promise.all([
     readFile(
@@ -368,7 +986,7 @@ test('multiple crate feature gates combine as required feature AND conditions',
   assert.match(violations[0].message, /second/);
 });
 
-test('product entrypoints must disable bitfun-core default features', () => {
+test('product entrypoints may inherit the guarded empty bitfun-core default', () => {
   const core = packageAt('bitfun-core', 'src/crates/assembly/core/Cargo.toml');
   const app = packageAt('entry', 'src/apps/example/Cargo.toml', [
     pathDependency('src/crates/assembly/core', {
@@ -382,8 +1000,7 @@ test('product entrypoints must disable bitfun-core default features', () => {
     { root: TEST_ROOT, crateLayoutRules },
   );
 
-  assert.equal(violations.length, 1);
-  assert.match(violations[0].message, /default-features = false/);
+  assert.deepEqual(violations, []);
 });
 
 test('Core Agent Runtime baseline excludes concrete capability unions', () => {
@@ -414,8 +1031,30 @@ test('Core Agent Runtime baseline excludes concrete capability unions', () => {
   }
 });
 
+test('Core optional document and subscription capabilities have independent modifiers', () => {
+  const ruleByFeature = new Map(
+    coreClosedFeatureProfileRules.map((rule) => [rule.featureName, rule]),
+  );
+  assert.deepEqual(ruleByFeature.get('document-read')?.requiredFeatureRefs, [
+    'tool-runtime?/document-read',
+  ]);
+  assert.deepEqual(ruleByFeature.get('subscription-auth')?.requiredFeatureRefs, [
+    'bitfun-ai-adapters?/subscription-auth',
+  ]);
+  assert.deepEqual(ruleByFeature.get('ai-adapter-runtime')?.requiredFeatureRefs, [
+    'dep:bitfun-ai-adapters',
+  ]);
+  assert.ok(
+    !ruleByFeature.get('tools-basic')?.requiredFeatureRefs.includes('tool-runtime/document-read'),
+    'baseline tools must not activate document conversion',
+  );
+});
+
 test('Core product-full explicitly assembles service and tool capability owners', () => {
   for (const required of [
+    'document-read',
+    'subscription-auth',
+    'i18n-runtime',
     'model-catalog',
     'mcp-runtime',
     'remote-connect',
@@ -485,12 +1124,320 @@ test('explicit product entrypoint bitfun-core feature selections pass', () => {
   );
 });
 
-const ACP_REVIEWED_CORE_FEATURES = [
+test('Desktop and Server must retain the full product Core capability closure', () => {
+  const core = packageAt('bitfun-core', 'src/crates/assembly/core/Cargo.toml');
+
+  for (const [name, manifestPath] of [
+    ['bitfun-desktop', 'src/apps/desktop/Cargo.toml'],
+    ['bitfun-server', 'src/apps/server/Cargo.toml'],
+  ]) {
+    const product = packageAt(name, manifestPath, [
+      pathDependency('src/crates/assembly/core', {
+        name: 'bitfun-core',
+        usesDefaultFeatures: false,
+        features: ['i18n-runtime'],
+      }),
+    ]);
+    const messages = findProductEntrypointCoreFeatureViolations(
+      [product, core],
+      { root: TEST_ROOT, crateLayoutRules },
+    ).map((violation) => violation.message);
+
+    assert.deepEqual(messages, [
+      `${name} Core capability closure must select exactly product-full`,
+    ]);
+  }
+});
+
+test('Desktop and Server must retain their Core product dependency', () => {
+  const core = packageAt('bitfun-core', 'src/crates/assembly/core/Cargo.toml');
+  for (const [name, manifestPath] of [
+    ['bitfun-desktop', 'src/apps/desktop/Cargo.toml'],
+    ['bitfun-server', 'src/apps/server/Cargo.toml'],
+  ]) {
+    const product = packageAt(name, manifestPath);
+    assert.deepEqual(
+      findProductEntrypointCoreFeatureViolations(
+        [product, core],
+        { root: TEST_ROOT, crateLayoutRules },
+      ).map((violation) => violation.message),
+      [`${name} Core capability closure must keep the bitfun-core dependency`],
+    );
+  }
+});
+
+test('Desktop must select only the ACP client role', () => {
+  const acp = {
+    ...packageAt('bitfun-acp', 'src/crates/interfaces/acp/Cargo.toml'),
+    features: {
+      default: ['client', 'server'],
+      client: [],
+      server: [],
+    },
+  };
+  const desktop = packageAt('bitfun-desktop', 'src/apps/desktop/Cargo.toml', [
+    pathDependency('src/crates/interfaces/acp', {
+      name: 'bitfun-acp',
+      usesDefaultFeatures: false,
+      features: ['client', 'server'],
+    }),
+  ]);
+
+  const violations = findProductEntrypointCoreFeatureViolations(
+    [desktop, acp],
+    { root: TEST_ROOT, crateLayoutRules },
+  );
+
+  assert.equal(violations.length, 1);
+  assert.match(violations[0].message, /Desktop ACP role selection must not include server/);
+});
+
+test('ACP consumers must disable compatibility default roles', () => {
+  const acp = {
+    ...packageAt('bitfun-acp', 'src/crates/interfaces/acp/Cargo.toml'),
+    features: { default: ['client', 'server'], client: [], server: [] },
+  };
+  const desktop = packageAt('bitfun-desktop', 'src/apps/desktop/Cargo.toml', [
+    pathDependency('src/crates/interfaces/acp', {
+      name: 'bitfun-acp',
+      usesDefaultFeatures: true,
+      features: ['client'],
+    }),
+  ]);
+
+  const violations = findProductEntrypointCoreFeatureViolations(
+    [desktop, acp],
+    { root: TEST_ROOT, crateLayoutRules },
+  );
+
+  assert.equal(violations.length, 1);
+  assert.match(violations[0].message, /must set default-features = false on every dependency/);
+});
+
+test('CLI must select both ACP roles explicitly', () => {
+  const acp = {
+    ...packageAt('bitfun-acp', 'src/crates/interfaces/acp/Cargo.toml'),
+    features: {
+      default: ['client', 'server'],
+      client: [],
+      server: [],
+    },
+  };
+  const cli = packageAt('bitfun-cli', 'src/apps/cli/Cargo.toml', [
+    pathDependency('src/crates/interfaces/acp', {
+      name: 'bitfun-acp',
+      usesDefaultFeatures: false,
+      features: ['client'],
+    }),
+  ]);
+
+  const violations = findProductEntrypointCoreFeatureViolations(
+    [cli, acp],
+    { root: TEST_ROOT, crateLayoutRules },
+  );
+
+  assert.equal(violations.length, 1);
+  assert.match(violations[0].message, /CLI ACP role selection must include server/);
+});
+
+test('new product entrypoints must register an explicit ACP role selection', () => {
+  const acp = {
+    ...packageAt('bitfun-acp', 'src/crates/interfaces/acp/Cargo.toml'),
+    features: {
+      default: ['client', 'server'],
+      client: [],
+      server: [],
+    },
+  };
+  const newHost = packageAt('bitfun-new-host', 'src/apps/new-host/Cargo.toml', [
+    pathDependency('src/crates/interfaces/acp', {
+      name: 'bitfun-acp',
+      usesDefaultFeatures: false,
+      features: ['client'],
+    }),
+  ]);
+
+  const violations = findProductEntrypointCoreFeatureViolations(
+    [newHost, acp],
+    { root: TEST_ROOT, crateLayoutRules },
+  );
+
+  assert.equal(violations.length, 1);
+  assert.match(violations[0].message, /must register an explicit role selection/);
+});
+
+test('ACP roles must be selected by an unconditional normal dependency', () => {
+  const acp = {
+    ...packageAt('bitfun-acp', 'src/crates/interfaces/acp/Cargo.toml'),
+    features: {
+      default: ['client', 'server'],
+      client: [],
+      server: [],
+    },
+  };
+  const desktop = packageAt('bitfun-desktop', 'src/apps/desktop/Cargo.toml', [
+    pathDependency('src/crates/interfaces/acp', {
+      name: 'bitfun-acp',
+      kind: 'dev',
+      usesDefaultFeatures: false,
+      features: ['client'],
+    }),
+  ]);
+
+  const violations = findProductEntrypointCoreFeatureViolations(
+    [desktop, acp],
+    { root: TEST_ROOT, crateLayoutRules },
+  );
+
+  assert.equal(violations.length, 1);
+  assert.match(
+    violations[0].message,
+    /Desktop ACP role selection must keep an unconditional normal bitfun-acp dependency/,
+  );
+});
+
+test('reviewed ACP roles require an unconditional normal dependency', () => {
+  const acp = {
+    ...packageAt('bitfun-acp', 'src/crates/interfaces/acp/Cargo.toml'),
+    features: { default: ['client', 'server'], client: [], server: [] },
+  };
+  const desktop = packageAt('bitfun-desktop', 'src/apps/desktop/Cargo.toml', [
+    pathDependency('src/crates/interfaces/acp', {
+      name: 'bitfun-acp',
+      target: 'cfg(windows)',
+      usesDefaultFeatures: false,
+      features: ['client'],
+    }),
+  ]);
+
+  const violations = findProductEntrypointCoreFeatureViolations(
+    [desktop, acp],
+    { root: TEST_ROOT, crateLayoutRules },
+  );
+
+  assert.equal(violations.length, 1);
+  assert.match(violations[0].message, /must keep an unconditional normal bitfun-acp dependency/);
+});
+
+test('target-specific ACP edges cannot expand a reviewed product role', () => {
+  const acp = {
+    ...packageAt('bitfun-acp', 'src/crates/interfaces/acp/Cargo.toml'),
+    features: { default: ['client', 'server'], client: [], server: [] },
+  };
+  const desktop = packageAt('bitfun-desktop', 'src/apps/desktop/Cargo.toml', [
+    pathDependency('src/crates/interfaces/acp', {
+      name: 'bitfun-acp',
+      usesDefaultFeatures: false,
+      features: ['client'],
+    }),
+    pathDependency('src/crates/interfaces/acp', {
+      name: 'bitfun-acp',
+      target: 'cfg(windows)',
+      usesDefaultFeatures: false,
+      features: ['server'],
+    }),
+  ]);
+
+  const violations = findProductEntrypointCoreFeatureViolations(
+    [desktop, acp],
+    { root: TEST_ROOT, crateLayoutRules },
+  );
+
+  assert.equal(violations.length, 1);
+  assert.match(violations[0].message, /Desktop ACP role selection must not include server/);
+});
+
+test('dev and build ACP edges cannot expand a reviewed product role', () => {
+  const acp = {
+    ...packageAt('bitfun-acp', 'src/crates/interfaces/acp/Cargo.toml'),
+    features: { default: ['client', 'server'], client: [], server: [] },
+  };
+
+  for (const kind of ['dev', 'build']) {
+    const desktop = packageAt('bitfun-desktop', 'src/apps/desktop/Cargo.toml', [
+      pathDependency('src/crates/interfaces/acp', {
+        name: 'bitfun-acp',
+        usesDefaultFeatures: false,
+        features: ['client'],
+      }),
+      pathDependency('src/crates/interfaces/acp', {
+        name: 'bitfun-acp',
+        kind,
+        usesDefaultFeatures: false,
+        features: ['server'],
+      }),
+    ]);
+
+    const violations = findProductEntrypointCoreFeatureViolations(
+      [desktop, acp],
+      { root: TEST_ROOT, crateLayoutRules },
+    );
+
+    assert.equal(violations.length, 1, `${kind} dependency must not widen Desktop ACP roles`);
+    assert.match(violations[0].message, /Desktop ACP role selection must not include server/);
+  }
+});
+
+test('reviewed ACP product dependencies must not become optional', () => {
+  const acp = {
+    ...packageAt('bitfun-acp', 'src/crates/interfaces/acp/Cargo.toml'),
+    features: { default: ['client', 'server'], client: [], server: [] },
+  };
+  const desktop = packageAt('bitfun-desktop', 'src/apps/desktop/Cargo.toml', [
+    pathDependency('src/crates/interfaces/acp', {
+      name: 'bitfun-acp',
+      optional: true,
+      usesDefaultFeatures: false,
+      features: ['client'],
+    }),
+  ]);
+
+  const violations = findProductEntrypointCoreFeatureViolations(
+    [desktop, acp],
+    { root: TEST_ROOT, crateLayoutRules },
+  );
+
+  assert.equal(violations.length, 2);
+  assert.match(violations[0].message, /must keep an unconditional normal bitfun-acp dependency/);
+  assert.match(violations[1].message, /must not make a bitfun-acp dependency optional/);
+});
+
+test('target, dev, and build ACP consumers must still register their role selection', () => {
+  const acp = {
+    ...packageAt('bitfun-acp', 'src/crates/interfaces/acp/Cargo.toml'),
+    features: { default: ['client', 'server'], client: [], server: [] },
+  };
+  for (const dependency of [
+    { target: 'cfg(windows)' },
+    { kind: 'dev' },
+    { kind: 'build' },
+  ]) {
+    const newHost = packageAt('bitfun-new-host', 'src/apps/new-host/Cargo.toml', [
+      pathDependency('src/crates/interfaces/acp', {
+        name: 'bitfun-acp',
+        ...dependency,
+        usesDefaultFeatures: false,
+        features: ['client'],
+      }),
+    ]);
+
+    const violations = findProductEntrypointCoreFeatureViolations(
+      [newHost, acp],
+      { root: TEST_ROOT, crateLayoutRules },
+    );
+
+    assert.equal(violations.length, 1);
+    assert.match(violations[0].message, /must register an explicit role selection/);
+  }
+});
+
+const SDK_HOST_REVIEWED_CORE_FEATURES = [
   'agent-runtime',
+  'document-read',
+  'subscription-auth',
   'deep-research',
   'lsp',
   'external-sources',
-  'ssh-remote',
   'tools-basic',
   'tools-git',
   'tools-mcp',
@@ -502,6 +1449,11 @@ const ACP_REVIEWED_CORE_FEATURES = [
   'tools-agent-control',
 ];
 
+const ACP_REVIEWED_CORE_FEATURES = [
+  ...SDK_HOST_REVIEWED_CORE_FEATURES,
+  'ssh-remote',
+];
+
 const CLI_REVIEWED_CORE_FEATURES = [
   ...ACP_REVIEWED_CORE_FEATURES,
   'remote-connect',
@@ -511,9 +1463,130 @@ const CLI_REVIEWED_CORE_FEATURES = [
 const APP_SERVER_REVIEWED_CORE_FEATURES = [
   'external-sources',
   'git',
+  'i18n-runtime',
   'remote-connect',
 ];
 
+test('SDK Host Core capability closure keeps every reviewed owner', () => {
+  const core = packageAt('bitfun-core', 'src/crates/assembly/core/Cargo.toml');
+  const sdkHost = packageAt(
+    'bitfun-sdk-host-app',
+    'src/apps/sdk-host/Cargo.toml',
+    [pathDependency('src/crates/assembly/core', {
+      name: 'bitfun-core',
+      usesDefaultFeatures: false,
+      features: SDK_HOST_REVIEWED_CORE_FEATURES.filter(
+        (feature) => feature !== 'external-sources',
+      ),
+    })],
+  );
+
+  const violations = findProductEntrypointCoreFeatureViolations(
+    [sdkHost, core],
+    { root: TEST_ROOT, crateLayoutRules },
+  );
+
+  assert.deepEqual(violations.map((violation) => violation.message), [
+    'bitfun-sdk-host-app Core capability closure must include external-sources',
+  ]);
+});
+
+test('SDK Host closure rejects unreviewed capability owners below Core', () => {
+  const cases = [
+    ['bitfun-services-integrations', 'src/crates/services/services-integrations/Cargo.toml', 'remote-connect'],
+    ['bitfun-services-integrations', 'src/crates/services/services-integrations/Cargo.toml', 'remote-ssh'],
+    ['bitfun-services-integrations', 'src/crates/services/services-integrations/Cargo.toml', 'remote-ssh-concrete'],
+    ['bitfun-services-integrations', 'src/crates/services/services-integrations/Cargo.toml', 'function-agents'],
+    ['bitfun-services-integrations', 'src/crates/services/services-integrations/Cargo.toml', 'announcement'],
+    ['bitfun-services-integrations', 'src/crates/services/services-integrations/Cargo.toml', 'debug-log'],
+    ['bitfun-services-integrations', 'src/crates/services/services-integrations/Cargo.toml', 'product-full'],
+    ['bitfun-product-domains', 'src/crates/contracts/product-domains/Cargo.toml', 'function-agents'],
+    ['bitfun-product-domains', 'src/crates/contracts/product-domains/Cargo.toml', 'product-full'],
+    ['bitfun-services-core', 'src/crates/services/services-core/Cargo.toml', 'dispatch-workspace'],
+  ];
+
+  for (const [ownerName, ownerManifest, forbiddenFeature] of cases) {
+    const core = packageAt('bitfun-core', 'src/crates/assembly/core/Cargo.toml');
+    const owner = {
+      ...packageAt(ownerName, ownerManifest),
+      features: { [forbiddenFeature]: [] },
+    };
+    const bridge = packageAt('bridge', 'src/crates/assembly/bridge/Cargo.toml', [
+      pathDependency(ownerManifest.replace('/Cargo.toml', ''), {
+        name: ownerName,
+        usesDefaultFeatures: false,
+        features: [forbiddenFeature],
+      }),
+    ]);
+    const sdkHost = packageAt(
+      'bitfun-sdk-host-app',
+      'src/apps/sdk-host/Cargo.toml',
+      [
+        pathDependency('src/crates/assembly/core', {
+          name: 'bitfun-core',
+          usesDefaultFeatures: false,
+          features: SDK_HOST_REVIEWED_CORE_FEATURES,
+        }),
+        pathDependency('src/crates/assembly/bridge', { name: 'bridge' }),
+      ],
+    );
+
+    const violations = findProductEntrypointCoreFeatureViolations(
+      [sdkHost, bridge, core, owner],
+      { root: TEST_ROOT, crateLayoutRules },
+    );
+
+    const forbiddenOwner = `${ownerName}/${forbiddenFeature}`;
+    assert.equal(violations.length, 1, forbiddenOwner);
+    assert.match(
+      violations[0].message,
+      new RegExp(forbiddenOwner),
+    );
+  }
+});
+
+test('SDK Host closure inspects lower owners forwarded by reviewed Core features', () => {
+  const ownerManifest = 'src/crates/services/services-integrations/Cargo.toml';
+  const core = {
+    ...packageAt(
+      'bitfun-core',
+      'src/crates/assembly/core/Cargo.toml',
+      [pathDependency('src/crates/services/services-integrations', {
+        name: 'bitfun-services-integrations',
+        optional: true,
+        usesDefaultFeatures: false,
+      })],
+    ),
+    features: {
+      'external-sources': ['bitfun-services-integrations/remote-connect'],
+    },
+  };
+  const owner = {
+    ...packageAt('bitfun-services-integrations', ownerManifest),
+    features: { 'remote-connect': [] },
+  };
+  const sdkHost = packageAt(
+    'bitfun-sdk-host-app',
+    'src/apps/sdk-host/Cargo.toml',
+    [pathDependency('src/crates/assembly/core', {
+      name: 'bitfun-core',
+      usesDefaultFeatures: false,
+      features: SDK_HOST_REVIEWED_CORE_FEATURES,
+    })],
+  );
+
+  const violations = findProductEntrypointCoreFeatureViolations(
+    [sdkHost, core, owner],
+    { root: TEST_ROOT, crateLayoutRules },
+  );
+
+  assert.equal(violations.length, 1);
+  assert.match(
+    violations[0].message,
+    /bitfun-services-integrations\/remote-connect/,
+  );
+});
+
 test('App Server Core capability closure keeps its production Git owner', () => {
   const core = packageAt('bitfun-core', 'src/crates/assembly/core/Cargo.toml');
   const appServer = packageAt(
@@ -536,6 +1609,30 @@ test('App Server Core capability closure keeps its production Git owner', () =>
   ]);
 });
 
+test('App Server Core capability closure keeps its backend i18n runtime', () => {
+  const core = packageAt('bitfun-core', 'src/crates/assembly/core/Cargo.toml');
+  const appServer = packageAt(
+    'bitfun-app-server',
+    'src/crates/interfaces/app-server/Cargo.toml',
+    [pathDependency('src/crates/assembly/core', {
+      name: 'bitfun-core',
+      usesDefaultFeatures: false,
+      features: APP_SERVER_REVIEWED_CORE_FEATURES.filter(
+        (feature) => feature !== 'i18n-runtime',
+      ),
+    })],
+  );
+
+  const violations = findProductEntrypointCoreFeatureViolations(
+    [appServer, core],
+    { root: TEST_ROOT, crateLayoutRules },
+  );
+
+  assert.deepEqual(violations.map((violation) => violation.message), [
+    'bitfun-app-server Core capability closure must include i18n-runtime',
+  ]);
+});
+
 test('App Server reviewed Core capability closure remains independently valid', () => {
   const core = packageAt('bitfun-core', 'src/crates/assembly/core/Cargo.toml');
   const appServer = packageAt(
@@ -1368,6 +2465,21 @@ test('workspace Tokio capabilities stay crate-owned', async () => {
   assert.doesNotMatch(workspaceTokio, /(?:^|,\s*)features\s*=/);
   const packages = collectCargoMetadataPackages({ root: repositoryRoot });
   assert.deepEqual(findTokioDependencyFeatureViolations(packages), []);
+
+  const integrations = packages.find((pkg) => pkg.name === 'bitfun-services-integrations');
+  const mutatedPackages = packages.map((pkg) => pkg === integrations
+    ? {
+        ...pkg,
+        dependencies: pkg.dependencies.map((dependency) =>
+          dependency.name === 'tokio' && (dependency.kind ?? null) === null
+            ? { ...dependency, features: ['net'] }
+            : dependency),
+      }
+    : pkg);
+  assert.ok(
+    findTokioDependencyFeatureViolations(mutatedPackages).some((violation) =>
+      violation.message === 'bitfun-services-integrations has unexpected base Tokio capabilities: net'),
+  );
 });
 
 test('services integrations Tokio owner contracts reject feature-union masking', async () => {
@@ -1399,7 +2511,7 @@ test('services integrations Reqwest policy uses Cargo-decoded feature references
 reqwest = ["dep:reqwest"]
 announcement = ["reqwest", "reqwest/rustls"]
 file-watch = ["reqwest?/__native-tls"]
-mcp = ["reqwest"]
+mcp = ["reqwest", "reqwest/rustls", "reqwest/json"]
 models-dev = ["reqwest", "reqwest/rustls", "reqwest/system-proxy"]
 speech = ["reqwest", "reqwest/rustls", "reqwest/http3"]
 `);
@@ -1407,8 +2519,9 @@ speech = ["reqwest", "reqwest/rustls", "reqwest/http3"]
   const messages = findServicesIntegrationsReqwestFeatureViolations(pkg)
     .map((violation) => violation.message)
     .join('\n');
+  assert.match(messages, /announcement.*missing Reqwest feature reference reqwest\/json/);
   assert.match(messages, /file-watch.*outside its reviewed owner features/);
-  assert.match(messages, /mcp.*missing reqwest\/rustls/);
+  assert.match(messages, /mcp.*missing Reqwest feature reference reqwest\/stream/);
   assert.doesNotMatch(messages, /models-dev.*system-proxy/);
   assert.match(messages, /speech.*unreviewed Reqwest feature reference reqwest\/http3/);
 });
@@ -1422,11 +2535,7 @@ test('direct Reqwest clients reject extra decoded dependency and package feature
       uses_default_features: false,
       features: [
         'http2',
-        'json',
         'stream',
-        'multipart',
-        'query',
-        'form',
         'rustls',
         '__native-tls',
       ],
@@ -1449,15 +2558,19 @@ test('direct Reqwest clients reject extra decoded dependency and package feature
 });
 
 test('AI adapters Reqwest profile owns the supported SOCKS transport', () => {
-  const baseFeatures = ['http2', 'json', 'stream', 'multipart', 'query', 'form'];
-  const valid = packageAt('bitfun-ai-adapters', 'src/crates/adapters/ai-adapters/Cargo.toml', [{
-    name: 'reqwest',
-    kind: null,
-    optional: false,
-    uses_default_features: false,
-    features: [...baseFeatures, 'rustls', 'socks'],
-  }]);
-  const missingSocks = packageAt(
+  const baseFeatures = ['http2', 'json', 'stream'];
+  const valid = {
+    ...packageAt('bitfun-ai-adapters', 'src/crates/adapters/ai-adapters/Cargo.toml', [{
+      name: 'reqwest',
+      kind: null,
+      optional: false,
+      uses_default_features: false,
+      features: [...baseFeatures, 'rustls', 'socks'],
+    }]),
+    features: { 'subscription-auth': ['reqwest/form'] },
+  };
+  const missingSocks = {
+    ...packageAt(
     'bitfun-ai-adapters',
     'src/crates/adapters/ai-adapters/Cargo.toml',
     [{
@@ -1467,7 +2580,9 @@ test('AI adapters Reqwest profile owns the supported SOCKS transport', () => {
       uses_default_features: false,
       features: [...baseFeatures, 'rustls'],
     }],
-  );
+    ),
+    features: { 'subscription-auth': ['reqwest/form'] },
+  };
 
   assert.deepEqual(findReqwestDependencyFeatureViolations([valid]), []);
   const messages = findReqwestDependencyFeatureViolations([missingSocks])
@@ -1477,14 +2592,14 @@ test('AI adapters Reqwest profile owns the supported SOCKS transport', () => {
 });
 
 test('Reqwest metadata policy covers URL-only and future dependency owners', () => {
-  const baseFeatures = ['http2', 'json', 'stream', 'multipart', 'query', 'form'];
+  const coreFeatures = [];
   const core = {
     ...packageAt('bitfun-core', 'src/crates/assembly/core/Cargo.toml', [{
       name: 'reqwest',
       kind: null,
       optional: true,
       uses_default_features: false,
-      features: baseFeatures,
+      features: coreFeatures,
     }]),
     features: { product: ['dep:reqwest', 'reqwest/__native-tls'] },
   };
@@ -1493,7 +2608,7 @@ test('Reqwest metadata policy covers URL-only and future dependency owners', ()
     kind: null,
     optional: false,
     uses_default_features: false,
-    features: [...baseFeatures, 'rustls'],
+    features: ['http2', 'rustls', 'stream'],
   }]);
   const duplicate = packageAt(
     'bitfun-services-integrations',
@@ -1504,7 +2619,7 @@ test('Reqwest metadata policy covers URL-only and future dependency owners', ()
         kind: null,
         optional: true,
         uses_default_features: false,
-        features: baseFeatures,
+        features: ['http2'],
       },
       {
         name: 'reqwest',
@@ -1513,7 +2628,7 @@ test('Reqwest metadata policy covers URL-only and future dependency owners', ()
         optional: true,
         target: 'cfg(windows)',
         uses_default_features: false,
-        features: [...baseFeatures, '__native-tls'],
+        features: ['http2', '__native-tls'],
       },
     ],
   );
@@ -1526,6 +2641,22 @@ test('Reqwest metadata policy covers URL-only and future dependency owners', ()
   assert.match(messages, /bitfun-services-integrations.*exactly one normal Reqwest dependency/);
 });
 
+test('Reqwest consumers inherit the workspace version without duplicating feature rules', async () => {
+  const { requiredContentRules } = await import(
+    './core-boundaries/rules/source/required-rules.mjs'
+  );
+  const rules = requiredContentRules.filter((rule) =>
+    rule.reason.includes('Reqwest consumers must inherit the workspace-owned compatible version')
+  );
+
+  assert.equal(rules.length, 7);
+  for (const rule of rules) {
+    const pattern = rule.patterns[0].regex;
+    assert.match('reqwest = { workspace = true, features = ["rustls"] }', pattern);
+    assert.doesNotMatch('reqwest = { version = "99", features = ["rustls"] }', pattern);
+  }
+});
+
 test('resolved Reqwest feature union rejects every native TLS backend alias', () => {
   const violations = findResolvedReqwestNativeTlsViolations(
     [
@@ -1980,7 +3111,10 @@ test('split core boundary check keeps self-test and default execution behavior',
 });
 
 test('optional dependency ownership rejects undeclared direct feature owners', async () => {
-  const { unexpectedDependencyOwnerFeatures } = await import(
+  const {
+    featureReferencesOptionalDependencyOwner,
+    unexpectedDependencyOwnerFeatures,
+  } = await import(
     './core-boundaries/manifest-feature-helpers.mjs'
   );
   const features = new Map([
@@ -1996,7 +3130,31 @@ test('optional dependency ownership rejects undeclared direct feature owners', a
       depName: 'example',
       ownerFeatures: ['declared'],
     }).map(([featureName]) => featureName),
-    ['missing', 'feature-ref'],
+    ['missing', 'feature-ref', 'weak-ref'],
+  );
+  assert.equal(featureReferencesOptionalDependencyOwner(features.get('declared'), 'example'), true);
+  assert.equal(featureReferencesOptionalDependencyOwner(features.get('weak-ref'), 'example'), true);
+  assert.equal(featureReferencesOptionalDependencyOwner(features.get('unrelated'), 'example'), false);
+});
+
+test('optional dependency ownership rejects hidden aliases but permits reviewed aggregates', async () => {
+  const { unexpectedDependencyOwnerFeatures } = await import(
+    './core-boundaries/manifest-feature-helpers.mjs'
+  );
+  const features = new Map([
+    ['owner', { refs: ['dep:example'], line: 1 }],
+    ['reviewed-aggregate', { refs: ['owner'], line: 2 }],
+    ['sneaky', { refs: ['owner'], line: 3 }],
+    ['bad-aggregate', { refs: ['owner', 'dep:example'], line: 4 }],
+  ]);
+
+  assert.deepEqual(
+    unexpectedDependencyOwnerFeatures(
+      features,
+      { depName: 'example', ownerFeatures: ['owner'] },
+      new Set(['reviewed-aggregate', 'bad-aggregate']),
+    ).map(([featureName]) => featureName),
+    ['sneaky', 'bad-aggregate'],
   );
 });
 
@@ -2021,14 +3179,20 @@ test('services-core capability profiles keep heavy owners out of the empty profi
     'dep:base64',
     'dep:chrono',
     'dep:ignore',
+    'dep:regex',
     'dep:sha2',
+    'dep:tokio',
     'tokio/fs',
+    'tokio/rt',
   ]);
   assert.deepEqual(profiles.get('json-io'), [
     'dep:fs2',
+    'dep:tokio',
     'dep:windows',
     'tokio/fs',
+    'tokio/rt',
     'tokio/sync',
+    'tokio/time',
     'windows/Win32_Foundation',
     'windows/Win32_Storage_FileSystem',
   ]);
@@ -2038,29 +3202,40 @@ test('services-core capability profiles keep heavy owners out of the empty profi
     'dep:chrono',
     'dep:fs2',
     'dep:libc',
+    'dep:regex',
     'dep:sha2',
+    'dep:similar',
+    'dep:tokio',
     'dep:windows',
     'tokio/fs',
+    'tokio/rt',
     'tokio/sync',
+    'tokio/time',
     'windows/Win32_Foundation',
     'windows/Win32_Storage_FileSystem',
   ]);
   assert.deepEqual(profiles.get('process-runtime'), [
     'dep:libc',
+    'dep:tokio',
     'dep:which',
     'dep:win32job',
     'dep:windows',
     'tokio/io-util',
     'tokio/process',
+    'tokio/rt',
+    'tokio/time',
     'windows/Win32_Foundation',
     'windows/Win32_System_Diagnostics_ToolHelp',
     'windows/Win32_System_Threading',
   ]);
   assert.deepEqual(profiles.get('workspace-instructions'), [
     'dep:globset',
+    'dep:regex',
     'dep:serde_yaml',
+    'dep:tokio',
     'tokio/fs',
     'tokio/io-util',
+    'tokio/rt',
   ]);
   assert.deepEqual(profiles.get('lsp'), [
     'dep:anyhow',
@@ -2076,6 +3251,8 @@ test('services-core capability profiles keep heavy owners out of the empty profi
     'dep:anyhow',
     'dep:async-trait',
     'dep:bitfun-runtime-ports',
+    'bitfun-runtime-ports/runtime-event-port',
+    'bitfun-runtime-ports/workspace-ports',
     'dep:dunce',
     'process-runtime',
     'tokio/fs',
@@ -2095,7 +3272,9 @@ test('services-core capability profiles keep heavy owners out of the empty profi
     'globset',
     'ignore',
     'libc',
+    'regex',
     'sha2',
+    'similar',
     'which',
     'win32job',
     'windows',
@@ -2111,6 +3290,8 @@ test('services-core capability profiles keep heavy owners out of the empty profi
   );
   const sourceContracts = sourceRule?.patterns.map((pattern) => pattern.regex.source).join('\n') ?? '';
   for (const moduleName of [
+    'diagnostics',
+    'diff',
     'filesystem',
     'json_store',
     'managed_runtime',
@@ -2172,6 +3353,186 @@ test('services-core Tokio capabilities stay owner-scoped', () => {
   );
 });
 
+test('Services Core accepts only the reviewed feature-owned Tokio runtime graph', () => {
+  const validPackage = {
+    name: 'bitfun-services-core',
+    manifest_path: 'src/crates/services/services-core/Cargo.toml',
+    dependencies: [
+      {
+        name: 'tokio',
+        kind: null,
+        optional: true,
+        features: [],
+      },
+    ],
+    features: {
+      diff: ['dep:tokio', 'tokio/rt', 'tokio/time'],
+      filesystem: ['dep:tokio', 'tokio/fs', 'tokio/rt'],
+      'json-io': ['dep:tokio', 'tokio/fs', 'tokio/rt', 'tokio/sync', 'tokio/time'],
+      'local-storage': [
+        'dep:tokio',
+        'tokio/fs',
+        'tokio/rt',
+        'tokio/sync',
+        'tokio/time',
+      ],
+      permission: ['dep:tokio', 'tokio/rt'],
+      'process-runtime': [
+        'dep:tokio',
+        'tokio/io-util',
+        'tokio/process',
+        'tokio/rt',
+        'tokio/time',
+      ],
+      'workspace-instructions': ['dep:tokio', 'tokio/fs', 'tokio/io-util', 'tokio/rt'],
+      'workspace-text-runtime': ['dep:tokio', 'tokio/rt'],
+      lsp: ['process-runtime', 'tokio/fs', 'tokio/io-util', 'tokio/sync'],
+      'workspace-runtime': [
+        'process-runtime',
+        'tokio/fs',
+        'tokio/io-util',
+        'tokio/sync',
+      ],
+      'session-git': ['local-storage'],
+    },
+  };
+
+  assert.deepEqual(findTokioDependencyFeatureViolations([validPackage]), []);
+});
+
+test('Services Core Tokio owners cannot be hidden behind an unreviewed alias', () => {
+  const invalidPackage = {
+    name: 'bitfun-services-core',
+    manifest_path: 'src/crates/services/services-core/Cargo.toml',
+    dependencies: [
+      {
+        name: 'tokio',
+        kind: null,
+        optional: true,
+        features: [],
+      },
+    ],
+    features: {
+      diff: ['dep:tokio', 'tokio/rt', 'tokio/time'],
+      filesystem: ['dep:tokio', 'tokio/fs', 'tokio/rt'],
+      'json-io': ['dep:tokio', 'tokio/fs', 'tokio/rt', 'tokio/sync', 'tokio/time'],
+      'local-storage': [
+        'dep:tokio',
+        'tokio/fs',
+        'tokio/rt',
+        'tokio/sync',
+        'tokio/time',
+      ],
+      permission: ['dep:tokio', 'tokio/rt'],
+      'process-runtime': [
+        'dep:tokio',
+        'tokio/io-util',
+        'tokio/process',
+        'tokio/rt',
+        'tokio/time',
+      ],
+      'workspace-instructions': ['dep:tokio', 'tokio/fs', 'tokio/io-util', 'tokio/rt'],
+      'workspace-text-runtime': ['dep:tokio', 'tokio/rt'],
+      lsp: ['process-runtime', 'tokio/fs', 'tokio/io-util', 'tokio/sync'],
+      'workspace-runtime': [
+        'process-runtime',
+        'tokio/fs',
+        'tokio/io-util',
+        'tokio/sync',
+      ],
+      sneaky: ['filesystem', 'local-storage'],
+      'sneaky-weak': ['tokio?/full'],
+    },
+  };
+
+  const messages = findTokioDependencyFeatureViolations([invalidPackage]).map(
+    (violation) => violation.message,
+  );
+  assert.ok(
+    messages.includes('bitfun-services-core:sneaky Tokio capabilities require an explicit owner contract'),
+  );
+  assert.ok(
+    messages.includes('bitfun-services-core:sneaky-weak Tokio capabilities require an explicit owner contract'),
+  );
+});
+
+test('Core feature-free Tokio capabilities stay limited to baseline path and state IO', () => {
+  const invalidPackage = {
+    name: 'bitfun-core',
+    manifest_path: 'src/crates/assembly/core/Cargo.toml',
+    dependencies: [
+      {
+        name: 'tokio',
+        kind: null,
+        optional: false,
+        features: ['fs', 'io-util', 'macros', 'net', 'rt', 'sync', 'time'],
+      },
+    ],
+    features: {},
+  };
+
+  const messages = findTokioDependencyFeatureViolations([invalidPackage]).map(
+    (violation) => violation.message,
+  );
+  assert.ok(
+    messages.some((message) => message.includes('unexpected base Tokio capabilities')),
+    'Core must reject async runtime, networking, and timing capabilities in its feature-free profile',
+  );
+});
+
+test('Core Tokio capabilities cannot hide behind an unreviewed owner feature', () => {
+  const invalidPackage = {
+    name: 'bitfun-core',
+    manifest_path: 'src/crates/assembly/core/Cargo.toml',
+    dependencies: [
+      {
+        name: 'tokio',
+        kind: null,
+        optional: false,
+        features: ['fs', 'sync'],
+      },
+    ],
+    features: {
+      'agent-runtime': ['tokio/io-util', 'tokio/macros', 'tokio/rt', 'tokio/time'],
+      'mcp-runtime': ['agent-runtime', 'tokio/rt-multi-thread'],
+      'browser-control': ['tokio/net', 'tokio/rt', 'tokio/time'],
+      'debug-log': ['tokio/macros', 'tokio/net', 'tokio/rt', 'tokio/time'],
+      lsp: ['tokio/macros'],
+      sneaky: ['agent-runtime', 'browser-control'],
+    },
+  };
+
+  const messages = findTokioDependencyFeatureViolations([invalidPackage]).map(
+    (violation) => violation.message,
+  );
+  assert.deepEqual(messages, [
+    'bitfun-core:sneaky Tokio capabilities require an explicit owner contract',
+  ]);
+});
+
+test('reviewed Tokio aggregates cannot declare runtime capabilities directly', () => {
+  const invalidPackage = {
+    name: 'bitfun-core',
+    manifest_path: 'src/crates/assembly/core/Cargo.toml',
+    dependencies: [{ name: 'tokio', kind: null, optional: false, features: ['fs', 'sync'] }],
+    features: {
+      'agent-runtime': ['tokio/io-util', 'tokio/macros', 'tokio/rt', 'tokio/time'],
+      'mcp-runtime': ['agent-runtime', 'tokio/rt-multi-thread'],
+      'browser-control': ['tokio/net', 'tokio/rt', 'tokio/time'],
+      'debug-log': ['tokio/macros', 'tokio/net', 'tokio/rt', 'tokio/time'],
+      lsp: ['tokio/macros'],
+      'product-full': ['agent-runtime', 'tokio/net'],
+    },
+  };
+
+  const messages = findTokioDependencyFeatureViolations([invalidPackage]).map(
+    (violation) => violation.message,
+  );
+  assert.deepEqual(messages, [
+    'bitfun-core:product-full Tokio aggregate must compose reviewed owners instead of declaring Tokio capabilities directly',
+  ]);
+});
+
 test('services-core Windows API capabilities stay feature-owned', async () => {
   const { findServicesCorePlatformDependencyFeatureViolations } = await import(
     './core-boundaries/cargo-dependency-boundaries.mjs'
@@ -2245,3 +3606,388 @@ test('closed feature profiles reject product-full hidden behind a child feature'
     ],
   );
 });
+
+test('capability contract consumers may inherit empty defaults but must select reviewed features', async () => {
+  const cargoBoundaries = await import(
+    './core-boundaries/cargo-dependency-boundaries.mjs'
+  );
+  assert.equal(
+    typeof cargoBoundaries.findCapabilityContractConsumerViolations,
+    'function',
+    'Cargo boundary checker must expose the capability contract consumer policy',
+  );
+
+  const runtimePorts = capabilityPackage(
+    'bitfun-runtime-ports',
+    'src/crates/contracts/runtime-ports/Cargo.toml',
+    RUNTIME_PORT_FEATURE_PROFILES,
+  );
+  const agentTools = agentToolsCapabilityPackage();
+  const pluginRuntimeClient = packageAt(
+    'bitfun-plugin-runtime-client',
+    'src/crates/execution/plugin-runtime-client/Cargo.toml',
+    [
+      pathDependency('src/crates/contracts/runtime-ports', {
+        name: 'bitfun-runtime-ports',
+      }),
+    ],
+  );
+
+  const messages = findTestCapabilityViolations(
+    cargoBoundaries.findCapabilityContractConsumerViolations,
+    [
+    runtimePorts,
+    agentTools,
+    pluginRuntimeClient,
+    ],
+  ).map((violation) => violation.message);
+
+  assert.doesNotMatch(messages.join('\n'), /default-features = false/);
+  assert.ok(messages.some((message) => /plugin-runtime/.test(message)));
+});
+
+test('unreviewed consumers cannot add capability contract dependency edges', async () => {
+  const { findCapabilityContractConsumerViolations } = await import(
+    './core-boundaries/cargo-dependency-boundaries.mjs'
+  );
+  const runtimePorts = capabilityPackage(
+    'bitfun-runtime-ports',
+    'src/crates/contracts/runtime-ports/Cargo.toml',
+    RUNTIME_PORT_FEATURE_PROFILES,
+  );
+  const agentTools = agentToolsCapabilityPackage();
+  const unreviewed = packageAt(
+    'unreviewed-host',
+    'src/apps/unreviewed-host/Cargo.toml',
+    [
+      pathDependency('src/crates/contracts/runtime-ports', {
+        name: 'bitfun-runtime-ports',
+        target: 'cfg(windows)',
+        usesDefaultFeatures: false,
+        features: ['agent-api'],
+      }),
+    ],
+  );
+
+  const messages = findTestCapabilityViolations(
+    findCapabilityContractConsumerViolations,
+    [runtimePorts, agentTools, unreviewed],
+    capabilityContractDependencyRules.slice(0, 2),
+  ).map(
+    (violation) => violation.message,
+  );
+  assert.equal(messages.length, 1, messages.join('\n'));
+  assert.match(messages[0], /unreviewed consumer/);
+});
+
+test('capability contract edge policy rejects alias, weak, optional, and non-normal widening', async () => {
+  const { findCapabilityContractConsumerViolations } = await import(
+    './core-boundaries/cargo-dependency-boundaries.mjs'
+  );
+  const runtimePorts = capabilityPackage(
+    'bitfun-runtime-ports',
+    'src/crates/contracts/runtime-ports/Cargo.toml',
+    RUNTIME_PORT_FEATURE_PROFILES,
+  );
+  const validDependency = pathDependency('src/crates/contracts/runtime-ports', {
+    name: 'bitfun-runtime-ports',
+    usesDefaultFeatures: false,
+    features: ['plugin-runtime'],
+  });
+  const mutations = [
+    { label: 'renamed alias forwarding', dependency: { ...validDependency, rename: 'ports' }, features: { sneaky: ['ports/agent-api'] }, expected: /sneaky.*unreviewed.*forwarding/ },
+    { label: 'weak alias forwarding', dependency: { ...validDependency, rename: 'ports' }, features: { sneaky: ['ports?/agent-api'] }, expected: /sneaky.*unreviewed.*forwarding/ },
+    { label: 'optional edge', dependency: { ...validDependency, optional: true }, features: {}, expected: /unreviewed.*dependency edge/ },
+    { label: 'dev edge', dependency: { ...validDependency, kind: 'dev' }, features: {}, expected: /unreviewed.*dependency edge/ },
+    { label: 'build edge', dependency: { ...validDependency, kind: 'build' }, features: {}, expected: /unreviewed.*dependency edge/ },
+    { label: 'target edge', dependency: { ...validDependency, target: 'cfg(windows)' }, features: {}, expected: /unreviewed.*dependency edge/ },
+  ];
+
+  for (const mutation of mutations) {
+    const consumer = {
+      ...packageAt(
+        'bitfun-plugin-runtime-client',
+        'src/crates/execution/plugin-runtime-client/Cargo.toml',
+        [mutation.dependency],
+      ),
+      features: mutation.features,
+    };
+    const messages = findTestCapabilityViolations(
+      findCapabilityContractConsumerViolations,
+      [runtimePorts, consumer],
+    ).map(
+      (violation) => violation.message,
+    );
+    assert.ok(
+      messages.some((message) => mutation.expected.test(message)),
+      `${mutation.label} must not widen the reviewed capability contract`,
+    );
+  }
+});
+
+test('capability contract targets require an explicit empty default feature', async () => {
+  const { findCapabilityContractConsumerViolations } = await import(
+    './core-boundaries/cargo-dependency-boundaries.mjs'
+  );
+  const runtimePorts = capabilityPackage(
+    'bitfun-runtime-ports',
+    'src/crates/contracts/runtime-ports/Cargo.toml',
+    RUNTIME_PORT_FEATURE_PROFILES,
+  );
+  delete runtimePorts.features.default;
+
+  const messages = findTestCapabilityViolations(
+    findCapabilityContractConsumerViolations,
+    [runtimePorts],
+  ).map(
+    (violation) => violation.message,
+  );
+  assert.ok(messages.some((message) => /default feature must stay empty/.test(message)));
+});
+
+test('capability contract optional activators reject unreviewed dep aliases', async () => {
+  const { findCapabilityContractConsumerViolations } = await import(
+    './core-boundaries/cargo-dependency-boundaries.mjs'
+  );
+  const agentTools = agentToolsCapabilityPackage();
+  const dependency = pathDependency('src/crates/execution/tool-contracts', {
+    name: 'bitfun-agent-tools',
+    rename: 'tools_contract',
+    optional: true,
+    usesDefaultFeatures: false,
+  });
+  const consumer = {
+    ...packageAt(
+      'bitfun-acp',
+      'src/crates/interfaces/acp/Cargo.toml',
+      [dependency],
+    ),
+    features: {
+      client: ['tools_contract/acp-bridge'],
+      server: ['dep:tools_contract'],
+      sneaky: ['tools_contract'],
+    },
+  };
+
+  const messages = findTestCapabilityViolations(
+    findCapabilityContractConsumerViolations,
+    [agentTools, consumer],
+  ).map(
+    (violation) => violation.message,
+  );
+  assert.ok(messages.some((message) => /sneaky.*unreviewed.*activation/.test(message)));
+  assert.doesNotMatch(messages.join('\n'), /server.*unreviewed.*activation/);
+});
+
+test('capability contract consumers cannot remove reviewed forwarding or activation', async () => {
+  const { findCapabilityContractConsumerViolations } = await import(
+    './core-boundaries/cargo-dependency-boundaries.mjs'
+  );
+  const runtimePorts = capabilityPackage(
+    'bitfun-runtime-ports',
+    'src/crates/contracts/runtime-ports/Cargo.toml',
+    RUNTIME_PORT_FEATURE_PROFILES,
+  );
+  const integrations = {
+    ...packageAt(
+      'bitfun-services-integrations',
+      'src/crates/services/services-integrations/Cargo.toml',
+      [pathDependency('src/crates/contracts/runtime-ports', {
+        name: 'bitfun-runtime-ports',
+        optional: true,
+        usesDefaultFeatures: false,
+      })],
+    ),
+    features: {
+      git: [],
+      'remote-connect': [
+        'bitfun-runtime-ports/agent-api',
+        'bitfun-runtime-ports/remote-workspace-ports',
+      ],
+      'remote-ssh': [
+        'bitfun-runtime-ports/remote-exec-port',
+        'bitfun-runtime-ports/remote-workspace-ports',
+        'bitfun-runtime-ports/workspace-ports',
+      ],
+      'remote-ssh-concrete': ['dep:bitfun-runtime-ports'],
+      'script-tool-runtime': ['bitfun-runtime-ports/script-tool-runtime'],
+    },
+  };
+  const servicesCore = {
+    ...packageAt(
+      'bitfun-services-core',
+      'src/crates/services/services-core/Cargo.toml',
+      [pathDependency('src/crates/contracts/runtime-ports', {
+        name: 'bitfun-runtime-ports',
+        optional: true,
+        usesDefaultFeatures: false,
+      })],
+    ),
+    features: {
+      permission: [],
+      'workspace-runtime': [
+        'dep:bitfun-runtime-ports',
+        'bitfun-runtime-ports/runtime-event-port',
+        'bitfun-runtime-ports/workspace-ports',
+      ],
+    },
+  };
+
+  const messages = findTestCapabilityViolations(findCapabilityContractConsumerViolations, [
+    runtimePorts,
+    integrations,
+    servicesCore,
+  ]).map((violation) => violation.message);
+
+  assert.ok(messages.some((message) => /bitfun-services-integrations:git.*missing reviewed.*git-port forwarding/.test(message)));
+  assert.ok(messages.some((message) => /bitfun-services-core:permission.*missing reviewed.*activation/.test(message)));
+});
+
+test('capability contract targets cannot be removed or replaced by a same-name package', async () => {
+  const { findCapabilityContractConsumerViolations } = await import(
+    './core-boundaries/cargo-dependency-boundaries.mjs'
+  );
+  const reviewedConsumer = packageAt(
+    'bitfun-plugin-runtime-client',
+    'src/crates/execution/plugin-runtime-client/Cargo.toml',
+    [pathDependency('src/crates/contracts/runtime-ports', {
+      name: 'bitfun-runtime-ports',
+      usesDefaultFeatures: false,
+      features: ['plugin-runtime'],
+    })],
+  );
+
+  const missingTargetMessages = findTestCapabilityViolations(
+    findCapabilityContractConsumerViolations,
+    [reviewedConsumer],
+  ).map((violation) => violation.message);
+  assert.ok(missingTargetMessages.some((message) =>
+    /bitfun-runtime-ports managed target.*missing/.test(message)));
+
+  const runtimePorts = capabilityPackage(
+    'bitfun-runtime-ports',
+    'src/crates/contracts/runtime-ports/Cargo.toml',
+    RUNTIME_PORT_FEATURE_PROFILES,
+  );
+  reviewedConsumer.dependencies[0] = {
+    ...reviewedConsumer.dependencies[0],
+    path: null,
+    source: 'registry+https://github.com/rust-lang/crates.io-index',
+  };
+  const spoofedTargetMessages = findTestCapabilityViolations(
+    findCapabilityContractConsumerViolations,
+    [runtimePorts, reviewedConsumer],
+  ).map((violation) => violation.message);
+  assert.ok(spoofedTargetMessages.some((message) => /managed internal path/.test(message)));
+
+  const vendorRuntimePorts = {
+    ...runtimePorts,
+    manifest_path: join(
+      TEST_ROOT,
+      'vendor',
+      'src',
+      'crates',
+      'contracts',
+      'runtime-ports',
+      'Cargo.toml',
+    ),
+  };
+  reviewedConsumer.dependencies[0] = {
+    ...reviewedConsumer.dependencies[0],
+    path: join(TEST_ROOT, 'vendor', 'src', 'crates', 'contracts', 'runtime-ports'),
+    source: null,
+  };
+  const vendorTargetMessages = findCapabilityContractConsumerViolations(
+    [vendorRuntimePorts, reviewedConsumer],
+    [capabilityContractDependencyRules[0]],
+    { root: TEST_ROOT },
+  ).map((violation) => violation.message);
+  assert.ok(vendorTargetMessages.some((message) => /managed target.*missing/.test(message)));
+});
+
+test('capability contract target feature graphs stay exact', async () => {
+  const { findCapabilityContractConsumerViolations } = await import(
+    './core-boundaries/cargo-dependency-boundaries.mjs'
+  );
+  const runtimePorts = capabilityPackage(
+    'bitfun-runtime-ports',
+    'src/crates/contracts/runtime-ports/Cargo.toml',
+    RUNTIME_PORT_FEATURE_PROFILES,
+  );
+  runtimePorts.features['git-port'] = ['plugin-runtime'];
+
+  const messages = findTestCapabilityViolations(
+    findCapabilityContractConsumerViolations,
+    [runtimePorts],
+  ).map(
+    (violation) => violation.message,
+  );
+  assert.ok(messages.some((message) => /git-port.*feature graph must stay exact/.test(message)));
+});
+
+test('unreviewed local feature aliases cannot wrap reviewed capability owners', async () => {
+  const { findCapabilityContractConsumerViolations } = await import(
+    './core-boundaries/cargo-dependency-boundaries.mjs'
+  );
+  const agentTools = agentToolsCapabilityPackage();
+  const acp = {
+    ...packageAt(
+      'bitfun-acp',
+      'src/crates/interfaces/acp/Cargo.toml',
+      [pathDependency('src/crates/execution/tool-contracts', {
+        name: 'bitfun-agent-tools',
+        optional: true,
+        usesDefaultFeatures: false,
+      })],
+    ),
+    features: {
+      default: ['client', 'server'],
+      client: ['bitfun-agent-tools/acp-bridge'],
+      server: ['dep:bitfun-agent-tools'],
+      sneakyClient: ['client'],
+      sneakyServer: ['server'],
+    },
+  };
+
+  const messages = findTestCapabilityViolations(
+    findCapabilityContractConsumerViolations,
+    [agentTools, acp],
+  ).map(
+    (violation) => violation.message,
+  );
+  assert.ok(messages.some((message) => /sneakyClient.*unreviewed.*aggregate/.test(message)));
+  assert.ok(messages.some((message) => /sneakyServer.*unreviewed.*aggregate/.test(message)));
+  assert.doesNotMatch(messages.join('\n'), /default.*unreviewed.*aggregate/);
+});
+
+test('capability contract consumers cannot remove reviewed dependency edges', async () => {
+  const { findCapabilityContractConsumerViolations } = await import(
+    './core-boundaries/cargo-dependency-boundaries.mjs'
+  );
+  const runtimePorts = capabilityPackage(
+    'bitfun-runtime-ports',
+    'src/crates/contracts/runtime-ports/Cargo.toml',
+    RUNTIME_PORT_FEATURE_PROFILES,
+  );
+  const pluginRuntimeClient = packageAt(
+    'bitfun-plugin-runtime-client',
+    'src/crates/execution/plugin-runtime-client/Cargo.toml',
+  );
+  const opencodeAdapter = packageAt(
+    'bitfun-opencode-adapter',
+    'src/crates/adapters/opencode-adapter/Cargo.toml',
+    [pathDependency('src/crates/contracts/runtime-ports', {
+      name: 'bitfun-runtime-ports',
+      usesDefaultFeatures: false,
+      features: ['plugin-runtime'],
+    })],
+  );
+
+  const messages = findTestCapabilityViolations(findCapabilityContractConsumerViolations, [
+    runtimePorts,
+    pluginRuntimeClient,
+    opencodeAdapter,
+  ]).map((violation) => violation.message);
+  assert.ok(messages.some((message) => /bitfun-plugin-runtime-client.*missing reviewed.*normal.*edge/.test(message)));
+  assert.ok(messages.some((message) => /bitfun-opencode-adapter.*missing reviewed.*dev.*edge/.test(message)));
+});
diff --git a/scripts/check-github-config.test.mjs b/scripts/check-github-config.test.mjs
index c53371815e..7ea018e46a 100644
--- a/scripts/check-github-config.test.mjs
+++ b/scripts/check-github-config.test.mjs
@@ -251,6 +251,56 @@ test('keeps Rust CI independent, restore-only on PRs, and target-focused', () =>
     assert.equal(cache?.with?.['cache-on-failure'], trustedMain);
   }
 
+  const rustCache = rustJob.steps.find((step) =>
+    step.uses?.startsWith('swatinem/rust-cache@'),
+  );
+  assert.equal(
+    rustCache?.with?.['cache-directories'],
+    undefined,
+    'Rust cache cleanup must not own native libraries stored under target',
+  );
+
+  const restoreSherpaCache = rustJob.steps.find(
+    (step) => step.name === 'Restore Sherpa native libraries',
+  );
+  const repairSherpaState = rustJob.steps.find(
+    (step) => step.name === 'Repair missing Sherpa native state',
+  );
+  const checkCompilation = rustJob.steps.find(
+    (step) => step.name === 'Check compilation',
+  );
+  const saveSherpaCache = rustJob.steps.find(
+    (step) => step.name === 'Save Sherpa native libraries',
+  );
+  const sherpaCacheKey =
+    'sherpa-onnx-v1-${{ runner.os }}-${{ runner.arch }}-1.13.4-static';
+
+  assert.equal(restoreSherpaCache?.uses, 'actions/cache/restore@v5');
+  assert.equal(restoreSherpaCache?.with?.path, 'target/sherpa-onnx-prebuilt');
+  assert.equal(restoreSherpaCache?.with?.key, sherpaCacheKey);
+  assert.match(
+    repairSherpaState?.run ?? '',
+    /rm -rf target\/sherpa-onnx-prebuilt/,
+  );
+  assert.match(repairSherpaState?.run ?? '', /cargo clean -p sherpa-onnx-sys/);
+  assert.equal(saveSherpaCache?.uses, 'actions/cache/save@v5');
+  assert.equal(saveSherpaCache?.with?.path, 'target/sherpa-onnx-prebuilt');
+  assert.equal(saveSherpaCache?.with?.key, sherpaCacheKey);
+  assert.equal(
+    saveSherpaCache?.if,
+    "github.event_name == 'push' && github.ref == 'refs/heads/main' && steps.sherpa-native-cache.outputs.cache-hit != 'true'",
+  );
+  assert.ok(
+    rustJob.steps.indexOf(restoreSherpaCache) <
+      rustJob.steps.indexOf(checkCompilation),
+    'Sherpa native libraries must be restored before cargo check',
+  );
+  assert.ok(
+    rustJob.steps.indexOf(checkCompilation) <
+      rustJob.steps.indexOf(saveSherpaCache),
+    'Sherpa native libraries must be saved before rust-cache post cleanup',
+  );
+
   const commandByStep = new Map(
     rustJob.steps.map((step) => [step.name, step.run]),
   );
@@ -327,22 +377,169 @@ test('stages unique release asset names before publishing', () => {
     ),
   );
   const steps = workflow.jobs['upload-release-assets'].steps;
-  const stagingIndex = steps.findIndex(
-    (step) => step.name === 'Stage uniquely named release assets',
-  );
+  const stagingIndexes = [
+    steps.findIndex((step) => step.name === 'Stage stable release assets'),
+    steps.findIndex((step) => step.name === 'Stage beta release assets'),
+  ];
   const uploadIndex = steps.findIndex((step) => step.name === 'Upload to release');
 
-  assert.notEqual(stagingIndex, -1);
+  assert.equal(stagingIndexes.every((index) => index >= 0), true);
   assert.notEqual(uploadIndex, -1);
-  assert.ok(stagingIndex < uploadIndex);
+  for (const stagingIndex of stagingIndexes) {
+    assert.ok(stagingIndex < uploadIndex);
+    assert.match(
+      steps[stagingIndex].run,
+      /node scripts\/stage-github-release-assets\.mjs/,
+    );
+    assert.doesNotMatch(
+      steps[stagingIndex].run,
+      /release-assets\/\*\*\/\*\.sig(?:\s|\\)/,
+      'raw updater signatures have colliding names across macOS architectures',
+    );
+  }
+  assert.equal(steps[uploadIndex].with.files, 'release-upload-assets/*');
+});
+
+test('Desktop packaging keeps beta identity explicit and stable-safe', () => {
+  const workflow = yaml.parse(
+    readFileSync(
+      path.join(repoRoot, '.github/workflows/desktop-package.yml'),
+      'utf8',
+    ),
+  );
+  const inputs = workflow.on.workflow_dispatch.inputs;
+  assert.deepEqual(inputs.release_channel.options, ['stable', 'beta']);
+  assert.equal(inputs.release_channel.default, 'stable');
+
+  const prepareStep = workflow.jobs.prepare.steps.find(
+    (step) => step.name === 'Resolve version metadata',
+  );
+  assert.match(prepareStep.run, /GITHUB_REPOSITORY.*GCWing\/BitFun/);
+  assert.match(prepareStep.run, /merge-base --is-ancestor/);
+  assert.match(prepareStep.run, /rev-parse --verify --quiet/);
+
+  const packageJob = workflow.jobs.package;
+  assert.equal(
+    packageJob.env.BITFUN_RELEASE_CHANNEL,
+    '${{ needs.prepare.outputs.release_channel }}',
+  );
+  assert.match(packageJob.env.TAURI_UPDATER_ENDPOINT, /github\.repository/);
+  assert.match(packageJob.env.TAURI_UPDATER_ENDPOINT, /channel-beta/);
+  assert.match(packageJob.env.BITFUN_RELEASE_PUBKEY, /BITFUN_RELEASE_PUBKEY/);
+  const appleSetupIndex = packageJob.steps.findIndex(
+    (step) => step.name === 'Configure Apple Developer ID signing and notarization',
+  );
+  const desktopBuildIndex = packageJob.steps.findIndex(
+    (step) => step.name === 'Build desktop app',
+  );
+  const appleVerifyIndex = packageJob.steps.findIndex(
+    (step) => step.name === 'Verify Apple signature and notarization',
+  );
+  assert.ok(
+    appleSetupIndex >= 0 &&
+      appleSetupIndex < desktopBuildIndex &&
+      desktopBuildIndex < appleVerifyIndex,
+    'Apple credentials must be configured before packaging and verified afterwards',
+  );
+  assert.equal(packageJob.steps[appleSetupIndex].if, "runner.os == 'macOS'");
+  assert.equal(
+    packageJob.steps[appleSetupIndex].env.BITFUN_REQUIRE_APPLE_SIGNING,
+    '${{ needs.prepare.outputs.upload_to_release }}',
+  );
+  assert.equal(packageJob.steps[appleVerifyIndex].if, "runner.os == 'macOS'");
+  const patchIndex = packageJob.steps.findIndex(
+    (step) => step.name === 'Project beta build version',
+  );
+  const verifyIndex = packageJob.steps.findIndex(
+    (step) => step.name === 'Verify release version metadata',
+  );
+  assert.ok(patchIndex >= 0 && patchIndex < verifyIndex);
+  assert.equal(
+    packageJob.steps[patchIndex].if,
+    "needs.prepare.outputs.release_channel == 'beta'",
+  );
+
+  const uploadSteps = workflow.jobs['upload-release-assets'].steps;
+  const release = uploadSteps.find((step) => step.name === 'Upload to release');
+  assert.equal(
+    release.with.prerelease,
+    "${{ needs.prepare.outputs.release_channel == 'beta' }}",
+  );
+  const verifyIndexPublished = uploadSteps.findIndex(
+    (step) => step.name === 'Verify published updater manifest',
+  );
+  const promoteIndex = uploadSteps.findIndex(
+    (step) => step.name === 'Publish beta channel manifest',
+  );
+  assert.ok(verifyIndexPublished >= 0 && verifyIndexPublished < promoteIndex);
+  assert.match(workflow.jobs['linux-binaries'].if, /release_channel == 'stable'/);
+  assert.equal(
+    uploadSteps.find((step) => step.name === 'Stage beta release assets').if,
+    "needs.prepare.outputs.release_channel == 'beta'",
+  );
   assert.match(
-    steps[stagingIndex].run,
-    /node scripts\/stage-github-release-assets\.mjs/,
+    uploadSteps.find((step) => step.name === 'Generate updater manifest').run,
+    /github\.repository/,
   );
-  assert.doesNotMatch(
-    steps[stagingIndex].run,
-    /release-assets\/\*\*\/\*\.sig(?:\s|\\)/,
-    'raw updater signatures have colliding names across macOS architectures',
+  const signingStep = uploadSteps.find(
+    (step) => step.name === 'Sign installer packages',
   );
-  assert.equal(steps[uploadIndex].with.files, 'release-upload-assets/*');
+  assert.match(signingStep.run, /write-minisign-public-key\.mjs/);
+  assert.doesNotMatch(signingStep.run, /BITFUN_SIGNING_PUBKEY.*base64 -d/);
+  const promotionStep = uploadSteps.find(
+    (step) => step.name === 'Resolve beta channel promotion',
+  );
+  assert.doesNotMatch(promotionStep.run, /current\.beta\.json \|\| true/);
+  assert.match(promotionStep.run, /case "\$\{channel_status\}" in/);
+  assert.match(promotionStep.run, /404\)/);
+  assert.match(promotionStep.run, /GitHub API returned/);
+  const publishStep = uploadSteps.find(
+    (step) => step.name === 'Publish beta channel manifest',
+  );
+  assert.equal(
+    publishStep.env.CHANNEL_EXISTS,
+    '${{ steps.beta-channel.outputs.channel_exists }}',
+  );
+});
+
+test('beta publishing cannot advance the Relay latest image tag', () => {
+  const workflow = yaml.parse(
+    readFileSync(
+      path.join(repoRoot, '.github/workflows/desktop-package.yml'),
+      'utf8',
+    ),
+  );
+  const imageTags = workflow.jobs['publish-relay-image'].steps.find(
+    (step) => step.name === 'Resolve image tags',
+  );
+  assert.equal(
+    imageTags.env.RELEASE_CHANNEL,
+    '${{ needs.prepare.outputs.release_channel }}',
+  );
+  assert.match(imageTags.run, /RELEASE_CHANNEL.*stable/);
+  assert.doesNotMatch(imageTags.run, /RELEASE_PRERELEASE/);
+});
+
+test('nightly and beta use the shared build-version projection', () => {
+  const nightly = yaml.parse(
+    readFileSync(path.join(repoRoot, '.github/workflows/nightly.yml'), 'utf8'),
+  );
+  const patch = nightly.jobs.package.steps.find(
+    (step) => step.name === 'Patch nightly version',
+  );
+  assert.match(patch.run, /node scripts\/set-build-version\.mjs/);
+  assert.equal(nightly.jobs.package.env.BITFUN_RELEASE_CHANNEL, 'nightly');
+  assert.equal(
+    nightly.jobs.package.env.TAURI_UPDATER_ENDPOINT,
+    'https://github.com/GCWing/BitFun/releases/latest/download/latest.json',
+  );
+  assert.equal(
+    nightly.jobs.package.env.TAURI_UPDATER_FALLBACK_ENDPOINT,
+    'https://openbitfun.com/release/latest.json',
+  );
+  assert.equal(nightly.jobs.package.env.BITFUN_ENABLE_UPDATER_ARTIFACTS, undefined);
+  const signingStep = nightly.jobs['publish-nightly'].steps.find(
+    (step) => step.name === 'Sign installer packages',
+  );
+  assert.match(signingStep.run, /write-minisign-public-key\.mjs/);
 });
diff --git a/scripts/check-harmonyos-architecture.mjs b/scripts/check-harmonyos-architecture.mjs
index 2ccdeff49b..a6be6621b4 100644
--- a/scripts/check-harmonyos-architecture.mjs
+++ b/scripts/check-harmonyos-architecture.mjs
@@ -44,6 +44,7 @@ const allPages = filesUnder(pagesRoot);
 const services = filesUnder(path.join(etsRoot, 'services'));
 const components = allPages.filter((file) => file.includes(`${path.sep}pages${path.sep}components${path.sep}`));
 const viewmodels = allPages.filter((file) => file.includes(`${path.sep}pages${path.sep}viewmodel${path.sep}`));
+const stateFiles = allPages.filter((file) => file.includes(`${path.sep}pages${path.sep}state${path.sep}`));
 
 const serviceToPages = services
   .filter((file) => imports(file).some((spec) => spec === 'pages' || spec.startsWith('pages/')))
@@ -54,6 +55,9 @@ const componentToViewmodel = components
 const viewmodelToComponents = viewmodels
   .filter((file) => imports(file).some((spec) => spec === 'pages/components' || spec.startsWith('pages/components/')))
   .map(relative);
+const stateToComponents = stateFiles
+  .filter((file) => imports(file).some((spec) => spec === 'pages/components' || spec.startsWith('pages/components/')))
+  .map(relative);
 const v1Components = allPages
   .filter((file) => /^\s*@Component\s*$/m.test(fs.readFileSync(file, 'utf8')))
   .map(relative);
@@ -98,10 +102,16 @@ const requiredPresentationFiles = [
   'components/AppRootOverlaySurfaces.ets',
   'components/ChatMessageChrome.ets',
   'components/ConnectManualPairingOverlay.ets',
+  'components/ConversationHeader.ets',
   'components/ConversationRouteSurface.ets',
   'components/ToolInteractionPanels.ets',
   'components/WideConversationHost.ets',
-  'components/remote/RemoteSurfaceHost.ets'
+  'components/remote/RemoteSurfaceHost.ets',
+  'policy/ConversationHeaderPolicy.ets',
+  'viewmodel/ConversationRuntime.ets',
+  'viewmodel/RemoteTranscriptController.ets',
+  'viewmodel/RemoteCreateFlowController.ets',
+  'viewmodel/VisibleConversationController.ets'
 ];
 const missingPresentationFiles = requiredPresentationFiles
   .filter((file) => !fs.existsSync(path.join(pagesRoot, file)));
@@ -132,7 +142,6 @@ const extractedCloudAccountMethods = [
   'loginCloudAccount',
   'restoreCloudAccountSession',
   'loadGeneralChatAccountModels',
-  'syncCloudAccount',
   'applyCloudAccountSession',
   'logoutCloudAccount',
   'listCloudAccountDevices',
@@ -269,6 +278,7 @@ const expected = {
   serviceToPages: [],
   componentToViewmodel: [],
   viewmodelToComponents: [],
+  stateToComponents: [],
   v1Components: [],
   positionalActionConstructors: [],
   duplicatedConversationTraceFields: [],
@@ -293,6 +303,7 @@ const actual = {
   serviceToPages,
   componentToViewmodel,
   viewmodelToComponents,
+  stateToComponents,
   v1Components,
   positionalActionConstructors,
   duplicatedConversationTraceFields,
@@ -325,6 +336,12 @@ if (appRootPresentationLines > 500) {
   failed = true;
   console.error(`AppRootPresentation line budget exceeded: expected <=500, actual=${appRootPresentationLines}`);
 }
+const conversationControllerFile = path.join(pagesRoot, 'viewmodel/ConversationController.ets');
+const conversationControllerLines = fs.readFileSync(conversationControllerFile, 'utf8').split(/\r?\n/).length - 1;
+if (conversationControllerLines > 400) {
+  failed = true;
+  console.error(`ConversationController line budget exceeded: expected <=400, actual=${conversationControllerLines}`);
+}
 for (const [file, budget] of componentLineBudgets) {
   const source = fs.readFileSync(path.join(pagesRoot, file), 'utf8');
   const lineCount = source.split(/\r?\n/).length - 1;
diff --git a/scripts/ci/setup-macos-signing.sh b/scripts/ci/setup-macos-signing.sh
new file mode 100755
index 0000000000..17264e4b36
--- /dev/null
+++ b/scripts/ci/setup-macos-signing.sh
@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+required=(
+  APPLE_CERTIFICATE
+  APPLE_CERTIFICATE_PASSWORD
+  APPLE_SIGNING_IDENTITY
+  APPLE_API_ISSUER
+  APPLE_API_KEY
+  APPLE_API_PRIVATE_KEY
+  KEYCHAIN_PASSWORD
+)
+
+missing=()
+for name in "${required[@]}"; do
+  if [[ -z "${!name:-}" ]]; then
+    missing+=("${name}")
+  fi
+done
+
+if [[ "${#missing[@]}" -gt 0 ]]; then
+  if [[ "${BITFUN_REQUIRE_APPLE_SIGNING:-false}" == "true" ]]; then
+    printf 'Apple signing is required, but these secrets are missing: %s\n' "${missing[*]}" >&2
+    exit 1
+  fi
+  printf 'Apple signing is not fully configured; leaving this non-release macOS build unsigned. Missing: %s\n' "${missing[*]}"
+  exit 0
+fi
+
+signing_dir="${RUNNER_TEMP}/bitfun-apple-signing"
+certificate_path="${signing_dir}/developer-id.p12"
+api_key_path="${signing_dir}/AuthKey_${APPLE_API_KEY}.p8"
+keychain_path="${RUNNER_TEMP}/bitfun-signing.keychain-db"
+
+mkdir -p "${signing_dir}"
+chmod 700 "${signing_dir}"
+printf '%s' "${APPLE_CERTIFICATE}" | base64 --decode >"${certificate_path}"
+printf '%s' "${APPLE_API_PRIVATE_KEY}" >"${api_key_path}"
+chmod 600 "${certificate_path}" "${api_key_path}"
+
+security create-keychain -p "${KEYCHAIN_PASSWORD}" "${keychain_path}"
+security set-keychain-settings -lut 21600 "${keychain_path}"
+security unlock-keychain -p "${KEYCHAIN_PASSWORD}" "${keychain_path}"
+security import "${certificate_path}" \
+  -k "${keychain_path}" \
+  -P "${APPLE_CERTIFICATE_PASSWORD}" \
+  -T /usr/bin/codesign \
+  -T /usr/bin/security
+security set-key-partition-list \
+  -S apple-tool:,apple:,codesign: \
+  -s \
+  -k "${KEYCHAIN_PASSWORD}" \
+  "${keychain_path}"
+
+curl --fail --location --silent --show-error \
+  'https://www.apple.com/certificateauthority/DeveloperIDG2CA.cer' \
+  --output "${signing_dir}/DeveloperIDG2CA.cer"
+security import "${signing_dir}/DeveloperIDG2CA.cer" -k "${keychain_path}"
+
+security list-keychains -d user -s "${keychain_path}" "${HOME}/Library/Keychains/login.keychain-db"
+security default-keychain -d user -s "${keychain_path}"
+security find-identity -v -p codesigning "${keychain_path}"
+
+if ! security find-identity -v -p codesigning "${keychain_path}" | grep -Fq "${APPLE_SIGNING_IDENTITY}"; then
+  echo "The imported certificate does not provide ${APPLE_SIGNING_IDENTITY}." >&2
+  exit 1
+fi
+
+{
+  echo "APPLE_API_ISSUER=${APPLE_API_ISSUER}"
+  echo "APPLE_API_KEY=${APPLE_API_KEY}"
+  echo "APPLE_API_KEY_PATH=${api_key_path}"
+  echo "APPLE_SIGNING_IDENTITY=${APPLE_SIGNING_IDENTITY}"
+  echo "BITFUN_APPLE_SIGNING_CONFIGURED=true"
+} >>"${GITHUB_ENV}"
+
+echo "Apple Developer ID signing and notarization credentials are ready."
diff --git a/scripts/ci/verify-macos-signing.sh b/scripts/ci/verify-macos-signing.sh
new file mode 100755
index 0000000000..4513fa57a5
--- /dev/null
+++ b/scripts/ci/verify-macos-signing.sh
@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+target="${1:?usage: verify-macos-signing.sh <target-triple>}"
+if [[ "${BITFUN_APPLE_SIGNING_CONFIGURED:-false}" != "true" ]]; then
+  echo "Apple signing is not configured; skipping macOS signature verification."
+  exit 0
+fi
+
+bundle_dir="target/${target}/release/bundle"
+
+shopt -s nullglob
+apps=("${bundle_dir}/macos/"*.app)
+dmgs=("${bundle_dir}/dmg/"*.dmg)
+
+if [[ "${#apps[@]}" -eq 0 || "${#dmgs[@]}" -eq 0 ]]; then
+  echo "Expected one or more macOS app and DMG bundles under ${bundle_dir}." >&2
+  exit 1
+fi
+
+for app in "${apps[@]}"; do
+  codesign --verify --deep --strict --verbose=2 "${app}"
+  while IFS= read -r -d '' candidate; do
+    if ! file -b "${candidate}" | grep -q 'Mach-O'; then
+      continue
+    fi
+    signature_details="$(codesign -dv --verbose=4 "${candidate}" 2>&1)"
+    grep -Fq 'Authority=Developer ID Application:' <<<"${signature_details}"
+    grep -Eq 'flags=.*\(runtime\)' <<<"${signature_details}"
+    grep -Fq 'Timestamp=' <<<"${signature_details}"
+  done < <(find "${app}" -type f -print0)
+  xcrun stapler validate "${app}"
+  spctl --assess --type execute --verbose=4 "${app}"
+done
+
+for dmg in "${dmgs[@]}"; do
+  xcrun notarytool submit "${dmg}" \
+    --issuer "${APPLE_API_ISSUER}" \
+    --key-id "${APPLE_API_KEY}" \
+    --key "${APPLE_API_KEY_PATH}" \
+    --wait
+  xcrun stapler staple "${dmg}"
+  xcrun stapler validate "${dmg}"
+  spctl --assess --type open --context context:primary-signature --verbose=4 "${dmg}"
+done
+
+echo "Verified Developer ID signatures, notarization tickets, and Gatekeeper acceptance."
diff --git a/scripts/core-boundaries/cargo-dependency-boundaries.mjs b/scripts/core-boundaries/cargo-dependency-boundaries.mjs
index b76ccc00ae..523c3ab192 100644
--- a/scripts/core-boundaries/cargo-dependency-boundaries.mjs
+++ b/scripts/core-boundaries/cargo-dependency-boundaries.mjs
@@ -2,7 +2,13 @@ import { readFileSync, readdirSync } from 'node:fs';
 import { isAbsolute, join, relative, resolve } from 'node:path';
 import { spawnSync } from 'node:child_process';
 
-import { servicesReqwestOwnerFeatures } from './rules/feature-rules.mjs';
+import {
+  acpClientCoreFeatures,
+  acpServerCoreFeatures,
+  capabilityContractDependencyRules,
+  guardedEmptyInternalDefaultManifestPaths,
+  servicesReqwestOwnerFeatures,
+} from './rules/feature-rules.mjs';
 
 const SKIPPED_DIRECTORIES = new Set([
   '.git',
@@ -127,7 +133,7 @@ const SERVICES_INTEGRATIONS_TOKIO_FEATURES = new Map([
   ['browser-control', ['time']],
   ['canvas-runtime', ['fs']],
   ['debug-log', ['rt']],
-  ['deep-research', ['fs']],
+  ['deep-research', []],
   ['git', ['fs', 'io-util', 'macros', 'rt', 'time']],
   ['file-watch', ['rt', 'sync']],
   ['function-agents', ['fs', 'io-util', 'macros', 'rt', 'time']],
@@ -146,18 +152,46 @@ const SERVICES_INTEGRATIONS_TOKIO_FEATURES = new Map([
 ]);
 
 const SERVICES_CORE_TOKIO_FEATURES = new Map([
-  ['filesystem', ['fs']],
-  ['json-io', ['fs', 'sync']],
-  ['local-storage', ['fs', 'sync']],
-  ['process-runtime', ['io-util', 'process']],
-  ['workspace-instructions', ['fs', 'io-util']],
-  ['lsp', ['fs', 'io-util', 'process', 'sync']],
-  ['workspace-runtime', ['fs', 'io-util', 'process', 'sync']],
+  ['diff', ['rt', 'time']],
+  ['filesystem', ['fs', 'rt']],
+  ['json-io', ['fs', 'rt', 'sync', 'time']],
+  ['local-storage', ['fs', 'rt', 'sync', 'time']],
+  ['permission', ['rt']],
+  ['process-runtime', ['io-util', 'process', 'rt', 'time']],
+  ['workspace-instructions', ['fs', 'io-util', 'rt']],
+  ['workspace-text-runtime', ['rt']],
+  ['lsp', ['fs', 'io-util', 'process', 'rt', 'sync', 'time']],
+  ['workspace-runtime', ['fs', 'io-util', 'process', 'rt', 'sync', 'time']],
+]);
+const SERVICES_CORE_BASE_TOKIO_FEATURES = [];
+const SERVICES_INTEGRATIONS_TOKIO_AGGREGATES = new Set(['product-full']);
+const SERVICES_CORE_TOKIO_AGGREGATES = new Set(['session-git']);
+const CORE_TOKIO_FEATURES = new Map([
+  ['agent-runtime', ['io-util', 'macros', 'rt', 'time']],
+  ['mcp-runtime', ['io-util', 'macros', 'rt', 'rt-multi-thread', 'time']],
+  ['browser-control', ['net', 'rt', 'time']],
+  ['debug-log', ['macros', 'net', 'rt', 'time']],
+  ['lsp', ['macros']],
+]);
+const CORE_TOKIO_AGGREGATES = new Set([
+  'external-sources',
+  'plugin-runtime',
+  'product-full',
+  'remote-connect',
+  'tools-browser-web',
+  'tools-mcp',
+]);
+const AGENT_RUNTIME_TOKIO_FEATURES = new Map([
+  ['native-hook-runtime', ['io-util', 'macros', 'process', 'rt', 'time']],
+  ['agent-runtime', ['io-util', 'macros', 'process', 'rt', 'sync', 'time']],
 ]);
-const SERVICES_CORE_BASE_TOKIO_FEATURES = ['rt', 'time'];
 
 const TOKIO_DEPENDENCY_POLICY_EXCLUDED_PACKAGES = new Set();
 
+function tokioCapabilityReference(value) {
+  return value.match(/^tokio\??\/(.+)$/)?.[1];
+}
+
 function effectiveTokioCapabilities(feature, featureGraph, visiting = new Set()) {
   if (visiting.has(feature)) {
     return new Set();
@@ -166,8 +200,9 @@ function effectiveTokioCapabilities(feature, featureGraph, visiting = new Set())
 
   const capabilities = new Set();
   for (const value of featureGraph[feature] ?? []) {
-    if (value.startsWith('tokio/')) {
-      capabilities.add(value.slice('tokio/'.length));
+    const capability = tokioCapabilityReference(value);
+    if (capability) {
+      capabilities.add(capability);
     } else if (Object.hasOwn(featureGraph, value)) {
       for (const capability of effectiveTokioCapabilities(value, featureGraph, visiting)) {
         capabilities.add(capability);
@@ -179,7 +214,7 @@ function effectiveTokioCapabilities(feature, featureGraph, visiting = new Set())
   return capabilities;
 }
 
-function findOwnedTokioFeatureViolations(pkg, ownerProfiles) {
+function findOwnedTokioFeatureViolations(pkg, ownerProfiles, aggregateFeatures = new Set()) {
   const violations = [];
   const featureGraph = pkg.features ?? {};
 
@@ -217,7 +252,17 @@ function findOwnedTokioFeatureViolations(pkg, ownerProfiles) {
     if (ownerProfiles.has(feature)) {
       continue;
     }
-    if (values.some((value) => value.startsWith('tokio/'))) {
+    if (aggregateFeatures.has(feature)) {
+      if (values.some((value) => tokioCapabilityReference(value))) {
+        violations.push({
+          path: pkg.manifest_path,
+          line: 1,
+          message: `${pkg.name}:${feature} Tokio aggregate must compose reviewed owners instead of declaring Tokio capabilities directly`,
+        });
+      }
+      continue;
+    }
+    if (effectiveTokioCapabilities(feature, featureGraph).size > 0) {
       violations.push({
         path: pkg.manifest_path,
         line: 1,
@@ -230,7 +275,11 @@ function findOwnedTokioFeatureViolations(pkg, ownerProfiles) {
 }
 
 export function findServicesIntegrationsTokioFeatureViolations(pkg) {
-  return findOwnedTokioFeatureViolations(pkg, SERVICES_INTEGRATIONS_TOKIO_FEATURES);
+  return findOwnedTokioFeatureViolations(
+    pkg,
+    SERVICES_INTEGRATIONS_TOKIO_FEATURES,
+    SERVICES_INTEGRATIONS_TOKIO_AGGREGATES,
+  );
 }
 
 function reqwestDependencyFeatureReferences(references) {
@@ -243,36 +292,37 @@ function reqwestDependencyFeatureReferences(references) {
   );
 }
 
-const REQWEST_TRANSPORT_FEATURES = [
-  'form',
-  'http2',
-  'json',
-  'multipart',
-  'query',
-  'stream',
-];
 const REQWEST_PACKAGE_PROFILES = new Map([
-  ['bitfun-core', { dependencyFeatures: REQWEST_TRANSPORT_FEATURES, optional: true }],
+  ['bitfun-core', { dependencyFeatures: [], optional: true }],
   ['bitfun-services-integrations', {
-    dependencyFeatures: REQWEST_TRANSPORT_FEATURES,
+    dependencyFeatures: ['http2'],
     optional: true,
     servicesOwners: true,
   }],
   ['bitfun-ai-adapters', {
-    dependencyFeatures: [...REQWEST_TRANSPORT_FEATURES, 'rustls', 'socks'],
+    dependencyFeatures: ['http2', 'json', 'rustls', 'socks', 'stream'],
+    optional: false,
+    allowedPackageFeatureRefs: new Set(['reqwest/form']),
+    requiredPackageFeatureRefs: new Map([
+      ['subscription-auth', new Set(['reqwest/form'])],
+    ]),
+  }],
+  ['bitfun-cli', {
+    dependencyFeatures: ['http2', 'rustls', 'stream'],
+    optional: false,
+  }],
+  ['bitfun-desktop', {
+    dependencyFeatures: ['http2', 'json', 'query', 'rustls', 'stream'],
+    optional: false,
+  }],
+  ['bitfun-miniapp-market-service', {
+    dependencyFeatures: ['form', 'http2', 'json', 'rustls'],
     optional: false,
-    allowedPackageFeatureRefs: new Set(['reqwest/rustls']),
   }],
-  ...[
-    'bitfun-cli',
-    'bitfun-desktop',
-    'bitfun-miniapp-market-service',
-    'bitfun-skin-market-service',
-  ].map((packageName) => [packageName, {
-    dependencyFeatures: [...REQWEST_TRANSPORT_FEATURES, 'rustls'],
+  ['bitfun-skin-market-service', {
+    dependencyFeatures: ['http2', 'json', 'rustls'],
     optional: false,
-    allowedPackageFeatureRefs: new Set(['reqwest/rustls']),
-  }]),
+  }],
 ]);
 
 function findReqwestPackageProfileViolations(pkg, profile) {
@@ -356,6 +406,18 @@ function findReqwestPackageProfileViolations(pkg, profile) {
         }
       }
     }
+    for (const [featureName, requiredReferences] of profile.requiredPackageFeatureRefs ?? []) {
+      const actualReferences = new Set(pkg.features?.[featureName] ?? []);
+      for (const reference of requiredReferences) {
+        if (!actualReferences.has(reference)) {
+          violations.push({
+            path: pkg.manifest_path,
+            line: 1,
+            message: `${pkg.name}:${featureName} is missing Reqwest feature reference ${reference}`,
+          });
+        }
+      }
+    }
   }
 
   return violations;
@@ -511,6 +573,20 @@ export function findServicesIntegrationsReqwestFeatureViolations(pkg) {
   const violations = [];
   const featureGraph = pkg.features ?? {};
   const ownerFeatures = new Set(servicesReqwestOwnerFeatures);
+  const ownerFeatureReferences = new Map([
+    ['announcement', ['reqwest/json']],
+    ['browser-control', ['reqwest/json']],
+    ['debug-log', ['reqwest/json']],
+    ['mcp', ['reqwest/json', 'reqwest/stream']],
+    ['miniapp-market', ['reqwest/json', 'reqwest/query', 'reqwest/stream']],
+    ['miniapp-runtime', ['reqwest/stream']],
+    ['models-dev', ['reqwest/system-proxy']],
+    ['remote-connect', ['reqwest/json', 'reqwest/multipart', 'reqwest/query']],
+    ['remote-ssh-concrete', ['reqwest/stream']],
+    ['review-platform', ['reqwest/json', 'reqwest/query', 'reqwest/stream']],
+    ['speech', ['reqwest/stream']],
+    ['web-tools', ['reqwest/json']],
+  ]);
 
   for (const featureName of servicesReqwestOwnerFeatures) {
     const references = featureGraph[featureName];
@@ -536,6 +612,15 @@ export function findServicesIntegrationsReqwestFeatureViolations(pkg) {
         message: `${pkg.name}:${featureName} is missing reqwest/rustls`,
       });
     }
+    for (const reference of ownerFeatureReferences.get(featureName) ?? []) {
+      if (!references.includes(reference)) {
+        violations.push({
+          path: pkg.manifest_path,
+          line: 1,
+          message: `${pkg.name}:${featureName} is missing Reqwest feature reference ${reference}`,
+        });
+      }
+    }
   }
 
   for (const [featureName, references] of Object.entries(featureGraph)) {
@@ -556,12 +641,15 @@ export function findServicesIntegrationsReqwestFeatureViolations(pkg) {
       });
       continue;
     }
+    const allowedReferences = new Set([
+      'reqwest',
+      'dep:reqwest',
+      'reqwest/rustls',
+      ...(ownerFeatureReferences.get(featureName) ?? []),
+    ]);
     for (const reference of reqwestReferences) {
       if (
-        reference !== 'reqwest'
-        && reference !== 'dep:reqwest'
-        && reference !== 'reqwest/rustls'
-        && !(featureName === 'models-dev' && reference === 'reqwest/system-proxy')
+        !allowedReferences.has(reference)
       ) {
         violations.push({
           path: pkg.manifest_path,
@@ -578,7 +666,11 @@ export function findServicesIntegrationsReqwestFeatureViolations(pkg) {
 
 
 export function findServicesCoreTokioFeatureViolations(pkg) {
-  return findOwnedTokioFeatureViolations(pkg, SERVICES_CORE_TOKIO_FEATURES);
+  return findOwnedTokioFeatureViolations(
+    pkg,
+    SERVICES_CORE_TOKIO_FEATURES,
+    SERVICES_CORE_TOKIO_AGGREGATES,
+  );
 }
 
 export function findServicesCorePlatformDependencyFeatureViolations(packages) {
@@ -629,9 +721,22 @@ export function findTokioDependencyFeatureViolations(packages) {
       const featureOwnedServicesCoreRuntime =
         pkg.name === 'bitfun-services-core'
         && (dependency.kind ?? null) === null;
-      if (featureOwnedServicesCoreRuntime) {
+      const featureOwnedCoreRuntime =
+        pkg.name === 'bitfun-core'
+        && (dependency.kind ?? null) === null;
+      const featureOwnedAgentRuntime =
+        pkg.name === 'bitfun-agent-runtime'
+        && (dependency.kind ?? null) === null;
+      if (
+        featureOwnedIntegrationRuntime
+        || featureOwnedServicesCoreRuntime
+        || featureOwnedCoreRuntime
+        || featureOwnedAgentRuntime
+      ) {
         const actual = [...features].sort();
-        const expected = [...SERVICES_CORE_BASE_TOKIO_FEATURES].sort();
+        const expected = [...(featureOwnedCoreRuntime
+          ? ['fs', 'sync']
+          : SERVICES_CORE_BASE_TOKIO_FEATURES)].sort();
         const missing = expected.filter((feature) => !actual.includes(feature));
         const unexpected = actual.filter((feature) => !expected.includes(feature));
         if (missing.length > 0) {
@@ -663,6 +768,19 @@ export function findTokioDependencyFeatureViolations(packages) {
     if (pkg.name === 'bitfun-services-core') {
       violations.push(...findServicesCoreTokioFeatureViolations(pkg));
     }
+    if (pkg.name === 'bitfun-core') {
+      violations.push(...findOwnedTokioFeatureViolations(
+        pkg,
+        CORE_TOKIO_FEATURES,
+        CORE_TOKIO_AGGREGATES,
+      ));
+    }
+    if (pkg.name === 'bitfun-agent-runtime') {
+      violations.push(...findOwnedTokioFeatureViolations(
+        pkg,
+        AGENT_RUNTIME_TOKIO_FEATURES,
+      ));
+    }
   }
 
   return violations;
@@ -770,53 +888,48 @@ export function findProductEntrypointCoreFeatureViolations(
   packages,
   { root, crateLayoutRules },
 ) {
+  const coreCompatibilityReviewedFeatures = [
+    'agent-runtime',
+    'document-read',
+    'subscription-auth',
+    'deep-research',
+    'lsp',
+    'external-sources',
+    'tools-basic',
+    'tools-git',
+    'tools-mcp',
+    'tools-browser-web',
+    'tools-computer-use',
+    'tools-image-analysis',
+    'tools-miniapp',
+    'tools-canvas',
+    'tools-agent-control',
+  ];
   const reviewedCoreFeatureClosures = new Map([
     ['bitfun-cli', [
-      'agent-runtime',
+      ...coreCompatibilityReviewedFeatures,
       'remote-connect',
-      'deep-research',
-      'lsp',
-      'external-sources',
       'plugin-runtime',
       'ssh-remote',
-      'tools-basic',
-      'tools-git',
-      'tools-mcp',
-      'tools-browser-web',
-      'tools-computer-use',
-      'tools-image-analysis',
-      'tools-miniapp',
-      'tools-canvas',
-      'tools-agent-control',
-    ]],
-    ['bitfun-acp', [
-      'agent-runtime',
-      'deep-research',
-      'lsp',
-      'external-sources',
-      'ssh-remote',
-      'tools-basic',
-      'tools-git',
-      'tools-mcp',
-      'tools-browser-web',
-      'tools-computer-use',
-      'tools-image-analysis',
-      'tools-miniapp',
-      'tools-canvas',
-      'tools-agent-control',
     ]],
+    ['bitfun-acp', [...new Set([...acpClientCoreFeatures, ...acpServerCoreFeatures])]],
     ['bitfun-app-server', [
       'external-sources',
       'git',
+      'i18n-runtime',
       'remote-connect',
     ]],
+    ['bitfun-sdk-host-app', coreCompatibilityReviewedFeatures],
   ]);
-  const acpActiveCoreFeatures = [
+  const fullProductCoreEntrypoints = new Set(['bitfun-desktop', 'bitfun-server']);
+  const fullProductCoreEntrypointsFound = new Set();
+  const coreCompatibilityActiveFeatures = [
     'agent-runtime',
     'ai-adapter-runtime',
     'browser-control',
     'canvas-runtime',
     'deep-research',
+    'document-read',
     'external-sources',
     'file-watch',
     'filesystem',
@@ -828,12 +941,11 @@ export function findProductEntrypointCoreFeatureViolations(
     'plugin-source',
     'process-runtime',
     'product-capabilities',
-    'remote-workspace',
     'review-platform',
     'runtime-services',
     'scheduled-jobs',
     'script-tool-runtime',
-    'ssh-remote',
+    'subscription-auth',
     'terminal',
     'tool-packs',
     'tools-agent-control',
@@ -850,9 +962,20 @@ export function findProductEntrypointCoreFeatureViolations(
     'workspace-runtime',
     'workspace-watch',
   ];
+  const acpActiveCoreFeatures = [
+    ...coreCompatibilityActiveFeatures,
+    'remote-workspace',
+    'ssh-remote',
+  ];
   const reviewedActiveCoreFeatureClosures = new Map([
-    ['bitfun-cli', [...acpActiveCoreFeatures, 'plugin-runtime', 'remote-connect']],
+    ['bitfun-cli', [
+      ...acpActiveCoreFeatures,
+      'i18n-runtime',
+      'plugin-runtime',
+      'remote-connect',
+    ]],
     ['bitfun-acp', acpActiveCoreFeatures],
+    ['bitfun-sdk-host-app', coreCompatibilityActiveFeatures],
     ['bitfun-app-server', [
       'agent-runtime',
       'ai-adapter-runtime',
@@ -860,6 +983,7 @@ export function findProductEntrypointCoreFeatureViolations(
       'file-watch',
       'filesystem',
       'git',
+      'i18n-runtime',
       'local-storage',
       'mcp-runtime',
       'model-catalog',
@@ -880,11 +1004,129 @@ export function findProductEntrypointCoreFeatureViolations(
       'workspace-watch',
     ]],
   ]);
+  const reviewedForbiddenDependencyOwnerFeatures = new Map([
+    ['bitfun-sdk-host-app', new Map([
+      ['bitfun-services-integrations', [
+        'announcement',
+        'debug-log',
+        'function-agents',
+        'product-full',
+        'remote-connect',
+        'remote-ssh',
+        'remote-ssh-concrete',
+      ]],
+      ['bitfun-product-domains', ['function-agents', 'product-full']],
+      ['bitfun-services-core', ['dispatch-workspace']],
+    ])],
+  ]);
   const packageByManifest = new Map(
     packages.map((pkg) => [normalizedPath(pkg.manifest_path), pkg]),
   );
   const violations = [];
 
+  const reviewedAcpRoleSelections = new Map([
+    ['bitfun-cli', {
+      label: 'CLI',
+      requiredFeatures: ['client', 'server'],
+    }],
+    ['bitfun-desktop', {
+      label: 'Desktop',
+      requiredFeatures: ['client'],
+    }],
+  ]);
+  const acpPackage = packages.find((pkg) => pkg.name === 'bitfun-acp');
+  if (acpPackage) {
+    const reviewedConsumersFound = new Set();
+    for (const sourcePackage of packages) {
+      const declaredDependencies = (sourcePackage.dependencies ?? []).filter((candidate) => {
+        if (!candidate.path) {
+          return false;
+        }
+        return packageByManifest.get(
+          normalizedPath(join(candidate.path, 'Cargo.toml')),
+        )?.name === 'bitfun-acp';
+      });
+      const normalDependencies = declaredDependencies.filter(
+        (dependency) => dependency.kind === null,
+      );
+      const rule = reviewedAcpRoleSelections.get(sourcePackage.name);
+      if (!rule) {
+        if (declaredDependencies.length > 0) {
+          violations.push({
+            path: sourcePackage.manifest_path,
+            line: 1,
+            message: `bitfun-acp consumer ${sourcePackage.name} must register an explicit role selection`,
+          });
+        }
+        continue;
+      }
+      if (declaredDependencies.length === 0) {
+        continue;
+      }
+      reviewedConsumersFound.add(sourcePackage.name);
+      const unconditionalDependencies = normalDependencies.filter(
+        (dependency) => dependency.target === null && dependency.optional !== true,
+      );
+      if (unconditionalDependencies.length === 0) {
+        violations.push({
+          path: sourcePackage.manifest_path,
+          line: 1,
+          message: `${rule.label} ACP role selection must keep an unconditional normal bitfun-acp dependency`,
+        });
+      }
+      if (declaredDependencies.some((dependency) => dependency.optional === true)) {
+        violations.push({
+          path: sourcePackage.manifest_path,
+          line: 1,
+          message: `${rule.label} ACP role selection must not make a bitfun-acp dependency optional`,
+        });
+      }
+      if (declaredDependencies.some((dependency) => dependency.uses_default_features !== false)) {
+        violations.push({
+          path: sourcePackage.manifest_path,
+          line: 1,
+          message: `${rule.label} ACP role selection must set default-features = false on every dependency`,
+        });
+      }
+      const unconditionalFeatures = new Set(
+        unconditionalDependencies.flatMap((dependency) => dependency.features ?? []),
+      );
+      const selectedFeatures = new Set(
+        declaredDependencies.flatMap((dependency) => dependency.features ?? []),
+      );
+      if (unconditionalDependencies.length > 0) {
+        for (const requiredFeature of rule.requiredFeatures) {
+          if (!unconditionalFeatures.has(requiredFeature)) {
+            violations.push({
+              path: sourcePackage.manifest_path,
+              line: 1,
+              message: `${rule.label} ACP role selection must include ${requiredFeature}`,
+            });
+          }
+        }
+      }
+      for (const selectedFeature of selectedFeatures) {
+        if (!rule.requiredFeatures.includes(selectedFeature)) {
+          violations.push({
+            path: sourcePackage.manifest_path,
+            line: 1,
+            message: `${rule.label} ACP role selection must not include ${selectedFeature}`,
+          });
+        }
+      }
+    }
+    for (const [sourceName, rule] of reviewedAcpRoleSelections) {
+      const sourcePackage = packages.find((pkg) => pkg.name === sourceName);
+      if (sourcePackage && !reviewedConsumersFound.has(sourceName)) {
+        violations.push({
+          path: sourcePackage.manifest_path,
+          line: 1,
+          message: `${rule.label} ACP role selection must keep the bitfun-acp dependency`,
+        });
+      }
+    }
+  }
+
   for (const sourcePackage of packages) {
     const sourceLayer = layerForManifest(sourcePackage.manifest_path, {
       root,
@@ -904,21 +1146,32 @@ export function findProductEntrypointCoreFeatureViolations(
       if (targetPackage?.name !== 'bitfun-core') {
         continue;
       }
-      if (dependency.uses_default_features !== false) {
-        violations.push({
-          path: sourcePackage.manifest_path,
-          line: 1,
-          message: `product entrypoint ${sourcePackage.name} must set default-features = false for its bitfun-core ${dependencyDescription(dependency)}`,
-        });
-      }
-      if (!Array.isArray(dependency.features) || dependency.features.length === 0) {
+      const roleOwnedAcpDependency =
+        sourcePackage.name === 'bitfun-acp' && dependency.optional === true;
+      if (
+        !roleOwnedAcpDependency
+        && (!Array.isArray(dependency.features) || dependency.features.length === 0)
+      ) {
         violations.push({
           path: sourcePackage.manifest_path,
           line: 1,
           message: `product entrypoint ${sourcePackage.name} must select at least one explicit feature for its bitfun-core ${dependencyDescription(dependency)}`,
         });
       }
-      const reviewedClosure = reviewedCoreFeatureClosures.get(sourcePackage.name);
+      if (fullProductCoreEntrypoints.has(sourcePackage.name)) {
+        fullProductCoreEntrypointsFound.add(sourcePackage.name);
+        const selectedFeatures = [...new Set(dependency.features ?? [])].sort();
+        if (selectedFeatures.length !== 1 || selectedFeatures[0] !== 'product-full') {
+          violations.push({
+            path: sourcePackage.manifest_path,
+            line: 1,
+            message: `${sourcePackage.name} Core capability closure must select exactly product-full`,
+          });
+        }
+      }
+      const reviewedClosure = roleOwnedAcpDependency
+        ? undefined
+        : reviewedCoreFeatureClosures.get(sourcePackage.name);
       if (reviewedClosure) {
         const selectedFeatures = new Set(dependency.features ?? []);
         for (const requiredFeature of reviewedClosure) {
@@ -942,6 +1195,18 @@ export function findProductEntrypointCoreFeatureViolations(
       }
     }
   }
+  for (const sourceName of packages.some((pkg) => pkg.name === 'bitfun-core')
+    ? fullProductCoreEntrypoints
+    : []) {
+    const sourcePackage = packages.find((pkg) => pkg.name === sourceName);
+    if (sourcePackage && !fullProductCoreEntrypointsFound.has(sourceName)) {
+      violations.push({
+        path: sourcePackage.manifest_path,
+        line: 1,
+        message: `${sourceName} Core capability closure must keep the bitfun-core dependency`,
+      });
+    }
+  }
 
   const corePackage = packages.find((pkg) => pkg.name === 'bitfun-core');
   if (corePackage) {
@@ -959,7 +1224,7 @@ export function findProductEntrypointCoreFeatureViolations(
         continue;
       }
       const allowedCoreFeatures = new Set(
-        reviewedActiveCoreFeatureClosures.get(rootName) ?? [],
+        ['default', ...(reviewedActiveCoreFeatureClosures.get(rootName) ?? [])],
       );
       const rootSelectedFeatures = Object.keys(rootPackage.features ?? {})
         .filter((feature) => feature !== 'default');
@@ -967,7 +1232,10 @@ export function findProductEntrypointCoreFeatureViolations(
         ['bitfun-cli', 'CLI'],
         ['bitfun-acp', 'ACP'],
         ['bitfun-app-server', 'App Server'],
+        ['bitfun-sdk-host-app', 'SDK Host'],
       ]).get(rootName) ?? rootName;
+      const forbiddenOwnerFeatures =
+        reviewedForbiddenDependencyOwnerFeatures.get(rootName);
 
       const packageStates = new Map();
       const pending = [];
@@ -1106,6 +1374,30 @@ export function findProductEntrypointCoreFeatureViolations(
             }
             continue;
           }
+
+          const forbiddenOwnerFeature = (
+            forbiddenOwnerFeatures?.get(targetPackage.name) ?? []
+          ).find((feature) => targetState.featureState.active.has(feature));
+          if (forbiddenOwnerFeature) {
+            const forbiddenOwner = `${targetPackage.name}/${forbiddenOwnerFeature}`;
+            const reportKey = [
+              rootName,
+              targetDependencyKindContext,
+              forbiddenOwner,
+            ].join('|');
+            if (!reportedUnexpectedFeatures.has(reportKey)) {
+              reportedUnexpectedFeatures.add(reportKey);
+              violations.push({
+                path: sourcePackage.manifest_path,
+                line: 1,
+                message: `${rootLabel} dependency closure must not enable ${forbiddenOwner}: ${[
+                  ...packagePath,
+                  forbiddenOwner,
+                ].join(' -> ')}`,
+              });
+            }
+            continue;
+          }
         }
       }
     }
@@ -1114,6 +1406,363 @@ export function findProductEntrypointCoreFeatureViolations(
   return violations;
 }
 
+function normalizedDependencyKind(dependency) {
+  return dependency.kind ?? 'normal';
+}
+
+function normalizedDependencyTarget(dependency) {
+  return dependency.target ?? null;
+}
+
+function sameStringSet(actual, expected) {
+  const left = [...new Set(actual ?? [])].sort();
+  const right = [...new Set(expected ?? [])].sort();
+  return left.length === right.length
+    && left.every((value, index) => value === right[index]);
+}
+
+function featureForwardingReferences(featureGraph, dependency) {
+  const alias = dependencyAlias(dependency);
+  const references = [];
+  for (const [sourceFeature, values] of Object.entries(featureGraph ?? {})) {
+    for (const value of values) {
+      const match = value.match(/^([^/?]+)(\?)?\/(.+)$/);
+      if (match?.[1] === alias) {
+        references.push({
+          sourceFeature,
+          feature: match[3],
+          weak: Boolean(match[2]),
+        });
+      }
+    }
+  }
+  return references;
+}
+
+function featureDependencyActivations(featureGraph, dependency) {
+  const alias = dependencyAlias(dependency);
+  const activations = [];
+  for (const [sourceFeature, values] of Object.entries(featureGraph ?? {})) {
+    if (values.includes(`dep:${alias}`) || values.includes(alias)) {
+      activations.push(sourceFeature);
+    }
+  }
+  return activations;
+}
+
+function packageMatchesManifest(pkg, manifestPath, root) {
+  return repositoryPath(root, pkg.manifest_path) === manifestPath;
+}
+
+function dependencyTargetsPackage(dependency, targetPackage) {
+  return dependency.path !== null
+    && dependency.path !== undefined
+    && normalizedPath(join(dependency.path, 'Cargo.toml'))
+      === normalizedPath(targetPackage.manifest_path);
+}
+
+function dependencyEdgeMatches(dependency, expected) {
+  return normalizedDependencyKind(dependency) === expected.kind
+    && dependency.optional === expected.optional
+    && normalizedDependencyTarget(dependency) === expected.target
+    && (dependency.rename ?? null) === (expected.rename ?? null)
+    && sameStringSet(dependency.features, expected.features);
+}
+
+function featureTransitivelyReaches(featureGraph, sourceFeature, destinations, seen = new Set()) {
+  if (destinations.has(sourceFeature)) {
+    return true;
+  }
+  if (seen.has(sourceFeature)) {
+    return false;
+  }
+  seen.add(sourceFeature);
+  return (featureGraph[sourceFeature] ?? []).some((reference) =>
+    Object.hasOwn(featureGraph, reference)
+    && featureTransitivelyReaches(featureGraph, reference, destinations, seen));
+}
+
+export function findRedundantInternalDefaultFeatureDisables(
+  packages,
+  {
+    root,
+    guardedManifests = guardedEmptyInternalDefaultManifestPaths,
+  } = {},
+) {
+  if (!root) {
+    throw new Error('redundant internal default-feature check requires the repository root');
+  }
+
+  const packageByManifest = new Map(
+    packages.map((pkg) => [normalizedPath(pkg.manifest_path), pkg]),
+  );
+  const guardedTargets = new Set(
+    guardedManifests.map((path) => normalizedPath(join(root, path))),
+  );
+  const violations = [];
+
+  for (const consumer of packages) {
+    for (const dependency of consumer.dependencies ?? []) {
+      if (dependency.uses_default_features !== false || !dependency.path) {
+        continue;
+      }
+      const targetPackage = packageByManifest.get(
+        normalizedPath(join(dependency.path, 'Cargo.toml')),
+      );
+      const targetFeatures = targetPackage?.features ?? {};
+      if (
+        !targetPackage
+        || !guardedTargets.has(normalizedPath(targetPackage.manifest_path))
+        || !Object.hasOwn(targetFeatures, 'default')
+        || !sameStringSet(targetFeatures.default, [])
+      ) {
+        continue;
+      }
+      violations.push({
+        path: consumer.manifest_path,
+        line: 1,
+        message: `${consumer.name} ${targetPackage.name} dependency has redundant default-features = false because the target default is guarded empty`,
+      });
+    }
+  }
+
+  return violations;
+}
+
+export function findGuardedInternalDefaultFeatureViolations(
+  packages,
+  {
+    root,
+    guardedManifests = guardedEmptyInternalDefaultManifestPaths,
+  } = {},
+) {
+  if (!root) {
+    throw new Error('guarded internal default-feature check requires the repository root');
+  }
+
+  const packageByManifest = new Map(
+    packages.map((pkg) => [normalizedPath(pkg.manifest_path), pkg]),
+  );
+  const violations = [];
+
+  for (const manifestPath of guardedManifests) {
+    const targetPackage = packageByManifest.get(normalizedPath(join(root, manifestPath)));
+    if (!targetPackage) {
+      violations.push({
+        path: join(root, manifestPath),
+        line: 1,
+        message: `guarded internal empty-default target is missing: ${manifestPath}`,
+      });
+      continue;
+    }
+    const targetFeatures = targetPackage.features ?? {};
+    if (
+      !Object.hasOwn(targetFeatures, 'default')
+      || !sameStringSet(targetFeatures.default, [])
+    ) {
+      violations.push({
+        path: targetPackage.manifest_path,
+        line: 1,
+        message: `${targetPackage.name} guarded default feature must stay explicitly empty`,
+      });
+    }
+  }
+
+  return violations;
+}
+
+export function findCapabilityContractConsumerViolations(
+  packages,
+  rules = capabilityContractDependencyRules,
+  { root } = {},
+) {
+  const violations = [];
+  const targetPackages = new Map();
+
+  if (!root) {
+    throw new Error('capability contract consumer check requires the repository root');
+  }
+
+  for (const rule of rules) {
+    const targetPackage = packages.find((pkg) =>
+      pkg.name === rule.packageName && packageMatchesManifest(pkg, rule.manifestPath, root));
+    if (!targetPackage) {
+      violations.push({
+        path: rule.manifestPath,
+        line: 1,
+        message: `${rule.packageName} managed target is missing from Cargo metadata`,
+      });
+      continue;
+    }
+    targetPackages.set(rule.packageName, targetPackage);
+    if (
+      !Object.hasOwn(targetPackage.features ?? {}, 'default')
+      || !sameStringSet(targetPackage.features.default, [])
+    ) {
+      violations.push({
+        path: targetPackage.manifest_path,
+        line: 1,
+        message: `${rule.packageName} capability contract default feature must stay empty`,
+      });
+    }
+    const actualFeatures = Object.keys(targetPackage.features ?? {})
+      .filter((feature) => feature !== 'default');
+    const expectedFeatures = Object.keys(rule.featureProfiles)
+      .filter((feature) => feature !== 'default');
+    if (!sameStringSet(actualFeatures, expectedFeatures)) {
+      violations.push({
+        path: targetPackage.manifest_path,
+        line: 1,
+        message: `${rule.packageName} capability contract feature surface must stay exact`,
+      });
+    }
+    for (const [feature, expectedReferences] of Object.entries(rule.featureProfiles)) {
+      if (
+        Object.hasOwn(targetPackage.features ?? {}, feature)
+        && !sameStringSet(targetPackage.features[feature], expectedReferences)
+      ) {
+        violations.push({
+          path: targetPackage.manifest_path,
+          line: 1,
+          message: `${rule.packageName}:${feature} feature graph must stay exact`,
+        });
+      }
+    }
+  }
+
+  for (const rule of rules) {
+    const targetPackage = targetPackages.get(rule.packageName);
+    if (!targetPackage) {
+      continue;
+    }
+    for (const consumer of packages) {
+      const namedDependencies = (consumer.dependencies ?? []).filter(
+        (dependency) => dependency.name === rule.packageName,
+      );
+      const managedDependencies = namedDependencies.filter((dependency) =>
+        dependencyTargetsPackage(dependency, targetPackage));
+      for (const dependency of namedDependencies) {
+        if (dependencyTargetsPackage(dependency, targetPackage)) {
+          continue;
+        }
+        violations.push({
+          path: consumer.manifest_path,
+          line: 1,
+          message: `${consumer.name} ${rule.packageName} dependency must use the managed internal path`,
+        });
+      }
+
+      const consumerProfile = rule.consumers.get(consumer.name);
+      if (!consumerProfile) {
+        if (managedDependencies.length > 0) {
+          violations.push({
+            path: consumer.manifest_path,
+            line: 1,
+            message: `${consumer.name} has an unreviewed consumer edge to ${rule.packageName}`,
+          });
+        }
+        continue;
+      }
+      const unmatchedExpectedEdges = [...consumerProfile.edges];
+      for (const dependency of managedDependencies) {
+        const matchIndex = unmatchedExpectedEdges.findIndex((edge) =>
+          dependencyEdgeMatches(dependency, edge));
+        if (matchIndex === -1) {
+          violations.push({
+            path: consumer.manifest_path,
+            line: 1,
+            message: `${consumer.name} has an unreviewed ${rule.packageName} dependency edge`,
+          });
+        } else {
+          unmatchedExpectedEdges.splice(matchIndex, 1);
+        }
+      }
+      for (const edge of unmatchedExpectedEdges) {
+        violations.push({
+          path: consumer.manifest_path,
+          line: 1,
+          message: `${consumer.name} is missing reviewed ${edge.kind} ${rule.packageName} dependency edge`,
+        });
+      }
+
+      const actualForwarders = managedDependencies.flatMap((dependency) =>
+        featureForwardingReferences(consumer.features, dependency));
+      for (const forwarding of actualForwarders) {
+        const allowed = (consumerProfile.forwarders ?? []).some((expected) =>
+          expected.sourceFeature === forwarding.sourceFeature
+          && expected.feature === forwarding.feature
+          && expected.weak === forwarding.weak);
+        if (allowed) {
+          continue;
+        }
+        violations.push({
+          path: consumer.manifest_path,
+          line: 1,
+          message: `${consumer.name}:${forwarding.sourceFeature} has unreviewed ${rule.packageName}/${forwarding.feature} forwarding`,
+        });
+      }
+      for (const expected of consumerProfile.forwarders ?? []) {
+        const present = actualForwarders.some((forwarding) =>
+          expected.sourceFeature === forwarding.sourceFeature
+          && expected.feature === forwarding.feature
+          && expected.weak === forwarding.weak);
+        if (present) {
+          continue;
+        }
+        violations.push({
+          path: consumer.manifest_path,
+          line: 1,
+          message: `${consumer.name}:${expected.sourceFeature} is missing reviewed ${rule.packageName}/${expected.feature} forwarding`,
+        });
+      }
+      const actualActivators = managedDependencies.flatMap((dependency) =>
+        featureDependencyActivations(consumer.features, dependency));
+      for (const sourceFeature of actualActivators) {
+        if ((consumerProfile.activators ?? []).includes(sourceFeature)) {
+          continue;
+        }
+        violations.push({
+          path: consumer.manifest_path,
+          line: 1,
+          message: `${consumer.name}:${sourceFeature} has unreviewed ${rule.packageName} activation`,
+        });
+      }
+      for (const sourceFeature of consumerProfile.activators ?? []) {
+        if (actualActivators.includes(sourceFeature)) {
+          continue;
+        }
+        violations.push({
+          path: consumer.manifest_path,
+          line: 1,
+          message: `${consumer.name}:${sourceFeature} is missing reviewed ${rule.packageName} activation`,
+        });
+      }
+
+      const directOwners = new Set([
+        ...(consumerProfile.forwarders ?? []).map(({ sourceFeature }) => sourceFeature),
+        ...(consumerProfile.activators ?? []),
+      ]);
+      const allowedAggregates = new Set(consumerProfile.aggregates ?? []);
+      for (const feature of Object.keys(consumer.features ?? {})) {
+        if (
+          directOwners.has(feature)
+          || allowedAggregates.has(feature)
+          || !featureTransitivelyReaches(consumer.features, feature, directOwners)
+        ) {
+          continue;
+        }
+        violations.push({
+          path: consumer.manifest_path,
+          line: 1,
+          message: `${consumer.name}:${feature} is an unreviewed aggregate of ${rule.packageName} capability owners`,
+        });
+      }
+    }
+  }
+
+  return violations;
+}
+
 function matchingClosingDelimiter(
   source,
   openingIndex,
@@ -1526,6 +2175,9 @@ export function checkCargoDependencyBoundaries({ root, crateLayoutRules }) {
       packages,
       { root, crateLayoutRules },
     ),
+    ...findGuardedInternalDefaultFeatureViolations(packages, { root }),
+    ...findRedundantInternalDefaultFeatureDisables(packages, { root }),
+    ...findCapabilityContractConsumerViolations(packages, undefined, { root }),
     ...findFeatureGatedTestTargetViolations(packages),
     ...findRuntimeServicesTestSupportFeatureViolations(packages),
     ...findTokioDependencyFeatureViolations(packages),
diff --git a/scripts/core-boundaries/checker.mjs b/scripts/core-boundaries/checker.mjs
index 0742b296e2..d70a510bc9 100644
--- a/scripts/core-boundaries/checker.mjs
+++ b/scripts/core-boundaries/checker.mjs
@@ -15,10 +15,12 @@ import {
 } from './rules/crate-layout.mjs';
 import { checkTuiLegacyBackendRatchet } from './tui-boundary-ratchet.mjs';
 import {
+  acpClosedFeatureProfileRules,
   coreClosedFeatureProfileRules,
   coreProductFullFeatureAssemblyRule,
   optionalDependencyFeatureOwnerRules,
   ownerCrateFeatureAssemblyRules,
+  reviewedOptionalDependencyAggregateFeatures,
 } from './rules/feature-rules.mjs';
 import {
   facadeOnlyFiles,
@@ -32,15 +34,18 @@ import { runManifestParserSelfTest } from './self-test.mjs';
 import {
   featureReferencesDependency,
   featureReferencesFeature,
+  featureReferencesOptionalDependencyOwner,
   unexpectedDependencyOwnerFeatures,
   unexpectedReachableLocalFeatures,
 } from './manifest-feature-helpers.mjs';
 import { checkCargoDependencyBoundariesSafely } from './cargo-dependency-boundaries.mjs';
+import { checkPeerCommandPolicySync } from './peer-command-policy.mjs';
 import {
   agentRuntimeIntegrationTestTargets,
   checkAgentRuntimeIntegrationTestTopology,
   checkCliIntegrationTestTopology,
-  checkServiceIntegrationTestTopologies,
+  checkExternalSourceIntegrationTestTopologies,
+  checkReviewedIntegrationTestTopologies,
   cliIntegrationTestTargets,
   validateExplicitIntegrationTestTopology,
 } from './explicit-test-topology.mjs';
@@ -511,11 +516,16 @@ function checkForbiddenManifestDependencyRule(rule) {
 
 function checkOptionalDependencyFeatureOwners(crateDir, rule) {
   const manifestPath = join(crateDir, 'Cargo.toml');
+  const repoManifestPath = toRepoPath(manifestPath);
   const lines = readText(manifestPath).split(/\r?\n/);
   const deps = parseManifestDependencies(lines);
   const normalDeps = deps.filter((dep) => dep.kind === 'normal');
   const depsByName = new Map(normalDeps.map((dep) => [dep.name, dep]));
   const features = parseManifestFeatures(lines);
+  const reviewedAggregateFeatures = new Set([
+    ...reviewedOptionalDependencyAggregateFeatures(repoManifestPath),
+    ...(rule.reviewedAggregateFeatures ?? []),
+  ]);
   const declaredOwnerDeps = new Set(rule.dependencies.map((dependency) => dependency.depName));
 
   for (const dependency of rule.dependencies) {
@@ -545,7 +555,7 @@ function checkOptionalDependencyFeatureOwners(crateDir, rule) {
         });
         continue;
       }
-      if (!featureReferencesDependency(feature, dependency.depName)) {
+      if (!featureReferencesOptionalDependencyOwner(feature, dependency.depName)) {
         failures.push({
           path: manifestPath,
           line: feature.line,
@@ -553,7 +563,11 @@ function checkOptionalDependencyFeatureOwners(crateDir, rule) {
         });
       }
     }
-    for (const [featureName, feature] of unexpectedDependencyOwnerFeatures(features, dependency)) {
+    for (const [featureName, feature] of unexpectedDependencyOwnerFeatures(
+      features,
+      dependency,
+      reviewedAggregateFeatures,
+    )) {
       failures.push({
         path: manifestPath,
         line: feature.line,
@@ -582,19 +596,6 @@ function checkOptionalDependencyFeatureOwners(crateDir, rule) {
   }
 }
 
-function checkCoreDefaultProductFullFeature() {
-  const manifestPath = join(crateDirForName('core'), 'Cargo.toml');
-  const features = parseManifestFeatures(readText(manifestPath).split(/\r?\n/));
-  if (!featureReferencesFeature(features.get('default'), 'product-full')) {
-    failures.push({
-      path: manifestPath,
-      line: features.get('default')?.line ?? 1,
-      message:
-        'bitfun-core default feature must remain product-full until a separate product matrix review changes it',
-    });
-  }
-}
-
 function checkCoreProductFullFeatureAssembly(rule) {
   const manifestPath = repoPathToFsPath(rule.manifestPath);
   const features = parseManifestFeatures(readText(manifestPath).split(/\r?\n/));
@@ -874,14 +875,14 @@ function checkForbiddenContent(repoPath, patterns) {
     }
   });
 }
-
 function checkRequiredContent(repoPath, patterns, reason) {
   const path = repoPathToFsPath(repoPath);
-  const text = readText(path);
   for (const pattern of patterns) {
+    const patternPath = pattern.path ? repoPathToFsPath(pattern.path) : path;
+    const text = readText(patternPath);
     if (!pattern.regex.test(text)) {
       failures.push({
-        path,
+        path: patternPath,
         line: 1,
         message: `${reason}; ${pattern.message}`,
       });
@@ -1089,6 +1090,7 @@ export function runCoreBoundaryCheck() {
       manifestDependencyMatches,
       matchingForbiddenDependency,
       coreClosedFeatureProfileRules,
+      acpClosedFeatureProfileRules,
       coreProductFullFeatureAssemblyRule,
       ownerCrateFeatureAssemblyRules,
       parseManifestFeatures,
@@ -1123,7 +1125,8 @@ export function runCoreBoundaryCheck() {
   failures.push(...checkCargoDependencyBoundariesSafely({ root: ROOT, crateLayoutRules }));
   failures.push(...checkAgentRuntimeIntegrationTestTopology(ROOT));
   failures.push(...checkCliIntegrationTestTopology(ROOT));
-  failures.push(...checkServiceIntegrationTestTopologies(ROOT));
+  failures.push(...checkExternalSourceIntegrationTestTopologies(ROOT), ...checkReviewedIntegrationTestTopologies(ROOT));
+  failures.push(...checkPeerCommandPolicySync(ROOT));
 
   for (const rule of forbiddenManifestDependencyRules) {
     checkForbiddenManifestDependencyRule(rule);
@@ -1154,11 +1157,13 @@ export function runCoreBoundaryCheck() {
     checkOptionalDependencyFeatureOwners(crateDir, rule);
   }
 
-  checkCoreDefaultProductFullFeature();
   checkCoreProductFullFeatureAssembly(coreProductFullFeatureAssemblyRule);
   for (const rule of coreClosedFeatureProfileRules) {
     checkClosedFeatureProfile(rule);
   }
+  for (const rule of acpClosedFeatureProfileRules) {
+    checkClosedFeatureProfile(rule);
+  }
   for (const rule of ownerCrateFeatureAssemblyRules) {
     checkOwnerCrateFeatureAssembly(rule);
   }
@@ -1178,7 +1183,6 @@ export function runCoreBoundaryCheck() {
   for (const rule of requiredContentRules) {
     checkRequiredContent(rule.path, rule.patterns, rule.reason);
   }
-
   for (const rule of publicApiAllowlistRules) {
     checkPublicApiAllowlist(rule);
   }
diff --git a/scripts/core-boundaries/explicit-test-topology.mjs b/scripts/core-boundaries/explicit-test-topology.mjs
index 9a157af1d4..01196cee6d 100644
--- a/scripts/core-boundaries/explicit-test-topology.mjs
+++ b/scripts/core-boundaries/explicit-test-topology.mjs
@@ -2,11 +2,25 @@ import { readdirSync, readFileSync } from 'node:fs';
 import { join, posix, relative } from 'node:path';
 
 export const agentRuntimeIntegrationTestTargets = [
-  { name: 'agent_definition_contracts', path: 'tests/agent_definition_contracts.rs' },
-  { name: 'agent_interaction_contracts', path: 'tests/agent_interaction_contracts.rs' },
-  { name: 'agent_long_horizon_contracts', path: 'tests/agent_long_horizon_contracts.rs' },
-  { name: 'agent_session_contracts', path: 'tests/agent_session_contracts.rs' },
-  { name: 'native_hook_execution_contracts', path: 'tests/native_hook_execution_contracts.rs' },
+  { name: 'agent_definition_contracts', path: 'tests/agent_definition_contracts.rs', requiredFeatures: ['agent-runtime'] },
+  { name: 'agent_interaction_contracts', path: 'tests/agent_interaction_contracts.rs', requiredFeatures: ['agent-runtime'] },
+  { name: 'agent_long_horizon_contracts', path: 'tests/agent_long_horizon_contracts.rs', requiredFeatures: ['agent-runtime'] },
+  { name: 'agent_session_contracts', path: 'tests/agent_session_contracts.rs', requiredFeatures: ['agent-runtime'] },
+  {
+    name: 'deep_research_contracts',
+    path: 'tests/deep_research_contracts.rs',
+    requiredFeatures: ['deep-research'],
+  },
+  {
+    name: 'native_hook_execution_contracts',
+    path: 'tests/native_hook_execution_contracts.rs',
+    requiredFeatures: ['native-hook-runtime'],
+  },
+  {
+    name: 'native_hook_settings_contracts',
+    path: 'tests/native_hook_settings_contracts.rs',
+    requiredFeatures: ['native-hook-settings'],
+  },
 ];
 
 export const cliIntegrationTestTargets = [
@@ -46,6 +60,260 @@ export const servicesIntegrationsIntegrationTestTargets = [
   { name: 'workspace_search_contracts', path: 'tests/workspace_search_contracts.rs' },
 ];
 
+export const opencodeAdapterIntegrationTestTargets = [
+  { name: 'opencode_mcp_adapter', path: 'tests/opencode_mcp_adapter.rs' },
+  { name: 'opencode_source_adapter', path: 'tests/opencode_source_adapter.rs' },
+  {
+    name: 'opencode_static_source_contracts',
+    path: 'tests/opencode_static_source_contracts.rs',
+    leaves: [
+      'tests/opencode_static_source_contracts/hook_source.rs',
+      'tests/opencode_static_source_contracts/opencode_command_adapter.rs',
+      'tests/opencode_static_source_contracts/opencode_skill_roots.rs',
+      'tests/opencode_static_source_contracts/opencode_subagent_adapter.rs',
+      'tests/opencode_static_source_contracts/opencode_workspace_references.rs',
+    ],
+    forbidRequiredFeatures: true,
+  },
+  { name: 'tool_source_contracts', path: 'tests/tool_source_contracts.rs' },
+];
+
+export const claudeCodeAdapterIntegrationTestTargets = [
+  {
+    name: 'claude_code_source_contracts',
+    path: 'tests/claude_code_source_contracts.rs',
+    leaves: [
+      'tests/claude_code_source_contracts/command_source.rs',
+      'tests/claude_code_source_contracts/hook_source.rs',
+      'tests/claude_code_source_contracts/mcp_source.rs',
+      'tests/claude_code_source_contracts/subagent_source.rs',
+    ],
+    forbidRequiredFeatures: true,
+  },
+];
+
+export const codexAdapterIntegrationTestTargets = [
+  {
+    name: 'codex_source_contracts',
+    path: 'tests/codex_source_contracts.rs',
+    leaves: [
+      'tests/codex_source_contracts/hook_source.rs',
+      'tests/codex_source_contracts/mcp_source.rs',
+      'tests/codex_source_contracts/subagent_source.rs',
+    ],
+    forbidRequiredFeatures: true,
+  },
+];
+
+export const externalSourcesIntegrationTestTargets = [
+  {
+    name: 'external_source_coordination_contracts',
+    path: 'tests/external_source_coordination_contracts.rs',
+    leaves: [
+      'tests/external_source_coordination_contracts/control_plane.rs',
+      'tests/external_source_coordination_contracts/coordinator_contracts.rs',
+      'tests/external_source_coordination_contracts/hook_coordinator.rs',
+      'tests/external_source_coordination_contracts/mcp_coordinator.rs',
+      'tests/external_source_coordination_contracts/subagent_coordinator.rs',
+      'tests/external_source_coordination_contracts/tool_coordinator_contracts.rs',
+      'tests/external_source_coordination_contracts/workspace_reference.rs',
+    ],
+    forbidRequiredFeatures: true,
+  },
+];
+
+export const coreTypesIntegrationTestTargets = [
+  {
+    name: 'core_type_contracts',
+    path: 'tests/core_type_contracts.rs',
+    leaves: [
+      'tests/core_type_contracts/lsp_contracts.rs',
+      'tests/core_type_contracts/session_contracts.rs',
+      'tests/core_type_contracts/session_usage_contracts.rs',
+      'tests/core_type_contracts/surface_contracts.rs',
+    ],
+    forbidRequiredFeatures: true,
+  },
+];
+
+export const runtimePortsIntegrationTestTargets = [
+  {
+    name: 'plugin_runtime_contracts',
+    path: 'tests/runtime_port_contracts.rs',
+    leaves: [
+      'tests/runtime_port_contracts/plugin_runtime_contracts.rs',
+      'tests/runtime_port_contracts/plugin_runtime_diagnostics_contracts.rs',
+    ],
+    requiredFeatures: ['plugin-runtime'],
+  },
+  {
+    name: 'git_port_contracts',
+    path: 'tests/git_port_contracts.rs',
+    requiredFeatures: ['git-port'],
+  },
+  {
+    name: 'script_tool_port_contracts',
+    path: 'tests/script_tool_port_contracts.rs',
+    requiredFeatures: ['script-tool-runtime'],
+  },
+  {
+    name: 'session_store_contracts',
+    path: 'tests/session_store_contracts.rs',
+    requiredFeatures: ['workspace-ports'],
+  },
+];
+
+export const productDomainsIntegrationTestTargets = [
+  {
+    name: 'product_domain_contracts',
+    path: 'tests/product_domain_contracts.rs',
+    leaves: [
+      'tests/product_domain_contracts/canvas_contracts.rs',
+      'tests/product_domain_contracts/tool_permission_contracts.rs',
+    ],
+    forbidRequiredFeatures: true,
+  },
+  {
+    name: 'external_source_contracts',
+    path: 'tests/external_source_contracts.rs',
+    leaves: [
+      'tests/external_source_contracts/external_hook_catalog_contracts.rs',
+      'tests/external_source_contracts/external_hook_contribution_contracts.rs',
+      'tests/external_source_contracts/external_source_contracts.rs',
+      'tests/external_source_contracts/workspace_reference_contracts.rs',
+    ],
+    requiredFeatures: ['external-sources'],
+  },
+  {
+    name: 'function_agent_contracts',
+    path: 'tests/function_agent_contracts.rs',
+    requiredFeatures: ['function-agents'],
+  },
+  {
+    name: 'miniapp_contracts',
+    path: 'tests/miniapp_contracts.rs',
+    requiredFeatures: ['miniapp'],
+  },
+  {
+    name: 'plugin_source_contracts',
+    path: 'tests/plugin_source_contracts.rs',
+    requiredFeatures: ['plugin-source'],
+  },
+];
+
+export const aiAdaptersIntegrationTestTargets = [
+  {
+    name: 'ai_protocol_contracts',
+    path: 'tests/ai_protocol_contracts.rs',
+    leaves: [
+      'tests/ai_protocol_contracts/model_selector.rs',
+      'tests/ai_protocol_contracts/openai_empty_content_parts.rs',
+    ],
+    forbidRequiredFeatures: true,
+  },
+  {
+    name: 'ai_stream_contracts',
+    path: 'tests/ai_stream_contracts.rs',
+    leaves: [
+      'tests/ai_stream_contracts/common.rs',
+      'tests/ai_stream_contracts/stream_processor_anthropic.rs',
+      'tests/ai_stream_contracts/stream_processor_openai.rs',
+      'tests/ai_stream_contracts/stream_processor_tool_arguments.rs',
+      'tests/ai_stream_contracts/stream_replay_regressions.rs',
+      'tests/ai_stream_contracts/stream_test_harness.rs',
+    ],
+    forbidRequiredFeatures: true,
+  },
+];
+
+export const productCapabilitiesIntegrationTestTargets = [
+  {
+    name: 'product_capability_contracts',
+    path: 'tests/product_capability_contracts.rs',
+    leaves: [
+      'tests/product_capability_contracts/plugin_product_shape.rs',
+      'tests/product_capability_contracts/product_capabilities.rs',
+      'tests/product_capability_contracts/product_sdk_assembly.rs',
+    ],
+    forbidRequiredFeatures: true,
+  },
+];
+
+function decodeBasicTomlKey(token) {
+  let decoded = '';
+  const simpleEscapes = new Map([
+    ['b', '\b'], ['t', '\t'], ['n', '\n'], ['f', '\f'], ['r', '\r'],
+    ['"', '"'], ['\\', '\\'],
+  ]);
+  for (let index = 1; index < token.length - 1; index += 1) {
+    if (token[index] !== '\\') {
+      decoded += token[index];
+      continue;
+    }
+    index += 1;
+    const escape = token[index];
+    if (simpleEscapes.has(escape)) {
+      decoded += simpleEscapes.get(escape);
+      continue;
+    }
+    if (escape !== 'u' && escape !== 'U') {
+      return null;
+    }
+    const digitCount = escape === 'u' ? 4 : 8;
+    const hex = token.slice(index + 1, index + 1 + digitCount);
+    if (!new RegExp(`^[0-9a-fA-F]{${digitCount}}$`).test(hex)) {
+      return null;
+    }
+    const codePoint = Number.parseInt(hex, 16);
+    if (codePoint > 0x10FFFF || (codePoint >= 0xD800 && codePoint <= 0xDFFF)) {
+      return null;
+    }
+    decoded += String.fromCodePoint(codePoint);
+    index += digitCount;
+  }
+  return decoded;
+}
+
+function tomlFieldName(line) {
+  const match = line.match(/^([A-Za-z0-9_-]+|'[^']*'|"(?:[^"\\]|\\.)*")\s*=/);
+  if (!match) {
+    return null;
+  }
+  const token = match[1];
+  if (token.startsWith("'")) {
+    return token.slice(1, -1);
+  }
+  return token.startsWith('"') ? decodeBasicTomlKey(token) : token;
+}
+
+function parseTomlStringArrayValue(line) {
+  const equalsIndex = line.indexOf('=');
+  const value = equalsIndex === -1 ? '' : line.slice(equalsIndex + 1).trim();
+  const array = value.match(/^\[(.*)\]\s*(?:#.*)?$/);
+  if (!array) {
+    return null;
+  }
+  const inner = array[1];
+  const values = [];
+  const stringPattern = /'[^']*'|"(?:[^"\\]|\\.)*"/g;
+  let cursor = 0;
+  for (const match of inner.matchAll(stringPattern)) {
+    if (!/^[\s,]*$/.test(inner.slice(cursor, match.index))) {
+      return null;
+    }
+    const token = match[0];
+    const decoded = token.startsWith("'")
+      ? token.slice(1, -1)
+      : decodeBasicTomlKey(token);
+    if (decoded === null) {
+      return null;
+    }
+    values.push(decoded);
+    cursor = match.index + token.length;
+  }
+  return /^[\s,]*$/.test(inner.slice(cursor)) ? values : null;
+}
+
 function parseExplicitTestTargets(manifestText) {
   const targets = [];
   let current = null;
@@ -67,6 +335,10 @@ function parseExplicitTestTargets(manifestText) {
       finishCurrent();
       continue;
     }
+    if (current && tomlFieldName(trimmed) === 'required-features') {
+      current.hasRequiredFeatures = true;
+      current.requiredFeatures = parseTomlStringArrayValue(trimmed);
+    }
     const field = current && trimmed.match(/^(name|path)\s*=\s*"([^"]+)"\s*$/);
     if (field) {
       current[field[1]] = field[2];
@@ -386,12 +658,41 @@ export function validateExplicitIntegrationTestTopology({
   }
 
   const expectedTargetEntries = expectedTargets.map(({ name, path }) => `${name}=${path}`).sort();
-  const actualTargetEntries = parseExplicitTestTargets(manifestText)
+  const actualTargets = parseExplicitTestTargets(manifestText);
+  const actualTargetEntries = actualTargets
     .map(({ name, path }) => `${name ?? '<missing-name>'}=${path ?? '<missing-path>'}`)
     .sort();
   if (actualTargetEntries.join('\n') !== expectedTargetEntries.join('\n')) {
     errors.push(`explicit test targets must be exactly: ${expectedTargetEntries.join(', ')}`);
   }
+  const targetsWithoutRequiredFeatures = new Set(
+    expectedTargets
+      .filter(({ forbidRequiredFeatures }) => forbidRequiredFeatures)
+      .map(({ name, path }) => `${name}=${path}`),
+  );
+  for (const { name, path, hasRequiredFeatures } of actualTargets) {
+    if (hasRequiredFeatures && targetsWithoutRequiredFeatures.has(`${name}=${path}`)) {
+      errors.push(`explicit test target ${name} must not declare required-features`);
+    }
+  }
+  for (const { name, path, requiredFeatures } of expectedTargets) {
+    if (requiredFeatures === undefined) {
+      continue;
+    }
+    const actual = actualTargets.find(
+      (target) => target.name === name && target.path === path,
+    );
+    const actualRequiredFeatures = actual?.requiredFeatures;
+    if (
+      actualRequiredFeatures === null
+      || actualRequiredFeatures === undefined
+      || [...actualRequiredFeatures].sort().join('\n') !== [...requiredFeatures].sort().join('\n')
+    ) {
+      errors.push(
+        `explicit test target ${name} required-features must be exactly: ${requiredFeatures.join(', ')}`,
+      );
+    }
+  }
 
   const expectedRoots = expectedTargets.map(({ path }) => path).sort();
   if ([...topLevelRustFiles].sort().join('\n') !== expectedRoots.join('\n')) {
@@ -399,6 +700,13 @@ export function validateExplicitIntegrationTestTopology({
   }
 
   const leaves = new Set(leafRustFiles);
+  const expectedLeaves = expectedTargets.flatMap(({ leaves: targetLeaves = [] }) => targetLeaves).sort();
+  if (
+    expectedLeaves.length > 0
+    && [...leaves].sort().join('\n') !== expectedLeaves.join('\n')
+  ) {
+    errors.push(`grouped test leaves must be exactly: ${expectedLeaves.join(', ')}`);
+  }
   const referenceCounts = new Map();
   for (const root of expectedRoots) {
     const source = rootSources.get(root);
@@ -543,9 +851,75 @@ export function checkServicesIntegrationsIntegrationTestTopology(root) {
   });
 }
 
+export function checkOpencodeAdapterIntegrationTestTopology(root) {
+  return checkExplicitIntegrationTestTopology(root, {
+    cratePath: 'src/crates/adapters/opencode-adapter',
+    expectedTargets: opencodeAdapterIntegrationTestTargets,
+    ignoredDirectories: ['tests/fixtures'],
+  });
+}
+
+export function checkClaudeCodeAdapterIntegrationTestTopology(root) {
+  return checkExplicitIntegrationTestTopology(root, {
+    cratePath: 'src/crates/adapters/claude-code-adapter',
+    expectedTargets: claudeCodeAdapterIntegrationTestTargets,
+  });
+}
+
+export function checkCodexAdapterIntegrationTestTopology(root) {
+  return checkExplicitIntegrationTestTopology(root, {
+    cratePath: 'src/crates/adapters/codex-adapter',
+    expectedTargets: codexAdapterIntegrationTestTargets,
+  });
+}
+
+export function checkExternalSourcesIntegrationTestTopology(root) {
+  return checkExplicitIntegrationTestTopology(root, {
+    cratePath: 'src/crates/assembly/external-sources',
+    expectedTargets: externalSourcesIntegrationTestTargets,
+  });
+}
+
+export function checkExternalSourceIntegrationTestTopologies(root) {
+  return [
+    ...checkOpencodeAdapterIntegrationTestTopology(root),
+    ...checkClaudeCodeAdapterIntegrationTestTopology(root),
+    ...checkCodexAdapterIntegrationTestTopology(root),
+    ...checkExternalSourcesIntegrationTestTopology(root),
+  ];
+}
+
 export function checkServiceIntegrationTestTopologies(root) {
   return [
     ...checkServicesCoreIntegrationTestTopology(root),
     ...checkServicesIntegrationsIntegrationTestTopology(root),
   ];
 }
+
+export function checkBuildGraphContractIntegrationTestTopologies(root) {
+  const topologies = [
+    ['src/crates/contracts/core-types', coreTypesIntegrationTestTargets],
+    ['src/crates/contracts/runtime-ports', runtimePortsIntegrationTestTargets],
+    ['src/crates/contracts/product-domains', productDomainsIntegrationTestTargets],
+    [
+      'src/crates/adapters/ai-adapters',
+      aiAdaptersIntegrationTestTargets,
+      ['tests/common', 'tests/fixtures'],
+    ],
+    ['src/crates/assembly/product-capabilities', productCapabilitiesIntegrationTestTargets],
+  ];
+  return topologies.flatMap(([cratePath, expectedTargets, ignoredDirectories]) => (
+    checkExplicitIntegrationTestTopology(root, {
+      cratePath,
+      expectedTargets,
+      ignoredDirectories,
+    })
+  ));
+}
+
+export function checkReviewedIntegrationTestTopologies(root) {
+  return [
+    ...checkServiceIntegrationTestTopologies(root),
+    ...checkBuildGraphContractIntegrationTestTopologies(root),
+  ];
+}
diff --git a/scripts/core-boundaries/manifest-feature-helpers.mjs b/scripts/core-boundaries/manifest-feature-helpers.mjs
index 4445e20707..618f04ca59 100644
--- a/scripts/core-boundaries/manifest-feature-helpers.mjs
+++ b/scripts/core-boundaries/manifest-feature-helpers.mjs
@@ -10,15 +10,64 @@ export function featureReferencesDependency(feature, depName) {
   );
 }
 
+export function featureReferencesOptionalDependencyOwner(feature, depName) {
+  return Boolean(
+    featureReferencesDependency(feature, depName)
+      || feature?.refs.some((reference) => reference.startsWith(`${depName}?/`)),
+  );
+}
+
 export function featureReferencesFeature(feature, featureName) {
   return Boolean(feature && feature.refs.includes(featureName));
 }
 
-export function unexpectedDependencyOwnerFeatures(features, dependency) {
+function featureTransitivelyReferencesOptionalDependencyOwner(
+  features,
+  featureName,
+  depName,
+  visiting = new Set(),
+) {
+  if (visiting.has(featureName)) {
+    return false;
+  }
+  const feature = features.get(featureName);
+  if (featureReferencesOptionalDependencyOwner(feature, depName)) {
+    return true;
+  }
+  const nextVisiting = new Set(visiting).add(featureName);
+  return Boolean(feature?.refs.some((reference) =>
+    features.has(reference)
+      && featureTransitivelyReferencesOptionalDependencyOwner(
+        features,
+        reference,
+        depName,
+        nextVisiting,
+      )));
+}
+
+export function unexpectedDependencyOwnerFeatures(
+  features,
+  dependency,
+  reviewedAggregateFeatures = new Set(),
+) {
   return [...features.entries()].filter(
-    ([featureName, feature]) =>
-      featureReferencesDependency(feature, dependency.depName)
-      && !dependency.ownerFeatures.includes(featureName),
+    ([featureName, feature]) => {
+      if (dependency.ownerFeatures.includes(featureName)) {
+        return false;
+      }
+      const directlyReferencesOwner = featureReferencesOptionalDependencyOwner(
+        feature,
+        dependency.depName,
+      );
+      if (reviewedAggregateFeatures.has(featureName)) {
+        return directlyReferencesOwner;
+      }
+      return featureTransitivelyReferencesOptionalDependencyOwner(
+        features,
+        featureName,
+        dependency.depName,
+      );
+    },
   );
 }
 
diff --git a/scripts/core-boundaries/peer-command-policy.mjs b/scripts/core-boundaries/peer-command-policy.mjs
new file mode 100644
index 0000000000..7be725188d
--- /dev/null
+++ b/scripts/core-boundaries/peer-command-policy.mjs
@@ -0,0 +1,137 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Peer Device Mode controller/peer command ownership boundary.
+ *
+ * The controller-side deny list in the Web UI transport adapter is an
+ * optimization: it keeps a controller-owned command on the controller without
+ * a round trip. It is not the boundary. A controller running an older build,
+ * or any non-Web-UI controller, still reaches a peer host over HostInvoke, so
+ * each peer host must independently refuse every controller-owned command.
+ *
+ * The enforced direction is therefore one-way: whatever the controller refuses
+ * to send, a peer host must also refuse to run. A host denying more than the
+ * controller is safe and stays allowed.
+ */
+
+const FE_ADAPTER = 'src/web-ui/src/infrastructure/api/adapters/peer-device-adapter.ts';
+const DESKTOP_HOST = 'src/apps/desktop/src/api/peer_host_invoke.rs';
+const CLI_HOST = 'src/apps/cli/src/peer_host/deny.rs';
+
+/**
+ * Commands the CLI peer host answers before the deny-list check, so they are
+ * intentionally absent from its list. See `src/apps/cli/src/peer_host/dispatch.rs`.
+ */
+const CLI_PRE_HANDLED_COMMANDS = new Set([
+  'peer_control_attach',
+  'peer_control_detach',
+  'peer_mode_ping',
+  'account_cancel_pending_login',
+]);
+
+function stripLineComments(text) {
+  return text.replace(/\/\/[^\n]*/g, '');
+}
+
+function parseTypeScriptSet(source, name) {
+  const match = new RegExp(`const ${name}\\s*=\\s*new Set\\(\\[(.*?)\\n\\]\\);`, 's').exec(source);
+  if (!match) {
+    return null;
+  }
+  return new Set(Array.from(stripLineComments(match[1]).matchAll(/'([^']+)'/g), m => m[1]));
+}
+
+function parseRustSlice(source, name) {
+  const match = new RegExp(`static ${name}[^=]*=\\s*&\\[(.*?)\\n\\];`, 's').exec(source);
+  if (!match) {
+    return null;
+  }
+  return new Set(Array.from(stripLineComments(match[1]).matchAll(/"([^"]+)"/g), m => m[1]));
+}
+
+export function checkPeerCommandPolicySync(root) {
+  const failures = [];
+
+  const read = (relativePath) => {
+    try {
+      return readFileSync(join(root, relativePath), 'utf8');
+    } catch {
+      failures.push({
+        path: relativePath,
+        line: 1,
+        message:
+          'Peer command policy check could not read this file; update scripts/core-boundaries/peer-command-policy.mjs if it moved',
+      });
+      return null;
+    }
+  };
+
+  const feSource = read(FE_ADAPTER);
+  const desktopSource = read(DESKTOP_HOST);
+  const cliSource = read(CLI_HOST);
+  if (!feSource || !desktopSource || !cliSource) {
+    return failures;
+  }
+
+  const controllerDenied = parseTypeScriptSet(feSource, 'LOCAL_ONLY_COMMANDS');
+  const desktopDenied = parseRustSlice(desktopSource, 'LOCAL_ONLY_COMMANDS');
+  const cliDenied = parseRustSlice(cliSource, 'LOCAL_ONLY_COMMANDS');
+
+  for (const [path, parsed] of [
+    [FE_ADAPTER, controllerDenied],
+    [DESKTOP_HOST, desktopDenied],
+    [CLI_HOST, cliDenied],
+  ]) {
+    if (!parsed) {
+      failures.push({
+        path,
+        line: 1,
+        message:
+          'Could not parse LOCAL_ONLY_COMMANDS; keep the declaration shape the peer command policy check expects',
+      });
+    }
+  }
+  if (!controllerDenied || !desktopDenied || !cliDenied) {
+    return failures;
+  }
+
+  const missingOnDesktop = [...controllerDenied].filter(command => !desktopDenied.has(command));
+  if (missingOnDesktop.length > 0) {
+    failures.push({
+      path: DESKTOP_HOST,
+      line: 1,
+      message:
+        `Desktop peer host must refuse every controller-owned command. Missing from LOCAL_ONLY_COMMANDS: ${missingOnDesktop.sort().join(', ')}. ` +
+        'An older or non-Web-UI controller can still HostInvoke these onto this peer',
+    });
+  }
+
+  const missingOnCli = [...controllerDenied].filter(
+    command => !cliDenied.has(command) && !CLI_PRE_HANDLED_COMMANDS.has(command),
+  );
+  if (missingOnCli.length > 0) {
+    failures.push({
+      path: CLI_HOST,
+      line: 1,
+      message:
+        `CLI peer host must refuse every controller-owned command. Missing from LOCAL_ONLY_COMMANDS: ${missingOnCli.sort().join(', ')}. ` +
+        'An older or non-Web-UI controller can still HostInvoke these onto this peer',
+    });
+  }
+
+  const staleCliExceptions = [...CLI_PRE_HANDLED_COMMANDS].filter(
+    command => !controllerDenied.has(command),
+  );
+  if (staleCliExceptions.length > 0) {
+    failures.push({
+      path: CLI_HOST,
+      line: 1,
+      message:
+        `Stale CLI pre-handled exception(s) in scripts/core-boundaries/peer-command-policy.mjs: ${staleCliExceptions.sort().join(', ')}. ` +
+        'Remove the exception once the controller no longer treats the command as controller-owned',
+    });
+  }
+
+  return failures;
+}
diff --git a/scripts/core-boundaries/rules/crate-layout.mjs b/scripts/core-boundaries/rules/crate-layout.mjs
index 47d3c80247..54d9d872a2 100644
--- a/scripts/core-boundaries/rules/crate-layout.mjs
+++ b/scripts/core-boundaries/rules/crate-layout.mjs
@@ -39,6 +39,7 @@ export const crateLayoutRules = [
   { crateName: 'claude-code-adapter', layer: 'adapters', path: 'src/crates/adapters/claude-code-adapter' },
   { crateName: 'codex-adapter', layer: 'adapters', path: 'src/crates/adapters/codex-adapter' },
   { crateName: 'opencode-adapter', layer: 'adapters', path: 'src/crates/adapters/opencode-adapter' },
+  { crateName: 'dsh-adapter', layer: 'adapters', path: 'src/crates/adapters/dsh-adapter' },
   { crateName: 'static-hook-support', layer: 'adapters', path: 'src/crates/adapters/static-hook-support' },
   { crateName: 'transport', layer: 'adapters', path: 'src/crates/adapters/transport' },
   { crateName: 'webdriver', layer: 'adapters', path: 'src/crates/adapters/webdriver' },
diff --git a/scripts/core-boundaries/rules/crate-rules.mjs b/scripts/core-boundaries/rules/crate-rules.mjs
index ab5288042e..b46e630bc9 100644
--- a/scripts/core-boundaries/rules/crate-rules.mjs
+++ b/scripts/core-boundaries/rules/crate-rules.mjs
@@ -10,6 +10,7 @@ const agentRuntimeIpcForbiddenDeps = [
   'bitfun-codex-adapter',
   'bitfun-core',
   'bitfun-core-types',
+  'bitfun-dsh-adapter',
   'bitfun-external-sources',
   'bitfun-harness',
   'bitfun-opencode-adapter',
@@ -24,7 +25,6 @@ const agentRuntimeIpcForbiddenDeps = [
   'bitfun-static-hook-support',
   'bitfun-tool-call-jsonrepair',
   'bitfun-tool-packs',
-  'bitfun-transport',
   'bitfun-webdriver',
   'terminal-core',
   'tool-runtime',
@@ -62,6 +62,7 @@ export const noCoreDependencyCrates = [
   'product-domains',
   'claude-code-adapter',
   'codex-adapter',
+  'dsh-adapter',
   'opencode-adapter',
   'static-hook-support',
   'external-sources',
@@ -117,6 +118,19 @@ export const forbiddenManifestDependencyRules = [
     message:
       'only bitfun-core product-full assembly may register bitfun-opencode-adapter through reviewed capability composition roots',
   },
+  {
+    dependencyNames: ['bitfun-dsh-adapter'],
+    scanRoots: ['src/apps', 'src/crates', 'BitFun-Installer/src-tauri'],
+    workspaceManifestPath: 'Cargo.toml',
+    allowManifestPaths: [
+      'src/crates/adapters/dsh-adapter/Cargo.toml',
+      'src/crates/assembly/core/Cargo.toml',
+    ],
+    reason:
+      'DeepSeek Harness adapter production dependencies are limited to the reviewed product composition root',
+    message:
+      'only bitfun-core product-full assembly may register bitfun-dsh-adapter through reviewed capability composition roots',
+  },
   ...[
     ['bitfun-claude-code-adapter', 'claude-code-adapter'],
     ['bitfun-codex-adapter', 'codex-adapter'],
@@ -462,7 +476,7 @@ export const dependencyProfileRules = [
     crateName: 'agent-runtime-ipc',
     profileName: 'private Shared TUI local IPC profile',
     reason:
-      'agent-runtime-ipc may share stable event and Runtime DTO contracts but must not acquire Runtime owners, SDK Host, services, remote transports, or product implementations',
+      'agent-runtime-ipc may share stable DTO contracts and protocol-neutral bitfun-transport mechanics but must not acquire Runtime owners, SDK Host, services, remote transports, or product implementations',
     forbiddenNonOptionalDeps: agentRuntimeIpcForbiddenDeps,
   },
   {
@@ -476,6 +490,7 @@ export const dependencyProfileRules = [
       'bitfun-services-integrations',
       'bitfun-product-capabilities',
       'bitfun-product-domains',
+      'bitfun-agent-tools',
       'bitfun-relay-service',
       'bitfun-tool-packs',
       'chrono-tz',
@@ -484,6 +499,7 @@ export const dependencyProfileRules = [
       'eventsource-stream',
       'filetime',
       'flate2',
+      'fluent-bundle',
       'fs2',
       'git2',
       'glob',
@@ -513,6 +529,8 @@ export const dependencyProfileRules = [
       'terminal-core',
       'tool-runtime',
       'tokio-tungstenite',
+      'bitfun-transport',
+      'unic-langid',
       'win32job',
       'x25519-dalek',
     ],
@@ -537,9 +555,11 @@ export const dependencyProfileRules = [
       'ignore',
       'libc',
       'notify',
+      'regex',
       'rusqlite',
       'serde_yaml',
       'sha2',
+      'similar',
       'which',
       'win32job',
       'windows',
diff --git a/scripts/core-boundaries/rules/feature-rules.mjs b/scripts/core-boundaries/rules/feature-rules.mjs
index a33661360f..10cc1fb43e 100644
--- a/scripts/core-boundaries/rules/feature-rules.mjs
+++ b/scripts/core-boundaries/rules/feature-rules.mjs
@@ -16,6 +16,19 @@ export const servicesReqwestOwnerFeatures = [
   'web-tools',
 ];
 
+export const guardedEmptyInternalDefaultManifestPaths = [
+  'src/crates/assembly/core/Cargo.toml',
+  'src/crates/assembly/product-capabilities/Cargo.toml',
+  'src/crates/contracts/product-domains/Cargo.toml',
+  'src/crates/contracts/runtime-ports/Cargo.toml',
+  'src/crates/execution/agent-runtime/Cargo.toml',
+  'src/crates/execution/tool-contracts/Cargo.toml',
+  'src/crates/execution/tool-execution/Cargo.toml',
+  'src/crates/execution/tool-provider-groups/Cargo.toml',
+  'src/crates/services/services-core/Cargo.toml',
+  'src/crates/services/services-integrations/Cargo.toml',
+];
+
 export const optionalDependencyFeatureOwnerRules = [
   {
     crateName: 'services-core',
@@ -36,8 +49,19 @@ export const optionalDependencyFeatureOwnerRules = [
       { depName: 'ignore', ownerFeatures: ['filesystem'] },
       { depName: 'libc', ownerFeatures: ['local-storage', 'process-runtime'] },
       { depName: 'notify', ownerFeatures: ['lsp'] },
+      {
+        depName: 'regex',
+        ownerFeatures: [
+          'diagnostics',
+          'filesystem',
+          'local-storage',
+          'markdown',
+          'workspace-instructions',
+        ],
+      },
       { depName: 'rusqlite', ownerFeatures: ['permission'] },
       { depName: 'serde_yaml', ownerFeatures: ['markdown', 'workspace-instructions'] },
+      { depName: 'similar', ownerFeatures: ['diff', 'local-storage'] },
       {
         depName: 'sha2',
         ownerFeatures: [
@@ -52,14 +76,63 @@ export const optionalDependencyFeatureOwnerRules = [
       { depName: 'win32job', ownerFeatures: ['process-runtime'] },
       { depName: 'windows', ownerFeatures: ['json-io', 'local-storage', 'process-runtime'] },
       { depName: 'zip', ownerFeatures: ['lsp'] },
+      {
+        depName: 'tokio',
+        ownerFeatures: [
+          'diff',
+          'filesystem',
+          'json-io',
+          'local-storage',
+          'lsp',
+          'permission',
+          'process-runtime',
+          'workspace-instructions',
+          'workspace-runtime',
+          'workspace-text-runtime',
+        ],
+      },
     ],
   },
   {
     crateName: 'runtime-ports',
+    reviewedAggregateFeatures: ['tool-runtime-handles'],
+    reason:
+      'runtime-ports optional capabilities must stay behind their exact contract slice',
+    dependencies: [
+      { depName: 'anyhow', ownerFeatures: ['workspace-ports'] },
+      { depName: 'bitfun-core-types', ownerFeatures: ['agent-api', 'ts'] },
+      { depName: 'bitfun-product-domains', ownerFeatures: ['permission', 'ts'] },
+      { depName: 'tokio', ownerFeatures: ['remote-exec-port', 'terminal-port'] },
+      { depName: 'tokio-util', ownerFeatures: ['workspace-ports'] },
+      { depName: 'ts-rs', ownerFeatures: ['ts'] },
+    ],
+  },
+  {
+    crateName: 'agent-runtime',
+    reviewedAggregateFeatures: ['native-hook-runtime'],
     reason:
-      'runtime-ports may expose product-domain permission ports only through the explicit permission contract slice',
+      'agent-runtime optional dependencies must stay behind the full runtime, DeepResearch, or native-hook owner slice',
     dependencies: [
-      { depName: 'bitfun-product-domains', ownerFeatures: ['permission'] },
+      { depName: 'async-trait', ownerFeatures: ['agent-runtime'] },
+      { depName: 'bitfun-agent-stream', ownerFeatures: ['agent-runtime'] },
+      { depName: 'bitfun-agent-tools', ownerFeatures: ['agent-runtime'] },
+      { depName: 'bitfun-core-types', ownerFeatures: ['agent-runtime'] },
+      { depName: 'bitfun-events', ownerFeatures: ['agent-runtime'] },
+      { depName: 'bitfun-harness', ownerFeatures: ['agent-runtime'] },
+      { depName: 'bitfun-runtime-ports', ownerFeatures: ['agent-runtime'] },
+      { depName: 'bitfun-runtime-services', ownerFeatures: ['agent-runtime'] },
+      { depName: 'dashmap', ownerFeatures: ['agent-runtime'] },
+      { depName: 'hex', ownerFeatures: ['agent-runtime'] },
+      { depName: 'log', ownerFeatures: ['agent-runtime', 'native-hook-runtime'] },
+      { depName: 'regex', ownerFeatures: ['agent-runtime', 'deep-research', 'native-hook-settings'] },
+      { depName: 'serde', ownerFeatures: ['agent-runtime', 'native-hook-runtime'] },
+      { depName: 'serde_json', ownerFeatures: ['agent-runtime', 'native-hook-runtime', 'native-hook-settings'] },
+      { depName: 'serde_yaml', ownerFeatures: ['agent-runtime'] },
+      { depName: 'sha2', ownerFeatures: ['agent-runtime'] },
+      { depName: 'thiserror', ownerFeatures: ['agent-runtime'] },
+      { depName: 'tokio', ownerFeatures: ['agent-runtime', 'native-hook-runtime'] },
+      { depName: 'tokio-util', ownerFeatures: ['agent-runtime'] },
+      { depName: 'uuid', ownerFeatures: ['agent-runtime'] },
     ],
   },
   {
@@ -68,14 +141,20 @@ export const optionalDependencyFeatureOwnerRules = [
       'bitfun-core product/runtime optional dependencies must stay owned by explicit feature gates',
     dependencies: [
       { depName: 'axum', ownerFeatures: ['debug-log', 'mcp-runtime'] },
-      { depName: 'bitfun-ai-adapters', ownerFeatures: ['ai-adapter-runtime'] },
-      { depName: 'bitfun-agent-runtime', ownerFeatures: ['agent-runtime'] },
+      { depName: 'base64', ownerFeatures: ['agent-runtime', 'dispatch-store'] },
+      {
+        depName: 'bitfun-ai-adapters',
+        ownerFeatures: ['ai-adapter-runtime', 'subscription-auth'],
+      },
+      { depName: 'bitfun-agent-runtime', ownerFeatures: ['agent-runtime', 'deep-research'] },
       { depName: 'bitfun-agent-stream', ownerFeatures: ['agent-runtime'] },
+      { depName: 'bitfun-agent-tools', ownerFeatures: ['agent-runtime', 'local-storage', 'mcp-runtime'] },
       { depName: 'bitfun-claude-code-adapter', ownerFeatures: ['external-sources'] },
       { depName: 'bitfun-codex-adapter', ownerFeatures: ['external-sources'] },
       { depName: 'bitfun-external-sources', ownerFeatures: ['external-sources'] },
       { depName: 'bitfun-harness', ownerFeatures: ['agent-runtime'] },
       { depName: 'bitfun-opencode-adapter', ownerFeatures: ['external-sources'] },
+      { depName: 'bitfun-dsh-adapter', ownerFeatures: ['external-sources'] },
       { depName: 'bitfun-plugin-runtime-client', ownerFeatures: ['plugin-runtime'] },
       { depName: 'bitfun-product-capabilities', ownerFeatures: ['product-capabilities'] },
       {
@@ -86,6 +165,7 @@ export const optionalDependencyFeatureOwnerRules = [
           'function-agents',
           'plugin-source',
           'tools-miniapp',
+          'ts',
         ],
       },
       { depName: 'bitfun-runtime-services', ownerFeatures: ['runtime-services'] },
@@ -110,6 +190,7 @@ export const optionalDependencyFeatureOwnerRules = [
           'script-tool-runtime',
           'ssh-remote',
           'tools-miniapp',
+          'ts',
           'web-tools',
           'workspace-search',
         ],
@@ -134,12 +215,15 @@ export const optionalDependencyFeatureOwnerRules = [
       { depName: 'dashmap', ownerFeatures: ['agent-runtime'] },
       { depName: 'filetime', ownerFeatures: ['agent-runtime'] },
       { depName: 'flate2', ownerFeatures: ['agent-runtime'] },
+      { depName: 'fluent-bundle', ownerFeatures: ['i18n-runtime'] },
       { depName: 'fs2', ownerFeatures: ['agent-runtime'] },
+      { depName: 'futures', ownerFeatures: ['agent-runtime'] },
       { depName: 'image', ownerFeatures: ['agent-runtime'] },
       { depName: 'include_dir', ownerFeatures: ['agent-runtime'] },
       { depName: 'indexmap', ownerFeatures: ['agent-runtime'] },
       { depName: 'md5', ownerFeatures: ['agent-runtime'] },
-      { depName: 'reqwest', ownerFeatures: ['ai-adapter-runtime', 'mcp-runtime', 'tools-miniapp'] },
+      { depName: 'reqwest', ownerFeatures: ['mcp-runtime', 'tools-miniapp'] },
+      { depName: 'regex', ownerFeatures: ['agent-runtime'] },
       { depName: 'rusqlite', ownerFeatures: ['agent-runtime'] },
       { depName: 'semver', ownerFeatures: ['tools-miniapp'] },
       { depName: 'serde_yaml', ownerFeatures: ['workspace-runtime'] },
@@ -147,8 +231,13 @@ export const optionalDependencyFeatureOwnerRules = [
       { depName: 'terminal-core', ownerFeatures: ['terminal'] },
       { depName: 'notify', ownerFeatures: ['lsp', 'workspace-watch'] },
       { depName: 'tokio-tungstenite', ownerFeatures: ['browser-control'] },
+      { depName: 'tokio-util', ownerFeatures: ['agent-runtime', 'debug-log'] },
       { depName: 'tower-http', ownerFeatures: ['debug-log'] },
-      { depName: 'tool-runtime', ownerFeatures: ['agent-runtime', 'tools-basic', 'web-tools'] },
+      { depName: 'unic-langid', ownerFeatures: ['i18n-runtime'] },
+      {
+        depName: 'tool-runtime',
+        ownerFeatures: ['agent-runtime', 'document-read', 'web-tools'],
+      },
     ],
   },
   {
@@ -158,10 +247,10 @@ export const optionalDependencyFeatureOwnerRules = [
     dependencies: [
       { depName: 'aes', ownerFeatures: ['remote-connect'] },
       { depName: 'aes-gcm', ownerFeatures: ['feedback', 'mcp', 'remote-connect', 'remote-ssh-concrete'] },
-      { depName: 'anyhow', ownerFeatures: ['browser-control', 'debug-log', 'feedback', 'mcp', 'remote-connect', 'remote-ssh', 'remote-ssh-concrete'] },
+      { depName: 'anyhow', ownerFeatures: ['browser-control', 'debug-log', 'deep-research', 'mcp', 'remote-connect', 'remote-ssh', 'remote-ssh-concrete'] },
       {
         depName: 'async-trait',
-        ownerFeatures: ['feedback', 'git', 'mcp', 'miniapp-market', 'remote-connect', 'remote-ssh', 'remote-ssh-concrete', 'review-platform', 'script-tool-runtime', 'speech', 'workspace-search'],
+        ownerFeatures: ['feedback', 'deep-research', 'git', 'mcp', 'remote-connect', 'remote-ssh', 'remote-ssh-concrete', 'review-platform', 'script-tool-runtime', 'speech', 'workspace-search'],
       },
       {
         depName: 'base64',
@@ -169,8 +258,8 @@ export const optionalDependencyFeatureOwnerRules = [
       },
       { depName: 'bitfun-agent-runtime', ownerFeatures: ['deep-research', 'hook-import'] },
       { depName: 'bitfun-core-types', ownerFeatures: ['remote-connect', 'speech'] },
-      { depName: 'bitfun-product-domains', ownerFeatures: ['canvas-runtime', 'feedback', 'function-agents', 'hook-import', 'miniapp-market', 'miniapp-runtime', 'plugin-source', 'privacy'] },
-      { depName: 'bitfun-runtime-ports', ownerFeatures: ['git', 'remote-connect', 'remote-ssh', 'remote-ssh-concrete', 'script-tool-runtime'] },
+      { depName: 'bitfun-product-domains', ownerFeatures: ['canvas-runtime', 'feedback', 'function-agents', 'hook-import', 'miniapp-market', 'miniapp-runtime', 'plugin-source'] },
+      { depName: 'bitfun-runtime-ports', ownerFeatures: ['deep-research', 'git', 'remote-connect', 'remote-ssh', 'remote-ssh-concrete', 'script-tool-runtime'] },
       {
         depName: 'bitfun-services-core',
         ownerFeatures: ['browser-control', 'git', 'hook-import', 'mcp', 'miniapp-runtime', 'process-tree', 'remote-connect', 'remote-ssh', 'review-platform', 'workspace-search'],
@@ -236,11 +325,320 @@ export const optionalDependencyFeatureOwnerRules = [
   },
 ];
 
+function capabilityEdge(features = [], overrides = {}) {
+  return {
+    kind: 'normal',
+    optional: false,
+    rename: null,
+    target: null,
+    features,
+    ...overrides,
+  };
+}
+
+function capabilityForwarder(sourceFeature, feature, weak = false) {
+  return { sourceFeature, feature, weak };
+}
+
+function capabilityConsumer(edges, forwarders = [], activators = [], aggregates = []) {
+  return { edges, forwarders, activators, aggregates };
+}
+
+export const capabilityContractDependencyRules = [
+  {
+    packageName: 'bitfun-runtime-ports',
+    manifestPath: 'src/crates/contracts/runtime-ports/Cargo.toml',
+    featureProfiles: {
+      default: [],
+      'agent-api': ['dep:bitfun-core-types'],
+      'git-port': [],
+      permission: ['dep:bitfun-product-domains'],
+      'plugin-runtime': [],
+      'remote-exec-port': ['dep:tokio'],
+      'remote-workspace-ports': [],
+      'runtime-event-port': [],
+      'script-tool-runtime': [],
+      'terminal-port': ['dep:tokio'],
+      'tool-runtime-handles': ['workspace-ports', 'terminal-port', 'remote-exec-port'],
+      ts: [
+        'dep:ts-rs',
+        'agent-api',
+        'permission',
+        'bitfun-core-types/ts',
+        'bitfun-product-domains?/ts',
+      ],
+      'workspace-ports': ['dep:anyhow', 'dep:tokio-util'],
+    },
+    consumers: new Map([
+      ['bitfun-agent-runtime', capabilityConsumer([
+        capabilityEdge([
+          'agent-api',
+          'git-port',
+          'permission',
+          'plugin-runtime',
+          'remote-workspace-ports',
+          'runtime-event-port',
+          'terminal-port',
+          'workspace-ports',
+        ], { optional: true }),
+      ], [], ['agent-runtime'])],
+      ['bitfun-agent-runtime-ipc', capabilityConsumer([
+        capabilityEdge(['agent-api', 'git-port']),
+      ])],
+      ['bitfun-agent-tools', capabilityConsumer([capabilityEdge()])],
+      ['bitfun-app-server', capabilityConsumer([capabilityEdge(['agent-api'])])],
+      ['bitfun-app-server-protocol', capabilityConsumer(
+        [capabilityEdge(['agent-api', 'git-port'])],
+        [capabilityForwarder('ts', 'ts')],
+      )],
+      ['bitfun-cli', capabilityConsumer([
+        capabilityEdge(['agent-api', 'git-port', 'permission', 'plugin-runtime', 'workspace-ports']),
+      ])],
+      ['bitfun-core', capabilityConsumer(
+        [capabilityEdge(['permission', 'workspace-ports'])],
+        [
+          capabilityForwarder('agent-runtime', 'agent-api'),
+          capabilityForwarder('agent-runtime', 'git-port'),
+          capabilityForwarder('agent-runtime', 'remote-exec-port'),
+          capabilityForwarder('agent-runtime', 'remote-workspace-ports'),
+          capabilityForwarder('agent-runtime', 'runtime-event-port'),
+          capabilityForwarder('agent-runtime', 'terminal-port'),
+          capabilityForwarder('agent-runtime', 'tool-runtime-handles'),
+          capabilityForwarder('agent-runtime', 'workspace-ports'),
+          capabilityForwarder('plugin-runtime', 'plugin-runtime'),
+          capabilityForwarder('script-tool-runtime', 'script-tool-runtime'),
+          capabilityForwarder('ts', 'ts'),
+        ],
+        [],
+        ['external-sources', 'mcp-runtime', 'product-full', 'remote-connect', 'tools-mcp'],
+      )],
+      ['bitfun-desktop', capabilityConsumer([
+        capabilityEdge(['agent-api', 'permission', 'workspace-ports']),
+      ])],
+      ['bitfun-opencode-adapter', capabilityConsumer([
+        capabilityEdge(['plugin-runtime']),
+        capabilityEdge(['script-tool-runtime'], { kind: 'dev' }),
+      ])],
+      ['bitfun-dsh-adapter', capabilityConsumer([
+        capabilityEdge(['plugin-runtime']),
+      ])],
+      ['bitfun-plugin-runtime-client', capabilityConsumer([
+        capabilityEdge(['plugin-runtime']),
+      ])],
+      ['bitfun-product-capabilities', capabilityConsumer([
+        capabilityEdge(['plugin-runtime']),
+        capabilityEdge(['agent-api'], { kind: 'dev' }),
+      ])],
+      ['bitfun-runtime-services', capabilityConsumer([
+        capabilityEdge([
+          'git-port',
+          'remote-exec-port',
+          'remote-workspace-ports',
+          'runtime-event-port',
+          'terminal-port',
+          'workspace-ports',
+        ]),
+      ])],
+      ['bitfun-sdk-host', capabilityConsumer([
+        capabilityEdge(['agent-api']),
+        capabilityEdge(['permission'], { kind: 'dev' }),
+      ])],
+      ['bitfun-services-core', capabilityConsumer(
+        [capabilityEdge([], { optional: true })],
+        [
+          capabilityForwarder('permission', 'permission'),
+          capabilityForwarder('workspace-runtime', 'runtime-event-port'),
+          capabilityForwarder('workspace-runtime', 'workspace-ports'),
+        ],
+        ['permission', 'workspace-runtime'],
+      )],
+      ['bitfun-services-integrations', capabilityConsumer(
+        [capabilityEdge([], { optional: true })],
+        [
+          capabilityForwarder('deep-research', 'workspace-ports'),
+          capabilityForwarder('git', 'git-port'),
+          capabilityForwarder('remote-connect', 'agent-api'),
+          capabilityForwarder('remote-connect', 'remote-workspace-ports'),
+          capabilityForwarder('remote-ssh', 'remote-exec-port'),
+          capabilityForwarder('remote-ssh', 'remote-workspace-ports'),
+          capabilityForwarder('remote-ssh', 'workspace-ports'),
+          capabilityForwarder('script-tool-runtime', 'script-tool-runtime'),
+        ],
+        ['remote-ssh-concrete'],
+        ['function-agents', 'product-full'],
+      )],
+      ['terminal-core', capabilityConsumer([
+        capabilityEdge(['terminal-port']),
+      ])],
+      ['tool-runtime', capabilityConsumer([capabilityEdge()])],
+    ]),
+  },
+  {
+    packageName: 'bitfun-agent-tools',
+    manifestPath: 'src/crates/execution/tool-contracts/Cargo.toml',
+    featureProfiles: {
+      default: [],
+      'acp-bridge': [],
+      'computer-use-contract': [],
+      'element-token': [],
+      'mcp-bridge': [],
+    },
+    consumers: new Map([
+      ['bitfun-acp', capabilityConsumer(
+        [capabilityEdge([], { optional: true })],
+        [capabilityForwarder('client', 'acp-bridge')],
+        ['server'],
+        ['default'],
+      )],
+      ['bitfun-agent-runtime', capabilityConsumer(
+        [capabilityEdge([], { optional: true })],
+        [],
+        ['agent-runtime'],
+      )],
+      ['bitfun-agent-stream', capabilityConsumer([
+        capabilityEdge([], { kind: 'dev' }),
+      ])],
+      ['bitfun-cli', capabilityConsumer([capabilityEdge()])],
+      ['bitfun-core', capabilityConsumer(
+        [capabilityEdge([], { optional: true })],
+        [
+          capabilityForwarder('agent-runtime', 'computer-use-contract'),
+          capabilityForwarder('mcp-runtime', 'mcp-bridge'),
+        ],
+        ['agent-runtime', 'local-storage'],
+        [
+          'dispatch-store',
+          'external-sources',
+          'plugin-runtime',
+          'product-full',
+          'remote-connect',
+          'remote-workspace',
+          'ssh-remote',
+          'tools-basic',
+          'tools-mcp',
+          'workspace-runtime',
+          'workspace-search',
+          'workspace-watch',
+        ],
+      )],
+      ['bitfun-desktop', capabilityConsumer([
+        capabilityEdge(['element-token']),
+      ])],
+      ['bitfun-services-integrations', capabilityConsumer(
+        [capabilityEdge([], { optional: true })],
+        [capabilityForwarder('mcp', 'mcp-bridge')],
+        ['remote-connect'],
+        ['product-full'],
+      )],
+      ['tool-runtime', capabilityConsumer([capabilityEdge()])],
+    ]),
+  },
+  {
+    packageName: 'bitfun-agent-runtime',
+    manifestPath: 'src/crates/execution/agent-runtime/Cargo.toml',
+    featureProfiles: {
+      default: [],
+      'deep-research': ['dep:regex'],
+      'native-hook-settings': ['dep:regex', 'dep:serde_json'],
+      'native-hook-runtime': [
+        'native-hook-settings',
+        'dep:log',
+        'dep:serde',
+        'dep:serde_json',
+        'dep:tokio',
+        'tokio/io-util',
+        'tokio/macros',
+        'tokio/process',
+        'tokio/rt',
+        'tokio/time',
+      ],
+      'agent-runtime': [
+        'native-hook-runtime',
+        'dep:async-trait',
+        'dep:bitfun-agent-stream',
+        'dep:bitfun-agent-tools',
+        'dep:bitfun-core-types',
+        'dep:bitfun-events',
+        'dep:bitfun-harness',
+        'dep:bitfun-runtime-ports',
+        'dep:bitfun-runtime-services',
+        'dep:dashmap',
+        'dep:hex',
+        'dep:log',
+        'dep:regex',
+        'dep:serde',
+        'dep:serde_json',
+        'dep:serde_yaml',
+        'dep:sha2',
+        'dep:thiserror',
+        'dep:tokio',
+        'dep:tokio-util',
+        'dep:uuid',
+        'tokio/macros',
+        'tokio/rt',
+        'tokio/sync',
+      ],
+    },
+    consumers: new Map([
+      ['bitfun-acp', capabilityConsumer(
+        [capabilityEdge([], { optional: true })],
+        [capabilityForwarder('server', 'agent-runtime')],
+        ['server'],
+        ['default'],
+      )],
+      ['bitfun-app-server', capabilityConsumer([
+        capabilityEdge(['agent-runtime']),
+      ])],
+      ['bitfun-cli', capabilityConsumer([
+        capabilityEdge(['agent-runtime']),
+      ])],
+      ['bitfun-core', capabilityConsumer(
+        [capabilityEdge([], { optional: true })],
+        [
+          capabilityForwarder('agent-runtime', 'agent-runtime'),
+          capabilityForwarder('deep-research', 'deep-research', true),
+        ],
+        ['agent-runtime'],
+        ['external-sources', 'mcp-runtime', 'plugin-runtime', 'product-full', 'remote-connect', 'tools-mcp'],
+      )],
+      ['bitfun-desktop', capabilityConsumer([
+        capabilityEdge(['agent-runtime']),
+      ])],
+      ['bitfun-product-capabilities', capabilityConsumer([
+        capabilityEdge(['agent-runtime'], { kind: 'dev' }),
+      ])],
+      ['bitfun-sdk-host', capabilityConsumer([
+        capabilityEdge(['agent-runtime']),
+      ])],
+      ['bitfun-sdk-host-app', capabilityConsumer([
+        capabilityEdge(['agent-runtime']),
+      ])],
+      ['bitfun-server', capabilityConsumer([
+        capabilityEdge(['agent-runtime']),
+      ])],
+      ['bitfun-services-integrations', capabilityConsumer(
+        [capabilityEdge([], { optional: true })],
+        [
+          capabilityForwarder('deep-research', 'deep-research'),
+          capabilityForwarder('hook-import', 'native-hook-settings'),
+        ],
+        ['deep-research', 'hook-import'],
+        ['product-full'],
+      )],
+    ]),
+  },
+];
+
 export const coreProductFullFeatureAssemblyRule = {
   manifestPath: 'src/crates/assembly/core/Cargo.toml',
   featureName: 'product-full',
   requiredFeatureRefs: [
     'agent-runtime',
+    'diagnostics',
+    'diff',
+    'document-read',
+    'subscription-auth',
+    'i18n-runtime',
     'browser-control',
     'deep-research',
     'mcp-runtime',
@@ -283,30 +681,141 @@ export const coreProductFullFeatureAssemblyRule = {
   reason: 'bitfun-core product-full must explicitly assemble current owner feature groups',
 };
 
+export const acpClientCoreFeatures = [
+  'agent-runtime',
+  'ssh-remote',
+];
+
+export const acpServerCoreFeatures = [
+  'agent-runtime',
+  'document-read',
+  'subscription-auth',
+  'deep-research',
+  'lsp',
+  'external-sources',
+  'tools-basic',
+  'tools-git',
+  'tools-mcp',
+  'tools-browser-web',
+  'tools-computer-use',
+  'tools-image-analysis',
+  'tools-miniapp',
+  'tools-canvas',
+  'tools-agent-control',
+];
+
+export const acpClosedFeatureProfileRules = [
+  {
+    manifestPath: 'src/crates/interfaces/acp/Cargo.toml',
+    featureName: 'default',
+    requiredFeatureRefs: ['client', 'server'],
+    exact: true,
+    reason: 'bitfun-acp default must preserve its complete client and server compatibility surface',
+  },
+  {
+    manifestPath: 'src/crates/interfaces/acp/Cargo.toml',
+    featureName: 'client',
+    requiredFeatureRefs: [
+      'bitfun-agent-tools/acp-bridge',
+      'dep:futures',
+      'dep:serde',
+      // The bundled DeepSeek Harness profile: `dirs` locates $DSH_HOME,
+      // `semver` compares the build's minimum dsh version against the installed
+      // one, and `tar` packs the profile for a remote workspace, which receives
+      // it as one stream over its own transport. All three are client-only —
+      // the server surface never launches an agent.
+      'dep:dirs',
+      'dep:semver',
+      'dep:tar',
+      'dep:bitfun-core',
+      ...acpClientCoreFeatures.map((feature) => `bitfun-core/${feature}`),
+    ],
+    exact: true,
+    reason: 'bitfun-acp client must own only external ACP agent and SSH transport capabilities',
+  },
+  {
+    manifestPath: 'src/crates/interfaces/acp/Cargo.toml',
+    featureName: 'server',
+    requiredFeatureRefs: [
+      'dep:bitfun-agent-tools',
+      'dep:bitfun-agent-runtime',
+      'bitfun-agent-runtime/agent-runtime',
+      'dep:bitfun-core-types',
+      'dep:bitfun-core',
+      'dep:sha2',
+      ...acpServerCoreFeatures.map((feature) => `bitfun-core/${feature}`),
+    ],
+    exact: true,
+    reason: 'bitfun-acp server must preserve the reviewed Agent Runtime capability surface without SSH transport',
+  },
+];
+
 export const coreClosedFeatureProfileRules = [
+  {
+    manifestPath: 'src/crates/interfaces/app-server/Cargo.toml',
+    featureName: 'ts',
+    requiredFeatureRefs: ['bitfun-app-server-protocol/ts'],
+    exact: true,
+    reason: 'App Server must delegate TypeScript wire export to the protocol owner',
+  },
+  {
+    manifestPath: 'src/crates/interfaces/app-server-protocol/Cargo.toml',
+    featureName: 'ts',
+    requiredFeatureRefs: [
+      'bitfun-core-types/ts',
+      'bitfun-product-domains/ts',
+      'bitfun-runtime-ports/ts',
+      'dep:ts-rs',
+    ],
+    exact: true,
+    reason: 'App Server Protocol must own the complete behavior-light TypeScript wire surface',
+  },
+  {
+    manifestPath: 'src/crates/assembly/core/Cargo.toml',
+    featureName: 'default',
+    requiredFeatureRefs: [],
+    exact: true,
+    reason: 'bitfun-core default must stay empty so product entrypoints select capabilities explicitly',
+  },
   {
     manifestPath: 'src/crates/assembly/core/Cargo.toml',
     featureName: 'agent-runtime',
     requiredFeatureRefs: [
       'ai-adapter-runtime',
       'dep:bitfun-agent-runtime',
+      'bitfun-agent-runtime/agent-runtime',
       'dep:bitfun-agent-content',
       'dep:bitfun-agent-stream',
+      'dep:bitfun-agent-tools',
+      'bitfun-agent-tools/computer-use-contract',
+      'bitfun-runtime-ports/agent-api',
+      'bitfun-runtime-ports/git-port',
+      'bitfun-runtime-ports/remote-exec-port',
+      'bitfun-runtime-ports/remote-workspace-ports',
+      'bitfun-runtime-ports/runtime-event-port',
+      'bitfun-runtime-ports/terminal-port',
+      'bitfun-runtime-ports/tool-runtime-handles',
+      'bitfun-runtime-ports/workspace-ports',
+      'dep:base64',
       'dep:bitfun-harness',
       'dep:dashmap',
       'dep:filetime',
       'dep:flate2',
       'dep:fs2',
+      'dep:futures',
       'dep:include_dir',
       'dep:indexmap',
       'dep:image',
       'dep:md5',
       'dep:rusqlite',
+      'dep:regex',
       'dep:similar',
+      'dep:tokio-util',
       'dep:tool-runtime',
       'bitfun-services-core/permission',
       'bitfun-services-core/runtime-ownership',
       'bitfun-services-core/session-git',
+      'bitfun-services-core/workspace-text-runtime',
       'filesystem',
       'local-storage',
       'process-runtime',
@@ -319,6 +828,10 @@ export const coreClosedFeatureProfileRules = [
       'tool-packs',
       'tools-basic',
       'tools-agent-control',
+      'tokio/io-util',
+      'tokio/macros',
+      'tokio/rt',
+      'tokio/time',
     ],
     allowedTransitiveFeatureRefs: [
       'workspace-search',
@@ -328,6 +841,28 @@ export const coreClosedFeatureProfileRules = [
     reason:
       'bitfun-core agent-runtime is the reviewed Core Agent Runtime owner closure, not a product-full alias',
   },
+  {
+    manifestPath: 'src/crates/assembly/core/Cargo.toml',
+    featureName: 'i18n-runtime',
+    requiredFeatureRefs: ['dep:fluent-bundle', 'dep:unic-langid'],
+    exact: true,
+    reason:
+      'i18n-runtime must own only the backend Fluent bundle and language identifier implementation',
+  },
+  {
+    manifestPath: 'src/crates/assembly/core/Cargo.toml',
+    featureName: 'diagnostics',
+    requiredFeatureRefs: ['bitfun-services-core/diagnostics'],
+    exact: true,
+    reason: 'bitfun-core diagnostics must preserve only the reusable diagnostic redaction facade',
+  },
+  {
+    manifestPath: 'src/crates/assembly/core/Cargo.toml',
+    featureName: 'diff',
+    requiredFeatureRefs: ['bitfun-services-core/diff'],
+    exact: true,
+    reason: 'bitfun-core diff must preserve only the reusable local diff facade',
+  },
   {
     manifestPath: 'src/crates/assembly/core/Cargo.toml',
     featureName: 'external-sources',
@@ -337,6 +872,7 @@ export const coreClosedFeatureProfileRules = [
       'mcp-runtime',
       'script-tool-runtime',
       'dep:bitfun-opencode-adapter',
+      'dep:bitfun-dsh-adapter',
       'dep:bitfun-claude-code-adapter',
       'dep:bitfun-codex-adapter',
       'dep:bitfun-external-sources',
@@ -372,7 +908,11 @@ export const coreClosedFeatureProfileRules = [
   {
     manifestPath: 'src/crates/assembly/core/Cargo.toml',
     featureName: 'plugin-runtime',
-    requiredFeatureRefs: ['external-sources', 'dep:bitfun-plugin-runtime-client'],
+    requiredFeatureRefs: [
+      'external-sources',
+      'dep:bitfun-plugin-runtime-client',
+      'bitfun-runtime-ports/plugin-runtime',
+    ],
     allowedTransitiveFeatureRefs: [
       'agent-runtime',
       'model-catalog',
@@ -419,6 +959,7 @@ export const coreClosedFeatureProfileRules = [
     featureName: 'mcp-runtime',
     requiredFeatureRefs: [
       'agent-runtime',
+      'bitfun-agent-tools/mcp-bridge',
       'dep:axum',
       'dep:reqwest',
       'bitfun-services-integrations/mcp',
@@ -483,7 +1024,13 @@ export const coreClosedFeatureProfileRules = [
   {
     manifestPath: 'src/crates/assembly/core/Cargo.toml',
     featureName: 'browser-control',
-    requiredFeatureRefs: ['dep:tokio-tungstenite', 'bitfun-services-integrations/browser-control'],
+    requiredFeatureRefs: [
+      'dep:tokio-tungstenite',
+      'bitfun-services-integrations/browser-control',
+      'tokio/net',
+      'tokio/rt',
+      'tokio/time',
+    ],
     exact: true,
     reason: 'browser-control must own only the CDP browser adapter',
   },
@@ -497,14 +1044,20 @@ export const coreClosedFeatureProfileRules = [
   {
     manifestPath: 'src/crates/assembly/core/Cargo.toml',
     featureName: 'deep-research',
-    requiredFeatureRefs: ['bitfun-services-integrations/deep-research'],
+    requiredFeatureRefs: [
+      'bitfun-agent-runtime?/deep-research',
+      'bitfun-services-integrations/deep-research',
+    ],
     exact: true,
     reason: 'deep-research must own only research report post-processing',
   },
   {
     manifestPath: 'src/crates/assembly/core/Cargo.toml',
     featureName: 'script-tool-runtime',
-    requiredFeatureRefs: ['bitfun-services-integrations/script-tool-runtime'],
+    requiredFeatureRefs: [
+      'bitfun-runtime-ports/script-tool-runtime',
+      'bitfun-services-integrations/script-tool-runtime',
+    ],
     exact: true,
     reason: 'script-tool-runtime must own only external script tool execution support',
   },
@@ -515,12 +1068,35 @@ export const coreClosedFeatureProfileRules = [
     exact: true,
     reason: 'scheduled-jobs is an additive Agent Runtime modifier for cron parsing and timezone scheduling',
   },
+  {
+    manifestPath: 'src/crates/assembly/core/Cargo.toml',
+    featureName: 'document-read',
+    requiredFeatureRefs: ['tool-runtime?/document-read'],
+    exact: true,
+    reason:
+      'document-read must add conversion only when the Agent tool runtime owner is selected',
+  },
+  {
+    manifestPath: 'src/crates/assembly/core/Cargo.toml',
+    featureName: 'subscription-auth',
+    requiredFeatureRefs: ['bitfun-ai-adapters?/subscription-auth'],
+    exact: true,
+    reason:
+      'subscription-auth must add local credential resolution only when the AI adapter runtime owner is selected',
+  },
+  {
+    manifestPath: 'src/crates/assembly/core/Cargo.toml',
+    featureName: 'ai-adapter-runtime',
+    requiredFeatureRefs: ['dep:bitfun-ai-adapters'],
+    exact: true,
+    reason:
+      'ai-adapter-runtime must own provider protocol clients without implicitly enabling local subscription credentials',
+  },
   {
     manifestPath: 'src/crates/assembly/core/Cargo.toml',
     featureName: 'tools-basic',
     requiredFeatureRefs: [
       'bitfun-tool-packs/basic',
-      'tool-runtime/document-read',
       'workspace-search',
     ],
     allowedTransitiveFeatureRefs: [
@@ -665,8 +1241,13 @@ export const coreClosedFeatureProfileRules = [
     featureName: 'debug-log',
     requiredFeatureRefs: [
       'dep:axum',
+      'dep:tokio-util',
       'dep:tower-http',
       'bitfun-services-integrations/debug-log',
+      'tokio/macros',
+      'tokio/net',
+      'tokio/rt',
+      'tokio/time',
     ],
     exact: true,
     reason: 'bitfun-core debug-log must own only the debug ingest HTTP capability',
@@ -678,10 +1259,33 @@ export const coreClosedFeatureProfileRules = [
     exact: true,
     reason: 'services-core default profile must stay empty so consumers select capabilities explicitly',
   },
+  {
+    manifestPath: 'src/crates/services/services-core/Cargo.toml',
+    featureName: 'diagnostics',
+    requiredFeatureRefs: ['dep:regex'],
+    exact: true,
+    reason: 'services-core diagnostics must own only deterministic diagnostic-log redaction',
+  },
+  {
+    manifestPath: 'src/crates/services/services-core/Cargo.toml',
+    featureName: 'diff',
+    requiredFeatureRefs: ['dep:similar', 'dep:tokio', 'tokio/rt', 'tokio/time'],
+    exact: true,
+    reason: 'services-core diff must own only local text diff calculation and its bounded async runtime',
+  },
   {
     manifestPath: 'src/crates/services/services-core/Cargo.toml',
     featureName: 'filesystem',
-    requiredFeatureRefs: ['dep:base64', 'dep:chrono', 'dep:ignore', 'dep:sha2', 'tokio/fs'],
+    requiredFeatureRefs: [
+      'dep:base64',
+      'dep:chrono',
+      'dep:ignore',
+      'dep:regex',
+      'dep:sha2',
+      'dep:tokio',
+      'tokio/fs',
+      'tokio/rt',
+    ],
     exact: true,
     reason: 'services-core filesystem must own only local file operations and recursive search dependencies',
   },
@@ -690,9 +1294,12 @@ export const coreClosedFeatureProfileRules = [
     featureName: 'json-io',
     requiredFeatureRefs: [
       'dep:fs2',
+      'dep:tokio',
       'dep:windows',
       'tokio/fs',
+      'tokio/rt',
       'tokio/sync',
+      'tokio/time',
       'windows/Win32_Foundation',
       'windows/Win32_Storage_FileSystem',
     ],
@@ -708,10 +1315,15 @@ export const coreClosedFeatureProfileRules = [
       'dep:chrono',
       'dep:fs2',
       'dep:libc',
+      'dep:regex',
       'dep:sha2',
+      'dep:similar',
+      'dep:tokio',
       'dep:windows',
       'tokio/fs',
+      'tokio/rt',
       'tokio/sync',
+      'tokio/time',
       'windows/Win32_Foundation',
       'windows/Win32_Storage_FileSystem',
     ],
@@ -723,11 +1335,14 @@ export const coreClosedFeatureProfileRules = [
     featureName: 'process-runtime',
     requiredFeatureRefs: [
       'dep:libc',
+      'dep:tokio',
       'dep:which',
       'dep:win32job',
       'dep:windows',
       'tokio/io-util',
       'tokio/process',
+      'tokio/rt',
+      'tokio/time',
       'windows/Win32_Foundation',
       'windows/Win32_System_Diagnostics_ToolHelp',
       'windows/Win32_System_Threading',
@@ -738,10 +1353,25 @@ export const coreClosedFeatureProfileRules = [
   {
     manifestPath: 'src/crates/services/services-core/Cargo.toml',
     featureName: 'workspace-instructions',
-    requiredFeatureRefs: ['dep:globset', 'dep:serde_yaml', 'tokio/fs', 'tokio/io-util'],
+    requiredFeatureRefs: [
+      'dep:globset',
+      'dep:regex',
+      'dep:serde_yaml',
+      'dep:tokio',
+      'tokio/fs',
+      'tokio/io-util',
+      'tokio/rt',
+    ],
     exact: true,
     reason: 'services-core workspace-instructions must own declarative instruction discovery, scope parsing, and glob expansion only',
   },
+  {
+    manifestPath: 'src/crates/services/services-core/Cargo.toml',
+    featureName: 'workspace-text-runtime',
+    requiredFeatureRefs: ['dep:tokio', 'tokio/rt'],
+    exact: true,
+    reason: 'services-core workspace-text-runtime must own only bounded asynchronous local workspace reads',
+  },
   {
     manifestPath: 'src/crates/services/services-core/Cargo.toml',
     featureName: 'lsp',
@@ -765,6 +1395,8 @@ export const coreClosedFeatureProfileRules = [
       'dep:anyhow',
       'dep:async-trait',
       'dep:bitfun-runtime-ports',
+      'bitfun-runtime-ports/runtime-event-port',
+      'bitfun-runtime-ports/workspace-ports',
       'dep:dunce',
       'process-runtime',
       'tokio/fs',
@@ -791,7 +1423,11 @@ export const coreClosedFeatureProfileRules = [
   {
     manifestPath: 'src/crates/assembly/core/Cargo.toml',
     featureName: 'dispatch-store',
-    requiredFeatureRefs: ['local-storage', 'bitfun-services-core/dispatch-workspace'],
+    requiredFeatureRefs: [
+      'dep:base64',
+      'local-storage',
+      'bitfun-services-core/dispatch-workspace',
+    ],
     exact: true,
     reason: 'bitfun-core dispatch-store must expose only the durable dispatch index facade',
   },
@@ -805,7 +1441,7 @@ export const coreClosedFeatureProfileRules = [
   {
     manifestPath: 'src/crates/assembly/core/Cargo.toml',
     featureName: 'local-storage',
-    requiredFeatureRefs: ['bitfun-services-core/local-storage'],
+    requiredFeatureRefs: ['dep:bitfun-agent-tools', 'bitfun-services-core/local-storage'],
     exact: true,
     reason: 'bitfun-core local-storage must select only reusable local persistence owners',
   },
@@ -819,7 +1455,7 @@ export const coreClosedFeatureProfileRules = [
   {
     manifestPath: 'src/crates/assembly/core/Cargo.toml',
     featureName: 'lsp',
-    requiredFeatureRefs: ['dep:notify', 'bitfun-services-core/lsp'],
+    requiredFeatureRefs: ['dep:notify', 'bitfun-services-core/lsp', 'tokio/macros'],
     exact: true,
     reason: 'bitfun-core lsp must select only the LSP owner and its workspace watcher dependency',
   },
@@ -941,6 +1577,13 @@ export const ownerCrateFeatureAssemblyRules = [
   {
     manifestPath: 'src/crates/services/services-integrations/Cargo.toml',
     reason: 'services-integrations must keep integration feature groups explicit and default-light',
+    optionalDependencyAggregateFeatures: [
+      'function-agents',
+      'mcp',
+      'miniapp-market',
+      'remote-ssh-concrete',
+      'script-tool-runtime',
+    ],
     requiredProductFullFeatures: [
       'announcement',
       'browser-control',
@@ -970,3 +1613,23 @@ export const ownerCrateFeatureAssemblyRules = [
     requiredProductFullFeatures: ['appearance-market', 'plugin-source', 'miniapp', 'function-agents', 'external-sources'],
   },
 ];
+
+export function reviewedOptionalDependencyAggregateFeatures(manifestPath) {
+  const features = new Set(
+    coreClosedFeatureProfileRules
+      .filter((profile) => profile.manifestPath === manifestPath)
+      .map((profile) => profile.featureName),
+  );
+  if (coreProductFullFeatureAssemblyRule.manifestPath === manifestPath) {
+    features.add(coreProductFullFeatureAssemblyRule.featureName);
+  }
+  const ownerAssembly = ownerCrateFeatureAssemblyRules.find((profile) =>
+    profile.manifestPath === manifestPath);
+  if (ownerAssembly) {
+    features.add('product-full');
+    for (const feature of ownerAssembly.optionalDependencyAggregateFeatures ?? []) {
+      features.add(feature);
+    }
+  }
+  return features;
+}
diff --git a/scripts/core-boundaries/rules/source-rules.mjs b/scripts/core-boundaries/rules/source-rules.mjs
index a318928e7c..edbc0afd5e 100644
--- a/scripts/core-boundaries/rules/source-rules.mjs
+++ b/scripts/core-boundaries/rules/source-rules.mjs
@@ -5,5 +5,9 @@ export {
   forbiddenContentRules,
   forbiddenContentUnderRules,
 } from './source/forbidden-rules.mjs';
-export { publicApiAllowlistRules, publicApiContractSlices } from './source/public-api-rules.mjs';
+export {
+  agentRuntimeRootPublicModules,
+  publicApiAllowlistRules,
+  publicApiContractSlices,
+} from './source/public-api-rules.mjs';
 export { requiredContentRules } from './source/required-rules.mjs';
diff --git a/scripts/core-boundaries/rules/source/forbidden-rules.mjs b/scripts/core-boundaries/rules/source/forbidden-rules.mjs
index d6eaab22e7..19e09ed0d1 100644
--- a/scripts/core-boundaries/rules/source/forbidden-rules.mjs
+++ b/scripts/core-boundaries/rules/source/forbidden-rules.mjs
@@ -1,6 +1,24 @@
 // Boundary rules for source ownership, facades, and required owner content.
 
+import { agentRuntimeRootPublicModules } from './public-api-rules.mjs';
+
+const agentRuntimeRootUnexpectedLine = new RegExp(
+  `^(?!(?:[ \\t]*|[ \\t]*\\/\\/!.*|[ \\t]*#\\[cfg\\(feature = "(?:agent-runtime|deep-research|native-hook-settings)"\\)\\][ \\t]*|[ \\t]*pub mod (?:${agentRuntimeRootPublicModules.join('|')});[ \\t]*)\\r?$).+$`,
+  'm',
+);
+
 export const forbiddenContentRules = [
+  {
+    path: 'src/crates/execution/agent-runtime/src/lib.rs',
+    reason:
+      'Agent Runtime root is a flat feature-owned module wrapper, not a feature-free implementation surface',
+    patterns: [
+      {
+        regex: agentRuntimeRootUnexpectedLine,
+        message: 'unexpected Agent Runtime root content outside the reviewed cfg/module pairs',
+      },
+    ],
+  },
   {
     path: 'src/apps/cli/src/tui_backend.rs',
     reason:
@@ -35,6 +53,19 @@ export const forbiddenContentRules = [
       },
     ],
   },
+  {
+    path: 'src/crates/adapters/agent-runtime-ipc/Cargo.toml',
+    reason:
+      'agent-runtime-ipc may reuse bounded JSON encoding without enabling bitfun-transport features',
+    patterns: [
+      {
+        regex:
+          /bitfun-transport\s*=\s*\{[^}\r\n]*(?:features|default-features)\s*=/,
+        message:
+          'agent-runtime-ipc must not enable event-host or Tauri transport features',
+      },
+    ],
+  },
   {
     path: 'src/crates/execution/plugin-runtime-client/src/adapter.rs',
     reason: 'plugin-runtime-client adapter trait method surface must stay narrow',
@@ -216,7 +247,7 @@ export const forbiddenContentRules = [
     ],
   },
   {
-    path: 'src/crates/assembly/product-capabilities/tests/product_sdk_assembly.rs',
+    path: 'src/crates/assembly/product-capabilities/tests/product_capability_contracts/product_sdk_assembly.rs',
     patterns: [
       {
         regex: /\bbitfun_core\b/,
@@ -3260,7 +3291,7 @@ export const forbiddenContentRules = [
           'Git function-agent commit generator must use CoreProductDomainRuntime for Git adapter wiring',
       },
       {
-        regex: /\bAIAnalysisService::new_with_agent_config\b/,
+        regex: /\bAIAnalysisService::new_with_task_config\b/,
         message:
           'Git function-agent commit generator must use CoreProductDomainRuntime for AI adapter wiring',
       },
@@ -3271,21 +3302,6 @@ export const forbiddenContentRules = [
       },
     ],
   },
-  {
-    path: 'src/crates/assembly/core/src/function_agents/startchat-func-agent/work_state_analyzer.rs',
-    patterns: [
-      {
-        regex: /\bAIWorkStateService::new_with_agent_config\b/,
-        message:
-          'Startchat work-state analyzer must use CoreProductDomainRuntime for AI adapter wiring',
-      },
-      {
-        regex: /\bcreate_command\("git"\)/,
-        message:
-          'Startchat work-state analyzer must use CoreProductDomainRuntime for Git adapter wiring',
-      },
-    ],
-  },
   {
     path: 'src/crates/assembly/core/src/service/mcp/server/config.rs',
     patterns: [
@@ -4058,6 +4074,12 @@ export const forbiddenContentUnderRules = [
           /\b(?:(?:Tcp|Udp)[A-Za-z0-9_]*|tokio_tungstenite|reqwest|hyper|WebSocket)\b/,
         message: 'agent-runtime-ipc must not add network or remote transports',
       },
+      {
+        regex:
+          /\bbitfun_transport\b(?!::(?:encode_json_with_limit|JsonCodecError)\b)/,
+        message:
+          'agent-runtime-ipc may consume only the reviewed bounded JSON API from bitfun-transport',
+      },
     ],
   },
   {
@@ -4135,13 +4157,13 @@ export const forbiddenContentUnderRules = [
           /\b(?:use\s+bitfun_opencode_adapter\b|extern\s+crate\s+bitfun_opencode_adapter\b|bitfun_opencode_adapter::)/,
         allowPaths: [
           'src/crates/adapters/opencode-adapter/tests/opencode_source_adapter.rs',
-          'src/crates/adapters/opencode-adapter/tests/opencode_command_adapter.rs',
-          'src/crates/adapters/opencode-adapter/tests/opencode_skill_roots.rs',
-          'src/crates/adapters/opencode-adapter/tests/opencode_workspace_references.rs',
+          'src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts/opencode_command_adapter.rs',
+          'src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts/opencode_skill_roots.rs',
+          'src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts/opencode_workspace_references.rs',
           'src/crates/adapters/opencode-adapter/tests/tool_source_contracts.rs',
-          'src/crates/adapters/opencode-adapter/tests/opencode_subagent_adapter.rs',
+          'src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts/opencode_subagent_adapter.rs',
           'src/crates/adapters/opencode-adapter/tests/opencode_mcp_adapter.rs',
-          'src/crates/adapters/opencode-adapter/tests/hook_source.rs',
+          'src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts/hook_source.rs',
           'src/crates/assembly/core/src/plugin_runtime.rs',
           'src/crates/assembly/core/src/external_sources.rs',
           'src/crates/assembly/core/src/external_hooks.rs',
@@ -4171,10 +4193,10 @@ export const forbiddenContentUnderRules = [
     patterns: [{
       regex: /\b(?:use\s+bitfun_claude_code_adapter\b|extern\s+crate\s+bitfun_claude_code_adapter\b|bitfun_claude_code_adapter::)/,
       allowPaths: [
-        'src/crates/adapters/claude-code-adapter/tests/hook_source.rs',
-        'src/crates/adapters/claude-code-adapter/tests/command_source.rs',
-        'src/crates/adapters/claude-code-adapter/tests/subagent_source.rs',
-        'src/crates/adapters/claude-code-adapter/tests/mcp_source.rs',
+        'src/crates/adapters/claude-code-adapter/tests/claude_code_source_contracts/hook_source.rs',
+        'src/crates/adapters/claude-code-adapter/tests/claude_code_source_contracts/command_source.rs',
+        'src/crates/adapters/claude-code-adapter/tests/claude_code_source_contracts/subagent_source.rs',
+        'src/crates/adapters/claude-code-adapter/tests/claude_code_source_contracts/mcp_source.rs',
         'src/crates/assembly/core/src/external_sources.rs',
         'src/crates/assembly/core/src/external_hooks.rs',
         'src/crates/assembly/core/src/instruction_sources.rs',
@@ -4188,9 +4210,9 @@ export const forbiddenContentUnderRules = [
     patterns: [{
       regex: /\b(?:use\s+bitfun_codex_adapter\b|extern\s+crate\s+bitfun_codex_adapter\b|bitfun_codex_adapter::)/,
       allowPaths: [
-        'src/crates/adapters/codex-adapter/tests/hook_source.rs',
-        'src/crates/adapters/codex-adapter/tests/subagent_source.rs',
-        'src/crates/adapters/codex-adapter/tests/mcp_source.rs',
+        'src/crates/adapters/codex-adapter/tests/codex_source_contracts/hook_source.rs',
+        'src/crates/adapters/codex-adapter/tests/codex_source_contracts/subagent_source.rs',
+        'src/crates/adapters/codex-adapter/tests/codex_source_contracts/mcp_source.rs',
         'src/crates/assembly/core/src/external_sources.rs',
         'src/crates/assembly/core/src/external_hooks.rs',
         'src/crates/assembly/core/src/instruction_sources.rs',
@@ -4207,6 +4229,7 @@ export const forbiddenContentUnderRules = [
         'src/crates/adapters/static-hook-support/tests/parser.rs',
         'src/crates/adapters/opencode-adapter/src/hook_source.rs',
         'src/crates/adapters/opencode-adapter/src/command_source.rs',
+        'src/crates/adapters/opencode-adapter/src/agent_source.rs',
         'src/crates/adapters/opencode-adapter/src/mcp_source.rs',
         'src/crates/adapters/claude-code-adapter/src/hook_source.rs',
         'src/crates/adapters/claude-code-adapter/src/command_source.rs',
diff --git a/scripts/core-boundaries/rules/source/public-api-rules.mjs b/scripts/core-boundaries/rules/source/public-api-rules.mjs
index 1fe145be9a..387c542529 100644
--- a/scripts/core-boundaries/rules/source/public-api-rules.mjs
+++ b/scripts/core-boundaries/rules/source/public-api-rules.mjs
@@ -16,6 +16,48 @@ export const publicApiContractSlices = [
   'external-integration-policy-contract',
 ];
 
+export const agentRuntimeRootPublicModules = [
+  'agents',
+  'checkpoint',
+  'context_profile',
+  'custom_agent',
+  'custom_subagent',
+  'deep_research',
+  'deep_review',
+  'dialog_turn',
+  'event_bus',
+  'event_queue',
+  'event_router',
+  'event_source',
+  'events',
+  'evidence_ledger',
+  'file_read_state',
+  'native_hooks',
+  'output_surface',
+  'permission',
+  'post_call_hooks',
+  'prompt',
+  'prompt_cache',
+  'prompt_markup',
+  'remote_file_delivery',
+  'runtime',
+  'scheduled_job',
+  'scheduler',
+  'sdk',
+  'session',
+  'session_control',
+  'session_state',
+  'session_state_manager',
+  'side_question',
+  'skill_agent_snapshot',
+  'skills',
+  'subagent_task',
+  'thread_goal',
+  'thread_goal_tools',
+  'turn_cancellation',
+  'user_questions',
+];
+
 const contractSlices = {
   frontendBackendCapabilityService: 'frontend-backend-capability-service',
   bitfunPluginExtension: 'bitfun-plugin-extension-contract',
@@ -319,6 +361,23 @@ function staticSourceSupportEntry(symbol) {
   };
 }
 
+function commonExternalSubagentToolMappingEntry(symbol) {
+  return {
+    symbol,
+    owner: 'static-hook-support shared declarative source adapter utility owner',
+    consumer: 'reviewed OpenCode and Claude Code declarative subagent adapters',
+    verification:
+      'shared mapping unit tests, ecosystem subagent adapter fixtures, and core-boundary public API budget checks',
+    p0: 'runtime-free common external Agent tool capability normalization',
+    contractSlice: contractSlices.externalSourceControlContract,
+    wireImpact: false,
+    rationale:
+      'sibling declarative adapters need one static mapping while provider-specific aliases remain adapter-owned',
+    exit:
+      'remove only if every reviewed consumer moves to an equivalent adapter-layer mapping owner',
+  };
+}
+
 function declarativeSourceAdapterEntry(
   symbol,
   owner,
@@ -477,7 +536,9 @@ export const staticHookSupportPublicApiEntries = [
   'BoundedDirectoryWalkLimit',
   'BoundedDirectoryWalkError',
   'collect_bounded_regular_files',
-].map(staticSourceSupportEntry));
+].map(staticSourceSupportEntry)).concat([
+  'common_external_subagent_tool_capability',
+].map(commonExternalSubagentToolMappingEntry));
 
 function externalHookContractEntry(symbol, owner, consumer, wireImpact = false) {
   return {
@@ -868,6 +929,7 @@ export const externalSubagentContractPublicApiEntries = [
   'ExternalSubagentModelBindingMethod',
   'ExternalSubagentModelBindingOption',
   'ExternalSubagentModelBindingGroup',
+  'ExternalSubagentToolCapability',
   'ExternalSubagentToolSelector',
   'ExternalSubagentToolRequest',
   'ExternalSubagentCompatibilityState',
@@ -1102,6 +1164,7 @@ export const externalSourceCorePublicApiEntries = [
     'ExternalToolConflictCandidateKind',
     'ExternalToolRuntimeKind',
     'set_external_tool_target_decision',
+    'set_external_tool_targets_enabled',
     'set_external_tool_conflict_choice',
   ].map((symbol) =>
     externalToolEntry(
@@ -1123,6 +1186,7 @@ export const externalSourceCorePublicApiEntries = [
     'ExternalSubagentModelRequest',
     'ExternalSubagentSummary',
     'set_external_subagent_activation',
+    'set_external_subagents_enabled',
     'set_external_subagent_model_binding',
     'choose_external_subagent_conflict',
   ].map((symbol) =>
@@ -1140,6 +1204,7 @@ export const externalSourceCorePublicApiEntries = [
     'ExternalMcpTransportKind',
     'native_mcp_candidate_id',
     'set_external_mcp_server_decision',
+    'set_external_mcp_servers_enabled',
     'choose_external_mcp_conflict',
   ].map((symbol) =>
     externalMcpEntry(
@@ -1241,6 +1306,12 @@ export const managedPluginSourceServicePublicApiEntries = [
 );
 
 export const publicApiAllowlistRules = [
+  {
+    path: 'src/crates/execution/agent-runtime/src/lib.rs',
+    reason:
+      'Agent Runtime root must expose only the reviewed feature-owned capability modules',
+    allowedSymbols: agentRuntimeRootPublicModules,
+  },
   {
     path: 'src/crates/contracts/runtime-ports/src/plugin.rs',
     reason:
diff --git a/scripts/core-boundaries/rules/source/required-rules.mjs b/scripts/core-boundaries/rules/source/required-rules.mjs
index 5510e2d0ad..80e882a646 100644
--- a/scripts/core-boundaries/rules/source/required-rules.mjs
+++ b/scripts/core-boundaries/rules/source/required-rules.mjs
@@ -1,49 +1,51 @@
 // Boundary rules for source ownership, facades, and required owner content.
 
+import { agentRuntimeRootPublicModules } from './public-api-rules.mjs';
+
 export const requiredContentRules = [
   {
-    path: 'Cargo.toml',
+    path: 'src/crates/adapters/agent-runtime-ipc/Cargo.toml',
     reason:
-      'workspace Reqwest defaults must stay transport-only so client owners select one TLS backend explicitly',
+      'agent-runtime-ipc must keep the exact feature-free bitfun-transport dependency',
     patterns: [
       {
-        regex: /^reqwest[ \t]*=[ \t]*\{[ \t]*version[ \t]*=[ \t]*"[^"]+",[ \t]*default-features[ \t]*=[ \t]*false,[ \t]*features[ \t]*=[ \t]*\[[ \t]*"http2",[ \t]*"json",[ \t]*"stream",[ \t]*"multipart",[ \t]*"query",[ \t]*"form"[ \t]*\][ \t]*\}[ \t]*$/m,
+        regex: /^bitfun-transport = \{ path = "\.\.\/transport" \}$/m,
         message:
-          'workspace Reqwest dependency must use the reviewed transport/data feature allowlist',
+          'bitfun-transport must stay feature-free and use the reviewed sibling path',
       },
     ],
   },
   ...[
     'src/apps/cli/Cargo.toml',
     'src/apps/desktop/Cargo.toml',
+    'src/crates/adapters/ai-adapters/Cargo.toml',
+    'src/crates/assembly/core/Cargo.toml',
     'src/crates/services/miniapp-market-service/Cargo.toml',
+    'src/crates/services/services-integrations/Cargo.toml',
     'src/crates/services/skin-market-service/Cargo.toml',
   ].map((path) => ({
     path,
-    reason: 'first-party Reqwest client owners must select the repository TLS backend explicitly',
+    reason: 'first-party Reqwest consumers must inherit the workspace-owned compatible version',
     patterns: [
       {
-        regex: /^reqwest\s*=\s*\{\s*workspace\s*=\s*true,\s*features\s*=\s*\[\s*"rustls"\s*\]\s*\}/m,
-        message: 'Reqwest client dependency must explicitly enable rustls',
+        regex: /^reqwest\s*=\s*\{\s*workspace\s*=\s*true(?:\s*,|\s*\})/m,
+        message: 'Reqwest dependency must use workspace = true',
       },
     ],
   })),
-  {
-    path: 'src/crates/adapters/ai-adapters/Cargo.toml',
-    reason:
-      'the AI adapter owns Rustls HTTPS clients and the product-supported SOCKS proxy transport',
-    patterns: [
-      {
-        regex: /^reqwest\s*=\s*\{\s*workspace\s*=\s*true,\s*features\s*=\s*\[\s*"rustls"\s*,\s*"socks"\s*\]\s*\}/m,
-        message: 'AI adapter Reqwest dependency must explicitly enable rustls and socks',
-      },
-    ],
-  },
   {
     path: 'src/crates/services/services-core/src/lib.rs',
     reason:
       'services-core must compile concrete service owners only through their declared capability features',
     patterns: [
+      {
+        regex: /#\[cfg\(feature = "diagnostics"\)\]\s*pub mod diagnostics;/,
+        message: 'missing diagnostic redaction capability source gate',
+      },
+      {
+        regex: /#\[cfg\(feature = "diff"\)\]\s*pub mod diff;/,
+        message: 'missing local diff capability source gate',
+      },
       {
         regex: /#\[cfg\(any\(feature = "local-storage", feature = "runtime-ownership"\)\)\]\s*mod file_lock;/,
         message: 'missing shared file lock owner source gate',
@@ -98,6 +100,25 @@ export const requiredContentRules = [
       },
     ],
   },
+  {
+    path: 'src/crates/services/services-core/src/workspace_text.rs',
+    reason:
+      'workspace text contracts stay synchronous while bounded local IO requires its runtime owner',
+    patterns: [
+      {
+        regex: /pub fn normalize_workspace_relative_path\b/,
+        message: 'missing feature-free workspace path normalization contract',
+      },
+      {
+        regex: /#\[cfg\(feature = "workspace-text-runtime"\)\]\s*pub async fn read_workspace_relative_text_bounded\b/s,
+        message: 'bounded workspace text reads must stay behind workspace-text-runtime',
+      },
+      {
+        regex: /#\[cfg\(feature = "workspace-text-runtime"\)\]\s*pub async fn resolve_workspace_relative_entry\b/s,
+        message: 'workspace entry resolution must stay behind workspace-text-runtime',
+      },
+    ],
+  },
   {
     path: 'src/crates/services/services-core/src/persistence.rs',
     reason:
@@ -207,7 +228,7 @@ export const requiredContentRules = [
         message: 'serde_yaml must remain optional in services-core',
       },
       {
-        regex: /markdown = \["dep:serde_yaml"\]/,
+        regex: /markdown = \[[^\]]*"dep:serde_yaml"[^\]]*\]/,
         message: 'missing explicit markdown feature for services-core',
       },
     ],
@@ -452,7 +473,7 @@ export const requiredContentRules = [
     ],
   },
   {
-    path: 'src/crates/contracts/core-types/tests/lsp_contracts.rs',
+    path: 'src/crates/contracts/core-types/tests/core_type_contracts/lsp_contracts.rs',
     reason:
       'core-types must keep LSP manifest serialization, default-value, and placeholder regressions',
     patterns: [
@@ -867,6 +888,10 @@ export const requiredContentRules = [
         regex: /default = \[\]/,
         message: 'agent-runtime default feature set must stay empty',
       },
+      {
+        regex: /\[\[example\]\]\r?\nname = "sdk_minimal"\r?\npath = "examples\/sdk_minimal\.rs"\r?\nrequired-features = \["agent-runtime"\]/,
+        message: 'sdk_minimal example must declare the versioned agent-runtime owner feature',
+      },
     ],
   },
   {
@@ -1533,7 +1558,7 @@ export const requiredContentRules = [
     ],
   },
   {
-    path: 'src/crates/assembly/product-capabilities/tests/product_capabilities.rs',
+    path: 'src/crates/assembly/product-capabilities/tests/product_capability_contracts/product_capabilities.rs',
     reason:
       'product-capabilities tests must protect product shape facts, runtime service gap reporting, and legacy harness routing',
     patterns: [
@@ -1564,7 +1589,7 @@ export const requiredContentRules = [
     ],
   },
   {
-    path: 'src/crates/assembly/product-capabilities/tests/plugin_product_shape.rs',
+    path: 'src/crates/assembly/product-capabilities/tests/product_capability_contracts/plugin_product_shape.rs',
     reason:
       'product-capabilities plugin shape tests must protect P0 plugin-capable profiles, non-P0 rejection, default availability reasons, and runtime handoff',
     patterns: [
@@ -1591,7 +1616,7 @@ export const requiredContentRules = [
     ],
   },
   {
-    path: 'src/crates/assembly/product-capabilities/tests/product_sdk_assembly.rs',
+    path: 'src/crates/assembly/product-capabilities/tests/product_capability_contracts/product_sdk_assembly.rs',
     reason:
       'product-capabilities must prove product runtime parts can feed the SDK runtime without bitfun-core',
     patterns: [
@@ -2766,7 +2791,7 @@ export const requiredContentRules = [
     ],
   },
   {
-    path: 'src/crates/execution/agent-runtime/tests/agent_long_horizon_contracts/deep_research_contracts.rs',
+    path: 'src/crates/execution/agent-runtime/tests/deep_research_contracts.rs',
     reason:
       'agent-runtime must keep behavior-equivalence contracts for DeepResearch citation renumbering',
     patterns: [
@@ -3917,12 +3942,12 @@ export const requiredContentRules = [
     patterns: [
       {
         regex:
-          /bitfun-tool-packs = \{ path = "\.\.\/\.\.\/execution\/tool-provider-groups", default-features = false, optional = true \}/,
+          /bitfun-tool-packs = \{ path = "\.\.\/\.\.\/execution\/tool-provider-groups", optional = true \}/,
         message: 'bitfun-tool-packs dependency must stay optional and not force product-full outside the core feature graph',
       },
       {
         regex:
-          /bitfun-services-integrations = \{ path = "\.\.\/\.\.\/services\/services-integrations", default-features = false, optional = true \}/,
+          /bitfun-services-integrations = \{ path = "\.\.\/\.\.\/services\/services-integrations", optional = true \}/,
         message:
           'bitfun-services-integrations dependency must stay optional so local workspace profiles do not compile remote integrations',
       },
@@ -3935,6 +3960,14 @@ export const requiredContentRules = [
         regex: /"dep:bitfun-ai-adapters"/,
         message: 'core ai-adapter-runtime feature must explicitly enable the optional dependency',
       },
+      {
+        regex: /subscription-auth = \["bitfun-ai-adapters\?\/subscription-auth"\]/,
+        message: 'core subscription-auth modifier must not activate the optional AI adapter runtime by itself',
+      },
+      {
+        regex: /document-read = \["tool-runtime\?\/document-read"\]/,
+        message: 'core document-read modifier must not activate the optional tool runtime by itself',
+      },
       {
         regex: /agent-runtime = \[[^\]]*"ai-adapter-runtime"[^\]]*\]/,
         message: 'core agent-runtime assembly must explicitly opt into AI adapter runtime',
@@ -3972,13 +4005,13 @@ export const requiredContentRules = [
       },
       {
         regex:
-          /bitfun-product-domains = \{ path = "\.\.\/\.\.\/contracts\/product-domains", default-features = false, optional = true \}/,
+          /bitfun-product-domains = \{ path = "\.\.\/\.\.\/contracts\/product-domains", optional = true \}/,
         message:
           'bitfun-product-domains dependency must stay optional and not force product-full outside the core feature graph',
       },
       {
         regex:
-          /bitfun-product-capabilities = \{ path = "\.\.\/product-capabilities", default-features = false, optional = true \}/,
+          /bitfun-product-capabilities = \{ path = "\.\.\/product-capabilities", optional = true \}/,
         message:
           'bitfun-product-capabilities dependency must stay optional and not force product-full outside the core feature graph',
       },
@@ -4071,8 +4104,8 @@ export const requiredContentRules = [
         message: 'AI client runtime must stay behind ai-adapter-runtime',
       },
       {
-        regex: /#\[cfg\(feature = "ai-adapter-runtime"\)\]\s*pub mod subscription_auth\b/s,
-        message: 'AI subscription auth runtime must stay behind ai-adapter-runtime',
+        regex: /#\[cfg\(all\(feature = "ai-adapter-runtime", feature = "subscription-auth"\)\)\]\s*pub mod subscription_auth\b/s,
+        message: 'AI subscription auth runtime must require both the adapter and credential owners',
       },
       {
         regex: /#\[cfg\(feature = "debug-log"\)\]\s*pub mod debug_log\b/s,
@@ -4107,6 +4140,14 @@ export const requiredContentRules = [
         regex: /#\[cfg\(feature = "file-watch"\)\]\s*pub use bitfun_services_integrations::file_watch\b/s,
         message: 'file-watch facade must stay behind its exact feature',
       },
+      {
+        regex: /#\[cfg\(feature = "diagnostics"\)\]\s*pub use bitfun_services_core::diagnostics\b/s,
+        message: 'diagnostics compatibility facade must stay behind diagnostics',
+      },
+      {
+        regex: /#\[cfg\(feature = "diff"\)\]\s*pub use bitfun_services_core::diff\b/s,
+        message: 'diff compatibility facade must stay behind diff',
+      },
       {
         regex: /#\[cfg\(feature = "git"\)\]\s*pub mod git\b/s,
         message: 'git service facade must stay behind its exact feature',
@@ -4855,7 +4896,7 @@ export const requiredContentRules = [
     ],
   },
   {
-    path: 'src/crates/contracts/runtime-ports/tests/plugin_runtime_contracts.rs',
+    path: 'src/crates/contracts/runtime-ports/tests/runtime_port_contracts/plugin_runtime_contracts.rs',
     reason:
       'runtime-ports plugin contract tests must cover typed envelopes, candidate effects, and disabled/projection-only behavior',
     patterns: [
@@ -4912,7 +4953,7 @@ export const requiredContentRules = [
     ],
   },
   {
-    path: 'src/crates/contracts/runtime-ports/tests/plugin_runtime_diagnostics_contracts.rs',
+    path: 'src/crates/contracts/runtime-ports/tests/runtime_port_contracts/plugin_runtime_diagnostics_contracts.rs',
     reason:
       'runtime-ports plugin diagnostics contract tests must cover permission prompts, diagnostics, and quarantine facts',
     patterns: [
@@ -5035,7 +5076,7 @@ export const requiredContentRules = [
     ],
   },
   {
-    path: 'src/crates/contracts/runtime-ports/src/lib.rs',
+    path: 'src/crates/contracts/runtime-ports/src/agent_api.rs',
     reason:
       'runtime-ports must keep remote and subagent runtime boundary contracts DTO/trait-only',
     patterns: [
@@ -5048,6 +5089,7 @@ export const requiredContentRules = [
         message: 'missing remote control state port contract',
       },
       {
+        path: 'src/crates/contracts/runtime-ports/src/runtime_event_port.rs',
         regex: /\bpub trait RuntimeEventSink\b/,
         message: 'missing runtime event sink contract',
       },
@@ -5056,62 +5098,87 @@ export const requiredContentRules = [
         message: 'agent session create result must return the persisted session name',
       },
       {
+        path: 'src/crates/contracts/runtime-ports/src/remote_workspace_ports.rs',
         regex: /\bpub struct RemoteWorkspaceFacts\b/,
         message: 'missing remote workspace facts contract',
       },
       {
+        path: 'src/crates/contracts/runtime-ports/src/remote_workspace_ports.rs',
         regex: /\bpub trait RemoteWorkspaceRuntimeHost\b/,
         message: 'missing remote workspace runtime host contract',
       },
       {
+        path: 'src/crates/contracts/runtime-ports/src/remote_workspace_ports.rs',
         regex: /\bpub trait RemoteWorkspacePort\b/,
         message: 'missing remote workspace service port contract',
       },
       {
+        path: 'src/crates/contracts/runtime-ports/src/remote_workspace_ports.rs',
         regex: /\bpub trait RemoteWorkspaceFileRuntimeHost\b/,
         message: 'missing remote workspace file runtime host contract',
       },
       {
+        path: 'src/crates/contracts/runtime-ports/src/remote_workspace_ports.rs',
         regex: /\bpub trait RemoteProjectionPort\b/,
         message: 'missing remote projection service port contract',
       },
       {
+        path: 'src/crates/contracts/runtime-ports/src/remote_workspace_ports.rs',
         regex: /\bpub trait RemoteInitialSyncRuntimeHost\b/,
         message: 'missing remote initial sync runtime host contract',
       },
       {
+        path: 'src/crates/contracts/runtime-ports/src/remote_workspace_ports.rs',
         regex: /\bremote_workspace_contracts_preserve_workspace_and_session_facts\b/,
         message: 'missing remote workspace contract regression',
       },
       {
+        path: 'src/crates/contracts/runtime-ports/src/remote_workspace_ports.rs',
         regex: /\bremote_projection_contract_preserves_file_chunk_identity\b/,
         message: 'missing remote projection contract regression',
       },
       {
+        path: 'src/crates/contracts/runtime-ports/src/workspace_ports.rs',
         regex: /\bpub trait WorkspaceFileSystem\b/,
         message: 'missing workspace file-system port contract',
       },
       {
+        path: 'src/crates/contracts/runtime-ports/src/workspace_ports.rs',
+        regex: /\bfn join_path\(&self, root: &str, components: &\[&str\]\) -> String\b/,
+        message: 'workspace filesystem providers must own their path joining syntax',
+      },
+      {
+        path: 'src/crates/services/services-integrations/src/remote_ssh/workspace_services.rs',
+        regex: /fn join_path\(&self, root: &str, components: &\[&str\]\) -> String \{\r?\n\s*join_posix_path\(root, components\)/,
+        message: 'remote workspace filesystem must keep POSIX path joining independent of the host',
+      },
+      {
+        path: 'src/crates/contracts/runtime-ports/src/workspace_ports.rs',
         regex: /\bpub trait WorkspaceShell\b/,
         message: 'missing workspace shell port contract',
       },
       {
+        path: 'src/crates/contracts/runtime-ports/src/workspace_ports.rs',
         regex: /\bpub struct WorkspaceServices\b/,
         message: 'missing workspace services bundle contract',
       },
       {
+        path: 'src/crates/contracts/runtime-ports/src/workspace_ports.rs',
         regex: /\bpub struct WorkspaceCommandOptions\b/,
         message: 'missing workspace command options contract',
       },
       {
+        path: 'src/crates/contracts/runtime-ports/src/workspace_ports.rs',
         regex: /\bpub struct WorkspaceCommandResult\b/,
         message: 'missing workspace command result contract',
       },
       {
+        path: 'src/crates/contracts/runtime-ports/src/workspace_ports.rs',
         regex: /\bpub struct WorkspaceDirEntry\b/,
         message: 'missing workspace dir-entry contract',
       },
       {
+        path: 'src/crates/contracts/runtime-ports/src/workspace_ports.rs',
         regex: /\bworkspace_services_contract_is_runtime_port_owned\b/,
         message: 'missing workspace service ownership regression',
       },
@@ -5188,10 +5255,12 @@ export const requiredContentRules = [
         message: 'missing thread-goal lifecycle request regression',
       },
       {
+        path: 'src/crates/contracts/runtime-ports/src/lib.rs',
         regex: /\bpub type DialogTriggerSource = AgentSubmissionSource\b/,
         message: 'missing dialog trigger source compatibility contract',
       },
       {
+        path: 'src/crates/contracts/runtime-ports/src/lib.rs',
         regex: /\bdialog_trigger_source_reuses_agent_submission_source_contract\b/,
         message: 'missing dialog trigger source alias regression',
       },
@@ -5332,31 +5401,111 @@ export const requiredContentRules = [
         message: 'missing compression contract rendering regression',
       },
       {
+        path: 'src/crates/contracts/runtime-ports/src/lib.rs',
         regex: /\bpub struct RelatedPath\b/,
         message: 'missing related path request-context contract',
       },
       {
+        path: 'src/crates/contracts/runtime-ports/src/lib.rs',
         regex: /\brelated_path_serializes_as_request_context_fact\b/,
         message: 'missing related path serialization regression',
       },
       {
+        path: 'src/crates/contracts/runtime-ports/src/lib.rs',
         regex: /\bpub struct DelegationPolicy\b/,
         message: 'missing delegation policy contract',
       },
       {
+        path: 'src/crates/contracts/runtime-ports/src/lib.rs',
         regex: /\bpub enum SubagentContextMode\b/,
         message: 'missing subagent context mode contract',
       },
       {
+        path: 'src/crates/contracts/runtime-ports/src/lib.rs',
         regex: /\bdelegation_policy_child_blocks_recursive_spawn_without_losing_depth\b/,
         message: 'missing delegation policy contract regression',
       },
       {
+        path: 'src/crates/contracts/runtime-ports/src/lib.rs',
         regex: /\bsubagent_context_mode_preserves_fork_wire_value\b/,
         message: 'missing subagent context mode contract regression',
       },
     ],
   },
+  {
+    path: 'src/crates/execution/agent-runtime/src/lib.rs',
+    reason: 'Agent Runtime leaf capability modules must stay behind their exact owner features',
+    patterns: [
+      {
+        regex: /#\[cfg\(feature = "deep-research"\)\]\r?\npub mod deep_research;/,
+        message: 'deep-research must gate its pure report capability',
+      },
+      {
+        regex: /#\[cfg\(feature = "native-hook-settings"\)\]\r?\npub mod native_hooks;/,
+        message: 'native-hook-settings must gate the portable hook facade',
+      },
+      ...agentRuntimeRootPublicModules
+        .filter((moduleName) => !['deep_research', 'native_hooks'].includes(moduleName))
+        .map((moduleName) => ({
+          regex: new RegExp(`#\\[cfg\\(feature = "agent-runtime"\\)\\]\\r?\\npub mod ${moduleName};`),
+          message: `${moduleName} must stay behind the full agent-runtime owner`,
+        })),
+    ],
+  },
+  {
+    path: 'src/crates/execution/agent-runtime/src/native_hooks/mod.rs',
+    reason: 'native hook execution modules must stay behind native-hook-runtime',
+    patterns: [
+      ...['engine', 'output', 'payload'].flatMap((moduleName) => [
+        {
+          regex: new RegExp(`#\\[cfg\\(feature = "native-hook-runtime"\\)\\]\\r?\\nmod ${moduleName};`),
+          message: `${moduleName} must stay behind native-hook-runtime`,
+        },
+        {
+          regex: new RegExp(`#\\[cfg\\(feature = "native-hook-runtime"\\)\\]\\r?\\npub use ${moduleName}(?:::|\\{)`),
+          message: `${moduleName} exports must stay behind native-hook-runtime`,
+        },
+      ]),
+    ],
+  },
+  {
+    path: 'src/crates/contracts/runtime-ports/src/lib.rs',
+    reason: 'runtime-ports capability features must gate their owned source modules and exports',
+    patterns: [
+      { regex: /#\[cfg\(feature = "agent-api"\)\]\r?\nmod agent_api;/, message: 'agent-api must gate its source module' },
+      { regex: /#\[cfg\(feature = "agent-api"\)\]\r?\npub use agent_api::\*;/, message: 'agent-api must gate its public exports' },
+      { regex: /#\[cfg\(feature = "plugin-runtime"\)\]\r?\nmod plugin;/, message: 'plugin-runtime must gate its source module' },
+      { regex: /#\[cfg\(feature = "plugin-runtime"\)\]\r?\npub use plugin::\{/, message: 'plugin-runtime must gate its public exports' },
+      { regex: /#\[cfg\(feature = "script-tool-runtime"\)\]\r?\nmod script_tool;/, message: 'script-tool-runtime must gate its source module' },
+      { regex: /#\[cfg\(feature = "script-tool-runtime"\)\]\r?\npub use script_tool::\{/, message: 'script-tool-runtime must gate its public exports' },
+      { regex: /#\[cfg\(feature = "workspace-ports"\)\]\r?\nmod workspace_ports;/, message: 'workspace-ports must gate its source module' },
+      { regex: /#\[cfg\(feature = "workspace-ports"\)\]\r?\npub use workspace_ports::\*;/, message: 'workspace-ports must gate its public exports' },
+      { regex: /#\[cfg\(feature = "terminal-port"\)\]\r?\nmod terminal_port;/, message: 'terminal-port must gate its source module' },
+      { regex: /#\[cfg\(feature = "terminal-port"\)\]\r?\npub use terminal_port::\*;/, message: 'terminal-port must gate its public exports' },
+      { regex: /#\[cfg\(feature = "remote-exec-port"\)\]\r?\nmod remote_exec_port;/, message: 'remote-exec-port must gate its source module' },
+      { regex: /#\[cfg\(feature = "remote-exec-port"\)\]\r?\npub use remote_exec_port::\*;/, message: 'remote-exec-port must gate its public exports' },
+      { regex: /#\[cfg\(feature = "remote-workspace-ports"\)\]\r?\nmod remote_workspace_ports;/, message: 'remote-workspace-ports must gate its source module' },
+      { regex: /#\[cfg\(feature = "remote-workspace-ports"\)\]\r?\npub use remote_workspace_ports::\*;/, message: 'remote-workspace-ports must gate its public exports' },
+      { regex: /#\[cfg\(feature = "runtime-event-port"\)\]\r?\nmod runtime_event_port;/, message: 'runtime-event-port must gate its source module' },
+      { regex: /#\[cfg\(feature = "runtime-event-port"\)\]\r?\npub use runtime_event_port::\*;/, message: 'runtime-event-port must gate its public exports' },
+      { regex: /#\[cfg\(feature = "git-port"\)\]\r?\nmod git_port;/, message: 'git-port must gate its source module' },
+      { regex: /#\[cfg\(feature = "git-port"\)\]\r?\npub use git_port::\*;/, message: 'git-port must gate its public exports' },
+      { regex: /#\[cfg\(feature = "tool-runtime-handles"\)\]\r?\nmod tool_runtime_handles;/, message: 'tool-runtime-handles must gate its source module' },
+      { regex: /#\[cfg\(feature = "tool-runtime-handles"\)\]\r?\npub use tool_runtime_handles::\*;/, message: 'tool-runtime-handles must gate its public exports' },
+    ],
+  },
+  {
+    path: 'src/crates/execution/tool-contracts/src/lib.rs',
+    reason: 'tool-contract capability features must gate their owned source modules and exports',
+    patterns: [
+      { regex: /#\[cfg\(feature = "acp-bridge"\)\]\r?\npub mod acp_tool_bridge;/, message: 'acp-bridge must gate its source module' },
+      { regex: /#\[cfg\(feature = "acp-bridge"\)\]\r?\npub use acp_tool_bridge::\{/, message: 'acp-bridge must gate its public exports' },
+      { regex: /#\[cfg\(feature = "mcp-bridge"\)\]\r?\npub mod mcp_tool_bridge;/, message: 'mcp-bridge must gate its source module' },
+      { regex: /#\[cfg\(feature = "mcp-bridge"\)\]\r?\npub use mcp_tool_bridge::\{/, message: 'mcp-bridge must gate its public exports' },
+      { regex: /#\[cfg\(feature = "computer-use-contract"\)\]\r?\npub mod computer_use;/, message: 'computer-use-contract must gate its source module' },
+      { regex: /#\[cfg\(feature = "element-token"\)\]\r?\npub mod element_token;/, message: 'element-token must gate its source module' },
+    ],
+  },
   {
     path: 'src/crates/assembly/core/src/agentic/subagent_runtime/mod.rs',
     reason:
@@ -9604,7 +9753,7 @@ export const requiredContentRules = [
   {
     path: 'src/crates/assembly/core/src/function_agents/port_adapters.rs',
     reason:
-      'core function-agent port adapters must continue owning AI concrete calls while product-domains owns prompt, parser, and facade policy',
+      'core function-agent port adapters must continue owning AI concrete calls while product-domains owns Git prompt, parser, and facade policy',
     patterns: [
       {
         regex: /\bprepare_commit_ai_prompt\b/,
@@ -9614,14 +9763,6 @@ export const requiredContentRules = [
         regex: /\bparse_commit_ai_response\b/,
         message: 'missing product-domain Git function-agent response policy use',
       },
-      {
-        regex: /\bbuild_work_state_analysis_prompt\b/,
-        message: 'missing product-domain Startchat prompt policy use',
-      },
-      {
-        regex: /\bparse_work_state_analysis_response\b/,
-        message: 'missing product-domain Startchat response policy use',
-      },
       {
         regex: /\bai_client\s*\.\s*send_message\b/,
         message: 'missing core-owned function-agent AI call',
@@ -9634,18 +9775,10 @@ export const requiredContentRules = [
         regex: /\bCoreCommitAiAnalysisService\b/,
         message: 'missing core-owned commit AI concrete service',
       },
-      {
-        regex: /\bCoreWorkStateAiAnalysisService\b/,
-        message: 'missing core-owned Startchat AI concrete service',
-      },
       {
         regex: /\bparse_commit_response_preserves_product_domain_response_policy\b/,
         message: 'missing Git function-agent AI response boundary regression test',
       },
-      {
-        regex: /\bparse_complete_analysis_preserves_product_domain_response_policy\b/,
-        message: 'missing Startchat AI response boundary regression test',
-      },
     ],
   },
   {
@@ -9661,14 +9794,6 @@ export const requiredContentRules = [
         regex: /\bgit_commit_snapshot\b/,
         message: 'missing commit snapshot service method',
       },
-      {
-        regex: /\bstartchat_git_snapshot\b/,
-        message: 'missing Startchat Git snapshot service method',
-      },
-      {
-        regex: /\bstartchat_time_snapshot\b/,
-        message: 'missing Startchat time snapshot service method',
-      },
       {
         regex: /\bGitService::get_status\b/,
         message: 'missing shared GitService status lookup',
@@ -9681,41 +9806,17 @@ export const requiredContentRules = [
         regex: /\bContextAnalyzer::analyze_project_context\b/,
         message: 'missing product-domain project context analysis',
       },
-      {
-        regex: /\bprocess_manager::create_command\("git"\)/,
-        message: 'missing process-manager backed lenient Git command fallback',
-      },
-      {
-        regex: /\bgit_unpushed_commits\b/,
-        message: 'missing unpushed-commit fallback helper',
-      },
-      {
-        regex: /\bgit_ahead_behind\b/,
-        message: 'missing ahead/behind fallback helper',
-      },
-      {
-        regex: /\bgit_last_commit_timestamp\b/,
-        message: 'missing last-commit timestamp helper',
-      },
     ],
   },
   {
     path: 'src/crates/services/services-integrations/tests/function_agent_contracts.rs',
     reason:
-      'services-integrations function-agent Git service must preserve legacy Git snapshot behavior',
+      'services-integrations function-agent Git service must preserve commit snapshot behavior',
     patterns: [
       {
         regex: /\bgit_service_builds_commit_snapshot_from_staged_diff_without_unstaged_content\b/,
         message: 'missing staged/unstaged boundary regression test',
       },
-      {
-        regex: /\bgit_service_startchat_snapshot_preserves_no_head_and_non_git_fallback\b/,
-        message: 'missing Startchat no-HEAD and non-Git fallback regression test',
-      },
-      {
-        regex: /\bgit_service_time_snapshot_uses_last_commit_timestamp\b/,
-        message: 'missing time snapshot regression test',
-      },
     ],
   },
   {
@@ -9729,17 +9830,6 @@ export const requiredContentRules = [
       },
     ],
   },
-  {
-    path: 'src/crates/assembly/core/src/function_agents/startchat-func-agent/ai_service.rs',
-    reason:
-      'legacy Startchat AI service path must remain a compatibility re-export only',
-    patterns: [
-      {
-        regex: /\bCoreWorkStateAiAnalysisService as AIWorkStateService\b/,
-        message: 'missing Startchat AI service compatibility re-export',
-      },
-    ],
-  },
   {
     path: 'src/crates/assembly/core/src/function_agents/git-func-agent/commit_generator.rs',
     reason:
@@ -9850,21 +9940,6 @@ export const requiredContentRules = [
       },
     ],
   },
-  {
-    path: 'src/crates/assembly/core/src/function_agents/startchat-func-agent/work_state_analyzer.rs',
-    reason:
-      'legacy Startchat work-state analyzer must delegate to the core product-domain runtime owner',
-    patterns: [
-      {
-        regex: /\bCoreProductDomainRuntime\b/,
-        message: 'missing core product-domain runtime owner routing',
-      },
-      {
-        regex: /\banalyze_function_agent_work_state\b/,
-        message: 'missing Startchat work-state owner method delegation',
-      },
-    ],
-  },
   {
     path: 'src/crates/contracts/product-domains/src/function_agents/ports.rs',
     reason:
@@ -9878,22 +9953,6 @@ export const requiredContentRules = [
         regex: /\bgenerate_commit_message\b/,
         message: 'missing function-agent commit facade orchestration',
       },
-      {
-        regex: /\banalyze_work_state\b/,
-        message: 'missing function-agent work-state facade orchestration',
-      },
-      {
-        regex: /\bgit_work_state_from_snapshot\b/,
-        message: 'missing Startchat Git snapshot projection helper',
-      },
-      {
-        regex: /\bStartchatTimeSnapshot\b/,
-        message: 'missing Startchat time snapshot contract',
-      },
-      {
-        regex: /\bstartchat_time_snapshot\b/,
-        message: 'missing Startchat time snapshot port',
-      },
     ],
   },
   {
@@ -9911,41 +9970,6 @@ export const requiredContentRules = [
       },
     ],
   },
-  {
-    path: 'src/crates/contracts/product-domains/src/function_agents/startchat_func_agent/utils.rs',
-    reason:
-      'product-domains owns Startchat function-agent prompt and response policy while core keeps AI calls',
-    patterns: [
-      {
-        regex: /\bpub const WORK_STATE_ANALYSIS_PROMPT\b/,
-        message: 'missing product-domain Startchat prompt template',
-      },
-      {
-        regex: /\bpub fn build_work_state_analysis_prompt\b/,
-        message: 'missing product-domain Startchat prompt builder',
-      },
-      {
-        regex: /\bpub struct ParsedCompleteAnalysis\b/,
-        message: 'missing Startchat complete-analysis parse result contract',
-      },
-      {
-        regex: /\bpub fn parse_complete_analysis_value\b/,
-        message: 'missing Startchat complete-analysis value parser',
-      },
-      {
-        regex: /\bpub fn parse_complete_analysis_json\b/,
-        message: 'missing Startchat complete-analysis JSON parser',
-      },
-      {
-        regex: /\bpub fn parse_work_state_analysis_response\b/,
-        message: 'missing Startchat AI response policy',
-      },
-      {
-        regex: /\bwork_state_ai_response_policy_extracts_json_and_maps_domain_errors\b/,
-        message: 'missing Startchat AI response policy regression test',
-      },
-    ],
-  },
   {
     path: 'src/crates/contracts/product-domains/src/function_agents/git_func_agent/utils.rs',
     reason:
@@ -10130,21 +10154,13 @@ export const requiredContentRules = [
         message: 'missing Git adapter delegation to integration runtime service',
       },
       {
-        regex: /\bCoreCommitAiAnalysisService::new_with_agent_config\b/,
+        regex: /\bCoreCommitAiAnalysisService::new_with_task_config\b/,
         message: 'missing commit AI adapter delegation to concrete runtime service',
       },
-      {
-        regex: /\bCoreWorkStateAiAnalysisService::new_with_agent_config\b/,
-        message: 'missing Startchat AI adapter delegation to concrete runtime service',
-      },
       {
         regex: /\bgit_adapter_commit_snapshot_keeps_staged_diff_and_unstaged_count_separate\b/,
         message: 'missing function-agent Git snapshot boundary regression test',
       },
-      {
-        regex: /\bgit_adapter_startchat_snapshot_preserves_git_state_when_diff_has_no_head\b/,
-        message: 'missing Startchat Git diff fallback regression test',
-      },
     ],
   },
   {
@@ -10176,10 +10192,6 @@ export const requiredContentRules = [
         regex: /\bfn generate_function_agent_commit_message\b/,
         message: 'missing Git function-agent concrete runtime owner entrypoint',
       },
-      {
-        regex: /\bfn analyze_function_agent_work_state\b/,
-        message: 'missing Startchat concrete runtime owner entrypoint',
-      },
       {
         regex: /\bCoreFunctionAgentGitAdapter\b/,
         message: 'missing core-owned Git adapter binding',
diff --git a/scripts/core-boundaries/self-test.mjs b/scripts/core-boundaries/self-test.mjs
index f2ce820c41..0344a9b1a8 100644
--- a/scripts/core-boundaries/self-test.mjs
+++ b/scripts/core-boundaries/self-test.mjs
@@ -7,6 +7,7 @@ export function runManifestParserSelfTest({
   parseManifestDependencies,
   manifestDependencyMatches,
   matchingForbiddenDependency,
+  acpClosedFeatureProfileRules,
   coreClosedFeatureProfileRules,
   coreProductFullFeatureAssemblyRule,
   ownerCrateFeatureAssemblyRules,
@@ -60,10 +61,13 @@ export function runManifestParserSelfTest({
   const explicitTestManifest = [
     '[package]',
     'autotests = false',
-    ...agentRuntimeIntegrationTestTargets.flatMap(({ name, path }) => [
+    ...agentRuntimeIntegrationTestTargets.flatMap(({ name, path, requiredFeatures }) => [
       '[[test]]',
       `name = "${name}"`,
       `path = "${path}"`,
+      ...(requiredFeatures === undefined
+        ? []
+        : [`required-features = [${requiredFeatures.map((feature) => `"${feature}"`).join(', ')}]`]),
     ]),
     '[lints]',
   ].join('\n');
@@ -152,6 +156,56 @@ export function runManifestParserSelfTest({
   if (!orphanErrors.some((error) => error.includes('orphan_contracts.rs'))) {
     throw new Error('explicit integration-test topology must reject an orphan leaf test');
   }
+  const reviewedLeafTargets = agentRuntimeIntegrationTestTargets.map((target) => (
+    target.path === 'tests/agent_definition_contracts.rs'
+      ? {
+          ...target,
+          leaves: ['tests/agent_definition_contracts/prompt_contracts.rs'],
+        }
+      : target
+  ));
+  const missingReviewedLeafErrors = validateExplicitIntegrationTestTopology({
+    ...explicitTestFixture,
+    expectedTargets: reviewedLeafTargets,
+    leafRustFiles: [],
+    leafSources: new Map(),
+  });
+  if (!missingReviewedLeafErrors.some((error) => error.includes('grouped test leaves'))) {
+    throw new Error('explicit integration-test topology must reject a removed reviewed leaf');
+  }
+  for (const requiredFeaturesDeclaration of [
+    'required-features = [\n  "opt-in",\n]',
+    '"required\\u002dfeatures" = ["opt-in"]',
+  ]) {
+    const unexpectedRequiredFeaturesErrors = validateExplicitIntegrationTestTopology({
+      ...explicitTestFixture,
+      expectedTargets: reviewedLeafTargets,
+      manifestText: explicitTestManifest.replace(
+        'required-features = ["agent-runtime"]',
+        requiredFeaturesDeclaration,
+      ),
+    });
+    if (!unexpectedRequiredFeaturesErrors.some((error) => error.includes('required-features'))) {
+      throw new Error(`ungated explicit test topology accepted: ${requiredFeaturesDeclaration}`);
+    }
+  }
+  const independentRequiredFeaturesErrors = validateExplicitIntegrationTestTopology({
+    ...explicitTestFixture,
+    expectedTargets: reviewedLeafTargets.map((target) => (
+      target.path === 'tests/native_hook_execution_contracts.rs'
+        ? { ...target, requiredFeatures: ['native-hooks'] }
+        : target
+    )),
+    manifestText: explicitTestManifest.replace(
+      'required-features = ["native-hook-runtime"]',
+      'required-features = ["native-hooks"]',
+    ),
+  });
+  if (independentRequiredFeaturesErrors.length > 0) {
+    throw new Error(
+      `target-scoped required-features contract rejected an independent target: ${independentRequiredFeaturesErrors.join('; ')}`,
+    );
+  }
   const reviewedLeafCfgFixture = {
     ...explicitTestFixture,
     leafSources: new Map([[
@@ -316,6 +370,8 @@ export function runManifestParserSelfTest({
 
   for (const featureName of [
     'agent-runtime',
+    'diagnostics',
+    'diff',
     'announcement',
     'canvas-runtime',
     'debug-log',
@@ -323,6 +379,7 @@ export function runManifestParserSelfTest({
     'file-watch',
     'filesystem',
     'git',
+    'i18n-runtime',
     'lsp',
     'local-storage',
     'process-runtime',
@@ -352,11 +409,30 @@ export function runManifestParserSelfTest({
   const coreManifest = 'src/crates/assembly/core/Cargo.toml';
   const servicesCoreManifest = 'src/crates/services/services-core/Cargo.toml';
   const expectedClosedCoreProfiles = [
+    [coreManifest, 'default', []],
+    [coreManifest, 'i18n-runtime', ['dep:fluent-bundle', 'dep:unic-langid']],
+    [coreManifest, 'diagnostics', ['bitfun-services-core/diagnostics']],
+    [coreManifest, 'diff', ['bitfun-services-core/diff']],
     [servicesCoreManifest, 'default', []],
+    [servicesCoreManifest, 'diagnostics', ['dep:regex']],
+    [
+      servicesCoreManifest,
+      'diff',
+      ['dep:similar', 'dep:tokio', 'tokio/rt', 'tokio/time'],
+    ],
     [
       servicesCoreManifest,
       'filesystem',
-      ['dep:base64', 'dep:chrono', 'dep:ignore', 'dep:sha2', 'tokio/fs'],
+      [
+        'dep:base64',
+        'dep:chrono',
+        'dep:ignore',
+        'dep:regex',
+        'dep:sha2',
+        'dep:tokio',
+        'tokio/fs',
+        'tokio/rt',
+      ],
     ],
     [
       servicesCoreManifest,
@@ -367,10 +443,15 @@ export function runManifestParserSelfTest({
         'dep:chrono',
         'dep:fs2',
         'dep:libc',
+        'dep:regex',
         'dep:sha2',
+        'dep:similar',
+        'dep:tokio',
         'dep:windows',
         'tokio/fs',
+        'tokio/rt',
         'tokio/sync',
+        'tokio/time',
         'windows/Win32_Foundation',
         'windows/Win32_Storage_FileSystem',
       ],
@@ -380,11 +461,14 @@ export function runManifestParserSelfTest({
       'process-runtime',
       [
         'dep:libc',
+        'dep:tokio',
         'dep:which',
         'dep:win32job',
         'dep:windows',
         'tokio/io-util',
         'tokio/process',
+        'tokio/rt',
+        'tokio/time',
         'windows/Win32_Foundation',
         'windows/Win32_System_Diagnostics_ToolHelp',
         'windows/Win32_System_Threading',
@@ -393,7 +477,20 @@ export function runManifestParserSelfTest({
     [
       servicesCoreManifest,
       'workspace-instructions',
-      ['dep:globset', 'dep:serde_yaml', 'tokio/fs', 'tokio/io-util'],
+      [
+        'dep:globset',
+        'dep:regex',
+        'dep:serde_yaml',
+        'dep:tokio',
+        'tokio/fs',
+        'tokio/io-util',
+        'tokio/rt',
+      ],
+    ],
+    [
+      servicesCoreManifest,
+      'workspace-text-runtime',
+      ['dep:tokio', 'tokio/rt'],
     ],
     [
       servicesCoreManifest,
@@ -416,6 +513,8 @@ export function runManifestParserSelfTest({
         'dep:anyhow',
         'dep:async-trait',
         'dep:bitfun-runtime-ports',
+        'bitfun-runtime-ports/runtime-event-port',
+        'bitfun-runtime-ports/workspace-ports',
         'dep:dunce',
         'process-runtime',
         'tokio/fs',
@@ -425,11 +524,19 @@ export function runManifestParserSelfTest({
     ],
     [servicesCoreManifest, 'session-git', ['local-storage', 'dep:git2']],
     [servicesCoreManifest, 'workspace-identity', ['dep:dunce', 'dep:sha2']],
-    [coreManifest, 'dispatch-store', ['local-storage', 'bitfun-services-core/dispatch-workspace']],
+    [
+      coreManifest,
+      'dispatch-store',
+      ['dep:base64', 'local-storage', 'bitfun-services-core/dispatch-workspace'],
+    ],
     [coreManifest, 'filesystem', ['bitfun-services-core/filesystem']],
-    [coreManifest, 'local-storage', ['bitfun-services-core/local-storage']],
+    [
+      coreManifest,
+      'local-storage',
+      ['dep:bitfun-agent-tools', 'bitfun-services-core/local-storage'],
+    ],
     [coreManifest, 'process-runtime', ['bitfun-services-core/process-runtime']],
-    [coreManifest, 'lsp', ['dep:notify', 'bitfun-services-core/lsp']],
+    [coreManifest, 'lsp', ['dep:notify', 'bitfun-services-core/lsp', 'tokio/macros']],
     [coreManifest, 'terminal', ['dep:terminal-core']],
     [
       coreManifest,
@@ -492,6 +599,70 @@ export function runManifestParserSelfTest({
       throw new Error(`core closed feature profile must not reach product-full in ${featureName}`);
     }
   }
+  const acpProfiles = new Map(
+    acpClosedFeatureProfileRules.map((rule) => [rule.featureName, rule]),
+  );
+  const expectedAcpProfiles = new Map([
+    ['default', ['client', 'server']],
+    [
+      'client',
+      [
+        'bitfun-agent-tools/acp-bridge',
+        'dep:futures',
+        'dep:serde',
+        // The bundled DeepSeek Harness profile the ACP client materializes:
+        // $DSH_HOME lookup, a minimum-version comparison, and packing the
+        // profile for a remote host.
+        'dep:dirs',
+        'dep:semver',
+        'dep:tar',
+        'dep:bitfun-core',
+        'bitfun-core/agent-runtime',
+        'bitfun-core/ssh-remote',
+      ],
+    ],
+    [
+      'server',
+      [
+        'dep:bitfun-agent-tools',
+        'dep:bitfun-agent-runtime',
+        'bitfun-agent-runtime/agent-runtime',
+        'dep:bitfun-core-types',
+        'dep:bitfun-core',
+        'dep:sha2',
+        'bitfun-core/agent-runtime',
+        'bitfun-core/document-read',
+        'bitfun-core/subscription-auth',
+        'bitfun-core/deep-research',
+        'bitfun-core/lsp',
+        'bitfun-core/external-sources',
+        'bitfun-core/tools-basic',
+        'bitfun-core/tools-git',
+        'bitfun-core/tools-mcp',
+        'bitfun-core/tools-browser-web',
+        'bitfun-core/tools-computer-use',
+        'bitfun-core/tools-image-analysis',
+        'bitfun-core/tools-miniapp',
+        'bitfun-core/tools-canvas',
+        'bitfun-core/tools-agent-control',
+      ],
+    ],
+  ]);
+  for (const [featureName, expectedReferences] of expectedAcpProfiles) {
+    const rule = acpProfiles.get(featureName);
+    if (!rule?.exact) {
+      throw new Error(`ACP closed feature profile must cover ${featureName} exactly`);
+    }
+    if (
+      rule.requiredFeatureRefs.length !== expectedReferences.length
+      || expectedReferences.some((reference) => !rule.requiredFeatureRefs.includes(reference))
+    ) {
+      throw new Error(`ACP closed feature profile has stale references for ${featureName}`);
+    }
+    if (rule.requiredFeatureRefs.some((reference) => reference.includes('product-full'))) {
+      throw new Error(`ACP closed feature profile must not reach product-full in ${featureName}`);
+    }
+  }
   const ownerFeatureRulePaths = new Set(
     ownerCrateFeatureAssemblyRules.map((rule) => rule.manifestPath),
   );
@@ -913,6 +1084,7 @@ export function runManifestParserSelfTest({
     'schannel',
     'win32job',
     'bitfun-relay-service',
+    'bitfun-transport',
     'htmd',
     'legible',
     'readability-js',
@@ -931,6 +1103,7 @@ export function runManifestParserSelfTest({
     'aes',
     'aes-gcm',
     'bitfun-relay-service',
+    'bitfun-transport',
     'eventsource-stream',
     'git2',
     'glob',
@@ -968,45 +1141,6 @@ export function runManifestParserSelfTest({
   const servicesOptionalOwnerRule = optionalDependencyFeatureOwnerRules.find(
     (rule) => rule.crateName === 'services-integrations',
   );
-  const workspaceReqwestRule = requiredContentRules.find((rule) => rule.path === 'Cargo.toml');
-  const workspaceReqwestRuleText = workspaceReqwestRule?.patterns
-    .map((pattern) => pattern.regex.source)
-    .join('\n') ?? '';
-  for (const featureName of ['http2', 'json', 'stream', 'multipart', 'query', 'form']) {
-    if (!workspaceReqwestRuleText.includes(featureName)) {
-      throw new Error(`workspace Reqwest boundary must allow only reviewed feature ${featureName}`);
-    }
-  }
-  const workspaceReqwestPattern = workspaceReqwestRule?.patterns[0]?.regex;
-  const reviewedReqwestDeclaration =
-    'reqwest = { version = "0.13.4", default-features = false, features = ["http2", "json", "stream", "multipart", "query", "form"] }';
-  if (!workspaceReqwestPattern?.test(reviewedReqwestDeclaration)) {
-    throw new Error('workspace Reqwest boundary must accept the reviewed transport/data profile');
-  }
-  for (const featureName of ['default-tls', 'http3', '__native-tls']) {
-    const expandedDeclaration = reviewedReqwestDeclaration.replace(
-      '"form"]',
-      `"form", "${featureName}"]`,
-    );
-    if (workspaceReqwestPattern.test(expandedDeclaration)) {
-      throw new Error(`workspace Reqwest boundary must reject TLS-enabling feature ${featureName}`);
-    }
-  }
-  for (const path of [
-    'src/apps/cli/Cargo.toml',
-    'src/apps/desktop/Cargo.toml',
-    'src/crates/adapters/ai-adapters/Cargo.toml',
-    'src/crates/services/miniapp-market-service/Cargo.toml',
-    'src/crates/services/skin-market-service/Cargo.toml',
-  ]) {
-    const reqwestRule = requiredContentRules.find((rule) => rule.path === path);
-    const reqwestRuleText = reqwestRule?.patterns
-      .map((pattern) => pattern.regex.source)
-      .join('\n') ?? '';
-    if (!reqwestRuleText.includes('rustls')) {
-      throw new Error(`${path} must guard the explicit Reqwest Rustls client dependency`);
-    }
-  }
   const servicesCoreOptionalOwnerRule = optionalDependencyFeatureOwnerRules.find(
     (rule) => rule.crateName === 'services-core',
   );
@@ -1029,8 +1163,13 @@ export function runManifestParserSelfTest({
     ['ignore', ['filesystem']],
     ['libc', ['local-storage', 'process-runtime']],
     ['notify', ['lsp']],
+    [
+      'regex',
+      ['diagnostics', 'filesystem', 'local-storage', 'markdown', 'workspace-instructions'],
+    ],
     ['rusqlite', ['permission']],
     ['serde_yaml', ['markdown', 'workspace-instructions']],
+    ['similar', ['diff', 'local-storage']],
     [
       'sha2',
       [
@@ -1045,6 +1184,21 @@ export function runManifestParserSelfTest({
     ['win32job', ['process-runtime']],
     ['windows', ['json-io', 'local-storage', 'process-runtime']],
     ['zip', ['lsp']],
+    [
+      'tokio',
+      [
+        'diff',
+        'filesystem',
+        'json-io',
+        'local-storage',
+        'lsp',
+        'permission',
+        'process-runtime',
+        'workspace-instructions',
+        'workspace-runtime',
+        'workspace-text-runtime',
+      ],
+    ],
   ]);
   for (const [dependencyName, ownerFeatures] of expectedServicesCoreOwners) {
     const dependency = servicesCoreOptionalOwnerRule?.dependencies.find(
@@ -1320,6 +1474,9 @@ export function runManifestParserSelfTest({
   const pluginPublicApiRule = publicApiAllowlistRules.find(
     (rule) => rule.path === 'src/crates/contracts/runtime-ports/src/plugin.rs',
   );
+  const agentRuntimePublicApiRule = publicApiAllowlistRules.find(
+    (rule) => rule.path === 'src/crates/execution/agent-runtime/src/lib.rs',
+  );
   const pluginRootReexportRule = publicApiAllowlistRules.find(
     (rule) => rule.path === 'src/crates/contracts/runtime-ports/src/lib.rs',
   );
@@ -1415,6 +1572,20 @@ export function runManifestParserSelfTest({
   ) {
     throw new Error('public API parser must collect top-level items and re-exports without impl methods');
   }
+  const parsedAgentRuntimeModules = collectTopLevelRustPublicSymbols(`
+    #[cfg(feature = "agent-runtime")]
+    pub mod agents;
+    pub mod accidental_feature_free_api;
+  `);
+  if (!agentRuntimePublicApiRule?.allowedSymbols?.includes('agents')) {
+    throw new Error('Agent Runtime public API allowlist must include reviewed owner modules');
+  }
+  if (
+    !parsedAgentRuntimeModules.includes('accidental_feature_free_api') ||
+    agentRuntimePublicApiRule.allowedSymbols.includes('accidental_feature_free_api')
+  ) {
+    throw new Error('Agent Runtime public API allowlist must reject an unreviewed feature-free module');
+  }
   const parsedExternalSubagentIds = collectTopLevelRustPublicSymbols(`
     external_subagent_id!(ExternalSubagentLocalId, "local");
     external_subagent_id!(
@@ -2356,7 +2527,7 @@ export function runManifestParserSelfTest({
 
   const requiredContentContracts = [
     {
-      path: 'src/crates/contracts/runtime-ports/src/lib.rs',
+      path: 'src/crates/contracts/runtime-ports/src/agent_api.rs',
       contracts: [
         'AgentDialogTurnRequest',
         'AgentDialogPrependedReminder',
@@ -3258,7 +3429,7 @@ export function runManifestParserSelfTest({
       ],
     },
     {
-      path: 'src/crates/assembly/product-capabilities/tests/product_capabilities.rs',
+      path: 'src/crates/assembly/product-capabilities/tests/product_capability_contracts/product_capabilities.rs',
       contracts: [
         'product_assembly_plan_exposes_build_feature_groups_explicitly',
         'product_runtime_assembly_reports_runtime_service_capability_gaps',
@@ -3266,7 +3437,7 @@ export function runManifestParserSelfTest({
       ],
     },
     {
-      path: 'src/crates/assembly/product-capabilities/tests/plugin_product_shape.rs',
+      path: 'src/crates/assembly/product-capabilities/tests/product_capability_contracts/plugin_product_shape.rs',
       contracts: [
         'executable_plugin_runtime_is_limited_to_product_full_desktop_and_cli',
         'executable_plugin_runtime_client_builds_agent_runtime_parts',
@@ -3305,7 +3476,7 @@ export function runManifestParserSelfTest({
       ],
     },
     {
-      path: 'src/crates/assembly/product-capabilities/tests/product_sdk_assembly.rs',
+      path: 'src/crates/assembly/product-capabilities/tests/product_capability_contracts/product_sdk_assembly.rs',
       contracts: [
         'product_runtime_parts_can_build_agent_runtime_sdk_without_core',
         'sdk_delivery_profile_builds_shared_runtime_owner_ceiling_without_bitfun_core',
@@ -4239,7 +4410,7 @@ export function runManifestParserSelfTest({
       contracts: ['renumber_research_report', 'ResearchCitationRenumberOutput', 'ResearchCitationDisplayMapEntry', 'rejected_index_rows_dropped', 'should_post_process_research_report'],
     },
     {
-      path: 'src/crates/execution/agent-runtime/tests/agent_long_horizon_contracts/deep_research_contracts.rs',
+      path: 'src/crates/execution/agent-runtime/tests/deep_research_contracts.rs',
       contracts: ['deep_research_citation_renumber_owner_preserves_report_and_display_map_contracts', 'deep_research_citation_renumber_owner_is_idempotent_without_citations'],
     },
     {
@@ -4300,11 +4471,11 @@ export function runManifestParserSelfTest({
     {
       path: 'src/crates/assembly/core/Cargo.toml',
       contracts: [
-        'bitfun-product-capabilities = \\{ path = "\\.\\.\\/product-capabilities", default-features = false, optional = true \\}',
+        'bitfun-product-capabilities = \\{ path = "\\.\\.\\/product-capabilities", optional = true \\}',
         'bitfun-ai-adapters = \\{ path = "\\.\\.\\/\\.\\.\\/adapters\\/ai-adapters", optional = true \\}',
-        'bitfun-tool-packs = \\{ path = "\\.\\.\\/\\.\\.\\/execution\\/tool-provider-groups", default-features = false, optional = true \\}',
-        'bitfun-services-integrations = \\{ path = "\\.\\.\\/\\.\\.\\/services\\/services-integrations", default-features = false, optional = true \\}',
-        'bitfun-product-domains = \\{ path = "\\.\\.\\/\\.\\.\\/contracts\\/product-domains", default-features = false, optional = true \\}',
+        'bitfun-tool-packs = \\{ path = "\\.\\.\\/\\.\\.\\/execution\\/tool-provider-groups", optional = true \\}',
+        'bitfun-services-integrations = \\{ path = "\\.\\.\\/\\.\\.\\/services\\/services-integrations", optional = true \\}',
+        'bitfun-product-domains = \\{ path = "\\.\\.\\/\\.\\.\\/contracts\\/product-domains", optional = true \\}',
         'dep:bitfun-ai-adapters',
         'ai-adapter-runtime',
         'canvas-runtime',
@@ -4875,14 +5046,11 @@ export function runManifestParserSelfTest({
       contracts: [
         'prepare_commit_ai_prompt',
         'parse_commit_ai_response',
-        'build_work_state_analysis_prompt',
-        'parse_work_state_analysis_response',
         'send_message',
         'AgentError::internal_error',
         'CoreCommitAiAnalysisService',
-        'CoreWorkStateAiAnalysisService',
+        'CoreCommitAiAnalysisService::new_with_task_config',
         'parse_commit_response_preserves_product_domain_response_policy',
-        'parse_complete_analysis_preserves_product_domain_response_policy',
       ],
     },
     {
@@ -4890,64 +5058,33 @@ export function runManifestParserSelfTest({
       contracts: [
         'FunctionAgentGitService',
         'git_commit_snapshot',
-        'startchat_git_snapshot',
-        'startchat_time_snapshot',
-        'process_manager::create_command("git")',
-        'git_unpushed_commits',
-        'git_ahead_behind',
-        'git_last_commit_timestamp',
       ],
     },
     {
       path: 'src/crates/services/services-integrations/tests/function_agent_contracts.rs',
       contracts: [
         'git_service_builds_commit_snapshot_from_staged_diff_without_unstaged_content',
-        'git_service_startchat_snapshot_preserves_no_head_and_non_git_fallback',
-        'git_service_time_snapshot_uses_last_commit_timestamp',
       ],
     },
     {
       path: 'src/crates/assembly/core/src/function_agents/git-func-agent/ai_service.rs',
       contracts: ['CoreCommitAiAnalysisService as AIAnalysisService'],
     },
-    {
-      path: 'src/crates/assembly/core/src/function_agents/startchat-func-agent/ai_service.rs',
-      contracts: ['CoreWorkStateAiAnalysisService as AIWorkStateService'],
-    },
     {
       path: 'src/crates/assembly/core/src/function_agents/git-func-agent/commit_generator.rs',
       contracts: ['CoreProductDomainRuntime', 'generate_function_agent_commit_message'],
     },
-    {
-      path: 'src/crates/assembly/core/src/function_agents/startchat-func-agent/work_state_analyzer.rs',
-      contracts: ['CoreProductDomainRuntime', 'analyze_function_agent_work_state'],
-    },
     {
       path: 'src/crates/contracts/product-domains/src/function_agents/ports.rs',
       contracts: [
         'FunctionAgentRuntimeFacade',
         'generate_commit_message',
-        'analyze_work_state',
-        'git_work_state_from_snapshot',
-        'StartchatTimeSnapshot',
-        'startchat_time_snapshot',
       ],
     },
     {
       path: 'src/crates/contracts/product-domains/src/function_agents/common.rs',
       contracts: ['extract_json_from_ai_response', 'try_repair_json'],
     },
-    {
-      path: 'src/crates/contracts/product-domains/src/function_agents/startchat_func_agent/utils.rs',
-      contracts: [
-        'WORK_STATE_ANALYSIS_PROMPT',
-        'build_work_state_analysis_prompt',
-        'ParsedCompleteAnalysis',
-        'parse_complete_analysis_value',
-        'parse_complete_analysis_json',
-        'parse_work_state_analysis_response',
-      ],
-    },
     {
       path: 'src/crates/contracts/product-domains/src/function_agents/git_func_agent/utils.rs',
       contracts: [
@@ -5451,7 +5588,6 @@ async fn release_baseline_claim(release: BaselineClaimRelease) -> Result<(), Dis
     'bitfun-sdk-host',
     'bitfun-services-core',
     'bitfun-services-integrations',
-    'bitfun-transport',
     'terminal-core',
     'tool-runtime',
     'tauri',
@@ -5463,13 +5599,14 @@ async fn release_baseline_claim(release: BaselineClaimRelease) -> Result<(), Dis
       throw new Error(`agent-runtime-ipc lightweight boundary must forbid ${dependency}`);
     }
   }
-  for (const sharedContract of [
+  for (const allowedDependency of [
     'bitfun-events',
     'bitfun-product-domains',
     'bitfun-runtime-ports',
+    'bitfun-transport',
   ]) {
-    if (runtimeIpcBoundary?.forbiddenDeps.includes(sharedContract)) {
-      throw new Error(`agent-runtime-ipc must be allowed to reuse ${sharedContract}`);
+    if (runtimeIpcBoundary?.forbiddenDeps.includes(allowedDependency)) {
+      throw new Error(`agent-runtime-ipc must be allowed to reuse ${allowedDependency}`);
     }
   }
   const runtimeIpcProfile = dependencyProfileRules.find(
@@ -5555,4 +5692,52 @@ async fn release_baseline_claim(release: BaselineClaimRelease) -> Result<(), Dis
       'agent-runtime-ipc local-only guard must cover network transports in new private modules',
     );
   }
+  const runtimeIpcSharedTransportPattern = runtimeIpcTransportRule?.patterns.find(
+    (pattern) => pattern.message.includes('bounded JSON API'),
+  )?.regex;
+  if (
+    !runtimeIpcSharedTransportPattern ||
+    !runtimeIpcSharedTransportPattern.test('use bitfun_transport::TransportAdapter;') ||
+    !runtimeIpcSharedTransportPattern.test('use bitfun_transport as transport;') ||
+    runtimeIpcSharedTransportPattern.test('use bitfun_transport::encode_json_with_limit;') ||
+    runtimeIpcSharedTransportPattern.test('use bitfun_transport::JsonCodecError;')
+  ) {
+    throw new Error(
+      'agent-runtime-ipc may consume only the reviewed bitfun-transport bounded JSON API',
+    );
+  }
+  const runtimeIpcTransportFeatureRule = forbiddenContentRules.find(
+    (rule) => rule.path === 'src/crates/adapters/agent-runtime-ipc/Cargo.toml' &&
+      rule.reason.includes('bitfun-transport features'),
+  );
+  const runtimeIpcTransportFeaturePattern =
+    runtimeIpcTransportFeatureRule?.patterns[0]?.regex;
+  if (
+    !runtimeIpcTransportFeaturePattern?.test(
+      'bitfun-transport = { path = "../transport", features = ["tauri-adapter"] }',
+    ) ||
+    runtimeIpcTransportFeaturePattern.test(
+      'bitfun-transport = { path = "../transport" }',
+    )
+  ) {
+    throw new Error('agent-runtime-ipc must not enable bitfun-transport features');
+  }
+  const runtimeIpcTransportDependencyRule = requiredContentRules.find(
+    (rule) => rule.path === 'src/crates/adapters/agent-runtime-ipc/Cargo.toml' &&
+      rule.reason.includes('exact feature-free bitfun-transport dependency'),
+  );
+  const runtimeIpcTransportDependencyPattern =
+    runtimeIpcTransportDependencyRule?.patterns[0]?.regex;
+  if (
+    !runtimeIpcTransportDependencyPattern?.test(
+      'bitfun-transport = { path = "../transport" }',
+    ) ||
+    runtimeIpcTransportDependencyPattern.test(
+      'bitfun-transport = {\n  path = "../transport",\n  features = ["tauri-adapter"]\n}',
+    )
+  ) {
+    throw new Error(
+      'agent-runtime-ipc must keep the exact feature-free bitfun-transport dependency',
+    );
+  }
 }
diff --git a/scripts/desktop-tauri-build.mjs b/scripts/desktop-tauri-build.mjs
index 24bf28cf31..d2ab567a26 100644
--- a/scripts/desktop-tauri-build.mjs
+++ b/scripts/desktop-tauri-build.mjs
@@ -4,6 +4,8 @@ import { spawnSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'path';
 import {
+  chmodSync,
+  copyFileSync,
   existsSync,
   mkdirSync,
   readFileSync,
@@ -15,6 +17,7 @@ import { ensureFlashgrepBinary } from './prepare-flashgrep-resource.mjs';
 import { extractProductConfigArg } from './product-customization/cli.mjs';
 import { productBuildEnvironment } from './product-customization/projections.mjs';
 import { resolveProductDefinition } from './product-customization/resolver.mjs';
+import { resolveReleaseChannel } from './release-channel.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = join(__dirname, '..');
@@ -40,18 +43,28 @@ async function main() {
   const resolution = resolveProductDefinition({ rootDir: ROOT, productConfig, member: 'desktop' });
   Object.assign(process.env, productBuildEnvironment(resolution));
   console.log(`[product] ${resolution.assembly.member} ${resolution.assembly.assemblyDigest}`);
-
-  const flashgrepBinary = ensureFlashgrepBinary();
-  process.env.FLASHGREP_DAEMON_BIN = flashgrepBinary;
+  const releaseChannel = resolveReleaseChannel(process.env.BITFUN_RELEASE_CHANNEL);
+  console.log(`[release] channel=${releaseChannel.channel}`);
 
   const desktopDir = join(ROOT, 'src', 'apps', 'desktop');
+  const flashgrepBinary = prepareMacOSFlashgrepForSigning(
+    ensureFlashgrepBinary(),
+    desktopDir,
+  );
+  process.env.FLASHGREP_DAEMON_BIN = flashgrepBinary;
   // Tauri CLI reads CI and rejects numeric "1" (common in CI providers).
   process.env.CI = 'true';
+  if (process.platform === 'darwin' && requestsDmgBundle(forward)) {
+    // Tauri otherwise passes --skip-jenkins under CI, which drops the branded
+    // Finder background and icon positions from the generated DMG.
+    process.env.TAURI_BUNDLER_DMG_IGNORE_CI = 'true';
+  }
 
   const tauriConfig = prepareTauriConfig(join(desktopDir, 'tauri.conf.json'), {
     desktopDir,
     flashgrepBinary,
     resolution,
+    releaseChannel,
   });
   const tauriBin = join(ROOT, 'node_modules', '.bin', 'tauri');
   const tauriArgs = ['build', '--config', tauriConfig, ...forward];
@@ -71,10 +84,6 @@ async function main() {
     process.exit(1);
   }
 
-  if (r.status === 0 && process.platform === 'darwin') {
-    patchDmgExtras(ROOT);
-  }
-
   // Keep only the latest useful Cargo caches for this build profile after tauri build ends.
   try {
     const { profileFromTauriBuildArgs, runGcBestEffort, targetFromTauriBuildArgs } = await import(
@@ -166,9 +175,49 @@ function optionValue(args, option) {
   return undefined;
 }
 
+export function prepareMacOSFlashgrepForSigning(
+  flashgrepBinary,
+  desktopDir,
+  runtime = {},
+) {
+  const platform = runtime.platform ?? process.platform;
+  const signingIdentity = runtime.signingIdentity ?? process.env.APPLE_SIGNING_IDENTITY;
+  if (platform !== 'darwin' || !signingIdentity) {
+    return flashgrepBinary;
+  }
+
+  const signedDir = join(desktopDir, 'gen', 'signed-resources', 'flashgrep');
+  const signedBinary = join(signedDir, basename(flashgrepBinary));
+  mkdirSync(signedDir, { recursive: true });
+  copyFileSync(flashgrepBinary, signedBinary);
+  chmodSync(signedBinary, statSync(signedBinary).mode | 0o111);
+
+  const run = runtime.spawnSync ?? spawnSync;
+  const result = run(
+    'codesign',
+    [
+      '--force',
+      '--sign',
+      signingIdentity,
+      '--options',
+      'runtime',
+      '--timestamp',
+      signedBinary,
+    ],
+    { encoding: 'utf8', shell: false },
+  );
+  if (result.error || result.status !== 0) {
+    const detail = result.error?.message || result.stderr || `exit status ${result.status}`;
+    throw new Error(`Failed to sign bundled flashgrep binary: ${detail}`);
+  }
+
+  console.log(`[tauri-build] Signed bundled flashgrep binary: ${signedBinary}`);
+  return signedBinary;
+}
+
 export function prepareTauriConfig(
   baseConfigPath,
-  { desktopDir, flashgrepBinary, resolution }
+  { desktopDir, flashgrepBinary, resolution, releaseChannel }
 ) {
   const config = JSON.parse(readFileSync(baseConfigPath, 'utf8'));
   if (resolution) {
@@ -180,6 +229,21 @@ export function prepareTauriConfig(
     config.identifier = resolution.assembly.bundleId;
   }
   injectTargetFlashgrepResource(config, desktopDir, flashgrepBinary);
+  // The DeepSeek bridge is not a compile-time resource: cargo check and
+  // desktop:dev must not require packages/dsh-acp/dist-profile. Official
+  // packaging injects it here; frontend:build-all (beforeBuildCommand)
+  // compiles the profile before Tauri copies resources.
+  injectDshProfileResource(config);
+
+  const release = releaseChannel
+    ?? resolveReleaseChannel(process.env.BITFUN_RELEASE_CHANNEL);
+  const primaryEndpoint =
+    process.env.TAURI_UPDATER_ENDPOINT || release.primaryUpdaterEndpoint;
+  const fallbackEndpoint =
+    process.env.TAURI_UPDATER_FALLBACK_ENDPOINT || release.fallbackUpdaterEndpoint;
+  process.env.BITFUN_RELEASE_CHANNEL = release.channel;
+  process.env.BITFUN_UPDATER_PRIMARY_ENDPOINT = primaryEndpoint;
+  process.env.BITFUN_UPDATER_FALLBACK_ENDPOINT = fallbackEndpoint;
 
   const enabled = ['1', 'true', 'yes'].includes(
     String(process.env.BITFUN_ENABLE_UPDATER_ARTIFACTS || '').toLowerCase()
@@ -196,16 +260,9 @@ export function prepareTauriConfig(
       process.exit(1);
     }
 
-    const primaryEndpoint =
-      process.env.TAURI_UPDATER_ENDPOINT ||
-      'https://github.com/GCWing/BitFun/releases/latest/download/latest.json';
     // Fallback endpoint used when GitHub is unreachable (not when no update is found).
     // Tauri updater iterates endpoints and only falls through on network/HTTP errors;
     // a 204 (no update) or a successfully parsed manifest stops the loop.
-    const fallbackEndpoint =
-      process.env.TAURI_UPDATER_FALLBACK_ENDPOINT ||
-      'https://openbitfun.com/release/latest.json';
-
     config.bundle = {
       ...(config.bundle || {}),
       createUpdaterArtifacts: true,
@@ -221,7 +278,7 @@ export function prepareTauriConfig(
       },
     };
     console.log(
-      `[tauri-build] Updater artifacts enabled: ${primaryEndpoint} (fallback: ${fallbackEndpoint})`
+      `[tauri-build] Updater artifacts enabled for ${release.channel}: ${primaryEndpoint} (fallback: ${fallbackEndpoint})`
     );
   }
 
@@ -237,6 +294,18 @@ export function prepareTauriConfig(
   return generatedConfig;
 }
 
+const DSH_PROFILE_RESOURCE_SOURCE = '../../../packages/dsh-acp/dist-profile';
+const DSH_PROFILE_RESOURCE_TARGET = 'resources/dsh-profile';
+
+function injectDshProfileResource(config) {
+  const resources = { ...(config.bundle?.resources || {}) };
+  resources[DSH_PROFILE_RESOURCE_SOURCE] = DSH_PROFILE_RESOURCE_TARGET;
+  config.bundle = {
+    ...(config.bundle || {}),
+    resources,
+  };
+}
+
 function injectTargetFlashgrepResource(config, desktopDir, flashgrepBinary) {
   const resources = { ...(config.bundle?.resources || {}) };
   delete resources['../../../resources/flashgrep'];
@@ -270,48 +339,6 @@ function toTauriPath(value) {
   return value.split(sep).join('/');
 }
 
-// Find all .dmg files under target/ and inject the helper TXT files
-// (quarantine removal instructions) into each one.
-function patchDmgExtras(root) {
-  const patchScript = join(root, 'scripts', 'patch-dmg-extras.sh');
-  const targetDir = join(root, 'target');
-
-  const dmgFiles = findDmgFiles(targetDir);
-  if (dmgFiles.length === 0) {
-    console.log('[patch-dmg] No .dmg files found — skipping.');
-    return;
-  }
-
-  for (const dmg of dmgFiles) {
-    console.log(`[patch-dmg] Patching ${dmg}`);
-    const p = spawnSync('bash', [patchScript, dmg], {
-      stdio: 'inherit',
-      shell: false,
-    });
-    if (p.status !== 0) {
-      console.error(`[patch-dmg] Failed to patch ${dmg}`);
-      process.exit(1);
-    }
-  }
-}
-
-function findDmgFiles(dir) {
-  const results = [];
-  try {
-    for (const entry of readdirSync(dir, { withFileTypes: true })) {
-      const full = join(dir, entry.name);
-      if (entry.isDirectory()) {
-        results.push(...findDmgFiles(full));
-      } else if (entry.name.endsWith('.dmg')) {
-        results.push(full);
-      }
-    }
-  } catch {
-    // directory may not exist for some targets
-  }
-  return results;
-}
-
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
   main().catch((e) => {
     console.error(e);
diff --git a/scripts/desktop-tauri-build.test.mjs b/scripts/desktop-tauri-build.test.mjs
index 4f15bc11bd..1dd4350ac6 100644
--- a/scripts/desktop-tauri-build.test.mjs
+++ b/scripts/desktop-tauri-build.test.mjs
@@ -3,13 +3,109 @@ import { mkdirSync, readFileSync, rmSync, utimesSync, writeFileSync } from 'node
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import test from 'node:test';
-import { prepareTauriConfig, shouldRetryMacDmgBuild } from './desktop-tauri-build.mjs';
+import {
+  prepareMacOSFlashgrepForSigning,
+  prepareTauriConfig,
+  shouldRetryMacDmgBuild,
+} from './desktop-tauri-build.mjs';
 import { resolveProductDefinition } from './product-customization/resolver.mjs';
 
 const FAILED_BUILD = { status: 1 };
 const DMG_ARGS = ['--target', 'x86_64-apple-darwin', '--bundles', 'app,dmg'];
 const ROOT = join(import.meta.dirname, '..');
 
+test('release builds do not mutate DMGs after Tauri signs and notarizes them', () => {
+  const source = readFileSync(join(ROOT, 'scripts', 'desktop-tauri-build.mjs'), 'utf8');
+  assert.doesNotMatch(source, /patchDmgExtras/);
+  assert.doesNotMatch(source, /patch-dmg-extras\.sh/);
+  assert.match(source, /TAURI_BUNDLER_DMG_IGNORE_CI = 'true'/);
+});
+
+test('Desktop DMG uses the branded installer layout', () => {
+  const config = JSON.parse(
+    readFileSync(join(ROOT, 'src', 'apps', 'desktop', 'tauri.conf.json'), 'utf8')
+  );
+  assert.deepEqual(config.bundle.macOS.dmg, {
+    background: 'dmg/background.png',
+    windowSize: { width: 660, height: 400 },
+    appPosition: { x: 180, y: 170 },
+    applicationFolderPosition: { x: 480, y: 170 },
+  });
+});
+
+test('macOS release signing covers the bundled flashgrep executable', () => {
+  const fixture = join(tmpdir(), `bitfun-flashgrep-signing-${process.pid}-${Date.now()}`);
+  const desktopDir = join(fixture, 'src', 'apps', 'desktop');
+  const source = join(fixture, 'flashgrep-aarch64-apple-darwin');
+  const calls = [];
+  mkdirSync(desktopDir, { recursive: true });
+  writeFileSync(source, 'test-binary');
+
+  try {
+    const signed = prepareMacOSFlashgrepForSigning(source, desktopDir, {
+      platform: 'darwin',
+      signingIdentity: 'Developer ID Application: Test (TEAMID)',
+      spawnSync: (...args) => {
+        calls.push(args);
+        return { status: 0 };
+      },
+    });
+
+    assert.notEqual(signed, source);
+    assert.equal(readFileSync(signed, 'utf8'), 'test-binary');
+    assert.deepEqual(calls[0][0], 'codesign');
+    assert.deepEqual(calls[0][1], [
+      '--force',
+      '--sign',
+      'Developer ID Application: Test (TEAMID)',
+      '--options',
+      'runtime',
+      '--timestamp',
+      signed,
+    ]);
+  } finally {
+    rmSync(fixture, { force: true, recursive: true });
+  }
+});
+
+test('unsigned and non-macOS builds keep the original flashgrep executable', () => {
+  assert.equal(
+    prepareMacOSFlashgrepForSigning('/tmp/flashgrep', '/tmp/desktop', {
+      platform: 'darwin',
+      signingIdentity: '',
+    }),
+    '/tmp/flashgrep',
+  );
+  assert.equal(
+    prepareMacOSFlashgrepForSigning('/tmp/flashgrep', '/tmp/desktop', {
+      platform: 'linux',
+      signingIdentity: 'unused',
+    }),
+    '/tmp/flashgrep',
+  );
+});
+
+test('macOS packaging fails when bundled flashgrep signing fails', () => {
+  const fixture = join(tmpdir(), `bitfun-flashgrep-signing-failure-${process.pid}-${Date.now()}`);
+  const desktopDir = join(fixture, 'src', 'apps', 'desktop');
+  const source = join(fixture, 'flashgrep-x86_64-apple-darwin');
+  mkdirSync(desktopDir, { recursive: true });
+  writeFileSync(source, 'test-binary');
+
+  try {
+    assert.throws(
+      () => prepareMacOSFlashgrepForSigning(source, desktopDir, {
+        platform: 'darwin',
+        signingIdentity: 'Developer ID Application: Test (TEAMID)',
+        spawnSync: () => ({ status: 1, stderr: 'identity unavailable' }),
+      }),
+      /Failed to sign bundled flashgrep binary: identity unavailable/,
+    );
+  } finally {
+    rmSync(fixture, { force: true, recursive: true });
+  }
+});
+
 function retryFixture() {
   const root = join(tmpdir(), `bitfun-dmg-retry-${process.pid}-${Date.now()}`);
   const desktopDir = join(root, 'src', 'apps', 'desktop');
@@ -130,7 +226,12 @@ test('Windows updater installs NSIS packages without showing its progress window
   const baseConfig = join(fixture, 'tauri.conf.json');
   const updaterEnv = {
     BITFUN_ENABLE_UPDATER_ARTIFACTS: process.env.BITFUN_ENABLE_UPDATER_ARTIFACTS,
+    BITFUN_RELEASE_CHANNEL: process.env.BITFUN_RELEASE_CHANNEL,
+    BITFUN_UPDATER_FALLBACK_ENDPOINT: process.env.BITFUN_UPDATER_FALLBACK_ENDPOINT,
+    BITFUN_UPDATER_PRIMARY_ENDPOINT: process.env.BITFUN_UPDATER_PRIMARY_ENDPOINT,
     TAURI_SIGNING_PRIVATE_KEY: process.env.TAURI_SIGNING_PRIVATE_KEY,
+    TAURI_UPDATER_ENDPOINT: process.env.TAURI_UPDATER_ENDPOINT,
+    TAURI_UPDATER_FALLBACK_ENDPOINT: process.env.TAURI_UPDATER_FALLBACK_ENDPOINT,
     TAURI_UPDATER_PUBKEY: process.env.TAURI_UPDATER_PUBKEY,
   };
   mkdirSync(fixture, { recursive: true });
@@ -146,6 +247,7 @@ test('Windows updater installs NSIS packages without showing its progress window
     });
     const config = JSON.parse(readFileSync(generated, 'utf8'));
     assert.equal(config.plugins.updater.windows.installMode, 'quiet');
+    assert.match(config.plugins.updater.endpoints[0], /releases\/latest\/download/);
   } finally {
     for (const [name, value] of Object.entries(updaterEnv)) {
       if (value === undefined) {
@@ -158,6 +260,99 @@ test('Windows updater installs NSIS packages without showing its progress window
   }
 });
 
+test('beta Desktop artifacts compile and bundle only beta updater endpoints', () => {
+  const fixture = join(tmpdir(), `bitfun-tauri-beta-${process.pid}-${Date.now()}`);
+  const baseConfig = join(fixture, 'tauri.conf.json');
+  const names = [
+    'BITFUN_ENABLE_UPDATER_ARTIFACTS',
+    'BITFUN_RELEASE_CHANNEL',
+    'BITFUN_UPDATER_FALLBACK_ENDPOINT',
+    'BITFUN_UPDATER_PRIMARY_ENDPOINT',
+    'TAURI_SIGNING_PRIVATE_KEY',
+    'TAURI_UPDATER_ENDPOINT',
+    'TAURI_UPDATER_FALLBACK_ENDPOINT',
+    'TAURI_UPDATER_PUBKEY',
+  ];
+  const previous = Object.fromEntries(names.map((name) => [name, process.env[name]]));
+  mkdirSync(fixture, { recursive: true });
+  writeFileSync(baseConfig, JSON.stringify({ bundle: { resources: {} } }));
+  process.env.BITFUN_ENABLE_UPDATER_ARTIFACTS = 'true';
+  process.env.BITFUN_RELEASE_CHANNEL = 'beta';
+  process.env.TAURI_SIGNING_PRIVATE_KEY = 'test-private-key';
+  process.env.TAURI_UPDATER_PUBKEY = 'test-public-key';
+  delete process.env.TAURI_UPDATER_ENDPOINT;
+  delete process.env.TAURI_UPDATER_FALLBACK_ENDPOINT;
+
+  try {
+    const generated = prepareTauriConfig(baseConfig, {
+      desktopDir: fixture,
+      flashgrepBinary: join(fixture, 'flashgrep'),
+    });
+    const config = JSON.parse(readFileSync(generated, 'utf8'));
+    assert.equal(
+      config.plugins.updater.endpoints[0],
+      'https://github.com/GCWing/BitFun/releases/download/channel-beta/latest.json',
+    );
+    assert.equal(
+      config.plugins.updater.endpoints[1],
+      'https://openbitfun.com/release/beta/latest.json',
+    );
+    assert.equal(
+      process.env.BITFUN_UPDATER_PRIMARY_ENDPOINT,
+      config.plugins.updater.endpoints[0],
+    );
+    assert.equal(
+      process.env.BITFUN_UPDATER_FALLBACK_ENDPOINT,
+      config.plugins.updater.endpoints[1],
+    );
+  } finally {
+    for (const [name, value] of Object.entries(previous)) {
+      if (value === undefined) delete process.env[name];
+      else process.env[name] = value;
+    }
+    rmSync(fixture, { force: true, recursive: true });
+  }
+});
+
+test('static desktop Tauri configs do not require the DeepSeek profile at compile time', () => {
+  for (const name of ['tauri.conf.json', 'tauri.dev.conf.json']) {
+    const config = JSON.parse(
+      readFileSync(join(ROOT, 'src', 'apps', 'desktop', name), 'utf8')
+    );
+    assert.equal(
+      config.bundle.resources['../../../packages/dsh-acp/dist-profile'],
+      undefined,
+      `${name} must not list dist-profile as a compile-time resource`,
+    );
+  }
+});
+
+test('official packaging injects the DeepSeek profile resource', () => {
+  const fixture = join(tmpdir(), `bitfun-tauri-dsh-${process.pid}-${Date.now()}`);
+  mkdirSync(fixture, { recursive: true });
+  const baseConfig = join(fixture, 'tauri.conf.json');
+  writeFileSync(baseConfig, JSON.stringify({
+    bundle: { resources: { 'resources/worker_host.js': 'resources/worker_host.js' } },
+  }));
+  try {
+    const generated = prepareTauriConfig(baseConfig, {
+      desktopDir: fixture,
+      flashgrepBinary: join(fixture, 'flashgrep'),
+    });
+    const config = JSON.parse(readFileSync(generated, 'utf8'));
+    assert.equal(
+      config.bundle.resources['../../../packages/dsh-acp/dist-profile'],
+      'resources/dsh-profile',
+    );
+    assert.equal(
+      config.bundle.resources['resources/worker_host.js'],
+      'resources/worker_host.js',
+    );
+  } finally {
+    rmSync(fixture, { force: true, recursive: true });
+  }
+});
+
 test('Desktop release config bundles models.dev notices and provenance', () => {
   const config = JSON.parse(
     readFileSync(join(ROOT, 'src', 'apps', 'desktop', 'tauri.conf.json'), 'utf8')
diff --git a/scripts/dev.cjs b/scripts/dev.cjs
index d218cb06b4..07cf156307 100644
--- a/scripts/dev.cjs
+++ b/scripts/dev.cjs
@@ -649,7 +649,9 @@ async function main() {
   // Step 1: Run all independent preparation tasks in parallel.
   // copy-monaco / generate-version / mobile-web / flashgrep have no
   // dependencies on each other; each task's output is line-prefixed so the
-  // interleaved logs stay attributable.
+  // interleaved logs stay attributable. The DeepSeek bridge is not prepared
+  // here: it is not a compile-time Tauri resource. Official desktop:build
+  // compiles it; local DeepSeek sessions run `pnpm run prepare:dsh-profile`.
   printStep(
     currentStep++,
     totalSteps,
diff --git a/scripts/diagnostics/analyze-flowchat-log.mjs b/scripts/diagnostics/analyze-flowchat-log.mjs
index 5cc894753c..081250c44b 100644
--- a/scripts/diagnostics/analyze-flowchat-log.mjs
+++ b/scripts/diagnostics/analyze-flowchat-log.mjs
@@ -1,16 +1,75 @@
+/**
+ * Read `flowchat.log` and answer the questions the viewport trail exists for.
+ *
+ * The log is JSONL, one object per entry, written by
+ * `src/web-ui/src/infrastructure/diagnostics/flowChatDiagnostics.ts` behind
+ * `app.logging.flow_chat_diagnostics`. Viewport entries carry the tag
+ * `viewport`; history paging carries `history-paging`.
+ *
+ * The reports here are not a frequency count with extra steps. Each one
+ * corresponds to a fault that has actually shipped:
+ *
+ * - **Placements that did not stick.** A Turn that lands and is dragged away
+ *   and a Turn that never landed leave the same final position, so every
+ *   placement is recorded with what became of it and the drift is what
+ *   separates them.
+ * - **Fights.** Travel far exceeding net displacement is two writers undoing
+ *   each other — the shape of a snap back reissued 958 times without arriving.
+ * - **Refusals.** Who was outranked, by whom. A write that never happened is
+ *   invisible in the DOM and in every other log.
+ * - **Silent declines.** Each writer's reason for not moving. "Nothing
+ *   happened" has been the report more often than "it moved wrongly".
+ *
+ * Entries carry a `repeated` summary when the frontend coalesced a run of
+ * identical events, so every count here weighs an entry by what it stands for
+ * rather than by one. Ignoring that would under-report exactly the runaway
+ * loops the log is for.
+ */
+
 import { createReadStream } from 'node:fs';
 import { createInterface } from 'node:readline';
+import { fileURLToPath } from 'node:url';
+
+/** Joins the parts of a composite map key; cannot occur inside one. */
+const KEY_SEPARATOR = String.fromCharCode(31);
+
+const VIEWPORT_TAG = 'viewport';
+const WRITE_LOCATION = 'viewportOwner.write';
+const OUTCOME_SUFFIX = '.outcome';
+const DROPPED_ENTRY_LOCATION = 'FlowChatDiagnosticsRecorder.flush';
+
+/** Locations whose whole purpose is to record a movement that did not happen. */
+const DECLINE_LOCATIONS = new Set([
+  'anchor.dropped',
+  'anchor.stoodDown',
+  'followOutput.deferNewTurn',
+  'historyPaging.refused',
+  'snapBack.declined',
+  'snapBack.notNeeded',
+  'turnNavigation.rejected',
+]);
+
+export const DEFAULT_OPTIONS = {
+  top: 20,
+  minDrift: 8,
+  gapMs: 750,
+  around: null,
+  radius: 12,
+  tags: [],
+};
 
 function printUsage() {
   console.log(`Usage:
   node scripts/diagnostics/analyze-flowchat-log.mjs <flowchat.log> [options]
 
 Options:
-  --top <count>       Maximum rows per summary table (default: 20)
-  --min-delta <px>    Minimum positive reservation jump to show (default: 100)
-  --around <sequence> Show a compact event window around a sequence
-  --radius <count>    Sequence radius for --around (default: 8)
-  --help              Show this help`);
+  --top <count>        Maximum rows per table (default: ${DEFAULT_OPTIONS.top})
+  --min-drift <px>     Report a placement as unstuck past this drift (default: ${DEFAULT_OPTIONS.minDrift})
+  --gap <ms>           Quiet period that ends an episode (default: ${DEFAULT_OPTIONS.gapMs})
+  --around <sequence>  Print the raw entries around a sequence number
+  --radius <count>     Sequence radius for --around (default: ${DEFAULT_OPTIONS.radius})
+  --tag <name>         Only entries with this hypothesis tag; repeatable
+  --help               Show this help`);
 }
 
 function parseNumberOption(args, index, optionName) {
@@ -22,7 +81,11 @@ function parseNumberOption(args, index, optionName) {
   return value;
 }
 
-function parseArgs(argv) {
+export function parseArgs(rawArgv) {
+  // `npm run … -- <path>` forwards the separator itself; pnpm forwards it too
+  // when it is typed. Either way it is not an argument.
+  const argv = rawArgv[0] === '--' ? rawArgv.slice(1) : rawArgv;
+
   if (argv.includes('--help')) {
     printUsage();
     process.exit(0);
@@ -34,21 +97,18 @@ function parseArgs(argv) {
     throw new Error('A FlowChat JSONL log path is required');
   }
 
-  const options = {
-    logPath,
-    top: 20,
-    minDelta: 100,
-    around: null,
-    radius: 8,
-  };
+  const options = { ...DEFAULT_OPTIONS, tags: [], logPath };
 
   for (let index = 1; index < argv.length; index += 1) {
     const arg = argv[index];
     if (arg === '--top') {
       options.top = Math.max(1, Math.floor(parseNumberOption(argv, index, arg)));
       index += 1;
-    } else if (arg === '--min-delta') {
-      options.minDelta = Math.max(0, parseNumberOption(argv, index, arg));
+    } else if (arg === '--min-drift') {
+      options.minDrift = Math.max(0, parseNumberOption(argv, index, arg));
+      index += 1;
+    } else if (arg === '--gap') {
+      options.gapMs = Math.max(0, parseNumberOption(argv, index, arg));
       index += 1;
     } else if (arg === '--around') {
       options.around = Math.floor(parseNumberOption(argv, index, arg));
@@ -56,6 +116,11 @@ function parseArgs(argv) {
     } else if (arg === '--radius') {
       options.radius = Math.max(0, Math.floor(parseNumberOption(argv, index, arg)));
       index += 1;
+    } else if (arg === '--tag') {
+      const tag = argv[index + 1];
+      if (!tag || tag.startsWith('--')) throw new Error('--tag requires a name');
+      options.tags.push(tag);
+      index += 1;
     } else {
       throw new Error(`Unknown option: ${arg}`);
     }
@@ -70,11 +135,26 @@ function finiteNumber(value) {
 }
 
 function round(value) {
-  return Math.round(finiteNumber(value) * 100) / 100;
+  return Math.round(finiteNumber(value) * 10) / 10;
 }
 
-function reservationTotal(reservation) {
-  return finiteNumber(reservation?.collapse?.px) + finiteNumber(reservation?.pin?.px);
+/**
+ * What one entry stands for.
+ *
+ * A coalesced entry is one line describing a run, so counting it as one event
+ * would report a 300-write fight as a handful of writes. Travel is the same
+ * question for distance.
+ */
+export function entryWeight(entry) {
+  return 1 + Math.max(0, Math.floor(finiteNumber(entry?.data?.repeated?.suppressedCount)));
+}
+
+export function entryTravelPx(entry) {
+  const data = entry?.data ?? {};
+  const own = data.toPx === undefined || data.fromPx === undefined
+    ? 0
+    : Math.abs(finiteNumber(data.toPx) - finiteNumber(data.fromPx));
+  return own + Math.abs(finiteNumber(data.repeated?.suppressedTravelPx));
 }
 
 function compactData(data) {
@@ -83,131 +163,330 @@ function compactData(data) {
   return serialized.length <= 240 ? serialized : `${serialized.slice(0, 237)}...`;
 }
 
-async function analyze(options) {
-  const eventCounts = new Map();
-  const reservationJumps = [];
-  const collapseIntents = [];
-  const sequenceWindow = [];
-  let lineCount = 0;
-  let eventCount = 0;
-  let parseErrorCount = 0;
-
-  const input = createReadStream(options.logPath, { encoding: 'utf8' });
-  const lines = createInterface({ input, crlfDelay: Infinity });
+function increment(map, key, by = 1) {
+  map.set(key, (map.get(key) ?? 0) + by);
+}
 
-  for await (const line of lines) {
-    lineCount += 1;
-    if (!line.trim()) continue;
+/**
+ * Group viewport writes into stretches of activity.
+ *
+ * A fault is a period, not an entry: "it flickered for a second when I opened
+ * the session" is one episode with several owners in it. The gap that ends one
+ * is wall-clock, because the interesting silence is the reader looking at a
+ * still transcript.
+ */
+export function collectEpisodes(writes, gapMs) {
+  const episodes = [];
+  let current = null;
 
-    let event;
-    try {
-      event = JSON.parse(line);
-    } catch {
-      parseErrorCount += 1;
-      continue;
+  for (const write of writes) {
+    const atMs = finiteNumber(write.performanceTimeMs);
+    if (current === null || atMs - current.endMs > gapMs) {
+      current = {
+        firstSequence: write.sequence,
+        lastSequence: write.sequence,
+        startMs: atMs,
+        endMs: atMs,
+        writes: 0,
+        refusals: 0,
+        travelPx: 0,
+        fromPx: null,
+        toPx: null,
+        owners: new Map(),
+      };
+      episodes.push(current);
     }
-    eventCount += 1;
 
-    const countKey = `${event.location ?? ''}\u0000${event.message ?? ''}`;
-    const existingCount = eventCounts.get(countKey);
-    if (existingCount) {
-      existingCount.count += 1;
+    const weight = entryWeight(write);
+    const granted = write.data?.granted !== false;
+    current.lastSequence = write.sequence;
+    current.endMs = atMs;
+    current.travelPx += entryTravelPx(write);
+    if (granted) {
+      current.writes += weight;
+      if (current.fromPx === null) current.fromPx = finiteNumber(write.data?.fromPx);
+      current.toPx = finiteNumber(write.data?.toPx);
     } else {
-      eventCounts.set(countKey, {
-        count: 1,
-        location: event.location ?? '',
-        message: event.message ?? '',
-      });
+      current.refusals += weight;
     }
+    increment(current.owners, String(write.data?.owner ?? 'unknown'), weight);
+  }
+
+  return episodes.map(episode => {
+    const netPx = episode.fromPx === null ? 0 : episode.toPx - episode.fromPx;
+    return {
+      sequences: `${episode.firstSequence}-${episode.lastSequence}`,
+      durationMs: Math.round(episode.endMs - episode.startMs),
+      writes: episode.writes,
+      refusals: episode.refusals,
+      travelPx: round(episode.travelPx),
+      netPx: round(netPx),
+      /*
+       * Distance travelled per pixel of progress. One means a clean move;
+       * anything large is writers undoing each other, and it is the number to
+       * sort by when the report is "it shook".
+       */
+      churn: Math.abs(netPx) < 1
+        ? round(episode.travelPx)
+        : round(episode.travelPx / Math.abs(netPx)),
+      owners: [...episode.owners.entries()]
+        .sort((left, right) => right[1] - left[1])
+        .map(([owner, count]) => `${owner}x${count}`)
+        .join(' '),
+    };
+  });
+}
 
-    if (
-      event.location === 'VirtualMessageList.updateBottomReservationState' &&
-      event.data?.before &&
-      event.data?.after
-    ) {
-      const before = reservationTotal(event.data.before);
-      const after = reservationTotal(event.data.after);
-      const delta = after - before;
-      if (delta >= options.minDelta) {
-        reservationJumps.push({
-          sequence: event.sequence,
-          deltaPx: round(delta),
-          beforePx: round(before),
-          afterPx: round(after),
-          collapsePx: round(event.data.after.collapse?.px),
-          pinPx: round(event.data.after.pin?.px),
-          coordinatorMode: event.data.coordinatorMode ?? '',
-          following: event.data.isFollowingOutput === true,
-          streaming: event.data.isStreamingOutput === true,
-        });
+/**
+ * Pair every placement with the sample taken after it settled.
+ *
+ * Matched first-in-first-out per location: an outcome lands hundreds of
+ * milliseconds after its placement, so another placement of the same kind can
+ * begin in between, and the queue keeps them in order. An outcome with nothing
+ * pending is reported rather than dropped — it means the log starts mid-flight.
+ */
+export function joinPlacements(entries) {
+  const pending = new Map();
+  const placements = [];
+  const orphanedOutcomes = [];
+
+  for (const entry of entries) {
+    const location = String(entry.location ?? '');
+    if (location.endsWith(OUTCOME_SUFFIX)) {
+      const placedLocation = location.slice(0, -OUTCOME_SUFFIX.length);
+      const queue = pending.get(placedLocation);
+      const placement = queue?.shift();
+      if (!placement) {
+        orphanedOutcomes.push({ sequence: entry.sequence, location: placedLocation });
+        continue;
       }
+      placement.outcome = entry;
+      continue;
     }
+    if (entry.data?.placedPx === undefined) continue;
+
+    const placement = { placed: entry, outcome: null };
+    placements.push(placement);
+    const queue = pending.get(location);
+    if (queue) queue.push(placement);
+    else pending.set(location, [placement]);
+  }
+
+  return { placements, orphanedOutcomes };
+}
+
+export function summarizePlacements(placements) {
+  return placements.map(({ placed, outcome }) => {
+    const data = placed.data ?? {};
+    const outcomeData = outcome?.data ?? {};
+    return {
+      sequence: placed.sequence,
+      location: String(placed.location ?? ''),
+      branch: String(data.branch ?? data.reason ?? ''),
+      beforePx: round(data.beforePx),
+      placedPx: round(data.placedPx),
+      targetPx: data.targetPx === undefined ? round(data.placedPx) : round(data.targetPx),
+      settledPx: outcome ? round(outcomeData.settledPx) : null,
+      driftPx: outcome ? round(outcomeData.driftPx) : null,
+      /*
+       * No outcome is not "no drift". The sample is scheduled on a timer, so a
+       * placement at the end of the log, or one whose view unmounted first,
+       * never reports — and reading that as a clean landing is how a report
+       * turns into a false negative.
+       */
+      settled: outcome ? 'yes' : 'unknown',
+    };
+  });
+}
 
-    if (
-      event.location === 'VirtualMessageList.handleToolCardCollapseIntent' &&
-      event.message === 'Tool card collapse reservation calculated'
-    ) {
-      const current = finiteNumber(event.data?.currentTotalCompensationPx);
-      const provisional = finiteNumber(event.data?.provisionalTotalCompensationPx);
-      collapseIntents.push({
-        sequence: event.sequence,
-        tool: event.data?.nextIntent?.toolName ?? '',
-        cardHeightPx: round(event.data?.estimatedShrink),
-        distancePx: round(event.data?.effectiveDistanceFromBottom),
-        addedPx: round(provisional - current),
-        totalPx: round(provisional),
-        coordinatorMode: event.data?.coordinatorMode ?? '',
-      });
+export function analyzeEntries(entries, options) {
+  const settings = { ...DEFAULT_OPTIONS, ...options };
+  const tags = new Set(settings.tags ?? []);
+  const kept = tags.size === 0
+    ? entries
+    : entries.filter(entry => tags.has(String(entry.hypothesis ?? '')));
+
+  const viewportEntries = kept.filter(entry => entry.hypothesis === VIEWPORT_TAG);
+  const writes = viewportEntries.filter(entry => entry.location === WRITE_LOCATION);
+
+  const refusals = new Map();
+  const ownerActivity = new Map();
+  for (const write of writes) {
+    const weight = entryWeight(write);
+    const owner = String(write.data?.owner ?? 'unknown');
+    const activity = ownerActivity.get(owner) ?? { owner, writes: 0, refusals: 0, travelPx: 0 };
+    activity.travelPx += entryTravelPx(write);
+    if (write.data?.granted === false) {
+      activity.refusals += weight;
+      increment(refusals, `${owner}${KEY_SEPARATOR}${String(write.data?.heldBy ?? 'nobody')}`, weight);
+    } else {
+      activity.writes += weight;
     }
+    ownerActivity.set(owner, activity);
+  }
+
+  const declines = new Map();
+  for (const entry of viewportEntries) {
+    const location = String(entry.location ?? '');
+    if (!DECLINE_LOCATIONS.has(location)) continue;
+    const reason = String(entry.data?.reason ?? entry.data?.branch ?? '');
+    increment(declines, `${location}${KEY_SEPARATOR}${reason}`, entryWeight(entry));
+  }
+
+  const frequency = new Map();
+  for (const entry of kept) {
+    const key = `${String(entry.hypothesis ?? '')}${KEY_SEPARATOR}${String(entry.location ?? '')}`;
+    increment(frequency, key, entryWeight(entry));
+  }
+
+  const { placements, orphanedOutcomes } = joinPlacements(viewportEntries);
+  const summarized = summarizePlacements(placements);
 
-    if (
-      options.around !== null &&
-      finiteNumber(event.sequence) >= options.around - options.radius &&
-      finiteNumber(event.sequence) <= options.around + options.radius
-    ) {
-      sequenceWindow.push({
-        sequence: event.sequence,
-        location: event.location ?? '',
-        message: event.message ?? '',
-        data: compactData(event.data),
-      });
+  const droppedEntries = kept
+    .filter(entry => entry.location === DROPPED_ENTRY_LOCATION)
+    .reduce((total, entry) => total + finiteNumber(entry.data?.droppedEntries), 0);
+
+  return {
+    entryCount: kept.length,
+    viewportEntryCount: viewportEntries.length,
+    droppedEntries,
+    sequenceRange: kept.length === 0
+      ? null
+      : { first: kept[0].sequence, last: kept[kept.length - 1].sequence },
+    episodes: collectEpisodes(writes, settings.gapMs)
+      .sort((left, right) => right.churn - left.churn),
+    unstuckPlacements: summarized
+      .filter(placement => placement.driftPx !== null
+        && Math.abs(placement.driftPx) >= settings.minDrift)
+      .sort((left, right) => Math.abs(right.driftPx) - Math.abs(left.driftPx)),
+    unsampledPlacements: summarized.filter(placement => placement.settled === 'unknown'),
+    placementCount: summarized.length,
+    orphanedOutcomes,
+    refusals: [...refusals.entries()]
+      .map(([key, count]) => {
+        const [owner, heldBy] = key.split(KEY_SEPARATOR);
+        return { owner, refusedBy: heldBy, count };
+      })
+      .sort((left, right) => right.count - left.count),
+    ownerActivity: [...ownerActivity.values()]
+      .map(activity => ({ ...activity, travelPx: round(activity.travelPx) }))
+      .sort((left, right) => right.writes + right.refusals - (left.writes + left.refusals)),
+    declines: [...declines.entries()]
+      .map(([key, count]) => {
+        const [location, reason] = key.split(KEY_SEPARATOR);
+        return { location, reason, count };
+      })
+      .sort((left, right) => right.count - left.count),
+    frequency: [...frequency.entries()]
+      .map(([key, count]) => {
+        const [tag, location] = key.split(KEY_SEPARATOR);
+        return { tag, location, count };
+      })
+      .sort((left, right) => right.count - left.count),
+    window: settings.around === null ? [] : kept
+      .filter(entry => finiteNumber(entry.sequence) >= settings.around - settings.radius
+        && finiteNumber(entry.sequence) <= settings.around + settings.radius)
+      .map(entry => ({
+        sequence: entry.sequence,
+        tag: String(entry.hypothesis ?? ''),
+        location: String(entry.location ?? ''),
+        message: String(entry.message ?? ''),
+        data: compactData(entry.data),
+      })),
+  };
+}
+
+export async function readEntries(logPath) {
+  const entries = [];
+  let lineCount = 0;
+  let parseErrorCount = 0;
+
+  const input = createReadStream(logPath, { encoding: 'utf8' });
+  const lines = createInterface({ input, crlfDelay: Infinity });
+  for await (const line of lines) {
+    lineCount += 1;
+    if (!line.trim()) continue;
+    try {
+      entries.push(JSON.parse(line));
+    } catch {
+      parseErrorCount += 1;
     }
   }
 
-  console.log(`FlowChat log: ${options.logPath}`);
-  console.log(`Lines: ${lineCount}, events: ${eventCount}, parse errors: ${parseErrorCount}`);
+  return { entries, lineCount, parseErrorCount };
+}
 
-  console.log('\nMost frequent events');
-  console.table(
-    [...eventCounts.values()]
-      .sort((left, right) => right.count - left.count)
-      .slice(0, options.top),
+function reportTable(title, rows, top) {
+  console.log(`\n${title}`);
+  if (rows.length === 0) {
+    console.log('  (none)');
+    return;
+  }
+  console.table(rows.slice(0, top));
+  if (rows.length > top) {
+    console.log(`  ... ${rows.length - top} more`);
+  }
+}
+
+export function printReport(report, options, source) {
+  console.log(`FlowChat log: ${source.logPath}`);
+  console.log(
+    `Lines: ${source.lineCount}, entries: ${report.entryCount}`
+    + ` (viewport: ${report.viewportEntryCount}), parse errors: ${source.parseErrorCount}`,
   );
+  if (report.sequenceRange) {
+    console.log(`Sequences: ${report.sequenceRange.first}-${report.sequenceRange.last}`);
+  }
+  if (report.droppedEntries > 0) {
+    // Said loudly: every count below is a lower bound once entries were lost.
+    console.log(
+      `WARNING: ${report.droppedEntries} entries were dropped before reaching the log.`
+      + ' Counts below are lower bounds.',
+    );
+  }
 
-  console.log(`\nLargest reservation increases (>= ${options.minDelta}px)`);
-  console.table(
-    reservationJumps
-      .sort((left, right) => right.deltaPx - left.deltaPx)
-      .slice(0, options.top),
+  reportTable(
+    'Episodes of viewport activity, worst churn first (travel per pixel of progress)',
+    report.episodes,
+    options.top,
   );
+  reportTable(
+    `Placements that did not stick (drift >= ${options.minDrift}px)`,
+    report.unstuckPlacements,
+    options.top,
+  );
+  reportTable('Refusals: who was outranked, by whom', report.refusals, options.top);
+  reportTable('Declines: a writer choosing not to move, and why', report.declines, options.top);
+  reportTable('Per owner', report.ownerActivity, options.top);
+  reportTable('Most frequent locations', report.frequency, options.top);
 
-  console.log('\nLargest collapse-intent estimates');
-  console.table(
-    collapseIntents
-      .sort((left, right) => right.addedPx - left.addedPx)
-      .slice(0, options.top),
+  console.log(
+    `\nPlacements: ${report.placementCount},`
+    + ` never sampled: ${report.unsampledPlacements.length},`
+    + ` outcomes with no placement in this log: ${report.orphanedOutcomes.length}`,
   );
 
   if (options.around !== null) {
-    console.log(`\nEvents around sequence ${options.around} (+/- ${options.radius})`);
-    console.table(sequenceWindow);
+    reportTable(
+      `Entries around sequence ${options.around} (+/- ${options.radius})`,
+      report.window,
+      report.window.length,
+    );
   }
 }
 
-try {
+async function main() {
   const options = parseArgs(process.argv.slice(2));
-  await analyze(options);
-} catch (error) {
-  console.error(error instanceof Error ? error.message : String(error));
-  process.exitCode = 1;
+  const source = await readEntries(options.logPath);
+  const report = analyzeEntries(source.entries, options);
+  printReport(report, options, { ...source, logPath: options.logPath });
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  try {
+    await main();
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
 }
diff --git a/scripts/diagnostics/analyze-flowchat-log.test.mjs b/scripts/diagnostics/analyze-flowchat-log.test.mjs
new file mode 100644
index 0000000000..152f583596
--- /dev/null
+++ b/scripts/diagnostics/analyze-flowchat-log.test.mjs
@@ -0,0 +1,190 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+  analyzeEntries,
+  collectEpisodes,
+  entryTravelPx,
+  entryWeight,
+  joinPlacements,
+  parseArgs,
+} from './analyze-flowchat-log.mjs';
+
+let nextSequence = 0;
+
+function entry(location, data, overrides = {}) {
+  nextSequence += 1;
+  return {
+    sequence: nextSequence,
+    timestamp: '2026-08-11T00:00:00.000Z',
+    performanceTimeMs: nextSequence * 16,
+    hypothesis: 'viewport',
+    location,
+    message: location,
+    data,
+    ...overrides,
+  };
+}
+
+function write(owner, fromPx, toPx, overrides = {}) {
+  return entry('viewportOwner.write', {
+    owner,
+    granted: true,
+    heldBy: null,
+    fromPx,
+    toPx,
+    ...overrides.data,
+  }, overrides.entry);
+}
+
+test('parseArgs requires a log path and rejects unknown options', () => {
+  assert.throws(() => parseArgs([]), /log path is required/);
+  assert.throws(() => parseArgs(['flowchat.log', '--nope']), /Unknown option/);
+
+  const options = parseArgs(['flowchat.log', '--min-drift', '20', '--tag', 'viewport']);
+  assert.equal(options.logPath, 'flowchat.log');
+  assert.equal(options.minDrift, 20);
+  assert.deepEqual(options.tags, ['viewport']);
+
+  // `npm run … -- <path>` hands the separator through as an argument.
+  assert.equal(parseArgs(['--', 'flowchat.log']).logPath, 'flowchat.log');
+});
+
+test('a coalesced entry counts as the run it stands for', () => {
+  const coalesced = write('follow-output', 100, 102, {
+    data: { repeated: { suppressedCount: 59, suppressedTravelPx: 118, suppressedForMs: 480 } },
+  });
+
+  assert.equal(entryWeight(coalesced), 60);
+  assert.equal(entryTravelPx(coalesced), 120);
+  // An entry with no run behind it still stands for itself.
+  assert.equal(entryWeight(write('follow-output', 0, 10)), 1);
+});
+
+test('episodes split on a quiet gap and score a fight by its churn', () => {
+  nextSequence = 0;
+  const fight = [
+    write('snap-back', 1000, 1000.7),
+    write('anchor-correction', 1000.7, 1000),
+    write('snap-back', 1000, 1000.7),
+    write('anchor-correction', 1000.7, 1000),
+  ];
+  const later = write('follow-output', 1000, 2000, {
+    entry: { performanceTimeMs: 20_000 },
+  });
+
+  const episodes = collectEpisodes([...fight, later], 750);
+
+  assert.equal(episodes.length, 2);
+  // Four writes that went nowhere: travel without progress is the whole signal.
+  assert.equal(episodes[0].writes, 4);
+  assert.equal(episodes[0].netPx, 0);
+  assert.ok(episodes[0].churn >= 2, `expected churn, got ${episodes[0].churn}`);
+  assert.equal(episodes[1].netPx, 1000);
+  assert.equal(episodes[1].churn, 1);
+});
+
+test('refused writes are counted apart from the ones that moved', () => {
+  nextSequence = 0;
+  const episodes = collectEpisodes([
+    write('follow-output', 500, 600),
+    write('anchor-correction', 600, 500, { data: { granted: false, heldBy: 'user-gesture' } }),
+  ], 750);
+
+  assert.equal(episodes[0].writes, 1);
+  assert.equal(episodes[0].refusals, 1);
+  // A refusal moved nothing, so it cannot contribute to net displacement.
+  assert.equal(episodes[0].netPx, 100);
+});
+
+test('placements pair with their outcome in order, and a stray outcome is reported', () => {
+  nextSequence = 0;
+  const first = entry('turnNavigation.placed', { beforePx: 0, placedPx: 800, targetPx: 800 });
+  const second = entry('turnNavigation.placed', { beforePx: 800, placedPx: 1600, targetPx: 1600 });
+  const firstOutcome = entry('turnNavigation.placed.outcome', { settledPx: 40, driftPx: -760 });
+  const secondOutcome = entry('turnNavigation.placed.outcome', { settledPx: 1600, driftPx: 0 });
+  const stray = entry('visibleTask.scrollToTask.outcome', { settledPx: 10, driftPx: -5 });
+
+  const { placements, orphanedOutcomes } = joinPlacements([
+    first,
+    second,
+    firstOutcome,
+    secondOutcome,
+    stray,
+  ]);
+
+  assert.equal(placements.length, 2);
+  assert.equal(placements[0].outcome, firstOutcome);
+  assert.equal(placements[1].outcome, secondOutcome);
+  assert.deepEqual(orphanedOutcomes, [
+    { sequence: stray.sequence, location: 'visibleTask.scrollToTask' },
+  ]);
+});
+
+test('analyzeEntries reports what did not stick, who was refused, and who declined', () => {
+  nextSequence = 0;
+  const report = analyzeEntries([
+    entry('visibleTask.scrollToTask', { beforePx: 0, placedPx: 900, targetPx: 900 }),
+    write('anchor-correction', 900, 120),
+    entry('visibleTask.scrollToTask.outcome', { settledPx: 120, driftPx: -780 }),
+    write('follow-output', 120, 200, { data: { granted: false, heldBy: 'user-gesture' } }),
+    entry('snapBack.declined', { reason: 'follow-correcting' }),
+    entry('snapBack.declined', { reason: 'follow-correcting' }),
+    entry('followOutput.deferNewTurn', { turnId: 't-42' }),
+    { ...entry('history_paging_requested', { direction: 'before' }), hypothesis: 'history-paging' },
+  ], { minDrift: 8 });
+
+  assert.equal(report.unstuckPlacements.length, 1);
+  assert.equal(report.unstuckPlacements[0].driftPx, -780);
+  assert.equal(report.unstuckPlacements[0].location, 'visibleTask.scrollToTask');
+
+  assert.deepEqual(report.refusals, [
+    { owner: 'follow-output', refusedBy: 'user-gesture', count: 1 },
+  ]);
+
+  const declined = report.declines.find(row => row.location === 'snapBack.declined');
+  assert.deepEqual(declined, {
+    location: 'snapBack.declined',
+    reason: 'follow-correcting',
+    count: 2,
+  });
+  assert.ok(report.declines.some(row => row.location === 'followOutput.deferNewTurn'));
+
+  // The paging tag is counted but never mistaken for viewport activity.
+  assert.equal(report.viewportEntryCount, 7);
+  assert.ok(report.frequency.some(row => row.tag === 'history-paging'));
+});
+
+test('a placement whose outcome never arrived is not reported as having stuck', () => {
+  nextSequence = 0;
+  const report = analyzeEntries([
+    entry('navigation.scrollIntoView', { beforePx: 0, placedPx: 300 }),
+  ], {});
+
+  assert.equal(report.placementCount, 1);
+  assert.equal(report.unstuckPlacements.length, 0);
+  assert.equal(report.unsampledPlacements.length, 1);
+  assert.equal(report.unsampledPlacements[0].settled, 'unknown');
+});
+
+test('dropped entries are surfaced, because every count becomes a lower bound', () => {
+  nextSequence = 0;
+  const report = analyzeEntries([
+    { ...entry('FlowChatDiagnosticsRecorder.flush', { droppedEntries: 128 }), hypothesis: 'I' },
+    write('follow-output', 0, 100),
+  ], {});
+
+  assert.equal(report.droppedEntries, 128);
+});
+
+test('--tag keeps only the requested stream', () => {
+  nextSequence = 0;
+  const report = analyzeEntries([
+    write('follow-output', 0, 100),
+    { ...entry('history_paging_requested', { direction: 'before' }), hypothesis: 'history-paging' },
+  ], { tags: ['history-paging'] });
+
+  assert.equal(report.entryCount, 1);
+  assert.equal(report.viewportEntryCount, 0);
+  assert.equal(report.episodes.length, 0);
+});
diff --git a/scripts/frontend-build-all.mjs b/scripts/frontend-build-all.mjs
index 4813cb1efe..00ad2c603c 100644
--- a/scripts/frontend-build-all.mjs
+++ b/scripts/frontend-build-all.mjs
@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 
 /**
- * Runs the two independent frontend build pipelines in parallel:
- *   - build:web          (type-check + vite build + monaco asset verify)
- *   - prepare:mobile-web (mobile-web install/build with mtime short-circuit)
+ * Runs the independent pre-bundle build pipelines in parallel:
+ *   - build:web            (type-check + vite build + monaco asset verify)
+ *   - prepare:mobile-web   (mobile-web install/build with mtime short-circuit)
+ *   - prepare:dsh-profile  (the DeepSeek Harness bridge official desktop:build ships)
  *
- * Used as the Tauri beforeBuildCommand so the frontend stage costs
- * max(build:web, mobile-web) instead of their sum. Either failure fails the
- * whole script with a non-zero exit code.
+ * Used as the Tauri beforeBuildCommand so the stage costs max(…) instead of
+ * their sum. Any failure fails the whole script with a non-zero exit code.
  */
 
 import { spawn } from 'node:child_process';
@@ -58,6 +58,10 @@ function runPrefixed(prefix, command, args) {
 const codes = await Promise.all([
   runPrefixed('web', 'pnpm', ['run', 'build:web']),
   runPrefixed('mobile-web', 'pnpm', ['run', 'prepare:mobile-web']),
+  // The DeepSeek Harness bridge Tauri ships as a resource. On a cold tree this
+  // installs its own pinned toolchain (~30s), which still fits inside the two
+  // above; it is independent of them, and of BitFun's pnpm store.
+  runPrefixed('dsh-profile', 'pnpm', ['run', 'prepare:dsh-profile']),
 ]);
 
 const failed = codes.some((code) => code !== 0);
diff --git a/scripts/generate-version.cjs b/scripts/generate-version.cjs
index 0081e52f2e..d84d8d50b5 100644
--- a/scripts/generate-version.cjs
+++ b/scripts/generate-version.cjs
@@ -59,6 +59,10 @@ function generateVersionInfo(buildEnv) {
   const buildDate = new Date().toISOString();
   const buildTimestamp = Date.now();
   const isDev = buildEnv === 'development';
+  const releaseChannel = process.env.BITFUN_RELEASE_CHANNEL || 'stable';
+  if (!['stable', 'beta', 'nightly'].includes(releaseChannel)) {
+    throw new Error(`Unsupported BITFUN_RELEASE_CHANNEL: ${releaseChannel}`);
+  }
   
   const versionInfo = {
     name: packageJson.name === 'BitFun' ? 'BitFun' : packageJson.name,
@@ -66,6 +70,7 @@ function generateVersionInfo(buildEnv) {
     buildDate,
     buildTimestamp,
     buildEnv,
+    releaseChannel,
     isDev,
     ...gitInfo
   };
@@ -146,4 +151,3 @@ try {
   process.exit(1);
 }
 
-
diff --git a/scripts/linux-binaries-manifest.test.mjs b/scripts/linux-binaries-manifest.test.mjs
index 01dcc038f4..e3d9e00d17 100644
--- a/scripts/linux-binaries-manifest.test.mjs
+++ b/scripts/linux-binaries-manifest.test.mjs
@@ -374,15 +374,17 @@ test('website download manifest uses installer while updater manifest keeps setu
   );
 });
 
-test('Linux archives are mirrored before the much larger Desktop packages', () => {
+test('stable Linux archives are mirrored before the much larger Desktop packages', () => {
   const syncScript = fs.readFileSync(
     path.join(repoRoot, 'scripts/openbitfun-release-sync.sh'),
     'utf8'
   );
 
-  const linuxCall = syncScript.indexOf('\n  mirror_linux_binaries\n');
+  const stableBranch = syncScript.indexOf('if [ "$RELEASE_CHANNEL" = "stable" ]; then');
+  const linuxCall = syncScript.indexOf('\n    mirror_linux_binaries\n', stableBranch);
   const desktopLoop = syncScript.indexOf('Mirroring Desktop asset');
-  assert.ok(linuxCall > 0, 'mirror_linux_binaries must be called from main');
+  assert.ok(stableBranch > 0, 'stable channel branch must exist');
+  assert.ok(linuxCall > stableBranch, 'stable main path must call mirror_linux_binaries');
   assert.ok(desktopLoop > 0, 'Desktop asset mirroring must still exist');
   assert.ok(
     linuxCall < desktopLoop,
@@ -406,3 +408,44 @@ test('the mirror retains enough releases for older Desktop builds', () => {
     `KEEP_VERSIONS must retain several releases, got ${keep[1]}`
   );
 });
+
+test('openbitfun sync lock and cron use the in-repo script, not a server-only copy', () => {
+  const syncScript = fs.readFileSync(
+    path.join(repoRoot, 'scripts/openbitfun-release-sync.sh'),
+    'utf8'
+  );
+  const cronFile = fs.readFileSync(
+    path.join(repoRoot, 'deploy/openbitfun-host/release-sync.cron'),
+    'utf8'
+  );
+  assert.match(
+    syncScript,
+    /BITFUN_RELEASE_SYNC_LOCK/,
+    'lock path must be overridable so a new host can run the repo script'
+  );
+  assert.match(
+    syncScript,
+    /\/root\/repos\/BitFun\/scripts\/openbitfun-release-sync\.sh/,
+    'documented cron must invoke the BitFun checkout, not a detached copy'
+  );
+  assert.doesNotMatch(
+    syncScript,
+    /LOCK_FILE="\/root\/repos\/BitFun-AutoUpdate\/sync\.lock"/,
+    'a hardcoded AutoUpdate lock forces every new host to recreate a server-only tree'
+  );
+  assert.match(
+    cronFile,
+    /\/root\/repos\/BitFun\/scripts\/openbitfun-release-sync\.sh/,
+    'installed crontab must invoke the BitFun checkout, not a detached copy'
+  );
+  assert.doesNotMatch(
+    cronFile,
+    /BitFun-AutoUpdate/,
+    'the crontab file must not revive the server-only AutoUpdate copy'
+  );
+  assert.match(
+    syncScript,
+    /LOCK_FILE="\$\{BITFUN_RELEASE_SYNC_LOCK:-\/var\/lock\/bitfun-release-sync\.lock\}"/,
+    'default lock must stay off the Nginx /release/ alias'
+  );
+});
diff --git a/scripts/openbitfun-release-sync.sh b/scripts/openbitfun-release-sync.sh
index fb9fb0426a..a873f41c63 100755
--- a/scripts/openbitfun-release-sync.sh
+++ b/scripts/openbitfun-release-sync.sh
@@ -3,7 +3,7 @@
 # sync-release.sh — Mirror BitFun release assets from GitHub to openbitfun.com.
 #
 # Flow:
-#   1. Fetch latest.json from GitHub (follows /releases/latest/download/ redirect)
+#   1. Fetch the selected channel's latest.json from GitHub
 #   2. Mirror the signed Relay image descriptor and Linux binary manifest FIRST
 #      (small trust metadata must not queue behind ~700 MB of Desktop packages)
 #   3. Download every Desktop updater package plus the standalone Windows
@@ -12,16 +12,19 @@
 #   5. Atomically publish versioned and root manifests
 #   6. Remove old version dirs, keeping only the most recent KEEP_VERSIONS
 #
-# The published release/latest.json is the Tauri updater fallback endpoint.
+# The published release/latest.json and release/beta/latest.json files are the
+# stable and beta Tauri updater fallback endpoints.
 # When GitHub is unreachable, the desktop client automatically falls through
 # to https://openbitfun.com/release/latest.json and downloads from this mirror.
 # The published release/downloads.json is for the website. Its Windows URL uses
 # latest.json's manual_installers entry while the updater keeps the versioned
 # Tauri setup.exe URL.
 #
-# Cron (every 10 minutes):
-#   */10 * * * * /root/repos/BitFun-AutoUpdate/openbitfun-release-sync.sh \
-#       >> /root/repos/BitFun-AutoUpdate/sync.log 2>&1
+# Cron (every 10 minutes). Run the in-repo script from the BitFun checkout so a
+# new host only needs this repository, not a detached AutoUpdate copy:
+#   */10 * * * * /root/repos/BitFun/scripts/openbitfun-release-sync.sh \
+#       >> /var/log/bitfun-release-sync.log 2>&1
+# Host restore: deploy/openbitfun-host/README.md
 #
 # Optional immediate trigger. The release workflow POSTs to
 # ${OPENBITFUN_SYNC_WEBHOOK_URL} once assets are published (see the "Request
@@ -31,10 +34,14 @@
 #
 #   while true; do
 #     nc -l -p 8787 -q 1 >/dev/null \
-#       && /root/repos/BitFun-AutoUpdate/openbitfun-release-sync.sh \
-#            >> /root/repos/BitFun-AutoUpdate/sync.log 2>&1
+#       && BITFUN_RELEASE_CHANNEL=stable \
+#            /root/repos/BitFun/scripts/openbitfun-release-sync.sh \
+#            >> /var/log/bitfun-release-sync.log 2>&1
 #   done
 #
+# The current production origin is cron-only. Do not invent a detached webhook
+# listener unless OPENBITFUN_SYNC_WEBHOOK_URL is actually configured.
+#
 # Cron stays the source of truth: this script is idempotent and holds a flock,
 # so a webhook run and a cron run cannot collide and a missed webhook only costs
 # latency. Leaving the secret unset keeps the cron-only behaviour.
@@ -42,17 +49,35 @@
 set -euo pipefail
 
 # ── Configuration ──────────────────────────────────────────────
-GITHUB_LATEST_JSON_URL="https://github.com/GCWing/BitFun/releases/latest/download/latest.json"
-GITHUB_LINUX_BINARIES_URL="https://github.com/GCWing/BitFun/releases/latest/download/linux-binaries.json"
-GITHUB_RELAY_IMAGE_URL="https://github.com/GCWing/BitFun/releases/latest/download/relay-image.json"
-OPENBITFUN_BASE_URL="https://openbitfun.com/release"
+RELEASE_CHANNEL="${BITFUN_RELEASE_CHANNEL:-stable}"
+case "$RELEASE_CHANNEL" in
+  stable)
+    CHANNEL_PATH=""
+    GITHUB_RELEASE_ROOT="https://github.com/GCWing/BitFun/releases/latest/download"
+    ;;
+  beta)
+    CHANNEL_PATH="/beta"
+    GITHUB_RELEASE_ROOT="https://github.com/GCWing/BitFun/releases/download/channel-beta"
+    ;;
+  *)
+    echo "Unsupported BITFUN_RELEASE_CHANNEL: $RELEASE_CHANNEL" >&2
+    exit 1
+    ;;
+esac
+GITHUB_LATEST_JSON_URL="${GITHUB_RELEASE_ROOT}/latest.json"
+GITHUB_LINUX_BINARIES_URL="${GITHUB_RELEASE_ROOT}/linux-binaries.json"
+GITHUB_RELAY_IMAGE_URL="${GITHUB_RELEASE_ROOT}/relay-image.json"
+OPENBITFUN_BASE_URL="https://openbitfun.com/release${CHANNEL_PATH}"
 # The mirror deliberately lives outside the website checkout. It used to be
 # BitFun-Website/dist/release, but `npm run build` empties dist/, so every
 # website deploy silently deleted the mirrored installers and manifests —
 # breaking downloads and the updater fallback until someone noticed. nginx
 # serves this directory through a `location ^~ /release/` alias instead.
-WEBSITE_RELEASE_DIR="${WEBSITE_RELEASE_DIR:-/srv/bitfun-release}"
-LOCK_FILE="/root/repos/BitFun-AutoUpdate/sync.lock"
+WEBSITE_RELEASE_ROOT="${WEBSITE_RELEASE_DIR:-/srv/bitfun-release}"
+WEBSITE_RELEASE_DIR="${WEBSITE_RELEASE_ROOT}${CHANNEL_PATH}"
+# Keep the lock off the Nginx /release/ alias. Override with
+# BITFUN_RELEASE_SYNC_LOCK if a host must share a lock across checkouts.
+LOCK_FILE="${BITFUN_RELEASE_SYNC_LOCK:-/var/lock/bitfun-release-sync.lock}"
 LEGACY_WINDOWS_INSTALLER_FILENAME="bitfun-installer.exe"
 WINDOWS_INSTALLER_FILENAME="$LEGACY_WINDOWS_INSTALLER_FILENAME"
 WINDOWS_INSTALLER_URL=""
@@ -495,7 +520,7 @@ main() {
     exit 0
   fi
 
-  log "=== BitFun release sync started ==="
+  log "=== BitFun ${RELEASE_CHANNEL} release sync started ==="
 
   mkdir -p "$WEBSITE_RELEASE_DIR"
 
@@ -566,10 +591,15 @@ if entry:
   VERSION_DIR="${WEBSITE_RELEASE_DIR}/${VERSION}"
   mkdir -p "$VERSION_DIR"
 
-  # 4. Mirror small trust metadata and Linux archives first.
-  mirror_relay_image_descriptor
-  mirror_linux_binaries
-  mirror_dispatch_macos_cli_archives
+  # 4. Stable owns the CLI/Relay floating manifests. The first beta slice only
+  # mirrors Desktop updater and installer assets under /release/beta.
+  if [ "$RELEASE_CHANNEL" = "stable" ]; then
+    mirror_relay_image_descriptor
+    mirror_linux_binaries
+    mirror_dispatch_macos_cli_archives
+  else
+    log "Skipping stable-only CLI and Relay metadata for the beta channel"
+  fi
 
   # 5. Download all platform installer packages
   #    Extract "<url>\t<filename>" pairs, then curl each one.
@@ -638,7 +668,7 @@ print(json.dumps(data, indent=2))
     done
   fi
 
-  log "=== Sync complete: version $VERSION ==="
+  log "=== ${RELEASE_CHANNEL} sync complete: version $VERSION ==="
 }
 
 if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
diff --git a/scripts/plan-channel-promotion.mjs b/scripts/plan-channel-promotion.mjs
new file mode 100644
index 0000000000..6e03a27efe
--- /dev/null
+++ b/scripts/plan-channel-promotion.mjs
@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { appendFileSync, existsSync, readFileSync } from 'node:fs';
+import { compareReleaseVersions } from './release-channel.mjs';
+
+const args = parseArgs(process.argv.slice(2));
+const candidatePath = requireArg(args, 'candidate');
+const currentPath = args.current;
+const candidate = readVersion(candidatePath);
+const current = currentPath && existsSync(currentPath) ? readVersion(currentPath) : null;
+const promote = current === null || compareReleaseVersions(candidate, current) >= 0;
+
+console.log(
+  current === null
+    ? `[channel-promotion] Initial channel version: ${candidate}`
+    : `[channel-promotion] current=${current} candidate=${candidate} promote=${promote}`,
+);
+if (args['github-output']) {
+  appendFileSync(args['github-output'], `promote=${promote}\n`, 'utf8');
+  appendFileSync(args['github-output'], `candidate_version=${candidate}\n`, 'utf8');
+}
+
+function readVersion(file) {
+  const data = JSON.parse(readFileSync(file, 'utf8'));
+  if (typeof data.version !== 'string') {
+    throw new Error(`Manifest has no string version: ${file}`);
+  }
+  return data.version;
+}
+
+function parseArgs(rawArgs) {
+  const parsed = {};
+  for (let index = 0; index < rawArgs.length; index += 2) {
+    const name = rawArgs[index];
+    const value = rawArgs[index + 1];
+    if (!name?.startsWith('--') || !value) {
+      throw new Error(`Invalid argument near ${name || '<end>'}`);
+    }
+    parsed[name.slice(2)] = value;
+  }
+  return parsed;
+}
+
+function requireArg(parsed, name) {
+  if (!parsed[name]) throw new Error(`Missing required --${name} argument`);
+  return parsed[name];
+}
diff --git a/scripts/prepare-dsh-profile.mjs b/scripts/prepare-dsh-profile.mjs
new file mode 100644
index 0000000000..c0c5898c9a
--- /dev/null
+++ b/scripts/prepare-dsh-profile.mjs
@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+
+/**
+ * Build the DeepSeek Harness bridge into the profile directory the desktop
+ * bundle ships (`packages/dsh-acp/dist-profile`).
+ *
+ * BitFun launches DeepSeek Harness as `dsh --profile bitfun-acp`, and copies
+ * that directory into the user's own dsh install on first use — see
+ * `src/crates/interfaces/acp/src/client/dsh_profile.rs`. The build has to
+ * happen here rather than in Cargo because it is a TypeScript compile.
+ *
+ * `packages/dsh-acp` is deliberately NOT a pnpm workspace member: it pins the
+ * whole harness `0.1.0-rc.6` train, and making every contributor's
+ * `pnpm install` fetch that is a poor trade when only the desktop bundle needs
+ * it. So this installs the package from its own lockfile, here, once — unless
+ * a developer already linked a local harness checkout, in which case that
+ * checkout wins and no install runs.
+ *
+ * A failure here fails the build. An app that silently ships no bridge looks
+ * exactly like an app that ships a working one until a user tries to start a
+ * DeepSeek session, and that is the wrong place to find out. Set
+ * `BITFUN_SKIP_DSH_PROFILE=1` to opt out deliberately.
+ *
+ * Official `desktop:build` compiles this via `frontend:build-all`. desktop:dev
+ * and cargo check do not: the profile is not a compile-time Tauri resource.
+ * Local DeepSeek sessions run this script explicitly. A stamped profile whose
+ * inputs have not changed is left alone — the same mtime short-circuit
+ * mobile-web uses. Escape hatches: `--force` /
+ * `BITFUN_DSH_PROFILE_FORCE_BUILD=1`.
+ */
+
+import { spawnSync } from 'node:child_process';
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import path, { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const PACKAGE_DIR = path.join(ROOT_DIR, 'packages', 'dsh-acp');
+const OUT_DIR = path.join(PACKAGE_DIR, 'dist-profile');
+const STAMP_FILENAME = '.bitfun-bridge.json';
+
+/** One installed harness package is enough to tell a populated tree from a bare one. */
+const DEPS_PROBE = path.join(PACKAGE_DIR, 'node_modules', '@deepseek-ai', 'dsh-app-boot');
+
+const INPUT_IGNORED_DIRS = new Set([
+  'node_modules',
+  'lib',
+  'dist-profile',
+  '.sessions',
+]);
+
+/** Explains an empty dist-profile to whoever finds one in a build tree. */
+const PLACEHOLDER = `This BitFun build ships no DeepSeek Harness bridge.
+
+BITFUN_SKIP_DSH_PROFILE was set when this build ran, so packages/dsh-acp was
+never compiled. BitFun's profile resolver rejects this unstamped directory and
+reports that the bridge is missing from the build.
+
+To include it: run \`pnpm run prepare:dsh-profile\` without that variable.
+`;
+
+/**
+ * Newest mtime among the profile build inputs (recursively for directories).
+ * @param {string} entryPath
+ * @returns {{ path: string, mtimeMs: number } | null}
+ */
+export function getNewestInputMtime(entryPath) {
+  if (!existsSync(entryPath)) {
+    return null;
+  }
+
+  const stat = lstatSync(entryPath);
+  if (stat.isSymbolicLink()) {
+    return null;
+  }
+
+  if (stat.isFile()) {
+    return { path: entryPath, mtimeMs: stat.mtimeMs };
+  }
+
+  if (!stat.isDirectory()) {
+    return null;
+  }
+
+  let newest = null;
+  for (const entry of readdirSync(entryPath, { withFileTypes: true })) {
+    if (entry.isSymbolicLink()) {
+      continue;
+    }
+    if (entry.isDirectory() && INPUT_IGNORED_DIRS.has(entry.name)) {
+      continue;
+    }
+    const candidate = getNewestInputMtime(path.join(entryPath, entry.name));
+    if (candidate && (!newest || candidate.mtimeMs > newest.mtimeMs)) {
+      newest = candidate;
+    }
+  }
+
+  return newest;
+}
+
+/**
+ * Decide whether the shipped profile needs a rebuild.
+ *
+ * A directory is not enough: Tauri only needs the path to exist, but BitFun's
+ * resolver rejects an unstamped tree. The stamp `.bitfun-bridge.json` is the
+ * same file `scripts/build-profile.mjs` writes and ACP reads.
+ *
+ * @param {{
+ *   packageDir?: string,
+ *   outDir?: string,
+ *   prepareScriptPath?: string,
+ *   force?: boolean,
+ * }} [options]
+ * @returns {{ shouldBuild: boolean, reason: string }}
+ */
+export function getDshProfileRebuildPlan({
+  packageDir = PACKAGE_DIR,
+  outDir = path.join(packageDir, 'dist-profile'),
+  prepareScriptPath = path.join(ROOT_DIR, 'scripts', 'prepare-dsh-profile.mjs'),
+  force = false,
+} = {}) {
+  if (force) {
+    return { shouldBuild: true, reason: 'Force rebuild requested for dsh-profile' };
+  }
+
+  const stampPath = path.join(outDir, STAMP_FILENAME);
+  if (!existsSync(stampPath)) {
+    return { shouldBuild: true, reason: 'dsh-profile stamp is missing' };
+  }
+
+  try {
+    const stamp = JSON.parse(readFileSync(stampPath, 'utf8'));
+    if (
+      typeof stamp.profile !== 'string' ||
+      stamp.profile === '' ||
+      typeof stamp.content !== 'string' ||
+      stamp.content === ''
+    ) {
+      return { shouldBuild: true, reason: 'dsh-profile stamp is incomplete' };
+    }
+  } catch {
+    return { shouldBuild: true, reason: 'dsh-profile stamp is unreadable' };
+  }
+
+  const stampMtimeMs = statSync(stampPath).mtimeMs;
+  const inputs = [
+    path.join(packageDir, 'src'),
+    path.join(packageDir, 'presets'),
+    path.join(packageDir, 'cordis.yml'),
+    path.join(packageDir, 'package.json'),
+    path.join(packageDir, 'package-lock.json'),
+    path.join(packageDir, 'tsconfig.build.json'),
+    path.join(packageDir, 'scripts', 'build-profile.mjs'),
+    prepareScriptPath,
+  ];
+
+  let newestInput = null;
+  for (const input of inputs) {
+    const candidate = getNewestInputMtime(input);
+    if (candidate && (!newestInput || candidate.mtimeMs > newestInput.mtimeMs)) {
+      newestInput = candidate;
+    }
+  }
+
+  if (newestInput && newestInput.mtimeMs > stampMtimeMs) {
+    return {
+      shouldBuild: true,
+      reason: `dsh-profile inputs changed since the last build (${path.relative(ROOT_DIR, newestInput.path)})`,
+    };
+  }
+
+  return {
+    shouldBuild: false,
+    reason:
+      'dsh-profile is up to date; skipping install/build (use --force or BITFUN_DSH_PROFILE_FORCE_BUILD=1 to rebuild)',
+  };
+}
+
+/**
+ * Run a command in the bridge package directory.
+ * @param {string} command - the executable to run.
+ * @param {string[]} args - its arguments.
+ * @returns {number} the exit status, with a missing status treated as a failure.
+ */
+function run(command, args) {
+  const result = spawnSync(command, args, {
+    cwd: PACKAGE_DIR,
+    shell: process.platform === 'win32',
+    stdio: 'inherit',
+    env: process.env,
+  });
+  return result.status ?? 1;
+}
+
+/**
+ * Fail the build, saying what to do about it.
+ * @param {string} message - what went wrong.
+ * @param {number} status - the exit status to propagate.
+ */
+function fail(message, status) {
+  process.stderr.write(`[dsh-profile] ${message}\n`);
+  process.stderr.write(
+    '[dsh-profile] set BITFUN_SKIP_DSH_PROFILE=1 to build without the DeepSeek bridge\n',
+  );
+  process.exit(status === 0 ? 1 : status);
+}
+
+function main() {
+  if (process.env.BITFUN_SKIP_DSH_PROFILE === '1') {
+    process.stdout.write('[dsh-profile] skipped (this build ships no DeepSeek bridge)\n');
+    mkdirSync(OUT_DIR, { recursive: true });
+    writeFileSync(path.join(OUT_DIR, 'NOT-BUILT.md'), PLACEHOLDER);
+    return;
+  }
+
+  const force =
+    process.argv.includes('--force') || process.env.BITFUN_DSH_PROFILE_FORCE_BUILD === '1';
+  const plan = getDshProfileRebuildPlan({ force });
+  if (!plan.shouldBuild) {
+    process.stdout.write(`[dsh-profile] ${plan.reason}\n`);
+    return;
+  }
+  process.stdout.write(`[dsh-profile] ${plan.reason}\n`);
+
+  if (!existsSync(DEPS_PROBE)) {
+    process.stdout.write('[dsh-profile] installing the harness toolchain from package-lock.json\n');
+    const installed = run('npm', ['ci', '--no-audit', '--no-fund']);
+    if (installed !== 0) fail('npm ci failed', installed);
+  }
+
+  const compiled = run('npm', ['run', 'build']);
+  if (compiled !== 0) fail('tsc failed', compiled);
+
+  const packaged = run('node', ['scripts/build-profile.mjs']);
+  if (packaged !== 0) fail('profile packaging failed', packaged);
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main();
+}
diff --git a/scripts/prepare-dsh-profile.test.mjs b/scripts/prepare-dsh-profile.test.mjs
new file mode 100644
index 0000000000..b9729a9608
--- /dev/null
+++ b/scripts/prepare-dsh-profile.test.mjs
@@ -0,0 +1,173 @@
+import assert from 'node:assert/strict';
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  utimesSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+import { getDshProfileRebuildPlan } from './prepare-dsh-profile.mjs';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+function createPackageTree() {
+  const root = mkdtempSync(path.join(tmpdir(), 'bitfun-dsh-profile-'));
+  const packageDir = path.join(root, 'packages', 'dsh-acp');
+  const outDir = path.join(packageDir, 'dist-profile');
+  const prepareScriptPath = path.join(root, 'scripts', 'prepare-dsh-profile.mjs');
+
+  mkdirSync(path.join(packageDir, 'src'), { recursive: true });
+  mkdirSync(path.join(packageDir, 'presets'), { recursive: true });
+  mkdirSync(path.join(packageDir, 'scripts'), { recursive: true });
+  mkdirSync(path.join(root, 'scripts'), { recursive: true });
+  mkdirSync(outDir, { recursive: true });
+
+  writeFileSync(path.join(packageDir, 'src', 'app.ts'), 'export {}\n');
+  writeFileSync(path.join(packageDir, 'presets', 'preset.yml'), 'name: test\n');
+  writeFileSync(path.join(packageDir, 'cordis.yml'), 'name: test\n');
+  writeFileSync(path.join(packageDir, 'package.json'), '{}\n');
+  writeFileSync(path.join(packageDir, 'package-lock.json'), '{}\n');
+  writeFileSync(path.join(packageDir, 'tsconfig.build.json'), '{}\n');
+  writeFileSync(path.join(packageDir, 'scripts', 'build-profile.mjs'), 'export {}\n');
+  writeFileSync(prepareScriptPath, 'export {}\n');
+
+  return { root, packageDir, outDir, prepareScriptPath };
+}
+
+function writeStamp(outDir, stamp = { profile: 'bitfun-acp', content: 'abc' }) {
+  const stampPath = path.join(outDir, '.bitfun-bridge.json');
+  writeFileSync(stampPath, `${JSON.stringify(stamp)}\n`);
+  return stampPath;
+}
+
+function setMtime(filePath, mtimeMs) {
+  const atime = new Date(mtimeMs);
+  const mtime = new Date(mtimeMs);
+  utimesSync(filePath, atime, mtime);
+}
+
+test('rebuilds when the profile stamp is missing', () => {
+  const { root, packageDir, outDir, prepareScriptPath } = createPackageTree();
+  try {
+    const plan = getDshProfileRebuildPlan({ packageDir, outDir, prepareScriptPath });
+    assert.equal(plan.shouldBuild, true);
+    assert.match(plan.reason, /stamp is missing/);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('rebuilds when force is requested', () => {
+  const { root, packageDir, outDir, prepareScriptPath } = createPackageTree();
+  try {
+    const stampPath = writeStamp(outDir);
+    setMtime(stampPath, Date.now() + 60_000);
+    const plan = getDshProfileRebuildPlan({
+      packageDir,
+      outDir,
+      prepareScriptPath,
+      force: true,
+    });
+    assert.equal(plan.shouldBuild, true);
+    assert.match(plan.reason, /Force rebuild/);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('rebuilds when the stamp is incomplete', () => {
+  const { root, packageDir, outDir, prepareScriptPath } = createPackageTree();
+  try {
+    writeStamp(outDir, { profile: 'bitfun-acp' });
+    const plan = getDshProfileRebuildPlan({ packageDir, outDir, prepareScriptPath });
+    assert.equal(plan.shouldBuild, true);
+    assert.match(plan.reason, /incomplete/);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('rebuilds when an input is newer than the stamp', () => {
+  const { root, packageDir, outDir, prepareScriptPath } = createPackageTree();
+  try {
+    const stampPath = writeStamp(outDir);
+    const older = Date.now() - 60_000;
+    const newer = Date.now();
+    for (const filePath of [
+      path.join(packageDir, 'src', 'app.ts'),
+      path.join(packageDir, 'presets', 'preset.yml'),
+      path.join(packageDir, 'cordis.yml'),
+      path.join(packageDir, 'package.json'),
+      path.join(packageDir, 'package-lock.json'),
+      path.join(packageDir, 'tsconfig.build.json'),
+      path.join(packageDir, 'scripts', 'build-profile.mjs'),
+      prepareScriptPath,
+      stampPath,
+    ]) {
+      setMtime(filePath, older);
+    }
+    setMtime(path.join(packageDir, 'src', 'app.ts'), newer);
+    const plan = getDshProfileRebuildPlan({ packageDir, outDir, prepareScriptPath });
+    assert.equal(plan.shouldBuild, true);
+    assert.match(plan.reason, /inputs changed/);
+    assert.match(plan.reason, /app\.ts/);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('skips when a complete stamp is newer than every input', () => {
+  const { root, packageDir, outDir, prepareScriptPath } = createPackageTree();
+  try {
+    const older = Date.now() - 60_000;
+    const newer = Date.now();
+    for (const filePath of [
+      path.join(packageDir, 'src', 'app.ts'),
+      path.join(packageDir, 'presets', 'preset.yml'),
+      path.join(packageDir, 'cordis.yml'),
+      path.join(packageDir, 'package.json'),
+      path.join(packageDir, 'package-lock.json'),
+      path.join(packageDir, 'tsconfig.build.json'),
+      path.join(packageDir, 'scripts', 'build-profile.mjs'),
+      prepareScriptPath,
+    ]) {
+      setMtime(filePath, older);
+    }
+    const stampPath = writeStamp(outDir);
+    setMtime(stampPath, newer);
+    const plan = getDshProfileRebuildPlan({ packageDir, outDir, prepareScriptPath });
+    assert.equal(plan.shouldBuild, false);
+    assert.match(plan.reason, /up to date/);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('desktop:dev does not compile the DeepSeek profile', () => {
+  const devScript = readFileSync(path.join(repoRoot, 'scripts', 'dev.cjs'), 'utf8');
+  assert.doesNotMatch(devScript, /runCommandPrefixed\('dsh-profile'/);
+  assert.doesNotMatch(devScript, /\['run', 'prepare:dsh-profile'\]/);
+  assert.match(
+    devScript,
+    /Prepare resources \(parallel: monaco, version, mobile-web, flashgrep\)/,
+  );
+});
+
+test('desktop clippy does not compile the DeepSeek profile', () => {
+  const packageJson = JSON.parse(readFileSync(path.join(repoRoot, 'package.json'), 'utf8'));
+  assert.doesNotMatch(packageJson.scripts['lint:rs:desktop'], /prepare:dsh-profile/);
+});
+
+test('official frontend packaging still compiles the DeepSeek profile', () => {
+  const frontendBuildAll = readFileSync(
+    path.join(repoRoot, 'scripts', 'frontend-build-all.mjs'),
+    'utf8',
+  );
+  assert.match(frontendBuildAll, /prepare:dsh-profile/);
+});
diff --git a/scripts/release-channel.mjs b/scripts/release-channel.mjs
new file mode 100644
index 0000000000..358cd24db6
--- /dev/null
+++ b/scripts/release-channel.mjs
@@ -0,0 +1,82 @@
+const CHANNELS = {
+  stable: {
+    primaryUpdaterEndpoint:
+      'https://github.com/GCWing/BitFun/releases/latest/download/latest.json',
+    fallbackUpdaterEndpoint: 'https://openbitfun.com/release/latest.json',
+    githubChannelTag: null,
+  },
+  beta: {
+    primaryUpdaterEndpoint:
+      'https://github.com/GCWing/BitFun/releases/download/channel-beta/latest.json',
+    fallbackUpdaterEndpoint: 'https://openbitfun.com/release/beta/latest.json',
+    githubChannelTag: 'channel-beta',
+  },
+  nightly: {
+    primaryUpdaterEndpoint:
+      'https://github.com/GCWing/BitFun/releases/download/nightly/latest.json',
+    fallbackUpdaterEndpoint: 'https://openbitfun.com/release/nightly/latest.json',
+    githubChannelTag: 'nightly',
+  },
+};
+
+export function resolveReleaseChannel(value = 'stable') {
+  const channel = String(value || 'stable').trim().toLowerCase();
+  const config = CHANNELS[channel];
+  if (!config) {
+    throw new Error(
+      `Unsupported release channel "${value}". Expected one of: ${Object.keys(CHANNELS).join(', ')}`,
+    );
+  }
+  return { channel, ...config };
+}
+
+export function validateReleaseVersion(channelValue, versionValue) {
+  const { channel } = resolveReleaseChannel(channelValue);
+  const version = String(versionValue || '').trim();
+  const stablePattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+  const betaPattern =
+    /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)-beta\.([1-9]\d*)$/;
+  const nightlyPattern =
+    /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)-nightly\.\d{8}$/;
+  const valid = channel === 'stable'
+    ? stablePattern.test(version)
+    : channel === 'beta'
+      ? betaPattern.test(version)
+      : nightlyPattern.test(version);
+  if (!valid) {
+    const example = channel === 'stable'
+      ? '0.2.18'
+      : channel === 'beta'
+        ? '0.2.18-beta.1'
+        : '0.2.18-nightly.20260811';
+    throw new Error(
+      `Version "${versionValue}" is invalid for the ${channel} channel. Expected a version like ${example}`,
+    );
+  }
+  return version;
+}
+
+export function compareReleaseVersions(leftValue, rightValue) {
+  const left = parseComparableVersion(leftValue);
+  const right = parseComparableVersion(rightValue);
+  for (let index = 0; index < 3; index += 1) {
+    if (left.core[index] !== right.core[index]) {
+      return left.core[index] < right.core[index] ? -1 : 1;
+    }
+  }
+  if (left.beta === right.beta) return 0;
+  if (left.beta === null) return 1;
+  if (right.beta === null) return -1;
+  return left.beta < right.beta ? -1 : 1;
+}
+
+function parseComparableVersion(value) {
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:-beta\.([1-9]\d*))?$/.exec(String(value));
+  if (!match) {
+    throw new Error(`Unsupported channel version: ${value}`);
+  }
+  return {
+    core: match.slice(1, 4).map(Number),
+    beta: match[4] === undefined ? null : Number(match[4]),
+  };
+}
diff --git a/scripts/release-channel.test.mjs b/scripts/release-channel.test.mjs
new file mode 100644
index 0000000000..02bed3d72e
--- /dev/null
+++ b/scripts/release-channel.test.mjs
@@ -0,0 +1,95 @@
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import {
+  compareReleaseVersions,
+  resolveReleaseChannel,
+  validateReleaseVersion,
+} from './release-channel.mjs';
+import { setBuildVersion } from './set-build-version.mjs';
+import { decodeMinisignPublicKey } from './write-minisign-public-key.mjs';
+
+const RAW_PUBLIC_KEY = `untrusted comment: minisign public key E3E0874CEC1C22C3
+RWTDIhzsTIfg41w2Gwiei0zNDKaLYm9dQVpEWNQ/Ulpyt2mbS2JE1U2M`;
+
+test('stable and beta channels resolve to isolated updater feeds', () => {
+  const stable = resolveReleaseChannel('stable');
+  const beta = resolveReleaseChannel('beta');
+  assert.match(stable.primaryUpdaterEndpoint, /releases\/latest\/download/);
+  assert.match(beta.primaryUpdaterEndpoint, /releases\/download\/channel-beta/);
+  assert.equal(beta.fallbackUpdaterEndpoint, 'https://openbitfun.com/release/beta/latest.json');
+  assert.notEqual(beta.primaryUpdaterEndpoint, stable.primaryUpdaterEndpoint);
+});
+
+test('channel promotion follows SemVer including beta precedence', () => {
+  assert.equal(compareReleaseVersions('0.2.18-beta.2', '0.2.18-beta.1'), 1);
+  assert.equal(compareReleaseVersions('0.2.18', '0.2.18-beta.9'), 1);
+  assert.equal(compareReleaseVersions('0.2.19-beta.1', '0.2.18'), 1);
+  assert.equal(compareReleaseVersions('0.2.18', '0.2.19-beta.1'), -1);
+  assert.equal(compareReleaseVersions('0.2.18-beta.2', '0.2.18-beta.2'), 0);
+});
+
+test('release versions must match their channel', () => {
+  assert.equal(validateReleaseVersion('stable', '0.2.18'), '0.2.18');
+  assert.equal(validateReleaseVersion('beta', '0.2.18-beta.1'), '0.2.18-beta.1');
+  assert.throws(() => validateReleaseVersion('stable', '0.2.18-beta.1'));
+  assert.throws(() => validateReleaseVersion('beta', '0.2.18'));
+  assert.throws(() => validateReleaseVersion('beta', '0.2.18-beta.0'));
+  assert.equal(
+    validateReleaseVersion('nightly', '0.2.18-nightly.20260811'),
+    '0.2.18-nightly.20260811',
+  );
+});
+
+test('release public key export accepts raw and legacy base64 values', () => {
+  const expected = `${RAW_PUBLIC_KEY}\n`;
+  assert.equal(decodeMinisignPublicKey(RAW_PUBLIC_KEY), expected);
+  assert.equal(
+    decodeMinisignPublicKey(Buffer.from(expected).toString('base64')),
+    expected,
+  );
+  assert.throws(() => decodeMinisignPublicKey('not-a-key'));
+});
+
+test('build version projection updates every release-owned version file', () => {
+  const root = mkdtempSync(path.join(tmpdir(), 'bitfun-build-version-'));
+  const jsonFiles = [
+    'package.json',
+    'package-lock.json',
+    'BitFun-Installer/package.json',
+    'BitFun-Installer/package-lock.json',
+  ];
+  for (const relative of jsonFiles) {
+    const file = path.join(root, relative);
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify({ version: '1.0.0', packages: { '': { version: '1.0.0' } } }));
+  }
+  writeFixture(root, 'Cargo.toml', 'version = "1.0.0" # x-release-please-version\n');
+  writeFixture(
+    root,
+    'src/apps/relay-server/Cargo.toml',
+    'version = "1.0.0" # x-release-please-version\n',
+  );
+  writeFixture(root, 'BitFun-Installer/src-tauri/Cargo.toml', 'version = "1.0.0"\n');
+
+  setBuildVersion(root, '1.1.0-beta.2');
+
+  for (const relative of jsonFiles) {
+    const data = JSON.parse(readFileSync(path.join(root, relative), 'utf8'));
+    assert.equal(data.version, '1.1.0-beta.2');
+    assert.equal(data.packages[''].version, '1.1.0-beta.2');
+  }
+  assert.match(readFileSync(path.join(root, 'Cargo.toml'), 'utf8'), /1\.1\.0-beta\.2/);
+  assert.match(
+    readFileSync(path.join(root, 'src/apps/relay-server/Cargo.toml'), 'utf8'),
+    /1\.1\.0-beta\.2/,
+  );
+});
+
+function writeFixture(root, relative, content) {
+  const file = path.join(root, relative);
+  mkdirSync(path.dirname(file), { recursive: true });
+  writeFileSync(file, content);
+}
diff --git a/scripts/set-build-version.mjs b/scripts/set-build-version.mjs
new file mode 100644
index 0000000000..deaaa91ddb
--- /dev/null
+++ b/scripts/set-build-version.mjs
@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+export function setBuildVersion(root, version) {
+  if (!/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
+    throw new Error(`Invalid build version: ${version}`);
+  }
+
+  for (const relative of [
+    'package.json',
+    'package-lock.json',
+    'BitFun-Installer/package.json',
+    'BitFun-Installer/package-lock.json',
+  ]) {
+    const file = path.join(root, relative);
+    const data = JSON.parse(readFileSync(file, 'utf8'));
+    data.version = version;
+    if (data.packages?.['']) {
+      data.packages[''].version = version;
+    }
+    writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+  }
+
+  replaceVersion(
+    path.join(root, 'Cargo.toml'),
+    /^version = "[^"]+" # x-release-please-version$/m,
+    `version = "${version}" # x-release-please-version`,
+  );
+  replaceVersion(
+    path.join(root, 'src/apps/relay-server/Cargo.toml'),
+    /^version = "[^"]+" # x-release-please-version$/m,
+    `version = "${version}" # x-release-please-version`,
+  );
+  replaceVersion(
+    path.join(root, 'BitFun-Installer/src-tauri/Cargo.toml'),
+    /^version = "[^"]+"$/m,
+    `version = "${version}"`,
+  );
+}
+
+function replaceVersion(file, pattern, replacement) {
+  const source = readFileSync(file, 'utf8');
+  if (!pattern.test(source)) {
+    throw new Error(`Version marker was not found in ${file}`);
+  }
+  writeFileSync(file, source.replace(pattern, replacement), 'utf8');
+}
+
+function readArg(args, name) {
+  const index = args.indexOf(name);
+  return index >= 0 ? args[index + 1] : undefined;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const version = readArg(process.argv.slice(2), '--version');
+    if (!version) {
+      throw new Error('Missing required --version argument');
+    }
+    setBuildVersion(ROOT, version);
+    console.log(`[build-version] Updated release metadata to ${version}`);
+  } catch (error) {
+    console.error(`[build-version] ${error.message || error}`);
+    process.exit(1);
+  }
+}
diff --git a/scripts/sign-release-assets.sh b/scripts/sign-release-assets.sh
index f094711654..84370c5517 100755
--- a/scripts/sign-release-assets.sh
+++ b/scripts/sign-release-assets.sh
@@ -6,9 +6,11 @@
 # Usage: sign-release-assets.sh <file> [<file>...]
 #
 # Environment:
-#   BITFUN_SIGNING_KEY       minisign secret key, base64 (Tauri's wrapper format)
+#   BITFUN_SIGNING_KEY       minisign secret key, either the raw key file or
+#                            base64 of that file (legacy wrapper format)
 #   BITFUN_SIGNING_PASSWORD  password for that key
-#   BITFUN_SIGNING_PUBKEY    minisign public key, base64; used to self-verify
+#   BITFUN_SIGNING_PUBKEY    minisign public key, either the raw key file or
+#                            base64 of that file; used to self-verify
 #
 # With no signing key configured this is a no-op, so forks keep building.
 #
@@ -88,10 +90,25 @@ WORK="$(mktemp -d)"
 trap 'rm -rf "$WORK"' EXIT
 umask 077
 
-# Tauri stores the minisign secret key base64-wrapped; unwrap it to the on-disk
-# format minisign expects.
-printf '%s' "$BITFUN_SIGNING_KEY" | base64 -d >"$WORK/release.key"
-printf '%s' "${BITFUN_SIGNING_PUBKEY:-}" | base64 -d >"$WORK/release.pub" 2>/dev/null || true
+# New Tauri CLIs accept the raw minisign key file as their environment value;
+# older repository secrets wrap that whole file in base64. Support both so the
+# Tauri bundler and direct minisign asset signing can share one secret.
+case "$BITFUN_SIGNING_KEY" in
+  "untrusted comment:"*)
+    printf '%s\n' "$BITFUN_SIGNING_KEY" >"$WORK/release.key"
+    ;;
+  *)
+    printf '%s' "$BITFUN_SIGNING_KEY" | base64 -d >"$WORK/release.key"
+    ;;
+esac
+case "${BITFUN_SIGNING_PUBKEY:-}" in
+  "untrusted comment:"*)
+    printf '%s\n' "$BITFUN_SIGNING_PUBKEY" >"$WORK/release.pub"
+    ;;
+  *)
+    printf '%s' "${BITFUN_SIGNING_PUBKEY:-}" | base64 -d >"$WORK/release.pub" 2>/dev/null || true
+    ;;
+esac
 
 signed=0
 skipped=0
diff --git a/scripts/verify-webkit-compatibility.cjs b/scripts/verify-webkit-compatibility.cjs
new file mode 100644
index 0000000000..cce0df65d0
--- /dev/null
+++ b/scripts/verify-webkit-compatibility.cjs
@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT_DIR = path.resolve(__dirname, '..');
+const DEFAULT_DIST_DIR = path.join(ROOT_DIR, 'dist');
+const FORBIDDEN_PATTERNS = [
+  {
+    label: 'remark-gfm variable-length email lookbehind',
+    source: '(?<=^|\\s|\\p{P}|\\p{S})',
+  },
+];
+
+function collectJavaScriptFiles(directory) {
+  if (!fs.existsSync(directory)) {
+    return [];
+  }
+
+  const files = [];
+  const entries = fs.readdirSync(directory, { withFileTypes: true });
+  for (const entry of entries) {
+    const entryPath = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...collectJavaScriptFiles(entryPath));
+    } else if (entry.isFile() && entry.name.endsWith('.js')) {
+      files.push(entryPath);
+    }
+  }
+  return files;
+}
+
+function findWebKitCompatibilityViolations(directory = DEFAULT_DIST_DIR) {
+  const violations = [];
+  for (const filePath of collectJavaScriptFiles(directory)) {
+    const content = fs.readFileSync(filePath, 'utf8');
+    for (const pattern of FORBIDDEN_PATTERNS) {
+      if (content.includes(pattern.source)) {
+        violations.push({ filePath, label: pattern.label });
+      }
+    }
+  }
+  return violations;
+}
+
+function main() {
+  if (!fs.existsSync(DEFAULT_DIST_DIR)) {
+    console.error('[verify-webkit-compatibility] Production output directory is missing.');
+    process.exitCode = 1;
+    return;
+  }
+
+  const violations = findWebKitCompatibilityViolations();
+  if (violations.length === 0) {
+    console.log(
+      '[verify-webkit-compatibility] Known Markdown WebKit incompatibilities were not found.'
+    );
+    return;
+  }
+
+  console.error('[verify-webkit-compatibility] Unsupported JavaScript found:');
+  for (const violation of violations) {
+    console.error(
+      `  - ${path.relative(ROOT_DIR, violation.filePath)}: ${violation.label}`
+    );
+  }
+  process.exitCode = 1;
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { findWebKitCompatibilityViolations };
diff --git a/scripts/verify-webkit-compatibility.test.mjs b/scripts/verify-webkit-compatibility.test.mjs
new file mode 100644
index 0000000000..a5868ba0f5
--- /dev/null
+++ b/scripts/verify-webkit-compatibility.test.mjs
@@ -0,0 +1,42 @@
+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 { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { findWebKitCompatibilityViolations } = require('./verify-webkit-compatibility.cjs');
+
+function withTempDist(callback) {
+  const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'bitfun-webkit-compat-'));
+  try {
+    return callback(directory);
+  } finally {
+    fs.rmSync(directory, { recursive: true, force: true });
+  }
+}
+
+test('accepts production JavaScript without the incompatible lookbehind', () => {
+  withTempDist((directory) => {
+    fs.writeFileSync(path.join(directory, 'app.js'), 'const email = /[-.\\w+]+@example\\.com/gu;');
+    assert.deepEqual(findWebKitCompatibilityViolations(directory), []);
+  });
+});
+
+test('rejects the remark-gfm variable-length email lookbehind', () => {
+  withTempDist((directory) => {
+    const filePath = path.join(directory, 'app.js');
+    fs.writeFileSync(
+      filePath,
+      String.raw`const email = /(?<=^|\s|\p{P}|\p{S})([-.\w+]+)@example/gu;`
+    );
+
+    assert.deepEqual(findWebKitCompatibilityViolations(directory), [
+      {
+        filePath,
+        label: 'remark-gfm variable-length email lookbehind',
+      },
+    ]);
+  });
+});
diff --git a/scripts/version-generation.test.mjs b/scripts/version-generation.test.mjs
index bd599fcfea..6750c23073 100644
--- a/scripts/version-generation.test.mjs
+++ b/scripts/version-generation.test.mjs
@@ -18,10 +18,24 @@ for (const [buildEnv, isDev] of [['production', false], ['development', true]])
     );
     assert.equal(generated.version, expectedVersion);
     assert.equal(generated.buildEnv, buildEnv);
+    assert.equal(generated.releaseChannel, 'stable');
     assert.equal(generated.isDev, isDev);
   });
 }
 
+test('records the immutable release channel in generated metadata', () => {
+  const outputRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'bitfun-version-beta-'));
+  const result = run(
+    ['--build-env', 'production', '--output-root', outputRoot],
+    { BITFUN_RELEASE_CHANNEL: 'beta' },
+  );
+  assert.equal(result.status, 0, result.stderr);
+  const generated = JSON.parse(
+    fs.readFileSync(path.join(outputRoot, 'src/web-ui/public/version.json'), 'utf8')
+  );
+  assert.equal(generated.releaseChannel, 'beta');
+});
+
 test('fails instead of reusing stale metadata when build environment is missing', () => {
   const outputRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'bitfun-version-missing-'));
   const result = run(['--output-root', outputRoot]);
@@ -29,9 +43,10 @@ test('fails instead of reusing stale metadata when build environment is missing'
   assert.match(`${result.stdout}\n${result.stderr}`, /Expected --build-env/);
 });
 
-function run(args) {
+function run(args, extraEnv = {}) {
   return spawnSync(process.execPath, ['scripts/generate-version.cjs', ...args], {
     cwd: root,
     encoding: 'utf8',
+    env: { ...process.env, ...extraEnv },
   });
 }
diff --git a/scripts/write-minisign-public-key.mjs b/scripts/write-minisign-public-key.mjs
new file mode 100644
index 0000000000..900fab03cb
--- /dev/null
+++ b/scripts/write-minisign-public-key.mjs
@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import { writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export function decodeMinisignPublicKey(value) {
+  const input = String(value || '').trim();
+  if (!input) {
+    throw new Error('BITFUN_SIGNING_PUBKEY is required');
+  }
+
+  const raw = input.startsWith('untrusted comment:')
+    ? input
+    : decodeBase64(input);
+  const lines = raw.trim().split(/\r?\n/);
+  if (!lines[0]?.startsWith('untrusted comment:') || lines.length < 2 || !lines[1]) {
+    throw new Error('Public key is not a minisign public key file');
+  }
+  return `${raw.trim()}\n`;
+}
+
+function decodeBase64(value) {
+  const compact = value.replace(/\s/g, '');
+  if (
+    compact.length === 0
+    || compact.length % 4 !== 0
+    || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(compact)
+  ) {
+    throw new Error('Public key is neither raw minisign text nor valid base64');
+  }
+  return Buffer.from(compact, 'base64').toString('utf8');
+}
+
+function readArg(args, name) {
+  const index = args.indexOf(name);
+  return index >= 0 ? args[index + 1] : undefined;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const output = readArg(process.argv.slice(2), '--out');
+    if (!output) throw new Error('Missing required --out argument');
+    writeFileSync(output, decodeMinisignPublicKey(process.env.BITFUN_SIGNING_PUBKEY), 'utf8');
+  } catch (error) {
+    console.error(`[release-key] ${error.message || error}`);
+    process.exit(1);
+  }
+}
diff --git a/sdk/typescript/README.md b/sdk/typescript/README.md
new file mode 100644
index 0000000000..95e3f5e159
--- /dev/null
+++ b/sdk/typescript/README.md
@@ -0,0 +1,64 @@
+# BitFun Agent SDK for TypeScript
+
+This package is a repository-internal vertical slice. It is private, reports
+`not_delivered` through the Host handshake, and must not be published or
+described as a Preview SDK yet.
+
+The slice validates the intended public object model:
+
+- one application-level `AgentClient` owns one managed native
+  `bitfun-sdk-host` process and one Host connection;
+- `client.query()` uses a Host-managed transient Session;
+- `client.sessions.create()` creates an explicit Session whose Turns reuse the
+  same connection and existing Agent Runtime owner;
+- `Query` is an ordered async stream with idempotent cancellation, cached final
+  `Result`, and explicit close semantics;
+- protocol and process failures use `SdkError`, including outcome certainty.
+
+Lifecycle cleanup is bounded. The Windows Host contains descendants in a
+kill-on-close Job Object, while Unix managed Hosts run in an isolated process
+group. A cleanup result whose outcome is unknown makes the connection
+unusable and triggers Host reclamation.
+
+It does not start the CLI or the Node/Bun Plugin Host, and it does not implement
+another Agent Runtime. The managed native Host adapts this package to the
+existing `agent-runtime::sdk` API.
+
+## Repository usage
+
+Build `bitfun-sdk-host`, then pass its absolute path while the platform-native
+package layout is still pending:
+
+```typescript
+import { AgentClient } from "@bitfun/agent-sdk";
+
+await using client = await AgentClient.start({
+  cwd: process.cwd(),
+  hostPath: process.env.BITFUN_SDK_HOST_PATH,
+});
+
+await using query = await client.query({ prompt: "Summarize this repository" });
+for await (const item of query) {
+  if (item.type === "assistant_text_delta") {
+    process.stdout.write(item.text);
+  }
+}
+const result = await query.result();
+```
+
+`BITFUN_SDK_HOST_PATH` is also read directly when `hostPath` is omitted. The
+eventual installable package must bundle or resolve a matching signed Host; it
+must not require a separately installed BitFun CLI.
+
+## Development
+
+```bash
+pnpm --dir sdk/typescript test
+pnpm --dir sdk/typescript type-check
+```
+
+The internal TypeScript wire bindings are generated from the Rust SDK Host
+protocol with `ts-rs`. Runtime validators are generated from those same
+bindings, while only JSON-RPC envelope and cross-field semantic checks remain
+hand-written. The generated sources are deliberately not the public API and
+are not checked in.
diff --git a/sdk/typescript/package.json b/sdk/typescript/package.json
new file mode 100644
index 0000000000..735786447e
--- /dev/null
+++ b/sdk/typescript/package.json
@@ -0,0 +1,33 @@
+{
+  "name": "@bitfun/agent-sdk",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Internal TypeScript vertical slice for the BitFun Agent SDK",
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/sdk/typescript/src/index.d.ts",
+      "import": "./dist/sdk/typescript/src/index.js"
+    }
+  },
+  "files": [
+    "dist/sdk/typescript/src/*.d.ts",
+    "dist/sdk/typescript/src/*.js",
+    "dist/sdk/typescript/src/internal/*.js",
+    "dist/src/crates/adapters/transport/typescript/src/*.js",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "pnpm run generate:wire && tsc -p tsconfig.json",
+    "generate:wire": "node scripts/generate-wire.mjs",
+    "test": "pnpm run build && node --test scripts/*.test.mjs dist/src/crates/adapters/transport/typescript/test/**/*.test.js dist/sdk/typescript/test/**/*.test.js",
+    "type-check": "pnpm run generate:wire && tsc -p tsconfig.json --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "22.19.7",
+    "typescript": "~5.8.3"
+  }
+}
diff --git a/sdk/typescript/scripts/generate-wire.mjs b/sdk/typescript/scripts/generate-wire.mjs
new file mode 100644
index 0000000000..bd94f6b863
--- /dev/null
+++ b/sdk/typescript/scripts/generate-wire.mjs
@@ -0,0 +1,106 @@
+import { spawn } from "node:child_process";
+import { mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { generateRuntimeValidators } from "./runtime-validator-generator.mjs";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const repositoryRoot = resolve(packageRoot, "../..");
+const outputDirectory = join(packageRoot, "src", "internal", "wire");
+const validatorOutput = join(
+  packageRoot,
+  "src",
+  "internal",
+  "wire-validators.ts",
+);
+
+await rm(outputDirectory, { recursive: true, force: true });
+await rm(validatorOutput, { force: true });
+await mkdir(outputDirectory, { recursive: true });
+
+await run(
+  "cargo",
+  [
+    "test",
+    "--locked",
+    "-p",
+    "bitfun-sdk-host",
+    "--no-default-features",
+    "--features",
+    "ts",
+    "--lib",
+    "export",
+    "--",
+    "--nocapture",
+  ],
+  {
+    ...process.env,
+    TS_RS_EXPORT_DIR: outputDirectory,
+  },
+);
+
+const files = (await readdir(outputDirectory))
+  .filter((file) => file.endsWith(".ts") && file !== "index.ts")
+  .map((file) => file.slice(0, -3))
+  .sort();
+const requiredTypes = [
+  "ErrorData",
+  "HostCapabilities",
+  "InitializeParams",
+  "InitializeResult",
+  "QueryCancelParams",
+  "QueryCancelResult",
+  "QueryEventParams",
+  "QueryResultParams",
+  "QueryStartParams",
+  "QueryStartResult",
+  "SessionCloseParams",
+  "SessionCloseResult",
+  "SessionCreateParams",
+  "SessionCreateResult",
+  "ShutdownResult",
+];
+const missing = requiredTypes.filter((type) => !files.includes(type));
+if (missing.length > 0) {
+  throw new Error(`SDK Host wire generation missed: ${missing.join(", ")}`);
+}
+
+await writeFile(
+  validatorOutput,
+  await generateRuntimeValidators(outputDirectory, {
+    typeImportPath: "./wire/index.js",
+  }),
+);
+
+const header = `// GENERATED CODE! DO NOT MODIFY BY HAND!\n// Source: bitfun-sdk-host protocol types via ts-rs.\n`;
+const exports = files.map(
+  (file) => `export type { ${file} } from "./${file}.js";`,
+);
+await writeFile(
+  join(outputDirectory, "index.ts"),
+  `${header}\n${exports.join("\n")}\n`,
+);
+
+async function run(command, args, env) {
+  await new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn(command, args, {
+      cwd: repositoryRoot,
+      env,
+      shell: false,
+      stdio: "inherit",
+    });
+    child.once("error", rejectPromise);
+    child.once("exit", (code, signal) => {
+      if (code === 0) {
+        resolvePromise();
+        return;
+      }
+      rejectPromise(
+        new Error(
+          `${command} ${args.join(" ")} failed with ${signal ?? `exit ${code}`}`,
+        ),
+      );
+    });
+  });
+}
diff --git a/sdk/typescript/scripts/generated-wire-runtime.test.mjs b/sdk/typescript/scripts/generated-wire-runtime.test.mjs
new file mode 100644
index 0000000000..fa8306cf86
--- /dev/null
+++ b/sdk/typescript/scripts/generated-wire-runtime.test.mjs
@@ -0,0 +1,135 @@
+import assert from "node:assert/strict";
+import { readFile, readdir } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import test from "node:test";
+
+import ts from "typescript";
+
+const scriptsDirectory = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(scriptsDirectory, "..");
+const wireDirectory = join(packageRoot, "src", "internal", "wire");
+const validatorPath = join(packageRoot, "src", "internal", "wire-validators.ts");
+
+test("Rust wire export produces executable validators for every type", async () => {
+  const typeNames = (await readdir(wireDirectory))
+    .filter((file) => file.endsWith(".ts") && file !== "index.ts")
+    .map((file) => file.slice(0, -3))
+    .sort();
+  const validatorSource = await readFile(validatorPath, "utf8").catch((error) => {
+    if (error?.code === "ENOENT") {
+      throw new Error(
+        "generated wire validators are missing; run the SDK build before this test",
+      );
+    }
+    throw error;
+  });
+  const javascript = ts.transpileModule(validatorSource, {
+    compilerOptions: {
+      module: ts.ModuleKind.ES2022,
+      target: ts.ScriptTarget.ES2022,
+    },
+  }).outputText;
+  const validators = await import(
+    `data:text/javascript;base64,${Buffer.from(javascript).toString("base64")}`
+  );
+
+  for (const typeName of typeNames) {
+    assert.equal(
+      typeof validators[`is${typeName}`],
+      "function",
+      `${typeName} must have an executable runtime validator`,
+    );
+  }
+
+  const initializeResult = {
+    protocolVersion: 1,
+    runtimeVersion: "0.1.0",
+    stability: "not_delivered",
+    capabilities: {
+      sessionCreate: true,
+      sessionCreateLifetime: "connection",
+      query: true,
+      queryCancel: true,
+      sessionClose: true,
+      eventStream: true,
+      structuredOutput: false,
+      usage: false,
+      customTools: false,
+      permissionCallbacks: false,
+      hooks: false,
+      mcpConfiguration: false,
+      prestartedTransport: false,
+    },
+  };
+  assert.equal(validators.isInitializeResult(initializeResult), true);
+  assert.equal(
+    validators.isInitializeResult({ ...initializeResult, unexpected: true }),
+    false,
+  );
+  assert.equal(
+    validators.isInitializeResult({
+      ...initializeResult,
+      capabilities: {
+        ...initializeResult.capabilities,
+        eventStream: "yes",
+      },
+    }),
+    false,
+  );
+
+  assert.equal(
+    validators.isQueryEventParams({
+      queryId: "query_1",
+      sessionId: "session_1",
+      turnId: "turn_1",
+      operationId: "operation_1",
+      sequence: 1,
+      event: { type: "assistant_text_delta", text: "hello" },
+    }),
+    true,
+  );
+  assert.equal(
+    validators.isQueryEventParams({
+      queryId: "query_1",
+      sessionId: "session_1",
+      turnId: "turn_1",
+      operationId: "operation_1",
+      sequence: 1,
+    }),
+    false,
+  );
+
+  assert.equal(
+    validators.isSessionCreateResult({
+      sessionId: "session_1",
+      sessionName: "Main",
+      agent: "agentic",
+      lifetime: "connection",
+      executionTarget: {
+        kind: "managedWorktree",
+        worktreeId: "worktree_1",
+        rootPath: "D:/workspace/worktrees/worktree_1",
+        lifecycle: "managed",
+      },
+    }),
+    true,
+  );
+  assert.equal(
+    validators.isSessionCreateResult({
+      sessionId: "session_1",
+      sessionName: "Main",
+      agent: "agentic",
+      lifetime: "connection",
+      executionTarget: {
+        kind: "managedWorktree",
+        rootPath: "D:/workspace/worktrees/worktree_1",
+        lifecycle: "temporary",
+      },
+    }),
+    false,
+  );
+
+  assert.equal(validators.isShutdownParams({}), true);
+  assert.equal(validators.isShutdownParams({ reason: "later" }), false);
+});
diff --git a/sdk/typescript/scripts/runtime-validator-generator.mjs b/sdk/typescript/scripts/runtime-validator-generator.mjs
new file mode 100644
index 0000000000..f2cb93feee
--- /dev/null
+++ b/sdk/typescript/scripts/runtime-validator-generator.mjs
@@ -0,0 +1,235 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import ts from "typescript";
+
+export async function generateRuntimeValidators(
+  directory,
+  { typeImportPath = "./index.js" } = {},
+) {
+  const aliases = await readAliases(directory);
+  const names = [...aliases.keys()].sort();
+
+  for (const [name, declaration] of aliases) {
+    validateSupportedType(declaration.type, aliases, name);
+  }
+
+  const header = [
+    "// GENERATED CODE! DO NOT MODIFY BY HAND!",
+    "// Source: bitfun-sdk-host Rust protocol types via ts-rs.",
+    "",
+    `import type { ${names.join(", ")} } from ${JSON.stringify(typeImportPath)};`,
+    "",
+  ];
+  const functions = names.flatMap((name) => {
+    const declaration = aliases.get(name);
+    const expression = emitTypeCheck(declaration.type, "value", aliases, name);
+    return [
+      `export function is${name}(value: unknown): value is ${name} {`,
+      `  return ${expression};`,
+      "}",
+      "",
+    ];
+  });
+  const helpers = [
+    "function isRecord(value: unknown): value is Record<string, unknown> {",
+    '  return typeof value === "object" && value !== null && !Array.isArray(value);',
+    "}",
+    "",
+    "function hasOnlyKeys(value: Record<string, unknown>, allowed: readonly string[]): boolean {",
+    "  const keys = Object.keys(value);",
+    "  return keys.length <= allowed.length && keys.every((key) => allowed.includes(key));",
+    "}",
+    "",
+  ];
+
+  return [...header, ...functions, ...helpers].join("\n");
+}
+
+async function readAliases(directory) {
+  const files = (await readdir(directory))
+    .filter(
+      (file) =>
+        file.endsWith(".ts") &&
+        file !== "index.ts" &&
+        file !== "validators.ts",
+    )
+    .sort();
+  const aliases = new Map();
+
+  for (const file of files) {
+    const sourceText = await readFile(join(directory, file), "utf8");
+    const source = ts.createSourceFile(
+      file,
+      sourceText,
+      ts.ScriptTarget.Latest,
+      true,
+      ts.ScriptKind.TS,
+    );
+    if (source.parseDiagnostics.length > 0) {
+      throw new Error(`cannot parse generated wire type ${file}`);
+    }
+    const unexpected = source.statements.find(
+      (statement) =>
+        !ts.isImportDeclaration(statement) &&
+        !ts.isTypeAliasDeclaration(statement),
+    );
+    if (unexpected !== undefined) {
+      throw new Error(
+        `generated wire file ${file} contains unsupported declaration ${ts.SyntaxKind[unexpected.kind]}`,
+      );
+    }
+    const declarations = source.statements.filter(ts.isTypeAliasDeclaration);
+    if (declarations.length !== 1) {
+      throw new Error(
+        `generated wire file ${file} must contain exactly one type alias`,
+      );
+    }
+    const declaration = declarations[0];
+    const expectedName = file.slice(0, -3);
+    if (declaration.name.text !== expectedName) {
+      throw new Error(
+        `generated wire file ${file} must declare ${expectedName}`,
+      );
+    }
+    if (
+      !declaration.modifiers?.some(
+        (modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword,
+      )
+    ) {
+      throw new Error(`generated wire type ${expectedName} must be exported`);
+    }
+    aliases.set(expectedName, declaration);
+  }
+  return aliases;
+}
+
+function validateSupportedType(node, aliases, owner) {
+  emitTypeCheck(node, "value", aliases, owner);
+}
+
+function emitTypeCheck(node, value, aliases, owner) {
+  if (ts.isParenthesizedTypeNode(node)) {
+    return emitTypeCheck(node.type, value, aliases, owner);
+  }
+  if (ts.isUnionTypeNode(node)) {
+    return `(${node.types
+      .map((member) => emitTypeCheck(member, value, aliases, owner))
+      .join(" || ")})`;
+  }
+  if (ts.isLiteralTypeNode(node)) {
+    if (node.literal.kind === ts.SyntaxKind.NullKeyword) {
+      return `${value} === null`;
+    }
+    if (
+      ts.isStringLiteral(node.literal) ||
+      ts.isNumericLiteral(node.literal)
+    ) {
+      return `${value} === ${JSON.stringify(
+        ts.isStringLiteral(node.literal)
+          ? node.literal.text
+          : Number(node.literal.text),
+      )}`;
+    }
+    if (node.literal.kind === ts.SyntaxKind.TrueKeyword) {
+      return `${value} === true`;
+    }
+    if (node.literal.kind === ts.SyntaxKind.FalseKeyword) {
+      return `${value} === false`;
+    }
+    throw unsupported(owner, node, "literal");
+  }
+  if (node.kind === ts.SyntaxKind.StringKeyword) {
+    return `typeof ${value} === "string"`;
+  }
+  if (node.kind === ts.SyntaxKind.NumberKeyword) {
+    return `(typeof ${value} === "number" && Number.isFinite(${value}))`;
+  }
+  if (node.kind === ts.SyntaxKind.BooleanKeyword) {
+    return `typeof ${value} === "boolean"`;
+  }
+  if (ts.isArrayTypeNode(node)) {
+    const item = emitTypeCheck(node.elementType, "item", aliases, owner);
+    return `(Array.isArray(${value}) && ${value}.every((item: unknown) => ${item}))`;
+  }
+  if (ts.isTypeLiteralNode(node)) {
+    return emitObjectCheck(node, value, aliases, owner);
+  }
+  if (ts.isTypeReferenceNode(node)) {
+    if (!ts.isIdentifier(node.typeName)) {
+      throw unsupported(owner, node, "qualified type reference");
+    }
+    const name = node.typeName.text;
+    if (aliases.has(name)) {
+      if (node.typeArguments !== undefined) {
+        throw unsupported(owner, node, `generic wire type ${name}`);
+      }
+      return `is${name}(${value})`;
+    }
+    if (name === "Array" || name === "ReadonlyArray") {
+      if (node.typeArguments?.length !== 1) {
+        throw unsupported(owner, node, `${name} arity`);
+      }
+      const item = emitTypeCheck(node.typeArguments[0], "item", aliases, owner);
+      return `(Array.isArray(${value}) && ${value}.every((item: unknown) => ${item}))`;
+    }
+    if (name === "Record" && isEmptyRecord(node)) {
+      return `(isRecord(${value}) && Object.keys(${value}).length === 0)`;
+    }
+    throw new Error(
+      `${owner}: unsupported type reference ${name}; runtime validator generation is fail-closed`,
+    );
+  }
+  throw unsupported(owner, node, ts.SyntaxKind[node.kind] ?? "unknown syntax");
+}
+
+function emitObjectCheck(node, value, aliases, owner) {
+  const properties = [];
+  for (const member of node.members) {
+    if (!ts.isPropertySignature(member) || member.type === undefined) {
+      throw unsupported(owner, member, "object member");
+    }
+    properties.push({
+      name: propertyName(member.name, owner),
+      optional: member.questionToken !== undefined,
+      type: member.type,
+    });
+  }
+  const allowed = JSON.stringify(properties.map(({ name }) => name));
+  const checks = properties.map(({ name, optional, type }) => {
+    const access = `${value}[${JSON.stringify(name)}]`;
+    const check = emitTypeCheck(type, access, aliases, owner);
+    return optional ? `(${access} === undefined || ${check})` : check;
+  });
+  return [
+    `(isRecord(${value})`,
+    `hasOnlyKeys(${value}, ${allowed})`,
+    ...checks,
+  ].join(" && ") + ")";
+}
+
+function propertyName(node, owner) {
+  if (ts.isIdentifier(node) || ts.isStringLiteral(node)) {
+    return node.text;
+  }
+  if (ts.isNumericLiteral(node)) {
+    return node.text;
+  }
+  throw unsupported(owner, node, "computed property name");
+}
+
+function isEmptyRecord(node) {
+  if (node.typeArguments?.length !== 2) {
+    return false;
+  }
+  return (
+    node.typeArguments[0].kind === ts.SyntaxKind.SymbolKeyword &&
+    node.typeArguments[1].kind === ts.SyntaxKind.NeverKeyword
+  );
+}
+
+function unsupported(owner, node, detail) {
+  return new Error(
+    `${owner}: unsupported ${detail} (${ts.SyntaxKind[node.kind] ?? node.kind}); runtime validator generation is fail-closed`,
+  );
+}
diff --git a/sdk/typescript/scripts/runtime-validator-generator.test.mjs b/sdk/typescript/scripts/runtime-validator-generator.test.mjs
new file mode 100644
index 0000000000..2dcb6aa907
--- /dev/null
+++ b/sdk/typescript/scripts/runtime-validator-generator.test.mjs
@@ -0,0 +1,144 @@
+import assert from "node:assert/strict";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+
+import ts from "typescript";
+
+import { generateRuntimeValidators } from "./runtime-validator-generator.mjs";
+
+test("generated validators enforce nested ts-rs wire structures", async () => {
+  const directory = await mkdtemp(join(tmpdir(), "bitfun-wire-validator-"));
+  try {
+    await Promise.all([
+      writeFile(join(directory, "Kind.ts"), 'export type Kind = "local" | "remote";\n'),
+      writeFile(
+        join(directory, "Child.ts"),
+        "export type Child = { note?: string | null, tags: Array<string> };\n",
+      ),
+      writeFile(
+        join(directory, "Envelope.ts"),
+        [
+          'import type { Child } from "./Child";',
+          'import type { Kind } from "./Kind";',
+          "export type Envelope = { kind: Kind, child?: Child, empty: Record<symbol, never> };",
+          "",
+        ].join("\n"),
+      ),
+    ]);
+
+    const validators = await loadValidators(directory);
+
+    assert.equal(
+      validators.isEnvelope({
+        kind: "local",
+        child: { note: null, tags: ["one", "two"] },
+        empty: {},
+      }),
+      true,
+    );
+    assert.equal(
+      validators.isEnvelope({
+        kind: "other",
+        child: { tags: [] },
+        empty: {},
+      }),
+      false,
+    );
+    assert.equal(
+      validators.isEnvelope({
+        kind: "remote",
+        child: { tags: ["ok", 2] },
+        empty: {},
+      }),
+      false,
+    );
+    assert.equal(
+      validators.isEnvelope({
+        kind: "remote",
+        child: { tags: [], unexpected: true },
+        empty: {},
+      }),
+      false,
+    );
+    assert.equal(
+      validators.isEnvelope({ kind: "remote", empty: {}, unexpected: true }),
+      false,
+    );
+    assert.equal(
+      validators.isEnvelope({ kind: "remote", empty: { unexpected: true } }),
+      false,
+    );
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("generated validators reject missing required fields", async () => {
+  const directory = await mkdtemp(join(tmpdir(), "bitfun-wire-validator-"));
+  try {
+    await writeFile(
+      join(directory, "Required.ts"),
+      "export type Required = { required: string, optional?: string };\n",
+    );
+
+    const validators = await loadValidators(directory);
+
+    assert.equal(validators.isRequired({ required: "present" }), true);
+    assert.equal(validators.isRequired({ optional: "present" }), false);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("generation fails closed for unsupported type syntax", async () => {
+  const directory = await mkdtemp(join(tmpdir(), "bitfun-wire-validator-"));
+  try {
+    await writeFile(
+      join(directory, "Unsupported.ts"),
+      "export type Unsupported = { createdAt: Date };\n",
+    );
+
+    await assert.rejects(
+      generateRuntimeValidators(directory),
+      /unsupported type reference Date/i,
+    );
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("generation rejects declarations outside the ts-rs type surface", async () => {
+  const directory = await mkdtemp(join(tmpdir(), "bitfun-wire-validator-"));
+  try {
+    await writeFile(
+      join(directory, "Unexpected.ts"),
+      [
+        "export type Unexpected = { value: string };",
+        "export const runtimeValue = true;",
+        "",
+      ].join("\n"),
+    );
+
+    await assert.rejects(
+      generateRuntimeValidators(directory),
+      /unsupported declaration/i,
+    );
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+async function loadValidators(directory) {
+  const source = await generateRuntimeValidators(directory);
+  const javascript = ts.transpileModule(source, {
+    compilerOptions: {
+      module: ts.ModuleKind.ES2022,
+      target: ts.ScriptTarget.ES2022,
+    },
+  }).outputText;
+  return import(
+    `data:text/javascript;base64,${Buffer.from(javascript).toString("base64")}`
+  );
+}
diff --git a/sdk/typescript/src/client.ts b/sdk/typescript/src/client.ts
new file mode 100644
index 0000000000..e73ef997e5
--- /dev/null
+++ b/sdk/typescript/src/client.ts
@@ -0,0 +1,154 @@
+import type { InitializeResult, QueryStartParams, QueryStartResult } from "./internal/wire/index.js";
+import type { JsonRpcConnection } from "./internal/json-rpc.js";
+import { Query } from "./query.js";
+import { Session, Sessions } from "./session.js";
+import type { AgentCapabilities, AgentClientOptions, QueryInput } from "./types.js";
+
+export class AgentClient {
+  readonly #connection: JsonRpcConnection;
+  readonly #options: AgentClientOptions;
+  readonly capabilities: AgentCapabilities;
+  readonly sessions: Sessions;
+  readonly #queries = new Set<Query>();
+  readonly #ownedSessions = new Set<Session>();
+  #closed = false;
+  #closePromise?: Promise<void>;
+
+  static async start(options: AgentClientOptions): Promise<AgentClient> {
+    const hostPath = options.hostPath ?? process.env.BITFUN_SDK_HOST_PATH;
+    if (hostPath === undefined || hostPath.length === 0) {
+      const { SdkError } = await import("./errors.js");
+      throw new SdkError("SDK Host executable is unavailable", {
+        code: "not_found",
+        stage: "initialize",
+        retryable: false,
+        correlationId: "local:host_start",
+        outcomeCertainty: "not_started",
+      });
+    }
+    const [{ createAgentClient }, { startManagedHost }] = await Promise.all([
+      import("./internal/client.js"),
+      import("./internal/managed-host.js"),
+    ]);
+    const transport = await startManagedHost({
+      executable: hostPath,
+      cwd: options.cwd,
+    });
+    try {
+      return await createAgentClient(transport, options);
+    } catch (error) {
+      await transport.close();
+      throw error;
+    }
+  }
+
+  private constructor(
+    connection: JsonRpcConnection,
+    options: AgentClientOptions,
+    initialized: InitializeResult,
+  ) {
+    this.#connection = connection;
+    this.#options = options;
+    this.capabilities = Object.freeze({
+      query: initialized.capabilities.query,
+      sessions: initialized.capabilities.sessionCreate,
+      cancellation: initialized.capabilities.queryCancel,
+    });
+    this.sessions = Sessions.forClient(
+      connection,
+      options.cwd,
+      (query) => this.#trackQuery(query),
+      (session) => this.#trackSession(session),
+      () => this.#ensureOpen(),
+    );
+  }
+
+  /** @internal */
+  static create(
+    connection: JsonRpcConnection,
+    options: AgentClientOptions,
+    initialized: InitializeResult,
+  ): AgentClient {
+    return new AgentClient(connection, options, initialized);
+  }
+
+  async query(input: QueryInput): Promise<Query> {
+    this.#ensureOpen();
+    const params: QueryStartParams = {
+      prompt: input.prompt,
+      sessionId: null,
+      sessionName: null,
+      agent: input.agent ?? null,
+      cwd: this.#options.cwd,
+      model: input.model ?? null,
+    };
+    const started = await this.#connection.request<QueryStartResult>(
+      "query/start",
+      params,
+    );
+    if (!started.accepted) {
+      throw new Error("SDK Host did not accept the Query");
+    }
+    return this.#trackQuery(Query.create(this.#connection, started));
+  }
+
+  close(): Promise<void> {
+    this.#closePromise ??= this.#closeOwnedResources();
+    return this.#closePromise;
+  }
+
+  async #closeOwnedResources(): Promise<void> {
+    this.#closed = true;
+    const querySettlements = await Promise.allSettled(
+      [...this.#queries].map((query) => query.close()),
+    );
+    const sessionSettlements = await Promise.allSettled(
+      [...this.#ownedSessions].map((session) => session.close()),
+    );
+    let shutdownError: unknown;
+    try {
+      await this.#connection.shutdown();
+    } catch (error) {
+      shutdownError = error;
+    }
+    const cleanupFailure = [...querySettlements, ...sessionSettlements].find(
+      (settlement): settlement is PromiseRejectedResult =>
+        settlement.status === "rejected",
+    );
+    if (cleanupFailure !== undefined) {
+      throw cleanupFailure.reason;
+    }
+    if (shutdownError !== undefined) {
+      throw shutdownError;
+    }
+  }
+
+  [Symbol.asyncDispose](): Promise<void> {
+    return this.close();
+  }
+
+  #ensureOpen(): void {
+    if (this.#closed) {
+      throw new Error("AgentClient is closed");
+    }
+  }
+
+  #trackQuery(query: Query): Query {
+    this.#queries.add(query);
+    query.onClosed(() => this.#queries.delete(query));
+    void query.result().then(
+      () => {
+        if (!query.ownsSession) {
+          this.#queries.delete(query);
+        }
+      },
+      () => this.#queries.delete(query),
+    );
+    return query;
+  }
+
+  #trackSession(session: Session): void {
+    this.#ownedSessions.add(session);
+    session.onClosed(() => this.#ownedSessions.delete(session));
+  }
+}
diff --git a/sdk/typescript/src/errors.ts b/sdk/typescript/src/errors.ts
new file mode 100644
index 0000000000..30864409bb
--- /dev/null
+++ b/sdk/typescript/src/errors.ts
@@ -0,0 +1,40 @@
+import type {
+  OutcomeCertainty,
+  RecoveryAction,
+  SdkErrorCode,
+  SdkErrorDetails,
+  SdkErrorStage,
+} from "./types.js";
+
+export class SdkError extends Error {
+  readonly code: SdkErrorCode;
+  readonly stage: SdkErrorStage;
+  readonly retryable: boolean;
+  readonly correlationId: string;
+  readonly operationId?: string;
+  readonly causationId?: string;
+  readonly outcomeCertainty: OutcomeCertainty;
+  readonly recovery?: RecoveryAction;
+
+  constructor(message: string, data: SdkErrorDetails, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "SdkError";
+    this.code = data.code;
+    this.stage = data.stage;
+    this.retryable = data.retryable;
+    this.correlationId = data.correlationId;
+    this.operationId = data.operationId ?? undefined;
+    this.causationId = data.causationId ?? undefined;
+    this.outcomeCertainty = data.outcomeCertainty;
+    this.recovery = data.recovery ?? undefined;
+  }
+}
+
+/** @internal */
+export function isConnectionUnusableError(error: unknown): error is SdkError {
+  return (
+    error instanceof SdkError &&
+    error.outcomeCertainty === "unknown" &&
+    error.recovery === "restart_host"
+  );
+}
diff --git a/sdk/typescript/src/index.ts b/sdk/typescript/src/index.ts
new file mode 100644
index 0000000000..c3d6901c6b
--- /dev/null
+++ b/sdk/typescript/src/index.ts
@@ -0,0 +1,23 @@
+export { AgentClient } from "./client.js";
+export { SdkError } from "./errors.js";
+export { Query } from "./query.js";
+export { Session, Sessions } from "./session.js";
+export type {
+  AgentCapabilities,
+  AgentClientOptions,
+  AssistantTextDelta,
+  OutcomeCertainty,
+  QueryInput,
+  QueryStreamItem,
+  RecoveryAction,
+  Result,
+  ResultError,
+  ResultStatus,
+  SdkErrorCode,
+  SdkErrorDetails,
+  SdkErrorStage,
+  SessionCreateInput,
+  SessionLifetime,
+  Turn,
+  TurnInput,
+} from "./types.js";
diff --git a/sdk/typescript/src/internal/client.ts b/sdk/typescript/src/internal/client.ts
new file mode 100644
index 0000000000..4199e3c539
--- /dev/null
+++ b/sdk/typescript/src/internal/client.ts
@@ -0,0 +1,32 @@
+import { AgentClient } from "../client.js";
+import type { AgentClientOptions } from "../types.js";
+import { JsonRpcConnection } from "./json-rpc.js";
+import type { HostTransport } from "./transport.js";
+import type { InitializeParams, InitializeResult } from "./wire/index.js";
+
+const PROTOCOL_VERSION = 1;
+const DEFAULT_INITIALIZE_TIMEOUT_MS = 30_000;
+
+export async function createAgentClient(
+  transport: HostTransport,
+  options: AgentClientOptions,
+): Promise<AgentClient> {
+  const connection = new JsonRpcConnection(transport);
+  const params: InitializeParams = {
+    protocolVersion: PROTOCOL_VERSION,
+    clientInfo: { name: "@bitfun/agent-sdk", version: "0.0.0" },
+    capabilities: { serverNotifications: true },
+  };
+  const initialized = await connection.request<InitializeResult>(
+    "initialize",
+    params,
+    options.initializeTimeoutMs ?? DEFAULT_INITIALIZE_TIMEOUT_MS,
+  );
+  if (initialized.protocolVersion !== PROTOCOL_VERSION) {
+    await connection.shutdown();
+    throw new Error(
+      `SDK Host selected protocol ${initialized.protocolVersion}; expected ${PROTOCOL_VERSION}`,
+    );
+  }
+  return AgentClient.create(connection, options, initialized);
+}
diff --git a/sdk/typescript/src/internal/deadline.ts b/sdk/typescript/src/internal/deadline.ts
new file mode 100644
index 0000000000..e59ccd2605
--- /dev/null
+++ b/sdk/typescript/src/internal/deadline.ts
@@ -0,0 +1,17 @@
+export async function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  timeoutError: () => Error,
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const expired = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => reject(timeoutError()), timeoutMs);
+  });
+  try {
+    return await Promise.race([promise, expired]);
+  } finally {
+    if (timer !== undefined) {
+      clearTimeout(timer);
+    }
+  }
+}
diff --git a/sdk/typescript/src/internal/json-rpc.ts b/sdk/typescript/src/internal/json-rpc.ts
new file mode 100644
index 0000000000..0ca19f1c51
--- /dev/null
+++ b/sdk/typescript/src/internal/json-rpc.ts
@@ -0,0 +1,307 @@
+import {
+  JsonRpcLimitError,
+  JsonRpcPeer,
+  JsonRpcProtocolError,
+  JsonRpcRemoteError,
+  JsonRpcTimeoutError,
+  JsonRpcTransportError,
+  type JsonRpcLimits,
+  type JsonRpcNotification,
+} from "../../../../src/crates/adapters/transport/typescript/src/index.js";
+
+import { SdkError } from "../errors.js";
+import type { SdkErrorStage } from "../types.js";
+import { withTimeout } from "./deadline.js";
+import type { HostTransport } from "./transport.js";
+import { HostMessageTransport } from "./transport.js";
+import {
+  isErrorData,
+  type QueryNotification,
+  validateQueryNotification,
+  validateResponseResult,
+} from "./wire-validation.js";
+
+interface QuerySubscriber {
+  notification(value: QueryNotification): void;
+  failure(error: SdkError): void;
+}
+
+interface JsonRpcConnectionOptions {
+  requestTimeoutMs?: number;
+  limits?: Partial<JsonRpcLimits>;
+}
+
+const DEFAULT_LIMITS: JsonRpcLimits = {
+  maxMessageBytes: 1024 * 1024,
+  maxPendingRequests: 128,
+  maxPendingBytes: 8 * 1024 * 1024,
+  maxOutboundBytes: 2 * 1024 * 1024,
+};
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+
+export class JsonRpcConnection {
+  readonly #peer: JsonRpcPeer;
+  readonly #queryHandlers = new Map<string, QuerySubscriber>();
+  readonly #backlog = new Map<string, QueryNotification[]>();
+  #closed = false;
+  #transportClosePromise?: Promise<void>;
+
+  constructor(
+    transport: HostTransport,
+    options: JsonRpcConnectionOptions = {},
+  ) {
+    const limits: JsonRpcLimits = {
+      ...DEFAULT_LIMITS,
+      ...options.limits,
+    };
+    let nextRequestId = 1;
+    this.#peer = new JsonRpcPeer(
+      new HostMessageTransport(transport, limits.maxMessageBytes),
+      {
+        createRequestId: () => nextRequestId++,
+        requestTimeoutMs: options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+        limits,
+        onNotificationError: (error) => {
+          this.#fail(
+            processLost("SDK Host notification violates the protocol", error),
+          );
+        },
+      },
+    );
+    this.#peer.onNotification((notification) => {
+      this.#handleNotification(notification);
+    });
+    this.#peer.onFailure((error) => {
+      this.#handlePeerFailure(error);
+    });
+  }
+
+  async request<T>(
+    method: string,
+    params: object,
+    timeoutMs?: number,
+  ): Promise<T> {
+    if (this.#closed) {
+      throw processLost("SDK Host connection is closed");
+    }
+    let result: unknown;
+    try {
+      result = await this.#peer.request(method, params, timeoutMs);
+    } catch (error) {
+      if (error instanceof JsonRpcRemoteError) {
+        if (!isErrorData(error.data)) {
+          const protocolError = processLost(
+            "SDK Host returned an invalid error contract",
+            error,
+          );
+          await this.abort(protocolError);
+          throw protocolError;
+        }
+        throw new SdkError(error.message, error.data, { cause: error });
+      }
+      if (error instanceof JsonRpcLimitError) {
+        throw requestOverloaded(method, error);
+      }
+      if (error instanceof JsonRpcTimeoutError) {
+        const timeoutError = requestTimeout(method, error);
+        await this.abort(timeoutError);
+        throw timeoutError;
+      }
+      if (
+        error instanceof JsonRpcProtocolError ||
+        error instanceof JsonRpcTransportError
+      ) {
+        throw processLost("SDK Host connection failed", error);
+      }
+      throw error;
+    }
+
+    try {
+      return validateResponseResult(method, result) as T;
+    } catch (error) {
+      const protocolError = processLost(
+        "SDK Host returned an invalid method result",
+        error,
+      );
+      await this.abort(protocolError);
+      throw protocolError;
+    }
+  }
+
+  subscribeQuery(
+    queryId: string,
+    handler: (value: QueryNotification) => void,
+    onFailure: (error: SdkError) => void,
+  ): () => void {
+    if (this.#queryHandlers.has(queryId)) {
+      throw new Error(`Query ${queryId} already has a stream owner`);
+    }
+    this.#queryHandlers.set(queryId, {
+      notification: handler,
+      failure: onFailure,
+    });
+    for (const notification of this.#backlog.get(queryId) ?? []) {
+      handler(notification);
+    }
+    this.#backlog.delete(queryId);
+    return () => {
+      this.#queryHandlers.delete(queryId);
+      this.#backlog.delete(queryId);
+    };
+  }
+
+  async shutdown(timeoutMs = 12_000): Promise<void> {
+    if (this.#closed) {
+      await this.#closeTransport();
+      return;
+    }
+    try {
+      const timeoutError = cleanupTimeout(
+        "SDK Host did not acknowledge shutdown before its cleanup deadline",
+        "shutdown",
+        "local:shutdown_timeout",
+      );
+      try {
+        await withTimeout(this.request("shutdown", {}), timeoutMs, () => timeoutError);
+      } catch (error) {
+        if (error === timeoutError) {
+          this.#fail(timeoutError);
+        }
+        throw error;
+      }
+    } finally {
+      this.#closed = true;
+      await this.#closeTransport();
+    }
+  }
+
+  /** @internal */
+  abort(error: SdkError): Promise<void> {
+    this.#fail(error);
+    return this.#closeTransport();
+  }
+
+  #handleNotification(notification: JsonRpcNotification): void {
+    if (
+      notification.method !== "query/event" &&
+      notification.method !== "query/result"
+    ) {
+      throw new Error("Unsupported SDK Host notification");
+    }
+    const validated = validateQueryNotification({
+      jsonrpc: "2.0",
+      method: notification.method,
+      params: notification.params,
+    });
+    const handler = this.#queryHandlers.get(validated.params.queryId);
+    if (handler !== undefined) {
+      handler.notification(validated);
+      return;
+    }
+    const backlog = this.#backlog.get(validated.params.queryId) ?? [];
+    if (backlog.length >= 16) {
+      throw new Error("SDK Host sent too many events before Query registration");
+    }
+    backlog.push(validated);
+    this.#backlog.set(validated.params.queryId, backlog);
+  }
+
+  #handlePeerFailure(error: Error): void {
+    if (this.#closed) {
+      return;
+    }
+    this.#fail(
+      error instanceof SdkError
+        ? error
+        : processLost("SDK Host connection was lost", error),
+    );
+  }
+
+  #fail(error: SdkError): void {
+    if (this.#closed) {
+      return;
+    }
+    this.#closed = true;
+    for (const subscriber of this.#queryHandlers.values()) {
+      subscriber.failure(error);
+    }
+    this.#queryHandlers.clear();
+    this.#backlog.clear();
+    void this.#peer.abort(error);
+  }
+
+  #closeTransport(): Promise<void> {
+    this.#transportClosePromise ??= this.#peer.close();
+    return this.#transportClosePromise;
+  }
+}
+
+function requestStage(method: string): SdkErrorStage {
+  if (method === "initialize") {
+    return "initialize";
+  }
+  if (method.startsWith("query/")) {
+    return "query";
+  }
+  if (method.startsWith("session/")) {
+    return "session";
+  }
+  if (method === "shutdown") {
+    return "shutdown";
+  }
+  return "protocol";
+}
+
+function requestOverloaded(method: string, cause: JsonRpcLimitError): SdkError {
+  return new SdkError(
+    "SDK Host request capacity was exceeded before the request was sent",
+    {
+      code: "overloaded",
+      stage: requestStage(method),
+      retryable: true,
+      correlationId: `local:${cause.limit}`,
+      outcomeCertainty: "not_started",
+    },
+    { cause },
+  );
+}
+
+function requestTimeout(method: string, cause: JsonRpcTimeoutError): SdkError {
+  return new SdkError(`SDK Host request timed out: ${method}`, {
+    code: "timeout",
+    stage: requestStage(method),
+    retryable: false,
+    correlationId: `local:request_timeout:${String(cause.id)}`,
+    outcomeCertainty: "unknown",
+    recovery: "restart_host",
+  }, { cause });
+}
+
+function processLost(message: string, cause?: unknown): SdkError {
+  return new SdkError(message, {
+    code: "process_lost",
+    stage: "protocol",
+    retryable: false,
+    correlationId: "local:process_lost",
+    outcomeCertainty: "unknown",
+    recovery: "restart_host",
+  }, cause === undefined ? undefined : { cause });
+}
+
+function cleanupTimeout(
+  message: string,
+  stage: "query" | "session" | "shutdown",
+  correlationId: string,
+  operationId?: string,
+): SdkError {
+  return new SdkError(message, {
+    code: "cleanup_required",
+    stage,
+    retryable: false,
+    correlationId,
+    operationId,
+    outcomeCertainty: "unknown",
+    recovery: "restart_host",
+  });
+}
diff --git a/sdk/typescript/src/internal/managed-host.ts b/sdk/typescript/src/internal/managed-host.ts
new file mode 100644
index 0000000000..78b5f40a4e
--- /dev/null
+++ b/sdk/typescript/src/internal/managed-host.ts
@@ -0,0 +1,222 @@
+import { spawn } from "node:child_process";
+
+import { SdkError } from "../errors.js";
+import type { HostTransport } from "./transport.js";
+
+export interface ManagedHostOptions {
+  executable: string;
+  args?: readonly string[];
+  cwd: string;
+  gracefulShutdownMs?: number;
+  forceKillTimeoutMs?: number;
+}
+
+export interface ManagedHostTransport extends HostTransport {
+  exitCode(): number | null;
+  hasExited(): boolean;
+}
+
+export async function startManagedHost(
+  options: ManagedHostOptions,
+): Promise<ManagedHostTransport> {
+  const child = spawn(options.executable, [...(options.args ?? [])], {
+    cwd: options.cwd,
+    env: process.env,
+    shell: false,
+    detached: process.platform !== "win32",
+    stdio: ["pipe", "pipe", "pipe"],
+    windowsHide: true,
+  });
+
+  child.stderr.setEncoding("utf8");
+  child.stderr.on("data", () => {
+    // Drain diagnostics so a verbose Host cannot block on a full stderr pipe.
+  });
+
+  try {
+    await new Promise<void>((resolve, reject) => {
+      const onSpawn = (): void => {
+        child.off("error", onError);
+        resolve();
+      };
+      const onError = (error: Error): void => {
+        child.off("spawn", onSpawn);
+        reject(error);
+      };
+      child.once("spawn", onSpawn);
+      child.once("error", onError);
+    });
+  } catch (cause) {
+    throw hostStartError(options.executable, cause);
+  }
+
+  child.on("error", (error) => {
+    child.stdout.destroy(error);
+  });
+
+  let observedExitCode: number | null = null;
+  let exitObserved = false;
+  const exited = new Promise<void>((resolve) => {
+    child.once("exit", (code) => {
+      observedExitCode = code;
+      exitObserved = true;
+      resolve();
+    });
+  });
+  let closePromise: Promise<void> | undefined;
+
+  return {
+    readable: child.stdout,
+    writable: child.stdin,
+    close: () => {
+      closePromise ??= closeChild();
+      return closePromise;
+    },
+    exitCode: () => observedExitCode ?? child.exitCode,
+    hasExited: () => exitObserved,
+  };
+
+  async function closeChild(): Promise<void> {
+    child.stdin.end();
+    const gracefulExit = await settlesWithin(
+      exited,
+      options.gracefulShutdownMs ?? 5_000,
+    );
+    const forceKillTimeoutMs = options.forceKillTimeoutMs ?? 2_000;
+    if (process.platform !== "win32") {
+      await forceKillTree(child.pid, forceKillTimeoutMs);
+      if (!gracefulExit && !(await settlesWithin(exited, forceKillTimeoutMs))) {
+        throw processTreeCleanupError("direct Host exit was not observed");
+      }
+      return;
+    }
+    if (gracefulExit) {
+      return;
+    }
+    await forceKillTree(child.pid, forceKillTimeoutMs);
+    if (!(await settlesWithin(exited, forceKillTimeoutMs))) {
+      throw new SdkError("SDK Host process tree could not be reclaimed", {
+        code: "cleanup_required",
+        stage: "shutdown",
+        retryable: false,
+        correlationId: "local:host_process_tree",
+        outcomeCertainty: "unknown",
+        recovery: "restart_host",
+      });
+    }
+  }
+}
+
+/** @internal */
+export async function forceKillTree(
+  pid: number | undefined,
+  timeoutMs: number,
+): Promise<void> {
+  if (pid === undefined) {
+    throw new SdkError("SDK Host process id is unavailable during cleanup", {
+      code: "cleanup_required",
+      stage: "shutdown",
+      retryable: false,
+      correlationId: "local:host_process_tree",
+      outcomeCertainty: "unknown",
+      recovery: "restart_host",
+    });
+  }
+  if (process.platform !== "win32") {
+    try {
+      process.kill(-pid, "SIGKILL");
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ESRCH") {
+        throw error;
+      }
+    }
+    if (!(await processGroupExited(pid, timeoutMs))) {
+      throw processTreeCleanupError("Unix process group remained alive after SIGKILL");
+    }
+    return;
+  }
+
+  const taskkill = spawn("taskkill.exe", ["/pid", String(pid), "/t", "/f"], {
+    shell: false,
+    stdio: "ignore",
+    windowsHide: true,
+  });
+  const completed = new Promise<void>((resolve, reject) => {
+    taskkill.once("error", reject);
+    taskkill.once("exit", (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(processTreeCleanupError(`taskkill exited with status ${String(code)}`));
+      }
+    });
+  });
+  if (!(await settlesWithin(completed, timeoutMs))) {
+    taskkill.kill();
+    throw new SdkError("Timed out while terminating the SDK Host process tree", {
+      code: "cleanup_required",
+      stage: "shutdown",
+      retryable: false,
+      correlationId: "local:host_process_tree",
+      outcomeCertainty: "unknown",
+      recovery: "restart_host",
+    });
+  }
+}
+
+async function processGroupExited(pid: number, timeoutMs: number): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  do {
+    try {
+      process.kill(-pid, 0);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ESRCH") {
+        return true;
+      }
+      throw error;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 20));
+  } while (Date.now() < deadline);
+  return false;
+}
+
+function processTreeCleanupError(message: string): SdkError {
+  return new SdkError(`SDK Host process tree could not be reclaimed: ${message}`, {
+    code: "cleanup_required",
+    stage: "shutdown",
+    retryable: false,
+    correlationId: "local:host_process_tree",
+    outcomeCertainty: "unknown",
+    recovery: "restart_host",
+  });
+}
+
+async function settlesWithin(
+  promise: Promise<void>,
+  timeoutMs: number,
+): Promise<boolean> {
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  const timedOut = new Promise<false>((resolve) => {
+    timeout = setTimeout(() => resolve(false), timeoutMs);
+  });
+  const settled = promise.then(() => true as const);
+  const result = await Promise.race([settled, timedOut]);
+  if (timeout !== undefined) {
+    clearTimeout(timeout);
+  }
+  return result;
+}
+
+function hostStartError(executable: string, cause: unknown): SdkError {
+  return new SdkError(
+    `SDK Host executable was not found: ${executable}`,
+    {
+      code: "not_found",
+      stage: "initialize",
+      retryable: false,
+      correlationId: "local:host_start",
+      outcomeCertainty: "not_started",
+    },
+    { cause },
+  );
+}
diff --git a/sdk/typescript/src/internal/transport.ts b/sdk/typescript/src/internal/transport.ts
new file mode 100644
index 0000000000..125988b342
--- /dev/null
+++ b/sdk/typescript/src/internal/transport.ts
@@ -0,0 +1,113 @@
+import type { Readable, Writable } from "node:stream";
+import { StringDecoder } from "node:string_decoder";
+
+import type {
+  MessageTransport,
+  MessageTransportObserver,
+} from "../../../../src/crates/adapters/transport/typescript/src/index.js";
+
+export interface HostTransport {
+  readable: Readable;
+  writable: Writable;
+  close(): Promise<void>;
+}
+
+/** SDK-owned newline framing over a managed Host's stdio carrier. */
+export class HostMessageTransport implements MessageTransport {
+  readonly #host: HostTransport;
+  readonly #maxLineBytes: number;
+  #observer?: MessageTransportObserver;
+  #closePromise?: Promise<void>;
+
+  constructor(host: HostTransport, maxLineBytes: number) {
+    this.#host = host;
+    this.#maxLineBytes = maxLineBytes;
+  }
+
+  subscribe(observer: MessageTransportObserver): () => void {
+    if (this.#observer !== undefined) {
+      throw new Error("SDK Host transport already has a message owner");
+    }
+    this.#observer = observer;
+    void this.#readLoop(observer);
+    return () => {
+      if (this.#observer === observer) {
+        this.#observer = undefined;
+      }
+    };
+  }
+
+  send(message: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+      try {
+        this.#host.writable.write(`${message}\n`, (error) => {
+          if (error !== null && error !== undefined) {
+            reject(error);
+          } else {
+            resolve();
+          }
+        });
+      } catch (error) {
+        reject(error);
+      }
+    });
+  }
+
+  close(): Promise<void> {
+    this.#closePromise ??= this.#host.close();
+    return this.#closePromise;
+  }
+
+  async #readLoop(observer: MessageTransportObserver): Promise<void> {
+    try {
+      for await (const line of readBoundedLines(
+        this.#host.readable,
+        this.#maxLineBytes,
+      )) {
+        if (this.#observer !== observer) {
+          return;
+        }
+        observer.message(line);
+      }
+      if (this.#observer === observer) {
+        observer.close(new Error("SDK Host closed its output stream"));
+      }
+    } catch (error) {
+      if (this.#observer === observer) {
+        observer.close(error);
+      }
+    }
+  }
+}
+
+async function* readBoundedLines(
+  readable: Readable,
+  maxLineBytes: number,
+): AsyncGenerator<string> {
+  const decoder = new StringDecoder("utf8");
+  let buffered = "";
+  for await (const chunk of readable) {
+    buffered +=
+      typeof chunk === "string" ? chunk : decoder.write(chunk as Buffer);
+    let newline = buffered.indexOf("\n");
+    while (newline >= 0) {
+      let line = buffered.slice(0, newline);
+      buffered = buffered.slice(newline + 1);
+      if (Buffer.byteLength(line, "utf8") > maxLineBytes) {
+        throw new Error("SDK Host response line exceeds the size limit");
+      }
+      if (line.endsWith("\r")) {
+        line = line.slice(0, -1);
+      }
+      yield line;
+      newline = buffered.indexOf("\n");
+    }
+    if (Buffer.byteLength(buffered, "utf8") > maxLineBytes) {
+      throw new Error("SDK Host response line exceeds the size limit");
+    }
+  }
+  buffered += decoder.end();
+  if (buffered.length > 0) {
+    throw new Error("SDK Host output ended with an unterminated response line");
+  }
+}
diff --git a/sdk/typescript/src/internal/wire-validation.ts b/sdk/typescript/src/internal/wire-validation.ts
new file mode 100644
index 0000000000..7b390f41dc
--- /dev/null
+++ b/sdk/typescript/src/internal/wire-validation.ts
@@ -0,0 +1,219 @@
+import type {
+  ErrorData,
+  InitializeResult,
+  QueryCancelResult,
+  QueryEventParams,
+  QueryResultParams,
+  QueryStartResult,
+  SessionCloseResult,
+  SessionCreateResult,
+  ShutdownResult,
+} from "./wire/index.js";
+import {
+  isErrorData as isGeneratedErrorData,
+  isInitializeResult,
+  isQueryCancelResult,
+  isQueryEventParams,
+  isQueryResultParams,
+  isQueryStartResult,
+  isSessionCloseResult,
+  isSessionCreateResult,
+  isShutdownResult,
+} from "./wire-validators.js";
+
+// Rust protocol types own field names, shapes, and enum values through the
+// generated validators. This module keeps only SDK envelope and semantic rules
+// that TypeScript types cannot express.
+
+export type QueryNotification =
+  | { jsonrpc: "2.0"; method: "query/event"; params: QueryEventParams }
+  | { jsonrpc: "2.0"; method: "query/result"; params: QueryResultParams };
+
+export function validateResponseResult<T>(method: string, value: unknown): T {
+  switch (method) {
+    case "initialize":
+      return validateInitializeResult(value) as T;
+    case "session/create":
+      return validateSessionCreateResult(value) as T;
+    case "query/start":
+      return validateQueryStartResult(value) as T;
+    case "query/cancel":
+      return validateQueryCancelResult(value) as T;
+    case "session/close":
+      return validateSessionCloseResult(value) as T;
+    case "shutdown":
+      return validateWireValue(isShutdownResult, value, "shutdown result") as T;
+    default:
+      throw new Error(`SDK Host returned a result for unknown method ${method}`);
+  }
+}
+
+export function validateQueryNotification(value: unknown): QueryNotification {
+  assertRecord(value, "Query notification");
+  assertOnlyKeys(value, ["jsonrpc", "method", "params"], "Query notification");
+  if (value.jsonrpc !== "2.0") {
+    throw new Error("Query notification has an invalid JSON-RPC version");
+  }
+  if (value.method === "query/event") {
+    return {
+      jsonrpc: "2.0",
+      method: "query/event",
+      params: validateQueryEventParams(value.params),
+    };
+  }
+  if (value.method === "query/result") {
+    return {
+      jsonrpc: "2.0",
+      method: "query/result",
+      params: validateQueryResultParams(value.params),
+    };
+  }
+  throw new Error("SDK Host notification method is unsupported");
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function hasOnlyKeys(
+  value: Record<string, unknown>,
+  allowed: readonly string[],
+): boolean {
+  const keys = Object.keys(value);
+  return keys.length <= allowed.length && keys.every((key) => allowed.includes(key));
+}
+
+export function isErrorData(value: unknown): value is ErrorData {
+  return isGeneratedErrorData(value);
+}
+
+function validateInitializeResult(value: unknown): InitializeResult {
+  const result = validateWireValue(
+    isInitializeResult,
+    value,
+    "initialize result",
+  );
+  if (!Number.isSafeInteger(result.protocolVersion)) {
+    throw new Error("SDK Host initialize protocol version is invalid");
+  }
+  return result;
+}
+
+function validateSessionCreateResult(value: unknown): SessionCreateResult {
+  const result = validateWireValue(
+    isSessionCreateResult,
+    value,
+    "Session create result",
+  );
+  if (!isNonEmptyString(result.sessionId)) {
+    throw new Error("SDK Host Session create identity is invalid");
+  }
+  return result;
+}
+
+function validateQueryStartResult(value: unknown): QueryStartResult {
+  const result = validateWireValue(isQueryStartResult, value, "Query start result");
+  if (!hasQueryIdentity(result)) {
+    throw new Error("SDK Host Query start identity is invalid");
+  }
+  return result;
+}
+
+function validateQueryCancelResult(value: unknown): QueryCancelResult {
+  const result = validateWireValue(
+    isQueryCancelResult,
+    value,
+    "Query cancel result",
+  );
+  if (!hasQueryIdentity(result)) {
+    throw new Error("SDK Host Query cancel identity is invalid");
+  }
+  return result;
+}
+
+function validateSessionCloseResult(value: unknown): SessionCloseResult {
+  const result = validateWireValue(
+    isSessionCloseResult,
+    value,
+    "Session close result",
+  );
+  if (!isNonEmptyString(result.sessionId)) {
+    throw new Error("SDK Host Session close identity is invalid");
+  }
+  return result;
+}
+
+function validateQueryEventParams(value: unknown): QueryEventParams {
+  const params = validateWireValue(isQueryEventParams, value, "Query event params");
+  if (
+    !hasQueryIdentity(params) ||
+    !Number.isSafeInteger(params.sequence) ||
+    params.sequence < 1
+  ) {
+    throw new Error("SDK Host Query event identity or sequence is invalid");
+  }
+  return params;
+}
+
+function validateQueryResultParams(value: unknown): QueryResultParams {
+  const params = validateWireValue(
+    isQueryResultParams,
+    value,
+    "Query result params",
+  );
+  if (!hasQueryIdentity(params)) {
+    throw new Error("SDK Host Query result identity is invalid");
+  }
+  if (params.status === "completed" && params.error !== undefined) {
+    throw new Error("A completed SDK Host Query Result cannot contain an error");
+  }
+  return params;
+}
+
+function validateWireValue<T>(
+  validator: (value: unknown) => value is T,
+  value: unknown,
+  label: string,
+): T {
+  if (!validator(value)) {
+    throw new Error(`${label} does not match the generated Rust wire contract`);
+  }
+  return value;
+}
+
+function hasQueryIdentity(value: {
+  queryId: string;
+  sessionId: string;
+  turnId: string;
+  operationId: string;
+}): boolean {
+  return (
+    isNonEmptyString(value.queryId) &&
+    isNonEmptyString(value.sessionId) &&
+    isNonEmptyString(value.turnId) &&
+    isNonEmptyString(value.operationId)
+  );
+}
+
+function assertRecord(
+  value: unknown,
+  label: string,
+): asserts value is Record<string, unknown> {
+  if (!isRecord(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+}
+
+function assertOnlyKeys(
+  value: Record<string, unknown>,
+  allowed: readonly string[],
+  label: string,
+): void {
+  if (!hasOnlyKeys(value, allowed)) {
+    throw new Error(`${label} contains unknown fields`);
+  }
+}
+
+function isNonEmptyString(value: string): boolean {
+  return value.length > 0;
+}
diff --git a/sdk/typescript/src/query.ts b/sdk/typescript/src/query.ts
new file mode 100644
index 0000000000..2fbe466c51
--- /dev/null
+++ b/sdk/typescript/src/query.ts
@@ -0,0 +1,364 @@
+import type { JsonRpcConnection } from "./internal/json-rpc.js";
+import { withTimeout } from "./internal/deadline.js";
+import type {
+  QueryCancelParams,
+  QueryCancelResult,
+  QueryEventParams,
+  QueryResultParams,
+  QueryStartResult,
+  SessionCloseParams,
+  SessionCloseResult,
+} from "./internal/wire/index.js";
+import type { QueryStreamItem, Result, ResultError, Turn } from "./types.js";
+import { isConnectionUnusableError, SdkError } from "./errors.js";
+
+interface QueueWaiter {
+  resolve(value: IteratorResult<QueryStreamItem>): void;
+  reject(error: Error): void;
+}
+
+const MAX_BUFFERED_ITEMS = 1_024;
+const MAX_BUFFERED_EVENT_BYTES = 1024 * 1024;
+
+export class Query implements AsyncIterable<QueryStreamItem> {
+  readonly #connection: JsonRpcConnection;
+  readonly id: string;
+  readonly operationId: string;
+  readonly turn: Turn;
+  readonly #items: QueryStreamItem[] = [];
+  readonly #waiters: QueueWaiter[] = [];
+  readonly #resultPromise: Promise<Result>;
+  readonly #resolveResult: (result: Result) => void;
+  readonly #rejectResult: (error: Error) => void;
+  readonly #ownsSession: boolean;
+  readonly #closeTimeoutMs: number;
+  readonly #closedHandlers = new Set<() => void>();
+  #lastSequence = 0;
+  #terminal = false;
+  #unsubscribe: () => void = () => {};
+  #cancelPromise?: Promise<void>;
+  #closePromise?: Promise<void>;
+  #failure?: Error;
+  #closed = false;
+  #bufferedBytes = 0;
+
+  /** @internal */
+  static create(
+    connection: JsonRpcConnection,
+    started: QueryStartResult,
+    closeTimeoutMs = 7_000,
+  ): Query {
+    return new Query(connection, started, closeTimeoutMs);
+  }
+
+  private constructor(
+    connection: JsonRpcConnection,
+    started: QueryStartResult,
+    closeTimeoutMs: number,
+  ) {
+    this.#connection = connection;
+    this.id = started.queryId;
+    this.operationId = started.operationId;
+    this.#ownsSession = started.createdSession;
+    this.#closeTimeoutMs = closeTimeoutMs;
+    this.turn = Object.freeze({
+      id: started.turnId,
+      sessionId: started.sessionId,
+    });
+    let resolveResult!: (result: Result) => void;
+    let rejectResult!: (error: Error) => void;
+    this.#resultPromise = new Promise((resolve, reject) => {
+      resolveResult = resolve;
+      rejectResult = reject;
+    });
+    this.#resolveResult = resolveResult;
+    this.#rejectResult = rejectResult;
+    this.#unsubscribe = connection.subscribeQuery(
+      this.id,
+      (notification) => {
+        if (notification.method === "query/event") {
+          this.#onEvent(notification.params);
+        } else {
+          this.#onResult(notification.params);
+        }
+      },
+      (error) => this.#onConnectionFailure(error),
+    );
+    if (this.#terminal) {
+      this.#unsubscribe();
+    }
+  }
+
+  result(): Promise<Result> {
+    return this.#resultPromise;
+  }
+
+  cancel(): Promise<void> {
+    if (this.#terminal) {
+      return Promise.resolve();
+    }
+    this.#cancelPromise ??= this.#requestCancel();
+    return this.#cancelPromise;
+  }
+
+  close(): Promise<void> {
+    this.#closePromise ??= this.#closeQuery();
+    return this.#closePromise;
+  }
+
+  /** @internal */
+  get ownsSession(): boolean {
+    return this.#ownsSession;
+  }
+
+  /** @internal */
+  onClosed(handler: () => void): void {
+    this.#closedHandlers.add(handler);
+  }
+
+  [Symbol.asyncDispose](): Promise<void> {
+    return this.close();
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<QueryStreamItem> {
+    return {
+      next: () => this.#next(),
+      return: async () => {
+        await this.close();
+        return { done: true, value: undefined };
+      },
+    };
+  }
+
+  #onEvent(params: QueryEventParams): void {
+    this.#assertIdentity(
+      params.queryId,
+      params.sessionId,
+      params.turnId,
+      params.operationId,
+    );
+    if (this.#terminal || params.sequence !== this.#lastSequence + 1) {
+      throw new Error("SDK Host Query event ordering is invalid");
+    }
+    this.#lastSequence = params.sequence;
+    if (params.event.type === "assistant_text_delta") {
+      this.#push({
+        type: "assistant_text_delta",
+        queryId: params.queryId,
+        sessionId: params.sessionId,
+        turnId: params.turnId,
+        operationId: params.operationId,
+        sequence: params.sequence,
+        text: params.event.text,
+      });
+    }
+  }
+
+  async #requestCancel(): Promise<void> {
+    const params: QueryCancelParams = {
+      queryId: this.id,
+      sessionId: this.turn.sessionId,
+      turnId: this.turn.id,
+      operationId: this.operationId,
+    };
+    const cancelled = await this.#connection.request<QueryCancelResult>(
+      "query/cancel",
+      params,
+    );
+    if (
+      cancelled.queryId !== this.id ||
+      cancelled.sessionId !== this.turn.sessionId ||
+      cancelled.turnId !== this.turn.id ||
+      cancelled.operationId !== this.operationId
+    ) {
+      throw new Error("SDK Host returned a different Query from cancellation");
+    }
+  }
+
+  async #closeQuery(): Promise<void> {
+    const timeoutError = new SdkError(
+      "SDK Host did not settle Query cleanup before its deadline",
+      {
+        code: "cleanup_required",
+        stage: "query",
+        retryable: false,
+        correlationId: `query:${this.id}`,
+        operationId: this.operationId,
+        outcomeCertainty: "unknown",
+        recovery: "restart_host",
+      },
+    );
+    try {
+      await withTimeout(
+        this.#closeWithinProtocol(),
+        this.#closeTimeoutMs,
+        () => timeoutError,
+      );
+    } catch (error) {
+      if (isConnectionUnusableError(error)) {
+        await this.#connection.abort(error);
+      }
+      throw error;
+    }
+    this.#markClosed();
+  }
+
+  async #closeWithinProtocol(): Promise<void> {
+    if (!this.#terminal) {
+      await this.cancel();
+    }
+    await this.#resultPromise;
+    if (this.#ownsSession) {
+      const params: SessionCloseParams = { sessionId: this.turn.sessionId };
+      const closed = await this.#connection.request<SessionCloseResult>(
+        "session/close",
+        params,
+      );
+      if (closed.sessionId !== this.turn.sessionId) {
+        throw new Error("SDK Host closed a different transient Session");
+      }
+    }
+  }
+
+  #onResult(params: QueryResultParams): void {
+    this.#assertIdentity(
+      params.queryId,
+      params.sessionId,
+      params.turnId,
+      params.operationId,
+    );
+    if (this.#terminal) {
+      throw new Error("SDK Host emitted more than one terminal Result");
+    }
+    const result: Result = {
+      type: "result",
+      queryId: params.queryId,
+      sessionId: params.sessionId,
+      turnId: params.turnId,
+      operationId: params.operationId,
+      status: params.status,
+      outputText: params.output.text,
+      ...(params.error === undefined ? {} : { error: mapResultError(params.error) }),
+    };
+    if (!this.#push(result)) {
+      return;
+    }
+    this.#terminal = true;
+    this.#resolveResult(result);
+    this.#unsubscribe();
+    while (this.#waiters.length > 0) {
+      this.#waiters.shift()?.resolve({ done: true, value: undefined });
+    }
+  }
+
+  #assertIdentity(
+    queryId: string,
+    sessionId: string,
+    turnId: string,
+    operationId: string,
+  ): void {
+    if (
+      queryId !== this.id ||
+      sessionId !== this.turn.sessionId ||
+      turnId !== this.turn.id ||
+      operationId !== this.operationId
+    ) {
+      throw new Error("SDK Host Query identity changed during streaming");
+    }
+  }
+
+  #push(item: QueryStreamItem): boolean {
+    const waiter = this.#waiters.shift();
+    if (waiter !== undefined) {
+      waiter.resolve({ done: false, value: item });
+      return true;
+    }
+    const itemBytes = bufferedItemBytes(item);
+    if (
+      this.#items.length >= MAX_BUFFERED_ITEMS ||
+      this.#bufferedBytes + itemBytes > MAX_BUFFERED_EVENT_BYTES
+    ) {
+      const error = new SdkError("SDK Host Query event buffer capacity was exceeded", {
+        code: "overloaded",
+        stage: "query",
+        retryable: false,
+        correlationId: `query:${this.id}`,
+        operationId: this.operationId,
+        outcomeCertainty: "unknown",
+        recovery: "restart_host",
+      });
+      void this.#connection.abort(error);
+      return false;
+    }
+    this.#items.push(item);
+    this.#bufferedBytes += itemBytes;
+    return true;
+  }
+
+  #next(): Promise<IteratorResult<QueryStreamItem>> {
+    const item = this.#items.shift();
+    if (item !== undefined) {
+      this.#bufferedBytes -= bufferedItemBytes(item);
+      return Promise.resolve({ done: false, value: item });
+    }
+    if (this.#failure !== undefined) {
+      return Promise.reject(this.#failure);
+    }
+    if (this.#terminal) {
+      return Promise.resolve({ done: true, value: undefined });
+    }
+    return new Promise((resolve, reject) => {
+      this.#waiters.push({ resolve, reject });
+    });
+  }
+
+  #onConnectionFailure(error: SdkError): void {
+    if (this.#terminal) {
+      return;
+    }
+    this.#terminal = true;
+    this.#failure = error;
+    this.#rejectResult(error);
+    this.#unsubscribe();
+    while (this.#waiters.length > 0) {
+      this.#waiters.shift()?.reject(error);
+    }
+  }
+
+  #markClosed(): void {
+    if (this.#closed) {
+      return;
+    }
+    this.#closed = true;
+    for (const handler of this.#closedHandlers) {
+      handler();
+    }
+    this.#closedHandlers.clear();
+  }
+}
+
+function bufferedItemBytes(item: QueryStreamItem): number {
+  // Result frames have their own connection-level frame bound. Counting their
+  // aggregate output again against the event backlog would reject a valid
+  // Query that has not consumed the same text deltas yet.
+  return item.type === "assistant_text_delta"
+    ? Buffer.byteLength(item.text, "utf8") + 256
+    : 0;
+}
+
+function mapResultError(error: QueryResultParams["error"]): ResultError {
+  if (error === undefined) {
+    throw new Error("Result error is unavailable");
+  }
+  return {
+    message: error.message,
+    code: error.data.code,
+    stage: error.data.stage,
+    retryable: error.data.retryable,
+    correlationId: error.data.correlationId,
+    operationId: error.data.operationId ?? undefined,
+    causationId: error.data.causationId ?? undefined,
+    outcomeCertainty: error.data.outcomeCertainty,
+    recovery: error.data.recovery ?? undefined,
+  };
+}
diff --git a/sdk/typescript/src/session.ts b/sdk/typescript/src/session.ts
new file mode 100644
index 0000000000..c6b865e9b7
--- /dev/null
+++ b/sdk/typescript/src/session.ts
@@ -0,0 +1,177 @@
+import type {
+  QueryStartParams,
+  QueryStartResult,
+  SessionCloseParams,
+  SessionCreateParams,
+  SessionCreateResult,
+} from "./internal/wire/index.js";
+import type { JsonRpcConnection } from "./internal/json-rpc.js";
+import { withTimeout } from "./internal/deadline.js";
+import { isConnectionUnusableError, SdkError } from "./errors.js";
+import { Query } from "./query.js";
+import type { SessionCreateInput, SessionLifetime, TurnInput } from "./types.js";
+
+export class Sessions {
+  readonly #connection: JsonRpcConnection;
+  readonly #cwd: string;
+  readonly #onQuery: (query: Query) => Query;
+  readonly #onSession: (session: Session) => void;
+  readonly #ensureClientOpen: () => void;
+
+  /** @internal */
+  static forClient(
+    connection: JsonRpcConnection,
+    cwd: string,
+    onQuery: (query: Query) => Query,
+    onSession: (session: Session) => void,
+    ensureClientOpen: () => void,
+  ): Sessions {
+    return new Sessions(
+      connection,
+      cwd,
+      onQuery,
+      onSession,
+      ensureClientOpen,
+    );
+  }
+
+  private constructor(
+    connection: JsonRpcConnection,
+    cwd: string,
+    onQuery: (query: Query) => Query,
+    onSession: (session: Session) => void,
+    ensureClientOpen: () => void,
+  ) {
+    this.#connection = connection;
+    this.#cwd = cwd;
+    this.#onQuery = onQuery;
+    this.#onSession = onSession;
+    this.#ensureClientOpen = ensureClientOpen;
+  }
+
+  async create(input: SessionCreateInput = {}): Promise<Session> {
+    this.#ensureClientOpen();
+    const params: SessionCreateParams = {
+      sessionName: input.sessionName ?? null,
+      agent: input.agent ?? null,
+      cwd: this.#cwd,
+      model: input.model ?? null,
+    };
+    const created = await this.#connection.request<SessionCreateResult>(
+      "session/create",
+      params,
+    );
+    const session = Session.create(this.#connection, created, this.#onQuery);
+    this.#onSession(session);
+    return session;
+  }
+}
+
+export class Session {
+  readonly #connection: JsonRpcConnection;
+  readonly id: string;
+  readonly name: string;
+  readonly agent: string;
+  readonly lifetime: SessionLifetime;
+  readonly workspacePath?: string;
+  readonly #onQuery: (query: Query) => Query;
+  readonly #closeTimeoutMs: number;
+  readonly #closedHandlers = new Set<() => void>();
+  #closed = false;
+  #closePromise?: Promise<void>;
+
+  /** @internal */
+  static create(
+    connection: JsonRpcConnection,
+    created: SessionCreateResult,
+    onQuery: (query: Query) => Query,
+    closeTimeoutMs = 7_000,
+  ): Session {
+    return new Session(connection, created, onQuery, closeTimeoutMs);
+  }
+
+  private constructor(
+    connection: JsonRpcConnection,
+    created: SessionCreateResult,
+    onQuery: (query: Query) => Query,
+    closeTimeoutMs: number,
+  ) {
+    this.#connection = connection;
+    this.id = created.sessionId;
+    this.name = created.sessionName;
+    this.agent = created.agent;
+    this.lifetime = created.lifetime;
+    this.workspacePath = created.workspacePath;
+    this.#onQuery = onQuery;
+    this.#closeTimeoutMs = closeTimeoutMs;
+  }
+
+  async startTurn(input: TurnInput): Promise<Query> {
+    this.#ensureOpen();
+    const params: QueryStartParams = {
+      prompt: input.prompt,
+      sessionId: this.id,
+    };
+    const started = await this.#connection.request<QueryStartResult>(
+      "query/start",
+      params,
+    );
+    if (!started.accepted || started.sessionId !== this.id) {
+      throw new Error("SDK Host did not accept the Turn for this Session");
+    }
+    return this.#onQuery(Query.create(this.#connection, started));
+  }
+
+  close(): Promise<void> {
+    this.#closePromise ??= this.#closeSession();
+    return this.#closePromise;
+  }
+
+  /** @internal */
+  onClosed(handler: () => void): void {
+    this.#closedHandlers.add(handler);
+  }
+
+  async #closeSession(): Promise<void> {
+    this.#closed = true;
+    const params: SessionCloseParams = { sessionId: this.id };
+    const timeoutError = new SdkError(
+      "SDK Host did not close Session before its cleanup deadline",
+      {
+        code: "cleanup_required",
+        stage: "session",
+        retryable: false,
+        correlationId: `session:${this.id}`,
+        outcomeCertainty: "unknown",
+        recovery: "restart_host",
+      },
+    );
+    try {
+      await withTimeout(
+        this.#connection.request("session/close", params),
+        this.#closeTimeoutMs,
+        () => timeoutError,
+      );
+    } catch (error) {
+      if (isConnectionUnusableError(error)) {
+        await this.#connection.abort(error);
+      }
+      throw error;
+    } finally {
+      for (const handler of this.#closedHandlers) {
+        handler();
+      }
+      this.#closedHandlers.clear();
+    }
+  }
+
+  [Symbol.asyncDispose](): Promise<void> {
+    return this.close();
+  }
+
+  #ensureOpen(): void {
+    if (this.#closed) {
+      throw new Error("Session is closed");
+    }
+  }
+}
diff --git a/sdk/typescript/src/types.ts b/sdk/typescript/src/types.ts
new file mode 100644
index 0000000000..cd460482c4
--- /dev/null
+++ b/sdk/typescript/src/types.ts
@@ -0,0 +1,114 @@
+export interface AgentClientOptions {
+  cwd: string;
+  /** Native `bitfun-sdk-host` path. Platform packages will provide this later. */
+  hostPath?: string;
+  /** Deadline for the SDK Host initialize handshake. */
+  initializeTimeoutMs?: number;
+}
+
+export interface AgentCapabilities {
+  query: boolean;
+  sessions: boolean;
+  cancellation: boolean;
+}
+
+export type SdkErrorCode =
+  | "invalid_request"
+  | "not_initialized"
+  | "already_initialized"
+  | "version_mismatch"
+  | "capability_unavailable"
+  | "not_found"
+  | "permission_denied"
+  | "action_required"
+  | "authentication"
+  | "rate_limited"
+  | "provider_quota"
+  | "provider_billing"
+  | "provider_unavailable"
+  | "context_overflow"
+  | "content_policy"
+  | "overloaded"
+  | "timeout"
+  | "cancelled"
+  | "process_lost"
+  | "cleanup_required"
+  | "internal";
+
+export type SdkErrorStage =
+  | "protocol"
+  | "initialize"
+  | "session"
+  | "query"
+  | "shutdown";
+
+export type OutcomeCertainty = "not_started" | "committed" | "unknown";
+
+export type RecoveryAction =
+  | "initialize"
+  | "retry"
+  | "update_sdk"
+  | "restart_host";
+
+export interface SdkErrorDetails {
+  code: SdkErrorCode;
+  stage: SdkErrorStage;
+  retryable: boolean;
+  correlationId: string;
+  operationId?: string;
+  causationId?: string;
+  outcomeCertainty: OutcomeCertainty;
+  recovery?: RecoveryAction;
+}
+
+export type SessionLifetime = "connection";
+
+export interface QueryInput {
+  prompt: string;
+  agent?: string;
+  model?: string;
+}
+
+export interface SessionCreateInput {
+  sessionName?: string;
+  agent?: string;
+  model?: string;
+}
+
+export interface TurnInput {
+  prompt: string;
+}
+
+export interface Turn {
+  readonly id: string;
+  readonly sessionId: string;
+}
+
+export interface AssistantTextDelta {
+  type: "assistant_text_delta";
+  queryId: string;
+  sessionId: string;
+  turnId: string;
+  operationId: string;
+  sequence: number;
+  text: string;
+}
+
+export type ResultStatus = "completed" | "failed" | "cancelled";
+
+export interface ResultError extends SdkErrorDetails {
+  message: string;
+}
+
+export interface Result {
+  type: "result";
+  queryId: string;
+  sessionId: string;
+  turnId: string;
+  operationId: string;
+  status: ResultStatus;
+  outputText: string;
+  error?: ResultError;
+}
+
+export type QueryStreamItem = AssistantTextDelta | Result;
diff --git a/sdk/typescript/test/buffer-limits.test.ts b/sdk/typescript/test/buffer-limits.test.ts
new file mode 100644
index 0000000000..443137d2b2
--- /dev/null
+++ b/sdk/typescript/test/buffer-limits.test.ts
@@ -0,0 +1,310 @@
+import assert from "node:assert/strict";
+import { PassThrough, Writable } from "node:stream";
+import test from "node:test";
+
+import { SdkError } from "../src/errors.js";
+import { JsonRpcConnection } from "../src/internal/json-rpc.js";
+import type { QueryStartResult } from "../src/internal/wire/index.js";
+import { Query } from "../src/query.js";
+
+test("request correlation rejects overload before the pending request count grows", async () => {
+  const clientToHost = new PassThrough();
+  const hostToClient = new PassThrough();
+  const connection = createBoundedConnection(
+    hostToClient,
+    clientToHost,
+    { maxPendingRequests: 1 },
+  );
+  const first = connection.request("query/start", {});
+
+  try {
+    await assert.rejects(connection.request("query/start", {}), isLocalOverload);
+  } finally {
+    void first.catch(() => {});
+    await connection.abort(testCleanupError());
+  }
+});
+
+test("request correlation rejects overload while the carrier remains backpressured", async () => {
+  const hostToClient = new PassThrough();
+  const stalled = new Writable({
+    write(_chunk, _encoding, _callback) {
+      // Deliberately retain the callback: the carrier has not accepted the
+      // complete message, so MessageTransport.send must remain backpressured.
+    },
+  });
+  const connection = createBoundedConnection(
+    hostToClient,
+    stalled,
+    { maxOutboundBytes: 100 },
+  );
+  const first = connection.request("query/start", {});
+
+  try {
+    await assert.rejects(connection.request("query/start", {}), isLocalOverload);
+  } finally {
+    void first.catch(() => {});
+    await connection.abort(testCleanupError());
+  }
+});
+
+test("a slow Query consumer fails closed before its event queue grows without bound", async () => {
+  const clientToHost = new PassThrough();
+  const hostToClient = new PassThrough();
+  let transportClosed = false;
+  const connection = new JsonRpcConnection({
+    readable: hostToClient,
+    writable: clientToHost,
+    close: async () => {
+      transportClosed = true;
+      clientToHost.end();
+      hostToClient.end();
+    },
+  });
+  const started: QueryStartResult = {
+    queryId: "query-slow-consumer",
+    sessionId: "session-slow-consumer",
+    turnId: "turn-slow-consumer",
+    operationId: "operation-slow-consumer",
+    accepted: true,
+    createdSession: false,
+    sessionLifetime: "connection",
+  };
+  const query = Query.create(connection, started);
+
+  for (let sequence = 1; sequence <= 1_025; sequence += 1) {
+    write(hostToClient, {
+      jsonrpc: "2.0",
+      method: "query/event",
+      params: {
+        queryId: started.queryId,
+        sessionId: started.sessionId,
+        turnId: started.turnId,
+        operationId: started.operationId,
+        sequence,
+        event: { type: "assistant_text_delta", text: "x" },
+      },
+    });
+  }
+  write(hostToClient, {
+    jsonrpc: "2.0",
+    method: "query/result",
+    params: {
+      queryId: started.queryId,
+      sessionId: started.sessionId,
+      turnId: started.turnId,
+      operationId: started.operationId,
+      status: "completed",
+      output: { text: "x".repeat(1_025) },
+    },
+  });
+
+  try {
+    await assert.rejects(query.result(), (error: unknown) => {
+      assert.ok(error instanceof SdkError);
+      assert.equal(error.code, "overloaded");
+      assert.equal(error.stage, "query");
+      assert.equal(error.outcomeCertainty, "unknown");
+      return true;
+    });
+    assert.equal(transportClosed, true);
+  } finally {
+    await connection.abort(
+      new SdkError("test cleanup", {
+        code: "process_lost",
+        stage: "protocol",
+        retryable: false,
+        correlationId: "test:cleanup",
+        outcomeCertainty: "unknown",
+      }),
+    );
+  }
+});
+
+test("a protocol-sized Result remains available without consuming the event stream", async () => {
+  const clientToHost = new PassThrough();
+  const hostToClient = new PassThrough();
+  let transportClosed = false;
+  const connection = new JsonRpcConnection({
+    readable: hostToClient,
+    writable: clientToHost,
+    close: async () => {
+      transportClosed = true;
+      clientToHost.end();
+      hostToClient.end();
+    },
+  });
+  const started: QueryStartResult = {
+    queryId: "query-result-only",
+    sessionId: "session-result-only",
+    turnId: "turn-result-only",
+    operationId: "operation-result-only",
+    accepted: true,
+    createdSession: false,
+    sessionLifetime: "connection",
+  };
+  const query = Query.create(connection, started);
+  const output = "x".repeat(512 * 1024);
+
+  write(hostToClient, {
+    jsonrpc: "2.0",
+    method: "query/event",
+    params: {
+      queryId: started.queryId,
+      sessionId: started.sessionId,
+      turnId: started.turnId,
+      operationId: started.operationId,
+      sequence: 1,
+      event: { type: "assistant_text_delta", text: output },
+    },
+  });
+  write(hostToClient, {
+    jsonrpc: "2.0",
+    method: "query/result",
+    params: {
+      queryId: started.queryId,
+      sessionId: started.sessionId,
+      turnId: started.turnId,
+      operationId: started.operationId,
+      status: "completed",
+      output: { text: output },
+    },
+  });
+
+  try {
+    const result = await withTestDeadline(query.result());
+    assert.equal(result.status, "completed");
+    assert.equal(result.outputText.length, output.length);
+    assert.equal(transportClosed, false);
+  } finally {
+    await connection.abort(
+      new SdkError("test cleanup", {
+        code: "process_lost",
+        stage: "protocol",
+        retryable: false,
+        correlationId: "test:cleanup",
+        outcomeCertainty: "unknown",
+      }),
+    );
+  }
+});
+
+test("an oversized unterminated Host frame fails the connection before unbounded buffering", async () => {
+  const clientToHost = new PassThrough();
+  const hostToClient = new PassThrough();
+  let transportClosed = false;
+  const connection = new JsonRpcConnection({
+    readable: hostToClient,
+    writable: clientToHost,
+    close: async () => {
+      transportClosed = true;
+      clientToHost.end();
+      hostToClient.end();
+    },
+  });
+  const pending = connection.request("initialize", {});
+  hostToClient.write("x".repeat(1024 * 1024 + 1));
+
+  try {
+    await assert.rejects(withTestDeadline(pending), (error: unknown) => {
+      assert.ok(error instanceof SdkError);
+      assert.equal(error.code, "process_lost");
+      assert.equal(error.outcomeCertainty, "unknown");
+      return true;
+    });
+    assert.equal(transportClosed, true);
+  } finally {
+    await connection.abort(
+      new SdkError("test cleanup", {
+        code: "process_lost",
+        stage: "protocol",
+        retryable: false,
+        correlationId: "test:cleanup",
+        outcomeCertainty: "unknown",
+      }),
+    );
+  }
+});
+
+function write(stream: PassThrough, value: unknown): void {
+  stream.write(`${JSON.stringify(value)}\n`);
+}
+
+async function withTestDeadline<T>(promise: Promise<T>): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const expired = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => reject(new Error("frame buffering did not stop")), 250);
+  });
+  try {
+    return await Promise.race([promise, expired]);
+  } finally {
+    if (timer !== undefined) {
+      clearTimeout(timer);
+    }
+  }
+}
+
+interface TestConnectionLimits {
+  maxPendingRequests?: number;
+  maxOutboundBytes?: number;
+}
+
+function createBoundedConnection(
+  readable: PassThrough,
+  writable: Writable,
+  limits: TestConnectionLimits,
+): JsonRpcConnection {
+  const Connection = JsonRpcConnection as unknown as new (
+    transport: {
+      readable: PassThrough;
+      writable: Writable;
+      close(): Promise<void>;
+    },
+    options: {
+      requestTimeoutMs: number;
+      limits: {
+        maxMessageBytes: number;
+        maxPendingRequests: number;
+        maxPendingBytes: number;
+        maxOutboundBytes: number;
+      };
+    },
+  ) => JsonRpcConnection;
+  return new Connection(
+    {
+      readable,
+      writable,
+      close: async () => {
+        readable.end();
+        writable.destroy();
+      },
+    },
+    {
+      requestTimeoutMs: 1_000,
+      limits: {
+        maxMessageBytes: 1_024,
+        maxPendingRequests: limits.maxPendingRequests ?? 8,
+        maxPendingBytes: 4_096,
+        maxOutboundBytes: limits.maxOutboundBytes ?? 4_096,
+      },
+    },
+  );
+}
+
+function isLocalOverload(error: unknown): boolean {
+  assert.ok(error instanceof SdkError);
+  assert.equal(error.code, "overloaded");
+  assert.equal(error.stage, "query");
+  assert.equal(error.outcomeCertainty, "not_started");
+  return true;
+}
+
+function testCleanupError(): SdkError {
+  return new SdkError("test cleanup", {
+    code: "process_lost",
+    stage: "protocol",
+    retryable: false,
+    correlationId: "test:cleanup",
+    outcomeCertainty: "unknown",
+  });
+}
diff --git a/sdk/typescript/test/client.test.ts b/sdk/typescript/test/client.test.ts
new file mode 100644
index 0000000000..b9b9106aac
--- /dev/null
+++ b/sdk/typescript/test/client.test.ts
@@ -0,0 +1,1016 @@
+import assert from "node:assert/strict";
+import { PassThrough } from "node:stream";
+import { createInterface } from "node:readline";
+import test from "node:test";
+
+import { AgentClient, SdkError } from "../src/index.js";
+import { createAgentClient } from "../src/internal/client.js";
+
+test("a Query streams ordered events and returns the Host terminal Result", async () => {
+  const clientToHost = new PassThrough();
+  const hostToClient = new PassThrough();
+  const host = runFixtureHost(clientToHost, hostToClient);
+  const client = await createAgentClient(
+    {
+      readable: hostToClient,
+      writable: clientToHost,
+      close: async () => {
+        clientToHost.end();
+        await host;
+      },
+    },
+    { cwd: "D:/workspace/project" },
+  );
+
+  assert.ok(client instanceof AgentClient);
+  const query = await client.query({ prompt: "hello" });
+  assert.equal(query.id, "query-1");
+  assert.equal(query.operationId, "operation-1");
+  assert.deepEqual(query.turn, { id: "turn-1", sessionId: "session-1" });
+  const items = [];
+  for await (const item of query) {
+    items.push(item);
+  }
+
+  assert.deepEqual(items, [
+    {
+      type: "assistant_text_delta",
+      queryId: "query-1",
+      sessionId: "session-1",
+      turnId: "turn-1",
+      operationId: "operation-1",
+      sequence: 1,
+      text: "fixture result",
+    },
+    {
+      type: "result",
+      queryId: "query-1",
+      sessionId: "session-1",
+      turnId: "turn-1",
+      operationId: "operation-1",
+      status: "completed",
+      outputText: "fixture result",
+    },
+  ]);
+  assert.equal((await query.result()).outputText, "fixture result");
+  assert.equal(typeof query[Symbol.asyncDispose], "function");
+
+  await client.close();
+  assert.equal(typeof client[Symbol.asyncDispose], "function");
+});
+
+test("an explicit Session starts Turns on the existing client connection", async () => {
+  const clientToHost = new PassThrough();
+  const hostToClient = new PassThrough();
+  const methods: string[] = [];
+  const host = runSessionFixtureHost(clientToHost, hostToClient, methods);
+  const client = await createAgentClient(
+    {
+      readable: hostToClient,
+      writable: clientToHost,
+      close: async () => {
+        clientToHost.end();
+        await host;
+      },
+    },
+    { cwd: "D:/workspace/project" },
+  );
+
+  const session = await client.sessions.create({ agent: "agentic" });
+  assert.equal(session.id, "session-explicit");
+  assert.equal(session.agent, "agentic");
+
+  const query = await session.startTurn({ prompt: "continue" });
+  assert.equal((await query.result()).outputText, "continued");
+  await session.close();
+  assert.equal(typeof session[Symbol.asyncDispose], "function");
+  await client.close();
+
+  assert.deepEqual(methods, [
+    "initialize",
+    "session/create",
+    "query/start",
+    "session/close",
+    "shutdown",
+  ]);
+});
+
+test("Query cancel and close are idempotent and the Host Result remains authoritative", async () => {
+  const clientToHost = new PassThrough();
+  const hostToClient = new PassThrough();
+  let cancelRequests = 0;
+  const host = runCancelFixtureHost(clientToHost, hostToClient, () => {
+    cancelRequests += 1;
+  });
+  const client = await createAgentClient(
+    {
+      readable: hostToClient,
+      writable: clientToHost,
+      close: async () => {
+        clientToHost.end();
+        await host;
+      },
+    },
+    { cwd: "D:/workspace/project" },
+  );
+
+  const query = await client.query({ prompt: "wait" });
+  await Promise.all([query.cancel(), query.cancel()]);
+  const result = await query.result();
+  assert.equal(result.status, "cancelled");
+  assert.equal(result.error?.code, "cancelled");
+  await query.close();
+  assert.equal(cancelRequests, 1);
+
+  await client.close();
+});
+
+test("leaving Query iteration early cancels and settles the Turn", async () => {
+  const clientToHost = new PassThrough();
+  const hostToClient = new PassThrough();
+  let cancelRequests = 0;
+  const host = runCancelFixtureHost(
+    clientToHost,
+    hostToClient,
+    () => {
+      cancelRequests += 1;
+    },
+    true,
+  );
+  const client = await createAgentClient(
+    {
+      readable: hostToClient,
+      writable: clientToHost,
+      close: async () => {
+        clientToHost.end();
+        await host;
+      },
+    },
+    { cwd: "D:/workspace/project" },
+  );
+
+  const query = await client.query({ prompt: "stream" });
+  for await (const item of query) {
+    assert.equal(item.type, "assistant_text_delta");
+    break;
+  }
+  assert.equal(cancelRequests, 1);
+  assert.equal((await query.result()).status, "cancelled");
+
+  await client.close();
+});
+
+test("Host loss rejects an accepted Query with unknown outcome instead of fabricating a Result", async () => {
+  const clientToHost = new PassThrough();
+  const hostToClient = new PassThrough();
+  let transportClosed = false;
+  const host = runProcessLossFixtureHost(clientToHost, hostToClient);
+  const client = await createAgentClient(
+    {
+      readable: hostToClient,
+      writable: clientToHost,
+      close: async () => {
+        transportClosed = true;
+        clientToHost.end();
+        await host;
+      },
+    },
+    { cwd: "D:/workspace/project" },
+  );
+
+  const query = await client.query({ prompt: "may have side effects" });
+  await assert.rejects(query.result(), (error: unknown) => {
+    assert.ok(error instanceof SdkError);
+    assert.equal(error.code, "process_lost");
+    assert.equal(error.stage, "protocol");
+    assert.equal(error.outcomeCertainty, "unknown");
+    return true;
+  });
+  await assert.rejects(query[Symbol.asyncIterator]().next(), SdkError);
+
+  await client.close();
+  assert.equal(transportClosed, true);
+});
+
+test("AgentClient.close settles owned Queries before shutting down its connection", async () => {
+  const clientToHost = new PassThrough();
+  const hostToClient = new PassThrough();
+  const methods: string[] = [];
+  const host = runClientCloseFixtureHost(clientToHost, hostToClient, methods);
+  const client = await createAgentClient(
+    {
+      readable: hostToClient,
+      writable: clientToHost,
+      close: async () => {
+        clientToHost.end();
+        await host;
+      },
+    },
+    { cwd: "D:/workspace/project" },
+  );
+
+  const query = await client.query({ prompt: "still running" });
+  await client.close();
+  assert.equal((await query.result()).status, "cancelled");
+  assert.deepEqual(methods, [
+    "initialize",
+    "query/start",
+    "query/cancel",
+    "session/close",
+    "shutdown",
+  ]);
+});
+
+test("Host operation errors preserve stable SDK error facts", async () => {
+  const clientToHost = new PassThrough();
+  const hostToClient = new PassThrough();
+  const host = runOperationErrorFixtureHost(clientToHost, hostToClient);
+  const client = await createAgentClient(
+    {
+      readable: hostToClient,
+      writable: clientToHost,
+      close: async () => {
+        clientToHost.end();
+        await host;
+      },
+    },
+    { cwd: "D:/workspace/project" },
+  );
+
+  await assert.rejects(client.query({ prompt: "requires auth" }), (error: unknown) => {
+    assert.ok(error instanceof SdkError);
+    assert.equal(error.code, "action_required");
+    assert.equal(error.stage, "query");
+    assert.equal(error.retryable, false);
+    assert.equal(error.correlationId, "request:query-start");
+    assert.equal(error.outcomeCertainty, "not_started");
+    assert.equal(error.recovery, "initialize");
+    return true;
+  });
+
+  await client.close();
+});
+
+test("unknown Host error facts fail the protocol closed", async () => {
+  const clientToHost = new PassThrough();
+  const hostToClient = new PassThrough();
+  const host = runInvalidErrorFixtureHost(clientToHost, hostToClient);
+  const client = await createAgentClient(
+    {
+      readable: hostToClient,
+      writable: clientToHost,
+      close: async () => {
+        clientToHost.end();
+        await host;
+      },
+    },
+    { cwd: "D:/workspace/project" },
+  );
+
+  await assert.rejects(client.query({ prompt: "invalid error" }), (error: unknown) => {
+    assert.ok(error instanceof SdkError);
+    assert.equal(error.code, "process_lost");
+    assert.equal(error.outcomeCertainty, "unknown");
+    return true;
+  });
+  await client.close();
+});
+
+test("ambiguous JSON-RPC response envelopes fail the protocol closed", async () => {
+  const clientToHost = new PassThrough();
+  const hostToClient = new PassThrough();
+  const host = runAmbiguousResponseFixtureHost(clientToHost, hostToClient);
+  const client = await createAgentClient(
+    {
+      readable: hostToClient,
+      writable: clientToHost,
+      close: async () => {
+        clientToHost.end();
+        await host;
+      },
+    },
+    { cwd: "D:/workspace/project" },
+  );
+
+  await assert.rejects(client.query({ prompt: "reject ambiguous response" }), (error: unknown) => {
+    assert.ok(error instanceof SdkError);
+    assert.equal(error.code, "process_lost");
+    assert.equal(error.outcomeCertainty, "unknown");
+    return true;
+  });
+  await client.close();
+});
+
+test("unknown Query event and Result status fail the protocol closed", async (context) => {
+  const cases = [
+    {
+      name: "unknown event",
+      notification: {
+        jsonrpc: "2.0",
+        method: "query/event",
+        params: {
+          queryId: "query-invalid",
+          sessionId: "session-invalid",
+          turnId: "turn-invalid",
+          operationId: "operation-invalid",
+          sequence: 1,
+          event: { type: "permission_request", text: "must not be dropped" },
+        },
+      },
+      appendValidResult: true,
+    },
+    {
+      name: "unknown Result status",
+      notification: {
+        jsonrpc: "2.0",
+        method: "query/result",
+        params: {
+          queryId: "query-invalid",
+          sessionId: "session-invalid",
+          turnId: "turn-invalid",
+          operationId: "operation-invalid",
+          status: "partially_completed",
+          output: { text: "invalid" },
+        },
+      },
+      appendValidResult: false,
+    },
+  ] as const;
+
+  for (const fixture of cases) {
+    await context.test(fixture.name, async () => {
+      const clientToHost = new PassThrough();
+      const hostToClient = new PassThrough();
+      const host = runInvalidNotificationFixtureHost(
+        clientToHost,
+        hostToClient,
+        fixture.notification,
+        fixture.appendValidResult,
+      );
+      const client = await createAgentClient(
+        {
+          readable: hostToClient,
+          writable: clientToHost,
+          close: async () => {
+            clientToHost.end();
+            await host;
+          },
+        },
+        { cwd: "D:/workspace/project" },
+      );
+
+      try {
+        const query = await client.query({ prompt: "reject protocol drift" });
+        await assert.rejects(query.result(), (error: unknown) => {
+          assert.ok(error instanceof SdkError);
+          assert.equal(error.code, "process_lost");
+          assert.equal(error.outcomeCertainty, "unknown");
+          return true;
+        });
+      } finally {
+        await client.close();
+      }
+    });
+  }
+});
+
+async function runFixtureHost(
+  requests: PassThrough,
+  responses: PassThrough,
+): Promise<void> {
+  const lines = createInterface({ input: requests, crlfDelay: Infinity });
+  for await (const line of lines) {
+    const request = JSON.parse(line) as {
+      id: number;
+      method: string;
+      params: Record<string, unknown>;
+    };
+    if (request.method === "initialize") {
+      write(responses, {
+        jsonrpc: "2.0",
+        id: request.id,
+        result: {
+          protocolVersion: 1,
+          runtimeVersion: "0.2.17",
+          stability: "not_delivered",
+          capabilities: {
+            sessionCreate: true,
+            sessionCreateLifetime: "connection",
+            query: true,
+            queryCancel: true,
+            sessionClose: true,
+            eventStream: true,
+            structuredOutput: false,
+            usage: false,
+            customTools: false,
+            permissionCallbacks: false,
+            hooks: false,
+            mcpConfiguration: false,
+            prestartedTransport: false,
+          },
+        },
+      });
+      continue;
+    }
+    if (request.method === "query/start") {
+      write(responses, {
+        jsonrpc: "2.0",
+        id: request.id,
+        result: {
+          queryId: "query-1",
+          sessionId: "session-1",
+          turnId: "turn-1",
+          operationId: "operation-1",
+          accepted: true,
+          createdSession: true,
+          sessionLifetime: "connection",
+        },
+      });
+      write(responses, {
+        jsonrpc: "2.0",
+        method: "query/event",
+        params: {
+          queryId: "query-1",
+          sessionId: "session-1",
+          turnId: "turn-1",
+          operationId: "operation-1",
+          sequence: 1,
+          event: { type: "assistant_text_delta", text: "fixture result" },
+        },
+      });
+      write(responses, {
+        jsonrpc: "2.0",
+        method: "query/result",
+        params: {
+          queryId: "query-1",
+          sessionId: "session-1",
+          turnId: "turn-1",
+          operationId: "operation-1",
+          status: "completed",
+          output: { text: "fixture result" },
+        },
+      });
+      continue;
+    }
+    if (request.method === "session/close") {
+      write(responses, {
+        jsonrpc: "2.0",
+        id: request.id,
+        result: { sessionId: "session-1", unloaded: true },
+      });
+      continue;
+    }
+    if (request.method === "shutdown") {
+      write(responses, {
+        jsonrpc: "2.0",
+        id: request.id,
+        result: { accepted: true },
+      });
+      responses.end();
+      return;
+    }
+    throw new Error(`Unexpected fixture method: ${request.method}`);
+  }
+}
+
+async function runSessionFixtureHost(
+  requests: PassThrough,
+  responses: PassThrough,
+  methods: string[],
+): Promise<void> {
+  const lines = createInterface({ input: requests, crlfDelay: Infinity });
+  for await (const line of lines) {
+    const request = JSON.parse(line) as {
+      id: number;
+      method: string;
+      params: Record<string, unknown>;
+    };
+    methods.push(request.method);
+    if (request.method === "initialize") {
+      write(responses, initializeResponse(request.id));
+      continue;
+    }
+    if (request.method === "session/create") {
+      assert.deepEqual(request.params, {
+        sessionName: null,
+        agent: "agentic",
+        cwd: "D:/workspace/project",
+        model: null,
+      });
+      write(responses, {
+        jsonrpc: "2.0",
+        id: request.id,
+        result: {
+          sessionId: "session-explicit",
+          sessionName: "Explicit",
+          agent: "agentic",
+          lifetime: "connection",
+        },
+      });
+      continue;
+    }
+    if (request.method === "query/start") {
+      assert.deepEqual(request.params, {
+        prompt: "continue",
+        sessionId: "session-explicit",
+      });
+      write(responses, {
+        jsonrpc: "2.0",
+        id: request.id,
+        result: {
+          queryId: "query-explicit",
+          sessionId: "session-explicit",
+          turnId: "turn-explicit",
+          operationId: "operation-explicit",
+          accepted: true,
+          createdSession: false,
+          sessionLifetime: "connection",
+        },
+      });
+      write(responses, {
+        jsonrpc: "2.0",
+        method: "query/result",
+        params: {
+          queryId: "query-explicit",
+          sessionId: "session-explicit",
+          turnId: "turn-explicit",
+          operationId: "operation-explicit",
+          status: "completed",
+          output: { text: "continued" },
+        },
+      });
+      continue;
+    }
+    if (request.method === "session/close") {
+      assert.deepEqual(request.params, {
+        sessionId: "session-explicit",
+      });
+      write(responses, {
+        jsonrpc: "2.0",
+        id: request.id,
+        result: { sessionId: "session-explicit", unloaded: true },
+      });
+      continue;
+    }
+    if (request.method === "shutdown") {
+      write(responses, {
+        jsonrpc: "2.0",
+        id: request.id,
+        result: { accepted: true },
+      });
+      responses.end();
+      return;
+    }
+    throw new Error(`Unexpected fixture method: ${request.method}`);
+  }
+}
+
+async function runCancelFixtureHost(
+  requests: PassThrough,
+  responses: PassThrough,
+  onCancel: () => void,
+  emitEventAfterStart = false,
+): Promise<void> {
+  const lines = createInterface({ input: requests, crlfDelay: Infinity });
+  for await (const line of lines) {
+    const request = JSON.parse(line) as {
+      id: number;
+      method: string;
+      params: Record<string, unknown>;
+    };
+    if (request.method === "initialize") {
+      write(responses, initializeResponse(request.id));
+      continue;
+    }
+    if (request.method === "query/start") {
+      write(responses, {
+        jsonrpc: "2.0",
+        id: request.id,
+        result: {
+          queryId: "query-cancel",
+          sessionId: "session-cancel",
+          turnId: "turn-cancel",
+          operationId: "operation-cancel",
+          accepted: true,
+          createdSession: true,
+          sessionLifetime: "connection",
+        },
+      });
+      if (emitEventAfterStart) {
+        write(responses, {
+          jsonrpc: "2.0",
+          method: "query/event",
+          params: {
+            queryId: "query-cancel",
+            sessionId: "session-cancel",
+            turnId: "turn-cancel",
+            operationId: "operation-cancel",
+            sequence: 1,
+            event: { type: "assistant_text_delta", text: "partial" },
+          },
+        });
+      }
+      continue;
+    }
+    if (request.method === "query/cancel") {
+      onCancel();
+      assert.deepEqual(request.params, {
+        queryId: "query-cancel",
+        sessionId: "session-cancel",
+        turnId: "turn-cancel",
+        operationId: "operation-cancel",
+      });
+      write(responses, {
+        jsonrpc: "2.0",
+        id: request.id,
+        result: {
+          queryId: "query-cancel",
+          sessionId: "session-cancel",
+          turnId: "turn-cancel",
+          operationId: "operation-cancel",
+          requested: true,
+        },
+      });
+      write(responses, {
+        jsonrpc: "2.0",
+        method: "query/result",
+        params: {
+          queryId: "query-cancel",
+          sessionId: "session-cancel",
+          turnId: "turn-cancel",
+          operationId: "operation-cancel",
+          status: "cancelled",
+          output: { text: "" },
+          error: {
+            message: "cancelled by caller",
+            data: {
+              code: "cancelled",
+              stage: "query",
+              retryable: false,
+              correlationId: "operation-cancel",
+              operationId: "operation-cancel",
+              outcomeCertainty: "committed",
+            },
+          },
+        },
+      });
+      continue;
+    }
+    if (request.method === "session/close") {
+      write(responses, {
+        jsonrpc: "2.0",
+        id: request.id,
+        result: { sessionId: "session-cancel", unloaded: true },
+      });
+      continue;
+    }
+    if (request.method === "shutdown") {
+      write(responses, {
+        jsonrpc: "2.0",
+        id: request.id,
+        result: { accepted: true },
+      });
+      responses.end();
+      return;
+    }
+    throw new Error(`Unexpected fixture method: ${request.method}`);
+  }
+}
+
+async function runProcessLossFixtureHost(
+  requests: PassThrough,
+  responses: PassThrough,
+): Promise<void> {
+  const lines = createInterface({ input: requests, crlfDelay: Infinity });
+  for await (const line of lines) {
+    const request = JSON.parse(line) as { id: number; method: string };
+    if (request.method === "initialize") {
+      write(responses, initializeResponse(request.id));
+      continue;
+    }
+    if (request.method === "query/start") {
+      write(responses, {
+        jsonrpc: "2.0",
+        id: request.id,
+        result: {
+          queryId: "query-lost",
+          sessionId: "session-lost",
+          turnId: "turn-lost",
+          operationId: "operation-lost",
+          accepted: true,
+          createdSession: true,
+          sessionLifetime: "connection",
+        },
+      });
+      responses.end();
+      return;
+    }
+    throw new Error(`Unexpected fixture method: ${request.method}`);
+  }
+}
+
+async function runClientCloseFixtureHost(
+  requests: PassThrough,
+  responses: PassThrough,
+  methods: string[],
+): Promise<void> {
+  const lines = createInterface({ input: requests, crlfDelay: Infinity });
+  for await (const line of lines) {
+    const request = JSON.parse(line) as {
+      id: number;
+      method: string;
+      params: Record<string, unknown>;
+    };
+    methods.push(request.method);
+    if (request.method === "initialize") {
+      write(responses, initializeResponse(request.id));
+      continue;
+    }
+    if (request.method === "query/start") {
+      write(responses, {
+        jsonrpc: "2.0",
+        id: request.id,
+        result: {
+          queryId: "query-client-close",
+          sessionId: "session-client-close",
+          turnId: "turn-client-close",
+          operationId: "operation-client-close",
+          accepted: true,
+          createdSession: true,
+          sessionLifetime: "connection",
+        },
+      });
+      continue;
+    }
+    if (request.method === "query/cancel") {
+      assert.deepEqual(request.params, {
+        queryId: "query-client-close",
+        sessionId: "session-client-close",
+        turnId: "turn-client-close",
+        operationId: "operation-client-close",
+      });
+      write(responses, {
+        jsonrpc: "2.0",
+        id: request.id,
+        result: {
+          queryId: "query-client-close",
+          sessionId: "session-client-close",
+          turnId: "turn-client-close",
+          operationId: "operation-client-close",
+          requested: true,
+        },
+      });
+      write(responses, {
+        jsonrpc: "2.0",
+        method: "query/result",
+        params: {
+          queryId: "query-client-close",
+          sessionId: "session-client-close",
+          turnId: "turn-client-close",
+          operationId: "operation-client-close",
+          status: "cancelled",
+          output: { text: "" },
+          error: {
+            message: "cancelled during client close",
+            data: {
+              code: "cancelled",
+              stage: "query",
+              retryable: false,
+              correlationId: "operation-client-close",
+              operationId: "operation-client-close",
+              outcomeCertainty: "committed",
+            },
+          },
+        },
+      });
+      continue;
+    }
+    if (request.method === "session/close") {
+      assert.deepEqual(request.params, { sessionId: "session-client-close" });
+      write(responses, {
+        jsonrpc: "2.0",
+        id: request.id,
+        result: { sessionId: "session-client-close", unloaded: true },
+      });
+      continue;
+    }
+    if (request.method === "shutdown") {
+      write(responses, {
+        jsonrpc: "2.0",
+        id: request.id,
+        result: { accepted: true },
+      });
+      responses.end();
+      return;
+    }
+    throw new Error(`Unexpected fixture method: ${request.method}`);
+  }
+}
+
+async function runOperationErrorFixtureHost(
+  requests: PassThrough,
+  responses: PassThrough,
+): Promise<void> {
+  const lines = createInterface({ input: requests, crlfDelay: Infinity });
+  for await (const line of lines) {
+    const request = JSON.parse(line) as { id: number; method: string };
+    if (request.method === "initialize") {
+      write(responses, initializeResponse(request.id));
+      continue;
+    }
+    if (request.method === "query/start") {
+      write(responses, {
+        jsonrpc: "2.0",
+        id: request.id,
+        error: {
+          code: -32000,
+          message: "authentication is required",
+          data: {
+            code: "action_required",
+            stage: "query",
+            retryable: false,
+            correlationId: "request:query-start",
+            outcomeCertainty: "not_started",
+            recovery: "initialize",
+          },
+        },
+      });
+      continue;
+    }
+    if (request.method === "shutdown") {
+      write(responses, {
+        jsonrpc: "2.0",
+        id: request.id,
+        result: { accepted: true },
+      });
+      responses.end();
+      return;
+    }
+    throw new Error(`Unexpected fixture method: ${request.method}`);
+  }
+}
+
+async function runInvalidErrorFixtureHost(
+  requests: PassThrough,
+  responses: PassThrough,
+): Promise<void> {
+  const lines = createInterface({ input: requests, crlfDelay: Infinity });
+  for await (const line of lines) {
+    const request = JSON.parse(line) as { id: number; method: string };
+    if (request.method === "initialize") {
+      write(responses, initializeResponse(request.id));
+      continue;
+    }
+    if (request.method === "query/start") {
+      write(responses, {
+        jsonrpc: "2.0",
+        id: request.id,
+        error: {
+          code: -32000,
+          message: "unknown error contract",
+          data: {
+            code: "invented_error",
+            stage: "query",
+            retryable: false,
+            correlationId: "request:invalid",
+            outcomeCertainty: "not_started",
+          },
+        },
+      });
+      responses.end();
+      return;
+    }
+    throw new Error(`Unexpected fixture method: ${request.method}`);
+  }
+}
+
+async function runAmbiguousResponseFixtureHost(
+  requests: PassThrough,
+  responses: PassThrough,
+): Promise<void> {
+  const lines = createInterface({ input: requests, crlfDelay: Infinity });
+  for await (const line of lines) {
+    const request = JSON.parse(line) as { id: number; method: string };
+    if (request.method === "initialize") {
+      write(responses, initializeResponse(request.id));
+      continue;
+    }
+    if (request.method === "query/start") {
+      write(responses, {
+        jsonrpc: "2.0",
+        id: request.id,
+        result: {
+          queryId: "query-ambiguous",
+          sessionId: "session-ambiguous",
+          turnId: "turn-ambiguous",
+          operationId: "operation-ambiguous",
+          accepted: true,
+          createdSession: true,
+          sessionLifetime: "connection",
+        },
+        error: {
+          code: -32000,
+          message: "must not coexist with result",
+          data: {
+            code: "internal",
+            stage: "query",
+            retryable: false,
+            correlationId: "request:ambiguous",
+            outcomeCertainty: "not_started",
+          },
+        },
+      });
+      responses.end();
+      return;
+    }
+    throw new Error(`Unexpected fixture method: ${request.method}`);
+  }
+}
+
+async function runInvalidNotificationFixtureHost(
+  requests: PassThrough,
+  responses: PassThrough,
+  notification: unknown,
+  appendValidResult: boolean,
+): Promise<void> {
+  const lines = createInterface({ input: requests, crlfDelay: Infinity });
+  for await (const line of lines) {
+    const request = JSON.parse(line) as { id: number; method: string };
+    if (request.method === "initialize") {
+      write(responses, initializeResponse(request.id));
+      continue;
+    }
+    if (request.method === "query/start") {
+      write(responses, {
+        jsonrpc: "2.0",
+        id: request.id,
+        result: {
+          queryId: "query-invalid",
+          sessionId: "session-invalid",
+          turnId: "turn-invalid",
+          operationId: "operation-invalid",
+          accepted: true,
+          createdSession: true,
+          sessionLifetime: "connection",
+        },
+      });
+      write(responses, notification);
+      if (appendValidResult) {
+        write(responses, {
+          jsonrpc: "2.0",
+          method: "query/result",
+          params: {
+            queryId: "query-invalid",
+            sessionId: "session-invalid",
+            turnId: "turn-invalid",
+            operationId: "operation-invalid",
+            status: "completed",
+            output: { text: "must not become authoritative" },
+          },
+        });
+      }
+      continue;
+    }
+    if (request.method === "shutdown") {
+      write(responses, {
+        jsonrpc: "2.0",
+        id: request.id,
+        result: { accepted: true },
+      });
+      responses.end();
+      return;
+    }
+  }
+  responses.end();
+}
+
+function initializeResponse(id: number): unknown {
+  return {
+    jsonrpc: "2.0",
+    id,
+    result: {
+      protocolVersion: 1,
+      runtimeVersion: "0.2.17",
+      stability: "not_delivered",
+      capabilities: {
+        sessionCreate: true,
+        sessionCreateLifetime: "connection",
+        query: true,
+        queryCancel: true,
+        sessionClose: true,
+        eventStream: true,
+        structuredOutput: false,
+        usage: false,
+        customTools: false,
+        permissionCallbacks: false,
+        hooks: false,
+        mcpConfiguration: false,
+        prestartedTransport: false,
+      },
+    },
+  };
+}
+
+function write(stream: PassThrough, value: unknown): void {
+  stream.write(`${JSON.stringify(value)}\n`);
+}
diff --git a/sdk/typescript/test/fixtures/host.mjs b/sdk/typescript/test/fixtures/host.mjs
new file mode 100644
index 0000000000..0fea572501
--- /dev/null
+++ b/sdk/typescript/test/fixtures/host.mjs
@@ -0,0 +1,42 @@
+import { createInterface } from "node:readline";
+
+const lines = createInterface({ input: process.stdin, crlfDelay: Infinity });
+for await (const line of lines) {
+  const request = JSON.parse(line);
+  if (request.method === "initialize") {
+    write({
+      jsonrpc: "2.0",
+      id: request.id,
+      result: {
+        protocolVersion: 1,
+        runtimeVersion: "fixture",
+        stability: "not_delivered",
+        capabilities: {
+          sessionCreate: true,
+          sessionCreateLifetime: "connection",
+          query: true,
+          queryCancel: true,
+          sessionClose: true,
+          eventStream: true,
+          structuredOutput: false,
+          usage: false,
+          customTools: false,
+          permissionCallbacks: false,
+          hooks: false,
+          mcpConfiguration: false,
+          prestartedTransport: false,
+        },
+      },
+    });
+    continue;
+  }
+  if (request.method === "shutdown") {
+    write({ jsonrpc: "2.0", id: request.id, result: { accepted: true } });
+    break;
+  }
+  throw new Error(`Unexpected method: ${request.method}`);
+}
+
+function write(value) {
+  process.stdout.write(`${JSON.stringify(value)}\n`);
+}
diff --git a/sdk/typescript/test/fixtures/unresponsive-host.mjs b/sdk/typescript/test/fixtures/unresponsive-host.mjs
new file mode 100644
index 0000000000..ad87d63958
--- /dev/null
+++ b/sdk/typescript/test/fixtures/unresponsive-host.mjs
@@ -0,0 +1,15 @@
+import { spawn } from "node:child_process";
+
+const grandchild = spawn(
+  process.execPath,
+  ["-e", "setInterval(() => {}, 1000)"],
+  { stdio: "ignore", windowsHide: true },
+);
+
+process.stdout.write(`${grandchild.pid}\n`);
+if (process.argv[2] === "exit-parent") {
+  grandchild.unref();
+  process.exit(0);
+}
+process.stdin.resume();
+setInterval(() => {}, 1000);
diff --git a/sdk/typescript/test/lifecycle-timeouts.test.ts b/sdk/typescript/test/lifecycle-timeouts.test.ts
new file mode 100644
index 0000000000..b63903a481
--- /dev/null
+++ b/sdk/typescript/test/lifecycle-timeouts.test.ts
@@ -0,0 +1,251 @@
+import assert from "node:assert/strict";
+import { createInterface } from "node:readline";
+import { PassThrough } from "node:stream";
+import test from "node:test";
+
+import { SdkError } from "../src/errors.js";
+import { createAgentClient } from "../src/internal/client.js";
+import { JsonRpcConnection } from "../src/internal/json-rpc.js";
+import type {
+  QueryStartResult,
+  SessionCreateResult,
+} from "../src/internal/wire/index.js";
+import { Query } from "../src/query.js";
+import { Session } from "../src/session.js";
+
+test("client initialization aborts the Host connection after its startup deadline", async () => {
+  const clientToHost = new PassThrough();
+  const hostToClient = new PassThrough();
+  let transportClosed = false;
+  const starting = createAgentClient(
+    {
+      readable: hostToClient,
+      writable: clientToHost,
+      close: async () => {
+        transportClosed = true;
+        clientToHost.end();
+        hostToClient.end();
+      },
+    },
+    { cwd: "D:/workspace/project", initializeTimeoutMs: 20 },
+  );
+
+  await assert.rejects(withTestDeadline(starting), (error: unknown) => {
+    assert.ok(error instanceof SdkError);
+    assert.equal(error.code, "timeout");
+    assert.equal(error.stage, "initialize");
+    assert.equal(error.outcomeCertainty, "unknown");
+    assert.equal(error.recovery, "restart_host");
+    return true;
+  });
+  assert.equal(transportClosed, true);
+});
+
+test("Query.close aborts an unresponsive Host after its cleanup deadline", async () => {
+  const clientToHost = new PassThrough();
+  const hostToClient = new PassThrough();
+  let transportClosed = false;
+  const connection = new JsonRpcConnection({
+    readable: hostToClient,
+    writable: clientToHost,
+    close: async () => {
+      transportClosed = true;
+      clientToHost.end();
+      hostToClient.end();
+    },
+  });
+  const started: QueryStartResult = {
+    queryId: "query-timeout",
+    sessionId: "session-timeout",
+    turnId: "turn-timeout",
+    operationId: "operation-timeout",
+    accepted: true,
+    createdSession: true,
+    sessionLifetime: "connection",
+  };
+  const createQuery = Query.create as unknown as (
+    owner: JsonRpcConnection,
+    accepted: QueryStartResult,
+    closeTimeoutMs: number,
+  ) => Query;
+  const query = createQuery(connection, started, 20);
+  void query.result().catch(() => {});
+  const closing = query.close();
+
+  try {
+    await assert.rejects(withTestDeadline(closing), isCleanupTimeout);
+    assert.equal(transportClosed, true);
+  } finally {
+    hostToClient.end();
+    await closing.catch(() => {});
+  }
+});
+
+test("connection shutdown closes transport when the Host never responds", async () => {
+  const clientToHost = new PassThrough();
+  const hostToClient = new PassThrough();
+  let transportClosed = false;
+  const connection = new JsonRpcConnection({
+    readable: hostToClient,
+    writable: clientToHost,
+    close: async () => {
+      transportClosed = true;
+      clientToHost.end();
+      hostToClient.end();
+    },
+  });
+  const shutdown = connection.shutdown as unknown as (timeoutMs: number) => Promise<void>;
+  const closing = shutdown.call(connection, 20);
+
+  try {
+    await assert.rejects(withTestDeadline(closing), isCleanupTimeout);
+    assert.equal(transportClosed, true);
+  } finally {
+    hostToClient.end();
+    await closing.catch(() => {});
+  }
+});
+
+test("Session.close aborts an unresponsive Host after its cleanup deadline", async () => {
+  const clientToHost = new PassThrough();
+  const hostToClient = new PassThrough();
+  let transportClosed = false;
+  const connection = new JsonRpcConnection({
+    readable: hostToClient,
+    writable: clientToHost,
+    close: async () => {
+      transportClosed = true;
+      clientToHost.end();
+      hostToClient.end();
+    },
+  });
+  const created: SessionCreateResult = {
+    sessionId: "session-timeout",
+    sessionName: "timeout",
+    agent: "agentic",
+    lifetime: "connection",
+  };
+  const createSession = Session.create as unknown as (
+    owner: JsonRpcConnection,
+    accepted: SessionCreateResult,
+    onQuery: (query: Query) => Query,
+    closeTimeoutMs: number,
+  ) => Session;
+  const session = createSession(connection, created, (query) => query, 20);
+  const closing = session.close();
+
+  try {
+    await assert.rejects(withTestDeadline(closing), isCleanupTimeout);
+    assert.equal(transportClosed, true);
+  } finally {
+    hostToClient.end();
+    await closing.catch(() => {});
+  }
+});
+
+test("implicit Session cleanup with unknown outcome makes the Query connection unusable", async () => {
+  const clientToHost = new PassThrough();
+  const hostToClient = new PassThrough();
+  let transportClosed = false;
+  const connection = new JsonRpcConnection({
+    readable: hostToClient,
+    writable: clientToHost,
+    close: async () => {
+      transportClosed = true;
+      clientToHost.end();
+      hostToClient.end();
+    },
+  });
+  const started: QueryStartResult = {
+    queryId: "query-uncertain-session-cleanup",
+    sessionId: "session-uncertain-cleanup",
+    turnId: "turn-uncertain-cleanup",
+    operationId: "operation-uncertain-cleanup",
+    accepted: true,
+    createdSession: true,
+    sessionLifetime: "connection",
+  };
+  const query = Query.create(connection, started);
+  write(hostToClient, {
+    jsonrpc: "2.0",
+    method: "query/result",
+    params: {
+      queryId: started.queryId,
+      sessionId: started.sessionId,
+      turnId: started.turnId,
+      operationId: started.operationId,
+      status: "completed",
+      output: { text: "done" },
+    },
+  });
+  await query.result();
+  const host = respondWithUncertainSessionCleanup(clientToHost, hostToClient);
+
+  try {
+    await assert.rejects(query.close(), (error: unknown) => {
+      assert.ok(error instanceof SdkError);
+      assert.equal(error.code, "cleanup_required");
+      assert.equal(error.outcomeCertainty, "unknown");
+      assert.equal(error.recovery, "restart_host");
+      return true;
+    });
+    assert.equal(transportClosed, true);
+  } finally {
+    hostToClient.end();
+    await host;
+  }
+});
+
+function isCleanupTimeout(error: unknown): boolean {
+  assert.ok(error instanceof SdkError);
+  assert.equal(error.code, "cleanup_required");
+  assert.equal(error.outcomeCertainty, "unknown");
+  assert.equal(error.recovery, "restart_host");
+  return true;
+}
+
+async function withTestDeadline<T>(promise: Promise<T>): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const expired = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => reject(new Error("cleanup did not honor its deadline")), 250);
+  });
+  try {
+    return await Promise.race([promise, expired]);
+  } finally {
+    if (timer !== undefined) {
+      clearTimeout(timer);
+    }
+  }
+}
+
+async function respondWithUncertainSessionCleanup(
+  requests: PassThrough,
+  responses: PassThrough,
+): Promise<void> {
+  const lines = createInterface({ input: requests, crlfDelay: Infinity });
+  for await (const line of lines) {
+    const request = JSON.parse(line) as { id: number; method: string };
+    assert.equal(request.method, "session/close");
+    write(responses, {
+      jsonrpc: "2.0",
+      id: request.id,
+      error: {
+        code: -32000,
+        message: "cleanup outcome is unknown",
+        data: {
+          code: "cleanup_required",
+          stage: "session",
+          retryable: false,
+          correlationId: "session:uncertain-cleanup",
+          outcomeCertainty: "unknown",
+          recovery: "restart_host",
+        },
+      },
+    });
+    return;
+  }
+}
+
+function write(stream: PassThrough, value: unknown): void {
+  stream.write(`${JSON.stringify(value)}\n`);
+}
diff --git a/sdk/typescript/test/managed-host.test.ts b/sdk/typescript/test/managed-host.test.ts
new file mode 100644
index 0000000000..9667f012ba
--- /dev/null
+++ b/sdk/typescript/test/managed-host.test.ts
@@ -0,0 +1,138 @@
+import assert from "node:assert/strict";
+import { once } from "node:events";
+import { fileURLToPath } from "node:url";
+import test from "node:test";
+
+import { AgentClient, SdkError } from "../src/index.js";
+import { createAgentClient } from "../src/internal/client.js";
+import { forceKillTree, startManagedHost } from "../src/internal/managed-host.js";
+
+test("the managed transport owns one child Host process", async () => {
+  const fixture = fileURLToPath(
+    new URL("../../../../test/fixtures/host.mjs", import.meta.url),
+  );
+  const transport = await startManagedHost({
+    executable: process.execPath,
+    args: [fixture],
+    cwd: process.cwd(),
+  });
+  const client = await createAgentClient(transport, { cwd: process.cwd() });
+
+  assert.ok(client instanceof AgentClient);
+  await client.close();
+  assert.equal(transport.exitCode(), 0);
+});
+
+test("AgentClient.start reports a missing Host before an operation begins", async () => {
+  await assert.rejects(
+    AgentClient.start({
+      cwd: process.cwd(),
+      hostPath: fileURLToPath(
+        new URL("../../../../test/fixtures/missing-host", import.meta.url),
+      ),
+    }),
+    (error: unknown) => {
+      assert.ok(error instanceof SdkError);
+      assert.equal(error.code, "not_found");
+      assert.equal(error.stage, "initialize");
+      assert.equal(error.outcomeCertainty, "not_started");
+      return true;
+    },
+  );
+});
+
+test("forced managed Host cleanup reclaims its descendant process tree", async () => {
+  const fixture = fileURLToPath(
+    new URL("../../../../test/fixtures/unresponsive-host.mjs", import.meta.url),
+  );
+  const options = {
+    executable: process.execPath,
+    args: [fixture],
+    cwd: process.cwd(),
+    gracefulShutdownMs: 20,
+    forceKillTimeoutMs: 2_000,
+  } as Parameters<typeof startManagedHost>[0];
+  const transport = await startManagedHost(options);
+  const [chunk] = (await once(transport.readable, "data")) as [Buffer];
+  const descendantPid = Number.parseInt(chunk.toString("utf8").trim(), 10);
+  assert.equal(Number.isSafeInteger(descendantPid), true);
+
+  try {
+    await transport.close();
+    assert.equal(transport.hasExited(), true);
+    assert.equal(await processExited(descendantPid), true);
+  } finally {
+    if (!(await processExited(descendantPid, 50))) {
+      try {
+        process.kill(descendantPid);
+      } catch {
+        // The descendant exited between the final probe and cleanup.
+      }
+    }
+  }
+});
+
+test(
+  "Unix cleanup reclaims the process group after the direct Host exits first",
+  { skip: process.platform === "win32" },
+  async () => {
+    const fixture = fileURLToPath(
+      new URL("../../../../test/fixtures/unresponsive-host.mjs", import.meta.url),
+    );
+    const transport = await startManagedHost({
+      executable: process.execPath,
+      args: [fixture, "exit-parent"],
+      cwd: process.cwd(),
+      gracefulShutdownMs: 20,
+      forceKillTimeoutMs: 2_000,
+    });
+    const [chunk] = (await once(transport.readable, "data")) as [Buffer];
+    const descendantPid = Number.parseInt(chunk.toString("utf8").trim(), 10);
+    if (!transport.readable.readableEnded) {
+      await once(transport.readable, "end");
+    }
+    assert.equal(transport.hasExited(), true);
+
+    try {
+      await transport.close();
+      assert.equal(await processExited(descendantPid), true);
+    } finally {
+      if (!(await processExited(descendantPid, 50))) {
+        try {
+          process.kill(descendantPid);
+        } catch {
+          // The descendant exited between the final probe and cleanup.
+        }
+      }
+    }
+  },
+);
+
+test(
+  "Windows process-tree cleanup rejects a non-zero taskkill result",
+  { skip: process.platform !== "win32" },
+  async () => {
+    await assert.rejects(forceKillTree(0, 2_000), (error: unknown) => {
+      assert.ok(error instanceof SdkError);
+      assert.equal(error.code, "cleanup_required");
+      assert.equal(error.outcomeCertainty, "unknown");
+      return true;
+    });
+  },
+);
+
+async function processExited(pid: number, timeoutMs = 1_000): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  do {
+    try {
+      process.kill(pid, 0);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ESRCH") {
+        return true;
+      }
+      throw error;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 20));
+  } while (Date.now() < deadline);
+  return false;
+}
diff --git a/sdk/typescript/test/public-contract.test.ts b/sdk/typescript/test/public-contract.test.ts
new file mode 100644
index 0000000000..531b636ddf
--- /dev/null
+++ b/sdk/typescript/test/public-contract.test.ts
@@ -0,0 +1,47 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import test from "node:test";
+
+test("public declarations do not expose internal wire DTOs", async () => {
+  const names = ["client", "errors", "query", "session", "types"];
+  const declarations = new Map(
+    await Promise.all(
+      names.map(async (name) => [
+        name,
+        await readFile(new URL(`../src/${name}.d.ts`, import.meta.url), "utf8"),
+      ] as const),
+    ),
+  );
+
+  for (const declaration of declarations.values()) {
+    assert.doesNotMatch(declaration, /internal\/wire/);
+  }
+
+  assert.match(declarations.get("client") ?? "", /private constructor\(\)/);
+  assert.match(declarations.get("query") ?? "", /private constructor\(\)/);
+  assert.match(
+    declarations.get("session") ?? "",
+    /class Sessions[\s\S]*?private constructor\(\)/,
+  );
+  assert.match(
+    declarations.get("session") ?? "",
+    /class Session[\s\S]*?private constructor\(\)/,
+  );
+});
+
+test("package files keep internal declarations and wire DTOs private", async () => {
+  const packageJson = JSON.parse(
+    await readFile(
+      new URL("../../../../package.json", import.meta.url),
+      "utf8",
+    ),
+  ) as { files?: string[] };
+
+  assert.deepEqual(packageJson.files, [
+    "dist/sdk/typescript/src/*.d.ts",
+    "dist/sdk/typescript/src/*.js",
+    "dist/sdk/typescript/src/internal/*.js",
+    "dist/src/crates/adapters/transport/typescript/src/*.js",
+    "README.md",
+  ]);
+});
diff --git a/sdk/typescript/tsconfig.json b/sdk/typescript/tsconfig.json
new file mode 100644
index 0000000000..8527f7eaba
--- /dev/null
+++ b/sdk/typescript/tsconfig.json
@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "Bundler",
+    "rootDir": "../..",
+    "outDir": "dist",
+    "declaration": true,
+    "declarationMap": true,
+    "stripInternal": true,
+    "sourceMap": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "noEmitOnError": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true
+  },
+  "include": [
+    "src/**/*.ts",
+    "test/**/*.ts",
+    "../../src/crates/adapters/transport/typescript/test/**/*.ts"
+  ]
+}
diff --git a/src/apps/cli/AGENTS.md b/src/apps/cli/AGENTS.md
index 9d7c98b672..7098a99fbc 100644
--- a/src/apps/cli/AGENTS.md
+++ b/src/apps/cli/AGENTS.md
@@ -42,8 +42,9 @@ ChatView -> TuiAgentClient -> TuiBackend -> App Server client
 Embedded TUI uses an in-memory App Server connection. During the migration,
 Shared TUI uses a CLI Host compatibility adapter that implements `TuiBackend`
 over the private versioned Runtime IPC; the TUI client and controllers must not
-reference that IPC. Replacing the physical Shared transport with App Server
-Pipe/UDS framing belongs to Phase 5. Side-effecting operations need stable
+reference that IPC. Embedded direct-runtime migration belongs to Phase 5;
+replacing the physical Shared transport with App Server Pipe/UDS framing belongs
+to the separately reviewed Phase 6. Side-effecting operations need stable
 identities, controller/idle rules, bounded frames, and outcome-unknown handling
 before a connection can retry.
 
diff --git a/src/apps/cli/Cargo.toml b/src/apps/cli/Cargo.toml
index 7210dd2839..e98d8add2d 100644
--- a/src/apps/cli/Cargo.toml
+++ b/src/apps/cli/Cargo.toml
@@ -30,8 +30,10 @@ path = "tests/terminal_process_contracts.rs"
 
 [dependencies]
 # Internal crates
-bitfun-core = { path = "../../crates/assembly/core", default-features = false, features = [
+bitfun-core = { path = "../../crates/assembly/core", features = [
     "agent-runtime",
+    "document-read",
+    "subscription-auth",
     "remote-connect",
     "deep-research",
     "lsp",
@@ -50,14 +52,14 @@ bitfun-core = { path = "../../crates/assembly/core", default-features = false, f
 ] }
 bitfun-events = { path = "../../crates/contracts/events" }
 bitfun-core-types = { path = "../../crates/contracts/core-types" }
-bitfun-acp = { path = "../../crates/interfaces/acp" }
-bitfun-agent-runtime = { path = "../../crates/execution/agent-runtime" }
+bitfun-acp = { path = "../../crates/interfaces/acp", default-features = false, features = ["client", "server"] }
+bitfun-agent-runtime = { path = "../../crates/execution/agent-runtime", features = ["agent-runtime"] }
 bitfun-agent-runtime-ipc = { path = "../../crates/adapters/agent-runtime-ipc" }
-bitfun-runtime-ports = { path = "../../crates/contracts/runtime-ports" }
+bitfun-runtime-ports = { path = "../../crates/contracts/runtime-ports", features = ["agent-api", "git-port", "permission", "plugin-runtime", "workspace-ports"] }
 bitfun-runtime-services = { path = "../../crates/execution/runtime-services" }
-bitfun-services-core = { path = "../../crates/services/services-core", default-features = false, features = ["dispatch-workspace", "local-storage", "process-runtime", "runtime-ownership"] }
+bitfun-services-core = { path = "../../crates/services/services-core", features = ["dispatch-workspace", "local-storage", "process-runtime", "runtime-ownership"] }
 bitfun-agent-tools = { path = "../../crates/execution/tool-contracts" }
-bitfun-product-domains = { path = "../../crates/contracts/product-domains", default-features = false, features = ["external-sources"] }
+bitfun-product-domains = { path = "../../crates/contracts/product-domains", features = ["external-sources"] }
 bitfun-app-server = { path = "../../crates/interfaces/app-server" }
 bitfun-app-server-client = { path = "../../crates/interfaces/app-server-client" }
 bitfun-app-server-protocol = { path = "../../crates/interfaces/app-server-protocol" }
@@ -76,7 +78,6 @@ toml = { workspace = true }
 # Session management
 uuid = { workspace = true }
 chrono = { workspace = true }
-dashmap = { workspace = true }
 
 # Async trait
 async-trait = { workspace = true }
@@ -95,7 +96,6 @@ similar = { workspace = true }
 
 # Syntax highlighting for code blocks and tool cards
 syntect = { workspace = true }
-syntect-tui = { workspace = true }
 
 # Lazy initialization for syntax highlighter singleton
 once_cell = { workspace = true }
@@ -119,7 +119,7 @@ fs2 = { workspace = true }
 base64 = { workspace = true }
 image = { workspace = true }
 minisign-verify = "0.2"
-reqwest = { workspace = true, features = ["rustls"] }
+reqwest = { workspace = true, features = ["http2", "rustls", "stream"] }
 sha2 = { workspace = true }
 tar = { workspace = true }
 tempfile = "3"
diff --git a/src/apps/cli/src/agent/runtime_client.rs b/src/apps/cli/src/agent/runtime_client.rs
index 369677501a..906a667ffc 100644
--- a/src/apps/cli/src/agent/runtime_client.rs
+++ b/src/apps/cli/src/agent/runtime_client.rs
@@ -13,8 +13,8 @@ use tokio::sync::{broadcast, Mutex};
 
 use bitfun_agent_runtime::sdk::{
     AgentDialogSteerRequest, AgentDialogTurnExecution, AgentDialogTurnRequest, AgentEventReceiver,
-    AgentInputAttachment, AgentLocalCommandTurnRecordRequest,
-    AgentMessageWorkspaceReferencesRequest, AgentRuntime, AgentSessionCompactionRequest,
+    AgentInputAttachment, AgentMessageWorkspaceReferencesRequest, AgentRuntime,
+    AgentSessionCompactionRequest,
     AgentSessionCreateRequest, AgentSessionDeleteRequest, AgentSessionForkBeforeTurnRequest,
     AgentSessionForkRequest, AgentSessionForkResult, AgentSessionLineageCancellationRequest,
     AgentSessionLineageInspection, AgentSessionLineageRequest, AgentSessionLineageSnapshot,
@@ -485,17 +485,6 @@ impl ExecAgentRuntimeClient {
         }
     }
 
-    pub(crate) async fn record_completed_local_command_turn(
-        &self,
-        request: AgentLocalCommandTurnRecordRequest,
-    ) -> Result<()> {
-        self.embedded_runtime("recording local command turns")?
-            .record_completed_local_command_turn(request)
-            .await
-            .map(|_| ())
-            .map_err(|error| anyhow::anyhow!(error.into_message()))
-    }
-
     pub(crate) fn set_approval_policy(&self, policy: CliApprovalPolicy) {
         *self
             .approval_policy
@@ -1543,6 +1532,9 @@ impl ExecAgentRuntimeClient {
             turn_id: turn_id.clone(),
             content,
             display_content,
+            // The CLI steer prompt is text; attachments ride turn submissions.
+            attachments: Vec::new(),
+            metadata: serde_json::Map::new(),
         };
 
         match &self.backend {
diff --git a/src/apps/cli/src/agent/tui_client.rs b/src/apps/cli/src/agent/tui_client.rs
index 7c85d763d0..527508dfd5 100644
--- a/src/apps/cli/src/agent/tui_client.rs
+++ b/src/apps/cli/src/agent/tui_client.rs
@@ -33,17 +33,17 @@ use bitfun_product_domains::tool_permissions::{
 use bitfun_runtime_ports::{
     put_agent_workspace_references, AgentContextReloadRequest, AgentDialogSteerRequest,
     AgentDialogTurnExecution, AgentDialogTurnRequest, AgentInputAttachment,
-    AgentLocalCommandTurnRecordRequest, AgentMessageWorkspaceReferencesRequest,
-    AgentSessionCompactionRequest, AgentSessionCreateRequest, AgentSessionDeleteRequest,
-    AgentSessionLineageCancellationRequest, AgentSessionLineageInspection,
-    AgentSessionLineageRequest, AgentSessionLineageSnapshot, AgentSessionLineageTranscriptRequest,
-    AgentSessionListRequest, AgentSessionModeUpdateRequest, AgentSessionModelUpdateRequest,
-    AgentSessionRenameRequest, AgentSessionRevertRequest, AgentSessionRevertResult,
-    AgentSessionSummary, AgentSessionUsageRequest, AgentSessionWorkspaceBinding,
-    AgentSubmissionSource, AgentTurnCancellationRequest, AgentTurnCancellationResult,
-    AgentTurnSettlementRequest, AgentUserShellCommandRequest, AgentWorkspaceReference,
-    AgentWorkspaceReferenceSearchRequest, AgentWorkspaceReferenceSearchResult,
-    DialogSubmissionPolicy, SessionExecutionTarget, SessionTranscript, WorkspaceDiffSnapshot,
+    AgentMessageWorkspaceReferencesRequest, AgentSessionCompactionRequest,
+    AgentSessionCreateRequest, AgentSessionDeleteRequest, AgentSessionLineageCancellationRequest,
+    AgentSessionLineageInspection, AgentSessionLineageRequest, AgentSessionLineageSnapshot,
+    AgentSessionLineageTranscriptRequest, AgentSessionListRequest, AgentSessionModeUpdateRequest,
+    AgentSessionModelUpdateRequest, AgentSessionRenameRequest, AgentSessionRevertRequest,
+    AgentSessionRevertResult, AgentSessionSummary, AgentSessionUsageRequest,
+    AgentSessionWorkspaceBinding, AgentSubmissionSource, AgentTurnCancellationRequest,
+    AgentTurnCancellationResult, AgentTurnSettlementRequest, AgentUserShellCommandRequest,
+    AgentWorkspaceReference, AgentWorkspaceReferenceSearchRequest,
+    AgentWorkspaceReferenceSearchResult, DialogSubmissionPolicy, SessionExecutionTarget,
+    SessionTranscript, WorkspaceDiffSnapshot,
 };
 use tokio::sync::{broadcast, Mutex};
 
@@ -769,16 +769,6 @@ impl TuiAgentClient {
         Ok(())
     }
 
-    pub(crate) async fn record_completed_local_command_turn(
-        &self,
-        request: AgentLocalCommandTurnRecordRequest,
-    ) -> Result<()> {
-        self.backend
-            .record_local_command_turn(RecordLocalCommandTurnRequest(request))
-            .await?;
-        Ok(())
-    }
-
     pub(crate) fn set_approval_policy(&self, policy: CliApprovalPolicy) {
         *self
             .approval_policy
@@ -1368,7 +1358,7 @@ impl TuiAgentClient {
             .map_err(|error| anyhow::anyhow!(error.message))?;
         let result = self
             .backend
-            .submit_dialog_turn(SubmitDialogTurnRequest(AgentDialogTurnRequest {
+            .submit_dialog_turn(SubmitDialogTurnRequest::from(AgentDialogTurnRequest {
                 session_id: session_id.clone(),
                 message,
                 original_message,
@@ -1429,6 +1419,8 @@ impl TuiAgentClient {
                 turn_id,
                 content,
                 display_content,
+                attachments: Vec::new(),
+                metadata: serde_json::Map::new(),
             }))
             .await?
             .steering_id)
diff --git a/src/apps/cli/src/dispatch/mod.rs b/src/apps/cli/src/dispatch/mod.rs
index 5e200aea92..3e5ff86bc1 100644
--- a/src/apps/cli/src/dispatch/mod.rs
+++ b/src/apps/cli/src/dispatch/mod.rs
@@ -387,7 +387,9 @@ fn answer(request: DispatchAnswerRequest) -> Result<DispatchAnswerResponse> {
 }
 
 fn append(request: DispatchAppendRequest) -> Result<DispatchAppendResponse> {
-    if request.content.trim().is_empty() {
+    // An attachment-only message is a real message; only one with neither text
+    // nor attachments is empty.
+    if request.content.trim().is_empty() && request.attachments.is_empty() {
         bail!("dispatch appended message cannot be empty");
     }
     let total_bytes = request
@@ -397,6 +399,7 @@ fn append(request: DispatchAppendRequest) -> Result<DispatchAppendResponse> {
     if total_bytes > MAX_DISPATCH_TEXT_BYTES {
         bail!("dispatch appended message exceeds the 32 KiB request limit");
     }
+    validate_attachments(&request.attachments)?;
     let message_id = request.message_id.clone();
     let store = DispatchStore::open_default()?;
     let accepted = store.enqueue_append_message(request)?;
diff --git a/src/apps/cli/src/dispatch/protocol.rs b/src/apps/cli/src/dispatch/protocol.rs
index 18ad8719d5..9deaea7e34 100644
--- a/src/apps/cli/src/dispatch/protocol.rs
+++ b/src/apps/cli/src/dispatch/protocol.rs
@@ -165,6 +165,10 @@ pub(crate) struct DispatchAppendRequest {
     pub(crate) content: String,
     #[serde(default)]
     pub(crate) display_content: Option<String>,
+    /// Attachments injected into the running turn with the message. An older
+    /// controller omits the field entirely, which decodes to an empty list.
+    #[serde(default)]
+    pub(crate) attachments: Vec<DispatchAttachment>,
 }
 
 #[derive(Clone, Debug, Serialize, PartialEq, Eq)]
diff --git a/src/apps/cli/src/dispatch/runner.rs b/src/apps/cli/src/dispatch/runner.rs
index 0f4eec6aca..a5f115ddec 100644
--- a/src/apps/cli/src/dispatch/runner.rs
+++ b/src/apps/cli/src/dispatch/runner.rs
@@ -220,13 +220,55 @@ pub(crate) fn process_alive(pid: u32) -> bool {
         return false;
     };
     // SAFETY: signal 0 performs liveness/permission checking only.
-    if unsafe { libc::kill(pid, 0) } == 0 {
-        return true;
+    if unsafe { libc::kill(pid, 0) } != 0
+        && !matches!(
+            std::io::Error::last_os_error().raw_os_error(),
+            Some(libc::EPERM)
+        )
+    {
+        return false;
+    }
+
+    #[cfg(target_os = "linux")]
+    {
+        // A zombie still answers to kill(0), but it has already exited and
+        // must not be treated as an authenticated leader for escalation.
+        if let Ok(stat) = std::fs::read_to_string(format!("/proc/{pid}/stat")) {
+            if stat
+                .rsplit_once(") ")
+                .and_then(|(_, fields)| fields.split_whitespace().next())
+                == Some("Z")
+            {
+                return false;
+            }
+        }
+    }
+
+    #[cfg(target_os = "macos")]
+    {
+        // macOS also reports zombies as present to kill(0). Query the process
+        // state before using a leader PID to authenticate SIGKILL escalation;
+        // a failed/empty query means the process disappeared during the check.
+        let output = Command::new("ps")
+            .args(["-p", &pid.to_string(), "-o", "stat="])
+            .output();
+        let Ok(output) = output else {
+            return false;
+        };
+        if !output.status.success() {
+            return false;
+        }
+        return String::from_utf8_lossy(&output.stdout)
+            .trim_start()
+            .chars()
+            .next()
+            .is_some_and(|state| state != 'Z');
+    }
+
+    #[cfg(not(target_os = "macos"))]
+    {
+        true
     }
-    matches!(
-        std::io::Error::last_os_error().raw_os_error(),
-        Some(libc::EPERM)
-    )
 }
 
 #[cfg(not(unix))]
diff --git a/src/apps/cli/src/dispatch/store.rs b/src/apps/cli/src/dispatch/store.rs
index 8ad9dcd157..02b594f0b8 100644
--- a/src/apps/cli/src/dispatch/store.rs
+++ b/src/apps/cli/src/dispatch/store.rs
@@ -2522,6 +2522,7 @@ mod tests {
             message_id: "message-1".to_string(),
             content: "Continue with tests".to_string(),
             display_content: None,
+            attachments: Vec::new(),
         };
 
         assert!(store
diff --git a/src/apps/cli/src/dispatch/worker.rs b/src/apps/cli/src/dispatch/worker.rs
index 2a6679bce0..c37cbf41a8 100644
--- a/src/apps/cli/src/dispatch/worker.rs
+++ b/src/apps/cli/src/dispatch/worker.rs
@@ -505,6 +505,8 @@ async fn process_mailboxes(
                 turn_id: turn_id.to_string(),
                 content: request.content.clone(),
                 display_content: request.display_content.clone(),
+                attachments: runtime_attachments(&request.attachments),
+                metadata: serde_json::Map::new(),
             })
             .await
             .map_err(|error| anyhow!(error.into_message()))
diff --git a/src/apps/cli/src/modes/chat.rs b/src/apps/cli/src/modes/chat.rs
index 82aa7d6513..bba902a043 100644
--- a/src/apps/cli/src/modes/chat.rs
+++ b/src/apps/cli/src/modes/chat.rs
@@ -23,10 +23,9 @@ use tokio::sync::broadcast::error::TryRecvError;
 use bitfun_app_server_protocol::model::{AddModelRequest, UpdateModelRequest};
 use bitfun_app_server_protocol::skill::SkillSummary;
 use bitfun_app_server_protocol::subagent::SubagentSummary;
-use bitfun_core_types::SessionUsageReport;
 use bitfun_events::{AgenticEvent, ToolEventData, ToolEventIdentity};
 use bitfun_runtime_ports::{
-    AgentLocalCommandTurnRecordRequest, AgentSessionComposerUpdate, AgentSessionLineageEntry,
+    AgentSessionComposerUpdate, AgentSessionLineageEntry,
     AgentSessionLineageInspection, AgentSessionLineageSnapshot, AgentSessionUsageRequest,
     AgentTurnCancellationResult, AgentWorkspaceReferenceSearchResult, SessionTranscript,
     WorkspaceDiffSnapshot,
diff --git a/src/apps/cli/src/modes/chat/selection.rs b/src/apps/cli/src/modes/chat/selection.rs
index 4435319964..d9048ee44f 100644
--- a/src/apps/cli/src/modes/chat/selection.rs
+++ b/src/apps/cli/src/modes/chat/selection.rs
@@ -92,20 +92,6 @@ fn apply_agent_mode_feedback(
     }
 }
 
-fn usage_report_metadata(report: &SessionUsageReport) -> Result<serde_json::Value> {
-    let usage_report = serde_json::to_value(report)
-        .map_err(|error| anyhow!("Failed to serialize usage report: {error}"))?;
-    Ok(serde_json::json!({
-        "localCommandKind": "usage_report",
-        "reportId": report.report_id,
-        "schemaVersion": report.schema_version,
-        "generatedAt": report.generated_at,
-        "modelVisible": false,
-        "usageReport": usage_report,
-        "usageReportStatus": "completed",
-    }))
-}
-
 fn apply_model_selection_feedback(
     chat_state: &mut ChatState,
     selected_display_name: &str,
@@ -252,6 +238,17 @@ impl ChatMode {
             .or_else(|| Some(self.agent.workspace_path_string()));
         let agent = self.agent.clone();
 
+        /*
+         * Rendered into the conversation view and nowhere else. A report about
+         * a session is not an event in it, and this used to write one as a
+         * `local_command` Turn as well — which the desktop then loaded from
+         * disk and gave a numbered slot in its Turn rail, because the ordinals
+         * come from the backend catalog and the catalog counts what is stored.
+         *
+         * `add_assistant_message` is already the UI-only path: `turn_id: None`,
+         * never persisted, never in model context. In a terminal the scrollback
+         * is the record, so nothing here needs to replace what is being removed.
+         */
         let report_result: Result<bitfun_core::service::session_usage::SessionUsageReport> =
             tokio::task::block_in_place(|| {
                 let session_id = session_id.clone();
@@ -262,39 +259,21 @@ impl ChatMode {
                         .filter(|path| !path.trim().is_empty())
                         .ok_or_else(|| anyhow!("Workspace path is required for usage reports"))?;
 
-                    let report = agent
+                    agent
                         .generate_session_usage_report(AgentSessionUsageRequest {
-                            session_id: session_id.clone(),
+                            session_id,
                             workspace_path: Some(workspace_path),
                             remote_connection_id: None,
                             remote_ssh_host: None,
                             include_hidden_subagents: true,
                         })
-                        .await?;
-
-                    let markdown = render_usage_report_markdown(&report);
-                    let generated_at = u64::try_from(report.generated_at).unwrap_or_default();
-                    let metadata = usage_report_metadata(&report)?;
-                    agent
-                        .record_completed_local_command_turn(AgentLocalCommandTurnRecordRequest {
-                            session_id,
-                            content: markdown,
-                            turn_id: Some(format!("local-usage-{}", report.report_id)),
-                            timestamp_ms: Some(generated_at),
-                            metadata: metadata.as_object().cloned().ok_or_else(|| {
-                                anyhow!("Usage report metadata must be an object")
-                            })?,
-                        })
-                        .await?;
-
-                    Ok(report)
+                        .await
                 })
             });
 
         match report_result {
             Ok(report) => {
-                let markdown = render_usage_report_markdown(&report);
-                chat_state.add_assistant_message(markdown);
+                chat_state.add_assistant_message(render_usage_report_markdown(&report));
                 chat_view.set_status(Some("Usage report added to conversation".to_string()));
             }
             Err(error) => {
@@ -857,10 +836,7 @@ fn session_update_unavailable_message(setting_name: &str, is_processing: bool) -
 
 #[cfg(test)]
 mod usage_metadata_tests {
-    use super::{
-        session_update_allowed, session_update_unavailable_message, usage_report_metadata,
-        SessionUsageReport,
-    };
+    use super::{session_update_allowed, session_update_unavailable_message};
 
     #[test]
     fn session_update_is_rechecked_when_an_idle_popup_outlives_turn_start() {
@@ -878,21 +854,4 @@ mod usage_metadata_tests {
             "Agent mode cannot be changed during the current turn."
         );
     }
-
-    #[test]
-    fn usage_metadata_preserves_the_existing_tui_transcript_schema() {
-        let mut report = SessionUsageReport::partial_unavailable("session-1", 1_778_347_200_000);
-        report.report_id = "usage-session-1-1778347200000".to_string();
-
-        let metadata = usage_report_metadata(&report).expect("usage metadata");
-
-        assert_eq!(metadata["localCommandKind"], "usage_report");
-        assert_eq!(metadata["reportId"], report.report_id);
-        assert_eq!(metadata["schemaVersion"], report.schema_version);
-        assert_eq!(metadata["generatedAt"], report.generated_at);
-        assert_eq!(metadata["modelVisible"], false);
-        assert_eq!(metadata["usageReportStatus"], "completed");
-        assert_eq!(metadata["usageReport"]["sessionId"], "session-1");
-        assert_eq!(metadata.as_object().map(serde_json::Map::len), Some(7));
-    }
 }
diff --git a/src/apps/cli/src/peer_host/args.rs b/src/apps/cli/src/peer_host/args.rs
index 25704eace1..cf282ab428 100644
--- a/src/apps/cli/src/peer_host/args.rs
+++ b/src/apps/cli/src/peer_host/args.rs
@@ -34,17 +34,6 @@ pub(crate) fn optional_bool(obj: &Value, camel: &str) -> Option<bool> {
     field(obj, camel, &snake).and_then(|v| v.as_bool())
 }
 
-pub(crate) fn get_usize(obj: &Value, camel: &str) -> Result<usize, String> {
-    let snake = camel_to_snake(camel);
-    let value =
-        field(obj, camel, &snake).ok_or_else(|| format!("Missing or invalid '{camel}' field"))?;
-    value
-        .as_u64()
-        .map(|n| n as usize)
-        .or_else(|| value.as_i64().filter(|n| *n >= 0).map(|n| n as usize))
-        .ok_or_else(|| format!("Missing or invalid '{camel}' field"))
-}
-
 fn camel_to_snake(camel: &str) -> String {
     let mut out = String::with_capacity(camel.len() + 4);
     for (i, ch) in camel.chars().enumerate() {
diff --git a/src/apps/cli/src/peer_host/commands/external_sources.rs b/src/apps/cli/src/peer_host/commands/external_sources.rs
index 07c9ff545a..0a335ad12b 100644
--- a/src/apps/cli/src/peer_host/commands/external_sources.rs
+++ b/src/apps/cli/src/peer_host/commands/external_sources.rs
@@ -6,12 +6,14 @@ use bitfun_core::external_sources::{
     apply_external_source_control_action, choose_external_mcp_conflict,
     choose_external_subagent_conflict, external_source_snapshot,
     get_external_source_control_snapshot, set_external_mcp_server_decision,
-    set_external_prompt_command_conflict_choice, set_external_source_enabled,
-    set_external_subagent_activation, set_external_subagent_model_binding,
+    set_external_mcp_servers_enabled, set_external_prompt_command_conflict_choice,
+    set_external_source_enabled, set_external_subagent_activation,
+    set_external_subagent_model_binding, set_external_subagents_enabled,
     set_external_tool_conflict_choice, set_external_tool_target_decision,
-    update_external_integration_policy, ExternalIntegrationPolicyMutation,
-    ExternalSourceControlRequestV1, ExternalSourceHostCapabilities, ExternalSourceOperationError,
-    ExternalSourceOperationErrorCode, ExternalSourceOperationResult, ExternalSourcePublicSnapshot,
+    set_external_tool_targets_enabled, update_external_integration_policy,
+    ExternalIntegrationPolicyMutation, ExternalSourceControlRequestV1,
+    ExternalSourceHostCapabilities, ExternalSourceOperationError, ExternalSourceOperationErrorCode,
+    ExternalSourceOperationResult, ExternalSourcePublicSnapshot,
     ExternalSubagentModelBindingTarget,
 };
 use serde_json::Value;
@@ -60,6 +62,28 @@ fn required_u64(request: &Value, key: &str) -> ExternalSourceOperationResult<u64
     })
 }
 
+fn decision_pairs(
+    request: &Value,
+    first_key: &str,
+    second_key: &str,
+) -> ExternalSourceOperationResult<Vec<(String, String)>> {
+    let decisions = request
+        .get("decisions")
+        .and_then(Value::as_array)
+        .ok_or_else(|| {
+            ExternalSourceOperationError::invalid_request("Missing or invalid 'decisions'")
+        })?;
+    decisions
+        .iter()
+        .map(|decision| {
+            Ok((
+                required_string(decision, first_key)?,
+                required_string(decision, second_key)?,
+            ))
+        })
+        .collect()
+}
+
 fn model_binding_target_field(
     request: &Value,
     key: &str,
@@ -221,6 +245,16 @@ async fn dispatch_inner(
             )
             .await
         }
+        "set_external_tool_targets_enabled_command" => {
+            set_external_tool_targets_enabled(
+                workspace,
+                decision_pairs(request, "approvalKey", "decisionKey")?,
+                required_bool(request, "enabled")?,
+                required_u64(request, "expectedCatalogGeneration")?,
+                required_u64(request, "expectedPreferenceRevision")?,
+            )
+            .await
+        }
         "set_external_tool_conflict_choice_command" => {
             set_external_tool_conflict_choice(
                 workspace,
@@ -241,6 +275,16 @@ async fn dispatch_inner(
             )
             .await
         }
+        "set_external_subagents_enabled_command" => {
+            set_external_subagents_enabled(
+                workspace,
+                decision_pairs(request, "candidateId", "decisionKey")?,
+                required_bool(request, "enabled")?,
+                required_u64(request, "expectedSubagentGeneration")?,
+                required_u64(request, "expectedPreferenceRevision")?,
+            )
+            .await
+        }
         "set_external_subagent_model_binding_command" => {
             set_external_subagent_model_binding(
                 workspace,
@@ -273,6 +317,16 @@ async fn dispatch_inner(
             )
             .await
         }
+        "set_external_mcp_servers_enabled_command" => {
+            set_external_mcp_servers_enabled(
+                workspace,
+                decision_pairs(request, "candidateId", "decisionKey")?,
+                required_bool(request, "enabled")?,
+                required_u64(request, "expectedMcpGeneration")?,
+                required_u64(request, "expectedPreferenceRevision")?,
+            )
+            .await
+        }
         "choose_external_mcp_conflict_command" => {
             choose_external_mcp_conflict(
                 workspace,
@@ -395,4 +449,22 @@ mod tests {
             ExternalSourceOperationErrorCode::InvalidRequest
         );
     }
+
+    #[test]
+    fn peer_bulk_decisions_preserve_the_reviewed_identity_pairs() {
+        let request = serde_json::json!({
+            "decisions": [
+                { "candidateId": "agent-a", "decisionKey": "decision-a" },
+                { "candidateId": "agent-b", "decisionKey": "decision-b" }
+            ]
+        });
+
+        assert_eq!(
+            decision_pairs(&request, "candidateId", "decisionKey").unwrap(),
+            vec![
+                ("agent-a".to_string(), "decision-a".to_string()),
+                ("agent-b".to_string(), "decision-b".to_string()),
+            ]
+        );
+    }
 }
diff --git a/src/apps/cli/src/peer_host/commands/mod.rs b/src/apps/cli/src/peer_host/commands/mod.rs
index 5f45ea6875..f75a74f8fc 100644
--- a/src/apps/cli/src/peer_host/commands/mod.rs
+++ b/src/apps/cli/src/peer_host/commands/mod.rs
@@ -46,11 +46,14 @@ pub(crate) async fn dispatch(
         | "set_external_source_enabled_command"
         | "set_external_source_conflict_choice_command"
         | "set_external_tool_target_decision_command"
+        | "set_external_tool_targets_enabled_command"
         | "set_external_tool_conflict_choice_command"
         | "set_external_subagent_activation_command"
+        | "set_external_subagents_enabled_command"
         | "set_external_subagent_model_binding_command"
         | "choose_external_subagent_conflict_command"
         | "set_external_mcp_server_decision_command"
+        | "set_external_mcp_servers_enabled_command"
         | "choose_external_mcp_conflict_command"
         | "update_external_integration_policy_command" => {
             external_sources::dispatch(command, args, state).await
@@ -91,7 +94,7 @@ pub(crate) async fn dispatch(
         "save_session_turn" => session::save_session_turn(state, args).await,
 
         // Snapshot / rollback
-        "rollback_to_turn" => snapshot::rollback_to_turn(state, args).await,
+        "rollback_session_to_turn" => snapshot::rollback_session_to_turn(state, args).await,
         "get_session_files" => snapshot::get_session_files(state, args).await,
 
         // Dialog / tools
diff --git a/src/apps/cli/src/peer_host/commands/session.rs b/src/apps/cli/src/peer_host/commands/session.rs
index f8ac8f11ba..ec4e1fa345 100644
--- a/src/apps/cli/src/peer_host/commands/session.rs
+++ b/src/apps/cli/src/peer_host/commands/session.rs
@@ -796,7 +796,7 @@ mod tests {
 
         let snapshot_source = include_str!("snapshot.rs");
         let rollback = snapshot_source
-            .split_once("pub(crate) async fn rollback_to_turn")
+            .split_once("pub(crate) async fn rollback_session_to_turn")
             .expect("Peer rollback")
             .1
             .split_once("#[cfg(test)]")
diff --git a/src/apps/cli/src/peer_host/commands/snapshot.rs b/src/apps/cli/src/peer_host/commands/snapshot.rs
index f6a25c2b12..cc3084a809 100644
--- a/src/apps/cli/src/peer_host/commands/snapshot.rs
+++ b/src/apps/cli/src/peer_host/commands/snapshot.rs
@@ -1,20 +1,16 @@
 //! Snapshot / rollback HostInvoke handlers for CLI Peer Host.
 
-use std::collections::HashSet;
 use std::path::PathBuf;
 
 use serde_json::{json, Value};
 
 use bitfun_core::service::remote_ssh::workspace_state::is_remote_path;
 use bitfun_runtime_ports::{
-    LocalWorkspaceSnapshotPort, LocalWorkspaceSnapshotSessionRequest, LocalWorkspaceSnapshotStats,
-    LocalWorkspaceSnapshotTurnRequest, PortError, PortErrorKind,
+    AgentSessionRollbackToTurnRequest, LocalWorkspaceSnapshotPort,
+    LocalWorkspaceSnapshotSessionRequest, LocalWorkspaceSnapshotStats, PortError, PortErrorKind,
 };
 
-use crate::peer_host::args::{
-    get_string, get_usize, optional_bool, optional_string, request_value,
-};
-use crate::peer_host::fanout::fanout_peer_device_event;
+use crate::peer_host::args::{get_string, optional_string, request_value};
 use crate::peer_host::state::PeerHostState;
 
 use super::session::{ensure_session_workspace_runtime_ownership, resolved_session_storage_scope};
@@ -97,63 +93,6 @@ pub(super) async fn local_snapshot_session_stats(
     })
 }
 
-async fn rollback_local_workspace_files(
-    port: &dyn LocalWorkspaceSnapshotPort,
-    workspace_path: PathBuf,
-    session_id: String,
-    turn_index: usize,
-) -> Result<Vec<PathBuf>, String> {
-    port.rollback_workspace_files_to_turn(LocalWorkspaceSnapshotTurnRequest {
-        workspace_path,
-        session_id,
-        turn_index,
-    })
-    .await
-    .map_err(|error| {
-        format!(
-            "Failed to rollback turn: {}",
-            snapshot_compatibility_error(error)
-        )
-    })
-}
-
-fn history_rollback_partial_failure(error: impl std::fmt::Display) -> String {
-    format!(
-        "Workspace files were rolled back, but session history rollback failed. Reload the session before retrying: {error}"
-    )
-}
-
-fn rollback_device_events(
-    session_id: &str,
-    turn_index: usize,
-    files_count: usize,
-    delete_turns: bool,
-    deleted_turns_count: usize,
-) -> Vec<(String, Value)> {
-    let mut events = Vec::with_capacity(if delete_turns { 2 } else { 1 });
-    if delete_turns {
-        events.push((
-            "conversation_turns_deleted".to_string(),
-            json!({
-                "session_id": session_id,
-                "remaining_turns": turn_index,
-                "deleted_count": deleted_turns_count,
-            }),
-        ));
-    }
-    events.push((
-        "turn_rolled_back".to_string(),
-        json!({
-            "session_id": session_id,
-            "turn_index": turn_index,
-            "files_count": files_count,
-            "deleted_turns": delete_turns,
-            "deleted_turns_count": deleted_turns_count,
-        }),
-    ));
-    events
-}
-
 pub(crate) async fn get_session_files(
     state: &PeerHostState,
     args: &Value,
@@ -185,125 +124,24 @@ pub(crate) async fn get_session_files(
         .collect::<Vec<_>>()))
 }
 
-pub(crate) async fn rollback_to_turn(state: &PeerHostState, args: &Value) -> Result<Value, String> {
+pub(crate) async fn rollback_session_to_turn(
+    state: &PeerHostState,
+    args: &Value,
+) -> Result<Value, String> {
     let request = request_value(args);
-    let session_id = get_string(request, "sessionId")?;
-    let workspace_path = get_string(request, "workspacePath")?;
-    let turn_index = get_usize(request, "turnIndex")?;
-    let delete_turns = optional_bool(request, "deleteTurns").unwrap_or(false);
-
-    bitfun_agent_runtime::session_control::validate_session_id(&session_id)?;
-    require_complete_rollback_workspace(request, &workspace_path).await?;
-    let workspace = PathBuf::from(&workspace_path);
-    let scope = ensure_session_workspace_runtime_ownership(state, request)?;
-    let session_storage_path = resolved_session_storage_scope(state, scope).await?;
-    state
-        .compatibility
-        .ensure_session_loaded_from_storage_path(&session_storage_path, &session_id, false)
-        .await
-        .map_err(|error| format!("Failed to load session before rollback: {error}"))?;
-    let maintenance = state
-        .compatibility
-        .begin_session_maintenance(&session_storage_path, &session_id, 2_000)
-        .await
-        .map_err(|error| format!("Failed to quiesce session before rollback: {error}"))?;
-    let mut descendant_cancellation = state.turns.session_turns_for_cancellation(&session_id);
-    descendant_cancellation
-        .turns
-        .retain(|turn| turn.session_id != session_id);
-    state
-        .cancel_peer_turns(descendant_cancellation, "Peer session rollback")
-        .await
-        .map_err(|error| format!("Failed to cancel Peer descendants before rollback: {error}"))?;
-    state.turns.drain_session_turns(&session_id);
-
-    let mutation = state
-        .compatibility
-        .begin_persisted_session_mutation(&session_storage_path, &session_id)
-        .await
-        .map_err(|error| format!("Failed to lock session rollback: {error}"))?;
-    state
-        .compatibility
-        .commit_session_revert_before_snapshot_mutation(&mutation)
+    let rollback_request: AgentSessionRollbackToTurnRequest =
+        serde_json::from_value(request.clone())
+            .map_err(|error| format!("Invalid targeted Session rollback request: {error}"))?;
+
+    bitfun_agent_runtime::session_control::validate_session_id(&rollback_request.session_id)?;
+    require_complete_rollback_workspace(request, &rollback_request.workspace_path).await?;
+    ensure_session_workspace_runtime_ownership(state, request)?;
+    let outcome = state
+        .agent_runtime
+        .rollback_session_to_turn(rollback_request)
         .await
-        .map_err(|error| {
-            format!("Failed to commit the staged Session undo before rollback: {error}")
-        })?;
-
-    let rolled_back_parent_turn_ids = if delete_turns {
-        let turns = state
-            .compatibility
-            .load_persisted_session_turns_for_mutation(&mutation, None)
-            .await
-            .map_err(|error| format!("Failed to load turns before rollback: {error}"))?;
-        state
-            .compatibility
-            .validate_persisted_session_context_rollback(&mutation, turn_index)
-            .await
-            .map_err(|error| format!("Failed to validate session rollback: {error}"))?;
-        turns
-            .into_iter()
-            .filter(|turn| turn.turn_index >= turn_index)
-            .map(|turn| turn.turn_id)
-            .collect::<HashSet<_>>()
-    } else {
-        HashSet::new()
-    };
-
-    let restored_files = rollback_local_workspace_files(
-        state.local_workspace_snapshot.as_ref(),
-        workspace,
-        session_id.clone(),
-        turn_index,
-    )
-    .await?;
-
-    let restored_files_str: Vec<String> = restored_files
-        .iter()
-        .map(|p| p.to_string_lossy().to_string())
-        .collect();
-
-    let deleted_turns_count = rolled_back_parent_turn_ids.len();
-    if delete_turns {
-        if let Err(error) = state
-            .compatibility
-            .rollback_persisted_session_context_to_turn_start(&mutation, turn_index)
-            .await
-        {
-            return Err(history_rollback_partial_failure(error));
-        }
-
-        if !rolled_back_parent_turn_ids.is_empty() {
-            if let Err(error) = state
-                .compatibility
-                .delete_hidden_subagent_sessions_for_parent_turns(
-                    &session_storage_path,
-                    &session_id,
-                    &rolled_back_parent_turn_ids,
-                )
-                .await
-            {
-                tracing::warn!(
-                    "Failed to delete hidden subagent sessions during rollback: session_id={session_id}, turn_index={turn_index}, error={error}"
-                );
-            }
-        }
-    }
-
-    drop(mutation);
-    drop(maintenance);
-
-    for (event_name, payload) in rollback_device_events(
-        &session_id,
-        turn_index,
-        restored_files_str.len(),
-        delete_turns,
-        deleted_turns_count,
-    ) {
-        fanout_peer_device_event(event_name, payload).await;
-    }
-
-    Ok(json!(restored_files_str))
+        .map_err(|error| error.into_message())?;
+    serde_json::to_value(outcome).map_err(|error| error.to_string())
 }
 
 #[cfg(test)]
@@ -320,9 +158,8 @@ mod tests {
     use serde_json::json;
 
     use super::{
-        history_rollback_partial_failure, local_snapshot_session_files,
-        local_snapshot_session_stats, require_complete_rollback_workspace,
-        require_local_snapshot_workspace, rollback_device_events, rollback_local_workspace_files,
+        local_snapshot_session_files, local_snapshot_session_stats,
+        require_complete_rollback_workspace, require_local_snapshot_workspace,
         snapshot_compatibility_error,
     };
 
@@ -330,10 +167,8 @@ mod tests {
     struct RecordingSnapshotPort {
         file_calls: AtomicUsize,
         stats_calls: AtomicUsize,
-        rollback_calls: AtomicUsize,
         file_request: Mutex<Option<LocalWorkspaceSnapshotSessionRequest>>,
         stats_request: Mutex<Option<LocalWorkspaceSnapshotSessionRequest>>,
-        rollback_request: Mutex<Option<LocalWorkspaceSnapshotTurnRequest>>,
     }
 
     #[async_trait::async_trait]
@@ -368,10 +203,8 @@ mod tests {
 
         async fn rollback_workspace_files_to_turn(
             &self,
-            request: LocalWorkspaceSnapshotTurnRequest,
+            _request: LocalWorkspaceSnapshotTurnRequest,
         ) -> PortResult<Vec<PathBuf>> {
-            self.rollback_calls.fetch_add(1, Ordering::SeqCst);
-            *self.rollback_request.lock().expect("rollback request lock") = Some(request);
             Ok(vec![PathBuf::from("restored.txt")])
         }
     }
@@ -404,38 +237,15 @@ mod tests {
 
         let source = include_str!("snapshot.rs");
         let rollback_source = &source[source
-            .find("pub(crate) async fn rollback_to_turn")
+            .find("pub(crate) async fn rollback_session_to_turn")
             .expect("rollback handler must exist")..];
         let remote_guard = rollback_source
-            .find("require_complete_rollback_workspace(request, &workspace_path).await?")
+            .find("require_complete_rollback_workspace(request, &rollback_request.workspace_path)")
             .expect("rollback must have an explicit remote guard");
-        let maintenance = rollback_source
-            .find("begin_session_maintenance")
-            .expect("host-owned maintenance must remain in the rollback flow");
-        let cancellation = rollback_source
-            .find("cancel_peer_turns")
-            .expect("descendant cancellation must remain in the rollback flow");
-        let revert_commit = rollback_source
-            .find("commit_session_revert_before_snapshot_mutation")
-            .expect("staged Session undo must be committed before legacy rollback");
-        let file_rollback = rollback_source
-            .find("rollback_local_workspace_files(")
-            .expect("workspace-file rollback must remain in the rollback flow");
-        let history_rollback = rollback_source
-            .find("rollback_persisted_session_context_to_turn_start")
-            .expect("history rollback must remain in the rollback flow");
-        let event_projection = rollback_source
-            .find("rollback_device_events(")
-            .expect("rollback events must remain host-projected");
-        assert!(
-            remote_guard < maintenance
-                && maintenance < cancellation
-                && cancellation < revert_commit
-                && revert_commit < file_rollback
-                && file_rollback < history_rollback
-                && history_rollback < event_projection,
-            "rollback must preserve remote guard, maintenance, cancellation, files, history, and event order"
-        );
+        let runtime_call = rollback_source
+            .find(".rollback_session_to_turn(")
+            .expect("rollback must delegate to the Agent Session runtime");
+        assert!(remote_guard < runtime_call);
     }
 
     #[tokio::test]
@@ -459,17 +269,10 @@ mod tests {
         )
         .await
         .expect("stats projection should succeed");
-        let restored =
-            rollback_local_workspace_files(&port, workspace.clone(), "session-1".to_string(), 4)
-                .await
-                .expect("rollback projection should succeed");
-
         assert_eq!(port.file_calls.load(Ordering::SeqCst), 1);
         assert_eq!(port.stats_calls.load(Ordering::SeqCst), 1);
-        assert_eq!(port.rollback_calls.load(Ordering::SeqCst), 1);
         assert_eq!(files, vec![PathBuf::from("changed.txt")]);
         assert_eq!(stats.total_changes, 3);
-        assert_eq!(restored, vec![PathBuf::from("restored.txt")]);
         assert_eq!(
             port.file_request
                 .lock()
@@ -488,36 +291,6 @@ mod tests {
                 .max_turn_exclusive,
             Some(2)
         );
-        assert_eq!(
-            port.rollback_request
-                .lock()
-                .expect("rollback request lock")
-                .as_ref()
-                .expect("rollback request")
-                .turn_index,
-            4
-        );
-    }
-
-    #[test]
-    fn rollback_projection_preserves_partial_failure_and_event_order() {
-        assert_eq!(
-            history_rollback_partial_failure("history backend failed"),
-            "Workspace files were rolled back, but session history rollback failed. Reload the session before retrying: history backend failed"
-        );
-
-        let events = rollback_device_events("session-1", 4, 2, true, 3);
-        assert_eq!(events.len(), 2);
-        assert_eq!(events[0].0, "conversation_turns_deleted");
-        assert_eq!(events[0].1["remaining_turns"], 4);
-        assert_eq!(events[0].1["deleted_count"], 3);
-        assert_eq!(events[1].0, "turn_rolled_back");
-        assert_eq!(events[1].1["files_count"], 2);
-        assert_eq!(events[1].1["deleted_turns"], true);
-
-        let file_only = rollback_device_events("session-1", 4, 2, false, 0);
-        assert_eq!(file_only.len(), 1);
-        assert_eq!(file_only[0].0, "turn_rolled_back");
     }
 
     #[test]
diff --git a/src/apps/cli/src/peer_host/control.rs b/src/apps/cli/src/peer_host/control.rs
index af3dcc4b4d..ea795600c5 100644
--- a/src/apps/cli/src/peer_host/control.rs
+++ b/src/apps/cli/src/peer_host/control.rs
@@ -133,6 +133,9 @@ pub(crate) fn peer_mode_ping_value() -> Value {
         "ok": true,
         "peer": true,
         "device_id": device_id,
+        "capabilities": {
+            "targeted_session_rollback": true,
+        },
     })
 }
 
diff --git a/src/apps/cli/src/peer_host/deny.rs b/src/apps/cli/src/peer_host/deny.rs
index 4e6770864c..b4c702e67b 100644
--- a/src/apps/cli/src/peer_host/deny.rs
+++ b/src/apps/cli/src/peer_host/deny.rs
@@ -96,8 +96,18 @@ static LOCAL_ONLY_COMMANDS: &[&str] = &[
     "dispatch_list_jobs",
     "dispatch_answer",
     "dispatch_append",
+    "dispatch_continue",
     "dispatch_load_transcript",
     "dispatch_save_transcript",
+    "speech_list_models",
+    "speech_download_model",
+    "speech_cancel_model_download",
+    "speech_delete_model",
+    "speech_verify_model",
+    "speech_start_input_session",
+    "speech_append_audio_chunk",
+    "speech_finish_input_session",
+    "speech_cancel_input_session",
 ];
 
 /// Desktop IDE surfaces that CLI Peer Host does not implement.
@@ -158,10 +168,30 @@ mod tests {
             "dispatch_list_jobs",
             "dispatch_answer",
             "dispatch_append",
+            "dispatch_continue",
             "dispatch_load_transcript",
             "dispatch_save_transcript",
         ] {
             assert!(is_local_only_command(command), "{command}");
         }
     }
+
+    /// The controller-side FE deny list is an optimization, not the boundary.
+    /// An older or non-FE controller still reaches this host.
+    #[test]
+    fn speech_capture_stays_on_the_controller_device() {
+        for command in [
+            "speech_list_models",
+            "speech_download_model",
+            "speech_cancel_model_download",
+            "speech_delete_model",
+            "speech_verify_model",
+            "speech_start_input_session",
+            "speech_append_audio_chunk",
+            "speech_finish_input_session",
+            "speech_cancel_input_session",
+        ] {
+            assert!(is_local_only_command(command), "{command}");
+        }
+    }
 }
diff --git a/src/apps/cli/src/peer_host/dispatch.rs b/src/apps/cli/src/peer_host/dispatch.rs
index b42e16e6fa..0bb1d26a43 100644
--- a/src/apps/cli/src/peer_host/dispatch.rs
+++ b/src/apps/cli/src/peer_host/dispatch.rs
@@ -161,6 +161,10 @@ mod tests {
                 assert_eq!(value.get("ok"), Some(&json!(true)));
                 assert_eq!(value.get("peer"), Some(&json!(true)));
                 assert!(value.get("device_id").and_then(|v| v.as_str()).is_some());
+                assert_eq!(
+                    value.pointer("/capabilities/targeted_session_rollback"),
+                    Some(&json!(true))
+                );
             }
             other => panic!("unexpected response: {other:?}"),
         }
diff --git a/src/apps/cli/src/peer_host/state.rs b/src/apps/cli/src/peer_host/state.rs
index 8e0cad1f11..a928d7c3ab 100644
--- a/src/apps/cli/src/peer_host/state.rs
+++ b/src/apps/cli/src/peer_host/state.rs
@@ -449,18 +449,6 @@ impl PeerTurnTracker {
             .unwrap_or_default()
     }
 
-    pub(crate) fn session_turns_for_cancellation(&self, session_id: &str) -> PeerTurnDrain {
-        self.inner
-            .lock()
-            .map(|inner| {
-                let keys = session_tree_keys(&inner, session_id);
-                let mut drain = peer_turn_drain_for_keys(&inner, &keys);
-                merge_completed_background_subagents(&inner, &mut drain, Some(session_id));
-                drain
-            })
-            .unwrap_or_default()
-    }
-
     pub(crate) fn interrupt_event_stream(&self, closed: bool) -> PeerTurnDrain {
         let Ok(mut inner) = self.inner.lock() else {
             return PeerTurnDrain::default();
diff --git a/src/apps/cli/src/self_update.rs b/src/apps/cli/src/self_update.rs
index 2224dc8313..56e118a661 100644
--- a/src/apps/cli/src/self_update.rs
+++ b/src/apps/cli/src/self_update.rs
@@ -899,26 +899,33 @@ fn release_pubkey() -> Option<&'static str> {
 }
 
 /// Verify a Tauri-format `.sig` (base64 of a minisign signature file) over the
-/// archive, using the base64-wrapped public key.
+/// archive. The public key accepts both current raw Tauri values and the legacy
+/// base64 wrapper.
 ///
 /// A checksum only proves the transfer was not corrupted: whoever serves the
 /// archive can serve a matching `.sha256`. A signature proves the bytes came
 /// from whoever holds the release key, which is what actually protects the
 /// third-party GitHub proxy and mirror paths.
-fn verify_signature(archive: &[u8], signature_b64: &str, pubkey_b64: &str) -> Result<()> {
+fn verify_signature(archive: &[u8], signature_b64: &str, pubkey: &str) -> Result<()> {
     use base64::Engine as _;
-    let decode = |value: &str, what: &str| -> Result<String> {
+
+    let public_key_text = if pubkey.trim().starts_with("untrusted comment:") {
+        pubkey.trim().to_owned()
+    } else {
         let bytes = base64::engine::general_purpose::STANDARD
-            .decode(value.trim().as_bytes())
-            .with_context(|| format!("decode {what}"))?;
-        String::from_utf8(bytes).with_context(|| format!("decode {what} as UTF-8"))
+            .decode(pubkey.trim().as_bytes())
+            .context("decode release public key")?;
+        String::from_utf8(bytes).context("decode release public key as UTF-8")?
     };
-
-    let public_key = minisign_verify::PublicKey::decode(&decode(pubkey_b64, "release public key")?)
+    let public_key = minisign_verify::PublicKey::decode(&public_key_text)
         .map_err(|error| anyhow!("invalid release public key: {error}"))?;
-    let signature =
-        minisign_verify::Signature::decode(&decode(signature_b64, "release signature")?)
-            .map_err(|error| anyhow!("invalid release signature: {error}"))?;
+    let signature_bytes = base64::engine::general_purpose::STANDARD
+        .decode(signature_b64.trim().as_bytes())
+        .context("decode release signature")?;
+    let signature_text =
+        String::from_utf8(signature_bytes).context("decode release signature as UTF-8")?;
+    let signature = minisign_verify::Signature::decode(&signature_text)
+        .map_err(|error| anyhow!("invalid release signature: {error}"))?;
     public_key
         .verify(archive, &signature, false)
         .map_err(|error| anyhow!("release signature does not match the archive: {error}"))
@@ -1128,7 +1135,7 @@ fn is_newer_version(candidate: &str, current: &str) -> bool {
 
 fn automatic_update_is_eligible() -> bool {
     if std::env::var_os("BITFUN_CLI_DISABLE_AUTO_UPDATE").is_some()
-        || env!("CARGO_PKG_VERSION").contains("-nightly.")
+        || !release_version_allows_automatic_update(env!("CARGO_PKG_VERSION"))
     {
         return false;
     }
@@ -1137,6 +1144,10 @@ fn automatic_update_is_eligible() -> bool {
         .is_some_and(|path| current_platform_key().is_some() && !is_development_binary(&path))
 }
 
+fn release_version_allows_automatic_update(version: &str) -> bool {
+    !version.contains("-nightly.") && !version.contains("-beta.")
+}
+
 /// Share the CLI's own config directory so a relocated profile (E2E storage
 /// guard, non-default home) does not silently re-check on every launch.
 fn automatic_stamp_path() -> Option<PathBuf> {
@@ -1194,6 +1205,7 @@ fn restart_managed_daemon() {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use base64::Engine as _;
     use sha2::{Digest, Sha256};
     use std::sync::Arc;
     use tokio::io::{AsyncReadExt, AsyncWriteExt};
@@ -1446,6 +1458,15 @@ mod tests {
         assert!(!is_newer_version("0.2.12", "0.2.13"));
     }
 
+    #[test]
+    fn prerelease_cli_builds_do_not_use_the_stable_auto_update_feed() {
+        assert!(release_version_allows_automatic_update("0.2.14"));
+        assert!(!release_version_allows_automatic_update("0.2.14-beta.1"));
+        assert!(!release_version_allows_automatic_update(
+            "0.2.14-nightly.20260811"
+        ));
+    }
+
     /// Fixture produced with the real `minisign` CLI, then wrapped the way
     /// Tauri wraps keys and signatures (base64 of the whole file), so this pins
     /// the exact on-disk format CI must emit.
@@ -1457,6 +1478,14 @@ mod tests {
     fn release_signature_accepts_the_tauri_wire_format() {
         verify_signature(FIXTURE_DATA, FIXTURE_SIGNATURE, FIXTURE_PUBKEY)
             .expect("minisign signature in Tauri's base64 wrapper must verify");
+        let raw_pubkey = String::from_utf8(
+            base64::engine::general_purpose::STANDARD
+                .decode(FIXTURE_PUBKEY)
+                .expect("decode fixture public key"),
+        )
+        .expect("fixture public key is UTF-8");
+        verify_signature(FIXTURE_DATA, FIXTURE_SIGNATURE, &raw_pubkey)
+            .expect("raw minisign public key must verify");
     }
 
     #[test]
diff --git a/src/apps/cli/src/shared_runtime.rs b/src/apps/cli/src/shared_runtime.rs
index 3c2cad6a38..a5af4e4b6c 100644
--- a/src/apps/cli/src/shared_runtime.rs
+++ b/src/apps/cli/src/shared_runtime.rs
@@ -593,12 +593,6 @@ impl RuntimeIpcRequestHandler for SharedRuntimeHandler {
                     .remove(&request.tool_id);
                 Ok(RuntimeIpcOperationResult::Unit)
             }
-            RuntimeIpcOperation::RecordLocalCommandTurn { request } => self
-                .runtime
-                .record_completed_local_command_turn(request)
-                .await
-                .map(|record| RuntimeIpcOperationResult::LocalCommandTurnRecorded { record })
-                .map_err(runtime_ipc_error),
         }
     }
 
diff --git a/src/apps/cli/src/shared_tui_backend.rs b/src/apps/cli/src/shared_tui_backend.rs
index fc7061cf86..f4c515e4d8 100644
--- a/src/apps/cli/src/shared_tui_backend.rs
+++ b/src/apps/cli/src/shared_tui_backend.rs
@@ -42,7 +42,7 @@ use bitfun_app_server_protocol::worktree::*;
 use bitfun_app_server_protocol::{MIN_PROTOCOL_VERSION, PROTOCOL_VERSION};
 use bitfun_runtime_ports::{
     AgentSessionCompactionResult, AgentSessionForkResult, AgentSessionWorkspaceBinding,
-    AgentUserShellCommandResult,
+    AgentSubmissionSource, AgentUserShellCommandResult, DialogSubmissionPolicy,
 };
 use tokio::sync::broadcast;
 
@@ -421,7 +421,11 @@ impl TuiBackend for SharedTuiBackend {
         request: SubmitDialogTurnRequest,
     ) -> Result<SubmitDialogTurnResponse, TuiBackendError> {
         match self
-            .request(RuntimeIpcOperation::SubmitTurn { request: request.0 })
+            .request(RuntimeIpcOperation::SubmitTurn {
+                request: request.0.to_request(DialogSubmissionPolicy::for_source(
+                    AgentSubmissionSource::Cli,
+                )),
+            })
             .await?
         {
             RuntimeIpcOperationResult::TurnAccepted {
@@ -502,21 +506,6 @@ impl TuiBackend for SharedTuiBackend {
         Ok(SubmitUserAnswersResponse {})
     }
 
-    async fn record_local_command_turn(
-        &self,
-        request: RecordLocalCommandTurnRequest,
-    ) -> Result<RecordLocalCommandTurnResponse, TuiBackendError> {
-        match self
-            .request(RuntimeIpcOperation::RecordLocalCommandTurn { request: request.0 })
-            .await?
-        {
-            RuntimeIpcOperationResult::LocalCommandTurnRecorded { record } => {
-                Ok(RecordLocalCommandTurnResponse(record))
-            }
-            other => Err(unexpected("record_local_command_turn", other)),
-        }
-    }
-
     async fn respond_permission(
         &self,
         request: RespondPermissionRequest,
@@ -1209,7 +1198,6 @@ fn tui_capabilities(management: &AppManagementCapabilities) -> Vec<CapabilityDes
             "session",
             vec![
                 "session/sync",
-                "session/recordLocalCommandTurn",
                 "session/rename",
                 "session/updateModel",
                 "session/updateMode",
diff --git a/src/apps/cli/src/tui_backend.rs b/src/apps/cli/src/tui_backend.rs
index 4aa747bdc7..36f7ab618a 100644
--- a/src/apps/cli/src/tui_backend.rs
+++ b/src/apps/cli/src/tui_backend.rs
@@ -147,10 +147,6 @@ pub(crate) trait TuiBackend: Send + Sync {
         &self,
         request: SubmitUserAnswersRequest,
     ) -> Result<SubmitUserAnswersResponse, TuiBackendError>;
-    async fn record_local_command_turn(
-        &self,
-        request: RecordLocalCommandTurnRequest,
-    ) -> Result<RecordLocalCommandTurnResponse, TuiBackendError>;
     async fn respond_permission(
         &self,
         request: RespondPermissionRequest,
@@ -503,13 +499,6 @@ impl TuiBackend for AppServerTuiBackend {
         map_client(self.client.submit_user_answers(request).await)
     }
 
-    async fn record_local_command_turn(
-        &self,
-        request: RecordLocalCommandTurnRequest,
-    ) -> Result<RecordLocalCommandTurnResponse, TuiBackendError> {
-        map_client(self.client.record_local_command_turn(request).await)
-    }
-
     async fn respond_permission(
         &self,
         request: RespondPermissionRequest,
diff --git a/src/apps/cli/src/ui/syntax_highlight.rs b/src/apps/cli/src/ui/syntax_highlight.rs
index 1652fea129..1d2e7de5f6 100644
--- a/src/apps/cli/src/ui/syntax_highlight.rs
+++ b/src/apps/cli/src/ui/syntax_highlight.rs
@@ -1,7 +1,7 @@
 /// Syntax highlighting module for TUI
 ///
-/// Uses `syntect` for syntax analysis and `syntect-tui` to convert
-/// highlighted output into ratatui `Span`s.
+/// Uses `syntect` for syntax analysis and converts highlighted output directly
+/// into ratatui `Span`s.
 use once_cell::sync::Lazy;
 use ratatui::{
     style::Style,
diff --git a/src/apps/cli/tests/cli_command_contracts/exec_cli_contracts.rs b/src/apps/cli/tests/cli_command_contracts/exec_cli_contracts.rs
index 48862de237..6c6bba56da 100644
--- a/src/apps/cli/tests/cli_command_contracts/exec_cli_contracts.rs
+++ b/src/apps/cli/tests/cli_command_contracts/exec_cli_contracts.rs
@@ -367,6 +367,48 @@ fn stream_json_patch_success_emits_one_success_terminal() {
     );
 }
 
+#[test]
+fn stream_json_malformed_sse_retries_then_completes() {
+    let server = MockOpenAiServer::malformed_sse_then_immediate();
+    let environment = CliTestEnvironment::new();
+    environment.configure_mock_model(server.base_url());
+    let mut command = environment.std_command();
+    command.args([
+        "exec",
+        "exercise malformed provider stream retry",
+        "--output-format",
+        "stream-json",
+    ]);
+    let output = command_output_with_timeout(&mut command, std::time::Duration::from_secs(30));
+    server.assert_chat_completion_requests(2);
+
+    let stdout = stdout(&output);
+    assert!(output.status.success(), "{}\n{stdout}", stderr(&output));
+    let events = jsonl_events(&stdout);
+    assert!(
+        events.iter().any(|value| {
+            value["event"]["type"] == "TextChunk"
+                && value["event"]["text"]
+                    .as_str()
+                    .is_some_and(|text| text.contains(STREAM_COMPLETED_MARKER))
+        }),
+        "retried model stream did not complete: {stdout}"
+    );
+    assert_eq!(
+        events
+            .iter()
+            .filter(|value| is_terminal_event(value))
+            .count(),
+        1,
+        "retried stream must emit exactly one terminal envelope: {stdout}"
+    );
+    assert_eq!(
+        events.last().expect("retried stream terminal event")["event"]["type"],
+        "DialogTurnCompleted",
+        "retried stream terminal must be last: {stdout}"
+    );
+}
+
 #[test]
 fn stream_json_provider_http_403_emits_one_error_terminal() {
     let server = MockOpenAiServer::http_403("provider authorization denied");
@@ -380,7 +422,7 @@ fn stream_json_provider_http_403_emits_one_error_terminal() {
         "stream-json",
     ]);
     let output = command_output_with_timeout(&mut command, std::time::Duration::from_secs(30));
-    server.assert_chat_completion_requests(1);
+    server.assert_chat_completion_requests(10);
 
     let stdout = stdout(&output);
     assert!(!output.status.success(), "{stdout}");
@@ -443,7 +485,7 @@ fn stream_json_provider_and_patch_failures_publish_one_final_classification() {
         &output_target,
     ]);
     let output = command_output_with_timeout(&mut command, std::time::Duration::from_secs(30));
-    server.assert_chat_completion_requests(1);
+    server.assert_chat_completion_requests(10);
 
     let stdout = stdout(&output);
     let stderr = stderr(&output);
@@ -481,7 +523,7 @@ fn stream_json_provider_and_patch_failures_publish_one_final_classification() {
 }
 
 #[test]
-fn stream_json_disconnect_then_permanent_retry_failure_emits_one_error_terminal() {
+fn stream_json_disconnect_then_exhausted_retry_failure_emits_one_error_terminal() {
     let server = MockOpenAiServer::disconnect_then_http_403();
     let environment = CliTestEnvironment::new();
     environment.configure_mock_model(server.base_url());
@@ -493,7 +535,7 @@ fn stream_json_disconnect_then_permanent_retry_failure_emits_one_error_terminal(
         "stream-json",
     ]);
     let output = command_output_with_timeout(&mut command, std::time::Duration::from_secs(30));
-    server.assert_chat_completion_requests(2);
+    server.assert_chat_completion_requests(10);
 
     let stdout = stdout(&output);
     assert!(!output.status.success(), "{stdout}");
diff --git a/src/apps/cli/tests/cli_command_contracts/product_assembly_cli.rs b/src/apps/cli/tests/cli_command_contracts/product_assembly_cli.rs
index 2f453a9c95..da2cb83a06 100644
--- a/src/apps/cli/tests/cli_command_contracts/product_assembly_cli.rs
+++ b/src/apps/cli/tests/cli_command_contracts/product_assembly_cli.rs
@@ -249,10 +249,19 @@ fn peer_session_control_and_usage_persistence_use_runtime_sdk() {
             "Peer Host session control must route {sdk_operation} through the Runtime SDK"
         );
     }
+    // Inverted, along with the behaviour it described. `/usage` renders into
+    // the conversation view and writes nothing: a report about a session is not
+    // an event in it, and the Turn this used to persist was loaded back by the
+    // desktop and given a numbered slot in its Turn rail. `add_assistant_message`
+    // is the UI-only path — `turn_id: None`, never persisted — and in a terminal
+    // the scrollback is the record.
+    //
+    // Source text only. This says the call is absent, not that nothing persists;
+    // a behavioural guarantee would have to come from the runtime port's own
+    // tests.
     assert!(
-        CHAT_SELECTION.contains("record_completed_local_command_turn")
-            && !CHAT_SELECTION.contains("append_completed_local_command_turn"),
-        "TUI usage persistence must use the fixed-semantics Runtime SDK port"
+        !CHAT_SELECTION.contains("record_completed_local_command_turn"),
+        "/usage must not write a local_command Turn: it renders into the          conversation view and persists nothing"
     );
 
     for removed_compatibility_method in [
@@ -350,14 +359,13 @@ fn chat_context_reload_uses_the_same_tui_backend_as_session_operations() {
 }
 
 #[test]
-fn tui_client_covers_interactive_permission_and_local_turn_operations() {
+fn tui_client_covers_interactive_permission_operations() {
     const TUI_CLIENT: &str = include_str!("../../src/agent/tui_client.rs");
 
     for sdk_operation in [
         "subscribe_permission_requests",
         "pending_permission_requests",
         "respond_permission",
-        "record_completed_local_command_turn",
     ] {
         assert!(
             TUI_CLIENT.contains(sdk_operation),
diff --git a/src/apps/cli/tests/support/mod.rs b/src/apps/cli/tests/support/mod.rs
index b8c634b31c..03fcd71dc5 100644
--- a/src/apps/cli/tests/support/mod.rs
+++ b/src/apps/cli/tests/support/mod.rs
@@ -303,6 +303,7 @@ enum MockModelResponse {
     Gated,
     Http403 { reason: String },
     DisconnectThenHttp403,
+    MalformedSseThenImmediate,
 }
 
 impl MockOpenAiServer {
@@ -324,6 +325,10 @@ impl MockOpenAiServer {
         Self::spawn(MockModelResponse::DisconnectThenHttp403)
     }
 
+    pub(crate) fn malformed_sse_then_immediate() -> Self {
+        Self::spawn(MockModelResponse::MalformedSseThenImmediate)
+    }
+
     pub(crate) fn base_url(&self) -> &str {
         &self.base_url
     }
@@ -405,11 +410,14 @@ impl MockOpenAiServer {
                             &disconnect_tx,
                         );
                         attempt += 1;
-                        if matches!(
-                            response,
-                            MockModelResponse::Http403 { .. }
-                                | MockModelResponse::DisconnectThenHttp403
-                        ) {
+                        let accepts_more_requests =
+                            matches!(
+                                response,
+                                MockModelResponse::Http403 { .. }
+                                    | MockModelResponse::DisconnectThenHttp403
+                            ) || (matches!(response, MockModelResponse::MalformedSseThenImmediate)
+                                && attempt < 2);
+                        if accepts_more_requests {
                             continue;
                         }
                         break;
@@ -473,6 +481,13 @@ fn serve_model_response(
         )
         .expect("write mock response headers");
 
+    if matches!(response, MockModelResponse::MalformedSseThenImmediate) && attempt == 0 {
+        write_chunk(stream, b"data: not-json\n\n").expect("write malformed SSE frame");
+        let _ = stream.write_all(b"0\r\n\r\n");
+        let _ = stream.flush();
+        return;
+    }
+
     write_sse_chunk(
         stream,
         &json!({
@@ -579,7 +594,7 @@ fn write_http_403(stream: &mut TcpStream, reason: &str) -> std::io::Result<()> {
     .to_string();
     write!(
         stream,
-        "HTTP/1.1 403 Forbidden\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}",
+        "HTTP/1.1 403 Forbidden\r\nContent-Type: application/json\r\nContent-Length: {}\r\nRetry-After: 1\r\nConnection: close\r\n\r\n{body}",
         body.len()
     )?;
     stream.flush()
diff --git a/src/apps/desktop/AGENTS-CN.md b/src/apps/desktop/AGENTS-CN.md
index 3cc388e6dd..2e09b88435 100644
--- a/src/apps/desktop/AGENTS-CN.md
+++ b/src/apps/desktop/AGENTS-CN.md
@@ -40,6 +40,7 @@ crate；`src/crates/assembly/core` 只保留产品装配与兼容桥接。
 ```bash
 pnpm run desktop:dev
 pnpm run desktop:preview:debug
+pnpm run prepare:dsh-profile   # 可选：本地 DeepSeek Harness 会话
 ```
 
 ## 快速构建
diff --git a/src/apps/desktop/AGENTS.md b/src/apps/desktop/AGENTS.md
index c8411a10d9..465a532e6c 100644
--- a/src/apps/desktop/AGENTS.md
+++ b/src/apps/desktop/AGENTS.md
@@ -49,6 +49,7 @@ the Verification section below.
 ```bash
 pnpm run desktop:dev
 pnpm run desktop:preview:debug
+pnpm run prepare:dsh-profile   # optional: local DeepSeek Harness sessions
 ```
 
 ## Fast builds
diff --git a/src/apps/desktop/Cargo.toml b/src/apps/desktop/Cargo.toml
index 5f96147e62..7c6ed07924 100644
--- a/src/apps/desktop/Cargo.toml
+++ b/src/apps/desktop/Cargo.toml
@@ -19,18 +19,18 @@ serde_json = { workspace = true }
 
 [dependencies]
 # Internal crates
-bitfun-core = { path = "../../crates/assembly/core", default-features = false, features = ["product-full"] }
+bitfun-core = { path = "../../crates/assembly/core", features = ["product-full"] }
 bitfun-relay-service = { path = "../../crates/services/relay-service" }
-bitfun-agent-runtime = { path = "../../crates/execution/agent-runtime" }
-bitfun-runtime-ports = { path = "../../crates/contracts/runtime-ports" }
-bitfun-product-domains = { path = "../../crates/contracts/product-domains", default-features = false, features = ["appearance-market"] }
-bitfun-services-integrations = { path = "../../crates/services/services-integrations", default-features = false, features = ["canvas-runtime", "miniapp-market", "speech", "feedback", "privacy"] }
+bitfun-agent-runtime = { path = "../../crates/execution/agent-runtime", features = ["agent-runtime"] }
+bitfun-runtime-ports = { path = "../../crates/contracts/runtime-ports", features = ["agent-api", "permission", "workspace-ports"] }
+bitfun-product-domains = { path = "../../crates/contracts/product-domains", features = ["appearance-market"] }
+bitfun-services-integrations = { path = "../../crates/services/services-integrations", features = ["canvas-runtime", "miniapp-market", "speech", "feedback", "privacy"] }
 bitfun-core-types = { path = "../../crates/contracts/core-types" }
-bitfun-agent-tools = { path = "../../crates/execution/tool-contracts" }
+bitfun-agent-tools = { path = "../../crates/execution/tool-contracts", features = ["element-token"] }
 bitfun-transport = { path = "../../crates/adapters/transport", features = ["tauri-adapter"] }
 bitfun-events = { path = "../../crates/contracts/events" }
 bitfun-webdriver = { path = "../../crates/adapters/webdriver" }
-bitfun-acp = { path = "../../crates/interfaces/acp" }
+bitfun-acp = { path = "../../crates/interfaces/acp", default-features = false, features = ["client"] }
 
 # Tauri
 tauri = { workspace = true }
@@ -63,7 +63,7 @@ dirs = { workspace = true }
 similar = { workspace = true }
 ignore = { workspace = true }
 urlencoding = { workspace = true }
-reqwest = { workspace = true, features = ["rustls"] }
+reqwest = { workspace = true, features = ["http2", "json", "query", "rustls", "stream"] }
 semver = { workspace = true }
 zip = { workspace = true }
 tar = { workspace = true }
@@ -93,9 +93,9 @@ dispatch = { workspace = true }
 foreign-types = { workspace = true }
 libc = { workspace = true }
 objc2 = { workspace = true, features = ["exception"] }
-objc2-foundation = { workspace = true }
+objc2-foundation = { workspace = true, features = ["std", "NSArray", "NSData", "NSDictionary", "NSError", "NSString"] }
 objc2-app-kit = { workspace = true }
-objc2-vision = { workspace = true }
+objc2-vision = { workspace = true, features = ["std", "VNRecognizeTextRequest", "VNRequest", "VNObservation", "VNRequestHandler", "VNUtils", "VNTypes", "objc2-core-foundation"] }
 
 [target.'cfg(windows)'.dependencies]
 win32job = { workspace = true }
diff --git a/src/apps/desktop/build.rs b/src/apps/desktop/build.rs
index d84e5ec5db..8232623697 100644
--- a/src/apps/desktop/build.rs
+++ b/src/apps/desktop/build.rs
@@ -1,4 +1,7 @@
 fn main() {
+    println!("cargo:rerun-if-env-changed=BITFUN_RELEASE_CHANNEL");
+    println!("cargo:rerun-if-env-changed=BITFUN_UPDATER_PRIMARY_ENDPOINT");
+    println!("cargo:rerun-if-env-changed=BITFUN_UPDATER_FALLBACK_ENDPOINT");
     // The Windows primary thread keeps the Tauri event loop and native window
     // creation stack. Reserve the same headroom as the Tokio workers so a
     // large debug invoke dispatcher cannot exhaust the default 1 MiB stack.
diff --git a/src/apps/desktop/capabilities/default.json b/src/apps/desktop/capabilities/default.json
index 21f84c5c86..d18bf9024b 100644
--- a/src/apps/desktop/capabilities/default.json
+++ b/src/apps/desktop/capabilities/default.json
@@ -1,89 +1,103 @@
 {
-    "$schema": "../gen/schemas/desktop-schema.json",
-    "identifier": "default",
-    "description": "BitFun default capabilities",
-    "windows": ["main", "agent-companion-pet", "spotlight"],
-    "permissions": [
-        "log:default",
-        "core:default",
-        "core:path:default",
-        "core:event:default",
-        "core:event:allow-listen",
-        "core:event:allow-emit",
-        "core:window:default",
-        "core:webview:default",
-        "core:webview:allow-create-webview",
-        "core:webview:allow-set-webview-position",
-        "core:webview:allow-set-webview-size",
-        "core:webview:allow-set-webview-focus",
-        "core:webview:allow-reparent",
-        "core:webview:allow-webview-show",
-        "core:webview:allow-webview-hide",
-        "core:webview:allow-webview-close",
-        "core:window:allow-create",
-        "core:window:allow-set-focus",
-        "core:window:allow-set-always-on-top",
-        "core:window:allow-set-position",
-        "core:window:allow-set-size",
-        "core:window:allow-set-decorations",
-        "core:window:allow-set-title-bar-style",
-        "core:window:allow-set-skip-taskbar",
-        "core:window:allow-set-resizable",
-        "core:window:allow-current-monitor",
-        "core:window:allow-outer-position",
-        "core:window:allow-outer-size",
-        "core:window:allow-is-maximized",
-        "core:window:allow-center",
-        "core:window:allow-close",
-        "core:window:allow-hide",
-        "core:window:allow-maximize",
-        "core:window:allow-minimize",
-        "core:window:allow-show",
-        "core:window:allow-start-dragging",
-        "core:window:allow-unmaximize",
-        "core:window:allow-unminimize",
-        "core:window:allow-set-min-size",
-        "opener:default",
-        "opener:allow-open-url",
-        "opener:allow-open-path",
-        "opener:allow-reveal-item-in-dir",
-        "fs:default",
-        "fs:allow-read-file",
-        "fs:allow-write-file",
-        "fs:allow-read-dir",
-        "fs:allow-copy-file",
-        "fs:allow-create",
-        "fs:allow-mkdir",
-        "fs:allow-remove",
-        "fs:allow-rename",
-        "fs:allow-exists",
-        "fs:allow-read-text-file",
-        "fs:allow-write-text-file",
-        "fs:allow-stat",
-        "fs:allow-lstat",
-        "fs:allow-fstat",
-        "fs:allow-truncate",
-        "fs:allow-ftruncate",
-        "fs:allow-open",
-        "fs:allow-read",
-        "fs:allow-write",
-        "fs:allow-seek",
-        "fs:allow-unwatch",
-        "fs:allow-watch",
-        "fs:read-all",
-        "fs:write-all",
-        "fs:scope-app-recursive",
-        {
-            "identifier": "fs:allow-home-read-recursive",
-            "allow": [
-                { "path": "$HOME/**" }
-            ]
-        },
-        {
-            "identifier": "fs:allow-home-write-recursive",
-            "allow": [
-                { "path": "$HOME/**" }
-            ]
-        }
-    ]
+  "$schema": "../gen/schemas/desktop-schema.json",
+  "identifier": "default",
+  "description": "BitFun default capabilities",
+  "windows": ["main", "agent-companion-pet", "spotlight"],
+  "permissions": [
+    "log:default",
+    "autostart:default",
+    "core:default",
+    "core:path:default",
+    "core:event:default",
+    "core:event:allow-listen",
+    "core:event:allow-emit",
+    "core:window:default",
+    "core:webview:default",
+    "core:webview:allow-create-webview",
+    "core:webview:allow-set-webview-position",
+    "core:webview:allow-set-webview-size",
+    "core:webview:allow-set-webview-focus",
+    "core:webview:allow-reparent",
+    "core:webview:allow-webview-show",
+    "core:webview:allow-webview-hide",
+    "core:webview:allow-webview-close",
+    "core:window:allow-create",
+    "core:window:allow-set-focus",
+    "core:window:allow-set-always-on-top",
+    "core:window:allow-set-position",
+    "core:window:allow-set-size",
+    "core:window:allow-set-decorations",
+    "core:window:allow-set-title-bar-style",
+    "core:window:allow-set-skip-taskbar",
+    "core:window:allow-set-resizable",
+    "core:window:allow-current-monitor",
+    "core:window:allow-outer-position",
+    "core:window:allow-outer-size",
+    "core:window:allow-is-fullscreen",
+    "core:window:allow-is-maximized",
+    "core:window:allow-center",
+    "core:window:allow-close",
+    "core:window:allow-hide",
+    "core:window:allow-maximize",
+    "core:window:allow-minimize",
+    "core:window:allow-show",
+    "core:window:allow-start-dragging",
+    "core:window:allow-unmaximize",
+    "core:window:allow-unminimize",
+    "core:window:allow-set-min-size",
+    "dialog:default",
+    "dialog:allow-open",
+    "dialog:allow-save",
+    "dialog:allow-ask",
+    "dialog:allow-confirm",
+    "dialog:allow-message",
+    "opener:default",
+    "opener:allow-open-url",
+    {
+      "identifier": "opener:allow-open-path",
+      "allow": [
+        { "path": "$APPDATA/**" },
+        { "path": "$HOME/**" }
+      ]
+    },
+    "opener:allow-reveal-item-in-dir",
+    "fs:default",
+    "fs:allow-read-file",
+    "fs:allow-write-file",
+    "fs:allow-read-dir",
+    "fs:allow-copy-file",
+    "fs:allow-create",
+    "fs:allow-mkdir",
+    "fs:allow-remove",
+    "fs:allow-rename",
+    "fs:allow-exists",
+    "fs:allow-read-text-file",
+    "fs:allow-write-text-file",
+    "fs:allow-stat",
+    "fs:allow-lstat",
+    "fs:allow-fstat",
+    "fs:allow-truncate",
+    "fs:allow-ftruncate",
+    "fs:allow-open",
+    "fs:allow-read",
+    "fs:allow-write",
+    "fs:allow-seek",
+    "fs:allow-unwatch",
+    "fs:allow-watch",
+    "fs:read-all",
+    "fs:write-all",
+    "fs:scope-app-recursive",
+    {
+      "identifier": "fs:allow-home-read-recursive",
+      "allow": [
+        { "path": "$HOME/**" }
+      ]
+    },
+    {
+      "identifier":     "fs:allow-home-write-recursive",
+      "allow": [
+        { "path": "$HOME/**" }
+      ]
+    }
+  ]
 }
\ No newline at end of file
diff --git a/src/apps/desktop/dmg/background.png b/src/apps/desktop/dmg/background.png
new file mode 100644
index 0000000000..9fe35cd211
Binary files /dev/null and b/src/apps/desktop/dmg/background.png differ
diff --git a/src/apps/desktop/src/api/agentic_api.rs b/src/apps/desktop/src/api/agentic_api.rs
index 2b4c6c468e..f77cf4c45c 100644
--- a/src/apps/desktop/src/api/agentic_api.rs
+++ b/src/apps/desktop/src/api/agentic_api.rs
@@ -16,12 +16,13 @@ use crate::runtime::{
 use crate::startup_trace::DesktopStartupTrace;
 use bitfun_agent_runtime::deep_review::sanitize_focused_review_public_metadata;
 use bitfun_agent_runtime::sdk::{
-    AgentDialogSteerRequest, AgentDialogTurnExecution, AgentDialogTurnRequest,
-    AgentInputAttachment, AgentSessionCreateResult, AgentSessionModeUpdateRequest,
-    AgentSessionModelSelection, AgentSessionModelSelectionUpdateRequest,
-    AgentSessionModelUpdateRequest, AgentSubmissionSource, AgentTurnCancellationRequest,
-    DialogSteerOutcome, PermissionAuditRecord, PermissionGrant, PermissionGrantKey,
-    PermissionReply, PermissionRequest,
+    AgentDialogSteerRequest, AgentDialogTurnExecution, AgentDialogTurnRecoveryOutcome,
+    AgentDialogTurnRecoveryRequest, AgentDialogTurnRequest, AgentInputAttachment,
+    AgentSessionCreateResult, AgentSessionModeUpdateRequest, AgentSessionModelSelection,
+    AgentSessionModelSelectionUpdateRequest, AgentSessionModelUpdateRequest, AgentSubmissionSource,
+    AgentTurnCancellationRequest, AgentTurnInterruptionRequest, DialogSteerOutcome,
+    PermissionAuditRecord, PermissionGrant, PermissionGrantKey, PermissionReply, PermissionRequest,
+    RuntimeError,
 };
 use bitfun_core::agentic::agents::AgentSource;
 use bitfun_core::agentic::coordination::{
@@ -65,7 +66,7 @@ use bitfun_core_types::{
     WorktreeError, WorktreeErrorCode,
 };
 use bitfun_product_domains::tool_permissions::PermissionRule;
-use bitfun_runtime_ports::{PermissionMode, SessionTurnWindowRequest};
+use bitfun_runtime_ports::{PermissionMode, PortErrorKind, SessionTurnWindowRequest};
 
 const SESSION_VIEW_TOOL_RESULT_TOTAL_CHAR_BUDGET: usize = 512 * 1024;
 const SESSION_VIEW_TOOL_RESULT_STRING_CHAR_LIMIT: usize = 16 * 1024;
@@ -252,6 +253,27 @@ pub struct UpdateSessionPermissionModeRequest {
     #[serde(default)]
     pub mode: Option<String>,
     #[serde(default)]
+    pub turn_id: Option<String>,
+    #[serde(default)]
+    pub workspace_path: Option<String>,
+    #[serde(default)]
+    pub remote_connection_id: Option<String>,
+    #[serde(default)]
+    pub remote_ssh_host: Option<String>,
+    #[serde(default)]
+    pub include_internal: bool,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct UpdateActiveTurnPermissionModeRequest {
+    pub session_id: String,
+    pub turn_id: String,
+    /// `None` clears the one-off override and returns the active turn to its
+    /// session mode at the next model-round boundary.
+    #[serde(default)]
+    pub mode: Option<String>,
+    #[serde(default)]
     pub workspace_path: Option<String>,
     #[serde(default)]
     pub remote_connection_id: Option<String>,
@@ -266,6 +288,9 @@ pub struct UpdateSessionPermissionModeRequest {
 pub struct SessionPermissionModeResponse {
     /// The session's own selection, or `null` when it follows the default.
     pub mode: Option<PermissionMode>,
+    /// Ephemeral override for the requested active turn, when one exists.
+    pub turn_mode: Option<PermissionMode>,
+    pub active_turn_id: Option<String>,
 }
 
 fn deserialize_present_nullable<'de, D, T>(deserializer: D) -> Result<Option<Option<T>>, D::Error>
@@ -740,6 +765,20 @@ pub struct CancelDialogTurnRequest {
     pub dialog_turn_id: String,
 }
 
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RecoverInterruptedDialogTurnRequest {
+    pub session_id: String,
+    pub dialog_turn_id: String,
+    pub execution_generation: u32,
+    #[serde(default)]
+    pub workspace_path: Option<String>,
+    #[serde(default)]
+    pub remote_connection_id: Option<String>,
+    #[serde(default)]
+    pub remote_ssh_host: Option<String>,
+}
+
 #[derive(Debug, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct SteerDialogTurnRequest {
@@ -751,6 +790,14 @@ pub struct SteerDialogTurnRequest {
     /// Original user text for UI rendering (defaults to `content`).
     #[serde(default)]
     pub display_content: Option<String>,
+    /// Images attached to the steering message. Same shape the composer sends
+    /// when it starts a turn — a message keeps its attachments whether it is
+    /// submitted at a turn boundary or injected into a running turn.
+    #[serde(default)]
+    pub image_contexts: Option<Vec<ImageContextData>>,
+    /// Structured metadata carried with the steering message.
+    #[serde(default)]
+    pub user_message_metadata: Option<serde_json::Value>,
 }
 
 #[derive(Debug, Serialize)]
@@ -1856,14 +1903,110 @@ pub async fn update_session_permission_mode(
         request.include_internal,
     )
     .await?;
+    let session_manager = coordinator.get_session_manager();
+    let requested_turn_id = request
+        .turn_id
+        .as_deref()
+        .map(str::trim)
+        .filter(|value| !value.is_empty());
 
-    coordinator
-        .get_session_manager()
+    session_manager
         .update_session_permission_mode(&session_id, mode)
         .await
         .map_err(|error| format!("Failed to update session permission mode: {error}"))?;
+    if let Some(turn_id) = requested_turn_id {
+        session_manager.clear_active_turn_permission_mode(&session_id, turn_id);
+    }
 
-    Ok(SessionPermissionModeResponse { mode })
+    let active_turn_id = requested_turn_id.and_then(|turn_id| {
+        session_manager
+            .get_session(&session_id)
+            .filter(|session| {
+                matches!(
+                    &session.state,
+                    SessionState::Processing { current_turn_id, .. } if current_turn_id == turn_id
+                )
+            })
+            .map(|_| turn_id.to_string())
+    });
+    Ok(SessionPermissionModeResponse {
+        mode: session_manager.session_permission_mode(&session_id),
+        turn_mode: active_turn_id
+            .as_deref()
+            .and_then(|turn_id| session_manager.active_turn_permission_mode(&session_id, turn_id)),
+        active_turn_id,
+    })
+}
+
+/// Replaces or clears the temporary mode for one exact active turn.
+///
+/// This is intentionally a distinct command from the session setter: a new
+/// frontend talking to an older backend must fail loudly instead of having an
+/// unknown scope field ignored and accidentally persisting a one-off choice.
+#[tauri::command]
+pub async fn update_active_turn_permission_mode(
+    runtime: State<'_, DesktopRuntimeContext>,
+    coordinator: State<'_, Arc<ConversationCoordinator>>,
+    request: UpdateActiveTurnPermissionModeRequest,
+) -> Result<SessionPermissionModeResponse, String> {
+    let session_id = request.session_id.trim().to_string();
+    let turn_id = request.turn_id.trim().to_string();
+    if session_id.is_empty() {
+        return Err("session_id is required".to_string());
+    }
+    if turn_id.is_empty() {
+        return Err("turn_id is required".to_string());
+    }
+    let mode = match request.mode.as_deref().map(str::trim) {
+        None | Some("") => None,
+        Some(value) => Some(
+            PermissionMode::parse(value)
+                .ok_or_else(|| format!("unsupported permission mode: {value}"))?,
+        ),
+    };
+
+    ensure_session_loaded_for_selector_update(
+        runtime.inner(),
+        &session_id,
+        request.workspace_path,
+        request.remote_connection_id,
+        request.remote_ssh_host,
+        request.include_internal,
+    )
+    .await?;
+
+    let session_manager = coordinator.get_session_manager();
+    let is_active = match mode {
+        Some(turn_mode) => {
+            session_manager.set_active_turn_permission_mode(&session_id, &turn_id, turn_mode)
+        }
+        None => {
+            let is_active = session_manager
+                .get_session(&session_id)
+                .is_some_and(|session| {
+                    matches!(
+                        &session.state,
+                        SessionState::Processing { current_turn_id, .. }
+                            if current_turn_id == &turn_id
+                    )
+                });
+            if is_active {
+                session_manager.clear_active_turn_permission_mode(&session_id, &turn_id);
+            }
+            is_active
+        }
+    };
+    if !is_active {
+        return Err(format!(
+            "Turn is no longer active for this session: session_id={session_id}, turn_id={turn_id}"
+        ));
+    }
+
+    Ok(SessionPermissionModeResponse {
+        mode: session_manager.session_permission_mode(&session_id),
+        turn_mode: session_manager.active_turn_permission_mode(&session_id, &turn_id),
+        active_turn_id: Some(turn_id),
+    })
 }
 
 /// Reads the session's own permission mode selection.
@@ -1889,10 +2032,29 @@ pub async fn get_session_permission_mode(
     )
     .await?;
 
+    let session_manager = coordinator.get_session_manager();
+    let requested_turn_id = request
+        .turn_id
+        .as_deref()
+        .map(str::trim)
+        .filter(|value| !value.is_empty());
+    let active_turn_id = requested_turn_id.and_then(|turn_id| {
+        session_manager
+            .get_session(&session_id)
+            .filter(|session| {
+                matches!(
+                    &session.state,
+                    SessionState::Processing { current_turn_id, .. } if current_turn_id == turn_id
+                )
+            })
+            .map(|_| turn_id.to_string())
+    });
     Ok(SessionPermissionModeResponse {
-        mode: coordinator
-            .get_session_manager()
-            .session_permission_mode(&session_id),
+        mode: session_manager.session_permission_mode(&session_id),
+        turn_mode: active_turn_id
+            .as_deref()
+            .and_then(|turn_id| session_manager.active_turn_permission_mode(&session_id, turn_id)),
+        active_turn_id,
     })
 }
 
@@ -2739,6 +2901,97 @@ pub async fn cancel_dialog_turn(
         .map(|_| ())
 }
 
+/// Request a recoverable interruption for a native local dialog turn. The
+/// command returns only after the old execution has settled and the
+/// `dialog-turn-interrupted` event is safe to act on.
+#[tauri::command]
+pub async fn interrupt_dialog_turn(
+    runtime: State<'_, DesktopRuntimeContext>,
+    request: CancelDialogTurnRequest,
+) -> Result<(), String> {
+    let interruption = runtime
+        .agent_runtime()
+        .interrupt_turn(AgentTurnInterruptionRequest {
+            session_id: request.session_id.clone(),
+            turn_id: request.dialog_turn_id.clone(),
+            source: Some(AgentSubmissionSource::DesktopUi),
+            wait_timeout_ms: Some(30_000),
+        })
+        .await;
+    match interruption {
+        Ok(_) => Ok(()),
+        // Stop remains universally available. Unsupported recovery surfaces
+        // (external routes, Goal, remote, non-standard sessions) degrade to
+        // the existing hard cancellation and emit DialogTurnCancelled.
+        Err(RuntimeError::Port(error))
+            if matches!(error.kind, PortErrorKind::InvalidRequest | PortErrorKind::Timeout) => runtime
+            .agent_runtime()
+            .cancel_turn(AgentTurnCancellationRequest {
+                session_id: request.session_id.clone(),
+                turn_id: Some(request.dialog_turn_id.clone()),
+                source: Some(AgentSubmissionSource::DesktopUi),
+                requester_session_id: None,
+                reason: Some(if error.kind == PortErrorKind::Timeout {
+                    "recoverable interruption timed out".to_string()
+                } else {
+                    "recoverable interruption unavailable".to_string()
+                }),
+                wait_timeout_ms: None,
+                cancel_descendants: true,
+            })
+            .await
+            .map(|_| ())
+            .map_err(|fallback_error| {
+                log::error!(
+                    "Failed to cancel dialog turn after interruption was unavailable: session_id={}, dialog_turn_id={}, error={}",
+                    request.session_id,
+                    request.dialog_turn_id,
+                    fallback_error
+                );
+                format!("Failed to cancel dialog turn: {}", fallback_error.into_message())
+            }),
+        Err(error) => {
+            log::error!(
+                "Failed to interrupt dialog turn: session_id={}, dialog_turn_id={}, error={}",
+                request.session_id,
+                request.dialog_turn_id,
+                error
+            );
+            Err(format!("Failed to interrupt dialog turn: {}", error.into_message()))
+        }
+    }
+}
+
+#[tauri::command]
+pub async fn recover_interrupted_dialog_turn(
+    runtime: State<'_, DesktopRuntimeContext>,
+    request: RecoverInterruptedDialogTurnRequest,
+) -> Result<AgentDialogTurnRecoveryOutcome, String> {
+    runtime
+        .agent_runtime()
+        .recover_interrupted_turn(AgentDialogTurnRecoveryRequest {
+            session_id: request.session_id.clone(),
+            turn_id: request.dialog_turn_id.clone(),
+            execution_generation: request.execution_generation,
+            workspace_path: request.workspace_path,
+            remote_connection_id: request.remote_connection_id,
+            remote_ssh_host: request.remote_ssh_host,
+        })
+        .await
+        .map_err(|error| {
+            log::error!(
+                "Failed to recover interrupted dialog turn: session_id={}, dialog_turn_id={}, error={}",
+                request.session_id,
+                request.dialog_turn_id,
+                error
+            );
+            format!(
+                "Failed to recover interrupted dialog turn: {}",
+                error.into_message()
+            )
+        })
+}
+
 #[tauri::command]
 pub async fn steer_dialog_turn(
     runtime: State<'_, DesktopRuntimeContext>,
@@ -2749,13 +3002,24 @@ pub async fn steer_dialog_turn(
         dialog_turn_id,
         content,
         display_content,
+        image_contexts,
+        user_message_metadata,
     } = request;
 
-    let trimmed = content.trim();
-    if trimmed.is_empty() {
+    let attachments: Vec<AgentInputAttachment> = image_contexts
+        .unwrap_or_default()
+        .into_iter()
+        .map(desktop_image_attachment)
+        .collect();
+
+    // An image-only steering message is a real message; only a message with
+    // neither text nor attachments is empty.
+    if content.trim().is_empty() && attachments.is_empty() {
         return Err("Steering content cannot be empty".to_string());
     }
 
+    let metadata = desktop_user_message_metadata(user_message_metadata);
+
     let outcome = runtime
         .agent_runtime()
         .steer_dialog_turn(AgentDialogSteerRequest {
@@ -2763,6 +3027,8 @@ pub async fn steer_dialog_turn(
             turn_id: dialog_turn_id,
             content,
             display_content,
+            attachments,
+            metadata,
         })
         .await
         .map_err(|error| format!("Failed to steer dialog turn: {}", error.into_message()))?;
@@ -4121,6 +4387,8 @@ mod tests {
             token_usage: None,
             finish_reason: None,
             has_final_response: None,
+            recovery: None,
+            recovery_epoch: None,
             error: None,
             error_detail: None,
             status: TurnStatus::Completed,
@@ -4205,6 +4473,8 @@ mod tests {
             token_usage: None,
             finish_reason: None,
             has_final_response: None,
+            recovery: None,
+            recovery_epoch: None,
             error: None,
             error_detail: None,
             status: TurnStatus::Completed,
@@ -4270,6 +4540,8 @@ mod tests {
             token_usage: None,
             finish_reason: None,
             has_final_response: None,
+            recovery: None,
+            recovery_epoch: None,
             error: None,
             error_detail: None,
             status: TurnStatus::Completed,
diff --git a/src/apps/desktop/src/api/browser_control_api.rs b/src/apps/desktop/src/api/browser_control_api.rs
index 1a7731a4d5..797be73d6b 100644
--- a/src/apps/desktop/src/api/browser_control_api.rs
+++ b/src/apps/desktop/src/api/browser_control_api.rs
@@ -18,6 +18,70 @@ fn default_cdp_port() -> u16 {
     DEFAULT_CDP_PORT
 }
 
+/// Reattach to a browser that is already running with remote debugging on.
+///
+/// The browser remembers the remote debugging preference across its own
+/// restarts, and it keeps an approved connection grant for as long as it stays
+/// running — but BitFun's connection registry lives in this process, so every
+/// BitFun restart otherwise leaves Settings reporting "not connected" until
+/// something asks for the browser. Reattaching here restores that connection
+/// without the user having to click anything.
+///
+/// Opt-in, because the grant does not survive a browser restart: after one,
+/// reattaching raises an approval dialog before the user has asked for the
+/// browser at all.
+///
+/// This never starts a browser and never opens a settings page: when there is
+/// no live endpoint to reattach to, it does nothing and leaves the on-demand
+/// path to handle it.
+pub fn init_on_startup() {
+    tokio::spawn(async {
+        if !auto_connect_on_startup_enabled().await {
+            return;
+        }
+        let Ok(kind) = selected_browser_kind().await else {
+            return;
+        };
+        let Some(endpoint) = BrowserLauncher::user_profile_debug_endpoint(&kind) else {
+            return;
+        };
+        if CdpClient::browser_connection_for_kind(DEFAULT_CDP_PORT, &kind)
+            .await
+            .is_some()
+        {
+            return;
+        }
+        // A denial or an approval timeout is an ordinary outcome here, not an
+        // error worth surfacing: the user never asked for this connection.
+        match CdpClient::connect_user_profile_browser(
+            DEFAULT_CDP_PORT,
+            endpoint.port,
+            &kind,
+            &endpoint.web_socket_url,
+        )
+        .await
+        {
+            Ok(_) => log::info!("Reattached to the running {} profile on startup", kind),
+            Err(error) => log::info!(
+                "Could not reattach to the running {} profile on startup: {}",
+                kind,
+                error
+            ),
+        }
+    });
+}
+
+async fn auto_connect_on_startup_enabled() -> bool {
+    let Ok(service) = get_global_config_service().await else {
+        return false;
+    };
+    service
+        .get_config::<GlobalConfig>(None)
+        .await
+        .map(|config| config.ai.browser_control_auto_connect_on_startup)
+        .unwrap_or(false)
+}
+
 async fn selected_browser_kind() -> Result<BrowserKind, String> {
     let config = get_global_config_service()
         .await
@@ -91,6 +155,12 @@ pub async fn browser_control_list_browsers() -> Result<BrowserControlBrowsersRes
 #[serde(rename_all = "camelCase")]
 pub struct BrowserControlStatusResponse {
     pub cdp_available: bool,
+    pub default_cdp_supported: bool,
+    pub default_cdp_enabled: bool,
+    /// The selected browser is running with remote debugging on, so BitFun can
+    /// attach whenever it needs to. Distinguishes "ready, nothing attached yet"
+    /// from "nothing to attach to", which both used to read as "not connected".
+    pub browser_ready: bool,
     pub browser_kind: String,
     pub browser_version: Option<String>,
     pub port: u16,
@@ -103,11 +173,48 @@ pub async fn browser_control_get_status(
     request: BrowserControlStatusRequest,
 ) -> Result<BrowserControlStatusResponse, String> {
     let port = request.port;
-    let available = BrowserLauncher::is_cdp_available(port).await;
     let configured_kind = selected_browser_kind().await?;
+    let default_cdp_supported = BrowserLauncher::supports_default_cdp(&configured_kind);
+    // Probe the live endpoint once and answer both questions from it: whether
+    // the persistent setting is on, and whether there is something to attach to
+    // right now. The probe is a file read plus a short local TCP connect, so it
+    // never prompts the browser the way attaching does.
+    let user_profile_endpoint = BrowserLauncher::user_profile_debug_endpoint(&configured_kind);
+    let default_cdp_enabled = default_cdp_supported
+        && (user_profile_endpoint.is_some()
+            || BrowserLauncher::is_default_cdp_enabled(&configured_kind));
+    let user_profile_connection =
+        CdpClient::browser_connection_for_kind(port, &configured_kind).await;
+    let legacy_version =
+        if user_profile_connection.is_none() && BrowserLauncher::is_cdp_available(port).await {
+            CdpClient::get_version(port).await.ok()
+        } else {
+            None
+        };
+    // Chrome and Edge share the logical 9222 slot in Settings. Do not report
+    // the selected browser as connected merely because the other one owns a
+    // legacy fixed-port endpoint left from an earlier selection.
+    let legacy_matches_selection = legacy_version.as_ref().is_some_and(|version| {
+        let detected = version
+            .browser
+            .as_deref()
+            .and_then(BrowserLauncher::browser_kind_from_cdp_version);
+        match &configured_kind {
+            BrowserKind::Chrome | BrowserKind::Edge => {
+                detected.map(|kind| kind == configured_kind).unwrap_or(true)
+            }
+            _ => true,
+        }
+    });
+    let available = user_profile_connection.is_some() || legacy_matches_selection;
+    let browser_ready = available || user_profile_endpoint.is_some();
 
     let (version, page_count, actual_kind) = if available {
-        let ver_info = CdpClient::get_version(port).await.ok();
+        let ver_info = if let Some(connection) = &user_profile_connection {
+            connection.client.browser_version().await.ok()
+        } else {
+            legacy_version
+        };
         let ver = ver_info.as_ref().and_then(|v| v.browser.clone());
         // Identify the actual browser from CDP version response.
         let kind = ver
@@ -116,15 +223,17 @@ pub async fn browser_control_get_status(
             .unwrap_or_else(|| configured_kind.clone());
         // Only count targets of type "page" (real browser tabs),
         // not service workers, browser targets, etc.
-        let pages = CdpClient::list_pages(port)
-            .await
-            .ok()
-            .map(|p| {
-                p.iter()
-                    .filter(|t| t.page_type.as_deref() == Some("page"))
-                    .count()
-            })
-            .unwrap_or(0);
+        let pages = if let Some(connection) = &user_profile_connection {
+            connection.client.browser_pages().await.ok()
+        } else {
+            CdpClient::list_pages(port).await.ok()
+        }
+        .map(|p| {
+            p.iter()
+                .filter(|t| t.page_type.as_deref() == Some("page"))
+                .count()
+        })
+        .unwrap_or(0);
         (ver, pages, kind)
     } else {
         (None, 0, configured_kind)
@@ -132,6 +241,9 @@ pub async fn browser_control_get_status(
 
     Ok(BrowserControlStatusResponse {
         cdp_available: available,
+        default_cdp_supported,
+        default_cdp_enabled,
+        browser_ready,
         browser_kind: actual_kind.to_string(),
         browser_version: version,
         port,
@@ -153,6 +265,10 @@ pub struct BrowserControlLaunchResponse {
     pub status: String,
     pub message: Option<String>,
     pub browser_kind: String,
+    /// Remote debugging settings URL, sent when the user has to open it
+    /// themselves because the platform cannot open a `chrome://` URL for them.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub setup_url: Option<String>,
 }
 
 fn to_launch_response(kind: &BrowserKind, result: LaunchResult) -> BrowserControlLaunchResponse {
@@ -162,18 +278,47 @@ fn to_launch_response(kind: &BrowserKind, result: LaunchResult) -> BrowserContro
             status: "already_connected".into(),
             message: None,
             browser_kind: kind.to_string(),
+            setup_url: None,
         },
         LaunchResult::Launched => BrowserControlLaunchResponse {
             success: true,
             status: "launched".into(),
             message: None,
             browser_kind: kind.to_string(),
+            setup_url: None,
+        },
+        LaunchResult::UserProfileReady { .. } => BrowserControlLaunchResponse {
+            success: false,
+            status: "user_profile_ready".into(),
+            message: None,
+            browser_kind: kind.to_string(),
+            setup_url: None,
+        },
+        LaunchResult::UserProfileSetupRequired {
+            instructions,
+            setup_url,
+            opened,
+            ..
+        } => BrowserControlLaunchResponse {
+            success: false,
+            // The two cases need different guidance: one asks the user to
+            // finish on a page that is already in front of them, the other
+            // asks them to open that page first.
+            status: if opened {
+                "requires_user_profile_setup".into()
+            } else {
+                "requires_manual_user_profile_setup".into()
+            },
+            message: Some(instructions),
+            browser_kind: kind.to_string(),
+            setup_url: Some(setup_url),
         },
         LaunchResult::LaunchedButCdpNotReady { message, .. } => BrowserControlLaunchResponse {
             success: false,
             status: "cdp_not_ready".into(),
             message: Some(message),
             browser_kind: kind.to_string(),
+            setup_url: None,
         },
         LaunchResult::BrowserRunningWithoutCdp { instructions, .. } => {
             BrowserControlLaunchResponse {
@@ -181,11 +326,47 @@ fn to_launch_response(kind: &BrowserKind, result: LaunchResult) -> BrowserContro
                 status: "needs_restart".into(),
                 message: Some(instructions),
                 browser_kind: kind.to_string(),
+                setup_url: None,
             }
         }
     }
 }
 
+async fn complete_launch(
+    kind: &BrowserKind,
+    logical_port: u16,
+    result: LaunchResult,
+) -> Result<BrowserControlLaunchResponse, String> {
+    match result {
+        LaunchResult::UserProfileReady { endpoint } => {
+            let connection = CdpClient::connect_user_profile_browser(
+                logical_port,
+                endpoint.port,
+                kind,
+                &endpoint.web_socket_url,
+            )
+            .await;
+            if let Err(error) = connection {
+                return Ok(BrowserControlLaunchResponse {
+                    success: false,
+                    status: "user_profile_connection_failed".into(),
+                    message: Some(error.to_string()),
+                    browser_kind: kind.to_string(),
+                    setup_url: None,
+                });
+            }
+            Ok(BrowserControlLaunchResponse {
+                success: true,
+                status: "connected_user_profile".into(),
+                message: None,
+                browser_kind: kind.to_string(),
+                setup_url: None,
+            })
+        }
+        other => Ok(to_launch_response(kind, other)),
+    }
+}
+
 /// Launch the user's default browser with CDP debug port.
 #[tauri::command]
 pub async fn browser_control_launch(
@@ -194,11 +375,64 @@ pub async fn browser_control_launch(
     let port = request.port;
     let kind = selected_browser_kind().await?;
 
+    if CdpClient::browser_connection_for_kind(port, &kind)
+        .await
+        .is_some()
+    {
+        return Ok(to_launch_response(&kind, LaunchResult::AlreadyConnected));
+    }
+
+    // The logical port is shared across browser choices. Drop only the lookup
+    // entry when the user switches browsers; any already-attached page session
+    // keeps its transport alive, but new actions cannot accidentally reuse it.
+    if CdpClient::browser_connection(port).await.is_some() {
+        CdpClient::remove_browser_connection(port).await;
+    }
+
     let result = BrowserLauncher::launch_with_cdp(&kind, port)
         .await
         .map_err(|e| e.to_string())?;
 
-    Ok(to_launch_response(&kind, result))
+    complete_launch(&kind, port, result).await
+}
+
+/// Open the selected browser's persistent guarded-CDP setting and wait for the
+/// user-owned consent toggle. Once enabled, immediately request and retain the
+/// real-profile connection so the Settings action is one continuous flow.
+#[tauri::command]
+pub async fn browser_control_enable_default_cdp(
+    request: BrowserControlLaunchRequest,
+) -> Result<BrowserControlLaunchResponse, String> {
+    let port = request.port;
+    let kind = selected_browser_kind().await?;
+
+    if !BrowserLauncher::supports_default_cdp(&kind) {
+        return Ok(BrowserControlLaunchResponse {
+            success: false,
+            status: "default_cdp_unsupported".into(),
+            message: Some(format!(
+                "{} does not expose a supported persistent guarded-CDP setting",
+                kind
+            )),
+            browser_kind: kind.to_string(),
+            setup_url: None,
+        });
+    }
+
+    if CdpClient::browser_connection_for_kind(port, &kind)
+        .await
+        .is_some()
+    {
+        return Ok(to_launch_response(&kind, LaunchResult::AlreadyConnected));
+    }
+    if CdpClient::browser_connection(port).await.is_some() {
+        CdpClient::remove_browser_connection(port).await;
+    }
+
+    let result = BrowserLauncher::enable_default_cdp(&kind, port)
+        .await
+        .map_err(|e| e.to_string())?;
+    complete_launch(&kind, port, result).await
 }
 
 /// Restart the user's default browser with CDP debug port enabled.
@@ -213,19 +447,5 @@ pub async fn browser_control_restart_with_cdp(
         .await
         .map_err(|e| e.to_string())?;
 
-    Ok(to_launch_response(&kind, result))
-}
-
-/// Create a macOS .app wrapper for the browser with CDP enabled.
-#[tauri::command]
-pub async fn browser_control_create_launcher() -> Result<String, String> {
-    #[cfg(target_os = "macos")]
-    {
-        let kind = selected_browser_kind().await?;
-        BrowserLauncher::create_cdp_launcher_app(&kind, DEFAULT_CDP_PORT).map_err(|e| e.to_string())
-    }
-    #[cfg(not(target_os = "macos"))]
-    {
-        Err("CDP launcher app creation is only supported on macOS".into())
-    }
+    complete_launch(&kind, port, result).await
 }
diff --git a/src/apps/desktop/src/api/commands.rs b/src/apps/desktop/src/api/commands.rs
index 70dbeeaa36..fc8ed169f3 100644
--- a/src/apps/desktop/src/api/commands.rs
+++ b/src/apps/desktop/src/api/commands.rs
@@ -16,20 +16,19 @@ use crate::api::search_api::{
 use crate::api::workspace_activation::spawn_workspace_background_warmup;
 use crate::startup_trace::DesktopStartupTrace;
 use bitfun_core::infrastructure::{
-    BatchedFileSearchProgressSink, FileSearchOutcome, FileSearchProgressSink, FileSearchResult,
-    FileSearchResultGroup, FileTreeNode, SearchMatchType,
+    BatchedFileSearchProgressSink, FileSearchResult, FileSearchResultGroup, FileTreeNode,
+    SearchMatchType,
 };
 use bitfun_core::service::file_watch;
 use bitfun_core::service::remote_ssh::get_remote_workspace_manager;
 use bitfun_core::service::remote_ssh::workspace_state::is_remote_path;
 use bitfun_core::service::remote_ssh::{
-    shell_quote_posix, RemoteDirEntry, RemoteFileService, RemoteWorkspaceEntry,
+    search_remote_file_names, shell_quote_posix, RemoteFileNameSearch,
 };
 use bitfun_core::service::workspace::{
     ScanOptions, WorkspaceInfo, WorkspaceKind, WorkspaceOpenOptions,
 };
 use log::{debug, error, info, warn};
-use regex::Regex;
 use serde::{Deserialize, Serialize};
 use std::io::{Read, Write};
 use std::path::{Path, PathBuf};
@@ -598,6 +597,8 @@ pub struct SearchFilenamesRequest {
     pub root_path: String,
     pub pattern: String,
     #[serde(default)]
+    pub remote_connection_id: Option<String>,
+    #[serde(default)]
     pub search_id: Option<String>,
     #[serde(default)]
     pub case_sensitive: bool,
@@ -611,6 +612,38 @@ pub struct SearchFilenamesRequest {
     pub include_directories: bool,
 }
 
+#[cfg(test)]
+mod search_filenames_request_tests {
+    use super::SearchFilenamesRequest;
+
+    #[test]
+    fn legacy_payload_without_remote_scope_remains_readable() {
+        let request: SearchFilenamesRequest = serde_json::from_value(serde_json::json!({
+            "rootPath": "/workspace",
+            "pattern": "src"
+        }))
+        .expect("deserialize legacy filename search request");
+
+        assert_eq!(request.remote_connection_id, None);
+        assert!(request.include_directories);
+    }
+
+    #[test]
+    fn remote_scope_is_deserialized_when_supplied() {
+        let request: SearchFilenamesRequest = serde_json::from_value(serde_json::json!({
+            "rootPath": "/workspace",
+            "pattern": "src",
+            "remoteConnectionId": "remote-connection-1"
+        }))
+        .expect("deserialize scoped filename search request");
+
+        assert_eq!(
+            request.remote_connection_id.as_deref(),
+            Some("remote-connection-1")
+        );
+    }
+}
+
 #[derive(Debug, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct SearchFileContentsRequest {
@@ -648,208 +681,6 @@ fn resolve_search_limit(requested: Option<usize>, fallback: usize) -> usize {
         .clamp(1, HARD_MAX_SEARCH_RESULTS)
 }
 
-fn compile_filename_search_regex(
-    pattern: &str,
-    case_sensitive: bool,
-    use_regex: bool,
-    whole_word: bool,
-) -> Result<Regex, String> {
-    let mut pattern = if use_regex {
-        pattern.to_string()
-    } else {
-        regex::escape(pattern)
-    };
-
-    if whole_word {
-        pattern = format!(r"\b(?:{})\b", pattern);
-    }
-
-    if !case_sensitive {
-        pattern = format!("(?i){}", pattern);
-    }
-
-    Regex::new(&pattern).map_err(|error| format!("Invalid search pattern: {}", error))
-}
-
-fn should_skip_remote_search_directory(name: &str) -> bool {
-    matches!(
-        name,
-        ".git"
-            | ".svn"
-            | ".hg"
-            | "node_modules"
-            | "target"
-            | "dist"
-            | "build"
-            | ".next"
-            | ".nuxt"
-            | ".cache"
-            | ".turbo"
-    )
-}
-
-fn should_skip_remote_search_file(name: &str) -> bool {
-    let lower = name.to_ascii_lowercase();
-    matches!(
-        lower.rsplit_once('.').map(|(_, ext)| ext),
-        Some(
-            "png"
-                | "jpg"
-                | "jpeg"
-                | "gif"
-                | "webp"
-                | "ico"
-                | "pdf"
-                | "zip"
-                | "tar"
-                | "gz"
-                | "rar"
-                | "7z"
-                | "exe"
-                | "dll"
-                | "so"
-                | "dylib"
-        )
-    )
-}
-
-fn remote_filename_search_result(entry: &RemoteDirEntry) -> FileSearchResult {
-    FileSearchResult {
-        path: entry.path.clone(),
-        name: entry.name.clone(),
-        is_directory: entry.is_dir,
-        match_type: SearchMatchType::FileName,
-        line_number: None,
-        matched_content: None,
-        preview_before: None,
-        preview_inside: None,
-        preview_after: None,
-    }
-}
-
-struct RemoteFilenameSearch {
-    remote_fs: RemoteFileService,
-    entry: RemoteWorkspaceEntry,
-    root_path: String,
-    pattern: String,
-    case_sensitive: bool,
-    use_regex: bool,
-    whole_word: bool,
-    include_directories: bool,
-    limit: usize,
-    cancel_flag: Option<Arc<AtomicBool>>,
-    progress_sink: Option<Arc<dyn FileSearchProgressSink>>,
-}
-
-async fn search_remote_file_names_with_progress(
-    search: RemoteFilenameSearch,
-) -> Result<FileSearchOutcome, String> {
-    let RemoteFilenameSearch {
-        remote_fs,
-        entry,
-        root_path,
-        pattern,
-        case_sensitive,
-        use_regex,
-        whole_word,
-        include_directories,
-        limit,
-        cancel_flag,
-        progress_sink,
-    } = search;
-    let matcher = compile_filename_search_regex(&pattern, case_sensitive, use_regex, whole_word)?;
-    let mut stack = vec![root_path];
-    let mut results = Vec::new();
-    let mut truncated = false;
-
-    while let Some(directory) = stack.pop() {
-        if cancel_flag
-            .as_ref()
-            .is_some_and(|flag| flag.load(Ordering::Relaxed))
-        {
-            break;
-        }
-
-        let mut entries = remote_fs
-            .read_dir(&entry.connection_id, &directory)
-            .await
-            .map_err(|error| format!("Failed to read remote directory: {}", error))?;
-        entries.sort_by(|a, b| match (a.is_dir, b.is_dir) {
-            (true, false) => std::cmp::Ordering::Less,
-            (false, true) => std::cmp::Ordering::Greater,
-            _ => a.name.cmp(&b.name),
-        });
-
-        for child in entries {
-            if cancel_flag
-                .as_ref()
-                .is_some_and(|flag| flag.load(Ordering::Relaxed))
-            {
-                break;
-            }
-
-            if child.is_dir {
-                if should_skip_remote_search_directory(&child.name) {
-                    continue;
-                }
-
-                if include_directories && matcher.is_match(&child.name) {
-                    let result = remote_filename_search_result(&child);
-                    if let Some(sink) = progress_sink.as_ref() {
-                        sink.report(FileSearchResultGroup {
-                            path: result.path.clone(),
-                            name: result.name.clone(),
-                            is_directory: result.is_directory,
-                            file_name_match: Some(result.clone()),
-                            content_matches: Vec::new(),
-                        });
-                    }
-                    results.push(result);
-                    if results.len() >= limit {
-                        truncated = true;
-                        break;
-                    }
-                }
-
-                stack.push(child.path);
-                continue;
-            }
-
-            if !child.is_file || should_skip_remote_search_file(&child.name) {
-                continue;
-            }
-
-            if matcher.is_match(&child.name) {
-                let result = remote_filename_search_result(&child);
-                if let Some(sink) = progress_sink.as_ref() {
-                    sink.report(FileSearchResultGroup {
-                        path: result.path.clone(),
-                        name: result.name.clone(),
-                        is_directory: result.is_directory,
-                        file_name_match: Some(result.clone()),
-                        content_matches: Vec::new(),
-                    });
-                }
-                results.push(result);
-                if results.len() >= limit {
-                    truncated = true;
-                    break;
-                }
-            }
-        }
-
-        if truncated {
-            break;
-        }
-    }
-
-    if let Some(sink) = progress_sink.as_ref() {
-        sink.flush();
-    }
-
-    Ok(FileSearchOutcome { results, truncated })
-}
-
 #[derive(Debug, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct RenameFileRequest {
@@ -5077,14 +4908,20 @@ pub async fn search_filenames(
         include_directories: request.include_directories,
     };
 
-    let result = match resolve_desktop_path_target(&state, &request.root_path, None).await {
+    let result = match resolve_desktop_path_target(
+        &state,
+        &request.root_path,
+        request.remote_connection_id.as_deref(),
+    )
+    .await
+    {
         Ok(DesktopPathTarget::Remote {
             requested_path,
             entry,
         }) => match state.get_remote_file_service_async().await {
-            Ok(remote_fs) => search_remote_file_names_with_progress(RemoteFilenameSearch {
+            Ok(remote_fs) => search_remote_file_names(RemoteFileNameSearch {
                 remote_fs,
-                entry,
+                workspace: entry,
                 root_path: requested_path,
                 pattern: request.pattern.clone(),
                 case_sensitive: request.case_sensitive,
@@ -5222,27 +5059,32 @@ pub async fn start_search_filenames_stream(
         include_directories: request.include_directories,
     };
 
-    let remote_search_target =
-        match resolve_desktop_path_target(&state, &request.root_path, None).await {
-            Ok(DesktopPathTarget::Remote {
-                requested_path,
-                entry,
-            }) => {
-                let remote_fs = match state.get_remote_file_service_async().await {
-                    Ok(remote_fs) => remote_fs,
-                    Err(error) => {
-                        unregister_search(&state, Some(&search_id));
-                        return Err(format!("Remote file service not available: {}", error));
-                    }
-                };
-                Some((remote_fs, entry, requested_path))
-            }
-            Ok(DesktopPathTarget::Local { .. }) => None,
-            Err(error) => {
-                unregister_search(&state, Some(&search_id));
-                return Err(error);
-            }
-        };
+    let remote_search_target = match resolve_desktop_path_target(
+        &state,
+        &request.root_path,
+        request.remote_connection_id.as_deref(),
+    )
+    .await
+    {
+        Ok(DesktopPathTarget::Remote {
+            requested_path,
+            entry,
+        }) => {
+            let remote_fs = match state.get_remote_file_service_async().await {
+                Ok(remote_fs) => remote_fs,
+                Err(error) => {
+                    unregister_search(&state, Some(&search_id));
+                    return Err(format!("Remote file service not available: {}", error));
+                }
+            };
+            Some((remote_fs, entry, requested_path))
+        }
+        Ok(DesktopPathTarget::Local { .. }) => None,
+        Err(error) => {
+            unregister_search(&state, Some(&search_id));
+            return Err(error);
+        }
+    };
 
     let filesystem_service = state.filesystem_service.clone();
     let active_searches = state.active_searches.clone();
@@ -5270,9 +5112,9 @@ pub async fn start_search_filenames_stream(
 
     tokio::spawn(async move {
         let result = if let Some((remote_fs, entry, requested_path)) = remote_search_target {
-            search_remote_file_names_with_progress(RemoteFilenameSearch {
+            search_remote_file_names(RemoteFileNameSearch {
                 remote_fs,
-                entry,
+                workspace: entry,
                 root_path: requested_path,
                 pattern: pattern.clone(),
                 case_sensitive,
@@ -5570,6 +5412,13 @@ pub async fn get_ai_model_catalog() -> Result<bitfun_core::AIModelCatalog, Strin
     bitfun_core::get_ai_model_catalog().await
 }
 
+#[tauri::command]
+pub async fn project_ai_model_reasoning_catalog(
+    request: bitfun_core_types::ReasoningCatalogProjectionRequest,
+) -> bitfun_core_types::ReasoningCatalogProjection {
+    bitfun_core::project_ai_model_reasoning_catalog(request).await
+}
+
 #[tauri::command]
 pub async fn get_models_dev_catalog_status() -> bitfun_core_types::ModelsDevCatalogStatus {
     bitfun_core::get_models_dev_catalog_status().await
diff --git a/src/apps/desktop/src/api/external_sources_api.rs b/src/apps/desktop/src/api/external_sources_api.rs
index 0890159bac..9288eb1f25 100644
--- a/src/apps/desktop/src/api/external_sources_api.rs
+++ b/src/apps/desktop/src/api/external_sources_api.rs
@@ -7,17 +7,18 @@ use bitfun_core::external_sources::{
     external_source_snapshot,
     get_external_source_control_snapshot as core_get_external_source_control_snapshot,
     native_prompt_command_conflicts, set_external_mcp_server_decision,
-    set_external_prompt_command_conflict_choice, set_external_source_enabled,
-    set_external_subagent_activation, set_external_subagent_model_binding,
+    set_external_mcp_servers_enabled, set_external_prompt_command_conflict_choice,
+    set_external_source_enabled, set_external_subagent_activation,
+    set_external_subagent_model_binding, set_external_subagents_enabled,
     set_external_tool_conflict_choice, set_external_tool_target_decision,
-    set_native_prompt_command_conflict_choice, unacknowledged_external_ecosystems,
-    update_external_integration_policy, workspace_reference_snapshot,
-    ExternalIntegrationPolicyMutation, ExternalSourceControlRequestV1,
-    ExternalSourceHostCapabilities, ExternalSourceOperationError, ExternalSourceOperationErrorCode,
-    ExternalSourceOperationResult, ExternalSourcePublicSnapshot, ExternalSourceSurfaceSnapshotV1,
-    ExternalSubagentModelBindingTarget, NativePromptCommandConflictSnapshot,
-    NativePromptCommandDescriptor, PromptCommandInvocationOutcome,
-    PromptCommandShellReviewDecision,
+    set_external_tool_targets_enabled, set_native_prompt_command_conflict_choice,
+    unacknowledged_external_ecosystems, update_external_integration_policy,
+    workspace_reference_snapshot, ExternalIntegrationPolicyMutation,
+    ExternalSourceControlRequestV1, ExternalSourceHostCapabilities, ExternalSourceOperationError,
+    ExternalSourceOperationErrorCode, ExternalSourceOperationResult, ExternalSourcePublicSnapshot,
+    ExternalSourceSurfaceSnapshotV1, ExternalSubagentModelBindingTarget,
+    NativePromptCommandConflictSnapshot, NativePromptCommandDescriptor,
+    PromptCommandInvocationOutcome, PromptCommandShellReviewDecision,
 };
 use bitfun_core::service::remote_ssh::workspace_state::is_remote_path;
 use bitfun_core::service::remote_ssh::workspace_state::{
@@ -154,6 +155,23 @@ pub struct SetExternalToolTargetDecisionRequest {
     pub expected_preference_revision: u64,
 }
 
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct ExternalToolDecisionRef {
+    pub approval_key: String,
+    pub decision_key: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct SetExternalToolTargetsEnabledRequest {
+    pub workspace_path: Option<String>,
+    pub decisions: Vec<ExternalToolDecisionRef>,
+    pub enabled: bool,
+    pub expected_catalog_generation: u64,
+    pub expected_preference_revision: u64,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct SetExternalToolConflictChoiceRequest {
@@ -174,6 +192,23 @@ pub struct SetExternalSubagentActivationRequest {
     pub decision_key: String,
 }
 
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct ExternalCandidateDecisionRef {
+    pub candidate_id: String,
+    pub decision_key: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct SetExternalSubagentsEnabledRequest {
+    pub workspace_path: Option<String>,
+    pub decisions: Vec<ExternalCandidateDecisionRef>,
+    pub enabled: bool,
+    pub expected_subagent_generation: u64,
+    pub expected_preference_revision: u64,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct SetExternalSubagentModelBindingRequest {
@@ -207,6 +242,16 @@ pub struct SetExternalMcpServerDecisionRequest {
     pub expected_preference_revision: u64,
 }
 
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct SetExternalMcpServersEnabledRequest {
+    pub workspace_path: Option<String>,
+    pub decisions: Vec<ExternalCandidateDecisionRef>,
+    pub enabled: bool,
+    pub expected_mcp_generation: u64,
+    pub expected_preference_revision: u64,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct ChooseExternalMcpConflictRequest {
@@ -553,6 +598,27 @@ pub async fn set_external_tool_target_decision_command(
     .map_err(bitfun_core::external_sources::sanitize_external_source_operation_error)
 }
 
+#[tauri::command]
+pub async fn set_external_tool_targets_enabled_command(
+    request: SetExternalToolTargetsEnabledRequest,
+) -> ExternalSourceOperationResult<ExternalSourceSnapshotResponse> {
+    let workspace = require_local_workspace(request.workspace_path.as_deref()).await?;
+    set_external_tool_targets_enabled(
+        workspace,
+        request
+            .decisions
+            .into_iter()
+            .map(|decision| (decision.approval_key, decision.decision_key))
+            .collect(),
+        request.enabled,
+        request.expected_catalog_generation,
+        request.expected_preference_revision,
+    )
+    .await
+    .map(Into::into)
+    .map_err(bitfun_core::external_sources::sanitize_external_source_operation_error)
+}
+
 #[tauri::command]
 pub async fn set_external_tool_conflict_choice_command(
     request: SetExternalToolConflictChoiceRequest,
@@ -587,6 +653,27 @@ pub async fn set_external_subagent_activation_command(
     .map_err(bitfun_core::external_sources::sanitize_external_source_operation_error)
 }
 
+#[tauri::command]
+pub async fn set_external_subagents_enabled_command(
+    request: SetExternalSubagentsEnabledRequest,
+) -> ExternalSourceOperationResult<ExternalSourceSnapshotResponse> {
+    let workspace = require_local_workspace(request.workspace_path.as_deref()).await?;
+    set_external_subagents_enabled(
+        workspace,
+        request
+            .decisions
+            .into_iter()
+            .map(|decision| (decision.candidate_id, decision.decision_key))
+            .collect(),
+        request.enabled,
+        request.expected_subagent_generation,
+        request.expected_preference_revision,
+    )
+    .await
+    .map(Into::into)
+    .map_err(bitfun_core::external_sources::sanitize_external_source_operation_error)
+}
+
 #[tauri::command]
 pub async fn set_external_subagent_model_binding_command(
     request: SetExternalSubagentModelBindingRequest,
@@ -640,6 +727,27 @@ pub async fn set_external_mcp_server_decision_command(
     .map_err(bitfun_core::external_sources::sanitize_external_source_operation_error)
 }
 
+#[tauri::command]
+pub async fn set_external_mcp_servers_enabled_command(
+    request: SetExternalMcpServersEnabledRequest,
+) -> ExternalSourceOperationResult<ExternalSourceSnapshotResponse> {
+    let workspace = require_local_workspace(request.workspace_path.as_deref()).await?;
+    set_external_mcp_servers_enabled(
+        workspace,
+        request
+            .decisions
+            .into_iter()
+            .map(|decision| (decision.candidate_id, decision.decision_key))
+            .collect(),
+        request.enabled,
+        request.expected_mcp_generation,
+        request.expected_preference_revision,
+    )
+    .await
+    .map(Into::into)
+    .map_err(bitfun_core::external_sources::sanitize_external_source_operation_error)
+}
+
 #[tauri::command]
 pub async fn choose_external_mcp_conflict_command(
     request: ChooseExternalMcpConflictRequest,
diff --git a/src/apps/desktop/src/api/lsp_workspace_api.rs b/src/apps/desktop/src/api/lsp_workspace_api.rs
index bf13e53e77..b16f154fb2 100644
--- a/src/apps/desktop/src/api/lsp_workspace_api.rs
+++ b/src/apps/desktop/src/api/lsp_workspace_api.rs
@@ -6,12 +6,11 @@ use std::collections::HashMap;
 use std::path::PathBuf;
 use std::sync::Arc;
 
-use bitfun_core::infrastructure::events::TransportEmitter;
 use bitfun_core::service::lsp::types::CompletionItem;
 use bitfun_core::service::lsp::{
     close_workspace, get_workspace_manager, open_workspace_with_emitter, ServerState,
 };
-use bitfun_transport::TauriTransportAdapter;
+use bitfun_transport::{TauriTransportAdapter, TransportEmitter};
 
 #[derive(Debug, Deserialize)]
 #[serde(rename_all = "camelCase")]
diff --git a/src/apps/desktop/src/api/mod.rs b/src/apps/desktop/src/api/mod.rs
index 465b009951..61a85c19df 100644
--- a/src/apps/desktop/src/api/mod.rs
+++ b/src/apps/desktop/src/api/mod.rs
@@ -55,7 +55,6 @@ pub mod skill_api;
 pub mod snapshot_service;
 pub mod speech_api;
 pub mod ssh_api;
-pub mod startchat_agent_api;
 pub mod storage_commands;
 pub mod subagent_api;
 pub mod system_api;
diff --git a/src/apps/desktop/src/api/path_target.rs b/src/apps/desktop/src/api/path_target.rs
index 598f9fa52a..b7fd4b6f1e 100644
--- a/src/apps/desktop/src/api/path_target.rs
+++ b/src/apps/desktop/src/api/path_target.rs
@@ -123,12 +123,15 @@ async fn lookup_remote_entry_for_path(
     }
 
     let manager = get_remote_workspace_manager()?;
+    if let Some(connection_id) = request_preferred {
+        return manager.lookup_scoped_connection(path, connection_id).await;
+    }
+
     let legacy = app_state
         .get_remote_workspace_async()
         .await
         .map(|workspace| workspace.connection_id);
-    let preferred = request_preferred.map(|s| s.to_string()).or(legacy);
-    manager.lookup_connection(path, preferred.as_deref()).await
+    manager.lookup_connection(path, legacy.as_deref()).await
 }
 
 fn should_force_local_assistant_path(
@@ -152,8 +155,11 @@ pub async fn resolve_desktop_path_target(
         });
     }
 
+    let explicit_connection_id = preferred_remote_connection_id
+        .map(str::trim)
+        .filter(|value| !value.is_empty());
     if let Some(entry) =
-        lookup_remote_entry_for_path(app_state, raw_path, preferred_remote_connection_id).await
+        lookup_remote_entry_for_path(app_state, raw_path, explicit_connection_id).await
     {
         return Ok(DesktopPathTarget::Remote {
             requested_path: raw_path.to_string(),
@@ -161,6 +167,13 @@ pub async fn resolve_desktop_path_target(
         });
     }
 
+    if let Some(connection_id) = explicit_connection_id {
+        return Err(format!(
+            "Remote workspace connection '{}' is unavailable or does not own path '{}'; local filesystem fallback was not attempted",
+            connection_id, raw_path
+        ));
+    }
+
     Ok(DesktopPathTarget::Local {
         requested_path: raw_path.to_string(),
         resolved_path: PathBuf::from(raw_path),
diff --git a/src/apps/desktop/src/api/peer_host_invoke.rs b/src/apps/desktop/src/api/peer_host_invoke.rs
index bac4f20251..3054b596eb 100644
--- a/src/apps/desktop/src/api/peer_host_invoke.rs
+++ b/src/apps/desktop/src/api/peer_host_invoke.rs
@@ -119,6 +119,7 @@ static LOCAL_ONLY_COMMANDS: &[&str] = &[
     "dispatch_list_jobs",
     "dispatch_answer",
     "dispatch_append",
+    "dispatch_continue",
     "dispatch_load_transcript",
     "dispatch_save_transcript",
     // One-click relay deploy SSHes from the controller to a user host
@@ -129,6 +130,16 @@ static LOCAL_ONLY_COMMANDS: &[&str] = &[
     "relay_deploy_cancel",
     "relay_deploy_register",
     "relay_deploy_verify",
+    // Speech capture and model files belong to the machine the user speaks at.
+    "speech_list_models",
+    "speech_download_model",
+    "speech_cancel_model_download",
+    "speech_delete_model",
+    "speech_verify_model",
+    "speech_start_input_session",
+    "speech_append_audio_chunk",
+    "speech_finish_input_session",
+    "speech_cancel_input_session",
 ];
 
 static PENDING: OnceLock<Mutex<HashMap<String, oneshot::Sender<HostInvokeBridgeResult>>>> =
@@ -350,6 +361,7 @@ pub async fn peer_mode_ping() -> Result<Value, String> {
             .unwrap_or_else(|_| "unknown".to_string()),
         "capabilities": {
             "idempotent_dialog_submit": true,
+            "targeted_session_rollback": true,
         },
     }))
 }
@@ -449,7 +461,7 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn peer_ping_advertises_idempotent_dialog_submission() {
+    async fn peer_ping_advertises_mutation_capabilities() {
         let value = peer_mode_ping().await.expect("peer ping");
         assert_eq!(
             value
@@ -457,6 +469,12 @@ mod tests {
                 .and_then(Value::as_bool),
             Some(true)
         );
+        assert_eq!(
+            value
+                .pointer("/capabilities/targeted_session_rollback")
+                .and_then(Value::as_bool),
+            Some(true)
+        );
     }
 
     #[test]
@@ -476,6 +494,30 @@ mod tests {
         }
     }
 
+    /// The controller-side FE deny list is an optimization, not the boundary.
+    /// A controller on an older build (or a non-FE controller) still reaches
+    /// this host, so every controller-owned command must be refused here too.
+    #[test]
+    fn controller_owned_capture_and_dispatch_commands_are_refused_on_the_peer() {
+        for command in [
+            // Capture and model files belong to the machine the user speaks at.
+            "speech_list_models",
+            "speech_download_model",
+            "speech_cancel_model_download",
+            "speech_delete_model",
+            "speech_verify_model",
+            "speech_start_input_session",
+            "speech_append_audio_chunk",
+            "speech_finish_input_session",
+            "speech_cancel_input_session",
+            // Same controller-owned observer/credential family as the other
+            // dispatch verbs already denied here.
+            "dispatch_continue",
+        ] {
+            assert!(is_local_only_command(command), "{command}");
+        }
+    }
+
     #[test]
     fn only_the_final_detach_drains_peer_permission_requests() {
         let mut state = control_state(&["controller-a", "controller-b"], &["request-1"]);
diff --git a/src/apps/desktop/src/api/remote_connect_api.rs b/src/apps/desktop/src/api/remote_connect_api.rs
index 37ec27c71d..86bc51a02e 100644
--- a/src/apps/desktop/src/api/remote_connect_api.rs
+++ b/src/apps/desktop/src/api/remote_connect_api.rs
@@ -22,7 +22,7 @@ use bitfun_core::service::remote_connect::{
     bot::{self, weixin, BotConfig},
     lan, session_store, sync_state, AccountClient, AccountPairingVerification, AccountSession,
     ConnectionMethod, ConnectionResult, DelegatedIdentityAuthorization, DeviceIdentity,
-    PairingState, RemoteConnectConfig, RemoteConnectService,
+    PairingState, ProvisionedDeviceAuthorization, RemoteConnectConfig, RemoteConnectService,
 };
 use bitfun_core::service::session::{DialogTurnData, SessionMetadata};
 use bitfun_core::service::workspace::{get_global_workspace_service, WorkspaceKind};
@@ -82,6 +82,17 @@ static ACCOUNT_CONTEXT_TRANSITIONS: AtomicUsize = AtomicUsize::new(0);
 static DEVICE_ROUTING_LIFECYCLE_LOCK: tokio::sync::RwLock<()> = tokio::sync::RwLock::const_new(());
 static DEVICE_ROUTING_CONNECTION_ID: AtomicU64 = AtomicU64::new(0);
 
+/// Ceiling on device RPCs executing at once.
+///
+/// RPCs run off the routing loop rather than on it, so without a bound a phone
+/// that fans out a screenful of `list_sessions` would put all of them on the
+/// webview bridge at once. The bound exists to keep that burst from crowding
+/// out the next device's first request, not because concurrency is unsafe:
+/// each RPC holds its own routing lease and answers its own correlation id.
+const MAX_CONCURRENT_DEVICE_RPCS: usize = 8;
+static DEVICE_RPC_SLOTS: tokio::sync::Semaphore =
+    tokio::sync::Semaphore::const_new(MAX_CONCURRENT_DEVICE_RPCS);
+
 #[derive(Clone, Debug, Eq, PartialEq)]
 struct DeviceRoutingOwner {
     account_generation: u64,
@@ -359,6 +370,37 @@ fn emit_account_event(event: &str, payload: serde_json::Value) {
     }
 }
 
+/// Payload key carrying the device that produced a re-emitted Peer DeviceEvent.
+///
+/// The controller re-emits peer events under their original event name so the
+/// existing listeners keep working, which means a controller that is also
+/// running its own local work would otherwise see two indistinguishable
+/// streams on one bus. The frontend routes on this key and delivers an event
+/// only to the device surface it belongs to. Keep in sync with
+/// `src/web-ui/src/infrastructure/peer-device/deviceSurfaceRouting.ts`.
+pub const PEER_EVENT_SOURCE_KEY: &str = "__bitfunSourceDeviceId";
+
+/// Wrapper key used when a peer payload is not a JSON object and therefore
+/// cannot carry `PEER_EVENT_SOURCE_KEY` inline.
+pub const PEER_EVENT_WRAPPED_PAYLOAD_KEY: &str = "__bitfunSourcePayload";
+
+/// Tag a peer-originated event payload with the device that produced it.
+fn tag_peer_event_source(payload: serde_json::Value, source_device_id: &str) -> serde_json::Value {
+    let source = serde_json::Value::String(source_device_id.to_string());
+    match payload {
+        serde_json::Value::Object(mut map) => {
+            map.insert(PEER_EVENT_SOURCE_KEY.to_string(), source);
+            serde_json::Value::Object(map)
+        }
+        other => {
+            let mut map = serde_json::Map::new();
+            map.insert(PEER_EVENT_SOURCE_KEY.to_string(), source);
+            map.insert(PEER_EVENT_WRAPPED_PAYLOAD_KEY.to_string(), other);
+            serde_json::Value::Object(map)
+        }
+    }
+}
+
 fn emit_device_presence(devices: &[(String, String)]) {
     let payload = serde_json::json!({
         "devices": devices
@@ -902,6 +944,7 @@ pub(crate) async fn provision_dispatch_account_device(
             &session,
             &identity.device_id,
             &identity.device_name,
+            "desktop",
             uuid::Uuid::new_v4(),
         )
         .await
@@ -1220,6 +1263,62 @@ async fn register_delegated_identity_providers() {
             })
             .await;
 
+        // Room-channel provider that adds a keyboard-less device (a watch) to
+        // this account. Same lease discipline as delegation above; the errors
+        // are returned rather than swallowed because a provisioning failure is
+        // shown to someone standing there waiting for it.
+        let account_context = get_account_context().clone();
+        service
+            .set_peer_device_provisioner(move |device_id, device_name, request_id| {
+                let account_context = account_context.clone();
+                Box::pin(async move {
+                    // Minted by the device being provisioned so a retry anywhere
+                    // along the chain replays one idempotent relay request.
+                    let request_id = uuid::Uuid::parse_str(&request_id)
+                        .map_err(|_| "Request id must be a UUID".to_string())?;
+                    let generation = account_context_generation();
+                    if !account_context_is_current(generation) {
+                        return Err("Desktop account changed; try again".to_string());
+                    }
+                    let account_lease = lock_account_sync(generation)
+                        .await
+                        .map_err(|_| "Desktop account changed; try again".to_string())?;
+                    let context = account_context
+                        .read()
+                        .await
+                        .clone()
+                        .ok_or_else(|| "Desktop is not logged into a BitFun account".to_string())?;
+                    if !account_context_matches(generation, &context.session.token).await {
+                        return Err("Desktop account changed; try again".to_string());
+                    }
+                    let provisioned = AccountClient::new()
+                        .provision_device_token(
+                            &context.relay_url,
+                            &context.session,
+                            &device_id,
+                            &device_name,
+                            "watch",
+                            request_id,
+                        )
+                        .await
+                        .map_err(|e| {
+                            log::warn!("Provision device token failed: {e}");
+                            format!("Could not add the device to your account: {e}")
+                        })?;
+                    if !account_context_matches(generation, &context.session.token).await {
+                        return Err("Desktop account changed; try again".to_string());
+                    }
+                    Ok(ProvisionedDeviceAuthorization::with_host_lease(
+                        provisioned.token,
+                        provisioned.user_id,
+                        context.session.master_key,
+                        provisioned.device_id,
+                        account_lease,
+                    ))
+                })
+            })
+            .await;
+
         // Account-mode mobile pairing: QR prefill + password verification.
         register_account_pairing_context(service).await;
 
@@ -2727,9 +2826,15 @@ pub async fn account_connect_devices() -> Result<Vec<OnlineDeviceInfo>, String>
                                         break 'routing_events;
                                     };
                                     // Controller receiving peer UI events — re-emit locally
-                                    // under the same event name so PeerDeviceTransport listen works.
+                                    // under the same event name so PeerDeviceTransport listen
+                                    // works. The source device is tagged onto the payload so a
+                                    // controller that is also running local work can route each
+                                    // stream to the right device surface.
                                     log::debug!("DeviceEvent from {source_device_id}: {event}");
-                                    emit_account_event(&event, payload);
+                                    emit_account_event(
+                                        &event,
+                                        tag_peer_event_source(payload, &source_device_id),
+                                    );
                                 }
                                 Ok(RemoteCommand::ExecuteOnDevice {
                                     session_id,
@@ -2826,7 +2931,10 @@ pub async fn account_connect_devices() -> Result<Vec<OnlineDeviceInfo>, String>
                                     }
                                 }
                                 Ok(cmd) if source_device_id == "rpc" => {
-                                    let Some(_routing_effect) =
+                                    // The lease is taken here, on the loop, so a
+                                    // retiring loop still notices it has been
+                                    // replaced and stops reading events at once.
+                                    let Some(routing_effect) =
                                         lock_current_device_routing(&event_owner).await
                                     else {
                                         break 'routing_events;
@@ -2837,34 +2945,56 @@ pub async fn account_connect_devices() -> Result<Vec<OnlineDeviceInfo>, String>
                                     log::info!(
                                         "RPC request received from relay: corr={correlation_id}"
                                     );
-                                    let execution = execute_local_remote_command(&cmd).await;
-                                    if !device_routing_owner_is_current(&event_owner).await {
-                                        break 'routing_events;
-                                    }
-                                    match execution {
-                                        Ok(resp_value) => {
-                                            send_rpc_envelope(
-                                                &event_owner,
-                                                &event_session,
-                                                &correlation_id,
-                                                resp_value,
-                                            )
-                                            .await;
+                                    // Spawned rather than awaited. Most commands
+                                    // are answered by the webview, which can take
+                                    // up to DEFAULT_INVOKE_TIMEOUT (120s) to reply;
+                                    // awaiting here meant one slow command stalled
+                                    // every device behind it, so a `ping` from the
+                                    // watch could take 40s to come back for no
+                                    // reason of its own. Each RPC carries its own
+                                    // correlation id, so nothing about the reply
+                                    // path depends on them finishing in order.
+                                    let rpc_owner = event_owner.clone();
+                                    let rpc_session = event_session.clone();
+                                    tokio::spawn(async move {
+                                        // Held for the whole call: teardown takes
+                                        // the write lease, so an in-flight RPC now
+                                        // keeps the connection from being replaced
+                                        // out from under its own reply.
+                                        let _routing_effect = routing_effect;
+                                        let Ok(_slot) = DEVICE_RPC_SLOTS.acquire().await else {
+                                            return;
+                                        };
+                                        let execution = execute_local_remote_command(&cmd).await;
+                                        // Returning drops this reply only. The loop
+                                        // re-checks ownership at the top of every
+                                        // iteration, so a stale connection is still
+                                        // retired there — just not from in here.
+                                        if !device_routing_owner_is_current(&rpc_owner).await {
+                                            return;
                                         }
-                                        Err(e) => {
-                                            log::warn!("RPC: execute command failed: {e}");
-                                            send_rpc_error(
-                                                &event_owner,
-                                                &event_session,
-                                                &correlation_id,
-                                                format!("RPC execute failed: {e}"),
-                                            )
-                                            .await;
+                                        match execution {
+                                            Ok(resp_value) => {
+                                                send_rpc_envelope(
+                                                    &rpc_owner,
+                                                    &rpc_session,
+                                                    &correlation_id,
+                                                    resp_value,
+                                                )
+                                                .await;
+                                            }
+                                            Err(e) => {
+                                                log::warn!("RPC: execute command failed: {e}");
+                                                send_rpc_error(
+                                                    &rpc_owner,
+                                                    &rpc_session,
+                                                    &correlation_id,
+                                                    format!("RPC execute failed: {e}"),
+                                                )
+                                                .await;
+                                            }
                                         }
-                                    }
-                                    if !device_routing_owner_is_current(&event_owner).await {
-                                        break 'routing_events;
-                                    }
+                                    });
                                 }
                                 Ok(cmd) => {
                                     let _ = cmd;
diff --git a/src/apps/desktop/src/api/remote_workspace_policy.rs b/src/apps/desktop/src/api/remote_workspace_policy.rs
index 825ea77ef5..89912d6c40 100644
--- a/src/apps/desktop/src/api/remote_workspace_policy.rs
+++ b/src/apps/desktop/src/api/remote_workspace_policy.rs
@@ -228,7 +228,6 @@ pub const REMOTE_WORKSPACE_COMMAND_POLICIES: &[(&str, RemoteWorkspacePolicy)] =
         RemoteWorkspacePolicy::LegacyUnaudited,
     ),
     ("add_skill", RemoteWorkspacePolicy::LegacyUnaudited),
-    ("analyze_work_state", RemoteWorkspacePolicy::LegacyUnaudited),
     (
         "apply_external_mcp_import_command",
         RemoteWorkspacePolicy::RemoteUnsupported,
@@ -252,7 +251,7 @@ pub const REMOTE_WORKSPACE_COMMAND_POLICIES: &[(&str, RemoteWorkspacePolicy)] =
     ),
     ("archive_session", RemoteWorkspacePolicy::LegacyUnaudited),
     (
-        "browser_control_create_launcher",
+        "browser_control_enable_default_cdp",
         RemoteWorkspacePolicy::LocalOnly,
     ),
     (
@@ -284,6 +283,7 @@ pub const REMOTE_WORKSPACE_COMMAND_POLICIES: &[(&str, RemoteWorkspacePolicy)] =
         RemoteWorkspacePolicy::LegacyUnaudited,
     ),
     ("cancel_dialog_turn", RemoteWorkspacePolicy::LegacyUnaudited),
+    ("interrupt_dialog_turn", RemoteWorkspacePolicy::LocalOnly),
     (
         "cancel_insights_generation",
         RemoteWorkspacePolicy::LocalOnly,
@@ -497,13 +497,10 @@ pub const REMOTE_WORKSPACE_COMMAND_POLICIES: &[(&str, RemoteWorkspacePolicy)] =
         "expand_external_prompt_command_command",
         RemoteWorkspacePolicy::RemoteUnsupported,
     ),
-    (
-        "explorer_get_children",
-        RemoteWorkspacePolicy::LegacyUnaudited,
-    ),
+    ("explorer_get_children", RemoteWorkspacePolicy::RemoteRouted),
     (
         "explorer_get_children_paginated",
-        RemoteWorkspacePolicy::LegacyUnaudited,
+        RemoteWorkspacePolicy::RemoteRouted,
     ),
     (
         "explorer_get_file_tree",
@@ -531,10 +528,6 @@ pub const REMOTE_WORKSPACE_COMMAND_POLICIES: &[(&str, RemoteWorkspacePolicy)] =
         "generate_commit_message",
         RemoteWorkspacePolicy::LegacyUnaudited,
     ),
-    (
-        "generate_greeting_only",
-        RemoteWorkspacePolicy::LegacyUnaudited,
-    ),
     ("generate_insights", RemoteWorkspacePolicy::RemoteRouted),
     (
         "generate_session_title",
@@ -561,6 +554,10 @@ pub const REMOTE_WORKSPACE_COMMAND_POLICIES: &[(&str, RemoteWorkspacePolicy)] =
         "get_ai_model_catalog",
         RemoteWorkspacePolicy::WorkspaceAgnostic,
     ),
+    (
+        "project_ai_model_reasoning_catalog",
+        RemoteWorkspacePolicy::WorkspaceAgnostic,
+    ),
     (
         "get_models_dev_catalog_status",
         RemoteWorkspacePolicy::LocalOnly,
@@ -608,11 +605,11 @@ pub const REMOTE_WORKSPACE_COMMAND_POLICIES: &[(&str, RemoteWorkspacePolicy)] =
     ),
     (
         "get_directory_children",
-        RemoteWorkspacePolicy::LegacyUnaudited,
+        RemoteWorkspacePolicy::RemoteRouted,
     ),
     (
         "get_directory_children_paginated",
-        RemoteWorkspacePolicy::LegacyUnaudited,
+        RemoteWorkspacePolicy::RemoteRouted,
     ),
     (
         "get_external_hook_catalog",
@@ -811,10 +808,6 @@ pub const REMOTE_WORKSPACE_COMMAND_POLICIES: &[(&str, RemoteWorkspacePolicy)] =
     ("get_tool_info", RemoteWorkspacePolicy::LegacyUnaudited),
     ("get_turn_files", RemoteWorkspacePolicy::LegacyUnaudited),
     ("get_watched_paths", RemoteWorkspacePolicy::LegacyUnaudited),
-    (
-        "get_work_state_summary",
-        RemoteWorkspacePolicy::LegacyUnaudited,
-    ),
     ("git_add_files", RemoteWorkspacePolicy::RemoteRouted),
     ("git_add_worktree", RemoteWorkspacePolicy::RemoteUnsupported),
     ("git_checkout_branch", RemoteWorkspacePolicy::RemoteRouted),
@@ -1400,10 +1393,6 @@ pub const REMOTE_WORKSPACE_COMMAND_POLICIES: &[(&str, RemoteWorkspacePolicy)] =
         "probe_acp_client_requirements",
         RemoteWorkspacePolicy::LegacyUnaudited,
     ),
-    (
-        "quick_analyze_work_state",
-        RemoteWorkspacePolicy::LegacyUnaudited,
-    ),
     (
         "quick_commit_message",
         RemoteWorkspacePolicy::LegacyUnaudited,
@@ -1421,10 +1410,6 @@ pub const REMOTE_WORKSPACE_COMMAND_POLICIES: &[(&str, RemoteWorkspacePolicy)] =
     ),
     ("read_mcp_resource", RemoteWorkspacePolicy::LegacyUnaudited),
     ("record_file_change", RemoteWorkspacePolicy::LegacyUnaudited),
-    (
-        "record_local_command_turn",
-        RemoteWorkspacePolicy::RemoteRouted,
-    ),
     (
         "refresh_model_client",
         RemoteWorkspacePolicy::LegacyUnaudited,
@@ -1455,6 +1440,10 @@ pub const REMOTE_WORKSPACE_COMMAND_POLICIES: &[(&str, RemoteWorkspacePolicy)] =
         "remove_project_permission_grant",
         RemoteWorkspacePolicy::WorkspaceAgnostic,
     ),
+    (
+        "recover_interrupted_dialog_turn",
+        RemoteWorkspacePolicy::LocalOnly,
+    ),
     (
         "clear_project_permission_grants",
         RemoteWorkspacePolicy::WorkspaceAgnostic,
@@ -1695,7 +1684,10 @@ pub const REMOTE_WORKSPACE_COMMAND_POLICIES: &[(&str, RemoteWorkspacePolicy)] =
     ),
     ("rollback_miniapp", RemoteWorkspacePolicy::LegacyUnaudited),
     ("rollback_session", RemoteWorkspacePolicy::RemoteUnsupported),
-    ("rollback_to_turn", RemoteWorkspacePolicy::RemoteUnsupported),
+    (
+        "rollback_session_to_turn",
+        RemoteWorkspacePolicy::RemoteUnsupported,
+    ),
     ("run_init_agents_md", RemoteWorkspacePolicy::LegacyUnaudited),
     ("run_system_command", RemoteWorkspacePolicy::LegacyUnaudited),
     (
@@ -1733,7 +1725,7 @@ pub const REMOTE_WORKSPACE_COMMAND_POLICIES: &[(&str, RemoteWorkspacePolicy)] =
         "search_file_contents",
         RemoteWorkspacePolicy::LegacyUnaudited,
     ),
-    ("search_filenames", RemoteWorkspacePolicy::LegacyUnaudited),
+    ("search_filenames", RemoteWorkspacePolicy::RemoteRouted),
     ("search_files", RemoteWorkspacePolicy::LegacyUnaudited),
     (
         "search_referenceable_sessions",
@@ -1782,6 +1774,10 @@ pub const REMOTE_WORKSPACE_COMMAND_POLICIES: &[(&str, RemoteWorkspacePolicy)] =
         "set_external_mcp_server_decision_command",
         RemoteWorkspacePolicy::RemoteUnsupported,
     ),
+    (
+        "set_external_mcp_servers_enabled_command",
+        RemoteWorkspacePolicy::RemoteUnsupported,
+    ),
     (
         "set_external_source_conflict_choice_command",
         RemoteWorkspacePolicy::RemoteUnsupported,
@@ -1802,10 +1798,18 @@ pub const REMOTE_WORKSPACE_COMMAND_POLICIES: &[(&str, RemoteWorkspacePolicy)] =
         "set_external_tool_target_decision_command",
         RemoteWorkspacePolicy::RemoteUnsupported,
     ),
+    (
+        "set_external_tool_targets_enabled_command",
+        RemoteWorkspacePolicy::RemoteUnsupported,
+    ),
     (
         "set_external_subagent_activation_command",
         RemoteWorkspacePolicy::RemoteUnsupported,
     ),
+    (
+        "set_external_subagents_enabled_command",
+        RemoteWorkspacePolicy::RemoteUnsupported,
+    ),
     (
         "set_external_subagent_model_binding_command",
         RemoteWorkspacePolicy::RemoteUnsupported,
@@ -1937,7 +1941,7 @@ pub const REMOTE_WORKSPACE_COMMAND_POLICIES: &[(&str, RemoteWorkspacePolicy)] =
     ),
     (
         "start_search_filenames_stream",
-        RemoteWorkspacePolicy::LegacyUnaudited,
+        RemoteWorkspacePolicy::RemoteRouted,
     ),
     ("start_subscription_login", RemoteWorkspacePolicy::LocalOnly),
     ("startup_window_control", RemoteWorkspacePolicy::LocalOnly),
@@ -2010,6 +2014,10 @@ pub const REMOTE_WORKSPACE_COMMAND_POLICIES: &[(&str, RemoteWorkspacePolicy)] =
         "update_app_status",
         RemoteWorkspacePolicy::WorkspaceAgnostic,
     ),
+    (
+        "update_active_turn_permission_mode",
+        RemoteWorkspacePolicy::RemoteRouted,
+    ),
     ("update_cron_job", RemoteWorkspacePolicy::LegacyUnaudited),
     (
         "update_custom_agent",
@@ -2200,7 +2208,7 @@ mod tests {
 
     #[test]
     fn complete_rollback_commands_explicitly_reject_remote_workspaces() {
-        for command in ["rollback_session", "rollback_to_turn"] {
+        for command in ["rollback_session", "rollback_session_to_turn"] {
             assert_eq!(
                 remote_workspace_policy(command),
                 Some(RemoteWorkspacePolicy::RemoteUnsupported),
@@ -2277,7 +2285,6 @@ mod tests {
         "accept_session",
         "activate_session_goal",
         "add_skill",
-        "analyze_work_state",
         "apply_patch",
         "archive_all_sessions",
         "archive_session",
@@ -2330,8 +2337,6 @@ mod tests {
         "editor_ai_stream",
         "ensure_coordinator_session",
         "execute_tool",
-        "explorer_get_children",
-        "explorer_get_children_paginated",
         "explorer_get_file_tree",
         "export_config",
         "export_diagnostics_bundle",
@@ -2340,7 +2345,6 @@ mod tests {
         "fetch_mcp_app_resource",
         "fork_session",
         "generate_commit_message",
-        "generate_greeting_only",
         "generate_session_title",
         "get_acp_clients",
         "get_acp_session_commands",
@@ -2358,8 +2362,6 @@ mod tests {
         "get_current_workspace",
         "get_custom_agent_detail",
         "get_default_review_team_definition",
-        "get_directory_children",
-        "get_directory_children_paginated",
         "get_file_change_history",
         "get_file_diff",
         "get_file_editor_sync_hash",
@@ -2404,7 +2406,6 @@ mod tests {
         "get_tool_info",
         "get_turn_files",
         "get_watched_paths",
-        "get_work_state_summary",
         "grant_miniapp_path",
         "grant_miniapp_workspace",
         "import_agent_companion_pet_package",
@@ -2518,7 +2519,6 @@ mod tests {
         "predownload_acp_client_adapter",
         "preview_commit_message",
         "probe_acp_client_requirements",
-        "quick_analyze_work_state",
         "quick_commit_message",
         "read_background_command_output",
         "read_file_content",
@@ -2559,7 +2559,6 @@ mod tests {
         "save_session_turn",
         "scan_workspace_info",
         "search_file_contents",
-        "search_filenames",
         "search_files",
         "search_skill_market",
         "send_background_command_input",
@@ -2580,7 +2579,6 @@ mod tests {
         "start_mcp_remote_oauth",
         "start_mcp_server",
         "start_search_file_contents_stream",
-        "start_search_filenames_stream",
         "steer_dialog_turn",
         "stop_acp_client",
         "stop_file_watch",
diff --git a/src/apps/desktop/src/api/session_api.rs b/src/apps/desktop/src/api/session_api.rs
index abacb34899..17623bea85 100644
--- a/src/apps/desktop/src/api/session_api.rs
+++ b/src/apps/desktop/src/api/session_api.rs
@@ -12,7 +12,7 @@ use bitfun_core::agentic::persistence::{SessionBranchResult, SessionMetadataPage
 use bitfun_core::service::remote_ssh::normalize_remote_workspace_path;
 use bitfun_core::service::session::{
     DialogTurnData, SessionKind, SessionMetadata, SessionStatus, SessionTranscriptExport,
-    SessionTranscriptExportOptions, SessionTurnCatalog,
+    SessionTranscriptExportOptions,
 };
 use bitfun_core::service::session_usage::SessionUsageReport;
 use bitfun_core::service::workspace::WorkspaceKind;
@@ -89,25 +89,6 @@ pub struct SaveSessionTurnRequest {
     pub remote_ssh_host: Option<String>,
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct RecordLocalCommandTurnRequest {
-    pub turn_data: DialogTurnData,
-    pub workspace_path: String,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_connection_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_ssh_host: Option<String>,
-}
-
-#[derive(Debug, Clone, Serialize)]
-#[serde(rename_all = "camelCase")]
-pub struct RecordLocalCommandTurnResponse {
-    pub turn_id: String,
-    pub storage_turn_index: usize,
-    pub total_turn_count: usize,
-    pub turn_catalog: SessionTurnCatalog,
-}
-
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct SaveSessionMetadataRequest {
     pub metadata: SessionMetadata,
@@ -502,36 +483,6 @@ pub async fn save_session_turn(
     Ok(())
 }
 
-#[tauri::command]
-pub async fn record_local_command_turn(
-    request: RecordLocalCommandTurnRequest,
-    runtime: State<'_, DesktopRuntimeContext>,
-) -> Result<RecordLocalCommandTurnResponse, String> {
-    let recorded = runtime
-        .session_application()
-        .record_local_command_turn(
-            desktop_session_scope(
-                request.workspace_path.clone(),
-                request.remote_connection_id,
-                request.remote_ssh_host,
-            ),
-            &request.turn_data,
-        )
-        .await
-        .map_err(|error| format!("Failed to record local command turn: {error}"))?;
-
-    crate::api::remote_connect_api::notify_session_changed(
-        &request.turn_data.session_id,
-        &request.workspace_path,
-    );
-    Ok(RecordLocalCommandTurnResponse {
-        turn_id: recorded.turn_id,
-        storage_turn_index: recorded.storage_turn_index,
-        total_turn_count: recorded.total_turn_count,
-        turn_catalog: recorded.turn_catalog,
-    })
-}
-
 #[tauri::command]
 pub async fn save_session_metadata(
     request: SaveSessionMetadataRequest,
diff --git a/src/apps/desktop/src/api/snapshot_service.rs b/src/apps/desktop/src/api/snapshot_service.rs
index 6daa965c11..6b07272d06 100644
--- a/src/apps/desktop/src/api/snapshot_service.rs
+++ b/src/apps/desktop/src/api/snapshot_service.rs
@@ -9,15 +9,10 @@ use bitfun_core::service::snapshot::{
     initialize_snapshot_manager_for_workspace, open_snapshot_manager_for_view, FileChangeEntry,
     OperationType, SnapshotConfig, SnapshotManager,
 };
-#[cfg(test)]
-use bitfun_runtime_ports::LocalWorkspaceSnapshotSessionRequest;
-use bitfun_runtime_ports::{
-    LocalWorkspaceSnapshotPort, LocalWorkspaceSnapshotTurnRequest, PortError, PortErrorKind,
-    SessionStoragePathRequest,
-};
+use bitfun_runtime_ports::SessionStoragePathRequest;
 use log::{info, warn};
 use serde::{Deserialize, Serialize};
-use std::collections::{BTreeSet, HashSet};
+use std::collections::BTreeSet;
 use std::{path::PathBuf, sync::Arc};
 use tauri::{AppHandle, Emitter, State};
 
@@ -98,20 +93,6 @@ pub struct RollbackSessionRequest {
     pub remote_scope: SnapshotRemoteScope,
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct RollbackTurnRequest {
-    #[serde(alias = "sessionId")]
-    pub session_id: String,
-    #[serde(alias = "turnIndex")]
-    pub turn_index: usize,
-    #[serde(default)]
-    pub delete_turns: bool,
-    #[serde(alias = "workspacePath")]
-    pub workspace_path: String,
-    #[serde(flatten)]
-    pub remote_scope: SnapshotRemoteScope,
-}
-
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct AcceptSessionRequest {
     #[serde(alias = "sessionId")]
@@ -318,86 +299,6 @@ async fn resolve_workspace_dir(workspace_path: &str) -> Result<PathBuf, String>
     Ok(workspace_dir)
 }
 
-fn local_snapshot_command_error(operation: &str, workspace_path: &str, error: PortError) -> String {
-    if error.kind == PortErrorKind::NotAvailable {
-        format!(
-            "Failed to initialize snapshot system for workspace {}: {}",
-            workspace_path, error.message
-        )
-    } else {
-        format!("Failed to {operation}: {}", error.message)
-    }
-}
-
-async fn rollback_local_workspace_files(
-    port: &dyn LocalWorkspaceSnapshotPort,
-    workspace_path: PathBuf,
-    workspace_display: &str,
-    session_id: String,
-    turn_index: usize,
-) -> Result<Vec<String>, String> {
-    let restored_files = port
-        .rollback_workspace_files_to_turn(LocalWorkspaceSnapshotTurnRequest {
-            workspace_path,
-            session_id,
-            turn_index,
-        })
-        .await
-        .map_err(|error| local_snapshot_command_error("rollback turn", workspace_display, error))?;
-    Ok(restored_files
-        .iter()
-        .map(|path| path.to_string_lossy().to_string())
-        .collect())
-}
-
-#[cfg(test)]
-async fn local_snapshot_session_files(
-    port: &dyn LocalWorkspaceSnapshotPort,
-    workspace_path: PathBuf,
-    workspace_display: &str,
-    session_id: String,
-) -> Result<Vec<String>, String> {
-    let files = port
-        .get_session_files(LocalWorkspaceSnapshotSessionRequest {
-            workspace_path,
-            session_id,
-            max_turn_exclusive: None,
-        })
-        .await
-        .map_err(|error| {
-            local_snapshot_command_error("get session files", workspace_display, error)
-        })?;
-    Ok(files
-        .iter()
-        .map(|path| path.to_string_lossy().to_string())
-        .collect())
-}
-
-#[cfg(test)]
-async fn local_snapshot_session_stats(
-    port: &dyn LocalWorkspaceSnapshotPort,
-    workspace_path: PathBuf,
-    workspace_display: &str,
-    session_id: String,
-) -> Result<serde_json::Value, String> {
-    let stats = port
-        .get_session_stats(LocalWorkspaceSnapshotSessionRequest {
-            workspace_path,
-            session_id,
-            max_turn_exclusive: None,
-        })
-        .await
-        .map_err(|error| {
-            local_snapshot_command_error("get session stats", workspace_display, error)
-        })?;
-    Ok(serde_json::json!({
-        "session_id": stats.session_id,
-        "total_files": stats.total_files,
-        "total_turns": stats.total_turns,
-        "total_changes": stats.total_changes
-    }))
-}
-
 async fn ensure_snapshot_manager_ready_for(
     workspace_path: &str,
     caller: &str,
@@ -496,8 +397,8 @@ async fn snapshot_manager_for_view(
 
 struct SnapshotHistoryMutation {
     _maintenance: CoreSessionMaintenancePermit,
-    mutation: CoreSessionMutationPermit,
-    storage_path: PathBuf,
+    _mutation: CoreSessionMutationPermit,
+    _storage_path: PathBuf,
 }
 
 async fn begin_snapshot_history_read(
@@ -558,8 +459,8 @@ async fn begin_snapshot_history_mutation(
         })?;
     Ok(SnapshotHistoryMutation {
         _maintenance: maintenance,
-        mutation,
-        storage_path,
+        _mutation: mutation,
+        _storage_path: storage_path,
     })
 }
 
@@ -686,104 +587,21 @@ pub async fn rollback_session(
 }
 
 #[tauri::command]
-pub async fn rollback_to_turn(
-    app_handle: AppHandle,
+pub async fn rollback_session_to_turn(
     runtime: State<'_, DesktopRuntimeContext>,
-    request: RollbackTurnRequest,
-) -> Result<Vec<String>, String> {
-    ensure_complete_rollback_supported(&request.workspace_path, &request.remote_scope).await?;
-    ensure_local_runtime_ownership(runtime.inner(), &request.workspace_path).await?;
-    let workspace_path = resolve_workspace_dir(&request.workspace_path).await?;
-    let compatibility = runtime.session_application().compatibility();
-    let history_mutation = begin_snapshot_history_mutation(
-        runtime.inner(),
-        &request.workspace_path,
-        &request.session_id,
-    )
-    .await?;
-
-    let rolled_back_parent_turn_ids = if request.delete_turns {
-        compatibility
-            .validate_persisted_session_context_rollback(
-                &history_mutation.mutation,
-                request.turn_index,
-            )
-            .await
-            .map_err(|error| format!("Failed to validate session rollback: {error}"))?;
-        compatibility
-            .load_persisted_session_turns_for_mutation(&history_mutation.mutation, None)
-            .await
-            .map_err(|error| format!("Failed to load turns before rollback: {error}"))?
-            .into_iter()
-            .filter(|turn| turn.turn_index >= request.turn_index)
-            .map(|turn| turn.turn_id)
-            .collect::<HashSet<_>>()
-    } else {
-        HashSet::new()
+    request: bitfun_runtime_ports::AgentSessionRollbackToTurnRequest,
+) -> Result<bitfun_runtime_ports::AgentSessionRollbackToTurnOutcome, String> {
+    let remote_scope = SnapshotRemoteScope {
+        remote_connection_id: request.remote_connection_id.clone(),
+        remote_ssh_host: request.remote_ssh_host.clone(),
     };
-
-    let restored_files_str = rollback_local_workspace_files(
-        runtime.local_workspace_snapshot(),
-        workspace_path,
-        &request.workspace_path,
-        request.session_id.clone(),
-        request.turn_index,
-    )
-    .await?;
-
-    let deleted_turns_count = rolled_back_parent_turn_ids.len();
-    if request.delete_turns {
-        compatibility
-            .rollback_persisted_session_context_to_turn_start(
-                &history_mutation.mutation,
-                request.turn_index,
-            )
-            .await
-            .map_err(|error| {
-                format!(
-                    "Workspace files were rolled back, but session history rollback failed. Reload the session before retrying: {error}"
-                )
-            })?;
-        if !rolled_back_parent_turn_ids.is_empty() {
-            if let Err(error) = compatibility
-                .delete_hidden_subagent_sessions_for_parent_turns(
-                    &history_mutation.storage_path,
-                    &request.session_id,
-                    &rolled_back_parent_turn_ids,
-                )
-                .await
-            {
-                warn!(
-                    "Failed to delete hidden subagent sessions during rollback: session_id={}, turn_index={}, error={}",
-                    request.session_id, request.turn_index, error
-                );
-            }
-        }
-
-        let _ = app_handle.emit(
-            "conversation_turns_deleted",
-            serde_json::json!({
-                "session_id": request.session_id,
-                "remaining_turns": request.turn_index,
-                "deleted_count": deleted_turns_count,
-            }),
-        );
-    }
-
-    drop(history_mutation);
-
-    let _ = app_handle.emit(
-        "turn_rolled_back",
-        serde_json::json!({
-            "session_id": request.session_id,
-            "turn_index": request.turn_index,
-            "files_count": restored_files_str.len(),
-            "deleted_turns": request.delete_turns,
-            "deleted_turns_count": deleted_turns_count,
-        }),
-    );
-
-    Ok(restored_files_str)
+    ensure_complete_rollback_supported(&request.workspace_path, &remote_scope).await?;
+    ensure_local_runtime_ownership(runtime.inner(), &request.workspace_path).await?;
+    runtime
+        .session_application()
+        .rollback_session_to_turn(request)
+        .await
+        .map_err(|error| error.to_string())
 }
 
 #[tauri::command]
@@ -1446,41 +1264,36 @@ pub async fn get_baseline_snapshot_diff(
 
 #[cfg(test)]
 mod tests {
-    use std::path::PathBuf;
-    use std::sync::atomic::{AtomicUsize, Ordering};
-
-    use bitfun_runtime_ports::{
-        LocalWorkspaceSnapshotPort, LocalWorkspaceSnapshotSessionRequest,
-        LocalWorkspaceSnapshotStats, LocalWorkspaceSnapshotTurnRequest, PortError, PortErrorKind,
-        PortResult,
-    };
-
     use super::{
         ensure_complete_rollback_supported, ensure_local_snapshot_mutation_path,
-        get_snapshot_manager_for_workspace, local_snapshot_command_error,
-        local_snapshot_session_files, local_snapshot_session_stats, rollback_local_workspace_files,
-        snapshot_manager_for_view, RollbackTurnRequest, SnapshotRemoteScope,
+        get_snapshot_manager_for_workspace, snapshot_manager_for_view, SnapshotRemoteScope,
     };
 
     #[test]
-    fn snapshot_mutation_dto_preserves_structured_remote_facts() {
-        let request: RollbackTurnRequest = serde_json::from_value(serde_json::json!({
-            "sessionId": "remote-session",
-            "turnIndex": 2,
-            "workspacePath": "/srv/project",
-            "remoteConnectionId": "ssh:user@example.com:22",
-            "remoteSshHost": "example.com"
-        }))
-        .expect("deserialize snapshot mutation scope");
-
+    fn targeted_rollback_request_preserves_stable_identity_and_remote_facts() {
+        let request: bitfun_runtime_ports::AgentSessionRollbackToTurnRequest =
+            serde_json::from_value(serde_json::json!({
+                "sessionId": "remote-session",
+                "targetTurnId": "turn-7",
+                "expectedStorageTurnIndex": 7,
+                "expectedCatalogRevision": "catalog-3",
+                "workspacePath": "/srv/project",
+                "remoteConnectionId": "ssh:user@example.com:22",
+                "remoteSshHost": "example.com"
+            }))
+            .expect("deserialize targeted rollback request");
+
+        assert_eq!(request.target_turn_id, "turn-7");
+        assert_eq!(request.expected_storage_turn_index, Some(7));
         assert_eq!(
-            request.remote_scope.remote_connection_id.as_deref(),
-            Some("ssh:user@example.com:22")
+            request.expected_catalog_revision.as_deref(),
+            Some("catalog-3")
         );
         assert_eq!(
-            request.remote_scope.remote_ssh_host.as_deref(),
-            Some("example.com")
+            request.remote_connection_id.as_deref(),
+            Some("ssh:user@example.com:22")
         );
+        assert_eq!(request.remote_ssh_host.as_deref(), Some("example.com"));
     }
 
     #[tokio::test]
@@ -1550,12 +1363,12 @@ mod tests {
             .split_once("pub async fn rollback_session")
             .expect("rollback_session remains present")
             .1
-            .split_once("pub async fn rollback_to_turn")
-            .expect("rollback_to_turn remains present")
+            .split_once("pub async fn rollback_session_to_turn")
+            .expect("targeted rollback remains present")
             .0;
-        let rollback_to_turn = source
-            .split_once("pub async fn rollback_to_turn")
-            .expect("rollback_to_turn remains present")
+        let targeted_rollback = source
+            .split_once("pub async fn rollback_session_to_turn")
+            .expect("targeted rollback remains present")
             .1
             .split_once("pub async fn accept_session")
             .expect("accept_session remains present")
@@ -1573,16 +1386,15 @@ mod tests {
 
         assert_remote_guard_precedes(rollback_session, "ensure_local_runtime_ownership");
         assert_remote_guard_precedes(rollback_session, "ensure_snapshot_manager_ready_for");
-        assert_remote_guard_precedes(rollback_to_turn, "ensure_local_runtime_ownership");
-        assert_remote_guard_precedes(rollback_to_turn, "begin_snapshot_history_mutation");
+        assert_remote_guard_precedes(targeted_rollback, "ensure_local_runtime_ownership");
+        assert_remote_guard_precedes(targeted_rollback, "rollback_session_to_turn");
     }
 
     #[test]
     fn snapshot_mutators_share_session_revert_admission() {
         let source = include_str!("snapshot_service.rs");
         for (command, next_command) in [
-            ("rollback_session", "rollback_to_turn"),
-            ("rollback_to_turn", "accept_session"),
+            ("rollback_session", "rollback_session_to_turn"),
             ("accept_session", "accept_file"),
             ("accept_file", "reject_file"),
             ("reject_file", "get_session_files"),
@@ -1602,6 +1414,22 @@ mod tests {
             );
         }
 
+        let targeted_rollback = source
+            .split_once("pub async fn rollback_session_to_turn")
+            .expect("targeted rollback remains present")
+            .1
+            .split_once("pub async fn accept_session")
+            .expect("accept_session remains present")
+            .0;
+        assert!(
+            targeted_rollback.contains(".rollback_session_to_turn(request)"),
+            "targeted rollback must delegate admission to the Agent Session transaction"
+        );
+        assert!(
+            !targeted_rollback.contains("begin_snapshot_history_mutation"),
+            "targeted rollback must not reacquire the Session mutation owned by the Agent Session transaction"
+        );
+
         let record = source
             .split_once("pub async fn record_file_change")
             .expect("record_file_change remains present")
@@ -1644,109 +1472,4 @@ mod tests {
         assert!(error.contains("snapshot_remote_workspace_unavailable"));
         assert!(get_snapshot_manager_for_workspace(workspace.path()).is_none());
     }
-
-    #[derive(Default)]
-    struct RecordingSnapshotPort {
-        file_calls: AtomicUsize,
-        stats_calls: AtomicUsize,
-        rollback_calls: AtomicUsize,
-    }
-
-    #[async_trait::async_trait]
-    impl LocalWorkspaceSnapshotPort for RecordingSnapshotPort {
-        async fn prepare_local_workspace(&self, _workspace_path: PathBuf) -> PortResult<()> {
-            Ok(())
-        }
-
-        async fn get_session_files(
-            &self,
-            _request: LocalWorkspaceSnapshotSessionRequest,
-        ) -> PortResult<Vec<PathBuf>> {
-            self.file_calls.fetch_add(1, Ordering::SeqCst);
-            Ok(vec![PathBuf::from("changed.txt")])
-        }
-
-        async fn get_session_stats(
-            &self,
-            request: LocalWorkspaceSnapshotSessionRequest,
-        ) -> PortResult<LocalWorkspaceSnapshotStats> {
-            self.stats_calls.fetch_add(1, Ordering::SeqCst);
-            Ok(LocalWorkspaceSnapshotStats {
-                session_id: request.session_id,
-                total_files: 1,
-                total_turns: 2,
-                total_changes: 3,
-            })
-        }
-
-        async fn rollback_workspace_files_to_turn(
-            &self,
-            _request: LocalWorkspaceSnapshotTurnRequest,
-        ) -> PortResult<Vec<PathBuf>> {
-            self.rollback_calls.fetch_add(1, Ordering::SeqCst);
-            Ok(vec![PathBuf::from("restored.txt")])
-        }
-    }
-
-    #[test]
-    fn local_snapshot_errors_preserve_desktop_initialization_and_operation_context() {
-        let initialization = local_snapshot_command_error(
-            "get session files",
-            "C:\\workspace",
-            PortError::new(PortErrorKind::NotAvailable, "backend unavailable"),
-        );
-        assert_eq!(
-            initialization,
-            "Failed to initialize snapshot system for workspace C:\\workspace: backend unavailable"
-        );
-
-        let operation = local_snapshot_command_error(
-            "get session stats",
-            "C:\\workspace",
-            PortError::new(PortErrorKind::Backend, "stats failed"),
-        );
-        assert_eq!(operation, "Failed to get session stats: stats failed");
-    }
-
-    #[tokio::test]
-    async fn local_snapshot_adapters_call_each_port_operation_once_and_keep_json_shape() {
-        let port = RecordingSnapshotPort::default();
-        let workspace = PathBuf::from("workspace");
-
-        let files = local_snapshot_session_files(
-            &port,
-            workspace.clone(),
-            "workspace",
-            "session-1".to_string(),
-        )
-        .await
-        .expect("file adapter should succeed");
-        let stats = local_snapshot_session_stats(
-            &port,
-            workspace.clone(),
-            "workspace",
-            "session-1".to_string(),
-        )
-        .await
-        .expect("stats adapter should succeed");
-        let restored = rollback_local_workspace_files(
-            &port,
-            workspace,
-            "workspace",
-            "session-1".to_string(),
-            4,
-        )
-        .await
-        .expect("rollback adapter should succeed");
-
-        assert_eq!(port.file_calls.load(Ordering::SeqCst), 1);
-        assert_eq!(port.stats_calls.load(Ordering::SeqCst), 1);
-        assert_eq!(port.rollback_calls.load(Ordering::SeqCst), 1);
-        assert_eq!(files, vec!["changed.txt"]);
-        assert_eq!(restored, vec!["restored.txt"]);
-        assert_eq!(stats["session_id"], "session-1");
-        assert_eq!(stats["total_files"], 1);
-        assert_eq!(stats["total_turns"], 2);
-        assert_eq!(stats["total_changes"], 3);
-    }
 }
diff --git a/src/apps/desktop/src/api/startchat_agent_api.rs b/src/apps/desktop/src/api/startchat_agent_api.rs
deleted file mode 100644
index 5405f64efb..0000000000
--- a/src/apps/desktop/src/api/startchat_agent_api.rs
+++ /dev/null
@@ -1,142 +0,0 @@
-//! Startchat Agent API
-
-use bitfun_core::function_agents::{
-    startchat_func_agent::Language, StartchatFunctionAgent, WorkStateAnalysis, WorkStateOptions,
-};
-use log::error;
-use serde::{Deserialize, Serialize};
-use std::path::Path;
-use tauri::State;
-
-use super::app_state::AppState;
-
-#[derive(Debug, Clone, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AnalyzeWorkStateRequest {
-    pub repo_path: String,
-    pub options: Option<WorkStateOptions>,
-}
-
-#[derive(Debug, Clone, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct QuickAnalyzeRequest {
-    pub repo_path: String,
-    pub language: Option<Language>,
-}
-
-#[derive(Debug, Clone, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct GenerateGreetingRequest {
-    pub repo_path: String,
-}
-
-#[derive(Debug, Clone, Serialize)]
-#[serde(rename_all = "camelCase")]
-pub struct WorkStateSummaryResponse {
-    pub greeting_title: String,
-    pub current_state_summary: String,
-    pub has_git_changes: bool,
-    pub unstaged_files: u32,
-    pub unpushed_commits: u32,
-    pub predicted_actions_count: usize,
-}
-
-#[tauri::command]
-pub async fn analyze_work_state(
-    state: State<'_, AppState>,
-    request: AnalyzeWorkStateRequest,
-) -> Result<WorkStateAnalysis, String> {
-    let agent = StartchatFunctionAgent::new(state.ai_client_factory.clone());
-    let opts = request.options.unwrap_or_default();
-
-    agent
-        .analyze_work_state(Path::new(&request.repo_path), opts)
-        .await
-        .map_err(|e| {
-            error!(
-                "Work state analysis failed: repo_path={}, error={}",
-                request.repo_path, e
-            );
-            e.to_string()
-        })
-}
-
-#[tauri::command]
-pub async fn quick_analyze_work_state(
-    state: State<'_, AppState>,
-    request: QuickAnalyzeRequest,
-) -> Result<WorkStateAnalysis, String> {
-    let agent = StartchatFunctionAgent::new(state.ai_client_factory.clone());
-    let language = request.language.unwrap_or(Language::Chinese);
-
-    agent
-        .quick_analyze(Path::new(&request.repo_path), language)
-        .await
-        .map_err(|e| {
-            error!(
-                "Quick work state analysis failed: repo_path={}, error={}",
-                request.repo_path, e
-            );
-            e.to_string()
-        })
-}
-
-#[tauri::command]
-pub async fn generate_greeting_only(
-    state: State<'_, AppState>,
-    request: GenerateGreetingRequest,
-) -> Result<WorkStateAnalysis, String> {
-    let agent = StartchatFunctionAgent::new(state.ai_client_factory.clone());
-
-    agent
-        .generate_greeting_only(Path::new(&request.repo_path))
-        .await
-        .map_err(|e| {
-            error!(
-                "Generate greeting failed: repo_path={}, error={}",
-                request.repo_path, e
-            );
-            e.to_string()
-        })
-}
-
-#[tauri::command]
-pub async fn get_work_state_summary(
-    state: State<'_, AppState>,
-    request: QuickAnalyzeRequest,
-) -> Result<WorkStateSummaryResponse, String> {
-    let agent = StartchatFunctionAgent::new(state.ai_client_factory.clone());
-
-    let language = request.language.unwrap_or(Language::Chinese);
-
-    let analysis = agent
-        .quick_analyze(Path::new(&request.repo_path), language)
-        .await
-        .map_err(|e| {
-            error!(
-                "Failed to get work state summary: repo_path={}, error={}",
-                request.repo_path, e
-            );
-            e.to_string()
-        })?;
-
-    let (unstaged_files, unpushed_commits, has_git_changes) =
-        if let Some(ref git) = analysis.current_state.git_state {
-            (
-                git.unstaged_files + git.staged_files,
-                git.unpushed_commits,
-                git.unstaged_files > 0 || git.staged_files > 0 || git.unpushed_commits > 0,
-            )
-        } else {
-            (0, 0, false)
-        };
-
-    Ok(WorkStateSummaryResponse {
-        greeting_title: analysis.greeting.title,
-        current_state_summary: analysis.current_state.summary,
-        has_git_changes,
-        unstaged_files,
-        unpushed_commits,
-        predicted_actions_count: analysis.predicted_actions.len(),
-    })
-}
diff --git a/src/apps/desktop/src/api/system_api.rs b/src/apps/desktop/src/api/system_api.rs
index 3465aab81b..37fe9bd879 100644
--- a/src/apps/desktop/src/api/system_api.rs
+++ b/src/apps/desktop/src/api/system_api.rs
@@ -18,9 +18,14 @@ const UPDATE_PROGRESS_EVENT: &str = "bitfun-update-progress";
 
 /// Updater origins, in configured (fallback) order. Kept in step with
 /// `scripts/desktop-tauri-build.mjs`, which bakes the same pair into the bundle.
-const GITHUB_UPDATER_ENDPOINT: &str =
-    "https://github.com/GCWing/BitFun/releases/latest/download/latest.json";
-const OPENBITFUN_UPDATER_ENDPOINT: &str = "https://openbitfun.com/release/latest.json";
+const GITHUB_UPDATER_ENDPOINT: &str = match option_env!("BITFUN_UPDATER_PRIMARY_ENDPOINT") {
+    Some(endpoint) => endpoint,
+    None => "https://github.com/GCWing/BitFun/releases/latest/download/latest.json",
+};
+const OPENBITFUN_UPDATER_ENDPOINT: &str = match option_env!("BITFUN_UPDATER_FALLBACK_ENDPOINT") {
+    Some(endpoint) => endpoint,
+    None => "https://openbitfun.com/release/latest.json",
+};
 
 /// Throughput probe settings, matching the CLI updater and the relay deploy
 /// script (`src/apps/cli/src/self_update.rs`,
diff --git a/src/apps/desktop/src/computer_use/desktop_host/mod.rs b/src/apps/desktop/src/computer_use/desktop_host/mod.rs
index 929303c55b..c3fcd69a68 100644
--- a/src/apps/desktop/src/computer_use/desktop_host/mod.rs
+++ b/src/apps/desktop/src/computer_use/desktop_host/mod.rs
@@ -36,6 +36,86 @@ const STALE_CAPTURE_TOOL_MESSAGE: &str = "Computer use refused: call **`screensh
 
 static SCREENSHOT_ID_COUNTER: AtomicU64 = AtomicU64::new(1);
 
+/// How long `open_app` waits for a freshly activated app to show up in
+/// LaunchServices before giving up on resolving its pid.
+#[cfg(target_os = "macos")]
+const OPEN_APP_SETTLE_MS: u64 = 3_000;
+/// How long `open_app` waits for the app to put a window on screen. Cold
+/// Electron launches routinely need several seconds; reporting `window_count:
+/// 0` too early would send the agent down a false "app is broken" path.
+#[cfg(target_os = "macos")]
+const OPEN_APP_WINDOW_WAIT_MS: u64 = 8_000;
+#[cfg(target_os = "macos")]
+const OPEN_APP_POLL_INTERVAL_MS: u64 = 150;
+
+/// How long an `open_app` AppleScript may run before it is killed.
+///
+/// `activate` sends an AppleEvent to the target app and waits for it to answer.
+/// A hung or busy app simply does not answer, and macOS's default AppleEvent
+/// timeout is **120 seconds** — during which `open_app` occupies a blocking
+/// thread and the agent has no idea anything is wrong. An app that has not
+/// acknowledged activation in a few seconds is not going to.
+#[cfg(target_os = "macos")]
+const OSASCRIPT_TIMEOUT_MS: u64 = 10_000;
+
+/// Run `osascript -e <script>`, killing it if it outlives `timeout_ms`.
+///
+/// `Command::output()` has no timeout, so a wedged AppleEvent blocks until
+/// macOS gives up. Polling `try_wait` lets us bound it. Output here is a bundle
+/// id or an error line, far below the pipe buffer, so draining after exit
+/// cannot deadlock — and a child that did fill the buffer would stop making
+/// progress and get killed by this same deadline.
+#[cfg(target_os = "macos")]
+fn run_osascript_bounded(script: &str, timeout_ms: u64) -> std::io::Result<std::process::Output> {
+    use std::process::Stdio;
+
+    let mut child = std::process::Command::new("/usr/bin/osascript")
+        .args(["-e", script])
+        .stdin(Stdio::null())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .spawn()?;
+
+    let deadline = std::time::Instant::now() + std::time::Duration::from_millis(timeout_ms);
+    loop {
+        match child.try_wait()? {
+            // Exited: `wait_with_output` below returns the recorded status.
+            Some(_) => break,
+            None => {
+                if std::time::Instant::now() >= deadline {
+                    let _ = child.kill();
+                    let _ = child.wait();
+                    return Err(std::io::Error::new(
+                        std::io::ErrorKind::TimedOut,
+                        format!("osascript did not finish within {}ms", timeout_ms),
+                    ));
+                }
+                std::thread::sleep(std::time::Duration::from_millis(20));
+            }
+        }
+    }
+    child.wait_with_output()
+}
+
+/// Quote a string as an AppleScript literal.
+///
+/// App names reach us from the model and can contain quotes or backslashes;
+/// interpolating them raw would let a name break out of the string and change
+/// what the script does.
+#[cfg(target_os = "macos")]
+fn applescript_quote(s: &str) -> String {
+    let mut out = String::with_capacity(s.len() + 2);
+    out.push('"');
+    for ch in s.chars() {
+        if ch == '"' || ch == '\\' {
+            out.push('\\');
+        }
+        out.push(ch);
+    }
+    out.push('"');
+    out
+}
+
 #[cfg(test)]
 mod visual_grid_tests {
     use super::*;
@@ -109,6 +189,125 @@ mod visual_grid_tests {
     }
 }
 
+#[cfg(all(test, target_os = "macos"))]
+mod macos_applescript_tests {
+    use super::*;
+
+    /// Compile an AppleScript source **without running it**. `osacompile`
+    /// reports the same syntax errors `osascript` would, so this checks that a
+    /// template is valid AppleScript with no side effects.
+    fn compiles(script: &str) -> Result<(), String> {
+        let out = std::process::Command::new("/usr/bin/osacompile")
+            .args(["-o", "/dev/null", "-e", script])
+            .output()
+            .map_err(|e| format!("spawn osacompile: {e}"))?;
+        if out.status.success() {
+            Ok(())
+        } else {
+            Err(String::from_utf8_lossy(&out.stderr).trim().to_string())
+        }
+    }
+
+    /// The bug that motivated this test: the frontmost-app lookup embedded a
+    /// `try … end try` **block** in expression position. AppleScript rejects
+    /// that at compile time, so the command always exited non-zero and the
+    /// caller silently saw `None` — for every call, forever. Nothing in the
+    /// build or the test suite noticed, because an AppleScript template is just
+    /// a string until something runs it.
+    ///
+    /// Every AppleScript this module generates now has to compile.
+    #[test]
+    fn every_generated_applescript_compiles() {
+        // Includes the names that exercise `applescript_quote`: a quote, a
+        // backslash and CJK. Asserting the *escaped* form compiles is what
+        // proves the escaping is genuine AppleScript rather than a plausible
+        // guess about its string-literal syntax.
+        for name in ["Safari", "a\"b", "a\\b", "飞书", "Visual Studio Code"] {
+            for t in [
+                format!("id of application {}", applescript_quote(name)),
+                format!("tell application {} to activate", applescript_quote(name)),
+            ] {
+                assert!(compiles(&t).is_ok(), "template failed to compile: {t}");
+            }
+        }
+    }
+
+    #[test]
+    fn applescript_compile_check_actually_rejects_bad_syntax() {
+        // Guards the guard: if `compiles` ever silently passed everything, the
+        // test above would be worthless. This is the exact broken spelling.
+        let broken = r#"tell application "System Events"
+  return (try (bundle identifier of p as text) on error "" end try)
+end tell"#;
+        assert!(compiles(broken).is_err());
+    }
+
+    /// A wedged AppleEvent must not pin a blocking thread for macOS's 120s
+    /// default. `delay` inside osascript is a real hang from our side: the
+    /// process is alive and unresponsive, exactly like an app that never
+    /// acknowledges activation.
+    #[test]
+    fn a_hung_applescript_is_killed_at_the_deadline() {
+        let started = std::time::Instant::now();
+        let err = run_osascript_bounded("delay 30", 700)
+            .expect_err("a 30s script under a 700ms budget must not succeed");
+
+        assert_eq!(err.kind(), std::io::ErrorKind::TimedOut, "{err}");
+        assert!(
+            started.elapsed() < std::time::Duration::from_secs(5),
+            "returned after {:?} — the deadline did not take effect",
+            started.elapsed()
+        );
+    }
+
+    /// The bounded runner must stay a drop-in for the normal path: same stdout,
+    /// same exit status.
+    #[test]
+    fn a_normal_applescript_still_returns_its_output() {
+        let out = run_osascript_bounded("return \"ok\"", OSASCRIPT_TIMEOUT_MS).expect("should run");
+        assert!(out.status.success());
+        assert_eq!(String::from_utf8_lossy(&out.stdout).trim(), "ok");
+    }
+
+    #[test]
+    fn applescript_quote_escapes_quotes_and_backslashes() {
+        // App names come from the model, so a name containing a quote must not
+        // be able to terminate the literal and change what the script does.
+        assert_eq!(applescript_quote("Safari"), "\"Safari\"");
+        assert_eq!(applescript_quote("a\"b"), "\"a\\\"b\"");
+        assert_eq!(applescript_quote("a\\b"), "\"a\\\\b\"");
+        assert_eq!(applescript_quote("飞书"), "\"飞书\"");
+    }
+
+    #[test]
+    fn quoted_app_names_stay_inside_the_literal() {
+        // `" to activate` + a payload would otherwise become script code.
+        let hostile = "X\" to activate\ntell application \"Calculator";
+        let script = format!(
+            "tell application {} to activate",
+            applescript_quote(hostile)
+        );
+        assert!(
+            !script.contains("tell application \"Calculator\""),
+            "injected tell survived quoting: {script}"
+        );
+    }
+
+    /// The foreground lookup must return a real app in a GUI session. Ignored
+    /// by default because it needs a logged-in window server.
+    #[test]
+    #[ignore]
+    fn frontmost_application_resolves_in_a_gui_session() {
+        let app = DesktopComputerUseHost::macos_foreground_application()
+            .expect("a GUI session always has a frontmost application");
+        assert!(app.process_id.unwrap_or(0) > 0);
+        assert!(
+            app.name.is_some() || app.bundle_id.is_some(),
+            "frontmost app must be identifiable: {app:?}"
+        );
+    }
+}
+
 #[cfg(all(test, target_os = "windows"))]
 mod windows_foreground_tests {
     use super::*;
@@ -128,8 +327,11 @@ mod windows_foreground_tests {
 
     #[test]
     fn foreground_app_falls_back_to_title_only_when_process_lookup_fails() {
-        let app =
-            DesktopComputerUseHost::windows_foreground_application("Search".to_string(), 4242, None);
+        let app = DesktopComputerUseHost::windows_foreground_application(
+            "Search".to_string(),
+            4242,
+            None,
+        );
 
         assert_eq!(app.name.as_deref(), Some("Search"));
         assert_eq!(app.process_name, None);
@@ -411,33 +613,178 @@ impl DesktopComputerUseHost {
         }
     }
 
+    /// Launch (or re-front) a macOS app and report enough identity for the
+    /// agent to keep working with it.
+    ///
+    /// Three things the previous implementation got wrong, each of which cost
+    /// the agent a long recovery detour:
+    ///
+    /// 1. It reported only a pid. The name the caller launches by, the
+    ///    executable name and the bundle id are frequently three different
+    ///    strings (`Lark` / `Feishu` / `com.electron.lark`), so every follow-up
+    ///    `tell process "…"` or `open -a …` guessed wrong.
+    /// 2. It slept a flat `delay 1` and declared success, whether or not a
+    ///    window ever appeared.
+    /// 3. `activate` does not reopen a window for an app that is already
+    ///    running with none — the usual state for an Electron client the user
+    ///    closed earlier. The result was `success: true` with an empty screen.
+    ///
+    /// So: resolve the bundle id via LaunchServices, activate, poll for a
+    /// window, and re-open the bundle when the poll comes up empty.
+    #[cfg(target_os = "macos")]
+    fn open_app_macos(
+        name: String,
+    ) -> BitFunResult<bitfun_core::agentic::tools::computer_use_host::OpenAppResult> {
+        use crate::computer_use::macos_bg_input::running_app_identity_macos;
+        use bitfun_core::agentic::tools::computer_use_host::OpenAppResult;
+
+        let failure = |err: String| OpenAppResult {
+            app_name: name.clone(),
+            success: false,
+            process_id: None,
+            error_message: Some(err),
+            bundle_id: None,
+            process_name: None,
+            window_count: None,
+            launch_path: None,
+        };
+
+        // `id of application "X"` asks LaunchServices to resolve the name the
+        // same way `tell application "X"` will, so the bundle id we report is
+        // guaranteed to describe the app we are about to activate.
+        let bundle_id = run_osascript_bounded(
+            &format!("id of application {}", applescript_quote(&name)),
+            OSASCRIPT_TIMEOUT_MS,
+        )
+        .ok()
+        .filter(|o| o.status.success())
+        .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string())
+        .filter(|s| !s.is_empty());
+
+        let activate = match run_osascript_bounded(
+            &format!("tell application {} to activate", applescript_quote(&name)),
+            OSASCRIPT_TIMEOUT_MS,
+        ) {
+            Ok(out) => out,
+            // A timeout is a real outcome, not an internal error: the app is
+            // installed but not answering. Report it as a failed launch the
+            // agent can act on rather than bubbling an opaque io error.
+            Err(e) if e.kind() == std::io::ErrorKind::TimedOut => {
+                return Ok(failure(format!(
+                    "'{}' did not respond to activation within {}s — it may be hung or showing a modal dialog. \
+Check the app directly, or ask the user to bring it up.",
+                    name,
+                    OSASCRIPT_TIMEOUT_MS / 1000
+                )));
+            }
+            Err(e) => return Err(BitFunError::tool(format!("open_app osascript: {}", e))),
+        };
+        if !activate.status.success() {
+            return Ok(failure(
+                String::from_utf8_lossy(&activate.stderr).trim().to_string(),
+            ));
+        }
+
+        let mut launch_path = "activate";
+        // Resolving by bundle id beats "whoever is frontmost right now" —
+        // activation is asynchronous, so the frontmost app during the first
+        // poll ticks is often still the previous one.
+        let mut pid = Self::poll_for_app_pid(bundle_id.as_deref(), OPEN_APP_SETTLE_MS);
+        let mut window_count = Self::poll_for_window(pid, OPEN_APP_WINDOW_WAIT_MS);
+
+        // Alive but windowless: `open -b` asks the app to reopen its main
+        // window (AppKit `applicationShouldHandleReopen:`), which `activate`
+        // alone never triggers.
+        if window_count == Some(0) {
+            if let Some(bid) = bundle_id.as_deref() {
+                let reopened = std::process::Command::new("/usr/bin/open")
+                    .args(["-b", bid])
+                    .output()
+                    .map(|o| o.status.success())
+                    .unwrap_or(false);
+                if reopened {
+                    launch_path = "reopen_bundle";
+                    pid = Self::poll_for_app_pid(Some(bid), OPEN_APP_WINDOW_WAIT_MS).or(pid);
+                    window_count = Self::poll_for_window(pid, OPEN_APP_WINDOW_WAIT_MS);
+                }
+            }
+        }
+
+        let (localized_name, resolved_bundle) = pid
+            .and_then(running_app_identity_macos)
+            .unwrap_or((None, None));
+
+        Ok(OpenAppResult {
+            app_name: name,
+            success: true,
+            process_id: pid,
+            error_message: None,
+            bundle_id: resolved_bundle.or(bundle_id),
+            process_name: localized_name,
+            window_count,
+            launch_path: Some(launch_path.to_string()),
+        })
+    }
+
+    /// Poll until the app owning `bundle_id` is running (or the frontmost app
+    /// settles, when no bundle id could be resolved). Returns its pid.
+    #[cfg(target_os = "macos")]
+    fn poll_for_app_pid(bundle_id: Option<&str>, budget_ms: u64) -> Option<i32> {
+        use crate::computer_use::macos_bg_input::{frontmost_pid_macos, pid_for_bundle_id_macos};
+        let deadline = std::time::Instant::now() + std::time::Duration::from_millis(budget_ms);
+        loop {
+            let found = match bundle_id {
+                Some(bid) => pid_for_bundle_id_macos(bid),
+                None => frontmost_pid_macos(),
+            };
+            if found.is_some() {
+                return found;
+            }
+            if std::time::Instant::now() >= deadline {
+                return None;
+            }
+            std::thread::sleep(std::time::Duration::from_millis(OPEN_APP_POLL_INTERVAL_MS));
+        }
+    }
+
+    /// Poll until the app owns at least one window, or the budget expires.
+    /// Returns the final observed count so callers can report `Some(0)` — a
+    /// windowless-but-alive app is a real state, not a failure to measure.
+    #[cfg(target_os = "macos")]
+    fn poll_for_window(pid: Option<i32>, budget_ms: u64) -> Option<usize> {
+        use crate::computer_use::macos_ax_ui::window_count_for_pid;
+        let pid = pid?;
+        let deadline = std::time::Instant::now() + std::time::Duration::from_millis(budget_ms);
+        let mut last = window_count_for_pid(pid);
+        while last.unwrap_or(0) == 0 && std::time::Instant::now() < deadline {
+            std::thread::sleep(std::time::Duration::from_millis(OPEN_APP_POLL_INTERVAL_MS));
+            last = window_count_for_pid(pid);
+        }
+        last
+    }
+
+    /// Identity of the frontmost macOS application, read from `NSWorkspace`.
+    ///
+    /// This used to shell out to `osascript`. That spelling embedded a
+    /// `try … end try` **block** in expression position, which AppleScript
+    /// rejects at compile time (`-2741`), so the command always exited
+    /// non-zero and this function always returned `None`. Because
+    /// `describe_screen` derives its target app from this value, the text-only
+    /// observation path was permanently blind: it reported
+    /// `foreground_application: null` and `ax_tree_text: null` on every call,
+    /// and the agent could only conclude its own output was being truncated.
     #[cfg(target_os = "macos")]
     fn macos_foreground_application() -> Option<ComputerUseForegroundApplication> {
-        let out = std::process::Command::new("/usr/bin/osascript")
-            .args(["-e", r#"tell application "System Events"
-  set p to first process whose frontmost is true
-  return (unix id of p as text) & "|" & (name of p) & "|" & (try (bundle identifier of p as text) on error "" end try)
-end tell"#])
-            .output()
-            .ok()?;
-        if !out.status.success() {
-            return None;
-        }
-        let s = String::from_utf8_lossy(&out.stdout);
-        let parts: Vec<&str> = s.trim().splitn(3, '|').collect();
-        if parts.len() < 2 {
-            return None;
-        }
-        let pid = parts[0].trim().parse::<i32>().ok()?;
-        let name = parts[1].trim();
-        let bundle = parts.get(2).map(|x| x.trim()).filter(|x| !x.is_empty());
+        let app = crate::computer_use::macos_bg_input::frontmost_app_identity_macos()?;
         Some(ComputerUseForegroundApplication {
-            name: Some(name.to_string()),
-            // `name of p` from System Events is already the process name, not a
-            // window title, so it doubles as the process identity here.
-            process_name: Some(name.to_string()),
-            bundle_id: bundle.map(|b| b.to_string()),
-            process_id: Some(pid),
+            name: app.name.clone(),
+            // `localizedName` is the app's user-visible name ("飞书"), which on
+            // localised or re-branded bundles differs from both the executable
+            // name ("Feishu") and the bundle name ("Lark"). Callers that need
+            // to address the process by name should prefer `bundle_id`.
+            process_name: app.name,
+            bundle_id: app.bundle_id,
+            process_id: Some(app.pid),
         })
     }
 
@@ -477,7 +824,11 @@ end tell"#])
                 } else {
                     crate::computer_use::windows_list_apps::exe_basename_for_pid(pid)
                 };
-                Some(Self::windows_foreground_application(title, pid, exe_basename))
+                Some(Self::windows_foreground_application(
+                    title,
+                    pid,
+                    exe_basename,
+                ))
             };
 
             ComputerUseSessionSnapshot {
@@ -1000,6 +1351,18 @@ impl ComputerUseHost for DesktopComputerUseHost {
             recommended_next_action = Some("screenshot".to_string());
         }
 
+        // `interaction_state` rides on *every* ComputerUse result, and the
+        // display list is the bulk of it. On a single-screen machine it is pure
+        // repetition: `active_display_id` already names the only screen, and
+        // there is nothing to disambiguate. It earns its bytes only when the
+        // model actually has to choose, so send it only then — `list_displays`
+        // and `describe_screen` still report the full list on demand.
+        let displays = if displays.len() > 1 {
+            displays
+        } else {
+            Vec::new()
+        };
+
         ComputerUseInteractionState {
             click_ready,
             enter_ready: !click_needs_fresh,
@@ -1176,37 +1539,7 @@ impl ComputerUseHost for DesktopComputerUseHost {
         #[cfg(target_os = "macos")]
         {
             let result = tokio::task::spawn_blocking(move || -> BitFunResult<OpenAppResult> {
-                let output = std::process::Command::new("/usr/bin/osascript")
-                    .args([
-                        "-e",
-                        &format!(
-                            r#"tell application "{}" to activate
-delay 1
-tell application "System Events" to get unix id of first process whose frontmost is true"#,
-                            name
-                        ),
-                    ])
-                    .output()
-                    .map_err(|e| BitFunError::tool(format!("open_app osascript: {}", e)))?;
-
-                if output.status.success() {
-                    let stdout = String::from_utf8_lossy(&output.stdout);
-                    let pid = stdout.trim().parse::<i32>().ok();
-                    Ok(OpenAppResult {
-                        app_name: name,
-                        success: true,
-                        process_id: pid,
-                        error_message: None,
-                    })
-                } else {
-                    let stderr = String::from_utf8_lossy(&output.stderr);
-                    Ok(OpenAppResult {
-                        app_name: name,
-                        success: false,
-                        process_id: None,
-                        error_message: Some(stderr.trim().to_string()),
-                    })
-                }
+                Self::open_app_macos(name)
             })
             .await
             .map_err(|e| BitFunError::tool(e.to_string()))??;
@@ -1229,6 +1562,16 @@ tell application "System Events" to get unix id of first process whose frontmost
                     } else {
                         Some(String::from_utf8_lossy(&output.stderr).trim().to_string())
                     },
+                    // `start` hands off to the shell and returns immediately
+                    // without telling us what it launched, so there is no pid
+                    // to resolve identity or window count from. Left as `None`
+                    // (the "not measured" value) rather than faked — the model
+                    // reads `window_count: Some(0)` as a definite windowless
+                    // app and would act on it.
+                    bundle_id: None,
+                    process_name: None,
+                    window_count: None,
+                    launch_path: Some("shell_start".to_string()),
                 })
             })
             .await
@@ -1253,6 +1596,14 @@ tell application "System Events" to get unix id of first process whose frontmost
                     } else {
                         Some(String::from_utf8_lossy(&output.stderr).trim().to_string())
                     },
+                    // Linux is the legacy tier: no AX layer, so there is no pid
+                    // to resolve identity or window count from. `None` means
+                    // "not measured" — do not substitute `Some(0)`, which the
+                    // model reads as a definite windowless app.
+                    bundle_id: None,
+                    process_name: None,
+                    window_count: None,
+                    launch_path: Some("xdg_open".to_string()),
                 })
             })
             .await
@@ -1398,6 +1749,13 @@ tell application "System Events" to get unix id of first process whose frontmost
         }
     }
 
+    fn computer_use_waive_fresh_capture_guard(&self) {
+        if let Ok(mut s) = self.state.lock() {
+            s.click_needs_fresh_screenshot = false;
+            s.pending_verify_screenshot = false;
+        }
+    }
+
     fn computer_use_guard_click_allowed(&self) -> BitFunResult<()> {
         let s = self
             .state
diff --git a/src/apps/desktop/src/computer_use/macos_ax_dump.rs b/src/apps/desktop/src/computer_use/macos_ax_dump.rs
index 7298eeffb7..86c24eefe9 100644
--- a/src/apps/desktop/src/computer_use/macos_ax_dump.rs
+++ b/src/apps/desktop/src/computer_use/macos_ax_dump.rs
@@ -431,6 +431,15 @@ pub(super) struct DumpOpts {
     pub max_depth: u32,
     pub max_nodes: usize,
     pub focus_window_only: bool,
+    /// Walk into menus that are currently closed. Off by default.
+    ///
+    /// A closed `AXMenu` still reports its whole item hierarchy, but every item
+    /// comes back collapsed at a zero-size off-screen frame — unclickable until
+    /// the menu is opened, and useless for addressing. They dominate the dump
+    /// anyway: observing a windowless app produced 188 nodes, 180 of them
+    /// closed menu items. `get_app_shortcuts` is the supported way to read menu
+    /// structure (and walks menus itself), so `get_app_state` stops at the menu.
+    pub include_closed_menus: bool,
 }
 
 impl Default for DumpOpts {
@@ -439,10 +448,28 @@ impl Default for DumpOpts {
             max_depth: 32,
             max_nodes: 4_000,
             focus_window_only: false,
+            include_closed_menus: false,
         }
     }
 }
 
+/// Whether a node is a menu container that is not currently open, and whose
+/// children are therefore off-screen and unclickable.
+///
+/// macOS gives an open menu's items real on-screen frames; a closed one leaves
+/// them at a zero-size origin. Size is the reliable signal here — `AXExpanded`
+/// is not exposed consistently by `AXMenu` across apps.
+fn is_closed_menu_container(role: &str, frame: Option<(f64, f64, f64, f64)>) -> bool {
+    if role != "AXMenu" {
+        return false;
+    }
+    match frame {
+        // No frame at all: treat as closed.
+        None => true,
+        Some((_, _, w, h)) => w < 1.0 || h < 1.0,
+    }
+}
+
 pub(super) fn dump_app_ax(pid: i32, opts: DumpOpts) -> BitFunResult<AppStateSnapshot> {
     let app = unsafe { AXUIElementCreateApplication(pid) };
     if app.is_null() {
@@ -501,6 +528,7 @@ pub(super) fn dump_app_ax(pid: i32, opts: DumpOpts) -> BitFunResult<AppStateSnap
         depth: 0,
     });
     let mut visited: usize = 0;
+    let mut pruned_menu_subtrees: usize = 0;
 
     while let Some(cur) = queue.pop_front() {
         if cur.depth > opts.max_depth || visited >= opts.max_nodes {
@@ -530,10 +558,13 @@ pub(super) fn dump_app_ax(pid: i32, opts: DumpOpts) -> BitFunResult<AppStateSnap
         let frame = unsafe { read_global_frame(cur.elem) };
         let actions = unsafe { read_action_names(cur.elem) };
 
+        let role = role.unwrap_or_default();
+        let is_closed_menu = is_closed_menu_container(&role, frame);
+
         nodes.push(AxNode {
             idx,
             parent_idx: cur.parent_idx,
-            role: role.unwrap_or_default(),
+            role,
             title,
             value,
             description,
@@ -552,6 +583,14 @@ pub(super) fn dump_app_ax(pid: i32, opts: DumpOpts) -> BitFunResult<AppStateSnap
         // Cache the retained ref so future actions can look it up.
         refs.push(AxRef(cur.elem));
 
+        // A closed menu is a leaf for our purposes: keep the container node so
+        // the model can see the menu exists (and `AXPress` it), but skip the
+        // subtree of unclickable zero-size items underneath.
+        if is_closed_menu && !opts.include_closed_menus {
+            pruned_menu_subtrees += 1;
+            continue;
+        }
+
         // Enqueue children — but DO NOT release `cur.elem`; the cache owns it.
         // At the application root (parent_idx is None), union `AXChildren`
         // with `AXWindows`. macOS only puts windows in `AXChildren` when the
@@ -600,7 +639,18 @@ pub(super) fn dump_app_ax(pid: i32, opts: DumpOpts) -> BitFunResult<AppStateSnap
         unsafe { ax_release(q.elem as CFTypeRef) };
     }
 
-    let tree_text = render_tree_text(&nodes);
+    let mut tree_text = render_tree_text(&nodes);
+    // Say that menus were skipped on purpose, and where to get them. Otherwise
+    // an agent that needs a menu command sees a bare `AXMenu` leaf and has no
+    // way to tell "pruned" from "this app has no menu items".
+    if pruned_menu_subtrees > 0 {
+        tree_text.push_str(&format!(
+            "\n[note] {} closed menu subtree(s) omitted — their items are off-screen and \
+unclickable until the menu opens. Use `get_app_shortcuts` for menu commands and their key \
+equivalents, or AXPress the menu first.\n",
+            pruned_menu_subtrees
+        ));
+    }
     let digest = compute_digest(&nodes);
     let captured_at_ms = SystemTime::now()
         .duration_since(UNIX_EPOCH)
@@ -887,6 +937,28 @@ mod tests {
         assert!(out.contains("actions=[AXShowMenu]"));
     }
 
+    #[test]
+    fn closed_menus_are_pruned_but_open_ones_are_kept() {
+        // A closed menu reports its items at a zero-size off-screen frame.
+        assert!(is_closed_menu_container(
+            "AXMenu",
+            Some((0.0, 982.0, 0.0, 0.0))
+        ));
+        assert!(is_closed_menu_container("AXMenu", None));
+        // An open menu has a real frame and must still be walked.
+        assert!(!is_closed_menu_container(
+            "AXMenu",
+            Some((100.0, 40.0, 220.0, 380.0))
+        ));
+        // Only menus are ever pruned — a zero-size button is still a node the
+        // model may need to reason about.
+        assert!(!is_closed_menu_container(
+            "AXButton",
+            Some((0.0, 0.0, 0.0, 0.0))
+        ));
+        assert!(!is_closed_menu_container("AXMenuItem", None));
+    }
+
     #[test]
     fn quote_clip_truncates_on_char_boundary() {
         let s = "中文字符测试abcdef";
@@ -903,6 +975,83 @@ mod tests {
         assert_ne!(d1, d2);
     }
 
+    /// Measure the closed-menu pruning against a real running app rather than
+    /// trusting the unit test's synthetic frames.
+    ///
+    /// Dumps the frontmost application twice — once with menus walked, once
+    /// with the default pruning — and reports both node counts. Requires
+    /// Accessibility permission and a GUI session, so it is `#[ignore]`d.
+    #[test]
+    #[ignore]
+    fn closed_menu_pruning_shrinks_a_real_app_dump() {
+        let pid = crate::computer_use::macos_bg_input::frontmost_pid_macos()
+            .expect("a GUI session has a frontmost app");
+
+        let with_menus = dump_app_ax(
+            pid,
+            DumpOpts {
+                include_closed_menus: true,
+                ..Default::default()
+            },
+        )
+        .expect("dump with menus");
+        let pruned = dump_app_ax(pid, DumpOpts::default()).expect("pruned dump");
+
+        // What `describe_screen` actually asks for: depth 8, focused window
+        // only. Reported alongside so the cost of the observe path is visible
+        // next to the cost of a full `get_app_state`.
+        let observe = dump_app_ax(
+            pid,
+            DumpOpts {
+                max_depth: 8,
+                focus_window_only: true,
+                ..Default::default()
+            },
+        )
+        .expect("describe_screen-shaped dump");
+
+        eprintln!(
+            "pid={pid}\n  full+menus:  {:>5} nodes, {:>7} bytes\n  full pruned: {:>5} nodes, {:>7} bytes\n  observe:     {:>5} nodes, {:>7} bytes",
+            with_menus.nodes.len(),
+            with_menus.tree_text.len(),
+            pruned.nodes.len(),
+            pruned.tree_text.len(),
+            observe.nodes.len(),
+            observe.tree_text.len(),
+        );
+        // Depth profile of the focused window. Run this when retuning
+        // `DESCRIBE_SCREEN_AX_DEPTH`: "actionable" (has AX actions and a real
+        // frame) is what the agent can actually click, and it is the column
+        // that matters — node count and bytes grow long after it plateaus.
+        for d in [8u32, 12, 16, 20, 24, 32] {
+            let s = dump_app_ax(
+                pid,
+                DumpOpts {
+                    max_depth: d,
+                    focus_window_only: true,
+                    ..Default::default()
+                },
+            )
+            .expect("depth dump");
+            let actionable = s
+                .nodes
+                .iter()
+                .filter(|n| !n.actions.is_empty() && n.frame_global.is_some())
+                .count();
+            eprintln!(
+                "  depth {:>2}: {:>5} nodes, {:>4} actionable, {:>7} bytes",
+                d,
+                s.nodes.len(),
+                actionable,
+                s.tree_text.len()
+            );
+        }
+        assert!(
+            pruned.nodes.len() <= with_menus.nodes.len(),
+            "pruning must never grow the tree"
+        );
+    }
+
     /// Smoke test: dump the AX tree of *this* test process. The test process
     /// usually has no AX windows of its own, so we only assert the call
     /// returns *something* (possibly an empty tree) without panicking and
diff --git a/src/apps/desktop/src/computer_use/macos_ax_ui.rs b/src/apps/desktop/src/computer_use/macos_ax_ui.rs
index 721b6a1e43..e2b8994550 100644
--- a/src/apps/desktop/src/computer_use/macos_ax_ui.rs
+++ b/src/apps/desktop/src/computer_use/macos_ax_ui.rs
@@ -48,24 +48,17 @@ unsafe extern "C" {
 const K_AX_VALUE_CGPOINT: u32 = 1;
 const K_AX_VALUE_CGSIZE: u32 = 2;
 
+/// Pid of the frontmost application, via `NSWorkspace.frontmostApplication`.
+///
+/// Reads in-process in microseconds. The previous implementation shelled out to
+/// `osascript` on every call — and this is on the hot path for
+/// `describe_screen` (which reaches it up to three times per call), so a single
+/// observation used to cost several hundred milliseconds of process spawns plus
+/// the risk of a System Events AppleEvent timeout.
 fn frontmost_pid() -> BitFunResult<i32> {
-    let out = std::process::Command::new("/usr/bin/osascript")
-        .args([
-            "-e",
-            "tell application \"System Events\" to get unix id of first process whose frontmost is true",
-        ])
-        .output()
-        .map_err(|e| BitFunError::tool(format!("osascript spawn: {}", e)))?;
-    if !out.status.success() {
-        return Err(BitFunError::tool(format!(
-            "osascript failed: {}",
-            String::from_utf8_lossy(&out.stderr)
-        )));
-    }
-    let s = String::from_utf8_lossy(&out.stdout);
-    s.trim()
-        .parse::<i32>()
-        .map_err(|_| BitFunError::tool("Could not parse frontmost process id.".to_string()))
+    crate::computer_use::macos_bg_input::frontmost_pid_macos().ok_or_else(|| {
+        BitFunError::tool("NSWorkspace reported no frontmost application.".to_string())
+    })
 }
 
 unsafe fn ax_release(v: CFTypeRef) {
@@ -525,8 +518,10 @@ unsafe fn is_ax_hidden(elem: AXUIElementRef) -> bool {
             return false; // No AXHidden attribute = not hidden
         };
         // AXHidden is a CFBoolean
-        let hidden =
-            std::ptr::eq(val, core_foundation::boolean::kCFBooleanTrue as *const c_void);
+        let hidden = std::ptr::eq(
+            val,
+            core_foundation::boolean::kCFBooleanTrue as *const c_void,
+        );
         ax_release(val);
         hidden
     }
@@ -1123,6 +1118,37 @@ pub(super) fn frontmost_window_bounds_global() -> BitFunResult<(i32, i32, u32, u
     window_bounds_global_for_pid(pid)
 }
 
+/// Number of windows the app currently owns, per the AX `AXWindows` attribute.
+///
+/// A launched-but-windowless app — common for Electron clients whose window was
+/// closed while the process kept running — is otherwise indistinguishable from a
+/// healthy launch: `open_app` reports `success: true` with a live pid while
+/// there is nothing on screen to act on. Returning the count lets `open_app`
+/// detect that case and re-open the app instead of leaving the agent to
+/// discover it by trial and error.
+///
+/// `None` means the AX handle could not be created at all (dead pid, no
+/// Accessibility trust); `Some(0)` means the app is alive with no windows.
+pub(super) fn window_count_for_pid(pid: i32) -> Option<usize> {
+    // SAFETY: `AXUIElementCreateApplication` accepts any pid and returns null
+    // rather than an invalid handle, which we check before use.
+    let app = unsafe { AXUIElementCreateApplication(pid) };
+    if app.is_null() {
+        return None;
+    }
+    // SAFETY: `app` is a live non-null AXUIElementRef we own. `ax_copy_attr`
+    // follows the CF *Copy* rule, so the returned array carries a +1 retain that
+    // `wrap_under_create_rule` takes over. `app` is released as soon as the
+    // attribute has been copied out of it, on both the Some and None paths.
+    unsafe {
+        let arr_ref = ax_copy_attr(app, "AXWindows");
+        ax_release(app as CFTypeRef);
+        let arr_ref = arr_ref?;
+        let arr = CFArray::<*const c_void>::wrap_under_create_rule(arr_ref as CFArrayRef);
+        Some(arr.len() as usize)
+    }
+}
+
 /// Bounds of the selected app's focused or main window in global screen coordinates.
 pub(super) fn window_bounds_global_for_pid(pid: i32) -> BitFunResult<(i32, i32, u32, u32)> {
     let app = unsafe { AXUIElementCreateApplication(pid) };
diff --git a/src/apps/desktop/src/computer_use/macos_bg_input.rs b/src/apps/desktop/src/computer_use/macos_bg_input.rs
index 092c716063..33a9f58721 100644
--- a/src/apps/desktop/src/computer_use/macos_bg_input.rs
+++ b/src/apps/desktop/src/computer_use/macos_bg_input.rs
@@ -388,8 +388,39 @@ pub(super) fn bg_click(
 /// Returns `None` when the AppKit lookup is not available (e.g. headless tests
 /// or non-main-thread contexts where we don't want to assert).
 pub(super) fn frontmost_pid_macos() -> Option<i32> {
+    frontmost_app_identity_macos().map(|id| id.pid)
+}
+
+/// Identity of the macOS frontmost application, read straight from
+/// `NSWorkspace.frontmostApplication`.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(super) struct MacFrontmostApp {
+    pub pid: i32,
+    /// `NSRunningApplication.localizedName` — what the user sees in the menu
+    /// bar (e.g. "飞书"), which is **not** always the executable or bundle
+    /// name (`Feishu` / `Lark.app`).
+    pub name: Option<String>,
+    pub bundle_id: Option<String>,
+}
+
+/// Best-effort identity (pid + localized name + bundle id) of the frontmost
+/// application.
+///
+/// This deliberately avoids `osascript`: the previous AppleScript spelling
+/// (`tell application "System Events" to … first process whose frontmost is
+/// true`) cost a process spawn on every single tool result, could block on an
+/// AppleEvent timeout when System Events was busy, and — because it embedded a
+/// `try … end try` block in expression position — never actually compiled, so
+/// the caller silently saw `None` forever. `NSWorkspace` answers in-process in
+/// microseconds and needs no Automation permission.
+pub(super) fn frontmost_app_identity_macos() -> Option<MacFrontmostApp> {
     use objc2::msg_send;
     use objc2::runtime::AnyObject;
+    // SAFETY: every selector is sent to a class/instance that was just checked
+    // non-null. `sharedWorkspace`, `frontmostApplication`, `localizedName` and
+    // `bundleIdentifier` are all +0 (autoreleased/borrowed) returns, so nothing
+    // here owns a retain to balance. `NSWorkspace.frontmostApplication` is
+    // documented as safe to read from any thread.
     unsafe {
         let cls = objc2::runtime::AnyClass::get(c"NSWorkspace")?;
         let ws: *mut AnyObject = msg_send![cls, sharedWorkspace];
@@ -402,9 +433,102 @@ pub(super) fn frontmost_pid_macos() -> Option<i32> {
         }
         let pid: i32 = msg_send![app, processIdentifier];
         if pid <= 0 {
+            return None;
+        }
+        let name: *mut AnyObject = msg_send![app, localizedName];
+        let bundle: *mut AnyObject = msg_send![app, bundleIdentifier];
+        Some(MacFrontmostApp {
+            pid,
+            name: ns_string_to_rust(name),
+            bundle_id: ns_string_to_rust(bundle),
+        })
+    }
+}
+
+/// Pid of a running application with the given bundle identifier, preferring
+/// the most recently activated instance. `None` when nothing with that bundle
+/// id is running.
+pub(super) fn pid_for_bundle_id_macos(bundle_id: &str) -> Option<i32> {
+    use objc2::msg_send;
+    use objc2::runtime::AnyObject;
+    use objc2_foundation::NSString;
+    // SAFETY: `runningApplicationsWithBundleIdentifier:` returns a +0 NSArray;
+    // indices stay in `0..count` and every element is null-checked before use.
+    unsafe {
+        let cls = objc2::runtime::AnyClass::get(c"NSRunningApplication")?;
+        let ns_bundle = NSString::from_str(bundle_id);
+        let arr: *mut AnyObject =
+            msg_send![cls, runningApplicationsWithBundleIdentifier: &*ns_bundle];
+        if arr.is_null() {
+            return None;
+        }
+        let count: usize = msg_send![arr, count];
+        // Prefer an instance that already owns windows; fall back to the first.
+        let mut fallback: Option<i32> = None;
+        for i in 0..count {
+            let app: *mut AnyObject = msg_send![arr, objectAtIndex: i];
+            if app.is_null() {
+                continue;
+            }
+            let pid: i32 = msg_send![app, processIdentifier];
+            if pid <= 0 {
+                continue;
+            }
+            if fallback.is_none() {
+                fallback = Some(pid);
+            }
+            if crate::computer_use::macos_ax_ui::window_count_for_pid(pid).unwrap_or(0) > 0 {
+                return Some(pid);
+            }
+        }
+        fallback
+    }
+}
+
+/// Localized name and bundle id of a running application, by pid.
+pub(super) fn running_app_identity_macos(pid: i32) -> Option<(Option<String>, Option<String>)> {
+    use objc2::msg_send;
+    use objc2::runtime::AnyObject;
+    // SAFETY: `runningApplicationWithProcessIdentifier:` returns nil for an
+    // unknown pid, which is checked; the two property reads are +0 returns.
+    unsafe {
+        let cls = objc2::runtime::AnyClass::get(c"NSRunningApplication")?;
+        let app: *mut AnyObject = msg_send![cls, runningApplicationWithProcessIdentifier: pid];
+        if app.is_null() {
+            return None;
+        }
+        let name: *mut AnyObject = msg_send![app, localizedName];
+        let bundle: *mut AnyObject = msg_send![app, bundleIdentifier];
+        Some((ns_string_to_rust(name), ns_string_to_rust(bundle)))
+    }
+}
+
+/// Copy an `NSString *` into an owned Rust `String`. Returns `None` for a null
+/// pointer or a string whose UTF-8 buffer is unavailable.
+///
+/// # Safety
+/// `s` must be null or a valid `NSString` pointer.
+pub(super) unsafe fn ns_string_to_rust(s: *mut objc2::runtime::AnyObject) -> Option<String> {
+    use objc2::msg_send;
+    if s.is_null() {
+        return None;
+    }
+    // SAFETY: `s` is a valid NSString per this function's contract, checked
+    // non-null above. `UTF8String` hands back a NUL-terminated buffer owned by
+    // the autorelease pool; `CStr::to_string_lossy().into_owned()` copies out of
+    // it before returning, so nothing borrows the pool past this block.
+    unsafe {
+        let utf8: *const std::os::raw::c_char = msg_send![s, UTF8String];
+        if utf8.is_null() {
+            return None;
+        }
+        let out = std::ffi::CStr::from_ptr(utf8)
+            .to_string_lossy()
+            .into_owned();
+        if out.is_empty() {
             None
         } else {
-            Some(pid)
+            Some(out)
         }
     }
 }
diff --git a/src/apps/desktop/src/embedded_relay_host.rs b/src/apps/desktop/src/embedded_relay_host.rs
index 1c1a6f2438..72fd793762 100644
--- a/src/apps/desktop/src/embedded_relay_host.rs
+++ b/src/apps/desktop/src/embedded_relay_host.rs
@@ -206,6 +206,56 @@ mod tests {
             .port()
     }
 
+    /// Assert `port` became bindable again, i.e. the host really did drop its
+    /// listener.
+    ///
+    /// A single bind attempt conflates two different things: our host leaking
+    /// the listener, and some other socket on the machine transiently holding
+    /// the port — it came from the ephemeral range, so a busy test run reissues
+    /// it constantly. Retrying separates them: a leaked listener is held until
+    /// the process exits and never frees up, while a transient steal clears in
+    /// milliseconds.
+    async fn assert_port_released(port: u16, what: &str) {
+        let deadline = std::time::Instant::now() + std::time::Duration::from_secs(5);
+        let mut last_err = None;
+        loop {
+            match tokio::net::TcpListener::bind(("0.0.0.0", port)).await {
+                Ok(l) => {
+                    drop(l);
+                    return;
+                }
+                Err(e) => last_err = Some(e),
+            }
+            if std::time::Instant::now() >= deadline {
+                panic!("{what}: port {port} never became bindable again: {last_err:?}");
+            }
+            tokio::time::sleep(std::time::Duration::from_millis(25)).await;
+        }
+    }
+
+    /// Start `host` on a port nothing else has taken, returning that port.
+    ///
+    /// `unused_port` can only report a port that was free a moment ago: it
+    /// binds an ephemeral port, reads the number and drops the listener, so
+    /// anything else on the machine may claim it before the caller binds. A
+    /// single attempt is a race that stays invisible on a quiet machine and
+    /// fails most of the time when the rest of the suite is busy enough to
+    /// churn through ephemeral ports. Retry rather than assume.
+    async fn start_on_free_port(
+        host: &DesktopEmbeddedRelayHost,
+        static_dir: Option<String>,
+    ) -> u16 {
+        let mut last_err = String::new();
+        for _ in 0..16 {
+            let port = unused_port().await;
+            match host.start(port, static_dir.clone()).await {
+                Ok(()) => return port,
+                Err(e) => last_err = e.to_string(),
+            }
+        }
+        panic!("could not find a free port for the embedded relay: {last_err}");
+    }
+
     #[tokio::test]
     async fn bind_failure_does_not_create_an_active_runtime() {
         let occupied = tokio::net::TcpListener::bind("0.0.0.0:0")
@@ -241,11 +291,8 @@ mod tests {
         std::fs::write(static_dir.join("assets").join("app.js"), "test asset")
             .expect("test asset should be written");
 
-        let port = unused_port().await;
         let host = DesktopEmbeddedRelayHost::default();
-        host.start(port, Some(static_dir.to_string_lossy().into_owned()))
-            .await
-            .expect("embedded relay should start");
+        let port = start_on_free_port(&host, Some(static_dir.to_string_lossy().into_owned())).await;
 
         let client = reqwest::Client::new();
         let index = client
@@ -290,35 +337,44 @@ mod tests {
             .expect("embedded relay should restart immediately on the same port");
         host.stop().await;
 
-        let released = tokio::net::TcpListener::bind(("0.0.0.0", port))
-            .await
-            .expect("stop must release the listener before returning");
-        drop(released);
+        assert_port_released(port, "stop must release the listener before returning").await;
         std::fs::remove_dir_all(&static_dir).expect("test static directory should be removed");
     }
 
     #[tokio::test]
     async fn cancelled_start_releases_listener_without_committing_runtime() {
-        let port = unused_port().await;
+        // Same port race as `start_on_free_port`, but this test aborts `start`
+        // mid-flight and so cannot use its success as the signal: a port stolen
+        // between reservation and bind shows up here as readiness never firing.
+        // Retry until we get a port `start` could actually take.
         let host = Arc::new(DesktopEmbeddedRelayHost::default());
-        let start_task = tokio::spawn({
-            let host = host.clone();
-            async move { host.start(port, None).await }
-        });
+        let mut acquired: Option<(u16, tokio::task::JoinHandle<_>)> = None;
+        for _ in 0..16 {
+            let port = unused_port().await;
+            let start_task = tokio::spawn({
+                let host = host.clone();
+                async move { host.start(port, None).await }
+            });
+            if tokio::time::timeout(
+                std::time::Duration::from_secs(1),
+                host.start_candidate_ready.notified(),
+            )
+            .await
+            .is_ok()
+            {
+                acquired = Some((port, start_task));
+                break;
+            }
+            start_task.abort();
+            let _ = start_task.await;
+        }
+        let (port, start_task) =
+            acquired.expect("start should create the candidate runtime before readiness completes");
 
-        tokio::time::timeout(
-            std::time::Duration::from_secs(1),
-            host.start_candidate_ready.notified(),
-        )
-        .await
-        .expect("start should create the candidate runtime before readiness completes");
         start_task.abort();
         let _ = start_task.await;
 
         assert!(host.runtime.lock().await.is_none());
-        let released = tokio::net::TcpListener::bind(("0.0.0.0", port))
-            .await
-            .expect("cancelling start must release the listener");
-        drop(released);
+        assert_port_released(port, "cancelling start must release the listener").await;
     }
 }
diff --git a/src/apps/desktop/src/lib.rs b/src/apps/desktop/src/lib.rs
index a4579884ee..76f41c4ef2 100644
--- a/src/apps/desktop/src/lib.rs
+++ b/src/apps/desktop/src/lib.rs
@@ -91,7 +91,6 @@ use api::session_api::*;
 use api::skill_api::*;
 use api::snapshot_service::*;
 use api::speech_api::*;
-use api::startchat_agent_api::*;
 use api::storage_commands::*;
 use api::subagent_api::*;
 use api::system_api::*;
@@ -1144,6 +1143,16 @@ pub async fn _run() {
                 step_started,
             );
 
+            // Reattach to a browser that is already running with remote
+            // debugging on, so a BitFun restart does not drop the connection.
+            let step_started = Instant::now();
+            api::browser_control_api::init_on_startup();
+            startup_trace.record_elapsed_step(
+                "native_setup",
+                "browser_control_init_on_startup",
+                step_started,
+            );
+
             {
                 let step_started = Instant::now();
                 let _terminal_state: tauri::State<'_, api::terminal_api::TerminalState> =
@@ -1281,6 +1290,7 @@ pub async fn _run() {
             api::agentic_api::update_session_mode,
             api::agentic_api::update_session_model,
             api::agentic_api::update_session_permission_mode,
+            api::agentic_api::update_active_turn_permission_mode,
             api::agentic_api::get_session_permission_mode,
             api::agentic_api::reload_session_context,
             api::agentic_api::update_session_title,
@@ -1295,6 +1305,8 @@ pub async fn _run() {
             api::agentic_api::ensure_assistant_bootstrap,
             api::agentic_api::run_init_agents_md,
             api::agentic_api::cancel_dialog_turn,
+            api::agentic_api::interrupt_dialog_turn,
+            api::agentic_api::recover_interrupted_dialog_turn,
             api::agentic_api::steer_dialog_turn,
             api::agentic_api::control_deep_review_queue,
             api::agentic_api::cancel_session,
@@ -1353,11 +1365,14 @@ pub async fn _run() {
             set_native_prompt_command_conflict_choice_command,
             expand_external_prompt_command_command,
             set_external_tool_target_decision_command,
+            set_external_tool_targets_enabled_command,
             set_external_tool_conflict_choice_command,
             set_external_subagent_activation_command,
+            set_external_subagents_enabled_command,
             set_external_subagent_model_binding_command,
             choose_external_subagent_conflict_command,
             set_external_mcp_server_decision_command,
+            set_external_mcp_servers_enabled_command,
             choose_external_mcp_conflict_command,
             api::context_upload_api::upload_image_contexts,
             get_all_tools_info,
@@ -1540,17 +1555,13 @@ pub async fn _run() {
             save_git_repo_history,
             load_git_repo_history,
             preview_commit_message,
-            analyze_work_state,
-            quick_analyze_work_state,
-            generate_greeting_only,
-            get_work_state_summary,
             compute_diff,
             apply_patch,
             save_merged_diff_content,
             initialize_snapshot,
             record_file_change,
             rollback_session,
-            rollback_to_turn,
+            rollback_session_to_turn,
             accept_session,
             accept_file,
             reject_file,
@@ -1585,7 +1596,6 @@ pub async fn _run() {
             load_session_turns,
             get_session_usage_report,
             save_session_turn,
-            record_local_command_turn,
             save_session_metadata,
             export_session_transcript,
             delete_persisted_session,
@@ -1684,6 +1694,7 @@ pub async fn _run() {
             subscribe_config_updates,
             get_model_configs,
             get_ai_model_catalog,
+            project_ai_model_reasoning_catalog,
             get_models_dev_catalog_status,
             refresh_models_dev_catalog_now,
             reveal_models_dev_cache_directory,
@@ -1895,8 +1906,8 @@ pub async fn _run() {
             api::browser_control_api::browser_control_list_browsers,
             api::browser_control_api::browser_control_get_status,
             api::browser_control_api::browser_control_launch,
+            api::browser_control_api::browser_control_enable_default_cdp,
             api::browser_control_api::browser_control_restart_with_cdp,
-            api::browser_control_api::browser_control_create_launcher,
             // Insights API
             api::insights_api::generate_insights,
             api::insights_api::get_latest_insights,
@@ -2203,10 +2214,6 @@ async fn init_function_agents(ai_client_factory: Arc<AIClientFactory>) -> anyhow
         ai_client_factory.clone(),
     );
 
-    let _ = bitfun_core::function_agents::startchat_func_agent::StartchatFunctionAgent::new(
-        ai_client_factory.clone(),
-    );
-
     Ok(())
 }
 
@@ -2653,7 +2660,7 @@ fn spawn_runtime_log_level_listener(default_level: log::LevelFilter) {
 fn create_event_emitter(
     transport: Arc<TauriTransportAdapter>,
 ) -> Arc<dyn bitfun_core::infrastructure::events::EventEmitter> {
-    use bitfun_core::infrastructure::events::TransportEmitter;
+    use bitfun_transport::TransportEmitter;
     let inner: Arc<dyn bitfun_core::infrastructure::events::EventEmitter> =
         Arc::new(TransportEmitter::new(transport));
     api::remote_connect_api::wrap_peer_aware_emitter(inner)
diff --git a/src/apps/desktop/src/runtime/mod.rs b/src/apps/desktop/src/runtime/mod.rs
index d5d9189e51..20dd0121d8 100644
--- a/src/apps/desktop/src/runtime/mod.rs
+++ b/src/apps/desktop/src/runtime/mod.rs
@@ -3,11 +3,9 @@ use std::sync::Arc;
 
 use bitfun_agent_runtime::sdk::{AgentRuntime, PermissionRequestEvent};
 use bitfun_core::agentic::coordination::{ConversationCoordinator, DialogScheduler};
-use bitfun_core::product_runtime::CoreLocalWorkspaceSnapshot;
 use bitfun_core::service::remote_ssh::SSHConnectionManager;
 use bitfun_core::service::token_usage::TokenUsageService;
 use bitfun_core::service::workspace::WorkspaceService;
-use bitfun_runtime_ports::LocalWorkspaceSnapshotPort;
 use tokio::sync::RwLock;
 
 mod session_application;
@@ -28,7 +26,6 @@ pub(crate) use session_application::{
 /// Desktop delivery profile or its product services have been assembled.
 pub struct DesktopRuntimeContext {
     session_application: DesktopSessionApplication,
-    local_workspace_snapshot: Arc<dyn LocalWorkspaceSnapshotPort>,
     permission_events_started: AtomicBool,
 }
 
@@ -50,11 +47,8 @@ impl DesktopRuntimeContext {
             ssh_manager,
             host_effects,
         )?;
-        let local_workspace_snapshot = CoreLocalWorkspaceSnapshot::build();
-
         Ok(Self {
             session_application,
-            local_workspace_snapshot,
             permission_events_started: AtomicBool::new(false),
         })
     }
@@ -67,10 +61,6 @@ impl DesktopRuntimeContext {
         &self.session_application
     }
 
-    pub(crate) fn local_workspace_snapshot(&self) -> &dyn LocalWorkspaceSnapshotPort {
-        self.local_workspace_snapshot.as_ref()
-    }
-
     pub(crate) fn start_permission_event_forwarding(
         &self,
         app: tauri::AppHandle,
@@ -161,8 +151,6 @@ mod tests {
         assert!(app_source.contains(".manage(desktop_runtime)"));
 
         assert!(runtime_source.contains("DesktopSessionApplication::build("));
-        assert!(runtime_source.contains("CoreLocalWorkspaceSnapshot::build()"));
-
         let session_commands = include_str!("../api/session_api.rs");
         assert_eq!(
             session_commands.matches("PersistenceManager::new").count(),
@@ -174,47 +162,20 @@ mod tests {
         assert!(session_application.contains("export_persisted_session_transcript"));
 
         let snapshot_commands = include_str!("../api/snapshot_service.rs");
-        assert_eq!(
-            snapshot_commands
-                .matches(".local_workspace_snapshot()")
-                .count(),
-            1,
-            "only workspace rollback uses the mutation port; reads use Core's bounded snapshot view"
-        );
         assert!(snapshot_commands.contains("begin_snapshot_history_read"));
         assert!(snapshot_commands.contains("open_snapshot_manager_for_view"));
         assert!(snapshot_commands.contains("ensure_local_snapshot_mutation_path"));
 
         let rollback_source = &snapshot_commands[snapshot_commands
-            .find("pub async fn rollback_to_turn")
+            .find("pub async fn rollback_session_to_turn")
             .expect("rollback command must exist")..];
         let remote_guard = rollback_source
             .find("ensure_complete_rollback_supported")
             .expect("remote rollback guard must remain host-owned");
-        let maintenance = rollback_source
-            .find("begin_snapshot_history_mutation")
-            .expect("scheduler maintenance must precede rollback");
-        let file_rollback = rollback_source
-            .find("rollback_local_workspace_files(")
-            .expect("workspace files must be restored through the port adapter");
-        let history_cleanup = file_rollback
-            + rollback_source[file_rollback..]
-                .find("if request.delete_turns")
-                .expect("history cleanup must remain host-owned");
-        let history_event = rollback_source
-            .find("conversation_turns_deleted")
-            .expect("history event must remain host-projected");
-        let rollback_event = rollback_source
-            .find("turn_rolled_back")
-            .expect("rollback event must remain host-projected");
-        assert!(
-            remote_guard < maintenance
-                && maintenance < file_rollback
-                && file_rollback < history_cleanup
-                && history_cleanup < history_event
-                && history_event < rollback_event,
-            "Desktop rollback must preserve remote, maintenance, files, history, and event order"
-        );
+        let runtime_revert = rollback_source
+            .find(".rollback_session_to_turn(request)")
+            .expect("rollback must delegate to the Agent Session transaction");
+        assert!(remote_guard < runtime_revert);
 
         let sdk_source = include_str!("../../../../crates/execution/agent-runtime/src/sdk.rs");
         assert!(!sdk_source.contains("LocalWorkspaceSnapshot"));
@@ -347,7 +308,7 @@ mod tests {
             "pub async fn initialize_snapshot",
             "pub async fn record_file_change",
             "pub async fn rollback_session",
-            "pub async fn rollback_to_turn",
+            "pub async fn rollback_session_to_turn",
             "pub async fn accept_session",
             "pub async fn accept_file",
             "pub async fn reject_file",
diff --git a/src/apps/desktop/src/runtime/session_application.rs b/src/apps/desktop/src/runtime/session_application.rs
index 671bbc3add..a9731a7074 100644
--- a/src/apps/desktop/src/runtime/session_application.rs
+++ b/src/apps/desktop/src/runtime/session_application.rs
@@ -131,14 +131,6 @@ pub(crate) struct DesktopSessionViewRestore {
     pub timings: SessionViewRestoreTiming,
 }
 
-#[derive(Debug, Clone)]
-pub(crate) struct DesktopRecordedLocalCommandTurn {
-    pub turn_id: String,
-    pub storage_turn_index: usize,
-    pub total_turn_count: usize,
-    pub turn_catalog: SessionTurnCatalog,
-}
-
 #[derive(Debug)]
 pub(crate) struct DesktopSessionWithTurnsRestore {
     pub session: Session,
@@ -334,6 +326,17 @@ impl DesktopSessionApplication {
             .map_err(|error| DesktopSessionApplicationError::Core(error.to_string()))
     }
 
+    pub(crate) async fn rollback_session_to_turn(
+        &self,
+        request: bitfun_runtime_ports::AgentSessionRollbackToTurnRequest,
+    ) -> DesktopSessionApplicationResult<bitfun_runtime_ports::AgentSessionRollbackToTurnOutcome>
+    {
+        self.agent_runtime
+            .rollback_session_to_turn(request)
+            .await
+            .map_err(|error| DesktopSessionApplicationError::Runtime(error.into_message()))
+    }
+
     async fn resolved_scope(
         &self,
         request: DesktopSessionScopeRequest,
@@ -494,10 +497,19 @@ impl DesktopSessionApplication {
         let scope = self.resolved_scope(request).await;
         self.ensure_runtime_ownership(&scope)?;
         let storage_path = self.storage_path(&scope);
-        self.compatibility
-            .ensure_session_loaded_from_storage_path(&storage_path, &turn.session_id, false)
+        // An externally projected Session has no Runtime state to restore, and
+        // loading one would rewrite its persisted mode to a local fallback.
+        if !self
+            .compatibility
+            .is_externally_projected_session(&storage_path, &turn.session_id)
             .await
-            .map_err(desktop_core_session_error)?;
+            .map_err(desktop_core_session_error)?
+        {
+            self.compatibility
+                .ensure_session_loaded_from_storage_path(&storage_path, &turn.session_id, false)
+                .await
+                .map_err(desktop_core_session_error)?;
+        }
         if let Some(local_command) = local_command_turn_record_request(turn)? {
             return self
                 .agent_runtime
@@ -517,55 +529,6 @@ impl DesktopSessionApplication {
             .map_err(desktop_core_session_error)
     }
 
-    pub(crate) async fn record_local_command_turn(
-        &self,
-        request: DesktopSessionScopeRequest,
-        turn: &DialogTurnData,
-    ) -> DesktopSessionApplicationResult<DesktopRecordedLocalCommandTurn> {
-        let scope = self.resolved_scope(request).await;
-        self.ensure_runtime_ownership(&scope)?;
-        let storage_path = self.storage_path(&scope);
-        self.compatibility
-            .ensure_session_loaded_from_storage_path(&storage_path, &turn.session_id, false)
-            .await
-            .map_err(desktop_core_session_error)?;
-        let local_command = local_command_turn_record_request(turn)?.ok_or_else(|| {
-            DesktopSessionApplicationError::Validation(
-                "record_local_command_turn accepts only local_command Turns".to_string(),
-            )
-        })?;
-        let recorded = self
-            .agent_runtime
-            .record_completed_local_command_turn(local_command)
-            .await
-            .map_err(desktop_runtime_session_error)?;
-        let (_, _, total_turn_count, turn_catalog, _) = self
-            .compatibility
-            .restore_session_view_from_storage_path(&storage_path, &turn.session_id, false, Some(1))
-            .await
-            .map_err(desktop_core_session_error)?;
-        let catalog_entry = turn_catalog
-            .entries
-            .iter()
-            .find(|entry| {
-                entry.turn_id.as_deref() == Some(recorded.turn_id.as_str())
-                    && entry.storage_turn_index == recorded.storage_turn_index
-            })
-            .ok_or_else(|| {
-                DesktopSessionApplicationError::OutcomeUnknown(format!(
-                    "Recorded local command Turn is missing from the authoritative catalog: {}",
-                    recorded.turn_id
-                ))
-            })?;
-
-        Ok(DesktopRecordedLocalCommandTurn {
-            turn_id: recorded.turn_id,
-            storage_turn_index: catalog_entry.storage_turn_index,
-            total_turn_count,
-            turn_catalog,
-        })
-    }
-
     pub(crate) async fn touch_session(
         &self,
         request: DesktopSessionScopeRequest,
diff --git a/src/apps/desktop/tauri.conf.json b/src/apps/desktop/tauri.conf.json
index 3be96887b2..ded84a9102 100644
--- a/src/apps/desktop/tauri.conf.json
+++ b/src/apps/desktop/tauri.conf.json
@@ -24,6 +24,23 @@
       "../../crates/services/services-integrations/assets/models-dev.LICENSE.txt": "third-party/models.dev/LICENSE.txt",
       "../../crates/services/services-integrations/assets/models-dev.provenance.json": "third-party/models.dev/provenance.json"
     },
+    "macOS": {
+      "dmg": {
+        "background": "dmg/background.png",
+        "windowSize": {
+          "width": 660,
+          "height": 400
+        },
+        "appPosition": {
+          "x": 180,
+          "y": 170
+        },
+        "applicationFolderPosition": {
+          "x": 480,
+          "y": 170
+        }
+      }
+    },
     "linux": {
       "deb": {
         "depends": [
diff --git a/src/apps/mobile/harmonyos/AGENTS.md b/src/apps/mobile/harmonyos/AGENTS.md
index 15e9ccc1a3..fdcefa6d23 100644
--- a/src/apps/mobile/harmonyos/AGENTS.md
+++ b/src/apps/mobile/harmonyos/AGENTS.md
@@ -13,22 +13,26 @@ the module. Keep the official responsibilities explicit:
   intents/events rather than calling services directly.
 - ViewModels bridge services and views by owning feature state, projecting data,
   and handling intents. ViewModels must not import components.
+- Shared conversation presentation DTOs (`ChatSurface`, `ChatComposerCapabilities`,
+  `ConversationUiModels`) live in `pages/state/`. State must not import
+  `pages/components`.
 
 The following constraints are enforced incrementally by
 `pnpm run harmony:architecture` (the runtime behavior checks remain in
 `entry/src/test/ArchitectureUnit.test.ets`):
 
 1. `services/**` must not import `../pages/`.
-2. `pages/components/**` must not import `pages/viewmodel/`; imports of
+2. `pages/state/**` must not import `pages/components/`.
+3. `pages/components/**` must not import `pages/viewmodel/`; imports of
    `pages/state/` and `pages/policy/` are allowed for observable state and pure
    policies.
-3. The page dependency graph must remain acyclic; ViewModels must not depend on
+4. The page dependency graph must remain acyclic; ViewModels must not depend on
    components.
-4. Actions and Hooks use typed interfaces with object literals. Do not add
+5. Actions and Hooks use typed interfaces with object literals. Do not add
    position-dependent callback constructors.
-5. New components use `@ComponentV2`; do not add V1 `@Component`, `@State`,
+6. New components use `@ComponentV2`; do not add V1 `@Component`, `@State`,
    `@Prop`, `@Link`, or `@Watch` declarations. `@BuilderParam` remains supported.
-6. General Chat and Remote Chat shared observable fields belong to
+7. General Chat and Remote Chat shared observable fields belong to
    `pages/state/ConversationCoreState.ets`. Page-specific state objects compose
    that core and must not redeclare the shared `@Trace` fields.
 
@@ -43,7 +47,7 @@ source scripts/ohos-env.sh
 ## Visual reference fidelity
 
 - Before drawing a system glyph, text approximation, or new bitmap, search the existing HarmonyOS media resources and the approved desktop reference images. Reuse the established asset when one exists.
-- Conversation header controls must use the approved `remote_ref_back` and `remote_ref_more` assets. Do not replace them with a system chevron or text such as `...` / bullet characters.
+- Conversation header controls must use the approved `remote_ref_back` and `remote_ref_more` assets. Do not replace them with a system chevron or text such as `...` / bullet characters. Compact top-left open-sidebar uses `CompactMenuButton` (`gpt_home_menu_glyph`). Wide restore/collapse uses `SidebarToggleButton` (the sidebar-pane glyph).
 - Render monochrome reference assets in template mode and tint them with semantic theme colors such as `INK`. Never rely on the bitmap's original black or white pixels; the same control must remain legible in light and dark themes.
 - Keep paired header controls on the same fixed touch-target size and optical alignment. A responsive layout may reposition a control, but must not silently change its icon geometry or visual weight.
 - Keep `SymbolGlyph` geometry separate from its touch target. When a glyph is clickable or sits in a decorated control, wrap it in `Stack({ alignContent: Alignment.Center })` (or use a centered `Button`) and give the glyph its visual size; do not stretch the glyph itself to the full 32vp/40vp/44vp target, because font metrics can make the icon look off-center.
diff --git a/src/apps/mobile/harmonyos/AppScope/app.json5 b/src/apps/mobile/harmonyos/AppScope/app.json5
index 46c672f414..cba82bca53 100644
--- a/src/apps/mobile/harmonyos/AppScope/app.json5
+++ b/src/apps/mobile/harmonyos/AppScope/app.json5
@@ -1,6 +1,6 @@
 {
   "app": {
-    "bundleName": "com.example.bitfun_mobile",
+    "bundleName": "com.bitfun.app",
     "vendor": "example",
     "versionCode": 1000000,
     "versionName": "1.0.0",
diff --git a/src/apps/mobile/harmonyos/docs/mvvm-architecture-refactor-design.md b/src/apps/mobile/harmonyos/docs/mvvm-architecture-refactor-design.md
index 8185fa3cff..fd18c001bb 100644
--- a/src/apps/mobile/harmonyos/docs/mvvm-architecture-refactor-design.md
+++ b/src/apps/mobile/harmonyos/docs/mvvm-architecture-refactor-design.md
@@ -547,7 +547,7 @@ hdc -t 5ZU0226202001116 file recv /data/local/tmp/s.jpeg ./s.jpeg
 
 设备侧注意事项（已踩过的坑）：
 
-- bundle 名是 **`com.example.bitfun_mobile`**，不是 `com.bitfun.mobile`；
+- bundle 名是 **`com.bitfun.app`**，和手表端共用一个 bundle。2026-08-10 从脚手架遗留的 `com.example.bitfun_mobile` 改过来的，原因是 `distributedKVStore` 按 bundleName + storeId 隔离，跨设备同步的前提是同一个 app —— bundle 不一致时手机和手表各自建的是两个互不相干的库，手机↔手表的凭证交接物理上跑不通。改动的代价是已装的旧包等于另一个 app，数据不通、要重新登录；
 - `hdc` 必须带 `-t <serial>`，否则报 `[Fail]ExecuteCommand need connect-key`（列出了两个 target）；
 - 外屏分辨率 1080×2444；点击用 `hdc -t <id> shell uinput -T -c X Y`。
 
diff --git a/src/apps/mobile/harmonyos/docs/wide-conversation-navigation-design.md b/src/apps/mobile/harmonyos/docs/wide-conversation-navigation-design.md
index a2296504cc..efba5ae6bd 100644
--- a/src/apps/mobile/harmonyos/docs/wide-conversation-navigation-design.md
+++ b/src/apps/mobile/harmonyos/docs/wide-conversation-navigation-design.md
@@ -6,23 +6,30 @@ Scope: `src/apps/mobile/harmonyos`，主要涉及双屏/三屏布局、会话来
 
 ## 实施状态
 
-截至 2026-08-07：
+截至 2026-08-13：
 
 ### 已实现
 
+- 布局判定对齐官方 GridRow 横向断点：md `600vp` 起双栏，lg `840vp` 起 extra-wide；合盖与悬停（`HALF_FOLDED`）强制不走 master-detail。不再用 `deviceType === tablet` 决定宽屏。
+- 展开折叠屏若 `getCurrentFoldCreaseRegion()` 为空，合成中线铰链（16vp）作为 master/detail 分界，避免内容压在铰链上。
+- 悬停态会话使用官方 `FolderStack`：上半为显示区（时间线），下半为操作区（Composer）。
+- 展开态只要存在可用纵向折痕（双折叠一道、三折叠两道），且当前视口放得下 master + detail，就进入 master-detail。
 - 宽屏本地与远程左栏在相同位置复用固定的“本地 / Remote”分段选择器，选中态由当前路由推导。
 - 来源选择器使用独立来源切换动作，不复用单屏 `enterCodeEntry()`；具体会话行只选择当前来源内的会话。
 - 宽屏来源切换使用 `clear(false)` 与 `pushPath(..., false)` 无转场替换路由，不播放页面进入或退出动画。
 - 宽屏本地和远程 master pane 均不提供全局侧边栏入口；远程宽屏标题栏已移除会叠加本地 drawer 的菜单按钮，单屏标题栏菜单保持不变。
 - 本地与远程来源切换使用路由合同计算目标，不累积跨来源返回路径。
 - 切回本地时停止手机侧远程轮询，但不清空远程活动会话或断开桌面。
-- 通过 `display.getCurrentFoldCreaseRegion()` 读取折痕；第一道有效纵向折痕用于 master/detail 分界，无有效折痕时回退到 `344`。
-- 两道折痕或超宽宽度被识别为 extra-wide，但继续使用同一个 master-detail，不创建第三栏。
+- 通过 `display.getCurrentFoldCreaseRegion()` 读取折痕；第一道有效纵向折痕用于 master/detail 分界。
+- 双折叠展开打开文件预览时，会话/预览分界对齐那一道折痕，而不是按视口对半切。
+- 两道折痕或 lg 宽度被识别为 extra-wide，但会话仍使用同一个 master-detail，不创建第三会话栏。官方聊天分栏在 md/lg/xl 均为列表|会话；第三窗格只用于文件预览。
 - 第二道折痕会把 detail 划分为无折痕候选内容带；会话视图选择最宽的候选带，同宽时优先右侧，避免 Composer、菜单和消息内操作热区跨越折痕。
 - extra-wide detail 外层仍覆盖中间和右侧两屏；上述内容带只是 presentation 几何约束，不增加第三个业务 pane。
+- 监听 `foldStatusChange` 与 `foldDisplayModeChange`，折叠形态变化时重算几何。
 
 ### 已验证
 
+- 下列真机项仍以改前 HAP 为准，本轮官方断点/合成铰链/悬停改动需重新安装后复验。
 - `assembleHap` 在固定来源选择器和第二道折痕安全内容带实现后重新构建通过；主题颜色治理检查通过。
 - HarmonyOS 本地单元测试任务通过，覆盖折叠优先级、来源路由、连续来源切换不增长返回栈、零/一/两道折痕、非法折痕和非对称三屏几何。
 - `ConversationLayoutPolicy` 的新增行、函数和分支覆盖率均为 100%。
@@ -39,13 +46,14 @@ Scope: `src/apps/mobile/harmonyos`，主要涉及双屏/三屏布局、会话来
 
 ### 待验证
 
+- 本轮改动后的 Mate X7 展开态：折痕为空时应走中线铰链，而不是固定 344。
+- Mate X7 悬停态：`FolderStack` 将 Composer 放到下半操作区。
 - 两道折痕的三折叠真机完整展开态（Mate X7 不覆盖此项）。
 - 三屏与双屏之间的真实折叠切换连续性。
-- 固定来源选择器版本的最终 HAP 在折叠单屏下复验；代码路径仍通过默认关闭的显式宽屏开关隔离。
 
 当前 Mate X7 的 DisplayManagerService 报告 `dms.hidumper.supportdebug false`，因此单屏验收使用设备真实折叠状态完成，没有用显示调试命令模拟合盖。
 
-在上述真机项完成前，不应把三屏手工验收标记为完成。折叠单屏基线矩阵已经完成，但固定来源选择器最终 HAP 仍需一次真实折叠复验后才能关闭回归项。
+在上述真机项完成前，不应把三屏手工验收标记为完成。
 
 ## 背景
 
@@ -76,8 +84,9 @@ HarmonyOS 手机在展开双屏、完整展开三屏或其他宽屏形态下，
 - 不改变远程连接、配对、鉴权或断线重连协议。
 - 不因为切换会话来源而停止桌面端正在执行的任务。
 - 第一阶段不调整 `RemoteCreate` 的页面结构。
-- 不改变当前宽屏阈值和折叠状态判定规则。
-- 不因为三屏增加一个独立的第三栏、第二套会话列表或新的业务路由模式。
+- 宽度阈值对齐官方 md/lg（600 / 840）；合盖与悬停强制单屏（悬停走 FolderStack 上下分带）。展开后是否进入宽屏由宽度、纵向折痕和折叠状态决定，不使用 `deviceType`。
+- 不因为三屏增加一个独立的第三会话栏、第二套会话列表或新的业务路由模式。文件预览可以占用第三窗格。
+- 展开会话不改造成 `FoldSplitContainer` 外壳：该组件只有预设比例，无法对齐实测折痕像素。折叠屏展开继续用折痕几何；悬停用官方 `FolderStack`。
 
 ## 当前逻辑
 
@@ -86,13 +95,15 @@ HarmonyOS 手机在展开双屏、完整展开三屏或其他宽屏形态下，
 `AppRootPresentation.isWideLayout()` 当前遵循以下逻辑：
 
 ```text
-设备处于折叠状态                    -> 单屏
-设备非折叠，且 media query 命中宽屏 -> 宽屏
-设备非折叠，且实际宽度达到阈值      -> 宽屏
-其他                                -> 单屏
+设备处于折叠状态                                      -> 单屏
+设备处于悬停（HALF_FOLDED）                          -> 单屏 + FolderStack（上显示 / 下操作）
+设备非折叠，宽视口（≥600vp 或 media query），有纵向折痕，且放得下两栏 -> 宽屏
+设备非折叠，宽视口，折叠屏展开且折痕缺失              -> 宽屏，合成中线铰链
+设备非折叠，宽视口，无折痕                            -> 宽屏（断点驱动，含平板）
+其他                                                  -> 单屏
 ```
 
-折叠状态优先于宽度。因此即使报告的可用宽度较大，只要设备处于折叠状态，也必须继续使用单屏布局。
+折叠与悬停优先于宽度和折痕。双折叠展开的一道折痕与三折叠的两道折痕使用同一套 master-detail，不新增第三会话栏。
 
 ### 路由分流
 
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/i18n/RemoteI18n.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/i18n/RemoteI18n.ets
index 1fce0571d1..987c97abd1 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/i18n/RemoteI18n.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/i18n/RemoteI18n.ets
@@ -12,6 +12,7 @@ const ZH_CN_MESSAGES: [string, string][] = [
   ['common.keep', '保留'],
   ['common.loading', '加载中...'],
   ['common.open', '打开'],
+  ['common.other', '其他'],
   ['common.ready', '就绪'],
   ['common.refresh', '刷新'],
   ['common.retry', '重试'],
@@ -22,6 +23,7 @@ const ZH_CN_MESSAGES: [string, string][] = [
 
   ['chatHome.prompt', '今天想做什么？'],
   ['chatHome.placeholder', '问问 BitFun'],
+  ['chatHome.localHint', '这是手机上的对话。要读写电脑上的项目，请切换到远程。'],
   ['chatHome.research', '查找资料'],
   ['chatHome.researchPrompt', '帮我查找资料并整理重点：'],
   ['chatHome.image', '分析图片'],
@@ -34,12 +36,9 @@ const ZH_CN_MESSAGES: [string, string][] = [
   ['chatHome.organizePrompt', '请帮我梳理这个问题的重点和思路：'],
   ['chatHome.plan', '制定行动计划'],
   ['chatHome.planPrompt', '请帮我制定一份清晰、可执行的行动计划：'],
-  ['chatHome.codeHintTitle', '这个任务可能需要 Code 能力'],
-  ['chatHome.codeHintBody', '连接本地工作区后，BitFun 才能读取项目文件、运行命令并修改代码。'],
-  ['chatHome.enterCode', '进入 Code'],
-  ['chatHome.generalAdvice', '仅给出通用建议'],
-  ['chatHome.generalPending', '普通聊天服务即将接入。需要处理本地项目时，请从侧栏进入 Code。'],
-  ['chatHome.generalAdvicePending', '普通代码建议服务即将接入。需要读取项目或运行命令时，请进入 Code。'],
+  ['chatHome.codeHintTitle', '这个任务可能需要远程能力'],
+  ['chatHome.codeHintBody', '连接桌面工作区后，BitFun 才能读取项目文件、运行命令并修改代码。'],
+  ['chatHome.enterCode', '进入远程'],
 
   ['generalChat.ready', 'BitFun 已就绪'],
   ['generalChat.generating', 'BitFun 正在回复'],
@@ -48,11 +47,10 @@ const ZH_CN_MESSAGES: [string, string][] = [
   ['generalChat.stopped', '已停止生成。'],
   ['generalChat.interrupted', '回复已中断，已保留收到的内容。'],
   ['generalChat.replyInterrupted', '回复中断'],
-  ['generalChat.fileDownloadMock', '普通聊天暂不支持下载桌面端文件，请进入 Code 后处理本地文件。'],
-  ['generalChat.filePreviewUnavailable', '普通聊天暂不支持预览桌面端文件，请进入 Code 后打开。'],
+  ['generalChat.fileDownloadMock', '普通聊天暂不支持下载桌面端文件，请进入远程后处理本地文件。'],
+  ['generalChat.filePreviewUnavailable', '普通聊天暂不支持预览桌面端文件，请进入远程后打开。'],
   ['generalChat.localRestoreFailed', '普通对话历史暂时无法恢复，你仍可新建对话。'],
   ['generalChat.modelNotConfigured', '请先在设置中配置普通对话模型。'],
-  ['generalChat.imageNotSupported', '当前模型通道暂不支持图片，请先发送文字消息。'],
   ['generalChat.authenticationFailed', 'API Key 无效或无权访问该模型。'],
   ['generalChat.rateLimited', '模型服务请求过于频繁，请稍后重试。'],
   ['generalChat.serviceUnavailable', '模型服务暂时不可用，请稍后重试。'],
@@ -101,12 +99,13 @@ const ZH_CN_MESSAGES: [string, string][] = [
   ['sidebar.projects', '项目'],
   ['sidebar.tasks', '已计划'],
   ['sidebar.tools', '应用'],
-  ['sidebar.code', 'Remote'],
+  ['sidebar.code', '远程'],
   ['sidebar.more', '更多'],
   ['sidebar.recent', '最近'],
   ['sidebar.newChat', '聊天'],
   ['sidebar.generalChat', '普通对话'],
   ['sidebar.local', '本地'],
+  ['sidebar.pinned', '置顶'],
   ['sidebar.archived', '已归档'],
   ['sidebar.archive', '归档'],
   ['sidebar.unarchive', '取消归档'],
@@ -145,18 +144,18 @@ const ZH_CN_MESSAGES: [string, string][] = [
   ['viewSettings.status', '运行状态'],
   ['common.unknown', '未知'],
 
-  ['code.title', 'BitFun Code'],
+  ['code.title', 'BitFun 远程'],
   ['code.heroTitle', '本地开发助手'],
   ['code.heroBody', '连接桌面端后，BitFun 可以访问你的代码仓库、运行命令和修改文件。'],
   ['code.connectWorkspace', '连接本地工作区'],
   ['code.connectDesc', '扫码或粘贴连接链接'],
   ['code.noWorkspacePreview', '连接桌面端后会显示最近打开的代码仓库。'],
-  ['code.newTask', '新建 Code 任务'],
+  ['code.newTask', '新建远程任务'],
   ['code.switchWorkspace', '切换工作区'],
   ['code.disconnect', '断开连接'],
-  ['code.recentSessions', '最近 Code 会话'],
-  ['code.emptySessionTitle', '暂无 Code 会话'],
-  ['code.emptySessionText', '连接本地工作区后，可以新建 Code 任务处理项目问题。'],
+  ['code.recentSessions', '最近远程会话'],
+  ['code.emptySessionTitle', '暂无远程会话'],
+  ['code.emptySessionText', '连接本地工作区后，可以新建远程任务处理项目问题。'],
 
   ['remote.title', '远程'],
   ['remote.chats', '聊天'],
@@ -227,9 +226,6 @@ const ZH_CN_MESSAGES: [string, string][] = [
   ['remote.settings.accountSigningIn', '正在登录…'],
   ['remote.settings.accountLoginFailed', '云账号登录失败，请检查 relay 地址和账号密码。'],
   ['remote.settings.relayUrlPlaceholder', 'Relay 地址，例如 https://relay.example.com'],
-  ['remote.settings.accountSync', '同步云端会话'],
-  ['remote.settings.accountSyncSuccess', '已同步 {0} 个会话'],
-  ['remote.settings.accountSyncFailed', '云端会话同步失败，请稍后重试。'],
   ['remote.settings.accountLogout', '退出登录'],
   ['remote.settings.accountLoggingOut', '正在退出…'],
   ['remote.settings.deviceManagement', '设备管理'],
@@ -277,7 +273,7 @@ const ZH_CN_MESSAGES: [string, string][] = [
   ['connect.scanPairCode', '扫描二维码以配对'],
   ['connect.scanPairCodeAction', '扫描二维码连接'],
   ['connect.accountDevicesTitle', '选择桌面设备'],
-  ['connect.accountDevicesSubtitle', 'Remote'],
+  ['connect.accountDevicesSubtitle', '远程'],
   ['connect.accountDevicesBody', '选择一台在线桌面继续工作。'],
   ['connect.availableDevices', '账号设备'],
   ['connect.deviceLastUsed', '上次连接'],
@@ -372,7 +368,7 @@ const ZH_CN_MESSAGES: [string, string][] = [
   ['home.emptyAssistantTitle', '暂无助理会话'],
   ['home.emptyAssistantText', '桌面端开放创建后可在这里开始。'],
   ['home.emptyTitle', '暂无会话'],
-  ['home.emptyText', '用 Code 处理编码任务，或用 Cowork 处理日常办公。'],
+  ['home.emptyText', '用远程处理编码任务，或用普通对话处理日常问题。'],
 
   ['sheet.createTitle', '创建 {0} 会话'],
   ['sheet.workspace', '工作区'],
@@ -384,24 +380,24 @@ const ZH_CN_MESSAGES: [string, string][] = [
   ['sheet.creating', '创建中...'],
   ['sheet.start', '开始'],
 
-  ['chat.remoteSession', 'Remote Session'],
+  ['chat.remoteSession', '远程会话'],
   ['chat.sessionTitle', '会话标题'],
+  ['chat.sessionSection', '会话'],
+  ['chat.pin', '置顶'],
+  ['chat.unpin', '取消置顶'],
+  ['chat.uploadedFiles', '已上传的文件'],
   ['chat.stop', '停止'],
+  ['chat.send', '发送'],
+  ['chat.voiceInput', '语音输入'],
+  ['chat.stopListening', '停止听写'],
+  ['chat.addImage', '添加图片'],
+  ['chat.removeImage', '移除图片'],
   ['chat.selectModel', '选择模型'],
   ['chat.loadOlder', '加载更早消息'],
   ['chat.inputPlaceholder', '向 BitFun 提问'],
   ['chat.voiceListeningPlaceholder', '正在听，请说话...'],
-  ['chat.quickExplain', '解释当前状态'],
-  ['chat.quickExplainPrompt', '请解释当前任务状态和下一步计划。'],
-  ['chat.quickContinue', '继续执行'],
-  ['chat.quickContinuePrompt', '继续执行当前任务。'],
-  ['chat.quickSummary', '总结结果'],
-  ['chat.quickSummaryPrompt', '总结目前完成的内容和剩余风险。'],
+  ['chat.queuedAfterRunningTurn', '已排队，当前任务结束后执行'],
   ['chat.image', '图片'],
-  ['chat.attachments', '附件'],
-  ['chat.pickImage', '选择图片'],
-  ['chat.pickImageDesc', '从相册选择图片发送给 BitFun'],
-  ['chat.quickPrompts', '快捷指令'],
   ['chat.thinkingRunning', '运行中'],
   ['chat.thinkingDone', '已完成'],
   ['chat.thinkingInProgress', '正在思考'],
@@ -497,6 +493,7 @@ const ZH_CN_MESSAGES: [string, string][] = [
   ['status.sessionUnarchived', '会话已取消归档'],
   ['status.sessionExported', '已复制为 Markdown'],
   ['status.messagesSynced', '消息已同步'],
+  ['status.messagesRestored', '已恢复本地会话记录'],
   ['status.switchingModel', '正在切换模型'],
   ['status.modelSwitched', '模型已切换'],
   ['status.loadOlderMessages', '加载更早消息'],
@@ -548,12 +545,27 @@ const ZH_CN_MESSAGES: [string, string][] = [
   ['errors.remoteUrlInvalid', '远程连接链接格式不正确，请重新扫描二维码或粘贴完整链接。'],
   ['errors.permissionDenied', '没有获得所需权限，请允许扫码或剪贴板访问后重试。'],
   ['errors.operationFailed', '操作失败，请稍后重试。'],
+  ['errors.payloadTooLarge', '这条消息带的附件超过了中继允许的大小，请减少图片数量或选择更小的图片。'],
   ['errors.imageTooLargeAfterCompression', '图片压缩后仍超过 {0} MB，请选择较小图片。'],
   ['errors.imageCompressionFailed', '图片压缩失败，请选择较小图片。'],
   ['errors.voicePermissionDenied', '没有获得麦克风权限，无法语音输入。'],
   ['errors.voiceInputUnavailable', '语音识别暂不可用，请稍后重试。'],
   ['errors.voiceInputFailed', '语音识别失败（{0}），请稍后重试。'],
 
+  ['watchProvision.title', '把这块手表加入你的 BitFun 账号？'],
+  ['watchProvision.deviceId', '设备编号 {0}'],
+  ['watchProvision.body', '同意后，这块手表可以用你的账号连接桌面端，有效期 30 天。请确认这台设备就在你手里。'],
+  ['watchProvision.approve', '允许'],
+  ['watchProvision.reject', '拒绝'],
+  ['watchProvision.gotIt', '知道了'],
+  ['watchProvision.working', '正在从桌面端申请授权...'],
+  ['watchProvision.doneBody', '{0} 已加入账号，手表上可以直接使用了。'],
+  ['watchProvision.rejected', '已在手机上拒绝。'],
+  ['watchProvision.busy', '手机正在处理另一台设备的请求，请稍后再试。'],
+  ['watchProvision.errors.noDesktop', '需要先在手机上扫码连接桌面端，才能给手表授权。'],
+  ['watchProvision.errors.desktopUnreachable', '桌面端未在线或版本过旧，请更新桌面端后重试。'],
+  ['watchProvision.errors.handoffFailed', '授权已完成，但没能把凭证发给手表，请在手表上重试一次。'],
+
   ['ui.emptyMessage', '(空消息)'],
   ['ui.desktopProcessing', '桌面端正在处理...'],
   ['ui.seedConnected', '{0} 已连接。你可以继续发送指令，桌面端会在 BitFun 中执行。'],
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/model/RemoteModels.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/model/RemoteModels.ets
index ce5ad00ddd..3a99c59a07 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/model/RemoteModels.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/model/RemoteModels.ets
@@ -128,6 +128,12 @@ export interface RemoteCommand {
   answers?: Object;
   image_contexts?: RemoteImageContext[];
   images?: ImageAttachment[];
+  // provision_peer_device. `request_id` is minted by the device being
+  // provisioned, unlike `_request_id`, which the phone stamps on every command
+  // for its own correlation logging.
+  device_id?: string;
+  device_name?: string;
+  request_id?: string;
 }
 
 export interface PairChallengeResponse {
@@ -250,6 +256,18 @@ export interface DelegatedIdentityResponse extends CommandStatusResponse {
   device_id?: string;
 }
 
+/**
+ * Answer to `provision_peer_device`. Shaped like a delegated identity but
+ * carrying a 30-day *full* device credential, and `device_id` names the device
+ * that was just registered rather than the desktop that registered it.
+ */
+export interface PeerDeviceProvisionedResponse extends CommandStatusResponse {
+  token?: string;
+  user_id?: string;
+  master_key?: string;
+  device_id?: string;
+}
+
 export interface SessionListResult {
   sessions: RemoteSession[];
   hasMore: boolean;
@@ -338,8 +356,11 @@ export interface RemoteToolStatusResponse {
 }
 
 export interface RemoteQuestionAnswerPayload {
-  answer: string;
-  '0': string;
+  answer?: string;
+  '0'?: string | string[];
+  '1'?: string | string[];
+  '2'?: string | string[];
+  '3'?: string | string[];
 }
 
 export interface ChatMessageItemResponse {
@@ -353,6 +374,7 @@ export interface ChatMessageItemResponse {
 export interface ImageAttachment {
   name: string;
   data_url: string;
+  mime_type?: string;
 }
 
 export interface SelectedImageAttachment extends ImageAttachment {
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/AppRoot.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/AppRoot.ets
index 3c22ccc445..94e6e565bd 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/AppRoot.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/AppRoot.ets
@@ -1,4 +1,5 @@
 import { AppRootPresentation } from './components/AppRootPresentation';
+import { WatchProvisionCard } from './components/WatchProvisionCard';
 import { ArkUiAppRootHostAdapter } from './host/AppRootHostAdapter';
 import { AppRootRuntime } from './runtime/AppRootRuntime';
 
@@ -41,6 +42,21 @@ struct AppRoot {
         deviceId: this.runtime.remoteConnectionController.getDeviceId(),
         actions: this.runtime.presentationActions
       })
+
+      // Sits above every route on purpose: a watch waiting for approval must
+      // not be hidden behind whatever screen the phone happens to be on.
+      WatchProvisionCard({
+        state: this.runtime.watchProvisionState,
+        onApprove: () => {
+          void this.runtime.watchProvisionController.approve();
+        },
+        onReject: () => {
+          void this.runtime.watchProvisionController.reject();
+        },
+        onDismiss: () => {
+          this.runtime.watchProvisionController.dismiss();
+        }
+      })
     }
     .width('100%')
     .height('100%')
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/actions/AppRootPresentationActions.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/actions/AppRootPresentationActions.ets
index 63fecd397e..1ee798cff9 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/actions/AppRootPresentationActions.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/actions/AppRootPresentationActions.ets
@@ -1,5 +1,6 @@
 import { RemotePermissionMode, RemoteSession } from '../../model/RemoteModels';
 import { CloudAccountDevice } from '../../services/CloudAccountClient';
+import { DetectedUrlAction } from '../../services/ConnectScanDecisionPolicy';
 import { ConversationIntent } from './ConversationIntent';
 import { AppRoute, ConversationSource } from '../navigation/AppRouteContract';
 
@@ -86,9 +87,9 @@ export interface SettingsPresentationActions {
   readonly reconnect: () => void;
   readonly openAccount: () => void;
   readonly cloudLogin: (relayUrl: string, username: string, password: string) => Promise<string>;
-  readonly cloudSync: () => Promise<string>;
   readonly cloudLogout: () => Promise<void>;
   readonly cloudListDevices: () => Promise<CloudAccountDevice[]>;
+  readonly cloudSelectDevice: (device: CloudAccountDevice) => Promise<void>;
   readonly getPermissionMode: () => Promise<RemotePermissionMode>;
   readonly setPermissionMode: (mode: RemotePermissionMode) => Promise<RemotePermissionMode>;
   readonly testGeneral: (url: string, key: string, model: string, clear: boolean) => Promise<string>;
@@ -101,7 +102,7 @@ export interface ConnectPresentationActions {
   readonly clearPairing: () => void;
   readonly urlChanged: (url: string) => void;
   readonly userChanged: (user: string) => void;
-  readonly detected: (url: string) => boolean;
+  readonly detected: (url: string) => string;
   readonly inputVisible: (visible: boolean) => void;
   readonly paste: () => void;
   readonly scan: () => void;
@@ -136,14 +137,15 @@ export function emptyAppRootPresentationActions(): AppRootPresentationActions {
     },
     onSettings: {
       close: () => {}, addConnection: () => {}, disconnect: () => {}, reconnect: () => {}, openAccount: () => {},
-      cloudLogin: async () => '', cloudSync: async () => '', cloudLogout: async () => {},
-      cloudListDevices: async () => [], getPermissionMode: async () => 'ask',
+      cloudLogin: async () => '', cloudLogout: async () => {},
+      cloudListDevices: async () => [], cloudSelectDevice: async () => {},
+      getPermissionMode: async () => 'ask',
       setPermissionMode: async (mode: RemotePermissionMode) => mode,
       testGeneral: async () => '', saveGeneral: async () => ''
     },
     onConnect: {
       back: () => {}, connect: () => {}, clearPairing: () => {}, urlChanged: () => {}, userChanged: () => {},
-      detected: () => false, inputVisible: () => {}, paste: () => {}, scan: () => {},
+      detected: () => DetectedUrlAction.INVALID, inputVisible: () => {}, paste: () => {}, scan: () => {},
       cloudListDevices: async () => [], cloudSelectDevice: async () => {}
     },
     onFilePreview: { close: () => {}, refresh: () => {}, download: () => {}, openLink: () => {} },
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/actions/ConversationIntent.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/actions/ConversationIntent.ets
index 76dc0a66e0..b0cf70479a 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/actions/ConversationIntent.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/actions/ConversationIntent.ets
@@ -1,4 +1,4 @@
-import { ConversationUiQuestionAnswer } from '../components/ConversationUiModels';
+import { ConversationUiQuestionAnswer } from '../state/ConversationUiModels';
 import { FilePreviewRequest } from '../../model/FilePreviewTarget';
 
 export enum ConversationIntentType {
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/actions/ConversationIntentDispatcher.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/actions/ConversationIntentDispatcher.ets
index a07455141e..9ce3a59e6a 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/actions/ConversationIntentDispatcher.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/actions/ConversationIntentDispatcher.ets
@@ -1,7 +1,7 @@
 import { RemoteQuestionAnswerPayload, RemoteSession } from '../../model/RemoteModels';
 import { AppRoute, AppRouteContract } from '../navigation/AppRouteContract';
 import { ConversationIntent, ConversationIntentType } from './ConversationIntent';
-import { toRemoteQuestionAnswer } from '../components/ConversationUiModels';
+import { toRemoteQuestionAnswer } from '../state/ConversationUiModels';
 import { FilePreviewRequest } from '../../model/FilePreviewTarget';
 
 export interface ConversationIntentDispatcherHooks {
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/AppRootOverlaySurfaces.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/AppRootOverlaySurfaces.ets
index 734b9f7ea4..18c71f525e 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/AppRootOverlaySurfaces.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/AppRootOverlaySurfaces.ets
@@ -3,7 +3,7 @@ import {
   emptyAppRootPresentationActions
 } from '../actions/AppRootPresentationActions';
 import { AppRouteContract, ConversationSource } from '../navigation/AppRouteContract';
-import { AppShellState } from '../state/AppShellState';
+import { AppShellState, CONNECT_INTENT_AUTO } from '../state/AppShellState';
 import { GeneralChatPageState } from '../state/GeneralChatPageState';
 import { RemotePageState } from '../state/RemotePageState';
 import { AppSidebar } from './AppSidebar';
@@ -120,9 +120,9 @@ export struct AppSettingsSurface {
         onOpenAccount: this.actions.onSettings.openAccount,
         onAddConnection: this.actions.onSettings.addConnection,
         cloudLogin: this.actions.onSettings.cloudLogin,
-        cloudSync: this.actions.onSettings.cloudSync,
         cloudLogout: this.actions.onSettings.cloudLogout,
         cloudListDevices: this.actions.onSettings.cloudListDevices,
+        cloudSelectDevice: this.actions.onSettings.cloudSelectDevice,
         getPermissionMode: this.actions.onSettings.getPermissionMode,
         setPermissionMode: this.actions.onSettings.setPermissionMode,
         openAccountOnAppear: this.shellState.settingsMode === 'account',
@@ -152,6 +152,7 @@ export struct AppSettingsSurface {
 export struct AppConnectSurface {
   @Param remotePageState: RemotePageState = new RemotePageState();
   @Param deviceId: string = '';
+  @Param openIntent: string = CONNECT_INTENT_AUTO;
   @Param actions: AppRootPresentationActions = emptyAppRootPresentationActions();
 
   build() {
@@ -169,7 +170,7 @@ export struct AppConnectSurface {
       controlTargetDeviceId: this.remotePageState.controlTargetDeviceId,
       requiresAccountAuth: this.remotePageState.requiresAccountAuth,
       accountUsername: this.remotePageState.accountUsername,
-      startWithScanner: true,
+      openIntent: this.openIntent,
       onBack: this.actions.onConnect.back,
       onConnect: this.actions.onConnect.connect,
       onRemoteUrlChange: this.actions.onConnect.urlChanged,
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/AppRootPresentation.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/AppRootPresentation.ets
index cd5564c45f..09e36f4262 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/AppRootPresentation.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/AppRootPresentation.ets
@@ -1,5 +1,4 @@
 import display from '@ohos.display';
-import deviceInfo from '@ohos.deviceInfo';
 import mediaQuery from '@ohos.mediaquery';
 import { RemoteUiState } from '../../services/RemoteUiState';
 import { AppShell } from './AppShell';
@@ -46,14 +45,6 @@ function safeFoldStatus(): display.FoldStatus {
   }
 }
 
-function safeDeviceType(): string {
-  try {
-    return deviceInfo.deviceType || '';
-  } catch (_err) {
-    return '';
-  }
-}
-
 @ComponentV2
 export struct AppRootPresentation {
   @Param shellState: AppShellState = new AppShellState();
@@ -78,7 +69,6 @@ export struct AppRootPresentation {
   @Local restoreCollapsedMasterAfterPreview: boolean = false;
   @Local showRemoteViewSettings: boolean = false;
   @Local remoteSurfaceState: RemoteSurfaceState = new RemoteSurfaceState();
-  private readonly deviceType: string = safeDeviceType();
   private verticalCreases: ConversationLayoutCrease[] = [];
   private wideQueryListener?: mediaQuery.MediaQueryListener;
   private foldStatusChanged: (status: display.FoldStatus) => void =
@@ -86,6 +76,10 @@ export struct AppRootPresentation {
       this.foldStatus = status;
       this.refreshWideGeometry();
     };
+  private foldDisplayModeChanged: (mode: display.FoldDisplayMode) => void =
+    (_mode: display.FoldDisplayMode): void => {
+      this.refreshWideGeometry();
+    };
   private wideQueryChanged: (result: mediaQuery.MediaQueryResult) => void =
     (result: mediaQuery.MediaQueryResult): void => {
       this.wideLayoutMatched = result.matches;
@@ -181,6 +175,7 @@ export struct AppRootPresentation {
         // Compact conversations own the drawer, not a back control: Local and
         // Remote both open the sidebar over the chat instead of leaving it.
         showBackButton: false,
+        hoverOperateMode: this.isHoverLayout(),
         onRestoreSidebar: () => this.restoreWideMasterPane()
       })
     }
@@ -271,7 +266,7 @@ export struct AppRootPresentation {
     try {
       const appMediaQuery = this.getUIContext().getMediaQuery();
       this.wideQueryListener = appMediaQuery.matchMediaSync(
-        `screen and (${ConversationLayoutPolicy.WIDE_LAYOUT_MIN_WIDTH} < width)`
+        `screen and (${ConversationLayoutPolicy.MD_MIN_WIDTH} < width)`
       );
       this.wideLayoutMatched = this.wideQueryListener.matches;
       this.wideQueryListener.on('change', this.wideQueryChanged);
@@ -287,6 +282,7 @@ export struct AppRootPresentation {
       this.foldStatus = display.getFoldStatus();
       this.refreshWideGeometry();
       display.on('foldStatusChange', this.foldStatusChanged);
+      display.on('foldDisplayModeChange', this.foldDisplayModeChanged);
     } catch (_err) {
       this.foldStatus = display.FoldStatus.FOLD_STATUS_UNKNOWN;
       this.unbindFoldStatus();
@@ -296,6 +292,7 @@ export struct AppRootPresentation {
   private unbindFoldStatus(): void {
     try {
       display.off('foldStatusChange', this.foldStatusChanged);
+      display.off('foldDisplayModeChange', this.foldDisplayModeChanged);
     } catch (_err) {
     }
   }
@@ -319,8 +316,9 @@ export struct AppRootPresentation {
       this.viewportWidth,
       this.wideLayoutMatched,
       this.foldStatus === display.FoldStatus.FOLD_STATUS_FOLDED,
-      this.deviceType,
-      verticalCreases
+      verticalCreases,
+      this.isExpandedFoldable(),
+      this.isHoverLayout()
     );
     const geometry = ConversationLayoutPolicy.resolveWideGeometry(
       this.viewportWidth,
@@ -338,13 +336,43 @@ export struct AppRootPresentation {
     }
   }
 
+  private isHoverLayout(): boolean {
+    return this.foldStatus === display.FoldStatus.FOLD_STATUS_HALF_FOLDED;
+  }
+
+  private isExpandedFoldable(): boolean {
+    return this.foldStatus === display.FoldStatus.FOLD_STATUS_EXPANDED && this.isFoldableDevice();
+  }
+
+  private isFoldableDevice(): boolean {
+    try {
+      return display.isFoldable();
+    } catch (_err) {
+      return this.foldStatus === display.FoldStatus.FOLD_STATUS_EXPANDED ||
+        this.foldStatus === display.FoldStatus.FOLD_STATUS_HALF_FOLDED ||
+        this.foldStatus === display.FoldStatus.FOLD_STATUS_FOLDED;
+    }
+  }
+
   private currentVerticalCreases(): ConversationLayoutCrease[] {
-    if (this.foldStatus === display.FoldStatus.FOLD_STATUS_FOLDED) {
+    if (this.foldStatus === display.FoldStatus.FOLD_STATUS_FOLDED || this.isHoverLayout()) {
       return [];
     }
+    return ConversationLayoutPolicy.effectiveVerticalCreases(
+      this.viewportWidth,
+      this.reportedVerticalCreases(),
+      this.isExpandedFoldable()
+    );
+  }
+
+  private reportedVerticalCreases(): ConversationLayoutCrease[] {
     try {
       const region = display.getCurrentFoldCreaseRegion();
-      return region.creaseRects
+      const creaseRects = region.creaseRects;
+      if (!creaseRects) {
+        return [];
+      }
+      return creaseRects
         .filter((rect: display.Rect): boolean => rect.height > rect.width)
         .map((rect: display.Rect): ConversationLayoutCrease => {
           return new ConversationLayoutCrease(
@@ -403,6 +431,7 @@ export struct AppRootPresentation {
     AppConnectSurface({
       remotePageState: this.remotePageState,
       deviceId: this.deviceId,
+      openIntent: this.shellState.connectSheetIntent,
       actions: this.actions
     })
   }
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/AppShell.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/AppShell.ets
index 1d71ccca67..5a9b66ffb1 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/AppShell.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/AppShell.ets
@@ -1,4 +1,5 @@
 import { AppShellState } from '../state/AppShellState';
+import { ConversationLayoutPolicy } from '../policy/ConversationLayoutPolicy';
 import { PAGE_BG } from './Theme';
 
 const WIDE_SETTINGS_SHEET_MAX_WIDTH: number = 680;
@@ -24,7 +25,14 @@ export struct AppShell {
   build() {
     Stack({ alignContent: Alignment.Start }) {
       Column() {
-        this.sidebar()
+        // The drawer is a compact affordance. Wide layouts put the same session
+        // list in the master pane instead, and this copy stayed mounted behind
+        // an opacity of 0 — invisible, but rebuilt on every selection change,
+        // which on a tablet doubled the cost of switching sessions. Compact
+        // keeps it mounted so opening and closing still cross-fades.
+        if (!this.useWideLayout || this.shellState.showSidebar) {
+          this.sidebar()
+        }
       }
       .width(this.sidebarWidth())
       .height('100%')
@@ -126,7 +134,7 @@ export struct AppShell {
     if (this.shellWidth <= 0) {
       return 280;
     }
-    if (this.shellWidth < 720) {
+    if (this.shellWidth < ConversationLayoutPolicy.MD_MIN_WIDTH) {
       return Math.min(280, Math.max(220, Math.round(this.shellWidth * 0.68)));
     }
     return Math.min(420, Math.max(280, Math.round(this.shellWidth * 0.35)));
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/AppSidebar.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/AppSidebar.ets
index 6e02ff01b0..69f8d2b16d 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/AppSidebar.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/AppSidebar.ets
@@ -111,7 +111,7 @@ export struct AppSidebar {
   LocalSessionContent() {
     Column() {
       if (this.visiblePinnedSessions().length > 0) {
-        Text('置顶')
+        Text(RemoteI18n.t('sidebar.pinned'))
           .fontSize(14).fontWeight(FontWeight.Medium).fontColor(MUTED)
           .width('100%').margin({ top: 16, bottom: 6 })
         ForEach(this.visiblePinnedSessions(), (session: RemoteSession) => {
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/BitFunAccountLoginPage.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/BitFunAccountLoginPage.ets
index c1a6917fd0..627acca613 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/BitFunAccountLoginPage.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/BitFunAccountLoginPage.ets
@@ -1,6 +1,7 @@
 import { RemoteI18n } from '../../i18n/RemoteI18n';
 import { DEFAULT_CLOUD_RELAY_URL } from '../../services/CloudAccountClient';
 import { CARD, INK, MUTED, PRIMARY_ACTION, PRIMARY_ACTION_TEXT, RED, SUBTLE } from './Theme';
+import { TemplateIcon } from './TemplateIcon';
 
 @ComponentV2
 export struct BitFunAccountLoginPage {
@@ -104,11 +105,11 @@ export struct BitFunAccountLoginPage {
       .scrollBar(BarState.Off)
 
       Button() {
-        SymbolGlyph($r('sys.symbol.chevron_left'))
-          .fontSize(23)
-          .fontColor([INK])
-          .width(26)
-          .height(26)
+        TemplateIcon({
+          src: $r('app.media.remote_ref_back'),
+          iconWidth: 15,
+          iconHeight: 23
+        })
       }
       .width(44)
       .height(44)
@@ -116,6 +117,7 @@ export struct BitFunAccountLoginPage {
       .type(ButtonType.Circle)
       .backgroundColor('#00000000')
       .position({ x: 28, y: 22 })
+      .accessibilityText(RemoteI18n.t('common.back'))
       .onClick(() => {
         this.onBack();
       })
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ChatMessageBubble.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ChatMessageBubble.ets
index 66628abaa6..fb82970c09 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ChatMessageBubble.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ChatMessageBubble.ets
@@ -1,7 +1,12 @@
-import { ConversationUiImage, ConversationUiMessage, ConversationUiMessageItem, ConversationUiQuestionAnswer, ConversationUiToolStatus } from './ConversationUiModels';
-import { INK, LINE, MUTED, SOFT } from './Theme';
+import { ConversationUiImage, ConversationUiMessage, ConversationUiMessageItem, ConversationUiQuestionAnswer, ConversationUiToolStatus } from '../state/ConversationUiModels';
+import { ActivityGroupPolicy } from '../policy/ActivityGroupPolicy';
+import { AssistantProcessLayoutPolicy } from '../policy/AssistantProcessLayoutPolicy';
+import { ConversationMessageRenderPolicy } from '../policy/ConversationMessageRenderPolicy';
+import { ThinkingPresentationPolicy } from '../policy/ThinkingPresentationPolicy';
+import { LINE } from './Theme';
 import { MessageFileCards, MessageImageGallery, MessageMarkdown } from './ChatMessageContent';
 import { ChatMessageRetryAction, ChatTypingDots, ChatUserMessageBubble } from './ChatMessageChrome';
+import { SubagentTaskCard } from './SubagentTaskCard';
 import { ThinkingBlock } from './ThinkingBlock';
 import { ToolStatusList } from './ToolStatusList';
 import { MessageFileReference, MessageFileReferenceProjectionCache } from '../../services/MessageFileReferenceProjector';
@@ -105,24 +110,32 @@ export struct ChatMessageBubble {
 
   @Builder
   ProcessContent(item: ConversationUiMessage) {
+    if (this.leadingThinkingText(item).length > 0) {
+      this.Thinking(
+        this.leadingThinkingText(item),
+        this.leadingThinkingStatus(item),
+        `${item.id}-thinking`,
+        ThinkingPresentationPolicy.isRunning(this.leadingThinkingStatus(item))
+      )
+    }
     if (this.shouldRenderStructuredItems(item)) {
       this.StructuredItems(item.items || [], this.shouldOmitStructuredThinking(item))
       if (this.uncoveredTools(item).length > 0) {
         this.Tools(this.uncoveredTools(item))
       }
     } else {
+      if (item.tools && item.tools.length > 0) {
+        this.Tools(item.tools)
+      }
+      if (this.shouldShowTypingDots(item)) {
+        ChatTypingDots()
+      }
       if (item.role !== 'user' && this.visibleMessageText(item).length > 0 && this.visibleMessageText(item) !== item.thinking) {
         this.MessageText(this.visibleMessageText(item), this.isStreamingAssistant(), `${item.id}-body`)
         if (this.fileReferences(this.visibleMessageText(item)).length > 0) {
           this.FileCards(this.visibleMessageText(item))
         }
       }
-      if (this.shouldShowTypingDots(item)) {
-        ChatTypingDots()
-      }
-      if (item.tools && item.tools.length > 0) {
-        this.Tools(item.tools)
-      }
     }
     if (this.pinnedThinkingText(item).length > 0) {
       this.Thinking(
@@ -179,22 +192,19 @@ export struct ChatMessageBubble {
   @Builder
   ActivityGroup(group: StructuredRenderGroup, omitActiveThinking: boolean = false) {
     Column({ space: 6 }) {
+      if (!omitActiveThinking &&
+        ActivityGroupPolicy.thinkingHeaderCount(this.activityThinkingCount(group)) > 0 &&
+        (this.activityThinkingText(group).length > 0 || this.activityThinkingStreaming(group))) {
+        this.Thinking(
+          this.activityThinkingText(group),
+          this.activityThinkingStatus(group),
+          `${this.item.id}-${group.path}-activity-thinking`,
+          this.activityThinkingStreaming(group)
+        )
+      }
       if (this.activityGroupTools(group).length > 0) {
         this.Tools(this.activityGroupTools(group))
       }
-      ForEach(group.items, (entry: ConversationUiMessageItem, index: number) => {
-        if (!omitActiveThinking &&
-          this.isRenderableActivityThinking(entry, group.itemStatuses[index] || '', group.itemStreaming[index] || false)) {
-          this.Thinking(
-            entry.content || '',
-            group.itemStatuses[index] || this.item.status,
-            `${this.item.id}-${group.path}-activity-${index}-thinking`,
-            group.itemStreaming[index] || false
-          )
-        }
-      }, (entry: ConversationUiMessageItem, index: number) => {
-        return this.structuredItemKey(entry, `${group.path}-activity-thinking-${index}`);
-      })
     }
     .width('100%')
   }
@@ -233,37 +243,17 @@ export struct ChatMessageBubble {
 
   @Builder
   SubagentGroup(entry: ConversationUiMessageItem, path: string, activeScope: boolean = false) {
-    Column({ space: 8 }) {
-      Row({ space: 8 }) {
-        Text('↳')
-          .width(18)
-          .fontSize(13)
-          .fontColor(MUTED)
-          .textAlign(TextAlign.Center)
-        Text(this.subagentTitle(entry))
-          .fontSize(13)
-          .fontWeight(FontWeight.Medium)
-          .fontColor(INK)
-          .layoutWeight(1)
-          .maxLines(1)
-          .textOverflow({ overflow: TextOverflow.Ellipsis })
-      }
-      .width('100%')
-      if (entry.tool && this.isRunningTool(entry.tool)) {
-        ChatTypingDots()
-      }
-      if (entry.content && entry.content.trim().length > 0 && !this.isTextEntry(entry) && !this.isThinkingEntry(entry)) {
-        this.MessageText(entry.content, activeScope && (!entry.subItems || entry.subItems.length === 0), `${this.item.id}-${path}-subagent`)
-      }
-      if (entry.subItems && entry.subItems.length > 0) {
-        this.ChildItems(entry.subItems, path, activeScope)
+    SubagentTaskCard({
+      title: this.subagentTitle(entry),
+      running: !!(entry.tool && this.isRunningTool(entry.tool)),
+      content: this.subagentBody(entry),
+      hasChildren: !!(entry.subItems && entry.subItems.length > 0),
+      childItems: () => {
+        if (entry.subItems && entry.subItems.length > 0) {
+          this.ChildItems(entry.subItems, path, activeScope)
+        }
       }
-    }
-    .width('100%')
-    .padding({ left: 10, right: 10, top: 8, bottom: 8 })
-    .backgroundColor(SOFT)
-    .borderRadius(12)
-    .border({ width: 1, color: LINE })
+    })
   }
 
   @Builder
@@ -285,10 +275,7 @@ export struct ChatMessageBubble {
       status,
       keepExpandedWhenDone: false,
       streaming,
-      streamKey,
-      onCopyText: (body: string) => {
-        this.onCopyMessage(body);
-      }
+      streamKey
     })
   }
 
@@ -350,11 +337,7 @@ export struct ChatMessageBubble {
   }
 
   private visibleMessageText(item: ConversationUiMessage): string {
-    const text = item.text.trim();
-    if (text === '(空消息)' || text === '(empty message)') {
-      return '';
-    }
-    return text;
+    return ConversationMessageRenderPolicy.visibleText(item.text);
   }
 
   private shouldShowTypingDots(item: ConversationUiMessage): boolean {
@@ -384,7 +367,8 @@ export struct ChatMessageBubble {
   }
 
   private shouldPinThinkingToBottom(item: ConversationUiMessage): boolean {
-    return this.isStreamingAssistant() &&
+    return AssistantProcessLayoutPolicy.pinsThinkingAfterTools() &&
+      this.isStreamingAssistant() &&
       this.currentThinkingText(item).length > 0;
   }
 
@@ -395,17 +379,52 @@ export struct ChatMessageBubble {
     return this.currentThinkingText(item);
   }
 
-  private shouldOmitStructuredThinking(item: ConversationUiMessage): boolean {
-    return this.shouldPinThinkingToBottom(item) ||
-      (this.isStreamingAssistant() && this.hasVisibleAssistantOutput(item));
+  private leadingThinkingText(item: ConversationUiMessage): string {
+    if (this.shouldPinThinkingToBottom(item)) {
+      return '';
+    }
+    if (this.lastThinkingText(item.items || []).length > 0) {
+      return '';
+    }
+    return (item.thinking || '').trim();
+  }
+
+  private leadingThinkingStatus(item: ConversationUiMessage): string {
+    return ThinkingPresentationPolicy.liveThinkingStatus(
+      item.status,
+      this.hasLaterProcessOutput(item)
+    );
   }
 
-  private hasVisibleAssistantOutput(item: ConversationUiMessage): boolean {
-    if (this.lastTopLevelText(item.items || []).length > 0) {
+  private hasLaterProcessOutput(item: ConversationUiMessage): boolean {
+    if (item.tools && item.tools.length > 0) {
       return true;
     }
     const visible = this.visibleMessageText(item);
-    return visible.length > 0 && visible !== (item.thinking || '').trim();
+    if (visible.length > 0 && visible !== (item.thinking || '').trim()) {
+      return true;
+    }
+    return this.hasToolOrTextItems(item.items || []);
+  }
+
+  private hasToolOrTextItems(items: ConversationUiMessageItem[]): boolean {
+    return items.some((entry: ConversationUiMessageItem) => {
+      if (entry.tool || this.isTextEntry(entry)) {
+        return true;
+      }
+      return !!entry.subItems && this.hasToolOrTextItems(entry.subItems);
+    });
+  }
+
+  private subagentBody(entry: ConversationUiMessageItem): string {
+    if (!entry.content || this.isTextEntry(entry) || this.isThinkingEntry(entry)) {
+      return '';
+    }
+    return entry.content;
+  }
+
+  private shouldOmitStructuredThinking(_item: ConversationUiMessage): boolean {
+    return AssistantProcessLayoutPolicy.omitsInFlowThinkingWhileStreaming();
   }
 
   private currentThinkingText(item: ConversationUiMessage): string {
@@ -655,54 +674,11 @@ export struct ChatMessageBubble {
   }
 
   private shouldFoldIntoActivityGroup(entry: ConversationUiMessageItem): boolean {
-    if (this.isThinkingEntry(entry)) {
-      return true;
-    }
-    if (!entry.tool) {
-      return false;
-    }
-    return this.shouldFoldToolWithThinking(entry.tool);
-  }
-
-  private shouldFoldToolWithThinking(tool: ConversationUiToolStatus): boolean {
-    if (!this.isCollapsibleActivityTool(tool)) {
-      return false;
-    }
-    if (this.hasToolError(tool) || this.isPendingTool(tool) || this.isRunningTool(tool) || this.isQuestionTool(tool)) {
-      return false;
-    }
-    return this.isCompletedTool(tool) || this.isCancelledTool(tool);
-  }
-
-  private isCollapsibleActivityTool(tool: ConversationUiToolStatus): boolean {
-    const kind = this.activityToolKind(tool);
-    return kind === 'read' || kind === 'search';
-  }
-
-  private activityToolKind(tool: ConversationUiToolStatus): string {
-    const raw = tool.name || '';
-    const normalized = this.normalizedToolName(tool);
-    if (raw === 'Read' || raw === 'LS' ||
-      normalized === 'read' ||
-      normalized === 'read_file' ||
-      normalized === 'ls' ||
-      normalized === 'list_directory') {
-      return 'read';
-    }
-    if (raw === 'Grep' ||
-      raw === 'Glob' ||
-      raw === 'WebSearch' ||
-      raw === 'SemanticSearch' ||
-      normalized === 'grep' ||
-      normalized === 'glob' ||
-      normalized === 'websearch' ||
-      normalized === 'web_search' ||
-      normalized === 'semanticsearch' ||
-      normalized === 'semantic_search' ||
-      normalized.indexOf('search') >= 0) {
-      return 'search';
-    }
-    return '';
+    return ActivityGroupPolicy.shouldFoldEntry(
+      this.isThinkingEntry(entry),
+      this.isSubagentEntry(entry),
+      entry.tool
+    );
   }
 
   private activityGroupTools(group: StructuredRenderGroup): ConversationUiToolStatus[] {
@@ -715,19 +691,46 @@ export struct ChatMessageBubble {
     return tools;
   }
 
-  private isRenderableActivityThinking(
-    entry: ConversationUiMessageItem,
-    status: string,
-    streaming: boolean
-  ): boolean {
-    if (!this.isThinkingEntry(entry)) {
-      return false;
-    }
-    if (this.hasVisibleAssistantOutput(this.item)) {
-      return false;
-    }
-    const normalized = (status || '').toLowerCase();
-    return streaming || normalized === 'active' || normalized === 'running';
+  private activityThinkingCount(group: StructuredRenderGroup): number {
+    let count = 0;
+    group.items.forEach((entry: ConversationUiMessageItem) => {
+      if (this.isThinkingEntry(entry)) {
+        count += 1;
+      }
+    });
+    return count;
+  }
+
+  private activityThinkingText(group: StructuredRenderGroup): string {
+    const parts: string[] = [];
+    group.items.forEach((entry: ConversationUiMessageItem) => {
+      if (this.isThinkingEntry(entry)) {
+        parts.push(entry.content || '');
+      }
+    });
+    return ThinkingPresentationPolicy.mergedText(parts);
+  }
+
+  private activityThinkingStatus(group: StructuredRenderGroup): string {
+    const statuses: string[] = [];
+    const streamings: boolean[] = [];
+    group.items.forEach((entry: ConversationUiMessageItem, index: number) => {
+      if (this.isThinkingEntry(entry)) {
+        statuses.push(group.itemStatuses[index] || '');
+        streamings.push(group.itemStreaming[index] || false);
+      }
+    });
+    return ThinkingPresentationPolicy.mergedStatusValue(statuses, streamings);
+  }
+
+  private activityThinkingStreaming(group: StructuredRenderGroup): boolean {
+    const streamings: boolean[] = [];
+    group.items.forEach((entry: ConversationUiMessageItem, index: number) => {
+      if (this.isThinkingEntry(entry)) {
+        streamings.push(group.itemStreaming[index] || false);
+      }
+    });
+    return ThinkingPresentationPolicy.mergedStreaming(streamings);
   }
 
   private stableToolHash(tools: ConversationUiToolStatus[]): string {
@@ -901,6 +904,9 @@ export struct ChatMessageBubble {
   }
 
   private structuredItemKey(entry: ConversationUiMessageItem, path: string): string {
+    if (this.isThinkingEntry(entry)) {
+      return `${path}-thinking`;
+    }
     if (entry.tool && entry.tool.id) {
       return `${path}-tool-${entry.tool.id}`;
     }
@@ -920,12 +926,12 @@ export struct ChatMessageBubble {
   private activityGroupKey(items: ConversationUiMessageItem[], path: string): string {
     const parts: string[] = [];
     items.forEach((entry: ConversationUiMessageItem, index: number) => {
-      const content = entry.content || '';
       const tool = entry.tool;
+      const thinking = this.isThinkingEntry(entry);
       parts.push([
         `${index}`,
         entry.type || '',
-        `${content.length}:${this.stableTextHash(content)}`,
+        thinking ? 'thinking' : `${(entry.content || '').length}:${this.stableTextHash(entry.content || '')}`,
         tool ? `${tool.id || ''}:${tool.name || ''}:${tool.status || ''}` : ''
       ].join(':'));
     });
@@ -936,16 +942,6 @@ export struct ChatMessageBubble {
     return (tool.name || 'Tool').replace(/[\s-]/g, '_').toLowerCase();
   }
 
-  private isCompletedTool(tool: ConversationUiToolStatus): boolean {
-    const normalized = (tool.status || '').toLowerCase();
-    return normalized === 'completed' || normalized === 'done' || normalized === 'success';
-  }
-
-  private isCancelledTool(tool: ConversationUiToolStatus): boolean {
-    const normalized = (tool.status || '').toLowerCase();
-    return normalized === 'cancelled' || normalized === 'canceled';
-  }
-
   private isRunningTool(tool: ConversationUiToolStatus): boolean {
     const normalized = (tool.status || '').toLowerCase();
     return normalized === 'running' || normalized === 'active';
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ChatMessageChrome.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ChatMessageChrome.ets
index c485c0add8..98a3ee75b8 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ChatMessageChrome.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ChatMessageChrome.ets
@@ -1,5 +1,5 @@
 import { RemoteI18n } from '../../i18n/RemoteI18n';
-import { ConversationUiMessage } from './ConversationUiModels';
+import { ConversationUiMessage } from '../state/ConversationUiModels';
 import { MessageImageGallery } from './ChatMessageContent';
 import { ACCENT, INK, MUTED, PRIMARY_ACTION_TEXT, RED, SOFT } from './Theme';
 
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ChatMessageContent.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ChatMessageContent.ets
index 10df9e3317..d21b3f6921 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ChatMessageContent.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ChatMessageContent.ets
@@ -1,4 +1,4 @@
-import { ConversationUiImage } from './ConversationUiModels';
+import { ConversationUiImage } from '../state/ConversationUiModels';
 import { RemoteI18n } from '../../i18n/RemoteI18n';
 import { FileTargetResolver } from '../../services/FileTargetResolver';
 import {
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ChatStatusBar.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ChatStatusBar.ets
index aa21d5e3f4..5eb5d96a6a 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ChatStatusBar.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ChatStatusBar.ets
@@ -39,6 +39,7 @@ export struct ChatStatusBar {
           .textAlign(TextAlign.Center)
           .backgroundColor(SOFT)
           .borderRadius(17)
+          .accessibilityText(RemoteI18n.t('chat.stop'))
           .onClick(() => {
             this.onStop();
           })
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ChatTimeline.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ChatTimeline.ets
index 79ad92a1cc..afe6df14f7 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ChatTimeline.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ChatTimeline.ets
@@ -1,7 +1,8 @@
-import { ConversationUiMessage, ConversationUiMessageItem, ConversationUiQuestionAnswer, toConversationUiMessage } from './ConversationUiModels';
+import { ConversationUiMessage, ConversationUiMessageItem, ConversationUiQuestionAnswer, toConversationUiMessage } from '../state/ConversationUiModels';
+import { ConversationMessageRenderPolicy } from '../policy/ConversationMessageRenderPolicy';
 import { RemoteI18n } from '../../i18n/RemoteI18n';
-import { ChatTimelineItem } from '../../services/ChatTimelineProjector';
-import { ChatSurface } from './ChatSurface';
+import { ChatTimelineItem, ChatTimelineRevisionTracker } from '../../services/ChatTimelineProjector';
+import { ChatSurface } from '../state/ChatSurface';
 import { CARD, INK, LINE, MUTED, RED } from './Theme';
 import { ChatMessageBubble } from './ChatMessageBubble';
 import { RemoteLogger } from '../../services/RemoteLogger';
@@ -9,6 +10,11 @@ import { RemoteLogger } from '../../services/RemoteLogger';
 @ComponentV2
 export struct ChatTimeline {
   private readonly listScroller: Scroller = new Scroller();
+  // Whether new content should pull the viewport down with it. True until the
+  // user scrolls up to read back through the transcript: at that point taking
+  // the viewport away from them would be worse than letting the reply grow off
+  // screen, and the chevron button below gives them the way back.
+  @Local stickToBottom: boolean = true;
   @Param surface: ChatSurface = ChatSurface.Remote;
   @Param timelineItems: ChatTimelineItem[] = [];
   @Param timelineRevision: number = 0;
@@ -34,6 +40,29 @@ export struct ChatTimeline {
   @Event onOpenFilePreview: (path: string, label: string) => void = (_path: string, _label: string) => {};
   @Event onDownloadFile: (path: string) => void = (_path: string) => {};
 
+  // Says whether an open reuses this subtree or rebuilds it. A rebuild means
+  // every bubble is constructed from nothing, and the cost of that is the
+  // difference between the two readings.
+  aboutToAppear(): void {
+    RemoteLogger.info(`chat timeline mounted surface=${this.surface} items=${this.timelineItems.length}`);
+    this.logTimelineProjection('mount');
+  }
+
+  aboutToDisappear(): void {
+    RemoteLogger.info(`chat timeline disposed items=${this.timelineItems.length}`);
+  }
+
+  // `stackFromEnd` covers content that grows inside the last item, but a whole
+  // new bubble arriving is a layout change the list does not chase on its own.
+  @Monitor('timelineRevision')
+  onTimelineChanged(): void {
+    this.logTimelineProjection('revision');
+    if (!this.stickToBottom) {
+      return;
+    }
+    this.listScroller.scrollEdge(Edge.Bottom);
+  }
+
   build() {
     Stack({ alignContent: Alignment.Bottom }) {
       List({ space: 12, scroller: this.listScroller }) {
@@ -52,15 +81,27 @@ export struct ChatTimeline {
         }
         ForEach(this.timelineItems, (item: ChatTimelineItem) => {
           this.TimelineItem(item)
-        }, (item: ChatTimelineItem) => `${this.timelineRevision}-${item.id}`)
+        }, (item: ChatTimelineItem) => ChatTimelineRevisionTracker.itemSignature(item))
       }
       .width('100%')
       .height('100%')
       .padding({ left: 20, right: 20, top: 0, bottom: 12 })
-      .stackFromEnd(false)
+      // A streaming reply grows in place rather than arriving as a new item, so
+      // the bottom of the list has to be the anchor — otherwise the text the
+      // agent is writing right now renders below the fold and never comes back.
+      .stackFromEnd(true)
+      // Keeps the read position when older messages are prepended above.
+      .maintainVisibleContentPosition(true)
       .scrollBar(BarState.Off)
+      .onDidScroll((_scrollOffset: number, scrollState: ScrollState) => {
+        if (this.listScroller.isAtEnd()) {
+          this.stickToBottom = true;
+        } else if (scrollState !== ScrollState.Idle) {
+          this.stickToBottom = false;
+        }
+      })
 
-      if (this.surface === ChatSurface.Remote && this.timelineItems.length > 2) {
+      if (this.surface === ChatSurface.Remote && !this.stickToBottom) {
         Stack({ alignContent: Alignment.Center }) {
           SymbolGlyph($r('sys.symbol.chevron_down'))
             .fontSize(18)
@@ -73,6 +114,7 @@ export struct ChatTimeline {
         .shadow({ radius: 14, color: '#14000000', offsetY: 5 })
         .margin({ bottom: 4 })
         .onClick(() => {
+          this.stickToBottom = true;
           this.listScroller.scrollEdge(Edge.Bottom);
         })
       }
@@ -124,7 +166,7 @@ export struct ChatTimeline {
       .onAppear(() => {
         this.logRenderedItem(item);
       })
-    } else if (item.message && this.shouldRenderMessage(toConversationUiMessage(item.message))) {
+    } else if (item.message && this.shouldRenderTimelineMessage(item)) {
       ListItem() {
         this.MessageBubble(item)
       }
@@ -136,7 +178,37 @@ export struct ChatTimeline {
 
   private logRenderedItem(item: ChatTimelineItem): void {
     const message = item.message;
-    RemoteLogger.info(`chat timeline item appear revision=${this.timelineRevision} type=${item.type} id=${item.id} status=${message ? message.status : ''} textLength=${message ? message.text.length : 0}`);
+    const uiMessage = message ? toConversationUiMessage(message) : undefined;
+    const thinkingLength = uiMessage && uiMessage.thinking ? uiMessage.thinking.length : 0;
+    const toolCount = uiMessage && uiMessage.tools ? uiMessage.tools.length : 0;
+    const itemCount = uiMessage && uiMessage.items ? uiMessage.items.length : 0;
+    RemoteLogger.info(
+      `chat timeline item appear revision=${this.timelineRevision} type=${item.type} id=${item.id} ` +
+      `status=${uiMessage ? uiMessage.status : ''} textLength=${uiMessage ? uiMessage.text.length : 0} ` +
+      `thinkingLength=${thinkingLength} toolCount=${toolCount} itemCount=${itemCount} ` +
+      `itemTypes=${this.itemTypeSummary(uiMessage && uiMessage.items ? uiMessage.items : [])}`
+    );
+  }
+
+  private itemTypeSummary(items: ConversationUiMessageItem[]): string {
+    if (items.length === 0) {
+      return '';
+    }
+    const parts: string[] = [];
+    items.forEach((entry: ConversationUiMessageItem) => {
+      if (entry.tool && entry.tool.name) {
+        parts.push(entry.tool.name);
+      } else if ((entry.type || '').length > 0) {
+        parts.push(entry.type || '');
+      } else {
+        parts.push('item');
+      }
+    });
+    const summary = parts.join(',');
+    if (summary.length > 80) {
+      return summary.substring(0, 80);
+    }
+    return summary;
   }
 
   @Builder
@@ -179,32 +251,44 @@ export struct ChatTimeline {
     })
   }
 
-  private shouldRenderMessage(item: ConversationUiMessage): boolean {
-    return item.role === 'user' ||
-      this.visibleMessageText(item).length > 0 ||
-      (item.thinking || '').trim().length > 0 ||
-      (item.tools && item.tools.length > 0) ||
-      this.hasRenderableItems(item.items || []) ||
-      (item.images && item.images.length > 0) ||
-      (item.status || '').toLowerCase() === 'active' ||
-      item.status === 'failed';
+  private shouldRenderTimelineMessage(item: ChatTimelineItem): boolean {
+    if (!item.message) {
+      return false;
+    }
+    try {
+      const uiMessage = toConversationUiMessage(item.message);
+      const render = ConversationMessageRenderPolicy.shouldRender(uiMessage);
+      RemoteLogger.info(
+        `chat timeline decide type=${item.type} id=${item.id} role=${uiMessage.role} ` +
+        `render=${render ? 1 : 0} text=${uiMessage.text ? uiMessage.text.length : -1} ` +
+        `thinking=${uiMessage.thinking ? uiMessage.thinking.length : 0} ` +
+        `tools=${uiMessage.tools ? uiMessage.tools.length : 0} ` +
+        `items=${uiMessage.items ? uiMessage.items.length : 0}`
+      );
+      return render;
+    } catch (err) {
+      RemoteLogger.error(`chat timeline decide failed type=${item.type} id=${item.id} err=${err}`);
+      return false;
+    }
   }
 
-  private hasRenderableItems(items: ConversationUiMessageItem[]): boolean {
-    return items.some((entry: ConversationUiMessageItem) => {
-      if ((entry.content || '').trim().length > 0 || !!entry.tool) {
-        return true;
-      }
-      return !!entry.subItems && this.hasRenderableItems(entry.subItems);
+  private logTimelineProjection(reason: string): void {
+    const parts: string[] = [];
+    this.timelineItems.forEach((item: ChatTimelineItem) => {
+      const message = item.message;
+      parts.push(
+        `${item.type}:${item.id}:role=${message ? message.role : 'none'}:` +
+        `text=${message && message.text ? message.text.length : -1}:` +
+        `thinking=${message && message.thinking ? message.thinking.length : 0}:` +
+        `tools=${message && message.tools ? message.tools.length : 0}:` +
+        `items=${message && message.items ? message.items.length : 0}`
+      );
     });
-  }
-
-  private visibleMessageText(item: ConversationUiMessage): string {
-    const text = item.text.trim();
-    if (text === '(空消息)' || text === '(empty message)') {
-      return '';
-    }
-    return text;
+    const summary = parts.join(' | ');
+    RemoteLogger.info(
+      `chat timeline project reason=${reason} revision=${this.timelineRevision} ` +
+      `count=${this.timelineItems.length} ${summary.length > 600 ? summary.substring(0, 600) : summary}`
+    );
   }
 
   private emptyChatIcon(): string {
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/CompactMenuButton.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/CompactMenuButton.ets
index ab6f189da4..b1ddaecdc1 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/CompactMenuButton.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/CompactMenuButton.ets
@@ -1,5 +1,6 @@
 import { RemoteI18n } from '../../i18n/RemoteI18n';
-import { CARD, INK } from './Theme';
+import { TemplateIcon } from './TemplateIcon';
+import { CARD } from './Theme';
 
 @ComponentV2
 export struct CompactMenuButton {
@@ -8,12 +9,11 @@ export struct CompactMenuButton {
 
   build() {
     Stack({ alignContent: Alignment.Center }) {
-      Image($r('app.media.gpt_home_menu_glyph'))
-        .width(22)
-        .height(14)
-        .objectFit(ImageFit.Contain)
-        .renderMode(ImageRenderMode.Template)
-        .foregroundColor(INK)
+      TemplateIcon({
+        src: $r('app.media.gpt_home_menu_glyph'),
+        iconWidth: 22,
+        iconHeight: 14
+      })
     }
     .width(this.controlSize)
     .height(this.controlSize)
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ComposerBar.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ComposerBar.ets
index 2c0aceb715..39220d68d9 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ComposerBar.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ComposerBar.ets
@@ -1,12 +1,11 @@
 import { RemoteI18n } from '../../i18n/RemoteI18n';
-import { ChatComposerPolicy } from '../../services/ChatComposerPolicy';
-import { ChatComposerCapabilities, REMOTE_CHAT_COMPOSER_CAPABILITIES } from './ChatComposerCapabilities';
-import { ChatSurface } from './ChatSurface';
+import { ChatComposerPolicy, ComposerPrimaryAction } from '../../services/ChatComposerPolicy';
+import { ChatComposerCapabilities, REMOTE_CHAT_COMPOSER_CAPABILITIES } from '../state/ChatComposerCapabilities';
 import {
   ConversationUiModel,
   ConversationUiModelCatalog,
   ConversationUiSelectedImage
-} from './ConversationUiModels';
+} from '../state/ConversationUiModels';
 import { ConversationModelPresentationPolicy } from '../policy/ConversationModelPresentationPolicy';
 import { CARD, FLOATING_PANEL_BG, GREEN, INK, LINE, MUTED, RED, SOFT } from './Theme';
 
@@ -19,6 +18,13 @@ export enum ComposerPresentation {
 const COMPOSER_ACTION_SIZE: number = 40;
 const COMPOSER_INPUT_HEIGHT: number = 42;
 const COMPOSER_EXPANDED_INPUT_HEIGHT: number = 74;
+const COMPOSER_COLLAPSED_HEIGHT: number = 52;
+const COMPOSER_EXPANDED_HEIGHT: number = 126;
+const COMPOSER_IMAGE_CARD_SIZE: number = 64;
+const COMPOSER_IMAGE_STRIP_TOP_GAP: number = 6;
+/** Strip height plus its top gap and the parent Column's 2vp row spacing. */
+const COMPOSER_IMAGE_STRIP_BLOCK: number =
+  COMPOSER_IMAGE_CARD_SIZE + COMPOSER_IMAGE_STRIP_TOP_GAP + 2;
 
 @ComponentV2
 export struct ComposerBar {
@@ -28,7 +34,6 @@ export struct ComposerBar {
   @Param chatInput: string = '';
   @Local inputText: string = '';
   @Local inputFocused: boolean = false;
-  @Param showQuickActions: boolean = false;
   @Param selectedImages: ConversationUiSelectedImage[] = [];
   @Param isBusy: boolean = false;
   @Param canStop: boolean = false;
@@ -42,7 +47,6 @@ export struct ComposerBar {
   @Param selectedModelId: string = '';
   @Local showModelSelectorSheet: boolean = false;
   @Local showModelSelectorPopover: boolean = false;
-  @Event onToggleQuickActions: () => void = () => {};
   @Event onPickImages: () => void = () => {};
   @Event onRemoveImage: (imageId: string) => void = (_imageId: string) => {};
   @Event onSend: () => void = () => {};
@@ -68,10 +72,7 @@ export struct ComposerBar {
   }
 
   build() {
-    Column({ space: 8 }) {
-      if (this.selectedImages.length > 0) {
-        this.SelectedImageStrip()
-      }
+    Column() {
       this.AdaptiveComposer()
     }
     .width('100%')
@@ -90,6 +91,9 @@ export struct ComposerBar {
   @Builder
   AdaptiveComposer() {
     Column({ space: 2 }) {
+      if (this.selectedImages.length > 0) {
+        this.SelectedImageStrip()
+      }
       Row({ space: this.isComposerExpanded() ? 0 : 5 }) {
         if (this.shouldShowAddButton()) {
           Row() {
@@ -135,7 +139,7 @@ export struct ComposerBar {
       }
     }
     .width('100%')
-    .height(this.isComposerExpanded() ? 126 : 52)
+    .height(this.composerHeight())
     .padding({
       left: 8,
       right: 8,
@@ -143,8 +147,7 @@ export struct ComposerBar {
       bottom: this.isComposerExpanded() ? 2 : 0
     })
     .backgroundColor(CARD)
-    .borderRadius(this.isComposerExpanded() ? 18 :
-      (this.presentation === ComposerPresentation.Floating ? 18 : 26))
+    .borderRadius(this.composerRadius())
     .shadow({
       radius: this.presentation === ComposerPresentation.Floating ? 18 : 10,
       color: this.presentation === ComposerPresentation.Floating ? '#18000000' : '#0D000000',
@@ -298,14 +301,13 @@ export struct ComposerBar {
     }
     .width(COMPOSER_ACTION_SIZE)
     .height(COMPOSER_ACTION_SIZE)
+    .accessibilityText(RemoteI18n.t('chat.addImage'))
     .onClick(() => {
       if (this.isVoiceListening) {
         return;
       }
-      if (this.capabilities.supportsAttachments) {
-        this.onToggleQuickActions();
-        return;
-      }
+      // Images are the only thing a message can carry, so a menu in front of the
+      // picker would be a menu of one. Straight to the album, same as local chat.
       this.onPickImages();
     })
   }
@@ -362,26 +364,21 @@ export struct ComposerBar {
   PrimaryActionButton() {
     Button() {
       Stack({ alignContent: Alignment.Center }) {
-        if (this.isVoiceListening || this.canStop) {
+        if (this.primaryAction() === ComposerPrimaryAction.Stop) {
           Text('')
             .width(13)
             .height(13)
             .backgroundColor(CARD)
             .borderRadius(3)
-        } else if (this.hasComposedContent()) {
-          SymbolGlyph($r('sys.symbol.arrow_up'))
-            .fontSize(23)
-            .fontWeight(FontWeight.Medium)
-            .fontColor([INK])
-            .opacity(this.canSend() ? 1 : 0.38)
-        } else if (this.capabilities.showVoiceInput) {
+        } else if (this.primaryAction() === ComposerPrimaryAction.Voice ||
+          this.primaryAction() === ComposerPrimaryAction.VoiceBlocked) {
           this.MicrophoneGlyph()
         } else {
           SymbolGlyph($r('sys.symbol.arrow_up'))
             .fontSize(23)
             .fontWeight(FontWeight.Medium)
             .fontColor([INK])
-            .opacity(0.38)
+            .opacity(this.primaryAction() === ComposerPrimaryAction.Send ? 1 : 0.38)
         }
       }
       .width(40)
@@ -393,20 +390,25 @@ export struct ComposerBar {
     .type(ButtonType.Circle)
     .backgroundColor(this.actionBackgroundColor())
     .borderRadius(20)
+    .accessibilityText(RemoteI18n.t(ChatComposerPolicy.primaryActionAccessibilityKey(
+      this.primaryAction(), this.isVoiceListening)))
+    // Driven off the same decision that drew the glyph, so the button can never
+    // do something other than what it is showing.
     .onClick(() => {
-      if (this.isVoiceListening) {
-        this.onVoiceInput();
-        return;
-      }
-      if (this.canStop) {
-        this.onStop();
+      const action = this.primaryAction();
+      if (action === ComposerPrimaryAction.Stop) {
+        if (this.isVoiceListening) {
+          this.onVoiceInput();
+        } else if (this.canStop) {
+          this.onStop();
+        }
         return;
       }
-      if (this.canSend()) {
+      if (action === ComposerPrimaryAction.Send) {
         this.onSend();
         return;
       }
-      if (this.canUseVoice()) {
+      if (action === ComposerPrimaryAction.Voice) {
         this.onVoiceInput();
       }
     })
@@ -466,65 +468,92 @@ export struct ComposerBar {
           this.SelectedImageCard(image)
         }, (image: ConversationUiSelectedImage) => image.id)
       }
-      .padding({ right: 4 })
+      .padding({ left: 4, right: 4 })
     }
     .scrollable(ScrollDirection.Horizontal)
     .scrollBar(BarState.Off)
+    // Scroll centres content that is narrower than the viewport, which parks a
+    // lone thumbnail in the middle of the composer instead of at its left edge.
+    .align(Alignment.Start)
     .width('100%')
+    .height(COMPOSER_IMAGE_CARD_SIZE)
+    .margin({ top: COMPOSER_IMAGE_STRIP_TOP_GAP })
   }
 
   @Builder
   SelectedImageCard(image: ConversationUiSelectedImage) {
     Stack({ alignContent: Alignment.TopEnd }) {
       Image(image.data_url)
-        .width(64)
-        .height(64)
+        .width(COMPOSER_IMAGE_CARD_SIZE)
+        .height(COMPOSER_IMAGE_CARD_SIZE)
         .objectFit(ImageFit.Cover)
         .borderRadius(14)
       Text('×')
-        .width(22)
-        .height(22)
-        .fontSize(14)
+        .width(32)
+        .height(32)
+        .fontSize(16)
         .fontColor(CARD)
         .textAlign(TextAlign.Center)
         .backgroundColor('#AA222222')
-        .borderRadius(11)
-        .margin({ top: 4, right: 4 })
+        .borderRadius(16)
+        .margin({ top: 0, right: 0 })
+        .accessibilityText(RemoteI18n.t('chat.removeImage'))
         .onClick(() => {
           this.onRemoveImage(image.id);
         })
     }
-    .width(64)
-    .height(64)
+    .width(COMPOSER_IMAGE_CARD_SIZE)
+    .height(COMPOSER_IMAGE_CARD_SIZE)
+  }
+
+  private canUseVoice(): boolean {
+    return this.capabilities.showVoiceInput &&
+      ChatComposerPolicy.canUseVoice(this.inputText, this.selectedImages.length, this.isBusy);
   }
 
-  private canSend(): boolean {
-    return ChatComposerPolicy.canSend(
+  // Dictation runs inside this app rather than in a system dialog, so listening
+  // outranks the draft here in a way a running turn does not.
+  private primaryAction(): ComposerPrimaryAction {
+    return ChatComposerPolicy.primaryAction(
       this.inputText,
       this.selectedImages.length,
       this.isBusy,
+      this.isVoiceListening,
+      this.canStop,
+      this.capabilities.supportsMidRunSend,
       this.capabilities.requiresRemoteConnection,
-      this.connectionState
+      this.connectionState,
+      this.capabilities.showVoiceInput
     );
   }
 
-  private canUseVoice(): boolean {
-    return this.capabilities.showVoiceInput &&
-      ChatComposerPolicy.canUseVoice(this.inputText, this.selectedImages.length, this.isBusy);
+  private shouldShowAddButton(): boolean {
+    return ChatComposerPolicy.shouldShowAddButton(
+      this.capabilities.showAddButton,
+      this.capabilities.supportsAttachments
+    );
   }
 
-  private hasComposedContent(): boolean {
-    return this.inputText.trim().length > 0 || this.selectedImages.length > 0;
+  // Attachments live inside the card, so the card has to grow to hold them.
+  private composerHeight(): number {
+    const base = this.isComposerExpanded() ? COMPOSER_EXPANDED_HEIGHT : COMPOSER_COLLAPSED_HEIGHT;
+    return this.selectedImages.length > 0 ? base + COMPOSER_IMAGE_STRIP_BLOCK : base;
   }
 
-  private shouldShowAddButton(): boolean {
-    return this.capabilities.showAddButton &&
-      (this.capabilities.supportsAttachments || this.capabilities.surface === ChatSurface.General);
+  // The pill radius only reads as a pill while the card is one row tall.
+  private composerRadius(): number {
+    if (this.isComposerExpanded() || this.selectedImages.length > 0) {
+      return 18;
+    }
+    return this.presentation === ComposerPresentation.Floating ? 18 : 26;
   }
 
   private isComposerExpanded(): boolean {
-    return this.inputFocused || this.showQuickActions || this.showModelSelectorSheet ||
-      this.showModelSelectorPopover || this.inputText.indexOf('\n') >= 0;
+    return ChatComposerPolicy.isExpanded(
+      this.inputText,
+      this.inputFocused,
+      this.isModelSelectorExpanded()
+    );
   }
 
   private isModelSelectorExpanded(): boolean {
@@ -532,8 +561,7 @@ export struct ComposerBar {
   }
 
   private shouldShowModelControl(): boolean {
-    return (this.capabilities.surface === ChatSurface.Remote || this.capabilities.surface === ChatSurface.General) &&
-      this.enabledModels().length > 0;
+    return this.enabledModels().length > 0;
   }
 
   private enabledModels(): ConversationUiModel[] {
@@ -590,13 +618,13 @@ export struct ComposerBar {
       RemoteI18n.t('chat.inputPlaceholder');
   }
 
+  // Follows the offered action rather than the raw flags: while a turn runs and
+  // the user has typed something, the button is a send arrow, and a send arrow
+  // on a stop-red circle reads as "this will cancel".
   private actionBackgroundColor(): ResourceColor {
-    if (this.canStop) {
-      return RED;
-    }
-    if (this.isVoiceListening) {
-      return GREEN;
+    if (this.primaryAction() !== ComposerPrimaryAction.Stop) {
+      return '#00000000';
     }
-    return '#00000000';
+    return this.isVoiceListening ? GREEN : RED;
   }
 }
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConnectAccountDevicePage.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConnectAccountDevicePage.ets
index e1e87a723d..6f04ef6504 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConnectAccountDevicePage.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConnectAccountDevicePage.ets
@@ -1,6 +1,7 @@
 import { RemoteI18n } from '../../i18n/RemoteI18n';
 import { CloudAccountDevice } from '../../services/CloudAccountClient';
 import { ACCENT, CARD, GREEN, INK, LINE, MUTED, PAGE_BG, RED, SOFT } from './Theme';
+import { AccountDeviceSelectionPolicy } from '../policy/AccountDeviceSelectionPolicy';
 
 @ComponentV2
 export struct ConnectAccountDevicePage {
@@ -17,7 +18,6 @@ export struct ConnectAccountDevicePage {
   @Local accountDevicesBusy: boolean = false;
   @Local accountDevicesError: string = '';
   @Local switchingDeviceId: string = '';
-  @Local otherConnectionMethodsExpanded: boolean = false;
 
   aboutToAppear(): void {
     this.refreshAccountDevices();
@@ -50,7 +50,7 @@ export struct ConnectAccountDevicePage {
           Text(RemoteI18n.t('connect.accountDevicesBody'))
             .fontSize(14).lineHeight(21).fontColor(MUTED).width('100%')
           this.AccountDeviceList()
-          this.OtherConnectionMethods()
+          this.ScanPairCodeAction()
         }
         .width('100%')
         .constraintSize({ minHeight: '100%' })
@@ -110,36 +110,18 @@ export struct ConnectAccountDevicePage {
   }
 
   @Builder
-  private OtherConnectionMethods() {
-    Column() {
-      Row({ space: 12 }) {
-        Text(RemoteI18n.t('connect.otherConnectionMethods'))
-          .fontSize(16).fontWeight(FontWeight.Medium).fontColor(INK)
-        Blank()
-        SymbolGlyph(this.otherConnectionMethodsExpanded ?
-          $r('sys.symbol.chevron_up') : $r('sys.symbol.chevron_down'))
-          .fontSize(13).fontColor([MUTED])
-      }
-      .width('100%').height(58).padding({ left: 16, right: 16 })
-      .onClick(() => {
-        this.otherConnectionMethodsExpanded = !this.otherConnectionMethodsExpanded;
-      })
-
-      if (this.otherConnectionMethodsExpanded) {
-        Divider().color(LINE).margin({ left: 16, right: 16 })
-        Row({ space: 12 }) {
-          SymbolGlyph($r('sys.symbol.link'))
-            .fontSize(20).fontColor([MUTED]).width(22).height(22).opacity(0.66)
-          Text(RemoteI18n.t('connect.scanPairCodeAction'))
-            .fontSize(16).fontWeight(FontWeight.Medium).fontColor(INK).layoutWeight(1)
-          SymbolGlyph($r('sys.symbol.chevron_right'))
-            .fontSize(13).fontColor([MUTED]).width(16).height(16).opacity(0.44)
-        }
-        .width('100%').height(58).padding({ left: 16, right: 16 })
-        .onClick(() => this.onOpenScanner())
-      }
+  private ScanPairCodeAction() {
+    Row({ space: 12 }) {
+      SymbolGlyph($r('sys.symbol.link'))
+        .fontSize(20).fontColor([MUTED]).width(22).height(22).opacity(0.66)
+      Text(RemoteI18n.t('connect.scanPairCodeAction'))
+        .fontSize(16).fontWeight(FontWeight.Medium).fontColor(INK).layoutWeight(1)
+      SymbolGlyph($r('sys.symbol.chevron_right'))
+        .fontSize(13).fontColor([MUTED]).width(16).height(16).opacity(0.44)
     }
-    .width('100%').backgroundColor(CARD).borderRadius(8).border({ width: 1, color: LINE })
+    .width('100%').height(58).padding({ left: 16, right: 16 })
+    .backgroundColor(CARD).borderRadius(8).border({ width: 1, color: LINE })
+    .onClick(() => this.onOpenScanner())
   }
 
   @Builder
@@ -170,7 +152,15 @@ export struct ConnectAccountDevicePage {
       }
       .layoutWeight(1)
       .alignItems(HorizontalAlign.Start)
-      if (device.online) {
+      if (this.canSelectAccountDevice(device) && AccountDeviceSelectionPolicy.shouldShowConnectAction(
+        device.online, device.deviceId, this.deviceId, this.controlTargetDeviceId, this.connectionState
+      )) {
+        Text(this.switchingDeviceId === device.deviceId ?
+          RemoteI18n.t('remote.settings.deviceConnecting') : RemoteI18n.t('connect.connect'))
+          .fontSize(14).fontColor(INK)
+          .padding({ left: 10, right: 10, top: 6, bottom: 6 })
+          .backgroundColor(SOFT).borderRadius(14)
+      } else if (device.online) {
         SymbolGlyph($r('sys.symbol.chevron_right'))
           .fontSize(13).fontColor([MUTED]).width(16).height(16).opacity(0.44)
       }
@@ -204,9 +194,6 @@ export struct ConnectAccountDevicePage {
         RemoteI18n.t('remote.settings.deviceLoadFailed');
     } finally {
       this.accountDevicesBusy = false;
-      if (!this.hasOnlineDesktopDevice()) {
-        this.otherConnectionMethodsExpanded = true;
-      }
     }
   }
 
@@ -216,15 +203,9 @@ export struct ConnectAccountDevicePage {
   }
 
   private canSelectAccountDevice(device: CloudAccountDevice): boolean {
-    return device.online && device.deviceId !== this.deviceId && this.switchingDeviceId.length === 0;
-  }
-
-  private hasOnlineDesktopDevice(): boolean {
-    const devices = this.desktopDevices();
-    for (let index = 0; index < devices.length; index += 1) {
-      if (devices[index].online) return true;
-    }
-    return false;
+    return AccountDeviceSelectionPolicy.canSelectOnline(
+      device.online, device.deviceId, this.deviceId, this.switchingDeviceId
+    );
   }
 
   private accountDeviceStatus(device: CloudAccountDevice): string {
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConnectView.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConnectView.ets
index b01a2402db..bcfe1a13ef 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConnectView.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConnectView.ets
@@ -4,7 +4,14 @@ import { RemoteI18n } from '../../i18n/RemoteI18n';
 import { CloudAccountDevice } from '../../services/CloudAccountClient';
 import { ConnectAccountDevicePage } from './ConnectAccountDevicePage';
 import { ConnectManualPairingOverlay } from './ConnectManualPairingOverlay';
-import { ACCENT, CARD, CONNECT_HERO_ACCENT, CONNECT_HERO_BG, CONNECT_HERO_SECONDARY,
+import { CONNECT_INTENT_AUTO, CONNECT_INTENT_SCAN } from '../state/AppShellState';
+import {
+  ConnectSheetLandingPolicy,
+  ConnectSheetStatusPolicy,
+  ConnectSheetStep
+} from '../policy/ConnectSheetLandingPolicy';
+import { DetectedUrlAction } from '../../services/ConnectScanDecisionPolicy';
+import { CARD, CONNECT_HERO_ACCENT, CONNECT_HERO_BG, CONNECT_HERO_SECONDARY,
   CONNECT_HERO_SURFACE, CONNECT_SCAN_ACCENT, GREEN, INK, LINE, MUTED, PRIMARY_ACTION, PRIMARY_ACTION_TEXT, RED, SOFT,
   SUBTLE } from './Theme';
 const CAMERA_PERMISSION: Permissions = 'ohos.permission.CAMERA';
@@ -28,12 +35,12 @@ export struct ConnectView {
   @Param controlTargetDeviceId: string = '';
   @Param requiresAccountAuth: boolean = false;
   @Param accountUsername: string = '';
-  @Param startWithScanner: boolean = true;
+  @Param openIntent: string = CONNECT_INTENT_AUTO;
   @Event onBack: () => void = () => {};
   @Event onConnect: (password?: string) => void = (_password?: string) => {};
   @Event onRemoteUrlChange: (value: string) => void = (_value: string) => {};
   @Event onUserIdChange: (value: string) => void = (_value: string) => {};
-  @Event onRemoteUrlDetected: (value: string) => boolean = (_value: string) => false;
+  @Event onRemoteUrlDetected: (value: string) => string = (_value: string) => DetectedUrlAction.INVALID;
   @Event onRemoteUrlInputVisibleChange: (visible: boolean) => void = (_visible: boolean) => {};
   @Event cloudListDevices: () => Promise<CloudAccountDevice[]> = async (): Promise<CloudAccountDevice[]> => [];
   @Event cloudSelectDevice: (device: CloudAccountDevice) => Promise<void> =
@@ -45,12 +52,16 @@ export struct ConnectView {
   @Local cameraPermissionReady: boolean = false;
   @Local requestingCameraPermission: boolean = false;
 
+  /**
+   * SCAN intent always opens the camera. Every other automatic open lands on
+   * the account device list when signed in, and on the pair-code explainer
+   * when not — never on the camera by default.
+   */
   aboutToAppear(): void {
-    if (this.isAccountAuthenticated()) {
-      this.pairingStep = 'account';
-    } else if (this.startWithScanner && this.remoteUrl.trim().length === 0) {
-      this.pairingStep = 'scan';
-    }
+    this.pairingStep = ConnectSheetLandingPolicy.initialStep(
+      this.openIntent,
+      this.isAccountAuthenticated()
+    );
   }
 
   aboutToDisappear(): void {
@@ -261,9 +272,10 @@ export struct ConnectView {
       .borderRadius(24)
       .position({ x: 28, y: 18 })
       .onClick(() => {
-        if (this.currentStep() === 'scan' && this.remoteUrl.trim().length === 0 && !this.showManualPairing) {
+        if (this.openIntent !== CONNECT_INTENT_SCAN &&
+          this.currentStep() === ConnectSheetStep.Scan && this.remoteUrl.trim().length === 0 && !this.showManualPairing) {
           this.stopInlineScan();
-          this.pairingStep = this.isAccountAuthenticated() ? 'account' : 'intro';
+          this.pairingStep = this.isAccountAuthenticated() ? ConnectSheetStep.Account : ConnectSheetStep.Intro;
           return;
         }
         this.stopInlineScan();
@@ -464,6 +476,10 @@ export struct ConnectView {
     }
     if (this.remoteUrl.trim().length > 0) {
       if (this.requiresAccountAuth && this.accountPassword.length === 0) {
+        if (this.isAccountAuthenticated()) {
+          this.pairingStep = ConnectSheetStep.Account;
+          return;
+        }
         this.showManualPairing = true;
         this.onRemoteUrlInputVisibleChange(true);
         return;
@@ -475,7 +491,7 @@ export struct ConnectView {
     this.onRemoteUrlInputVisibleChange(true);
     this.stopInlineScan();
     this.showManualPairing = true;
-    this.pairingStep = 'scan';
+    this.pairingStep = ConnectSheetStep.Scan;
   }
 
   private canConnect(): boolean {
@@ -495,19 +511,7 @@ export struct ConnectView {
   }
 
   private currentStep(): string {
-    if (this.pairingStep === 'account' && this.isAccountAuthenticated()) {
-      return 'account';
-    }
-    if (this.pairingStep === 'scan' ||
-      this.remoteUrl.trim().length > 0 ||
-      this.isBusy ||
-      this.isConnected ||
-      this.connectionState === 'parsing' ||
-      this.connectionState === 'pairing' ||
-      this.connectionState === 'reconnecting') {
-      return 'scan';
-    }
-    return 'intro';
+    return ConnectSheetLandingPolicy.visibleStep(this.pairingStep, this.isAccountAuthenticated());
   }
 
   private isAccountAuthenticated(): boolean {
@@ -539,7 +543,7 @@ export struct ConnectView {
   private async startInlineScan(): Promise<void> {
     if (this.scannerStarted ||
       this.scanCompleted ||
-      this.currentStep() !== 'scan' ||
+      this.currentStep() !== ConnectSheetStep.Scan ||
       this.showManualPairing) {
       return;
     }
@@ -589,15 +593,26 @@ export struct ConnectView {
         }
         this.scanCompleted = true;
         this.stopInlineScan();
-        const shouldPrompt = this.onRemoteUrlDetected(text);
-        if (shouldPrompt) {
+        const action = this.onRemoteUrlDetected(text);
+        if (action === DetectedUrlAction.PROMPT_ACCOUNT_PASSWORD) {
           this.showManualPairing = true;
           this.onRemoteUrlInputVisibleChange(true);
-          this.pairingStep = 'scan';
+          this.pairingStep = ConnectSheetStep.Scan;
           return;
         }
-        this.ensureUserId();
-        this.onConnect();
+        if (action === DetectedUrlAction.SHOW_CLOUD_DEVICES ||
+          action === DetectedUrlAction.USE_CLOUD_DEVICE) {
+          this.pairingStep = ConnectSheetStep.Account;
+          return;
+        }
+        if (action === DetectedUrlAction.PAIR_NOW) {
+          this.ensureUserId();
+          this.onConnect();
+          return;
+        }
+        this.inlineScanError = this.statusText || RemoteI18n.t('connect.hintInvalidLink');
+        this.scanCompleted = false;
+        this.resumeInlineScan();
       });
     } catch (_err) {
       this.scannerStarted = false;
@@ -617,7 +632,7 @@ export struct ConnectView {
   }
 
   private resumeInlineScan(): void {
-    if (this.remoteUrl.trim().length > 0 || this.pairingStep !== 'scan') {
+    if (this.remoteUrl.trim().length > 0 || this.pairingStep !== ConnectSheetStep.Scan) {
       return;
     }
     this.scanCompleted = false;
@@ -656,39 +671,23 @@ export struct ConnectView {
     this.scanStartRetryCount = 0;
     this.inlineScanError = '';
     this.cameraPermissionReady = false;
-    this.pairingStep = 'scan';
+    this.pairingStep = ConnectSheetStep.Scan;
   }
 
   private isConnectError(): boolean {
-    if (this.connectionState === 'failed') {
-      return true;
-    }
-    if (this.isBusy || this.isConnected) {
-      return false;
-    }
-    const text = this.statusText.toLowerCase();
-    return text.indexOf('http') >= 0 ||
-      text.indexOf('error') >= 0 ||
-      text.indexOf('failed') >= 0 ||
-      text.indexOf(RemoteI18n.t('common.failed')) >= 0 ||
-      this.statusText === RemoteI18n.t('errors.remoteUrlMissingParams') ||
-      this.statusText === RemoteI18n.t('errors.remoteUrlRequired') ||
-      text.indexOf('rejected') >= 0;
+    return ConnectSheetStatusPolicy.isConnectError(
+      this.connectionState,
+      this.isBusy,
+      this.isConnected,
+      this.statusText,
+      RemoteI18n.t('common.failed'),
+      RemoteI18n.t('errors.remoteUrlMissingParams'),
+      RemoteI18n.t('errors.remoteUrlRequired')
+    );
   }
 
   private failureHint(): string {
-    if (this.connectionFailureKind === 'expired_room') {
-      return RemoteI18n.t('connect.hintExpiredRoom');
-    }
-    if (this.connectionFailureKind === 'network') {
-      return RemoteI18n.t('connect.hintNetwork');
-    }
-    if (this.connectionFailureKind === 'protected_user') {
-      return RemoteI18n.t('connect.hintProtectedUser');
-    }
-    if (this.connectionFailureKind === 'invalid_link') {
-      return RemoteI18n.t('connect.hintInvalidLink');
-    }
-    return '';
+    const key = ConnectSheetStatusPolicy.failureHintKey(this.connectionFailureKind);
+    return key.length > 0 ? RemoteI18n.t(key) : '';
   }
 }
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/GeneralChatHeader.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConversationHeader.ets
similarity index 56%
rename from src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/GeneralChatHeader.ets
rename to src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConversationHeader.ets
index 0382f2db61..a2f5606373 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/GeneralChatHeader.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConversationHeader.ets
@@ -1,13 +1,15 @@
 import { RemoteI18n } from '../../i18n/RemoteI18n';
-import { CARD, INK, LINE, MUTED, PAGE_BG } from './Theme';
+import { ACCENT, CARD, INK, LINE, MUTED, PAGE_BG, PRIMARY_ACTION_TEXT, SOFT } from './Theme';
 import { CompactMenuButton } from './CompactMenuButton';
+import { TemplateIcon } from './TemplateIcon';
 import { SidebarToggleButton } from './SidebarToggleButton';
 
 @ComponentV2
-export struct GeneralChatHeader {
+export struct ConversationHeader {
   @Param title: string = '';
-  /** Secondary context line. Empty keeps the single-line header. */
   @Param subtitle: string = '';
+  @Param titleFallback: string = '';
+  @Param allowRename: boolean = false;
   @Param showActions: boolean = false;
   @Param showSidebarButton: boolean = true;
   @Param showBackButton: boolean = false;
@@ -19,8 +21,23 @@ export struct GeneralChatHeader {
   @Event onBack: () => void = () => {};
   @Event onOpenActions: () => void = () => {};
   @Event onActionsMenuStateChange: (visible: boolean) => void = (_visible: boolean) => {};
+  @Event onRenameSession: (title: string) => void = (_title: string) => {};
+  @Local showTitleEditor: boolean = false;
+  @Local renameTitle: string = '';
 
   build() {
+    Column() {
+      this.HeaderRow()
+      if (this.showTitleEditor) {
+        this.TitleEditor()
+      }
+    }
+    .width('100%')
+    .backgroundColor(PAGE_BG)
+  }
+
+  @Builder
+  private HeaderRow() {
     Row({ space: 8 }) {
       this.LeadingControl()
       this.TitleBlock()
@@ -33,17 +50,23 @@ export struct GeneralChatHeader {
     .backgroundColor(PAGE_BG)
   }
 
-  /** Mirrors the conversation header: title above a muted context line. */
   @Builder
   private TitleBlock() {
     Column({ space: 3 }) {
-      Text(this.title || 'BitFun')
+      Text(this.resolvedTitle())
         .fontSize(this.hasSubtitle() ? 18 : 17)
         .fontWeight(FontWeight.Medium)
         .fontColor(INK)
         .maxLines(1)
         .textOverflow({ overflow: TextOverflow.Ellipsis })
         .textAlign(TextAlign.Center)
+        .onClick(() => {
+          if (!this.allowRename) {
+            return;
+          }
+          this.renameTitle = this.title;
+          this.showTitleEditor = true;
+        })
       if (this.hasSubtitle()) {
         Text(this.subtitle)
           .fontSize(14)
@@ -57,26 +80,21 @@ export struct GeneralChatHeader {
     .alignItems(HorizontalAlign.Center)
   }
 
-  private hasSubtitle(): boolean {
-    return this.subtitle.length > 0;
-  }
-
   @Builder
   private LeadingControl() {
     if (this.showSidebarRestoreButton) {
       SidebarToggleButton({
         restore: true,
-        controlSize: 48,
+        controlSize: 44,
         onToggle: this.onRestoreSidebar
       })
     } else if (this.showBackButton) {
       Stack({ alignContent: Alignment.Center }) {
-        Image($r('app.media.remote_ref_back'))
-          .width(15)
-          .height(23)
-          .objectFit(ImageFit.Contain)
-          .renderMode(ImageRenderMode.Template)
-          .foregroundColor(INK)
+        TemplateIcon({
+          src: $r('app.media.remote_ref_back'),
+          iconWidth: 15,
+          iconHeight: 23
+        })
       }
       .width(44)
       .height(44)
@@ -90,6 +108,7 @@ export struct GeneralChatHeader {
       })
     } else if (this.showSidebarButton) {
       CompactMenuButton({
+        controlSize: 44,
         onOpen: () => {
           this.onOpenSidebar();
         }
@@ -103,12 +122,11 @@ export struct GeneralChatHeader {
   private TrailingControl() {
     if (this.showActions) {
       Stack({ alignContent: Alignment.Center }) {
-        Image($r('app.media.remote_ref_more'))
-          .width(23)
-          .height(7)
-          .objectFit(ImageFit.Contain)
-          .renderMode(ImageRenderMode.Template)
-          .foregroundColor(INK)
+        TemplateIcon({
+          src: $r('app.media.remote_ref_more'),
+          iconWidth: 23,
+          iconHeight: 7
+        })
       }
       .width(44)
       .height(44)
@@ -132,6 +150,7 @@ export struct GeneralChatHeader {
         }
       })
       .onClick(() => {
+        this.showTitleEditor = false;
         this.onOpenActions();
       })
     } else {
@@ -139,6 +158,63 @@ export struct GeneralChatHeader {
     }
   }
 
+  @Builder
+  private TitleEditor() {
+    Row({ space: 8 }) {
+      TextInput({ placeholder: RemoteI18n.t('chat.sessionTitle'), text: this.renameTitle })
+        .layoutWeight(1)
+        .height(42)
+        .fontSize(14)
+        .backgroundColor(CARD)
+        .borderRadius(14)
+        .padding({ left: 12, right: 12 })
+        .border({ width: 1, color: LINE })
+        .defaultFocus(false)
+        .onChange((value: string) => {
+          this.renameTitle = value;
+        })
+      Text(RemoteI18n.t('common.save'))
+        .width(52)
+        .height(42)
+        .fontSize(13)
+        .fontColor(PRIMARY_ACTION_TEXT)
+        .textAlign(TextAlign.Center)
+        .backgroundColor(this.renameTitle.trim().length > 0 ? ACCENT : SOFT)
+        .borderRadius(14)
+        .onClick(() => {
+          if (this.renameTitle.trim().length > 0) {
+            this.onRenameSession(this.renameTitle.trim());
+            this.showTitleEditor = false;
+          }
+        })
+      Text(RemoteI18n.t('common.cancel'))
+        .width(52)
+        .height(42)
+        .fontSize(13)
+        .fontColor(INK)
+        .textAlign(TextAlign.Center)
+        .backgroundColor(SOFT)
+        .borderRadius(14)
+        .onClick(() => {
+          this.showTitleEditor = false;
+        })
+    }
+    .width('100%')
+    .padding({ left: 16, right: 16, top: 10, bottom: 8 })
+    .backgroundColor(PAGE_BG)
+  }
+
+  private resolvedTitle(): string {
+    if (this.title.length > 0) {
+      return this.title;
+    }
+    return this.titleFallback;
+  }
+
+  private hasSubtitle(): boolean {
+    return this.subtitle.length > 0;
+  }
+
   @Builder
   private EmptyBuilder() {
   }
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConversationRouteSurface.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConversationRouteSurface.ets
index 6a82568798..835c78d0f4 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConversationRouteSurface.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConversationRouteSurface.ets
@@ -10,7 +10,7 @@ import { RemoteCreateSessionState } from '../state/RemoteCreateSessionState';
 import { RemotePageState } from '../state/RemotePageState';
 import { ComposerPresentation } from './ComposerBar';
 import { ConversationViewHost } from './ConversationViewHost';
-import { toConversationUiModelCatalog } from './ConversationUiModels';
+import { toConversationUiModelCatalog } from '../state/ConversationUiModels';
 import { RemoteCreateSessionView } from './RemoteCreateSessionView';
 import {
   RemoteSurfaceHost,
@@ -33,6 +33,7 @@ export struct ConversationRouteSurface {
   @Param showBackButton: boolean = false;
   @Param showSidebarRestoreButton: boolean = false;
   @Param useWidePresentation: boolean = false;
+  @Param hoverOperateMode: boolean = false;
   @Param contentHorizontalOffset: number = 0;
   @Event onRestoreSidebar: () => void = () => {};
 
@@ -54,6 +55,7 @@ export struct ConversationRouteSurface {
           modelCatalog: toConversationUiModelCatalog(this.remotePageState.conversation.modelCatalog),
           selectedModelId: this.remoteCreateState.selectedModelId,
           showSidebarRestoreButton: this.showSidebarRestoreButton,
+          hoverOperateMode: this.hoverOperateMode,
           onRestoreSidebar: this.onRestoreSidebar,
           onBack: this.actions.onRemoteCreate.back,
           onToggleDeviceMenu: this.actions.onRemoteCreate.toggleDevices,
@@ -71,7 +73,8 @@ export struct ConversationRouteSurface {
             this.route,
             this.remotePageState,
             this.generalPageState,
-            this.actions.generalStatus()
+            this.actions.generalStatus(),
+            this.remoteCreateState
           ),
           activeFilePreviewPath: this.route === AppRoute.RemoteChat && this.filePreviewState.visible ?
             this.filePreviewState.target.remotePath : '',
@@ -82,6 +85,7 @@ export struct ConversationRouteSurface {
           showSidebarRestoreButton: this.showSidebarRestoreButton,
           composerPresentation: this.useWidePresentation ? ComposerPresentation.Floating : ComposerPresentation.Compact,
           contentHorizontalOffset: this.contentHorizontalOffset,
+          hoverOperateMode: this.hoverOperateMode,
           onRestoreSidebar: this.onRestoreSidebar,
           onIntent: (intent: ConversationIntent) => this.actions.onConversationIntent(this.route, intent)
         })
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConversationSourceSwitcher.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConversationSourceSwitcher.ets
index 1c66b5a892..562eb4f164 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConversationSourceSwitcher.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConversationSourceSwitcher.ets
@@ -9,8 +9,8 @@ export struct ConversationSourceSwitcher {
 
   build() {
     Row({ space: 2 }) {
-      this.SourceOption(ConversationSource.General, RemoteI18n.t('sidebar.local'))
-      this.SourceOption(ConversationSource.Remote, RemoteI18n.t('sidebar.code'))
+      this.SourceOption(ConversationSource.General, RemoteI18n.t('sidebar.local'), 'conversation-source-local')
+      this.SourceOption(ConversationSource.Remote, RemoteI18n.t('sidebar.code'), 'conversation-source-remote')
     }
     .width('100%')
     .height(40)
@@ -21,8 +21,9 @@ export struct ConversationSourceSwitcher {
   }
 
   @Builder
-  private SourceOption(source: ConversationSource, label: string) {
+  private SourceOption(source: ConversationSource, label: string, optionId: string) {
     Text(label)
+      .id(optionId)
       .layoutWeight(1)
       .height(32)
       .fontSize(13)
@@ -31,6 +32,7 @@ export struct ConversationSourceSwitcher {
       .textAlign(TextAlign.Center)
       .backgroundColor(this.activeSource === source ? CARD : '#00000000')
       .borderRadius(6)
+      .accessibilityText(label)
       .onClick(() => {
         if (this.activeSource !== source) {
           this.onSelectSource(source);
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConversationView.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConversationView.ets
index db3f0fc7f1..6f2951c77f 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConversationView.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConversationView.ets
@@ -2,8 +2,9 @@ import { KeyboardAvoidMode } from '@kit.ArkUI';
 import { RemoteI18n } from '../../i18n/RemoteI18n';
 import { ChatTimelineItem } from '../../services/ChatTimelineProjector';
 import { ConnectionStatusPresenter } from '../../services/ConnectionStatusPresenter';
-import { ChatComposerCapabilities, REMOTE_CHAT_COMPOSER_CAPABILITIES } from './ChatComposerCapabilities';
-import { ChatSurface } from './ChatSurface';
+import { RemoteLogger } from '../../services/RemoteLogger';
+import { ChatComposerCapabilities, REMOTE_CHAT_COMPOSER_CAPABILITIES } from '../state/ChatComposerCapabilities';
+import { ChatSurface } from '../state/ChatSurface';
 import { ChatStatusBar } from './ChatStatusBar';
 import { ChatTimeline } from './ChatTimeline';
 import { ConversationLoadingState } from './ConversationLoadingState';
@@ -13,11 +14,11 @@ import {
   ConversationUiQuestionAnswer,
   ConversationUiSelectedImage,
   ConversationUiSession
-} from './ConversationUiModels';
+} from '../state/ConversationUiModels';
 import { ComposerBar, ComposerPresentation } from './ComposerBar';
-import { GeneralChatHeader } from './GeneralChatHeader';
-import { RemoteChatHeader } from './RemoteChatHeader';
-import { CARD, FLOATING_PANEL_BG, GREEN, INK, LINE, MUTED, PAGE_BG, RED, SOFT } from './Theme';
+import { ConversationHeader } from './ConversationHeader';
+import { ConversationHeaderPolicy, ConversationHeaderPresentation } from '../policy/ConversationHeaderPolicy';
+import { FLOATING_PANEL_BG, GREEN, INK, LINE, MUTED, PAGE_BG, RED, SOFT } from './Theme';
 
 @ComponentV2
 export struct ConversationView {
@@ -40,10 +41,6 @@ export struct ConversationView {
   @Param hasMoreMessages: boolean = false;
   @Param timelineItems: ChatTimelineItem[] = [];
   @Param timelineRevision: number = 0;
-  @Param showSuggestionsWhenEmpty: boolean = false;
-  @Param supportsSearch: boolean = false;
-  @Param supportsImages: boolean = false;
-  @Param supportsFiles: boolean = false;
   @Param modelCatalog: ConversationUiModelCatalog = {
     version: 0,
     models: [],
@@ -62,7 +59,10 @@ export struct ConversationView {
   @Param showBackButton: boolean = true;
   @Param showSidebarRestoreButton: boolean = false;
   @Param composerPresentation: ComposerPresentation = ComposerPresentation.Compact;
+  @Param composerInputId: string = 'conversation-composer-input';
   @Param contentHorizontalOffset: number = 0;
+  @Param hoverOperateMode: boolean = false;
+  @BuilderParam aboveComposer: () => void = this.EmptyBuilder;
   @Event onOpenSidebar: () => void = () => {};
   @Event onRestoreSidebar: () => void = () => {};
   @Event onBack: () => void = () => {};
@@ -90,17 +90,18 @@ export struct ConversationView {
   @Event onSend: () => void = () => {};
   @Event onVoiceInput: () => void = () => {};
   @Event onChatInputChange: (value: string) => void = (_value: string) => {};
-  @Event onToggleQuickActions: () => void = () => {};
-  @Local showQuickActions: boolean = false;
+  @Event onBackgroundTap: () => void = () => {};
   @Local showHeaderActions: boolean = false;
   private previousKeyboardAvoidMode: KeyboardAvoidMode = KeyboardAvoidMode.OFFSET;
 
   aboutToAppear(): void {
+    RemoteLogger.info(`conversation view mounted surface=${this.surface}`);
     this.previousKeyboardAvoidMode = this.getUIContext().getKeyboardAvoidMode();
     this.getUIContext().setKeyboardAvoidMode(KeyboardAvoidMode.RESIZE);
   }
 
   aboutToDisappear(): void {
+    RemoteLogger.info('conversation view disposed');
     this.getUIContext().setKeyboardAvoidMode(this.previousKeyboardAvoidMode);
   }
 
@@ -108,42 +109,13 @@ export struct ConversationView {
     Stack() {
       Column() {
         this.Header()
-        Column() {
-          if (this.shouldShowStatusBar()) {
-            this.ExecutionStatusBar()
-          }
-          if (this.isLoadingConversation) {
-            ConversationLoadingState({
-              maxContentWidth: this.composerPresentation === ComposerPresentation.Floating ? 800 : 0
-            })
-              .layoutWeight(1)
-          } else if (this.shouldShowSuggestions()) {
-            Blank().layoutWeight(1)
-            if (!this.isVoiceListening) {
-              this.PromptArea()
-            }
-          } else if (this.shouldCenterInlineStatus()) {
-            this.CenteredInlineStatus()
-          } else {
-            this.MessageList()
-          }
-          if (this.inlineStatusText.length > 0 && !this.shouldCenterInlineStatus()) {
-            Text(this.inlineStatusText)
-              .fontSize(12).lineHeight(18).fontColor(MUTED).width('100%')
-              .padding({ left: 20, right: 20, bottom: 8 })
-          }
-          this.Composer()
+        if (this.hoverOperateMode) {
+          this.HoverBody()
+        } else {
+          this.StandardBody()
         }
-        .layoutWeight(1)
-        .width('100%')
-        .translate({ x: this.contentHorizontalOffset, y: 0 })
-        .animation({ duration: 220, curve: Curve.EaseInOut })
       }
       .width('100%').height('100%').backgroundColor(PAGE_BG)
-      if (this.showQuickActions && this.composerCapabilities.supportsAttachments) {
-        this.MenuBackdrop(() => { this.showQuickActions = false; })
-        this.QuickActionsMenu()
-      }
     }
     .width('100%')
     .height('100%')
@@ -151,70 +123,103 @@ export struct ConversationView {
   }
 
   @Builder
-  Header() {
-    if (this.surface === ChatSurface.General) {
-      GeneralChatHeader({
-        title: this.activeSession.title,
-        showActions: ConversationViewContract.hasRealTimelineItem(this.timelineItems),
-        showSidebarButton: this.showSidebarButton,
-        showBackButton: this.showBackButton,
-        showSidebarRestoreButton: this.showSidebarRestoreButton,
-        showActionsMenu: this.showHeaderActions,
-        actionsMenu: () => {
-          this.HeaderActionsPopover();
-        },
-        onOpenSidebar: () => {
-          this.onOpenSidebar();
-        },
-        onRestoreSidebar: () => {
-          this.onRestoreSidebar();
-        },
-        onBack: () => {
-          this.onBack();
-        },
-        onOpenActions: () => {
-          this.showQuickActions = false;
-          this.showHeaderActions = !this.showHeaderActions;
-        },
-        onActionsMenuStateChange: (visible: boolean) => {
-          this.showHeaderActions = visible;
-        }
+  private StandardBody() {
+    Column() {
+      this.ConversationBody()
+      this.Composer()
+    }
+    .layoutWeight(1)
+    .width('100%')
+    .translate({ x: this.contentHorizontalOffset, y: 0 })
+    .animation({ duration: 220, curve: Curve.EaseInOut })
+  }
+
+  @Builder
+  private HoverBody() {
+    FolderStack() {
+      Column() {
+        this.ConversationBody()
+      }
+      .width('100%')
+      .height('100%')
+      .padding({ bottom: 12 })
+      Column() {
+        this.Composer()
+      }
+      .width('100%')
+    }
+    .alignContent(Alignment.Bottom)
+    .layoutWeight(1)
+    .width('100%')
+    .enableAnimation(true)
+    .autoHalfFold(true)
+  }
+
+  @Builder
+  private ConversationBody() {
+    if (this.shouldShowStatusBar()) {
+      this.ExecutionStatusBar()
+    }
+    if (this.isLoadingConversation) {
+      ConversationLoadingState({
+        maxContentWidth: this.composerPresentation === ComposerPresentation.Floating ? 800 : 0
       })
+        .layoutWeight(1)
+    } else if (this.surface === ChatSurface.Create) {
+      Blank()
+        .layoutWeight(1)
+        .width('100%')
+        .onClick(() => {
+          this.onBackgroundTap();
+        })
+    } else if (this.shouldCenterInlineStatus()) {
+      this.CenteredInlineStatus()
     } else {
-      RemoteChatHeader({
-        activeSession: this.activeSession,
-        workspaceBranch: this.workspaceBranch,
-        desktopName: this.desktopName,
-        showBackButton: this.showBackButton,
-        showSidebarButton: this.showSidebarButton,
-        showSidebarRestoreButton: this.showSidebarRestoreButton,
-        showActionsMenu: this.showHeaderActions,
-        actionsMenu: () => {
-          this.HeaderActionsPopover();
-        },
-        onBack: () => {
-          this.onBack();
-        },
-        onOpenSidebar: () => {
-          this.onOpenSidebar();
-        },
-        onRestoreSidebar: () => {
-          this.onRestoreSidebar();
-        },
-        onOpenActions: () => {
-          this.showQuickActions = false;
-          this.showHeaderActions = !this.showHeaderActions;
-        },
-        onActionsMenuStateChange: (visible: boolean) => {
-          this.showHeaderActions = visible;
-        },
-        onRenameSession: (title: string) => {
-          this.onRenameSession(title);
-        }
-      })
+      this.MessageList()
+    }
+    if (this.inlineStatusText.length > 0 && !this.shouldCenterInlineStatus()) {
+      Text(this.inlineStatusText)
+        .fontSize(12).lineHeight(18).fontColor(MUTED).width('100%')
+        .padding({ left: 20, right: 20, bottom: 8 })
     }
   }
 
+  @Builder
+  Header() {
+    ConversationHeader({
+      title: this.headerTitle(),
+      subtitle: this.headerSubtitle(),
+      titleFallback: this.headerFallback(),
+      allowRename: this.headerAllowRename(),
+      showActions: this.headerShowActions(),
+      showSidebarButton: this.showSidebarButton,
+      showBackButton: this.showBackButton,
+      showSidebarRestoreButton: this.showSidebarRestoreButton,
+      showActionsMenu: this.showHeaderActions,
+      actionsMenu: () => {
+        this.HeaderActionsPopover();
+      },
+      onOpenSidebar: () => {
+        this.onOpenSidebar();
+      },
+      onRestoreSidebar: () => {
+        this.onRestoreSidebar();
+      },
+      onBack: () => {
+        this.onBack();
+      },
+      onOpenActions: () => {
+        this.showHeaderActions = !this.showHeaderActions;
+      },
+      onActionsMenuStateChange: (visible: boolean) => {
+        this.showHeaderActions = visible;
+      },
+      onRenameSession: (title: string) => {
+        this.onRenameSession(title);
+      }
+    })
+  }
+
   @Builder
   ExecutionStatusBar() {
     ChatStatusBar({
@@ -290,50 +295,15 @@ export struct ConversationView {
     .padding({ left: 32, right: 32, bottom: 48 })
   }
 
-  @Builder
-  PromptArea() {
-    Column({ space: 15 }) {
-      if (this.supportsSearch) {
-        this.SuggestionRow('globe', RemoteI18n.t('chatHome.research'), RemoteI18n.t('chatHome.researchPrompt'))
-      }
-      if (this.supportsImages) {
-        this.SuggestionRow('image', RemoteI18n.t('chatHome.image'), RemoteI18n.t('chatHome.imagePrompt'))
-      }
-      if (this.supportsFiles) {
-        this.SuggestionRow('file', RemoteI18n.t('chatHome.file'), RemoteI18n.t('chatHome.filePrompt'))
-      }
-    }
-    .width('100%')
-    .padding({ left: 24, right: 36, bottom: 18 })
-  }
-
-  @Builder
-  SuggestionRow(icon: string, label: string, prompt: string) {
-    Row({ space: 14 }) {
-      this.SuggestionIcon(icon)
-      Text(label)
-        .fontSize(17)
-        .fontWeight(FontWeight.Medium)
-        .fontColor(MUTED)
-        .layoutWeight(1)
-    }
-    .width('100%')
-    .height(38)
-    .onClick(() => {
-      this.onChatInputChange(prompt);
-    })
-  }
-
   @Builder
   Composer() {
-    ComposerBar({
+    Column() {
+      this.aboveComposer()
+      ComposerBar({
       presentation: this.composerPresentation,
       capabilities: this.composerCapabilities,
+      inputId: this.composerInputId,
       chatInput: this.chatInput,
-      showQuickActions: this.showQuickActions,
-      onToggleQuickActions: () => {
-        this.showQuickActions = !this.showQuickActions;
-      },
       selectedImages: this.selectedImages,
       isBusy: this.isBusy,
       canStop: this.canStop,
@@ -362,98 +332,13 @@ export struct ConversationView {
       onChatInputChange: (value: string) => {
         this.onChatInputChange(value);
       }
-    })
-  }
-
-  @Builder
-  AttachmentPanel() {
-    Column({ space: 8 }) {
-      Row() {
-        Text(RemoteI18n.t('chat.attachments'))
-          .fontSize(13)
-          .fontWeight(FontWeight.Medium)
-          .fontColor(INK)
-        Blank()
-        Text(RemoteI18n.t('common.close'))
-          .fontSize(12)
-          .fontColor(MUTED)
-          .onClick(() => {
-            this.showQuickActions = false;
-          })
-      }
-      .width('100%')
-      this.ImageActionRow()
-      Text(RemoteI18n.t('chat.quickPrompts'))
-        .fontSize(11)
-        .fontColor(MUTED)
-        .width('100%')
-      Row({ space: 8 }) {
-        this.QuickActionChip(RemoteI18n.t('chat.quickExplain'), RemoteI18n.t('chat.quickExplainPrompt'))
-        this.QuickActionChip(RemoteI18n.t('chat.quickContinue'), RemoteI18n.t('chat.quickContinuePrompt'))
-        this.QuickActionChip(RemoteI18n.t('chat.quickSummary'), RemoteI18n.t('chat.quickSummaryPrompt'))
-      }
-      .width('100%')
+      })
     }
     .width('100%')
-    .padding({ left: 18, right: 18, top: 12, bottom: 10 })
-  }
-
-  @Builder
-  MenuBackdrop(onClose: () => void) {
-    Text('')
-      .width('100%').height('100%')
-      .backgroundColor(this.composerPresentation === ComposerPresentation.Floating ? '#00000000' : '#18000000')
-      .zIndex(5)
-      .onClick(onClose)
-  }
-
-  @Builder
-  QuickActionsMenu() {
-    if (this.composerPresentation === ComposerPresentation.Floating) {
-      this.QuickActionsPopover()
-    } else {
-      this.QuickActionsBottomSheet()
-    }
-  }
-
-  @Builder
-  QuickActionsPopover() {
-    Column() {
-      this.AttachmentPanel()
-    }
-    .width(360)
-    .backgroundColor(CARD)
-    .border({ width: 1, color: LINE })
-    .borderRadius(18)
-    .shadow({ radius: 20, color: '#1A000000', offsetY: 8 })
-    .position({ left: 80 + this.contentHorizontalOffset, bottom: 86 })
-    .zIndex(6)
-    .transition(TransitionEffect.translate({ x: 0, y: 14 })
-      .combine(TransitionEffect.opacity(0))
-      .animation({ duration: 220, curve: Curve.EaseOut }))
   }
 
   @Builder
-  QuickActionsBottomSheet() {
-    Column() {
-      Text('')
-        .width(36)
-        .height(4)
-        .backgroundColor(LINE)
-        .borderRadius(2)
-        .margin({ top: 10 })
-      this.AttachmentPanel()
-    }
-    .width('100%')
-    .backgroundColor(CARD)
-    .border({ width: { top: 1 }, color: LINE })
-    .borderRadius({ topLeft: 18, topRight: 18 })
-    .position({ left: 0, bottom: 0 })
-    .zIndex(6)
-    .alignItems(HorizontalAlign.Center)
-    .transition(TransitionEffect.translate({ x: 0, y: 24 })
-      .combine(TransitionEffect.opacity(0))
-      .animation({ duration: 220, curve: Curve.EaseOut }))
+  private EmptyBuilder() {
   }
 
   @Builder
@@ -474,18 +359,22 @@ export struct ConversationView {
 
   @Builder
   HeaderActionsContent() {
-    Text('会话')
+    Text(RemoteI18n.t('chat.sessionSection'))
       .fontSize(13).fontWeight(FontWeight.Medium).fontColor(MUTED)
       .width('100%').height(28).padding({ left: 8 })
     if (this.surface === ChatSurface.General) {
       this.RemoteStyleMenuItem('remote_actions_check',
-        this.isSessionPinned ? '取消置顶' : '置顶', () => this.onTogglePinSession(), this.isSessionPinned)
+        this.isSessionPinned ? RemoteI18n.t('chat.unpin') : RemoteI18n.t('chat.pin'),
+        () => this.onTogglePinSession(), this.isSessionPinned)
     }
-    this.RemoteStyleMenuItem('remote_actions_cloud', '已上传的文件', () => this.onShowUploadedFiles())
+    this.RemoteStyleMenuItem('remote_actions_cloud', RemoteI18n.t('chat.uploadedFiles'),
+      () => this.onShowUploadedFiles())
     if (this.surface === ChatSurface.General) {
       Divider().strokeWidth(1).color(LINE).margin({ top: 8, bottom: 8 })
-      this.RemoteStyleMenuItem('remote_actions_folder', '归档', () => this.onArchiveSession())
-      this.RemoteStyleMenuItem('remote_actions_settings', '删除', () => this.onDeleteSession())
+      this.RemoteStyleMenuItem('remote_actions_folder', RemoteI18n.t('sidebar.archive'),
+        () => this.onArchiveSession())
+      this.RemoteStyleMenuItem('remote_actions_settings', RemoteI18n.t('common.delete'),
+        () => this.onDeleteSession())
     } else if (this.canStop) {
       Divider().strokeWidth(1).color(LINE).margin({ top: 8, bottom: 8 })
       this.RemoteStyleMenuItem('remote_actions_settings', RemoteI18n.t('chat.stop'), () => this.onStop())
@@ -525,127 +414,9 @@ export struct ConversationView {
     }
   }
 
-  @Builder
-  ImageActionRow() {
-    Row({ space: 10 }) {
-      Text('+')
-        .width(32)
-        .height(32)
-        .fontSize(21)
-        .fontColor(INK)
-        .textAlign(TextAlign.Center)
-        .backgroundColor(SOFT)
-        .borderRadius(16)
-      Column({ space: 3 }) {
-        Text(RemoteI18n.t('chat.pickImage'))
-          .fontSize(13)
-          .fontWeight(FontWeight.Medium)
-          .fontColor(INK)
-        Text(RemoteI18n.t('chat.pickImageDesc'))
-          .fontSize(11)
-          .fontColor(MUTED)
-          .maxLines(1)
-          .textOverflow({ overflow: TextOverflow.Ellipsis })
-      }
-      .layoutWeight(1)
-      .alignItems(HorizontalAlign.Start)
-      Text('>')
-        .fontSize(20)
-        .fontColor(MUTED)
-    }
-    .width('100%')
-    .height(48)
-    .padding({ left: 12, right: 12 })
-    .backgroundColor(CARD)
-    .borderRadius(14)
-    .border({ width: 1, color: LINE })
-    .onClick(() => {
-      this.showQuickActions = false;
-      this.onPickImages();
-    })
-  }
-
-  @Builder
-  QuickActionChip(label: string, prompt: string) {
-    Text(label)
-      .fontSize(11)
-      .fontColor(INK)
-      .textAlign(TextAlign.Center)
-      .layoutWeight(1)
-      .height(30)
-      .backgroundColor(CARD)
-      .borderRadius(15)
-      .border({ width: 1, color: LINE })
-      .onClick(() => {
-        this.onChatInputChange(prompt);
-        this.showQuickActions = false;
-      })
-  }
-
-  @Builder
-  SuggestionIcon(kind: string) {
-    Stack({ alignContent: Alignment.Center }) {
-      if (kind === 'write') {
-        Text('Aa')
-          .fontSize(13)
-          .fontWeight(FontWeight.Medium)
-          .fontColor(MUTED)
-      } else if (kind === 'organize') {
-        Text('=')
-          .fontSize(23)
-          .fontColor(MUTED)
-      } else if (kind === 'plan') {
-        Text('✓')
-          .fontSize(18)
-          .fontWeight(FontWeight.Medium)
-          .fontColor(MUTED)
-      } else if (kind === 'globe') {
-        SymbolGlyph($r('sys.symbol.website'))
-          .fontSize(21)
-          .fontColor([MUTED])
-      } else if (kind === 'image') {
-        SymbolGlyph($r('sys.symbol.picture'))
-          .fontSize(21)
-          .fontColor([MUTED])
-      } else {
-        this.FileGlyph()
-      }
-    }
-    .width(26)
-    .height(26)
-  }
-
-  @Builder
-  FileGlyph() {
-    Stack() {
-      Text('')
-        .width(19)
-        .height(23)
-        .borderRadius(3)
-        .border({ width: 1.5, color: MUTED })
-        .position({ x: 3, y: 2 })
-      Text('')
-        .width(7)
-        .height(7)
-        .border({ width: { right: 1.5, bottom: 1.5 }, color: MUTED })
-        .position({ x: 15, y: 3 })
-    }
-    .width(26)
-    .height(26)
-  }
-
-  private shouldShowSuggestions(): boolean {
-    return ConversationViewContract.shouldShowSuggestions(
-      this.showSuggestionsWhenEmpty,
-      this.isBusy,
-      this.timelineItems
-    ) && (this.supportsSearch || this.supportsImages || this.supportsFiles);
-  }
-
   private shouldCenterInlineStatus(): boolean {
     return this.inlineStatusText.length > 0 &&
       !this.isBusy &&
-      !this.shouldShowSuggestions() &&
       !ConversationViewContract.hasRealTimelineItem(this.timelineItems);
   }
 
@@ -686,7 +457,39 @@ export struct ConversationView {
   }
 
   private shouldShowStatusBar(): boolean {
-    return !this.isLoadingConversation && this.surface === ChatSurface.Remote && this.connectionState !== 'connected';
+    return this.surface === ChatSurface.Remote &&
+      !this.isLoadingConversation &&
+      this.connectionState !== 'connected';
+  }
+
+  private headerTitle(): string {
+    return this.headerPresentation().title;
+  }
+
+  private headerSubtitle(): string {
+    return this.headerPresentation().subtitle;
+  }
+
+  private headerFallback(): string {
+    return RemoteI18n.t(this.headerPresentation().fallbackKey);
+  }
+
+  private headerAllowRename(): boolean {
+    return this.headerPresentation().allowRename;
+  }
+
+  private headerShowActions(): boolean {
+    return this.headerPresentation().showActions;
+  }
+
+  private headerPresentation(): ConversationHeaderPresentation {
+    return ConversationHeaderPolicy.present(
+      this.surface,
+      this.activeSession.title,
+      this.desktopName,
+      this.workspaceBranch,
+      ConversationViewContract.hasRealTimelineItem(this.timelineItems)
+    );
   }
 
   private connectionColor(): ResourceColor {
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConversationViewContract.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConversationViewContract.ets
index f3e42cc60b..c9d002522f 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConversationViewContract.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConversationViewContract.ets
@@ -1,5 +1,5 @@
 import { ChatTimelineItem } from '../../services/ChatTimelineProjector';
-import { ChatSurface } from './ChatSurface';
+import { ChatSurface } from '../state/ChatSurface';
 
 export class ConversationViewContract {
   static surfaceForRoute(isRemoteChat: boolean): ChatSurface {
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConversationViewHost.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConversationViewHost.ets
index 045054b74a..5a64e50332 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConversationViewHost.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConversationViewHost.ets
@@ -5,7 +5,7 @@ import {
   ConversationIntents,
   ConversationIntentType
 } from '../actions/ConversationIntent';
-import { ConversationUiQuestionAnswer } from './ConversationUiModels';
+import { ConversationUiQuestionAnswer } from '../state/ConversationUiModels';
 import { ComposerPresentation } from './ComposerBar';
 
 @ComponentV2
@@ -18,6 +18,7 @@ export struct ConversationViewHost {
   @Param showSidebarRestoreButton: boolean = false;
   @Param composerPresentation: ComposerPresentation = ComposerPresentation.Compact;
   @Param contentHorizontalOffset: number = 0;
+  @Param hoverOperateMode: boolean = false;
   @Param onRestoreSidebar: () => void = () => {};
   @Param onIntent: (intent: ConversationIntent) => void = (_intent: ConversationIntent) => {};
 
@@ -37,10 +38,6 @@ export struct ConversationViewHost {
       hasMoreMessages: this.viewState.hasMoreMessages,
       timelineItems: this.viewState.timelineItems,
       timelineRevision: this.viewState.timelineRevision,
-      showSuggestionsWhenEmpty: this.viewState.showSuggestionsWhenEmpty,
-      supportsSearch: this.viewState.supportsSearch,
-      supportsImages: this.viewState.supportsImages,
-      supportsFiles: this.viewState.supportsFiles,
       modelCatalog: this.viewState.modelCatalog,
       selectedModelId: this.viewState.selectedModelId,
       downloadingFilePath: this.viewState.downloadingFilePath,
@@ -57,6 +54,7 @@ export struct ConversationViewHost {
       showSidebarRestoreButton: this.showSidebarRestoreButton,
       composerPresentation: this.composerPresentation,
       contentHorizontalOffset: this.contentHorizontalOffset,
+      hoverOperateMode: this.hoverOperateMode,
       onOpenSidebar: () => this.dispatch(ConversationIntents.simple(ConversationIntentType.OpenSidebar)),
       onRestoreSidebar: this.onRestoreSidebar,
       onBack: () => this.dispatch(ConversationIntents.simple(ConversationIntentType.Back)),
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/CreateSessionSheet.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/CreateSessionSheet.ets
deleted file mode 100644
index a00d0ca784..0000000000
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/CreateSessionSheet.ets
+++ /dev/null
@@ -1,228 +0,0 @@
-import { RemoteI18n } from '../../i18n/RemoteI18n';
-import { CARD, INK, LINE, MUTED, PAGE_BG, PRIMARY_ACTION, PRIMARY_ACTION_TEXT, SOFT, SUBTLE } from './Theme';
-
-@ComponentV2
-export struct CreateSessionSheet {
-  @Param createAgentType: string = 'code';
-  @Param workspaceName: string = '';
-  @Param workspaceBranch: string = '';
-  @Param isBusy: boolean = false;
-  @Param sessionTitle: string = '';
-  @Param instruction: string = '';
-  @Event onSessionTitleChange: (value: string) => void = (_value: string) => {};
-  @Event onInstructionChange: (value: string) => void = (_value: string) => {};
-  @Event onClose: () => void = () => {};
-  @Event onChooseWorkspace: () => void = () => {};
-  @Event onStart: () => void = () => {};
-
-  build() {
-    Column() {
-      Blank()
-      Column({ space: 16 }) {
-        Text('')
-          .width(42)
-          .height(4)
-          .backgroundColor(SUBTLE)
-          .borderRadius(2)
-
-        Row() {
-          Text(RemoteI18n.f('sheet.createTitle', this.displayAgent()))
-            .fontSize(20)
-            .fontWeight(FontWeight.Bold)
-            .fontColor(INK)
-          Blank()
-          Text('×')
-            .fontSize(26)
-            .fontColor(INK)
-            .width(34)
-            .height(34)
-            .textAlign(TextAlign.Center)
-            .onClick(() => {
-              this.onClose();
-            })
-        }
-        .width('100%')
-
-        Scroll() {
-          Column({ space: 18 }) {
-            Text(RemoteI18n.t('sheet.workspace'))
-              .fontSize(14)
-              .fontWeight(FontWeight.Medium)
-              .fontColor(INK)
-              .width('100%')
-              .margin({ top: 4 })
-
-            Row({ space: 10 }) {
-              this.FolderGlyph()
-              Text(this.workspaceTitle())
-                .fontSize(15)
-                .fontWeight(FontWeight.Medium)
-                .fontColor(INK)
-                .layoutWeight(1)
-                .maxLines(1)
-                .textOverflow({ overflow: TextOverflow.Ellipsis })
-              Text('›')
-                .fontSize(18)
-                .fontColor(INK)
-            }
-            .width('100%')
-            .height(58)
-            .padding({ left: 14, right: 12 })
-            .backgroundColor(SOFT)
-            .borderRadius(14)
-            .border({ width: 1, color: LINE })
-            .onClick(() => {
-              this.onChooseWorkspace();
-            })
-
-            this.InstructionField()
-            this.AdvancedOptions()
-          }
-          .width('100%')
-          .padding({ bottom: 8 })
-        }
-        .layoutWeight(1)
-        .scrollBar(BarState.Off)
-
-        Button(this.isBusy ? RemoteI18n.t('sheet.creating') : RemoteI18n.t('sheet.start'))
-          .width('100%')
-          .height(56)
-          .fontSize(17)
-          .fontWeight(FontWeight.Medium)
-          .fontColor(PRIMARY_ACTION_TEXT)
-          .backgroundColor(PRIMARY_ACTION)
-          .borderRadius(14)
-          .enabled(!this.isBusy)
-          .onClick(() => {
-            this.onStart();
-          })
-      }
-      .width('100%')
-      .height('64%')
-      .padding({ left: 22, right: 22, top: 10, bottom: 26 })
-      .backgroundColor(PAGE_BG)
-      .borderRadius({ topLeft: 20, topRight: 20 })
-    }
-    .width('100%')
-    .height('100%')
-    .backgroundColor('#99000000')
-  }
-
-  @Builder
-  TitleField() {
-    Column({ space: 10 }) {
-      Text(RemoteI18n.t('sheet.sessionTitleOptional'))
-        .fontSize(14)
-        .fontWeight(FontWeight.Medium)
-        .fontColor(INK)
-        .width('100%')
-      TextInput({ placeholder: this.defaultSessionTitle(), text: this.sessionTitle })
-        .height(52)
-        .fontSize(15)
-        .backgroundColor(SOFT)
-        .borderRadius(14)
-        .padding({ left: 14, right: 14 })
-        .border({ width: 1, color: LINE })
-        .defaultFocus(false)
-        .onChange((value: string) => {
-          this.onSessionTitleChange(value);
-        })
-    }
-    .width('100%')
-  }
-
-  @Builder
-  InstructionField() {
-    Column({ space: 10 }) {
-      Text(RemoteI18n.t('sheet.firstInstructionOptional'))
-        .fontSize(14)
-        .fontWeight(FontWeight.Medium)
-        .fontColor(INK)
-        .width('100%')
-      TextArea({ placeholder: RemoteI18n.t('sheet.instructionPlaceholder'), text: this.instruction })
-        .height(68)
-        .fontSize(15)
-        .backgroundColor(SOFT)
-        .borderRadius(14)
-        .padding(14)
-        .border({ width: 1, color: LINE })
-        .defaultFocus(false)
-        .onChange((value: string) => {
-          this.onInstructionChange(value);
-        })
-    }
-    .width('100%')
-  }
-
-  @Builder
-  AdvancedOptions() {
-    Column({ space: 10 }) {
-      Text(RemoteI18n.t('sheet.advancedOptions'))
-        .fontSize(15)
-        .fontWeight(FontWeight.Medium)
-        .fontColor(INK)
-        .width('100%')
-      Row() {
-        Text('模型')
-          .fontSize(15)
-          .fontWeight(FontWeight.Medium)
-          .fontColor(INK)
-        Blank()
-        Text('Auto')
-          .fontSize(14)
-          .fontColor(INK)
-        Text('⌄')
-          .fontSize(18)
-          .fontColor(INK)
-          .margin({ left: 10 })
-      }
-      .width('100%')
-      .height(56)
-      .padding({ left: 14, right: 14 })
-      .backgroundColor(SOFT)
-      .borderRadius(14)
-      .border({ width: 1, color: LINE })
-    }
-    .width('100%')
-  }
-
-  @Builder
-  FolderGlyph() {
-    Stack() {
-      Text('')
-        .width(26)
-        .height(18)
-        .borderRadius(4)
-        .border({ width: 2, color: INK })
-        .position({ x: 2, y: 9 })
-      Text('')
-        .width(12)
-        .height(7)
-        .borderRadius({ topLeft: 4, topRight: 4 })
-        .border({ width: { top: 2, left: 2, right: 2 }, color: INK })
-        .position({ x: 4, y: 5 })
-    }
-    .width(30)
-    .height(30)
-  }
-
-  private workspaceTitle(): string {
-    const base = this.workspaceName || 'BitFun';
-    return this.workspaceBranch.length > 0 ? `${base} / ${this.workspaceBranch}` : base;
-  }
-
-  private defaultSessionTitle(): string {
-    return `Remote ${this.displayAgent()} Session`;
-  }
-
-  private displayAgent(): string {
-    const normalized = (this.createAgentType || '').toLowerCase();
-    if (normalized === 'cowork') {
-      return 'Cowork';
-    }
-    if (normalized === 'claw') {
-      return 'Claw';
-    }
-    return 'Code';
-  }
-}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/RemoteChatHeader.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/RemoteChatHeader.ets
deleted file mode 100644
index 539ea93aaa..0000000000
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/RemoteChatHeader.ets
+++ /dev/null
@@ -1,213 +0,0 @@
-import { RemoteI18n } from '../../i18n/RemoteI18n';
-import { ConversationUiSession } from './ConversationUiModels';
-import { ACCENT, CARD, INK, LINE, MUTED, PAGE_BG, PRIMARY_ACTION_TEXT, SOFT } from './Theme';
-import { CompactMenuButton } from './CompactMenuButton';
-import { SidebarToggleButton } from './SidebarToggleButton';
-
-@ComponentV2
-export struct RemoteChatHeader {
-  @Param activeSession: ConversationUiSession = {
-    sessionId: '',
-    title: '',
-    workspacePath: '',
-    agentType: 'code'
-  };
-  @Param workspaceBranch: string = '';
-  @Param desktopName: string = '';
-  @Param showBackButton: boolean = true;
-  @Param showSidebarButton: boolean = false;
-  @Param showSidebarRestoreButton: boolean = false;
-  @Param showActionsMenu: boolean = false;
-  @BuilderParam actionsMenu: () => void = this.EmptyBuilder;
-  @Event onBack: () => void = () => {};
-  @Event onOpenSidebar: () => void = () => {};
-  @Event onRestoreSidebar: () => void = () => {};
-  @Event onOpenActions: () => void = () => {};
-  @Event onActionsMenuStateChange: (visible: boolean) => void = (_visible: boolean) => {};
-  @Event onRenameSession: (title: string) => void = (_title: string) => {};
-  @Local showTitleEditor: boolean = false;
-  @Local renameTitle: string = '';
-
-  build() {
-    Column() {
-      this.HeaderRow()
-      if (this.showTitleEditor) {
-        this.TitleEditor()
-      }
-    }
-    .width('100%')
-    .backgroundColor(PAGE_BG)
-  }
-
-  @Builder
-  HeaderRow() {
-    Row({ space: 8 }) {
-      this.LeadingControl()
-      Column({ space: 3 }) {
-        Text(this.activeSession.title || RemoteI18n.t('chat.remoteSession'))
-          .fontSize(18)
-          .fontWeight(FontWeight.Medium)
-          .fontColor(INK)
-          .textAlign(TextAlign.Center)
-          .maxLines(1)
-          .textOverflow({ overflow: TextOverflow.Ellipsis })
-          .onClick(() => {
-            this.renameTitle = this.activeSession.title || '';
-            this.showTitleEditor = true;
-          })
-        Row({ space: 6 }) {
-          Text(this.headerContextTitle())
-            .fontSize(14)
-            .fontColor(MUTED)
-            .textAlign(TextAlign.Center)
-            .maxLines(1)
-            .textOverflow({ overflow: TextOverflow.Ellipsis })
-        }
-        .width('100%')
-        .justifyContent(FlexAlign.Center)
-      }
-      .layoutWeight(1)
-      .alignItems(HorizontalAlign.Center)
-      this.ActionsControl()
-    }
-    .width('100%')
-    .alignItems(VerticalAlign.Center)
-    .padding({ left: 18, right: 18, top: 14, bottom: 16 })
-    .backgroundColor(PAGE_BG)
-  }
-
-  @Builder
-  private LeadingControl() {
-    if (this.showSidebarRestoreButton) {
-      SidebarToggleButton({
-        restore: true,
-        controlSize: 48,
-        onToggle: this.onRestoreSidebar
-      })
-    } else if (this.showBackButton) {
-      Stack({ alignContent: Alignment.Center }) {
-        Image($r('app.media.remote_ref_back'))
-          .width(15)
-          .height(23)
-          .objectFit(ImageFit.Contain)
-          .renderMode(ImageRenderMode.Template)
-          .foregroundColor(INK)
-      }
-      .width(44)
-      .height(44)
-      .backgroundColor(CARD)
-      .border({ width: 1, color: LINE })
-      .borderRadius(22)
-      .shadow({ radius: 10, color: LINE, offsetY: 3 })
-      .accessibilityText(RemoteI18n.t('common.back'))
-      .onClick(() => {
-        this.onBack();
-      })
-    } else if (this.showSidebarButton) {
-      CompactMenuButton({
-        controlSize: 44,
-        onOpen: () => {
-          this.onOpenSidebar();
-        }
-      })
-    } else {
-      Blank().width(44).height(44)
-    }
-  }
-
-  @Builder
-  private ActionsControl() {
-    Stack({ alignContent: Alignment.Center }) {
-        Image($r('app.media.remote_ref_more'))
-        .width(23)
-        .height(7)
-        .objectFit(ImageFit.Contain)
-        .renderMode(ImageRenderMode.Template)
-        .foregroundColor(INK)
-    }
-    .width(44)
-    .height(44)
-    .backgroundColor(CARD)
-    .borderRadius(22)
-    .border({ width: 1, color: LINE })
-    .shadow({ radius: 10, color: LINE, offsetY: 3 })
-    .accessibilityText(RemoteI18n.t('sidebar.more'))
-    .bindPopup(this.showActionsMenu, {
-      builder: () => {
-        this.actionsMenu();
-      },
-      placement: Placement.BottomRight,
-      popupColor: '#00000000',
-      enableArrow: false,
-      autoCancel: true,
-      mask: false,
-      targetSpace: 8,
-      onStateChange: (event) => {
-        this.onActionsMenuStateChange(event.isVisible);
-      }
-    })
-    .onClick(() => {
-      this.showTitleEditor = false;
-      this.onOpenActions();
-    })
-  }
-
-  @Builder
-  TitleEditor() {
-    Row({ space: 8 }) {
-      TextInput({ placeholder: RemoteI18n.t('chat.sessionTitle'), text: this.renameTitle })
-        .layoutWeight(1)
-        .height(42)
-        .fontSize(14)
-        .backgroundColor(CARD)
-        .borderRadius(14)
-        .padding({ left: 12, right: 12 })
-        .border({ width: 1, color: LINE })
-        .defaultFocus(false)
-        .onChange((value: string) => {
-          this.renameTitle = value;
-        })
-      Text(RemoteI18n.t('common.save'))
-        .width(52)
-        .height(42)
-        .fontSize(13)
-        .fontColor(PRIMARY_ACTION_TEXT)
-        .textAlign(TextAlign.Center)
-        .backgroundColor(this.renameTitle.trim().length > 0 ? ACCENT : SOFT)
-        .borderRadius(14)
-        .onClick(() => {
-          if (this.renameTitle.trim().length > 0) {
-            this.onRenameSession(this.renameTitle.trim());
-            this.showTitleEditor = false;
-          }
-        })
-      Text(RemoteI18n.t('common.cancel'))
-        .width(52)
-        .height(42)
-        .fontSize(13)
-        .fontColor(INK)
-        .textAlign(TextAlign.Center)
-        .backgroundColor(SOFT)
-        .borderRadius(14)
-        .onClick(() => {
-          this.showTitleEditor = false;
-        })
-    }
-    .width('100%')
-    .padding({ left: 18, right: 18, top: 10, bottom: 8 })
-    .backgroundColor(PAGE_BG)
-  }
-
-  private headerContextTitle(): string {
-    if (this.desktopName.length > 0) {
-      return this.desktopName;
-    }
-    const brand = 'BitFun';
-    return this.workspaceBranch.length > 0 ? `${brand} · ${this.workspaceBranch}` : brand;
-  }
-
-  @Builder
-  private EmptyBuilder() {
-  }
-
-}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/RemoteControlSettingsSheet.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/RemoteControlSettingsSheet.ets
index 3396da0e91..4a4beebf4e 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/RemoteControlSettingsSheet.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/RemoteControlSettingsSheet.ets
@@ -1,9 +1,10 @@
 import { RemoteI18n } from '../../i18n/RemoteI18n';
-import { CARD, GREEN, INK, LINE, MUTED, PAGE_BG, PRIMARY_ACTION, PRIMARY_ACTION_TEXT, RED, SOFT } from './Theme';
+import { CARD, GREEN, INK, LINE, MUTED, PAGE_BG, PRIMARY_ACTION_TEXT, RED, SOFT } from './Theme';
 import { CloudAccountDevice } from '../../services/CloudAccountClient';
 import { RemotePermissionMode } from '../../model/RemoteModels';
 import { DefaultAccountAvatar } from './DefaultAccountAvatar';
 import { BitFunAccountLoginPage } from './BitFunAccountLoginPage';
+import { AccountDeviceSelectionPolicy } from '../policy/AccountDeviceSelectionPolicy';
 
 @ComponentV2
 export struct RemoteControlSettingsSheet {
@@ -23,9 +24,10 @@ export struct RemoteControlSettingsSheet {
   @Event onOpenAccount: () => void = () => {};
   @Event onAddConnection: () => void = () => {};
   @Event cloudLogin: (relayUrl: string, username: string, password: string) => Promise<string> = async (_relayUrl: string, _username: string, _password: string): Promise<string> => '';
-  @Event cloudSync: () => Promise<string> = async (): Promise<string> => '0';
   @Event cloudLogout: () => Promise<void> = async (): Promise<void> => {};
   @Event cloudListDevices: () => Promise<CloudAccountDevice[]> = async (): Promise<CloudAccountDevice[]> => [];
+  @Event cloudSelectDevice: (device: CloudAccountDevice) => Promise<void> =
+    async (_device: CloudAccountDevice): Promise<void> => {};
   @Event getPermissionMode: () => Promise<RemotePermissionMode> = async (): Promise<RemotePermissionMode> => 'ask';
   @Event setPermissionMode: (mode: RemotePermissionMode) => Promise<RemotePermissionMode> =
     async (mode: RemotePermissionMode): Promise<RemotePermissionMode> => mode;
@@ -33,11 +35,10 @@ export struct RemoteControlSettingsSheet {
   @Event onReconnect: () => void = () => {};
   @Local showProfile: boolean = false;
   @Local showLogin: boolean = false;
-  @Local cloudSyncBusy: boolean = false;
-  @Local cloudSyncStatus: string = '';
   @Local accountDevices: CloudAccountDevice[] = [];
   @Local accountDevicesBusy: boolean = false;
   @Local accountDevicesError: string = '';
+  @Local switchingDeviceId: string = '';
   @Local permissionMode: RemotePermissionMode = 'ask';
   @Local permissionModeBusy: boolean = false;
   @Local permissionModeLoaded: boolean = false;
@@ -553,32 +554,6 @@ export struct RemoteControlSettingsSheet {
         .lineHeight(20)
         .fontColor(MUTED)
         .width('100%')
-
-      Text(RemoteI18n.t('remote.settings.accountSync'))
-        .height(42)
-        .width('100%')
-        .fontSize(15)
-        .fontColor(PRIMARY_ACTION_TEXT)
-        .backgroundColor(PRIMARY_ACTION)
-        .textAlign(TextAlign.Center)
-        .borderRadius(21)
-        .opacity(this.cloudSyncBusy ? 0.52 : 1)
-        .onClick(async () => {
-          if (this.cloudSyncBusy) return;
-          this.cloudSyncBusy = true;
-          this.cloudSyncStatus = '';
-          try {
-            const count = await this.cloudSync();
-            this.cloudSyncStatus = RemoteI18n.f('remote.settings.accountSyncSuccess', count);
-          } catch (err) {
-            this.cloudSyncStatus = err instanceof Error ? err.message : RemoteI18n.t('remote.settings.accountSyncFailed');
-          } finally {
-            this.cloudSyncBusy = false;
-          }
-        })
-      if (this.cloudSyncStatus.length > 0) {
-        Text(this.cloudSyncStatus).fontSize(13).fontColor(MUTED).width('100%')
-      }
     }
     .width('100%')
     .padding({ left: 18, right: 18, top: 16, bottom: 16 })
@@ -613,7 +588,6 @@ export struct RemoteControlSettingsSheet {
       this.logoutBusy = true;
       try {
         await this.cloudLogout();
-        this.cloudSyncStatus = '';
         this.showProfile = false;
         this.showLogin = true;
       } finally {
@@ -651,6 +625,10 @@ export struct RemoteControlSettingsSheet {
         }, (device: CloudAccountDevice): string =>
           `${device.deviceId}:${device.online ? 'online' : 'offline'}:${device.lastSeenAt || 0}:${device.deviceName}`)
       }
+      if (this.accountDevicesError.length > 0 && this.desktopDevices().length > 0) {
+        Text(this.accountDevicesError)
+          .fontSize(13).lineHeight(18).fontColor(RED).width('100%')
+      }
     }
     .width('100%').padding({ left: 18, right: 18, top: 16, bottom: 16 })
     .backgroundColor(CARD).borderRadius(24).margin({ bottom: 24 })
@@ -668,9 +646,19 @@ export struct RemoteControlSettingsSheet {
         Text(this.deviceStatus(device))
           .fontSize(13).fontColor(device.online ? GREEN : MUTED)
       }.layoutWeight(1).alignItems(HorizontalAlign.Start)
+      if (this.shouldShowDeviceConnectAction(device)) {
+        Text(this.switchingDeviceId === device.deviceId ?
+          RemoteI18n.t('remote.settings.deviceConnecting') : RemoteI18n.t('connect.connect'))
+          .fontSize(14).fontColor(INK)
+          .padding({ left: 10, right: 10, top: 6, bottom: 6 })
+          .backgroundColor(SOFT).borderRadius(14)
+      }
     }
     .width('100%').height(54).alignItems(VerticalAlign.Center)
-    .opacity(device.online ? 1 : 0.68)
+    .opacity(this.canActivateAccountDevice(device) ? 1 : 0.68)
+    .onClick(() => {
+      void this.connectAccountDevice(device);
+    })
   }
 
   private async refreshAccountDevices(allowPendingLogin: boolean = false): Promise<void> {
@@ -691,6 +679,49 @@ export struct RemoteControlSettingsSheet {
       device.deviceId !== this.deviceId && device.deviceName !== 'HarmonyOS Phone');
   }
 
+  private canActivateAccountDevice(device: CloudAccountDevice): boolean {
+    return AccountDeviceSelectionPolicy.canActivate(
+      device.online,
+      device.deviceId,
+      this.deviceId,
+      this.controlTargetDeviceId,
+      this.connectionState,
+      this.switchingDeviceId
+    );
+  }
+
+  private shouldShowDeviceConnectAction(device: CloudAccountDevice): boolean {
+    return AccountDeviceSelectionPolicy.shouldShowConnectAction(
+      device.online,
+      device.deviceId,
+      this.deviceId,
+      this.controlTargetDeviceId,
+      this.connectionState
+    );
+  }
+
+  private async connectAccountDevice(device: CloudAccountDevice): Promise<void> {
+    if (!this.canActivateAccountDevice(device)) {
+      return;
+    }
+    this.switchingDeviceId = device.deviceId;
+    this.accountDevicesError = '';
+    try {
+      if (AccountDeviceSelectionPolicy.canSelectOnline(
+        device.online, device.deviceId, this.deviceId, ''
+      )) {
+        await this.cloudSelectDevice(device);
+      } else {
+        this.onReconnect();
+      }
+    } catch (err) {
+      this.accountDevicesError = err instanceof Error ? err.message :
+        RemoteI18n.t('remote.settings.deviceSwitchFailed');
+    } finally {
+      this.switchingDeviceId = '';
+    }
+  }
+
   private deviceStatus(device: CloudAccountDevice): string {
     if (device.deviceId === this.deviceId) return RemoteI18n.t('remote.settings.deviceCurrent');
     const presence = device.online ? RemoteI18n.t('remote.settings.deviceOnline') :
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/RemoteCreateSessionView.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/RemoteCreateSessionView.ets
index a11ab7ee5e..38b9c38a6b 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/RemoteCreateSessionView.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/RemoteCreateSessionView.ets
@@ -1,19 +1,20 @@
-import { KeyboardAvoidMode } from '@kit.ArkUI';
 import { RecentWorkspaceEntry } from '../../model/RemoteModels';
 import { RemoteI18n } from '../../i18n/RemoteI18n';
 import { CloudAccountDevice } from '../../services/CloudAccountClient';
 import { RemoteCreateSessionState } from '../state/RemoteCreateSessionState';
-import { ACCENT, CARD, INK, LINE, MUTED, PAGE_BG, RED, SOFT, SUBTLE } from './Theme';
-import { ComposerBar, ComposerPresentation } from './ComposerBar';
-import { ConversationUiModelCatalog } from './ConversationUiModels';
-import { REMOTE_CREATE_COMPOSER_CAPABILITIES } from './ChatComposerCapabilities';
-import { SidebarToggleButton } from './SidebarToggleButton';
+import { CARD, INK, LINE, MUTED, PAGE_BG } from './Theme';
+import { ComposerPresentation } from './ComposerBar';
+import { ConversationView } from './ConversationView';
+import { ConversationUiModelCatalog } from '../state/ConversationUiModels';
+import { REMOTE_CREATE_COMPOSER_CAPABILITIES } from '../state/ChatComposerCapabilities';
+import { ChatSurface } from '../state/ChatSurface';
 
 @ComponentV2
 export struct RemoteCreateSessionView {
   @Param state: RemoteCreateSessionState = new RemoteCreateSessionState();
   @Param presentation: ComposerPresentation = ComposerPresentation.Create;
   @Param showSidebarRestoreButton: boolean = false;
+  @Param hoverOperateMode: boolean = false;
   @Param isVoiceListening: boolean = false;
   @Param modelCatalog: ConversationUiModelCatalog = {
     version: 0,
@@ -32,139 +33,49 @@ export struct RemoteCreateSessionView {
   @Event onVoiceInput: () => void = () => {};
   @Event onSelectModel: (modelId: string) => void = (_modelId: string) => {};
   @Local showSelectorSheet: boolean = false;
-  private previousKeyboardAvoidMode: KeyboardAvoidMode = KeyboardAvoidMode.OFFSET;
 
   aboutToAppear(): void {
-    this.previousKeyboardAvoidMode = this.getUIContext().getKeyboardAvoidMode();
-    this.getUIContext().setKeyboardAvoidMode(KeyboardAvoidMode.RESIZE);
     setTimeout(() => this.keepComposerFocused(), 180);
   }
 
-  aboutToDisappear(): void {
-    this.getUIContext().setKeyboardAvoidMode(this.previousKeyboardAvoidMode);
-  }
-
   build() {
     Column() {
-      if (this.presentation === ComposerPresentation.Floating) {
-        this.Header()
-        Blank()
-          .layoutWeight(1)
-          .onClick(() => {
-            this.state.closeMenu();
-            this.keepComposerFocused();
-          })
-      } else {
-        this.CompactNavigationSpace()
-        this.ContextControls()
-        this.CompactComposerBar()
-      }
-      if (this.presentation === ComposerPresentation.Floating) {
-        this.TaskComposer()
-      }
-    }
-    .width('100%')
-    .height('100%')
-    .backgroundColor(PAGE_BG)
-    .bindSheet($$this.showSelectorSheet, this.SelectorSheet(), this.selectorSheetOptions())
-  }
-
-  @Builder
-  CompactComposerBar() {
-    ComposerBar({
-      presentation: ComposerPresentation.Create,
-      capabilities: REMOTE_CREATE_COMPOSER_CAPABILITIES,
-      inputId: 'remote-create-composer',
-      chatInput: this.state.draft,
-      isBusy: this.state.isSubmitting,
-      connectionState: 'connected',
-      isVoiceListening: this.isVoiceListening,
-      modelCatalog: this.modelCatalog,
-      selectedModelId: this.selectedModelId,
-      onSend: () => this.onSend(),
-      onChatInputChange: (value: string) => this.onDraftChange(value),
-      onVoiceInput: () => this.onVoiceInput(),
-      onSelectModel: (modelId: string) => this.onSelectModel(modelId)
-    })
-  }
-
-  @Builder
-  CompactNavigationSpace() {
-    Column() {
-      Row() {
-        Button() {
-          Image($r('app.media.remote_ref_back'))
-            .width(15)
-            .height(23)
-            .objectFit(ImageFit.Contain)
-            .renderMode(ImageRenderMode.Template)
-            .foregroundColor(INK)
-        }
-        .width(44)
-        .height(44)
-        .padding(0)
-        .type(ButtonType.Circle)
-        .backgroundColor(CARD)
-        .border({ width: 1, color: LINE })
-        .borderRadius(22)
-        .shadow({ radius: 16, color: '#10000000', offsetY: 7 })
-        .accessibilityText(RemoteI18n.t('common.back'))
-        .onClick(() => this.onBack())
-      }
-      .width('100%')
-      .height(78)
-      .padding({ left: 18, top: 14 })
-      .alignItems(VerticalAlign.Top)
-      Column()
-        .width('100%')
-        .layoutWeight(1)
-        .onClick(() => {
+      ConversationView({
+        surface: ChatSurface.Create,
+        composerCapabilities: REMOTE_CREATE_COMPOSER_CAPABILITIES,
+        composerPresentation: this.presentation === ComposerPresentation.Floating ?
+          ComposerPresentation.Floating : ComposerPresentation.Create,
+        composerInputId: 'remote-create-composer',
+        chatInput: this.state.draft,
+        isBusy: this.state.isSubmitting,
+        inlineStatusText: this.state.errorText,
+        connectionState: 'connected',
+        isVoiceListening: this.isVoiceListening,
+        modelCatalog: this.modelCatalog,
+        selectedModelId: this.selectedModelId,
+        showBackButton: true,
+        showSidebarButton: false,
+        showSidebarRestoreButton: this.showSidebarRestoreButton,
+        hoverOperateMode: this.hoverOperateMode,
+        aboveComposer: () => {
+          this.ContextControls();
+        },
+        onBack: () => this.onBack(),
+        onRestoreSidebar: () => this.onRestoreSidebar(),
+        onSend: () => this.onSend(),
+        onChatInputChange: (value: string) => this.onDraftChange(value),
+        onVoiceInput: () => this.onVoiceInput(),
+        onSelectModel: (modelId: string) => this.onSelectModel(modelId),
+        onBackgroundTap: () => {
           this.state.closeMenu();
           this.keepComposerFocused();
-        })
-    }
-    .width('100%')
-    .layoutWeight(1)
-  }
-
-  @Builder
-  Header() {
-    Row({ space: 8 }) {
-      if (this.showSidebarRestoreButton) {
-        SidebarToggleButton({
-          restore: true,
-          controlSize: 48,
-          onToggle: this.onRestoreSidebar
-        })
-      } else if (this.presentation !== ComposerPresentation.Floating) {
-        Button() {
-          SymbolGlyph($r('sys.symbol.chevron_left'))
-            .fontSize(22)
-            .fontColor([INK])
         }
-        .width(48)
-        .height(48)
-        .padding(0)
-        .type(ButtonType.Circle)
-        .backgroundColor(CARD)
-        .border({ width: 1, color: LINE })
-        .borderRadius(24)
-        .accessibilityText(RemoteI18n.t('common.back'))
-        .onClick(() => this.onBack())
-      } else {
-        Blank().width(48).height(48)
-      }
-      Text(RemoteI18n.t('remote.create.title'))
-        .layoutWeight(1)
-        .fontSize(17)
-        .fontWeight(FontWeight.Medium)
-        .fontColor(INK)
-        .textAlign(TextAlign.Center)
-      Blank().width(48).height(48)
+      })
     }
     .width('100%')
-    .height(64)
-    .padding({ left: 16, right: 16, top: 8, bottom: 8 })
+    .height('100%')
+    .backgroundColor(PAGE_BG)
+    .bindSheet($$this.showSelectorSheet, this.SelectorSheet(), this.selectorSheetOptions())
   }
 
   @Builder
@@ -445,102 +356,6 @@ export struct RemoteCreateSessionView {
     .borderRadius(16)
   }
 
-  @Builder
-  TaskComposer() {
-    Column({ space: 6 }) {
-      if (this.presentation === ComposerPresentation.Floating) {
-        this.ContextControls()
-        Divider()
-          .color(LINE)
-          .margin({ left: 18, right: 18 })
-      }
-      if (this.state.errorText.length > 0) {
-        Text(this.state.errorText)
-          .width('100%')
-          .padding({ left: 12, right: 12 })
-          .fontSize(12)
-          .fontColor(RED)
-          .maxLines(2)
-      }
-      Row({ space: 8 }) {
-        TextArea({ placeholder: RemoteI18n.t('remote.create.placeholder'), text: this.state.draft })
-          .id('remote-create-composer')
-          .layoutWeight(1)
-          .height(56)
-          .fontSize(16)
-          .fontColor(INK)
-          .placeholderColor(SUBTLE)
-          .backgroundColor('#00000000')
-          .padding({ left: 6, right: 4, top: 8, bottom: 8 })
-          .defaultFocus(true)
-          .maxLines(3)
-          .onChange((value: string, previewText?: PreviewText) => {
-            if (previewText && previewText.value.length > 0) {
-              return;
-            }
-            this.onDraftChange(value);
-          })
-        Button() {
-          SymbolGlyph($r('sys.symbol.arrow_up'))
-            .fontSize(23)
-            .fontColor([INK])
-            .opacity(this.canSend() ? 1 : 0.36)
-        }
-        .width(42)
-        .height(42)
-        .padding(0)
-        .type(ButtonType.Circle)
-        .backgroundColor('#00000000')
-        .enabled(this.canSend())
-        .onClick(() => this.onSend())
-      }
-      .width('100%')
-      .height(this.presentation === ComposerPresentation.Floating ? 72 : 66)
-      .padding({ left: 12, right: 7, top: 5, bottom: 5 })
-      .backgroundColor(this.presentation === ComposerPresentation.Floating ? '#00000000' : CARD)
-      .borderRadius(this.presentation === ComposerPresentation.Floating ? 0 : 25)
-      .border({
-        width: this.presentation === ComposerPresentation.Floating ? 0 : 1,
-        color: this.presentation === ComposerPresentation.Floating ? '#00000000' : SOFT
-      })
-      .shadow({
-        radius: this.presentation === ComposerPresentation.Floating ? 0 : 22,
-        color: this.presentation === ComposerPresentation.Floating ? '#00000000' : '#18000000',
-        offsetY: this.presentation === ComposerPresentation.Floating ? 0 : 7
-      })
-    }
-    .width('100%')
-    .constraintSize({ maxWidth: this.presentation === ComposerPresentation.Floating ? 760 : 10000 })
-    .alignSelf(ItemAlign.Center)
-    .padding({
-      left: this.presentation === ComposerPresentation.Floating ? 0 : 16,
-      right: this.presentation === ComposerPresentation.Floating ? 0 : 16,
-      top: this.presentation === ComposerPresentation.Floating ? 4 : 0,
-      bottom: this.presentation === ComposerPresentation.Floating ? 4 : 14
-    })
-    .backgroundColor(this.presentation === ComposerPresentation.Floating ? CARD : '#00000000')
-    .borderRadius(this.presentation === ComposerPresentation.Floating ? 18 : 0)
-    .border({
-      width: this.presentation === ComposerPresentation.Floating ? 1 : 0,
-      color: this.presentation === ComposerPresentation.Floating ? SOFT : '#00000000'
-    })
-    .shadow({
-      radius: this.presentation === ComposerPresentation.Floating ? 20 : 0,
-      color: this.presentation === ComposerPresentation.Floating ? '#18000000' : '#00000000',
-      offsetY: this.presentation === ComposerPresentation.Floating ? 6 : 0
-    })
-    .margin({
-      left: this.presentation === ComposerPresentation.Floating ? 24 : 0,
-      right: this.presentation === ComposerPresentation.Floating ? 24 : 0,
-      bottom: this.presentation === ComposerPresentation.Floating ? 24 : 0
-    })
-  }
-
-  private canSend(): boolean {
-    return this.state.draft.trim().length > 0 && this.state.selectedDeviceId.length > 0 &&
-      !this.state.isSubmitting;
-  }
-
   private keepComposerFocused(): void {
     setTimeout(() => focusControl.requestFocus('remote-create-composer'), 30);
   }
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/RemoteSessionList.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/RemoteSessionList.ets
index bfca15020c..5f74954afe 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/RemoteSessionList.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/RemoteSessionList.ets
@@ -1,11 +1,15 @@
 import { RecentWorkspaceEntry, RemoteSession } from '../../model/RemoteModels';
 import { RemoteI18n } from '../../i18n/RemoteI18n';
-import { TimeFormat } from '../../services/TimeFormat';
 import { CARD, INK, MUTED, SOFT } from './Theme';
 import { SessionActionPresentation, SessionActionSurface } from './SessionActionSurface';
 import { SessionActionCapabilities, SessionActionPolicy, SessionActionScope } from '../policy/SessionActionPolicy';
 import { SessionDetailsView } from './SessionDetailsView';
-import { ConversationSessionFilterPolicy } from '../policy/ConversationSessionFilterPolicy';
+import {
+  SessionListInputs,
+  SessionListProjection,
+  SessionListProjectionCache,
+  SessionListProjector
+} from '../policy/SessionListProjection';
 
 @ComponentV2
 export struct RemoteSessionList {
@@ -47,6 +51,11 @@ export struct RemoteSessionList {
   @Local detailsSessionId: string = '';
   @Local showSessionDetails: boolean = false;
   @Local optimisticSelectedSessionId: string = '';
+  // Selecting a row reruns this whole builder tree, and the tree asks for the
+  // grouped lists far more often than it changes them. The cache answers from
+  // the last projection unless the sessions, the workspaces or a filter moved —
+  // none of which a selection touches.
+  private readonly projectionCache: SessionListProjectionCache = new SessionListProjectionCache();
 
   @Monitor('isBusy', 'workspacePath')
   onWorkspaceContextChanged(): void {
@@ -414,21 +423,34 @@ export struct RemoteSessionList {
     }
   }
 
+  /**
+   * The grouped session list, computed at most once per change to its inputs.
+   *
+   * Every derived accessor below reads through here rather than deriving
+   * anything itself, so calling them repeatedly across the builder tree — which
+   * is what the tree does — costs a map lookup instead of a full scan.
+   */
+  private view(): SessionListProjection {
+    const inputs: SessionListInputs = {
+      sessions: this.sessions,
+      query: this.query,
+      sortMode: this.sortMode,
+      workspaceName: this.workspaceName,
+      workspacePath: this.workspacePath,
+      workspaceKind: this.workspaceKind,
+      recentWorkspaces: this.recentWorkspaces,
+      workspaceFilter: this.workspaceFilter,
+      agentFilter: this.agentFilter,
+      statusFilter: this.statusFilter,
+      showWorkspaceMetadata: this.showWorkspaceMetadata,
+      showUpdatedMetadata: this.showUpdatedMetadata,
+      showStatusMetadata: this.showStatusMetadata
+    };
+    return this.projectionCache.get(inputs);
+  }
+
   private projectEntries(): RecentWorkspaceEntry[] {
-    const entries: RecentWorkspaceEntry[] = [];
-    if ((this.workspacePath.length > 0 || this.workspaceName.length > 0) && !this.isAssistantWorkspace(this.workspacePath)) {
-      entries.push({ path: this.workspacePath, name: this.workspaceName, lastOpened: '', workspaceKind: 'normal' });
-    }
-    this.recentWorkspaces.forEach((item: RecentWorkspaceEntry) => {
-      if (item.path.length > 0 && !this.isAssistantWorkspace(item.path) &&
-        !entries.some((entry: RecentWorkspaceEntry) => entry.path === item.path)) {
-        entries.push(item);
-      }
-    });
-    if (!this.hasActiveListFilter()) {
-      return entries;
-    }
-    return entries.filter((item: RecentWorkspaceEntry) => this.projectSessions(item.path).length > 0);
+    return this.view().projects;
   }
 
   private visibleProjectEntries(): RecentWorkspaceEntry[] {
@@ -445,76 +467,31 @@ export struct RemoteSessionList {
   }
 
   private visibleChatSessions(): RemoteSession[] {
-    return this.filteredSessions().filter((item: RemoteSession) => this.isAssistantSession(item));
+    return this.view().chats;
   }
 
   private sessionsByTime(): RemoteSession[] {
-    return this.filteredSessions().slice().sort((left: RemoteSession, right: RemoteSession) => {
-      return this.sessionTimestamp(right) - this.sessionTimestamp(left);
-    });
+    return this.view().byTime;
   }
 
   private sessionsForTimeBucket(bucket: string): RemoteSession[] {
-    return this.sessionsByTime().filter((item: RemoteSession) => {
-      return this.timeBucket(item) === bucket;
-    });
-  }
-
-  private timeBucket(item: RemoteSession): string {
-    const timestamp = this.sessionTimestamp(item);
-    if (timestamp <= 0) {
-      return 'earlier';
-    }
-    const sessionDate = new Date(timestamp);
-    const now = new Date();
-    if (this.sameCalendarDay(sessionDate, now)) {
-      return 'today';
-    }
-    const yesterday = new Date(now.getFullYear(), now.getMonth(), now.getDate() - 1);
-    return this.sameCalendarDay(sessionDate, yesterday) ? 'yesterday' : 'earlier';
-  }
-
-  private sessionTimestamp(item: RemoteSession): number {
-    const updated = TimeFormat.timestampMs(item.updatedAt || '');
-    if (!Number.isNaN(updated) && updated > 0) {
-      return updated;
+    const projection = this.view();
+    if (bucket === 'today') {
+      return projection.today;
     }
-    const created = TimeFormat.timestampMs(item.createdAt || '');
-    return !Number.isNaN(created) && created > 0 ? created : 0;
-  }
-
-  private sameCalendarDay(left: Date, right: Date): boolean {
-    return left.getFullYear() === right.getFullYear() &&
-      left.getMonth() === right.getMonth() &&
-      left.getDate() === right.getDate();
+    return bucket === 'yesterday' ? projection.yesterday : projection.earlier;
   }
 
   private projectSessions(path: string): RemoteSession[] {
-    return this.filteredSessions().filter((item: RemoteSession) => {
-      return !this.isAssistantSession(item) && ConversationSessionFilterPolicy.workspacePathsEqual(
-        item.workspacePath || this.workspacePath,
-        path
-      );
-    });
+    return SessionListProjector.sessionsForProject(this.view(), path);
   }
 
   private filteredSessions(): RemoteSession[] {
-    return this.sessions.filter((item: RemoteSession) => {
-      return ConversationSessionFilterPolicy.matches(
-        item,
-        this.query,
-        this.workspacePath,
-        this.workspaceFilter,
-        this.agentFilter,
-        this.statusFilter,
-        this.isAssistantSession(item)
-      );
-    });
+    return this.view().filtered;
   }
 
   private hasActiveListFilter(): boolean {
-    return this.query.trim().length > 0 || this.workspaceFilter.length > 0 ||
-      this.agentFilter.length > 0 || this.statusFilter.length > 0;
+    return this.view().hasActiveFilter;
   }
 
   private visibleProjectSessions(path: string): RemoteSession[] {
@@ -534,25 +511,6 @@ export struct RemoteSessionList {
     return Math.min(3, this.visibleChatSessions().length - this.chatVisibleCount);
   }
 
-  private isAssistantSession(item: RemoteSession): boolean {
-    const agentType = (item.agentType || '').toLowerCase();
-    return agentType === 'claw' || agentType === 'assistant' || agentType === 'chat' ||
-      this.isAssistantWorkspace(item.workspacePath || '');
-  }
-
-  private isAssistantWorkspace(path: string): boolean {
-    if (path.length === 0) {
-      return this.workspaceKind.toLowerCase() === 'assistant';
-    }
-    if (path === this.workspacePath && this.workspaceKind.toLowerCase() === 'assistant') {
-      return true;
-    }
-    return this.recentWorkspaces.some((item: RecentWorkspaceEntry) => {
-      return item.path === path && item.workspaceKind.toLowerCase() === 'assistant';
-    });
-  }
-
-
   private isWorkspaceCollapsed(path: string): boolean {
     return this.collapsedWorkspacePaths.indexOf(path) >= 0;
   }
@@ -748,20 +706,7 @@ export struct RemoteSessionList {
   }
 
   private metadataText(item: RemoteSession): string {
-    const values: string[] = [];
-    if (this.showWorkspaceMetadata) {
-      const workspace = item.workspaceName || item.workspacePath || '';
-      if (workspace.length > 0) {
-        values.push(workspace);
-      }
-    }
-    if (this.showUpdatedMetadata && !Number.isNaN(TimeFormat.timestampMs(item.updatedAt))) {
-      values.push(TimeFormat.relative(item.updatedAt));
-    }
-    if (this.showStatusMetadata && item.status.length > 0) {
-      values.push(item.status === 'archived' ? RemoteI18n.t('sidebar.archived') : item.status);
-    }
-    return values.join(' · ');
+    return SessionListProjector.metadataFor(this.view(), item.id);
   }
 
   private actionCapabilities(): SessionActionCapabilities {
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/SettingsSheet.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/SettingsSheet.ets
index 0a3cb71b96..45380c8b6b 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/SettingsSheet.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/SettingsSheet.ets
@@ -92,6 +92,7 @@ export struct SettingsSheet {
       .backgroundColor(CARD)
       .shadow({ radius: 16, color: '#10000000', offsetY: 7 })
       .margin({ top: 22, right: 18 })
+      .accessibilityText(RemoteI18n.t('common.close'))
       .onClick(() => {
         this.onClose();
       })
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/SidebarGlyphs.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/SidebarGlyphs.ets
index af5a2504d6..11bdba7192 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/SidebarGlyphs.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/SidebarGlyphs.ets
@@ -1,4 +1,5 @@
 import { CARD, GREEN, INK, MUTED } from './Theme';
+import { TemplateIcon } from './TemplateIcon';
 
 @ComponentV2
 export struct SidebarGlyph {
@@ -44,15 +45,11 @@ export struct SidebarGlyph {
   private Remote() {
     Stack({ alignContent: Alignment.Center }) {
       if (this.connectionState === 'connected' || this.connectionState === 'reconnecting') {
-        Image($r('app.media.remote_ref_sidebar_connected'))
-          .width(35).height(34).objectFit(ImageFit.Contain)
-          .renderMode(ImageRenderMode.Template).foregroundColor(INK)
+        TemplateIcon({ src: $r('app.media.remote_ref_sidebar_connected'), iconWidth: 35, iconHeight: 34 })
         Text('').width(8).height(8).backgroundColor(GREEN).borderRadius(4)
           .position({ x: 24, y: 22 })
       } else {
-        Image($r('app.media.remote_logo'))
-          .width(34).height(34).objectFit(ImageFit.Contain)
-          .renderMode(ImageRenderMode.Template).foregroundColor(MUTED)
+        TemplateIcon({ src: $r('app.media.remote_logo'), iconWidth: 34, iconHeight: 34, tint: MUTED })
       }
     }
     .width(35).height(34)
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/SubagentTaskCard.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/SubagentTaskCard.ets
new file mode 100644
index 0000000000..b40887f65a
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/SubagentTaskCard.ets
@@ -0,0 +1,87 @@
+import { RemoteI18n } from '../../i18n/RemoteI18n';
+import { ToolCollapsePolicy } from '../policy/ToolCollapsePolicy';
+import { ChatTypingDots } from './ChatMessageChrome';
+import { INK, LINE, MUTED, SOFT } from './Theme';
+
+@ComponentV2
+export struct SubagentTaskCard {
+  @Param title: string = '';
+  @Param running: boolean = false;
+  @Param content: string = '';
+  @Param hasChildren: boolean = false;
+  @BuilderParam childItems: () => void = this.EmptyChildren;
+  @Local expanded: boolean = false;
+  @Local userToggled: boolean = false;
+
+  aboutToAppear(): void {
+    this.userToggled = false;
+    this.expanded = ToolCollapsePolicy.defaultSubagentExpanded(this.running);
+  }
+
+  @Monitor('running')
+  onRunningChanged(): void {
+    this.expanded = ToolCollapsePolicy.subagentExpandedForStatus(
+      this.running,
+      this.userToggled,
+      this.expanded
+    );
+    if (!this.running) {
+      this.userToggled = false;
+    }
+  }
+
+  build() {
+    Column({ space: 8 }) {
+      Row({ space: 8 }) {
+        Stack({ alignContent: Alignment.Center }) {
+          SymbolGlyph(this.expanded ? $r('sys.symbol.chevron_down') : $r('sys.symbol.chevron_right'))
+            .fontSize(14)
+            .fontColor([MUTED])
+            .width(16)
+            .height(16)
+        }
+        .width(18)
+        .height(32)
+        Text(this.title)
+          .fontSize(13)
+          .fontWeight(FontWeight.Medium)
+          .fontColor(INK)
+          .layoutWeight(1)
+          .maxLines(1)
+          .textOverflow({ overflow: TextOverflow.Ellipsis })
+      }
+      .width('100%')
+      .height(32)
+      .alignItems(VerticalAlign.Center)
+      .onClick(() => {
+        this.userToggled = this.running;
+        this.expanded = !this.expanded;
+      })
+      .accessibilityText(this.expanded ? RemoteI18n.t('chat.showLess') : RemoteI18n.t('chat.showMore'))
+      if (this.expanded) {
+        if (this.running) {
+          ChatTypingDots()
+        }
+        if (this.content.trim().length > 0) {
+          Text(this.content)
+            .fontSize(13)
+            .lineHeight(19)
+            .fontColor(MUTED)
+            .width('100%')
+        }
+        if (this.hasChildren) {
+          this.childItems()
+        }
+      }
+    }
+    .width('100%')
+    .padding({ left: 10, right: 10, top: 8, bottom: 8 })
+    .backgroundColor(SOFT)
+    .borderRadius(12)
+    .border({ width: 1, color: LINE })
+  }
+
+  @Builder
+  EmptyChildren() {
+  }
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/TemplateIcon.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/TemplateIcon.ets
new file mode 100644
index 0000000000..86d16c223d
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/TemplateIcon.ets
@@ -0,0 +1,36 @@
+import { INK } from './Theme';
+
+// Monochrome bitmap glyph tinted with a semantic theme color.
+//
+// The reference assets are black-pixel PNGs with an alpha mask, and ArkUI
+// cannot tint those the way iOS template images work: `fillColor` only applies
+// to SVG sources, and `renderMode(ImageRenderMode.Template)` is a monochrome
+// render that keeps the original luminance, so the black pixels stayed black on
+// dark surfaces. Painting the tint over the glyph in an offscreen layer and
+// clipping it to the alpha mask with `SRC_IN` keeps the color a plain
+// `ResourceColor`, so it still resolves per theme.
+@ComponentV2
+export struct TemplateIcon {
+  @Require @Param src: Resource;
+  @Param iconWidth: number = 24;
+  @Param iconHeight: number = 24;
+  @Param tint: ResourceColor = INK;
+
+  build() {
+    Stack() {
+      Image(this.src)
+        .width(this.iconWidth)
+        .height(this.iconHeight)
+        .objectFit(ImageFit.Contain)
+        .draggable(false)
+      Text('')
+        .width(this.iconWidth)
+        .height(this.iconHeight)
+        .backgroundColor(this.tint)
+        .blendMode(BlendMode.SRC_IN)
+    }
+    .width(this.iconWidth)
+    .height(this.iconHeight)
+    .blendMode(BlendMode.SRC_OVER, BlendApplyType.OFFSCREEN)
+  }
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ThinkingBlock.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ThinkingBlock.ets
index 42a9a75af5..216b458b39 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ThinkingBlock.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ThinkingBlock.ets
@@ -1,3 +1,5 @@
+import { RemoteI18n } from '../../i18n/RemoteI18n';
+import { ThinkingPresentationPolicy } from '../policy/ThinkingPresentationPolicy';
 import { MUTED } from './Theme';
 
 @ComponentV2
@@ -7,53 +9,123 @@ export struct ThinkingBlock {
   @Param keepExpandedWhenDone: boolean = false;
   @Param streaming: boolean = false;
   @Param streamKey: string = '';
-  @Event onCopyText: (text: string) => void = (_text: string) => {};
   @Local dotPhase: number = 0;
+  @Local expanded: boolean = false;
+  @Local userToggled: boolean = false;
   private dotTimerId: number = 0;
 
   aboutToAppear(): void {
-    if (this.isRunning()) {
-      this.dotTimerId = setInterval(() => {
-        this.dotPhase = (this.dotPhase + 1) % 3;
-      }, 360);
-    }
+    this.userToggled = false;
+    this.expanded = ThinkingPresentationPolicy.defaultExpanded(this.isRunning(), this.keepExpandedWhenDone);
+    this.syncDotTimer();
   }
 
   aboutToDisappear(): void {
-    if (this.dotTimerId !== 0) {
-      clearInterval(this.dotTimerId);
-      this.dotTimerId = 0;
+    this.stopDotTimer();
+  }
+
+  @Monitor('status')
+  onStatusChanged(): void {
+    this.expanded = ThinkingPresentationPolicy.expandedForStatus(
+      this.isRunning(),
+      this.keepExpandedWhenDone,
+      this.userToggled,
+      this.expanded
+    );
+    if (!this.isRunning()) {
+      this.userToggled = false;
     }
+    this.syncDotTimer();
   }
 
   build() {
-    if (this.isRunning()) {
-      Row({ space: 6 }) {
-        Text('•')
-          .width(6)
-          .height(18)
-          .fontSize(16)
-          .fontColor(MUTED)
-          .opacity(this.dotOpacity(0))
-          .animation({ duration: 180, curve: Curve.EaseInOut })
-        Text('•')
-          .width(6)
-          .height(18)
-          .fontSize(16)
-          .fontColor(MUTED)
-          .opacity(this.dotOpacity(1))
-          .animation({ duration: 180, curve: Curve.EaseInOut })
-        Text('•')
-          .width(6)
-          .height(18)
-          .fontSize(16)
+    if (ThinkingPresentationPolicy.shouldRender(this.status, this.text)) {
+      Column({ space: 8 }) {
+        this.HeaderRow()
+        if (this.expanded && this.hasBody()) {
+          Text(this.text)
+            .fontSize(14)
+            .lineHeight(21)
+            .fontColor(MUTED)
+            .width('100%')
+        }
+      }
+      .width('100%')
+      .padding({ left: 2, right: 2, top: 2, bottom: this.expanded && this.hasBody() ? 8 : 2 })
+    }
+  }
+
+  @Builder
+  HeaderRow() {
+    Row({ space: 8 }) {
+      Row({ space: 8 }) {
+        if (this.isRunning()) {
+          this.RunningDots()
+        } else if (this.expanded) {
+          SymbolGlyph($r('sys.symbol.chevron_down'))
+            .fontSize(14)
+            .fontColor([MUTED])
+            .width(16)
+            .height(16)
+        } else {
+          SymbolGlyph($r('sys.symbol.chevron_right'))
+            .fontSize(14)
+            .fontColor([MUTED])
+            .width(16)
+            .height(16)
+        }
+        Text(this.isRunning() ? RemoteI18n.t('chat.thinkingInProgress') : RemoteI18n.t('chat.thinkingComplete'))
+          .fontSize(13)
+          .fontWeight(FontWeight.Medium)
           .fontColor(MUTED)
-          .opacity(this.dotOpacity(2))
-          .animation({ duration: 180, curve: Curve.EaseInOut })
+          .layoutWeight(1)
       }
-      .height(24)
-      .padding({ left: 2 })
+      .layoutWeight(1)
+      .height(32)
+      .alignItems(VerticalAlign.Center)
+      .onClick(() => {
+        if (!ThinkingPresentationPolicy.allowsToggle(this.hasBody())) {
+          return;
+        }
+        this.userToggled = this.isRunning();
+        this.expanded = !this.expanded;
+      })
+      .accessibilityText(this.isRunning() ?
+        RemoteI18n.t('chat.thinkingInProgress') :
+        RemoteI18n.t('chat.thinkingComplete'))
+    }
+    .width('100%')
+    .height(32)
+    .alignItems(VerticalAlign.Center)
+  }
+
+  @Builder
+  RunningDots() {
+    Row({ space: 6 }) {
+      Text('•')
+        .width(6)
+        .height(18)
+        .fontSize(16)
+        .fontColor(MUTED)
+        .opacity(this.dotOpacity(0))
+        .animation({ duration: 180, curve: Curve.EaseInOut })
+      Text('•')
+        .width(6)
+        .height(18)
+        .fontSize(16)
+        .fontColor(MUTED)
+        .opacity(this.dotOpacity(1))
+        .animation({ duration: 180, curve: Curve.EaseInOut })
+      Text('•')
+        .width(6)
+        .height(18)
+        .fontSize(16)
+        .fontColor(MUTED)
+        .opacity(this.dotOpacity(2))
+        .animation({ duration: 180, curve: Curve.EaseInOut })
     }
+    .width(22)
+    .height(18)
   }
 
   private dotOpacity(index: number): number {
@@ -61,7 +133,29 @@ export struct ThinkingBlock {
   }
 
   private isRunning(): boolean {
-    const normalized = (this.status || '').toLowerCase();
-    return normalized === 'active' || normalized === 'running';
+    return ThinkingPresentationPolicy.isRunning(this.status);
+  }
+
+  private hasBody(): boolean {
+    return this.text.trim().length > 0;
+  }
+
+  private syncDotTimer(): void {
+    if (this.isRunning()) {
+      if (this.dotTimerId === 0) {
+        this.dotTimerId = setInterval(() => {
+          this.dotPhase = (this.dotPhase + 1) % 3;
+        }, 360);
+      }
+      return;
+    }
+    this.stopDotTimer();
+  }
+
+  private stopDotTimer(): void {
+    if (this.dotTimerId !== 0) {
+      clearInterval(this.dotTimerId);
+      this.dotTimerId = 0;
+    }
   }
 }
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ToolInteractionPanels.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ToolInteractionPanels.ets
index 9af587e2af..5427bad5a4 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ToolInteractionPanels.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ToolInteractionPanels.ets
@@ -1,7 +1,23 @@
 import { RemoteI18n } from '../../i18n/RemoteI18n';
-import { ConversationUiQuestionAnswer } from './ConversationUiModels';
+import { ConversationUiQuestionAnswer } from '../state/ConversationUiModels';
 import { ACCENT, CARD, INK, LINE, MUTED, PRIMARY_ACTION_TEXT, RED, SOFT } from './Theme';
 
+interface QuestionOption {
+  label: string;
+  description?: string;
+}
+
+interface QuestionInput {
+  question: string;
+  header: string;
+  options: QuestionOption[];
+  multiSelect?: boolean;
+}
+
+interface QuestionPayload {
+  questions?: QuestionInput[];
+}
+
 @ComponentV2
 export struct ToolConfirmationPanel {
   @Param toolId: string = '';
@@ -116,36 +132,38 @@ export struct ToolConfirmationPanel {
 @ComponentV2
 export struct ToolQuestionAnswerPanel {
   @Param toolId: string = '';
-  @Param prompt: string = '';
+  @Param questionsJson: string = '';
+  @Param isBusy: boolean = false;
   @Event onAnswerQuestion: (toolId: string, answers: ConversationUiQuestionAnswer) => void =
     (_toolId: string, _answers: ConversationUiQuestionAnswer) => {};
-  @Local answerText: string = '';
+  @Local questions: QuestionInput[] = [];
+  @Local selectedAnswers: Map<number, string[]> = new Map<number, string[]>();
+  @Local customAnswers: Map<number, string> = new Map<number, string>();
+
+  aboutToAppear(): void {
+    this.questions = this.parseQuestions(this.questionsJson);
+  }
+
+  @Monitor('questionsJson')
+  onQuestionsChanged(): void {
+    this.questions = this.parseQuestions(this.questionsJson);
+    this.selectedAnswers = new Map<number, string[]>();
+    this.customAnswers = new Map<number, string>();
+  }
 
   build() {
     Column({ space: 8 }) {
-      Text(this.prompt)
-        .fontSize(12)
-        .lineHeight(17)
-        .fontColor(INK)
-        .width('100%')
-      TextArea({ placeholder: RemoteI18n.t('chat.answerPlaceholder'), text: this.answerText })
-        .height(78)
-        .fontSize(13)
-        .backgroundColor(CARD)
-        .borderRadius(14)
-        .padding(12)
-        .border({ width: 1, color: LINE })
-        .defaultFocus(false)
-        .enabled(true)
-        .onChange((value: string) => { this.answerText = value; })
+      ForEach(this.questions, (question: QuestionInput, index: number) => {
+        this.Question(question, index);
+      }, (question: QuestionInput, index: number) => `${index}:${question.header}:${question.question}`)
       Row() {
         Text(RemoteI18n.t('chat.submitAnswer'))
-          .fontSize(12)
-          .fontColor(this.canSubmit() ? PRIMARY_ACTION_TEXT : MUTED)
+          .fontSize(12).fontColor(this.canSubmit() ? PRIMARY_ACTION_TEXT : MUTED)
           .textAlign(TextAlign.Center)
           .height(32)
           .layoutWeight(1)
           .backgroundColor(this.canSubmit() ? ACCENT : SOFT)
+          .opacity(this.isBusy ? 0.5 : 1)
           .borderRadius(16)
           .onClick(() => this.submit())
       }
@@ -155,17 +173,137 @@ export struct ToolQuestionAnswerPanel {
     .padding({ left: 30 })
   }
 
+  @Builder
+  private Question(question: QuestionInput, index: number) {
+    Column({ space: 6 }) {
+      Text(question.header.length > 0 ? `${question.header}  ${question.question}` : question.question)
+        .fontSize(12).lineHeight(17).fontColor(INK).width('100%')
+      ForEach(question.options, (option: QuestionOption) => {
+        this.OptionRow(option, index, question.multiSelect === true)
+      }, (option: QuestionOption) => option.label)
+      if (this.isOtherSelected(index)) {
+        TextArea({ placeholder: RemoteI18n.t('chat.answerPlaceholder'), text: this.customAnswers.get(index) || '' })
+          .height(64).fontSize(12).backgroundColor(CARD).borderRadius(10).padding(10)
+          .border({ width: 1, color: LINE }).defaultFocus(false).enabled(!this.isBusy)
+          .onChange((value: string) => {
+            const next = new Map<number, string>(this.customAnswers);
+            next.set(index, value);
+            this.customAnswers = next;
+          })
+      }
+    }
+    .width('100%')
+  }
+
+  // The label is the thing being chosen, so it wraps rather than truncates: an
+  // option the user cannot read in full is one they cannot pick with any
+  // confidence. That rules out a fixed row height and a side-by-side
+  // description, which on a phone leaves the label a sliver of the row.
+  @Builder
+  private OptionRow(option: QuestionOption, index: number, multiSelect: boolean) {
+    Row({ space: 8 }) {
+      SymbolGlyph(this.isSelected(index, option.label) ?
+        $r('sys.symbol.checkmark_circle_fill') : $r('sys.symbol.circle'))
+        .fontSize(18)
+        .fontColor([this.isSelected(index, option.label) ? INK : MUTED])
+        .width(20)
+      Column({ space: 3 }) {
+        Text(option.label)
+          .fontSize(12)
+          .lineHeight(17)
+          .fontColor(INK)
+          .width('100%')
+        if (option.description && option.description.length > 0) {
+          Text(option.description)
+            .fontSize(11)
+            .lineHeight(15)
+            .fontColor(MUTED)
+            .maxLines(3)
+            .textOverflow({ overflow: TextOverflow.Ellipsis })
+            .width('100%')
+        }
+      }
+      .layoutWeight(1)
+      .alignItems(HorizontalAlign.Start)
+    }
+    .width('100%')
+    .alignItems(VerticalAlign.Top)
+    .padding({ left: 10, right: 10, top: 9, bottom: 9 })
+    .backgroundColor(this.isSelected(index, option.label) ? SOFT : CARD).borderRadius(10)
+    .onClick(() => this.toggleOption(index, option.label, multiSelect))
+  }
+
   private canSubmit(): boolean {
-    return this.toolId.length > 0 && this.answerText.trim().length > 0;
+    if (this.isBusy || this.toolId.length === 0 || this.questions.length === 0) {
+      return false;
+    }
+    return this.questions.every((_question: QuestionInput, index: number) => {
+      const selected = this.selectedAnswers.get(index) || [];
+      if (selected.length === 0) return false;
+      return !this.isOtherSelected(index) || (this.customAnswers.get(index) || '').trim().length > 0;
+    });
+  }
+
+  private isSelected(index: number, label: string): boolean {
+    return (this.selectedAnswers.get(index) || []).indexOf(label) >= 0;
+  }
+
+  private isOtherSelected(index: number): boolean {
+    return this.isSelected(index, RemoteI18n.t('common.other'));
+  }
+
+  private toggleOption(index: number, label: string, multiSelect: boolean): void {
+    if (this.isBusy) return;
+    const current = (this.selectedAnswers.get(index) || []).slice();
+    if (multiSelect) {
+      const position = current.indexOf(label);
+      if (position >= 0) current.splice(position, 1);
+      else current.push(label);
+    } else {
+      current.splice(0, current.length, label);
+    }
+    const next = new Map<number, string[]>(this.selectedAnswers);
+    next.set(index, current);
+    this.selectedAnswers = next;
   }
 
   private submit(): void {
     if (!this.canSubmit()) {
       return;
     }
-    const answer = this.answerText.trim();
-    const answers: ConversationUiQuestionAnswer = { answer, '0': answer };
+    const answers: ConversationUiQuestionAnswer = {};
+    this.questions.forEach((question: QuestionInput, index: number) => {
+      const selected = (this.selectedAnswers.get(index) || []).map((value: string) => {
+        return value === RemoteI18n.t('common.other') ? (this.customAnswers.get(index) || '').trim() : value;
+      });
+      const value: string | string[] = question.multiSelect === true ? selected : selected[0];
+      (answers as Record<string, Object>)[`${index}`] = value as Object;
+    });
     this.onAnswerQuestion(this.toolId, answers);
-    this.answerText = '';
+  }
+
+  private parseQuestions(value: string): QuestionInput[] {
+    try {
+      const payload = JSON.parse(value) as QuestionPayload;
+      return (payload.questions || []).map((question: QuestionInput) => this.normalizeQuestion(question))
+        .filter((question: QuestionInput) => question.question.length > 0);
+    } catch (_err) {
+      return [];
+    }
+  }
+
+  private normalizeQuestion(question: QuestionInput): QuestionInput {
+    const normalized: QuestionInput = {
+      question: question.question || '',
+      header: question.header || '',
+      options: (question.options || []).slice(),
+      multiSelect: question.multiSelect === true
+    };
+    const otherLabel = RemoteI18n.t('common.other');
+    if (!normalized.options.some((option: QuestionOption) => option.label.trim().toLowerCase() === 'other' ||
+      option.label === otherLabel)) {
+      normalized.options.push({ label: otherLabel, description: '' });
+    }
+    return normalized;
   }
 }
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ToolStatusList.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ToolStatusList.ets
index bb8c2ed7e9..76129e0c28 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ToolStatusList.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ToolStatusList.ets
@@ -1,6 +1,7 @@
-import { ConversationUiQuestionAnswer, ConversationUiToolStatus } from './ConversationUiModels';
+import { ConversationUiQuestionAnswer, ConversationUiToolStatus } from '../state/ConversationUiModels';
 import { RemoteI18n } from '../../i18n/RemoteI18n';
 import { ToolFileReference, ToolFileReferenceResolver } from '../../services/ToolFileReferenceResolver';
+import { ToolCollapseGroup, ToolCollapsePolicy } from '../policy/ToolCollapsePolicy';
 import { CARD, FILE_LINK, GREEN, INK, LINE, MUTED, RED, SOFT } from './Theme';
 import { ToolGlyph } from './ToolGlyphs';
 import { ToolConfirmationPanel, ToolQuestionAnswerPanel } from './ToolInteractionPanels';
@@ -146,11 +147,12 @@ export struct ToolStatusList {
       if (this.isQuestionTool(tool)) {
         ToolQuestionAnswerPanel({
           toolId: tool.id || '',
-          prompt: this.questionPrompt(tool),
+          questionsJson: this.questionInputJson(tool),
+          isBusy: this.isBusy,
           onAnswerQuestion: this.onAnswerQuestion
         })
       }
-      if (this.isRunningTool(tool)) {
+      if (this.isRunningTool(tool) || this.isQuestionTool(tool)) {
         Row() {
           Blank()
           Text(RemoteI18n.t('chat.cancelTool'))
@@ -335,47 +337,31 @@ export struct ToolStatusList {
   }
 
   private toolRenderEntries(): ToolRenderEntry[] {
-    if (this.expanded) {
-      return this.expandedToolRenderEntries();
-    }
-
+    const groups = this.expanded ?
+      ToolCollapsePolicy.expandedGroups(this.tools) :
+      ToolCollapsePolicy.collapsedGroups(this.tools);
     const entries: ToolRenderEntry[] = [];
-    let collapsed: ConversationUiToolStatus[] = [];
-    let collapsedStart = 0;
-    this.tools.forEach((tool: ConversationUiToolStatus, index: number) => {
-      if (this.shouldCollapseExploreTool(tool)) {
-        if (collapsed.length === 0) {
-          collapsedStart = index;
-        }
-        collapsed.push(tool);
-        return;
-      }
-      this.flushCollapsedTools(entries, collapsed, collapsedStart);
-      collapsed = [];
-      entries.push(this.toolEntry(tool, index));
+    groups.forEach((group: ToolCollapseGroup) => {
+      entries.push(this.entryFromGroup(group));
     });
-    this.flushCollapsedTools(entries, collapsed, collapsedStart);
     return entries;
   }
 
-  private expandedToolRenderEntries(): ToolRenderEntry[] {
-    const entries: ToolRenderEntry[] = [];
-    let collapsed: ConversationUiToolStatus[] = [];
-    let collapsedStart = 0;
-    this.tools.forEach((tool: ConversationUiToolStatus, index: number) => {
-      if (this.shouldCollapseExploreTool(tool)) {
-        if (collapsed.length === 0) {
-          collapsedStart = index;
-        }
-        collapsed.push(tool);
-        return;
-      }
-      this.flushExpandedCollapsedTools(entries, collapsed, collapsedStart);
-      collapsed = [];
-      entries.push(this.toolEntry(tool, index));
-    });
-    this.flushExpandedCollapsedTools(entries, collapsed, collapsedStart);
-    return entries;
+  private entryFromGroup(group: ToolCollapseGroup): ToolRenderEntry {
+    if (group.type === 'summary') {
+      const stats = this.collapsedToolStats(group.tools);
+      return {
+        type: 'summary',
+        key: `summary-${group.startIndex}-${group.tools.length}-${stats.readCount}-${stats.searchCount}-${stats.commandCount}-${stats.otherCount}`,
+        tools: group.tools,
+        readCount: stats.readCount,
+        searchCount: stats.searchCount,
+        commandCount: stats.commandCount,
+        otherCount: stats.otherCount
+      };
+    }
+    const tool = group.tools[0];
+    return this.toolEntry(tool, group.startIndex);
   }
 
   private toolEntry(tool: ConversationUiToolStatus, index: number): ToolRenderEntry {
@@ -391,52 +377,6 @@ export struct ToolStatusList {
     };
   }
 
-  private flushCollapsedTools(
-    entries: ToolRenderEntry[],
-    tools: ConversationUiToolStatus[],
-    startIndex: number
-  ): void {
-    if (tools.length === 0) {
-      return;
-    }
-    if (tools.length < 2) {
-      tools.forEach((tool: ConversationUiToolStatus, index: number) => {
-        entries.push(this.toolEntry(tool, startIndex + index));
-      });
-      return;
-    }
-    const stats = this.collapsedToolStats(tools);
-    entries.push({
-      type: 'summary',
-      key: `summary-${startIndex}-${tools.length}-${stats.readCount}-${stats.searchCount}-${stats.commandCount}-${stats.otherCount}`,
-      tools,
-      readCount: stats.readCount,
-      searchCount: stats.searchCount,
-      commandCount: stats.commandCount,
-      otherCount: stats.otherCount
-    });
-  }
-
-  private flushExpandedCollapsedTools(
-    entries: ToolRenderEntry[],
-    tools: ConversationUiToolStatus[],
-    startIndex: number
-  ): void {
-    if (tools.length === 0) {
-      return;
-    }
-    if (tools.length < 2) {
-      tools.forEach((tool: ConversationUiToolStatus, index: number) => {
-        entries.push(this.toolEntry(tool, startIndex + index));
-      });
-      return;
-    }
-    this.flushCollapsedTools(entries, tools, startIndex);
-    tools.forEach((tool: ConversationUiToolStatus, index: number) => {
-      entries.push(this.toolEntry(tool, startIndex + index));
-    });
-  }
-
   private collapsedToolStats(tools: ConversationUiToolStatus[]): ToolRenderEntry {
     let readCount = 0;
     let searchCount = 0;
@@ -448,7 +388,7 @@ export struct ToolStatusList {
         readCount += 1;
       } else if (kind === 'search') {
         searchCount += 1;
-      } else if (kind === 'command') {
+      } else if (this.isCommandTool(tool)) {
         commandCount += 1;
       } else {
         otherCount += 1;
@@ -465,19 +405,6 @@ export struct ToolStatusList {
     };
   }
 
-  private shouldCollapseExploreTool(tool: ConversationUiToolStatus): boolean {
-    if (this.hasToolError(tool) || this.isPendingConfirmation(tool) || this.isQuestionTool(tool) ||
-      this.isRunningTool(tool)) {
-      return false;
-    }
-    return this.isCollapsibleExploreTool(tool) && (this.isCompletedTool(tool) || this.isCancelledTool(tool));
-  }
-
-  private isCollapsibleExploreTool(tool: ConversationUiToolStatus): boolean {
-    const kind = this.exploreToolKind(tool);
-    return kind === 'read' || kind === 'search';
-  }
-
   private exploreToolKind(tool: ConversationUiToolStatus): string {
     const raw = tool.name || '';
     const normalized = this.normalizedToolName(tool);
@@ -1015,8 +942,8 @@ export struct ToolStatusList {
 
   private isQuestionTool(tool: ConversationUiToolStatus): boolean {
     const status = (tool.status || '').toLowerCase();
-    const name = tool.name || '';
-    return name === 'AskUserQuestion' &&
+    const name = this.normalizedToolName(tool);
+    return (name === 'askuserquestion' || name === 'ask_user_question') &&
       status !== 'completed' &&
       status !== 'done' &&
       status !== 'failed' &&
@@ -1039,6 +966,16 @@ export struct ToolStatusList {
     return this.toolPreview(preview);
   }
 
+  private questionInputJson(tool: ConversationUiToolStatus): string {
+    if (tool.tool_input) {
+      try {
+        return JSON.stringify(tool.tool_input);
+      } catch (_err) {
+      }
+    }
+    return this.toolInputPreview(tool);
+  }
+
   private questionPromptFromJson(preview: string): string {
     if (preview.trim().length === 0) {
       return '';
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/WatchProvisionCard.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/WatchProvisionCard.ets
new file mode 100644
index 0000000000..4e63cdbd6d
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/WatchProvisionCard.ets
@@ -0,0 +1,129 @@
+import { RemoteI18n } from '../../i18n/RemoteI18n';
+import { WatchProvisionPhase, WatchProvisionState } from '../state/WatchProvisionState';
+import { CARD, GREEN, INK, LINE, MODAL_SCRIM, MUTED, PRIMARY_ACTION, PRIMARY_ACTION_TEXT, RED, SOFT } from './Theme';
+
+/**
+ * The one place a watch can be added to the account. It is deliberately modal:
+ * granting a device a 30-day credential should interrupt, not sit in a corner
+ * waiting to be noticed.
+ */
+@ComponentV2
+export struct WatchProvisionCard {
+  @Param state: WatchProvisionState = new WatchProvisionState();
+  @Event onApprove: () => void = () => {};
+  @Event onReject: () => void = () => {};
+  @Event onDismiss: () => void = () => {};
+
+  build() {
+    if (this.state.visible()) {
+      Stack() {
+        Text('')
+          .width('100%')
+          .height('100%')
+          .backgroundColor(MODAL_SCRIM)
+          .onClick(() => {
+            // Tapping away while the desktop is minting would leave the watch
+            // with no answer and no card to explain it.
+            if (this.state.dismissible()) {
+              this.onDismiss();
+            }
+          })
+
+        Column({ space: 18 }) {
+          Text(RemoteI18n.t('watchProvision.title'))
+            .fontSize(23)
+            .fontWeight(FontWeight.Bold)
+            .fontColor(INK)
+            .width('100%')
+
+          Column({ space: 6 }) {
+            Text(this.state.deviceName)
+              .fontSize(18)
+              .fontWeight(FontWeight.Medium)
+              .fontColor(INK)
+              .width('100%')
+              .maxLines(2)
+              .textOverflow({ overflow: TextOverflow.Ellipsis })
+            Text(RemoteI18n.f('watchProvision.deviceId', this.state.deviceIdLabel))
+              .fontSize(14)
+              .fontColor(MUTED)
+              .width('100%')
+          }
+          .width('100%')
+          .padding({ left: 16, right: 16, top: 14, bottom: 14 })
+          .backgroundColor(SOFT)
+          .borderRadius(20)
+
+          if (this.state.phase === WatchProvisionPhase.Asking) {
+            Text(RemoteI18n.t('watchProvision.body'))
+              .fontSize(16)
+              .lineHeight(23)
+              .fontColor(MUTED)
+              .width('100%')
+          } else if (this.state.phase === WatchProvisionPhase.Working) {
+            Row({ space: 10 }) {
+              LoadingProgress()
+                .width(20)
+                .height(20)
+                .color(MUTED)
+              Text(RemoteI18n.t('watchProvision.working'))
+                .fontSize(16)
+                .lineHeight(23)
+                .fontColor(MUTED)
+                .layoutWeight(1)
+            }
+            .width('100%')
+          } else {
+            Text(this.state.message)
+              .fontSize(16)
+              .lineHeight(23)
+              .fontColor(this.state.phase === WatchProvisionPhase.Done ? GREEN : RED)
+              .width('100%')
+          }
+
+          if (this.state.phase === WatchProvisionPhase.Asking) {
+            Row({ space: 12 }) {
+              Button(RemoteI18n.t('watchProvision.reject'))
+                .layoutWeight(1)
+                .height(56)
+                .fontSize(18)
+                .fontWeight(FontWeight.Bold)
+                .fontColor(INK)
+                .backgroundColor(SOFT)
+                .borderRadius(28)
+                .onClick(this.onReject)
+              Button(RemoteI18n.t('watchProvision.approve'))
+                .layoutWeight(1)
+                .height(56)
+                .fontSize(18)
+                .fontWeight(FontWeight.Bold)
+                .fontColor(PRIMARY_ACTION_TEXT)
+                .backgroundColor(PRIMARY_ACTION)
+                .borderRadius(28)
+                .onClick(this.onApprove)
+            }
+            .width('100%')
+          } else if (this.state.phase !== WatchProvisionPhase.Working) {
+            Button(RemoteI18n.t('watchProvision.gotIt'))
+              .width('100%')
+              .height(56)
+              .fontSize(18)
+              .fontWeight(FontWeight.Bold)
+              .fontColor(PRIMARY_ACTION_TEXT)
+              .backgroundColor(PRIMARY_ACTION)
+              .borderRadius(28)
+              .onClick(this.onDismiss)
+          }
+        }
+        .width('82%')
+        .constraintSize({ maxWidth: 520 })
+        .padding({ left: 26, right: 26, top: 28, bottom: 26 })
+        .backgroundColor(CARD)
+        .borderRadius(34)
+        .border({ width: 1, color: LINE })
+      }
+      .width('100%')
+      .height('100%')
+    }
+  }
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/WideConversationHost.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/WideConversationHost.ets
index 8db93d9fac..616833fc5d 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/WideConversationHost.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/WideConversationHost.ets
@@ -246,7 +246,8 @@ export struct WideConversationHost {
 
         if (this.wideMasterPaneCollapsed) {
           SidebarToggleButton({ restore: true, controlSize: 44, onToggle: this.onRestoreMasterPane })
-            .position({ x: this.currentDetailOffset() + 12, y: 12 }).zIndex(2)
+            .position({ x: 12, y: 12 }).zIndex(2)
+            .hitTestBehavior(HitTestMode.Default)
             .transition(TransitionEffect.scale({ x: 0.9, y: 0.9 }).combine(TransitionEffect.opacity(0))
               .animation({ duration: 180, curve: Curve.EaseOut }))
         }
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/remote/RemoteSurfaceHost.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/remote/RemoteSurfaceHost.ets
index 11f1f41e09..e50afb131c 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/remote/RemoteSurfaceHost.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/remote/RemoteSurfaceHost.ets
@@ -1,12 +1,15 @@
 import { RemoteI18n } from '../../../i18n/RemoteI18n';
 import { RemoteSession } from '../../../model/RemoteModels';
+import { RemoteLogger } from '../../../services/RemoteLogger';
+import { RemoteUiState } from '../../../services/RemoteUiState';
 import { RemotePageState } from '../../state/RemotePageState';
 import {
   AppRootPresentationActions,
   emptyAppRootPresentationActions
 } from '../../actions/AppRootPresentationActions';
 import { ConversationViewSettings } from '../ConversationViewSettings';
-import { GeneralChatHeader } from '../GeneralChatHeader';
+import { ConversationHeader } from '../ConversationHeader';
+import { RemoteCompactHomePolicy } from '../../policy/RemoteCompactHomePolicy';
 import { RemoteSessionList } from '../RemoteSessionList';
 import { RemoteSessionLoadingView } from '../RemoteSessionLoadingView';
 import { SidebarToggleButton } from '../SidebarToggleButton';
@@ -53,6 +56,16 @@ export struct RemoteSurfaceHost {
   @Event onRestoreSidebar: () => void = () => {};
   @Event onCloseSettings: () => void = () => {};
 
+  // The wide layout keeps the master pane inside a routed destination, so a
+  // mount here while switching sessions means the navigation stack was torn
+  // down for a change that is only page state — the sidebar rebuild this used
+  // to pay for. See AppShellViewModel.replaceRouteWithoutAnimation.
+  aboutToAppear(): void {
+    RemoteLogger.info(
+      `remote surface mounted mode=${this.mode} connection=${this.remotePageState.connectionState} sessions=${this.remotePageState.visibleSessions().length}`
+    );
+  }
+
   build() {
     if (this.mode === RemoteSurfaceMode.Master) {
       this.MasterContent();
@@ -89,6 +102,9 @@ export struct RemoteSurfaceHost {
           showStatusMetadata: this.presentationState.showStatusMetadata,
           hasMoreSessions: this.remotePageState.hasMoreSessions,
           isBusy: this.remotePageState.conversation.isBusy || this.remotePageState.isLoadingSessions,
+          // A pending id means a row was tapped, whether or not the open is slow
+          // enough to have raised a skeleton. Keying the highlight off the
+          // loading flag instead used to tie selection to how long the load took.
           selectedSessionId: this.remotePageState.pendingSessionId.length > 0 ?
             this.remotePageState.pendingSessionId :
             (this.showSelectedSession ? this.remotePageState.conversation.activeSession.sessionId : ''),
@@ -121,6 +137,17 @@ export struct RemoteSurfaceHost {
         .maxLines(1)
         .textOverflow({ overflow: TextOverflow.Ellipsis })
         .layoutWeight(1)
+      if (this.canReconnect()) {
+        Text(RemoteI18n.t('remote.settings.reconnect'))
+          .fontSize(13)
+          .fontWeight(FontWeight.Medium)
+          .fontColor(PRIMARY_ACTION_TEXT)
+          .height(28)
+          .padding({ left: 12, right: 12 })
+          .backgroundColor(PRIMARY_ACTION)
+          .borderRadius(14)
+          .onClick(() => this.actions.onRemoteHome.reconnect())
+      }
     }
     .width('100%')
     .margin({ top: 16, bottom: 6 })
@@ -129,7 +156,7 @@ export struct RemoteSurfaceHost {
 
   @Builder
   private StatusIndicator() {
-    if (this.isInitialLoading()) {
+    if (this.isSyncing()) {
       LoadingProgress().width(14).height(14).color(MUTED)
     } else {
       Stack() {
@@ -172,16 +199,17 @@ export struct RemoteSurfaceHost {
   @Builder
   private CompactHomeContent() {
     Column() {
-      GeneralChatHeader({
+      ConversationHeader({
         title: RemoteI18n.t('remote.title'),
         subtitle: this.compactHeaderContext(),
+        titleFallback: RemoteI18n.t('remote.title'),
         showSidebarButton: true,
         onOpenSidebar: this.onOpenSidebar
       })
-      if (this.canShowSessionList()) {
-        this.CompactEmptyState()
-      } else {
+      if (RemoteCompactHomePolicy.shouldShowConnectHome(this.remotePageState.connectionState)) {
         this.DisconnectedState()
+      } else {
+        this.CompactEmptyState()
       }
     }
     .width('100%')
@@ -201,11 +229,22 @@ export struct RemoteSurfaceHost {
         .fontSize(14).lineHeight(21).fontColor(MUTED).maxLines(2)
         .textOverflow({ overflow: TextOverflow.Ellipsis }).textAlign(TextAlign.Center)
         .constraintSize({ maxWidth: 280 })
-      Text(RemoteI18n.t('remote.startSession'))
-        .width(148).height(46).fontSize(15).fontWeight(FontWeight.Medium)
-        .fontColor(PRIMARY_ACTION_TEXT).backgroundColor(PRIMARY_ACTION)
-        .textAlign(TextAlign.Center).borderRadius(23).margin({ top: 12 })
-        .onClick(() => this.actions.onRemoteHome.createAssistant())
+      // Starting a session needs a desktop on the other end, so while the link
+      // is down the button that is actually useful is the one that brings it
+      // back up.
+      if (this.canReconnect()) {
+        Text(RemoteI18n.t('remote.settings.reconnect'))
+          .width(148).height(46).fontSize(15).fontWeight(FontWeight.Medium)
+          .fontColor(PRIMARY_ACTION_TEXT).backgroundColor(PRIMARY_ACTION)
+          .textAlign(TextAlign.Center).borderRadius(23).margin({ top: 12 })
+          .onClick(() => this.actions.onRemoteHome.reconnect())
+      } else {
+        Text(RemoteI18n.t('remote.startSession'))
+          .width(148).height(46).fontSize(15).fontWeight(FontWeight.Medium)
+          .fontColor(PRIMARY_ACTION_TEXT).backgroundColor(PRIMARY_ACTION)
+          .textAlign(TextAlign.Center).borderRadius(23).margin({ top: 12 })
+          .onClick(() => this.actions.onRemoteHome.createAssistant())
+      }
     }
     .width('100%').layoutWeight(1).justifyContent(FlexAlign.Center)
     .alignItems(HorizontalAlign.Center).padding({ left: 24, right: 24, bottom: 56 })
@@ -304,13 +343,41 @@ export struct RemoteSurfaceHost {
     this.actions.onRemoteHome.createAssistant();
   }
 
+  /**
+   * Whether the surface still owes the user a way back onto a desktop.
+   *
+   * The connect button used to live only on the disconnected placeholder, so
+   * the moment a restored session list took that placeholder's place there was
+   * no entry point left anywhere on the surface — a list from the cache reads
+   * as "connected" while nothing is. Offering it from the status row instead
+   * keeps the two independent: the list says what the phone knows, this says
+   * whether the desktop is answering.
+   */
+  private canReconnect(): boolean {
+    return !RemoteUiState.canUseRemote(this.remotePageState.connectionState) && !this.isSyncing();
+  }
+
   private canShowSessionList(): boolean {
     return this.remotePageState.connectionState === 'connected' ||
       this.remotePageState.visibleSessions().length > 0 ||
       this.remotePageState.isLoadingHome || this.remotePageState.isLoadingSessions;
   }
 
+  /**
+   * Only the first load gets a skeleton. Once there are sessions to show — from
+   * this connection or from the cache a launch restored — connecting is a
+   * refresh happening behind a usable list, and replacing that list with
+   * placeholder rows would be a step backwards.
+   */
   private isInitialLoading(): boolean {
+    if (this.remotePageState.sessions.length > 0) {
+      return false;
+    }
+    return this.isSyncing();
+  }
+
+  /** Work in progress, whether or not there is already a list behind it. */
+  private isSyncing(): boolean {
     return this.remotePageState.isLoadingHome || this.isConnecting();
   }
 
@@ -341,7 +408,10 @@ export struct RemoteSurfaceHost {
    * the connect state does not advertise a stale desktop.
    */
   private compactHeaderContext(): string {
-    return this.canShowSessionList() ? this.remotePageState.desktopName : '';
+    return RemoteCompactHomePolicy.headerSubtitle(
+      this.remotePageState.connectionState,
+      this.remotePageState.desktopName
+    );
   }
 
   private desktopName(): string {
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/AccountDeviceSelectionPolicy.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/AccountDeviceSelectionPolicy.ets
new file mode 100644
index 0000000000..2a85a48f80
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/AccountDeviceSelectionPolicy.ets
@@ -0,0 +1,52 @@
+/**
+ * Shared selection rules for the account-device list on Connect and Settings.
+ * Online desktops can be selected. The last control target can still be tapped
+ * to reconnect after the live link drops, even if presence already reads offline.
+ */
+export class AccountDeviceSelectionPolicy {
+  static canSelectOnline(
+    online: boolean,
+    deviceId: string,
+    phoneDeviceId: string,
+    switchingDeviceId: string
+  ): boolean {
+    return online && deviceId !== phoneDeviceId && switchingDeviceId.length === 0;
+  }
+
+  static shouldReconnectLastTarget(
+    deviceId: string,
+    controlTargetDeviceId: string,
+    connectionState: string
+  ): boolean {
+    return deviceId.length > 0 &&
+      deviceId === controlTargetDeviceId &&
+      connectionState !== 'connected';
+  }
+
+  static canActivate(
+    online: boolean,
+    deviceId: string,
+    phoneDeviceId: string,
+    controlTargetDeviceId: string,
+    connectionState: string,
+    switchingDeviceId: string
+  ): boolean {
+    if (switchingDeviceId.length > 0) {
+      return false;
+    }
+    return AccountDeviceSelectionPolicy.canSelectOnline(online, deviceId, phoneDeviceId, switchingDeviceId) ||
+      AccountDeviceSelectionPolicy.shouldReconnectLastTarget(deviceId, controlTargetDeviceId, connectionState);
+  }
+
+  static shouldShowConnectAction(
+    online: boolean,
+    deviceId: string,
+    phoneDeviceId: string,
+    controlTargetDeviceId: string,
+    connectionState: string
+  ): boolean {
+    return AccountDeviceSelectionPolicy.canActivate(
+      online, deviceId, phoneDeviceId, controlTargetDeviceId, connectionState, ''
+    ) && !(deviceId === controlTargetDeviceId && connectionState === 'connected');
+  }
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/ActivityGroupPolicy.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/ActivityGroupPolicy.ets
new file mode 100644
index 0000000000..762bf9d127
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/ActivityGroupPolicy.ets
@@ -0,0 +1,25 @@
+import { ConversationUiToolStatus } from '../state/ConversationUiModels';
+import { ToolCollapsePolicy } from './ToolCollapsePolicy';
+
+export class ActivityGroupPolicy {
+  static shouldFoldEntry(
+    isThinking: boolean,
+    isSubagent: boolean,
+    tool?: ConversationUiToolStatus
+  ): boolean {
+    if (isThinking) {
+      return true;
+    }
+    if (isSubagent || !tool) {
+      return false;
+    }
+    return ToolCollapsePolicy.shouldFoldIntoSummary(tool);
+  }
+
+  static thinkingHeaderCount(thinkingPartCount: number): number {
+    if (thinkingPartCount <= 0) {
+      return 0;
+    }
+    return 1;
+  }
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/AssistantProcessLayoutPolicy.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/AssistantProcessLayoutPolicy.ets
new file mode 100644
index 0000000000..703986caab
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/AssistantProcessLayoutPolicy.ets
@@ -0,0 +1,53 @@
+export class AssistantProcessLayoutPolicy {
+  /**
+   * Streaming used to pin the current thinking block after tools so the
+   * viewport could chase it. That inverts chronology: a Task card appears
+   * above the thought that produced it. Keep thinking in document order.
+   */
+  static pinsThinkingAfterTools(): boolean {
+    return false;
+  }
+
+  static omitsInFlowThinkingWhileStreaming(): boolean {
+    return false;
+  }
+
+  static shouldRenderActivityThinking(hasContent: boolean): boolean {
+    return hasContent;
+  }
+
+  static processBlockOrder(
+    thinkingText: string,
+    hasStructuredThinking: boolean,
+    visibleText: string,
+    showTyping: boolean,
+    toolCount: number
+  ): string[] {
+    const order: string[] = [];
+    const hasLeadingThinking = thinkingText.trim().length > 0 && !hasStructuredThinking;
+    if (hasLeadingThinking || hasStructuredThinking) {
+      order.push('thinking');
+    }
+    if (toolCount > 0) {
+      order.push('tools');
+    }
+    if (showTyping) {
+      order.push('typing');
+    }
+    if (visibleText.trim().length > 0 && visibleText.trim() !== thinkingText.trim()) {
+      order.push('text');
+    }
+    return order;
+  }
+
+  static activityGroupBlockOrder(hasThinking: boolean, toolCount: number): string[] {
+    const order: string[] = [];
+    if (hasThinking) {
+      order.push('thinking');
+    }
+    if (toolCount > 0) {
+      order.push('tools');
+    }
+    return order;
+  }
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/ConnectSheetLandingPolicy.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/ConnectSheetLandingPolicy.ets
new file mode 100644
index 0000000000..6d90249bd6
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/ConnectSheetLandingPolicy.ets
@@ -0,0 +1,80 @@
+import { CONNECT_INTENT_SCAN } from '../state/AppShellState';
+
+export class ConnectSheetStep {
+  static readonly Intro: string = 'intro';
+  static readonly Scan: string = 'scan';
+  static readonly Account: string = 'account';
+}
+
+/**
+ * Where the connect sheet should open, and which step it may keep showing.
+ *
+ * The camera is a named action, not the default: an unsigned-in first open
+ * has to explain that the pair code comes from the desktop. A signed-in phone
+ * already has an account device list. Only an entry that promised the scanner
+ * may land on it.
+ */
+export class ConnectSheetLandingPolicy {
+  static initialStep(openIntent: string, accountAuthenticated: boolean): string {
+    if (openIntent === CONNECT_INTENT_SCAN) {
+      return ConnectSheetStep.Scan;
+    }
+    if (accountAuthenticated) {
+      return ConnectSheetStep.Account;
+    }
+    return ConnectSheetStep.Intro;
+  }
+
+  static visibleStep(pairingStep: string, accountAuthenticated: boolean): string {
+    if (pairingStep === ConnectSheetStep.Account && accountAuthenticated) {
+      return ConnectSheetStep.Account;
+    }
+    if (pairingStep === ConnectSheetStep.Scan) {
+      return ConnectSheetStep.Scan;
+    }
+    return ConnectSheetStep.Intro;
+  }
+}
+
+export class ConnectSheetStatusPolicy {
+  static isConnectError(
+    connectionState: string,
+    isBusy: boolean,
+    isConnected: boolean,
+    statusText: string,
+    failedLabel: string,
+    missingParams: string,
+    urlRequired: string
+  ): boolean {
+    if (connectionState === 'failed') {
+      return true;
+    }
+    if (isBusy || isConnected) {
+      return false;
+    }
+    const text = statusText.toLowerCase();
+    return text.indexOf('http') >= 0 ||
+      text.indexOf('error') >= 0 ||
+      text.indexOf('failed') >= 0 ||
+      text.indexOf(failedLabel.toLowerCase()) >= 0 ||
+      statusText === missingParams ||
+      statusText === urlRequired ||
+      text.indexOf('rejected') >= 0;
+  }
+
+  static failureHintKey(kind: string): string {
+    if (kind === 'expired_room') {
+      return 'connect.hintExpiredRoom';
+    }
+    if (kind === 'network') {
+      return 'connect.hintNetwork';
+    }
+    if (kind === 'protected_user') {
+      return 'connect.hintProtectedUser';
+    }
+    if (kind === 'invalid_link') {
+      return 'connect.hintInvalidLink';
+    }
+    return '';
+  }
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/ConversationHeaderPolicy.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/ConversationHeaderPolicy.ets
new file mode 100644
index 0000000000..4531abc170
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/ConversationHeaderPolicy.ets
@@ -0,0 +1,68 @@
+import { ChatSurface } from '../state/ChatSurface';
+
+export class ConversationHeaderPresentation {
+  title: string = '';
+  subtitle: string = '';
+  fallbackKey: string = 'app.title';
+  allowRename: boolean = false;
+  showActions: boolean = false;
+
+  constructor(
+    title: string,
+    subtitle: string,
+    fallbackKey: string,
+    allowRename: boolean,
+    showActions: boolean
+  ) {
+    this.title = title;
+    this.subtitle = subtitle;
+    this.fallbackKey = fallbackKey;
+    this.allowRename = allowRename;
+    this.showActions = showActions;
+  }
+}
+
+/**
+ * One header contract for local chat, remote chat, create, and remote home.
+ * View supplies i18n for fallbackKey; this policy only decides structure.
+ */
+export class ConversationHeaderPolicy {
+  static readonly REMOTE_BRAND: string = 'BitFun';
+
+  static present(
+    surface: ChatSurface,
+    sessionTitle: string,
+    desktopName: string,
+    workspaceBranch: string,
+    hasTimeline: boolean
+  ): ConversationHeaderPresentation {
+    if (surface === ChatSurface.Create) {
+      return new ConversationHeaderPresentation('', '', 'remote.create.title', false, false);
+    }
+    if (surface === ChatSurface.Remote) {
+      return new ConversationHeaderPresentation(
+        sessionTitle,
+        ConversationHeaderPolicy.remoteSubtitle(desktopName, workspaceBranch),
+        'chat.remoteSession',
+        true,
+        true
+      );
+    }
+    return new ConversationHeaderPresentation(
+      sessionTitle,
+      '',
+      'app.title',
+      false,
+      hasTimeline
+    );
+  }
+
+  static remoteSubtitle(desktopName: string, workspaceBranch: string): string {
+    if (desktopName.length > 0) {
+      return desktopName;
+    }
+    return workspaceBranch.length > 0 ?
+      `${ConversationHeaderPolicy.REMOTE_BRAND} · ${workspaceBranch}` :
+      ConversationHeaderPolicy.REMOTE_BRAND;
+  }
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/ConversationLayoutPolicy.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/ConversationLayoutPolicy.ets
index f6a011f6d8..600e44f52f 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/ConversationLayoutPolicy.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/ConversationLayoutPolicy.ets
@@ -47,31 +47,40 @@ class ConversationLayoutSegment {
 }
 
 export class ConversationLayoutPolicy {
-  static readonly TABLET_DEVICE_TYPE: string = 'tablet';
-  static readonly WIDE_LAYOUT_MIN_WIDTH: number = 720;
+  /** Official GridRow sm|md boundary: 320 / 600 / 840 / 1440 vp. */
+  static readonly MD_MIN_WIDTH: number = 600;
+  static readonly LG_MIN_WIDTH: number = 840;
+  static readonly XL_MIN_WIDTH: number = 1440;
+  static readonly WIDE_LAYOUT_MIN_WIDTH: number = 600;
+  static readonly EXTRA_WIDE_MIN_WIDTH: number = 840;
   static readonly FALLBACK_MASTER_PANE_WIDTH: number = 344;
   static readonly MIN_MASTER_PANE_WIDTH: number = 280;
   static readonly MIN_DETAIL_PANE_WIDTH: number = 360;
-  static readonly EXTRA_WIDE_MIN_WIDTH: number = 1080;
+  static readonly SYNTHETIC_HINGE_WIDTH: number = 16;
 
   static useMasterDetail(
     viewportWidth: number,
     mediaQueryMatched: boolean,
     isFolded: boolean,
-    deviceType: string,
-    creases: ConversationLayoutCrease[]
+    creases: ConversationLayoutCrease[],
+    isExpandedFoldable: boolean = false,
+    isHover: boolean = false
   ): boolean {
-    if (isFolded) {
+    if (isFolded || isHover) {
       return false;
     }
     if (!ConversationLayoutPolicy.hasWideViewport(viewportWidth, mediaQueryMatched)) {
       return false;
     }
-    const visibleCreases = ConversationLayoutPolicy.visibleCreases(viewportWidth, creases);
+    const visibleCreases = ConversationLayoutPolicy.effectiveVerticalCreases(
+      viewportWidth,
+      creases,
+      isExpandedFoldable
+    );
     if (visibleCreases.length > 0) {
-      return visibleCreases.length >= 2;
+      return ConversationLayoutPolicy.canFitMasterDetail(viewportWidth, visibleCreases);
     }
-    return ConversationLayoutPolicy.isTabletDevice(deviceType);
+    return ConversationLayoutPolicy.canFitMasterDetail(viewportWidth, []);
   }
 
   static resolveWideGeometry(
@@ -79,28 +88,71 @@ export class ConversationLayoutPolicy {
     creases: ConversationLayoutCrease[]
   ): ConversationLayoutGeometry {
     const visibleCreases = ConversationLayoutPolicy.visibleCreases(viewportWidth, creases);
-    const firstCrease = visibleCreases.find((crease: ConversationLayoutCrease): boolean => {
-      return crease.left >= ConversationLayoutPolicy.MIN_MASTER_PANE_WIDTH &&
-        crease.left + crease.width <= viewportWidth - ConversationLayoutPolicy.MIN_DETAIL_PANE_WIDTH;
-    });
+    const firstCrease = ConversationLayoutPolicy.firstUsableCrease(viewportWidth, visibleCreases);
     const masterPaneWidth = firstCrease ? firstCrease.left :
-      ConversationLayoutPolicy.FALLBACK_MASTER_PANE_WIDTH;
+      ConversationLayoutPolicy.fallbackMasterPaneWidth(viewportWidth);
     const masterDetailGap = firstCrease ? Math.max(0, firstCrease.width) : 0;
     const detailStart = masterPaneWidth + masterDetailGap;
     const detailSegments = ConversationLayoutPolicy.detailSegments(viewportWidth, detailStart, visibleCreases);
     const contentSegment = ConversationLayoutPolicy.widestSegment(detailSegments);
-    const collapsedContentSegment = ConversationLayoutPolicy.widestSegment(
-      ConversationLayoutPolicy.detailSegments(viewportWidth, 0, visibleCreases)
+    const collapsedContentSegment = ConversationLayoutPolicy.collapsedContentSegment(
+      viewportWidth,
+      visibleCreases
     );
     return new ConversationLayoutGeometry(
       masterPaneWidth,
       masterDetailGap,
-      visibleCreases.length > 1 || viewportWidth >= ConversationLayoutPolicy.EXTRA_WIDE_MIN_WIDTH,
+      visibleCreases.length > 1 || viewportWidth >= ConversationLayoutPolicy.LG_MIN_WIDTH,
       contentSegment ? contentSegment.left - detailStart : 0,
       contentSegment ? contentSegment.width : 0,
-      collapsedContentSegment ? collapsedContentSegment.left : 0,
-      collapsedContentSegment ? collapsedContentSegment.width : 0
+      collapsedContentSegment.left,
+      collapsedContentSegment.width
+    );
+  }
+
+  private static collapsedContentSegment(
+    viewportWidth: number,
+    visibleCreases: ConversationLayoutCrease[]
+  ): ConversationLayoutSegment {
+    if (visibleCreases.length <= 1) {
+      return new ConversationLayoutSegment(0, Math.max(0, viewportWidth));
+    }
+    const widest = ConversationLayoutPolicy.widestSegment(
+      ConversationLayoutPolicy.detailSegments(viewportWidth, 0, visibleCreases)
+    );
+    return widest ? widest : new ConversationLayoutSegment(0, Math.max(0, viewportWidth));
+  }
+
+  static effectiveVerticalCreases(
+    viewportWidth: number,
+    creases: ConversationLayoutCrease[],
+    synthesizeCenterHinge: boolean
+  ): ConversationLayoutCrease[] {
+    const visibleCreases = ConversationLayoutPolicy.visibleCreases(viewportWidth, creases);
+    if (visibleCreases.length > 0) {
+      return visibleCreases;
+    }
+    if (!synthesizeCenterHinge) {
+      return [];
+    }
+    const synthetic = ConversationLayoutPolicy.syntheticCenterCrease(viewportWidth);
+    return synthetic ? [synthetic] : [];
+  }
+
+  static syntheticCenterCrease(viewportWidth: number): ConversationLayoutCrease | undefined {
+    const hinge = ConversationLayoutPolicy.SYNTHETIC_HINGE_WIDTH;
+    const minimum = ConversationLayoutPolicy.MIN_MASTER_PANE_WIDTH +
+      ConversationLayoutPolicy.MIN_DETAIL_PANE_WIDTH + hinge;
+    if (viewportWidth < minimum) {
+      return undefined;
+    }
+    const centered = Math.floor((viewportWidth - hinge) / 2);
+    const maximumMaster = viewportWidth - hinge - ConversationLayoutPolicy.MIN_DETAIL_PANE_WIDTH;
+    const masterPaneWidth = Math.max(
+      ConversationLayoutPolicy.MIN_MASTER_PANE_WIDTH,
+      Math.min(centered, maximumMaster)
     );
+    return new ConversationLayoutCrease(masterPaneWidth, hinge);
   }
 
   private static detailSegments(
@@ -135,12 +187,38 @@ export class ConversationLayoutPolicy {
     }, undefined);
   }
 
-  private static hasWideViewport(viewportWidth: number, mediaQueryMatched: boolean): boolean {
-    return mediaQueryMatched || viewportWidth >= ConversationLayoutPolicy.WIDE_LAYOUT_MIN_WIDTH;
+  private static canFitMasterDetail(
+    viewportWidth: number,
+    visibleCreases: ConversationLayoutCrease[]
+  ): boolean {
+    const firstCrease = ConversationLayoutPolicy.firstUsableCrease(viewportWidth, visibleCreases);
+    const masterPaneWidth = firstCrease ? firstCrease.left :
+      ConversationLayoutPolicy.fallbackMasterPaneWidth(viewportWidth);
+    const masterDetailGap = firstCrease ? Math.max(0, firstCrease.width) : 0;
+    return masterPaneWidth >= ConversationLayoutPolicy.MIN_MASTER_PANE_WIDTH &&
+      viewportWidth - masterPaneWidth - masterDetailGap >= ConversationLayoutPolicy.MIN_DETAIL_PANE_WIDTH;
   }
 
-  private static isTabletDevice(deviceType: string): boolean {
-    return deviceType.toLowerCase() === ConversationLayoutPolicy.TABLET_DEVICE_TYPE;
+  private static fallbackMasterPaneWidth(viewportWidth: number): number {
+    const maximumMaster = viewportWidth - ConversationLayoutPolicy.MIN_DETAIL_PANE_WIDTH;
+    if (maximumMaster < ConversationLayoutPolicy.MIN_MASTER_PANE_WIDTH) {
+      return ConversationLayoutPolicy.FALLBACK_MASTER_PANE_WIDTH;
+    }
+    return Math.min(ConversationLayoutPolicy.FALLBACK_MASTER_PANE_WIDTH, maximumMaster);
+  }
+
+  private static firstUsableCrease(
+    viewportWidth: number,
+    visibleCreases: ConversationLayoutCrease[]
+  ): ConversationLayoutCrease | undefined {
+    return visibleCreases.find((crease: ConversationLayoutCrease): boolean => {
+      return crease.left >= ConversationLayoutPolicy.MIN_MASTER_PANE_WIDTH &&
+        crease.left + crease.width <= viewportWidth - ConversationLayoutPolicy.MIN_DETAIL_PANE_WIDTH;
+    });
+  }
+
+  private static hasWideViewport(viewportWidth: number, mediaQueryMatched: boolean): boolean {
+    return mediaQueryMatched || viewportWidth >= ConversationLayoutPolicy.MD_MIN_WIDTH;
   }
 
   private static visibleCreases(
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/ConversationMessageRenderPolicy.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/ConversationMessageRenderPolicy.ets
new file mode 100644
index 0000000000..e9c075c733
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/ConversationMessageRenderPolicy.ets
@@ -0,0 +1,44 @@
+import { ConversationUiMessage, ConversationUiMessageItem } from '../state/ConversationUiModels';
+
+export class ConversationMessageRenderPolicy {
+  static visibleText(text?: string): string {
+    const value = (text || '').trim();
+    if (value === '(空消息)' || value === '(empty message)') {
+      return '';
+    }
+    return value;
+  }
+
+  static shouldRender(item: ConversationUiMessage): boolean {
+    if ((item.role || '').toLowerCase() === 'user') {
+      return true;
+    }
+    if (ConversationMessageRenderPolicy.visibleText(item.text).length > 0) {
+      return true;
+    }
+    if ((item.thinking || '').trim().length > 0) {
+      return true;
+    }
+    if (item.tools && item.tools.length > 0) {
+      return true;
+    }
+    if (ConversationMessageRenderPolicy.hasRenderableItems(item.items || [])) {
+      return true;
+    }
+    if (item.images && item.images.length > 0) {
+      return true;
+    }
+    const status = (item.status || '').toLowerCase();
+    return status === 'active' || status === 'failed';
+  }
+
+  static hasRenderableItems(items: ConversationUiMessageItem[]): boolean {
+    return items.some((entry: ConversationUiMessageItem) => {
+      if ((entry.content || '').trim().length > 0 || !!entry.tool) {
+        return true;
+      }
+      return !!entry.subItems && ConversationMessageRenderPolicy.hasRenderableItems(entry.subItems);
+    });
+  }
+
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/ConversationModelPresentationPolicy.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/ConversationModelPresentationPolicy.ets
index 9d60fafb3e..d99c447ef4 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/ConversationModelPresentationPolicy.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/ConversationModelPresentationPolicy.ets
@@ -1,7 +1,7 @@
 import {
   ConversationUiModel,
   ConversationUiModelCatalog
-} from '../components/ConversationUiModels';
+} from '../state/ConversationUiModels';
 
 export class ConversationModelPresentationPolicy {
   static enabledModels(catalog: ConversationUiModelCatalog): ConversationUiModel[] {
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/ConversationSessionFilterPolicy.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/ConversationSessionFilterPolicy.ets
index 0ab0183dd2..9ef633a22b 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/ConversationSessionFilterPolicy.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/ConversationSessionFilterPolicy.ets
@@ -41,7 +41,8 @@ export class ConversationSessionFilterPolicy {
       ConversationSessionFilterPolicy.normalizeWorkspacePath(right);
   }
 
-  private static normalizeWorkspacePath(path: string): string {
+  /** Public so a caller can bucket by workspace instead of comparing pairwise. */
+  static normalizeWorkspacePath(path: string): string {
     let value = path.trim();
     while (value.length > 1 && (value.endsWith('/') || value.endsWith('\\'))) {
       value = value.slice(0, value.length - 1);
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/FilePreviewPlacementPolicy.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/FilePreviewPlacementPolicy.ets
index c7da144bda..1c48faac00 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/FilePreviewPlacementPolicy.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/FilePreviewPlacementPolicy.ets
@@ -76,6 +76,10 @@ export class FilePreviewPlacementPolicy {
     if (creaseLayout) {
       return creaseLayout;
     }
+    const creaseFocusLayout = FilePreviewPlacementPolicy.creaseAlignedFocusSplit(viewportWidth, creases);
+    if (creaseFocusLayout) {
+      return creaseFocusLayout;
+    }
     const flatLayout = FilePreviewPlacementPolicy.flatTriplePane(
       viewportWidth,
       creases,
@@ -144,6 +148,31 @@ export class FilePreviewPlacementPolicy {
     );
   }
 
+  private static creaseAlignedFocusSplit(
+    viewportWidth: number,
+    creases: ConversationLayoutCrease[]
+  ): FilePreviewLayout | undefined {
+    const visible = FilePreviewPlacementPolicy.visibleCreases(viewportWidth, creases);
+    if (visible.length !== 1) {
+      return undefined;
+    }
+    const crease = visible[0];
+    const conversationWidth = crease.left;
+    const previewWidth = viewportWidth - crease.left - crease.width;
+    if (conversationWidth < FilePreviewPlacementPolicy.MIN_CONVERSATION_WIDTH ||
+      previewWidth < FilePreviewPlacementPolicy.MIN_PREVIEW_WIDTH) {
+      return undefined;
+    }
+    return new FilePreviewLayout(
+      FilePreviewPlacement.WideFocusSplit,
+      0,
+      0,
+      conversationWidth,
+      crease.width,
+      previewWidth
+    );
+  }
+
   private static creaseAlignedTriplePane(
     viewportWidth: number,
     creases: ConversationLayoutCrease[]
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/RemoteCompactHomePolicy.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/RemoteCompactHomePolicy.ets
new file mode 100644
index 0000000000..90512a27ca
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/RemoteCompactHomePolicy.ets
@@ -0,0 +1,19 @@
+/**
+ * Compact Remote Home is conversation chrome, not a session list.
+ *
+ * The sidebar may keep a cached list after the desktop drops so the user can
+ * still see what the phone already knows. Compact home must not treat that
+ * cache as a live link: "pick a session" only belongs on a connected desktop.
+ */
+export class RemoteCompactHomePolicy {
+  static shouldShowConnectHome(connectionState: string): boolean {
+    return connectionState !== 'connected';
+  }
+
+  static headerSubtitle(connectionState: string, desktopName: string): string {
+    if (RemoteCompactHomePolicy.shouldShowConnectHome(connectionState)) {
+      return '';
+    }
+    return desktopName;
+  }
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/RemoteSurfaceEntryPolicy.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/RemoteSurfaceEntryPolicy.ets
new file mode 100644
index 0000000000..36c4cfc30e
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/RemoteSurfaceEntryPolicy.ets
@@ -0,0 +1,16 @@
+export class RemoteConnectEntryKind {
+  static readonly EnterSurface: string = 'enter_surface';
+  static readonly OpenConnect: string = 'open_connect';
+  static readonly OpenScan: string = 'open_scan';
+}
+
+/**
+ * Switching to Remote is a change of context. Opening the connect sheet is a
+ * command to pair or pick a desktop. Those two must not share an entry point.
+ */
+export class RemoteSurfaceEntryPolicy {
+  static shouldOpenConnectSheet(kind: string): boolean {
+    return kind === RemoteConnectEntryKind.OpenConnect ||
+      kind === RemoteConnectEntryKind.OpenScan;
+  }
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/SessionListProjection.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/SessionListProjection.ets
new file mode 100644
index 0000000000..3085e8af4a
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/SessionListProjection.ets
@@ -0,0 +1,373 @@
+import { RecentWorkspaceEntry, RemoteSession } from '../../model/RemoteModels';
+import { RemoteI18n } from '../../i18n/RemoteI18n';
+import { TimeFormat } from '../../services/TimeFormat';
+import { ConversationSessionFilterPolicy } from './ConversationSessionFilterPolicy';
+
+/** Everything the sidebar's grouping depends on. */
+export interface SessionListInputs {
+  sessions: RemoteSession[];
+  query: string;
+  sortMode: string;
+  workspaceName: string;
+  workspacePath: string;
+  workspaceKind: string;
+  recentWorkspaces: RecentWorkspaceEntry[];
+  workspaceFilter: string;
+  agentFilter: string;
+  statusFilter: string;
+  showWorkspaceMetadata: boolean;
+  showUpdatedMetadata: boolean;
+  showStatusMetadata: boolean;
+}
+
+/**
+ * The session list, already filtered, grouped and labelled.
+ *
+ * Every array here is shared, not copied, and must be treated as read-only:
+ * a cache hands the same instance to every caller until the inputs change.
+ */
+export interface SessionListProjection {
+  filtered: RemoteSession[];
+  chats: RemoteSession[];
+  byTime: RemoteSession[];
+  today: RemoteSession[];
+  yesterday: RemoteSession[];
+  earlier: RemoteSession[];
+  projects: RecentWorkspaceEntry[];
+  projectSessions: Map<string, RemoteSession[]>;
+  metadata: Map<string, string>;
+  hasActiveFilter: boolean;
+}
+
+const EMPTY_SESSIONS: RemoteSession[] = [];
+
+/**
+ * Turns the raw session list into the shape the sidebar renders, in one pass.
+ *
+ * The sidebar used to derive this inline, and its builders asked for the
+ * derived values rather than holding them: `filteredSessions()` alone was
+ * reached around twenty times per build — once per section header, once per
+ * project group, three times per row — and re-scanned the whole array every
+ * time, each scan re-deciding whether a session was an assistant session by
+ * searching the recent-workspace list again. Traced on device, one selection
+ * change spent 690ms inside the list's rerender with no child layout beneath
+ * it: all of it was this arithmetic, run again for inputs that had not moved.
+ */
+export class SessionListProjector {
+  static project(inputs: SessionListInputs): SessionListProjection {
+    const assistantPaths: Set<string> = SessionListProjector.assistantWorkspacePaths(inputs.recentWorkspaces);
+    const hasActiveFilter = inputs.query.trim().length > 0 || inputs.workspaceFilter.length > 0 ||
+      inputs.agentFilter.length > 0 || inputs.statusFilter.length > 0;
+    const wantsMetadata = inputs.showWorkspaceMetadata || inputs.showUpdatedMetadata || inputs.showStatusMetadata;
+
+    const filtered: RemoteSession[] = [];
+    const chats: RemoteSession[] = [];
+    const projectSessions: Map<string, RemoteSession[]> = new Map();
+    const metadata: Map<string, string> = new Map();
+    const nowMs = Date.now();
+
+    inputs.sessions.forEach((item: RemoteSession) => {
+      // Decided once and carried through the rest of the pass. It is the
+      // expensive predicate — it searches the recent-workspace list — and it
+      // feeds the filter, the chat/project split and the agent grouping alike.
+      const assistant = SessionListProjector.isAssistantSession(item, inputs, assistantPaths);
+      const matches = ConversationSessionFilterPolicy.matches(
+        item,
+        inputs.query,
+        inputs.workspacePath,
+        inputs.workspaceFilter,
+        inputs.agentFilter,
+        inputs.statusFilter,
+        assistant
+      );
+      if (!matches) {
+        return;
+      }
+      filtered.push(item);
+      if (assistant) {
+        chats.push(item);
+      } else {
+        const key = ConversationSessionFilterPolicy.normalizeWorkspacePath(
+          item.workspacePath ? item.workspacePath : inputs.workspacePath);
+        const bucket = projectSessions.get(key);
+        if (bucket === undefined) {
+          projectSessions.set(key, [item]);
+        } else {
+          bucket.push(item);
+        }
+      }
+      if (wantsMetadata) {
+        metadata.set(item.id, SessionListProjector.metadataText(item, inputs, nowMs));
+      }
+    });
+
+    const projects = SessionListProjector.projectEntries(inputs, assistantPaths, hasActiveFilter, projectSessions);
+    // Sorting by time parses two timestamps per session per comparison, so it
+    // stays behind the mode that asks for it.
+    const byTime = inputs.sortMode === 'time' ? SessionListProjector.sortByTime(filtered) : EMPTY_SESSIONS;
+
+    return {
+      filtered,
+      chats,
+      byTime,
+      today: SessionListProjector.bucket(byTime, 'today', nowMs),
+      yesterday: SessionListProjector.bucket(byTime, 'yesterday', nowMs),
+      earlier: SessionListProjector.bucket(byTime, 'earlier', nowMs),
+      projects,
+      projectSessions,
+      metadata,
+      hasActiveFilter
+    };
+  }
+
+  /** The sessions filed under a workspace, or an empty list when there are none. */
+  static sessionsForProject(projection: SessionListProjection, path: string): RemoteSession[] {
+    const bucket = projection.projectSessions.get(ConversationSessionFilterPolicy.normalizeWorkspacePath(path));
+    return bucket === undefined ? EMPTY_SESSIONS : bucket;
+  }
+
+  static metadataFor(projection: SessionListProjection, sessionId: string): string {
+    const value = projection.metadata.get(sessionId);
+    return value === undefined ? '' : value;
+  }
+
+  static empty(): SessionListProjection {
+    return {
+      filtered: EMPTY_SESSIONS,
+      chats: EMPTY_SESSIONS,
+      byTime: EMPTY_SESSIONS,
+      today: EMPTY_SESSIONS,
+      yesterday: EMPTY_SESSIONS,
+      earlier: EMPTY_SESSIONS,
+      projects: [],
+      projectSessions: new Map(),
+      metadata: new Map(),
+      hasActiveFilter: false
+    };
+  }
+
+  private static assistantWorkspacePaths(entries: RecentWorkspaceEntry[]): Set<string> {
+    const paths: Set<string> = new Set();
+    entries.forEach((item: RecentWorkspaceEntry) => {
+      if (item.workspaceKind.toLowerCase() === 'assistant') {
+        paths.add(item.path);
+      }
+    });
+    return paths;
+  }
+
+  private static isAssistantWorkspace(
+    path: string,
+    inputs: SessionListInputs,
+    assistantPaths: Set<string>
+  ): boolean {
+    if (path.length === 0) {
+      return inputs.workspaceKind.toLowerCase() === 'assistant';
+    }
+    if (path === inputs.workspacePath && inputs.workspaceKind.toLowerCase() === 'assistant') {
+      return true;
+    }
+    return assistantPaths.has(path);
+  }
+
+  private static isAssistantSession(
+    item: RemoteSession,
+    inputs: SessionListInputs,
+    assistantPaths: Set<string>
+  ): boolean {
+    const agentType = (item.agentType ? item.agentType : '').toLowerCase();
+    if (agentType === 'claw' || agentType === 'assistant' || agentType === 'chat') {
+      return true;
+    }
+    return SessionListProjector.isAssistantWorkspace(
+      item.workspacePath ? item.workspacePath : '', inputs, assistantPaths);
+  }
+
+  private static projectEntries(
+    inputs: SessionListInputs,
+    assistantPaths: Set<string>,
+    hasActiveFilter: boolean,
+    projectSessions: Map<string, RemoteSession[]>
+  ): RecentWorkspaceEntry[] {
+    const entries: RecentWorkspaceEntry[] = [];
+    const currentIsAssistant = SessionListProjector.isAssistantWorkspace(inputs.workspacePath, inputs, assistantPaths);
+    if ((inputs.workspacePath.length > 0 || inputs.workspaceName.length > 0) && !currentIsAssistant) {
+      entries.push({
+        path: inputs.workspacePath,
+        name: inputs.workspaceName,
+        lastOpened: '',
+        workspaceKind: 'normal'
+      });
+    }
+    inputs.recentWorkspaces.forEach((item: RecentWorkspaceEntry) => {
+      if (item.path.length === 0 ||
+        SessionListProjector.isAssistantWorkspace(item.path, inputs, assistantPaths)) {
+        return;
+      }
+      if (entries.some((entry: RecentWorkspaceEntry) => entry.path === item.path)) {
+        return;
+      }
+      entries.push(item);
+    });
+    if (!hasActiveFilter) {
+      return entries;
+    }
+    // A filter narrow enough to empty a project takes that project's header off
+    // the list too, so the sidebar does not read as a wall of empty groups.
+    return entries.filter((item: RecentWorkspaceEntry) => {
+      const bucket = projectSessions.get(ConversationSessionFilterPolicy.normalizeWorkspacePath(item.path));
+      return bucket !== undefined && bucket.length > 0;
+    });
+  }
+
+  private static sortByTime(sessions: RemoteSession[]): RemoteSession[] {
+    // Timestamps are parsed once each and sorted alongside their session, rather
+    // than re-parsed inside the comparator for every comparison it makes.
+    const stamped: TimestampedSession[] = sessions.map((item: RemoteSession): TimestampedSession => {
+      return { session: item, timestamp: SessionListProjector.sessionTimestamp(item) };
+    });
+    stamped.sort((left: TimestampedSession, right: TimestampedSession) => right.timestamp - left.timestamp);
+    return stamped.map((item: TimestampedSession) => item.session);
+  }
+
+  private static bucket(sessions: RemoteSession[], bucket: string, nowMs: number): RemoteSession[] {
+    if (sessions.length === 0) {
+      return EMPTY_SESSIONS;
+    }
+    return sessions.filter((item: RemoteSession) => SessionListProjector.timeBucket(item, nowMs) === bucket);
+  }
+
+  private static timeBucket(item: RemoteSession, nowMs: number): string {
+    const timestamp = SessionListProjector.sessionTimestamp(item);
+    if (timestamp <= 0) {
+      return 'earlier';
+    }
+    const sessionDate = new Date(timestamp);
+    const now = new Date(nowMs);
+    if (SessionListProjector.sameCalendarDay(sessionDate, now)) {
+      return 'today';
+    }
+    const yesterday = new Date(now.getFullYear(), now.getMonth(), now.getDate() - 1);
+    return SessionListProjector.sameCalendarDay(sessionDate, yesterday) ? 'yesterday' : 'earlier';
+  }
+
+  private static sessionTimestamp(item: RemoteSession): number {
+    const updated = TimeFormat.timestampMs(item.updatedAt ? item.updatedAt : '');
+    if (!Number.isNaN(updated) && updated > 0) {
+      return updated;
+    }
+    const created = TimeFormat.timestampMs(item.createdAt ? item.createdAt : '');
+    return !Number.isNaN(created) && created > 0 ? created : 0;
+  }
+
+  private static sameCalendarDay(left: Date, right: Date): boolean {
+    return left.getFullYear() === right.getFullYear() &&
+      left.getMonth() === right.getMonth() &&
+      left.getDate() === right.getDate();
+  }
+
+  private static metadataText(item: RemoteSession, inputs: SessionListInputs, nowMs: number): string {
+    const values: string[] = [];
+    if (inputs.showWorkspaceMetadata) {
+      const workspace = item.workspaceName ? item.workspaceName : (item.workspacePath ? item.workspacePath : '');
+      if (workspace.length > 0) {
+        values.push(workspace);
+      }
+    }
+    if (inputs.showUpdatedMetadata && !Number.isNaN(TimeFormat.timestampMs(item.updatedAt))) {
+      values.push(TimeFormat.relative(item.updatedAt, nowMs));
+    }
+    if (inputs.showStatusMetadata && item.status.length > 0) {
+      values.push(item.status === 'archived' ? RemoteI18n.t('sidebar.archived') : item.status);
+    }
+    return values.join(' · ');
+  }
+}
+
+interface TimestampedSession {
+  session: RemoteSession;
+  timestamp: number;
+}
+
+/**
+ * Holds the last projection and rebuilds it only when its inputs move.
+ *
+ * The point of the cache is the selection change: picking a session rebuilds
+ * the sidebar's whole builder tree, but touches none of the inputs here, so the
+ * rerender becomes a property diff over lists that were already computed.
+ *
+ * The fast path is reference identity on the two arrays. When that misses —
+ * a caller handing out a freshly filtered array each build would defeat it —
+ * the contents are compared field by field, which is still one cheap pass
+ * instead of twenty expensive ones.
+ */
+export class SessionListProjectionCache {
+  private key: string = '';
+  private sessionsRef: RemoteSession[] = EMPTY_SESSIONS;
+  private workspacesRef: RecentWorkspaceEntry[] = [];
+  private sessionFingerprint: string[] = [];
+  private workspaceFingerprint: string[] = [];
+  private projection: SessionListProjection = SessionListProjector.empty();
+
+  get(inputs: SessionListInputs): SessionListProjection {
+    const key = SessionListProjectionCache.scalarKey(inputs);
+    if (key === this.key && inputs.sessions === this.sessionsRef &&
+      inputs.recentWorkspaces === this.workspacesRef) {
+      return this.projection;
+    }
+    const sessionFingerprint = SessionListProjectionCache.sessionFingerprint(inputs.sessions);
+    const workspaceFingerprint = SessionListProjectionCache.workspaceFingerprint(inputs.recentWorkspaces);
+    if (key === this.key &&
+      SessionListProjectionCache.sameFingerprint(sessionFingerprint, this.sessionFingerprint) &&
+      SessionListProjectionCache.sameFingerprint(workspaceFingerprint, this.workspaceFingerprint)) {
+      // Same contents behind a new array. Adopt the new references so the next
+      // call takes the identity fast path.
+      this.sessionsRef = inputs.sessions;
+      this.workspacesRef = inputs.recentWorkspaces;
+      return this.projection;
+    }
+    this.key = key;
+    this.sessionsRef = inputs.sessions;
+    this.workspacesRef = inputs.recentWorkspaces;
+    this.sessionFingerprint = sessionFingerprint;
+    this.workspaceFingerprint = workspaceFingerprint;
+    this.projection = SessionListProjector.project(inputs);
+    return this.projection;
+  }
+
+  private static scalarKey(inputs: SessionListInputs): string {
+    // Relative timestamps are rendered from the projection, so when they are on
+    // screen the minute they were rendered in is part of what the projection
+    // depends on. Off — which is the default — nothing here moves on its own.
+    const minute = inputs.showUpdatedMetadata ? Math.floor(Date.now() / 60000) : 0;
+    return `${inputs.query}${inputs.sortMode}${inputs.workspaceName}${inputs.workspacePath}` +
+      `${inputs.workspaceKind}${inputs.workspaceFilter}${inputs.agentFilter}` +
+      `${inputs.statusFilter}${inputs.showWorkspaceMetadata ? 1 : 0}` +
+      `${inputs.showUpdatedMetadata ? 1 : 0}${inputs.showStatusMetadata ? 1 : 0}${minute}`;
+  }
+
+  private static sessionFingerprint(sessions: RemoteSession[]): string[] {
+    return sessions.map((item: RemoteSession): string => {
+      return `${item.id}
${item.title}
${item.status}
${item.agentType}` +
+        `
${item.workspacePath}
${item.workspaceName}
${item.updatedAt}
${item.createdAt}`;
+    });
+  }
+
+  private static workspaceFingerprint(entries: RecentWorkspaceEntry[]): string[] {
+    return entries.map((item: RecentWorkspaceEntry): string => {
+      return `${item.path}
${item.name}
${item.workspaceKind}`;
+    });
+  }
+
+  private static sameFingerprint(left: string[], right: string[]): boolean {
+    if (left.length !== right.length) {
+      return false;
+    }
+    for (let index = 0; index < left.length; index++) {
+      if (left[index] !== right[index]) {
+        return false;
+      }
+    }
+    return true;
+  }
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/ThinkingPresentationPolicy.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/ThinkingPresentationPolicy.ets
new file mode 100644
index 0000000000..84df0b152f
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/ThinkingPresentationPolicy.ets
@@ -0,0 +1,77 @@
+export class ThinkingPresentationPolicy {
+  static isRunning(status: string): boolean {
+    const normalized = (status || '').toLowerCase();
+    return normalized === 'active' || normalized === 'running';
+  }
+
+  static shouldRender(status: string, text: string): boolean {
+    if (ThinkingPresentationPolicy.isRunning(status)) {
+      return true;
+    }
+    return text.trim().length > 0;
+  }
+
+  static defaultExpanded(isRunning: boolean, keepExpandedWhenDone: boolean): boolean {
+    return isRunning || keepExpandedWhenDone;
+  }
+
+  static allowsToggle(hasBody: boolean): boolean {
+    return hasBody;
+  }
+
+  /**
+   * Option 2: the live thinking block starts expanded. The user may collapse it
+   * while it streams. Completing always folds it back unless keepExpandedWhenDone.
+   */
+  static expandedForStatus(
+    isRunning: boolean,
+    keepExpandedWhenDone: boolean,
+    userToggled: boolean,
+    currentlyExpanded: boolean
+  ): boolean {
+    if (!isRunning) {
+      return keepExpandedWhenDone;
+    }
+    if (userToggled) {
+      return currentlyExpanded;
+    }
+    return true;
+  }
+
+  static liveThinkingStatus(messageStatus: string, hasLaterOutput: boolean): string {
+    if (hasLaterOutput) {
+      return 'done';
+    }
+    return messageStatus;
+  }
+
+  static mergedText(parts: string[]): string {
+    const kept: string[] = [];
+    parts.forEach((part: string) => {
+      const text = (part || '').trim();
+      if (text.length > 0) {
+        kept.push(text);
+      }
+    });
+    return kept.join('\n\n');
+  }
+
+  static mergedStatusValue(statuses: string[], streamings: boolean[]): string {
+    const count = statuses.length > streamings.length ? statuses.length : streamings.length;
+    for (let index = count - 1; index >= 0; index--) {
+      const streaming = index < streamings.length ? streamings[index] : false;
+      const status = index < statuses.length ? statuses[index] : '';
+      if (streaming || ThinkingPresentationPolicy.isRunning(status)) {
+        return status.length > 0 ? status : 'active';
+      }
+    }
+    if (statuses.length > 0 && statuses[statuses.length - 1].length > 0) {
+      return statuses[statuses.length - 1];
+    }
+    return 'done';
+  }
+
+  static mergedStreaming(streamings: boolean[]): boolean {
+    return streamings.some((streaming: boolean) => streaming);
+  }
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/ToolCollapsePolicy.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/ToolCollapsePolicy.ets
new file mode 100644
index 0000000000..98ea29c0f4
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/policy/ToolCollapsePolicy.ets
@@ -0,0 +1,133 @@
+import { ConversationUiToolStatus } from '../state/ConversationUiModels';
+
+export class ToolCollapseGroup {
+  readonly type: string;
+  readonly startIndex: number;
+  readonly tools: ConversationUiToolStatus[];
+
+  constructor(type: string, startIndex: number, tools: ConversationUiToolStatus[]) {
+    this.type = type;
+    this.startIndex = startIndex;
+    this.tools = tools;
+  }
+}
+
+export class ToolCollapsePolicy {
+  static readonly MIN_SUMMARY_COUNT: number = 2;
+
+  static defaultSubagentExpanded(isRunning: boolean): boolean {
+    return isRunning;
+  }
+
+  static subagentExpandedForStatus(
+    isRunning: boolean,
+    userToggled: boolean,
+    currentlyExpanded: boolean
+  ): boolean {
+    if (!isRunning) {
+      return false;
+    }
+    if (userToggled) {
+      return currentlyExpanded;
+    }
+    return true;
+  }
+
+  static shouldFoldIntoSummary(tool: ConversationUiToolStatus): boolean {
+    if (ToolCollapsePolicy.hasError(tool) ||
+      ToolCollapsePolicy.isPending(tool) ||
+      ToolCollapsePolicy.isQuestion(tool) ||
+      ToolCollapsePolicy.isRunning(tool)) {
+      return false;
+    }
+    return ToolCollapsePolicy.isCompleted(tool) || ToolCollapsePolicy.isCancelled(tool);
+  }
+
+  static collapsedGroups(tools: ConversationUiToolStatus[]): ToolCollapseGroup[] {
+    return ToolCollapsePolicy.groupTools(tools, false);
+  }
+
+  static expandedGroups(tools: ConversationUiToolStatus[]): ToolCollapseGroup[] {
+    return ToolCollapsePolicy.groupTools(tools, true);
+  }
+
+  private static groupTools(
+    tools: ConversationUiToolStatus[],
+    includeMembers: boolean
+  ): ToolCollapseGroup[] {
+    const groups: ToolCollapseGroup[] = [];
+    let folded: ConversationUiToolStatus[] = [];
+    let foldedStart = 0;
+    tools.forEach((tool: ConversationUiToolStatus, index: number) => {
+      if (ToolCollapsePolicy.shouldFoldIntoSummary(tool)) {
+        if (folded.length === 0) {
+          foldedStart = index;
+        }
+        folded.push(tool);
+        return;
+      }
+      ToolCollapsePolicy.flushFolded(groups, folded, foldedStart, includeMembers);
+      folded = [];
+      groups.push(new ToolCollapseGroup('tool', index, [tool]));
+    });
+    ToolCollapsePolicy.flushFolded(groups, folded, foldedStart, includeMembers);
+    return groups;
+  }
+
+  private static flushFolded(
+    groups: ToolCollapseGroup[],
+    tools: ConversationUiToolStatus[],
+    startIndex: number,
+    includeMembers: boolean
+  ): void {
+    if (tools.length === 0) {
+      return;
+    }
+    if (tools.length < ToolCollapsePolicy.MIN_SUMMARY_COUNT) {
+      tools.forEach((tool: ConversationUiToolStatus, offset: number) => {
+        groups.push(new ToolCollapseGroup('tool', startIndex + offset, [tool]));
+      });
+      return;
+    }
+    groups.push(new ToolCollapseGroup('summary', startIndex, tools));
+    if (includeMembers) {
+      tools.forEach((tool: ConversationUiToolStatus, offset: number) => {
+        groups.push(new ToolCollapseGroup('tool', startIndex + offset, [tool]));
+      });
+    }
+  }
+
+  private static isRunning(tool: ConversationUiToolStatus): boolean {
+    const normalized = (tool.status || '').toLowerCase();
+    return normalized === 'running' || normalized === 'active';
+  }
+
+  private static isCompleted(tool: ConversationUiToolStatus): boolean {
+    const normalized = (tool.status || '').toLowerCase();
+    return normalized === 'completed' || normalized === 'done' || normalized === 'success';
+  }
+
+  private static isCancelled(tool: ConversationUiToolStatus): boolean {
+    const normalized = (tool.status || '').toLowerCase();
+    return normalized === 'cancelled' || normalized === 'canceled';
+  }
+
+  private static isPending(tool: ConversationUiToolStatus): boolean {
+    const normalized = (tool.status || '').toLowerCase();
+    return normalized === 'pending' || normalized === 'queued' ||
+      normalized === 'pending_confirmation' || normalized === 'needs_confirmation';
+  }
+
+  private static isQuestion(tool: ConversationUiToolStatus): boolean {
+    const raw = tool.name || '';
+    const normalized = raw.replace(/[\s-]/g, '_').toLowerCase();
+    return raw === 'AskUserQuestion' || normalized === 'askuserquestion' ||
+      normalized === 'ask_user_question';
+  }
+
+  private static hasError(tool: ConversationUiToolStatus): boolean {
+    const normalized = (tool.status || '').toLowerCase();
+    return normalized === 'failed' || normalized === 'error' || normalized === 'timeout' ||
+      (tool.error_preview || '').length > 0;
+  }
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/runtime/AppRootRuntime.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/runtime/AppRootRuntime.ets
index 7d34cede75..42f4b56499 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/runtime/AppRootRuntime.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/runtime/AppRootRuntime.ets
@@ -5,6 +5,7 @@ import { CloudAccountDevice } from '../../services/CloudAccountClient';
 import { RemoteLogger } from '../../services/RemoteLogger';
 import { RemoteUiState } from '../../services/RemoteUiState';
 import { AppRootHostPort } from '../host/AppRootHostAdapter';
+import { CONNECT_INTENT_SCAN } from '../state/AppShellState';
 import {
   AppNavigationBackAction,
   AppRoute,
@@ -23,15 +24,37 @@ export class AppRootRuntime extends AppRootRuntimeComposition {
 
   async aboutToAppear(): Promise<void> {
     this.syncRemotePageSummary();
+    await this.remoteChatCache.init(this.host.context());
+    await this.remoteSessionListCache.init(this.host.context());
+    await this.restoreCachedRemoteSessions();
     await this.generalChatBootstrapController.restore(this.host.context());
     await this.settingsController.initializeCloudAccount(this.host.context());
     await this.settingsController.refreshModelCatalog();
     await this.restoreIdentity();
+    await this.startWatchProvisioning();
+  }
+
+  /**
+   * Only ask for distributed data sync once the phone actually has something to
+   * provision a watch with. A fresh install has nothing, and a permission
+   * prompt at first launch would have no explanation behind it.
+   *
+   * A signed-in account counts on its own, with no desktop in sight: the phone
+   * mints the watch's credential itself in that case, so waiting for a live
+   * connection would keep the listener down exactly when it is not needed.
+   */
+  private async startWatchProvisioning(): Promise<void> {
+    if (!this.settingsController.hasCloudAccountSession() && !this.hasRemoteBindingForResume()) {
+      return;
+    }
+    await this.watchProvisionController.start(this.host.context());
   }
 
   onPageShow(): void {
     RemoteLogger.info(`page show state=${(this.remotePageState.connectionState as ConnectionState)} route=${this.appShellViewModel.currentRoute()}`);
     this.remoteActivityViewModel.resume();
+    // Idempotent: covers the pairing that happened after the last cold start.
+    void this.startWatchProvisioning();
   }
 
   onPageHide(): void {
@@ -43,6 +66,7 @@ export class AppRootRuntime extends AppRootRuntimeComposition {
   }
 
   aboutToDisappear(): void {
+    this.watchProvisionController.stop();
     this.remoteActivityViewModel.invalidate();
     this.remoteConnectionCoordinator.invalidate();
     this.remotePageState.setBusy(false);
@@ -95,11 +119,36 @@ export class AppRootRuntime extends AppRootRuntimeComposition {
 
   async restoreIdentity(): Promise<void> {
     if (this.remotePageState.controlTargetType === 'account_device') {
+      await this.restoreAccountDeviceTarget(false);
       return;
     }
     await this.remoteConnectionController.restore(this.host.context());
   }
 
+  /**
+   * Reconnects to the desktop the signed-in account was last driving.
+   *
+   * The scanned-room path restores itself from its pairing snapshot, but the
+   * account path used to do nothing at launch: the phone came up holding a
+   * session list and a desktop name with no link behind either, and the only
+   * way back was for the user to walk the device picker again. Announcing
+   * `reconnecting` up front is what keeps that from reading as connected while
+   * the device lookup is still in flight.
+   */
+  private async restoreAccountDeviceTarget(navigateHome: boolean): Promise<void> {
+    const deviceId = this.remotePageState.controlTargetDeviceId.trim();
+    if (deviceId.length === 0) {
+      return;
+    }
+    this.remotePageState.setConnectionState(ConnectionState.Reconnecting);
+    this.remotePageState.setStatusText(RemoteI18n.t('status.restoringConnection'));
+    await this.settingsController.restoreCloudTarget(
+      deviceId,
+      this.remotePageState.controlTargetDeviceName,
+      navigateHome
+    );
+  }
+
   async connect(autoReconnect: boolean = false, accountPassword: string = ''): Promise<void> {
     await this.remoteConnectionController.connect(autoReconnect, accountPassword);
     await this.settingsController.persistDelegatedAccountSession();
@@ -107,10 +156,7 @@ export class AppRootRuntime extends AppRootRuntimeComposition {
 
   async reconnect(): Promise<void> {
     if (this.remotePageState.controlTargetType === 'account_device') {
-      await this.settingsController.restoreCloudTarget(
-        this.remotePageState.controlTargetDeviceId,
-        this.remotePageState.controlTargetDeviceName
-      );
+      await this.restoreAccountDeviceTarget(true);
       return;
     }
     await this.remoteConnectionController.reconnect();
@@ -130,8 +176,20 @@ export class AppRootRuntime extends AppRootRuntimeComposition {
     }
   }
 
+  /**
+   * A request that failed against a link the phone still has a binding for is a
+   * link that dropped, not one that ended, so the heartbeat stays up and its
+   * next ping is what notices the desktop coming back. Killing it here is what
+   * used to make a momentary drop permanent: `failed` disables every remote
+   * action, and nothing was left running to lift it again.
+   */
   failRemoteConnection(err: Object): void {
     this.remotePageState.setStatusText(ConnectionErrorPolicy.errorText(err));
+    if (this.hasRemoteBindingForResume()) {
+      this.remotePageState.setConnectionState(ConnectionState.Reconnecting);
+      this.remoteActivityViewModel.startHeartbeat();
+      return;
+    }
     this.remotePageState.setConnectionState(ConnectionState.Failed);
     this.remoteActivityViewModel.stopHeartbeat();
   }
@@ -158,19 +216,6 @@ export class AppRootRuntime extends AppRootRuntimeComposition {
     });
   }
 
-  enterCodeEntry(): void {
-    if (this.settingsController.hasCloudAccountSession() && this.remotePageState.accountUserId.trim().length > 0) {
-      this.appShellState.setConnectSheetVisible(true);
-      return;
-    }
-    if (RemoteUiState.canUseRemote((this.remotePageState.connectionState as ConnectionState))) {
-      this.appShellState.setConnectSheetVisible(false);
-      this.appShellViewModel.replaceRouteWithoutAnimation(AppRoute.RemoteHome);
-      return;
-    }
-    this.appShellState.setConnectSheetVisible(true);
-  }
-
   async switchWideConversationSource(source: ConversationSource): Promise<void> {
     if (AppRouteContract.conversationSource(this.appShellViewModel.currentRoute()) === source) {
       return;
@@ -262,10 +307,16 @@ export class AppRootRuntime extends AppRootRuntimeComposition {
     }, 180);
   }
 
+  /**
+   * From the settings row that says 「扫描二维码连接」, and so straight to the
+   * camera: this is the one entry that names what it opens, and it is also the
+   * only way a signed-in phone can reach the scanner at all — every other path
+   * stops at the account's device list.
+   */
   openAddConnectionFromSettings(): void {
     this.appShellState.setSettingsVisible(false);
     setTimeout(() => {
-      this.appShellState.setConnectSheetVisible(true);
+      this.openConnectSheet(CONNECT_INTENT_SCAN);
     }, 220);
   }
 
@@ -273,7 +324,42 @@ export class AppRootRuntime extends AppRootRuntimeComposition {
     this.remoteWorkspaceSessions = all;
     const current = this.remotePageState.sessions;
     const extras = all.filter((item: RemoteSession) => item.workspacePath !== this.remotePageState.workspacePath);
-    this.remotePageState.setSessions(this.mergeSessions(current, extras), this.remotePageState.hasMoreSessions);
+    this.publishRemoteSessions(this.mergeSessions(current, extras), this.remotePageState.hasMoreSessions);
+  }
+
+  /**
+   * The single way a session list reaches the screen, so everything the user
+   * sees is also what the next launch starts from.
+   *
+   * The write is deliberately not awaited: the list is on screen either way,
+   * and making a repaint wait on disk is the one way this cache could make the
+   * app feel slower than it did without it.
+   */
+  publishRemoteSessions(sessions: RemoteSession[], hasMore: boolean): void {
+    this.remotePageState.setSessions(sessions, hasMore);
+    this.remoteSessionListCache.save(sessions, hasMore);
+  }
+
+  /**
+   * Fills Remote Home from disk before anything is connected.
+   *
+   * Runs against whichever desktop was used last, because the device to key on
+   * is not known this early — identity is still being restored, and the
+   * auto-reconnect that follows targets exactly that desktop. Anything the
+   * desktop reports replaces this, so a stale entry costs a repaint.
+   */
+  private async restoreCachedRemoteSessions(): Promise<void> {
+    if (this.remotePageState.sessions.length > 0) {
+      return;
+    }
+    const cached = await this.remoteSessionListCache.restoreLast();
+    // Checked again: a connection may have landed while the read was in flight,
+    // and the desktop's answer outranks the stored one.
+    if (cached.sessions.length === 0 || this.remotePageState.sessions.length > 0) {
+      return;
+    }
+    RemoteLogger.info(`session list from cache count=${cached.sessions.length}`);
+    this.remotePageState.setSessions(cached.sessions, cached.hasMore);
   }
 
   mergeSessions(primary: RemoteSession[], extras: RemoteSession[]): RemoteSession[] {
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/runtime/AppRootRuntimeComposition.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/runtime/AppRootRuntimeComposition.ets
index c2d87b233f..7455ff4a68 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/runtime/AppRootRuntimeComposition.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/runtime/AppRootRuntimeComposition.ets
@@ -30,7 +30,9 @@ import { MobileIdentityStore } from '../../services/MobileIdentityStore';
 import { CloudAccountClient, CloudAccountDevice } from '../../services/CloudAccountClient';
 import { CloudAccountSessionStore } from '../../services/CloudAccountSessionStore';
 import { RemoteActivityLifecycleController } from '../../services/RemoteActivityLifecycleController';
+import { RemoteChatCache } from '../../services/RemoteChatCache';
 import { RemoteChatCommandController } from '../../services/RemoteChatCommandController';
+import { RemoteChatLocalRdbStore } from '../../services/RemoteChatLocalRdbStore';
 import { RemoteChatPollingLifecycleController, RemoteChatPollingSnapshot } from '../../services/RemoteChatPollingLifecycleController';
 import { RemoteFileDownloadController } from '../../services/RemoteFileDownloadController';
 import { FilePreviewController } from '../viewmodel/FilePreviewController';
@@ -39,7 +41,10 @@ import { ConversationController } from '../viewmodel/ConversationController';
 import { RemoteLogger } from '../../services/RemoteLogger';
 import { RemoteModelController } from '../../services/RemoteModelController';
 import { RemotePairingPolicy } from '../../services/RemotePairingPolicy';
+import { DetectedUrlAction } from '../../services/ConnectScanDecisionPolicy';
 import { RemoteSessionController } from '../../services/RemoteSessionController';
+import { RemoteSessionListCache } from '../../services/RemoteSessionListCache';
+import { RemoteSessionListRdbStore } from '../../services/RemoteSessionListRdbStore';
 import { RemoteSessionManager } from '../../services/RemoteSessionManager';
 import { RemoteWorkspaceRepository } from '../../services/RemoteWorkspaceRepository';
 import { RemoteWorkspaceCoordinator } from '../../services/RemoteWorkspaceCoordinator';
@@ -59,7 +64,11 @@ import {
   AppRouteContract,
   ConversationSource
 } from '../navigation/AppRouteContract';
-import { AppShellState } from '../state/AppShellState';
+import { AppShellState, CONNECT_INTENT_AUTO, CONNECT_INTENT_SCAN } from '../state/AppShellState';
+import {
+  RemoteConnectEntryKind,
+  RemoteSurfaceEntryPolicy
+} from '../policy/RemoteSurfaceEntryPolicy';
 import { AppShellViewModel } from '../viewmodel/AppShellViewModel';
 import { RemoteActivityViewModel } from '../viewmodel/RemoteActivityViewModel';
 import {
@@ -69,6 +78,12 @@ import { ConversationIntentDispatcher } from '../actions/ConversationIntentDispa
 import { GeneralChatPageState } from '../state/GeneralChatPageState';
 import { RemotePageState } from '../state/RemotePageState';
 import { RemoteCreateSessionState } from '../state/RemoteCreateSessionState';
+import { WatchProvisionState } from '../state/WatchProvisionState';
+import {
+  WatchProvisionController,
+  WatchProvisionOutcome,
+  WatchProvisionPort
+} from '../../services/WatchProvisionController';
 import { ConversationViewModel } from '../viewmodel/ConversationViewModel';
 import { FilePreviewState } from '../state/FilePreviewState';
 import { FilePreviewRequest } from '../../model/FilePreviewTarget';
@@ -102,7 +117,6 @@ export abstract class AppRootRuntimeComposition {
   abstract connect(autoReconnect?: boolean, accountPassword?: string): Promise<void>;
   abstract currentActiveTurnId(): string;
   abstract disconnect(clearPairing: boolean): Promise<void>;
-  abstract enterCodeEntry(): void;
   abstract enterCompactLayout(): void;
   abstract exitActiveChat(): void;
   abstract failRemoteConnection(err: Object): void;
@@ -114,6 +128,7 @@ export abstract class AppRootRuntimeComposition {
   abstract openAppSidebar(): void;
   abstract openRemoteControlSettings(): void;
   abstract pickImages(): Promise<void>;
+  abstract publishRemoteSessions(sessions: RemoteSession[], hasMore: boolean): void;
   abstract reconnect(): Promise<void>;
   abstract reconnectActiveRemote(): Promise<void>;
   abstract selectAssistant(path: string): Promise<void>;
@@ -147,6 +162,72 @@ export abstract class AppRootRuntimeComposition {
   readonly generalChatPageState: GeneralChatPageState = new GeneralChatPageState();
   readonly remotePageState: RemotePageState = new RemotePageState();
   readonly remoteCreateState: RemoteCreateSessionState = new RemoteCreateSessionState();
+  readonly watchProvisionState: WatchProvisionState = new WatchProvisionState();
+  private readonly watchProvisionPort: WatchProvisionPort = {
+    // Two ways to reach a credential, and the phone's own account is the
+    // better one: it works with the desktop asleep. The room channel stays as
+    // the fallback for a phone that only ever scanned a QR code and so has no
+    // account of its own to mint from.
+    canProvision: (): boolean => this.settingsController.canMintWatchCredential() ||
+      this.canProvisionViaDesktop(),
+    provision: (deviceId: string, deviceName: string, requestId: string): Promise<WatchProvisionOutcome> =>
+      this.provisionWatchDevice(deviceId, deviceName, requestId)
+  };
+  readonly watchProvisionController: WatchProvisionController =
+    new WatchProvisionController(this.watchProvisionState, this.watchProvisionPort);
+
+  private canProvisionViaDesktop(): boolean {
+    return (this.remotePageState.connectionState as ConnectionState) === ConnectionState.Connected &&
+      this.sessionManager.hasRoomChannel();
+  }
+
+  /**
+   * Mints the watch's credential, preferring this phone's own account.
+   *
+   * The relay gates minting on holding a device token, which a password login
+   * on this phone produces — the desktop was never uniquely entitled, it was
+   * just the only party the old code asked. Going direct means a watch can be
+   * onboarded with the desktop closed, and skips a 45-second round trip when
+   * it is open.
+   *
+   * `undefined` back from the account path means "not entitled" (a token
+   * delegated by a room pairing rather than a login), which is the one case
+   * worth falling back for. A network failure throws instead, so a blip is not
+   * reported as a missing desktop.
+   */
+  private async provisionWatchDevice(
+    deviceId: string,
+    deviceName: string,
+    requestId: string
+  ): Promise<WatchProvisionOutcome> {
+    const minted = await this.settingsController.provisionWatchCredential(deviceId, deviceName, requestId);
+    if (minted) {
+      return minted;
+    }
+    if (!this.canProvisionViaDesktop()) {
+      return AppRootRuntimeComposition.provisionUnavailable();
+    }
+    const outcome = await this.sessionManager.provisionPeerDevice(deviceId, deviceName, requestId);
+    return {
+      ok: outcome.ok,
+      // The desktop mints against the relay its room lives on, which is not
+      // necessarily the one this phone's account is on.
+      relayUrl: outcome.ok ? this.sessionManager.roomRelayEndpoint() : '',
+      token: outcome.token,
+      userId: outcome.userId,
+      masterKeyBase64: outcome.masterKeyBase64,
+      deviceId: outcome.deviceId,
+      failure: outcome.failure,
+      desktopReported: outcome.desktopReported
+    };
+  }
+
+  private static provisionUnavailable(): WatchProvisionOutcome {
+    return {
+      ok: false, relayUrl: '', token: '', userId: '', masterKeyBase64: '', deviceId: '',
+      failure: '', desktopReported: false
+    };
+  }
   readonly generalChatConfigStore: GeneralChatConfigStore = new GeneralChatConfigStore();
   readonly generalChatController: GeneralChatController =
     GeneralChatController.createDefault(this.generalChatConfigStore);
@@ -165,6 +246,25 @@ export abstract class AppRootRuntimeComposition {
       (): string => this.conversationController.visibleGeneralChatDraftId()
     );
   readonly chatTimelineStore: ConversationViewModel = new ConversationViewModel();
+  // Scoped to the desktop currently being controlled: session ids are issued by
+  // the desktop, so two of them on one account can name different conversations
+  // with the same id.
+  readonly remoteChatCache: RemoteChatCache =
+    new RemoteChatCache(
+      new RemoteChatLocalRdbStore(),
+      (): string => this.remotePageState.controlTargetDeviceId || this.remotePageState.desktopId
+    );
+  readonly remoteSessionListCache: RemoteSessionListCache =
+    new RemoteSessionListCache(
+      new RemoteSessionListRdbStore(),
+      (): string => this.remotePageState.controlTargetDeviceId || this.remotePageState.desktopId
+    );
+  // Both caches hold what one account saw on one desktop, so they are dropped
+  // together whenever that binding ends.
+  readonly clearCachedRemoteData: () => Promise<void> = async (): Promise<void> => {
+    await this.remoteChatCache.clear();
+    await this.remoteSessionListCache.clear();
+  };
   readonly generalChatCommandController: GeneralChatCommandController =
     new GeneralChatCommandController(
       this.generalChatController,
@@ -219,8 +319,11 @@ export abstract class AppRootRuntimeComposition {
     );
   readonly voiceInputService: VoiceInputService = new VoiceInputService();
   readonly remoteActivityLifecycleController: RemoteActivityLifecycleController =
-    new RemoteActivityLifecycleController(() => {
-      this.remoteActivityViewModel.checkConnectionHealth();
+    new RemoteActivityLifecycleController((): Promise<void> => {
+      // Returned, not fired and forgotten: the heartbeat skips its next tick
+      // while this one is still out, and it can only do that if it is handed
+      // something to wait on.
+      return this.remoteActivityViewModel.checkConnectionHealth();
     });
   readonly remoteActivityViewModel: RemoteActivityViewModel =
     new RemoteActivityViewModel(
@@ -229,6 +332,7 @@ export abstract class AppRootRuntimeComposition {
       this.remoteResumeGate,
       {
         isConnected: (): boolean => (this.remotePageState.connectionState as ConnectionState) === ConnectionState.Connected,
+        isReconnecting: (): boolean => (this.remotePageState.connectionState as ConnectionState) === ConnectionState.Reconnecting,
         isBusy: (): boolean => this.remotePageState.isBusy,
         hasRemoteBinding: (): boolean => this.hasRemoteBindingForResume(),
         isRemoteChat: (): boolean => this.appShellViewModel.isRoute(AppRoute.RemoteChat),
@@ -236,7 +340,6 @@ export abstract class AppRootRuntimeComposition {
         onConnectionState: (state: string): void => this.remotePageState.setConnectionState(state as ConnectionState),
         onStatus: (status: string): void => this.remotePageState.setStatusText(status),
         onConnectionError: async (err: Object): Promise<boolean> => this.settingsController.handleRemoteConnectionError(err),
-        onStopHeartbeat: (): void => this.remoteActivityViewModel.stopHeartbeat(),
         onStartPolling: (): void => this.conversationController.startRemotePolling(),
         onStopPolling: (): void => this.remoteChatPollingLifecycleController.stop(),
         onPoll: async (): Promise<void> => {
@@ -313,7 +416,7 @@ export abstract class AppRootRuntimeComposition {
           const extras = this.remoteWorkspaceSessions.filter((item: RemoteSession) => {
             return item.workspacePath !== this.remotePageState.workspacePath;
           });
-          this.remotePageState.setSessions(this.mergeSessions(sessions, extras), hasMore);
+          this.publishRemoteSessions(this.mergeSessions(sessions, extras), hasMore);
         },
         onActiveSession: (session: SessionSummary) => {
           this.conversationController.applyRemoteActiveSession(session);
@@ -356,6 +459,9 @@ export abstract class AppRootRuntimeComposition {
         onMessageCountKnown: (pollVersion: number, knownMessageCount: number) => {
           this.conversationController.updateKnownMessageCount(pollVersion, knownMessageCount);
         },
+        onTimelineReady: () => {
+          this.remotePageState.setConversationLoading(false);
+        },
         onSendSucceeded: (turnId: string, pendingActiveId: string) => {
           if (turnId.length > 0) {
             this.chatTimelineStore.setLocalActiveTurn(turnId);
@@ -389,13 +495,17 @@ export abstract class AppRootRuntimeComposition {
         onStatusText: (statusText: string) => {
           this.remotePageState.setStatusText(statusText);
         },
+        onToast: (message: string) => {
+          this.conversationController.showHomeToast(message);
+        },
         onBusy: (isBusy: boolean) => {
           this.remotePageState.setBusy(isBusy);
         },
         onPollRequested: () => {
-          this.remoteChatPollingLifecycleController.pollNow();
+          this.remoteChatPollingLifecycleController.nudge();
         }
-      }
+      },
+      this.remoteChatCache
     );
   readonly remoteFileDownloadController: RemoteFileDownloadController =
     new RemoteFileDownloadController(
@@ -437,7 +547,7 @@ export abstract class AppRootRuntimeComposition {
         this.remotePageState.setBusy(isBusy);
       },
       () => {
-        this.remoteChatPollingLifecycleController.pollNow();
+        this.remoteChatPollingLifecycleController.nudge();
       }
     );
   readonly remoteChatPollingLifecycleController: RemoteChatPollingLifecycleController =
@@ -496,9 +606,6 @@ export abstract class AppRootRuntimeComposition {
         onResetTimeline: (sessionId: string): void => this.conversationController.resetRemoteTimeline(sessionId),
         onClearRemoteFiles: (): void => this.remoteFileDownloadController.clear(),
         onKnownStateReset: (): void => this.conversationController.resetKnownRemoteState(),
-        onLoadModelCatalog: async (sessionId: string): Promise<void> => {
-          await this.conversationController.loadRemoteModelCatalog(sessionId);
-        },
         onLoadActiveMessages: async (): Promise<void> => {
           await this.conversationController.loadRemoteMessages();
         },
@@ -550,9 +657,10 @@ export abstract class AppRootRuntimeComposition {
       async (): Promise<void> => {
         await this.remoteWorkspaceViewModel.loadRecentWorkspacesInBackground();
       },
+      this.clearCachedRemoteData,
       (route: AppRoute): void => this.appShellViewModel.replaceRouteWithoutAnimation(route),
-      (): void => this.appShellState.setConnectSheetVisible(false),
-      (): void => this.appShellState.setConnectSheetVisible(true)
+      (): void => this.dismissConnectSheetAfterSuccess(),
+      (): void => this.openConnectSheet()
     );
   readonly settingsController: SettingsController =
     new SettingsController(
@@ -579,8 +687,9 @@ export abstract class AppRootRuntimeComposition {
           startHeartbeat: (): void => this.remoteActivityViewModel.startHeartbeat(),
           resetTimeline: (): void => this.conversationController.resetRemoteTimeline(''),
           resetKnownRemoteState: (): void => this.conversationController.resetKnownRemoteState(),
+          clearCachedRemoteData: this.clearCachedRemoteData,
           closeSettings: (): void => this.appShellState.setSettingsVisible(false),
-          closeConnectSheet: (): void => this.appShellState.setConnectSheetVisible(false),
+          closeConnectSheet: (): void => this.dismissConnectSheetAfterSuccess(),
           navigateRemoteHome: (): void => this.appShellViewModel.replaceRouteWithoutAnimation(AppRoute.RemoteHome),
           loadRecentWorkspaces: async (): Promise<void> => {
             await this.remoteWorkspaceViewModel.loadRecentWorkspacesInBackground();
@@ -597,6 +706,7 @@ export abstract class AppRootRuntimeComposition {
       {
         timeline: this.chatTimelineStore,
         chat: this.remoteChatCommandController,
+        chatCache: this.remoteChatCache,
         polling: this.remoteChatPollingLifecycleController,
         models: this.remoteModelController,
         files: this.remoteFileDownloadController,
@@ -687,8 +797,8 @@ export abstract class AppRootRuntimeComposition {
     onLayoutModeChanged: (wideLayout: boolean): void => this.appShellState.setWideLayout(wideLayout),
     onRemoteHome: {
       openSidebar: (): void => this.openAppSidebar(),
-      connectWorkspace: (): void => this.enterCodeEntry(),
-      addConnection: (): void => this.appShellState.setConnectSheetVisible(true),
+      connectWorkspace: (): void => this.openConnectSheet(),
+      addConnection: (): void => this.openConnectSheet(),
       openSettings: (): void => this.openRemoteControlSettings(),
       refresh: (): void => { this.remoteSessionViewModel.refreshSessions(); },
       showWorkspaces: (): void => { this.remoteWorkspaceViewModel.toggleRecentWorkspaces(); },
@@ -758,9 +868,10 @@ export abstract class AppRootRuntimeComposition {
       openAccount: (): void => { this.appShellState.openSettings('account'); },
       cloudLogin: (relayUrl: string, username: string, password: string): Promise<string> =>
         this.settingsController.loginCloudAccount(relayUrl, username, password),
-      cloudSync: (): Promise<string> => this.settingsController.syncCloudAccount(),
       cloudLogout: (): Promise<void> => this.settingsController.logoutCloudAccount(),
       cloudListDevices: (): Promise<CloudAccountDevice[]> => this.settingsController.listCloudAccountDevices(),
+      cloudSelectDevice: (device: CloudAccountDevice): Promise<void> =>
+        this.settingsController.selectCloudAccountDevice(device),
       getPermissionMode: (): Promise<RemotePermissionMode> => this.settingsController.getRemotePermissionMode(),
       setPermissionMode: (mode: RemotePermissionMode): Promise<RemotePermissionMode> =>
         this.settingsController.setRemotePermissionMode(mode),
@@ -772,18 +883,15 @@ export abstract class AppRootRuntimeComposition {
     onConnect: {
       back: (): void => this.appShellState.setConnectSheetVisible(false),
       connect: (password?: string): void => {
-        // Keep connection progress on the same RemoteHome surface as the connected state.
-        this.appShellState.setConnectSheetVisible(false);
-        this.appShellViewModel.replaceRouteWithoutAnimation(AppRoute.RemoteHome);
         this.connect(false, password || '');
       },
       clearPairing: (): void => { this.appShellState.setConnectSheetVisible(false); this.disconnect(true); },
       urlChanged: (url: string): void => { this.remotePageState.setRemoteUrl(url); this.remoteConnectionController.projectRemoteUrl(url); },
       userChanged: (user: string): void => this.remotePageState.setUserId(user),
-      detected: (url: string): boolean => this.remoteConnectionController.handleDetectedUrl(url),
+      detected: (url: string): string => this.handleDetectedRemoteUrl(url),
       inputVisible: (visible: boolean): void => this.remotePageState.setRemoteUrlInputVisible(visible),
       paste: (): void => { this.remoteConnectionController.paste(); },
-      scan: (): void => { this.remoteConnectionController.scan(this.host.context()); },
+      scan: (): void => { void this.scanRemotePairCode(); },
       cloudListDevices: (): Promise<CloudAccountDevice[]> => this.settingsController.listCloudAccountDevices(),
       cloudSelectDevice: (device: CloudAccountDevice): Promise<void> =>
         this.settingsController.selectCloudAccountDevice(device)
@@ -798,6 +906,66 @@ export abstract class AppRootRuntimeComposition {
   };
   readonly navigationStack: NavPathStack = this.appShellViewModel.navigationStack;
 
+  enterCodeEntry(): void {
+    this.enterRemoteSurface();
+  }
+
+  enterRemoteSurface(): void {
+    this.appShellState.setConnectSheetVisible(false);
+    if (this.appShellState.wideLayout) {
+      void this.switchWideConversationSource(ConversationSource.Remote);
+      return;
+    }
+    void this.switchCompactConversationSource(ConversationSource.Remote);
+  }
 
-}
+  openConnectSheet(intent: string = CONNECT_INTENT_AUTO): void {
+    const kind = intent === CONNECT_INTENT_SCAN ?
+      RemoteConnectEntryKind.OpenScan : RemoteConnectEntryKind.OpenConnect;
+    if (!RemoteSurfaceEntryPolicy.shouldOpenConnectSheet(kind)) {
+      this.enterRemoteSurface();
+      return;
+    }
+    this.appShellState.setConnectSheetVisible(true, intent);
+  }
 
+  /**
+   * Close the sheet only after a connect that the user is watching on it.
+   * Heartbeat reconnects and background restores must not steal the current
+   * route just because they also go through the same success path.
+   */
+  dismissConnectSheetAfterSuccess(): void {
+    const opened = this.appShellState.showConnectSheet;
+    this.appShellState.setConnectSheetVisible(false);
+    if (opened) {
+      this.appShellViewModel.replaceRouteWithoutAnimation(AppRoute.RemoteHome);
+    }
+  }
+
+  handleDetectedRemoteUrl(url: string): string {
+    const result = this.remoteConnectionController.handleDetectedUrl(
+      url,
+      this.settingsController.hasCloudAccountSession(),
+      this.remotePageState.accountUsername
+    );
+    if (result.action === DetectedUrlAction.USE_CLOUD_DEVICE) {
+      void this.settingsController.restoreCloudTarget(
+        result.cloudDeviceId,
+        this.remotePageState.desktopName,
+        true
+      );
+    }
+    return result.action;
+  }
+
+  async scanRemotePairCode(): Promise<void> {
+    const text = await this.remoteConnectionController.scan(this.host.context());
+    if (text.length === 0) {
+      return;
+    }
+    const action = this.handleDetectedRemoteUrl(text);
+    if (action === DetectedUrlAction.PAIR_NOW) {
+      void this.connect(false, '');
+    }
+  }
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/state/AppShellState.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/state/AppShellState.ets
index e34e22c5d1..6301298b05 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/state/AppShellState.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/state/AppShellState.ets
@@ -1,5 +1,10 @@
 import { AppRoute } from '../navigation/AppRouteContract';
 
+/** The connect sheet decides for itself where to open. */
+export const CONNECT_INTENT_AUTO: string = 'auto';
+/** The user tapped something that promised a camera, so open the camera. */
+export const CONNECT_INTENT_SCAN: string = 'scan';
+
 @ObservedV2
 export class AppShellState {
   /**
@@ -12,6 +17,13 @@ export class AppShellState {
   @Trace showSettings: boolean = false;
   @Trace settingsMode: string = 'general';
   @Trace showConnectSheet: boolean = false;
+  /**
+   * Why the connect sheet was opened, which is not something the sheet can work
+   * out for itself: a signed-in phone has an account device list to offer and a
+   * camera to offer, and only the entry point knows which one the user just
+   * asked for by name.
+   */
+  @Trace connectSheetIntent: string = CONNECT_INTENT_AUTO;
   /**
    * Mirror of the resolved master-detail layout mode. Only the presentation
    * layer measures the viewport, so runtime logic that must branch on compact
@@ -55,7 +67,15 @@ export class AppShellState {
     this.setSettingsVisible(false);
   }
 
-  setConnectSheetVisible(visible: boolean): void {
+  /**
+   * The intent is set on every open rather than cleared on close, because the
+   * sheet can also be dismissed by a drag that never reaches this class — and a
+   * default that only holds while nobody swipes is not a default.
+   */
+  setConnectSheetVisible(visible: boolean, intent: string = CONNECT_INTENT_AUTO): void {
+    if (visible) {
+      this.connectSheetIntent = intent;
+    }
     this.showConnectSheet = visible;
   }
 
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ChatComposerCapabilities.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/state/ChatComposerCapabilities.ets
similarity index 56%
rename from src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ChatComposerCapabilities.ets
rename to src/apps/mobile/harmonyos/entry/src/main/ets/pages/state/ChatComposerCapabilities.ets
index 6edfc38e4a..0da62826a0 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ChatComposerCapabilities.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/state/ChatComposerCapabilities.ets
@@ -6,27 +6,34 @@ export class ChatComposerCapabilities {
   readonly requiresRemoteConnection: boolean;
   readonly showAddButton: boolean;
   readonly showVoiceInput: boolean;
+  // Whether a message typed while a turn is still running can be handed over
+  // right away. The desktop relay queues it server-side and lets the current
+  // turn yield to it, so on that surface the draft outranks the stop button.
+  // Where nothing queues, holding the draft back is the honest behaviour.
+  readonly supportsMidRunSend: boolean;
 
   constructor(
     surface: ChatSurface,
     supportsAttachments: boolean,
     requiresRemoteConnection: boolean,
     showAddButton: boolean = true,
-    showVoiceInput: boolean = true
+    showVoiceInput: boolean = true,
+    supportsMidRunSend: boolean = false
   ) {
     this.surface = surface;
     this.supportsAttachments = supportsAttachments;
     this.requiresRemoteConnection = requiresRemoteConnection;
     this.showAddButton = showAddButton;
     this.showVoiceInput = showVoiceInput;
+    this.supportsMidRunSend = supportsMidRunSend;
   }
 }
 
 export const GENERAL_CHAT_COMPOSER_CAPABILITIES: ChatComposerCapabilities =
-  new ChatComposerCapabilities(ChatSurface.General, false, false);
+  new ChatComposerCapabilities(ChatSurface.General, true, false);
 
 export const REMOTE_CHAT_COMPOSER_CAPABILITIES: ChatComposerCapabilities =
-  new ChatComposerCapabilities(ChatSurface.Remote, true, true);
+  new ChatComposerCapabilities(ChatSurface.Remote, true, true, true, true, true);
 
 export const REMOTE_CREATE_COMPOSER_CAPABILITIES: ChatComposerCapabilities =
-  new ChatComposerCapabilities(ChatSurface.Remote, false, true, false, true);
+  new ChatComposerCapabilities(ChatSurface.Create, false, true, false, true);
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ChatSurface.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/state/ChatSurface.ets
similarity index 55%
rename from src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ChatSurface.ets
rename to src/apps/mobile/harmonyos/entry/src/main/ets/pages/state/ChatSurface.ets
index 284d69a2a4..4a3940af24 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ChatSurface.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/state/ChatSurface.ets
@@ -1,4 +1,5 @@
 export enum ChatSurface {
   General = 'general',
-  Remote = 'remote'
+  Remote = 'remote',
+  Create = 'create'
 }
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConversationUiModels.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/state/ConversationUiModels.ets
similarity index 90%
rename from src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConversationUiModels.ets
rename to src/apps/mobile/harmonyos/entry/src/main/ets/pages/state/ConversationUiModels.ets
index 0e656fc1a6..5de53cba77 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/components/ConversationUiModels.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/state/ConversationUiModels.ets
@@ -100,8 +100,11 @@ export interface ConversationUiMessage {
 }
 
 export interface ConversationUiQuestionAnswer {
-  answer: string;
-  '0': string;
+  answer?: string;
+  '0'?: string | string[];
+  '1'?: string | string[];
+  '2'?: string | string[];
+  '3'?: string | string[];
 }
 
 export function toConversationUiSession(source: SessionSummary): ConversationUiSession {
@@ -205,5 +208,22 @@ export function toConversationUiMessage(source: ChatMessage): ConversationUiMess
 }
 
 export function toRemoteQuestionAnswer(source: ConversationUiQuestionAnswer): RemoteQuestionAnswerPayload {
-  return { answer: source.answer, '0': source.answer };
+  const result: Record<string, Object> = {};
+  const values = source as Record<string, Object>;
+  if (source.answer !== undefined) {
+    result['answer'] = source.answer as Object;
+  }
+  if (values['0'] !== undefined) {
+    result['0'] = values['0'];
+  }
+  if (values['1'] !== undefined) {
+    result['1'] = values['1'];
+  }
+  if (values['2'] !== undefined) {
+    result['2'] = values['2'];
+  }
+  if (values['3'] !== undefined) {
+    result['3'] = values['3'];
+  }
+  return result as RemoteQuestionAnswerPayload;
 }
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/state/ConversationViewState.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/state/ConversationViewState.ets
index a555f25aa0..2985d42456 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/state/ConversationViewState.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/state/ConversationViewState.ets
@@ -6,9 +6,10 @@ import { RemoteUiState } from '../../services/RemoteUiState';
 import {
   ChatComposerCapabilities,
   GENERAL_CHAT_COMPOSER_CAPABILITIES,
-  REMOTE_CHAT_COMPOSER_CAPABILITIES
-} from '../components/ChatComposerCapabilities';
-import { ChatSurface } from '../components/ChatSurface';
+  REMOTE_CHAT_COMPOSER_CAPABILITIES,
+  REMOTE_CREATE_COMPOSER_CAPABILITIES
+} from './ChatComposerCapabilities';
+import { ChatSurface } from './ChatSurface';
 import {
   ConversationUiModelCatalog,
   ConversationUiSelectedImage,
@@ -16,10 +17,11 @@ import {
   toConversationUiModelCatalog,
   toConversationUiSelectedImage,
   toConversationUiSession
-} from '../components/ConversationUiModels';
+} from './ConversationUiModels';
 import { AppRoute } from '../navigation/AppRouteContract';
 import { ConversationCoreState } from './ConversationCoreState';
 import { GeneralChatPageState } from './GeneralChatPageState';
+import { RemoteCreateSessionState } from './RemoteCreateSessionState';
 import { RemotePageState } from './RemotePageState';
 
 /** Immutable presentation state consumed by ConversationView. */
@@ -38,10 +40,7 @@ export class ConversationViewState {
   hasMoreMessages: boolean = false;
   timelineItems: ChatTimelineItem[] = [];
   timelineRevision: number = 0;
-  showSuggestionsWhenEmpty: boolean = true;
-  supportsSearch: boolean = false;
-  supportsImages: boolean = false;
-  supportsFiles: boolean = false;
+  showSuggestionsWhenEmpty: boolean = false;
   modelCatalog: ConversationUiModelCatalog = toConversationUiModelCatalog(RemoteUiState.emptyModelCatalog());
   selectedModelId: string = '';
   isSessionPinned: boolean = false;
@@ -56,14 +55,34 @@ export class ConversationViewState {
     route: AppRoute,
     remote: RemotePageState,
     general: GeneralChatPageState,
-    generalInlineStatus: string
+    generalInlineStatus: string,
+    create: RemoteCreateSessionState = new RemoteCreateSessionState()
   ): ConversationViewState {
+    if (route === AppRoute.RemoteCreate) {
+      return ConversationViewState.create(remote, create);
+    }
     if (route === AppRoute.RemoteChat) {
       return ConversationViewState.remote(remote);
     }
     return ConversationViewState.general(general, generalInlineStatus);
   }
 
+  private static create(remote: RemotePageState, create: RemoteCreateSessionState): ConversationViewState {
+    const state = new ConversationViewState();
+    state.surface = ChatSurface.Create;
+    state.desktopName = remote.desktopName;
+    state.workspaceBranch = remote.workspaceBranch;
+    state.connectionState = 'connected';
+    state.composerCapabilities = REMOTE_CREATE_COMPOSER_CAPABILITIES;
+    state.chatInput = create.draft;
+    state.isBusy = create.isSubmitting;
+    state.inlineStatusText = create.errorText;
+    state.isVoiceListening = create.isVoiceListening;
+    state.selectedModelId = create.selectedModelId;
+    state.modelCatalog = toConversationUiModelCatalog(remote.conversation.modelCatalog);
+    return state;
+  }
+
   private static remote(remote: RemotePageState): ConversationViewState {
     const state = ConversationViewState.fromCore(remote.conversation);
     state.surface = ChatSurface.Remote;
@@ -71,6 +90,9 @@ export class ConversationViewState {
     state.workspaceBranch = remote.workspaceBranch;
     state.connectionState = remote.connectionState;
     state.isLoadingConversation = remote.isLoadingConversation;
+    if (state.isLoadingConversation) {
+      state.activeSession = ConversationViewState.emptySession();
+    }
     state.composerCapabilities = REMOTE_CHAT_COMPOSER_CAPABILITIES;
     state.showSuggestionsWhenEmpty = false;
     state.downloadingFilePath = remote.downloadingFilePath;
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/state/RemotePageState.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/state/RemotePageState.ets
index 3284ff69fb..e72fe68688 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/state/RemotePageState.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/state/RemotePageState.ets
@@ -53,6 +53,11 @@ export class RemotePageState {
   @Trace pendingSessionId: string = '';
   @Trace isConversationDismissed: boolean = false;
   @Trace sessionErrorText: string = '';
+  // Deliberately untraced: the memo behind visibleSessions(), not state anything
+  // renders. Tracing it would make reading the list a write to the list.
+  private visibleSessionsCache: RemoteSession[] = [];
+  private visibleSessionsSource: RemoteSession[] | undefined = undefined;
+  private visibleSessionsQuery: string = ' ';
   get activeSession(): SessionSummary { return this.conversation.activeSession; }
   get sessions(): RemoteSession[] { return this.conversation.sessions; }
   get persistedMessages(): ChatMessage[] { return this.conversation.persistedMessages; }
@@ -310,14 +315,30 @@ export class RemotePageState {
     this.closePickers();
   }
 
+  /**
+   * The sessions the sidebar may show, as a stable array.
+   *
+   * This is read straight into a `@Param`, so returning a fresh array each call
+   * marked the session list dirty on every rebuild of its parent — including
+   * the rebuild that a selection change causes, which is the one case where
+   * nothing about the list has moved. Handing back the same instance until the
+   * source or the query changes lets the list keep what it already computed.
+   */
   visibleSessions(): RemoteSession[] {
+    const source = this.conversation.sessions;
     const query = this.sessionQuery.trim().toLowerCase();
-    return this.conversation.sessions.filter((item: RemoteSession) => {
+    if (source === this.visibleSessionsSource && query === this.visibleSessionsQuery) {
+      return this.visibleSessionsCache;
+    }
+    this.visibleSessionsSource = source;
+    this.visibleSessionsQuery = query;
+    this.visibleSessionsCache = source.filter((item: RemoteSession) => {
       if (item.id.length === 0 || item.status === 'archived') {
         return false;
       }
       return query.length === 0 || item.title.toLowerCase().indexOf(query) >= 0;
     });
+    return this.visibleSessionsCache;
   }
 
   hasRunningActiveTurn(): boolean {
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/state/WatchProvisionState.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/state/WatchProvisionState.ets
new file mode 100644
index 0000000000..d2ddfcfd01
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/state/WatchProvisionState.ets
@@ -0,0 +1,59 @@
+import { WatchProvisionProtocol } from '../../services/WatchProvisionProtocol';
+import { WatchProvisionDisplay } from '../../services/WatchProvisionDisplay';
+
+export enum WatchProvisionPhase {
+  /** No watch is waiting; the card is not on screen. */
+  Hidden = 'hidden',
+  /** A request arrived and its owner has not answered yet. */
+  Asking = 'asking',
+  /** Approved; the desktop is minting the credential. */
+  Working = 'working',
+  Done = 'done',
+  Failed = 'failed'
+}
+
+@ObservedV2
+export class WatchProvisionState implements WatchProvisionDisplay {
+  @Trace phase: WatchProvisionPhase = WatchProvisionPhase.Hidden;
+  @Trace deviceName: string = '';
+  @Trace deviceIdLabel: string = '';
+  @Trace message: string = '';
+
+  ask(deviceName: string, deviceId: string): void {
+    this.phase = WatchProvisionPhase.Asking;
+    this.deviceName = deviceName;
+    this.deviceIdLabel = WatchProvisionProtocol.shortDeviceId(deviceId);
+    this.message = '';
+  }
+
+  working(): void {
+    this.phase = WatchProvisionPhase.Working;
+    this.message = '';
+  }
+
+  done(message: string): void {
+    this.phase = WatchProvisionPhase.Done;
+    this.message = message;
+  }
+
+  fail(message: string): void {
+    this.phase = WatchProvisionPhase.Failed;
+    this.message = message;
+  }
+
+  hide(): void {
+    this.phase = WatchProvisionPhase.Hidden;
+    this.deviceName = '';
+    this.deviceIdLabel = '';
+    this.message = '';
+  }
+
+  visible(): boolean {
+    return this.phase !== WatchProvisionPhase.Hidden;
+  }
+
+  /** The card is only dismissible when nothing is in flight behind it. */
+  dismissible(): boolean {
+    return this.phase !== WatchProvisionPhase.Working;
+  }
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/AppShellViewModel.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/AppShellViewModel.ets
index 2b723f14d5..889c48082d 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/AppShellViewModel.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/AppShellViewModel.ets
@@ -48,8 +48,20 @@ export class AppShellViewModel {
     this.syncActiveRoute();
   }
 
+  /**
+   * Makes [route] the whole stack, or does nothing if it already is.
+   *
+   * The guard deliberately ignores [sessionId]. A route names a screen, not the
+   * conversation on it — which session is open is read from page state, and no
+   * component ever reads the path param back. Treating a session switch as a
+   * navigation meant clearing the stack and pushing a fresh `NavDestination`,
+   * and on the wide layout the master pane lives inside that destination: every
+   * tap on a row tore down and rebuilt the whole sidebar. Measured on tablet,
+   * that rebuild was ~2.1s of the ~3.5s the main thread spent blocked before
+   * the transcript appeared.
+   */
   replaceRouteWithoutAnimation(route: AppRoute, sessionId: string = ''): void {
-    if (this.currentRoute() === route && sessionId.length === 0) {
+    if (this.currentRoute() === route) {
       return;
     }
     this.navigationStack.clear(false);
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/ConversationController.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/ConversationController.ets
index b43aa96612..c877a88fc7 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/ConversationController.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/ConversationController.ets
@@ -1,98 +1,43 @@
 import {
-  RecentWorkspaceEntry,
-  RemoteImageContext,
   RemoteQuestionAnswerPayload,
   RemoteSession,
-  SessionSummary,
-  SelectedImageAttachment
+  SelectedImageAttachment,
+  SessionSummary
 } from '../../model/RemoteModels';
 import { CloudAccountDevice } from '../../services/CloudAccountClient';
 import { ChatTimelineItem } from '../../services/ChatTimelineProjector';
-import { ChatTimelineState } from '../../services/ChatTimelineStore';
-import { ClipboardService } from '../../services/ClipboardService';
-import { ConnectionErrorPolicy } from '../../services/ConnectionErrorPolicy';
-import { ImagePickerService } from '../../services/ImagePickerService';
-import { GeneralChatCommandController } from '../../services/general-chat/GeneralChatCommandController';
-import { GeneralChatConversationViewModel } from './GeneralChatConversationViewModel';
-import { GeneralChatDraftLifecycleController } from '../../services/general-chat/GeneralChatDraftLifecycleController';
-import {
-  GeneralChatServiceState,
-  GeneralChatServiceStatus
-} from '../../services/general-chat/GeneralChatServiceState';
-import { RemoteChatCommandController } from '../../services/RemoteChatCommandController';
-import {
-  RemoteChatPollingCursor,
-  RemoteChatPollingLifecycleController,
-  RemoteChatPollingSnapshot
-} from '../../services/RemoteChatPollingLifecycleController';
-import { RemoteFileDownloadController } from '../../services/RemoteFileDownloadController';
-import { RemoteI18n } from '../../i18n/RemoteI18n';
-import { RemoteLogger } from '../../services/RemoteLogger';
-import { RemoteModelController } from '../../services/RemoteModelController';
-import { RemoteToolActionController } from '../../services/RemoteToolActionController';
-import { RemoteUiState } from '../../services/RemoteUiState';
-import { RemoteSessionManager } from '../../services/RemoteSessionManager';
-import { RemoteWorkspaceCoordinator } from '../../services/RemoteWorkspaceCoordinator';
 import { VoiceInputRouteSnapshot } from '../../services/VoiceInputLifecycleController';
 import { AppRootRouteState } from '../navigation/AppRootRouteState';
 import { AppRoute, AppRouteContract } from '../navigation/AppRouteContract';
 import { GeneralChatPageState } from '../state/GeneralChatPageState';
 import { RemoteCreateSessionState } from '../state/RemoteCreateSessionState';
 import { RemotePageState } from '../state/RemotePageState';
-import { ConversationViewModel } from './ConversationViewModel';
-import { AppShellViewModel } from './AppShellViewModel';
-import { FilePreviewController } from './FilePreviewController';
-import { RemoteConnectionController } from './RemoteConnectionController';
-import { RemoteSessionViewModel } from './RemoteSessionViewModel';
-import { SettingsController } from './SettingsController';
-const GENERAL_CHAT_HOME_DRAFT_ID: string = 'new-chat';
-
-export interface ConversationControllerHooks {
-  readonly currentRoute: () => AppRoute;
-}
-
-export interface RemoteConversationHooks {
-  readonly isConversationContext: (sessionId: string) => boolean;
-  readonly isFilePreviewVisible: () => boolean;
-  readonly stopVoiceInput: () => Promise<void>;
-  readonly showToast: (message: string) => boolean;
-  readonly selectAssistantWorkspace: (path: string) => Promise<void>;
-}
-
-export interface RemoteConversationDependencies {
-  readonly timeline: ConversationViewModel;
-  readonly chat: RemoteChatCommandController;
-  readonly polling: RemoteChatPollingLifecycleController;
-  readonly models: RemoteModelController;
-  readonly files: RemoteFileDownloadController;
-  readonly tools: RemoteToolActionController;
-  readonly connection: RemoteConnectionController;
-  readonly imagePicker: ImagePickerService;
-  readonly clipboard: ClipboardService;
-  readonly sessions: RemoteSessionViewModel;
-  readonly sessionManager: RemoteSessionManager;
-  readonly workspace: RemoteWorkspaceCoordinator;
-  readonly settings: SettingsController;
-  readonly appShell: AppShellViewModel;
-  readonly filePreview: FilePreviewController;
-  readonly generalCommands: GeneralChatCommandController;
-  readonly generalConversation: GeneralChatConversationViewModel;
-  readonly generalDrafts: GeneralChatDraftLifecycleController;
-  readonly hooks: RemoteConversationHooks;
-}
-
-/** Owns route-dependent composer and voice presentation state. */
+import { RemoteChatPollingSnapshot } from '../../services/RemoteChatPollingLifecycleController';
+import {
+  ConversationControllerHooks,
+  RemoteConversationDependencies,
+  RemoteConversationHooks
+} from './ConversationRuntime';
+import { RemoteCreateFlowController } from './RemoteCreateFlowController';
+import { RemoteTranscriptController } from './RemoteTranscriptController';
+import { VisibleConversationController } from './VisibleConversationController';
+
+export {
+  ConversationControllerHooks,
+  RemoteConversationDependencies,
+  RemoteConversationHooks
+} from './ConversationRuntime';
+
+/** Owns route-dependent composer state and delegates feature work. */
 export class ConversationController {
   private readonly general: GeneralChatPageState;
   private readonly remote: RemotePageState;
   private readonly remoteCreate: RemoteCreateSessionState;
   private readonly hooks: ConversationControllerHooks;
   private readonly remoteRuntime?: RemoteConversationDependencies;
-  private knownPollVersionValue: number = 0;
-  private knownModelCatalogVersion: number = 0;
-  private knownRemoteMessageCount: number = 0;
-  private isSyncingAfterTurn: boolean = false;
-  private remoteCreateWorkspaceLoadVersion: number = 0;
+  private readonly transcript: RemoteTranscriptController;
+  private readonly createFlow: RemoteCreateFlowController;
+  private readonly visible: VisibleConversationController;
 
   constructor(
     general: GeneralChatPageState,
@@ -106,6 +51,21 @@ export class ConversationController {
     this.remoteCreate = remoteCreate;
     this.hooks = hooks;
     this.remoteRuntime = remoteRuntime;
+    this.transcript = new RemoteTranscriptController(remote, remoteRuntime, (message: string) => {
+      this.showHomeToast(message);
+    });
+    this.createFlow = new RemoteCreateFlowController(remote, remoteCreate, remoteRuntime);
+    this.visible = new VisibleConversationController(
+      general,
+      remote,
+      remoteRuntime,
+      this.transcript,
+      this.createFlow,
+      (route: AppRoute, value: string) => this.setChatInput(route, value),
+      (statusText: string) => this.setVisibleStatusText(statusText),
+      (route: AppRoute) => this.isGeneralComposerRoute(route),
+      (message: string) => this.showHomeToast(message)
+    );
   }
 
   visibleChatInput(): string {
@@ -189,850 +149,108 @@ export class ConversationController {
     return AppRouteContract.isGeneralComposerRoute(route);
   }
 
-  knownPollVersion(): number {
-    return this.knownPollVersionValue;
-  }
-
-  resetKnownRemoteState(): void {
-    this.knownPollVersionValue = 0;
-    this.knownModelCatalogVersion = 0;
-    this.knownRemoteMessageCount = 0;
-  }
-
+  knownPollVersion(): number { return this.transcript.knownPollVersion(); }
+  resetKnownRemoteState(): void { this.transcript.resetKnownRemoteState(); }
   updateKnownMessageCount(pollVersion: number, knownMessageCount: number): void {
-    this.knownRemoteMessageCount = knownMessageCount;
-    this.updateChatPollingCursor(pollVersion, knownMessageCount);
+    this.transcript.updateKnownMessageCount(pollVersion, knownMessageCount);
   }
-
   updateKnownModelCatalogVersion(version: number): void {
-    this.knownModelCatalogVersion = version;
-    this.requireRemoteRuntime().polling.updateKnownModelCatalogVersion(version);
-  }
-
-  async loadRemoteMessages(): Promise<void> {
-    const runtime = this.requireRemoteRuntime();
-    await runtime.chat.loadMessages(
-      this.remote.activeSession.sessionId || '',
-      runtime.hooks.isConversationContext
-    );
-  }
-
-  async loadRemoteModelCatalog(sessionId: string): Promise<void> {
-    const runtime = this.requireRemoteRuntime();
-    await runtime.models.loadCatalog(
-      sessionId,
-      runtime.connection.ensureAvailable(),
-      runtime.hooks.isConversationContext
-    );
-  }
-
-  async selectRemoteModel(modelId: string): Promise<void> {
-    const runtime = this.requireRemoteRuntime();
-    await runtime.models.selectModel(
-      modelId,
-      this.remote.activeSession.sessionId || '',
-      this.remote.isBusy,
-      runtime.connection.ensureAvailable()
-    );
-  }
-
-  async loadOlderRemoteMessages(): Promise<void> {
-    const runtime = this.requireRemoteRuntime();
-    await runtime.chat.loadOlderMessages(
-      this.remote.activeSession.sessionId || '',
-      this.knownPollVersionValue,
-      this.remote.hasMoreMessages,
-      this.remote.isBusy
-    );
-  }
-
-  async sendRemoteMessage(): Promise<void> {
-    const runtime = this.requireRemoteRuntime();
-    if (this.remote.isVoiceListening) {
-      await runtime.hooks.stopVoiceInput();
-    }
-    const rawText = this.remote.chatInput.trim();
-    const images = this.remote.selectedImages.slice();
-    const text = rawText.length > 0 ? rawText :
-      (images.length > 0 ? RemoteI18n.t('chat.analyzeImageDefault') : '');
-    const sessionId = this.remote.activeSession.sessionId || '';
-    if ((!text && images.length === 0) || !sessionId || this.remote.isBusy ||
-      !runtime.connection.ensureAvailable()) {
-      return;
-    }
-    this.remote.clearComposer();
-    const localMessage = RemoteUiState.localUserMessage(text, images);
-    runtime.timeline.appendOptimisticMessage(localMessage);
-    const pendingActiveId = runtime.timeline.setPendingActiveTurn(localMessage.id);
-    this.syncRemoteTimeline();
-    RemoteLogger.info(`chat send queued session=${this.shortSessionId(sessionId)} pending=${pendingActiveId}`);
-    this.startRemotePolling();
-    runtime.polling.nudge();
-    const imageContexts: RemoteImageContext[] = images.length > 0 ?
-      runtime.imagePicker.toRemoteContexts(images) : [];
-    await runtime.chat.sendPreparedMessage(
-      sessionId,
-      text,
-      this.remote.activeSession.agentType,
-      rawText,
-      images,
-      imageContexts,
-      localMessage.id,
-      pendingActiveId,
-      this.remote.isBusy,
-      true
-    );
-  }
-
-  async stopRemoteTask(): Promise<void> {
-    const runtime = this.requireRemoteRuntime();
-    const sessionId = this.remote.activeSession.sessionId || '';
-    if (!sessionId) {
-      return;
-    }
-    await runtime.chat.stopTask(
-      sessionId,
-      this.remote.activeTurnMessage.id,
-      this.remoteActiveTurnId(),
-      runtime.connection.ensureAvailable()
-    );
-  }
-
-  async renameRemoteSession(title: string): Promise<void> {
-    const runtime = this.requireRemoteRuntime();
-    const nextTitle = title.trim();
-    if (!this.remote.activeSession.sessionId || nextTitle.length === 0 ||
-      nextTitle === this.remote.activeSession.title || this.remote.isBusy) {
-      return;
-    }
-    await runtime.chat.renameActiveSession(
-      this.remote.activeSession,
-      nextTitle,
-      this.remote.isBusy,
-      runtime.connection.ensureAvailable()
-    );
-  }
-
-  async copyRemoteMessage(text: string): Promise<void> {
-    if (text.trim().length === 0) {
-      return;
-    }
-    try {
-      await this.requireRemoteRuntime().clipboard.writeText(text);
-      this.remote.setStatusText(RemoteI18n.t('status.messageCopied'));
-    } catch (err) {
-      this.remote.setStatusText(ConnectionErrorPolicy.errorText(err));
-    }
-  }
-
-  async downloadRemoteFile(path: string): Promise<void> {
-    const runtime = this.requireRemoteRuntime();
-    await runtime.files.download(
-      path,
-      this.remote.activeSession.sessionId || '',
-      this.remote.isBusy,
-      runtime.connection.ensureAvailable()
-    );
-  }
-
-  retryRemoteMessage(text: string): void {
-    if (this.remote.isBusy || !this.requireRemoteRuntime().connection.ensureAvailable()) {
-      return;
-    }
-    this.remote.setChatInput(text);
-    this.sendRemoteMessage();
-  }
-
+    this.transcript.updateKnownModelCatalogVersion(version);
+  }
+  async loadRemoteMessages(): Promise<void> { await this.transcript.loadRemoteMessages(); }
+  async selectRemoteModel(modelId: string): Promise<void> { await this.transcript.selectRemoteModel(modelId); }
+  async loadOlderRemoteMessages(): Promise<void> { await this.transcript.loadOlderRemoteMessages(); }
+  async sendRemoteMessage(): Promise<void> { await this.transcript.sendRemoteMessage(); }
+  async stopRemoteTask(): Promise<void> { await this.transcript.stopRemoteTask(); }
+  async renameRemoteSession(title: string): Promise<void> { await this.transcript.renameRemoteSession(title); }
+  async copyRemoteMessage(text: string): Promise<void> { await this.transcript.copyRemoteMessage(text); }
+  async downloadRemoteFile(path: string): Promise<void> { await this.transcript.downloadRemoteFile(path); }
+  retryRemoteMessage(text: string): void { this.transcript.retryRemoteMessage(text); }
   async approveRemoteTool(toolId: string, updatedInput?: Object): Promise<void> {
-    const runtime = this.requireRemoteRuntime();
-    await runtime.tools.approve(
-      toolId, this.remote.activeSession.sessionId || '', runtime.connection.ensureAvailable(), updatedInput
-    );
-  }
-
-  async rejectRemoteTool(toolId: string): Promise<void> {
-    const runtime = this.requireRemoteRuntime();
-    await runtime.tools.reject(
-      toolId, this.remote.activeSession.sessionId || '', runtime.connection.ensureAvailable()
-    );
+    await this.transcript.approveRemoteTool(toolId, updatedInput);
   }
-
-  async cancelRemoteTool(toolId: string): Promise<void> {
-    const runtime = this.requireRemoteRuntime();
-    await runtime.tools.cancel(
-      toolId, this.remote.activeSession.sessionId || '', runtime.connection.ensureAvailable()
-    );
-  }
-
+  async rejectRemoteTool(toolId: string): Promise<void> { await this.transcript.rejectRemoteTool(toolId); }
+  async cancelRemoteTool(toolId: string): Promise<void> { await this.transcript.cancelRemoteTool(toolId); }
   async answerRemoteQuestion(toolId: string, answers: RemoteQuestionAnswerPayload): Promise<void> {
-    const runtime = this.requireRemoteRuntime();
-    await runtime.tools.answer(
-      toolId, this.remote.activeSession.sessionId || '', runtime.connection.ensureAvailable(), answers
-    );
-  }
-
-  resetRemoteTimeline(sessionId: string): void {
-    const runtime = this.requireRemoteRuntime();
-    runtime.timeline.reset(sessionId);
-    this.knownPollVersionValue = 0;
-    this.syncRemoteTimeline();
-  }
-
-  syncRemoteTimeline(): void {
-    const runtime = this.requireRemoteRuntime();
-    const state: ChatTimelineState = runtime.timeline.snapshotState();
-    this.remote.setTimelineProjection(
-      state.persistedMessages,
-      state.optimisticMessages,
-      state.activeTurn || RemoteUiState.emptyActiveTurn(),
-      this.remote.hasMoreMessages,
-      runtime.timeline.viewState(this.remote.hasMoreMessages)
-    );
-    this.remote.setModelCatalog(state.modelCatalog, state.selectedModelId);
-  }
-
-  startRemotePolling(): void {
-    this.requireRemoteRuntime().polling.startActiveSession({
-      sessionId: this.remote.activeSession.sessionId || '',
-      cursor: this.currentChatPollingCursor(),
-      activeTurn: this.remote.activeTurnMessage
-    });
+    await this.transcript.answerRemoteQuestion(toolId, answers);
   }
-
+  resetRemoteTimeline(sessionId: string): void { this.transcript.resetRemoteTimeline(sessionId); }
+  syncRemoteTimeline(): void { this.transcript.syncRemoteTimeline(); }
+  startRemotePolling(): void { this.transcript.startRemotePolling(); }
   applyRemoteSnapshot(snapshot: RemoteChatPollingSnapshot): void {
-    const runtime = this.requireRemoteRuntime();
-    if (!runtime.hooks.isConversationContext(snapshot.sessionId)) {
-      return;
-    }
-    runtime.timeline.applySnapshot(snapshot);
-    this.syncRemoteTimeline();
-    this.knownPollVersionValue = snapshot.cursor.pollVersion;
-    this.knownModelCatalogVersion = snapshot.cursor.knownModelCatalogVersion;
-    this.knownRemoteMessageCount = snapshot.cursor.knownMessageCount;
-    if (snapshot.title.length > 0) {
-      this.remote.setActiveSession({
-        sessionId: this.remote.activeSession.sessionId,
-        title: snapshot.title,
-        workspacePath: this.remote.activeSession.workspacePath,
-        agentType: this.remote.activeSession.agentType
-      });
-    }
-    if (snapshot.modelCatalog) {
-      runtime.models.applyCatalog(snapshot.modelCatalog);
-    }
-    this.remote.setStatusText(this.hasRunningRemoteTurn()
-      ? RemoteI18n.t('status.desktopProcessing')
-      : RemoteI18n.t('status.messagesSynced'));
-    if (snapshot.shouldSyncAfterTurnEnded) {
-      this.syncAfterRemoteTurnEnded();
-    }
-  }
-
-  hasRunningRemoteTurn(): boolean {
-    return this.remote.activeTurnMessage.id.length > 0 &&
-      (this.remote.activeTurnMessage.status || '').toLowerCase() === 'active';
-  }
-
-  remoteActiveTurnId(): string {
-    const active = this.remote.activeTurnMessage;
-    if (active.turnId && active.turnId.length > 0) {
-      return active.turnId;
-    }
-    return active.id.indexOf('active-') === 0 ? active.id.slice('active-'.length) : '';
-  }
-
-  projectedRemoteTimelineItems(): ChatTimelineItem[] {
-    return this.requireRemoteRuntime().timeline.viewState(this.remote.hasMoreMessages);
+    this.transcript.applyRemoteSnapshot(snapshot);
   }
+  hasRunningRemoteTurn(): boolean { return this.transcript.hasRunningRemoteTurn(); }
+  remoteActiveTurnId(): string { return this.transcript.remoteActiveTurnId(); }
+  projectedRemoteTimelineItems(): ChatTimelineItem[] { return this.transcript.projectedRemoteTimelineItems(); }
 
   async createRemoteSession(agentType: string, inPlace: boolean = false): Promise<void> {
-    const runtime = this.requireRemoteRuntime();
-    runtime.filePreview.close();
-    await runtime.sessions.createSession(
-      agentType,
-      '',
-      inPlace ? (sessionId: string): void => this.routeRemoteSessionInPlace(sessionId) :
-        (sessionId: string): void => this.routeCreatedRemoteSession(sessionId)
-    );
-  }
-
-  openRemoteCreateSession(): void {
-    const runtime = this.requireRemoteRuntime();
-    if (!runtime.connection.ensureAvailable()) {
-      return;
-    }
-    const deviceId = this.remote.controlTargetDeviceId || this.remote.desktopId;
-    const deviceName = this.remote.controlTargetDeviceName || this.remote.desktopName;
-    this.remoteCreate.prepare(deviceId, deviceName, this.remote.selectedModelId);
-    if (deviceId.length > 0) {
-      this.remoteCreate.setDevices([{
-        deviceId,
-        deviceName: deviceName || deviceId,
-        online: true
-      }]);
-    }
-    this.remoteCreate.setWorkspaces(this.remote.recentWorkspaces);
-    runtime.appShell.pushRoute(AppRoute.RemoteCreate);
-    this.loadRemoteCreateChoices();
-    this.loadRemoteCreateModelCatalog();
-  }
-
-  closeRemoteCreateSession(): void {
-    const runtime = this.requireRemoteRuntime();
-    this.remoteCreateWorkspaceLoadVersion += 1;
-    runtime.hooks.stopVoiceInput();
-    this.remoteCreate.closeMenu();
-    runtime.appShell.popRoute(AppRoute.RemoteHome);
-  }
-
-  async loadRemoteCreateChoices(): Promise<void> {
-    await Promise.all([
-      this.loadRemoteCreateDevices(),
-      this.loadRemoteCreateWorkspaces()
-    ]);
-  }
-
-  async loadRemoteCreateModelCatalog(): Promise<void> {
-    const runtime = this.requireRemoteRuntime();
-    if (this.remote.modelCatalog.models.length > 0) {
-      return;
-    }
-    try {
-      const catalog = await runtime.sessionManager.getModelCatalog();
-      const selectedModelId = RemoteUiState.selectedModelIdForCatalog(catalog, this.remote.selectedModelId);
-      this.remote.setModelCatalog(catalog, selectedModelId);
-      this.remoteCreate.setSelectedModelId(selectedModelId);
-    } catch (_err) {
-      // Model selection remains hidden when the remote does not expose a catalog.
-    }
-  }
-
-  async loadRemoteCreateDevices(): Promise<void> {
-    const runtime = this.requireRemoteRuntime();
-    this.remoteCreate.isLoadingDevices = this.remoteCreate.devices.length === 0;
-    try {
-      const phoneDeviceId = runtime.connection.getDeviceId();
-      const accountDevices = await runtime.settings.listCloudAccountDevices();
-      const devices = accountDevices.filter((device: CloudAccountDevice): boolean =>
-        device.online && device.deviceId !== phoneDeviceId
-      );
-      const currentId = this.remoteCreate.selectedDeviceId;
-      if (currentId.length > 0 &&
-        !devices.some((device: CloudAccountDevice): boolean => device.deviceId === currentId)) {
-        devices.unshift({
-          deviceId: currentId,
-          deviceName: this.remoteCreate.selectedDeviceName || currentId,
-          online: true
-        });
-      }
-      this.remoteCreate.setDevices(devices);
-    } catch (_err) {
-      const currentId = this.remoteCreate.selectedDeviceId;
-      if (currentId.length > 0) {
-        this.remoteCreate.setDevices([{
-          deviceId: currentId,
-          deviceName: this.remoteCreate.selectedDeviceName || currentId,
-          online: true
-        }]);
-      } else {
-        this.remoteCreate.setDevices([]);
-      }
-      this.remoteCreate.errorText = RemoteI18n.t('remote.create.deviceLoadFailed');
-    }
-  }
-
-  async loadRemoteCreateWorkspaces(): Promise<void> {
-    const runtime = this.requireRemoteRuntime();
-    const loadVersion = ++this.remoteCreateWorkspaceLoadVersion;
-    const deviceId = this.remoteCreate.selectedDeviceId;
-    this.remoteCreate.isLoadingWorkspaces = this.remoteCreate.workspaces.length === 0;
-    try {
-      const workspaces = await runtime.workspace.recentWorkspaces();
-      if (loadVersion !== this.remoteCreateWorkspaceLoadVersion ||
-        deviceId !== this.remoteCreate.selectedDeviceId) {
-        return;
-      }
-      this.remoteCreate.setWorkspaces(workspaces);
-    } catch (_err) {
-      if (loadVersion !== this.remoteCreateWorkspaceLoadVersion ||
-        deviceId !== this.remoteCreate.selectedDeviceId) {
-        return;
-      }
-      this.remoteCreate.setWorkspaces([]);
-      this.remoteCreate.errorText = RemoteI18n.t('remote.create.workspaceLoadFailed');
-    }
-  }
-
-  toggleRemoteCreateDevices(): void {
-    this.remoteCreate.toggleMenu('devices');
-    if (this.remoteCreate.openMenu === 'devices' && this.remoteCreate.devices.length === 0) {
-      this.loadRemoteCreateDevices();
-    }
-  }
-
-  toggleRemoteCreateWorkspaces(): void {
-    this.remoteCreate.toggleMenu('workspaces');
-    if (this.remoteCreate.openMenu === 'workspaces' && this.remoteCreate.workspaces.length === 0) {
-      this.loadRemoteCreateWorkspaces();
-    }
-  }
-
+    await this.createFlow.createRemoteSession(agentType, inPlace);
+  }
+  openRemoteCreateSession(): void { this.createFlow.openRemoteCreateSession(); }
+  closeRemoteCreateSession(): void { this.createFlow.closeRemoteCreateSession(); }
+  async loadRemoteCreateChoices(): Promise<void> { await this.createFlow.loadRemoteCreateChoices(); }
+  async loadRemoteCreateModelCatalog(): Promise<void> { await this.createFlow.loadRemoteCreateModelCatalog(); }
+  async loadRemoteCreateDevices(): Promise<void> { await this.createFlow.loadRemoteCreateDevices(); }
+  async loadRemoteCreateWorkspaces(): Promise<void> { await this.createFlow.loadRemoteCreateWorkspaces(); }
+  toggleRemoteCreateDevices(): void { this.createFlow.toggleRemoteCreateDevices(); }
+  toggleRemoteCreateWorkspaces(): void { this.createFlow.toggleRemoteCreateWorkspaces(); }
   async selectRemoteCreateDevice(device: CloudAccountDevice): Promise<void> {
-    const runtime = this.requireRemoteRuntime();
-    if (device.deviceId === this.remoteCreate.selectedDeviceId) {
-      this.remoteCreate.closeMenu();
-      return;
-    }
-    const draft = this.remoteCreate.draft;
-    this.remoteCreate.closeMenu();
-    this.remoteCreate.isLoadingWorkspaces = true;
-    try {
-      await runtime.settings.selectCloudAccountDevice(device, false);
-      this.remoteCreate.selectDevice(device);
-      this.remoteCreate.setDraft(draft);
-      await this.loadRemoteCreateWorkspaces();
-    } catch (err) {
-      this.remoteCreate.isLoadingWorkspaces = false;
-      this.remoteCreate.errorText = err instanceof Error ? err.message :
-        RemoteI18n.t('remote.settings.deviceSwitchFailed');
-    }
-  }
-
-  selectRemoteCreateWorkspace(path: string): void {
-    const workspace = this.remoteCreate.workspaces
-      .find((item: RecentWorkspaceEntry): boolean => item.path === path);
-    this.remoteCreate.selectWorkspace(workspace);
-  }
-
-  async submitRemoteCreateSession(): Promise<void> {
-    const runtime = this.requireRemoteRuntime();
-    const instruction = this.remoteCreate.draft.trim();
-    if (instruction.length === 0 || this.remoteCreate.isSubmitting || !runtime.connection.ensureAvailable()) {
-      return;
-    }
-    const context = this.remoteCreate.submissionContext();
-    const activeDeviceId = this.remote.controlTargetDeviceId || this.remote.desktopId;
-    if (context.deviceId.length === 0 || context.deviceId !== activeDeviceId) {
-      this.remoteCreate.errorText = RemoteI18n.t('remote.create.deviceMismatch');
-      return;
-    }
-    this.remoteCreate.isSubmitting = true;
-    this.remoteCreate.errorText = '';
-    this.remoteCreate.closeMenu();
-    try {
-      if (context.workspacePath.length > 0) {
-        await runtime.sessions.createSessionInWorkspace(
-          context.workspacePath,
-          this.remote.workspacePath,
-          instruction,
-          context.agentType,
-          undefined,
-          this.remoteCreate.selectedModelId
-        );
-      } else {
-        await this.bindAssistantWorkspace();
-        await runtime.sessions.createSession(
-          context.agentType,
-          instruction,
-          undefined,
-          this.remoteCreate.selectedModelId
-        );
-      }
-      if (runtime.appShell.isRoute(AppRoute.RemoteCreate)) {
-        this.remoteCreate.errorText = this.remote.statusText || RemoteI18n.t('remote.create.submitFailed');
-      }
-    } catch (err) {
-      this.remoteCreate.errorText = err instanceof Error ? err.message :
-        RemoteI18n.t('remote.create.submitFailed');
-    } finally {
-      this.remoteCreate.isSubmitting = false;
-    }
-  }
-
-  /**
-   * The chat option creates a Claw session, and the desktop always binds those
-   * to its assistant workspace. Follow it there first, otherwise the app stays
-   * bound to the code workspace it was on and the new chat is listed, titled
-   * and file-scoped as if it had been created inside that workspace.
-   */
-  private async bindAssistantWorkspace(): Promise<void> {
-    const runtime = this.requireRemoteRuntime();
-    if (this.remote.workspaceKind === 'assistant') {
-      return;
-    }
-    try {
-      const assistants = await runtime.workspace.assistants();
-      if (assistants.length === 0) {
-        return;
-      }
-      await runtime.hooks.selectAssistantWorkspace(assistants[0].path);
-    } catch (err) {
-      RemoteLogger.warn(`assistant workspace bind failed: ${String(err)}`);
-    }
+    await this.createFlow.selectRemoteCreateDevice(device);
   }
-
+  selectRemoteCreateWorkspace(path: string): void { this.createFlow.selectRemoteCreateWorkspace(path); }
+  async submitRemoteCreateSession(): Promise<void> { await this.createFlow.submitRemoteCreateSession(); }
   async createRemoteSessionInWorkspace(
     path: string,
     agentType: string = 'code',
     inPlace: boolean = false
   ): Promise<void> {
-    const runtime = this.requireRemoteRuntime();
-    runtime.filePreview.close();
-    await runtime.sessions.createSessionInWorkspace(
-      path,
-      this.remote.workspacePath,
-      '',
-      agentType,
-      inPlace ? (sessionId: string): void => this.routeRemoteSessionInPlace(sessionId) :
-        (sessionId: string): void => this.routeCreatedRemoteSession(sessionId)
-    );
+    await this.createFlow.createRemoteSessionInWorkspace(path, agentType, inPlace);
   }
-
   async openRemoteSession(item: RemoteSession, inPlace: boolean = false): Promise<void> {
-    const runtime = this.requireRemoteRuntime();
-    runtime.filePreview.close();
-    await runtime.sessions.openSession(
-      item,
-      this.remote.workspacePath,
-      inPlace ? (sessionId: string): void => this.routeRemoteSessionInPlace(sessionId) :
-        (sessionId: string): void => this.routeCreatedRemoteSession(sessionId)
-    );
+    await this.createFlow.openRemoteSession(item, inPlace);
   }
-
   applyRemoteActiveSession(session: SessionSummary): void {
-    const runtime = this.requireRemoteRuntime();
-    const current = this.remote.activeSession;
-    if (runtime.hooks.isFilePreviewVisible() &&
-      (current.sessionId !== session.sessionId || current.workspacePath !== session.workspacePath)) {
-      runtime.filePreview.close();
-    }
-    this.remote.setActiveSession(session);
+    this.createFlow.applyRemoteActiveSession(session);
   }
-
   async deleteRemoteSession(item: RemoteSession): Promise<void> {
-    await this.requireRemoteRuntime().sessions.deleteSession(item, this.remote.workspacePath);
-  }
-
-  openHomeSession(session: RemoteSession, inPlace: boolean = false): void {
-    this.requireRemoteRuntime().filePreview.close();
-    if (session.agentType === 'chat') {
-      this.openGeneralSession(session);
-      return;
-    }
-    this.openRemoteSession(session, inPlace);
-  }
-
-  async deleteHomeSession(session: RemoteSession): Promise<void> {
-    if (session.agentType !== 'chat') {
-      await this.deleteRemoteSession(session);
-      return;
-    }
-    await this.requireRemoteRuntime().generalCommands.deleteSession(session, this.general.isBusy);
+    await this.createFlow.deleteRemoteSession(item);
   }
-
-  activeGeneralChatAsRemoteSession(): RemoteSession {
-    const active = this.general.activeSession;
-    return {
-      id: active.sessionId,
-      title: active.title,
-      agentType: 'chat',
-      status: 'ready',
-      updatedAt: '',
-      createdAt: '',
-      messageCount: this.general.timelineItems.length,
-      workspacePath: active.workspacePath
-    };
+  routeCreatedRemoteSession(sessionId: string): void {
+    this.createFlow.routeCreatedRemoteSession(sessionId);
   }
 
-  activeGeneralUploadedFileCount(): number {
-    let count = 0;
-    this.general.timelineItems.forEach((item: ChatTimelineItem) => {
-      if (item.message && item.message.images) {
-        count += item.message.images.length;
-      }
-    });
-    return count;
+  openHomeSession(session: RemoteSession, inPlace: boolean = false): void {
+    this.visible.openHomeSession(session, inPlace);
   }
-
+  async deleteHomeSession(session: RemoteSession): Promise<void> { await this.visible.deleteHomeSession(session); }
+  activeGeneralChatAsRemoteSession(): RemoteSession { return this.visible.activeGeneralChatAsRemoteSession(); }
+  activeGeneralUploadedFileCount(): number { return this.visible.activeGeneralUploadedFileCount(); }
   async archiveHomeSession(session: RemoteSession, archived: boolean): Promise<void> {
-    await this.requireRemoteRuntime().generalCommands.archiveSession(session, archived, this.general.isBusy);
-  }
-
-  async exportHomeSession(session: RemoteSession): Promise<void> {
-    const runtime = this.requireRemoteRuntime();
-    await runtime.generalCommands.exportSession(
-      session,
-      this.general.isBusy,
-      async (text: string): Promise<void> => runtime.clipboard.writeText(text)
-    );
-  }
-
-  async openGeneralSession(item: RemoteSession): Promise<void> {
-    const runtime = this.requireRemoteRuntime();
-    if (this.general.isBusy) {
-      return;
-    }
-    runtime.polling.stop();
-    runtime.generalConversation.stop(false);
-    await runtime.generalCommands.openSession(
-      item,
-      this.general.isBusy,
-      async (sessionId: string): Promise<string> => runtime.generalDrafts.restore(sessionId),
-      (_sessionId: string): void => runtime.appShell.replaceRouteWithoutAnimation(AppRoute.ChatHome)
-    );
-  }
-
-  async startGeneralChat(text: string): Promise<void> {
-    const runtime = this.requireRemoteRuntime();
-    const trimmed = text.trim();
-    if (trimmed.length === 0 || this.general.isBusy) {
-      return;
-    }
-    runtime.polling.stop();
-    runtime.generalConversation.stop(false);
-    runtime.generalDrafts.cancel();
-    const created = await runtime.generalCommands.createSession(
-      trimmed,
-      this.general.isBusy,
-      async (): Promise<void> => runtime.generalDrafts.clearHomeNow(),
-      (_sessionId: string): void => runtime.appShell.replaceRouteWithoutAnimation(AppRoute.ChatHome)
-    );
-    if (created) {
-      await runtime.generalConversation.sendMessage();
-    }
-  }
-
-  async sendVisibleMessage(): Promise<void> {
-    const runtime = this.requireRemoteRuntime();
-    if (runtime.appShell.isGeneralChatVisible()) {
-      if ((this.general.activeSession.sessionId || '').length === 0) {
-        this.startVisibleGeneralChat();
-        return;
-      }
-      await runtime.generalConversation.sendMessage();
-      return;
-    }
-    await this.sendRemoteMessage();
-  }
-
-  async stopVisibleTask(): Promise<void> {
-    const runtime = this.requireRemoteRuntime();
-    if (runtime.appShell.isGeneralChatVisible()) {
-      runtime.generalConversation.stop(true);
-      return;
-    }
-    await this.stopRemoteTask();
-  }
-
-  closeActiveChat(): void {
-    const runtime = this.requireRemoteRuntime();
-    runtime.filePreview.close();
-    runtime.hooks.stopVoiceInput();
-    if (runtime.appShell.isRoute(AppRoute.GeneralChat)) {
-      runtime.generalDrafts.persistVisible(this.general.chatInput);
-      runtime.generalConversation.stop(true);
-      runtime.appShell.popRoute(AppRoute.ChatHome);
-      this.restoreGeneralChatDraft(GENERAL_CHAT_HOME_DRAFT_ID);
-      return;
-    }
-    runtime.polling.stop();
-    this.remote.setConversationDismissed(true);
-    runtime.appShell.replaceRouteWithoutAnimation(AppRoute.RemoteHome);
-  }
-
-  async renameVisibleSession(title: string): Promise<void> {
-    const runtime = this.requireRemoteRuntime();
-    if (runtime.appShell.isGeneralChatVisible()) {
-      await runtime.generalCommands.renameActiveSession(this.general.activeSession, title);
-      return;
-    }
-    await this.renameRemoteSession(title);
-  }
-
-  async retryVisibleMessage(text: string): Promise<void> {
-    const runtime = this.requireRemoteRuntime();
-    if (runtime.appShell.isGeneralChatVisible()) {
-      const prepared = await runtime.generalCommands.retryMessage(
-        this.general.activeSession.sessionId || '', text, this.general.isBusy
-      );
-      if (prepared) {
-        await runtime.generalConversation.sendMessage();
-      }
-      return;
-    }
-    this.retryRemoteMessage(text);
-  }
-
-  downloadVisibleFile(path: string): void {
-    if (this.requireRemoteRuntime().appShell.isGeneralChatVisible()) {
-      this.general.setStatus(RemoteI18n.t('generalChat.fileDownloadMock'));
-      return;
-    }
-    this.downloadRemoteFile(path);
-  }
-
-  async selectVisibleModel(modelId: string): Promise<void> {
-    const runtime = this.requireRemoteRuntime();
-    if (runtime.appShell.isGeneralChatVisible()) {
-      await runtime.settings.selectModel(modelId);
-      return;
-    }
-    await this.selectRemoteModel(modelId);
-  }
-
-  startVisibleGeneralChat(): void {
-    const rawText = this.general.chatInput.trim();
-    const text = rawText.length > 0 ? rawText :
-      (this.general.selectedImages.length > 0 ? RemoteI18n.t('chat.analyzeImageDefault') : '');
-    if (text.length === 0 || this.general.isBusy) {
-      return;
-    }
-    if (this.general.serviceState === GeneralChatServiceState.Unconfigured) {
-      const statusText = GeneralChatServiceStatus.userMessage(this.general.serviceState);
-      this.general.setStatus(statusText);
-      this.showHomeToast(statusText);
-      return;
-    }
-    this.startGeneralChat(text);
-  }
-
-  generalChatHomeStatusText(): string {
-    if (this.general.serviceState === GeneralChatServiceState.Ready ||
-      this.general.serviceState === GeneralChatServiceState.Sending ||
-      this.general.serviceState === GeneralChatServiceState.Streaming) {
-      return '';
-    }
-    return GeneralChatServiceStatus.userMessage(this.general.serviceState, this.general.statusText);
-  }
-
-  prepareNewGeneralChat(): void {
-    const runtime = this.requireRemoteRuntime();
-    runtime.hooks.stopVoiceInput();
-    runtime.generalConversation.stop(true);
-    runtime.generalDrafts.clearHome();
-    this.general.clearComposer();
-    this.general.clearActiveSession();
-    this.resetGeneralTimeline('');
-    runtime.appShell.replaceRouteWithoutAnimation(AppRoute.ChatHome);
-  }
-
+    await this.visible.archiveHomeSession(session, archived);
+  }
+  async exportHomeSession(session: RemoteSession): Promise<void> { await this.visible.exportHomeSession(session); }
+  async openGeneralSession(item: RemoteSession): Promise<void> { await this.visible.openGeneralSession(item); }
+  async startGeneralChat(text: string): Promise<void> { await this.visible.startGeneralChat(text); }
+  async sendVisibleMessage(): Promise<void> { await this.visible.sendVisibleMessage(); }
+  async stopVisibleTask(): Promise<void> { await this.visible.stopVisibleTask(); }
+  closeActiveChat(): void { this.visible.closeActiveChat(); }
+  async renameVisibleSession(title: string): Promise<void> { await this.visible.renameVisibleSession(title); }
+  async retryVisibleMessage(text: string): Promise<void> { await this.visible.retryVisibleMessage(text); }
+  downloadVisibleFile(path: string): void { this.visible.downloadVisibleFile(path); }
+  async selectVisibleModel(modelId: string): Promise<void> { await this.visible.selectVisibleModel(modelId); }
+  startVisibleGeneralChat(): void { this.visible.startVisibleGeneralChat(); }
+  generalChatHomeStatusText(): string { return this.visible.generalChatHomeStatusText(); }
+  prepareNewGeneralChat(): void { this.visible.prepareNewGeneralChat(); }
   onVisibleChatInputChange(route: AppRoute, value: string): void {
-    this.setChatInput(route, value);
-    if (this.isGeneralComposerRoute(route)) {
-      this.requireRemoteRuntime().generalDrafts.scheduleVisible(value);
-    }
-  }
-
-  visibleGeneralChatDraftId(): string {
-    return this.requireRemoteRuntime().appShell.isGeneralChatVisible() ?
-      this.general.activeSession.sessionId || GENERAL_CHAT_HOME_DRAFT_ID : '';
+    this.visible.onVisibleChatInputChange(route, value);
   }
-
+  visibleGeneralChatDraftId(): string { return this.visible.visibleGeneralChatDraftId(); }
   async restoreGeneralChatDraft(draftId: string): Promise<void> {
-    this.general.setChatInput(await this.requireRemoteRuntime().generalDrafts.restore(draftId));
-  }
-
-  latestUserMessageText(): string {
-    if (this.requireRemoteRuntime().appShell.isGeneralChatVisible()) {
-      return this.general.latestUserMessageText();
-    }
-    const candidates = this.remote.persistedMessages.concat(this.remote.optimisticMessages);
-    for (let index = candidates.length - 1; index >= 0; index--) {
-      if (candidates[index].role === 'user' && candidates[index].text.trim().length > 0) {
-        return candidates[index].text;
-      }
-    }
-    return '';
-  }
-
-  resetGeneralTimeline(sessionId: string): void {
-    this.requireRemoteRuntime().timeline.reset(sessionId);
-    this.syncGeneralTimeline();
-  }
-
-  syncGeneralTimeline(): void {
-    const runtime = this.requireRemoteRuntime();
-    const state: ChatTimelineState = runtime.timeline.snapshotState();
-    const projectedItems = runtime.timeline.viewState(false);
-    this.general.setTimelineProjection(
-      state.persistedMessages,
-      state.optimisticMessages,
-      state.activeTurn || RemoteUiState.emptyActiveTurn(),
-      false,
-      projectedItems
-    );
-    const itemSummary = projectedItems.map((item: ChatTimelineItem) => {
-      const message = item.message;
-      return `${item.type}:${item.id}:${message ? message.status : ''}:${message ? message.text.length : 0}`;
-    }).join(',');
-    RemoteLogger.info(`general chat projection revision=${this.general.timelineRevision} persisted=${state.persistedMessages.length} active=${state.activeTurn ? state.activeTurn.id : 'none'} items=${itemSummary}`);
-  }
-
-  showHomeToast(message: string): void {
-    const runtime = this.requireRemoteRuntime();
-    if (!runtime.hooks.showToast(message)) {
-      this.setVisibleStatusText(message);
-    }
-  }
-
-  private currentChatPollingCursor(): RemoteChatPollingCursor {
-    return {
-      pollVersion: this.knownPollVersionValue,
-      knownMessageCount: this.knownRemoteMessageCount,
-      knownModelCatalogVersion: this.knownModelCatalogVersion
-    };
-  }
-
-  private updateChatPollingCursor(pollVersion: number, knownMessageCount: number): void {
-    this.knownPollVersionValue = pollVersion;
-    this.knownRemoteMessageCount = knownMessageCount;
-    this.requireRemoteRuntime().polling.updateCursor({
-      pollVersion,
-      knownMessageCount,
-      knownModelCatalogVersion: this.knownModelCatalogVersion
-    });
-  }
-
-  private async syncAfterRemoteTurnEnded(): Promise<void> {
-    if (this.isSyncingAfterTurn) {
-      return;
-    }
-    this.isSyncingAfterTurn = true;
-    try {
-      await this.loadRemoteMessages();
-    } finally {
-      this.isSyncingAfterTurn = false;
-    }
-  }
-
-  private shortSessionId(sessionId: string): string {
-    return sessionId.length <= 8 ? sessionId :
-      sessionId.slice(0, 4) + '...' + sessionId.slice(sessionId.length - 4);
-  }
-
-  routeCreatedRemoteSession(sessionId: string): void {
-    const runtime = this.requireRemoteRuntime();
-    runtime.filePreview.close();
-    this.remote.setConversationDismissed(false);
-    if (runtime.appShell.isRoute(AppRoute.RemoteCreate)) {
-      runtime.appShell.replaceCurrentRoute(AppRoute.RemoteChat, sessionId);
-      return;
-    }
-    runtime.appShell.pushRoute(AppRoute.RemoteChat, sessionId);
-  }
-
-  private routeRemoteSessionInPlace(sessionId: string): void {
-    const runtime = this.requireRemoteRuntime();
-    runtime.filePreview.close();
-    this.remote.setConversationDismissed(false);
-    const target = AppRouteContract.remoteSessionDestination(sessionId);
-    runtime.appShell.replaceRouteWithoutAnimation(target.name, target.routeParam().sessionId);
-  }
-
-  private requireRemoteRuntime(): RemoteConversationDependencies {
-    if (!this.remoteRuntime) {
-      throw new Error('Remote conversation dependencies are not configured.');
-    }
-    return this.remoteRuntime;
+    await this.visible.restoreGeneralChatDraft(draftId);
   }
+  latestUserMessageText(): string { return this.visible.latestUserMessageText(); }
+  resetGeneralTimeline(sessionId: string): void { this.visible.resetGeneralTimeline(sessionId); }
+  syncGeneralTimeline(): void { this.visible.syncGeneralTimeline(); }
+  showHomeToast(message: string): void { this.visible.showHomeToast(message); }
 }
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/ConversationRuntime.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/ConversationRuntime.ets
new file mode 100644
index 0000000000..50766953c1
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/ConversationRuntime.ets
@@ -0,0 +1,99 @@
+import { ImagePickerService } from '../../services/ImagePickerService';
+import { ClipboardService } from '../../services/ClipboardService';
+import { GeneralChatCommandController } from '../../services/general-chat/GeneralChatCommandController';
+import { GeneralChatDraftLifecycleController } from '../../services/general-chat/GeneralChatDraftLifecycleController';
+import { RemoteChatCache } from '../../services/RemoteChatCache';
+import { RemoteChatCommandController } from '../../services/RemoteChatCommandController';
+import { RemoteChatPollingLifecycleController } from '../../services/RemoteChatPollingLifecycleController';
+import { RemoteFileDownloadController } from '../../services/RemoteFileDownloadController';
+import { RemoteModelController } from '../../services/RemoteModelController';
+import { RemoteToolActionController } from '../../services/RemoteToolActionController';
+import { RemoteSessionManager } from '../../services/RemoteSessionManager';
+import { RemoteWorkspaceCoordinator } from '../../services/RemoteWorkspaceCoordinator';
+import { AppRoute, AppRouteContract } from '../navigation/AppRouteContract';
+import { ConversationViewModel } from './ConversationViewModel';
+import { AppShellViewModel } from './AppShellViewModel';
+import { FilePreviewController } from './FilePreviewController';
+import { RemoteConnectionController } from './RemoteConnectionController';
+import { RemoteSessionViewModel } from './RemoteSessionViewModel';
+import { SettingsController } from './SettingsController';
+import { GeneralChatConversationViewModel } from './GeneralChatConversationViewModel';
+
+export const GENERAL_CHAT_HOME_DRAFT_ID: string = 'new-chat';
+
+export interface ConversationControllerHooks {
+  readonly currentRoute: () => AppRoute;
+}
+
+export interface RemoteConversationHooks {
+  readonly isConversationContext: (sessionId: string) => boolean;
+  readonly isFilePreviewVisible: () => boolean;
+  readonly stopVoiceInput: () => Promise<void>;
+  readonly showToast: (message: string) => boolean;
+  readonly selectAssistantWorkspace: (path: string) => Promise<void>;
+}
+
+export interface RemoteConversationDependencies {
+  readonly timeline: ConversationViewModel;
+  readonly chat: RemoteChatCommandController;
+  readonly chatCache: RemoteChatCache;
+  readonly polling: RemoteChatPollingLifecycleController;
+  readonly models: RemoteModelController;
+  readonly files: RemoteFileDownloadController;
+  readonly tools: RemoteToolActionController;
+  readonly connection: RemoteConnectionController;
+  readonly imagePicker: ImagePickerService;
+  readonly clipboard: ClipboardService;
+  readonly sessions: RemoteSessionViewModel;
+  readonly sessionManager: RemoteSessionManager;
+  readonly workspace: RemoteWorkspaceCoordinator;
+  readonly settings: SettingsController;
+  readonly appShell: AppShellViewModel;
+  readonly filePreview: FilePreviewController;
+  readonly generalCommands: GeneralChatCommandController;
+  readonly generalConversation: GeneralChatConversationViewModel;
+  readonly generalDrafts: GeneralChatDraftLifecycleController;
+  readonly hooks: RemoteConversationHooks;
+}
+
+export function requireRemoteRuntime(
+  remoteRuntime?: RemoteConversationDependencies
+): RemoteConversationDependencies {
+  if (!remoteRuntime) {
+    throw new Error('Remote conversation dependencies are not configured.');
+  }
+  return remoteRuntime;
+}
+
+export function shortSessionId(sessionId: string): string {
+  return sessionId.length <= 8 ? sessionId :
+    sessionId.slice(0, 4) + '...' + sessionId.slice(sessionId.length - 4);
+}
+
+export function routeCreatedRemoteSession(
+  sessionId: string,
+  remoteRuntime: RemoteConversationDependencies,
+  setDismissed: (dismissed: boolean) => void
+): void {
+  remoteRuntime.filePreview.close();
+  setDismissed(false);
+  if (remoteRuntime.appShell.isRoute(AppRoute.RemoteChat)) {
+    return;
+  }
+  if (remoteRuntime.appShell.isRoute(AppRoute.RemoteCreate)) {
+    remoteRuntime.appShell.replaceCurrentRoute(AppRoute.RemoteChat, sessionId);
+    return;
+  }
+  remoteRuntime.appShell.pushRoute(AppRoute.RemoteChat, sessionId);
+}
+
+export function routeRemoteSessionInPlace(
+  sessionId: string,
+  remoteRuntime: RemoteConversationDependencies,
+  setDismissed: (dismissed: boolean) => void
+): void {
+  remoteRuntime.filePreview.close();
+  setDismissed(false);
+  const target = AppRouteContract.remoteSessionDestination(sessionId);
+  remoteRuntime.appShell.replaceRouteWithoutAnimation(target.name, target.routeParam().sessionId);
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/RemoteActivityViewModel.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/RemoteActivityViewModel.ets
index 8228df45dd..632e3d4681 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/RemoteActivityViewModel.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/RemoteActivityViewModel.ets
@@ -4,9 +4,11 @@ import { ConnectionErrorPolicy } from '../../services/ConnectionErrorPolicy';
 import { AsyncLifecycleGate } from '../../services/AsyncLifecycleGate';
 import { RemoteActivityLifecycleController } from '../../services/RemoteActivityLifecycleController';
 import { RemoteConnectionCoordinator } from '../../services/RemoteConnectionCoordinator';
+import { RemoteLogger } from '../../services/RemoteLogger';
 
 export interface RemoteActivityViewModelHooks {
   readonly isConnected: () => boolean;
+  readonly isReconnecting: () => boolean;
   readonly isBusy: () => boolean;
   readonly hasRemoteBinding: () => boolean;
   readonly isRemoteChat: () => boolean;
@@ -14,7 +16,6 @@ export interface RemoteActivityViewModelHooks {
   readonly onConnectionState: (state: string) => void;
   readonly onStatus: (status: string) => void;
   readonly onConnectionError: (err: Object) => Promise<boolean>;
-  readonly onStopHeartbeat: () => void;
   readonly onStartPolling: () => void;
   readonly onStopPolling: () => void;
   readonly onPoll: () => Promise<void>;
@@ -28,6 +29,7 @@ export class RemoteActivityViewModel {
   private readonly connection: RemoteConnectionCoordinator;
   private readonly gate: AsyncLifecycleGate;
   private readonly hooks: RemoteActivityViewModelHooks;
+  private recovering: boolean = false;
 
   constructor(
     activity: RemoteActivityLifecycleController,
@@ -49,21 +51,52 @@ export class RemoteActivityViewModel {
     this.activity.stopHeartbeat();
   }
 
+  /**
+   * A health check while the link is up, a recovery probe once it is not.
+   *
+   * A failed ping used to park the connection in `failed` and stop the
+   * heartbeat with it. Nothing survived that: the poller was stopped too, and
+   * `failed` disables every remote action, so a desktop that blinked out for a
+   * moment left the phone dead until the user backgrounded and refocused the
+   * app. The heartbeat is the only thing still ticking at that point, which
+   * makes it the only thing that can notice the desktop coming back — so it
+   * keeps ticking, and the first ping that answers puts the session back on the
+   * wire. Ticks are serialised by the heartbeat itself, and a ping is cheap
+   * enough to repeat every interval for as long as the drop lasts.
+   */
   async checkConnectionHealth(): Promise<void> {
-    if (!this.hooks.isConnected() || this.hooks.isBusy()) {
+    if (this.hooks.isBusy() || this.recovering || !this.hooks.hasRemoteBinding()) {
+      return;
+    }
+    const wasConnected = this.hooks.isConnected();
+    if (!wasConnected && !this.hooks.isReconnecting()) {
       return;
     }
     try {
       await this.connection.ping();
+      if (!wasConnected) {
+        await this.restoreAfterHealthyPing();
+      }
     } catch (err) {
       if (await this.hooks.onConnectionError(err)) {
         return;
       }
-      const message = ConnectionErrorPolicy.errorText(err);
-      this.hooks.onConnectionState('failed');
-      this.hooks.onStatus(message);
-      this.hooks.onStopPolling();
-      this.hooks.onStopHeartbeat();
+      this.hooks.onStatus(ConnectionErrorPolicy.errorText(err));
+      if (wasConnected) {
+        RemoteLogger.info('heartbeat ping failed, waiting for the link to come back');
+        this.hooks.onStopPolling();
+        this.hooks.onConnectionState('reconnecting');
+      }
+    }
+  }
+
+  private async restoreAfterHealthyPing(): Promise<void> {
+    RemoteLogger.info('heartbeat ping answered, link restored');
+    this.hooks.onConnectionState('connected');
+    this.hooks.onStatus(RemoteI18n.t('connection.connected'));
+    if (this.hooks.isRemoteChat() && this.hooks.activeSession().sessionId.length > 0) {
+      this.hooks.onStartPolling();
+      await this.hooks.onPoll();
     }
   }
 
@@ -103,9 +136,18 @@ export class RemoteActivityViewModel {
         return;
       }
       this.hooks.onStatus(ConnectionErrorPolicy.errorText(err));
-      this.hooks.onStopHeartbeat();
       this.hooks.onConnectionState('reconnecting');
-      await this.reconnect(token);
+      // The heartbeat keeps running through this. If the reconnect below fails
+      // there is nothing else left to try again, and its next tick is the retry
+      // — it just has to stay out of the way while this one is in flight.
+      this.recovering = true;
+      try {
+        await this.reconnect(token);
+      } catch (reconnectErr) {
+        this.hooks.onStatus(ConnectionErrorPolicy.errorText(reconnectErr));
+      } finally {
+        this.recovering = false;
+      }
     }
   }
 
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/RemoteConnectionController.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/RemoteConnectionController.ets
index 40e66955c8..bdf88a4966 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/RemoteConnectionController.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/RemoteConnectionController.ets
@@ -11,6 +11,11 @@ import { MobileIdentitySnapshot, MobileIdentityStore } from '../../services/Mobi
 import { RemoteDescriptorParser } from '../../services/RemoteDescriptorParser';
 import { RemoteFileDownloadController } from '../../services/RemoteFileDownloadController';
 import { RemoteModelController } from '../../services/RemoteModelController';
+import {
+  ConnectScanDecisionPolicy,
+  DetectedRemoteUrlResult,
+  DetectedUrlAction
+} from '../../services/ConnectScanDecisionPolicy';
 import { RemotePairingPolicy } from '../../services/RemotePairingPolicy';
 import { RemoteSessionController } from '../../services/RemoteSessionController';
 import { RemoteUiState } from '../../services/RemoteUiState';
@@ -46,6 +51,7 @@ export class RemoteConnectionController {
   private readonly stopHeartbeat: () => void;
   private readonly stopPolling: () => void;
   private readonly loadRecentWorkspaces: () => Promise<void>;
+  private readonly clearCachedRemoteData: () => Promise<void>;
   private readonly replaceRoute: (route: AppRoute) => void;
   private readonly closeConnectSheet: () => void;
   private readonly openConnectSheet: () => void;
@@ -70,6 +76,7 @@ export class RemoteConnectionController {
     stopHeartbeat: () => void,
     stopPolling: () => void,
     loadRecentWorkspaces: () => Promise<void>,
+    clearCachedRemoteData: () => Promise<void>,
     replaceRoute: (route: AppRoute) => void,
     closeConnectSheet: () => void,
     openConnectSheet: () => void
@@ -89,6 +96,7 @@ export class RemoteConnectionController {
     this.stopHeartbeat = stopHeartbeat;
     this.stopPolling = stopPolling;
     this.loadRecentWorkspaces = loadRecentWorkspaces;
+    this.clearCachedRemoteData = clearCachedRemoteData;
     this.replaceRoute = replaceRoute;
     this.closeConnectSheet = closeConnectSheet;
     this.openConnectSheet = openConnectSheet;
@@ -167,7 +175,10 @@ export class RemoteConnectionController {
       this.pageState.setStatusText(RemoteI18n.t('connection.connected'));
       this.closeConnectSheet();
       this.startHeartbeat();
-      await this.loadRecentWorkspaces();
+      // Left running rather than awaited: this scan costs one round trip per
+      // recent workspace, and everything it finds is an addition to a session
+      // list that is already on screen. Its own failures are logged inside.
+      void this.loadRecentWorkspaces();
       this.pageState.setLoadingHome(false);
       RemoteLogger.info('connect success');
     } catch (err) {
@@ -238,6 +249,10 @@ export class RemoteConnectionController {
       this.pageState.setAccountPairing(false, '');
       this.pageState.setRemoteUrlInputVisible(false);
       await this.identity.clearPairingInput();
+      // Unpairing is the user saying they are done with that desktop. Leaving
+      // its sessions on disk would put them back on Remote Home at the next
+      // launch, with nothing behind them to open.
+      await this.clearCachedRemoteData();
     } else {
       this.pageState.setRemoteUrlInputVisible(this.pageState.remoteUrl.trim().length > 0);
     }
@@ -265,39 +280,59 @@ export class RemoteConnectionController {
     }
   }
 
-  async scan(context: Context): Promise<void> {
+  async scan(context: Context): Promise<string> {
     try {
       this.pageState.setStatusText(RemoteI18n.t('status.openScanner'));
       const text = (await this.scanner.scanRemoteUrl(context)).trim();
       if (text.length === 0) {
         this.pageState.setStatusText(RemoteI18n.t('status.scanEmpty'));
-        return;
+        return '';
       }
-      this.handleDetectedUrl(text);
+      return text;
     } catch (err) {
       this.pageState.setRemoteUrlInputVisible(true);
       this.pageState.setStatusText(ConnectionErrorPolicy.errorText(err));
+      return '';
     }
   }
 
-  handleDetectedUrl(remoteUrl: string): boolean {
+  /**
+   * Apply a scanned pair URL and say what should happen next.
+   *
+   * This method must not start a connect and must not close the sheet: the
+   * caller owns both, so a camera callback cannot pair twice and cannot jump
+   * off the progress the sheet is showing.
+   */
+  handleDetectedUrl(
+    remoteUrl: string,
+    hasCloudAccountSession: boolean = false,
+    cloudUsername: string = ''
+  ): DetectedRemoteUrlResult {
     try {
       this.applyRemoteUrl(remoteUrl);
       const descriptor = RemoteDescriptorParser.parse(remoteUrl);
       this.pageState.setStatusText(RemoteI18n.t('status.scannedUrl'));
-      if (this.pairing.shouldPromptForAccount(descriptor)) {
+      const action = ConnectScanDecisionPolicy.decide(
+        descriptor.accountAuth,
+        hasCloudAccountSession,
+        cloudUsername,
+        descriptor.accountUsername,
+        RemoteUiState.desktopIdFromRemoteUrl(remoteUrl)
+      );
+      if (action === DetectedUrlAction.PROMPT_ACCOUNT_PASSWORD) {
         this.pageState.setStatusText(RemoteI18n.t('connect.enterAccountToPair'));
         this.openConnectSheet();
-        return true;
+        return new DetectedRemoteUrlResult(action);
       }
-      this.closeConnectSheet();
-      this.replaceRoute(AppRoute.RemoteHome);
-      void this.connect();
-      return false;
+      return new DetectedRemoteUrlResult(
+        action,
+        action === DetectedUrlAction.USE_CLOUD_DEVICE ?
+          RemoteUiState.desktopIdFromRemoteUrl(remoteUrl) : ''
+      );
     } catch (err) {
       this.pageState.setRemoteUrlInputVisible(true);
       this.pageState.setStatusText(ConnectionErrorPolicy.errorText(err));
-      return true;
+      return new DetectedRemoteUrlResult(DetectedUrlAction.INVALID);
     }
   }
 
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/RemoteCreateFlowController.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/RemoteCreateFlowController.ets
new file mode 100644
index 0000000000..58fc0143d5
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/RemoteCreateFlowController.ets
@@ -0,0 +1,316 @@
+import { RecentWorkspaceEntry, RemoteSession, SessionSummary } from '../../model/RemoteModels';
+import { CloudAccountDevice } from '../../services/CloudAccountClient';
+import { RemoteI18n } from '../../i18n/RemoteI18n';
+import { RemoteLogger } from '../../services/RemoteLogger';
+import { RemoteUiState } from '../../services/RemoteUiState';
+import { AppRoute } from '../navigation/AppRouteContract';
+import { RemoteCreateSessionState } from '../state/RemoteCreateSessionState';
+import { RemotePageState } from '../state/RemotePageState';
+import {
+  RemoteConversationDependencies,
+  requireRemoteRuntime,
+  routeCreatedRemoteSession,
+  routeRemoteSessionInPlace
+} from './ConversationRuntime';
+
+export class RemoteCreateFlowController {
+  private readonly remote: RemotePageState;
+  private readonly remoteCreate: RemoteCreateSessionState;
+  private readonly remoteRuntime?: RemoteConversationDependencies;
+  private remoteCreateWorkspaceLoadVersion: number = 0;
+
+  constructor(
+    remote: RemotePageState,
+    remoteCreate: RemoteCreateSessionState,
+    remoteRuntime: RemoteConversationDependencies | undefined
+  ) {
+    this.remote = remote;
+    this.remoteCreate = remoteCreate;
+    this.remoteRuntime = remoteRuntime;
+  }
+
+  private navigateCreated(sessionId: string): void {
+    routeCreatedRemoteSession(sessionId, requireRemoteRuntime(this.remoteRuntime), (dismissed: boolean) => {
+      this.remote.setConversationDismissed(dismissed);
+    });
+  }
+
+  private navigateInPlace(sessionId: string): void {
+    routeRemoteSessionInPlace(sessionId, requireRemoteRuntime(this.remoteRuntime), (dismissed: boolean) => {
+      this.remote.setConversationDismissed(dismissed);
+    });
+  }
+
+  async createRemoteSession(agentType: string, inPlace: boolean = false): Promise<void> {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    runtime.filePreview.close();
+    await runtime.sessions.createSession(
+      agentType,
+      '',
+      inPlace ? (sessionId: string): void => this.navigateInPlace(sessionId) :
+        (sessionId: string): void => this.navigateCreated(sessionId)
+    );
+  }
+
+  openRemoteCreateSession(): void {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    if (!runtime.connection.ensureAvailable()) {
+      return;
+    }
+    const deviceId = this.remote.controlTargetDeviceId || this.remote.desktopId;
+    const deviceName = this.remote.controlTargetDeviceName || this.remote.desktopName;
+    this.remoteCreate.prepare(deviceId, deviceName, this.remote.selectedModelId);
+    if (deviceId.length > 0) {
+      this.remoteCreate.setDevices([{
+        deviceId,
+        deviceName: deviceName || deviceId,
+        online: true
+      }]);
+    }
+    this.remoteCreate.setWorkspaces(this.remote.recentWorkspaces);
+    runtime.appShell.pushRoute(AppRoute.RemoteCreate);
+    this.loadRemoteCreateChoices();
+    this.loadRemoteCreateModelCatalog();
+  }
+
+  closeRemoteCreateSession(): void {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    this.remoteCreateWorkspaceLoadVersion += 1;
+    runtime.hooks.stopVoiceInput();
+    this.remoteCreate.closeMenu();
+    runtime.appShell.popRoute(AppRoute.RemoteHome);
+  }
+
+  async loadRemoteCreateChoices(): Promise<void> {
+    await Promise.all([
+      this.loadRemoteCreateDevices(),
+      this.loadRemoteCreateWorkspaces()
+    ]);
+  }
+
+  async loadRemoteCreateModelCatalog(): Promise<void> {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    if (this.remote.modelCatalog.models.length > 0) {
+      return;
+    }
+    try {
+      const catalog = await runtime.sessionManager.getModelCatalog();
+      const selectedModelId = RemoteUiState.selectedModelIdForCatalog(catalog, this.remote.selectedModelId);
+      this.remote.setModelCatalog(catalog, selectedModelId);
+      this.remoteCreate.setSelectedModelId(selectedModelId);
+    } catch (_err) {
+      // Model selection remains hidden when the remote does not expose a catalog.
+    }
+  }
+
+  async loadRemoteCreateDevices(): Promise<void> {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    this.remoteCreate.isLoadingDevices = this.remoteCreate.devices.length === 0;
+    try {
+      const phoneDeviceId = runtime.connection.getDeviceId();
+      const accountDevices = await runtime.settings.listCloudAccountDevices();
+      const devices = accountDevices.filter((device: CloudAccountDevice): boolean =>
+        device.online && device.deviceId !== phoneDeviceId
+      );
+      const currentId = this.remoteCreate.selectedDeviceId;
+      if (currentId.length > 0 &&
+        !devices.some((device: CloudAccountDevice): boolean => device.deviceId === currentId)) {
+        devices.unshift({
+          deviceId: currentId,
+          deviceName: this.remoteCreate.selectedDeviceName || currentId,
+          online: true
+        });
+      }
+      this.remoteCreate.setDevices(devices);
+    } catch (_err) {
+      const currentId = this.remoteCreate.selectedDeviceId;
+      if (currentId.length > 0) {
+        this.remoteCreate.setDevices([{
+          deviceId: currentId,
+          deviceName: this.remoteCreate.selectedDeviceName || currentId,
+          online: true
+        }]);
+      } else {
+        this.remoteCreate.setDevices([]);
+      }
+      this.remoteCreate.errorText = RemoteI18n.t('remote.create.deviceLoadFailed');
+    }
+  }
+
+  async loadRemoteCreateWorkspaces(): Promise<void> {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    const loadVersion = ++this.remoteCreateWorkspaceLoadVersion;
+    const deviceId = this.remoteCreate.selectedDeviceId;
+    this.remoteCreate.isLoadingWorkspaces = this.remoteCreate.workspaces.length === 0;
+    try {
+      const workspaces = await runtime.workspace.recentWorkspaces();
+      if (loadVersion !== this.remoteCreateWorkspaceLoadVersion ||
+        deviceId !== this.remoteCreate.selectedDeviceId) {
+        return;
+      }
+      this.remoteCreate.setWorkspaces(workspaces);
+    } catch (_err) {
+      if (loadVersion !== this.remoteCreateWorkspaceLoadVersion ||
+        deviceId !== this.remoteCreate.selectedDeviceId) {
+        return;
+      }
+      this.remoteCreate.setWorkspaces([]);
+      this.remoteCreate.errorText = RemoteI18n.t('remote.create.workspaceLoadFailed');
+    }
+  }
+
+  toggleRemoteCreateDevices(): void {
+    this.remoteCreate.toggleMenu('devices');
+    if (this.remoteCreate.openMenu === 'devices' && this.remoteCreate.devices.length === 0) {
+      this.loadRemoteCreateDevices();
+    }
+  }
+
+  toggleRemoteCreateWorkspaces(): void {
+    this.remoteCreate.toggleMenu('workspaces');
+    if (this.remoteCreate.openMenu === 'workspaces' && this.remoteCreate.workspaces.length === 0) {
+      this.loadRemoteCreateWorkspaces();
+    }
+  }
+
+  async selectRemoteCreateDevice(device: CloudAccountDevice): Promise<void> {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    if (device.deviceId === this.remoteCreate.selectedDeviceId) {
+      this.remoteCreate.closeMenu();
+      return;
+    }
+    const draft = this.remoteCreate.draft;
+    this.remoteCreate.closeMenu();
+    this.remoteCreate.isLoadingWorkspaces = true;
+    try {
+      await runtime.settings.selectCloudAccountDevice(device, false);
+      this.remoteCreate.selectDevice(device);
+      this.remoteCreate.setDraft(draft);
+      await this.loadRemoteCreateWorkspaces();
+    } catch (err) {
+      this.remoteCreate.isLoadingWorkspaces = false;
+      this.remoteCreate.errorText = err instanceof Error ? err.message :
+        RemoteI18n.t('remote.settings.deviceSwitchFailed');
+    }
+  }
+
+  selectRemoteCreateWorkspace(path: string): void {
+    const workspace = this.remoteCreate.workspaces
+      .find((item: RecentWorkspaceEntry): boolean => item.path === path);
+    this.remoteCreate.selectWorkspace(workspace);
+  }
+
+  async submitRemoteCreateSession(): Promise<void> {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    const instruction = this.remoteCreate.draft.trim();
+    if (instruction.length === 0 || this.remoteCreate.isSubmitting || !runtime.connection.ensureAvailable()) {
+      return;
+    }
+    const context = this.remoteCreate.submissionContext();
+    const activeDeviceId = this.remote.controlTargetDeviceId || this.remote.desktopId;
+    if (context.deviceId.length === 0 || context.deviceId !== activeDeviceId) {
+      this.remoteCreate.errorText = RemoteI18n.t('remote.create.deviceMismatch');
+      return;
+    }
+    this.remoteCreate.isSubmitting = true;
+    this.remoteCreate.errorText = '';
+    this.remoteCreate.closeMenu();
+    try {
+      if (context.workspacePath.length > 0) {
+        await runtime.sessions.createSessionInWorkspace(
+          context.workspacePath,
+          this.remote.workspacePath,
+          instruction,
+          context.agentType,
+          undefined,
+          this.remoteCreate.selectedModelId
+        );
+      } else {
+        await this.bindAssistantWorkspace();
+        await runtime.sessions.createSession(
+          context.agentType,
+          instruction,
+          undefined,
+          this.remoteCreate.selectedModelId
+        );
+      }
+      if (runtime.appShell.isRoute(AppRoute.RemoteCreate)) {
+        this.remoteCreate.errorText = this.remote.statusText || RemoteI18n.t('remote.create.submitFailed');
+      }
+    } catch (err) {
+      this.remoteCreate.errorText = err instanceof Error ? err.message :
+        RemoteI18n.t('remote.create.submitFailed');
+    } finally {
+      this.remoteCreate.isSubmitting = false;
+    }
+  }
+
+  /**
+   * The chat option creates a Claw session, and the desktop always binds those
+   * to its assistant workspace. Follow it there first, otherwise the app stays
+   * bound to the code workspace it was on and the new chat is listed, titled
+   * and file-scoped as if it had been created inside that workspace.
+   */
+  private async bindAssistantWorkspace(): Promise<void> {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    if (this.remote.workspaceKind === 'assistant') {
+      return;
+    }
+    try {
+      const assistants = await runtime.workspace.assistants();
+      if (assistants.length === 0) {
+        return;
+      }
+      await runtime.hooks.selectAssistantWorkspace(assistants[0].path);
+    } catch (err) {
+      RemoteLogger.warn(`assistant workspace bind failed: ${String(err)}`);
+    }
+  }
+
+  async createRemoteSessionInWorkspace(
+    path: string,
+    agentType: string = 'code',
+    inPlace: boolean = false
+  ): Promise<void> {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    runtime.filePreview.close();
+    await runtime.sessions.createSessionInWorkspace(
+      path,
+      this.remote.workspacePath,
+      '',
+      agentType,
+      inPlace ? (sessionId: string): void => this.navigateInPlace(sessionId) :
+        (sessionId: string): void => this.navigateCreated(sessionId)
+    );
+  }
+
+  async openRemoteSession(item: RemoteSession, inPlace: boolean = false): Promise<void> {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    runtime.filePreview.close();
+    await runtime.sessions.openSession(
+      item,
+      this.remote.workspacePath,
+      inPlace ? (sessionId: string): void => this.navigateInPlace(sessionId) :
+        (sessionId: string): void => this.navigateCreated(sessionId)
+    );
+  }
+
+  applyRemoteActiveSession(session: SessionSummary): void {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    const current = this.remote.activeSession;
+    if (runtime.hooks.isFilePreviewVisible() &&
+      (current.sessionId !== session.sessionId || current.workspacePath !== session.workspacePath)) {
+      runtime.filePreview.close();
+    }
+    this.remote.setActiveSession(session);
+  }
+
+  async deleteRemoteSession(item: RemoteSession): Promise<void> {
+    await requireRemoteRuntime(this.remoteRuntime).sessions.deleteSession(item, this.remote.workspacePath);
+  }
+
+  routeCreatedRemoteSession(sessionId: string): void {
+    this.navigateCreated(sessionId);
+  }
+}
+
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/RemoteSessionViewModel.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/RemoteSessionViewModel.ets
index 42ab00f630..947ee6a13a 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/RemoteSessionViewModel.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/RemoteSessionViewModel.ets
@@ -4,6 +4,9 @@ import { RemoteChatCommandController } from '../../services/RemoteChatCommandCon
 import { RemoteModelController } from '../../services/RemoteModelController';
 import { RemoteSessionController } from '../../services/RemoteSessionController';
 import { RemoteFileDownloadController } from '../../services/RemoteFileDownloadController';
+import { DeferredLoadingGate } from '../../services/DeferredLoadingGate';
+import { RemoteLogger } from '../../services/RemoteLogger';
+import { MainThreadStallProbe } from '../../services/MainThreadStallProbe';
 import { RemotePageState } from '../state/RemotePageState';
 
 export interface RemoteSessionViewModelHooks {
@@ -18,7 +21,6 @@ export interface RemoteSessionViewModelHooks {
   readonly onResetTimeline: (sessionId: string) => void;
   readonly onClearRemoteFiles: () => void;
   readonly onKnownStateReset: () => void;
-  readonly onLoadModelCatalog: (sessionId: string) => Promise<void>;
   readonly onLoadActiveMessages: () => Promise<void>;
   readonly onRefreshSessions: () => Promise<void>;
   readonly onSelectWorkspace: (path: string) => Promise<void>;
@@ -32,6 +34,14 @@ export class RemoteSessionViewModel {
   private readonly models: RemoteModelController;
   private readonly files: RemoteFileDownloadController;
   private readonly hooks: RemoteSessionViewModelHooks;
+  // Long enough that a cached transcript never flashes a skeleton on its way in,
+  // short enough that a transcript coming over the relay still says so.
+  private readonly openLoadingGate: DeferredLoadingGate =
+    new DeferredLoadingGate(140, (visible: boolean): void => this.pageState.setConversationLoading(visible));
+  // How many opens this view model has started and not yet settled. Opening a
+  // session raises the busy flag, so without this the flag an open sets would
+  // read, to the next tap, as a run in progress.
+  private openInFlight: number = 0;
 
   constructor(
     pageState: RemotePageState,
@@ -49,6 +59,13 @@ export class RemoteSessionViewModel {
     this.hooks = hooks;
   }
 
+  private static shortId(value: string): string {
+    if (value.length <= 10) {
+      return value;
+    }
+    return `${value.slice(0, 6)}...${value.slice(-4)}`;
+  }
+
   async refreshSessions(): Promise<void> {
     await this.sessions.refresh(
       this.pageState.sessionQuery,
@@ -81,7 +98,29 @@ export class RemoteSessionViewModel {
     onRouteChat: (sessionId: string) => void = this.hooks.onRouteChat,
     modelId: string = ''
   ): Promise<void> {
-    await this.sessions.create(
+    if (this.hooks.isBusy() || !this.hooks.remoteAvailable()) {
+      return;
+    }
+    const previousSession: SessionSummary = this.copySession(this.pageState.activeSession);
+    this.beginSessionCreation(onRouteChat);
+    try {
+      const created = await this.performCreateSession(agentType, instruction, onRouteChat, modelId);
+      if (!created) {
+        this.restoreAfterFailedCreation(previousSession, onRouteChat);
+      }
+    } finally {
+      this.pageState.setConversationLoading(false);
+      this.pageState.setPendingSessionId('');
+    }
+  }
+
+  private async performCreateSession(
+    agentType: string,
+    instruction: string,
+    onRouteChat: (sessionId: string) => void,
+    modelId: string
+  ): Promise<SessionSummary | undefined> {
+    return await this.sessions.create(
       agentType,
       this.hooks.isBusy(),
       this.hooks.remoteAvailable(),
@@ -91,10 +130,12 @@ export class RemoteSessionViewModel {
         this.hooks.onKnownStateReset();
         this.hooks.onResetTimeline(session.sessionId);
         onRouteChat(session.sessionId);
-        await this.hooks.onLoadModelCatalog(session.sessionId);
-        await this.refreshSessions();
+        // Same ordering as openSession: whatever the new session already has to
+        // show goes up first. The model picker needs no request of its own —
+        // the poll started here carries the catalog back with it.
         await this.hooks.onLoadActiveMessages();
         this.hooks.onStartPolling();
+        await this.refreshSessions();
       },
       instruction,
       modelId
@@ -109,14 +150,69 @@ export class RemoteSessionViewModel {
     onRouteChat: (sessionId: string) => void = this.hooks.onRouteChat,
     modelId: string = ''
   ): Promise<void> {
-    if (path.length > 0 && path !== currentPath) {
-      await this.hooks.onSelectWorkspace(path);
-      await this.createSession(agentType, instruction, onRouteChat, modelId);
+    if (this.hooks.isBusy() || !this.hooks.remoteAvailable()) {
       return;
     }
-    if (path.length === 0 || path === currentPath) {
-      await this.createSession(agentType, instruction, onRouteChat, modelId);
+    const previousSession: SessionSummary = this.copySession(this.pageState.activeSession);
+    const previousWorkspacePath = currentPath;
+    this.beginSessionCreation(onRouteChat);
+    let created: SessionSummary | undefined;
+    try {
+      if (path.length > 0 && path !== currentPath) {
+        await this.hooks.onSelectWorkspace(path);
+        // Workspace selection clears page discovery state. Creation still owns
+        // the detail pane until the create command resolves.
+        this.pageState.setConversationLoading(true);
+      }
+      if (path.length === 0 || path === currentPath) {
+        created = await this.performCreateSession(agentType, instruction, onRouteChat, modelId);
+      } else if (this.pageState.workspacePath === path) {
+        created = await this.performCreateSession(agentType, instruction, onRouteChat, modelId);
+      }
+      if (!created) {
+        if (this.pageState.workspacePath === previousWorkspacePath) {
+          this.restoreAfterFailedCreation(previousSession, onRouteChat);
+        } else {
+          this.pageState.clearActiveSession();
+          this.hooks.onResetTimeline('');
+          this.hooks.onKnownStateReset();
+          this.hooks.onRouteHome();
+        }
+      }
+    } finally {
+      this.pageState.setConversationLoading(false);
+      this.pageState.setPendingSessionId('');
+    }
+  }
+
+  private beginSessionCreation(onRouteChat: (sessionId: string) => void): void {
+    this.hooks.onStopPolling();
+    this.pageState.setPendingSessionId('');
+    this.pageState.setConversationLoading(true);
+    onRouteChat('');
+  }
+
+  private restoreAfterFailedCreation(
+    previousSession: SessionSummary,
+    onRouteChat: (sessionId: string) => void
+  ): void {
+    if (previousSession.sessionId.length === 0) {
+      this.hooks.onRouteHome();
+      return;
     }
+    this.pageState.setActiveSession(previousSession);
+    onRouteChat(previousSession.sessionId);
+    this.hooks.onStartPolling();
+  }
+
+  private copySession(session: SessionSummary): SessionSummary {
+    return {
+      sessionId: session.sessionId,
+      title: session.title,
+      workspacePath: session.workspacePath,
+      agentType: session.agentType,
+      initialTurnId: session.initialTurnId
+    };
   }
 
   async openSession(
@@ -124,14 +220,36 @@ export class RemoteSessionViewModel {
     currentWorkspacePath: string,
     onRouteChat: (sessionId: string) => void = this.hooks.onRouteChat
   ): Promise<void> {
-    const isBusy = this.hooks.isBusy();
+    // A tap that arrives while another open is still in flight is a correction,
+    // not a mistake: the user has picked a different session and expects that
+    // one. It used to be swallowed, because `RemoteSessionController.open`
+    // raises the busy flag for the whole open and this guard read that flag as
+    // a run in progress — so for the second or so an uncached open takes, every
+    // row in the list was dead and nothing on screen said why. Opens supersede
+    // each other instead; only a run this view model did not start blocks.
+    const isBusy = this.hooks.isBusy() && this.openInFlight === 0;
     const remoteAvailable = this.hooks.remoteAvailable();
     if (isBusy || item.id.length === 0 || !remoteAvailable) {
+      // Dropped taps are invisible from the outside — the row simply does
+      // nothing — so say which guard swallowed it.
+      RemoteLogger.info(`session open ignored session=${RemoteSessionViewModel.shortId(item.id)} busy=${isBusy ? '1' : '0'} available=${remoteAvailable ? '1' : '0'}`);
       return;
     }
+    // Bracketing the open: every stage between this line and the transcript
+    // reaching the screen logs, so the gap that the user feels can be pinned on
+    // one of them rather than inferred from the two ends.
+    RemoteLogger.info(`session open tap session=${RemoteSessionViewModel.shortId(item.id)}`);
+    MainThreadStallProbe.watch('session-open', 6000);
     this.pageState.setPendingSessionId(item.id);
-    this.pageState.setConversationLoading(true);
+    // No skeleton yet. The tapped row highlights from the pending id alone, and
+    // everything the detail pane needs to show the new session empty — title,
+    // workspace, a cleared timeline — is set synchronously below. If the
+    // transcript is cached it lands before the gate opens and the pane goes
+    // straight from one conversation to the next.
+    const loadingToken = this.openLoadingGate.arm();
     onRouteChat(item.id);
+    RemoteLogger.info(`session open routed session=${RemoteSessionViewModel.shortId(item.id)}`);
+    this.openInFlight += 1;
     try {
       await this.sessions.open(
         item,
@@ -145,7 +263,16 @@ export class RemoteSessionViewModel {
           this.pageState.setHasMoreMessages(false);
           this.files.clear();
           this.pageState.clearComposer();
-          await this.hooks.onLoadModelCatalog(item.id);
+          // Transcript first: it is the thing the user opened the session to
+          // see, and a cached one needs no round trip at all.
+          //
+          // Nothing fetches the model catalog here. The reset above puts the
+          // known catalog version back to zero, so the first poll asks for the
+          // catalog as part of the same request and the desktop sends it. A
+          // separate `get_model_catalog` would only queue ahead of the
+          // transcript — the desktop answers device RPCs one at a time, and
+          // measured against this device it pushed the transcript from ~2.4s
+          // out to ~5.5s.
           await this.hooks.onLoadActiveMessages();
           if (this.pageState.activeSession.sessionId === session.sessionId) {
             this.hooks.onStartPolling();
@@ -153,8 +280,14 @@ export class RemoteSessionViewModel {
         }
       );
     } finally {
-      this.pageState.setConversationLoading(false);
-      this.pageState.setPendingSessionId('');
+      this.openInFlight -= 1;
+      this.openLoadingGate.release(loadingToken);
+      // Only the tap that still owns the gate owns the highlight: a second tap
+      // during the first open has already moved both.
+      if (loadingToken === this.openLoadingGate.currentToken()) {
+        this.pageState.setPendingSessionId('');
+      }
+      RemoteLogger.info(`session open settled session=${RemoteSessionViewModel.shortId(item.id)}`);
     }
   }
 
@@ -168,6 +301,7 @@ export class RemoteSessionViewModel {
       this.pageState.sessionFilter,
       async (): Promise<void> => {
         this.hooks.onStopPolling();
+        await this.chat.forgetMessages(item.id);
         this.hooks.onResetTimeline('');
         this.pageState.setHasMoreMessages(false);
         this.pageState.clearComposer();
@@ -199,10 +333,6 @@ export class RemoteSessionViewModel {
     );
   }
 
-  async loadModelCatalog(sessionId: string, isChatRoute: (sessionId: string) => boolean): Promise<void> {
-    await this.models.loadCatalog(sessionId, this.hooks.remoteAvailable(), isChatRoute);
-  }
-
   async selectModel(modelId: string): Promise<void> {
     await this.models.selectModel(
       modelId,
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/RemoteTranscriptController.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/RemoteTranscriptController.ets
new file mode 100644
index 0000000000..f5082ddb43
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/RemoteTranscriptController.ets
@@ -0,0 +1,371 @@
+import {
+  RemoteImageContext,
+  RemoteQuestionAnswerPayload
+} from '../../model/RemoteModels';
+import { ChatTimelineItem } from '../../services/ChatTimelineProjector';
+import { ChatTimelineState, ChatTimelineStore } from '../../services/ChatTimelineStore';
+import { ConnectionErrorPolicy } from '../../services/ConnectionErrorPolicy';
+import { RemoteChatPollingCursor, RemoteChatPollingSnapshot } from '../../services/RemoteChatPollingLifecycleController';
+import { RemoteI18n } from '../../i18n/RemoteI18n';
+import { RemoteLogger } from '../../services/RemoteLogger';
+import { RemoteUiState } from '../../services/RemoteUiState';
+import { RemotePageState } from '../state/RemotePageState';
+import {
+  RemoteConversationDependencies,
+  requireRemoteRuntime,
+  shortSessionId
+} from './ConversationRuntime';
+
+export class RemoteTranscriptController {
+  private readonly remote: RemotePageState;
+  private readonly remoteRuntime?: RemoteConversationDependencies;
+  private readonly notify: (message: string) => void;
+  private knownPollVersionValue: number = 0;
+  private knownModelCatalogVersion: number = 0;
+  private knownRemoteMessageCount: number = 0;
+  private isSyncingAfterTurn: boolean = false;
+  private isRebuildingRemoteTranscript: boolean = false;
+
+  constructor(
+    remote: RemotePageState,
+    remoteRuntime: RemoteConversationDependencies | undefined,
+    notify: (message: string) => void
+  ) {
+    this.remote = remote;
+    this.remoteRuntime = remoteRuntime;
+    this.notify = notify;
+  }
+
+  knownPollVersion(): number {
+    return this.knownPollVersionValue;
+  }
+
+  resetKnownRemoteState(): void {
+    this.knownPollVersionValue = 0;
+    this.knownModelCatalogVersion = 0;
+    this.knownRemoteMessageCount = 0;
+  }
+
+  updateKnownMessageCount(pollVersion: number, knownMessageCount: number): void {
+    this.knownRemoteMessageCount = knownMessageCount;
+    this.updateChatPollingCursor(pollVersion, knownMessageCount);
+  }
+
+  updateKnownModelCatalogVersion(version: number): void {
+    this.knownModelCatalogVersion = version;
+    requireRemoteRuntime(this.remoteRuntime).polling.updateKnownModelCatalogVersion(version);
+  }
+
+  async loadRemoteMessages(): Promise<void> {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    await runtime.chat.loadMessages(
+      this.remote.activeSession.sessionId || '',
+      runtime.hooks.isConversationContext
+    );
+  }
+
+  async selectRemoteModel(modelId: string): Promise<void> {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    await runtime.models.selectModel(
+      modelId,
+      this.remote.activeSession.sessionId || '',
+      this.remote.isBusy,
+      runtime.connection.ensureAvailable()
+    );
+  }
+
+  async loadOlderRemoteMessages(): Promise<void> {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    await runtime.chat.loadOlderMessages(
+      this.remote.activeSession.sessionId || '',
+      this.knownPollVersionValue,
+      this.remote.hasMoreMessages,
+      this.remote.isBusy
+    );
+  }
+
+  async sendRemoteMessage(): Promise<void> {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    if (this.remote.isVoiceListening) {
+      await runtime.hooks.stopVoiceInput();
+    }
+    const rawText = this.remote.chatInput.trim();
+    const images = this.remote.selectedImages.slice();
+    const text = rawText.length > 0 ? rawText :
+      (images.length > 0 ? RemoteI18n.t('chat.analyzeImageDefault') : '');
+    const sessionId = this.remote.activeSession.sessionId || '';
+    if ((!text && images.length === 0) || !sessionId || this.remote.isBusy ||
+      !runtime.connection.ensureAvailable()) {
+      return;
+    }
+    // Sending into a turn that is still running is allowed, but the desktop
+    // queues it rather than interrupting, so say so once — otherwise the
+    // message just sits in the transcript with nothing appearing to happen.
+    const queuedBehindRunningTurn = this.hasRunningRemoteTurn();
+    this.remote.clearComposer();
+    const localMessage = RemoteUiState.localUserMessage(text, images);
+    runtime.timeline.appendOptimisticMessage(localMessage);
+    const pendingActiveId = runtime.timeline.setPendingActiveTurn(localMessage.id);
+    this.syncRemoteTimeline();
+    RemoteLogger.info(`chat send queued session=${shortSessionId(sessionId)} pending=${pendingActiveId} behindRunningTurn=${queuedBehindRunningTurn ? '1' : '0'}`);
+    if (queuedBehindRunningTurn) {
+      this.notify(RemoteI18n.t('chat.queuedAfterRunningTurn'));
+    }
+    this.startRemotePolling();
+    runtime.polling.nudge();
+    const imageContexts: RemoteImageContext[] = images.length > 0 ?
+      runtime.imagePicker.toRemoteContexts(images) : [];
+    await runtime.chat.sendPreparedMessage(
+      sessionId,
+      text,
+      this.remote.activeSession.agentType,
+      rawText,
+      images,
+      imageContexts,
+      localMessage.id,
+      pendingActiveId,
+      this.remote.isBusy,
+      true
+    );
+  }
+
+  async stopRemoteTask(): Promise<void> {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    const sessionId = this.remote.activeSession.sessionId || '';
+    if (!sessionId) {
+      return;
+    }
+    await runtime.chat.stopTask(
+      sessionId,
+      this.remote.activeTurnMessage.id,
+      this.remoteActiveTurnId(),
+      runtime.connection.ensureAvailable()
+    );
+  }
+
+  async renameRemoteSession(title: string): Promise<void> {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    const nextTitle = title.trim();
+    if (!this.remote.activeSession.sessionId || nextTitle.length === 0 ||
+      nextTitle === this.remote.activeSession.title || this.remote.isBusy) {
+      return;
+    }
+    await runtime.chat.renameActiveSession(
+      this.remote.activeSession,
+      nextTitle,
+      this.remote.isBusy,
+      runtime.connection.ensureAvailable()
+    );
+  }
+
+  async copyRemoteMessage(text: string): Promise<void> {
+    if (text.trim().length === 0) {
+      return;
+    }
+    try {
+      await requireRemoteRuntime(this.remoteRuntime).clipboard.writeText(text);
+      this.remote.setStatusText(RemoteI18n.t('status.messageCopied'));
+    } catch (err) {
+      this.remote.setStatusText(ConnectionErrorPolicy.errorText(err));
+    }
+  }
+
+  async downloadRemoteFile(path: string): Promise<void> {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    await runtime.files.download(
+      path,
+      this.remote.activeSession.sessionId || '',
+      this.remote.isBusy,
+      runtime.connection.ensureAvailable()
+    );
+  }
+
+  retryRemoteMessage(text: string): void {
+    if (this.remote.isBusy || !requireRemoteRuntime(this.remoteRuntime).connection.ensureAvailable()) {
+      return;
+    }
+    this.remote.setChatInput(text);
+    this.sendRemoteMessage();
+  }
+
+  async approveRemoteTool(toolId: string, updatedInput?: Object): Promise<void> {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    await runtime.tools.approve(
+      toolId, this.remote.activeSession.sessionId || '', runtime.connection.ensureAvailable(), updatedInput
+    );
+  }
+
+  async rejectRemoteTool(toolId: string): Promise<void> {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    await runtime.tools.reject(
+      toolId, this.remote.activeSession.sessionId || '', runtime.connection.ensureAvailable()
+    );
+  }
+
+  async cancelRemoteTool(toolId: string): Promise<void> {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    await runtime.tools.cancel(
+      toolId, this.remote.activeSession.sessionId || '', runtime.connection.ensureAvailable()
+    );
+  }
+
+  async answerRemoteQuestion(toolId: string, answers: RemoteQuestionAnswerPayload): Promise<void> {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    await runtime.tools.answer(
+      toolId, this.remote.activeSession.sessionId || '', runtime.connection.ensureAvailable(), answers
+    );
+  }
+
+  resetRemoteTimeline(sessionId: string): void {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    runtime.timeline.reset(sessionId);
+    this.knownPollVersionValue = 0;
+    this.syncRemoteTimeline();
+  }
+
+  syncRemoteTimeline(): void {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    const state: ChatTimelineState = runtime.timeline.snapshotState();
+    this.remote.setTimelineProjection(
+      state.persistedMessages,
+      state.optimisticMessages,
+      state.activeTurn || RemoteUiState.emptyActiveTurn(),
+      this.remote.hasMoreMessages,
+      runtime.timeline.viewState(this.remote.hasMoreMessages)
+    );
+    this.remote.setModelCatalog(state.modelCatalog, state.selectedModelId);
+  }
+
+  startRemotePolling(): void {
+    requireRemoteRuntime(this.remoteRuntime).polling.startActiveSession({
+      sessionId: this.remote.activeSession.sessionId || '',
+      cursor: this.currentChatPollingCursor(),
+      activeTurn: this.remote.activeTurnMessage
+    });
+  }
+
+  applyRemoteSnapshot(snapshot: RemoteChatPollingSnapshot): void {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    if (!runtime.hooks.isConversationContext(snapshot.sessionId)) {
+      return;
+    }
+    if (snapshot.historyRewritten) {
+      this.rebuildRemoteTranscript(snapshot.sessionId);
+      return;
+    }
+    runtime.timeline.applySnapshot(snapshot);
+    this.syncRemoteTimeline();
+    if (snapshot.newMessages.length > 0) {
+      this.cacheRemoteTranscript(snapshot.sessionId);
+    }
+    this.knownPollVersionValue = snapshot.cursor.pollVersion;
+    this.knownModelCatalogVersion = snapshot.cursor.knownModelCatalogVersion;
+    this.knownRemoteMessageCount = snapshot.cursor.knownMessageCount;
+    if (snapshot.title.length > 0) {
+      this.remote.setActiveSession({
+        sessionId: this.remote.activeSession.sessionId,
+        title: snapshot.title,
+        workspacePath: this.remote.activeSession.workspacePath,
+        agentType: this.remote.activeSession.agentType
+      });
+    }
+    if (snapshot.modelCatalog) {
+      runtime.models.applyCatalog(snapshot.modelCatalog);
+    }
+    this.remote.setStatusText(this.hasRunningRemoteTurn()
+      ? RemoteI18n.t('status.desktopProcessing')
+      : RemoteI18n.t('status.messagesSynced'));
+    if (snapshot.shouldSyncAfterTurnEnded) {
+      this.syncAfterRemoteTurnEnded();
+    }
+  }
+
+  /**
+   * Writes the transcript now on screen back to disk.
+   *
+   * Fire-and-forget on purpose: the snapshot is already rendered, and a cache
+   * that cannot be written only costs the next open a fetch it used to pay for
+   * anyway.
+   */
+  private cacheRemoteTranscript(sessionId: string): void {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    const state: ChatTimelineState = runtime.timeline.snapshotState();
+    runtime.chatCache.sync(sessionId, state.persistedMessages);
+  }
+
+  /**
+   * Refetches a transcript the desktop no longer agrees with.
+   *
+   * Tails are handed out by index, so once the desktop reports fewer messages
+   * than this session had counted there is no offset left that means the same
+   * thing on both ends. Everything stored for the session goes, including the
+   * poll cursor, which `reloadMessages` resets by way of `onMessageCountKnown`.
+   */
+  private rebuildRemoteTranscript(sessionId: string): void {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    if (this.isRebuildingRemoteTranscript) {
+      return;
+    }
+    this.isRebuildingRemoteTranscript = true;
+    RemoteLogger.info(`remote transcript rewritten upstream session=${shortSessionId(sessionId)}`);
+    runtime.chatCache.forget(sessionId)
+      .then((): Promise<void> => runtime.chat.reloadMessages(sessionId, runtime.hooks.isConversationContext))
+      .then((): void => {
+        this.isRebuildingRemoteTranscript = false;
+      })
+      .catch((): void => {
+        this.isRebuildingRemoteTranscript = false;
+      });
+  }
+
+  hasRunningRemoteTurn(): boolean {
+    return this.remote.activeTurnMessage.id.length > 0 &&
+      (this.remote.activeTurnMessage.status || '').toLowerCase() === 'active';
+  }
+
+  remoteActiveTurnId(): string {
+    return ChatTimelineStore.cancelableTurnId(this.remote.activeTurnMessage);
+  }
+
+  projectedRemoteTimelineItems(): ChatTimelineItem[] {
+    return requireRemoteRuntime(this.remoteRuntime).timeline.viewState(this.remote.hasMoreMessages);
+  }
+
+  private currentChatPollingCursor(): RemoteChatPollingCursor {
+    return {
+      pollVersion: this.knownPollVersionValue,
+      knownMessageCount: this.knownRemoteMessageCount,
+      knownModelCatalogVersion: this.knownModelCatalogVersion
+    };
+  }
+
+  private updateChatPollingCursor(pollVersion: number, knownMessageCount: number): void {
+    this.knownPollVersionValue = pollVersion;
+    this.knownRemoteMessageCount = knownMessageCount;
+    requireRemoteRuntime(this.remoteRuntime).polling.updateCursor({
+      pollVersion,
+      knownMessageCount,
+      knownModelCatalogVersion: this.knownModelCatalogVersion
+    });
+  }
+
+  private async syncAfterRemoteTurnEnded(): Promise<void> {
+    if (this.isSyncingAfterTurn) {
+      return;
+    }
+    this.isSyncingAfterTurn = true;
+    try {
+      // Deliberately not the cached path: this exists to pick up whatever the
+      // desktop settled on after the turn finished, which is exactly what the
+      // cache does not know yet.
+      const runtime = requireRemoteRuntime(this.remoteRuntime);
+      await runtime.chat.reloadMessages(
+        this.remote.activeSession.sessionId || '',
+        runtime.hooks.isConversationContext
+      );
+    } finally {
+      this.isSyncingAfterTurn = false;
+    }
+  }
+
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/SettingsController.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/SettingsController.ets
index 02e90e9f0b..6f04721a46 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/SettingsController.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/SettingsController.ets
@@ -1,6 +1,6 @@
 import { RemoteI18n } from '../../i18n/RemoteI18n';
 import { CloudAccountDevice, CloudAccountRequestError, CloudAccountSession, CloudAccountClient } from '../../services/CloudAccountClient';
-import { CloudAccountSessionStore } from '../../services/CloudAccountSessionStore';
+import { CloudAccountSessionStore, PersistedCloudAccountSession } from '../../services/CloudAccountSessionStore';
 import { ConnectionErrorPolicy } from '../../services/ConnectionErrorPolicy';
 import { Encoding } from '../../services/Encoding';
 import {
@@ -14,6 +14,7 @@ import { GeneralChatCloudConfigPolicy } from '../../services/general-chat/Genera
 import { GeneralChatServiceStatus } from '../../services/general-chat/GeneralChatServiceState';
 import { RemoteLogger } from '../../services/RemoteLogger';
 import { RemoteSessionManager } from '../../services/RemoteSessionManager';
+import { WatchProvisionOutcome } from '../../services/WatchProvisionController';
 import { RemotePermissionMode } from '../../model/RemoteModels';
 import { GeneralChatPageState } from '../state/GeneralChatPageState';
 import { RemotePageState } from '../state/RemotePageState';
@@ -33,6 +34,8 @@ export interface CloudAccountSettingsHooks {
   readonly startHeartbeat: () => void;
   readonly resetTimeline: () => void;
   readonly resetKnownRemoteState: () => void;
+  /** Cached transcripts and session lists belong to the account that was signed in. */
+  readonly clearCachedRemoteData: () => Promise<void>;
   readonly closeSettings: () => void;
   readonly closeConnectSheet: () => void;
   readonly navigateRemoteHome: () => void;
@@ -157,6 +160,63 @@ export class SettingsController {
     return this.cloudSession !== undefined;
   }
 
+  /**
+   * Whether this phone might be able to add a device to the account itself.
+   *
+   * Deliberately "might": the session here is either a real password login or
+   * one delegated by a room pairing, and only the first carries a token the
+   * relay will mint from. The two are indistinguishable locally, so the answer
+   * is optimistic and `provisionWatchCredential` reports the refusal.
+   */
+  canMintWatchCredential(): boolean {
+    return this.cloudSession !== undefined && this.cloudRelayUrl.length > 0;
+  }
+
+  /**
+   * Mints a watch's own account credential straight from this phone.
+   *
+   * Returns `undefined` when this phone is not entitled to mint — no session,
+   * or a delegated token the relay refuses — which is the caller's cue to fall
+   * back to asking the paired desktop. Any other failure throws, because a
+   * network blip is not the same answer as "you may not".
+   *
+   * The account master key never leaves for the relay: it is read from the
+   * session this phone already holds and handed back for sealing to the
+   * watch's ephemeral key.
+   */
+  async provisionWatchCredential(
+    deviceId: string,
+    deviceName: string,
+    requestId: string
+  ): Promise<WatchProvisionOutcome | undefined> {
+    const session = this.cloudSession;
+    if (!session || this.cloudRelayUrl.length === 0) {
+      return undefined;
+    }
+    const cloud = this.requireCloud();
+    try {
+      const provisioned = await cloud.client.provisionDevice(
+        this.cloudRelayUrl, session, deviceId, deviceName, requestId);
+      RemoteLogger.info(`watch credential minted from the phone account device=${provisioned.deviceId}`);
+      return {
+        ok: true,
+        relayUrl: this.cloudRelayUrl,
+        token: provisioned.token,
+        userId: provisioned.userId,
+        masterKeyBase64: Encoding.bytesToBase64(session.masterKey),
+        deviceId: provisioned.deviceId,
+        failure: '',
+        desktopReported: false
+      };
+    } catch (err) {
+      if (err instanceof CloudAccountRequestError && (err.statusCode === 401 || err.statusCode === 403)) {
+        RemoteLogger.info('phone account may not mint a device credential; deferring to the desktop');
+        return undefined;
+      }
+      throw err instanceof Error ? err : new Error('Watch credential provisioning failed.');
+    }
+  }
+
   async persistDelegatedAccountSession(): Promise<void> {
     if (this.cloudSession) {
       return;
@@ -192,27 +252,6 @@ export class SettingsController {
     return session.userId;
   }
 
-  async syncCloudAccount(): Promise<string> {
-    const cloud = this.requireCloud();
-    const session = this.cloudSession;
-    if (!session || this.cloudRelayUrl.length === 0) {
-      throw new Error(RemoteI18n.t('remote.settings.accountNotSignedIn'));
-    }
-    let bundles: Object[];
-    try {
-      bundles = await cloud.client.fetchSessions(this.cloudRelayUrl, session, 0);
-    } catch (err) {
-      if (err instanceof CloudAccountRequestError && err.statusCode === 401) {
-        await this.expireCloudAccountSession();
-        throw new Error(RemoteI18n.t('remote.settings.accountExpired'));
-      }
-      throw new Error(err instanceof Error ? err.message : RemoteI18n.t('remote.settings.accountSyncFailed'));
-    }
-    await this.loadGeneralChatAccountModels(session, this.cloudRelayUrl);
-    RemoteLogger.info(`cloud account backup sync completed count=${bundles.length}`);
-    return String(bundles.length);
-  }
-
   applyCloudAccountSession(session: CloudAccountSession, relayUrl: string, username: string): void {
     const remoteState = this.requireCloud().remoteState;
     this.cloudSession = session;
@@ -232,6 +271,7 @@ export class SettingsController {
     this.store.replaceAccountModels([]);
     await this.refreshModelCatalog();
     await cloud.sessionStore.clear();
+    await cloud.hooks.clearCachedRemoteData();
     cloud.remoteState.setAccountUserId('');
     cloud.remoteState.setAccountUsername('');
     cloud.remoteState.clearControlTarget();
@@ -245,7 +285,7 @@ export class SettingsController {
       return [];
     }
     try {
-      return await cloud.client.listDevices(this.cloudRelayUrl, session);
+      return await cloud.client.listDevices(this.cloudRelayUrl, session, cloud.hooks.deviceId());
     } catch (err) {
       if (err instanceof CloudAccountRequestError && err.statusCode === 401) {
         await this.expireCloudAccountSession();
@@ -275,7 +315,19 @@ export class SettingsController {
     return cloud.sessionManager.setPermissionMode(mode);
   }
 
-  async restoreCloudTarget(targetDeviceId: string, targetDeviceName: string): Promise<void> {
+  /**
+   * Puts the account back on the desktop it was last driving.
+   *
+   * `navigateHome` is off for the cold-start restore: the launch route is the
+   * user's business, and reconnecting in the background should not move them
+   * off the screen the app opened on. A manual reconnect is already on the
+   * Remote surface, so there it lands where the user expects.
+   */
+  async restoreCloudTarget(
+    targetDeviceId: string,
+    targetDeviceName: string,
+    navigateHome: boolean = true
+  ): Promise<void> {
     const targetId = targetDeviceId.trim();
     if (targetId.length === 0) {
       return;
@@ -297,9 +349,27 @@ export class SettingsController {
         deviceName: target.deviceName || targetDeviceName || target.deviceId,
         online: target.online,
         lastSeenAt: target.lastSeenAt
-      });
+      }, navigateHome);
     } catch (err) {
       RemoteLogger.warn(`cloud target restore failed: ${err instanceof Error ? err.message : 'unknown error'}`);
+      if (!this.cloudSession) {
+        // The account itself went away — an expired token clears it — so there
+        // is no desktop left to aim at, and the surfaces already say as much.
+        return;
+      }
+      // A failed connect attempt drops the target so a half-open link cannot be
+      // mistaken for a live one, but a restore that failed is exactly the case
+      // where the target still matters: without it the reconnect button has
+      // nothing to retry and falls through to the paired-desktop path.
+      remoteState.setControlTarget('account_device', targetId, targetDeviceName.trim() || targetId);
+      // The caller announces `reconnecting` before this runs, and every surface
+      // hides its reconnect entry point while a connect is in flight. Failing
+      // silently would leave that announcement standing forever, with no way
+      // left to retry it. Only report when nothing downstream already did.
+      if (remoteState.connectionState !== 'failed') {
+        remoteState.setConnectionState('failed');
+        remoteState.setStatusText(ConnectionErrorPolicy.errorText(err));
+      }
     }
   }
 
@@ -370,7 +440,9 @@ export class SettingsController {
         targetDeviceName: device.deviceName
       });
       cloud.hooks.startHeartbeat();
-      await cloud.hooks.loadRecentWorkspaces();
+      // Same reasoning as the paired-desktop path in RemoteConnectionController:
+      // the cross-workspace scan runs behind a list that is already usable.
+      void cloud.hooks.loadRecentWorkspaces();
     } catch (err) {
       if (err instanceof CloudAccountRequestError && err.statusCode === 401) {
         await this.expireCloudAccountSession();
@@ -438,6 +510,7 @@ export class SettingsController {
         masterKey: Encoding.base64ToBytes(persisted.masterKey)
       };
       this.applyCloudAccountSession(session, persisted.relayUrl, persisted.username || session.userId);
+      this.restorePersistedControlTarget(persisted);
       await this.loadGeneralChatAccountModels(session, persisted.relayUrl);
     } catch (err) {
       RemoteLogger.warn(`cloud account restore failed: ${err instanceof Error ? err.message : 'unknown error'}`);
@@ -445,6 +518,25 @@ export class SettingsController {
     }
   }
 
+  /**
+   * Names the desktop this account was last driving, without connecting to it.
+   *
+   * The account path has no pairing snapshot on disk the way the scanned-room
+   * path does — the target rides along in the encrypted account record — so
+   * without this a cold start could not even say which desktop it used to be
+   * on, and the restore that follows would have nothing to aim at.
+   */
+  private restorePersistedControlTarget(persisted: PersistedCloudAccountSession): void {
+    const targetId = (persisted.targetDeviceId || '').trim();
+    if (targetId.length === 0) {
+      return;
+    }
+    const targetName = (persisted.targetDeviceName || '').trim() || targetId;
+    const remoteState = this.requireCloud().remoteState;
+    remoteState.setControlTarget('account_device', targetId, targetName);
+    remoteState.setDesktopIdentity(targetName, targetId);
+  }
+
   private async loadGeneralChatAccountModels(session: CloudAccountSession, relayUrl: string): Promise<void> {
     const cloud = this.requireCloud();
     this.store.replaceAccountModels([]);
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/VisibleConversationController.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/VisibleConversationController.ets
new file mode 100644
index 0000000000..3b49a51543
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/pages/viewmodel/VisibleConversationController.ets
@@ -0,0 +1,316 @@
+import { RemoteSession } from '../../model/RemoteModels';
+import { ChatTimelineItem } from '../../services/ChatTimelineProjector';
+import { ChatTimelineState } from '../../services/ChatTimelineStore';
+import { RemoteI18n } from '../../i18n/RemoteI18n';
+import { RemoteLogger } from '../../services/RemoteLogger';
+import { RemoteUiState } from '../../services/RemoteUiState';
+import {
+  GeneralChatServiceState,
+  GeneralChatServiceStatus
+} from '../../services/general-chat/GeneralChatServiceState';
+import { AppRoute } from '../navigation/AppRouteContract';
+import { GeneralChatPageState } from '../state/GeneralChatPageState';
+import { RemotePageState } from '../state/RemotePageState';
+import {
+  GENERAL_CHAT_HOME_DRAFT_ID,
+  RemoteConversationDependencies,
+  requireRemoteRuntime
+} from './ConversationRuntime';
+import { RemoteCreateFlowController } from './RemoteCreateFlowController';
+import { RemoteTranscriptController } from './RemoteTranscriptController';
+
+export class VisibleConversationController {
+  private readonly general: GeneralChatPageState;
+  private readonly remote: RemotePageState;
+  private readonly remoteRuntime?: RemoteConversationDependencies;
+  private readonly transcript: RemoteTranscriptController;
+  private readonly createFlow: RemoteCreateFlowController;
+  private readonly setChatInputRef: (route: AppRoute, value: string) => void;
+  private readonly setVisibleStatusTextRef: (statusText: string) => void;
+  private readonly isGeneralComposerRouteRef: (route: AppRoute) => boolean;
+  private readonly notify: (message: string) => void;
+
+  constructor(
+    general: GeneralChatPageState,
+    remote: RemotePageState,
+    remoteRuntime: RemoteConversationDependencies | undefined,
+    transcript: RemoteTranscriptController,
+    createFlow: RemoteCreateFlowController,
+    setChatInputRef: (route: AppRoute, value: string) => void,
+    setVisibleStatusTextRef: (statusText: string) => void,
+    isGeneralComposerRouteRef: (route: AppRoute) => boolean,
+    notify: (message: string) => void
+  ) {
+    this.general = general;
+    this.remote = remote;
+    this.remoteRuntime = remoteRuntime;
+    this.transcript = transcript;
+    this.createFlow = createFlow;
+    this.setChatInputRef = setChatInputRef;
+    this.setVisibleStatusTextRef = setVisibleStatusTextRef;
+    this.isGeneralComposerRouteRef = isGeneralComposerRouteRef;
+    this.notify = notify;
+  }
+
+  openHomeSession(session: RemoteSession, inPlace: boolean = false): void {
+    requireRemoteRuntime(this.remoteRuntime).filePreview.close();
+    if (session.agentType === 'chat') {
+      this.openGeneralSession(session);
+      return;
+    }
+    this.createFlow.openRemoteSession(session, inPlace);
+  }
+
+  async deleteHomeSession(session: RemoteSession): Promise<void> {
+    if (session.agentType !== 'chat') {
+      await this.createFlow.deleteRemoteSession(session);
+      return;
+    }
+    await requireRemoteRuntime(this.remoteRuntime).generalCommands.deleteSession(session, this.general.isBusy);
+  }
+
+  activeGeneralChatAsRemoteSession(): RemoteSession {
+    const active = this.general.activeSession;
+    return {
+      id: active.sessionId,
+      title: active.title,
+      agentType: 'chat',
+      status: 'ready',
+      updatedAt: '',
+      createdAt: '',
+      messageCount: this.general.timelineItems.length,
+      workspacePath: active.workspacePath
+    };
+  }
+
+  activeGeneralUploadedFileCount(): number {
+    let count = 0;
+    this.general.timelineItems.forEach((item: ChatTimelineItem) => {
+      if (item.message && item.message.images) {
+        count += item.message.images.length;
+      }
+    });
+    return count;
+  }
+
+  async archiveHomeSession(session: RemoteSession, archived: boolean): Promise<void> {
+    await requireRemoteRuntime(this.remoteRuntime).generalCommands.archiveSession(session, archived, this.general.isBusy);
+  }
+
+  async exportHomeSession(session: RemoteSession): Promise<void> {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    await runtime.generalCommands.exportSession(
+      session,
+      this.general.isBusy,
+      async (text: string): Promise<void> => runtime.clipboard.writeText(text)
+    );
+  }
+
+  async openGeneralSession(item: RemoteSession): Promise<void> {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    if (this.general.isBusy) {
+      return;
+    }
+    runtime.polling.stop();
+    runtime.generalConversation.stop(false);
+    await runtime.generalCommands.openSession(
+      item,
+      this.general.isBusy,
+      async (sessionId: string): Promise<string> => runtime.generalDrafts.restore(sessionId),
+      (_sessionId: string): void => runtime.appShell.replaceRouteWithoutAnimation(AppRoute.ChatHome)
+    );
+  }
+
+  async startGeneralChat(text: string): Promise<void> {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    const trimmed = text.trim();
+    if (trimmed.length === 0 || this.general.isBusy) {
+      return;
+    }
+    runtime.polling.stop();
+    runtime.generalConversation.stop(false);
+    runtime.generalDrafts.cancel();
+    const created = await runtime.generalCommands.createSession(
+      trimmed,
+      this.general.isBusy,
+      async (): Promise<void> => runtime.generalDrafts.clearHomeNow(),
+      (_sessionId: string): void => runtime.appShell.replaceRouteWithoutAnimation(AppRoute.ChatHome)
+    );
+    if (created) {
+      await runtime.generalConversation.sendMessage();
+    }
+  }
+
+  async sendVisibleMessage(): Promise<void> {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    if (runtime.appShell.isGeneralChatVisible()) {
+      if ((this.general.activeSession.sessionId || '').length === 0) {
+        this.startVisibleGeneralChat();
+        return;
+      }
+      await runtime.generalConversation.sendMessage();
+      return;
+    }
+    await this.transcript.sendRemoteMessage();
+  }
+
+  async stopVisibleTask(): Promise<void> {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    if (runtime.appShell.isGeneralChatVisible()) {
+      runtime.generalConversation.stop(true);
+      return;
+    }
+    await this.transcript.stopRemoteTask();
+  }
+
+  closeActiveChat(): void {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    runtime.filePreview.close();
+    runtime.hooks.stopVoiceInput();
+    if (runtime.appShell.isRoute(AppRoute.GeneralChat)) {
+      runtime.generalDrafts.persistVisible(this.general.chatInput);
+      runtime.generalConversation.stop(true);
+      runtime.appShell.popRoute(AppRoute.ChatHome);
+      this.restoreGeneralChatDraft(GENERAL_CHAT_HOME_DRAFT_ID);
+      return;
+    }
+    runtime.polling.stop();
+    this.remote.setConversationDismissed(true);
+    runtime.appShell.replaceRouteWithoutAnimation(AppRoute.RemoteHome);
+  }
+
+  async renameVisibleSession(title: string): Promise<void> {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    if (runtime.appShell.isGeneralChatVisible()) {
+      await runtime.generalCommands.renameActiveSession(this.general.activeSession, title);
+      return;
+    }
+    await this.transcript.renameRemoteSession(title);
+  }
+
+  async retryVisibleMessage(text: string): Promise<void> {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    if (runtime.appShell.isGeneralChatVisible()) {
+      const prepared = await runtime.generalCommands.retryMessage(
+        this.general.activeSession.sessionId || '', text, this.general.isBusy
+      );
+      if (prepared) {
+        await runtime.generalConversation.sendMessage();
+      }
+      return;
+    }
+    this.transcript.retryRemoteMessage(text);
+  }
+
+  downloadVisibleFile(path: string): void {
+    if (requireRemoteRuntime(this.remoteRuntime).appShell.isGeneralChatVisible()) {
+      this.general.setStatus(RemoteI18n.t('generalChat.fileDownloadMock'));
+      return;
+    }
+    this.transcript.downloadRemoteFile(path);
+  }
+
+  async selectVisibleModel(modelId: string): Promise<void> {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    if (runtime.appShell.isGeneralChatVisible()) {
+      await runtime.settings.selectModel(modelId);
+      return;
+    }
+    await this.transcript.selectRemoteModel(modelId);
+  }
+
+  startVisibleGeneralChat(): void {
+    const rawText = this.general.chatInput.trim();
+    const text = rawText.length > 0 ? rawText :
+      (this.general.selectedImages.length > 0 ? RemoteI18n.t('chat.analyzeImageDefault') : '');
+    if (text.length === 0 || this.general.isBusy) {
+      return;
+    }
+    if (this.general.serviceState === GeneralChatServiceState.Unconfigured) {
+      const statusText = GeneralChatServiceStatus.userMessage(this.general.serviceState);
+      this.general.setStatus(statusText);
+      this.notify(statusText);
+      return;
+    }
+    this.startGeneralChat(text);
+  }
+
+  generalChatHomeStatusText(): string {
+    if (this.general.serviceState === GeneralChatServiceState.Ready ||
+      this.general.serviceState === GeneralChatServiceState.Sending ||
+      this.general.serviceState === GeneralChatServiceState.Streaming) {
+      return '';
+    }
+    return GeneralChatServiceStatus.userMessage(this.general.serviceState, this.general.statusText);
+  }
+
+  prepareNewGeneralChat(): void {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    runtime.hooks.stopVoiceInput();
+    runtime.generalConversation.stop(true);
+    runtime.generalDrafts.clearHome();
+    this.general.clearComposer();
+    this.general.clearActiveSession();
+    this.resetGeneralTimeline('');
+    runtime.appShell.replaceRouteWithoutAnimation(AppRoute.ChatHome);
+  }
+
+  onVisibleChatInputChange(route: AppRoute, value: string): void {
+    this.setChatInputRef(route, value);
+    if (this.isGeneralComposerRouteRef(route)) {
+      requireRemoteRuntime(this.remoteRuntime).generalDrafts.scheduleVisible(value);
+    }
+  }
+
+  visibleGeneralChatDraftId(): string {
+    return requireRemoteRuntime(this.remoteRuntime).appShell.isGeneralChatVisible() ?
+      this.general.activeSession.sessionId || GENERAL_CHAT_HOME_DRAFT_ID : '';
+  }
+
+  async restoreGeneralChatDraft(draftId: string): Promise<void> {
+    this.general.setChatInput(await requireRemoteRuntime(this.remoteRuntime).generalDrafts.restore(draftId));
+  }
+
+  latestUserMessageText(): string {
+    if (requireRemoteRuntime(this.remoteRuntime).appShell.isGeneralChatVisible()) {
+      return this.general.latestUserMessageText();
+    }
+    const candidates = this.remote.persistedMessages.concat(this.remote.optimisticMessages);
+    for (let index = candidates.length - 1; index >= 0; index--) {
+      if (candidates[index].role === 'user' && candidates[index].text.trim().length > 0) {
+        return candidates[index].text;
+      }
+    }
+    return '';
+  }
+
+  resetGeneralTimeline(sessionId: string): void {
+    requireRemoteRuntime(this.remoteRuntime).timeline.reset(sessionId);
+    this.syncGeneralTimeline();
+  }
+
+  syncGeneralTimeline(): void {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    const state: ChatTimelineState = runtime.timeline.snapshotState();
+    const projectedItems = runtime.timeline.viewState(false);
+    this.general.setTimelineProjection(
+      state.persistedMessages,
+      state.optimisticMessages,
+      state.activeTurn || RemoteUiState.emptyActiveTurn(),
+      false,
+      projectedItems
+    );
+    const itemSummary = projectedItems.map((item: ChatTimelineItem) => {
+      const message = item.message;
+      return `${item.type}:${item.id}:${message ? message.status : ''}:${message ? message.text.length : 0}`;
+    }).join(',');
+    RemoteLogger.info(`general chat projection revision=${this.general.timelineRevision} persisted=${state.persistedMessages.length} active=${state.activeTurn ? state.activeTurn.id : 'none'} items=${itemSummary}`);
+  }
+
+  showHomeToast(message: string): void {
+    const runtime = requireRemoteRuntime(this.remoteRuntime);
+    if (!runtime.hooks.showToast(message)) {
+      this.setVisibleStatusTextRef(message);
+    }
+  }
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/ChatComposerPolicy.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/ChatComposerPolicy.ets
index 36a5ab165d..cb88aa0e09 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/services/ChatComposerPolicy.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/ChatComposerPolicy.ets
@@ -1,3 +1,18 @@
+// Each offered action has a live and a dimmed form, and both are worth keeping
+// apart from Idle. SendBlocked means the user has written something the link
+// cannot carry yet — drawing that as idle would tell them their draft does not
+// exist. VoiceBlocked keeps the microphone on screen through a busy moment, so
+// the control does not swap glyphs mid-turn and then swap back. Idle is the one
+// state with nothing to offer: no dictation on this surface, and no draft.
+export enum ComposerPrimaryAction {
+  Stop = 'stop',
+  Send = 'send',
+  SendBlocked = 'send_blocked',
+  Voice = 'voice',
+  VoiceBlocked = 'voice_blocked',
+  Idle = 'idle'
+}
+
 export class ChatComposerPolicy {
   static canSend(
     text: string,
@@ -15,4 +30,76 @@ export class ChatComposerPolicy {
   static canUseVoice(text: string, attachmentCount: number, isBusy: boolean): boolean {
     return text.trim().length === 0 && attachmentCount === 0 && !isBusy;
   }
+
+  // Which of the things the one round button on the right is offering. The
+  // composer has a single primary slot rather than a row of buttons, so "which
+  // action" is a decision, not a layout detail — and it is the same decision on
+  // both clients. Dictation and a running turn used to arrive here folded into
+  // one flag, but they sit on opposite sides of the draft: dictation outranks
+  // it because the draft is still being spoken, whereas a running turn only
+  // outranks it where the draft has nowhere to go — on a surface that can hand
+  // the message over mid-run, keeping the button on Stop traps what was typed.
+  static primaryAction(
+    text: string,
+    attachmentCount: number,
+    isBusy: boolean,
+    isVoiceListening: boolean,
+    isTurnRunning: boolean,
+    supportsMidRunSend: boolean,
+    requiresRemoteConnection: boolean,
+    connectionState: string,
+    showVoiceInput: boolean
+  ): ComposerPrimaryAction {
+    if (isVoiceListening) {
+      return ComposerPrimaryAction.Stop;
+    }
+    if (isTurnRunning && !supportsMidRunSend) {
+      return ComposerPrimaryAction.Stop;
+    }
+    if (text.trim().length > 0 || attachmentCount > 0) {
+      const sendable = ChatComposerPolicy.canSend(
+        text, attachmentCount, isBusy, requiresRemoteConnection, connectionState);
+      return sendable ? ComposerPrimaryAction.Send : ComposerPrimaryAction.SendBlocked;
+    }
+    if (isTurnRunning) {
+      return ComposerPrimaryAction.Stop;
+    }
+    if (!showVoiceInput) {
+      return ComposerPrimaryAction.Idle;
+    }
+    const usable = ChatComposerPolicy.canUseVoice(text, attachmentCount, isBusy);
+    return usable ? ComposerPrimaryAction.Voice : ComposerPrimaryAction.VoiceBlocked;
+  }
+
+  // Whether the bar is in its tall form, where the field gets its own row and
+  // the side controls move to a second one. A newline counts even without
+  // focus: the collapsed field is one line tall, and text the user cannot see
+  // is text they cannot check before sending.
+  static isExpanded(
+    text: string,
+    inputFocused: boolean,
+    modelSelectorOpen: boolean
+  ): boolean {
+    return inputFocused || modelSelectorOpen || text.indexOf('\n') >= 0;
+  }
+
+  static shouldShowAddButton(showAddButton: boolean, supportsAttachments: boolean): boolean {
+    return showAddButton && supportsAttachments;
+  }
+
+  static primaryActionAccessibilityKey(
+    action: ComposerPrimaryAction,
+    isVoiceListening: boolean
+  ): string {
+    if (action === ComposerPrimaryAction.Stop) {
+      return isVoiceListening ? 'chat.stopListening' : 'chat.stop';
+    }
+    if (action === ComposerPrimaryAction.Voice || action === ComposerPrimaryAction.VoiceBlocked) {
+      return 'chat.voiceInput';
+    }
+    if (action === ComposerPrimaryAction.Send || action === ComposerPrimaryAction.SendBlocked) {
+      return 'chat.send';
+    }
+    return '';
+  }
 }
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/ChatSessionController.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/ChatSessionController.ets
index 84837768fa..ee974c5e55 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/services/ChatSessionController.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/ChatSessionController.ets
@@ -22,6 +22,10 @@ export interface ChatSessionSnapshot {
   activeTurn?: ChatMessage;
   modelCatalog?: RemoteModelCatalog;
   shouldSyncAfterTurnEnded: boolean;
+  // The desktop now holds fewer messages than this session had counted, so the
+  // transcript it was handing out tails of is no longer the one on screen.
+  // Nothing below can resume from an offset into a list that shrank.
+  historyRewritten: boolean;
 }
 
 export interface ChatSessionControllerCallbacks {
@@ -182,6 +186,8 @@ export class ChatSessionController {
     const hasAssistantMessage = incomingMessages.some((message: ChatMessage) => {
       return message.role === 'assistant';
     });
+    const historyRewritten = result.totalMessageCount > 0 &&
+      result.totalMessageCount < this.cursor.knownMessageCount;
 
     if (result.changed) {
       this.cursor = {
@@ -215,7 +221,8 @@ export class ChatSessionController {
       result.changed || activeTurnChanged,
       result,
       incomingMessages,
-      turnEndedNow || (isSettlingEndedTurn && !isRunningNow)
+      turnEndedNow || (isSettlingEndedTurn && !isRunningNow),
+      historyRewritten
     );
   }
 
@@ -232,7 +239,8 @@ export class ChatSessionController {
     changed: boolean,
     result: PollSessionResult,
     newMessages: ChatMessage[],
-    shouldSyncAfterTurnEnded: boolean
+    shouldSyncAfterTurnEnded: boolean,
+    historyRewritten: boolean
   ): void {
     this.callbacks.onSnapshot({
       sessionId: this.sessionId,
@@ -247,7 +255,8 @@ export class ChatSessionController {
       newMessages,
       activeTurn: this.activeTurn,
       modelCatalog: result.modelCatalog,
-      shouldSyncAfterTurnEnded
+      shouldSyncAfterTurnEnded,
+      historyRewritten
     });
   }
 
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/ChatTimelineProjector.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/ChatTimelineProjector.ets
index 05a894ef71..ef2cdca7bf 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/services/ChatTimelineProjector.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/ChatTimelineProjector.ets
@@ -21,14 +21,28 @@ export class ChatTimelineRevisionTracker {
   private signature: string = '';
   private revision: number = 0;
 
+  /**
+   * Identity of a single rendered item: its own id, plus everything about it
+   * the bubble draws.
+   *
+   * Doubles as the timeline's `ForEach` key, which is the point of it being
+   * per-item. Keying on the revision instead made every bubble in the
+   * transcript a new node whenever any one of them changed — during a run that
+   * is a full rebuild per poll tick, to show one message growing.
+   */
+  static itemSignature(item: ChatTimelineItem): string {
+    const message = item.message;
+    return `${item.type}:${item.id}:${item.isStreaming}:${item.isFinalizing}:` +
+      `${message ? message.status : ''}:${message ? message.renderVersion || 0 : 0}:` +
+      `${message ? ChatTimelineRevisionTracker.textSignature(message.text) : ''}:` +
+      `${message && message.thinking ? ChatTimelineRevisionTracker.textSignature(message.thinking) : ''}:` +
+      `${message && message.items ? message.items.length : 0}:${message && message.tools ? message.tools.length : 0}`;
+  }
+
   update(items: ChatTimelineItem[]): number {
-    const nextSignature = items.map((item: ChatTimelineItem) => {
-      const message = item.message;
-      return `${item.type}:${item.id}:${item.isStreaming}:${item.isFinalizing}:` +
-        `${message ? message.status : ''}:${message ? message.renderVersion || 0 : 0}:` +
-        `${message ? this.textSignature(message.text) : ''}:${message && message.thinking ? this.textSignature(message.thinking) : ''}:` +
-        `${message && message.items ? message.items.length : 0}:${message && message.tools ? message.tools.length : 0}`;
-    }).join('|');
+    const nextSignature = items
+      .map((item: ChatTimelineItem) => ChatTimelineRevisionTracker.itemSignature(item))
+      .join('|');
     if (nextSignature !== this.signature) {
       this.signature = nextSignature;
       this.revision += 1;
@@ -36,7 +50,7 @@ export class ChatTimelineRevisionTracker {
     return this.revision;
   }
 
-  private textSignature(value: string): string {
+  private static textSignature(value: string): string {
     let hash = 0;
     for (let index = 0; index < value.length; index++) {
       hash = ((hash << 5) - hash + value.charCodeAt(index)) | 0;
@@ -52,15 +66,23 @@ export class ChatTimelineRevisionTracker {
 }
 
 export class ChatTimelineProjector {
+  /**
+   * `activeTurnAnchorId` is the id of the optimistic message the running turn
+   * is answering. Anything sent after that message is queued behind the turn,
+   * so it belongs below the reply rather than above it — appending the turn
+   * last would push a mid-run message up under the previous one instead.
+   */
   static project(
     messages: ChatMessage[],
     pendingMessages: ChatMessage[],
     activeTurn: ChatMessage,
-    hasMoreMessages: boolean
+    hasMoreMessages: boolean,
+    activeTurnAnchorId: string = ''
   ): ChatTimelineItem[] {
     const timelineMessages = ChatTimelineProjector.realMessages(messages);
     const pendingItems = ChatTimelineProjector.pendingMessagesNotPersisted(pendingMessages, timelineMessages);
     const shouldRenderActiveTurn = ChatTimelineProjector.shouldRenderActiveTurn(timelineMessages, activeTurn);
+    const anchorIndex = ChatTimelineProjector.anchorIndex(pendingItems, activeTurnAnchorId);
     const items: ChatTimelineItem[] = timelineMessages.map((message: ChatMessage) => {
       const item: ChatTimelineItem = {
         id: `message-${message.id}`,
@@ -73,7 +95,14 @@ export class ChatTimelineProjector {
       return item;
     });
 
-    pendingItems.forEach((message: ChatMessage) => {
+    // The message that started the turn has usually been persisted by the time
+    // the reply streams, so no anchor is left to sit behind: whatever is still
+    // optimistic was sent later and is waiting its turn.
+    if (shouldRenderActiveTurn && anchorIndex < 0) {
+      items.push(ChatTimelineProjector.activeTurnItem(activeTurn));
+    }
+
+    pendingItems.forEach((message: ChatMessage, index: number) => {
       const item: ChatTimelineItem = {
         id: `pending-${message.id}`,
         type: 'optimistic_user_message',
@@ -83,21 +112,11 @@ export class ChatTimelineProjector {
         showRetryAction: false
       };
       items.push(item);
+      if (shouldRenderActiveTurn && index === anchorIndex) {
+        items.push(ChatTimelineProjector.activeTurnItem(activeTurn));
+      }
     });
 
-    if (shouldRenderActiveTurn) {
-      const turnKey = ChatTimelineProjector.activeTurnKey(activeTurn);
-      const item: ChatTimelineItem = {
-        id: `active-${turnKey}-${ChatTimelineProjector.activeTurnVersionKey(activeTurn)}`,
-        type: 'assistant_live_turn',
-        message: activeTurn,
-        isStreaming: (activeTurn.status || '').toLowerCase() === 'active',
-        isFinalizing: (activeTurn.status || '').toLowerCase() === 'completed',
-        showRetryAction: false
-      };
-      items.push(item);
-    }
-
     if (items.length === 0 && !hasMoreMessages) {
       const item: ChatTimelineItem = {
         id: 'empty-state',
@@ -113,6 +132,31 @@ export class ChatTimelineProjector {
     return items;
   }
 
+  private static anchorIndex(pendingItems: ChatMessage[], activeTurnAnchorId: string): number {
+    if (activeTurnAnchorId.length === 0) {
+      return -1;
+    }
+    for (let index = 0; index < pendingItems.length; index++) {
+      if (pendingItems[index].id === activeTurnAnchorId) {
+        return index;
+      }
+    }
+    return -1;
+  }
+
+  private static activeTurnItem(activeTurn: ChatMessage): ChatTimelineItem {
+    const turnKey = ChatTimelineProjector.activeTurnKey(activeTurn);
+    const item: ChatTimelineItem = {
+      id: `active-${turnKey}-${ChatTimelineProjector.activeTurnVersionKey(activeTurn)}`,
+      type: 'assistant_live_turn',
+      message: activeTurn,
+      isStreaming: (activeTurn.status || '').toLowerCase() === 'active',
+      isFinalizing: (activeTurn.status || '').toLowerCase() === 'completed',
+      showRetryAction: false
+    };
+    return item;
+  }
+
   private static markLatestFailedMessageRetryable(items: ChatTimelineItem[]): void {
     for (let index = items.length - 1; index >= 0; index--) {
       const message = items[index].message;
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/ChatTimelineStore.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/ChatTimelineStore.ets
index 691a619a49..ef90f6c172 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/services/ChatTimelineStore.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/ChatTimelineStore.ets
@@ -10,6 +10,11 @@ import { ChatTimelineItem, ChatTimelineProjector } from './ChatTimelineProjector
 import { RemoteUiState } from './RemoteUiState';
 import { ConversationEvent } from './ConversationEvent';
 
+// Marks the placeholder turn shown between sending a message and hearing back
+// which turn the desktop opened for it. Everything after the prefix is a local
+// message id, so it must never be mistaken for a server-issued turn id.
+export const PENDING_ACTIVE_TURN_ID_PREFIX: string = 'active-pending-';
+
 export type ChatSyncPhase =
   | 'idle'
   | 'loading'
@@ -32,9 +37,15 @@ export interface ChatTimelineState {
 
 export class ChatTimelineStore {
   private state: ChatTimelineState = ChatTimelineStore.emptyState('');
+  // The optimistic message the active turn is replying to. Kept out of
+  // `ChatTimelineState` because nothing but the projection needs it: it exists
+  // so a message sent mid-run renders below the running reply instead of
+  // jumping up beside the message that started it.
+  private activeTurnAnchor: string = '';
 
   reset(sessionId: string = ''): void {
     this.state = ChatTimelineStore.emptyState(sessionId);
+    this.activeTurnAnchor = '';
   }
 
   snapshot(): ChatTimelineState {
@@ -206,6 +217,11 @@ export class ChatTimelineStore {
       !ChatTimelineStore.isLocalPendingActiveTurn(this.state.activeTurn)) {
       return;
     }
+    // Promoting the placeholder keeps the message it was opened for; a turn
+    // that appears without one belongs to the newest thing the user sent.
+    if (!this.state.activeTurn || !ChatTimelineStore.isLocalPendingActiveTurn(this.state.activeTurn)) {
+      this.activeTurnAnchor = this.lastOptimisticMessageId();
+    }
     const activeTurn: ChatMessage = {
       id: activeId,
       turnId: normalizedTurnId,
@@ -231,12 +247,13 @@ export class ChatTimelineStore {
     if (normalizedLocalId.length === 0) {
       return '';
     }
-    const activeId = `active-pending-${normalizedLocalId}`;
+    const activeId = `${PENDING_ACTIVE_TURN_ID_PREFIX}${normalizedLocalId}`;
     if (this.state.activeTurn && this.state.activeTurn.id.length > 0 &&
       this.state.activeTurn.id !== activeId &&
       !ChatTimelineStore.isLocalPendingActiveTurn(this.state.activeTurn)) {
       return '';
     }
+    this.activeTurnAnchor = normalizedLocalId;
     const activeTurn: ChatMessage = {
       id: activeId,
       role: 'assistant',
@@ -262,6 +279,7 @@ export class ChatTimelineStore {
       !ChatTimelineStore.isLocalPendingActiveTurn(this.state.activeTurn)) {
       return;
     }
+    this.activeTurnAnchor = '';
     this.state = {
       sessionId: this.state.sessionId,
       persistedMessages: this.state.persistedMessages,
@@ -291,6 +309,7 @@ export class ChatTimelineStore {
   }
 
   clearActiveTurn(): void {
+    this.activeTurnAnchor = '';
     this.state = {
       sessionId: this.state.sessionId,
       persistedMessages: this.state.persistedMessages,
@@ -398,10 +417,21 @@ export class ChatTimelineStore {
       this.state.persistedMessages,
       this.state.optimisticMessages,
       this.activeTurnOrEmpty(),
-      hasMoreMessages
+      hasMoreMessages,
+      this.activeTurnAnchor
     );
   }
 
+  /** The optimistic message the running turn answers, or '' once it persisted. */
+  activeTurnAnchorId(): string {
+    return this.activeTurnAnchor;
+  }
+
+  private lastOptimisticMessageId(): string {
+    const messages = this.state.optimisticMessages;
+    return messages.length > 0 ? messages[messages.length - 1].id : '';
+  }
+
   private acceptsSession(sessionId: string): boolean {
     return sessionId.length === 0 || this.state.sessionId.length === 0 || this.state.sessionId === sessionId;
   }
@@ -494,8 +524,23 @@ export class ChatTimelineStore {
     return undefined;
   }
 
+  // The turn id to ask the desktop to cancel, or '' for "whatever is running
+  // now". A placeholder turn carries a local message id rather than a turn id,
+  // and offering that as one gets the cancel rejected as stale while the task
+  // keeps going — so the placeholder window has to fall through to no id.
+  static cancelableTurnId(activeTurn: ChatMessage): string {
+    if (activeTurn.turnId && activeTurn.turnId.length > 0) {
+      return activeTurn.turnId;
+    }
+    if (activeTurn.id.indexOf(PENDING_ACTIVE_TURN_ID_PREFIX) === 0) {
+      return '';
+    }
+    return activeTurn.id.indexOf('active-') === 0 ? activeTurn.id.slice('active-'.length) : '';
+  }
+
   private static isLocalPendingActiveTurn(activeTurn: ChatMessage): boolean {
-    return activeTurn.id.indexOf('active-pending-') === 0 && (!activeTurn.turnId || activeTurn.turnId.length === 0);
+    return activeTurn.id.indexOf(PENDING_ACTIVE_TURN_ID_PREFIX) === 0 &&
+      (!activeTurn.turnId || activeTurn.turnId.length === 0);
   }
 
   private static emptyState(sessionId: string): ChatTimelineState {
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/CloudAccountClient.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/CloudAccountClient.ets
index 1ae3c6919b..c00e33d725 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/services/CloudAccountClient.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/CloudAccountClient.ets
@@ -3,6 +3,7 @@ import { CloudAccountCrypto, CloudAccountKdfParams } from './CloudAccountCrypto'
 import { Encoding } from './Encoding';
 import { HarmonyRemoteCryptoCipher } from './RemoteCrypto';
 import { RemoteLogger } from './RemoteLogger';
+import { RemoteI18n } from '../i18n/RemoteI18n';
 import { CommandStatusResponse, EncryptedPayload, RemoteCommand } from '../model/RemoteModels';
 
 interface AccountChallenge {
@@ -18,7 +19,13 @@ interface AccountAuthResponse {
 }
 
 interface LoginChallengeRequest { username: string; }
-interface LoginRequest { username: string; password_hash: string; device_id: string; device_name: string; }
+interface LoginRequest {
+  username: string;
+  password_hash: string;
+  device_id: string;
+  device_name: string;
+  device_kind: string;
+}
 interface RelayErrorResponse { error?: string; }
 
 export class CloudAccountRequestError extends Error {
@@ -40,46 +47,37 @@ export interface CloudAccountSession {
 export interface CloudAccountDevice {
   deviceId: string;
   deviceName: string;
+  deviceKind?: string;
   online: boolean;
   lastSeenAt?: number;
 }
 
-interface CloudAccountDeviceWire {
-  device_id: string;
-  device_name: string;
-  online: boolean;
-  last_seen_at?: number;
+/** A device credential minted for another device, never for this one. */
+export interface CloudProvisionedDevice {
+  token: string;
+  userId: string;
+  deviceId: string;
 }
 
-export interface CloudSessionBundle {
-  sessionId: string;
-  metadata: Object;
-  turns: Object[];
-  sourceDeviceId?: string;
-  sourceDeviceName?: string;
-  version: number;
+interface ProvisionDeviceRequest {
+  device_id: string;
+  device_name: string;
+  device_kind: string;
+  request_id: string;
 }
 
-interface SyncSessionEntry {
-  session_id: string;
-  encrypted_data: string;
-  nonce: string;
-  version: number;
+interface ProvisionDeviceWire {
+  token: string;
+  user_id: string;
+  device_id: string;
 }
 
-interface SyncSessionList { sessions: SyncSessionEntry[]; }
-interface SessionBundleWire {
-  session_id: string;
-  metadata: Object;
-  turns: Object[];
-  source_device_id?: string;
-  source_device_name?: string;
-}
-interface SyncSessionUpload {
-  session_id: string;
-  encrypted_data: string;
-  nonce: string;
-  version: number;
+interface CloudAccountDeviceWire {
+  device_id: string;
+  device_name: string;
+  device_kind?: string;
+  online: boolean;
+  last_seen_at?: number;
 }
 
 interface SyncSettingsEntry {
@@ -96,6 +94,45 @@ export interface CloudSettingsBlob {
 /** Default BitFun cloud relay used by the desktop account flow. */
 export const DEFAULT_CLOUD_RELAY_URL: string = 'https://remote.openbitfun.com/relay';
 
+/** Device kinds the relay accepts; mirrors `relay-service/src/db.rs::DEVICE_KINDS`. */
+const DEVICE_KIND_DESKTOP: string = 'desktop';
+const DEVICE_KIND_MOBILE: string = 'mobile';
+const DEVICE_KIND_WATCH: string = 'watch';
+
+/**
+ * Device names our own non-desktop builds register under, lowercased.
+ *
+ * Only labels we hardcode ourselves belong here: the Android client reports
+ * `Build.MODEL` (`android/.../DeviceInstall.kt:27`), an arbitrary string that
+ * guessing at would hide desktops as readily as phones.
+ *
+ * Kept in step with `shared/core-transport/.../CloudAccountClient.kt`, which
+ * carries the same list for the Android and iOS clients.
+ */
+const KNOWN_NON_DESKTOP_DEVICE_NAMES: string[] = ['harmonyos phone', 'harmonyos watch'];
+
+/**
+ * Whether a relay device row is a desktop, and so controllable from a phone.
+ *
+ * A row that reports its kind is taken at its word. A row without one predates
+ * the relay learning about kinds, and is judged by two weaker signals: this
+ * phone's own row is never a desktop, and neither is one carrying a name our
+ * own builds register under. Anything else stays visible — hiding a real
+ * desktop would strand the user, while a stale phone row disappears the next
+ * time that phone logs in against a relay that stores kinds.
+ */
+function isDesktopDeviceRow(device: CloudAccountDeviceWire, selfDeviceId: string): boolean {
+  const kind = (device.device_kind || '').trim();
+  if (kind.length > 0) {
+    return kind === DEVICE_KIND_DESKTOP;
+  }
+  if (selfDeviceId.length > 0 && device.device_id === selfDeviceId) {
+    return false;
+  }
+  const name = (device.device_name || '').trim().toLowerCase();
+  return KNOWN_NON_DESKTOP_DEVICE_NAMES.indexOf(name) < 0;
+}
+
 /** Client for the current desktop relay account protocol. */
 export class CloudAccountClient {
   private readonly cipher: HarmonyRemoteCryptoCipher = new HarmonyRemoteCryptoCipher();
@@ -124,30 +161,53 @@ export class CloudAccountClient {
       username: normalizedUser,
       password_hash: Encoding.bytesToBase64(passwordHash),
       device_id: deviceId,
-      device_name: 'HarmonyOS Phone'
+      device_name: 'HarmonyOS Phone',
+      device_kind: DEVICE_KIND_MOBILE
     };
     const auth = await this.post<AccountAuthResponse>(normalizedRelayUrl, '/api/auth/login', loginRequest);
     RemoteLogger.info(`cloud login authenticated elapsed_ms=${Date.now() - startedAt}`);
     return { token: auth.token, userId: auth.user_id, masterKey };
   }
 
-  async fetchSessions(relayUrl: string, session: CloudAccountSession, since: number = 0): Promise<CloudSessionBundle[]> {
-    const suffix = `/api/sync/sessions?since=${Math.max(0, since)}`;
-    const payload = await this.request<SyncSessionList>(relayUrl, suffix, 'GET', undefined, session.token);
-    const bundles: CloudSessionBundle[] = [];
-    for (const entry of payload.sessions || []) {
-      const plain = await this.decryptSyncPayload(session.masterKey, entry.encrypted_data, entry.nonce);
-      const bundle = JSON.parse(plain) as SessionBundleWire;
-      bundles.push({
-        sessionId: bundle.session_id || entry.session_id,
-        metadata: bundle.metadata,
-        turns: bundle.turns,
-        sourceDeviceId: bundle.source_device_id,
-        sourceDeviceName: bundle.source_device_name,
-        version: entry.version
-      });
+  /**
+   * Adds another device to this account and returns its own credential.
+   *
+   * The relay gates `/api/auth/provision-device` on nothing but
+   * `AuthToken::is_device_token()` (`relay-service/src/routes/auth.rs`), so a
+   * phone that signed in with the account password is as entitled to mint here
+   * as the desktop is — the desktop was never special, it just happened to be
+   * the one holding a session. A token delegated by a room pairing is
+   * `delegated_control` rather than `device` and is refused with 403; that is
+   * the caller's cue to fall back to asking the desktop.
+   *
+   * The account master key is deliberately not part of this exchange. The relay
+   * never sees it, and the caller already holds its own copy — a watch gets it
+   * sealed to its ephemeral key, not from here.
+   */
+  async provisionDevice(
+    relayUrl: string,
+    session: CloudAccountSession,
+    deviceId: string,
+    deviceName: string,
+    requestId: string
+  ): Promise<CloudProvisionedDevice> {
+    const body: ProvisionDeviceRequest = {
+      device_id: deviceId,
+      device_name: deviceName,
+      device_kind: DEVICE_KIND_WATCH,
+      request_id: requestId
+    };
+    const wire = await this.request<ProvisionDeviceWire>(
+      relayUrl, '/api/auth/provision-device', 'POST', body, session.token);
+    const token = (wire.token || '').trim();
+    const userId = (wire.user_id || '').trim();
+    const provisionedDeviceId = (wire.device_id || '').trim();
+    if (token.length === 0 || userId !== session.userId || provisionedDeviceId !== deviceId) {
+      // A credential naming a different account or device would sign the watch
+      // in as somebody else. Refuse rather than pass it on.
+      throw new Error('Relay returned a mismatched provisioned device identity.');
     }
-    return bundles;
+    return { token, userId, deviceId: provisionedDeviceId };
   }
 
   async fetchSettings(relayUrl: string, session: CloudAccountSession): Promise<CloudSettingsBlob | undefined> {
@@ -169,11 +229,25 @@ export class CloudAccountClient {
     };
   }
 
-  async listDevices(relayUrl: string, session: CloudAccountSession): Promise<CloudAccountDevice[]> {
+  /**
+   * The account's controllable devices — desktops only.
+   *
+   * A relay that stores device kinds already filters this list; the client
+   * repeats the judgement so a phone stops listing itself and its peers before
+   * that relay is deployed. [selfDeviceId] is this install's own device id.
+   */
+  async listDevices(
+    relayUrl: string,
+    session: CloudAccountSession,
+    selfDeviceId: string = ''
+  ): Promise<CloudAccountDevice[]> {
     const devices = await this.request<CloudAccountDeviceWire[]>(relayUrl, '/api/devices', 'GET', undefined, session.token);
-    return devices.map((device: CloudAccountDeviceWire): CloudAccountDevice => ({
+    const desktops = devices.filter((device: CloudAccountDeviceWire): boolean =>
+      isDesktopDeviceRow(device, selfDeviceId));
+    return desktops.map((device: CloudAccountDeviceWire): CloudAccountDevice => ({
       deviceId: device.device_id,
       deviceName: device.device_name || device.device_id,
+      deviceKind: device.device_kind,
       online: device.online,
       lastSeenAt: device.last_seen_at
     }));
@@ -199,6 +273,7 @@ export class CloudAccountClient {
       encrypted_data: Encoding.bytesToBase64(encrypted),
       nonce: Encoding.bytesToBase64(nonce)
     };
+    RemoteLogger.info(`device rpc cmd=${command.cmd || 'unknown'} bytes=${body.encrypted_data.length}`);
     const response = await this.request<EncryptedPayload>(
       relayUrl,
       `/api/devices/${encodeURIComponent(target)}/rpc`,
@@ -219,33 +294,6 @@ export class CloudAccountClient {
     return parsed;
   }
 
-  async deleteSession(relayUrl: string, session: CloudAccountSession, sessionId: string): Promise<void> {
-    await this.request<Object>(relayUrl, `/api/sync/sessions/${encodeURIComponent(sessionId)}`, 'DELETE', undefined, session.token);
-  }
-
-  async uploadSession(relayUrl: string, session: CloudAccountSession, bundle: CloudSessionBundle): Promise<number> {
-    const nonce = Encoding.randomBytes(12);
-    const wire: SessionBundleWire = {
-      session_id: bundle.sessionId,
-      metadata: bundle.metadata,
-      turns: bundle.turns,
-      source_device_id: bundle.sourceDeviceId,
-      source_device_name: bundle.sourceDeviceName
-    };
-    const encrypted = await this.cipher.encrypt(
-      Encoding.utf8ToBytes(JSON.stringify(wire)), session.masterKey, nonce
-    );
-    const version = Date.now();
-    const body: SyncSessionUpload = {
-      session_id: bundle.sessionId,
-      encrypted_data: Encoding.bytesToBase64(encrypted),
-      nonce: Encoding.bytesToBase64(nonce),
-      version
-    };
-    await this.request<Object>(relayUrl, '/api/sync/sessions', 'POST', body, session.token);
-    return version;
-  }
-
   private async decryptSyncPayload(masterKey: Uint8Array, data: string, nonceText: string): Promise<string> {
     const plain = await this.cipher.decrypt(Encoding.base64ToBytes(data), masterKey, Encoding.base64ToBytes(nonceText));
     return Encoding.bytesToUtf8(plain);
@@ -286,6 +334,10 @@ export class CloudAccountClient {
   ): Promise<T> {
     const request = http.createHttp();
     const base = relayUrl.replace(/\/$/, '');
+    // Timed so the watch has something to be slow relative to. Phone and watch
+    // reach the same relay and the same desktop, so a gap between them is the
+    // client's own cost and a shared floor is the round trip's.
+    const startedAt = Date.now();
     try {
       const headers: Record<string, string> = { 'Content-Type': 'application/json', 'Accept': 'application/json' };
       if (token.length > 0) headers.Authorization = `Bearer ${token}`;
@@ -296,11 +348,26 @@ export class CloudAccountClient {
         connectTimeout: 15000,
         readTimeout: readTimeoutMs
       };
-      if (body !== undefined) requestOptions.extraData = JSON.stringify(body);
+      let bodyBytes = 0;
+      if (body !== undefined) {
+        const encoded = JSON.stringify(body);
+        bodyBytes = encoded.length;
+        requestOptions.extraData = encoded;
+      }
       const response = await request.request(`${base}${path}`, requestOptions);
       const text = typeof response.result === 'string' ? response.result : JSON.stringify(response.result);
+      // `tls` is cumulative from request start: near zero means the connection
+      // was reused, and anything large is a handshake this call paid for alone.
+      const timing = response.performanceTiming;
+      RemoteLogger.info(`relay ${method} ${path} status=${response.responseCode} elapsed_ms=${Date.now() - startedAt}` +
+        ` dns=${Math.round(timing.dnsTiming)} tcp=${Math.round(timing.tcpTiming)}` +
+        ` tls=${Math.round(timing.tlsTiming)} ttfb=${Math.round(timing.firstReceiveTiming)}`);
       if (response.responseCode < 200 || response.responseCode >= 300) {
-        let message = `Relay login failed (HTTP ${response.responseCode}).`;
+        // The size belongs in the log: a body the relay refuses for being too
+        // big is otherwise indistinguishable from one it refuses for auth.
+        RemoteLogger.error(`relay request failed ${method} ${path} status=${response.responseCode} bytes=${bodyBytes}`);
+        let message = response.responseCode === 413 ? RemoteI18n.t('errors.payloadTooLarge') :
+          `Relay request failed (HTTP ${response.responseCode}).`;
         try {
           const error = JSON.parse(text) as RelayErrorResponse;
           if (error.error) message = error.error;
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/ConnectScanDecisionPolicy.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/ConnectScanDecisionPolicy.ets
new file mode 100644
index 0000000000..0f1f57182d
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/ConnectScanDecisionPolicy.ets
@@ -0,0 +1,54 @@
+export class DetectedUrlAction {
+  static readonly INVALID: string = 'invalid';
+  static readonly PAIR_NOW: string = 'pair_now';
+  static readonly PROMPT_ACCOUNT_PASSWORD: string = 'prompt_account_password';
+  static readonly USE_CLOUD_DEVICE: string = 'use_cloud_device';
+  static readonly SHOW_CLOUD_DEVICES: string = 'show_cloud_devices';
+}
+
+export class DetectedRemoteUrlResult {
+  readonly action: string;
+  readonly cloudDeviceId: string;
+
+  constructor(action: string, cloudDeviceId: string = '') {
+    this.action = action;
+    this.cloudDeviceId = cloudDeviceId;
+  }
+}
+
+/**
+ * What a scanned pair URL should do next. Applying the URL and starting a
+ * connect are separate steps: the detector never connects by itself.
+ *
+ * A BitFun cloud session on this phone is already the account proof. An
+ * account-auth QR for that same user must not ask for the password again;
+ * it continues through the same-account device path instead of room pairing.
+ */
+export class ConnectScanDecisionPolicy {
+  static decide(
+    accountAuth: boolean,
+    hasCloudAccountSession: boolean,
+    cloudUsername: string,
+    qrUsername: string,
+    desktopId: string
+  ): string {
+    if (!accountAuth) {
+      return DetectedUrlAction.PAIR_NOW;
+    }
+    if (hasCloudAccountSession &&
+      ConnectScanDecisionPolicy.usernamesCompatible(cloudUsername, qrUsername)) {
+      return desktopId.trim().length > 0 ?
+        DetectedUrlAction.USE_CLOUD_DEVICE :
+        DetectedUrlAction.SHOW_CLOUD_DEVICES;
+    }
+    return DetectedUrlAction.PROMPT_ACCOUNT_PASSWORD;
+  }
+
+  static usernamesCompatible(cloudUsername: string, qrUsername: string): boolean {
+    const qr = qrUsername.trim();
+    if (qr.length === 0) {
+      return true;
+    }
+    return cloudUsername.trim() === qr;
+  }
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/DeferredLoadingGate.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/DeferredLoadingGate.ets
new file mode 100644
index 0000000000..0b758bb1ab
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/DeferredLoadingGate.ets
@@ -0,0 +1,69 @@
+/**
+ * Holds a loading state back until waiting for it is something the user can
+ * actually perceive.
+ *
+ * Opening a session that is already cached needs one short read off disk, and
+ * announcing that with a full-pane skeleton costs more than it explains: the
+ * transcript is replaced by a placeholder and then by itself again, which reads
+ * as a stall rather than as speed. Below the grace period nothing is shown at
+ * all; past it the read is slow enough — a fetch over the relay, say — that
+ * silence would be the worse answer.
+ *
+ * Each `arm` supersedes the one before it, so a second tap while the first open
+ * is still settling cannot have its skeleton dismissed by the first one
+ * finishing. The token is what enforces that.
+ */
+export class DeferredLoadingGate {
+  private readonly delayMs: number;
+  private readonly onVisible: (visible: boolean) => void;
+  private timerId: number = 0;
+  private token: number = 0;
+
+  constructor(delayMs: number, onVisible: (visible: boolean) => void) {
+    this.delayMs = delayMs;
+    this.onVisible = onVisible;
+  }
+
+  /** Starts a wait. The returned token is what `release` has to be given. */
+  arm(): number {
+    this.cancelTimer();
+    this.token += 1;
+    const armed = this.token;
+    this.timerId = setTimeout(() => {
+      this.timerId = 0;
+      if (armed !== this.token) {
+        return;
+      }
+      this.onVisible(true);
+    }, this.delayMs);
+    return armed;
+  }
+
+  /** The token of the most recent `arm`, for callers keeping state beside it. */
+  currentToken(): number {
+    return this.token;
+  }
+
+  /** Ends the wait started by `token`, if it is still the current one. */
+  release(token: number): void {
+    if (token !== this.token) {
+      return;
+    }
+    this.cancelTimer();
+    this.onVisible(false);
+  }
+
+  /** Ends whatever wait is open, for teardown. */
+  reset(): void {
+    this.cancelTimer();
+    this.token += 1;
+    this.onVisible(false);
+  }
+
+  private cancelTimer(): void {
+    if (this.timerId !== 0) {
+      clearTimeout(this.timerId);
+      this.timerId = 0;
+    }
+  }
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/Encoding.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/Encoding.ets
index 610a847bf4..c4cfc3c96a 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/services/Encoding.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/Encoding.ets
@@ -2,6 +2,17 @@ import buffer from '@ohos.buffer';
 import { cryptoFramework } from '@kit.CryptoArchitectureKit';
 import util from '@ohos.util';
 
+/**
+ * Byte/text conversions on the path every relay RPC takes.
+ *
+ * These run inline on whichever thread issues the call, which for the device
+ * RPC is the UI thread, and they run over the whole request and the whole
+ * response — a transcript-sized `poll_session` reply is hundreds of kilobytes.
+ * So the cost per byte is what decides whether the frame that should be
+ * painting a skeleton gets to run at all. Everything here has to stay on a
+ * native bulk primitive; anything that touches bytes one at a time from ArkTS
+ * shows up directly as a blocked main thread.
+ */
 export class Encoding {
   static utf8ToBytes(text: string): Uint8Array {
     const value = buffer.from(text, 'utf-8');
@@ -48,12 +59,23 @@ export class Encoding {
     return JSON.parse(text) as T;
   }
 
+  /**
+   * Detaches a `Buffer` into a plain `Uint8Array` in one native copy.
+   *
+   * This used to read `value[index]` in a loop. On a `Buffer` each of those is
+   * a proxied property access rather than a typed-array load, so a
+   * transcript-sized response — hundreds of kilobytes, hundreds of thousands of
+   * reads — spent about a second of the UI thread here, inside the window where
+   * the conversation pane was meant to be painting its skeleton.
+   *
+   * `value.buffer` is already scoped to this Buffer's own bytes: measured on
+   * device, a 32-byte Buffer sitting at pool offset 856 reports a 32-byte
+   * ArrayBuffer, so the offset must not be applied to it. `util.Base64Helper`
+   * and `util.TextEncoder` would skip the Buffer entirely, but both return
+   * empty on this runtime.
+   */
   private static copyBuffer(value: buffer.Buffer): Uint8Array {
-    const copy = new Uint8Array(value.length);
-    for (let index = 0; index < value.length; index++) {
-      copy[index] = value[index];
-    }
-    return copy;
+    return new Uint8Array(value.buffer);
   }
 
   private static copyRandomData(value: Uint8Array | ArrayBuffer, expectedSize: number): Uint8Array {
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/ImagePickerService.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/ImagePickerService.ets
index 524ab49dd9..397aaa6c42 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/services/ImagePickerService.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/ImagePickerService.ets
@@ -3,6 +3,7 @@ import image from '@ohos.multimedia.image';
 import photoAccessHelper from '@ohos.file.photoAccessHelper';
 import util from '@ohos.util';
 import { RemoteI18n } from '../i18n/RemoteI18n';
+import { RemoteLogger } from './RemoteLogger';
 import { RemoteImageContext, SelectedImageAttachment } from '../model/RemoteModels';
 
 interface ImageMetadata {
@@ -24,8 +25,15 @@ interface ImageSize {
 
 export class ImagePickerService {
   private readonly maxImageBytes: number = 4 * 1024 * 1024;
+  /**
+   * What an image is allowed to weigh on the wire. A picture travels as base64
+   * inside an encrypted, base64-wrapped command, so it reaches the relay at
+   * roughly 1.8× its byte size — a budget in the hundreds of KB is what keeps a
+   * phone photo inside a request the relay will accept.
+   */
+  private readonly transportImageBudgetBytes: number = 800 * 1024;
   private readonly maxImageDimension: number = 1600;
-  private readonly compressionQualities: number[] = [82, 72, 62];
+  private readonly compressionQualities: number[] = [82, 72, 62, 50];
 
   async pickImages(maxCount: number, existingCount: number): Promise<SelectedImageAttachment[]> {
     const remaining = Math.max(0, maxCount - existingCount);
@@ -74,6 +82,7 @@ export class ImagePickerService {
 
     const base64 = new util.Base64Helper().encodeToStringSync(encoded.bytes);
     const name = this.imageName(uri, index);
+    RemoteLogger.info(`image picked original=${stat.size} encoded=${encoded.bytes.length} compressed=${encoded.compressed ? '1' : '0'} mime=${encoded.mimeType}`);
     return {
       id: `harmony-image-${Date.now()}-${index}`,
       uri,
@@ -87,7 +96,7 @@ export class ImagePickerService {
   }
 
   private async encodeImage(uri: string, originalSize: number): Promise<EncodedImage> {
-    if (originalSize <= this.maxImageBytes) {
+    if (originalSize <= this.transportImageBudgetBytes) {
       return this.readOriginalImage(uri, originalSize);
     }
 
@@ -140,7 +149,7 @@ export class ImagePickerService {
         });
         const bytes = new Uint8Array(packed);
         bestBytes = bytes;
-        if (bytes.length <= this.maxImageBytes) {
+        if (bytes.length <= this.transportImageBudgetBytes) {
           return {
             bytes,
             mimeType: 'image/jpeg',
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/MainThreadStallProbe.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/MainThreadStallProbe.ets
new file mode 100644
index 0000000000..c0c5a6f66f
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/MainThreadStallProbe.ets
@@ -0,0 +1,58 @@
+import { RemoteLogger } from './RemoteLogger';
+
+const TICK_MS = 250;
+const REPORT_THRESHOLD_MS = 400;
+
+/**
+ * Tells a blocked main thread apart from a deferred frame.
+ *
+ * A fixed-interval timer whose own lateness is the measurement: the tick is
+ * trivial, so anything it arrives late by was spent by somebody else holding
+ * the JS thread. Without this, a log line that lands 1.6s after the state
+ * write behind it reads the same either way — the thread was busy, or ArkUI
+ * simply had not painted yet — and those two want opposite fixes.
+ *
+ * Armed for a window rather than left running, so nothing pays 4Hz for a
+ * measurement that only matters around an event someone asked about.
+ */
+export class MainThreadStallProbe {
+  private static timerId: number = 0;
+  private static deadline: number = 0;
+  private static expectedAt: number = 0;
+  private static reason: string = '';
+
+  /** Watches for `windowMs`, restarting the window if one is already open. */
+  static watch(reason: string, windowMs: number): void {
+    MainThreadStallProbe.reason = reason;
+    MainThreadStallProbe.deadline = Date.now() + windowMs;
+    if (MainThreadStallProbe.timerId !== 0) {
+      return;
+    }
+    MainThreadStallProbe.arm();
+  }
+
+  static stop(): void {
+    if (MainThreadStallProbe.timerId !== 0) {
+      clearTimeout(MainThreadStallProbe.timerId);
+      MainThreadStallProbe.timerId = 0;
+    }
+    MainThreadStallProbe.deadline = 0;
+  }
+
+  private static arm(): void {
+    MainThreadStallProbe.expectedAt = Date.now() + TICK_MS;
+    MainThreadStallProbe.timerId = setTimeout(() => {
+      MainThreadStallProbe.timerId = 0;
+      const now = Date.now();
+      const late = now - MainThreadStallProbe.expectedAt;
+      if (late >= REPORT_THRESHOLD_MS) {
+        RemoteLogger.info(`main thread stall reason=${MainThreadStallProbe.reason} blocked_ms=${late}`);
+      }
+      if (now >= MainThreadStallProbe.deadline) {
+        MainThreadStallProbe.deadline = 0;
+        return;
+      }
+      MainThreadStallProbe.arm();
+    }, TICK_MS);
+  }
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/RelayHttpClient.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/RelayHttpClient.ets
index ee48ae293d..9fc50aed1d 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/services/RelayHttpClient.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/RelayHttpClient.ets
@@ -1,14 +1,36 @@
 import { http } from '@kit.NetworkKit';
 import { RemoteI18n } from '../i18n/RemoteI18n';
+import { RemoteCommandFactory } from './RemoteCommandFactory';
 import { RemoteCrypto } from './RemoteCrypto';
 import { RemoteLogger } from './RemoteLogger';
-import { ChallengeCommand, CommandStatusResponse, DelegatedIdentityResponse, EncryptedPayload, InitialSyncResponse, PairChallengeResponse, PairRequest, RemoteCommand, RemoteDescriptor } from '../model/RemoteModels';
+import { ChallengeCommand, CommandStatusResponse, DelegatedIdentityResponse, EncryptedPayload, InitialSyncResponse, PairChallengeResponse, PairRequest, PeerDeviceProvisionedResponse, RemoteCommand, RemoteDescriptor } from '../model/RemoteModels';
 
 export interface PairIdentity {
   userId: string;
   password?: string;
 }
 
+/**
+ * Result of a `provision_peer_device` round trip, reported rather than thrown
+ * because the caller has to tell two failures apart and an `Error` cannot
+ * carry that distinction back through the transport's error collapsing.
+ *
+ * `desktopReported` means the desktop answered and refused, and its message is
+ * worth showing verbatim. Everything else — no answer at all — covers both a
+ * desktop that is offline and a desktop too old to know the command: an older
+ * build decrypts the payload, fails to deserialize the unknown variant, and
+ * replies with nothing, which on this side is indistinguishable from silence.
+ */
+export interface PeerDeviceProvisionOutcome {
+  ok: boolean;
+  token: string;
+  userId: string;
+  masterKeyBase64: string;
+  deviceId: string;
+  failure: string;
+  desktopReported: boolean;
+}
+
 export class RelayHttpClient {
   private descriptor?: RemoteDescriptor;
   private crypto?: RemoteCrypto;
@@ -95,6 +117,60 @@ export class RelayHttpClient {
     return false;
   }
 
+  /**
+   * Mint a full account device credential for a device that cannot type a
+   * password. Pinned to the room channel on purpose: only the desktop's room
+   * loop holds the trusted pairing identity that authorizes provisioning, so
+   * the account-device transport would answer "not available on this host".
+   */
+  async provisionPeerDevice(
+    deviceId: string,
+    deviceName: string,
+    requestId: string,
+    readTimeoutMs: number = 45000
+  ): Promise<PeerDeviceProvisionOutcome> {
+    const command: RemoteCommand = RemoteCommandFactory.provisionPeerDevice(deviceId, deviceName, requestId);
+    command._request_id = `req_provision_${requestId}`;
+    let response: PeerDeviceProvisionedResponse;
+    try {
+      response = await this.sendCommand<PeerDeviceProvisionedResponse>(command, readTimeoutMs, false);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : JSON.stringify(err);
+      RemoteLogger.error(`provision peer device transport failure: ${message}`);
+      return RelayHttpClient.provisionFailure(message, false);
+    }
+    if (response.resp === 'error') {
+      return RelayHttpClient.provisionFailure(response.message || '', true);
+    }
+    const token = response.token || '';
+    const userId = response.user_id || '';
+    const masterKey = response.master_key || '';
+    const provisionedDeviceId = response.device_id || '';
+    if (response.resp !== 'peer_device_provisioned' || token.length === 0 || userId.length === 0 ||
+      masterKey.length === 0) {
+      // A well-formed reply that is missing the credential is a desktop we do
+      // not understand, not a desktop that refused. Treat it as silence.
+      RemoteLogger.error(`provision peer device unexpected response resp=${response.resp || 'unknown'}`);
+      return RelayHttpClient.provisionFailure('', false);
+    }
+    if (provisionedDeviceId !== deviceId) {
+      // The desktop already checks this, so reaching here means the reply did
+      // not come from the desktop we asked. Refuse rather than hand the watch
+      // a credential minted for some other device.
+      RemoteLogger.error('provision peer device returned a mismatched device id');
+      return RelayHttpClient.provisionFailure('', false);
+    }
+    return {
+      ok: true,
+      token,
+      userId,
+      masterKeyBase64: masterKey,
+      deviceId: provisionedDeviceId,
+      failure: '',
+      desktopReported: false
+    };
+  }
+
   clearDelegatedIdentity(): void {
     this.delegatedToken = '';
     this.delegatedMasterKey = '';
@@ -105,7 +181,11 @@ export class RelayHttpClient {
     return this.delegatedToken.length > 0 && this.delegatedMasterKey.length > 0;
   }
 
-  async sendCommand<T extends CommandStatusResponse>(command: RemoteCommand, readTimeoutMs: number = 30000): Promise<T> {
+  async sendCommand<T extends CommandStatusResponse>(
+    command: RemoteCommand,
+    readTimeoutMs: number = 30000,
+    throwOnRemoteError: boolean = true
+  ): Promise<T> {
     const descriptor = this.requireDescriptor();
     const crypto = this.requireCrypto();
     const commandName = command.cmd || 'unknown';
@@ -134,7 +214,10 @@ export class RelayHttpClient {
       RemoteLogger.info(`command decrypt done cmd=${commandName} request=${requestId} resp=${response.resp || 'unknown'} ms=${Date.now() - decryptStartedAt}`);
       if (response.resp === 'error') {
         RemoteLogger.error(`command remote error cmd=${commandName} request=${requestId} message=${response.message || 'unknown'}`);
-        throw new Error(response.message || 'Remote command failed.');
+        if (throwOnRemoteError) {
+          throw new Error(response.message || 'Remote command failed.');
+        }
+        return response;
       }
       RemoteLogger.info(`command complete cmd=${commandName} request=${requestId} ms=${Date.now() - startedAt}`);
       return response;
@@ -230,6 +313,18 @@ export class RelayHttpClient {
     return this.crypto;
   }
 
+  private static provisionFailure(message: string, desktopReported: boolean): PeerDeviceProvisionOutcome {
+    return {
+      ok: false,
+      token: '',
+      userId: '',
+      masterKeyBase64: '',
+      deviceId: '',
+      failure: message,
+      desktopReported
+    };
+  }
+
   private static shortRequestId(requestId: string): string {
     if (requestId.length === 0) {
       return 'none';
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteActivityLifecycleController.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteActivityLifecycleController.ets
index 9a3382f119..d26fb88e5e 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteActivityLifecycleController.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteActivityLifecycleController.ets
@@ -4,7 +4,7 @@ export class RemoteActivityLifecycleController {
   private readonly heartbeatController: RemoteHeartbeatController;
 
   constructor(
-    onHeartbeatTick: () => void,
+    onHeartbeatTick: () => Promise<void>,
     heartbeatIntervalMs: number = 15000,
     heartbeatScheduler?: RemoteHeartbeatScheduler
   ) {
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteChatCache.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteChatCache.ets
new file mode 100644
index 0000000000..dac8913ddc
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteChatCache.ets
@@ -0,0 +1,276 @@
+import { ChatMessage } from '../model/RemoteModels';
+import { RemoteLogger } from './RemoteLogger';
+
+/**
+ * One session's cached transcript, as it was last written.
+ *
+ * `lastMessageId` is what makes an append safe: the desktop hands out message
+ * tails by index (`poll_session` skips `known_msg_count` entries), so a cached
+ * prefix that no longer matches the desktop's would silently splice two
+ * different transcripts together.
+ */
+export interface RemoteChatCacheSlice {
+  messages: ChatMessage[];
+  lastMessageId: string;
+}
+
+/** Storage behind [RemoteChatCache]; see `RemoteChatLocalRdbStore`. */
+export interface RemoteChatCacheStore {
+  init(context: Context): Promise<void>;
+  loadSlice(deviceKey: string, sessionId: string): Promise<RemoteChatCacheSlice>;
+  appendMessages(
+    deviceKey: string,
+    sessionId: string,
+    startSeq: number,
+    messages: ChatMessage[],
+    lastMessageId: string
+  ): Promise<void>;
+  replaceMessages(
+    deviceKey: string,
+    sessionId: string,
+    messages: ChatMessage[],
+    lastMessageId: string
+  ): Promise<void>;
+  deleteSession(deviceKey: string, sessionId: string): Promise<void>;
+  pruneSessions(deviceKey: string, keepMostRecent: number): Promise<void>;
+  clearAll(): Promise<void>;
+}
+
+/**
+ * How many sessions per desktop keep a cached transcript.
+ *
+ * The list a phone actually revisits is short, and every session past that is
+ * disk spent on a transcript the user will re-fetch anyway. Past the budget the
+ * least recently opened transcript goes first, and opening counts as reading —
+ * so a session the user keeps coming back to outlives any number of one-off
+ * ones opened around it.
+ */
+const CACHED_SESSIONS_PER_DEVICE: number = 20;
+
+/**
+ * How many transcripts stay in memory in front of the disk ones.
+ *
+ * Three covers what the phone actually alternates between — the session being
+ * worked in, the one before it, and whatever was glanced at in between — and
+ * costs nothing on disk. Past that the read off disk is already fast enough
+ * that holding more would be spending memory to save nothing.
+ */
+const RESIDENT_SESSIONS: number = 3;
+
+/**
+ * On-disk transcripts, so reopening a session renders before the network answers.
+ *
+ * Everything here is reconstructible from the desktop, which is what lets every
+ * method swallow its own failures: a cache that cannot be read or written makes
+ * the app as slow as it was before the cache existed, and nothing worse. The
+ * one thing it must never do is serve a transcript that is missing messages out
+ * of the middle, so any doubt about a stored prefix is resolved by reporting a
+ * miss.
+ *
+ * Entries are scoped per desktop: `session_id` is issued by the desktop that
+ * owns the session, so two desktops on one account can hand out the same id for
+ * different conversations.
+ */
+export class RemoteChatCache {
+  private readonly store: RemoteChatCacheStore;
+  private readonly deviceKeyProvider: () => string;
+  private ready: boolean = false;
+  // Write cursor for the session on screen, so a poll tick costs one append
+  // rather than a read followed by an append.
+  private trackedScope: string = '';
+  private trackedCount: number = 0;
+  private trackedLastMessageId: string = '';
+  // Transcripts held in memory, most recently used last.
+  //
+  // Only ever populated from a disk read that succeeded or a disk write that
+  // succeeded, so a resident copy can never claim more messages than the store
+  // actually holds — which is what lets a resident hit set the append cursor
+  // instead of forcing the next sync to rewrite the session.
+  private readonly resident: Map<string, RemoteChatCacheSlice> = new Map<string, RemoteChatCacheSlice>();
+  private residentOrder: string[] = [];
+
+  constructor(store: RemoteChatCacheStore, deviceKeyProvider: () => string) {
+    this.store = store;
+    this.deviceKeyProvider = deviceKeyProvider;
+  }
+
+  async init(context: Context): Promise<void> {
+    try {
+      await this.store.init(context);
+      this.ready = true;
+    } catch (err) {
+      RemoteLogger.error(`remote chat cache unavailable: ${RemoteChatCache.reason(err)}`);
+    }
+  }
+
+  /** The cached transcript for [sessionId], or an empty list on any miss. */
+  async load(sessionId: string): Promise<ChatMessage[]> {
+    const scope = this.scope(sessionId);
+    if (scope.length === 0) {
+      return [];
+    }
+    const resident = this.resident.get(scope);
+    if (resident !== undefined) {
+      this.touchResident(scope);
+      this.track(scope, resident.messages.length, resident.lastMessageId);
+      RemoteLogger.info(`remote chat cache resident hit count=${resident.messages.length}`);
+      return resident.messages.slice();
+    }
+    try {
+      const slice = await this.store.loadSlice(this.deviceKeyProvider(), sessionId);
+      this.track(scope, slice.messages.length, slice.lastMessageId);
+      if (slice.messages.length > 0) {
+        this.remember(scope, slice.messages, slice.lastMessageId);
+      }
+      return slice.messages;
+    } catch (err) {
+      this.forgetCursor();
+      this.evictResident(scope);
+      RemoteLogger.error(`remote chat cache read failed: ${RemoteChatCache.reason(err)}`);
+      return [];
+    }
+  }
+
+  /**
+   * Brings the stored transcript in line with what the timeline now holds.
+   *
+   * Appends when the stored rows are still a prefix of [persistedMessages] and
+   * rewrites the session otherwise — a poll tick adds a handful of messages to
+   * a transcript that can hold hundreds, and rewriting all of them every few
+   * hundred milliseconds is the one way this cache could cost more than it saves.
+   */
+  async sync(sessionId: string, persistedMessages: ChatMessage[]): Promise<void> {
+    const scope = this.scope(sessionId);
+    if (scope.length === 0 || persistedMessages.length === 0) {
+      return;
+    }
+    const lastMessageId = persistedMessages[persistedMessages.length - 1].id;
+    try {
+      if (this.canAppendTo(scope, persistedMessages)) {
+        if (persistedMessages.length === this.trackedCount) {
+          return;
+        }
+        await this.store.appendMessages(
+          this.deviceKeyProvider(),
+          sessionId,
+          this.trackedCount,
+          persistedMessages.slice(this.trackedCount),
+          lastMessageId
+        );
+      } else {
+        await this.store.replaceMessages(
+          this.deviceKeyProvider(),
+          sessionId,
+          persistedMessages,
+          lastMessageId
+        );
+        // Only a rewrite can bring a session into the cache that was not
+        // already there, so this is the one branch eviction has anything to do:
+        // a poll tick appending to a stored session leaves the count where it
+        // was, and paying for a prune on every tick would be pure overhead.
+        await this.store.pruneSessions(this.deviceKeyProvider(), CACHED_SESSIONS_PER_DEVICE);
+      }
+      this.track(scope, persistedMessages.length, lastMessageId);
+      this.remember(scope, persistedMessages, lastMessageId);
+    } catch (err) {
+      // Dropping the cursor turns the next sync into a rewrite, which is the
+      // only safe assumption once a write outcome is unknown. The resident copy
+      // goes with it: what it holds was true of a store this write may have
+      // moved out from under it.
+      this.forgetCursor();
+      this.evictResident(scope);
+      RemoteLogger.error(`remote chat cache write failed: ${RemoteChatCache.reason(err)}`);
+    }
+  }
+
+  /** Drops one session, for a delete or a transcript the desktop rewrote. */
+  async forget(sessionId: string): Promise<void> {
+    const scope = this.scope(sessionId);
+    if (scope.length === 0) {
+      return;
+    }
+    if (scope === this.trackedScope) {
+      this.forgetCursor();
+    }
+    this.evictResident(scope);
+    try {
+      await this.store.deleteSession(this.deviceKeyProvider(), sessionId);
+    } catch (err) {
+      RemoteLogger.error(`remote chat cache evict failed: ${RemoteChatCache.reason(err)}`);
+    }
+  }
+
+  /**
+   * Drops every cached transcript, for signing out.
+   *
+   * Transcripts belong to the account that was signed in; leaving them on disk
+   * for the next account to read is the one failure mode worth being loud about.
+   */
+  async clear(): Promise<void> {
+    this.forgetCursor();
+    this.resident.clear();
+    this.residentOrder = [];
+    if (!this.ready) {
+      return;
+    }
+    try {
+      await this.store.clearAll();
+    } catch (err) {
+      RemoteLogger.error(`remote chat cache clear failed: ${RemoteChatCache.reason(err)}`);
+    }
+  }
+
+  private canAppendTo(scope: string, persistedMessages: ChatMessage[]): boolean {
+    return this.trackedScope === scope &&
+      this.trackedCount > 0 &&
+      this.trackedCount <= persistedMessages.length &&
+      persistedMessages[this.trackedCount - 1].id === this.trackedLastMessageId;
+  }
+
+  private track(scope: string, count: number, lastMessageId: string): void {
+    this.trackedScope = scope;
+    this.trackedCount = count;
+    this.trackedLastMessageId = lastMessageId;
+  }
+
+  private forgetCursor(): void {
+    this.trackedScope = '';
+    this.trackedCount = 0;
+    this.trackedLastMessageId = '';
+  }
+
+  /** Takes a copy: the caller's array outlives this call and the timeline edits it. */
+  private remember(scope: string, messages: ChatMessage[], lastMessageId: string): void {
+    this.resident.set(scope, { messages: messages.slice(), lastMessageId });
+    this.touchResident(scope);
+    while (this.residentOrder.length > RESIDENT_SESSIONS) {
+      const oldest = this.residentOrder.shift();
+      if (oldest !== undefined) {
+        this.resident.delete(oldest);
+      }
+    }
+  }
+
+  private touchResident(scope: string): void {
+    this.residentOrder = this.residentOrder.filter((entry: string): boolean => entry !== scope);
+    this.residentOrder.push(scope);
+  }
+
+  private evictResident(scope: string): void {
+    this.resident.delete(scope);
+    this.residentOrder = this.residentOrder.filter((entry: string): boolean => entry !== scope);
+  }
+
+  /** Cache key for a session, or '' when there is nothing safe to key on. */
+  private scope(sessionId: string): string {
+    const deviceKey = this.deviceKeyProvider().trim();
+    if (!this.ready || deviceKey.length === 0 || sessionId.length === 0) {
+      return '';
+    }
+    return `${deviceKey}::${sessionId}`;
+  }
+
+  private static reason(err: Object): string {
+    return err instanceof Error ? err.message : `${err}`;
+  }
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteChatCommandController.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteChatCommandController.ets
index 4791ede63a..dc1d234f43 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteChatCommandController.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteChatCommandController.ets
@@ -7,6 +7,9 @@ import {
 } from '../model/RemoteModels';
 import { RemoteI18n } from '../i18n/RemoteI18n';
 import { ConnectionErrorPolicy } from './ConnectionErrorPolicy';
+import { RemoteChatCache } from './RemoteChatCache';
+import { RemoteLogger } from './RemoteLogger';
+import { TranscriptIntegrityPolicy } from './TranscriptIntegrityPolicy';
 
 export interface RemoteChatCommandClient {
   getSessionMessages(sessionId: string): Promise<SessionMessagesResult>;
@@ -24,6 +27,10 @@ export interface RemoteChatCommandClient {
 export interface RemoteChatCommandCallbacks {
   onMessagesLoaded: (messages: ChatMessage[], hasMoreMessages: boolean) => void;
   onMessageCountKnown: (pollVersion: number, knownMessageCount: number) => void;
+  // Raised once the transcript is on screen, which for a cached session is
+  // before any request has been sent. Without it the loading skeleton would
+  // outlive the messages it is standing in for.
+  onTimelineReady: () => void;
   onSendSucceeded: (turnId: string, pendingActiveId: string) => void;
   onSendFailed: (
     rawText: string,
@@ -34,6 +41,9 @@ export interface RemoteChatCommandCallbacks {
   onActiveSession: (session: SessionSummary) => void;
   onSessionTitleChanged: (sessionId: string, title: string) => void;
   onStatusText: (statusText: string) => void;
+  // The status line is only rendered while the link is down, so anything the
+  // user asked for and did not get has to be said out loud instead.
+  onToast: (message: string) => void;
   onBusy: (isBusy: boolean) => void;
   onPollRequested: () => void;
 }
@@ -41,34 +51,160 @@ export interface RemoteChatCommandCallbacks {
 export class RemoteChatCommandController {
   private readonly client: RemoteChatCommandClient;
   private readonly callbacks: RemoteChatCommandCallbacks;
+  private readonly cache: RemoteChatCache;
 
-  constructor(client: RemoteChatCommandClient, callbacks: RemoteChatCommandCallbacks) {
+  constructor(
+    client: RemoteChatCommandClient,
+    callbacks: RemoteChatCommandCallbacks,
+    cache: RemoteChatCache
+  ) {
     this.client = client;
     this.callbacks = callbacks;
+    this.cache = cache;
   }
 
+  private static shortId(value: string): string {
+    if (value.length <= 10) return value;
+    return `${value.slice(0, 6)}...${value.slice(-4)}`;
+  }
+
+  /**
+   * Puts a session's transcript on screen, from disk when there is one.
+   *
+   * A cache hit with complete rows sends nothing: the poller that starts right
+   * after this asks for `known_msg_count` messages onwards, so whatever arrived
+   * while the session was closed comes back as an ordinary tail rather than as
+   * another copy of the whole transcript.
+   *
+   * Hollow assistants are a miss. The poller will not refill them — it skips
+   * the rows the phone already counted — so the only way back to a body is a
+   * full `get_session_messages`. The hollow rows still go on screen first so
+   * the user messages do not wait on that fetch.
+   */
   async loadMessages(
     sessionId: string,
     canApply: (sessionId: string) => boolean
+  ): Promise<void> {
+    if (sessionId.length === 0) {
+      return;
+    }
+    const cached = await this.cache.load(sessionId);
+    if (cached.length > 0) {
+      if (!canApply(sessionId)) {
+        return;
+      }
+      RemoteLogger.info(`messages from cache session=${RemoteChatCommandController.shortId(sessionId)} count=${cached.length}`);
+      this.applyMessages(cached);
+      if (TranscriptIntegrityPolicy.hasHollowAssistants(cached)) {
+        RemoteLogger.info(
+          `hollow assistants in cache session=${RemoteChatCommandController.shortId(sessionId)} ` +
+            `${TranscriptIntegrityPolicy.describeMessages(cached)}`
+        );
+        await this.cache.forget(sessionId);
+        await this.reloadMessages(sessionId, canApply);
+        return;
+      }
+      this.callbacks.onStatusText(RemoteI18n.t('status.messagesRestored'));
+      return;
+    }
+    await this.reloadMessages(sessionId, canApply);
+  }
+
+  /**
+   * Fetches the whole transcript and makes it the cached one.
+   *
+   * Also the way out of a desktop-side rewrite: the tail protocol counts from
+   * the start of the transcript, so once the desktop reports fewer messages
+   * than the phone holds there is no offset left to resume from.
+   */
+  async reloadMessages(
+    sessionId: string,
+    canApply: (sessionId: string) => boolean
   ): Promise<void> {
     if (sessionId.length === 0) {
       return;
     }
     try {
-      this.callbacks.onStatusText(RemoteI18n.t('status.loadMessages'));
+      // Guarded like every other write below. A tap that lands while a disk read
+      // is still settling gets here for a session that is already off screen,
+      // and "正在加载消息" against someone else's transcript reads as a stall the
+      // visible session is not having.
+      if (canApply(sessionId)) {
+        this.callbacks.onStatusText(RemoteI18n.t('status.loadMessages'));
+      }
       const result = await this.client.getSessionMessages(sessionId);
+      RemoteLogger.info(
+        `get_session_messages mapped session=${RemoteChatCommandController.shortId(sessionId)} ` +
+          `${TranscriptIntegrityPolicy.describeMessages(result.messages)}`
+      );
+      if (canApply(sessionId)) {
+        this.applyMessages(result.messages);
+        this.callbacks.onStatusText(RemoteI18n.t('status.messagesSynced'));
+      }
+      // Stored whether or not that session is still the one on screen: the
+      // transcript was fetched by session id, so it is as valid for a session
+      // the user just switched away from as for one they stayed on. Discarding
+      // it would leave a session the user demonstrably opened uncached, and a
+      // fetch slow enough to be switched away from is exactly the one worth not
+      // paying for twice.
+      //
+      // Writing another session's transcript moves the cache's append cursor
+      // off the visible one, which costs that session a single full rewrite on
+      // its next sync before appends resume.
+      await this.cache.sync(sessionId, result.messages);
+    } catch (err) {
+      // A failure belongs to the session it was fetched for. Unguarded, a slow
+      // fetch the user switched away from would land its error text and its
+      // empty timeline on whatever session they switched to — the failure of
+      // the session they left, reported as the state of the one they are on.
       if (!canApply(sessionId)) {
+        RemoteLogger.info(
+          `stale message load dropped session=${RemoteChatCommandController.shortId(sessionId)}`);
         return;
       }
-      this.callbacks.onMessagesLoaded(result.messages, false);
-      this.callbacks.onMessageCountKnown(0, result.messages.length);
-      this.callbacks.onStatusText(RemoteI18n.t('status.messagesSynced'));
-    } catch (err) {
       this.callbacks.onStatusText(ConnectionErrorPolicy.errorText(err));
       this.callbacks.onMessageCountKnown(0, 0);
+      this.callbacks.onTimelineReady();
     }
   }
 
+  /**
+   * A poll version of 0 is deliberate on both paths: the desktop resets its
+   * tracker when it restarts, so a version carried over from a previous
+   * connection would match by accident and answer "nothing changed".
+   *
+   * The count handed on is the message count, which for a restored transcript
+   * can sit below what the desktop counts, because the timeline drops synthetic
+   * system entries. Erring low is the safe direction: the next poll returns a
+   * few messages already on screen, they merge by id, and the count corrects
+   * itself from the desktop's own total.
+   */
+  private applyMessages(messages: ChatMessage[]): void {
+    this.callbacks.onMessagesLoaded(messages, false);
+    this.callbacks.onMessageCountKnown(0, messages.length);
+    this.callbacks.onTimelineReady();
+    // The last thing that happens before ArkUI owns the delay: everything after
+    // this line is build, measure and paint.
+    RemoteLogger.info(
+      `messages applied to state ${TranscriptIntegrityPolicy.describeMessages(messages)}`
+    );
+  }
+
+  /** Drops a session's cached transcript once it no longer exists upstream. */
+  async forgetMessages(sessionId: string): Promise<void> {
+    await this.cache.forget(sessionId);
+  }
+
+  /**
+   * Reaches back for history the timeline is missing.
+   *
+   * No desktop reachable over the relay reports one today: `get_session_messages`
+   * ignores its `limit`/`before_message_id` and answers with the whole
+   * transcript and `has_more: false`, so `hasMoreMessages` never turns true and
+   * this stays a fetch nothing currently asks for. It is kept whole, and kept
+   * writing to the cache like every other full fetch, so that the day the
+   * desktop does page its history this path is not the odd one out.
+   */
   async loadOlderMessages(
     sessionId: string,
     currentPollVersion: number,
@@ -85,6 +221,7 @@ export class RemoteChatCommandController {
       this.callbacks.onMessagesLoaded(result.messages, false);
       this.callbacks.onMessageCountKnown(currentPollVersion, result.messages.length);
       this.callbacks.onStatusText(RemoteI18n.t('status.messagesSynced'));
+      await this.cache.sync(sessionId, result.messages);
     } catch (err) {
       this.callbacks.onStatusText(ConnectionErrorPolicy.errorText(err));
     } finally {
@@ -129,20 +266,29 @@ export class RemoteChatCommandController {
     activeTurnId: string,
     remoteAvailable: boolean
   ): Promise<void> {
+    RemoteLogger.info(`stop task requested session=${RemoteChatCommandController.shortId(sessionId)} turn=${RemoteChatCommandController.shortId(activeTurnId)} active=${activeTurnMessageId.length > 0 ? '1' : '0'}`);
     if (sessionId.length === 0 || !remoteAvailable) {
       return;
     }
     if (activeTurnMessageId.length === 0) {
-      this.callbacks.onStatusText(RemoteI18n.t('status.noRunningTask'));
+      const nothingRunning = RemoteI18n.t('status.noRunningTask');
+      this.callbacks.onStatusText(nothingRunning);
+      this.callbacks.onToast(nothingRunning);
       return;
     }
     try {
       this.callbacks.onStatusText(RemoteI18n.t('status.stoppingTask'));
       await this.client.cancelTask(sessionId, activeTurnId);
+      RemoteLogger.info(`stop task accepted session=${RemoteChatCommandController.shortId(sessionId)} turn=${RemoteChatCommandController.shortId(activeTurnId)}`);
       this.callbacks.onStatusText(RemoteI18n.t('status.stopRequested'));
       this.callbacks.onPollRequested();
     } catch (err) {
-      this.callbacks.onStatusText(ConnectionErrorPolicy.errorText(err));
+      // A rejected cancel leaves the task running, so failing quietly here is
+      // indistinguishable from the stop having worked.
+      const errorText = ConnectionErrorPolicy.errorText(err);
+      RemoteLogger.info(`stop task failed session=${RemoteChatCommandController.shortId(sessionId)} turn=${RemoteChatCommandController.shortId(activeTurnId)}`);
+      this.callbacks.onStatusText(errorText);
+      this.callbacks.onToast(errorText);
     }
   }
 
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteChatLocalRdbStore.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteChatLocalRdbStore.ets
new file mode 100644
index 0000000000..dca1cbd250
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteChatLocalRdbStore.ets
@@ -0,0 +1,243 @@
+import { relationalStore } from '@kit.ArkData';
+import { ChatMessage } from '../model/RemoteModels';
+import { Encoding } from './Encoding';
+import { RemoteChatCacheSlice, RemoteChatCacheStore } from './RemoteChatCache';
+
+const STORE_CONFIG: relationalStore.StoreConfig = {
+  name: 'bitfun_remote_chat.db',
+  // A step above the S1 the general-chat store uses: these transcripts carry
+  // the user's source, file paths and terminal output from a machine they own.
+  securityLevel: relationalStore.SecurityLevel.S2
+};
+
+/**
+ * Bumped whenever a stored row stops meaning what it used to.
+ *
+ * A cache is reconstructible by definition, so a mismatch drops the tables and
+ * refills them from the desktop instead of paying for a migration.
+ */
+const SCHEMA_VERSION: number = 1;
+const SCHEMA_VERSION_KEY: string = 'schema_version';
+
+const CREATE_META_SQL =
+  'CREATE TABLE IF NOT EXISTS remote_chat_meta (' +
+  'key TEXT PRIMARY KEY, value TEXT NOT NULL)';
+const CREATE_SESSIONS_SQL =
+  'CREATE TABLE IF NOT EXISTS remote_chat_sessions (' +
+  'device_key TEXT NOT NULL, session_id TEXT NOT NULL, message_count INTEGER NOT NULL, ' +
+  'last_message_id TEXT NOT NULL, updated_at INTEGER NOT NULL, ' +
+  'PRIMARY KEY (device_key, session_id))';
+// `seq` is the message's index in the desktop's own list, not an arbitrary sort
+// key: `poll_session` returns the tail after `known_msg_count` entries, so the
+// two have to count the same things in the same order.
+const CREATE_MESSAGES_SQL =
+  'CREATE TABLE IF NOT EXISTS remote_chat_messages (' +
+  'device_key TEXT NOT NULL, session_id TEXT NOT NULL, seq INTEGER NOT NULL, payload TEXT NOT NULL, ' +
+  'PRIMARY KEY (device_key, session_id, seq))';
+
+/** Remote transcripts on disk, keyed by the desktop that owns the session. */
+export class RemoteChatLocalRdbStore implements RemoteChatCacheStore {
+  private store?: relationalStore.RdbStore;
+
+  async init(context: Context): Promise<void> {
+    const store = await relationalStore.getRdbStore(context, STORE_CONFIG);
+    await store.executeSql(CREATE_META_SQL);
+    if (await RemoteChatLocalRdbStore.storedSchemaVersion(store) !== SCHEMA_VERSION) {
+      await store.executeSql('DROP TABLE IF EXISTS remote_chat_messages');
+      await store.executeSql('DROP TABLE IF EXISTS remote_chat_sessions');
+      await store.executeSql(
+        'INSERT OR REPLACE INTO remote_chat_meta (key, value) VALUES (?, ?)',
+        [SCHEMA_VERSION_KEY, `${SCHEMA_VERSION}`]
+      );
+    }
+    await store.executeSql(CREATE_SESSIONS_SQL);
+    await store.executeSql(CREATE_MESSAGES_SQL);
+    this.store = store;
+  }
+
+  async loadSlice(deviceKey: string, sessionId: string): Promise<RemoteChatCacheSlice> {
+    const store = this.requireStore();
+    let expectedCount = 0;
+    let lastMessageId = '';
+    const header = await store.querySql(
+      'SELECT message_count, last_message_id FROM remote_chat_sessions ' +
+      'WHERE device_key = ? AND session_id = ?',
+      [deviceKey, sessionId]
+    );
+    try {
+      if (header.goToNextRow()) {
+        expectedCount = header.getLong(header.getColumnIndex('message_count'));
+        lastMessageId = header.getString(header.getColumnIndex('last_message_id'));
+      }
+    } finally {
+      header.close();
+    }
+    if (expectedCount <= 0) {
+      return { messages: [], lastMessageId: '' };
+    }
+
+    const messages: ChatMessage[] = [];
+    const rows = await store.querySql(
+      'SELECT payload FROM remote_chat_messages ' +
+      'WHERE device_key = ? AND session_id = ? AND seq < ? ORDER BY seq ASC',
+      [deviceKey, sessionId, expectedCount]
+    );
+    try {
+      const payloadColumn = rows.getColumnIndex('payload');
+      while (rows.goToNextRow()) {
+        messages.push(Encoding.parseJsonObject<ChatMessage>(rows.getString(payloadColumn)));
+      }
+    } finally {
+      rows.close();
+    }
+    // Fewer rows than the header claims means a write was interrupted partway.
+    // Reporting a miss costs one fetch; reporting the rows would show the user
+    // a transcript with messages missing out of the middle.
+    if (messages.length !== expectedCount) {
+      return { messages: [], lastMessageId: '' };
+    }
+    await this.touchSession(deviceKey, sessionId);
+    return { messages, lastMessageId };
+  }
+
+  async appendMessages(
+    deviceKey: string,
+    sessionId: string,
+    startSeq: number,
+    messages: ChatMessage[],
+    lastMessageId: string
+  ): Promise<void> {
+    if (messages.length === 0) {
+      return;
+    }
+    const store = this.requireStore();
+    // Clearing the range first makes a retried append idempotent, which is what
+    // lets the write run without a transaction around it.
+    await store.executeSql(
+      'DELETE FROM remote_chat_messages WHERE device_key = ? AND session_id = ? AND seq >= ?',
+      [deviceKey, sessionId, startSeq]
+    );
+    await store.batchInsert(
+      'remote_chat_messages',
+      RemoteChatLocalRdbStore.rows(deviceKey, sessionId, startSeq, messages)
+    );
+    await this.writeHeader(deviceKey, sessionId, startSeq + messages.length, lastMessageId);
+  }
+
+  async replaceMessages(
+    deviceKey: string,
+    sessionId: string,
+    messages: ChatMessage[],
+    lastMessageId: string
+  ): Promise<void> {
+    const store = this.requireStore();
+    await store.executeSql(
+      'DELETE FROM remote_chat_messages WHERE device_key = ? AND session_id = ?',
+      [deviceKey, sessionId]
+    );
+    if (messages.length > 0) {
+      await store.batchInsert(
+        'remote_chat_messages',
+        RemoteChatLocalRdbStore.rows(deviceKey, sessionId, 0, messages)
+      );
+    }
+    await this.writeHeader(deviceKey, sessionId, messages.length, lastMessageId);
+  }
+
+  async deleteSession(deviceKey: string, sessionId: string): Promise<void> {
+    const store = this.requireStore();
+    await store.executeSql(
+      'DELETE FROM remote_chat_messages WHERE device_key = ? AND session_id = ?',
+      [deviceKey, sessionId]
+    );
+    await store.executeSql(
+      'DELETE FROM remote_chat_sessions WHERE device_key = ? AND session_id = ?',
+      [deviceKey, sessionId]
+    );
+  }
+
+  async pruneSessions(deviceKey: string, keepMostRecent: number): Promise<void> {
+    const store = this.requireStore();
+    const stale =
+      'SELECT session_id FROM remote_chat_sessions WHERE device_key = ? ' +
+      'ORDER BY updated_at DESC LIMIT -1 OFFSET ?';
+    await store.executeSql(
+      `DELETE FROM remote_chat_messages WHERE device_key = ? AND session_id IN (${stale})`,
+      [deviceKey, deviceKey, keepMostRecent]
+    );
+    await store.executeSql(
+      `DELETE FROM remote_chat_sessions WHERE device_key = ? AND session_id IN (${stale})`,
+      [deviceKey, deviceKey, keepMostRecent]
+    );
+  }
+
+  async clearAll(): Promise<void> {
+    const store = this.requireStore();
+    await store.executeSql('DELETE FROM remote_chat_messages');
+    await store.executeSql('DELETE FROM remote_chat_sessions');
+  }
+
+  /** Keeps [pruneSessions] evicting the sessions the user stopped opening. */
+  private async touchSession(deviceKey: string, sessionId: string): Promise<void> {
+    await this.requireStore().executeSql(
+      'UPDATE remote_chat_sessions SET updated_at = ? WHERE device_key = ? AND session_id = ?',
+      [Date.now(), deviceKey, sessionId]
+    );
+  }
+
+  private async writeHeader(
+    deviceKey: string,
+    sessionId: string,
+    messageCount: number,
+    lastMessageId: string
+  ): Promise<void> {
+    const values: relationalStore.ValuesBucket = {
+      device_key: deviceKey,
+      session_id: sessionId,
+      message_count: messageCount,
+      last_message_id: lastMessageId,
+      updated_at: Date.now()
+    };
+    await this.requireStore().insert(
+      'remote_chat_sessions',
+      values,
+      relationalStore.ConflictResolution.ON_CONFLICT_REPLACE
+    );
+  }
+
+  private static rows(
+    deviceKey: string,
+    sessionId: string,
+    startSeq: number,
+    messages: ChatMessage[]
+  ): relationalStore.ValuesBucket[] {
+    return messages.map((message: ChatMessage, index: number): relationalStore.ValuesBucket => ({
+      device_key: deviceKey,
+      session_id: sessionId,
+      seq: startSeq + index,
+      payload: JSON.stringify(message)
+    }));
+  }
+
+  private static async storedSchemaVersion(store: relationalStore.RdbStore): Promise<number> {
+    const result = await store.querySql(
+      'SELECT value FROM remote_chat_meta WHERE key = ?',
+      [SCHEMA_VERSION_KEY]
+    );
+    try {
+      if (!result.goToNextRow()) {
+        return 0;
+      }
+      return Number.parseInt(result.getString(result.getColumnIndex('value')), 10) || 0;
+    } finally {
+      result.close();
+    }
+  }
+
+  private requireStore(): relationalStore.RdbStore {
+    if (!this.store) {
+      throw new Error('Remote chat local store is not initialized.');
+    }
+    return this.store;
+  }
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteCommandFactory.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteCommandFactory.ets
index 283e388897..466bbdf424 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteCommandFactory.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteCommandFactory.ets
@@ -197,4 +197,19 @@ export class RemoteCommandFactory {
   static ping(): RemoteCommand {
     return { cmd: 'ping' };
   }
+
+  /**
+   * Ask the paired desktop to register a keyboard-less device on the account.
+   * `requestId` comes from that device rather than from here, so a retry
+   * anywhere along the watch → phone → desktop chain replays one idempotent
+   * relay request instead of registering a second device.
+   */
+  static provisionPeerDevice(deviceId: string, deviceName: string, requestId: string): RemoteCommand {
+    return {
+      cmd: 'provision_peer_device',
+      device_id: deviceId,
+      device_name: deviceName,
+      request_id: requestId
+    };
+  }
 }
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteHeartbeatController.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteHeartbeatController.ets
index e71d644cea..4c306c83af 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteHeartbeatController.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteHeartbeatController.ets
@@ -14,13 +14,14 @@ class SystemRemoteHeartbeatScheduler implements RemoteHeartbeatScheduler {
 }
 
 export class RemoteHeartbeatController {
-  private readonly onTick: () => void;
+  private readonly onTick: () => Promise<void>;
   private readonly intervalMs: number;
   private readonly scheduler: RemoteHeartbeatScheduler;
   private timerId: number = 0;
+  private inFlight: boolean = false;
 
   constructor(
-    onTick: () => void,
+    onTick: () => Promise<void>,
     intervalMs: number = 15000,
     scheduler: RemoteHeartbeatScheduler = new SystemRemoteHeartbeatScheduler()
   ) {
@@ -32,10 +33,30 @@ export class RemoteHeartbeatController {
   start(): void {
     this.stop();
     this.timerId = this.scheduler.setInterval(() => {
-      this.onTick();
+      void this.runTick();
     }, this.intervalMs);
   }
 
+  /**
+   * A tick that arrives while the previous one is still out is dropped, not
+   * queued. The interval counts wall-clock time, but a heartbeat can outlive
+   * many intervals: a desktop that has stopped answering holds every request
+   * until the relay's own timeout, two minutes later. Starting one more each
+   * interval turns a single unanswered request into a pile of them aimed at the
+   * desktop that is already not answering.
+   */
+  private async runTick(): Promise<void> {
+    if (this.inFlight) {
+      return;
+    }
+    this.inFlight = true;
+    try {
+      await this.onTick();
+    } finally {
+      this.inFlight = false;
+    }
+  }
+
   stop(): void {
     if (this.timerId !== 0) {
       this.scheduler.clearInterval(this.timerId);
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemotePairingPolicy.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemotePairingPolicy.ets
index 005cf6f710..3d9aa415f9 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemotePairingPolicy.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemotePairingPolicy.ets
@@ -1,5 +1,9 @@
 import { RemoteI18n } from '../i18n/RemoteI18n';
 import { RemoteDescriptor } from '../model/RemoteModels';
+import {
+  ConnectScanDecisionPolicy,
+  DetectedUrlAction
+} from './ConnectScanDecisionPolicy';
 import { PairIdentity } from './RelayHttpClient';
 import { RemoteDescriptorParser } from './RemoteDescriptorParser';
 
@@ -72,8 +76,18 @@ export class RemotePairingPolicy {
     };
   }
 
-  shouldPromptForAccount(descriptor: RemoteDescriptor): boolean {
-    return descriptor.accountAuth;
+  shouldPromptForAccount(
+    descriptor: RemoteDescriptor,
+    hasCloudAccountSession: boolean = false,
+    cloudUsername: string = ''
+  ): boolean {
+    return ConnectScanDecisionPolicy.decide(
+      descriptor.accountAuth,
+      hasCloudAccountSession,
+      cloudUsername,
+      descriptor.accountUsername,
+      ''
+    ) === DetectedUrlAction.PROMPT_ACCOUNT_PASSWORD;
   }
 
   private isDefaultUserId(userId: string, deviceId: string): boolean {
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteSessionController.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteSessionController.ets
index 8bbcd94eff..79d01a5ac0 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteSessionController.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteSessionController.ets
@@ -6,6 +6,7 @@ import {
 } from '../model/RemoteModels';
 import { RemoteI18n } from '../i18n/RemoteI18n';
 import { ConnectionErrorPolicy } from './ConnectionErrorPolicy';
+import { RemoteLogger } from './RemoteLogger';
 import { RemoteUiState } from './RemoteUiState';
 
 export interface RemoteSessionClient {
@@ -34,6 +35,7 @@ export class RemoteSessionController {
   private sessions: RemoteSession[] = [];
   private hasMore: boolean = false;
   private offset: number = 0;
+  private openGeneration: number = 0;
 
   constructor(
     client: RemoteSessionClient,
@@ -45,6 +47,13 @@ export class RemoteSessionController {
     this.callbacks = callbacks;
   }
 
+  private static shortId(value: string): string {
+    if (value.length <= 10) {
+      return value;
+    }
+    return `${value.slice(0, 6)}...${value.slice(-4)}`;
+  }
+
   setSessions(sessions: RemoteSession[], hasMore: boolean): void {
     this.sessions = sessions.slice();
     this.hasMore = hasMore;
@@ -132,9 +141,9 @@ export class RemoteSessionController {
     onCreated: (session: SessionSummary) => Promise<void>,
     instruction: string = '',
     modelId: string = ''
-  ): Promise<void> {
+  ): Promise<SessionSummary | undefined> {
     if (isBusy || !remoteAvailable) {
-      return;
+      return undefined;
     }
     try {
       this.callbacks.onBusy(true);
@@ -148,8 +157,10 @@ export class RemoteSessionController {
       this.callbacks.onActiveSession(session);
       this.callbacks.onStatusText(RemoteI18n.t('status.sessionCreated'));
       await onCreated(session);
+      return session;
     } catch (err) {
       this.callbacks.onStatusText(ConnectionErrorPolicy.errorText(err));
+      return undefined;
     } finally {
       this.callbacks.onBusy(false);
     }
@@ -163,8 +174,15 @@ export class RemoteSessionController {
     onOpened: (session: SessionSummary) => Promise<void>
   ): Promise<void> {
     if (isBusy || item.id.length === 0 || !remoteAvailable) {
+      RemoteLogger.info(`open session dropped session=${RemoteSessionController.shortId(item.id)} busy=${isBusy ? '1' : '0'} available=${remoteAvailable ? '1' : '0'}`);
       return;
     }
+    // Opens supersede each other, so the one that finishes first is not
+    // necessarily the one still on screen. Lowering the busy flag from that one
+    // would tell the composer the session it is attached to had finished
+    // loading while the newer open was still fetching.
+    this.openGeneration += 1;
+    const generation = this.openGeneration;
     try {
       this.callbacks.onBusy(true);
       this.callbacks.onStatusText(RemoteI18n.t('status.loadMessages'));
@@ -177,7 +195,9 @@ export class RemoteSessionController {
       this.callbacks.onActiveSession(session);
       await onOpened(session);
     } finally {
-      this.callbacks.onBusy(false);
+      if (generation === this.openGeneration) {
+        this.callbacks.onBusy(false);
+      }
     }
   }
 
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteSessionListCache.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteSessionListCache.ets
new file mode 100644
index 0000000000..662d9f75a3
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteSessionListCache.ets
@@ -0,0 +1,169 @@
+import { RemoteSession } from '../model/RemoteModels';
+import { RemoteLogger } from './RemoteLogger';
+
+/** A device's session list as it was last shown. */
+export interface RemoteSessionListSlice {
+  sessions: RemoteSession[];
+  hasMore: boolean;
+}
+
+/** Storage behind [RemoteSessionListCache]; see `RemoteSessionListRdbStore`. */
+export interface RemoteSessionListStore {
+  init(context: Context): Promise<void>;
+  loadList(deviceKey: string): Promise<RemoteSessionListSlice>;
+  /** The list for whichever device was written last, for a cold start. */
+  loadLastList(): Promise<RemoteSessionListSlice>;
+  saveList(deviceKey: string, sessions: RemoteSession[], hasMore: boolean): Promise<void>;
+  clearAll(): Promise<void>;
+}
+
+/**
+ * How many sessions per desktop are worth keeping.
+ *
+ * The list exists to fill the first screen while the connection settles, and
+ * the desktop replaces it wholesale a moment later, so storing past what the
+ * user can scroll to in that moment buys nothing.
+ */
+const CACHED_SESSIONS_PER_DEVICE: number = 60;
+
+/**
+ * The session list on disk, so Remote Home has something to show before the
+ * desktop answers.
+ *
+ * Same bargain as `RemoteChatCache`: every failure is swallowed, because a
+ * cache that cannot be read leaves the app exactly as slow as it was without
+ * one. What is served here is a snapshot that may already be stale — titles
+ * change, sessions get deleted — which is safe only because opening a session
+ * goes through the desktop anyway and the live list overwrites this one as soon
+ * as the connection is up.
+ */
+export class RemoteSessionListCache {
+  private readonly store: RemoteSessionListStore;
+  private readonly deviceKeyProvider: () => string;
+  private ready: boolean = false;
+  // Signature of the last list written, so the repeated `onSessions` callbacks
+  // behind one refresh cost one write rather than one write each.
+  private writtenScope: string = '';
+  private writtenSignature: string = '';
+
+  constructor(store: RemoteSessionListStore, deviceKeyProvider: () => string) {
+    this.store = store;
+    this.deviceKeyProvider = deviceKeyProvider;
+  }
+
+  async init(context: Context): Promise<void> {
+    try {
+      await this.store.init(context);
+      this.ready = true;
+    } catch (err) {
+      RemoteLogger.error(`remote session list cache unavailable: ${RemoteSessionListCache.reason(err)}`);
+    }
+  }
+
+  /**
+   * The list for the device the phone last talked to.
+   *
+   * Used at startup, where the device to key on is not known yet: identity is
+   * still being restored and the auto-reconnect that follows targets exactly
+   * the device this list came from.
+   */
+  async restoreLast(): Promise<RemoteSessionListSlice> {
+    if (!this.ready) {
+      return RemoteSessionListCache.empty();
+    }
+    try {
+      return await this.store.loadLastList();
+    } catch (err) {
+      RemoteLogger.error(`remote session list cache read failed: ${RemoteSessionListCache.reason(err)}`);
+      return RemoteSessionListCache.empty();
+    }
+  }
+
+  /** The list stored for the device currently being controlled. */
+  async load(): Promise<RemoteSessionListSlice> {
+    const deviceKey = this.scope();
+    if (deviceKey.length === 0) {
+      return RemoteSessionListCache.empty();
+    }
+    try {
+      return await this.store.loadList(deviceKey);
+    } catch (err) {
+      RemoteLogger.error(`remote session list cache read failed: ${RemoteSessionListCache.reason(err)}`);
+      return RemoteSessionListCache.empty();
+    }
+  }
+
+  /**
+   * Stores the list now on screen.
+   *
+   * An empty list is never written: disconnecting clears the list through the
+   * same path a real refresh takes, and a user who steps away from a desktop
+   * should still find their sessions there on the next launch.
+   */
+  async save(sessions: RemoteSession[], hasMore: boolean): Promise<void> {
+    const deviceKey = this.scope();
+    if (deviceKey.length === 0 || sessions.length === 0) {
+      return;
+    }
+    const kept = sessions.slice(0, CACHED_SESSIONS_PER_DEVICE);
+    const keptHasMore = hasMore || kept.length < sessions.length;
+    const signature = RemoteSessionListCache.signature(kept, keptHasMore);
+    if (this.writtenScope === deviceKey && this.writtenSignature === signature) {
+      return;
+    }
+    try {
+      await this.store.saveList(deviceKey, kept, keptHasMore);
+      this.writtenScope = deviceKey;
+      this.writtenSignature = signature;
+    } catch (err) {
+      this.forgetSignature();
+      RemoteLogger.error(`remote session list cache write failed: ${RemoteSessionListCache.reason(err)}`);
+    }
+  }
+
+  /** Drops every stored list, for signing out. */
+  async clear(): Promise<void> {
+    this.forgetSignature();
+    if (!this.ready) {
+      return;
+    }
+    try {
+      await this.store.clearAll();
+    } catch (err) {
+      RemoteLogger.error(`remote session list cache clear failed: ${RemoteSessionListCache.reason(err)}`);
+    }
+  }
+
+  private forgetSignature(): void {
+    this.writtenScope = '';
+    this.writtenSignature = '';
+  }
+
+  /** The device to key on, or '' when there is nothing safe to key on. */
+  private scope(): string {
+    const deviceKey = this.deviceKeyProvider().trim();
+    if (!this.ready || deviceKey.length === 0) {
+      return '';
+    }
+    return deviceKey;
+  }
+
+  /**
+   * Everything the list renders from, so a stored list is rewritten when a
+   * title changes but not when the same list is published twice.
+   */
+  private static signature(sessions: RemoteSession[], hasMore: boolean): string {
+    const parts = sessions.map((item: RemoteSession): string => {
+      return `${item.id}
${item.title}
${item.status}
${item.updatedAt}
${item.messageCount}`;
+    });
+    return `${hasMore ? '1' : '0'}${parts.join('')}`;
+  }
+
+  private static empty(): RemoteSessionListSlice {
+    return { sessions: [], hasMore: false };
+  }
+
+  private static reason(err: Object): string {
+    return err instanceof Error ? err.message : `${err}`;
+  }
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteSessionListRdbStore.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteSessionListRdbStore.ets
new file mode 100644
index 0000000000..0a7a302861
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteSessionListRdbStore.ets
@@ -0,0 +1,126 @@
+import { relationalStore } from '@kit.ArkData';
+import { RemoteSession } from '../model/RemoteModels';
+import { Encoding } from './Encoding';
+import { RemoteSessionListSlice, RemoteSessionListStore } from './RemoteSessionListCache';
+
+const STORE_CONFIG: relationalStore.StoreConfig = {
+  name: 'bitfun_remote_sessions.db',
+  // Session titles are as revealing as the transcripts themselves, so this
+  // matches the level the transcript store uses.
+  securityLevel: relationalStore.SecurityLevel.S2
+};
+
+/** Bumped whenever a stored row stops meaning what it used to; see the chat store. */
+const SCHEMA_VERSION: number = 1;
+const SCHEMA_VERSION_KEY: string = 'schema_version';
+const LAST_DEVICE_KEY: string = 'last_device_key';
+
+const CREATE_META_SQL =
+  'CREATE TABLE IF NOT EXISTS remote_session_meta (' +
+  'key TEXT PRIMARY KEY, value TEXT NOT NULL)';
+// One row per device: the list is small, is always replaced as a whole, and is
+// only ever read in full, so there is nothing for a per-session row to buy.
+const CREATE_LIST_SQL =
+  'CREATE TABLE IF NOT EXISTS remote_session_list (' +
+  'device_key TEXT PRIMARY KEY, payload TEXT NOT NULL, has_more INTEGER NOT NULL, ' +
+  'updated_at INTEGER NOT NULL)';
+
+/** Session lists on disk, keyed by the desktop that owns them. */
+export class RemoteSessionListRdbStore implements RemoteSessionListStore {
+  private store?: relationalStore.RdbStore;
+
+  async init(context: Context): Promise<void> {
+    const store = await relationalStore.getRdbStore(context, STORE_CONFIG);
+    await store.executeSql(CREATE_META_SQL);
+    if (await RemoteSessionListRdbStore.storedValue(store, SCHEMA_VERSION_KEY) !== `${SCHEMA_VERSION}`) {
+      await store.executeSql('DROP TABLE IF EXISTS remote_session_list');
+      await store.executeSql(
+        'DELETE FROM remote_session_meta WHERE key = ?',
+        [LAST_DEVICE_KEY]
+      );
+      await store.executeSql(
+        'INSERT OR REPLACE INTO remote_session_meta (key, value) VALUES (?, ?)',
+        [SCHEMA_VERSION_KEY, `${SCHEMA_VERSION}`]
+      );
+    }
+    await store.executeSql(CREATE_LIST_SQL);
+    this.store = store;
+  }
+
+  async loadList(deviceKey: string): Promise<RemoteSessionListSlice> {
+    if (deviceKey.length === 0) {
+      return RemoteSessionListRdbStore.empty();
+    }
+    const rows = await this.requireStore().querySql(
+      'SELECT payload, has_more FROM remote_session_list WHERE device_key = ?',
+      [deviceKey]
+    );
+    try {
+      if (!rows.goToNextRow()) {
+        return RemoteSessionListRdbStore.empty();
+      }
+      return {
+        sessions: Encoding.parseJsonObject<RemoteSession[]>(rows.getString(rows.getColumnIndex('payload'))),
+        hasMore: rows.getLong(rows.getColumnIndex('has_more')) === 1
+      };
+    } finally {
+      rows.close();
+    }
+  }
+
+  async loadLastList(): Promise<RemoteSessionListSlice> {
+    const deviceKey = await RemoteSessionListRdbStore.storedValue(this.requireStore(), LAST_DEVICE_KEY);
+    return await this.loadList(deviceKey);
+  }
+
+  async saveList(deviceKey: string, sessions: RemoteSession[], hasMore: boolean): Promise<void> {
+    if (deviceKey.length === 0) {
+      return;
+    }
+    const store = this.requireStore();
+    const values: relationalStore.ValuesBucket = {
+      device_key: deviceKey,
+      payload: JSON.stringify(sessions),
+      has_more: hasMore ? 1 : 0,
+      updated_at: Date.now()
+    };
+    await store.insert('remote_session_list', values, relationalStore.ConflictResolution.ON_CONFLICT_REPLACE);
+    // Written after the list, so a pointer never names a row that is not there.
+    await store.executeSql(
+      'INSERT OR REPLACE INTO remote_session_meta (key, value) VALUES (?, ?)',
+      [LAST_DEVICE_KEY, deviceKey]
+    );
+  }
+
+  async clearAll(): Promise<void> {
+    const store = this.requireStore();
+    await store.executeSql('DELETE FROM remote_session_list');
+    await store.executeSql('DELETE FROM remote_session_meta WHERE key = ?', [LAST_DEVICE_KEY]);
+  }
+
+  private static async storedValue(store: relationalStore.RdbStore, key: string): Promise<string> {
+    const rows = await store.querySql(
+      'SELECT value FROM remote_session_meta WHERE key = ?',
+      [key]
+    );
+    try {
+      if (!rows.goToNextRow()) {
+        return '';
+      }
+      return rows.getString(rows.getColumnIndex('value'));
+    } finally {
+      rows.close();
+    }
+  }
+
+  private static empty(): RemoteSessionListSlice {
+    return { sessions: [], hasMore: false };
+  }
+
+  private requireStore(): relationalStore.RdbStore {
+    if (!this.store) {
+      throw new Error('Remote session list local store is not initialized.');
+    }
+    return this.store;
+  }
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteSessionManager.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteSessionManager.ets
index ac6a07d757..58074a47c9 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteSessionManager.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteSessionManager.ets
@@ -1,6 +1,6 @@
 import { AssistantEntry, AssistantListResponse, ChatMessageItemResponse, ChatMessageResponse, CommandStatusResponse, CreateSessionOptions, CreateSessionResponse, FileInfo, FileInfoResponse, InitialSyncResult, ModelCatalogResponse, PermissionModeResponse, PollSessionResponse, PollSessionResult, ReadFileChunkResponse, ReadFileChunkResult, ReadFileResult, RecentWorkspaceEntry, RecentWorkspaceListResponse, RemoteCommand, RemoteDescriptor, RemoteImageContext, RemoteModelCatalog, RemotePermissionMode, RemoteQuestionAnswerPayload, RemoteSession, SendMessageResponse, SessionListResponse, SessionListResult, SessionMessagesResponse, SessionMessagesResult, SessionSummary, SetAssistantResponse, SetSessionModelResponse, SetWorkspaceResponse, WorkspaceInfo, WorkspaceInfoResponse } from '../model/RemoteModels';
 import { Encoding } from './Encoding';
-import { PairIdentity, RelayHttpClient } from './RelayHttpClient';
+import { PairIdentity, PeerDeviceProvisionOutcome, RelayHttpClient } from './RelayHttpClient';
 import { CloudAccountClient, CloudAccountSession } from './CloudAccountClient';
 import { AccountDeviceCommandTransport, RemoteCommandTransport, RoomRemoteCommandTransport } from './RemoteCommandTransport';
 import { RemoteCommandFactory } from './RemoteCommandFactory';
@@ -10,6 +10,7 @@ import { RemoteFileDownloadClient } from './RemoteFileDownloadController';
 import { RemoteLogger } from './RemoteLogger';
 import { RemoteModelClient } from './RemoteModelController';
 import { RemoteResponseMapper } from './RemoteResponseMapper';
+import { TranscriptIntegrityPolicy } from './TranscriptIntegrityPolicy';
 import { RemoteSessionClient } from './RemoteSessionController';
 import { RemoteToolActionClient } from './RemoteToolActionController';
 
@@ -18,6 +19,15 @@ export interface DelegatedAccountSession {
   session: CloudAccountSession;
 }
 
+/** A credential minted for a peer device, paired with the relay it belongs to. */
+export interface ProvisionedPeerDevice {
+  relayUrl: string;
+  token: string;
+  userId: string;
+  masterKeyBase64: string;
+  deviceId: string;
+}
+
 export class RemoteSessionManager implements RemoteChatCommandClient, RemoteFileDownloadClient, RemoteModelClient, RemoteSessionClient, RemoteToolActionClient {
   private readonly roomClient: RelayHttpClient = new RelayHttpClient();
   private transport?: RemoteCommandTransport;
@@ -71,6 +81,37 @@ export class RemoteSessionManager implements RemoteChatCommandClient, RemoteFile
     };
   }
 
+  /**
+   * True when a QR-paired room channel is live. Provisioning a peer device is
+   * only answerable there, so the caller uses this to decide whether the
+   * feature is offerable at all rather than letting the user find out after a
+   * 45-second wait.
+   */
+  hasRoomChannel(): boolean {
+    return this.roomRelayUrl.trim().length > 0;
+  }
+
+  /**
+   * Relay a watch's provisioning request to the paired desktop. Goes straight
+   * to the room client rather than through `send()`, because the account-device
+   * transport reaches a different desktop handler that cannot mint credentials.
+   */
+  async provisionPeerDevice(
+    deviceId: string,
+    deviceName: string,
+    requestId: string
+  ): Promise<PeerDeviceProvisionOutcome> {
+    if (!this.hasRoomChannel()) {
+      throw new Error('Remote room channel is not connected.');
+    }
+    return this.roomClient.provisionPeerDevice(deviceId, deviceName, requestId);
+  }
+
+  /** Relay the provisioned credential belongs to — the one this room lives on. */
+  roomRelayEndpoint(): string {
+    return this.roomRelayUrl;
+  }
+
   async connectAccountDevice(
     accountClient: CloudAccountClient,
     relayUrl: string,
@@ -221,9 +262,15 @@ export class RemoteSessionManager implements RemoteChatCommandClient, RemoteFile
   }
 
   async getSessionMessages(sessionId: string): Promise<SessionMessagesResult> {
+    const startedAt = Date.now();
     const response = await this.send<SessionMessagesResponse>(RemoteCommandFactory.getSessionMessages(sessionId));
     const rawMessages = response.messages || [];
     const messages = rawMessages.map((item: ChatMessageResponse) => RemoteResponseMapper.chatMessage(item));
+    RemoteLogger.info(
+      `get_session_messages done session=${RemoteSessionManager.shortId(sessionId)} ` +
+        `raw=${rawMessages.length} ${TranscriptIntegrityPolicy.describeMessages(messages)} ` +
+        `ms=${Date.now() - startedAt}`
+    );
     const result: SessionMessagesResult = {
       messages,
       hasMore: false
@@ -270,7 +317,7 @@ export class RemoteSessionManager implements RemoteChatCommandClient, RemoteFile
       modelCatalog: response.model_catalog
     };
     const rawActive = response.active_turn;
-    RemoteLogger.info(`poll_session done session=${RemoteSessionManager.shortId(sessionId)} changed=${result.changed ? '1' : '0'} state=${result.sessionState} active=${rawActive ? rawActive.turn_id : ''} activeStatus=${rawActive ? rawActive.status : ''} rawText=${rawActive && rawActive.text ? rawActive.text.length : 0} rawThinking=${rawActive && rawActive.thinking ? rawActive.thinking.length : 0} rawItems=${rawActive && rawActive.items ? rawActive.items.length : 0} rawItemText=${RemoteSessionManager.itemsContentLength(rawActive ? rawActive.items : undefined)} projectedText=${result.activeTurn ? result.activeTurn.text.length : 0} new=${newMessages.length} ms=${Date.now() - startedAt}`);
+    RemoteLogger.info(`poll_session done session=${RemoteSessionManager.shortId(sessionId)} changed=${result.changed ? '1' : '0'} state=${result.sessionState} active=${rawActive ? rawActive.turn_id : ''} activeStatus=${rawActive ? rawActive.status : ''} rawText=${rawActive && rawActive.text ? rawActive.text.length : 0} rawThinking=${rawActive && rawActive.thinking ? rawActive.thinking.length : 0} rawItems=${rawActive && rawActive.items ? rawActive.items.length : 0} rawItemText=${RemoteSessionManager.itemsContentLength(rawActive ? rawActive.items : undefined)} projectedText=${result.activeTurn ? result.activeTurn.text.length : 0} new=${newMessages.length} ${newMessages.length > 0 ? TranscriptIntegrityPolicy.describeMessages(newMessages) + ' ' : ''}ms=${Date.now() - startedAt}`);
     return result;
   }
 
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteToolActionController.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteToolActionController.ets
index 0112cf3101..de4ddd166e 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteToolActionController.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteToolActionController.ets
@@ -1,6 +1,7 @@
 import { RemoteQuestionAnswerPayload } from '../model/RemoteModels';
 import { RemoteI18n } from '../i18n/RemoteI18n';
 import { ConnectionErrorPolicy } from './ConnectionErrorPolicy';
+import { RemoteLogger } from './RemoteLogger';
 
 export interface RemoteToolActionClient {
   confirmTool(toolId: string, updatedInput?: Object): Promise<void>;
@@ -59,6 +60,7 @@ export class RemoteToolActionController {
   }
 
   async cancel(toolId: string, sessionId: string, remoteAvailable: boolean): Promise<void> {
+    RemoteLogger.info(`tool cancel requested tool=${RemoteToolActionController.shortId(toolId)} session=${RemoteToolActionController.shortId(sessionId)}`);
     await this.runToolAction(
       toolId,
       sessionId,
@@ -77,6 +79,7 @@ export class RemoteToolActionController {
     remoteAvailable: boolean,
     answers: RemoteQuestionAnswerPayload
   ): Promise<void> {
+    RemoteLogger.info(`question answer requested tool=${RemoteToolActionController.shortId(toolId)} session=${RemoteToolActionController.shortId(sessionId)} fields=${Object.keys(answers).length}`);
     await this.runToolAction(
       toolId,
       sessionId,
@@ -104,6 +107,7 @@ export class RemoteToolActionController {
       this.onBusy(true);
       this.onStatusText(pendingText);
       await action();
+      RemoteLogger.info(`tool action accepted tool=${RemoteToolActionController.shortId(toolId)}`);
       this.onStatusText(successText);
       this.onPoll();
     } catch (err) {
@@ -112,4 +116,9 @@ export class RemoteToolActionController {
       this.onBusy(false);
     }
   }
+
+  private static shortId(value: string): string {
+    if (value.length <= 10) return value;
+    return `${value.slice(0, 6)}...${value.slice(-4)}`;
+  }
 }
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteUiState.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteUiState.ets
index 4c1d998cc8..8fbbb14e3b 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteUiState.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteUiState.ets
@@ -6,6 +6,7 @@ import {
   RemoteSession
 } from '../model/RemoteModels';
 import { RemoteI18n } from '../i18n/RemoteI18n';
+import { TranscriptIntegrityPolicy } from './TranscriptIntegrityPolicy';
 
 export class RemoteUiState {
   static canUseRemote(connectionState: string): boolean {
@@ -216,6 +217,10 @@ export class RemoteUiState {
 
   private static mergeMessageSnapshot(previous: ChatMessage, incoming: ChatMessage): ChatMessage {
     const hasIncomingText = (incoming.text || '').trim().length > 0;
+    const incomingThinking = (incoming.thinking || '').trim();
+    const incomingTools = incoming.tools && incoming.tools.length > 0 ? incoming.tools : undefined;
+    const incomingItems = TranscriptIntegrityPolicy.hasRenderableItems(incoming.items) ? incoming.items : undefined;
+    const incomingImages = incoming.images && incoming.images.length > 0 ? incoming.images : undefined;
     return {
       id: incoming.id,
       turnId: incoming.turnId || previous.turnId,
@@ -224,10 +229,14 @@ export class RemoteUiState {
       status: incoming.status || previous.status,
       detail: incoming.detail || previous.detail,
       timestamp: incoming.timestamp || previous.timestamp,
-      thinking: incoming.thinking !== undefined ? incoming.thinking : (hasIncomingText ? undefined : previous.thinking),
-      tools: incoming.tools !== undefined ? incoming.tools : previous.tools,
-      items: incoming.items !== undefined ? incoming.items : previous.items,
-      images: incoming.images !== undefined ? incoming.images : previous.images,
+      // Final text without a thinking field still clears streamed thinking.
+      // An empty stub must not wipe a body the previous snapshot already had.
+      thinking: incomingThinking.length > 0
+        ? incoming.thinking
+        : (hasIncomingText ? incoming.thinking : previous.thinking),
+      tools: incomingTools !== undefined ? incomingTools : previous.tools,
+      items: incomingItems !== undefined ? incomingItems : previous.items,
+      images: incomingImages !== undefined ? incomingImages : previous.images,
       renderVersion: incoming.renderVersion !== undefined ? incoming.renderVersion : previous.renderVersion
     };
   }
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteWorkspaceCoordinator.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteWorkspaceCoordinator.ets
index b0cf3d2c5c..f6244b3c4c 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteWorkspaceCoordinator.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/RemoteWorkspaceCoordinator.ets
@@ -2,6 +2,18 @@ import { AssistantEntry, RecentWorkspaceEntry, RemoteSession, WorkspaceInfo } fr
 import { RemoteWorkspaceDataSource } from './RemoteWorkspaceRepository';
 import { RemoteLogger } from './RemoteLogger';
 
+/**
+ * How many workspaces are listed at once during cross-workspace discovery.
+ *
+ * Each listing is one round trip to the desktop over the relay, and a phone
+ * that has been used for a while has twenty-odd recent workspaces: done one
+ * after another that is five seconds of the session list rearranging itself
+ * behind the user. Kept small because these run alongside the polling that
+ * drives an open conversation, and a burst wide enough to crowd it out would
+ * trade a slow list for a slow chat.
+ */
+const CONCURRENT_WORKSPACE_LISTINGS: number = 4;
+
 /** Coordinates workspace/assistant selection and cross-workspace session discovery. */
 export class RemoteWorkspaceCoordinator {
   private readonly repository: RemoteWorkspaceDataSource;
@@ -26,20 +38,39 @@ export class RemoteWorkspaceCoordinator {
     return await this.repository.setAssistant(path);
   }
 
+  /**
+   * Every session the given workspaces know about, first occurrence winning.
+   *
+   * Listings run a batch at a time rather than all at once or one at a time,
+   * and results are merged in the order the paths were given, so widening the
+   * batch changes how long this takes and nothing about what it returns.
+   */
   async sessionsForWorkspaces(paths: string[]): Promise<RemoteSession[]> {
     const all: RemoteSession[] = [];
-    for (const path of paths) {
-      try {
-        const sessions = await this.repository.listSessionsForWorkspace(path, 50);
+    for (let start = 0; start < paths.length; start += CONCURRENT_WORKSPACE_LISTINGS) {
+      const batch: string[] = paths.slice(start, start + CONCURRENT_WORKSPACE_LISTINGS);
+      const listings: RemoteSession[][] = await Promise.all(
+        batch.map((path: string): Promise<RemoteSession[]> => this.sessionsForWorkspace(path))
+      );
+      listings.forEach((sessions: RemoteSession[]) => {
         sessions.forEach((item: RemoteSession) => {
           if (!all.some((existing: RemoteSession) => existing.id === item.id)) {
             all.push(item);
           }
         });
-      } catch (err) {
-        RemoteLogger.warn(`load workspace sessions failed path=${path}: ${String(err)}`);
-      }
+      });
     }
     return all;
   }
+
+  /** One workspace's sessions, or none when that workspace cannot be read. */
+  private async sessionsForWorkspace(path: string): Promise<RemoteSession[]> {
+    try {
+      return await this.repository.listSessionsForWorkspace(path, 50);
+    } catch (err) {
+      // One unreadable workspace is not a reason to lose the other twenty.
+      RemoteLogger.warn(`load workspace sessions failed path=${path}: ${String(err)}`);
+      return [];
+    }
+  }
 }
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/TranscriptIntegrityPolicy.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/TranscriptIntegrityPolicy.ets
new file mode 100644
index 0000000000..aac1b97eaf
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/TranscriptIntegrityPolicy.ets
@@ -0,0 +1,80 @@
+import { ChatMessage, ChatMessageItemResponse } from '../model/RemoteModels';
+
+/**
+ * Whether a persisted or polled transcript row still has a body the timeline
+ * can show. A hollow assistant is a real id with no text, thinking, tools,
+ * items, or images — the shape left behind when a slim poll stub overwrites a
+ * live turn, or when a cache row was written before the desktop settled.
+ */
+export class TranscriptIntegrityPolicy {
+  static hasDisplayableBody(message: ChatMessage): boolean {
+    if ((message.text || '').trim().length > 0) {
+      return true;
+    }
+    if ((message.thinking || '').trim().length > 0) {
+      return true;
+    }
+    if (message.tools && message.tools.length > 0) {
+      return true;
+    }
+    if (TranscriptIntegrityPolicy.hasRenderableItems(message.items)) {
+      return true;
+    }
+    if (message.images && message.images.length > 0) {
+      return true;
+    }
+    return false;
+  }
+
+  static isHollowAssistant(message: ChatMessage): boolean {
+    return (message.role || '').toLowerCase() === 'assistant' &&
+      !TranscriptIntegrityPolicy.hasDisplayableBody(message);
+  }
+
+  static hasHollowAssistants(messages: ChatMessage[]): boolean {
+    return messages.some((message: ChatMessage) => {
+      return TranscriptIntegrityPolicy.isHollowAssistant(message);
+    });
+  }
+
+  static hasRenderableItems(items?: ChatMessageItemResponse[]): boolean {
+    if (!items || items.length === 0) {
+      return false;
+    }
+    return items.some((entry: ChatMessageItemResponse) => {
+      if ((entry.content || '').trim().length > 0 || !!entry.tool) {
+        return true;
+      }
+      return TranscriptIntegrityPolicy.hasRenderableItems(entry.subItems);
+    });
+  }
+
+  static describeMessages(messages: ChatMessage[]): string {
+    const assistants = messages.filter((message: ChatMessage) => {
+      return (message.role || '').toLowerCase() === 'assistant';
+    });
+    let hollow = 0;
+    const parts: string[] = [];
+    assistants.forEach((message: ChatMessage) => {
+      if (TranscriptIntegrityPolicy.isHollowAssistant(message)) {
+        hollow += 1;
+      }
+      parts.push(
+        `id=${TranscriptIntegrityPolicy.shortId(message.id)} ` +
+          `text=${(message.text || '').length} ` +
+          `thinking=${(message.thinking || '').length} ` +
+          `tools=${message.tools ? message.tools.length : 0} ` +
+          `items=${message.items ? message.items.length : 0}`
+      );
+    });
+    const detail = parts.length > 0 ? ` ${parts.join(' ')}` : '';
+    return `total=${messages.length} assistants=${assistants.length} hollow=${hollow}${detail}`;
+  }
+
+  private static shortId(value: string): string {
+    if (value.length <= 10) {
+      return value;
+    }
+    return `${value.slice(0, 6)}...${value.slice(-4)}`;
+  }
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/WatchHandoffStore.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/WatchHandoffStore.ets
new file mode 100644
index 0000000000..4018f84beb
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/WatchHandoffStore.ets
@@ -0,0 +1,201 @@
+import distributedKVStore from '@ohos.data.distributedKVStore';
+import { common } from '@kit.AbilityKit';
+import { distributedDeviceManager } from '@kit.DistributedServiceKit';
+import { RemoteLogger } from './RemoteLogger';
+import {
+  WATCH_PROVISION_REQUEST_KEY,
+  WATCH_PROVISION_RESPONSE_KEY
+} from './WatchProvisionProtocol';
+
+/**
+ * Versioned because a store's `securityLevel` is fixed at creation: it can only
+ * ever be raised, and for a store that syncs across devices it cannot be changed
+ * at all. `bitfun_harmony_handoff` was created S2 on both devices and had to be
+ * abandoned rather than relabelled — see the S1 note on `securityLevel` below.
+ * Must stay identical to the watch's `DistributedHandoffStore`.
+ */
+const STORE_ID: string = 'bitfun_harmony_handoff_s1';
+
+export type WatchProvisionRequestHandler = (payload: string) => void;
+
+/**
+ * Phone half of the distributed KV channel the watch already listens on.
+ *
+ * `distributedKVStore` isolates stores by bundle name *and* store id and only
+ * replicates between installs of the same app on the same account, which is
+ * why the phone carries the watch's bundle name (`com.bitfun.app`) rather than
+ * a store id of its own.
+ *
+ * The isolation key is really bundle name + **AppID**, and AppID is derived from
+ * the signing certificate — so this project and the watch's must also be built
+ * with the same signing material. Two DevEco-generated debug identities under
+ * one bundle name produce two stores that never see each other, with no error on
+ * either side. The store, the id and the option set below all have
+ * to match the watch's `DistributedHandoffStore` exactly or the two apps end
+ * up with private stores that never see each other's writes.
+ */
+export class WatchHandoffStore {
+  private readonly context: common.UIAbilityContext;
+  private kvManager?: distributedKVStore.KVManager;
+  private kvStore?: distributedKVStore.SingleKVStore;
+  private listener?: (change: distributedKVStore.ChangeNotification) => void;
+  private syncListener?: (results: Array<[string, number]>) => void;
+  private deviceManager?: distributedDeviceManager.DeviceManager;
+
+  constructor(context: common.UIAbilityContext) {
+    this.context = context;
+  }
+
+  async start(handler: WatchProvisionRequestHandler): Promise<void> {
+    const store = await this.getStore();
+    this.listener = (change: distributedKVStore.ChangeNotification): void => {
+      const entries = change.insertEntries.concat(change.updateEntries);
+      entries.forEach((entry: distributedKVStore.Entry) => {
+        if (entry.key === WATCH_PROVISION_REQUEST_KEY &&
+          entry.value.type === distributedKVStore.ValueType.STRING) {
+          RemoteLogger.info('watch provision request arrived over KV');
+          handler(String(entry.value.value));
+        }
+      });
+    };
+    store.on('dataChange', distributedKVStore.SubscribeType.SUBSCRIBE_TYPE_ALL, this.listener);
+    // A watch that asked while the phone app was closed gets picked up here;
+    // the request's own age decides whether it is still worth acting on. The
+    // pull first: the watch pushes on write, but a write that happened while
+    // this app was not running was pushed at a replica that was not listening,
+    // and only an explicit pull goes back for it.
+    this.sync(store, distributedKVStore.SyncMode.PULL_ONLY);
+    try {
+      const value = await store.get(WATCH_PROVISION_REQUEST_KEY);
+      if (typeof value === 'string' && value.trim().length > 0) {
+        handler(value);
+      }
+    } catch (_err) {
+      // No request pending. dataChange delivers the next one.
+    }
+  }
+
+  async writeResponse(payload: string): Promise<void> {
+    const store = await this.getStore();
+    await store.put(WATCH_PROVISION_RESPONSE_KEY, payload);
+    // The watch is waiting on a foreground screen that blanks after nine
+    // seconds; `autoSync`'s own schedule is far too slack to catch that window.
+    this.sync(store, distributedKVStore.SyncMode.PUSH_ONLY);
+  }
+
+  /**
+   * `autoSync` is a hint, not a guarantee — it batches on the platform's
+   * schedule, which on this pair can be never. Both halves of the handoff push
+   * their own writes explicitly, so a missing answer means a missing answer
+   * rather than a sync that was still pending.
+   */
+  private sync(store: distributedKVStore.SingleKVStore, mode: distributedKVStore.SyncMode): void {
+    const peers = this.peerNetworkIds();
+    if (peers.length === 0) {
+      RemoteLogger.warn('watch handoff: no trusted device online to sync with');
+      return;
+    }
+    try {
+      store.sync(peers, mode, 0);
+      RemoteLogger.info(`watch handoff sync requested mode=${mode} peers=${peers.length}`);
+    } catch (err) {
+      RemoteLogger.warn(`watch handoff sync failed: ${WatchHandoffStore.errorText(err)}`);
+    }
+  }
+
+  /**
+   * Network ids of the trusted devices currently online. `sync` addresses
+   * devices by network id, which is per-session, so this is resolved per call
+   * rather than cached.
+   */
+  private peerNetworkIds(): string[] {
+    try {
+      if (!this.deviceManager) {
+        this.deviceManager = distributedDeviceManager.createDeviceManager(
+          this.context.abilityInfo.bundleName);
+      }
+      const ids: string[] = [];
+      this.deviceManager.getAvailableDeviceListSync()
+        .forEach((device: distributedDeviceManager.DeviceBasicInfo) => {
+          const networkId = device.networkId;
+          if (networkId && networkId.length > 0) {
+            ids.push(networkId);
+          }
+        });
+      return ids;
+    } catch (err) {
+      RemoteLogger.warn(`watch handoff device list failed: ${WatchHandoffStore.errorText(err)}`);
+      return [];
+    }
+  }
+
+  stop(): void {
+    if (this.kvStore) {
+      try {
+        if (this.listener) {
+          this.kvStore.off('dataChange', this.listener);
+        }
+        // By reference, never bare: an argument-less `off` drops every ArkTS
+        // instance's listener on this store, not just this one's.
+        if (this.syncListener) {
+          this.kvStore.off('syncComplete', this.syncListener);
+        }
+      } catch (err) {
+        RemoteLogger.warn(`watch handoff unsubscribe failed: ${WatchHandoffStore.errorText(err)}`);
+      }
+    }
+    this.listener = undefined;
+    this.syncListener = undefined;
+    if (this.deviceManager) {
+      distributedDeviceManager.releaseDeviceManager(this.deviceManager);
+      this.deviceManager = undefined;
+    }
+  }
+
+  private async getStore(): Promise<distributedKVStore.SingleKVStore> {
+    if (this.kvStore) {
+      return this.kvStore;
+    }
+    if (!this.kvManager) {
+      this.kvManager = distributedKVStore.createKVManager({
+        bundleName: this.context.abilityInfo.bundleName,
+        context: this.context
+      });
+    }
+    const options: distributedKVStore.Options = {
+      createIfMissing: true,
+      encrypt: true,
+      backup: false,
+      autoSync: true,
+      kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION,
+      // S1, and it has to be: a store only replicates to a device whose security
+      // level is at least its data label, and a watch is an SL1 device — SL1
+      // accepts S1 and nothing else. At S2 the sync was refused by policy before
+      // it was ever attempted, which is indistinguishable from a dead link: no
+      // `dataChange` here, and an empty RecentError on both devices.
+      //
+      // S1 is honest for what actually rides this store rather than a shortcut
+      // around the rule. The master key is never here in the clear — the request
+      // carries the watch's ephemeral public key, and the response carries a
+      // blob sealed to it that only the watch can open. If plaintext credentials
+      // needed to cross, the answer would be a second store, not a lower label.
+      securityLevel: distributedKVStore.SecurityLevel.S1
+    };
+    this.kvStore = await this.kvManager.getKVStore<distributedKVStore.SingleKVStore>(STORE_ID, options);
+    await this.kvStore.enableSync(true);
+    // The only place a refused or failed replication reports itself. Without it
+    // a sync the platform dropped is indistinguishable from a watch that never
+    // asked.
+    this.syncListener = (results: Array<[string, number]>): void => {
+      results.forEach((result: [string, number]) => {
+        RemoteLogger.info(`watch handoff sync complete device=${result[0].substring(0, 8)} code=${result[1]}`);
+      });
+    };
+    this.kvStore.on('syncComplete', this.syncListener);
+    return this.kvStore;
+  }
+
+  private static errorText(err: Object): string {
+    return err instanceof Error ? err.message : JSON.stringify(err);
+  }
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/WatchProvisionController.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/WatchProvisionController.ets
new file mode 100644
index 0000000000..b7faada547
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/WatchProvisionController.ets
@@ -0,0 +1,282 @@
+import { abilityAccessCtrl, common, Context, Permissions } from '@kit.AbilityKit';
+import { RemoteI18n } from '../i18n/RemoteI18n';
+import { RemoteLogger } from './RemoteLogger';
+import { WatchHandoffStore } from './WatchHandoffStore';
+import { WatchProvisionCrypto } from './WatchProvisionCrypto';
+import {
+  WatchProvisionCredential,
+  WatchProvisionProtocol,
+  WatchProvisionRequest
+} from './WatchProvisionProtocol';
+import { WatchProvisionDisplay } from './WatchProvisionDisplay';
+
+const DATASYNC_PERMISSION: Permissions = 'ohos.permission.DISTRIBUTED_DATASYNC';
+
+/**
+ * A minting attempt's result, whoever performed it.
+ *
+ * `relayUrl` travels with the credential rather than being asked for
+ * separately, because the two are only valid together: a token minted by this
+ * phone's own account authenticates against the account's relay, one minted by
+ * a paired desktop against the room's. Reporting them from two places is how
+ * they would come to disagree.
+ */
+export interface WatchProvisionOutcome {
+  ok: boolean;
+  relayUrl: string;
+  token: string;
+  userId: string;
+  masterKeyBase64: string;
+  deviceId: string;
+  failure: string;
+  /** True when a desktop answered and refused, so `failure` is worth showing. */
+  desktopReported: boolean;
+}
+
+/** What the controller needs from the remote stack, kept narrow for testing. */
+export interface WatchProvisionPort {
+  /** True when some path to a credential exists — account or paired desktop. */
+  readonly canProvision: () => boolean;
+  readonly provision: (
+    deviceId: string,
+    deviceName: string,
+    requestId: string
+  ) => Promise<WatchProvisionOutcome>;
+}
+
+/**
+ * Phone side of watch onboarding: watch asks, owner confirms here, desktop
+ * mints, phone seals the credential to the watch's public key.
+ *
+ * The confirmation is not a formality. The watch's request travels over a
+ * store shared by every install of this app on the account, so the only thing
+ * standing between "a device claims to be your watch" and a 30-day account
+ * credential is a person looking at this phone. Approval is therefore never
+ * implicit and never remembered.
+ */
+export class WatchProvisionController {
+  private readonly state: WatchProvisionDisplay;
+  private readonly port: WatchProvisionPort;
+  private store?: WatchHandoffStore;
+  private starting: boolean = false;
+  private started: boolean = false;
+  private pending?: WatchProvisionRequest;
+  private inFlight: boolean = false;
+  /**
+   * Requests already answered in this process. The watch clears its own
+   * request key once it consumes the response, so this only has to cover the
+   * window before that lands — and the TTL covers everything after a restart.
+   */
+  private readonly answered: Set<string> = new Set<string>();
+
+  constructor(state: WatchProvisionDisplay, port: WatchProvisionPort) {
+    this.state = state;
+    this.port = port;
+  }
+
+  /**
+   * Idempotent: called on every page appear, because the permission may have
+   * been granted since the last attempt. A denied permission is not an error
+   * worth surfacing — the phone simply cannot hear the watch until it is
+   * granted, and the watch's own screen says so.
+   */
+  async start(context: Context): Promise<void> {
+    if (this.started || this.starting) {
+      return;
+    }
+    this.starting = true;
+    try {
+      const atManager = abilityAccessCtrl.createAtManager();
+      const result = await atManager.requestPermissionsFromUser(context, [DATASYNC_PERMISSION]);
+      if (result.authResults.length === 0 ||
+        result.authResults[0] !== abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) {
+        RemoteLogger.info('watch provisioning idle: distributed data sync permission not granted');
+        return;
+      }
+      const store = new WatchHandoffStore(context as common.UIAbilityContext);
+      await store.start((payload: string) => {
+        this.onRequestPayload(payload);
+      });
+      this.store = store;
+      this.started = true;
+      RemoteLogger.info('watch provisioning listener started');
+    } catch (err) {
+      RemoteLogger.warn(`watch provisioning listener failed to start: ${WatchProvisionController.errorText(err)}`);
+      this.store = undefined;
+    } finally {
+      this.starting = false;
+    }
+  }
+
+  stop(): void {
+    if (this.store) {
+      this.store.stop();
+    }
+    this.store = undefined;
+    this.started = false;
+  }
+
+  /** Visible for tests and for the KV listener; validates before it prompts. */
+  onRequestPayload(payload: string): void {
+    const request = WatchProvisionProtocol.parseRequest(payload);
+    if (!request) {
+      // Nothing usable to answer — a malformed request has no request_id to
+      // address a response to, so silence is the only available reply.
+      RemoteLogger.warn('watch provisioning request ignored: malformed payload');
+      return;
+    }
+    if (this.answered.has(request.requestId)) {
+      return;
+    }
+    if (WatchProvisionProtocol.isExpired(request, Date.now())) {
+      RemoteLogger.info('watch provisioning request ignored: expired');
+      return;
+    }
+    if (this.pending && this.pending.requestId === request.requestId) {
+      return;
+    }
+    if (this.inFlight || (this.pending && this.pending.deviceId !== request.deviceId)) {
+      // One at a time: a second watch waiting behind a silent card would look
+      // identical to a phone that never heard it.
+      this.answered.add(request.requestId);
+      void this.writeError(request.requestId, RemoteI18n.t('watchProvision.busy'));
+      return;
+    }
+    if (this.pending) {
+      // The same watch asking again: it gave up on the last attempt and started
+      // over, and the card still up here is for a request nobody is waiting on.
+      // Replace it — telling a watch it is busy with itself is the one answer
+      // that cannot be true.
+      RemoteLogger.info('watch provisioning request replaced by a newer one from the same watch');
+      this.answered.add(this.pending.requestId);
+    }
+    this.pending = request;
+    this.state.ask(request.deviceName, request.deviceId);
+  }
+
+  async approve(): Promise<void> {
+    const request = this.pending;
+    if (!request || this.inFlight) {
+      return;
+    }
+    this.inFlight = true;
+    this.state.working();
+    try {
+      await this.runProvisioning(request);
+    } finally {
+      this.answered.add(request.requestId);
+      this.pending = undefined;
+      this.inFlight = false;
+    }
+  }
+
+  async reject(): Promise<void> {
+    const request = this.pending;
+    if (!request || this.inFlight) {
+      return;
+    }
+    this.answered.add(request.requestId);
+    this.pending = undefined;
+    this.state.hide();
+    await this.writeError(request.requestId, RemoteI18n.t('watchProvision.rejected'));
+  }
+
+  /** Closes the card after a finished attempt. Never cancels one in flight. */
+  dismiss(): void {
+    if (this.inFlight) {
+      return;
+    }
+    if (this.pending) {
+      void this.reject();
+      return;
+    }
+    this.state.hide();
+  }
+
+  private async runProvisioning(request: WatchProvisionRequest): Promise<void> {
+    if (!this.port.canProvision()) {
+      await this.failAttempt(request.requestId, RemoteI18n.t('watchProvision.errors.noDesktop'));
+      return;
+    }
+    let outcome: WatchProvisionOutcome;
+    try {
+      outcome = await this.port.provision(request.deviceId, request.deviceName, request.requestId);
+    } catch (err) {
+      RemoteLogger.error(`watch provisioning failed: ${WatchProvisionController.errorText(err)}`);
+      await this.failAttempt(request.requestId, RemoteI18n.t('watchProvision.errors.desktopUnreachable'));
+      return;
+    }
+    if (!outcome.ok) {
+      // A desktop that answered and refused knows why; a desktop that never
+      // answered is either offline or on a build that does not know this
+      // command, and the copy has to cover both because they look the same.
+      const message = outcome.desktopReported && outcome.failure.length > 0 ?
+        outcome.failure : RemoteI18n.t('watchProvision.errors.desktopUnreachable');
+      await this.failAttempt(request.requestId, message);
+      return;
+    }
+
+    if (outcome.relayUrl.trim().length === 0) {
+      // A credential with no relay to present it at is unusable, and the watch
+      // would only discover that after signing in. Stop here instead.
+      RemoteLogger.error('watch provisioning produced a credential without a relay url');
+      await this.failAttempt(request.requestId, RemoteI18n.t('watchProvision.errors.handoffFailed'));
+      return;
+    }
+    const credential: WatchProvisionCredential = {
+      relay_url: outcome.relayUrl,
+      token: outcome.token,
+      user_id: outcome.userId,
+      master_key: outcome.masterKeyBase64,
+      device_id: outcome.deviceId
+    };
+    try {
+      // Fresh key pair per attempt: a credential written to the shared store
+      // stays unreadable to anything but the watch that asked for it.
+      const crypto = new WatchProvisionCrypto();
+      const sealed = await crypto.seal(request.publicKeyBase64, JSON.stringify(credential));
+      await this.requireStore().writeResponse(WatchProvisionProtocol.successResponse(
+        request.requestId,
+        crypto.publicKeyBase64(),
+        sealed.encryptedData,
+        sealed.nonce
+      ));
+    } catch (err) {
+      // The device is registered on the account either way — the relay call
+      // already succeeded — so say so rather than implying nothing happened.
+      RemoteLogger.error(`watch provisioning handoff failed: ${WatchProvisionController.errorText(err)}`);
+      await this.failAttempt(request.requestId, RemoteI18n.t('watchProvision.errors.handoffFailed'));
+      return;
+    }
+    RemoteLogger.info('watch provisioning credential handed off');
+    this.state.done(RemoteI18n.f('watchProvision.doneBody', request.deviceName));
+  }
+
+  private async failAttempt(requestId: string, message: string): Promise<void> {
+    this.state.fail(message);
+    await this.writeError(requestId, message);
+  }
+
+  private async writeError(requestId: string, message: string): Promise<void> {
+    if (!this.store) {
+      return;
+    }
+    try {
+      await this.store.writeResponse(WatchProvisionProtocol.errorResponse(requestId, message));
+    } catch (err) {
+      // The watch falls back to its own timeout copy when no response lands.
+      RemoteLogger.warn(`watch provisioning error reply failed: ${WatchProvisionController.errorText(err)}`);
+    }
+  }
+
+  private requireStore(): WatchHandoffStore {
+    if (!this.store) {
+      throw new Error('Watch handoff store is not available.');
+    }
+    return this.store;
+  }
+
+  private static errorText(err: Object): string {
+    return err instanceof Error ? err.message : JSON.stringify(err);
+  }
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/WatchProvisionCrypto.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/WatchProvisionCrypto.ets
new file mode 100644
index 0000000000..c9f69a73b4
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/WatchProvisionCrypto.ets
@@ -0,0 +1,45 @@
+import { Encoding } from './Encoding';
+import { HarmonyRemoteCryptoCipher, RemoteCryptoCipher } from './RemoteCrypto';
+import { X25519, X25519KeyPair } from './X25519';
+
+export interface WatchSealedPayload {
+  encryptedData: string;
+  nonce: string;
+}
+
+/**
+ * Seals a provisioned credential to the watch's ephemeral public key.
+ *
+ * Same construction as the room channel — raw X25519 shared secret used
+ * directly as the AES-256-GCM key, ciphertext‖tag, base64 — so the watch can
+ * open it with the `CryptoService` it already has. A fresh key pair per
+ * provisioning attempt means a credential captured off the KV store stays
+ * unreadable even if the watch's stored keys later leak.
+ */
+export class WatchProvisionCrypto {
+  private readonly keyPair: X25519KeyPair;
+  private readonly cipher: RemoteCryptoCipher;
+
+  constructor(keyPair?: X25519KeyPair, cipher?: RemoteCryptoCipher) {
+    this.keyPair = keyPair || X25519.generateKeyPair();
+    this.cipher = cipher || new HarmonyRemoteCryptoCipher();
+  }
+
+  publicKeyBase64(): string {
+    return Encoding.bytesToBase64(this.keyPair.publicKey);
+  }
+
+  async seal(watchPublicKeyBase64: string, plaintext: string): Promise<WatchSealedPayload> {
+    const peerPublicKey = Encoding.base64ToBytes(watchPublicKeyBase64);
+    if (peerPublicKey.length !== 32) {
+      throw new Error('Watch public key must be 32 bytes.');
+    }
+    const key = X25519.scalarMult(this.keyPair.privateKey, peerPublicKey);
+    const nonce = Encoding.randomBytes(12);
+    const sealed = await this.cipher.encrypt(Encoding.utf8ToBytes(plaintext), key, nonce);
+    return {
+      encryptedData: Encoding.bytesToBase64(sealed),
+      nonce: Encoding.bytesToBase64(nonce)
+    };
+  }
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/WatchProvisionDisplay.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/WatchProvisionDisplay.ets
new file mode 100644
index 0000000000..e3db25bea0
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/WatchProvisionDisplay.ets
@@ -0,0 +1,8 @@
+/** Observable card the page owns. Model must not import pages/state. */
+export interface WatchProvisionDisplay {
+  ask(deviceName: string, deviceId: string): void;
+  working(): void;
+  done(message: string): void;
+  fail(message: string): void;
+  hide(): void;
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/WatchProvisionProtocol.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/WatchProvisionProtocol.ets
new file mode 100644
index 0000000000..b0529c3734
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/WatchProvisionProtocol.ets
@@ -0,0 +1,168 @@
+/**
+ * Wire format for the watch → phone → desktop device-provisioning handoff.
+ *
+ * The watch has no keyboard, so it cannot type an account password. Instead it
+ * writes a provisioning request into the distributed KV store both apps share
+ * (same bundle name, same store id), the phone asks its owner to confirm, and
+ * the phone relays the request to the paired desktop over the already
+ * encrypted room channel. The credential comes back through the same two keys.
+ *
+ * Only the credential itself is secret, and it is sealed to the watch's
+ * ephemeral X25519 public key before it is ever written, so neither the relay
+ * nor the KV replication layer sees the account master key in plaintext.
+ * Errors are written unsealed on purpose: the watch must be able to render
+ * them even when the failure was in key agreement.
+ */
+
+export const WATCH_PROVISION_REQUEST_KEY: string = 'bitfun.account.provision.request';
+export const WATCH_PROVISION_RESPONSE_KEY: string = 'bitfun.account.provision.response';
+export const WATCH_PROVISION_PROTOCOL_VERSION: number = 1;
+
+/**
+ * A request older than this is treated as abandoned. Without it, a request the
+ * watch never got to clear would re-open the confirmation card on every phone
+ * launch, long after whoever asked for it walked away.
+ */
+export const WATCH_PROVISION_REQUEST_TTL_MS: number = 5 * 60 * 1000;
+
+export const WATCH_PROVISION_STATUS_OK: string = 'ok';
+export const WATCH_PROVISION_STATUS_ERROR: string = 'error';
+
+/** As read off the KV store, before any field has been trusted. */
+export interface WatchProvisionRequestPayload {
+  v?: number;
+  request_id?: string;
+  device_id?: string;
+  device_name?: string;
+  public_key?: string;
+  created_ms?: number;
+}
+
+/** A request that passed every shape check the relay would apply later. */
+export interface WatchProvisionRequest {
+  requestId: string;
+  deviceId: string;
+  deviceName: string;
+  publicKeyBase64: string;
+  createdMs: number;
+}
+
+export interface WatchProvisionResponsePayload {
+  v: number;
+  request_id: string;
+  status: string;
+  message?: string;
+  public_key?: string;
+  nonce?: string;
+  encrypted_data?: string;
+}
+
+/** The plaintext sealed into `encrypted_data` of a successful response. */
+export interface WatchProvisionCredential {
+  relay_url: string;
+  token: string;
+  user_id: string;
+  master_key: string;
+  device_id: string;
+}
+
+/** Longest device name we will forward; the watch picks it, so bound it. */
+const MAX_DEVICE_NAME_LENGTH: number = 64;
+
+export class WatchProvisionProtocol {
+  /**
+   * Parse and fully validate a request. Returns `undefined` for anything we
+   * would not be able to act on, because a malformed request has no usable
+   * `request_id` to answer and silently ignoring it is the only option.
+   *
+   * The `device_id` rule mirrors the relay's exactly (32 lowercase hex): a
+   * request that would be refused at the far end is refused here, before the
+   * owner is asked to approve something that cannot succeed.
+   */
+  static parseRequest(payload: string): WatchProvisionRequest | undefined {
+    const text = payload.trim();
+    if (text.length === 0 || !text.startsWith('{')) {
+      return undefined;
+    }
+    let value: WatchProvisionRequestPayload;
+    try {
+      value = JSON.parse(text) as WatchProvisionRequestPayload;
+    } catch (_err) {
+      return undefined;
+    }
+    if ((value.v || 0) !== WATCH_PROVISION_PROTOCOL_VERSION) {
+      return undefined;
+    }
+    const requestId = (value.request_id || '').trim();
+    const deviceId = (value.device_id || '').trim();
+    const deviceName = (value.device_name || '').trim();
+    const publicKey = (value.public_key || '').trim();
+    if (!WatchProvisionProtocol.isUuid(requestId) || !WatchProvisionProtocol.isRelayDeviceId(deviceId)) {
+      return undefined;
+    }
+    if (deviceName.length === 0 || deviceName.length > MAX_DEVICE_NAME_LENGTH || publicKey.length === 0) {
+      return undefined;
+    }
+    return {
+      requestId,
+      deviceId,
+      deviceName,
+      publicKeyBase64: publicKey,
+      createdMs: value.created_ms || 0
+    };
+  }
+
+  /**
+   * A request is stale once it is older than the TTL. A watch clock running
+   * ahead of the phone yields a negative age and is accepted: clock skew
+   * between two devices on one account is not the user's problem to solve.
+   */
+  static isExpired(request: WatchProvisionRequest, nowMs: number): boolean {
+    if (request.createdMs <= 0) {
+      return true;
+    }
+    return nowMs - request.createdMs > WATCH_PROVISION_REQUEST_TTL_MS;
+  }
+
+  static successResponse(
+    requestId: string,
+    phonePublicKeyBase64: string,
+    encryptedData: string,
+    nonce: string
+  ): string {
+    const payload: WatchProvisionResponsePayload = {
+      v: WATCH_PROVISION_PROTOCOL_VERSION,
+      request_id: requestId,
+      status: WATCH_PROVISION_STATUS_OK,
+      public_key: phonePublicKeyBase64,
+      encrypted_data: encryptedData,
+      nonce
+    };
+    return JSON.stringify(payload);
+  }
+
+  static errorResponse(requestId: string, message: string): string {
+    const payload: WatchProvisionResponsePayload = {
+      v: WATCH_PROVISION_PROTOCOL_VERSION,
+      request_id: requestId,
+      status: WATCH_PROVISION_STATUS_ERROR,
+      message
+    };
+    return JSON.stringify(payload);
+  }
+
+  /** The relay rejects any `device_id` that is not 32 lowercase hex digits. */
+  static isRelayDeviceId(value: string): boolean {
+    return /^[0-9a-f]{32}$/.test(value);
+  }
+
+  /** The desktop parses `request_id` as a UUID before it calls the relay. */
+  static isUuid(value: string): boolean {
+    return /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/.test(value);
+  }
+
+  /** Short form for the confirmation card; the full id means nothing to a reader. */
+  static shortDeviceId(deviceId: string): string {
+    return deviceId.length <= 8 ? deviceId : deviceId.slice(0, 4) + '…' + deviceId.slice(deviceId.length - 4);
+  }
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/general-chat/MockGeneralChatAdapter.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/general-chat/MockGeneralChatAdapter.ets
index 90acc96ae5..9ce1177028 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/services/general-chat/MockGeneralChatAdapter.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/general-chat/MockGeneralChatAdapter.ets
@@ -101,11 +101,11 @@ export class MockGeneralChatAdapter implements GeneralChatPort {
     }
     if (MockGeneralChatAdapter.looksLikeCodeTask(normalized)) {
       return [
-        '这个问题可能需要 Code 能力来读取本地项目、运行命令或查看日志。',
+        '这个问题可能需要远程能力来读取本地项目、运行命令或查看日志。',
         '',
-        '如果只是要通用建议，我可以先给排查路径；如果要看本地仓库、改代码或运行命令，就应该从侧栏进入 Code。',
+        '如果只是要通用建议，我可以先给排查路径；如果要看本地仓库、改代码或运行命令，就应该从侧栏进入远程。',
         '',
-        '当前是 mock 回复。接入 BitFun harness 后，普通聊天会给出真实模型建议，Code 模块会继续负责本地 workspace 和工具执行。'
+        '当前是 mock 回复。接入 BitFun harness 后，普通聊天会给出真实模型建议，远程模块会继续负责本地 workspace 和工具执行。'
       ].join('\n');
     }
     if (normalized.indexOf('图片') >= 0 || normalized.toLowerCase().indexOf('image') >= 0) {
@@ -135,7 +135,7 @@ export class MockGeneralChatAdapter implements GeneralChatPort {
     return [
       `我收到了：${normalized}`,
       '',
-      '在手机端，BitFun 不应该只是普通聊天框，而是一个通用助手入口：可以问答、搜索资料、分析图片、处理文件、写作改写，也可以在需要本地项目能力时引导进入 Code。',
+      '在手机端，BitFun 不应该只是普通聊天框，而是一个通用助手入口：可以问答、搜索资料、分析图片、处理文件、写作改写，也可以在需要本地项目能力时引导进入远程。',
       '',
       '当前回复是 mock，用来验证移动端交互和流式 UI。下一步把这个 backend 替换为 BitFun harness 的普通聊天接口后，就会返回真实模型结果。'
     ].join('\n');
diff --git a/src/apps/mobile/harmonyos/entry/src/main/ets/services/general-chat/ModelProviderGeneralChatAdapter.ets b/src/apps/mobile/harmonyos/entry/src/main/ets/services/general-chat/ModelProviderGeneralChatAdapter.ets
index c5faf7efaa..2b1465abbe 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/ets/services/general-chat/ModelProviderGeneralChatAdapter.ets
+++ b/src/apps/mobile/harmonyos/entry/src/main/ets/services/general-chat/ModelProviderGeneralChatAdapter.ets
@@ -19,15 +19,33 @@ export const GENERAL_CHAT_SYSTEM_PROMPT: string = [
   'It is not a blockchain, gaming, NFT, cryptocurrency, or Web3 product. Never invent those product claims.',
   'Treat those product exclusions as internal factual constraints and do not mention them unless the user asks something directly related.',
   'Help with general questions, writing, summarization, planning, research preparation, and everyday work.',
+  'The user may attach images. When images are present, look at them and answer from what you can see.',
   'This mobile chat currently has no local workspace, shell, desktop file, web browsing, or external tool access.',
   'Never claim to have used unavailable tools or accessed information you were not given.',
   'When a task requires reading or changing a local repository, running commands, or accessing desktop files, explain that the user should use BitFun Remote/Code.',
   'Answer in the user\'s language. Be concise, concrete, and honest about uncertainty.'
 ].join('\n');
 
+export interface ModelProviderImageSource {
+  type: string;
+  media_type?: string;
+  data?: string;
+}
+
+export interface ModelProviderImageUrl {
+  url: string;
+}
+
+export interface ModelProviderContentPart {
+  type: string;
+  text?: string;
+  source?: ModelProviderImageSource;
+  image_url?: ModelProviderImageUrl;
+}
+
 export interface ModelProviderMessage {
   role: string;
-  content: string;
+  content: string | ModelProviderContentPart[];
 }
 
 interface AnthropicRequestBody {
@@ -261,9 +279,6 @@ export class ModelProviderGeneralChatAdapter implements GeneralChatPort {
     history: ChatMessage[] = [],
     observer?: GeneralChatStreamObserver
   ): Promise<GeneralChatSendResult> {
-    if (images.length > 0) {
-      throw new Error(RemoteI18n.t('generalChat.imageNotSupported'));
-    }
     const config = await this.configStore.activeSnapshot();
     const apiKey = (await this.configStore.activeAccessToken()).trim();
     if (config.apiUrl.length === 0 || config.modelName.length === 0 || apiKey.length === 0) {
@@ -277,14 +292,14 @@ export class ModelProviderGeneralChatAdapter implements GeneralChatPort {
       text: userText,
       status: 'pending',
       timestamp: new Date().toISOString(),
-      images: []
+      images: images.slice()
     };
     if (observer) {
       await observer.onUserMessage(userMessage);
     }
-    const messages = ModelProviderGeneralChatAdapter.toProviderMessages(history);
-    messages.push({ role: 'user', content: userText });
     const protocol = ModelProviderGeneralChatAdapter.resolveProtocol(config.apiUrl);
+    const messages = ModelProviderGeneralChatAdapter.toProviderMessages(history, protocol);
+    messages.push(ModelProviderGeneralChatAdapter.userProviderMessage(userText, images, protocol));
     const parser = new ModelProviderSseParser(protocol);
     const streamChunks: string[] = [];
     let assistantText = '';
@@ -495,19 +510,110 @@ export class ModelProviderGeneralChatAdapter implements GeneralChatPort {
     throw new Error(RemoteI18n.f('generalChat.requestFailed', `${statusCode}`));
   }
 
-  private static toProviderMessages(history: ChatMessage[]): ModelProviderMessage[] {
+  private static toProviderMessages(
+    history: ChatMessage[],
+    protocol: ModelProviderProtocol
+  ): ModelProviderMessage[] {
     const messages: ModelProviderMessage[] = [];
     history.forEach((message: ChatMessage) => {
-      const text = (message.text || '').trim();
       const status = (message.status || '').toLowerCase();
-      if (status !== 'failed' &&
-        (message.role === 'user' || message.role === 'assistant') && text.length > 0) {
-        messages.push({ role: message.role, content: text });
+      if (status === 'failed' || (message.role !== 'user' && message.role !== 'assistant')) {
+        return;
+      }
+      const text = (message.text || '').trim();
+      if (message.role === 'user') {
+        const providerMessage = ModelProviderGeneralChatAdapter.userProviderMessage(
+          text,
+          message.images || [],
+          protocol
+        );
+        if (ModelProviderGeneralChatAdapter.hasProviderContent(providerMessage)) {
+          messages.push(providerMessage);
+        }
+        return;
+      }
+      if (text.length > 0) {
+        messages.push({ role: 'assistant', content: text });
       }
     });
     return messages;
   }
 
+  private static userProviderMessage(
+    text: string,
+    images: ImageAttachment[],
+    protocol: ModelProviderProtocol
+  ): ModelProviderMessage {
+    const parts: ModelProviderContentPart[] = [];
+    if (protocol === ModelProviderProtocol.OpenAi && text.length > 0) {
+      parts.push({ type: 'text', text });
+    }
+    images.forEach((image: ImageAttachment) => {
+      const dataUrl = (image.data_url || '').trim();
+      if (dataUrl.length === 0) {
+        return;
+      }
+      const mediaType = ModelProviderGeneralChatAdapter.imageMediaType(dataUrl, image.mime_type);
+      const rawBase64 = ModelProviderGeneralChatAdapter.imageBase64(dataUrl);
+      if (rawBase64.length === 0) {
+        return;
+      }
+      if (protocol === ModelProviderProtocol.Anthropic) {
+        const source: ModelProviderImageSource = {
+          type: 'base64',
+          media_type: mediaType,
+          data: rawBase64
+        };
+        parts.push({ type: 'image', source });
+        return;
+      }
+      const imageUrl: ModelProviderImageUrl = {
+        url: dataUrl.indexOf('data:') === 0 ? dataUrl : `data:${mediaType};base64,${rawBase64}`
+      };
+      parts.push({ type: 'image_url', image_url: imageUrl });
+    });
+    if (protocol === ModelProviderProtocol.Anthropic && text.length > 0) {
+      parts.push({ type: 'text', text });
+    }
+    if (parts.length === 0) {
+      return { role: 'user', content: text };
+    }
+    if (parts.length === 1 && parts[0].type === 'text') {
+      return { role: 'user', content: text };
+    }
+    return { role: 'user', content: parts };
+  }
+
+  private static hasProviderContent(message: ModelProviderMessage): boolean {
+    if (typeof message.content === 'string') {
+      return message.content.trim().length > 0;
+    }
+    return message.content.length > 0;
+  }
+
+  private static imageMediaType(dataUrl: string, explicitMime?: string): string {
+    const trimmed = (explicitMime || '').trim();
+    if (trimmed.length > 0) {
+      return trimmed;
+    }
+    if (dataUrl.indexOf('data:') === 0) {
+      const semicolon = dataUrl.indexOf(';');
+      if (semicolon > 5) {
+        return dataUrl.slice(5, semicolon);
+      }
+    }
+    return 'image/jpeg';
+  }
+
+  private static imageBase64(dataUrl: string): string {
+    const marker = ';base64,';
+    const index = dataUrl.indexOf(marker);
+    if (index >= 0) {
+      return dataUrl.slice(index + marker.length);
+    }
+    return dataUrl;
+  }
+
   private static titleFromMessage(text: string): string {
     const normalized = text.trim().replace(/\s+/g, ' ');
     if (normalized.length === 0) {
diff --git a/src/apps/mobile/harmonyos/entry/src/main/module.json5 b/src/apps/mobile/harmonyos/entry/src/main/module.json5
index 33f39ae8e9..5f188dd415 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/module.json5
+++ b/src/apps/mobile/harmonyos/entry/src/main/module.json5
@@ -17,6 +17,16 @@
       {
         "name": "ohos.permission.GET_NETWORK_INFO"
       },
+      {
+        "name": "ohos.permission.DISTRIBUTED_DATASYNC",
+        "reason": "$string:permission_distributed_datasync_reason",
+        "usedScene": {
+          "abilities": [
+            "EntryAbility"
+          ],
+          "when": "inuse"
+        }
+      },
       {
         "name": "ohos.permission.CAMERA",
         "reason": "$string:permission_camera_reason",
diff --git a/src/apps/mobile/harmonyos/entry/src/main/resources/base/element/string.json b/src/apps/mobile/harmonyos/entry/src/main/resources/base/element/string.json
index 6d763ce34a..cc62308be9 100644
--- a/src/apps/mobile/harmonyos/entry/src/main/resources/base/element/string.json
+++ b/src/apps/mobile/harmonyos/entry/src/main/resources/base/element/string.json
@@ -23,6 +23,10 @@
     {
       "name": "permission_microphone_reason",
       "value": "用于在会话详情页将语音转成待发送文字。"
+    },
+    {
+      "name": "permission_distributed_datasync_reason",
+      "value": "用于把 BitFun 账号授权给同账号下的手表，免去在手表上输入密码。"
     }
   ]
 }
diff --git a/src/apps/mobile/harmonyos/entry/src/ohosTest/ets/test/DeviceSmoke.test.ets b/src/apps/mobile/harmonyos/entry/src/ohosTest/ets/test/DeviceSmoke.test.ets
index 5f64efebf6..61756211d5 100644
--- a/src/apps/mobile/harmonyos/entry/src/ohosTest/ets/test/DeviceSmoke.test.ets
+++ b/src/apps/mobile/harmonyos/entry/src/ohosTest/ets/test/DeviceSmoke.test.ets
@@ -2,7 +2,7 @@ import { Want } from '@kit.AbilityKit';
 import { Driver, ON, abilityDelegatorRegistry } from '@kit.TestKit';
 import { describe, it, expect } from '@ohos/hypium';
 
-const APP_BUNDLE: string = 'com.example.bitfun_mobile';
+const APP_BUNDLE: string = 'com.bitfun.app';
 const APP_ABILITY: string = 'EntryAbility';
 
 export default function deviceSmokeTest() {
@@ -21,7 +21,7 @@ export default function deviceSmokeTest() {
 
       await driver.click(130, 180);
       await driver.delayMs(300);
-      const remoteEntry = await driver.findComponent(ON.text('Remote'));
+      const remoteEntry = await driver.findComponent(ON.id('conversation-source-remote'));
       expect(remoteEntry !== undefined).assertTrue();
       await remoteEntry.click();
       await driver.delayMs(900);
diff --git a/src/apps/mobile/harmonyos/entry/src/test/ArchitectureUnit.test.ets b/src/apps/mobile/harmonyos/entry/src/test/ArchitectureUnit.test.ets
index 4161ebe9fd..1f982f5755 100644
--- a/src/apps/mobile/harmonyos/entry/src/test/ArchitectureUnit.test.ets
+++ b/src/apps/mobile/harmonyos/entry/src/test/ArchitectureUnit.test.ets
@@ -93,6 +93,19 @@ export default function architectureUnitTest() {
       expect(shell.navigationStack.getAllPathName().length).assertEqual(1);
     });
 
+    // Switching sessions is a state change, not a navigation. Treating the
+    // session id as part of the destination made every row tap clear the stack
+    // and push a fresh one, and on the wide layout the master pane lives inside
+    // that destination — so the whole sidebar was rebuilt on each tap.
+    it('keeps a session switch from rebuilding the chat destination', 0, () => {
+      const shell = new AppShellViewModel();
+      shell.pushRoute(AppRoute.RemoteHome);
+      shell.pushRoute(AppRoute.RemoteChat, 'session-a');
+      shell.replaceRouteWithoutAnimation(AppRoute.RemoteChat, 'session-b');
+      expect(shell.currentRoute()).assertEqual(AppRoute.RemoteChat);
+      expect(shell.navigationStack.getAllPathName().length).assertEqual(2);
+    });
+
     it('keeps wide layout geometry pure and deterministic', 0, () => {
       expect(WideLayoutGeometry.detailOffset(false, 24, 8)).assertEqual(24);
       expect(WideLayoutGeometry.detailOffset(true, 24, 8)).assertEqual(8);
diff --git a/src/apps/mobile/harmonyos/entry/src/test/ConversationPresentationUnit.test.ets b/src/apps/mobile/harmonyos/entry/src/test/ConversationPresentationUnit.test.ets
new file mode 100644
index 0000000000..33238c0154
--- /dev/null
+++ b/src/apps/mobile/harmonyos/entry/src/test/ConversationPresentationUnit.test.ets
@@ -0,0 +1,487 @@
+import { describe, it, expect } from '@ohos/hypium';
+import { RemoteI18n } from '../main/ets/i18n/RemoteI18n';
+import { ChatComposerPolicy, ComposerPrimaryAction } from '../main/ets/services/ChatComposerPolicy';
+import { ChatSurface } from '../main/ets/pages/state/ChatSurface';
+import {
+  GENERAL_CHAT_COMPOSER_CAPABILITIES,
+  REMOTE_CHAT_COMPOSER_CAPABILITIES,
+  REMOTE_CREATE_COMPOSER_CAPABILITIES
+} from '../main/ets/pages/state/ChatComposerCapabilities';
+import { ConversationViewState } from '../main/ets/pages/state/ConversationViewState';
+import { GeneralChatPageState } from '../main/ets/pages/state/GeneralChatPageState';
+import { RemoteCreateSessionState } from '../main/ets/pages/state/RemoteCreateSessionState';
+import { RemotePageState } from '../main/ets/pages/state/RemotePageState';
+import { AppRoute } from '../main/ets/pages/navigation/AppRouteContract';
+import { ConversationHeaderPolicy } from '../main/ets/pages/policy/ConversationHeaderPolicy';
+import { ThinkingPresentationPolicy } from '../main/ets/pages/policy/ThinkingPresentationPolicy';
+import { ActivityGroupPolicy } from '../main/ets/pages/policy/ActivityGroupPolicy';
+import { AssistantProcessLayoutPolicy } from '../main/ets/pages/policy/AssistantProcessLayoutPolicy';
+import { ConversationMessageRenderPolicy } from '../main/ets/pages/policy/ConversationMessageRenderPolicy';
+import { ToolCollapsePolicy } from '../main/ets/pages/policy/ToolCollapsePolicy';
+import { ConversationUiMessage, ConversationUiToolStatus } from '../main/ets/pages/state/ConversationUiModels';
+import {
+  ConnectSheetLandingPolicy,
+  ConnectSheetStatusPolicy,
+  ConnectSheetStep
+} from '../main/ets/pages/policy/ConnectSheetLandingPolicy';
+import {
+  RemoteConnectEntryKind,
+  RemoteSurfaceEntryPolicy
+} from '../main/ets/pages/policy/RemoteSurfaceEntryPolicy';
+import { RemoteCompactHomePolicy } from '../main/ets/pages/policy/RemoteCompactHomePolicy';
+import { AccountDeviceSelectionPolicy } from '../main/ets/pages/policy/AccountDeviceSelectionPolicy';
+import { CONNECT_INTENT_AUTO, CONNECT_INTENT_SCAN } from '../main/ets/pages/state/AppShellState';
+import {
+  ConnectScanDecisionPolicy,
+  DetectedUrlAction
+} from '../main/ets/services/ConnectScanDecisionPolicy';
+
+export default function conversationPresentationUnitTest() {
+  describe('Local conversation empty home', () => {
+    it('keeps local chat on a blank timeline instead of suggestion chips', 0, () => {
+      const projection = ConversationViewState.project(
+        AppRoute.ChatHome,
+        new RemotePageState(),
+        new GeneralChatPageState(),
+        ''
+      );
+
+      expect(projection.surface).assertEqual(ChatSurface.General);
+      expect(projection.showSuggestionsWhenEmpty).assertFalse();
+      expect(projection.timelineItems.length).assertEqual(0);
+    });
+  });
+
+  describe('ThinkingPresentationPolicy', () => {
+    it('treats active and running as in-progress thinking', 0, () => {
+      expect(ThinkingPresentationPolicy.isRunning('active')).assertTrue();
+      expect(ThinkingPresentationPolicy.isRunning('running')).assertTrue();
+      expect(ThinkingPresentationPolicy.isRunning('ACTIVE')).assertTrue();
+      expect(ThinkingPresentationPolicy.isRunning('complete')).assertFalse();
+      expect(ThinkingPresentationPolicy.isRunning('')).assertFalse();
+    });
+
+    it('hides the block when thinking is done and the body is empty', 0, () => {
+      expect(ThinkingPresentationPolicy.shouldRender('complete', '')).assertFalse();
+      expect(ThinkingPresentationPolicy.shouldRender('complete', '   ')).assertFalse();
+    });
+
+    it('keeps the block visible while running or when a body remains', 0, () => {
+      expect(ThinkingPresentationPolicy.shouldRender('running', '')).assertTrue();
+      expect(ThinkingPresentationPolicy.shouldRender('complete', '先看现有会话结构')).assertTrue();
+    });
+
+    it('expands by default only while running unless keepExpandedWhenDone is set', 0, () => {
+      expect(ThinkingPresentationPolicy.defaultExpanded(true, false)).assertTrue();
+      expect(ThinkingPresentationPolicy.defaultExpanded(false, false)).assertFalse();
+      expect(ThinkingPresentationPolicy.defaultExpanded(false, true)).assertTrue();
+    });
+
+    it('lets the user collapse live thinking and folds it when the turn moves on', 0, () => {
+      expect(ThinkingPresentationPolicy.allowsToggle(true)).assertTrue();
+      expect(ThinkingPresentationPolicy.allowsToggle(false)).assertFalse();
+      expect(ThinkingPresentationPolicy.expandedForStatus(true, false, false, false)).assertTrue();
+      expect(ThinkingPresentationPolicy.expandedForStatus(true, false, true, false)).assertFalse();
+      expect(ThinkingPresentationPolicy.expandedForStatus(false, false, true, true)).assertFalse();
+      expect(ThinkingPresentationPolicy.expandedForStatus(false, true, false, true)).assertTrue();
+    });
+
+    it('marks leading thinking done once tools or answer text have started', 0, () => {
+      expect(ThinkingPresentationPolicy.liveThinkingStatus('active', false)).assertEqual('active');
+      expect(ThinkingPresentationPolicy.liveThinkingStatus('active', true)).assertEqual('done');
+      expect(ThinkingPresentationPolicy.liveThinkingStatus('running', true)).assertEqual('done');
+    });
+
+    it('folds consecutive thinking segments into one body', 0, () => {
+      expect(ThinkingPresentationPolicy.mergedText(['先看结构', '', '再跑工具'])).assertEqual('先看结构\n\n再跑工具');
+      expect(ThinkingPresentationPolicy.mergedStatusValue(['done', 'done'], [false, false])).assertEqual('done');
+      expect(ThinkingPresentationPolicy.mergedStatusValue(['done', 'active'], [false, true])).assertEqual('active');
+      expect(ThinkingPresentationPolicy.mergedStreaming([false, false, true])).assertTrue();
+      expect(ThinkingPresentationPolicy.mergedStreaming([false, false])).assertFalse();
+    });
+  });
+
+  describe('ActivityGroupPolicy', () => {
+    it('keeps consecutive thinking and completed tools in one foldable group', 0, () => {
+      expect(ActivityGroupPolicy.shouldFoldEntry(true, false)).assertTrue();
+      expect(ActivityGroupPolicy.shouldFoldEntry(false, false, toolStatus('1', 'Grep', 'completed'))).assertTrue();
+      expect(ActivityGroupPolicy.shouldFoldEntry(false, false, toolStatus('2', 'ExecCommand', 'done'))).assertTrue();
+      expect(ActivityGroupPolicy.thinkingHeaderCount(4)).assertEqual(1);
+    });
+
+    it('does not swallow Task cards, questions, or live tools into the thinking group', 0, () => {
+      expect(ActivityGroupPolicy.shouldFoldEntry(false, true, toolStatus('1', 'Task', 'completed'))).assertFalse();
+      expect(ActivityGroupPolicy.shouldFoldEntry(false, false, toolStatus('2', 'AskUserQuestion', 'completed'))).assertFalse();
+      expect(ActivityGroupPolicy.shouldFoldEntry(false, false, toolStatus('3', 'Grep', 'running'))).assertFalse();
+      expect(ActivityGroupPolicy.thinkingHeaderCount(0)).assertEqual(0);
+    });
+  });
+
+  describe('ConversationMessageRenderPolicy', () => {
+    it('does not throw when assistant text is missing and still shows structured content', 0, () => {
+      expect(ConversationMessageRenderPolicy.visibleText(undefined)).assertEqual('');
+      expect(ConversationMessageRenderPolicy.visibleText('(空消息)')).assertEqual('');
+      const item: ConversationUiMessage = {
+        id: 'a1',
+        role: 'assistant',
+        text: '',
+        status: 'done',
+        items: [{ type: 'thinking', content: '先看仓库结构' }]
+      };
+      expect(ConversationMessageRenderPolicy.shouldRender(item)).assertTrue();
+    });
+
+    it('hides an assistant row that has no text, thinking, tools, or items', 0, () => {
+      const item: ConversationUiMessage = {
+        id: 'a2',
+        role: 'assistant',
+        text: '',
+        status: 'done'
+      };
+      expect(ConversationMessageRenderPolicy.shouldRender(item)).assertFalse();
+    });
+  });
+
+  describe('AssistantProcessLayoutPolicy', () => {
+    it('does not pin thinking below tools or omit in-flow thinking while streaming', 0, () => {
+      expect(AssistantProcessLayoutPolicy.pinsThinkingAfterTools()).assertFalse();
+      expect(AssistantProcessLayoutPolicy.omitsInFlowThinkingWhileStreaming()).assertFalse();
+    });
+
+    it('keeps a live Task card below the thinking that produced it', 0, () => {
+      const order = AssistantProcessLayoutPolicy.processBlockOrder(
+        '先看现有会话结构',
+        false,
+        '',
+        false,
+        1
+      );
+      expect(order.length).assertEqual(2);
+      expect(order[0]).assertEqual('thinking');
+      expect(order[1]).assertEqual('tools');
+    });
+
+    it('keeps thinking above tools when assistant text has also started', 0, () => {
+      const order = AssistantProcessLayoutPolicy.processBlockOrder(
+        '先看现有会话结构',
+        true,
+        '已经开始改布局',
+        false,
+        1
+      );
+      expect(order[0]).assertEqual('thinking');
+      expect(order[1]).assertEqual('tools');
+      expect(order[2]).assertEqual('text');
+    });
+
+    it('renders activity-group thinking before folded read or search cards', 0, () => {
+      const order = AssistantProcessLayoutPolicy.activityGroupBlockOrder(true, 2);
+      expect(order.length).assertEqual(2);
+      expect(order[0]).assertEqual('thinking');
+      expect(order[1]).assertEqual('tools');
+    });
+
+    it('still renders completed thinking inside an activity group', 0, () => {
+      expect(AssistantProcessLayoutPolicy.shouldRenderActivityThinking(true)).assertTrue();
+      expect(AssistantProcessLayoutPolicy.shouldRenderActivityThinking(false)).assertFalse();
+    });
+
+    it('shows typing dots only when the live turn has no thinking or tools yet', 0, () => {
+      const order = AssistantProcessLayoutPolicy.processBlockOrder('', false, '', true, 0);
+      expect(order.length).assertEqual(1);
+      expect(order[0]).assertEqual('typing');
+    });
+
+    it('keeps a tool-only activity group without inventing a thinking block', 0, () => {
+      const order = AssistantProcessLayoutPolicy.activityGroupBlockOrder(false, 1);
+      expect(order.length).assertEqual(1);
+      expect(order[0]).assertEqual('tools');
+    });
+  });
+
+  describe('ToolCollapsePolicy', () => {
+    it('folds consecutive completed tools of any kind into one summary', 0, () => {
+      const groups = ToolCollapsePolicy.collapsedGroups([
+        toolStatus('1', 'Grep', 'completed'),
+        toolStatus('2', 'ExecCommand', 'done'),
+        toolStatus('3', 'Task', 'success')
+      ]);
+      expect(groups.length).assertEqual(1);
+      expect(groups[0].type).assertEqual('summary');
+      expect(groups[0].tools.length).assertEqual(3);
+    });
+
+    it('keeps a single completed tool as its own row', 0, () => {
+      const groups = ToolCollapsePolicy.collapsedGroups([
+        toolStatus('1', 'ExecCommand', 'completed')
+      ]);
+      expect(groups.length).assertEqual(1);
+      expect(groups[0].type).assertEqual('tool');
+    });
+
+    it('does not fold running, failed, or blocking tools into the summary', 0, () => {
+      const groups = ToolCollapsePolicy.collapsedGroups([
+        toolStatus('1', 'Grep', 'completed'),
+        toolStatus('2', 'Read', 'completed'),
+        toolStatus('3', 'ExecCommand', 'running'),
+        toolStatus('4', 'AskUserQuestion', 'pending'),
+        toolStatus('5', 'Write', 'failed')
+      ]);
+      expect(groups.length).assertEqual(4);
+      expect(groups[0].type).assertEqual('summary');
+      expect(groups[0].tools.length).assertEqual(2);
+      expect(groups[1].type).assertEqual('tool');
+      expect(groups[1].tools[0].name).assertEqual('ExecCommand');
+      expect(groups[2].tools[0].name).assertEqual('AskUserQuestion');
+      expect(groups[3].tools[0].name).assertEqual('Write');
+    });
+
+    it('expands a subagent card only while that task is running', 0, () => {
+      expect(ToolCollapsePolicy.defaultSubagentExpanded(true)).assertTrue();
+      expect(ToolCollapsePolicy.defaultSubagentExpanded(false)).assertFalse();
+      expect(ToolCollapsePolicy.subagentExpandedForStatus(true, true, false)).assertFalse();
+      expect(ToolCollapsePolicy.subagentExpandedForStatus(false, true, true)).assertFalse();
+    });
+
+    it('keeps the summary row and lists members when the group is expanded', 0, () => {
+      const groups = ToolCollapsePolicy.expandedGroups([
+        toolStatus('1', 'Grep', 'completed'),
+        toolStatus('2', 'ExecCommand', 'completed')
+      ]);
+      expect(groups.length).assertEqual(3);
+      expect(groups[0].type).assertEqual('summary');
+      expect(groups[1].type).assertEqual('tool');
+      expect(groups[2].type).assertEqual('tool');
+    });
+  });
+
+  describe('ChatComposerPolicy add button', () => {
+    it('hides the add control unless attachments are supported', 0, () => {
+      expect(ChatComposerPolicy.shouldShowAddButton(true, false)).assertFalse();
+      expect(ChatComposerPolicy.shouldShowAddButton(false, true)).assertFalse();
+      expect(ChatComposerPolicy.shouldShowAddButton(true, true)).assertTrue();
+    });
+
+    it('lets local chat pick images because the composer can honour attachments', 0, () => {
+      expect(GENERAL_CHAT_COMPOSER_CAPABILITIES.surface).assertEqual(ChatSurface.General);
+      expect(GENERAL_CHAT_COMPOSER_CAPABILITIES.supportsAttachments).assertTrue();
+      expect(GENERAL_CHAT_COMPOSER_CAPABILITIES.showAddButton).assertTrue();
+      expect(ChatComposerPolicy.shouldShowAddButton(
+        GENERAL_CHAT_COMPOSER_CAPABILITIES.showAddButton,
+        GENERAL_CHAT_COMPOSER_CAPABILITIES.supportsAttachments
+      )).assertTrue();
+      expect(REMOTE_CHAT_COMPOSER_CAPABILITIES.showAddButton).assertTrue();
+      expect(REMOTE_CHAT_COMPOSER_CAPABILITIES.supportsAttachments).assertTrue();
+    });
+
+    it('names the primary composer action for assistive labels', 0, () => {
+      expect(ChatComposerPolicy.primaryActionAccessibilityKey(ComposerPrimaryAction.Send, false))
+        .assertEqual('chat.send');
+      expect(ChatComposerPolicy.primaryActionAccessibilityKey(ComposerPrimaryAction.Stop, false))
+        .assertEqual('chat.stop');
+      expect(ChatComposerPolicy.primaryActionAccessibilityKey(ComposerPrimaryAction.Stop, true))
+        .assertEqual('chat.stopListening');
+      expect(ChatComposerPolicy.primaryActionAccessibilityKey(ComposerPrimaryAction.Voice, false))
+        .assertEqual('chat.voiceInput');
+    });
+  });
+
+  describe('Conversation source naming', () => {
+    it('uses the same local/remote pair across the switcher and remote chrome', 0, () => {
+      expect(RemoteI18n.t('sidebar.local')).assertEqual('本地');
+      expect(RemoteI18n.t('sidebar.code')).assertEqual('远程');
+      expect(RemoteI18n.t('sidebar.code')).assertEqual(RemoteI18n.t('remote.title'));
+      expect(RemoteI18n.t('connect.accountDevicesSubtitle')).assertEqual('远程');
+      expect(RemoteI18n.t('chat.remoteSession')).assertEqual('远程会话');
+    });
+
+    it('does not keep leftover pending-copy keys that claim general chat is unavailable', 0, () => {
+      expect(RemoteI18n.t('chatHome.generalPending')).assertEqual('chatHome.generalPending');
+      expect(RemoteI18n.t('chatHome.generalAdvicePending')).assertEqual('chatHome.generalAdvicePending');
+    });
+  });
+
+  describe('ConnectSheetLandingPolicy', () => {
+    it('opens unsigned-in automatic entry on the explainer, not the camera', 0, () => {
+      expect(ConnectSheetLandingPolicy.initialStep(CONNECT_INTENT_AUTO, false))
+        .assertEqual(ConnectSheetStep.Intro);
+      expect(ConnectSheetLandingPolicy.initialStep(CONNECT_INTENT_AUTO, true))
+        .assertEqual(ConnectSheetStep.Account);
+      expect(ConnectSheetLandingPolicy.initialStep(CONNECT_INTENT_SCAN, false))
+        .assertEqual(ConnectSheetStep.Scan);
+      expect(ConnectSheetLandingPolicy.initialStep(CONNECT_INTENT_SCAN, true))
+        .assertEqual(ConnectSheetStep.Scan);
+    });
+
+    it('keeps the current pairing step while a URL is present or pairing is busy', 0, () => {
+      expect(ConnectSheetLandingPolicy.visibleStep(ConnectSheetStep.Intro, false))
+        .assertEqual(ConnectSheetStep.Intro);
+      expect(ConnectSheetLandingPolicy.visibleStep(ConnectSheetStep.Scan, false))
+        .assertEqual(ConnectSheetStep.Scan);
+      expect(ConnectSheetLandingPolicy.visibleStep(ConnectSheetStep.Account, true))
+        .assertEqual(ConnectSheetStep.Account);
+      expect(ConnectSheetLandingPolicy.visibleStep(ConnectSheetStep.Account, false))
+        .assertEqual(ConnectSheetStep.Intro);
+    });
+
+    it('maps a failed pair to the matching reconnect hint', 0, () => {
+      expect(ConnectSheetStatusPolicy.failureHintKey('expired_room'))
+        .assertEqual('connect.hintExpiredRoom');
+      expect(ConnectSheetStatusPolicy.failureHintKey('network'))
+        .assertEqual('connect.hintNetwork');
+      expect(ConnectSheetStatusPolicy.isConnectError('failed', false, false, '', '失败', '', ''))
+        .assertTrue();
+      expect(ConnectSheetStatusPolicy.isConnectError('pairing', true, false, '', '失败', '', ''))
+        .assertFalse();
+    });
+  });
+
+  describe('RemoteSurfaceEntryPolicy', () => {
+    it('treats switching to remote as navigation and keeps connect as an explicit action', 0, () => {
+      expect(RemoteSurfaceEntryPolicy.shouldOpenConnectSheet(RemoteConnectEntryKind.EnterSurface))
+        .assertFalse();
+      expect(RemoteSurfaceEntryPolicy.shouldOpenConnectSheet(RemoteConnectEntryKind.OpenConnect))
+        .assertTrue();
+      expect(RemoteSurfaceEntryPolicy.shouldOpenConnectSheet(RemoteConnectEntryKind.OpenScan))
+        .assertTrue();
+    });
+  });
+
+  describe('RemoteCompactHomePolicy', () => {
+    it('keeps pick-session chrome only while the desktop link is actually connected', 0, () => {
+      expect(RemoteCompactHomePolicy.shouldShowConnectHome('connected')).assertFalse();
+    });
+
+    it('opens the connect home after the desktop drops even when cached sessions remain', 0, () => {
+      expect(RemoteCompactHomePolicy.shouldShowConnectHome('reconnecting')).assertTrue();
+      expect(RemoteCompactHomePolicy.shouldShowConnectHome('failed')).assertTrue();
+      expect(RemoteCompactHomePolicy.shouldShowConnectHome('disconnected')).assertTrue();
+      expect(RemoteCompactHomePolicy.shouldShowConnectHome('idle')).assertTrue();
+      expect(RemoteCompactHomePolicy.headerSubtitle('reconnecting', 'Studio')).assertEqual('');
+      expect(RemoteCompactHomePolicy.headerSubtitle('connected', 'Studio')).assertEqual('Studio');
+    });
+  });
+
+  describe('AccountDeviceSelectionPolicy', () => {
+    it('lets an online desktop be selected unless this phone is already switching', 0, () => {
+      expect(AccountDeviceSelectionPolicy.canSelectOnline(true, 'desk-1', 'phone-1', '')).assertTrue();
+      expect(AccountDeviceSelectionPolicy.canSelectOnline(false, 'desk-1', 'phone-1', '')).assertFalse();
+      expect(AccountDeviceSelectionPolicy.canSelectOnline(true, 'phone-1', 'phone-1', '')).assertFalse();
+      expect(AccountDeviceSelectionPolicy.canSelectOnline(true, 'desk-1', 'phone-1', 'desk-1')).assertFalse();
+    });
+
+    it('offers connect on device management for another online desktop or the last target after drop', 0, () => {
+      expect(AccountDeviceSelectionPolicy.shouldShowConnectAction(true, 'desk-1', 'phone-1', 'desk-1', 'connected'))
+        .assertFalse();
+      expect(AccountDeviceSelectionPolicy.shouldShowConnectAction(true, 'desk-1', 'phone-1', 'desk-1', 'failed'))
+        .assertTrue();
+      expect(AccountDeviceSelectionPolicy.shouldShowConnectAction(true, 'desk-2', 'phone-1', 'desk-1', 'connected'))
+        .assertTrue();
+      expect(AccountDeviceSelectionPolicy.shouldShowConnectAction(false, 'desk-1', 'phone-1', 'desk-1', 'failed'))
+        .assertTrue();
+      expect(AccountDeviceSelectionPolicy.shouldShowConnectAction(false, 'desk-2', 'phone-1', 'desk-1', 'failed'))
+        .assertFalse();
+    });
+
+    it('reconnects the last control target when it is no longer live', 0, () => {
+      expect(AccountDeviceSelectionPolicy.shouldReconnectLastTarget('desk-1', 'desk-1', 'failed')).assertTrue();
+      expect(AccountDeviceSelectionPolicy.shouldReconnectLastTarget('desk-1', 'desk-1', 'connected')).assertFalse();
+      expect(AccountDeviceSelectionPolicy.shouldReconnectLastTarget('desk-2', 'desk-1', 'failed')).assertFalse();
+    });
+  });
+
+  describe('ConnectScanDecisionPolicy', () => {
+    it('pairs an ordinary QR immediately without asking for an account password', 0, () => {
+      expect(ConnectScanDecisionPolicy.decide(false, false, '', '', ''))
+        .assertEqual(DetectedUrlAction.PAIR_NOW);
+      expect(ConnectScanDecisionPolicy.decide(false, true, 'alice', '', 'desktop-1'))
+        .assertEqual(DetectedUrlAction.PAIR_NOW);
+    });
+
+    it('asks for a password only when the QR needs account auth and this phone is signed out', 0, () => {
+      expect(ConnectScanDecisionPolicy.decide(true, false, '', 'alice', 'desktop-1'))
+        .assertEqual(DetectedUrlAction.PROMPT_ACCOUNT_PASSWORD);
+    });
+
+    it('reuses the signed-in cloud session instead of asking for the password again', 0, () => {
+      expect(ConnectScanDecisionPolicy.decide(true, true, 'alice', 'alice', 'desktop-1'))
+        .assertEqual(DetectedUrlAction.USE_CLOUD_DEVICE);
+      expect(ConnectScanDecisionPolicy.decide(true, true, 'alice', 'alice', ''))
+        .assertEqual(DetectedUrlAction.SHOW_CLOUD_DEVICES);
+      expect(ConnectScanDecisionPolicy.decide(true, true, 'alice', '', 'desktop-1'))
+        .assertEqual(DetectedUrlAction.USE_CLOUD_DEVICE);
+    });
+
+    it('still asks for a password when the QR belongs to a different account', 0, () => {
+      expect(ConnectScanDecisionPolicy.decide(true, true, 'alice', 'bob', 'desktop-1'))
+        .assertEqual(DetectedUrlAction.PROMPT_ACCOUNT_PASSWORD);
+    });
+  });
+
+  describe('ConversationHeaderPolicy', () => {
+    it('keeps local chat on a single-line title and only shows actions once a timeline exists', 0, () => {
+      const empty = ConversationHeaderPolicy.present(ChatSurface.General, '今日计划', '', '', false);
+      expect(empty.fallbackKey).assertEqual('app.title');
+      expect(empty.title).assertEqual('今日计划');
+      expect(empty.subtitle).assertEqual('');
+      expect(empty.allowRename).assertFalse();
+      expect(empty.showActions).assertFalse();
+      const withTimeline = ConversationHeaderPolicy.present(ChatSurface.General, '今日计划', '', '', true);
+      expect(withTimeline.showActions).assertTrue();
+    });
+
+    it('gives remote chat a subtitle, rename, and a persistent overflow control', 0, () => {
+      const named = ConversationHeaderPolicy.present(ChatSurface.Remote, '修登录', 'Studio', 'main', false);
+      expect(named.fallbackKey).assertEqual('chat.remoteSession');
+      expect(named.subtitle).assertEqual('Studio');
+      expect(named.allowRename).assertTrue();
+      expect(named.showActions).assertTrue();
+      const branded = ConversationHeaderPolicy.present(ChatSurface.Remote, '', '', 'feat/ui', false);
+      expect(branded.subtitle).assertEqual('BitFun · feat/ui');
+    });
+
+    it('treats create as a titled conversation chrome without actions or rename', 0, () => {
+      const create = ConversationHeaderPolicy.present(ChatSurface.Create, 'ignored', 'Studio', 'main', true);
+      expect(create.fallbackKey).assertEqual('remote.create.title');
+      expect(create.title).assertEqual('');
+      expect(create.subtitle).assertEqual('');
+      expect(create.allowRename).assertFalse();
+      expect(create.showActions).assertFalse();
+    });
+  });
+
+  describe('Create conversation projection', () => {
+    it('projects remote create onto the shared conversation view with create capabilities', 0, () => {
+      const remote = new RemotePageState();
+      remote.desktopName = 'Studio';
+      const create = new RemoteCreateSessionState();
+      create.setDraft('hello from create');
+      create.setSelectedModelId('model-1');
+      create.isSubmitting = true;
+      create.errorText = 'device mismatch';
+      const projection = ConversationViewState.project(
+        AppRoute.RemoteCreate,
+        remote,
+        new GeneralChatPageState(),
+        '',
+        create
+      );
+      expect(projection.surface).assertEqual(ChatSurface.Create);
+      expect(projection.composerCapabilities.supportsAttachments).assertFalse();
+      expect(projection.composerCapabilities.showAddButton).assertFalse();
+      expect(projection.chatInput).assertEqual('hello from create');
+      expect(projection.isBusy).assertTrue();
+      expect(projection.inlineStatusText).assertEqual('device mismatch');
+      expect(projection.timelineItems.length).assertEqual(0);
+      expect(projection.desktopName).assertEqual('Studio');
+    });
+  });
+}
+
+function toolStatus(id: string, name: string, status: string): ConversationUiToolStatus {
+  return {
+    id,
+    name,
+    status
+  };
+}
diff --git a/src/apps/mobile/harmonyos/entry/src/test/ConversationStateUnit.test.ets b/src/apps/mobile/harmonyos/entry/src/test/ConversationStateUnit.test.ets
index 57de0bb8df..d58ad9167f 100644
--- a/src/apps/mobile/harmonyos/entry/src/test/ConversationStateUnit.test.ets
+++ b/src/apps/mobile/harmonyos/entry/src/test/ConversationStateUnit.test.ets
@@ -73,6 +73,7 @@ import { RemoteWorkspaceCoordinator } from '../main/ets/services/RemoteWorkspace
 import { RemoteWorkspaceDataSource } from '../main/ets/services/RemoteWorkspaceRepository';
 import { RemoteToolActionClient, RemoteToolActionController } from '../main/ets/services/RemoteToolActionController';
 import { RemoteUiState } from '../main/ets/services/RemoteUiState';
+import { TranscriptIntegrityPolicy } from '../main/ets/services/TranscriptIntegrityPolicy';
 import {
   VoiceInputLifecycleCallbacks,
   VoiceInputLifecycleController,
@@ -89,8 +90,8 @@ import { ConversationController } from '../main/ets/pages/viewmodel/Conversation
 import {
   GENERAL_CHAT_COMPOSER_CAPABILITIES,
   REMOTE_CHAT_COMPOSER_CAPABILITIES
-} from '../main/ets/pages/components/ChatComposerCapabilities';
-import { ChatSurface } from '../main/ets/pages/components/ChatSurface';
+} from '../main/ets/pages/state/ChatComposerCapabilities';
+import { ChatSurface } from '../main/ets/pages/state/ChatSurface';
 import { ConversationViewContract } from '../main/ets/pages/components/ConversationViewContract';
 import {
   AppNavigationBackAction,
@@ -290,6 +291,46 @@ export default function conversationStateUnitTest() {
       expect(merged[0].thinking || '').assertEqual('');
     });
 
+    it('does not let an empty poll stub wipe a richer assistant body', 0, () => {
+      const rich = chatMessage('assistant-rich-1', 'assistant', 'Done with the edit');
+      rich.thinking = 'Plan the change first';
+      rich.tools = [{ id: 'tool-1', name: 'Grep', status: 'completed' }];
+      rich.items = [{
+        type: 'thinking',
+        content: 'Plan the change first'
+      }, {
+        type: 'tool',
+        tool: { id: 'tool-1', name: 'Grep', status: 'completed' }
+      }];
+      const stub = chatMessage('assistant-rich-1', 'assistant', '');
+      stub.thinking = '';
+      stub.tools = [];
+      stub.items = [];
+      const merged = RemoteUiState.mergeMessages([rich], [stub]);
+
+      expect(TranscriptIntegrityPolicy.isHollowAssistant(stub)).assertTrue();
+      expect(TranscriptIntegrityPolicy.hasDisplayableBody(merged[0])).assertTrue();
+      expect(merged[0].text).assertEqual('Done with the edit');
+      expect(merged[0].thinking).assertEqual('Plan the change first');
+      expect(merged[0].tools ? merged[0].tools.length : 0).assertEqual(1);
+      expect(merged[0].items ? merged[0].items.length : 0).assertEqual(2);
+    });
+
+    it('keeps structured items when later text arrives without them', 0, () => {
+      const rich = chatMessage('assistant-rich-2', 'assistant', '');
+      rich.thinking = 'Still reasoning';
+      rich.items = [{ type: 'thinking', content: 'Still reasoning' }];
+      rich.tools = [{ id: 'tool-2', name: 'Read', status: 'completed' }];
+      const merged = RemoteUiState.mergeMessages([rich], [
+        chatMessage('assistant-rich-2', 'assistant', 'Final answer')
+      ]);
+
+      expect(merged[0].text).assertEqual('Final answer');
+      expect(merged[0].thinking || '').assertEqual('');
+      expect(merged[0].items ? merged[0].items.length : 0).assertEqual(1);
+      expect(merged[0].tools ? merged[0].tools.length : 0).assertEqual(1);
+    });
+
     it('owns optimistic merge and active turn cleanup rules', 0, () => {
       const store = new ChatTimelineStore();
       store.reset('session-1');
@@ -313,6 +354,61 @@ export default function conversationStateUnitTest() {
       expect(state.activeTurn ? state.activeTurn.id : '').assertEqual('');
     });
 
+    it('never offers a placeholder id as the turn to cancel', 0, () => {
+      const store = new ChatTimelineStore();
+      store.reset('session-stop');
+      store.appendOptimisticMessage(chatMessage('local-1', 'user', 'Run it'));
+      const pendingActiveId = store.setPendingActiveTurn('local-1');
+      const pendingTurn = store.snapshot().activeTurn;
+
+      // The placeholder is what the user sees while the desktop has not yet
+      // reported a turn — asking to cancel `pending-local-1` would be refused
+      // as stale, so this window must resolve to "cancel whatever is running".
+      expect(pendingActiveId).assertEqual('active-pending-local-1');
+      expect(ChatTimelineStore.cancelableTurnId(pendingTurn!)).assertEqual('');
+
+      store.setLocalActiveTurn('turn-9');
+      expect(ChatTimelineStore.cancelableTurnId(store.snapshot().activeTurn!)).assertEqual('turn-9');
+    });
+
+    it('keeps a message sent mid-run below the reply it is waiting on', 0, () => {
+      const store = new ChatTimelineStore();
+      store.reset('session-queue');
+      // The turn the desktop is already running: its own user message came back
+      // persisted, which is what leaves nothing for the turn to sit behind.
+      store.mergePersistedMessages([chatMessage('user-1', 'user', 'First')]);
+      store.setLocalActiveTurn('turn-1');
+      store.appendOptimisticMessage(chatMessage('local-2', 'user', 'Second'));
+
+      const items = store.project(false);
+      expect(items.length).assertEqual(3);
+      expect(items[0].type).assertEqual('user_message');
+      expect(items[1].type).assertEqual('assistant_live_turn');
+      expect(items[2].type).assertEqual('optimistic_user_message');
+      expect(items[2].message ? items[2].message!.id : '').assertEqual('local-2');
+    });
+
+    it('still draws the first reply under the message that started it', 0, () => {
+      const store = new ChatTimelineStore();
+      store.reset('session-first');
+      store.appendOptimisticMessage(chatMessage('local-1', 'user', 'First'));
+      store.setPendingActiveTurn('local-1');
+
+      // Nothing has been persisted yet, so without the anchor the placeholder
+      // would render above the message the user just sent.
+      expect(store.activeTurnAnchorId()).assertEqual('local-1');
+      const pending = store.project(false);
+      expect(pending[0].type).assertEqual('optimistic_user_message');
+      expect(pending[1].type).assertEqual('assistant_live_turn');
+
+      // Promoting the placeholder to the real turn must not lose the anchor.
+      store.setLocalActiveTurn('turn-1');
+      expect(store.activeTurnAnchorId()).assertEqual('local-1');
+      const promoted = store.project(false);
+      expect(promoted[0].type).assertEqual('optimistic_user_message');
+      expect(promoted[1].type).assertEqual('assistant_live_turn');
+    });
+
     it('projects empty state through the store', 0, () => {
       const store = new ChatTimelineStore();
       store.reset('session-empty');
@@ -1031,13 +1127,17 @@ export default function conversationStateUnitTest() {
       const remoteProjection = ConversationViewState.project(AppRoute.RemoteChat, remote, general, '');
       expect(remoteProjection.surface).assertEqual(ChatSurface.Remote);
       expect(remoteProjection.chatInput).assertEqual('remote draft');
-      expect(remoteProjection.activeSession.sessionId).assertEqual('remote-session');
+      expect(remoteProjection.activeSession.sessionId).assertEqual('');
+      expect(remote.activeSession.sessionId).assertEqual('remote-session');
       expect(remoteProjection.isLoadingConversation).assertTrue();
 
       const generalProjection = ConversationViewState.project(AppRoute.ChatHome, remote, general, 'Configure model');
       expect(generalProjection.surface).assertEqual(ChatSurface.General);
       expect(generalProjection.chatInput).assertEqual('general draft');
       expect(generalProjection.inlineStatusText).assertEqual('Configure model');
+      expect(generalProjection.showSuggestionsWhenEmpty).assertFalse();
+      expect(generalProjection.composerCapabilities.supportsAttachments).assertTrue();
+      expect(generalProjection.composerCapabilities.showAddButton).assertTrue();
     });
   });
 
@@ -1060,6 +1160,39 @@ export default function conversationStateUnitTest() {
       expect(sessions[1].id).assertEqual('one-session');
       expect(sessions[2].id).assertEqual('two-session');
     });
+
+    // Listings run several at a time, so the result can no longer be read off
+    // the order they happened to finish in.
+    it('keeps results in path order across concurrency batches', 0, async () => {
+      const source = new FakeRemoteWorkspaceDataSource();
+      const paths: string[] = [];
+      for (let index = 0; index < 9; index++) {
+        const path = `/workspace-${index}`;
+        paths.push(path);
+        source.sessionsByPath.set(path, [remoteSession(`session-${index}`, `Session ${index}`)]);
+      }
+      const coordinator = new RemoteWorkspaceCoordinator(source);
+
+      const sessions = await coordinator.sessionsForWorkspaces(paths);
+      expect(sessions.length).assertEqual(9);
+      expect(sessions[0].id).assertEqual('session-0');
+      expect(sessions[4].id).assertEqual('session-4');
+      expect(sessions[8].id).assertEqual('session-8');
+      expect(source.listedPaths.length).assertEqual(9);
+    });
+
+    it('keeps the other workspaces when one of them cannot be listed', 0, async () => {
+      const source = new FakeRemoteWorkspaceDataSource();
+      source.sessionsByPath.set('/one', [remoteSession('one-session', 'One')]);
+      source.sessionsByPath.set('/three', [remoteSession('three-session', 'Three')]);
+      source.failingPaths = ['/two'];
+      const coordinator = new RemoteWorkspaceCoordinator(source);
+
+      const sessions = await coordinator.sessionsForWorkspaces(['/one', '/two', '/three']);
+      expect(sessions.length).assertEqual(2);
+      expect(sessions[0].id).assertEqual('one-session');
+      expect(sessions[1].id).assertEqual('three-session');
+    });
   });
 
   describe('ProductSurfaceIsolation', () => {
diff --git a/src/apps/mobile/harmonyos/entry/src/test/LifecycleUnit.test.ets b/src/apps/mobile/harmonyos/entry/src/test/LifecycleUnit.test.ets
index 97a364d5b6..72cff66bc8 100644
--- a/src/apps/mobile/harmonyos/entry/src/test/LifecycleUnit.test.ets
+++ b/src/apps/mobile/harmonyos/entry/src/test/LifecycleUnit.test.ets
@@ -86,8 +86,8 @@ import { ConversationViewState } from '../main/ets/pages/state/ConversationViewS
 import {
   GENERAL_CHAT_COMPOSER_CAPABILITIES,
   REMOTE_CHAT_COMPOSER_CAPABILITIES
-} from '../main/ets/pages/components/ChatComposerCapabilities';
-import { ChatSurface } from '../main/ets/pages/components/ChatSurface';
+} from '../main/ets/pages/state/ChatComposerCapabilities';
+import { ChatSurface } from '../main/ets/pages/state/ChatSurface';
 import { ConversationViewContract } from '../main/ets/pages/components/ConversationViewContract';
 import {
   AppNavigationBackAction,
@@ -222,7 +222,7 @@ export default function lifecycleUnitTest() {
     it('owns heartbeat timer restart, stop, and tick dispatch', 0, () => {
       const scheduler = new FakeRemoteHeartbeatScheduler();
       let tickCount = 0;
-      const controller = new RemoteHeartbeatController(() => {
+      const controller = new RemoteHeartbeatController(async () => {
         tickCount += 1;
       }, 15000, scheduler);
 
@@ -244,13 +244,39 @@ export default function lifecycleUnitTest() {
       expect(scheduler.clearedIds.length).assertEqual(2);
       expect(scheduler.clearedIds[1]).assertEqual(2);
     });
+
+    it('drops ticks that arrive while the previous one is unanswered', 0, async () => {
+      const scheduler = new FakeRemoteHeartbeatScheduler();
+      let started = 0;
+      let answer: () => void = () => {};
+      const controller = new RemoteHeartbeatController((): Promise<void> => {
+        started += 1;
+        return new Promise<void>((resolve: () => void) => {
+          answer = resolve;
+        });
+      }, 15000, scheduler);
+
+      controller.start();
+      scheduler.tick(1);
+      scheduler.tick(1);
+      scheduler.tick(1);
+      // Three intervals have elapsed against a desktop that answered none of
+      // them, and exactly one request is out.
+      expect(started).assertEqual(1);
+
+      answer();
+      await Promise.resolve();
+      await Promise.resolve();
+      scheduler.tick(1);
+      expect(started).assertEqual(2);
+    });
   });
 
   describe('RemoteActivityLifecycleController', () => {
     it('owns remote heartbeat lifecycle while preserving tick dispatch', 0, () => {
       const scheduler = new FakeRemoteHeartbeatScheduler();
       let tickCount = 0;
-      const controller = new RemoteActivityLifecycleController(() => {
+      const controller = new RemoteActivityLifecycleController(async () => {
         tickCount += 1;
       }, 15000, scheduler);
 
diff --git a/src/apps/mobile/harmonyos/entry/src/test/LocalTestFixtures.ets b/src/apps/mobile/harmonyos/entry/src/test/LocalTestFixtures.ets
index 68a3341a7f..0204acf61f 100644
--- a/src/apps/mobile/harmonyos/entry/src/test/LocalTestFixtures.ets
+++ b/src/apps/mobile/harmonyos/entry/src/test/LocalTestFixtures.ets
@@ -52,7 +52,17 @@ import { RemoteCommandFactory } from '../main/ets/services/RemoteCommandFactory'
 import { RemoteCrypto, RemoteCryptoCipher } from '../main/ets/services/RemoteCrypto';
 import { RemoteDescriptorParser } from '../main/ets/services/RemoteDescriptorParser';
 import { RemoteActivityLifecycleController } from '../main/ets/services/RemoteActivityLifecycleController';
+import {
+  RemoteChatCache,
+  RemoteChatCacheSlice,
+  RemoteChatCacheStore
+} from '../main/ets/services/RemoteChatCache';
 import { RemoteChatCommandClient, RemoteChatCommandController } from '../main/ets/services/RemoteChatCommandController';
+import {
+  RemoteSessionListCache,
+  RemoteSessionListSlice,
+  RemoteSessionListStore
+} from '../main/ets/services/RemoteSessionListCache';
 import { RemoteChatPollingLifecycleController } from '../main/ets/services/RemoteChatPollingLifecycleController';
 import {
   RemoteFileDownloadClient,
@@ -87,8 +97,8 @@ import { ConversationViewState } from '../main/ets/pages/state/ConversationViewS
 import {
   GENERAL_CHAT_COMPOSER_CAPABILITIES,
   REMOTE_CHAT_COMPOSER_CAPABILITIES
-} from '../main/ets/pages/components/ChatComposerCapabilities';
-import { ChatSurface } from '../main/ets/pages/components/ChatSurface';
+} from '../main/ets/pages/state/ChatComposerCapabilities';
+import { ChatSurface } from '../main/ets/pages/state/ChatSurface';
 import { ConversationViewContract } from '../main/ets/pages/components/ConversationViewContract';
 import {
   AppNavigationBackAction,
@@ -151,6 +161,10 @@ export interface GeneralChatRecordedRequest {
 export class FakeRemoteWorkspaceDataSource implements RemoteWorkspaceDataSource {
   recent: RecentWorkspaceEntry[] = [];
   sessionsByPath: Map<string, RemoteSession[]> = new Map<string, RemoteSession[]>();
+  /** Paths whose listing rejects, for the workspace a desktop cannot read. */
+  failingPaths: string[] = [];
+  /** Every path listed, in the order the listings were started. */
+  listedPaths: string[] = [];
 
   async listRecentWorkspaces(): Promise<RecentWorkspaceEntry[]> {
     return this.recent;
@@ -175,6 +189,10 @@ export class FakeRemoteWorkspaceDataSource implements RemoteWorkspaceDataSource
   }
 
   async listSessionsForWorkspace(path: string, _limit: number): Promise<RemoteSession[]> {
+    this.listedPaths.push(path);
+    if (this.failingPaths.includes(path)) {
+      throw new Error(`workspace unavailable: ${path}`);
+    }
     return this.sessionsByPath.get(path) || [];
   }
 
@@ -918,6 +936,186 @@ export class RemoteChatMessagesProjectionRecord {
   knownMessageCount: number = -1;
 }
 
+/** Stands in for the RDB-backed transcript cache, keyed the same way it is. */
+/**
+ * An in-memory stand-in for `RemoteChatLocalRdbStore`.
+ *
+ * Recency is modelled the same way the real store models it — reads touch a
+ * session just as writes do — so a test can assert which transcript eviction
+ * actually kept rather than only that a prune was asked for.
+ */
+export class FakeRemoteChatCacheStore implements RemoteChatCacheStore {
+  readonly slices: Map<string, RemoteChatCacheSlice> = new Map<string, RemoteChatCacheSlice>();
+  appendCount: number = 0;
+  replaceCount: number = 0;
+  pruneRequests: number[] = [];
+  clearCount: number = 0;
+  shouldFail: boolean = false;
+  /** Cache keys, least recently touched first. */
+  private recency: string[] = [];
+
+  async init(_context: Context): Promise<void> {
+    this.failIfNeeded();
+  }
+
+  async loadSlice(deviceKey: string, sessionId: string): Promise<RemoteChatCacheSlice> {
+    this.failIfNeeded();
+    const key = FakeRemoteChatCacheStore.key(deviceKey, sessionId);
+    const slice = this.slices.get(key);
+    if (!slice) {
+      return { messages: [], lastMessageId: '' };
+    }
+    this.touch(key);
+    return { messages: slice.messages.slice(), lastMessageId: slice.lastMessageId };
+  }
+
+  async appendMessages(
+    deviceKey: string,
+    sessionId: string,
+    startSeq: number,
+    messages: ChatMessage[],
+    lastMessageId: string
+  ): Promise<void> {
+    this.failIfNeeded();
+    this.appendCount += 1;
+    const key = FakeRemoteChatCacheStore.key(deviceKey, sessionId);
+    const existing = this.slices.get(key);
+    const kept = existing ? existing.messages.slice(0, startSeq) : [];
+    this.slices.set(key, { messages: kept.concat(messages), lastMessageId });
+    this.touch(key);
+  }
+
+  async replaceMessages(
+    deviceKey: string,
+    sessionId: string,
+    messages: ChatMessage[],
+    lastMessageId: string
+  ): Promise<void> {
+    this.failIfNeeded();
+    this.replaceCount += 1;
+    const key = FakeRemoteChatCacheStore.key(deviceKey, sessionId);
+    this.slices.set(key, { messages: messages.slice(), lastMessageId });
+    this.touch(key);
+  }
+
+  async deleteSession(deviceKey: string, sessionId: string): Promise<void> {
+    this.failIfNeeded();
+    this.drop(FakeRemoteChatCacheStore.key(deviceKey, sessionId));
+  }
+
+  async pruneSessions(deviceKey: string, keepMostRecent: number): Promise<void> {
+    this.failIfNeeded();
+    this.pruneRequests.push(keepMostRecent);
+    const prefix = `${deviceKey}::`;
+    const owned = this.recency.filter((key: string): boolean => key.startsWith(prefix));
+    owned.slice(0, Math.max(0, owned.length - keepMostRecent))
+      .forEach((key: string): void => this.drop(key));
+  }
+
+  async clearAll(): Promise<void> {
+    this.failIfNeeded();
+    this.clearCount += 1;
+    this.slices.clear();
+    this.recency = [];
+  }
+
+  private touch(key: string): void {
+    this.recency = this.recency.filter((stored: string): boolean => stored !== key);
+    this.recency.push(key);
+  }
+
+  private drop(key: string): void {
+    this.slices.delete(key);
+    this.recency = this.recency.filter((stored: string): boolean => stored !== key);
+  }
+
+  private failIfNeeded(): void {
+    if (this.shouldFail) {
+      throw new Error('Expected remote chat cache failure.');
+    }
+  }
+
+  private static key(deviceKey: string, sessionId: string): string {
+    return `${deviceKey}::${sessionId}`;
+  }
+}
+
+/**
+ * A cache that never initializes, so every call is a miss.
+ *
+ * That is the shape most controller tests want: the cache is transparent and
+ * the assertions stay about the network path.
+ */
+export function inertRemoteChatCache(): RemoteChatCache {
+  return new RemoteChatCache(new FakeRemoteChatCacheStore(), (): string => 'device-1');
+}
+
+/** A cache backed by [store] and ready to read and write. */
+export async function readyRemoteChatCache(
+  store: FakeRemoteChatCacheStore,
+  deviceKey: string = 'device-1'
+): Promise<RemoteChatCache> {
+  const cache = new RemoteChatCache(store, (): string => deviceKey);
+  await cache.init({} as Context);
+  return cache;
+}
+
+export class FakeRemoteSessionListStore implements RemoteSessionListStore {
+  readonly lists: Map<string, RemoteSessionListSlice> = new Map<string, RemoteSessionListSlice>();
+  lastDeviceKey: string = '';
+  saveCount: number = 0;
+  clearCount: number = 0;
+  shouldFail: boolean = false;
+
+  async init(_context: Context): Promise<void> {
+    this.failIfNeeded();
+  }
+
+  async loadList(deviceKey: string): Promise<RemoteSessionListSlice> {
+    this.failIfNeeded();
+    const slice = this.lists.get(deviceKey);
+    if (!slice) {
+      return { sessions: [], hasMore: false };
+    }
+    return { sessions: slice.sessions.slice(), hasMore: slice.hasMore };
+  }
+
+  async loadLastList(): Promise<RemoteSessionListSlice> {
+    this.failIfNeeded();
+    return await this.loadList(this.lastDeviceKey);
+  }
+
+  async saveList(deviceKey: string, sessions: RemoteSession[], hasMore: boolean): Promise<void> {
+    this.failIfNeeded();
+    this.saveCount += 1;
+    this.lists.set(deviceKey, { sessions: sessions.slice(), hasMore });
+    this.lastDeviceKey = deviceKey;
+  }
+
+  async clearAll(): Promise<void> {
+    this.failIfNeeded();
+    this.clearCount += 1;
+    this.lists.clear();
+    this.lastDeviceKey = '';
+  }
+
+  private failIfNeeded(): void {
+    if (this.shouldFail) {
+      throw new Error('Expected remote session list cache failure.');
+    }
+  }
+}
+
+/** A session list cache backed by [store] and ready to read and write. */
+export async function readyRemoteSessionListCache(
+  store: FakeRemoteSessionListStore,
+  deviceKey: string = 'device-1'
+): Promise<RemoteSessionListCache> {
+  const cache = new RemoteSessionListCache(store, (): string => deviceKey);
+  await cache.init({} as Context);
+  return cache;
+}
+
 export class FakeGeneralChatCommandClient implements GeneralChatCommandClient {
   currentSessions: RemoteSession[] = [remoteSession('chat-1', 'Chat 1')];
   messagesBySession: Map<string, ChatMessage[]> = new Map<string, ChatMessage[]>();
diff --git a/src/apps/mobile/harmonyos/entry/src/test/LocalUnit.test.ets b/src/apps/mobile/harmonyos/entry/src/test/LocalUnit.test.ets
index adea80e19d..b7b41ed176 100644
--- a/src/apps/mobile/harmonyos/entry/src/test/LocalUnit.test.ets
+++ b/src/apps/mobile/harmonyos/entry/src/test/LocalUnit.test.ets
@@ -1,5 +1,6 @@
 import transportAndGeneralChatUnitTest from './TransportAndGeneralChatUnit.test';
 import conversationStateUnitTest from './ConversationStateUnit.test';
+import conversationPresentationUnitTest from './ConversationPresentationUnit.test';
 import lifecycleUnitTest from './LifecycleUnit.test';
 import appRootLifecycleUnitTest from './AppRootLifecycleUnit.test';
 import remoteControllersUnitTest from './RemoteControllersUnit.test';
@@ -8,6 +9,7 @@ import appRootRuntimeStartupUnitTest from './AppRootRuntimeStartupUnit.test';
 export default function localUnitTest() {
   transportAndGeneralChatUnitTest();
   conversationStateUnitTest();
+  conversationPresentationUnitTest();
   lifecycleUnitTest();
   appRootLifecycleUnitTest();
   remoteControllersUnitTest();
diff --git a/src/apps/mobile/harmonyos/entry/src/test/RemoteControllersUnit.test.ets b/src/apps/mobile/harmonyos/entry/src/test/RemoteControllersUnit.test.ets
index 471cc8ef7b..7de0608c5c 100644
--- a/src/apps/mobile/harmonyos/entry/src/test/RemoteControllersUnit.test.ets
+++ b/src/apps/mobile/harmonyos/entry/src/test/RemoteControllersUnit.test.ets
@@ -48,6 +48,7 @@ import {
 import { ModelProviderSseParser } from '../main/ets/services/general-chat/ModelProviderSseParser';
 import { MockGeneralChatAdapter } from '../main/ets/services/general-chat/MockGeneralChatAdapter';
 import { MarkdownParseCache, MarkdownParser } from '../main/ets/services/MarkdownParser';
+import { RemoteSessionListCache } from '../main/ets/services/RemoteSessionListCache';
 import {
   ToolFileInputPayload,
   ToolFileReferenceResolver
@@ -118,17 +119,22 @@ import {
 } from '../main/ets/pages/policy/ConversationLayoutPolicy';
 import { SessionActionPolicy, SessionActionScope } from '../main/ets/pages/policy/SessionActionPolicy';
 import { ConversationSessionFilterPolicy } from '../main/ets/pages/policy/ConversationSessionFilterPolicy';
+import {
+  SessionListInputs,
+  SessionListProjectionCache,
+  SessionListProjector
+} from '../main/ets/pages/policy/SessionListProjection';
 import { ConversationModelPresentationPolicy } from '../main/ets/pages/policy/ConversationModelPresentationPolicy';
 import {
   GENERAL_CHAT_COMPOSER_CAPABILITIES,
   REMOTE_CHAT_COMPOSER_CAPABILITIES
-} from '../main/ets/pages/components/ChatComposerCapabilities';
-import { ChatSurface } from '../main/ets/pages/components/ChatSurface';
+} from '../main/ets/pages/state/ChatComposerCapabilities';
+import { ChatSurface } from '../main/ets/pages/state/ChatSurface';
 import { ConversationViewContract } from '../main/ets/pages/components/ConversationViewContract';
 import {
   ConversationUiModel,
   ConversationUiModelCatalog
-} from '../main/ets/pages/components/ConversationUiModels';
+} from '../main/ets/pages/state/ConversationUiModels';
 import {
   AppNavigationBackAction,
   AppNavigationPathSpec,
@@ -201,6 +207,11 @@ import {
   FakeRemoteSessionClient,
   RemoteSessionProjectionRecord,
   FakeRemoteChatCommandClient,
+  FakeRemoteChatCacheStore,
+  FakeRemoteSessionListStore,
+  inertRemoteChatCache,
+  readyRemoteChatCache,
+  readyRemoteSessionListCache,
   RemoteChatMessagesProjectionRecord,
   FakeGeneralChatCommandClient,
   FakeGeneralChatConfigStore
@@ -766,6 +777,27 @@ export default function remoteControllersUnitTest() {
       expect(threshold.conversationPaneWidth).assertEqual(360);
       expect(threshold.previewPaneWidth).assertEqual(360);
     });
+
+    it('aligns dual-fold preview focus to the single vertical crease', 0, () => {
+      const layout = FilePreviewPlacementPolicy.resolveLayout(true, true, 2210, [
+        new ConversationLayoutCrease(1100, 16)
+      ]);
+      expect(layout.placement).assertEqual(FilePreviewPlacement.WideFocusSplit);
+      expect(layout.masterPaneWidth).assertEqual(0);
+      expect(layout.conversationPaneWidth).assertEqual(1100);
+      expect(layout.conversationPreviewGap).assertEqual(16);
+      expect(layout.previewPaneWidth).assertEqual(1094);
+    });
+
+    it('falls back from crease-aligned focus when one side is too narrow', 0, () => {
+      const layout = FilePreviewPlacementPolicy.resolveLayout(true, true, 900, [
+        new ConversationLayoutCrease(200, 8)
+      ]);
+      expect(layout.placement).assertEqual(FilePreviewPlacement.WideFocusSplit);
+      expect(layout.conversationPaneWidth).assertEqual(449);
+      expect(layout.conversationPreviewGap).assertEqual(1);
+      expect(layout.previewPaneWidth).assertEqual(450);
+    });
   });
 
   describe('RemoteCreateSessionState', () => {
@@ -1239,7 +1271,7 @@ export default function remoteControllersUnitTest() {
         onStartHeartbeat: () => {}
       });
 
-      await controller.create('code', false, true, async (session: SessionSummary): Promise<void> => {
+      const created = await controller.create('code', false, true, async (session: SessionSummary): Promise<void> => {
         openedSessions.push(session);
       });
       await controller.open(remoteSession('opened-session', 'Opened Session'), '/workspace', false, true,
@@ -1248,6 +1280,7 @@ export default function remoteControllersUnitTest() {
         });
 
       expect(client.createRequests[0]).assertEqual('code::');
+      expect(created?.sessionId || '').assertEqual('created-session');
       expect(activeSessions.length).assertEqual(2);
       expect(activeSessions[0].sessionId).assertEqual('created-session');
       expect(activeSessions[1].sessionId).assertEqual('opened-session');
@@ -1255,6 +1288,27 @@ export default function remoteControllersUnitTest() {
       expect(openedSessions.length).assertEqual(2);
     });
 
+    it('returns no created session when the remote create command fails', 0, async () => {
+      const client = new FakeRemoteSessionClient();
+      client.shouldFailCreate = true;
+      const controller = new RemoteSessionController(client, 8, {
+        onSessions: (_sessions: RemoteSession[], _hasMore: boolean) => {},
+        onActiveSession: (_session: SessionSummary) => {},
+        onStatusText: (_statusText: string) => {},
+        onBusy: (_isBusy: boolean) => {},
+        onLoading: (_isLoading: boolean) => {},
+        onSessionError: (_errorText: string) => {},
+        onReconnecting: () => {},
+        onConnected: () => {},
+        onConnectionFailed: (_err: Object) => {},
+        onStartHeartbeat: () => {}
+      });
+
+      const created = await controller.create('code', false, true, async (_session: SessionSummary): Promise<void> => {});
+
+      expect(created === undefined).assertTrue();
+    });
+
     it('deletes active sessions and backfills list when more pages exist', 0, async () => {
       const client = new FakeRemoteSessionClient();
       const projection = new RemoteSessionProjectionRecord();
@@ -1305,6 +1359,82 @@ export default function remoteControllersUnitTest() {
     });
   });
 
+  describe('RemoteSessionListCache', () => {
+    it('restores the list of the device it last stored one for', 0, async () => {
+      const store = new FakeRemoteSessionListStore();
+      const cache = await readyRemoteSessionListCache(store, 'desktop-a');
+
+      await cache.save([remoteSession('session-1', 'Session 1')], true);
+      const restored = await cache.restoreLast();
+
+      expect(restored.sessions.length).assertEqual(1);
+      expect(restored.sessions[0].id).assertEqual('session-1');
+      expect(restored.hasMore).assertTrue();
+    });
+
+    it('keeps each desktop list to itself', 0, async () => {
+      const store = new FakeRemoteSessionListStore();
+      const first = await readyRemoteSessionListCache(store, 'desktop-a');
+      const second = await readyRemoteSessionListCache(store, 'desktop-b');
+
+      await first.save([remoteSession('session-1', 'Session 1')], false);
+      await second.save([remoteSession('session-2', 'Session 2')], false);
+
+      const fromFirst = await first.load();
+      const fromSecond = await second.load();
+      expect(fromFirst.sessions[0].id).assertEqual('session-1');
+      expect(fromSecond.sessions[0].id).assertEqual('session-2');
+    });
+
+    it('writes once for a list that has not changed', 0, async () => {
+      const store = new FakeRemoteSessionListStore();
+      const cache = await readyRemoteSessionListCache(store);
+
+      await cache.save([remoteSession('session-1', 'Session 1')], false);
+      await cache.save([remoteSession('session-1', 'Session 1')], false);
+      expect(store.saveCount).assertEqual(1);
+
+      await cache.save([remoteSession('session-1', 'Renamed')], false);
+      expect(store.saveCount).assertEqual(2);
+    });
+
+    it('leaves a stored list alone when the sessions go away', 0, async () => {
+      const store = new FakeRemoteSessionListStore();
+      const cache = await readyRemoteSessionListCache(store);
+
+      await cache.save([remoteSession('session-1', 'Session 1')], false);
+      await cache.save([], false);
+
+      const restored = await cache.restoreLast();
+      expect(restored.sessions.length).assertEqual(1);
+    });
+
+    it('reads nothing back once signing out clears it', 0, async () => {
+      const store = new FakeRemoteSessionListStore();
+      const cache = await readyRemoteSessionListCache(store);
+
+      await cache.save([remoteSession('session-1', 'Session 1')], false);
+      await cache.clear();
+
+      const restored = await cache.restoreLast();
+      expect(restored.sessions.length).assertEqual(0);
+      expect(store.clearCount).assertEqual(1);
+    });
+
+    it('reports a miss instead of failing when the store is unusable', 0, async () => {
+      const store = new FakeRemoteSessionListStore();
+      store.shouldFail = true;
+      const cache = new RemoteSessionListCache(store, (): string => 'device-1');
+      await cache.init({} as Context);
+
+      await cache.save([remoteSession('session-1', 'Session 1')], false);
+      const restored = await cache.restoreLast();
+
+      expect(restored.sessions.length).assertEqual(0);
+      expect(store.saveCount).assertEqual(0);
+    });
+  });
+
   describe('RemoteChatCommandController', () => {
     it('loads active messages and ignores stale route projections', 0, async () => {
       const client = new FakeRemoteChatCommandClient();
@@ -1326,6 +1456,7 @@ export default function remoteControllersUnitTest() {
           projection.pollVersion = pollVersion;
           projection.knownMessageCount = knownMessageCount;
         },
+        onTimelineReady: () => {},
         onSendSucceeded: (_turnId: string, _pendingActiveId: string) => {},
         onSendFailed: (
           _rawText: string,
@@ -1338,9 +1469,10 @@ export default function remoteControllersUnitTest() {
         onStatusText: (statusText: string) => {
           statuses.push(statusText);
         },
+        onToast: (_message: string) => {},
         onBusy: (_isBusy: boolean) => {},
         onPollRequested: () => {}
-      });
+      }, inertRemoteChatCache());
 
       await controller.loadMessages('session-1', (_sessionId: string) => true);
       await controller.loadMessages('session-2', (_sessionId: string) => false);
@@ -1356,8 +1488,327 @@ export default function remoteControllersUnitTest() {
       expect(statuses[1]).assertEqual(RemoteI18n.t('status.messagesSynced'));
     });
 
+    it('caches a fetched transcript and reopens it without a request', 0, async () => {
+      const client = new FakeRemoteChatCommandClient();
+      const store = new FakeRemoteChatCacheStore();
+      const projection = new RemoteChatMessagesProjectionRecord();
+      const statuses: string[] = [];
+      let timelineReadyCount = 0;
+      client.messageResults = [{
+        messages: [
+          chatMessage('message-1', 'user', 'Hello'),
+          chatMessage('message-2', 'assistant', 'Hi')
+        ],
+        hasMore: false
+      }];
+      const controller = new RemoteChatCommandController(client, {
+        onMessagesLoaded: (messages: ChatMessage[], hasMoreMessages: boolean) => {
+          projection.messages = messages;
+          projection.hasMoreMessages = hasMoreMessages;
+        },
+        onMessageCountKnown: (pollVersion: number, knownMessageCount: number) => {
+          projection.pollVersion = pollVersion;
+          projection.knownMessageCount = knownMessageCount;
+        },
+        onTimelineReady: () => {
+          timelineReadyCount += 1;
+        },
+        onSendSucceeded: (_turnId: string, _pendingActiveId: string) => {},
+        onSendFailed: (
+          _rawText: string,
+          _images: SelectedImageAttachment[],
+          _localMessageId: string,
+          _pendingActiveId: string
+        ) => {},
+        onActiveSession: (_session: SessionSummary) => {},
+        onSessionTitleChanged: (_sessionId: string, _title: string) => {},
+        onStatusText: (statusText: string) => {
+          statuses.push(statusText);
+        },
+        onToast: (_message: string) => {},
+        onBusy: (_isBusy: boolean) => {},
+        onPollRequested: () => {}
+      }, await readyRemoteChatCache(store));
+
+      await controller.loadMessages('session-1', (_sessionId: string) => true);
+      await controller.loadMessages('session-1', (_sessionId: string) => true);
+
+      expect(client.messageRequests.length).assertEqual(1);
+      expect(projection.messages.length).assertEqual(2);
+      expect(projection.messages[1].id).assertEqual('message-2');
+      // A cached open still resets the poll version: the desktop restarts its
+      // version tracker, so a carried-over one would match by accident.
+      expect(projection.pollVersion).assertEqual(0);
+      expect(projection.knownMessageCount).assertEqual(2);
+      expect(timelineReadyCount).assertEqual(2);
+      expect(statuses[statuses.length - 1]).assertEqual(RemoteI18n.t('status.messagesRestored'));
+    });
+
+    it('refetches when a cached assistant has no body', 0, async () => {
+      const client = new FakeRemoteChatCommandClient();
+      const store = new FakeRemoteChatCacheStore();
+      const projection = new RemoteChatMessagesProjectionRecord();
+      const cache = await readyRemoteChatCache(store);
+      const hollow = chatMessage('message-2', 'assistant', '');
+      hollow.thinking = '';
+      hollow.tools = [];
+      hollow.items = [];
+      await cache.sync('session-1', [
+        chatMessage('message-1', 'user', 'Hello'),
+        hollow
+      ]);
+      client.messageResults = [{
+        messages: [
+          chatMessage('message-1', 'user', 'Hello'),
+          chatMessage('message-2', 'assistant', 'Recovered reply')
+        ],
+        hasMore: false
+      }];
+      const controller = new RemoteChatCommandController(client, {
+        onMessagesLoaded: (messages: ChatMessage[], hasMoreMessages: boolean) => {
+          projection.messages = messages;
+          projection.hasMoreMessages = hasMoreMessages;
+        },
+        onMessageCountKnown: (pollVersion: number, knownMessageCount: number) => {
+          projection.pollVersion = pollVersion;
+          projection.knownMessageCount = knownMessageCount;
+        },
+        onTimelineReady: () => {},
+        onSendSucceeded: (_turnId: string, _pendingActiveId: string) => {},
+        onSendFailed: (
+          _rawText: string,
+          _images: SelectedImageAttachment[],
+          _localMessageId: string,
+          _pendingActiveId: string
+        ) => {},
+        onActiveSession: (_session: SessionSummary) => {},
+        onSessionTitleChanged: (_sessionId: string, _title: string) => {},
+        onStatusText: (_statusText: string) => {},
+        onToast: (_message: string) => {},
+        onBusy: (_isBusy: boolean) => {},
+        onPollRequested: () => {}
+      }, cache);
+
+      await controller.loadMessages('session-1', (_sessionId: string) => true);
+
+      expect(client.messageRequests.length).assertEqual(1);
+      expect(projection.messages.length).assertEqual(2);
+      expect(projection.messages[1].text).assertEqual('Recovered reply');
+
+      await controller.loadMessages('session-1', (_sessionId: string) => true);
+      expect(client.messageRequests.length).assertEqual(1);
+    });
+
+    it('caches a transcript the user switched away from before it arrived', 0, async () => {
+      const client = new FakeRemoteChatCommandClient();
+      const store = new FakeRemoteChatCacheStore();
+      const projection = new RemoteChatMessagesProjectionRecord();
+      let timelineReadyCount = 0;
+      client.messageResults = [{
+        messages: [
+          chatMessage('message-1', 'user', 'Hello'),
+          chatMessage('message-2', 'assistant', 'Hi')
+        ],
+        hasMore: false
+      }];
+      const controller = new RemoteChatCommandController(client, {
+        onMessagesLoaded: (messages: ChatMessage[], hasMoreMessages: boolean) => {
+          projection.messages = messages;
+          projection.hasMoreMessages = hasMoreMessages;
+        },
+        onMessageCountKnown: (pollVersion: number, knownMessageCount: number) => {
+          projection.pollVersion = pollVersion;
+          projection.knownMessageCount = knownMessageCount;
+        },
+        onTimelineReady: () => {
+          timelineReadyCount += 1;
+        },
+        onSendSucceeded: (_turnId: string, _pendingActiveId: string) => {},
+        onSendFailed: (
+          _rawText: string,
+          _images: SelectedImageAttachment[],
+          _localMessageId: string,
+          _pendingActiveId: string
+        ) => {},
+        onActiveSession: (_session: SessionSummary) => {},
+        onSessionTitleChanged: (_sessionId: string, _title: string) => {},
+        onStatusText: (_statusText: string) => {},
+        onToast: (_message: string) => {},
+        onBusy: (_isBusy: boolean) => {},
+        onPollRequested: () => {}
+      }, await readyRemoteChatCache(store));
+
+      // Opened, then switched away from before the fetch landed. Nothing may
+      // reach the timeline that now belongs to another session.
+      await controller.loadMessages('session-1', (_sessionId: string) => false);
+      expect(projection.messages.length).assertEqual(0);
+      expect(timelineReadyCount).assertEqual(0);
+
+      // Reopening it has to be free: the transcript was already paid for.
+      await controller.loadMessages('session-1', (_sessionId: string) => true);
+
+      expect(client.messageRequests.length).assertEqual(1);
+      expect(projection.messages.length).assertEqual(2);
+      expect(projection.messages[1].id).assertEqual('message-2');
+      expect(projection.knownMessageCount).assertEqual(2);
+      expect(timelineReadyCount).assertEqual(1);
+    });
+
+    it('appends polled messages to the cache instead of rewriting it', 0, async () => {
+      const client = new FakeRemoteChatCommandClient();
+      const store = new FakeRemoteChatCacheStore();
+      const cache = await readyRemoteChatCache(store);
+      client.messageResults = [{
+        messages: [chatMessage('message-1', 'user', 'Hello')],
+        hasMore: false
+      }];
+      const controller = new RemoteChatCommandController(client, {
+        onMessagesLoaded: (_messages: ChatMessage[], _hasMoreMessages: boolean) => {},
+        onMessageCountKnown: (_pollVersion: number, _knownMessageCount: number) => {},
+        onTimelineReady: () => {},
+        onSendSucceeded: (_turnId: string, _pendingActiveId: string) => {},
+        onSendFailed: (
+          _rawText: string,
+          _images: SelectedImageAttachment[],
+          _localMessageId: string,
+          _pendingActiveId: string
+        ) => {},
+        onActiveSession: (_session: SessionSummary) => {},
+        onSessionTitleChanged: (_sessionId: string, _title: string) => {},
+        onStatusText: (_statusText: string) => {},
+        onToast: (_message: string) => {},
+        onBusy: (_isBusy: boolean) => {},
+        onPollRequested: () => {}
+      }, cache);
+
+      await controller.loadMessages('session-1', (_sessionId: string) => true);
+      await cache.sync('session-1', [
+        chatMessage('message-1', 'user', 'Hello'),
+        chatMessage('message-2', 'assistant', 'Hi')
+      ]);
+      // Nothing new arrived, so the second sync must not touch the store.
+      await cache.sync('session-1', [
+        chatMessage('message-1', 'user', 'Hello'),
+        chatMessage('message-2', 'assistant', 'Hi')
+      ]);
+
+      expect(store.replaceCount).assertEqual(1);
+      expect(store.appendCount).assertEqual(1);
+      expect((await cache.load('session-1')).length).assertEqual(2);
+    });
+
+    it('rewrites the cache when the stored prefix stops matching', 0, async () => {
+      const store = new FakeRemoteChatCacheStore();
+      const cache = await readyRemoteChatCache(store);
+
+      await cache.sync('session-1', [chatMessage('message-1', 'user', 'Hello')]);
+      // Same length, different first message: an append here would splice two
+      // different transcripts together.
+      await cache.sync('session-1', [chatMessage('message-9', 'user', 'Rewritten')]);
+
+      const restored = await cache.load('session-1');
+      expect(store.appendCount).assertEqual(0);
+      expect(store.replaceCount).assertEqual(2);
+      expect(restored.length).assertEqual(1);
+      expect(restored[0].id).assertEqual('message-9');
+    });
+
+    it('evicts only when a session enters the cache, not on every poll tick', 0, async () => {
+      const store = new FakeRemoteChatCacheStore();
+      const cache = await readyRemoteChatCache(store);
+
+      await cache.sync('session-1', [chatMessage('message-1', 'user', 'Hello')]);
+      await cache.sync('session-1', [
+        chatMessage('message-1', 'user', 'Hello'),
+        chatMessage('message-2', 'assistant', 'Hi')
+      ]);
+
+      expect(store.appendCount).assertEqual(1);
+      expect(store.pruneRequests.length).assertEqual(1);
+      expect(store.pruneRequests[0]).assertEqual(20);
+    });
+
+    it('drops the oldest transcript once the per-desktop budget is full', 0, async () => {
+      const store = new FakeRemoteChatCacheStore();
+      const cache = await readyRemoteChatCache(store);
+
+      // One past the budget the prune above reported.
+      for (let index = 0; index <= 20; index++) {
+        await cache.sync(`session-${index}`, [chatMessage(`message-${index}`, 'user', 'Hello')]);
+      }
+
+      expect((await cache.load('session-0')).length).assertEqual(0);
+      expect((await cache.load('session-1')).length).assertEqual(1);
+      expect((await cache.load('session-20')).length).assertEqual(1);
+    });
+
+    it('keeps a reopened transcript ahead of ones only ever written once', 0, async () => {
+      const store = new FakeRemoteChatCacheStore();
+      const cache = await readyRemoteChatCache(store);
+
+      for (let index = 0; index < 20; index++) {
+        await cache.sync(`session-${index}`, [chatMessage(`message-${index}`, 'user', 'Hello')]);
+      }
+      // Reopening is what recency is supposed to be about: this read has to
+      // outrank the nineteen sessions written after it.
+      expect((await cache.load('session-0')).length).assertEqual(1);
+      await cache.sync('session-20', [chatMessage('message-20', 'user', 'Hello')]);
+
+      expect((await cache.load('session-0')).length).assertEqual(1);
+      expect((await cache.load('session-1')).length).assertEqual(0);
+    });
+
+    it('drops a session from the cache when it is forgotten', 0, async () => {
+      const store = new FakeRemoteChatCacheStore();
+      const cache = await readyRemoteChatCache(store);
+
+      await cache.sync('session-1', [chatMessage('message-1', 'user', 'Hello')]);
+      await cache.forget('session-1');
+
+      expect((await cache.load('session-1')).length).assertEqual(0);
+    });
+
+    it('keeps working when the cache store is unusable', 0, async () => {
+      const client = new FakeRemoteChatCommandClient();
+      const store = new FakeRemoteChatCacheStore();
+      const projection = new RemoteChatMessagesProjectionRecord();
+      store.shouldFail = true;
+      client.messageResults = [{
+        messages: [chatMessage('message-1', 'assistant', 'Hello')],
+        hasMore: false
+      }];
+      const controller = new RemoteChatCommandController(client, {
+        onMessagesLoaded: (messages: ChatMessage[], hasMoreMessages: boolean) => {
+          projection.messages = messages;
+          projection.hasMoreMessages = hasMoreMessages;
+        },
+        onMessageCountKnown: (_pollVersion: number, _knownMessageCount: number) => {},
+        onTimelineReady: () => {},
+        onSendSucceeded: (_turnId: string, _pendingActiveId: string) => {},
+        onSendFailed: (
+          _rawText: string,
+          _images: SelectedImageAttachment[],
+          _localMessageId: string,
+          _pendingActiveId: string
+        ) => {},
+        onActiveSession: (_session: SessionSummary) => {},
+        onSessionTitleChanged: (_sessionId: string, _title: string) => {},
+        onStatusText: (_statusText: string) => {},
+        onToast: (_message: string) => {},
+        onBusy: (_isBusy: boolean) => {},
+        onPollRequested: () => {}
+      }, await readyRemoteChatCache(store));
+
+      await controller.loadMessages('session-1', (_sessionId: string) => true);
+
+      expect(client.messageRequests.length).assertEqual(1);
+      expect(projection.messages.length).assertEqual(1);
+    });
+
     it('loads older messages with busy and cursor callbacks', 0, async () => {
       const client = new FakeRemoteChatCommandClient();
+      const store = new FakeRemoteChatCacheStore();
+      const cache = await readyRemoteChatCache(store);
       const projection = new RemoteChatMessagesProjectionRecord();
       const busyEvents: boolean[] = [];
       client.messageResults = [{
@@ -1376,6 +1827,7 @@ export default function remoteControllersUnitTest() {
           projection.pollVersion = pollVersion;
           projection.knownMessageCount = knownMessageCount;
         },
+        onTimelineReady: () => {},
         onSendSucceeded: (_turnId: string, _pendingActiveId: string) => {},
         onSendFailed: (
           _rawText: string,
@@ -1386,11 +1838,12 @@ export default function remoteControllersUnitTest() {
         onActiveSession: (_session: SessionSummary) => {},
         onSessionTitleChanged: (_sessionId: string, _title: string) => {},
         onStatusText: (_statusText: string) => {},
+        onToast: (_message: string) => {},
         onBusy: (isBusy: boolean) => {
           busyEvents.push(isBusy);
         },
         onPollRequested: () => {}
-      });
+      }, cache);
 
       await controller.loadOlderMessages('session-1', 7, true, false);
 
@@ -1401,6 +1854,9 @@ export default function remoteControllersUnitTest() {
       expect(projection.knownMessageCount).assertEqual(2);
       expect(busyEvents[0]).assertTrue();
       expect(busyEvents[1]).assertFalse();
+      // What came back is a full transcript, so it belongs in the cache for the
+      // same reason the first load's does.
+      expect((await cache.load('session-1')).length).assertEqual(2);
     });
 
     it('sends prepared remote messages and reports failed payloads', 0, async () => {
@@ -1411,6 +1867,7 @@ export default function remoteControllersUnitTest() {
       const controller = new RemoteChatCommandController(client, {
         onMessagesLoaded: (_messages: ChatMessage[], _hasMoreMessages: boolean) => {},
         onMessageCountKnown: (_pollVersion: number, _knownMessageCount: number) => {},
+        onTimelineReady: () => {},
         onSendSucceeded: (turnId: string, pendingActiveId: string) => {
           succeeded.push(`${turnId}:${pendingActiveId}`);
         },
@@ -1425,11 +1882,12 @@ export default function remoteControllersUnitTest() {
         onActiveSession: (_session: SessionSummary) => {},
         onSessionTitleChanged: (_sessionId: string, _title: string) => {},
         onStatusText: (_statusText: string) => {},
+        onToast: (_message: string) => {},
         onBusy: (isBusy: boolean) => {
           busyEvents.push(isBusy);
         },
         onPollRequested: () => {}
-      });
+      }, inertRemoteChatCache());
 
       await controller.sendPreparedMessage(
         'session-1',
@@ -1474,10 +1932,12 @@ export default function remoteControllersUnitTest() {
     it('stops active tasks and reports guard states', 0, async () => {
       const client = new FakeRemoteChatCommandClient();
       const statuses: string[] = [];
+      const toasts: string[] = [];
       let pollCount = 0;
       const controller = new RemoteChatCommandController(client, {
         onMessagesLoaded: (_messages: ChatMessage[], _hasMoreMessages: boolean) => {},
         onMessageCountKnown: (_pollVersion: number, _knownMessageCount: number) => {},
+        onTimelineReady: () => {},
         onSendSucceeded: (_turnId: string, _pendingActiveId: string) => {},
         onSendFailed: (
           _rawText: string,
@@ -1490,11 +1950,14 @@ export default function remoteControllersUnitTest() {
         onStatusText: (statusText: string) => {
           statuses.push(statusText);
         },
+        onToast: (message: string) => {
+          toasts.push(message);
+        },
         onBusy: (_isBusy: boolean) => {},
         onPollRequested: () => {
           pollCount += 1;
         }
-      });
+      }, inertRemoteChatCache());
 
       await controller.stopTask('session-1', '', '', true);
       await controller.stopTask('session-1', 'active-turn', 'turn-1', true);
@@ -1504,6 +1967,45 @@ export default function remoteControllersUnitTest() {
       expect(statuses[1]).assertEqual(RemoteI18n.t('status.stoppingTask'));
       expect(statuses[2]).assertEqual(RemoteI18n.t('status.stopRequested'));
       expect(pollCount).assertEqual(1);
+      // The status line is hidden while connected, so a refused stop is only
+      // ever visible as a toast.
+      expect(toasts[0]).assertEqual(RemoteI18n.t('status.noRunningTask'));
+      expect(toasts.length).assertEqual(1);
+    });
+
+    it('surfaces a refused stop instead of leaving the task silently running', 0, async () => {
+      const client = new FakeRemoteChatCommandClient();
+      client.shouldFailCancel = true;
+      const statuses: string[] = [];
+      const toasts: string[] = [];
+      const controller = new RemoteChatCommandController(client, {
+        onMessagesLoaded: (_messages: ChatMessage[], _hasMoreMessages: boolean) => {},
+        onMessageCountKnown: (_pollVersion: number, _knownMessageCount: number) => {},
+        onTimelineReady: () => {},
+        onSendSucceeded: (_turnId: string, _pendingActiveId: string) => {},
+        onSendFailed: (
+          _rawText: string,
+          _images: SelectedImageAttachment[],
+          _localMessageId: string,
+          _pendingActiveId: string
+        ) => {},
+        onActiveSession: (_session: SessionSummary) => {},
+        onSessionTitleChanged: (_sessionId: string, _title: string) => {},
+        onStatusText: (statusText: string) => {
+          statuses.push(statusText);
+        },
+        onToast: (message: string) => {
+          toasts.push(message);
+        },
+        onBusy: (_isBusy: boolean) => {},
+        onPollRequested: () => {}
+      }, inertRemoteChatCache());
+
+      await controller.stopTask('session-1', 'active-turn', 'turn-1', true);
+
+      expect(toasts.length).assertEqual(1);
+      expect(toasts[0]).assertEqual(statuses[statuses.length - 1]);
+      expect(toasts[0] === RemoteI18n.t('status.stopRequested')).assertFalse();
     });
 
     it('renames active sessions and updates active/list projections', 0, async () => {
@@ -1514,6 +2016,7 @@ export default function remoteControllersUnitTest() {
       const controller = new RemoteChatCommandController(client, {
         onMessagesLoaded: (_messages: ChatMessage[], _hasMoreMessages: boolean) => {},
         onMessageCountKnown: (_pollVersion: number, _knownMessageCount: number) => {},
+        onTimelineReady: () => {},
         onSendSucceeded: (_turnId: string, _pendingActiveId: string) => {},
         onSendFailed: (
           _rawText: string,
@@ -1528,11 +2031,12 @@ export default function remoteControllersUnitTest() {
           titleUpdates.push(`${sessionId}:${title}`);
         },
         onStatusText: (_statusText: string) => {},
+        onToast: (_message: string) => {},
         onBusy: (isBusy: boolean) => {
           busyEvents.push(isBusy);
         },
         onPollRequested: () => {}
-      });
+      }, inertRemoteChatCache());
 
       await controller.renameActiveSession({
         sessionId: 'session-1',
@@ -1561,14 +2065,19 @@ export default function remoteControllersUnitTest() {
 
     it('keeps general chat independent from remote-only composer requirements', 0, () => {
       expect(GENERAL_CHAT_COMPOSER_CAPABILITIES.surface).assertEqual(ChatSurface.General);
-      expect(GENERAL_CHAT_COMPOSER_CAPABILITIES.supportsAttachments).assertFalse();
+      expect(GENERAL_CHAT_COMPOSER_CAPABILITIES.supportsAttachments).assertTrue();
       expect(GENERAL_CHAT_COMPOSER_CAPABILITIES.requiresRemoteConnection).assertFalse();
+      // Nothing queues a message on this surface, so a draft written mid-reply
+      // has nowhere to go until the reply finishes.
+      expect(GENERAL_CHAT_COMPOSER_CAPABILITIES.supportsMidRunSend).assertFalse();
     });
 
     it('keeps remote composer attachments behind the remote connection', 0, () => {
       expect(REMOTE_CHAT_COMPOSER_CAPABILITIES.surface).assertEqual(ChatSurface.Remote);
       expect(REMOTE_CHAT_COMPOSER_CAPABILITIES.supportsAttachments).assertTrue();
       expect(REMOTE_CHAT_COMPOSER_CAPABILITIES.requiresRemoteConnection).assertTrue();
+      // The desktop queues a mid-run message and lets the current turn yield.
+      expect(REMOTE_CHAT_COMPOSER_CAPABILITIES.supportsMidRunSend).assertTrue();
     });
   });
 
@@ -1784,6 +2293,125 @@ export default function remoteControllersUnitTest() {
     });
   });
 
+  describe('SessionListProjection', () => {
+    const session = (
+      id: string,
+      title: string,
+      agentType: string,
+      workspacePath: string,
+      status: string = 'idle'
+    ): RemoteSession => {
+      return {
+        id,
+        title,
+        agentType,
+        status,
+        updatedAt: '',
+        createdAt: '',
+        messageCount: 1,
+        workspacePath
+      };
+    };
+
+    const inputs = (sessions: RemoteSession[], query: string = ''): SessionListInputs => {
+      return {
+        sessions,
+        query,
+        sortMode: 'project',
+        workspaceName: 'BitFun',
+        workspacePath: '/workspace/bitfun',
+        workspaceKind: 'normal',
+        recentWorkspaces: [
+          { path: '/workspace/bitfun', name: 'BitFun', lastOpened: '', workspaceKind: 'normal' },
+          { path: '/workspace/notes', name: 'Notes', lastOpened: '', workspaceKind: 'assistant' }
+        ],
+        workspaceFilter: '',
+        agentFilter: '',
+        statusFilter: '',
+        showWorkspaceMetadata: false,
+        showUpdatedMetadata: false,
+        showStatusMetadata: false
+      };
+    };
+
+    const all: RemoteSession[] = [
+      session('code-1', 'Fix layout', 'code', '/workspace/bitfun'),
+      session('code-2', 'Trailing slash', 'code', '/workspace/bitfun/'),
+      session('chat-1', 'Product notes', 'claw', ''),
+      session('chat-2', 'Assistant workspace', 'code', '/workspace/notes'),
+      session('gone-1', 'Archived', 'code', '/workspace/bitfun', 'archived')
+    ];
+
+    it('splits chats from project sessions in one pass', 0, () => {
+      const projection = SessionListProjector.project(inputs(all));
+      expect(projection.filtered.length).assertEqual(4);
+      expect(projection.chats.map((item: RemoteSession) => item.id).join(',')).assertEqual('chat-1,chat-2');
+      // A trailing slash is the same workspace, so both code sessions land in
+      // the one bucket the sidebar renders under that project.
+      const bucket = SessionListProjector.sessionsForProject(projection, '/workspace/bitfun/');
+      expect(bucket.map((item: RemoteSession) => item.id).join(',')).assertEqual('code-1,code-2');
+      expect(projection.projects.map((item: RecentWorkspaceEntry) => item.path).join(','))
+        .assertEqual('/workspace/bitfun');
+      expect(projection.hasActiveFilter).assertFalse();
+      expect(SessionListProjector.sessionsForProject(projection, '/nowhere').length).assertEqual(0);
+    });
+
+    it('drops projects a filter has emptied', 0, () => {
+      const filtered = SessionListProjector.project(inputs(all, 'product'));
+      expect(filtered.hasActiveFilter).assertTrue();
+      expect(filtered.chats.length).assertEqual(1);
+      expect(filtered.projects.length).assertEqual(0);
+    });
+
+    it('reuses the projection until an input changes', 0, () => {
+      const cache = new SessionListProjectionCache();
+      const first = cache.get(inputs(all));
+      expect(cache.get(inputs(all)) === first).assertTrue();
+
+      // A caller that rebuilds the array every call — which is what a filtered
+      // getter bound to a @Param does — still gets the cached projection.
+      const copied = all.map((item: RemoteSession) => item);
+      expect(cache.get(inputs(copied)) === first).assertTrue();
+
+      expect(cache.get(inputs(all, 'layout')) === first).assertFalse();
+
+      const renamed = all.map((item: RemoteSession): RemoteSession => {
+        return item.id === 'code-1' ? session('code-1', 'Renamed', 'code', '/workspace/bitfun') : item;
+      });
+      const afterRename = cache.get(inputs(renamed));
+      expect(afterRename === first).assertFalse();
+      expect(afterRename.filtered[0].title).assertEqual('Renamed');
+    });
+
+    it('buckets by day only when sorting by time', 0, () => {
+      const now = new Date();
+      const recent = session('recent-1', 'Today', 'code', '/workspace/bitfun');
+      recent.updatedAt = new Date(now.getTime() - 60 * 60 * 1000).toISOString();
+      const old = session('old-1', 'Older', 'code', '/workspace/bitfun');
+      old.updatedAt = new Date(now.getTime() - 30 * 24 * 60 * 60 * 1000).toISOString();
+
+      const byProject = SessionListProjector.project(inputs([recent, old]));
+      expect(byProject.byTime.length).assertEqual(0);
+
+      const timeInputs = inputs([old, recent]);
+      timeInputs.sortMode = 'time';
+      const byTime = SessionListProjector.project(timeInputs);
+      expect(byTime.byTime.map((item: RemoteSession) => item.id).join(',')).assertEqual('recent-1,old-1');
+      expect(byTime.today.map((item: RemoteSession) => item.id).join(',')).assertEqual('recent-1');
+      expect(byTime.earlier.map((item: RemoteSession) => item.id).join(',')).assertEqual('old-1');
+    });
+
+    it('labels rows only for the metadata that is switched on', 0, () => {
+      const plain = SessionListProjector.project(inputs(all));
+      expect(SessionListProjector.metadataFor(plain, 'code-1')).assertEqual('');
+
+      const labelled = inputs(all);
+      labelled.showStatusMetadata = true;
+      const projection = SessionListProjector.project(labelled);
+      expect(SessionListProjector.metadataFor(projection, 'code-1')).assertEqual('idle');
+    });
+  });
+
   describe('ConversationModelPresentationPolicy', () => {
     const primaryModel: ConversationUiModel = {
       id: 'anthropic/claude-sonnet-4',
@@ -1849,86 +2477,117 @@ export default function remoteControllersUnitTest() {
   });
 
   describe('ConversationLayoutPolicy', () => {
-    it('keeps folded and narrow surfaces compact', 0, () => {
-      expect(ConversationLayoutPolicy.useMasterDetail(480, false, false, 'tablet', [])).assertFalse();
-      expect(ConversationLayoutPolicy.useMasterDetail(900, true, true, 'tablet', [])).assertFalse();
-      expect(ConversationLayoutPolicy.useMasterDetail(900, false, true, 'phone', [
+    it('keeps folded, hover and narrow surfaces compact', 0, () => {
+      expect(ConversationLayoutPolicy.useMasterDetail(480, false, false, [])).assertFalse();
+      expect(ConversationLayoutPolicy.useMasterDetail(900, true, true, [])).assertFalse();
+      expect(ConversationLayoutPolicy.useMasterDetail(900, false, true, [
         new ConversationLayoutCrease(300, 8),
         new ConversationLayoutCrease(600, 8)
       ])).assertFalse();
+      expect(ConversationLayoutPolicy.useMasterDetail(
+        2210,
+        true,
+        false,
+        [new ConversationLayoutCrease(1100, 16)],
+        true,
+        true
+      )).assertFalse();
     });
 
-    it('uses master-detail for width-qualified tablets', 0, () => {
+    it('uses official md width rather than device type for master-detail', 0, () => {
       expect(ConversationLayoutPolicy.useMasterDetail(
-        ConversationLayoutPolicy.WIDE_LAYOUT_MIN_WIDTH,
+        ConversationLayoutPolicy.MD_MIN_WIDTH +
+          ConversationLayoutPolicy.MIN_DETAIL_PANE_WIDTH,
         false,
         false,
-        'tablet',
         []
       )).assertTrue();
+      expect(ConversationLayoutPolicy.useMasterDetail(480, true, false, [])).assertFalse();
       expect(ConversationLayoutPolicy.useMasterDetail(
-        480,
+        ConversationLayoutPolicy.LG_MIN_WIDTH,
         true,
         false,
-        'tablet',
         []
       )).assertTrue();
     });
 
-    it('keeps phone, single-fold, and dual-screen foldables compact', 0, () => {
+    it('uses master-detail for unfolded dual-fold surfaces', 0, () => {
       expect(ConversationLayoutPolicy.useMasterDetail(
-        ConversationLayoutPolicy.EXTRA_WIDE_MIN_WIDTH,
+        ConversationLayoutPolicy.LG_MIN_WIDTH,
         true,
         false,
-        'phone',
-        []
-      )).assertFalse();
+        [new ConversationLayoutCrease(520, 8)]
+      )).assertTrue();
       expect(ConversationLayoutPolicy.useMasterDetail(
-        ConversationLayoutPolicy.EXTRA_WIDE_MIN_WIDTH,
-        true,
+        2210,
         false,
-        'phone',
-        [new ConversationLayoutCrease(520, 8)]
-      )).assertFalse();
+        false,
+        [new ConversationLayoutCrease(1100, 16)]
+      )).assertTrue();
+      expect(ConversationLayoutPolicy.useMasterDetail(
+        2210,
+        false,
+        false,
+        [],
+        true
+      )).assertTrue();
+    });
+
+    it('keeps an unfolded crease compact when master-detail cannot fit', 0, () => {
       expect(ConversationLayoutPolicy.useMasterDetail(
-        ConversationLayoutPolicy.EXTRA_WIDE_MIN_WIDTH,
+        500,
         true,
         false,
-        'tablet',
-        [new ConversationLayoutCrease(520, 8)]
+        [new ConversationLayoutCrease(200, 8)]
       )).assertFalse();
     });
 
     it('uses master-detail for unfolded tri-fold surfaces', 0, () => {
       expect(ConversationLayoutPolicy.useMasterDetail(
-        ConversationLayoutPolicy.EXTRA_WIDE_MIN_WIDTH,
+        ConversationLayoutPolicy.LG_MIN_WIDTH,
         false,
         false,
-        'phone',
         [new ConversationLayoutCrease(352, 8), new ConversationLayoutCrease(712, 8)]
       )).assertTrue();
       expect(ConversationLayoutPolicy.useMasterDetail(
-        ConversationLayoutPolicy.WIDE_LAYOUT_MIN_WIDTH,
+        720,
         false,
         false,
-        'phone',
         [new ConversationLayoutCrease(230, 8), new ConversationLayoutCrease(480, 8)]
       )).assertTrue();
     });
 
+    it('synthesizes a centered hinge when expanded foldables omit crease data', 0, () => {
+      const synthetic = ConversationLayoutPolicy.syntheticCenterCrease(2210);
+      expect(synthetic !== undefined).assertTrue();
+      expect(synthetic ? synthetic.left : 0).assertEqual(1097);
+      expect(synthetic ? synthetic.width : 0).assertEqual(ConversationLayoutPolicy.SYNTHETIC_HINGE_WIDTH);
+      expect(ConversationLayoutPolicy.syntheticCenterCrease(500) === undefined).assertTrue();
+      expect(ConversationLayoutPolicy.effectiveVerticalCreases(500, [], true).length).assertEqual(0);
+      const creases = ConversationLayoutPolicy.effectiveVerticalCreases(2210, [], true);
+      expect(creases.length).assertEqual(1);
+      expect(creases[0].left).assertEqual(1097);
+      const realCrease = ConversationLayoutPolicy.effectiveVerticalCreases(
+        2210,
+        [new ConversationLayoutCrease(1100, 16)],
+        true
+      );
+      expect(realCrease[0].left).assertEqual(1100);
+    });
+
     it('keeps the existing master width when no usable crease is available', 0, () => {
-      const geometry = ConversationLayoutPolicy.resolveWideGeometry(860, []);
+      const geometry = ConversationLayoutPolicy.resolveWideGeometry(820, []);
       const invalidCrease = ConversationLayoutPolicy.resolveWideGeometry(
-        860,
+        820,
         [new ConversationLayoutCrease(120, 10)]
       );
       expect(geometry.masterPaneWidth).assertEqual(ConversationLayoutPolicy.FALLBACK_MASTER_PANE_WIDTH);
       expect(geometry.masterDetailGap).assertEqual(0);
       expect(geometry.isExtraWide).assertFalse();
       expect(geometry.detailContentOffset).assertEqual(0);
-      expect(geometry.detailContentWidth).assertEqual(516);
+      expect(geometry.detailContentWidth).assertEqual(476);
       expect(geometry.collapsedDetailContentOffset).assertEqual(0);
-      expect(geometry.collapsedDetailContentWidth).assertEqual(860);
+      expect(geometry.collapsedDetailContentWidth).assertEqual(820);
       expect(invalidCrease.masterPaneWidth).assertEqual(ConversationLayoutPolicy.FALLBACK_MASTER_PANE_WIDTH);
     });
 
@@ -1939,6 +2598,9 @@ export default function remoteControllersUnitTest() {
       expect(geometry.detailContentWidth).assertEqual(0);
       expect(geometry.collapsedDetailContentOffset).assertEqual(0);
       expect(geometry.collapsedDetailContentWidth).assertEqual(300);
+      const emptyViewport = ConversationLayoutPolicy.resolveWideGeometry(0, []);
+      expect(emptyViewport.detailContentWidth).assertEqual(0);
+      expect(emptyViewport.collapsedDetailContentWidth).assertEqual(0);
     });
 
     it('aligns the master boundary with the first usable fold crease', 0, () => {
@@ -1951,6 +2613,17 @@ export default function remoteControllersUnitTest() {
       expect(geometry.isExtraWide).assertFalse();
       expect(geometry.detailContentOffset).assertEqual(0);
       expect(geometry.detailContentWidth).assertEqual(430);
+      expect(geometry.collapsedDetailContentOffset).assertEqual(0);
+      expect(geometry.collapsedDetailContentWidth).assertEqual(820);
+    });
+
+    it('keeps collapsed dual-fold content full-width so restore stays at the window origin', 0, () => {
+      const geometry = ConversationLayoutPolicy.resolveWideGeometry(
+        2210,
+        [new ConversationLayoutCrease(1097, 16)]
+      );
+      expect(geometry.collapsedDetailContentOffset).assertEqual(0);
+      expect(geometry.collapsedDetailContentWidth).assertEqual(2210);
     });
 
     it('accepts a zero-width crease without creating an empty detail segment', 0, () => {
@@ -1991,12 +2664,12 @@ export default function remoteControllersUnitTest() {
 
     it('uses width as the extra-wide fallback when crease data is missing', 0, () => {
       const geometry = ConversationLayoutPolicy.resolveWideGeometry(
-        ConversationLayoutPolicy.EXTRA_WIDE_MIN_WIDTH,
+        ConversationLayoutPolicy.LG_MIN_WIDTH,
         []
       );
       expect(geometry.isExtraWide).assertTrue();
       expect(geometry.detailContentOffset).assertEqual(0);
-      expect(geometry.detailContentWidth).assertEqual(736);
+      expect(geometry.detailContentWidth).assertEqual(496);
     });
 
     it('ignores crease regions outside the application viewport', 0, () => {
@@ -2060,6 +2733,47 @@ export default function remoteControllersUnitTest() {
       expect(errors.length).assertEqual(0);
     });
 
+    it('flags a transcript the desktop shortened', 0, async () => {
+      const manager = new FakePollSessionManager();
+      const snapshots: ChatSessionSnapshot[] = [];
+      manager.results = [pollResult({
+        version: 2,
+        changed: true,
+        sessionState: 'idle',
+        title: 'Session',
+        newMessages: [],
+        totalMessageCount: 2
+      }), pollResult({
+        version: 3,
+        changed: true,
+        sessionState: 'idle',
+        title: 'Session',
+        newMessages: [chatMessage('message-6', 'assistant', 'Reply')],
+        totalMessageCount: 6
+      })];
+      const controller = new ChatSessionController(manager, {
+        onSnapshot: (snapshot: ChatSessionSnapshot) => {
+          snapshots.push(snapshot);
+        },
+        onError: (_error: Object) => {},
+        canPoll: (_sessionId: string) => true
+      });
+
+      controller.start('session-1', {
+        pollVersion: 1,
+        knownMessageCount: 5,
+        knownModelCatalogVersion: 0
+      });
+      await delay(20);
+      await controller.pollNow();
+      controller.stop();
+
+      // 2 < 5: whatever the desktop is counting is not what this session had.
+      expect(snapshots[0].historyRewritten).assertTrue();
+      // 6 >= 2: an ordinary tail, resumable from the offset already agreed on.
+      expect(snapshots[1].historyRewritten).assertFalse();
+    });
+
     it('preserves active turn when unchanged poll omits active turn', 0, async () => {
       const manager = new FakePollSessionManager();
       const snapshots: ChatSessionSnapshot[] = [];
diff --git a/src/apps/mobile/harmonyos/entry/src/test/TransportAndGeneralChatUnit.test.ets b/src/apps/mobile/harmonyos/entry/src/test/TransportAndGeneralChatUnit.test.ets
index d083ef6550..123935c563 100644
--- a/src/apps/mobile/harmonyos/entry/src/test/TransportAndGeneralChatUnit.test.ets
+++ b/src/apps/mobile/harmonyos/entry/src/test/TransportAndGeneralChatUnit.test.ets
@@ -1,7 +1,7 @@
 import { describe, it, expect } from '@ohos/hypium';
 import { RemoteI18n } from '../main/ets/i18n/RemoteI18n';
 import { ChatSessionController, ChatSessionSnapshot } from '../main/ets/services/ChatSessionController';
-import { ChatComposerPolicy } from '../main/ets/services/ChatComposerPolicy';
+import { ChatComposerPolicy, ComposerPrimaryAction } from '../main/ets/services/ChatComposerPolicy';
 import { ChatTimelineItem, ChatTimelineProjector } from '../main/ets/services/ChatTimelineProjector';
 import { ChatTimelineStore } from '../main/ets/services/ChatTimelineStore';
 import { ConversationEvent } from '../main/ets/services/ConversationEvent';
@@ -53,6 +53,7 @@ import { ModelProviderSseParser } from '../main/ets/services/general-chat/ModelP
 import { MockGeneralChatAdapter } from '../main/ets/services/general-chat/MockGeneralChatAdapter';
 import { MarkdownParser } from '../main/ets/services/MarkdownParser';
 import { RemoteCommandFactory } from '../main/ets/services/RemoteCommandFactory';
+import { toRemoteQuestionAnswer } from '../main/ets/pages/state/ConversationUiModels';
 import { RemoteCrypto, RemoteCryptoCipher } from '../main/ets/services/RemoteCrypto';
 import { RemoteDescriptorParser } from '../main/ets/services/RemoteDescriptorParser';
 import { RemoteActivityLifecycleController } from '../main/ets/services/RemoteActivityLifecycleController';
@@ -91,8 +92,8 @@ import { ConversationViewState } from '../main/ets/pages/state/ConversationViewS
 import {
   GENERAL_CHAT_COMPOSER_CAPABILITIES,
   REMOTE_CHAT_COMPOSER_CAPABILITIES
-} from '../main/ets/pages/components/ChatComposerCapabilities';
-import { ChatSurface } from '../main/ets/pages/components/ChatSurface';
+} from '../main/ets/pages/state/ChatComposerCapabilities';
+import { ChatSurface } from '../main/ets/pages/state/ChatSurface';
 import { ConversationViewContract } from '../main/ets/pages/components/ConversationViewContract';
 import {
   AppNavigationBackAction,
@@ -265,6 +266,10 @@ class InMemorySettingsConfigStore extends GeneralChatConfigStore {
   async activeSnapshot(): Promise<GeneralChatConfigSnapshot> {
     return this.snapshotResult;
   }
+
+  async activeAccessToken(): Promise<string> {
+    return this.accessTokenResult;
+  }
 }
 
 export default function transportAndGeneralChatUnitTest() {
@@ -356,6 +361,17 @@ export default function transportAndGeneralChatUnitTest() {
         requiresAccountAuth: false
       })).assertTrue();
     });
+
+    it('does not prompt for an account password when this phone already has that cloud session', 0, () => {
+      const policy = new RemotePairingPolicy();
+      const descriptor = RemoteDescriptorParser.parse(
+        'https://relay.example.com/#/pair?room=room-a&pk=key-a&auth=account&user=alice'
+      );
+
+      expect(policy.shouldPromptForAccount(descriptor)).assertTrue();
+      expect(policy.shouldPromptForAccount(descriptor, true, 'alice')).assertFalse();
+      expect(policy.shouldPromptForAccount(descriptor, true, 'bob')).assertTrue();
+    });
   });
 
   describe('X25519', () => {
@@ -719,6 +735,39 @@ export default function transportAndGeneralChatUnitTest() {
       expect(ChatComposerPolicy.canSend('运行任务', 0, false, true, 'connected')).assertEqual(true);
       expect(ChatComposerPolicy.canSend('运行任务', 0, false, true, 'reconnecting')).assertEqual(true);
     });
+
+    it('lets a draft outrank a running turn where the message can be handed over', 0, () => {
+      expect(ChatComposerPolicy.primaryAction('追加要求', 0, false, false, true, true, true, 'connected', true))
+        .assertEqual(ComposerPrimaryAction.Send);
+      expect(ChatComposerPolicy.primaryAction('', 0, false, false, true, true, true, 'connected', true))
+        .assertEqual(ComposerPrimaryAction.Stop);
+    });
+
+    it('keeps a running turn in front of the draft where nothing queues it', 0, () => {
+      expect(ChatComposerPolicy.primaryAction('追加要求', 0, true, false, true, false, false, 'connected', true))
+        .assertEqual(ComposerPrimaryAction.Stop);
+      expect(ChatComposerPolicy.primaryAction('', 0, true, false, true, false, false, 'connected', true))
+        .assertEqual(ComposerPrimaryAction.Stop);
+    });
+
+    it('keeps dictation in front of the draft it is still writing', 0, () => {
+      expect(ChatComposerPolicy.primaryAction('说到一半', 0, false, true, false, true, true, 'connected', true))
+        .assertEqual(ComposerPrimaryAction.Stop);
+      expect(ChatComposerPolicy.primaryAction('说到一半', 0, false, true, true, true, true, 'connected', true))
+        .assertEqual(ComposerPrimaryAction.Stop);
+    });
+
+    it('still shows a draft it cannot carry as blocked rather than idle', 0, () => {
+      expect(ChatComposerPolicy.primaryAction('断线时写的', 0, false, false, true, true, true, 'failed', true))
+        .assertEqual(ComposerPrimaryAction.SendBlocked);
+    });
+
+    it('offers dictation only once no turn is running and no draft exists', 0, () => {
+      expect(ChatComposerPolicy.primaryAction('', 0, false, false, false, true, true, 'connected', true))
+        .assertEqual(ComposerPrimaryAction.Voice);
+      expect(ChatComposerPolicy.primaryAction('', 0, false, false, false, true, true, 'connected', false))
+        .assertEqual(ComposerPrimaryAction.Idle);
+    });
   });
 
   describe('GeneralChatApiClient', () => {
@@ -1015,6 +1064,93 @@ export default function transportAndGeneralChatUnitTest() {
       expect(openAiBody.indexOf('"role":"system"')).assertLarger(-1);
       expect(openAiBody.indexOf('blockchain')).assertLarger(-1);
     });
+
+    it('sends attached images on the Anthropic-compatible local chat path', 0, async () => {
+      const config = new InMemorySettingsConfigStore();
+      config.snapshotResult = {
+        apiUrl: 'https://api.openbitfun.com',
+        modelName: 'vision-model',
+        hasApiKey: true
+      };
+      config.accessTokenResult = 'sk-test-token';
+      const transport = new FakeModelProviderHttpTransport();
+      transport.responses.push(modelProviderRecordedResponse(
+        200,
+        'event: content_block_delta\ndata: {"type":"content_block_delta","delta":{"type":"text_delta","text":"图里是一只猫"}}\n\n'
+      ));
+      const adapter = new ModelProviderGeneralChatAdapter(config, transport);
+      const image = imageAttachment('cat.png', 'data:image/png;base64,aGVsbG8=');
+
+      const result = await adapter.sendMessage('chat-1', '这是什么', [image]);
+
+      expect(transport.requests.length).assertEqual(1);
+      expect(transport.requests[0].body.indexOf('"type":"image"')).assertLarger(-1);
+      expect(transport.requests[0].body.indexOf('"media_type":"image/png"')).assertLarger(-1);
+      expect(transport.requests[0].body.indexOf('"data":"aGVsbG8="')).assertLarger(-1);
+      expect(transport.requests[0].body.indexOf('data:image/png;base64,aGVsbG8=')).assertEqual(-1);
+      expect(transport.requests[0].body.indexOf('这是什么')).assertLarger(-1);
+      expect((result.userMessage.images || []).length).assertEqual(1);
+      expect(result.assistantMessage.text).assertEqual('图里是一只猫');
+    });
+
+    it('sends attached images on the OpenAI-compatible local chat path', 0, async () => {
+      const config = new InMemorySettingsConfigStore();
+      config.snapshotResult = {
+        apiUrl: 'https://llm.example.com/v1',
+        modelName: 'gpt-vision',
+        hasApiKey: true
+      };
+      config.accessTokenResult = 'sk-openai';
+      const transport = new FakeModelProviderHttpTransport();
+      transport.responses.push(modelProviderRecordedResponse(
+        200,
+        'data: {"id":"cmpl-1","choices":[{"delta":{"content":"A screenshot"}}]}\n\n'
+      ));
+      const adapter = new ModelProviderGeneralChatAdapter(config, transport);
+
+      await adapter.sendMessage(
+        'chat-1',
+        'describe this',
+        [imageAttachment('ui.jpg', 'data:image/jpeg;base64,dGVzdA==')]
+      );
+
+      expect(transport.requests[0].protocol).assertEqual(ModelProviderProtocol.OpenAi);
+      expect(transport.requests[0].body.indexOf('"type":"image_url"')).assertLarger(-1);
+      expect(transport.requests[0].body.indexOf('data:image/jpeg;base64,dGVzdA==')).assertLarger(-1);
+      expect(transport.requests[0].body.indexOf('describe this')).assertLarger(-1);
+    });
+
+    it('replays prior local-chat images when continuing a conversation', 0, async () => {
+      const config = new InMemorySettingsConfigStore();
+      config.snapshotResult = {
+        apiUrl: 'https://api.openbitfun.com',
+        modelName: 'vision-model',
+        hasApiKey: true
+      };
+      config.accessTokenResult = 'sk-test-token';
+      const transport = new FakeModelProviderHttpTransport();
+      transport.responses.push(modelProviderRecordedResponse(
+        200,
+        'event: content_block_delta\ndata: {"type":"content_block_delta","delta":{"type":"text_delta","text":"还是同一只猫"}}\n\n'
+      ));
+      const adapter = new ModelProviderGeneralChatAdapter(config, transport);
+      const history: ChatMessage[] = [
+        chatMessageWithImage(
+          'user-1',
+          'user',
+          '这是什么',
+          'cat.png',
+          'data:image/png;base64,aGVsbG8='
+        ),
+        chatMessage('assistant-1', 'assistant', '图里是一只猫', 'completed')
+      ];
+
+      await adapter.sendMessage('chat-1', '再看一眼颜色', [], history);
+
+      expect(transport.requests[0].body.indexOf('"data":"aGVsbG8="')).assertLarger(-1);
+      expect(transport.requests[0].body.indexOf('再看一眼颜色')).assertLarger(-1);
+      expect(transport.requests[0].body.indexOf('图里是一只猫')).assertLarger(-1);
+    });
   });
 
   describe('ModelProviderSseParser', () => {
@@ -1203,14 +1339,25 @@ export default function transportAndGeneralChatUnitTest() {
 
     it('builds tool and file commands', 0, () => {
       const answers: RemoteQuestionAnswerPayload = { answer: 'yes', '0': 'yes' };
+      const multipleAnswers: RemoteQuestionAnswerPayload = { '0': 'yes', '1': ['tests', 'docs'] };
 
       expectCommandJson(RemoteCommandFactory.confirmTool('tool-1'), '{"cmd":"confirm_tool","tool_id":"tool-1"}');
       expectCommandJson(RemoteCommandFactory.rejectTool('tool-1', 'no'), '{"cmd":"reject_tool","tool_id":"tool-1","reason":"no"}');
       expectCommandJson(RemoteCommandFactory.cancelTool('tool-1', 'stop'), '{"cmd":"cancel_tool","tool_id":"tool-1","reason":"stop"}');
       expectCommandJson(RemoteCommandFactory.answerQuestion('tool-2', answers), '{"cmd":"answer_question","tool_id":"tool-2","answers":{"0":"yes","answer":"yes"}}');
+      expectCommandJson(RemoteCommandFactory.answerQuestion('tool-3', multipleAnswers), '{"cmd":"answer_question","tool_id":"tool-3","answers":{"0":"yes","1":["tests","docs"]}}');
       expectCommandJson(RemoteCommandFactory.getFileInfo('/tmp/a.txt', 's1'), '{"cmd":"get_file_info","path":"/tmp/a.txt","session_id":"s1"}');
       expectCommandJson(RemoteCommandFactory.readFileChunk('/tmp/a.txt', 12, 64, 's1'), '{"cmd":"read_file_chunk","path":"/tmp/a.txt","offset":12,"limit":64,"session_id":"s1"}');
     });
+
+    it('preserves indexed question answers when dispatching from the UI', 0, () => {
+      const answers = toRemoteQuestionAnswer({ '0': 'tests', '1': ['docs', 'src'] });
+
+      expectCommandJson(
+        RemoteCommandFactory.answerQuestion('tool-4', answers),
+        '{"cmd":"answer_question","tool_id":"tool-4","answers":{"0":"tests","1":["docs","src"]}}'
+      );
+    });
   });
 
   describe('RemoteResponseMapper', () => {
diff --git a/src/apps/relay-server/Cargo.toml b/src/apps/relay-server/Cargo.toml
index 0deb7e6a68..1599f9a128 100644
--- a/src/apps/relay-server/Cargo.toml
+++ b/src/apps/relay-server/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "bitfun-relay-server"
-version = "0.2.17" # x-release-please-version
+version = "0.2.18" # x-release-please-version
 authors = ["BitFun Team"]
 edition = "2021"
 description = "BitFun standalone Remote Connect relay server"
diff --git a/src/apps/sdk-host/Cargo.toml b/src/apps/sdk-host/Cargo.toml
index bf80751689..f513aaffab 100644
--- a/src/apps/sdk-host/Cargo.toml
+++ b/src/apps/sdk-host/Cargo.toml
@@ -13,10 +13,31 @@ path = "src/main.rs"
 [dependencies]
 anyhow = { workspace = true }
 async-trait = { workspace = true }
-bitfun-agent-runtime = { path = "../../crates/execution/agent-runtime" }
-bitfun-core = { path = "../../crates/assembly/core", default-features = false, features = ["product-full"] }
+bitfun-agent-runtime = { path = "../../crates/execution/agent-runtime", features = ["agent-runtime"] }
+bitfun-core = { path = "../../crates/assembly/core", features = [
+    "agent-runtime",
+    "document-read",
+    "subscription-auth",
+    "deep-research",
+    "lsp",
+    "external-sources",
+    "tools-basic",
+    "tools-git",
+    "tools-mcp",
+    "tools-browser-web",
+    "tools-computer-use",
+    "tools-image-analysis",
+    "tools-miniapp",
+    "tools-canvas",
+    "tools-agent-control",
+] }
 bitfun-sdk-host = { path = "../../crates/interfaces/sdk-host" }
+bitfun-services-core = { path = "../../crates/services/services-core", features = [
+    "process-runtime",
+] }
+bitfun-transport = { path = "../../crates/adapters/transport" }
 futures-util = { workspace = true }
+rustls = { workspace = true }
 serde_json = { workspace = true }
 tokio = { workspace = true, features = ["io-std", "io-util", "macros", "rt-multi-thread", "sync", "time"] }
 tokio-util = { workspace = true, features = ["codec"] }
@@ -24,7 +45,6 @@ tracing = { workspace = true }
 tracing-subscriber = { workspace = true }
 
 [dev-dependencies]
-rustls = { workspace = true }
 tempfile = "3"
 tokio = { workspace = true, features = ["process"] }
 
diff --git a/src/apps/sdk-host/src/lib.rs b/src/apps/sdk-host/src/lib.rs
index b8a32c20fa..062de67bb9 100644
--- a/src/apps/sdk-host/src/lib.rs
+++ b/src/apps/sdk-host/src/lib.rs
@@ -4,13 +4,15 @@ pub mod transport;
 
 /// Stack size used by the SDK Host worker.
 ///
-/// The Host initializes the same full Agent Runtime as the CLI and preserves
-/// the reviewed Windows stack-overflow protection used by that runtime.
+/// The Host initializes its reviewed SDK capability profile and preserves the
+/// Windows stack-overflow protection used by the shared Agent Runtime.
 pub const SDK_HOST_WORKER_STACK_BYTES: usize = 16 * 1024 * 1024;
 
-/// Installs process-global prerequisites before any TLS-capable service starts.
-pub fn initialize_process_runtime() {
-    bitfun_core::service::remote_connect::ensure_rustls_crypto_provider();
+/// Installs process-global prerequisites before any service or descendant starts.
+pub fn initialize_process_runtime() -> std::io::Result<()> {
+    bitfun_services_core::process_manager::contain_current_process_tree()?;
+    let _ = rustls::crypto::ring::default_provider().install_default();
+    Ok(())
 }
 
 /// Spawns the SDK Host runtime on the reviewed worker-stack boundary.
diff --git a/src/apps/sdk-host/src/main.rs b/src/apps/sdk-host/src/main.rs
index 4768ad5692..3e02d28870 100644
--- a/src/apps/sdk-host/src/main.rs
+++ b/src/apps/sdk-host/src/main.rs
@@ -33,7 +33,10 @@ async fn run_host() -> Result<()> {
 }
 
 fn main() {
-    bitfun_sdk_host_app::initialize_process_runtime();
+    if let Err(error) = bitfun_sdk_host_app::initialize_process_runtime() {
+        eprintln!("Error: {error}");
+        std::process::exit(1);
+    }
 
     let worker = bitfun_sdk_host_app::spawn_sdk_host_worker(|| {
         let runtime = tokio::runtime::Builder::new_multi_thread()
diff --git a/src/apps/sdk-host/src/runtime.rs b/src/apps/sdk-host/src/runtime.rs
index f9da5654ac..525c1eed07 100644
--- a/src/apps/sdk-host/src/runtime.rs
+++ b/src/apps/sdk-host/src/runtime.rs
@@ -87,9 +87,6 @@ fn bind_core_execution_ports(agentic_system: &AgenticSystem) {
     agentic_system
         .coordinator
         .set_terminal_port(CoreRuntimeServicesProvider::terminal_port());
-    agentic_system
-        .coordinator
-        .set_remote_exec_port(CoreRuntimeServicesProvider::remote_exec_port());
 }
 
 pub(crate) async fn initialize_terminal_service() {
diff --git a/src/apps/sdk-host/src/transport.rs b/src/apps/sdk-host/src/transport.rs
index d18e5c0eac..cb1002d48a 100644
--- a/src/apps/sdk-host/src/transport.rs
+++ b/src/apps/sdk-host/src/transport.rs
@@ -4,6 +4,7 @@ use std::sync::Arc;
 use std::time::Duration;
 
 use bitfun_agent_runtime::sdk::AgentRuntime;
+use bitfun_transport::encode_json_with_limit;
 use futures_util::StreamExt;
 use tokio::io::{AsyncRead, AsyncWrite, AsyncWriteExt};
 use tokio::sync::Mutex;
@@ -21,6 +22,7 @@ use bitfun_sdk_host::protocol::{
 #[derive(Debug, Clone)]
 pub struct SdkHostTransportConfig {
     pub max_line_bytes: usize,
+    pub max_output_line_bytes: usize,
     pub write_timeout_ms: u64,
     pub shutdown_total_timeout_ms: u64,
     pub host: SdkHostConfig,
@@ -30,6 +32,7 @@ impl Default for SdkHostTransportConfig {
     fn default() -> Self {
         Self {
             max_line_bytes: 1024 * 1024,
+            max_output_line_bytes: 1024 * 1024,
             write_timeout_ms: 5_000,
             shutdown_total_timeout_ms: 10_000,
             host: SdkHostConfig::default(),
@@ -41,14 +44,16 @@ struct JsonLineOutput<Writer> {
     writer: Mutex<Writer>,
     failed: CancellationToken,
     write_timeout: Duration,
+    max_line_bytes: usize,
 }
 
 impl<Writer> JsonLineOutput<Writer> {
-    fn new(writer: Writer, write_timeout_ms: u64) -> Self {
+    fn new(writer: Writer, write_timeout_ms: u64, max_line_bytes: usize) -> Self {
         Self {
             writer: Mutex::new(writer),
             failed: CancellationToken::new(),
             write_timeout: Duration::from_millis(write_timeout_ms.max(1)),
+            max_line_bytes: max_line_bytes.max(1),
         }
     }
 
@@ -63,7 +68,9 @@ where
     Writer: AsyncWrite + Unpin + Send,
 {
     async fn send(&self, value: serde_json::Value) -> Result<(), ()> {
-        let mut line = serde_json::to_vec(&value).map_err(|_| ())?;
+        let mut line = encode_json_with_limit(&value, self.max_line_bytes).map_err(|_| {
+            self.failed.cancel();
+        })?;
         line.push(b'\n');
         let result = timeout(self.write_timeout, async {
             let mut writer = self.writer.lock().await;
@@ -95,10 +102,15 @@ where
     let max_in_flight_requests = config.host.max_in_flight_requests.max(1);
     let max_in_flight_control_requests = config.host.max_in_flight_control_requests.max(1);
     let shutdown_total_timeout = Duration::from_millis(config.shutdown_total_timeout_ms.max(1));
-    let output = Arc::new(JsonLineOutput::new(writer, config.write_timeout_ms));
+    let output = Arc::new(JsonLineOutput::new(
+        writer,
+        config.write_timeout_ms,
+        config.max_output_line_bytes,
+    ));
     let output_failed = output.failure_token();
     let connection =
         SdkHostConnection::with_output(runtime, default_cwd, output.clone(), config.host);
+    let connection_failed = connection.connection_failed_token();
     let mut lines = FramedRead::new(
         reader,
         LinesCodec::new_with_max_length(config.max_line_bytes),
@@ -118,6 +130,14 @@ where
                     "SDK Host output is unavailable",
                 ));
             }
+            _ = connection_failed.cancelled() => {
+                data_requests.abort_all();
+                control_requests.abort_all();
+                graceful_shutdown(&connection, shutdown_total_timeout).await;
+                return Err(std::io::Error::other(
+                    "SDK Host connection cleanup became uncertain",
+                ));
+            }
             completed = data_requests.join_next(), if !data_requests.is_empty() => {
                 if let Some(Ok(ConnectionControl::Shutdown)) = completed {
                     data_requests.abort_all();
@@ -362,3 +382,20 @@ pub async fn serve_stdio(
     )
     .await
 }
+
+#[cfg(test)]
+mod tests {
+    use super::{HostOutput, JsonLineOutput};
+
+    #[tokio::test]
+    async fn outbound_json_lines_fail_before_exceeding_the_transport_budget() {
+        let output = JsonLineOutput::new(tokio::io::sink(), 100, 32);
+        let failure = output.failure_token();
+
+        assert!(output
+            .send(serde_json::json!({ "text": "x".repeat(64) }))
+            .await
+            .is_err());
+        assert!(failure.is_cancelled());
+    }
+}
diff --git a/src/apps/sdk-host/tests/process_initialization.rs b/src/apps/sdk-host/tests/process_initialization.rs
index 8a5300f7d3..e21543995b 100644
--- a/src/apps/sdk-host/tests/process_initialization.rs
+++ b/src/apps/sdk-host/tests/process_initialization.rs
@@ -1,6 +1,6 @@
 #[test]
 fn sdk_host_process_installs_a_rustls_crypto_provider() {
-    bitfun_sdk_host_app::initialize_process_runtime();
+    bitfun_sdk_host_app::initialize_process_runtime().expect("initialize SDK Host process");
 
     assert!(
         rustls::crypto::CryptoProvider::get_default().is_some(),
@@ -8,6 +8,61 @@ fn sdk_host_process_installs_a_rustls_crypto_provider() {
     );
 }
 
+#[cfg(windows)]
+#[test]
+fn sdk_host_process_job_reclaims_descendants_when_host_exits() {
+    const TEST_NAME: &str = "sdk_host_process_job_reclaims_descendants_when_host_exits";
+    const MODE_ENV: &str = "BITFUN_SDK_HOST_JOB_TEST_MODE";
+    const PID_FILE_ENV: &str = "BITFUN_SDK_HOST_JOB_TEST_PID_FILE";
+
+    match std::env::var(MODE_ENV).as_deref() {
+        Ok("descendant") => loop {
+            std::thread::sleep(std::time::Duration::from_secs(1));
+        },
+        Ok("owner") => {
+            bitfun_sdk_host_app::initialize_process_runtime()
+                .expect("initialize owned SDK Host process");
+            let descendant = std::process::Command::new(std::env::current_exe().unwrap())
+                .args(["--exact", TEST_NAME, "--nocapture"])
+                .env(MODE_ENV, "descendant")
+                .spawn()
+                .expect("spawn owned descendant");
+            std::fs::write(
+                std::env::var(PID_FILE_ENV).expect("PID file path"),
+                descendant.id().to_string(),
+            )
+            .expect("record descendant PID");
+            std::thread::sleep(std::time::Duration::from_millis(100));
+            return;
+        }
+        _ => {}
+    }
+
+    let directory = tempfile::tempdir().expect("create job test directory");
+    let pid_file = directory.path().join("descendant.pid");
+    let status = std::process::Command::new(std::env::current_exe().unwrap())
+        .args(["--exact", TEST_NAME, "--nocapture"])
+        .env(MODE_ENV, "owner")
+        .env(PID_FILE_ENV, &pid_file)
+        .status()
+        .expect("run process-tree owner fixture");
+    assert!(status.success(), "process-tree owner fixture failed");
+    let descendant_pid = std::fs::read_to_string(pid_file)
+        .expect("read descendant PID")
+        .trim()
+        .to_string();
+    std::thread::sleep(std::time::Duration::from_millis(200));
+
+    let cleanup = std::process::Command::new("taskkill.exe")
+        .args(["/pid", &descendant_pid, "/t", "/f"])
+        .output()
+        .expect("probe descendant process");
+    assert!(
+        !cleanup.status.success(),
+        "SDK Host process exit left descendant {descendant_pid} alive"
+    );
+}
+
 #[test]
 fn sdk_host_process_uses_the_reviewed_worker_stack_contract() {
     let caller = std::thread::current().id();
@@ -29,6 +84,25 @@ fn sdk_host_process_keeps_cleanup_warnings_on_stderr() {
     assert!(entrypoint.contains(".with_writer(std::io::stderr)"));
 }
 
+#[test]
+fn sdk_host_delegates_process_tree_ownership_to_services_core() {
+    let manifest = include_str!("../Cargo.toml");
+    let bootstrap = include_str!("../src/lib.rs");
+
+    assert!(
+        manifest.contains("bitfun-services-core"),
+        "SDK Host must depend on the reusable process lifecycle owner"
+    );
+    assert!(
+        !manifest.contains("win32job"),
+        "SDK Host must not own a second Windows Job Object implementation"
+    );
+    assert!(
+        bootstrap.contains("bitfun_services_core::process_manager::contain_current_process_tree"),
+        "SDK Host bootstrap must delegate process-tree containment to services-core"
+    );
+}
+
 #[test]
 fn sdk_host_injects_core_ownership_before_runtime_initialization() {
     let runtime = include_str!("../src/runtime.rs");
diff --git a/src/apps/server/Cargo.toml b/src/apps/server/Cargo.toml
index 187c3a5b66..fb8b2bb2e2 100644
--- a/src/apps/server/Cargo.toml
+++ b/src/apps/server/Cargo.toml
@@ -10,13 +10,13 @@ name = "bitfun-server"
 path = "src/main.rs"
 
 [dependencies]
-bitfun-core = { path = "../../crates/assembly/core", default-features = false, features = ["product-full"] }
+bitfun-core = { path = "../../crates/assembly/core", features = ["product-full"] }
 
 # App-server surface: an in-process JSON-RPC server/client pair over an
 # in-memory channel transport. The websocket handler routes agent kernel RPCs
 # through this client so agent interfaces uniformly go through app-server.
 bitfun-app-server = { path = "../../crates/interfaces/app-server" }
-bitfun-agent-runtime = { path = "../../crates/execution/agent-runtime" }
+bitfun-agent-runtime = { path = "../../crates/execution/agent-runtime", features = ["agent-runtime"] }
 bitfun-events = { path = "../../crates/contracts/events" }
 
 agent-client-protocol = { workspace = true }
diff --git a/src/apps/server/src/bootstrap.rs b/src/apps/server/src/bootstrap.rs
index d521b1817b..c91fb625ec 100644
--- a/src/apps/server/src/bootstrap.rs
+++ b/src/apps/server/src/bootstrap.rs
@@ -163,10 +163,6 @@ pub(crate) async fn initialize(workspace: Option<String>) -> anyhow::Result<Arc<
     let _ = bitfun_core::function_agents::git_func_agent::GitFunctionAgent::new(
         ai_client_factory.clone(),
     );
-    let _ = bitfun_core::function_agents::startchat_func_agent::StartchatFunctionAgent::new(
-        ai_client_factory.clone(),
-    );
-
     // 4. Services
     let workspace_service = Arc::new(workspace::WorkspaceService::new().await?);
     workspace::set_global_workspace_service(workspace_service.clone());
diff --git a/src/apps/server/src/routes/external_sources.rs b/src/apps/server/src/routes/external_sources.rs
index 093801e18c..e7ed20a380 100644
--- a/src/apps/server/src/routes/external_sources.rs
+++ b/src/apps/server/src/routes/external_sources.rs
@@ -26,10 +26,13 @@ pub(crate) fn supports(method: &str) -> bool {
             | "set_external_source_enabled_command"
             | "set_external_source_conflict_choice_command"
             | "set_external_tool_target_decision_command"
+            | "set_external_tool_targets_enabled_command"
             | "set_external_tool_conflict_choice_command"
             | "set_external_subagent_activation_command"
+            | "set_external_subagents_enabled_command"
             | "choose_external_subagent_conflict_command"
             | "set_external_mcp_server_decision_command"
+            | "set_external_mcp_servers_enabled_command"
             | "choose_external_mcp_conflict_command"
             | "update_external_integration_policy_command"
     )
@@ -162,6 +165,7 @@ mod tests {
         assert!(supports("get_external_source_snapshot"));
         assert!(supports("get_external_source_control_snapshot"));
         assert!(supports("apply_external_source_control_action_command"));
+        assert!(supports("set_external_mcp_servers_enabled_command"));
         assert!(supports("update_external_integration_policy_command"));
         assert!(!supports("open_workspace"));
     }
diff --git a/src/crates/adapters/AGENTS.md b/src/crates/adapters/AGENTS.md
index 42ba50528a..58db8339ee 100644
--- a/src/crates/adapters/AGENTS.md
+++ b/src/crates/adapters/AGENTS.md
@@ -14,10 +14,11 @@ services.
 | `agent-runtime-ipc` | Non-published private local IPC adapter for the opt-in first-party Shared TUI Runtime; closed interactive operations only | [AGENTS.md](agent-runtime-ipc/AGENTS.md) |
 | `ai-adapters` | AI provider request/response adapters and stream protocol glue | [AGENTS.md](ai-adapters/AGENTS.md) |
 | `opencode-adapter` | OpenCode source semantics for user Instructions plus the live Command, standalone Tool, Subagent, MCP, and static Hook providers; managed-package static preview | [AGENTS.md](opencode-adapter/AGENTS.md) |
+| `dsh-adapter` | DeepSeek Harness (`dsh`) bundle/profile source projection for managed packages; static preview only | [AGENTS.md](dsh-adapter/AGENTS.md) |
 | `claude-code-adapter` | Runtime-free Claude Code user Instructions, Command, Subagent, MCP, and Hook source semantics with redacted projection | [AGENTS.md](claude-code-adapter/AGENTS.md) |
 | `codex-adapter` | Runtime-free Codex user Instructions, Subagent, MCP, and Hook source semantics with redacted projection | [AGENTS.md](codex-adapter/AGENTS.md) |
 | `static-hook-support` | Shared bounded/redacting static-source utilities plus the JSON/TOML Hook parser used by sibling ecosystem adapters; no ecosystem policy or runtime | inherited |
-| `transport` | Event transport emitters and host transport adapters | [AGENTS.md](transport/AGENTS.md) |
+| `transport` | Event transport adapters plus protocol-neutral bounded JSON encoding and TypeScript message/JSON-RPC mechanics shared by current hosts | [AGENTS.md](transport/AGENTS.md) |
 | `webdriver` | Embedded WebDriver protocol and browser automation adapter | [AGENTS.md](webdriver/AGENTS.md) |
 
 ## Placement Rules
diff --git a/src/crates/adapters/agent-runtime-ipc/AGENTS-CN.md b/src/crates/adapters/agent-runtime-ipc/AGENTS-CN.md
index c100aad26e..3b58b34c11 100644
--- a/src/crates/adapters/agent-runtime-ipc/AGENTS-CN.md
+++ b/src/crates/adapters/agent-runtime-ipc/AGENTS-CN.md
@@ -16,7 +16,7 @@
 
 - 只导出 CLI adapter 实际使用的 workspace-private API，且 crate 不得发布，也不得把 wire 作为 SDK 合同。
 - 封闭 operation 范围为 Health、只读且 workspace-scoped 的 main Agent 摘要、Session list/create/restore/delete/fork（restore/fork 结果包含 transcript）、当前 Session rename、Agent mode/model update、手动 context compaction、Session undo/redo、current-controller 限定的只读工作区引用搜索/持久化引用读取，以及不取得 Session lease 的 Runtime 绑定工作区只读 diff；此外还包括声明式上下文 reload、Turn submit/steer、用户显式 Shell 执行/cancel、pending/respond Permission 和 UserInput answers。delete 只允许作用于未被任何 Client 控制的空闲 Session。fork 要求当前 controller 且 Session 空闲：可以复制到最新持久化 Turn，也可以停在显式选中 Turn 之前；只有包含新 Session 与 transcript 的成功结果完成编码后，Server 才能把连接 lease 从源 Session 原子切换到 fork。手动 compaction 要求当前 controller 且 Session 空闲；Client 在准入前提供精确 Turn ID，使超时或断连 cleanup 可以取消同一个 owned task；Core 开始原子 context commit 后，晚到取消不能暴露错误的空闲状态。用户显式 Shell 执行同样要求当前 controller、Session 空闲和调用方提供的 Turn ID；它只委托给窄 Runtime port，并复用正常 ToolPipeline、权限、工作区路由、持久化与取消 owner，不是通用 Tool 或进程执行 wire。steer 要求当前 controller、活动 Turn 以及调用方提供的精确 Session/Turn ID；它只委托给共享 Runtime owner，拒绝过期投影，不创建第二个 Turn 或 queue owner。undo/redo 要求当前 controller，但可在活动 Turn 中进入，因为取消、drain 与回退写入顺序由 Core 统一负责；成功结果携带权威 transcript，并清除连接侧活动 Turn 投影。该能力只支持本地工作区，不暴露通用 checkpoint 协议。上下文 reload 可在活动 Turn 中执行，不改写该 Turn，并通过缓存保护保证下一条消息重新读取已失效的 instructions。断连 cleanup 属于内部生命周期，不是 detach operation。模型目录、默认值和完整 Agent/Subagent 管理仍是 wire 之外的产品配置；main Agent 摘要只服务 host-owned selector：启动页查询 Runtime 绑定工作区且不取得 Session lease，Session 级查询则要求该 Session 的当前 controller 并由 Runtime owner 解析执行工作区。摘要中的 external-source 分类保持生态无关，且不携带安装、变更、激活或 runtime lifecycle API。禁止顺带加入 archive、replay、observer、通用 controller transfer、Tool/MCP/Hook 管理或其他产品配置。
-- 可以复用稳定 Event、Product Domain 和 Runtime Port DTO。禁止依赖 `bitfun-core`、Agent Runtime 实现、SDK Host、services、Tauri、terminal、tool runtime 或远程 transport。
+- 可以复用稳定 Event、Product Domain 和 Runtime Port DTO；`bitfun-transport` 只复用协议无关的有界 JSON 编码，单一消费者的长度前缀 framing 仍归本 wire 私有。禁止依赖 `bitfun-core`、Agent Runtime 实现、SDK Host、services、Tauri、terminal、tool runtime 或远程 transport。
 - 只使用 Windows Named Pipe 或 Unix Domain Socket；禁止 TCP、HTTP、WebSocket、浏览器访问或远程 fallback。
 - 这是本机同用户隔离，不是沙箱。未来产品 composition 必须提供当前用户私有 runtime 目录。
 - Embedded 调用方必须继续以强类型直接调用 Agent Runtime，不能初始化本 transport。Shared 的 request、response 和 event frame 在写出前只编码一次；不能为了吞吐量削弱严格解码、未知字段拒绝、frame 上限、有界队列和背压。
diff --git a/src/crates/adapters/agent-runtime-ipc/AGENTS.md b/src/crates/adapters/agent-runtime-ipc/AGENTS.md
index 13c7e4c775..a2501d0c44 100644
--- a/src/crates/adapters/agent-runtime-ipc/AGENTS.md
+++ b/src/crates/adapters/agent-runtime-ipc/AGENTS.md
@@ -34,7 +34,9 @@ session controller leases, event delivery, connection bounds, and cleanup. It is
   Disconnect cleanup is internal lifecycle, not a detach operation.
   Model catalogs, defaults, and full Agent/Subagent management remain product configuration outside this wire. The main-Agent summary is only the minimal host-owned selector projection: startup reads the Runtime-bound workspace without a Session lease, while a Session-scoped query requires that Session's current controller and lets the Runtime owner resolve its execution workspace. Its external-source classification is ecosystem-neutral, and it carries no installation, mutation, activation, or runtime lifecycle API. Do not add archive, replay, observer,
   general controller transfer, Tool/MCP/Hook management, or other product configuration incidentally.
-- Stable Event, Product Domain, and Runtime Port DTOs may be reused. Do not
+- Stable Event, Product Domain, and Runtime Port DTOs may be reused. Only the
+  protocol-neutral bounded JSON encoder from `bitfun-transport` is reused; the
+  single-consumer length-prefix framing remains private to this wire. Do not
   depend on `bitfun-core`, Agent Runtime implementations, SDK Host, services,
   Tauri, terminal, tool runtime, or remote transports.
 - Use only Windows Named Pipes or Unix Domain Sockets. Do not add TCP, HTTP,
diff --git a/src/crates/adapters/agent-runtime-ipc/Cargo.toml b/src/crates/adapters/agent-runtime-ipc/Cargo.toml
index e1d2209288..cd68a0061f 100644
--- a/src/crates/adapters/agent-runtime-ipc/Cargo.toml
+++ b/src/crates/adapters/agent-runtime-ipc/Cargo.toml
@@ -12,9 +12,10 @@ crate-type = ["rlib"]
 
 [dependencies]
 async-trait = { workspace = true }
+bitfun-transport = { path = "../transport" }
 bitfun-events = { path = "../../contracts/events" }
-bitfun-product-domains = { path = "../../contracts/product-domains", default-features = false }
-bitfun-runtime-ports = { path = "../../contracts/runtime-ports" }
+bitfun-product-domains = { path = "../../contracts/product-domains" }
+bitfun-runtime-ports = { path = "../../contracts/runtime-ports", features = ["agent-api", "git-port"] }
 dunce = { workspace = true }
 fs2 = { workspace = true }
 serde = { workspace = true }
diff --git a/src/crates/adapters/agent-runtime-ipc/src/framing.rs b/src/crates/adapters/agent-runtime-ipc/src/framing.rs
index 18bc3568e7..48a002ec68 100644
--- a/src/crates/adapters/agent-runtime-ipc/src/framing.rs
+++ b/src/crates/adapters/agent-runtime-ipc/src/framing.rs
@@ -1,5 +1,6 @@
 use crate::RuntimeIpcFrame;
-use std::io::Write;
+use bitfun_transport::encode_json_with_limit;
+use bitfun_transport::JsonCodecError;
 use tokio::io::{AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt};
 
 pub(crate) const MAX_REQUEST_FRAME_BYTES: usize = 128 * 1024;
@@ -155,55 +156,6 @@ fn parse_strict_frame(bytes: &[u8]) -> Result<RuntimeIpcFrame, RuntimeIpcIoError
     Ok(frame)
 }
 
-pub(crate) fn serialize_frame_with_limit(
-    frame: &RuntimeIpcFrame,
-    max_bytes: usize,
-) -> Result<Vec<u8>, RuntimeIpcIoError> {
-    let mut writer = CappedWriter::new(max_bytes);
-    let result = serde_json::to_writer(&mut writer, frame);
-    if writer.overflowed {
-        return Err(RuntimeIpcIoError::FrameTooLarge {
-            size: max_bytes.saturating_add(1),
-            max_bytes,
-        });
-    }
-    result.map_err(RuntimeIpcIoError::Serialize)?;
-    Ok(writer.bytes)
-}
-
-struct CappedWriter {
-    bytes: Vec<u8>,
-    max_bytes: usize,
-    overflowed: bool,
-}
-
-impl CappedWriter {
-    fn new(max_bytes: usize) -> Self {
-        Self {
-            bytes: Vec::with_capacity(max_bytes.min(16 * 1024)),
-            max_bytes,
-            overflowed: false,
-        }
-    }
-}
-
-impl Write for CappedWriter {
-    fn write(&mut self, input: &[u8]) -> std::io::Result<usize> {
-        let remaining = self.max_bytes.saturating_sub(self.bytes.len());
-        if input.len() > remaining {
-            self.bytes.extend_from_slice(&input[..remaining]);
-            self.overflowed = true;
-            return Err(std::io::Error::other("runtime IPC frame is too large"));
-        }
-        self.bytes.extend_from_slice(input);
-        Ok(input.len())
-    }
-
-    fn flush(&mut self) -> std::io::Result<()> {
-        Ok(())
-    }
-}
-
 fn first_unknown_field(
     original: &serde_json::Value,
     canonical: &serde_json::Value,
@@ -233,6 +185,26 @@ fn first_unknown_field(
     }
 }
 
+pub(crate) fn serialize_frame_with_limit(
+    frame: &RuntimeIpcFrame,
+    max_bytes: usize,
+) -> Result<Vec<u8>, RuntimeIpcIoError> {
+    encode_json_with_limit(frame, max_bytes).map_err(map_json_error)
+}
+
+fn map_json_error(error: JsonCodecError) -> RuntimeIpcIoError {
+    match error {
+        JsonCodecError::PayloadTooLarge {
+            minimum_size,
+            max_bytes,
+        } => RuntimeIpcIoError::FrameTooLarge {
+            size: minimum_size,
+            max_bytes,
+        },
+        JsonCodecError::Encode(error) => RuntimeIpcIoError::Serialize(error),
+    }
+}
+
 #[derive(Debug, thiserror::Error)]
 pub enum RuntimeIpcIoError {
     #[error("runtime IPC frame exceeds {max_bytes} bytes: {size}")]
diff --git a/src/crates/adapters/agent-runtime-ipc/src/operation.rs b/src/crates/adapters/agent-runtime-ipc/src/operation.rs
index 15558630cd..5dd337d4a9 100644
--- a/src/crates/adapters/agent-runtime-ipc/src/operation.rs
+++ b/src/crates/adapters/agent-runtime-ipc/src/operation.rs
@@ -1,7 +1,6 @@
 use bitfun_product_domains::tool_permissions::{PermissionReply, PermissionRequest};
 use bitfun_runtime_ports::{
     AgentContextReloadRequest, AgentDialogSteerRequest, AgentDialogTurnRequest,
-    AgentLocalCommandTurnRecordRequest, AgentLocalCommandTurnRecordResult,
     AgentMessageWorkspaceReferencesRequest, AgentSessionCompactionRequest,
     AgentSessionCreateRequest, AgentSessionCreateResult, AgentSessionLineageCancellationRequest,
     AgentSessionLineageInspection, AgentSessionLineageRequest, AgentSessionLineageSnapshot,
@@ -183,9 +182,6 @@ pub enum RuntimeIpcOperation {
     SubmitUserAnswers {
         request: RuntimeUserAnswersRequest,
     },
-    RecordLocalCommandTurn {
-        request: AgentLocalCommandTurnRecordRequest,
-    },
 }
 
 impl RuntimeIpcOperation {
@@ -229,7 +225,6 @@ impl RuntimeIpcOperation {
             Self::PendingPermissions { session_id }
             | Self::RespondPermission { session_id, .. } => Some(session_id),
             Self::SubmitUserAnswers { request } => Some(&request.session_id),
-            Self::RecordLocalCommandTurn { request } => Some(&request.session_id),
             Self::Health
             | Self::ListAgentModes { session_id: None }
             | Self::ListSessions { .. }
@@ -280,9 +275,6 @@ impl RuntimeIpcOperation {
             | Self::SubmitUserAnswers { .. } => {
                 RuntimeIpcOperationRules::new(CurrentController, false, false, true)
             }
-            Self::RecordLocalCommandTurn { .. } => {
-                RuntimeIpcOperationRules::new(CurrentController, true, false, true)
-            }
             Self::PendingPermissions { .. } => {
                 RuntimeIpcOperationRules::new(CurrentController, false, false, false)
             }
@@ -404,9 +396,6 @@ pub enum RuntimeIpcOperationResult {
     WorkspaceDiff {
         snapshot: WorkspaceDiffSnapshot,
     },
-    LocalCommandTurnRecorded {
-        record: AgentLocalCommandTurnRecordResult,
-    },
 }
 
 #[cfg(test)]
@@ -461,6 +450,8 @@ mod tests {
                 turn_id: "turn-1".to_string(),
                 content: "check tests".to_string(),
                 display_content: None,
+                attachments: Vec::new(),
+                metadata: serde_json::Map::new(),
             },
         };
         let rules = operation.rules();
diff --git a/src/crates/adapters/agent-runtime-ipc/src/tests/protocol_contracts.rs b/src/crates/adapters/agent-runtime-ipc/src/tests/protocol_contracts.rs
index 753fa5fb3a..741f38d2d5 100644
--- a/src/crates/adapters/agent-runtime-ipc/src/tests/protocol_contracts.rs
+++ b/src/crates/adapters/agent-runtime-ipc/src/tests/protocol_contracts.rs
@@ -142,6 +142,8 @@ fn protocol_round_trips_exact_turn_steering_without_replacing_turn_admission() {
             turn_id: "turn-1".to_string(),
             content: "check tests".to_string(),
             display_content: Some("Check tests".to_string()),
+            attachments: Vec::new(),
+            metadata: serde_json::Map::new(),
         },
     };
     let result = RuntimeIpcOperationResult::TurnSteered {
diff --git a/src/crates/adapters/agent-runtime-ipc/src/tests/shared_controller.rs b/src/crates/adapters/agent-runtime-ipc/src/tests/shared_controller.rs
index b36b557ad4..a63b29e4dd 100644
--- a/src/crates/adapters/agent-runtime-ipc/src/tests/shared_controller.rs
+++ b/src/crates/adapters/agent-runtime-ipc/src/tests/shared_controller.rs
@@ -297,6 +297,11 @@ impl RuntimeIpcRequestHandler for FakeHandler {
                         retired_turn_ids: Vec::new(),
                         changed: true,
                         hidden_turn_count: 1,
+                        boundary_storage_turn_index: None,
+                        target_turn_id: None,
+                        restored_files: Vec::new(),
+                        reload_required: false,
+                        reload_reason: None,
                     },
                 })
             }
@@ -705,6 +710,8 @@ fn steer_operation(session_id: &str, turn_id: &str) -> RuntimeIpcOperation {
             turn_id: turn_id.to_string(),
             content: "check tests".to_string(),
             display_content: None,
+            attachments: Vec::new(),
+            metadata: serde_json::Map::new(),
         },
     }
 }
diff --git a/src/crates/adapters/ai-adapters/Cargo.toml b/src/crates/adapters/ai-adapters/Cargo.toml
index 6a54278c89..772f1e5721 100644
--- a/src/crates/adapters/ai-adapters/Cargo.toml
+++ b/src/crates/adapters/ai-adapters/Cargo.toml
@@ -4,18 +4,27 @@ version.workspace = true
 authors.workspace = true
 edition.workspace = true
 description = "Shared AI protocol adapters for BitFun core and installer"
+autotests = false
 
 [lib]
 name = "bitfun_ai_adapters"
 crate-type = ["rlib"]
 
+[[test]]
+name = "ai_protocol_contracts"
+path = "tests/ai_protocol_contracts.rs"
+
+[[test]]
+name = "ai_stream_contracts"
+path = "tests/ai_stream_contracts.rs"
+
 [dependencies]
 anyhow = { workspace = true }
 async-trait = { workspace = true }
 base64 = { workspace = true, optional = true }
 bitfun-agent-stream = { path = "../../execution/agent-stream" }
 bitfun-core-types = { path = "../../contracts/core-types" }
-bitfun-services-core = { path = "../../services/services-core", default-features = false, optional = true }
+bitfun-services-core = { path = "../../services/services-core", optional = true }
 chrono = { workspace = true }
 dirs = { workspace = true, optional = true }
 keyring-core = { workspace = true, optional = true }
@@ -24,7 +33,7 @@ futures = { workspace = true }
 fs2 = { workspace = true, optional = true }
 libc = { workspace = true, optional = true }
 log = { workspace = true }
-reqwest = { workspace = true, features = ["rustls", "socks"] }
+reqwest = { workspace = true, features = ["http2", "json", "rustls", "socks", "stream"] }
 serde = { workspace = true }
 serde_json = { workspace = true }
 sha2 = { workspace = true, optional = true }
@@ -52,6 +61,7 @@ subscription-auth = [
     "dep:fs2",
     "dep:keyring-core",
     "dep:libc",
+    "reqwest/form",
     "dep:sha2",
     "tokio/fs",
     "tokio/io-util",
diff --git a/src/crates/adapters/ai-adapters/src/client.rs b/src/crates/adapters/ai-adapters/src/client.rs
index 53bdaa94ce..aa1e1feecc 100644
--- a/src/crates/adapters/ai-adapters/src/client.rs
+++ b/src/crates/adapters/ai-adapters/src/client.rs
@@ -19,6 +19,7 @@ use crate::trace::{
 use crate::types::ProxyConfig;
 use crate::types::*;
 use anyhow::Result;
+use bitfun_core_types::errors::{AiProviderError, ErrorCategory};
 use format::ApiFormat;
 use log::warn;
 use reqwest::Client;
@@ -223,30 +224,36 @@ impl AIClient {
         extra_body: Option<serde_json::Value>,
         trace: Option<ModelExchangeTraceConfig>,
     ) -> Result<StreamResponse> {
-        let max_tries = SEND_MESSAGE_STREAM_ATTEMPTS;
-        match ApiFormat::parse(&self.config.format)? {
-            ApiFormat::OpenAIChat => {
-                openai::chat::send_stream(self, messages, tools, extra_body, max_tries, trace).await
-            }
-            ApiFormat::OpenAIResponses => {
-                openai::responses::send_stream(self, messages, tools, extra_body, max_tries, trace)
-                    .await
-            }
-            ApiFormat::Anthropic => {
-                anthropic::request::send_stream(self, messages, tools, extra_body, max_tries, trace)
-                    .await
-            }
-            ApiFormat::Gemini => {
-                gemini::request::send_stream(self, messages, tools, extra_body, max_tries, trace)
-                    .await
-            }
-            ApiFormat::GeminiCodeAssist => {
-                gemini::code_assist::send_stream(
-                    self, messages, tools, extra_body, max_tries, trace,
-                )
-                .await
-            }
-        }
+        self.send_message_stream_with_extra_body_and_max_attempts(
+            messages,
+            tools,
+            extra_body,
+            SEND_MESSAGE_STREAM_ATTEMPTS,
+            trace,
+        )
+        .await
+    }
+
+    /// Open one model stream without an adapter-owned retry loop.
+    ///
+    /// Runtime owners with a broader attempt lifecycle use this entry point so
+    /// connection, HTTP, TTFT, parsing, and in-stream failures all consume one
+    /// shared retry budget instead of multiplying nested retry loops.
+    pub async fn send_message_stream_once(
+        &self,
+        messages: Vec<Message>,
+        tools: Option<Vec<ToolDefinition>>,
+        trace: Option<ModelExchangeTraceConfig>,
+    ) -> Result<StreamResponse> {
+        let custom_body = self.config.custom_request_body.clone();
+        self.send_message_stream_with_extra_body_and_max_attempts(
+            messages,
+            tools,
+            custom_body,
+            1,
+            trace,
+        )
+        .await
     }
 
     pub async fn send_message(
@@ -306,15 +313,33 @@ impl AIClient {
         max_attempts: usize,
     ) -> Result<GeminiResponse> {
         for attempt in 0..max_attempts {
-            let stream_response = self
+            let stream_response = match self
                 .send_message_stream_with_extra_body_and_max_attempts(
                     messages.clone(),
                     tools.clone(),
                     extra_body.clone(),
-                    max_attempts,
+                    1,
                     trace.clone(),
                 )
-                .await?;
+                .await
+            {
+                Ok(response) => response,
+                Err(error) => {
+                    if attempt == max_attempts - 1 {
+                        return Err(error);
+                    }
+                    let delay_ms = send_message_retry_delay_ms_for_error(attempt, &error);
+                    warn!(
+                        "Retrying AI stream request after error: attempt={}/{}, delay_ms={}, error={}",
+                        attempt + 1,
+                        max_attempts,
+                        delay_ms,
+                        error
+                    );
+                    tokio::time::sleep(Duration::from_millis(delay_ms)).await;
+                    continue;
+                }
+            };
             let trace_handle = stream_response.trace_handle.clone();
 
             match response_aggregator::aggregate_stream_response(stream_response).await {
@@ -323,19 +348,19 @@ impl AIClient {
                         .await;
                     return Ok(response);
                 }
-                Err(error)
-                    if attempt < max_attempts - 1
-                        && is_transient_stream_error(&error.to_string()) =>
-                {
+                Err(error) => {
                     fail_aggregated_trace(
                         trace.as_ref(),
                         trace_handle.as_ref(),
                         &error.to_string(),
                     )
                     .await;
-                    let delay_ms = send_message_retry_delay_ms(attempt, &error.to_string());
+                    if attempt == max_attempts - 1 {
+                        return Err(error);
+                    }
+                    let delay_ms = send_message_retry_delay_ms_for_error(attempt, &error);
                     warn!(
-                        "Retrying aggregated AI stream after transient error: attempt={}/{}, delay_ms={}, error={}",
+                        "Retrying aggregated AI stream after error: attempt={}/{}, delay_ms={}, error={}",
                         attempt + 1,
                         max_attempts,
                         delay_ms,
@@ -343,15 +368,6 @@ impl AIClient {
                     );
                     tokio::time::sleep(Duration::from_millis(delay_ms)).await;
                 }
-                Err(error) => {
-                    fail_aggregated_trace(
-                        trace.as_ref(),
-                        trace_handle.as_ref(),
-                        &error.to_string(),
-                    )
-                    .await;
-                    return Err(error);
-                }
             }
         }
 
@@ -428,15 +444,35 @@ impl AIClient {
     }
 }
 
+#[cfg(test)]
 fn send_message_retry_delay_ms(attempt_index: usize, error_message: &str) -> u64 {
+    send_message_retry_delay_ms_with_provider(attempt_index, error_message, None)
+}
+
+fn send_message_retry_delay_ms_for_error(attempt_index: usize, error: &anyhow::Error) -> u64 {
+    send_message_retry_delay_ms_with_provider(
+        attempt_index,
+        &error.to_string(),
+        error.downcast_ref::<AiProviderError>(),
+    )
+}
+
+fn send_message_retry_delay_ms_with_provider(
+    attempt_index: usize,
+    error_message: &str,
+    provider_error: Option<&AiProviderError>,
+) -> u64 {
     let shift = u32::try_from(attempt_index)
         .unwrap_or(u32::MAX)
         .min(SEND_MESSAGE_MAX_RETRY_EXPONENT_SHIFT);
     let msg = error_message.to_lowercase();
-    let is_rate_limit =
-        msg.contains("429") || msg.contains("rate limit") || msg.contains("too many requests");
+    let is_rate_limit = provider_error
+        .is_some_and(|error| error.category == ErrorCategory::RateLimit)
+        || msg.contains("429")
+        || msg.contains("rate limit")
+        || msg.contains("too many requests");
 
-    if is_rate_limit {
+    let fallback = if is_rate_limit {
         SEND_MESSAGE_RATE_LIMIT_RETRY_BASE_DELAY_MS
             .saturating_mul(1u64 << shift)
             .min(SEND_MESSAGE_MAX_RATE_LIMIT_DELAY_MS)
@@ -444,93 +480,17 @@ fn send_message_retry_delay_ms(attempt_index: usize, error_message: &str) -> u64
         SEND_MESSAGE_RETRY_BASE_DELAY_MS
             .saturating_mul(1u64 << shift)
             .min(SEND_MESSAGE_MAX_EXPONENTIAL_DELAY_MS)
-    }
-}
-
-fn is_transient_stream_error(error_message: &str) -> bool {
-    let msg = error_message.to_lowercase();
+    };
 
-    let non_retryable_keywords = [
-        "invalid api key",
-        "unauthorized",
-        "forbidden",
-        "model not found",
-        "unsupported model",
-        "invalid request",
-        "bad request",
-        "prompt is too long",
-        "content policy",
-        "proxy authentication required",
-        "provider quota",
-        "provider billing",
-        "insufficient_quota",
-        "insufficient quota",
-        "insufficient balance",
-        "not_enough_balance",
-        "not enough balance",
-        "余额不足",
-        "无可用资源包",
-        "账户已欠费",
-        "code=1113",
-        "\"code\":\"1113\"",
-        "client error 400",
-        "client error 401",
-        "client error 402",
-        "client error 403",
-        "client error 404",
-        "client error 413",
-        "client error 422",
-        "sse parsing error",
-        "schema error",
-        "unknown api format",
-    ];
-
-    if non_retryable_keywords.iter().any(|k| msg.contains(k)) {
-        return false;
-    }
-
-    [
-        "transport error",
-        "error decoding response body",
-        "stream closed before response completed",
-        "stream processing error",
-        "sse stream error",
-        "sse error",
-        "sse timeout",
-        "stream data timeout",
-        "timeout",
-        "request timeout",
-        "deadline exceeded",
-        "connection reset",
-        "connection closed",
-        "broken pipe",
-        "unexpected eof",
-        "connection refused",
-        "socket closed",
-        "temporarily unavailable",
-        "service unavailable",
-        "bad gateway",
-        "gateway timeout",
-        "overloaded",
-        "proxy",
-        "tunnel",
-        "dns",
-        "network",
-        "econnreset",
-        "econnrefused",
-        "etimedout",
-        "rate limit",
-        "too many requests",
-        "408",
-        "409",
-        "425",
-        "429",
-        "502",
-        "503",
-        "504",
-    ]
-    .iter()
-    .any(|k| msg.contains(k))
+    match provider_error.and_then(|error| error.retry_after_ms) {
+        Some(retry_after_ms) if is_rate_limit => retry_after_ms
+            .max(fallback)
+            .min(SEND_MESSAGE_MAX_RATE_LIMIT_DELAY_MS),
+        Some(retry_after_ms) if retry_after_ms > 0 => {
+            retry_after_ms.min(SEND_MESSAGE_MAX_RATE_LIMIT_DELAY_MS)
+        }
+        Some(_) | None => fallback,
+    }
 }
 
 async fn complete_aggregated_trace(
@@ -584,11 +544,43 @@ fn gemini_response_to_trace(response: &GeminiResponse) -> ModelExchangeResponseT
 
 #[cfg(test)]
 mod tests {
-    use super::{is_transient_stream_error, send_message_retry_delay_ms, AIClient};
+    use super::{send_message_retry_delay_ms, AIClient};
     use crate::providers::{anthropic, gemini, gemini::GeminiMessageConverter, openai};
     use crate::types::{AIConfig, ToolDefinition};
     use crate::types::{ReasoningPresetAction, ReasoningPresetDescriptor};
+    use axum::extract::State;
+    use axum::http::header::CONTENT_TYPE;
+    use axum::response::IntoResponse;
+    use axum::routing::post;
+    use axum::Router;
     use serde_json::{json, Value};
+    use std::sync::{
+        atomic::{AtomicUsize, Ordering},
+        Arc,
+    };
+
+    #[derive(Clone)]
+    struct StreamRetryFixtureState {
+        attempts: Arc<AtomicUsize>,
+    }
+
+    async fn malformed_stream_then_success(
+        State(state): State<StreamRetryFixtureState>,
+    ) -> impl IntoResponse {
+        let payload = if state.attempts.fetch_add(1, Ordering::SeqCst) == 0 {
+            "data: not-json\n\n"
+        } else {
+            concat!(
+                "data: {\"id\":\"chatcmpl_test\",\"object\":\"chat.completion.chunk\",",
+                "\"created\":1,\"model\":\"test-model\",\"choices\":[{\"index\":0,",
+                "\"delta\":{\"content\":\"Recovered\"},\"finish_reason\":\"stop\"}],",
+                "\"usage\":null}\n\n",
+                "data: [DONE]\n\n"
+            )
+        };
+
+        ([(CONTENT_TYPE, "text/event-stream")], payload)
+    }
 
     fn make_test_client(format: &str, custom_request_body: Option<Value>) -> AIClient {
         AIClient::new(AIConfig {
@@ -2255,20 +2247,32 @@ mod tests {
         assert_eq!(request.timeout(), None);
     }
 
-    #[test]
-    fn aggregated_send_message_retries_transient_stream_errors() {
-        for msg in [
-            "SSE Error: stream closed before response completed",
-            "Transport Error: error decoding response body",
-            "Anthropic API is temporarily overloaded",
-            "Gemini SSE stream timeout after 60s",
-            "OpenAI Streaming API error 503: service unavailable",
-        ] {
-            assert!(
-                is_transient_stream_error(msg),
-                "expected transient stream error: {msg}"
-            );
-        }
+    #[tokio::test]
+    async fn aggregated_send_message_retries_every_stream_error() {
+        let attempts = Arc::new(AtomicUsize::new(0));
+        let app = Router::new()
+            .route("/chat/completions", post(malformed_stream_then_success))
+            .with_state(StreamRetryFixtureState {
+                attempts: Arc::clone(&attempts),
+            });
+        let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
+            .await
+            .expect("bind stream retry fixture");
+        let address = listener.local_addr().expect("stream retry fixture address");
+        let server_task = tokio::spawn(async move {
+            axum::serve(listener, app)
+                .await
+                .expect("stream retry fixture should run");
+        });
+        let mut client = make_test_client("openai", None);
+        client.config.request_url = format!("http://{address}/chat/completions");
+
+        let result = client.send_test_message(Vec::new(), None, 2).await;
+
+        server_task.abort();
+        let response = result.expect("the second stream attempt should succeed");
+        assert_eq!(response.text, "Recovered");
+        assert_eq!(attempts.load(Ordering::SeqCst), 2);
     }
 
     #[test]
@@ -2292,18 +2296,4 @@ mod tests {
         );
         assert_eq!(send_message_retry_delay_ms(5, "too many requests"), 60_000);
     }
-
-    #[test]
-    fn aggregated_send_message_does_not_retry_permanent_errors() {
-        for msg in [
-            "OpenAI Streaming API client error 401: unauthorized",
-            "SSE Parsing Error: missing field choices",
-            "Provider error: provider=glm, code=1113, message=余额不足或无可用资源包",
-        ] {
-            assert!(
-                !is_transient_stream_error(msg),
-                "expected permanent stream error: {msg}"
-            );
-        }
-    }
 }
diff --git a/src/crates/adapters/ai-adapters/src/client/sse.rs b/src/crates/adapters/ai-adapters/src/client/sse.rs
index 07eff41b74..560f1da90e 100644
--- a/src/crates/adapters/ai-adapters/src/client/sse.rs
+++ b/src/crates/adapters/ai-adapters/src/client/sse.rs
@@ -3,7 +3,7 @@ use crate::client::StreamResponse;
 use crate::stream::UnifiedResponse;
 use crate::trace::{ModelExchangeRequestAttempt, ModelExchangeTraceConfig};
 use anyhow::{anyhow, Result};
-use bitfun_core_types::errors::{AiProviderError, ErrorCategory};
+use bitfun_core_types::errors::AiProviderError;
 use chrono::{DateTime, Utc};
 use futures::Stream;
 use log::{debug, error, warn};
@@ -101,10 +101,6 @@ fn format_transport_error(label: &str, error: &reqwest::Error) -> String {
     message
 }
 
-fn is_retryable_http_status(status: StatusCode) -> bool {
-    status.is_server_error() || matches!(status.as_u16(), 408 | 409 | 425 | 429)
-}
-
 fn provider_error_code(body: &str) -> Option<String> {
     let value: serde_json::Value = serde_json::from_str(body).ok()?;
     let error = value.get("error").unwrap_or(&value);
@@ -122,6 +118,7 @@ fn http_provider_error(
     status: StatusCode,
     error_text: &str,
     error_kind: &str,
+    retry_after_ms: Option<u64>,
 ) -> AiProviderError {
     AiProviderError::from_parts(
         format!("{} {} {}: {}", label, error_kind, status, error_text),
@@ -129,6 +126,7 @@ fn http_provider_error(
         provider_error_code(error_text),
         Some(status.as_u16()),
     )
+    .with_retry_after_ms(retry_after_ms)
 }
 
 fn exponential_retry_delay_ms(attempt: usize) -> u64 {
@@ -271,26 +269,6 @@ where
                 let http_version = resp.version();
                 let headers = resp.headers().clone();
 
-                if status.is_client_error() && !is_retryable_http_status(status) {
-                    let error_text = resp
-                        .text()
-                        .await
-                        .unwrap_or_else(|e| format!("Failed to read error response: {}", e));
-                    let provider_error =
-                        http_provider_error(label, status, &error_text, "client error");
-                    if let Some(trace) = trace.as_ref() {
-                        trace
-                            .sink
-                            .request_attempt_failed(
-                                trace_handle.as_ref(),
-                                &provider_error.to_string(),
-                            )
-                            .await;
-                    }
-                    error!("{}", provider_error);
-                    return Err(anyhow!(provider_error));
-                }
-
                 if status.is_success() {
                     debug!(
                         "{} request connected: {}ms, status: {}, protocol: {:?}, transport_attempt: {}/{}",
@@ -307,20 +285,18 @@ where
                         .text()
                         .await
                         .unwrap_or_else(|e| format!("Failed to read error response: {}", e));
-                    let provider_error = http_provider_error(label, status, &error_text, "error");
-                    if provider_error.category == ErrorCategory::ContextOverflow {
-                        if let Some(trace) = trace.as_ref() {
-                            trace
-                                .sink
-                                .request_attempt_failed(
-                                    trace_handle.as_ref(),
-                                    &provider_error.to_string(),
-                                )
-                                .await;
-                        }
-                        error!("{}", provider_error);
-                        return Err(anyhow!(provider_error));
-                    }
+                    let error_kind = if status.is_client_error() {
+                        "client error"
+                    } else {
+                        "error"
+                    };
+                    let provider_error = http_provider_error(
+                        label,
+                        status,
+                        &error_text,
+                        error_kind,
+                        retry_after_delay_ms(&headers),
+                    );
                     let error = anyhow!(provider_error);
                     warn!(
                         "{} request failed: {}ms, transport_attempt {}/{}, error: {}",
@@ -444,25 +420,78 @@ where
         });
     }
 
-    let error_msg = format!(
-        "{} failed after {} attempts: {}",
-        label,
-        max_tries,
-        last_error.unwrap_or_else(|| anyhow!("Unknown error"))
-    );
-    error!("{}", error_msg);
-    Err(anyhow!(error_msg))
+    let last_error = last_error.unwrap_or_else(|| anyhow!("Unknown error"));
+    let error_context = format!("{} failed after {} attempts", label, max_tries);
+    error!("{}: {}", error_context, last_error);
+    Err(last_error.context(error_context))
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
+    use axum::extract::State;
+    use axum::response::IntoResponse;
+    use axum::routing::post;
+    use axum::{Json, Router};
+    use bitfun_core_types::errors::ErrorCategory;
     use reqwest::header::HeaderValue;
     use std::sync::{
-        atomic::{AtomicBool, Ordering},
+        atomic::{AtomicBool, AtomicUsize, Ordering},
         Arc,
     };
 
+    #[derive(Clone)]
+    struct RetryFixtureState {
+        attempts: Arc<AtomicUsize>,
+    }
+
+    async fn bad_requests_then_success(
+        State(state): State<RetryFixtureState>,
+        Json(body): Json<serde_json::Value>,
+    ) -> impl IntoResponse {
+        assert_eq!(body["model"], "configured-model");
+        match state.attempts.fetch_add(1, Ordering::SeqCst) {
+            0 => (
+                StatusCode::BAD_REQUEST,
+                Json(serde_json::json!({
+                    "error": {
+                        "message": "Invalid temperature value",
+                        "type": "invalid_request_error",
+                        "code": "invalid_parameter"
+                    }
+                })),
+            )
+                .into_response(),
+            1 => (
+                StatusCode::BAD_REQUEST,
+                Json(serde_json::json!({
+                    "error": {
+                        "message": "Maximum context length exceeded",
+                        "type": "invalid_request_error",
+                        "code": "context_length_exceeded"
+                    }
+                })),
+            )
+                .into_response(),
+            _ => StatusCode::OK.into_response(),
+        }
+    }
+
+    async fn forbidden_with_retry_after(Json(body): Json<serde_json::Value>) -> impl IntoResponse {
+        assert_eq!(body["model"], "configured-model");
+        (
+            StatusCode::FORBIDDEN,
+            [("retry-after", "7")],
+            Json(serde_json::json!({
+                "error": {
+                    "message": "provider authorization denied",
+                    "type": "permission_error",
+                    "code": "permission_denied"
+                }
+            })),
+        )
+    }
+
     #[test]
     fn http_error_uses_structured_code_before_generic_message() {
         let error = http_provider_error(
@@ -470,6 +499,7 @@ mod tests {
             StatusCode::BAD_REQUEST,
             r#"{"error":{"code":"context_length_exceeded","message":"Request failed"}}"#,
             "client error",
+            None,
         );
 
         assert_eq!(error.category, ErrorCategory::ContextOverflow);
@@ -487,6 +517,7 @@ mod tests {
             StatusCode::BAD_REQUEST,
             "400 status code (no body)",
             "client error",
+            None,
         );
 
         assert_eq!(error.category, ErrorCategory::InvalidRequest);
@@ -536,16 +567,89 @@ mod tests {
         assert!(observed_cancel.load(Ordering::SeqCst));
     }
 
-    #[test]
-    fn retryable_http_statuses_include_rate_limit_and_server_errors() {
-        assert!(is_retryable_http_status(StatusCode::TOO_MANY_REQUESTS));
-        assert!(is_retryable_http_status(StatusCode::REQUEST_TIMEOUT));
-        assert!(is_retryable_http_status(StatusCode::INTERNAL_SERVER_ERROR));
-        assert!(is_retryable_http_status(StatusCode::BAD_GATEWAY));
-
-        assert!(!is_retryable_http_status(StatusCode::UNAUTHORIZED));
-        assert!(!is_retryable_http_status(StatusCode::BAD_REQUEST));
-        assert!(!is_retryable_http_status(StatusCode::NOT_FOUND));
+    #[tokio::test]
+    async fn every_bad_request_uses_existing_retry_loop() {
+        let attempts = Arc::new(AtomicUsize::new(0));
+        let app = Router::new()
+            .route("/chat/completions", post(bad_requests_then_success))
+            .with_state(RetryFixtureState {
+                attempts: Arc::clone(&attempts),
+            });
+        let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
+            .await
+            .expect("bind retry fixture");
+        let address = listener.local_addr().expect("retry fixture address");
+        let server_task = tokio::spawn(async move {
+            axum::serve(listener, app)
+                .await
+                .expect("retry fixture should run");
+        });
+        let url = format!("http://{address}/chat/completions");
+        let client = reqwest::Client::new();
+        let request_body = serde_json::json!({"model": "configured-model"});
+
+        let result = execute_sse_request(
+            "OpenAI Streaming API",
+            &url,
+            &request_body,
+            3,
+            None,
+            None,
+            || client.post(&url),
+            |_response, tx, _tx_raw, _remaining_ttft_timeout| async move {
+                drop(tx);
+            },
+        )
+        .await;
+
+        server_task.abort();
+        assert!(
+            result.is_ok(),
+            "ordinary and context-overflow 400 responses should both retry"
+        );
+        assert_eq!(attempts.load(Ordering::SeqCst), 3);
+    }
+
+    #[tokio::test]
+    async fn single_attempt_preserves_retry_after_metadata_for_outer_budget() {
+        let app = Router::new().route("/chat/completions", post(forbidden_with_retry_after));
+        let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
+            .await
+            .expect("bind retry-after fixture");
+        let address = listener.local_addr().expect("retry-after fixture address");
+        let server_task = tokio::spawn(async move {
+            axum::serve(listener, app)
+                .await
+                .expect("retry-after fixture should run");
+        });
+        let url = format!("http://{address}/chat/completions");
+        let client = reqwest::Client::new();
+        let request_body = serde_json::json!({"model": "configured-model"});
+
+        let result = execute_sse_request(
+            "OpenAI Streaming API",
+            &url,
+            &request_body,
+            1,
+            None,
+            None,
+            || client.post(&url),
+            |_response, tx, _tx_raw, _remaining_ttft_timeout| async move {
+                drop(tx);
+            },
+        )
+        .await;
+
+        server_task.abort();
+        let error = match result {
+            Ok(_) => panic!("single forbidden response should fail"),
+            Err(error) => error,
+        };
+        let provider_error = error
+            .downcast_ref::<AiProviderError>()
+            .expect("structured provider error should survive retry context");
+        assert_eq!(provider_error.http_status, Some(403));
+        assert_eq!(provider_error.retry_after_ms, Some(7_000));
     }
 
     #[test]
diff --git a/src/crates/adapters/ai-adapters/src/models_dev.rs b/src/crates/adapters/ai-adapters/src/models_dev.rs
index a444952b58..bb05ca466d 100644
--- a/src/crates/adapters/ai-adapters/src/models_dev.rs
+++ b/src/crates/adapters/ai-adapters/src/models_dev.rs
@@ -567,6 +567,7 @@ pub fn project_reasoning_catalog_with_limit_and_auto_binding(
     };
 
     let mut descriptors = BTreeMap::<String, ReasoningPresetDescriptor>::new();
+    let mut unavailable_descriptors = BTreeMap::<String, ReasoningPresetDescriptor>::new();
     let mut has_unmapped_reasoning = false;
     if let Some((source_provider, source_model)) = source_match {
         if source_model.reasoning {
@@ -606,6 +607,37 @@ pub fn project_reasoning_catalog_with_limit_and_auto_binding(
                     | ModelsDevReasoningOption::Toggle
                     | ModelsDevReasoningOption::BudgetTokens { .. } => {
                         has_unmapped_reasoning = true;
+                        if matches!(binding, ReasoningCatalogBinding::ModelsDev { .. }) {
+                            let unavailable = match option {
+                                ModelsDevReasoningOption::Effort { values } => effort_descriptors(
+                                    values,
+                                    support.nullable_effort,
+                                    ReasoningPresetSource::ModelsDev,
+                                    source_provider,
+                                    &source_model.id,
+                                ),
+                                ModelsDevReasoningOption::Toggle => toggle_descriptors(
+                                    ReasoningPresetSource::ModelsDev,
+                                    source_provider,
+                                    &source_model.id,
+                                ),
+                                ModelsDevReasoningOption::BudgetTokens { min, max } => {
+                                    budget_descriptors(
+                                        *min,
+                                        *max,
+                                        source_model.output_limit,
+                                        effective_max_output_tokens,
+                                        provider,
+                                        ReasoningPresetSource::ModelsDev,
+                                        source_provider,
+                                        &source_model.id,
+                                    )
+                                }
+                            };
+                            for descriptor in unavailable {
+                                unavailable_descriptors.insert(descriptor.id.clone(), descriptor);
+                            }
+                        }
                         Vec::new()
                     }
                 };
@@ -673,12 +705,15 @@ pub fn project_reasoning_catalog_with_limit_and_auto_binding(
             }
             if preset.disabled {
                 descriptors.remove(preset_id);
+                unavailable_descriptors.remove(preset_id);
                 continue;
             }
             if preset.actions.is_empty() {
                 descriptors.remove(preset_id);
+                unavailable_descriptors.remove(preset_id);
                 continue;
             }
+            unavailable_descriptors.remove(preset_id);
             descriptors.insert(
                 preset_id.to_string(),
                 ReasoningPresetDescriptor {
@@ -704,6 +739,12 @@ pub fn project_reasoning_catalog_with_limit_and_auto_binding(
             .cmp(&right.order)
             .then_with(|| left.id.cmp(&right.id))
     });
+    let mut unavailable_presets = unavailable_descriptors.into_values().collect::<Vec<_>>();
+    unavailable_presets.sort_by(|left, right| {
+        left.order
+            .cmp(&right.order)
+            .then_with(|| left.id.cmp(&right.id))
+    });
     let status = if !presets.is_empty() {
         ReasoningCapabilityStatus::Known
     } else if matches!(binding, ReasoningCatalogBinding::Disabled) {
@@ -731,6 +772,7 @@ pub fn project_reasoning_catalog_with_limit_and_auto_binding(
         status,
         default_preset: default_preset.map(ToOwned::to_owned),
         presets,
+        unavailable_presets,
     }
 }
 
@@ -1193,7 +1235,9 @@ mod tests {
                 }},
                 "anthropic": {"models": {
                     "claude-sonnet-4-6": {"id":"claude-sonnet-4-6","reasoning":true,
-                        "reasoning_options":[{"type":"effort","values":["low","high"]},{"type":"budget_tokens","min":1024}]}
+                        "reasoning_options":[{"type":"effort","values":["low","high"]},{"type":"budget_tokens","min":1024}]},
+                    "claude-fable-5": {"id":"claude-fable-5","reasoning":true,
+                        "reasoning_options":{"type":"effort","values":["low","medium","high","xhigh","max"]}}
                 }},
                 "deepseek": {"models": {
                     "deepseek-v4-flash": {"id":"deepseek-v4-flash","reasoning":true,
@@ -1916,6 +1960,35 @@ mod tests {
         }));
     }
 
+    #[test]
+    fn explicit_anthropic_binding_reports_efforts_unavailable_to_openai_chat() {
+        let configured = ReasoningConfig {
+            catalog: ReasoningCatalogBinding::ModelsDev {
+                provider: "anthropic".to_string(),
+                model: "claude-fable-5".to_string(),
+            },
+            ..Default::default()
+        };
+        let projection = project_reasoning_catalog(
+            "openai",
+            "dummy-model",
+            "http://localhost:8000/v1/chat/completions",
+            Some(&configured),
+            Some(&catalog()),
+        );
+
+        assert_eq!(projection.status, ReasoningCapabilityStatus::Unknown);
+        assert!(projection.presets.is_empty());
+        assert_eq!(
+            projection
+                .unavailable_presets
+                .iter()
+                .map(|preset| preset.id.as_str())
+                .collect::<Vec<_>>(),
+            ["low", "medium", "high", "xhigh", "max"]
+        );
+    }
+
     #[test]
     fn custom_presets_keep_the_explicit_catalog_identity_for_adapter_compilation() {
         let configured = ReasoningConfig {
diff --git a/src/crates/adapters/ai-adapters/tests/ai_protocol_contracts.rs b/src/crates/adapters/ai-adapters/tests/ai_protocol_contracts.rs
new file mode 100644
index 0000000000..ba553f50be
--- /dev/null
+++ b/src/crates/adapters/ai-adapters/tests/ai_protocol_contracts.rs
@@ -0,0 +1,4 @@
+#[path = "ai_protocol_contracts/model_selector.rs"]
+mod model_selector;
+#[path = "ai_protocol_contracts/openai_empty_content_parts.rs"]
+mod openai_empty_content_parts;
diff --git a/src/crates/adapters/ai-adapters/tests/model_selector.rs b/src/crates/adapters/ai-adapters/tests/ai_protocol_contracts/model_selector.rs
similarity index 100%
rename from src/crates/adapters/ai-adapters/tests/model_selector.rs
rename to src/crates/adapters/ai-adapters/tests/ai_protocol_contracts/model_selector.rs
diff --git a/src/crates/adapters/ai-adapters/tests/openai_empty_content_parts.rs b/src/crates/adapters/ai-adapters/tests/ai_protocol_contracts/openai_empty_content_parts.rs
similarity index 100%
rename from src/crates/adapters/ai-adapters/tests/openai_empty_content_parts.rs
rename to src/crates/adapters/ai-adapters/tests/ai_protocol_contracts/openai_empty_content_parts.rs
diff --git a/src/crates/adapters/ai-adapters/tests/ai_stream_contracts.rs b/src/crates/adapters/ai-adapters/tests/ai_stream_contracts.rs
new file mode 100644
index 0000000000..0a1dd8ec51
--- /dev/null
+++ b/src/crates/adapters/ai-adapters/tests/ai_stream_contracts.rs
@@ -0,0 +1,12 @@
+#[path = "ai_stream_contracts/common.rs"]
+mod common;
+#[path = "ai_stream_contracts/stream_processor_anthropic.rs"]
+mod stream_processor_anthropic;
+#[path = "ai_stream_contracts/stream_processor_openai.rs"]
+mod stream_processor_openai;
+#[path = "ai_stream_contracts/stream_processor_tool_arguments.rs"]
+mod stream_processor_tool_arguments;
+#[path = "ai_stream_contracts/stream_replay_regressions.rs"]
+mod stream_replay_regressions;
+#[path = "ai_stream_contracts/stream_test_harness.rs"]
+mod stream_test_harness;
diff --git a/src/crates/adapters/ai-adapters/tests/ai_stream_contracts/common.rs b/src/crates/adapters/ai-adapters/tests/ai_stream_contracts/common.rs
new file mode 100644
index 0000000000..6f78b75e3b
--- /dev/null
+++ b/src/crates/adapters/ai-adapters/tests/ai_stream_contracts/common.rs
@@ -0,0 +1,6 @@
+#[path = "../common/fixture_loader.rs"]
+pub(crate) mod fixture_loader;
+#[path = "../common/sse_fixture_server.rs"]
+pub(crate) mod sse_fixture_server;
+#[path = "../common/stream_test_harness.rs"]
+pub(crate) mod stream_test_harness;
diff --git a/src/crates/adapters/ai-adapters/tests/stream_processor_anthropic.rs b/src/crates/adapters/ai-adapters/tests/ai_stream_contracts/stream_processor_anthropic.rs
similarity index 99%
rename from src/crates/adapters/ai-adapters/tests/stream_processor_anthropic.rs
rename to src/crates/adapters/ai-adapters/tests/ai_stream_contracts/stream_processor_anthropic.rs
index d8361e0c2e..0025ad2a37 100644
--- a/src/crates/adapters/ai-adapters/tests/stream_processor_anthropic.rs
+++ b/src/crates/adapters/ai-adapters/tests/ai_stream_contracts/stream_processor_anthropic.rs
@@ -1,9 +1,7 @@
-mod common;
-
-use bitfun_events::AgenticEvent;
-use common::stream_test_harness::{
+use crate::common::stream_test_harness::{
     run_stream_fixture_with_options, StreamFixtureProvider, StreamFixtureRunOptions,
 };
+use bitfun_events::AgenticEvent;
 use serde_json::json;
 
 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
diff --git a/src/crates/adapters/ai-adapters/tests/stream_processor_openai.rs b/src/crates/adapters/ai-adapters/tests/ai_stream_contracts/stream_processor_openai.rs
similarity index 99%
rename from src/crates/adapters/ai-adapters/tests/stream_processor_openai.rs
rename to src/crates/adapters/ai-adapters/tests/ai_stream_contracts/stream_processor_openai.rs
index 133cb34698..95cc8d613f 100644
--- a/src/crates/adapters/ai-adapters/tests/stream_processor_openai.rs
+++ b/src/crates/adapters/ai-adapters/tests/ai_stream_contracts/stream_processor_openai.rs
@@ -1,11 +1,9 @@
-mod common;
-
-use bitfun_events::{AgenticEvent, ToolEventData};
-use common::sse_fixture_server::FixtureSseServerOptions;
-use common::stream_test_harness::{
+use crate::common::sse_fixture_server::FixtureSseServerOptions;
+use crate::common::stream_test_harness::{
     run_stream_fixture, run_stream_fixture_with_options, StreamFixtureProvider,
     StreamFixtureRunOptions,
 };
+use bitfun_events::{AgenticEvent, ToolEventData};
 use serde_json::json;
 
 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
diff --git a/src/crates/adapters/ai-adapters/tests/stream_processor_tool_arguments.rs b/src/crates/adapters/ai-adapters/tests/ai_stream_contracts/stream_processor_tool_arguments.rs
similarity index 94%
rename from src/crates/adapters/ai-adapters/tests/stream_processor_tool_arguments.rs
rename to src/crates/adapters/ai-adapters/tests/ai_stream_contracts/stream_processor_tool_arguments.rs
index 64f2c91829..62e88cfd5c 100644
--- a/src/crates/adapters/ai-adapters/tests/stream_processor_tool_arguments.rs
+++ b/src/crates/adapters/ai-adapters/tests/ai_stream_contracts/stream_processor_tool_arguments.rs
@@ -1,8 +1,6 @@
-mod common;
-
+use crate::common::sse_fixture_server::FixtureSseServerOptions;
+use crate::common::stream_test_harness::{run_stream_fixture, StreamFixtureProvider};
 use bitfun_events::AgenticEvent;
-use common::sse_fixture_server::FixtureSseServerOptions;
-use common::stream_test_harness::{run_stream_fixture, StreamFixtureProvider};
 use serde_json::json;
 
 fn assert_no_stream_failure_event(events: &[AgenticEvent]) {
diff --git a/src/crates/adapters/ai-adapters/tests/stream_replay_regressions.rs b/src/crates/adapters/ai-adapters/tests/ai_stream_contracts/stream_replay_regressions.rs
similarity index 98%
rename from src/crates/adapters/ai-adapters/tests/stream_replay_regressions.rs
rename to src/crates/adapters/ai-adapters/tests/ai_stream_contracts/stream_replay_regressions.rs
index 80b96afc88..c499c7ec69 100644
--- a/src/crates/adapters/ai-adapters/tests/stream_replay_regressions.rs
+++ b/src/crates/adapters/ai-adapters/tests/ai_stream_contracts/stream_replay_regressions.rs
@@ -1,14 +1,12 @@
-mod common;
-
+use crate::common::sse_fixture_server::FixtureSseServerOptions;
+use crate::common::stream_test_harness::{
+    run_stream_fixture, run_stream_fixture_with_options, StreamFixtureProvider,
+    StreamFixtureRunOptions,
+};
 use bitfun_agent_stream::StreamResult;
 use bitfun_ai_adapters::providers::{openai::OpenAIMessageConverter, AnthropicMessageConverter};
 use bitfun_ai_adapters::{Message as AIMessage, ToolCall as AIToolCall};
 use bitfun_events::{AgenticEvent, ToolEventData};
-use common::sse_fixture_server::FixtureSseServerOptions;
-use common::stream_test_harness::{
-    run_stream_fixture, run_stream_fixture_with_options, StreamFixtureProvider,
-    StreamFixtureRunOptions,
-};
 use serde_json::json;
 
 fn build_replay_assistant_message(result: &StreamResult) -> AIMessage {
diff --git a/src/crates/adapters/ai-adapters/tests/stream_test_harness.rs b/src/crates/adapters/ai-adapters/tests/ai_stream_contracts/stream_test_harness.rs
similarity index 94%
rename from src/crates/adapters/ai-adapters/tests/stream_test_harness.rs
rename to src/crates/adapters/ai-adapters/tests/ai_stream_contracts/stream_test_harness.rs
index 98168c6994..55bcce0646 100644
--- a/src/crates/adapters/ai-adapters/tests/stream_test_harness.rs
+++ b/src/crates/adapters/ai-adapters/tests/ai_stream_contracts/stream_test_harness.rs
@@ -1,7 +1,5 @@
-mod common;
-
-use common::sse_fixture_server::FixtureSseServerOptions;
-use common::stream_test_harness::{
+use crate::common::sse_fixture_server::FixtureSseServerOptions;
+use crate::common::stream_test_harness::{
     run_stream_fixture_with_options, StreamFixtureProvider, StreamFixtureRunOptions,
 };
 use std::time::Duration;
diff --git a/src/crates/adapters/claude-code-adapter/Cargo.toml b/src/crates/adapters/claude-code-adapter/Cargo.toml
index dc7ae1510e..5afe861df7 100644
--- a/src/crates/adapters/claude-code-adapter/Cargo.toml
+++ b/src/crates/adapters/claude-code-adapter/Cargo.toml
@@ -4,14 +4,15 @@ version.workspace = true
 authors.workspace = true
 edition.workspace = true
 description = "Claude Code static source adapter for BitFun"
+autotests = false
 
 [lib]
 name = "bitfun_claude_code_adapter"
 crate-type = ["rlib"]
 
 [dependencies]
-bitfun-product-domains = { path = "../../contracts/product-domains", default-features = false, features = ["external-sources"] }
-bitfun-services-core = { path = "../../services/services-core", default-features = false, features = ["markdown"] }
+bitfun-product-domains = { path = "../../contracts/product-domains", features = ["external-sources"] }
+bitfun-services-core = { path = "../../services/services-core", features = ["markdown"] }
 bitfun-static-hook-support = { path = "../static-hook-support" }
 dirs = { workspace = true }
 dunce = { workspace = true }
@@ -26,5 +27,9 @@ url = { workspace = true }
 [dev-dependencies]
 tempfile = { workspace = true }
 
+[[test]]
+name = "claude_code_source_contracts"
+path = "tests/claude_code_source_contracts.rs"
+
 [lints]
 workspace = true
diff --git a/src/crates/adapters/claude-code-adapter/src/agent_source.rs b/src/crates/adapters/claude-code-adapter/src/agent_source.rs
index db8778c581..e1ec75dac1 100644
--- a/src/crates/adapters/claude-code-adapter/src/agent_source.rs
+++ b/src/crates/adapters/claude-code-adapter/src/agent_source.rs
@@ -14,8 +14,8 @@ use bitfun_product_domains::external_subagents::{
 };
 use bitfun_services_core::markdown::FrontMatterMarkdown;
 use bitfun_static_hook_support::{
-    collect_bounded_regular_files, read_bounded_text, BoundedDirectoryWalkError,
-    BoundedDirectoryWalkLimits, BoundedTextRead,
+    collect_bounded_regular_files, common_external_subagent_tool_capability, read_bounded_text,
+    BoundedDirectoryWalkError, BoundedDirectoryWalkLimits, BoundedTextRead,
 };
 use serde_json::{Map, Value};
 use sha2::{Digest, Sha256};
@@ -27,7 +27,6 @@ const ECOSYSTEM_ID: &str = "claude-code";
 const MAX_AGENT_FILES: usize = 2048;
 const MAX_AGENT_FILE_BYTES: usize = 256 * 1024;
 const MAX_TOTAL_PROMPT_BYTES: usize = 8 * 1024 * 1024;
-
 const KNOWN_FIELDS: &[&str] = &[
     "name",
     "description",
@@ -630,7 +629,7 @@ fn tool_request(
         selectors: selectors
             .into_iter()
             .map(|(source_name, allowed)| ExternalSubagentToolSelector {
-                canonical_host_name: canonical_tool_name(&source_name).map(str::to_string),
+                canonical_capability: common_external_subagent_tool_capability(&source_name),
                 source_name,
                 allowed,
             })
@@ -657,16 +656,6 @@ fn string_list(value: &Value) -> Option<Vec<String>> {
     }
 }
 
-fn canonical_tool_name(name: &str) -> Option<&'static str> {
-    match name.to_ascii_lowercase().as_str() {
-        "ls" | "list" => Some("LS"),
-        "read" => Some("Read"),
-        "glob" => Some("Glob"),
-        "grep" => Some("Grep"),
-        _ => None,
-    }
-}
-
 fn source_record(
     file: &AgentFile,
     key: SourceKey,
diff --git a/src/crates/adapters/claude-code-adapter/tests/claude_code_source_contracts.rs b/src/crates/adapters/claude-code-adapter/tests/claude_code_source_contracts.rs
new file mode 100644
index 0000000000..29346cbf23
--- /dev/null
+++ b/src/crates/adapters/claude-code-adapter/tests/claude_code_source_contracts.rs
@@ -0,0 +1,8 @@
+#[path = "claude_code_source_contracts/command_source.rs"]
+mod command_source;
+#[path = "claude_code_source_contracts/hook_source.rs"]
+mod hook_source;
+#[path = "claude_code_source_contracts/mcp_source.rs"]
+mod mcp_source;
+#[path = "claude_code_source_contracts/subagent_source.rs"]
+mod subagent_source;
diff --git a/src/crates/adapters/claude-code-adapter/tests/command_source.rs b/src/crates/adapters/claude-code-adapter/tests/claude_code_source_contracts/command_source.rs
similarity index 100%
rename from src/crates/adapters/claude-code-adapter/tests/command_source.rs
rename to src/crates/adapters/claude-code-adapter/tests/claude_code_source_contracts/command_source.rs
diff --git a/src/crates/adapters/claude-code-adapter/tests/hook_source.rs b/src/crates/adapters/claude-code-adapter/tests/claude_code_source_contracts/hook_source.rs
similarity index 100%
rename from src/crates/adapters/claude-code-adapter/tests/hook_source.rs
rename to src/crates/adapters/claude-code-adapter/tests/claude_code_source_contracts/hook_source.rs
diff --git a/src/crates/adapters/claude-code-adapter/tests/mcp_source.rs b/src/crates/adapters/claude-code-adapter/tests/claude_code_source_contracts/mcp_source.rs
similarity index 100%
rename from src/crates/adapters/claude-code-adapter/tests/mcp_source.rs
rename to src/crates/adapters/claude-code-adapter/tests/claude_code_source_contracts/mcp_source.rs
diff --git a/src/crates/adapters/claude-code-adapter/tests/subagent_source.rs b/src/crates/adapters/claude-code-adapter/tests/claude_code_source_contracts/subagent_source.rs
similarity index 93%
rename from src/crates/adapters/claude-code-adapter/tests/subagent_source.rs
rename to src/crates/adapters/claude-code-adapter/tests/claude_code_source_contracts/subagent_source.rs
index e8b651cc45..1d9cabb642 100644
--- a/src/crates/adapters/claude-code-adapter/tests/subagent_source.rs
+++ b/src/crates/adapters/claude-code-adapter/tests/claude_code_source_contracts/subagent_source.rs
@@ -5,7 +5,7 @@ use bitfun_product_domains::external_sources::{
 use bitfun_product_domains::external_subagents::{
     ExternalSubagentCompatibilityState, ExternalSubagentDiscoveryInput, ExternalSubagentMode,
     ExternalSubagentModelProfileRequest, ExternalSubagentModelRequest,
-    ExternalSubagentSourceProvider,
+    ExternalSubagentSourceProvider, ExternalSubagentToolCapability,
 };
 use std::collections::BTreeSet;
 use std::fs;
@@ -70,6 +70,32 @@ fn write(path: impl AsRef<Path>, contents: &str) {
     fs::write(path, contents).unwrap();
 }
 
+#[test]
+fn claude_code_builtin_tools_map_to_provider_neutral_capabilities() {
+    let fixture = Fixture::new();
+    write(
+        fixture.user_claude.join("agents/worker.md"),
+        "---\nname: worker\ndescription: Worker\ntools: [Bash, Edit, Write]\n---\nMake the requested change",
+    );
+
+    let snapshot = fixture.discover(BTreeSet::new());
+    let mappings = snapshot.definitions[0]
+        .requested_tools
+        .selectors
+        .iter()
+        .map(|selector| (selector.source_name.as_str(), selector.canonical_capability))
+        .collect::<Vec<_>>();
+
+    assert_eq!(
+        mappings,
+        vec![
+            ("Bash", Some(ExternalSubagentToolCapability::ExecuteCommand)),
+            ("Edit", Some(ExternalSubagentToolCapability::EditFile)),
+            ("Write", Some(ExternalSubagentToolCapability::WriteFile)),
+        ]
+    );
+}
+
 #[test]
 fn nearest_project_agent_overrides_user_agent_without_field_merge() {
     let fixture = Fixture::new();
diff --git a/src/crates/adapters/codex-adapter/Cargo.toml b/src/crates/adapters/codex-adapter/Cargo.toml
index 9d6faf176f..11e15c9f6e 100644
--- a/src/crates/adapters/codex-adapter/Cargo.toml
+++ b/src/crates/adapters/codex-adapter/Cargo.toml
@@ -4,14 +4,15 @@ version.workspace = true
 authors.workspace = true
 edition.workspace = true
 description = "Codex static source adapter for BitFun"
+autotests = false
 
 [lib]
 name = "bitfun_codex_adapter"
 crate-type = ["rlib"]
 
 [dependencies]
-bitfun-product-domains = { path = "../../contracts/product-domains", default-features = false, features = ["external-sources"] }
-bitfun-services-core = { path = "../../services/services-core", default-features = false }
+bitfun-product-domains = { path = "../../contracts/product-domains", features = ["external-sources"] }
+bitfun-services-core = { path = "../../services/services-core" }
 bitfun-static-hook-support = { path = "../static-hook-support" }
 dirs = { workspace = true }
 dunce = { workspace = true }
@@ -24,5 +25,9 @@ url = { workspace = true }
 [dev-dependencies]
 tempfile = { workspace = true }
 
+[[test]]
+name = "codex_source_contracts"
+path = "tests/codex_source_contracts.rs"
+
 [lints]
 workspace = true
diff --git a/src/crates/adapters/codex-adapter/tests/codex_source_contracts.rs b/src/crates/adapters/codex-adapter/tests/codex_source_contracts.rs
new file mode 100644
index 0000000000..6c033129c2
--- /dev/null
+++ b/src/crates/adapters/codex-adapter/tests/codex_source_contracts.rs
@@ -0,0 +1,6 @@
+#[path = "codex_source_contracts/hook_source.rs"]
+mod hook_source;
+#[path = "codex_source_contracts/mcp_source.rs"]
+mod mcp_source;
+#[path = "codex_source_contracts/subagent_source.rs"]
+mod subagent_source;
diff --git a/src/crates/adapters/codex-adapter/tests/hook_source.rs b/src/crates/adapters/codex-adapter/tests/codex_source_contracts/hook_source.rs
similarity index 100%
rename from src/crates/adapters/codex-adapter/tests/hook_source.rs
rename to src/crates/adapters/codex-adapter/tests/codex_source_contracts/hook_source.rs
diff --git a/src/crates/adapters/codex-adapter/tests/mcp_source.rs b/src/crates/adapters/codex-adapter/tests/codex_source_contracts/mcp_source.rs
similarity index 100%
rename from src/crates/adapters/codex-adapter/tests/mcp_source.rs
rename to src/crates/adapters/codex-adapter/tests/codex_source_contracts/mcp_source.rs
diff --git a/src/crates/adapters/codex-adapter/tests/subagent_source.rs b/src/crates/adapters/codex-adapter/tests/codex_source_contracts/subagent_source.rs
similarity index 100%
rename from src/crates/adapters/codex-adapter/tests/subagent_source.rs
rename to src/crates/adapters/codex-adapter/tests/codex_source_contracts/subagent_source.rs
diff --git a/src/crates/adapters/dsh-adapter/AGENTS.md b/src/crates/adapters/dsh-adapter/AGENTS.md
new file mode 100644
index 0000000000..c7d742cce0
--- /dev/null
+++ b/src/crates/adapters/dsh-adapter/AGENTS.md
@@ -0,0 +1,34 @@
+# DeepSeek Harness (dsh) Adapter
+
+This crate owns the static, runtime-free projection of DeepSeek Harness (`dsh`)
+plugin package sources. It reads a BitFun-managed package whose
+`bitfun.plugin.json` declares `adapter: "dsh_compatible"`, parses the package's
+`package.json` `dsh` declaration, and projects the discovered bundle entries
+(`dsh.bundle.patch` -> `cordis.patch.yml` rows) and/or profile bundle references
+(`dsh.profile.bundles`) as projection-only plugin sources.
+
+It does not execute Cordis plugins, install npm packages, or depend on a
+user-local `dsh` CLI. Execution of dsh bundles belongs to future Plugin Host /
+external-ACP work, not this adapter boundary.
+
+## Boundary Rules
+
+- Depend on stable contracts (`bitfun-runtime-ports`, `bitfun-product-domains`)
+  and the `PluginRuntimeAdapter` boundary trait. Do not depend on `bitfun-core`,
+  app crates, Tauri APIs, product UI, or concrete service managers.
+- Keep the dsh `package.json` `dsh` field shape and `cordis.patch.yml` entry
+  extraction inside this crate. Cross-crate outputs use typed
+  `PluginSourceRef` / `PluginStatusSnapshot` / `PluginDiagnostic` DTOs; do not
+  expose raw dsh YAML or JSON as product contracts.
+- Cordis rows may mount services that register model-facing tools when dsh runs
+  them, but static row metadata is not an executable BitFun provider candidate.
+  `load_dsh_package_adapter` therefore returns no provider dispatch targets.
+  Unsupported or unparsable content must produce typed invalid projections and
+  diagnostics, never silent success.
+- New ecosystems are sibling adapters registered by Product Assembly
+  (`bitfun-core/plugin_runtime`), not modes of this adapter.
+
+## Verification
+
+- `cargo test --locked -p bitfun-dsh-adapter --test dsh_source_adapter`
+- `cargo test --locked -p bitfun-core --no-default-features --features plugin-runtime --lib plugin_runtime::tests`
diff --git a/src/crates/adapters/dsh-adapter/Cargo.toml b/src/crates/adapters/dsh-adapter/Cargo.toml
new file mode 100644
index 0000000000..da6025a772
--- /dev/null
+++ b/src/crates/adapters/dsh-adapter/Cargo.toml
@@ -0,0 +1,33 @@
+[package]
+name = "bitfun-dsh-adapter"
+version.workspace = true
+authors.workspace = true
+edition.workspace = true
+description = "DeepSeek Harness (dsh) bundle source projection adapter for BitFun"
+autotests = false
+
+[lib]
+name = "bitfun_dsh_adapter"
+crate-type = ["rlib"]
+
+[dependencies]
+async-trait = { workspace = true }
+bitfun-plugin-runtime-client = { path = "../../execution/plugin-runtime-client" }
+bitfun-product-domains = { path = "../../contracts/product-domains", features = ["plugin-source"] }
+bitfun-runtime-ports = { path = "../../contracts/runtime-ports", features = ["plugin-runtime"] }
+hex = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+serde_yaml = { workspace = true }
+sha2 = { workspace = true }
+urlencoding = { workspace = true }
+
+[dev-dependencies]
+tokio = { workspace = true, features = ["macros", "rt"] }
+
+[[test]]
+name = "dsh_source_adapter"
+path = "tests/dsh_source_adapter.rs"
+
+[lints]
+workspace = true
diff --git a/src/crates/adapters/dsh-adapter/src/lib.rs b/src/crates/adapters/dsh-adapter/src/lib.rs
new file mode 100644
index 0000000000..4ac717765d
--- /dev/null
+++ b/src/crates/adapters/dsh-adapter/src/lib.rs
@@ -0,0 +1,11 @@
+//! DeepSeek Harness (`dsh`) bundle source adapter.
+//!
+//! The production surface is intentionally small: load a `dsh`-compatible
+//! managed package (its `package.json` bundle/profile declaration and any
+//! declared `cordis.patch.yml` bundle patch) as a projection-only plugin runtime
+//! adapter. The adapter does not execute Cordis plugins, install npm packages,
+//! or depend on a user-local `dsh` CLI.
+
+mod source_adapter;
+
+pub use source_adapter::load_dsh_package_adapter;
diff --git a/src/crates/adapters/dsh-adapter/src/source_adapter.rs b/src/crates/adapters/dsh-adapter/src/source_adapter.rs
new file mode 100644
index 0000000000..d382e54981
--- /dev/null
+++ b/src/crates/adapters/dsh-adapter/src/source_adapter.rs
@@ -0,0 +1,1361 @@
+//! DeepSeek Harness (`dsh`) bundle source projection.
+//!
+//! The adapter covers the `dsh` distribution shape: a `package.json` whose
+//! `dsh` field declares a bundle (`dsh.bundle.patch` -> a
+//! `cordis.patch.yml` list of Cordis plugin rows), a profile
+//! (`dsh.profile.bundles` -> an ordered list of bundle names). It projects the
+//! discovered entries for either or both roles as projection-only plugin
+//! sources. It does not execute JavaScript, install packages, or become the
+//! runtime client.
+
+use async_trait::async_trait;
+use bitfun_plugin_runtime_client::PluginRuntimeAdapter;
+use bitfun_product_domains::plugin_source::{
+    PluginActivationAuthority, PluginPackageInput, PluginPackageSourceIdentity,
+};
+use bitfun_runtime_ports::{
+    PluginAuditRef, PluginConfigValidationIssue, PluginConfigValidationState,
+    PluginConfigValidationStatus, PluginDiagnostic, PluginDiagnosticDetail,
+    PluginDiagnosticSeverity, PluginDispatchEnvelope, PluginManifestRef, PluginResponseEnvelope,
+    PluginRuntimeAvailability, PluginRuntimeEpochs, PluginRuntimeReadRequest,
+    PluginRuntimeReadResponse, PluginRuntimeUnavailableReason, PluginSourceKind, PluginSourceRef,
+    PluginStatusKind, PluginStatusSnapshot, PluginTrustLevel, PortError, PortErrorKind, PortResult,
+};
+use serde::Deserialize;
+use sha2::{Digest, Sha256};
+use std::collections::{BTreeMap, HashSet};
+use std::sync::Arc;
+
+const DSH_ADAPTER_ID: &str = "dsh-compatible";
+const DSH_MANIFEST_ADAPTER_ID: &str = "dsh_compatible";
+const DSH_PACKAGE_SCHEMA_VERSION: &str = "dsh.package.v1";
+const DSH_BUNDLE_SCHEMA_VERSION: &str = "dsh.bundle.v1";
+const DSH_PROFILE_SCHEMA_VERSION: &str = "dsh.profile.v1";
+const PACKAGE_JSON: &str = "package.json";
+const MAX_PLUGIN_ID_COMPONENT_LEN: usize = 40;
+const MAX_ENTRIES_PER_PACKAGE: usize = 256;
+const MAX_ENTRY_ID_BYTES: usize = 256;
+const MAX_PROFILE_BUNDLES: usize = 128;
+const MAX_PROFILE_BUNDLE_NAME_BYTES: usize = 256;
+
+struct DshPluginRuntimeAdapter {
+    projections: Vec<DshProjection>,
+    observed_at_ms: u64,
+    activation: Option<DshActivationContext>,
+}
+
+struct DshActivationContext {
+    project_domain_id: String,
+    workspace_id: String,
+    activation_epoch: u64,
+}
+
+impl DshPluginRuntimeAdapter {
+    fn from_package(input: PluginPackageInput, observed_at_ms: u64) -> PortResult<Self> {
+        let (manifest, source, files) = input.into_parts();
+        if manifest.adapter != DSH_MANIFEST_ADAPTER_ID {
+            return Err(adapter_port_error(format!(
+                "managed package adapter is not dsh-compatible: {}",
+                manifest.adapter
+            )));
+        }
+        let provenance_id = sha256_content_hash(&source.source_path)
+            .trim_start_matches("sha256:")
+            .to_string();
+        let package_uri = format!(
+            "bitfun://managed-plugins/{provenance_id}/{}",
+            urlencoding::encode(&source.package_id)
+        );
+        let package_json_uri = format!(
+            "bitfun://managed-plugins/{provenance_id}/{}/{PACKAGE_JSON}",
+            source.package_id
+        );
+        let projections = project_package(
+            &files,
+            &provenance_id,
+            &source,
+            &package_uri,
+            &package_json_uri,
+            observed_at_ms,
+        )?;
+        Ok(Self {
+            projections,
+            observed_at_ms,
+            activation: None,
+        })
+    }
+
+    fn from_activated_package(
+        input: PluginPackageInput,
+        authority: PluginActivationAuthority,
+        observed_at_ms: u64,
+    ) -> PortResult<Self> {
+        let (project_domain_id, workspace_id, authority_source, activation_epoch) =
+            authority.into_parts();
+        let (manifest, source, files) = input.into_parts();
+        if source != authority_source {
+            return Err(PortError::new(
+                PortErrorKind::InvalidRequest,
+                "dsh package input does not match its activation authority",
+            ));
+        }
+        let input = PluginPackageInput::new(manifest, source, files)
+            .map_err(|error| PortError::new(PortErrorKind::InvalidRequest, error.to_string()))?;
+        let mut adapter = Self::from_package(input, observed_at_ms)?;
+        if adapter.projections.iter().any(DshProjection::is_invalid) {
+            return Err(adapter_port_error(
+                "invalid dsh package projection cannot be activated".to_string(),
+            ));
+        }
+        for projection in &mut adapter.projections {
+            projection.activate_supported_source();
+        }
+        adapter.activation = Some(DshActivationContext {
+            project_domain_id,
+            workspace_id,
+            activation_epoch,
+        });
+        Ok(adapter)
+    }
+
+    fn validate_activation_scope(
+        &self,
+        project_domain_id: &str,
+        workspace_id: &str,
+        epochs: &PluginRuntimeEpochs,
+    ) -> PortResult<()> {
+        let Some(activation) = &self.activation else {
+            return Ok(());
+        };
+        if activation.project_domain_id != project_domain_id
+            || activation.workspace_id != workspace_id
+            || activation.activation_epoch != epochs.trust_epoch
+        {
+            return Err(PortError::new(
+                PortErrorKind::NotAvailable,
+                "dsh package activation scope or epoch is stale",
+            ));
+        }
+        Ok(())
+    }
+
+    fn activation_matches(
+        &self,
+        project_domain_id: &str,
+        workspace_id: &str,
+        epochs: &PluginRuntimeEpochs,
+    ) -> bool {
+        self.activation.as_ref().is_none_or(|activation| {
+            activation.project_domain_id == project_domain_id
+                && activation.workspace_id == workspace_id
+                && activation.activation_epoch == epochs.trust_epoch
+        })
+    }
+
+    fn projection_for_source(&self, source: &PluginSourceRef) -> Option<&DshProjection> {
+        self.projections
+            .iter()
+            .find(|projection| source_identity_matches(projection.source_ref(), source))
+    }
+
+    fn source_mismatch_response(&self, envelope: PluginDispatchEnvelope) -> PluginResponseEnvelope {
+        self.unavailable_response(
+            envelope,
+            "dsh.source_mismatch",
+            "dsh dispatch source does not match a loaded source snapshot",
+            false,
+        )
+    }
+
+    fn activation_stale_response(
+        &self,
+        envelope: PluginDispatchEnvelope,
+    ) -> PluginResponseEnvelope {
+        self.unavailable_response(
+            envelope,
+            "dsh.activation_stale",
+            "dsh package activation scope or epoch is stale",
+            true,
+        )
+    }
+
+    fn unavailable_response(
+        &self,
+        envelope: PluginDispatchEnvelope,
+        code: &str,
+        message: &str,
+        retryable: bool,
+    ) -> PluginResponseEnvelope {
+        let diagnostic_id = format!(
+            "diag:{}:dispatch:{}:{}",
+            envelope.source.plugin_id, envelope.event_id, code
+        );
+        let diagnostic = PluginDiagnostic {
+            diagnostic_id: diagnostic_id.clone(),
+            severity: PluginDiagnosticSeverity::Warning,
+            source: envelope.source.clone(),
+            code: code.to_string(),
+            message: message.to_string(),
+            detail: PluginDiagnosticDetail::Adapter {
+                adapter_id: DSH_ADAPTER_ID.to_string(),
+            },
+            audit: audit_ref(&envelope),
+            retryable,
+        };
+
+        PluginResponseEnvelope {
+            envelope_version: envelope.envelope_version,
+            request_event_id: envelope.event_id.clone(),
+            project_domain_id: envelope.project_domain_id.clone(),
+            workspace_id: envelope.workspace_id.clone(),
+            adapter_id: DSH_ADAPTER_ID.to_string(),
+            plugin_id: Some(envelope.source.plugin_id.clone()),
+            completed_at_ms: self.observed_at_ms,
+            effects: Vec::new(),
+            diagnostics: vec![diagnostic],
+            quarantine: None,
+            plugin_statuses: vec![PluginStatusSnapshot {
+                source: envelope.source.clone(),
+                status: PluginStatusKind::Unavailable,
+                availability: PluginRuntimeAvailability::Unavailable {
+                    reason: PluginRuntimeUnavailableReason::HostUnavailable,
+                },
+                config_validation: None,
+                quarantine: None,
+                diagnostic_ids: vec![diagnostic_id],
+                updated_at_ms: self.observed_at_ms,
+            }],
+            observed_epochs: envelope.epochs,
+        }
+    }
+}
+
+#[async_trait]
+impl PluginRuntimeAdapter for DshPluginRuntimeAdapter {
+    fn adapter_id(&self) -> &str {
+        DSH_ADAPTER_ID
+    }
+
+    fn availability(&self) -> PluginRuntimeAvailability {
+        PluginRuntimeAvailability::projection_only(PluginRuntimeUnavailableReason::HostUnavailable)
+    }
+
+    async fn read_plugins(
+        &self,
+        request: PluginRuntimeReadRequest,
+    ) -> PortResult<PluginRuntimeReadResponse> {
+        self.validate_activation_scope(
+            &request.project_domain_id,
+            &request.workspace_id,
+            &request.epochs,
+        )?;
+        let mut sources = Vec::new();
+        let mut plugin_statuses = Vec::new();
+        let mut diagnostics = Vec::new();
+
+        for projection in self.projections.iter().filter(|projection| {
+            request.plugin_ids.is_empty()
+                || request
+                    .plugin_ids
+                    .iter()
+                    .any(|plugin_id| plugin_id == &projection.source_ref().plugin_id)
+        }) {
+            let projection_diagnostics = projection.read_diagnostics();
+            let diagnostic_ids = projection_diagnostics
+                .iter()
+                .map(|diagnostic| diagnostic.diagnostic_id.clone())
+                .collect();
+            sources.push(projection.source_ref().clone());
+            plugin_statuses.push(
+                projection.status_snapshot(request.include_config_validation, diagnostic_ids),
+            );
+            diagnostics.extend(projection_diagnostics);
+        }
+
+        Ok(PluginRuntimeReadResponse {
+            request_id: request.request_id,
+            project_domain_id: request.project_domain_id,
+            workspace_id: request.workspace_id,
+            sources,
+            plugin_statuses,
+            diagnostics,
+            observed_epochs: request.epochs,
+        })
+    }
+
+    async fn dispatch(
+        &self,
+        envelope: PluginDispatchEnvelope,
+    ) -> PortResult<PluginResponseEnvelope> {
+        if !self.activation_matches(
+            &envelope.project_domain_id,
+            &envelope.workspace_id,
+            &envelope.epochs,
+        ) {
+            return Ok(self.activation_stale_response(envelope));
+        }
+        match self.projection_for_source(&envelope.source) {
+            Some(projection) => projection.project_dispatch_response(envelope),
+            None => Ok(self.source_mismatch_response(envelope)),
+        }
+    }
+}
+
+// Product Assembly consumes the same compatibility tuple exposed by the
+// sibling OpenCode adapter.
+#[allow(clippy::type_complexity)]
+pub fn load_dsh_package_adapter(
+    input: PluginPackageInput,
+    activation: Option<PluginActivationAuthority>,
+    observed_at_ms: u64,
+) -> PortResult<(
+    Arc<dyn PluginRuntimeAdapter>,
+    Vec<(
+        PluginSourceRef,
+        String,
+        bitfun_runtime_ports::PluginCapabilityRef,
+        Vec<(
+            bitfun_runtime_ports::PluginTargetRef,
+            bitfun_runtime_ports::PluginRiskLevel,
+        )>,
+    )>,
+)> {
+    let adapter = match activation {
+        Some(authority) => {
+            DshPluginRuntimeAdapter::from_activated_package(input, authority, observed_at_ms)?
+        }
+        None => DshPluginRuntimeAdapter::from_package(input, observed_at_ms)?,
+    };
+    // Cordis rows can mount services that later register model-facing tools in
+    // dsh, but static row metadata is not a safe executable BitFun provider
+    // candidate. This runtime-free adapter therefore exposes no dispatch target.
+    Ok((Arc::new(adapter), Vec::new()))
+}
+
+fn source_identity_matches(left: &PluginSourceRef, right: &PluginSourceRef) -> bool {
+    left.plugin_id == right.plugin_id
+        && left.source_kind == right.source_kind
+        && left.source == right.source
+        && left.version == right.version
+        && left.content_hash == right.content_hash
+}
+
+enum DshProjection {
+    Entry(DshEntryProjection),
+    Invalid(DshInvalidProjection),
+}
+
+impl DshProjection {
+    fn is_invalid(&self) -> bool {
+        matches!(self, Self::Invalid(_))
+    }
+
+    fn activate_supported_source(&mut self) {
+        if let Self::Entry(projection) = self {
+            projection.source.trust_level = PluginTrustLevel::Trusted;
+        }
+    }
+
+    fn source_ref(&self) -> &PluginSourceRef {
+        match self {
+            Self::Entry(projection) => projection.source_ref(),
+            Self::Invalid(projection) => projection.source_ref(),
+        }
+    }
+
+    fn read_diagnostics(&self) -> Vec<PluginDiagnostic> {
+        match self {
+            Self::Entry(projection) => projection.read_diagnostics(),
+            Self::Invalid(projection) => projection.read_diagnostics(),
+        }
+    }
+
+    fn status_snapshot(
+        &self,
+        include_config_validation: bool,
+        diagnostic_ids: Vec<String>,
+    ) -> PluginStatusSnapshot {
+        match self {
+            Self::Entry(projection) => {
+                projection.status_snapshot(include_config_validation, diagnostic_ids)
+            }
+            Self::Invalid(projection) => {
+                projection.status_snapshot(include_config_validation, diagnostic_ids)
+            }
+        }
+    }
+
+    fn project_dispatch_response(
+        &self,
+        envelope: PluginDispatchEnvelope,
+    ) -> PortResult<PluginResponseEnvelope> {
+        match self {
+            Self::Entry(projection) => projection.project_dispatch_response(envelope),
+            Self::Invalid(projection) => projection.project_dispatch_response(envelope),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum DshEntryKind {
+    Bundle,
+    ProfileBundle,
+}
+
+impl DshEntryKind {
+    fn diagnostic_code(self) -> &'static str {
+        match self {
+            Self::Bundle => "dsh.bundle_entry_projection_only",
+            Self::ProfileBundle => "dsh.profile_bundle_projection_only",
+        }
+    }
+
+    fn diagnostic_message(self) -> &'static str {
+        match self {
+            Self::Bundle => {
+                "dsh bundle entry is discovered from cordis.patch.yml but is not installed or executed by BitFun"
+            }
+            Self::ProfileBundle => {
+                "dsh profile bundle reference is discovered from package.json but is not installed or executed by BitFun"
+            }
+        }
+    }
+
+    fn schema_version(self) -> &'static str {
+        match self {
+            Self::Bundle => DSH_BUNDLE_SCHEMA_VERSION,
+            Self::ProfileBundle => DSH_PROFILE_SCHEMA_VERSION,
+        }
+    }
+}
+
+struct DshEntryProjection {
+    entry_id: String,
+    source: PluginSourceRef,
+    manifest: PluginManifestRef,
+    entry_kind: DshEntryKind,
+    observed_at_ms: u64,
+}
+
+impl DshEntryProjection {
+    #[allow(clippy::too_many_arguments)]
+    fn new(
+        entry_id: String,
+        source_uri: String,
+        manifest_path: String,
+        entry_kind: DshEntryKind,
+        version: &str,
+        content_hash: &str,
+        observed_at_ms: u64,
+    ) -> Self {
+        let plugin_id = stable_plugin_id(
+            "dsh.entry",
+            &sanitize_plugin_id_component(&entry_id),
+            &source_uri,
+        );
+        let manifest = PluginManifestRef {
+            manifest_id: format!("{plugin_id}:{}", entry_kind.schema_version()),
+            schema_version: entry_kind.schema_version().to_string(),
+            path: Some(manifest_path),
+        };
+        Self {
+            entry_id,
+            source: PluginSourceRef {
+                plugin_id: plugin_id.clone(),
+                source_kind: PluginSourceKind::DeepSeekHarnessCompatible,
+                source: source_uri,
+                version: Some(version.to_string()),
+                content_hash: content_hash.to_string(),
+                trust_level: PluginTrustLevel::Unknown,
+                manifest: Some(manifest.clone()),
+            },
+            manifest,
+            entry_kind,
+            observed_at_ms,
+        }
+    }
+
+    fn source_ref(&self) -> &PluginSourceRef {
+        &self.source
+    }
+
+    fn read_diagnostics(&self) -> Vec<PluginDiagnostic> {
+        let mut diagnostics = Vec::new();
+        if self.source.trust_level != PluginTrustLevel::Trusted {
+            diagnostics.push(self.trust_diagnostic());
+        }
+        diagnostics.push(self.entry_diagnostic());
+        diagnostics
+    }
+
+    fn status_snapshot(
+        &self,
+        include_config_validation: bool,
+        diagnostic_ids: Vec<String>,
+    ) -> PluginStatusSnapshot {
+        let (availability, status) = Self::trust_status_for_level(self.source.trust_level);
+        PluginStatusSnapshot {
+            source: self.source.clone(),
+            status,
+            availability,
+            config_validation: include_config_validation.then(|| PluginConfigValidationState {
+                status: PluginConfigValidationStatus::Valid,
+                issues: Vec::new(),
+            }),
+            quarantine: None,
+            diagnostic_ids,
+            updated_at_ms: self.observed_at_ms,
+        }
+    }
+
+    fn project_dispatch_response(
+        &self,
+        envelope: PluginDispatchEnvelope,
+    ) -> PortResult<PluginResponseEnvelope> {
+        if envelope.source.plugin_id != self.source.plugin_id {
+            return Err(PortError::new(
+                PortErrorKind::NotFound,
+                format!(
+                    "dsh source {} is not loaded by this adapter",
+                    envelope.source.plugin_id
+                ),
+            ));
+        }
+        let diagnostics = self.dispatch_diagnostics(&envelope);
+        let diagnostic_ids = diagnostics
+            .iter()
+            .map(|diagnostic| diagnostic.diagnostic_id.clone())
+            .collect();
+        let (availability, status) = Self::trust_status_for_level(self.source.trust_level);
+
+        Ok(PluginResponseEnvelope {
+            envelope_version: envelope.envelope_version,
+            request_event_id: envelope.event_id.clone(),
+            project_domain_id: envelope.project_domain_id.clone(),
+            workspace_id: envelope.workspace_id.clone(),
+            adapter_id: DSH_ADAPTER_ID.to_string(),
+            plugin_id: Some(envelope.source.plugin_id.clone()),
+            completed_at_ms: self.observed_at_ms,
+            effects: Vec::new(),
+            diagnostics,
+            quarantine: None,
+            plugin_statuses: vec![PluginStatusSnapshot {
+                source: envelope.source.clone(),
+                status,
+                availability,
+                config_validation: None,
+                quarantine: None,
+                diagnostic_ids,
+                updated_at_ms: self.observed_at_ms,
+            }],
+            observed_epochs: envelope.epochs,
+        })
+    }
+
+    fn dispatch_diagnostics(&self, envelope: &PluginDispatchEnvelope) -> Vec<PluginDiagnostic> {
+        let mut entry = self.entry_diagnostic();
+        entry.diagnostic_id = format!(
+            "diag:{}:dispatch:{}:entry",
+            self.source.plugin_id, envelope.event_id
+        );
+        entry.source = envelope.source.clone();
+        entry.audit = audit_ref(envelope);
+
+        if self.source.trust_level == PluginTrustLevel::Trusted {
+            return vec![entry];
+        }
+
+        let mut trust = self.trust_diagnostic();
+        trust.diagnostic_id = format!(
+            "diag:{}:dispatch:{}:trust",
+            self.source.plugin_id, envelope.event_id
+        );
+        trust.source = envelope.source.clone();
+        trust.audit = audit_ref(envelope);
+        vec![trust, entry]
+    }
+
+    fn trust_diagnostic(&self) -> PluginDiagnostic {
+        PluginDiagnostic {
+            diagnostic_id: format!("diag:{}:trust", self.source.plugin_id),
+            severity: PluginDiagnosticSeverity::Warning,
+            source: self.source.clone(),
+            code: "dsh.trust_required".to_string(),
+            message: "dsh bundle entry is not trusted for projection".to_string(),
+            detail: PluginDiagnosticDetail::Trust {
+                trust_level: self.source.trust_level,
+            },
+            audit: PluginAuditRef {
+                correlation_id: format!("trust:{}", self.source.plugin_id),
+                event_id: None,
+            },
+            retryable: false,
+        }
+    }
+
+    fn entry_diagnostic(&self) -> PluginDiagnostic {
+        PluginDiagnostic {
+            diagnostic_id: format!("diag:{}:entry:{}", self.source.plugin_id, self.entry_id),
+            severity: PluginDiagnosticSeverity::Info,
+            source: self.source.clone(),
+            code: self.entry_kind.diagnostic_code().to_string(),
+            message: format!(
+                "{}: {}",
+                self.entry_kind.diagnostic_message(),
+                self.entry_id
+            ),
+            detail: PluginDiagnosticDetail::Manifest {
+                manifest: self.manifest.clone(),
+            },
+            audit: PluginAuditRef {
+                correlation_id: format!("config:{}", self.source.plugin_id),
+                event_id: None,
+            },
+            retryable: false,
+        }
+    }
+
+    fn trust_status_for_level(
+        trust_level: PluginTrustLevel,
+    ) -> (PluginRuntimeAvailability, PluginStatusKind) {
+        match trust_level {
+            PluginTrustLevel::Trusted => (
+                PluginRuntimeAvailability::projection_only(
+                    PluginRuntimeUnavailableReason::HostUnavailable,
+                ),
+                PluginStatusKind::ProjectionOnly,
+            ),
+            PluginTrustLevel::Denied | PluginTrustLevel::Revoked => (
+                PluginRuntimeAvailability::disabled(
+                    PluginRuntimeUnavailableReason::DisabledByPolicy,
+                ),
+                PluginStatusKind::Disabled,
+            ),
+            _ => (
+                PluginRuntimeAvailability::projection_only(
+                    PluginRuntimeUnavailableReason::DisabledByPolicy,
+                ),
+                PluginStatusKind::TrustRequired,
+            ),
+        }
+    }
+}
+
+struct DshInvalidProjection {
+    source: PluginSourceRef,
+    validation: PluginConfigValidationState,
+    diagnostic_code: String,
+    diagnostic_message: String,
+    diagnostic_detail_manifest: PluginManifestRef,
+    observed_at_ms: u64,
+}
+
+impl DshInvalidProjection {
+    fn invalid(
+        source_uri: &str,
+        package_source: &PluginPackageSourceIdentity,
+        code: &str,
+        field: &str,
+        message: String,
+        observed_at_ms: u64,
+    ) -> Self {
+        let plugin_id = stable_plugin_id(
+            "dsh.package",
+            &sanitize_plugin_id_component(code),
+            &format!("{source_uri}#{code}"),
+        );
+        let manifest = PluginManifestRef {
+            manifest_id: format!("{plugin_id}:{DSH_PACKAGE_SCHEMA_VERSION}"),
+            schema_version: DSH_PACKAGE_SCHEMA_VERSION.to_string(),
+            path: Some(source_uri.to_string()),
+        };
+        Self {
+            source: PluginSourceRef {
+                plugin_id,
+                source_kind: PluginSourceKind::DeepSeekHarnessCompatible,
+                source: source_uri.to_string(),
+                version: Some(package_source.version.clone()),
+                content_hash: package_source.content_hash.clone(),
+                trust_level: PluginTrustLevel::Unknown,
+                manifest: Some(manifest.clone()),
+            },
+            validation: invalid_validation(field, code, &message),
+            diagnostic_code: code.to_string(),
+            diagnostic_message: message,
+            diagnostic_detail_manifest: manifest,
+            observed_at_ms,
+        }
+    }
+
+    fn source_ref(&self) -> &PluginSourceRef {
+        &self.source
+    }
+
+    fn read_diagnostics(&self) -> Vec<PluginDiagnostic> {
+        vec![self.diagnostic(None)]
+    }
+
+    fn status_snapshot(
+        &self,
+        include_config_validation: bool,
+        diagnostic_ids: Vec<String>,
+    ) -> PluginStatusSnapshot {
+        PluginStatusSnapshot {
+            source: self.source.clone(),
+            status: PluginStatusKind::InvalidConfig,
+            availability: PluginRuntimeAvailability::projection_only(
+                PluginRuntimeUnavailableReason::DisabledByPolicy,
+            ),
+            config_validation: include_config_validation.then(|| self.validation.clone()),
+            quarantine: None,
+            diagnostic_ids,
+            updated_at_ms: self.observed_at_ms,
+        }
+    }
+
+    fn project_dispatch_response(
+        &self,
+        envelope: PluginDispatchEnvelope,
+    ) -> PortResult<PluginResponseEnvelope> {
+        if envelope.source.plugin_id != self.source.plugin_id {
+            return Err(PortError::new(
+                PortErrorKind::NotFound,
+                format!(
+                    "dsh source {} is not loaded by this adapter",
+                    envelope.source.plugin_id
+                ),
+            ));
+        }
+        let diagnostics = vec![self.diagnostic(Some(&envelope))];
+        let diagnostic_ids = diagnostics
+            .iter()
+            .map(|diagnostic| diagnostic.diagnostic_id.clone())
+            .collect();
+        Ok(PluginResponseEnvelope {
+            envelope_version: envelope.envelope_version,
+            request_event_id: envelope.event_id.clone(),
+            project_domain_id: envelope.project_domain_id.clone(),
+            workspace_id: envelope.workspace_id.clone(),
+            adapter_id: DSH_ADAPTER_ID.to_string(),
+            plugin_id: Some(envelope.source.plugin_id.clone()),
+            completed_at_ms: self.observed_at_ms,
+            effects: Vec::new(),
+            diagnostics,
+            quarantine: None,
+            plugin_statuses: vec![PluginStatusSnapshot {
+                source: envelope.source.clone(),
+                status: PluginStatusKind::InvalidConfig,
+                availability: PluginRuntimeAvailability::projection_only(
+                    PluginRuntimeUnavailableReason::DisabledByPolicy,
+                ),
+                config_validation: None,
+                quarantine: None,
+                diagnostic_ids,
+                updated_at_ms: self.observed_at_ms,
+            }],
+            observed_epochs: envelope.epochs,
+        })
+    }
+
+    fn diagnostic(&self, envelope: Option<&PluginDispatchEnvelope>) -> PluginDiagnostic {
+        let diagnostic_id = match envelope {
+            Some(envelope) => format!(
+                "diag:{}:dispatch:{}:{}",
+                self.source.plugin_id, envelope.event_id, self.diagnostic_code
+            ),
+            None => format!("diag:{}:{}", self.source.plugin_id, self.diagnostic_code),
+        };
+        PluginDiagnostic {
+            diagnostic_id,
+            severity: PluginDiagnosticSeverity::Error,
+            source: envelope
+                .map_or_else(|| self.source.clone(), |envelope| envelope.source.clone()),
+            code: self.diagnostic_code.clone(),
+            message: self.diagnostic_message.clone(),
+            detail: PluginDiagnosticDetail::ConfigValidation {
+                manifest: self.diagnostic_detail_manifest.clone(),
+                validation: self.validation.clone(),
+            },
+            audit: envelope.map_or_else(
+                || PluginAuditRef {
+                    correlation_id: format!("invalid:{}", self.source.plugin_id),
+                    event_id: None,
+                },
+                audit_ref,
+            ),
+            retryable: false,
+        }
+    }
+}
+
+#[derive(Debug, Deserialize)]
+struct DshPackageDoc {
+    #[serde(default)]
+    dsh: Option<DshPackageField>,
+}
+
+#[derive(Debug, Deserialize)]
+struct DshPackageField {
+    #[serde(default)]
+    bundle: Option<DshBundleDecl>,
+    #[serde(default)]
+    profile: Option<DshProfileDecl>,
+}
+
+#[derive(Debug, Deserialize)]
+struct DshBundleDecl {
+    #[serde(default)]
+    patch: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+struct DshProfileDecl {
+    #[serde(default)]
+    bundles: Vec<String>,
+}
+
+#[derive(Debug, Deserialize)]
+struct DshPatchOperation {
+    #[serde(default)]
+    id: Option<String>,
+    #[serde(default)]
+    insert: Option<Vec<DshCordisEntry>>,
+    #[serde(default)]
+    group: Option<bool>,
+    #[serde(default)]
+    config: Option<serde_yaml::Value>,
+}
+
+#[derive(Debug, Deserialize)]
+struct DshCordisEntry {
+    #[serde(default)]
+    id: Option<String>,
+    #[serde(default)]
+    group: Option<bool>,
+    #[serde(default)]
+    config: Option<serde_yaml::Value>,
+}
+
+fn project_package(
+    files: &BTreeMap<String, Vec<u8>>,
+    provenance_id: &str,
+    source: &PluginPackageSourceIdentity,
+    package_uri: &str,
+    package_json_uri: &str,
+    observed_at_ms: u64,
+) -> PortResult<Vec<DshProjection>> {
+    let mut projections = Vec::new();
+
+    let Some(package_doc) = read_package_doc(
+        files,
+        source,
+        package_json_uri,
+        observed_at_ms,
+        &mut projections,
+    ) else {
+        return Ok(projections);
+    };
+
+    let Some(field) = package_doc.dsh.as_ref() else {
+        projections.push(DshProjection::Invalid(DshInvalidProjection::invalid(
+            package_json_uri,
+            source,
+            "dsh.package_no_dsh_field",
+            "dsh",
+            "package.json declares no dsh bundle or profile".to_string(),
+            observed_at_ms,
+        )));
+        return Ok(projections);
+    };
+
+    let mut declared_role = false;
+    if let Some(bundle) = field.bundle.as_ref() {
+        declared_role = true;
+        project_bundle(
+            bundle,
+            files,
+            provenance_id,
+            source,
+            package_json_uri,
+            observed_at_ms,
+            &mut projections,
+        )?;
+    }
+    if let Some(profile) = field.profile.as_ref() {
+        declared_role = true;
+        project_profile(
+            profile,
+            source,
+            package_uri,
+            package_json_uri,
+            observed_at_ms,
+            &mut projections,
+        )?;
+    }
+    if !declared_role {
+        projections.push(DshProjection::Invalid(DshInvalidProjection::invalid(
+            package_json_uri,
+            source,
+            "dsh.package_no_supported_role",
+            "dsh",
+            "dsh declaration has no supported bundle or profile role".to_string(),
+            observed_at_ms,
+        )));
+    }
+
+    Ok(projections)
+}
+
+fn read_package_doc(
+    files: &BTreeMap<String, Vec<u8>>,
+    source: &PluginPackageSourceIdentity,
+    package_json_uri: &str,
+    observed_at_ms: u64,
+    projections: &mut Vec<DshProjection>,
+) -> Option<DshPackageDoc> {
+    let Some(bytes) = files.get(PACKAGE_JSON) else {
+        projections.push(DshProjection::Invalid(DshInvalidProjection::invalid(
+            package_json_uri,
+            source,
+            "dsh.package_json_missing",
+            "package.json",
+            "managed package has no package.json".to_string(),
+            observed_at_ms,
+        )));
+        return None;
+    };
+    let json = match std::str::from_utf8(bytes) {
+        Ok(json) => json,
+        Err(error) => {
+            projections.push(DshProjection::Invalid(DshInvalidProjection::invalid(
+                package_json_uri,
+                source,
+                "dsh.package_json_invalid",
+                "package.json",
+                format!("package.json must be UTF-8: {error}"),
+                observed_at_ms,
+            )));
+            return None;
+        }
+    };
+    match serde_json::from_str::<DshPackageDoc>(json) {
+        Ok(doc) => Some(doc),
+        Err(error) => {
+            projections.push(DshProjection::Invalid(DshInvalidProjection::invalid(
+                package_json_uri,
+                source,
+                "dsh.package_json_invalid",
+                "package.json",
+                error.to_string(),
+                observed_at_ms,
+            )));
+            None
+        }
+    }
+}
+
+#[allow(clippy::too_many_arguments)]
+fn project_bundle(
+    bundle: &DshBundleDecl,
+    files: &BTreeMap<String, Vec<u8>>,
+    provenance_id: &str,
+    source: &PluginPackageSourceIdentity,
+    package_json_uri: &str,
+    observed_at_ms: u64,
+    projections: &mut Vec<DshProjection>,
+) -> PortResult<()> {
+    let Some(declared_patch) = bundle.patch.as_deref().filter(|patch| !patch.is_empty()) else {
+        projections.push(DshProjection::Invalid(DshInvalidProjection::invalid(
+            package_json_uri,
+            source,
+            "dsh.bundle_patch_missing",
+            "dsh.bundle.patch",
+            "dsh bundle declaration must name its patch file".to_string(),
+            observed_at_ms,
+        )));
+        return Ok(());
+    };
+    let Some(patch_rel) = normalize_relative_path(declared_patch) else {
+        projections.push(DshProjection::Invalid(DshInvalidProjection::invalid(
+            package_json_uri,
+            source,
+            "dsh.bundle_patch_invalid",
+            "dsh.bundle.patch",
+            "dsh bundle patch must resolve to a file inside the managed package".to_string(),
+            observed_at_ms,
+        )));
+        return Ok(());
+    };
+    let patch_uri = managed_source_uri(provenance_id, &source.package_id, &patch_rel);
+
+    let Some(bytes) = files.get(&patch_rel) else {
+        projections.push(DshProjection::Invalid(DshInvalidProjection::invalid(
+            package_json_uri,
+            source,
+            "dsh.bundle_patch_missing",
+            "dsh.bundle.patch",
+            format!("declared bundle patch file is not part of the package: {patch_rel}"),
+            observed_at_ms,
+        )));
+        return Ok(());
+    };
+
+    let patch_yaml = match std::str::from_utf8(bytes) {
+        Ok(yaml) => yaml,
+        Err(error) => {
+            projections.push(DshProjection::Invalid(DshInvalidProjection::invalid(
+                package_json_uri,
+                source,
+                "dsh.bundle_patch_invalid",
+                "dsh.bundle.patch",
+                format!("bundle patch must be UTF-8: {error}"),
+                observed_at_ms,
+            )));
+            return Ok(());
+        }
+    };
+
+    if patch_yaml.trim().is_empty() {
+        projections.push(DshProjection::Invalid(DshInvalidProjection::invalid(
+            &patch_uri,
+            source,
+            "dsh.bundle_no_entries",
+            "cordis.patch.yml",
+            "bundle patch declares no cordis entries".to_string(),
+            observed_at_ms,
+        )));
+        return Ok(());
+    }
+
+    let entries = match serde_yaml::from_str::<Vec<DshPatchOperation>>(patch_yaml) {
+        Ok(entries) => entries,
+        Err(error) => {
+            projections.push(DshProjection::Invalid(DshInvalidProjection::invalid(
+                &patch_uri,
+                source,
+                "dsh.bundle_patch_invalid",
+                "cordis.patch.yml",
+                format!("bundle patch must be a YAML list: {error}"),
+                observed_at_ms,
+            )));
+            return Ok(());
+        }
+    };
+
+    let mut entry_ids = Vec::new();
+    let mut seen = HashSet::new();
+    let mut visited_entries = 0usize;
+    let mut unprojectable_entries = 0usize;
+    collect_entry_ids(
+        &entries,
+        &mut entry_ids,
+        &mut seen,
+        &mut visited_entries,
+        &mut unprojectable_entries,
+    );
+    if visited_entries > MAX_ENTRIES_PER_PACKAGE {
+        return Err(adapter_port_error(format!(
+            "managed package declares more than {MAX_ENTRIES_PER_PACKAGE} dsh bundle entries"
+        )));
+    }
+    if unprojectable_entries > 0 {
+        let invalid_uri = format!("{patch_uri}#unprojectable-entry");
+        projections.push(DshProjection::Invalid(DshInvalidProjection::invalid(
+            &invalid_uri,
+            source,
+            "dsh.bundle_entry_invalid",
+            "cordis.patch.yml",
+            format!(
+                "bundle patch contains {unprojectable_entries} Cordis entry or group value(s) without a valid stable identity"
+            ),
+            observed_at_ms,
+        )));
+    }
+    if entry_ids.is_empty() {
+        projections.push(DshProjection::Invalid(DshInvalidProjection::invalid(
+            &patch_uri,
+            source,
+            "dsh.bundle_no_entries",
+            "cordis.patch.yml",
+            "bundle patch declares no cordis entries".to_string(),
+            observed_at_ms,
+        )));
+        return Ok(());
+    }
+
+    for entry_id in entry_ids {
+        let source_uri = format!("{patch_uri}#entry={}", urlencoding::encode(&entry_id));
+        projections.push(DshProjection::Entry(DshEntryProjection::new(
+            entry_id,
+            source_uri,
+            patch_uri.clone(),
+            DshEntryKind::Bundle,
+            &source.version,
+            &source.content_hash,
+            observed_at_ms,
+        )));
+    }
+    Ok(())
+}
+
+fn project_profile(
+    profile: &DshProfileDecl,
+    source: &PluginPackageSourceIdentity,
+    package_uri: &str,
+    package_json_uri: &str,
+    observed_at_ms: u64,
+    projections: &mut Vec<DshProjection>,
+) -> PortResult<()> {
+    if profile.bundles.len() > MAX_PROFILE_BUNDLES {
+        return Err(adapter_port_error(format!(
+            "managed package declares more than {MAX_PROFILE_BUNDLES} dsh profile bundles"
+        )));
+    }
+    if profile.bundles.is_empty() {
+        projections.push(DshProjection::Invalid(DshInvalidProjection::invalid(
+            package_json_uri,
+            source,
+            "dsh.profile_no_bundles",
+            "dsh.profile.bundles",
+            "dsh profile declares no bundles".to_string(),
+            observed_at_ms,
+        )));
+        return Ok(());
+    }
+
+    let mut projected = 0usize;
+    for (index, name) in profile.bundles.iter().enumerate() {
+        if name.is_empty()
+            || name.trim() != name
+            || name.len() > MAX_PROFILE_BUNDLE_NAME_BYTES
+            || name.chars().any(|ch| ch.is_control() || ch.is_whitespace())
+        {
+            let invalid_uri = format!("{package_json_uri}#bundle-index={index}");
+            projections.push(DshProjection::Invalid(DshInvalidProjection::invalid(
+                &invalid_uri,
+                source,
+                "dsh.profile_bundle_invalid",
+                &format!("dsh.profile.bundles[{index}]"),
+                "dsh profile bundle name must be a non-empty package name without whitespace"
+                    .to_string(),
+                observed_at_ms,
+            )));
+            continue;
+        }
+        projected += 1;
+        let source_uri = format!(
+            "{package_uri}#bundle-index={index}&bundle={}",
+            urlencoding::encode(name)
+        );
+        projections.push(DshProjection::Entry(DshEntryProjection::new(
+            name.to_string(),
+            source_uri,
+            package_json_uri.to_string(),
+            DshEntryKind::ProfileBundle,
+            &source.version,
+            &source.content_hash,
+            observed_at_ms,
+        )));
+    }
+
+    if projected == 0 {
+        projections.push(DshProjection::Invalid(DshInvalidProjection::invalid(
+            package_json_uri,
+            source,
+            "dsh.profile_no_bundles",
+            "dsh.profile.bundles",
+            "dsh profile declares no valid bundle names".to_string(),
+            observed_at_ms,
+        )));
+    }
+    Ok(())
+}
+
+fn collect_entry_ids(
+    entries: &[DshPatchOperation],
+    out: &mut Vec<String>,
+    seen: &mut HashSet<String>,
+    visited_entries: &mut usize,
+    unprojectable_entries: &mut usize,
+) {
+    for operation in entries {
+        *visited_entries = (*visited_entries).saturating_add(1);
+        if *visited_entries > MAX_ENTRIES_PER_PACKAGE {
+            return;
+        }
+        if let Some(id) = operation.id.as_deref() {
+            collect_stable_entry_id(id, out, seen, unprojectable_entries);
+        }
+        if let Some(insert) = operation.insert.as_deref() {
+            collect_cordis_entries(insert, out, seen, visited_entries, unprojectable_entries);
+            if *visited_entries > MAX_ENTRIES_PER_PACKAGE {
+                return;
+            }
+        }
+        collect_group_entries(
+            operation.group,
+            operation.config.as_ref(),
+            out,
+            seen,
+            visited_entries,
+            unprojectable_entries,
+        );
+    }
+}
+
+fn collect_cordis_entries(
+    entries: &[DshCordisEntry],
+    out: &mut Vec<String>,
+    seen: &mut HashSet<String>,
+    visited_entries: &mut usize,
+    unprojectable_entries: &mut usize,
+) {
+    for entry in entries {
+        *visited_entries = (*visited_entries).saturating_add(1);
+        if *visited_entries > MAX_ENTRIES_PER_PACKAGE {
+            return;
+        }
+        match entry.id.as_deref() {
+            Some(id) => collect_stable_entry_id(id, out, seen, unprojectable_entries),
+            None => *unprojectable_entries = (*unprojectable_entries).saturating_add(1),
+        }
+        collect_group_entries(
+            entry.group,
+            entry.config.as_ref(),
+            out,
+            seen,
+            visited_entries,
+            unprojectable_entries,
+        );
+    }
+}
+
+fn collect_group_entries(
+    group: Option<bool>,
+    config: Option<&serde_yaml::Value>,
+    out: &mut Vec<String>,
+    seen: &mut HashSet<String>,
+    visited_entries: &mut usize,
+    unprojectable_entries: &mut usize,
+) {
+    if group != Some(true) {
+        return;
+    }
+    let Some(serde_yaml::Value::Sequence(values)) = config else {
+        if config.is_some() {
+            *unprojectable_entries = (*unprojectable_entries).saturating_add(1);
+        }
+        return;
+    };
+    let mut entries = Vec::with_capacity(values.len());
+    for value in values {
+        match serde_yaml::from_value::<DshCordisEntry>(value.clone()) {
+            Ok(entry) => entries.push(entry),
+            Err(_) => *unprojectable_entries = (*unprojectable_entries).saturating_add(1),
+        }
+    }
+    collect_cordis_entries(&entries, out, seen, visited_entries, unprojectable_entries);
+}
+
+fn collect_stable_entry_id(
+    id: &str,
+    out: &mut Vec<String>,
+    seen: &mut HashSet<String>,
+    unprojectable_entries: &mut usize,
+) {
+    if id.is_empty() || id.len() > MAX_ENTRY_ID_BYTES || id.chars().any(char::is_control) {
+        *unprojectable_entries = (*unprojectable_entries).saturating_add(1);
+        return;
+    }
+    if seen.insert(id.to_string()) {
+        out.push(id.to_string());
+    }
+}
+
+fn normalize_relative_path(path: &str) -> Option<String> {
+    if path.starts_with('/') || path.contains('\\') {
+        return None;
+    }
+
+    let mut segments = Vec::new();
+    for segment in path.split('/') {
+        match segment {
+            "" | "." => {}
+            ".." => {
+                segments.pop()?;
+            }
+            _ if segment.contains(':') || segment.chars().any(char::is_control) => return None,
+            _ => segments.push(segment),
+        }
+    }
+    (!segments.is_empty()).then(|| segments.join("/"))
+}
+
+fn stable_plugin_id(prefix: &str, component: &str, identity: &str) -> String {
+    let digest = hex::encode(Sha256::digest(identity.as_bytes()));
+    format!("{prefix}.{component}.{}", &digest[..32])
+}
+
+fn sha256_content_hash(value: &str) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(value.as_bytes());
+    format!("sha256:{}", hex::encode(hasher.finalize()))
+}
+
+fn managed_source_uri(provenance_id: &str, package_id: &str, relative_path: &str) -> String {
+    let encoded_path = relative_path
+        .split('/')
+        .map(|segment| urlencoding::encode(segment).into_owned())
+        .collect::<Vec<_>>()
+        .join("/");
+    format!(
+        "bitfun://managed-plugins/{provenance_id}/{}/{encoded_path}",
+        urlencoding::encode(package_id)
+    )
+}
+
+fn sanitize_plugin_id_component(value: &str) -> String {
+    let mut sanitized = String::with_capacity(value.len().min(MAX_PLUGIN_ID_COMPONENT_LEN));
+    let mut previous_separator = false;
+    for ch in value.chars() {
+        if sanitized.len() >= MAX_PLUGIN_ID_COMPONENT_LEN {
+            break;
+        }
+        if ch.is_ascii_alphanumeric() {
+            sanitized.push(ch.to_ascii_lowercase());
+            previous_separator = false;
+        } else if !previous_separator {
+            sanitized.push('_');
+            previous_separator = true;
+        }
+    }
+
+    let sanitized = sanitized.trim_matches('_').to_string();
+    if sanitized.is_empty() {
+        "plugin".to_string()
+    } else {
+        sanitized
+    }
+}
+
+fn adapter_port_error(message: String) -> PortError {
+    PortError::new(PortErrorKind::InvalidRequest, message)
+}
+
+fn invalid_validation(field: &str, code: &str, message: &str) -> PluginConfigValidationState {
+    PluginConfigValidationState {
+        status: PluginConfigValidationStatus::Invalid,
+        issues: vec![PluginConfigValidationIssue {
+            field: field.to_string(),
+            code: code.to_string(),
+            message: message.to_string(),
+        }],
+    }
+}
+
+fn audit_ref(envelope: &PluginDispatchEnvelope) -> PluginAuditRef {
+    PluginAuditRef {
+        correlation_id: envelope.correlation_id.clone(),
+        event_id: Some(envelope.event_id.clone()),
+    }
+}
diff --git a/src/crates/adapters/dsh-adapter/tests/dsh_source_adapter.rs b/src/crates/adapters/dsh-adapter/tests/dsh_source_adapter.rs
new file mode 100644
index 0000000000..7eb2973399
--- /dev/null
+++ b/src/crates/adapters/dsh-adapter/tests/dsh_source_adapter.rs
@@ -0,0 +1,522 @@
+use bitfun_dsh_adapter::load_dsh_package_adapter;
+use bitfun_plugin_runtime_client::DefaultPluginRuntimeClient;
+use bitfun_product_domains::plugin_source::{
+    PluginPackageFile, PluginPackageInput, PluginPackageManifest, PluginPackageSourceIdentity,
+    PluginTrustDecision, PluginTrustStore,
+};
+use bitfun_runtime_ports::{
+    PluginCapabilityRef, PluginDispatchEnvelope, PluginOwnerKind, PluginOwnerRef,
+    PluginRuntimeAvailability, PluginRuntimeClient, PluginRuntimeEpochs, PluginRuntimeReadRequest,
+    PluginRuntimeUnavailableReason, PluginSourceKind, PluginStatusKind, PluginTrustLevel,
+};
+use sha2::{Digest, Sha256};
+use std::collections::BTreeMap;
+
+const BUNDLE_PACKAGE_JSON: &str = r#"{
+  "name": "acme-dsh-bundle",
+  "version": "1.0.0",
+  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
+}"#;
+
+const BUNDLE_PATCH: &str = r#"
+- insert:
+    - id: acme.tool
+      disabled: !!js process.platform === 'win32'
+      config:
+        command: [node, tool.js]
+    - id: acme.agent
+      name: group
+      group: true
+      config:
+        - id: acme.agent.inner
+          name: acme-agent-inner
+"#;
+
+const PROFILE_PACKAGE_JSON: &str = r#"{
+  "name": "acme-dsh-profile",
+  "version": "1.0.0",
+  "dsh": { "profile": { "bundles": ["@acme/dsh-base", "@acme/dsh-web"] } }
+}"#;
+
+const BUNDLE_AND_PROFILE_PACKAGE_JSON: &str = r#"{
+  "name": "acme-dsh-combined",
+  "version": "1.0.0",
+  "dsh": {
+    "bundle": { "patch": "./cordis.patch.yml" },
+    "profile": { "bundles": ["@acme/dsh-base", "@acme/dsh-web"] }
+  }
+}"#;
+
+fn build_input(files: &[(&str, &str)]) -> PluginPackageInput {
+    let manifest = PluginPackageManifest {
+        schema_version: 1,
+        id: "acme.dsh".to_string(),
+        version: "1.0.0".to_string(),
+        adapter: "dsh_compatible".to_string(),
+        files: files
+            .iter()
+            .map(|(path, content)| PluginPackageFile {
+                path: (*path).to_string(),
+                sha256: format!("sha256:{}", hex::encode(Sha256::digest(content.as_bytes()))),
+            })
+            .collect(),
+    };
+    let source = PluginPackageSourceIdentity {
+        package_id: "acme.dsh".to_string(),
+        version: "1.0.0".to_string(),
+        adapter: "dsh_compatible".to_string(),
+        source_path: "/managed/acme.dsh".to_string(),
+        content_hash: manifest.content_hash().expect("manifest content hash"),
+    };
+    let file_map = files
+        .iter()
+        .map(|(path, content)| ((*path).to_string(), content.as_bytes().to_vec()))
+        .collect::<BTreeMap<_, _>>();
+    PluginPackageInput::new(manifest, source, file_map).expect("valid package input")
+}
+
+fn bundle_input() -> PluginPackageInput {
+    build_input(&[
+        ("package.json", BUNDLE_PACKAGE_JSON),
+        ("cordis.patch.yml", BUNDLE_PATCH),
+    ])
+}
+
+fn read_request(plugin_ids: Vec<String>) -> PluginRuntimeReadRequest {
+    PluginRuntimeReadRequest {
+        request_id: "dsh-read".to_string(),
+        project_domain_id: "project".to_string(),
+        workspace_id: "workspace".to_string(),
+        plugin_ids,
+        include_config_validation: true,
+        epochs: PluginRuntimeEpochs {
+            project_epoch: 0,
+            trust_epoch: 1,
+            policy_epoch: 0,
+            tool_registry_epoch: None,
+        },
+    }
+}
+
+fn dispatch_envelope(source: bitfun_runtime_ports::PluginSourceRef) -> PluginDispatchEnvelope {
+    PluginDispatchEnvelope {
+        envelope_version: 1,
+        event_id: "dispatch-1".to_string(),
+        event_type: "plugin.dispatch.requested".to_string(),
+        event_version: "v1".to_string(),
+        project_domain_id: "project".to_string(),
+        workspace_id: "workspace".to_string(),
+        extension_point_id: "tool".to_string(),
+        declared_capability: PluginCapabilityRef {
+            capability_id: "dsh.entry".to_string(),
+            owner: PluginOwnerRef {
+                kind: PluginOwnerKind::ExtensionContract,
+                id: "dsh".to_string(),
+            },
+        },
+        source,
+        correlation_id: "correlation".to_string(),
+        causation_id: None,
+        idempotency_key: "idem-1".to_string(),
+        deadline_ms: 30_000,
+        epochs: PluginRuntimeEpochs {
+            project_epoch: 0,
+            trust_epoch: 1,
+            policy_epoch: 0,
+            tool_registry_epoch: None,
+        },
+        payload_ref: None,
+    }
+}
+
+fn activation_authority(
+    input: &PluginPackageInput,
+) -> bitfun_product_domains::plugin_source::PluginActivationAuthority {
+    let source = input.clone().into_parts().1;
+    let mut trust = PluginTrustStore::new(1);
+    trust
+        .apply_decision(
+            "project",
+            "workspace",
+            source.clone(),
+            PluginTrustDecision::ApproveSource,
+            1_720_000_000,
+        )
+        .expect("approve dsh source");
+    trust
+        .activate("project", "workspace", source.clone(), 1_720_000_001)
+        .expect("activate dsh source");
+    trust
+        .activation_authority("project", "workspace", &source)
+        .expect("dsh activation authority")
+}
+
+#[tokio::test]
+async fn bundle_entries_project_as_projection_only_sources() {
+    let (adapter, dispatch_targets) =
+        load_dsh_package_adapter(bundle_input(), None, 1_720_000_001).expect("dsh adapter");
+    assert!(
+        dispatch_targets.is_empty(),
+        "dsh entries have no tool targets"
+    );
+
+    let client = DefaultPluginRuntimeClient::new(adapter);
+    assert_eq!(
+        client.availability(),
+        PluginRuntimeAvailability::ProjectionOnly {
+            reason: PluginRuntimeUnavailableReason::HostUnavailable
+        }
+    );
+
+    let read = client
+        .read_plugins(read_request(Vec::new()))
+        .await
+        .expect("read plugins");
+    assert_eq!(read.sources.len(), 3, "two top-level + one nested entry");
+    assert!(read
+        .sources
+        .iter()
+        .all(|source| source.source_kind == PluginSourceKind::DeepSeekHarnessCompatible));
+    assert!(read
+        .sources
+        .iter()
+        .all(|source| source.trust_level == PluginTrustLevel::Unknown));
+    assert!(read
+        .plugin_statuses
+        .iter()
+        .all(|status| status.status == PluginStatusKind::TrustRequired));
+    assert!(read
+        .diagnostics
+        .iter()
+        .any(|diagnostic| diagnostic.code == "dsh.bundle_entry_projection_only"));
+
+    let source = read.sources[0].clone();
+    let response = client
+        .dispatch(dispatch_envelope(source))
+        .await
+        .expect("dispatch projection");
+    assert!(
+        response.effects.is_empty(),
+        "static adapter produces no effects"
+    );
+    assert_eq!(
+        response.plugin_statuses[0].status,
+        PluginStatusKind::TrustRequired
+    );
+}
+
+#[tokio::test]
+async fn profile_bundles_project_as_projection_only_sources() {
+    let input = build_input(&[("package.json", PROFILE_PACKAGE_JSON)]);
+    let (adapter, _) = load_dsh_package_adapter(input, None, 1_720_000_001).expect("dsh adapter");
+    let client = DefaultPluginRuntimeClient::new(adapter);
+
+    let read = client
+        .read_plugins(read_request(Vec::new()))
+        .await
+        .expect("read plugins");
+    assert_eq!(read.sources.len(), 2);
+    assert!(read
+        .diagnostics
+        .iter()
+        .any(|diagnostic| diagnostic.code == "dsh.profile_bundle_projection_only"));
+}
+
+#[tokio::test]
+async fn invalid_profile_names_are_diagnosed_and_duplicate_layers_are_preserved() {
+    let package_json = r#"{
+      "name": "acme-dsh-profile",
+      "version": "1.0.0",
+      "dsh": {
+        "profile": {
+          "bundles": ["@acme/dsh-base", " ", "@acme/dsh-base"]
+        }
+      }
+    }"#;
+    let input = build_input(&[("package.json", package_json)]);
+    let (adapter, _) = load_dsh_package_adapter(input, None, 1_720_000_001).unwrap();
+    let client = DefaultPluginRuntimeClient::new(adapter);
+
+    let read = client.read_plugins(read_request(Vec::new())).await.unwrap();
+    assert_eq!(
+        read.sources.len(),
+        3,
+        "two ordered layer references and one invalid projection"
+    );
+    assert!(read
+        .diagnostics
+        .iter()
+        .any(|diagnostic| diagnostic.code == "dsh.profile_bundle_invalid"));
+    assert_eq!(
+        read.plugin_statuses
+            .iter()
+            .filter(|status| status.status == PluginStatusKind::InvalidConfig)
+            .count(),
+        1
+    );
+    let valid_sources = read
+        .plugin_statuses
+        .iter()
+        .filter(|status| status.status == PluginStatusKind::TrustRequired)
+        .map(|status| &status.source)
+        .collect::<Vec<_>>();
+    assert_eq!(valid_sources.len(), 2);
+    assert_ne!(valid_sources[0].plugin_id, valid_sources[1].plugin_id);
+}
+
+#[tokio::test]
+async fn package_can_project_bundle_and_profile_roles_together() {
+    let input = build_input(&[
+        ("package.json", BUNDLE_AND_PROFILE_PACKAGE_JSON),
+        ("cordis.patch.yml", BUNDLE_PATCH),
+    ]);
+    let (adapter, _) = load_dsh_package_adapter(input, None, 1_720_000_001).unwrap();
+    let client = DefaultPluginRuntimeClient::new(adapter);
+
+    let read = client
+        .read_plugins(read_request(Vec::new()))
+        .await
+        .expect("read combined dsh package");
+    assert_eq!(read.sources.len(), 5, "three patch rows plus two bundles");
+    assert!(read
+        .diagnostics
+        .iter()
+        .any(|diagnostic| diagnostic.code == "dsh.bundle_entry_projection_only"));
+    assert!(read
+        .diagnostics
+        .iter()
+        .any(|diagnostic| diagnostic.code == "dsh.profile_bundle_projection_only"));
+}
+
+#[tokio::test]
+async fn read_plugins_filters_by_plugin_id() {
+    let (adapter, _) = load_dsh_package_adapter(bundle_input(), None, 1_720_000_001).unwrap();
+    let client = DefaultPluginRuntimeClient::new(adapter);
+    let all = client.read_plugins(read_request(Vec::new())).await.unwrap();
+    let target = all.sources[0].plugin_id.clone();
+
+    let filtered = client
+        .read_plugins(read_request(vec![target.clone()]))
+        .await
+        .unwrap();
+    assert_eq!(filtered.sources.len(), 1);
+    assert_eq!(filtered.sources[0].plugin_id, target);
+}
+
+#[tokio::test]
+async fn missing_package_json_produces_invalid_projection() {
+    let input = build_input(&[("cordis.patch.yml", BUNDLE_PATCH)]);
+    let expected_source = input.clone().into_parts().1;
+    let (adapter, _) = load_dsh_package_adapter(input, None, 1_720_000_001).unwrap();
+    let client = DefaultPluginRuntimeClient::new(adapter);
+    let read = client.read_plugins(read_request(Vec::new())).await.unwrap();
+    assert_eq!(read.sources.len(), 1);
+    assert_eq!(read.sources[0].version.as_deref(), Some("1.0.0"));
+    assert_eq!(read.sources[0].content_hash, expected_source.content_hash);
+    assert_eq!(
+        read.plugin_statuses[0].status,
+        PluginStatusKind::InvalidConfig
+    );
+    assert!(read
+        .diagnostics
+        .iter()
+        .any(|diagnostic| diagnostic.code == "dsh.package_json_missing"));
+}
+
+#[tokio::test]
+async fn bundle_declaration_requires_an_explicit_patch_path() {
+    let package_json = r#"{
+      "name": "acme-dsh-bundle",
+      "version": "1.0.0",
+      "dsh": { "bundle": {} }
+    }"#;
+    let input = build_input(&[
+        ("package.json", package_json),
+        ("cordis.patch.yml", BUNDLE_PATCH),
+    ]);
+    let (adapter, _) = load_dsh_package_adapter(input, None, 1_720_000_001).unwrap();
+    let client = DefaultPluginRuntimeClient::new(adapter);
+    let read = client.read_plugins(read_request(Vec::new())).await.unwrap();
+
+    assert_eq!(read.sources.len(), 1);
+    assert_eq!(
+        read.plugin_statuses[0].status,
+        PluginStatusKind::InvalidConfig
+    );
+    assert!(read
+        .diagnostics
+        .iter()
+        .any(|diagnostic| diagnostic.code == "dsh.bundle_patch_missing"));
+}
+
+#[tokio::test]
+async fn bundle_patch_path_uses_package_relative_normalization() {
+    let package_json = r#"{
+      "name": "acme-dsh-bundle",
+      "version": "1.0.0",
+      "dsh": { "bundle": { "patch": "./config/../cordis.patch.yml" } }
+    }"#;
+    let input = build_input(&[
+        ("package.json", package_json),
+        ("cordis.patch.yml", BUNDLE_PATCH),
+    ]);
+    let (adapter, _) = load_dsh_package_adapter(input, None, 1_720_000_001).unwrap();
+    let client = DefaultPluginRuntimeClient::new(adapter);
+    let read = client.read_plugins(read_request(Vec::new())).await.unwrap();
+
+    assert_eq!(read.sources.len(), 3);
+    assert!(read
+        .plugin_statuses
+        .iter()
+        .all(|status| status.status == PluginStatusKind::TrustRequired));
+}
+
+#[tokio::test]
+async fn package_without_dsh_field_produces_invalid_projection() {
+    let input = build_input(&[("package.json", r#"{ "name": "plain" }"#)]);
+    let (adapter, _) = load_dsh_package_adapter(input, None, 1_720_000_001).unwrap();
+    let client = DefaultPluginRuntimeClient::new(adapter);
+    let read = client.read_plugins(read_request(Vec::new())).await.unwrap();
+    assert_eq!(
+        read.plugin_statuses[0].status,
+        PluginStatusKind::InvalidConfig
+    );
+    assert!(read
+        .diagnostics
+        .iter()
+        .any(|diagnostic| diagnostic.code == "dsh.package_no_dsh_field"));
+}
+
+#[tokio::test]
+async fn unsupported_client_only_package_reports_its_actual_role() {
+    let input = build_input(&[(
+        "package.json",
+        r#"{
+          "name": "client-only",
+          "dsh": {
+            "client": { "platform": "web", "inject": [] }
+          }
+        }"#,
+    )]);
+    let (adapter, _) = load_dsh_package_adapter(input, None, 1_720_000_001).unwrap();
+    let client = DefaultPluginRuntimeClient::new(adapter);
+    let read = client.read_plugins(read_request(Vec::new())).await.unwrap();
+
+    assert_eq!(
+        read.plugin_statuses[0].status,
+        PluginStatusKind::InvalidConfig
+    );
+    assert!(read
+        .diagnostics
+        .iter()
+        .any(|diagnostic| diagnostic.code == "dsh.package_no_supported_role"));
+    assert!(!read
+        .diagnostics
+        .iter()
+        .any(|diagnostic| diagnostic.code == "dsh.package_no_dsh_field"));
+}
+
+#[tokio::test]
+async fn bundle_with_missing_patch_produces_invalid_projection() {
+    let input = build_input(&[("package.json", BUNDLE_PACKAGE_JSON)]);
+    let (adapter, _) = load_dsh_package_adapter(input, None, 1_720_000_001).unwrap();
+    let client = DefaultPluginRuntimeClient::new(adapter);
+    let read = client.read_plugins(read_request(Vec::new())).await.unwrap();
+    assert_eq!(
+        read.plugin_statuses[0].status,
+        PluginStatusKind::InvalidConfig
+    );
+    assert!(read
+        .diagnostics
+        .iter()
+        .any(|diagnostic| diagnostic.code == "dsh.bundle_patch_missing"));
+}
+
+#[tokio::test]
+async fn empty_bundle_patch_produces_invalid_projection() {
+    let input = build_input(&[
+        ("package.json", BUNDLE_PACKAGE_JSON),
+        ("cordis.patch.yml", "# comments only\n"),
+    ]);
+    let (adapter, _) = load_dsh_package_adapter(input, None, 1_720_000_001).unwrap();
+    let client = DefaultPluginRuntimeClient::new(adapter);
+    let read = client.read_plugins(read_request(Vec::new())).await.unwrap();
+    assert_eq!(
+        read.plugin_statuses[0].status,
+        PluginStatusKind::InvalidConfig
+    );
+    assert!(read
+        .diagnostics
+        .iter()
+        .any(|diagnostic| diagnostic.code == "dsh.bundle_no_entries"));
+}
+
+#[tokio::test]
+async fn bundle_entries_without_stable_ids_are_not_silently_dropped() {
+    let patch = r#"
+- insert:
+    - id: valid-entry
+    - id: ""
+"#;
+    let input = build_input(&[
+        ("package.json", BUNDLE_PACKAGE_JSON),
+        ("cordis.patch.yml", patch),
+    ]);
+    let (adapter, _) = load_dsh_package_adapter(input, None, 1_720_000_001).unwrap();
+    let client = DefaultPluginRuntimeClient::new(adapter);
+    let read = client.read_plugins(read_request(Vec::new())).await.unwrap();
+
+    assert_eq!(
+        read.sources.len(),
+        2,
+        "one valid and one invalid projection"
+    );
+    assert!(read
+        .diagnostics
+        .iter()
+        .any(|diagnostic| diagnostic.code == "dsh.bundle_entry_invalid"));
+}
+
+#[tokio::test]
+async fn invalid_package_cannot_be_activated() {
+    let input = build_input(&[("package.json", r#"{ "name": "plain" }"#)]);
+    let authority = activation_authority(&input);
+    let error = load_dsh_package_adapter(input, Some(authority), 1_720_000_001)
+        .err()
+        .expect("invalid dsh package must not activate");
+    assert!(error.to_string().contains("invalid dsh package projection"));
+}
+
+#[tokio::test]
+async fn wrong_adapter_is_rejected() {
+    let manifest = PluginPackageManifest {
+        schema_version: 1,
+        id: "acme.dsh".to_string(),
+        version: "1.0.0".to_string(),
+        adapter: "opencode_compatible".to_string(),
+        files: vec![PluginPackageFile {
+            path: "package.json".to_string(),
+            sha256: format!(
+                "sha256:{}",
+                hex::encode(Sha256::digest(BUNDLE_PACKAGE_JSON.as_bytes()))
+            ),
+        }],
+    };
+    let source = PluginPackageSourceIdentity {
+        package_id: "acme.dsh".to_string(),
+        version: "1.0.0".to_string(),
+        adapter: "opencode_compatible".to_string(),
+        source_path: "/managed/acme.dsh".to_string(),
+        content_hash: manifest.content_hash().unwrap(),
+    };
+    let files = BTreeMap::from([(
+        "package.json".to_string(),
+        BUNDLE_PACKAGE_JSON.as_bytes().to_vec(),
+    )]);
+    let input = PluginPackageInput::new(manifest, source, files).unwrap();
+
+    let error = load_dsh_package_adapter(input, None, 1)
+        .err()
+        .expect("wrong adapter must fail");
+    assert!(error.to_string().contains("not dsh-compatible"));
+}
diff --git a/src/crates/adapters/opencode-adapter/AGENTS-CN.md b/src/crates/adapters/opencode-adapter/AGENTS-CN.md
index a2aa76cb38..585d7769da 100644
--- a/src/crates/adapters/opencode-adapter/AGENTS-CN.md
+++ b/src/crates/adapters/opencode-adapter/AGENTS-CN.md
@@ -54,9 +54,10 @@
 ## 验证
 
 - `cargo test -p bitfun-opencode-adapter --test opencode_source_adapter`
-- `cargo test -p bitfun-opencode-adapter --test opencode_command_adapter`
+- `cargo test -p bitfun-opencode-adapter --test opencode_mcp_adapter`
+- `cargo test -p bitfun-opencode-adapter --test opencode_static_source_contracts opencode_command_adapter::`
+- `cargo test -p bitfun-opencode-adapter --test opencode_static_source_contracts opencode_subagent_adapter::`
 - `cargo test -p bitfun-opencode-adapter --test tool_source_contracts`
-- `cargo test -p bitfun-opencode-adapter --test opencode_subagent_adapter`
-- `cargo test -p bitfun-opencode-adapter p0_c2_fixture`
-- `cargo test -p bitfun-opencode-adapter client_path_projects_trusted_custom_tool_candidate_with_permission_prompt`
+- `cargo test -p bitfun-opencode-adapter --lib p0_c2_fixture`
+- `cargo test -p bitfun-opencode-adapter --lib client_path_projects_trusted_custom_tool_candidate_with_permission_prompt`
 - `node scripts/check-core-boundaries.mjs`
diff --git a/src/crates/adapters/opencode-adapter/AGENTS.md b/src/crates/adapters/opencode-adapter/AGENTS.md
index 550c004e7e..1750584bb9 100644
--- a/src/crates/adapters/opencode-adapter/AGENTS.md
+++ b/src/crates/adapters/opencode-adapter/AGENTS.md
@@ -114,9 +114,10 @@ Product-source boundary:
 ## Verification
 
 - `cargo test -p bitfun-opencode-adapter --test opencode_source_adapter`
-- `cargo test -p bitfun-opencode-adapter --test opencode_command_adapter`
+- `cargo test -p bitfun-opencode-adapter --test opencode_mcp_adapter`
+- `cargo test -p bitfun-opencode-adapter --test opencode_static_source_contracts opencode_command_adapter::`
+- `cargo test -p bitfun-opencode-adapter --test opencode_static_source_contracts opencode_subagent_adapter::`
 - `cargo test -p bitfun-opencode-adapter --test tool_source_contracts`
-- `cargo test -p bitfun-opencode-adapter --test opencode_subagent_adapter`
-- `cargo test -p bitfun-opencode-adapter p0_c2_fixture`
-- `cargo test -p bitfun-opencode-adapter client_path_projects_trusted_custom_tool_candidate_with_permission_prompt`
+- `cargo test -p bitfun-opencode-adapter --lib p0_c2_fixture`
+- `cargo test -p bitfun-opencode-adapter --lib client_path_projects_trusted_custom_tool_candidate_with_permission_prompt`
 - `node scripts/check-core-boundaries.mjs`
diff --git a/src/crates/adapters/opencode-adapter/Cargo.toml b/src/crates/adapters/opencode-adapter/Cargo.toml
index 804fd1e03e..0dbcc24215 100644
--- a/src/crates/adapters/opencode-adapter/Cargo.toml
+++ b/src/crates/adapters/opencode-adapter/Cargo.toml
@@ -4,6 +4,7 @@ version.workspace = true
 authors.workspace = true
 edition.workspace = true
 description = "OpenCode-compatible source and candidate adapter for BitFun"
+autotests = false
 
 [lib]
 name = "bitfun_opencode_adapter"
@@ -12,9 +13,9 @@ crate-type = ["rlib"]
 [dependencies]
 async-trait = { workspace = true }
 bitfun-plugin-runtime-client = { path = "../../execution/plugin-runtime-client" }
-bitfun-product-domains = { path = "../../contracts/product-domains", default-features = false, features = ["external-sources", "plugin-source"] }
-bitfun-runtime-ports = { path = "../../contracts/runtime-ports" }
-bitfun-services-core = { path = "../../services/services-core", default-features = false, features = ["markdown"] }
+bitfun-product-domains = { path = "../../contracts/product-domains", features = ["external-sources", "plugin-source"] }
+bitfun-runtime-ports = { path = "../../contracts/runtime-ports", features = ["plugin-runtime"] }
+bitfun-services-core = { path = "../../services/services-core", features = ["markdown"] }
 bitfun-static-hook-support = { path = "../static-hook-support" }
 dirs = { workspace = true }
 dunce = { workspace = true }
@@ -31,9 +32,26 @@ urlencoding = { workspace = true }
 url = { workspace = true }
 
 [dev-dependencies]
-bitfun-services-integrations = { path = "../../services/services-integrations", default-features = false, features = ["plugin-source", "script-tool-runtime"] }
+bitfun-runtime-ports = { path = "../../contracts/runtime-ports", features = ["script-tool-runtime"] }
+bitfun-services-integrations = { path = "../../services/services-integrations", features = ["plugin-source", "script-tool-runtime"] }
 tokio = { workspace = true, features = ["macros", "rt"] }
 tempfile = { workspace = true }
 
+[[test]]
+name = "opencode_mcp_adapter"
+path = "tests/opencode_mcp_adapter.rs"
+
+[[test]]
+name = "opencode_source_adapter"
+path = "tests/opencode_source_adapter.rs"
+
+[[test]]
+name = "opencode_static_source_contracts"
+path = "tests/opencode_static_source_contracts.rs"
+
+[[test]]
+name = "tool_source_contracts"
+path = "tests/tool_source_contracts.rs"
+
 [lints]
 workspace = true
diff --git a/src/crates/adapters/opencode-adapter/src/agent_source.rs b/src/crates/adapters/opencode-adapter/src/agent_source.rs
index da383aa8cb..1cd51f343f 100644
--- a/src/crates/adapters/opencode-adapter/src/agent_source.rs
+++ b/src/crates/adapters/opencode-adapter/src/agent_source.rs
@@ -14,14 +14,16 @@ use bitfun_product_domains::external_subagents::{
     ExternalSubagentContributionRole, ExternalSubagentDefinition, ExternalSubagentDiscoveryInput,
     ExternalSubagentLocalId, ExternalSubagentMode, ExternalSubagentModelProfileRequest,
     ExternalSubagentModelRequest, ExternalSubagentProvenanceRef, ExternalSubagentProviderIdentity,
-    ExternalSubagentProviderSnapshot, ExternalSubagentSourceProvider, ExternalSubagentToolRequest,
-    ExternalSubagentToolSelector, SecretText,
+    ExternalSubagentProviderSnapshot, ExternalSubagentSourceProvider,
+    ExternalSubagentToolCapability, ExternalSubagentToolRequest, ExternalSubagentToolSelector,
+    SecretText,
 };
 use bitfun_product_domains::tool_permissions::{
     wildcard_matches, PermissionConstraintLayer, PermissionEffect,
     PermissionResourceCaseSensitivity, PermissionRule,
 };
 use bitfun_services_core::{jsonc::strip_jsonc, markdown::FrontMatterMarkdown};
+use bitfun_static_hook_support::common_external_subagent_tool_capability;
 use serde_json::{Map, Value};
 use sha2::{Digest, Sha256};
 use std::collections::{BTreeMap, BTreeSet};
@@ -956,17 +958,19 @@ fn tool_request(
         degraded.push("opencode_default_permission_semantics_not_imported".to_string());
         return ExternalSubagentToolRequest {
             selectors: [
-                ("list", "LS"),
-                ("read", "Read"),
-                ("glob", "Glob"),
-                ("grep", "Grep"),
+                ("list", ExternalSubagentToolCapability::DirectoryList),
+                ("read", ExternalSubagentToolCapability::ReadFile),
+                ("glob", ExternalSubagentToolCapability::GlobFiles),
+                ("grep", ExternalSubagentToolCapability::SearchText),
             ]
             .into_iter()
-            .map(|(source_name, canonical)| ExternalSubagentToolSelector {
-                source_name: source_name.to_string(),
-                canonical_host_name: Some(canonical.to_string()),
-                allowed: true,
-            })
+            .map(
+                |(source_name, canonical_capability)| ExternalSubagentToolSelector {
+                    source_name: source_name.to_string(),
+                    canonical_capability: Some(canonical_capability),
+                    allowed: true,
+                },
+            )
             .collect(),
             uses_conservative_default: true,
         };
@@ -999,16 +1003,10 @@ fn tool_request(
             }
             continue;
         }
-        let canonical = match name.to_ascii_lowercase().as_str() {
-            "list" => Some("LS"),
-            "read" => Some("Read"),
-            "glob" => Some("Glob"),
-            "grep" => Some("Grep"),
-            _ => None,
-        };
+        let canonical_capability = common_external_subagent_tool_capability(name);
         selectors.push(ExternalSubagentToolSelector {
             source_name: name.clone(),
-            canonical_host_name: canonical.map(str::to_string),
+            canonical_capability,
             allowed,
         });
     }
@@ -1235,9 +1233,7 @@ fn permission_action_uses_workspace_paths(
         .selectors
         .iter()
         .filter(|selector| selector.allowed)
-        .filter_map(|selector| {
-            permission_action_for_host_tool(selector.canonical_host_name.as_deref())
-        })
+        .filter_map(|selector| permission_action_for_tool_capability(selector.canonical_capability))
         .filter(|host_action| {
             wildcard_matches(
                 host_action,
@@ -1285,7 +1281,7 @@ fn validate_current_permission_action_enforcement(
         if !selector.allowed {
             return false;
         }
-        let host_action = permission_action_for_host_tool(selector.canonical_host_name.as_deref());
+        let host_action = permission_action_for_tool_capability(selector.canonical_capability);
         let rule_reaches_tool = wildcard_matches(
             &selector.source_name,
             source_action,
@@ -1324,11 +1320,10 @@ fn validate_permission_action_enforcement(
         && requested_tools
             .selectors
             .iter()
-            .any(|selector| selector.allowed && selector.canonical_host_name.is_none());
+            .any(|selector| selector.allowed && selector.canonical_capability.is_none());
     let selected_named_tool_is_unenforced = source_action != "*"
         && requested_tools.selectors.iter().any(|selector| {
-            let host_action =
-                permission_action_for_host_tool(selector.canonical_host_name.as_deref());
+            let host_action = permission_action_for_tool_capability(selector.canonical_capability);
             let source_action_matches = wildcard_matches(
                 &selector.source_name,
                 source_action,
@@ -1347,8 +1342,7 @@ fn validate_permission_action_enforcement(
     let wildcard_reaches_unenforced_tool = source_action == "*"
         && requested_tools.selectors.iter().any(|selector| {
             selector.allowed
-                && permission_action_for_host_tool(selector.canonical_host_name.as_deref())
-                    .is_none()
+                && permission_action_for_tool_capability(selector.canonical_capability).is_none()
         });
 
     if effect != PermissionEffect::Allow
@@ -1362,16 +1356,15 @@ fn validate_permission_action_enforcement(
     }
 }
 
-fn permission_action_for_host_tool(host_tool: Option<&str>) -> Option<&'static str> {
-    match host_tool {
-        Some("Read") => Some("read"),
-        Some("Write" | "Edit" | "Delete") => Some("edit"),
-        Some("Bash" | "ExecCommand") => Some("bash"),
-        Some("Task") => Some("task"),
-        Some("Skill") => Some("skill"),
-        Some("WebFetch") => Some("webfetch"),
-        Some("WebSearch") => Some("websearch"),
-        Some("Git") => Some("git"),
+fn permission_action_for_tool_capability(
+    capability: Option<ExternalSubagentToolCapability>,
+) -> Option<&'static str> {
+    match capability {
+        Some(ExternalSubagentToolCapability::ReadFile) => Some("read"),
+        Some(
+            ExternalSubagentToolCapability::WriteFile | ExternalSubagentToolCapability::EditFile,
+        ) => Some("edit"),
+        Some(ExternalSubagentToolCapability::ExecuteCommand) => Some("bash"),
         _ => None,
     }
 }
diff --git a/src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts.rs b/src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts.rs
new file mode 100644
index 0000000000..112f66dc2c
--- /dev/null
+++ b/src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts.rs
@@ -0,0 +1,10 @@
+#[path = "opencode_static_source_contracts/hook_source.rs"]
+mod hook_source;
+#[path = "opencode_static_source_contracts/opencode_command_adapter.rs"]
+mod opencode_command_adapter;
+#[path = "opencode_static_source_contracts/opencode_skill_roots.rs"]
+mod opencode_skill_roots;
+#[path = "opencode_static_source_contracts/opencode_subagent_adapter.rs"]
+mod opencode_subagent_adapter;
+#[path = "opencode_static_source_contracts/opencode_workspace_references.rs"]
+mod opencode_workspace_references;
diff --git a/src/crates/adapters/opencode-adapter/tests/hook_source.rs b/src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts/hook_source.rs
similarity index 100%
rename from src/crates/adapters/opencode-adapter/tests/hook_source.rs
rename to src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts/hook_source.rs
diff --git a/src/crates/adapters/opencode-adapter/tests/opencode_command_adapter.rs b/src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts/opencode_command_adapter.rs
similarity index 100%
rename from src/crates/adapters/opencode-adapter/tests/opencode_command_adapter.rs
rename to src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts/opencode_command_adapter.rs
diff --git a/src/crates/adapters/opencode-adapter/tests/opencode_skill_roots.rs b/src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts/opencode_skill_roots.rs
similarity index 100%
rename from src/crates/adapters/opencode-adapter/tests/opencode_skill_roots.rs
rename to src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts/opencode_skill_roots.rs
diff --git a/src/crates/adapters/opencode-adapter/tests/opencode_subagent_adapter.rs b/src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts/opencode_subagent_adapter.rs
similarity index 96%
rename from src/crates/adapters/opencode-adapter/tests/opencode_subagent_adapter.rs
rename to src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts/opencode_subagent_adapter.rs
index bbd12953cb..344addbdb7 100644
--- a/src/crates/adapters/opencode-adapter/tests/opencode_subagent_adapter.rs
+++ b/src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts/opencode_subagent_adapter.rs
@@ -7,7 +7,7 @@ use bitfun_product_domains::external_sources::{
 use bitfun_product_domains::external_subagents::{
     ExternalSubagentCompatibilityState, ExternalSubagentDiscoveryInput, ExternalSubagentMode,
     ExternalSubagentModelProfileRequest, ExternalSubagentModelRequest,
-    ExternalSubagentSourceProvider,
+    ExternalSubagentSourceProvider, ExternalSubagentToolCapability,
 };
 use bitfun_product_domains::tool_permissions::{
     PermissionEffect, PermissionEvaluator, PermissionRule,
@@ -51,6 +51,57 @@ fn discover(
         .expect("discover OpenCode agents")
 }
 
+#[test]
+fn opencode_builtin_tools_map_to_provider_neutral_capabilities() {
+    let temp = TempDir::new().unwrap();
+    let workspace = temp.path().join("workspace");
+    fs::create_dir_all(workspace.join(".git")).unwrap();
+    fs::create_dir_all(temp.path().join("user")).unwrap();
+    fs::write(
+        temp.path().join("user/opencode.json"),
+        r#"{
+          "agent": {
+            "worker": {
+              "prompt": "Make the requested change",
+              "mode": "subagent",
+              "tools": {
+                "bash": true,
+                "edit": true,
+                "write": true
+              }
+            }
+          }
+        }"#,
+    )
+    .unwrap();
+
+    let snapshot = discover(&provider(&temp, &workspace), workspace, BTreeSet::new());
+    let definition = snapshot
+        .definitions
+        .iter()
+        .find(|definition| definition.logical_id == "worker")
+        .unwrap();
+    let mappings = definition
+        .requested_tools
+        .selectors
+        .iter()
+        .map(|selector| (selector.source_name.as_str(), selector.canonical_capability))
+        .collect::<Vec<_>>();
+
+    assert_eq!(
+        mappings,
+        vec![
+            ("bash", Some(ExternalSubagentToolCapability::ExecuteCommand)),
+            ("edit", Some(ExternalSubagentToolCapability::EditFile)),
+            ("write", Some(ExternalSubagentToolCapability::WriteFile)),
+        ]
+    );
+    assert_eq!(
+        definition.compatibility,
+        ExternalSubagentCompatibilityState::Ready
+    );
+}
+
 #[test]
 fn omo_oracle_flat_permissions_become_provider_neutral_constraints() {
     let temp = TempDir::new().unwrap();
@@ -1258,9 +1309,14 @@ fn safe_subset_is_fail_closed_and_default_tools_are_explicit() {
             .requested_tools
             .selectors
             .iter()
-            .map(|item| item.canonical_host_name.as_deref().unwrap())
+            .map(|item| item.canonical_capability.unwrap())
             .collect::<Vec<_>>(),
-        vec!["LS", "Read", "Glob", "Grep"]
+        vec![
+            ExternalSubagentToolCapability::DirectoryList,
+            ExternalSubagentToolCapability::ReadFile,
+            ExternalSubagentToolCapability::GlobFiles,
+            ExternalSubagentToolCapability::SearchText,
+        ]
     );
     assert!(defaulted.requested_tools.uses_conservative_default);
     assert_eq!(
diff --git a/src/crates/adapters/opencode-adapter/tests/opencode_workspace_references.rs b/src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts/opencode_workspace_references.rs
similarity index 100%
rename from src/crates/adapters/opencode-adapter/tests/opencode_workspace_references.rs
rename to src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts/opencode_workspace_references.rs
diff --git a/src/crates/adapters/static-hook-support/Cargo.toml b/src/crates/adapters/static-hook-support/Cargo.toml
index 3159aae70e..4ed3f3a7f9 100644
--- a/src/crates/adapters/static-hook-support/Cargo.toml
+++ b/src/crates/adapters/static-hook-support/Cargo.toml
@@ -10,8 +10,8 @@ name = "bitfun_static_hook_support"
 crate-type = ["rlib"]
 
 [dependencies]
-bitfun-product-domains = { path = "../../contracts/product-domains", default-features = false, features = ["external-sources"] }
-bitfun-services-core = { path = "../../services/services-core", default-features = false }
+bitfun-product-domains = { path = "../../contracts/product-domains", features = ["external-sources"] }
+bitfun-services-core = { path = "../../services/services-core" }
 serde_json = { workspace = true }
 toml = { workspace = true }
 hex = { workspace = true }
diff --git a/src/crates/adapters/static-hook-support/src/lib.rs b/src/crates/adapters/static-hook-support/src/lib.rs
index 0b465d8997..a3d07ad145 100644
--- a/src/crates/adapters/static-hook-support/src/lib.rs
+++ b/src/crates/adapters/static-hook-support/src/lib.rs
@@ -8,6 +8,7 @@ use bitfun_product_domains::external_hook_import::{
     MAX_EXTERNAL_HOOK_IMPORT_ASSET_BYTES, MAX_EXTERNAL_HOOK_IMPORT_ASSET_DEPTH,
     MAX_EXTERNAL_HOOK_IMPORT_TOTAL_ASSET_BYTES,
 };
+use bitfun_product_domains::external_subagents::ExternalSubagentToolCapability;
 pub use bitfun_services_core::bounded_fs::{
     collect_bounded_regular_files, read_bounded_file, read_bounded_text, BoundedDirectoryWalkError,
     BoundedDirectoryWalkLimit, BoundedDirectoryWalkLimits, BoundedFileRead, BoundedTextRead,
@@ -20,6 +21,29 @@ use std::path::{Component, Path, PathBuf};
 const MAX_MATCHER_BYTES: usize = 512;
 const MAX_EVENT_NAME_BYTES: usize = 160;
 
+const COMMON_EXTERNAL_SUBAGENT_TOOL_CAPABILITIES: &[(&str, ExternalSubagentToolCapability)] = &[
+    ("ls", ExternalSubagentToolCapability::DirectoryList),
+    ("list", ExternalSubagentToolCapability::DirectoryList),
+    ("read", ExternalSubagentToolCapability::ReadFile),
+    ("glob", ExternalSubagentToolCapability::GlobFiles),
+    ("grep", ExternalSubagentToolCapability::SearchText),
+    ("bash", ExternalSubagentToolCapability::ExecuteCommand),
+    ("edit", ExternalSubagentToolCapability::EditFile),
+    ("write", ExternalSubagentToolCapability::WriteFile),
+];
+
+/// Normalizes widely shared external Agent tool labels at the adapter boundary.
+/// Provider-specific aliases remain owned by their ecosystem adapter.
+pub fn common_external_subagent_tool_capability(
+    name: &str,
+) -> Option<ExternalSubagentToolCapability> {
+    COMMON_EXTERNAL_SUBAGENT_TOOL_CAPABILITIES
+        .iter()
+        .find_map(|(candidate, capability)| {
+            candidate.eq_ignore_ascii_case(name).then_some(*capability)
+        })
+}
+
 /// Distinguishes an absent path from metadata failures. Static adapters may
 /// ignore `NotFound`, but permission and transient filesystem failures must be
 /// surfaced so the coordinator can retain the last valid snapshot as stale.
@@ -648,6 +672,29 @@ fn matcher_summary(value: Option<&Value>) -> ExternalHookMatcherSummary {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use bitfun_product_domains::external_subagents::ExternalSubagentToolCapability;
+
+    #[test]
+    fn common_external_tool_names_map_without_source_specific_contract_behavior() {
+        use ExternalSubagentToolCapability::{EditFile, ExecuteCommand, WriteFile};
+
+        assert_eq!(
+            common_external_subagent_tool_capability("bash"),
+            Some(ExecuteCommand)
+        );
+        assert_eq!(
+            common_external_subagent_tool_capability("EDIT"),
+            Some(EditFile)
+        );
+        assert_eq!(
+            common_external_subagent_tool_capability("write"),
+            Some(WriteFile)
+        );
+        assert_eq!(
+            common_external_subagent_tool_capability("provider-specific-tool"),
+            None
+        );
+    }
 
     #[test]
     fn project_ancestors_are_bounded_and_returned_outer_to_inner() {
diff --git a/src/crates/adapters/transport/AGENTS.md b/src/crates/adapters/transport/AGENTS.md
index 27b47cc6f7..8ab55d71bf 100644
--- a/src/crates/adapters/transport/AGENTS.md
+++ b/src/crates/adapters/transport/AGENTS.md
@@ -2,9 +2,12 @@
 
 Scope: this guide applies to `src/crates/adapters/transport`.
 
-`bitfun-transport` owns the event delivery abstraction and adapters used by
-current product hosts. It bridges owned event projections to concrete delivery
-channels without owning product logic or future protocol plans.
+`bitfun-transport` owns the event delivery abstraction and the smallest
+protocol-neutral message mechanics reused by current product hosts. It bridges
+owned event projections to concrete delivery channels and caps JSON encoding
+without owning product logic or protocol plans. Its colocated TypeScript core
+owns carrier-neutral message and JSON-RPC correlation mechanics reused by SDK
+stdio and the WebSocket client.
 
 ## Guardrails
 
@@ -19,6 +22,10 @@ channels without owning product logic or future protocol plans.
   platform plan alone is not enough.
 - Transport may serialize and deliver events; it must not decide product policy,
   session lifecycle, tool exposure, permissions, or remote workspace behavior.
+- Shared JSON and message helpers must remain protocol-neutral. Host wire
+  shapes, routes, authentication, lifecycle, framing choice, and concrete
+  size-limit policy stay in the owning protocol adapter or app. Do not extract
+  a framing helper until at least two current consumers share its semantics.
 - Preserve event names, payload compatibility, ordering assumptions, and
   backpressure/error semantics when refactoring adapters.
 - Keep protocol routes and frontend clients in their owning app. Their existence
@@ -28,6 +35,7 @@ channels without owning product logic or future protocol plans.
 
 ```bash
 cargo check -p bitfun-transport
+pnpm --dir sdk/typescript test
 node scripts/check-core-boundaries.mjs
 ```
 
diff --git a/src/crates/adapters/transport/Cargo.toml b/src/crates/adapters/transport/Cargo.toml
index 582f32cba3..42bc1b4fa7 100644
--- a/src/crates/adapters/transport/Cargo.toml
+++ b/src/crates/adapters/transport/Cargo.toml
@@ -14,9 +14,11 @@ bitfun-events = { path = "../../contracts/events" }
 
 # Inherited from workspace
 async-trait = { workspace = true }
+serde = { workspace = true }
 serde_json = { workspace = true }
 anyhow = { workspace = true }
 log = { workspace = true }
+thiserror = { workspace = true }
 
 # Tauri adapter dependency (optional, enable only when needed)
 tauri = { workspace = true, optional = true }
diff --git a/src/crates/adapters/transport/src/json.rs b/src/crates/adapters/transport/src/json.rs
new file mode 100644
index 0000000000..e3568f9933
--- /dev/null
+++ b/src/crates/adapters/transport/src/json.rs
@@ -0,0 +1,64 @@
+use std::io::Write;
+
+use serde::Serialize;
+
+/// Serialize a JSON payload without buffering more than the configured budget.
+pub fn encode_json_with_limit<T>(value: &T, max_bytes: usize) -> Result<Vec<u8>, JsonCodecError>
+where
+    T: Serialize + ?Sized,
+{
+    let mut writer = CappedWriter::new(max_bytes);
+    let result = serde_json::to_writer(&mut writer, value);
+    if writer.overflowed {
+        return Err(JsonCodecError::PayloadTooLarge {
+            minimum_size: max_bytes.saturating_add(1),
+            max_bytes,
+        });
+    }
+    result.map_err(JsonCodecError::Encode)?;
+    Ok(writer.bytes)
+}
+
+struct CappedWriter {
+    bytes: Vec<u8>,
+    max_bytes: usize,
+    overflowed: bool,
+}
+
+impl CappedWriter {
+    fn new(max_bytes: usize) -> Self {
+        Self {
+            bytes: Vec::with_capacity(max_bytes.min(16 * 1024)),
+            max_bytes,
+            overflowed: false,
+        }
+    }
+}
+
+impl Write for CappedWriter {
+    fn write(&mut self, input: &[u8]) -> std::io::Result<usize> {
+        let remaining = self.max_bytes.saturating_sub(self.bytes.len());
+        if input.len() > remaining {
+            self.bytes.extend_from_slice(&input[..remaining]);
+            self.overflowed = true;
+            return Err(std::io::Error::other("JSON payload is too large"));
+        }
+        self.bytes.extend_from_slice(input);
+        Ok(input.len())
+    }
+
+    fn flush(&mut self) -> std::io::Result<()> {
+        Ok(())
+    }
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum JsonCodecError {
+    #[error("JSON payload exceeds {max_bytes} bytes (at least {minimum_size} bytes)")]
+    PayloadTooLarge {
+        minimum_size: usize,
+        max_bytes: usize,
+    },
+    #[error("failed to serialize JSON payload")]
+    Encode(#[source] serde_json::Error),
+}
diff --git a/src/crates/adapters/transport/src/lib.rs b/src/crates/adapters/transport/src/lib.rs
index c17140f832..3a1907ae98 100644
--- a/src/crates/adapters/transport/src/lib.rs
+++ b/src/crates/adapters/transport/src/lib.rs
@@ -1,11 +1,13 @@
 pub mod adapters;
 pub mod emitter;
+mod json;
 /// BitFun Transport Layer
 ///
 /// Event delivery abstraction used by current product hosts.
 pub mod traits;
 
 pub use emitter::TransportEmitter;
+pub use json::{encode_json_with_limit, JsonCodecError};
 pub use traits::TransportAdapter;
 
 #[cfg(feature = "tauri-adapter")]
diff --git a/src/crates/adapters/transport/tests/message_transport.rs b/src/crates/adapters/transport/tests/message_transport.rs
new file mode 100644
index 0000000000..d0f896173d
--- /dev/null
+++ b/src/crates/adapters/transport/tests/message_transport.rs
@@ -0,0 +1,15 @@
+use bitfun_transport::{encode_json_with_limit, JsonCodecError};
+
+#[test]
+fn bounded_json_encoding_stops_before_exceeding_the_budget() {
+    let error = encode_json_with_limit(&serde_json::json!({ "payload": "x".repeat(64) }), 32)
+        .expect_err("oversized JSON must be rejected");
+
+    assert!(matches!(
+        error,
+        JsonCodecError::PayloadTooLarge {
+            minimum_size: 33,
+            max_bytes: 32
+        }
+    ));
+}
diff --git a/src/crates/adapters/transport/typescript/src/index.ts b/src/crates/adapters/transport/typescript/src/index.ts
new file mode 100644
index 0000000000..ce10a43c7e
--- /dev/null
+++ b/src/crates/adapters/transport/typescript/src/index.ts
@@ -0,0 +1,586 @@
+export type JsonRpcId = number | string;
+
+export interface MessageTransportObserver {
+  message(message: string): void;
+  close(cause?: unknown): void;
+}
+
+/**
+ * A carrier-neutral, one-message-at-a-time channel.
+ *
+ * Implementations own carrier framing and reconnect policy. A resolved `send`
+ * means the carrier accepted the complete message; keeping the promise pending
+ * is how a carrier projects backpressure into the shared JSON-RPC peer.
+ */
+export interface MessageTransport {
+  subscribe(observer: MessageTransportObserver): () => void;
+  send(message: string): Promise<void>;
+  close(): Promise<void>;
+}
+
+export interface WebSocketLike {
+  readonly readyState: number;
+  readonly bufferedAmount: number;
+  send(message: string): void;
+  close(): void;
+}
+
+export interface WebSocketMessageTransportOptions {
+  maxBufferedBytes: number;
+  drainTimeoutMs: number;
+}
+
+export interface JsonRpcNotification {
+  method: string;
+  params: unknown;
+}
+
+export interface JsonRpcLimits {
+  maxMessageBytes: number;
+  maxPendingRequests: number;
+  maxPendingBytes: number;
+  maxOutboundBytes: number;
+}
+
+export interface JsonRpcPeerOptions {
+  createRequestId(): JsonRpcId;
+  requestTimeoutMs: number;
+  limits: JsonRpcLimits;
+  onNotificationError?(
+    error: Error,
+    notification: JsonRpcNotification,
+  ): void;
+}
+
+export class JsonRpcProtocolError extends Error {
+  override readonly name = "JsonRpcProtocolError";
+
+  constructor(message: string, cause?: unknown) {
+    super(message);
+    (this as Error & { cause?: unknown }).cause = cause;
+  }
+}
+
+export class JsonRpcTransportError extends Error {
+  override readonly name = "JsonRpcTransportError";
+
+  constructor(message: string, cause?: unknown) {
+    super(message);
+    (this as Error & { cause?: unknown }).cause = cause;
+  }
+}
+
+export class JsonRpcRemoteError extends Error {
+  override readonly name = "JsonRpcRemoteError";
+  readonly code: number;
+  readonly data: unknown;
+
+  constructor(code: number, message: string, data: unknown) {
+    super(message);
+    this.code = code;
+    this.data = data;
+  }
+}
+
+export class JsonRpcTimeoutError extends Error {
+  override readonly name = "JsonRpcTimeoutError";
+  readonly method: string;
+  readonly id: JsonRpcId;
+
+  constructor(method: string, id: JsonRpcId) {
+    super(`JSON-RPC request timed out: ${method}`);
+    this.method = method;
+    this.id = id;
+  }
+}
+
+export type JsonRpcLimit =
+  | "message_bytes"
+  | "pending_count"
+  | "pending_bytes"
+  | "outbound_bytes";
+
+export class JsonRpcLimitError extends Error {
+  override readonly name = "JsonRpcLimitError";
+  readonly limit: JsonRpcLimit;
+
+  constructor(limit: JsonRpcLimit) {
+    super(`JSON-RPC ${limit.replace(/_/g, " ")} limit was exceeded`);
+    this.limit = limit;
+  }
+}
+
+interface PendingRequest {
+  retainedBytes: number;
+  timer: ReturnType<typeof setTimeout>;
+  resolve(value: unknown): void;
+  reject(error: Error): void;
+}
+
+const UTF8 = new TextEncoder();
+const WEB_SOCKET_OPEN = 1;
+const WEB_SOCKET_CLOSING = 2;
+
+/** Browser-compatible WebSocket message delivery with bounded backpressure. */
+export class WebSocketMessageTransport implements MessageTransport {
+  readonly #socket: WebSocketLike;
+  readonly #options: WebSocketMessageTransportOptions;
+  #observer?: MessageTransportObserver;
+  #closePromise?: Promise<void>;
+  #closed = false;
+
+  constructor(
+    socket: WebSocketLike,
+    options: WebSocketMessageTransportOptions,
+  ) {
+    assertPositiveInteger(options.maxBufferedBytes, "WebSocket buffer limit");
+    assertPositiveInteger(options.drainTimeoutMs, "WebSocket drain timeout");
+    this.#socket = socket;
+    this.#options = options;
+  }
+
+  subscribe(observer: MessageTransportObserver): () => void {
+    if (this.#observer !== undefined) {
+      throw new Error("WebSocket carrier already has a message owner");
+    }
+    this.#observer = observer;
+    return () => {
+      if (this.#observer === observer) {
+        this.#observer = undefined;
+      }
+    };
+  }
+
+  async send(message: string): Promise<void> {
+    if (this.#closed || this.#socket.readyState !== WEB_SOCKET_OPEN) {
+      throw new Error("WebSocket is not connected");
+    }
+    const messageBytes = UTF8.encode(message).byteLength;
+    if (
+      this.#socket.bufferedAmount + messageBytes >
+      this.#options.maxBufferedBytes
+    ) {
+      throw new Error("WebSocket send buffer capacity was exceeded");
+    }
+    this.#socket.send(message);
+    await waitForWebSocketDrain(
+      this.#socket,
+      Date.now() + this.#options.drainTimeoutMs,
+    );
+  }
+
+  receive(message: string): void {
+    if (!this.#closed) {
+      this.#observer?.message(message);
+    }
+  }
+
+  carrierClosed(cause: unknown): void {
+    if (this.#closed) {
+      return;
+    }
+    this.#closed = true;
+    this.#observer?.close(cause);
+  }
+
+  close(): Promise<void> {
+    if (this.#closePromise === undefined) {
+      this.#closed = true;
+      if (this.#socket.readyState < WEB_SOCKET_CLOSING) {
+        this.#socket.close();
+      }
+      this.#closePromise = Promise.resolve();
+    }
+    return this.#closePromise;
+  }
+}
+
+/**
+ * Shared JSON-RPC 2.0 request correlation and bounded lifecycle machinery.
+ *
+ * This class deliberately does not own carrier framing/reconnect or
+ * application notification fanout and result validation.
+ */
+export class JsonRpcPeer {
+  readonly #transport: MessageTransport;
+  readonly #options: JsonRpcPeerOptions;
+  readonly #pending = new Map<JsonRpcId, PendingRequest>();
+  readonly #notificationListeners = new Set<
+    (notification: JsonRpcNotification) => void
+  >();
+  readonly #failureListeners = new Set<(error: Error) => void>();
+  readonly #timedOutIds = new Set<JsonRpcId>();
+  #unsubscribeTransport: () => void = () => {};
+  #pendingBytes = 0;
+  #outboundBytes = 0;
+  #failure?: Error;
+  #closePromise?: Promise<void>;
+
+  constructor(transport: MessageTransport, options: JsonRpcPeerOptions) {
+    validateOptions(options);
+    this.#transport = transport;
+    this.#options = options;
+    const unsubscribeTransport = transport.subscribe({
+      message: (message) => this.#receive(message),
+      close: (cause) => {
+        this.#fail(
+          new JsonRpcTransportError("JSON-RPC carrier closed", cause),
+        );
+      },
+    });
+    this.#unsubscribeTransport = unsubscribeTransport;
+    if (this.#failure !== undefined) {
+      unsubscribeTransport();
+    }
+  }
+
+  request<T = unknown>(
+    method: string,
+    params: object,
+    timeoutMs = this.#options.requestTimeoutMs,
+  ): Promise<T> {
+    if (this.#failure !== undefined) {
+      return Promise.reject(this.#failure);
+    }
+    if (method.length === 0) {
+      return Promise.reject(new TypeError("JSON-RPC method must not be empty"));
+    }
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
+      return Promise.reject(new TypeError("JSON-RPC timeout must be a positive integer"));
+    }
+
+    const id = this.#options.createRequestId();
+    if (
+      !isValidId(id) ||
+      this.#pending.has(id) ||
+      this.#timedOutIds.has(id)
+    ) {
+      return Promise.reject(new TypeError("JSON-RPC request id must be unique and valid"));
+    }
+
+    let message: string;
+    try {
+      message = JSON.stringify({ jsonrpc: "2.0", id, method, params });
+    } catch (cause) {
+      const error = new TypeError("JSON-RPC request params are not serializable");
+      (error as TypeError & { cause?: unknown }).cause = cause;
+      return Promise.reject(error);
+    }
+    const retainedBytes = messageBytes(message);
+    const limit = this.#options.limits;
+    if (retainedBytes > limit.maxMessageBytes) {
+      return Promise.reject(new JsonRpcLimitError("message_bytes"));
+    }
+    if (this.#pending.size >= limit.maxPendingRequests) {
+      return Promise.reject(new JsonRpcLimitError("pending_count"));
+    }
+    if (this.#pendingBytes + retainedBytes > limit.maxPendingBytes) {
+      return Promise.reject(new JsonRpcLimitError("pending_bytes"));
+    }
+    if (this.#outboundBytes + retainedBytes > limit.maxOutboundBytes) {
+      return Promise.reject(new JsonRpcLimitError("outbound_bytes"));
+    }
+
+    let resolveRequest!: (value: T) => void;
+    let rejectRequest!: (error: Error) => void;
+    const response = new Promise<T>((resolve, reject) => {
+      resolveRequest = resolve;
+      rejectRequest = reject;
+    });
+    const timer = setTimeout(() => {
+      const pending = this.#pending.get(id);
+      if (pending === undefined) {
+        return;
+      }
+      if (
+        this.#timedOutIds.size >=
+        this.#options.limits.maxPendingRequests
+      ) {
+        this.#fail(
+          new JsonRpcProtocolError(
+            "JSON-RPC timeout tombstone capacity was exceeded",
+          ),
+        );
+        return;
+      }
+      this.#removePending(id, pending);
+      this.#timedOutIds.add(id);
+      pending.reject(new JsonRpcTimeoutError(method, id));
+    }, timeoutMs);
+    this.#pending.set(id, {
+      retainedBytes,
+      timer,
+      resolve: (value) => resolveRequest(value as T),
+      reject: rejectRequest,
+    });
+    this.#pendingBytes += retainedBytes;
+    this.#outboundBytes += retainedBytes;
+
+    let sending: Promise<void>;
+    try {
+      sending = this.#transport.send(message);
+    } catch (cause) {
+      this.#releaseOutbound(retainedBytes);
+      this.#fail(
+        new JsonRpcTransportError("JSON-RPC carrier rejected a message", cause),
+      );
+      return response;
+    }
+    void sending.then(
+      () => this.#releaseOutbound(retainedBytes),
+      (cause: unknown) => {
+        this.#releaseOutbound(retainedBytes);
+        this.#fail(
+          new JsonRpcTransportError("JSON-RPC carrier rejected a message", cause),
+        );
+      },
+    );
+    return response;
+  }
+
+  onNotification(
+    listener: (notification: JsonRpcNotification) => void,
+  ): () => void {
+    this.#notificationListeners.add(listener);
+    return () => this.#notificationListeners.delete(listener);
+  }
+
+  onFailure(listener: (error: Error) => void): () => void {
+    if (this.#failure !== undefined) {
+      listener(this.#failure);
+      return () => {};
+    }
+    this.#failureListeners.add(listener);
+    return () => this.#failureListeners.delete(listener);
+  }
+
+  abort(error: Error): Promise<void> {
+    this.#fail(error);
+    return this.#closeTransport();
+  }
+
+  close(): Promise<void> {
+    this.#fail(new JsonRpcTransportError("JSON-RPC peer closed"));
+    return this.#closeTransport();
+  }
+
+  #receive(message: string): void {
+    if (this.#failure !== undefined) {
+      return;
+    }
+    let notification: JsonRpcNotification | undefined;
+    try {
+      if (messageBytes(message) > this.#options.limits.maxMessageBytes) {
+        throw new JsonRpcProtocolError(
+          "JSON-RPC carrier message exceeds the byte limit",
+        );
+      }
+      const envelope = JSON.parse(message) as unknown;
+      if (!isRecord(envelope) || envelope.jsonrpc !== "2.0") {
+        throw new JsonRpcProtocolError("Invalid JSON-RPC 2.0 envelope");
+      }
+      if (hasOwn(envelope, "id")) {
+        this.#receiveResponse(envelope);
+        return;
+      }
+      notification = this.#parseNotification(envelope);
+    } catch (cause) {
+      const error = cause instanceof JsonRpcProtocolError
+        ? cause
+        : new JsonRpcProtocolError("Invalid JSON-RPC carrier message", cause);
+      this.#fail(error);
+      return;
+    }
+    for (const listener of this.#notificationListeners) {
+      try {
+        listener(notification);
+      } catch (cause) {
+        const error = cause instanceof Error
+          ? cause
+          : new JsonRpcProtocolError("JSON-RPC notification listener failed", cause);
+        try {
+          this.#options.onNotificationError?.(error, notification);
+        } catch {
+          // The application hook is diagnostic/policy code. Its own failure
+          // must not be reclassified as malformed wire input.
+        }
+      }
+    }
+  }
+
+  #receiveResponse(envelope: Record<string, unknown>): void {
+    const id = envelope.id;
+    if (!isValidId(id)) {
+      throw new JsonRpcProtocolError("Invalid JSON-RPC response id");
+    }
+    const hasResult = hasOwn(envelope, "result");
+    const hasError = hasOwn(envelope, "error");
+    if (hasResult === hasError) {
+      throw new JsonRpcProtocolError(
+        "JSON-RPC response must contain exactly one result or error",
+      );
+    }
+    if (!hasOnlyKeys(envelope, ["jsonrpc", "id", hasError ? "error" : "result"])) {
+      throw new JsonRpcProtocolError("JSON-RPC response contains unknown fields");
+    }
+
+    let remoteError: JsonRpcRemoteError | undefined;
+    if (hasError) {
+      const remote = envelope.error;
+      if (!isRecord(remote)) {
+        throw new JsonRpcProtocolError("Invalid JSON-RPC error envelope");
+      }
+      const allowed = hasOwn(remote, "data")
+        ? ["code", "message", "data"]
+        : ["code", "message"];
+      if (
+        !hasOnlyKeys(remote, allowed) ||
+        !Number.isSafeInteger(remote.code) ||
+        typeof remote.message !== "string"
+      ) {
+        throw new JsonRpcProtocolError("Invalid JSON-RPC error envelope");
+      }
+      remoteError = new JsonRpcRemoteError(
+        remote.code as number,
+        remote.message,
+        remote.data,
+      );
+    }
+
+    if (this.#timedOutIds.delete(id)) {
+      return;
+    }
+    const pending = this.#pending.get(id);
+    if (pending === undefined) {
+      throw new JsonRpcProtocolError("Unknown JSON-RPC response id");
+    }
+    this.#removePending(id, pending);
+    if (remoteError !== undefined) {
+      pending.reject(remoteError);
+    } else {
+      pending.resolve(envelope.result);
+    }
+  }
+
+  #parseNotification(envelope: Record<string, unknown>): JsonRpcNotification {
+    if (
+      typeof envelope.method !== "string" ||
+      envelope.method.length === 0 ||
+      !hasOnlyKeys(
+        envelope,
+        hasOwn(envelope, "params")
+          ? ["jsonrpc", "method", "params"]
+          : ["jsonrpc", "method"],
+      )
+    ) {
+      throw new JsonRpcProtocolError("Invalid JSON-RPC notification envelope");
+    }
+    return {
+      method: envelope.method,
+      params: envelope.params,
+    };
+  }
+
+  #removePending(id: JsonRpcId, pending: PendingRequest): void {
+    clearTimeout(pending.timer);
+    this.#pending.delete(id);
+    this.#pendingBytes -= pending.retainedBytes;
+  }
+
+  #releaseOutbound(bytes: number): void {
+    this.#outboundBytes = Math.max(0, this.#outboundBytes - bytes);
+  }
+
+  #fail(error: Error): void {
+    if (this.#failure !== undefined) {
+      return;
+    }
+    this.#failure = error;
+    this.#unsubscribeTransport();
+    for (const [id, pending] of this.#pending) {
+      this.#removePending(id, pending);
+      pending.reject(error);
+    }
+    for (const listener of this.#failureListeners) {
+      try {
+        listener(error);
+      } catch {
+        // Failure listeners are observers. Resource reclamation and the other
+        // observers must still run if application diagnostics throw.
+      }
+    }
+    this.#failureListeners.clear();
+    this.#notificationListeners.clear();
+    void this.#closeTransport().catch(() => {});
+  }
+
+  #closeTransport(): Promise<void> {
+    if (this.#closePromise === undefined) {
+      try {
+        this.#closePromise = Promise.resolve(this.#transport.close());
+      } catch (error) {
+        this.#closePromise = Promise.reject(error);
+      }
+    }
+    return this.#closePromise;
+  }
+}
+
+function validateOptions(options: JsonRpcPeerOptions): void {
+  if (!Number.isSafeInteger(options.requestTimeoutMs) || options.requestTimeoutMs <= 0) {
+    throw new TypeError("JSON-RPC request timeout must be a positive integer");
+  }
+  for (const [name, value] of Object.entries(options.limits)) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+      throw new TypeError(`JSON-RPC ${name} must be a positive integer`);
+    }
+  }
+}
+
+function assertPositiveInteger(value: number, name: string): void {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new TypeError(`${name} must be a positive integer`);
+  }
+}
+
+async function waitForWebSocketDrain(
+  socket: WebSocketLike,
+  deadline: number,
+): Promise<void> {
+  while (socket.bufferedAmount > 0) {
+    if (socket.readyState !== WEB_SOCKET_OPEN) {
+      throw new Error("WebSocket closed while a message was backpressured");
+    }
+    if (Date.now() >= deadline) {
+      throw new Error("WebSocket send buffer drain deadline was exceeded");
+    }
+    await new Promise((resolve) => setTimeout(resolve, 4));
+  }
+}
+
+function isValidId(value: unknown): value is JsonRpcId {
+  return (
+    (typeof value === "number" && Number.isSafeInteger(value) && value >= 0) ||
+    (typeof value === "string" && value.length > 0)
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function hasOnlyKeys(
+  record: Record<string, unknown>,
+  keys: readonly string[],
+): boolean {
+  const actual = Object.keys(record);
+  return actual.length === keys.length && actual.every((key) => keys.includes(key));
+}
+
+function hasOwn(record: Record<string, unknown>, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(record, key);
+}
+
+function messageBytes(message: string): number {
+  return UTF8.encode(message).byteLength;
+}
diff --git a/src/crates/adapters/transport/typescript/test/json-rpc-peer.test.ts b/src/crates/adapters/transport/typescript/test/json-rpc-peer.test.ts
new file mode 100644
index 0000000000..4692637c66
--- /dev/null
+++ b/src/crates/adapters/transport/typescript/test/json-rpc-peer.test.ts
@@ -0,0 +1,396 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  JsonRpcLimitError,
+  JsonRpcPeer,
+  JsonRpcProtocolError,
+  JsonRpcRemoteError,
+  JsonRpcTimeoutError,
+  type MessageTransport,
+  type MessageTransportObserver,
+} from "../src/index.js";
+
+test("correlates one strict JSON-RPC response with its request", async () => {
+  const transport = new TestMessageTransport();
+  const peer = createPeer(transport);
+
+  const response = peer.request("example/read", { value: 7 });
+  assert.deepEqual(JSON.parse(transport.sent[0] ?? ""), {
+    jsonrpc: "2.0",
+    id: 1,
+    method: "example/read",
+    params: { value: 7 },
+  });
+
+  transport.receive({ jsonrpc: "2.0", id: 1, result: { accepted: true } });
+  assert.deepEqual(await response, { accepted: true });
+});
+
+test("rejects an ambiguous response envelope and fails every pending request", async () => {
+  const transport = new TestMessageTransport();
+  const peer = createPeer(transport);
+  const first = peer.request("example/first", {});
+  const second = peer.request("example/second", {});
+
+  transport.receive({
+    jsonrpc: "2.0",
+    id: 1,
+    result: null,
+    error: { code: -32000, message: "ambiguous" },
+  });
+
+  await assert.rejects(first, JsonRpcProtocolError);
+  await assert.rejects(second, JsonRpcProtocolError);
+  assert.equal(transport.closeCalls, 1);
+});
+
+test("projects a strict remote error without inventing application policy", async () => {
+  const transport = new TestMessageTransport();
+  const peer = createPeer(transport);
+  const response = peer.request("example/fail", {});
+
+  transport.receive({
+    jsonrpc: "2.0",
+    id: 1,
+    error: { code: -32001, message: "denied", data: { reason: "policy" } },
+  });
+
+  await assert.rejects(response, (error: unknown) => {
+    assert.ok(error instanceof JsonRpcRemoteError);
+    assert.equal(error.code, -32001);
+    assert.deepEqual(error.data, { reason: "policy" });
+    return true;
+  });
+});
+
+test("a request deadline clears only that request and leaves the carrier reusable", async () => {
+  const transport = new TestMessageTransport();
+  const peer = createPeer(transport, { requestTimeoutMs: 15 });
+  const first = peer.request("example/slow", {});
+
+  await assert.rejects(first, JsonRpcTimeoutError);
+  assert.equal(transport.closeCalls, 0);
+
+  const second = peer.request("example/next", {});
+  transport.receive({ jsonrpc: "2.0", id: 2, result: "ready" });
+  assert.equal(await second, "ready");
+});
+
+test("ignores one late response for a timed-out request id", async () => {
+  const transport = new TestMessageTransport();
+  const peer = createPeer(transport, { requestTimeoutMs: 15 });
+  const expired = peer.request("example/slow", {});
+  await assert.rejects(expired, JsonRpcTimeoutError);
+
+  transport.receive({ jsonrpc: "2.0", id: 1, result: "late" });
+  const next = peer.request("example/next", {});
+  transport.receive({ jsonrpc: "2.0", id: 2, result: "current" });
+
+  assert.equal(await next, "current");
+  assert.equal(transport.closeCalls, 0);
+});
+
+test("rejects an id generator that reuses a tombstoned request id", async () => {
+  const transport = new TestMessageTransport();
+  const peer = new JsonRpcPeer(transport, {
+    createRequestId: () => 1,
+    requestTimeoutMs: 15,
+    limits: {
+      maxMessageBytes: 1_024,
+      maxPendingRequests: 8,
+      maxPendingBytes: 4_096,
+      maxOutboundBytes: 4_096,
+    },
+  });
+  await assert.rejects(peer.request("example/slow", {}), JsonRpcTimeoutError);
+
+  await assert.rejects(
+    peer.request("example/reused", {}),
+    /request id must be unique/,
+  );
+});
+
+test("fails closed instead of evicting an unresolved timeout tombstone", async () => {
+  const transport = new TestMessageTransport();
+  let nextId = 1;
+  const peer = new JsonRpcPeer(transport, {
+    createRequestId: () => nextId++,
+    requestTimeoutMs: 15,
+    limits: {
+      maxMessageBytes: 1_024,
+      maxPendingRequests: 1,
+      maxPendingBytes: 4_096,
+      maxOutboundBytes: 4_096,
+    },
+  });
+  await assert.rejects(peer.request("example/first", {}), JsonRpcTimeoutError);
+
+  await assert.rejects(peer.request("example/second", {}), JsonRpcProtocolError);
+  assert.equal(transport.closeCalls, 1);
+});
+
+test("rejects a request before send when the pending count is exhausted", async () => {
+  const transport = new TestMessageTransport();
+  const peer = createPeer(transport, { maxPendingRequests: 1 });
+  const first = peer.request("example/first", {});
+
+  await assert.rejects(
+    peer.request("example/second", {}),
+    (error: unknown) => isLimit(error, "pending_count"),
+  );
+  assert.equal(transport.sent.length, 1);
+
+  transport.receive({ jsonrpc: "2.0", id: 1, result: null });
+  await first;
+});
+
+test("rejects a request before send when retained pending bytes are exhausted", async () => {
+  const transport = new TestMessageTransport();
+  const peer = createPeer(transport, { maxPendingBytes: 100 });
+  const first = peer.request("example/first", { value: "x".repeat(20) });
+
+  await assert.rejects(
+    peer.request("example/second", { value: "x".repeat(20) }),
+    (error: unknown) => isLimit(error, "pending_bytes"),
+  );
+  assert.equal(transport.sent.length, 1);
+
+  transport.receive({ jsonrpc: "2.0", id: 1, result: null });
+  await first;
+});
+
+test("bounds bytes waiting on a backpressured carrier", async () => {
+  const transport = new TestMessageTransport();
+  transport.blockSends();
+  const peer = createPeer(transport, {
+    maxOutboundBytes: 100,
+    maxPendingBytes: 1_000,
+  });
+  const first = peer.request("example/first", { value: "x".repeat(20) });
+
+  await assert.rejects(
+    peer.request("example/second", { value: "x".repeat(20) }),
+    (error: unknown) => isLimit(error, "outbound_bytes"),
+  );
+  assert.equal(transport.sent.length, 1);
+
+  transport.releaseSends();
+  transport.receive({ jsonrpc: "2.0", id: 1, result: null });
+  await first;
+});
+
+test("fails closed when an inbound carrier message exceeds its byte budget", async () => {
+  const transport = new TestMessageTransport();
+  const peer = createPeer(transport, { maxMessageBytes: 64 });
+  const response = peer.request("example/read", {});
+
+  transport.receiveRaw(JSON.stringify({
+    jsonrpc: "2.0",
+    id: 1,
+    result: "x".repeat(80),
+  }));
+
+  await assert.rejects(response, JsonRpcProtocolError);
+  assert.equal(transport.closeCalls, 1);
+});
+
+test("delivers strict notifications without owning their application fanout", async () => {
+  const transport = new TestMessageTransport();
+  const peer = createPeer(transport);
+  const notifications: Array<{ method: string; params: unknown }> = [];
+  peer.onNotification((notification) => notifications.push(notification));
+
+  transport.receive({
+    jsonrpc: "2.0",
+    method: "example/event",
+    params: { sequence: 1 },
+  });
+
+  assert.deepEqual(notifications, [
+    { method: "example/event", params: { sequence: 1 } },
+  ]);
+});
+
+test("isolates an application notification listener failure from the wire peer", async () => {
+  const transport = new TestMessageTransport();
+  const notificationErrors: Error[] = [];
+  const peer = createPeer(transport, { notificationErrors });
+  peer.onNotification(() => {
+    throw new Error("consumer failed");
+  });
+
+  transport.receive({
+    jsonrpc: "2.0",
+    method: "example/event",
+    params: { sequence: 1 },
+  });
+  const response = peer.request("example/next", {});
+  transport.receive({ jsonrpc: "2.0", id: 1, result: "ready" });
+
+  assert.equal(await response, "ready");
+  assert.equal(notificationErrors[0]?.message, "consumer failed");
+  assert.equal(transport.closeCalls, 0);
+});
+
+test("a malformed remote error rejects the correlated request as a protocol failure", async () => {
+  const transport = new TestMessageTransport();
+  const peer = createPeer(transport);
+  const response = peer.request("example/fail", {});
+
+  transport.receive({
+    jsonrpc: "2.0",
+    id: 1,
+    error: { code: "not-an-integer", message: "invalid" },
+  });
+
+  await assert.rejects(response, JsonRpcProtocolError);
+  assert.equal(transport.closeCalls, 1);
+});
+
+test("graceful close rejects pending requests and closes the carrier exactly once", async () => {
+  const transport = new TestMessageTransport();
+  const peer = createPeer(transport);
+  const pending = peer.request("example/pending", {});
+
+  await Promise.all([peer.close(), peer.close()]);
+
+  await assert.rejects(pending, /JSON-RPC peer closed/);
+  assert.equal(transport.closeCalls, 1);
+});
+
+test("a failure listener cannot prevent pending cleanup or carrier close", async () => {
+  const transport = new TestMessageTransport();
+  const peer = createPeer(transport);
+  peer.onFailure(() => {
+    throw new Error("diagnostic listener failed");
+  });
+  const pending = peer.request("example/pending", {});
+
+  assert.doesNotThrow(() => transport.end(new Error("carrier lost")));
+
+  await assert.rejects(pending, /carrier closed/);
+  await peer.close();
+  assert.equal(transport.closeCalls, 1);
+});
+
+test("a carrier that closes during subscription is reclaimed without a constructor race", async () => {
+  const transport = new SynchronouslyClosingTransport();
+  const peer = new JsonRpcPeer(transport, {
+    createRequestId: () => 1,
+    requestTimeoutMs: 1_000,
+    limits: {
+      maxMessageBytes: 1_024,
+      maxPendingRequests: 8,
+      maxPendingBytes: 4_096,
+      maxOutboundBytes: 4_096,
+    },
+  });
+
+  await assert.rejects(peer.request("example/read", {}), /carrier closed/);
+  await peer.close();
+  assert.equal(transport.unsubscribeCalls, 1);
+  assert.equal(transport.closeCalls, 1);
+});
+
+interface PeerOverrides {
+  requestTimeoutMs?: number;
+  maxMessageBytes?: number;
+  maxPendingRequests?: number;
+  maxPendingBytes?: number;
+  maxOutboundBytes?: number;
+  notificationErrors?: Error[];
+}
+
+function createPeer(
+  transport: TestMessageTransport,
+  overrides: PeerOverrides = {},
+): JsonRpcPeer {
+  let nextId = 1;
+  return new JsonRpcPeer(transport, {
+    createRequestId: () => nextId++,
+    requestTimeoutMs: overrides.requestTimeoutMs ?? 1_000,
+    limits: {
+      maxMessageBytes: overrides.maxMessageBytes ?? 1_024,
+      maxPendingRequests: overrides.maxPendingRequests ?? 8,
+      maxPendingBytes: overrides.maxPendingBytes ?? 4_096,
+      maxOutboundBytes: overrides.maxOutboundBytes ?? 4_096,
+    },
+    onNotificationError: (error) => overrides.notificationErrors?.push(error),
+  });
+}
+
+function isLimit(error: unknown, limit: JsonRpcLimitError["limit"]): boolean {
+  assert.ok(error instanceof JsonRpcLimitError);
+  assert.equal(error.limit, limit);
+  return true;
+}
+
+class TestMessageTransport implements MessageTransport {
+  readonly sent: string[] = [];
+  closeCalls = 0;
+  #observer?: MessageTransportObserver;
+  #sendGate?: Promise<void>;
+  #releaseSend?: () => void;
+
+  subscribe(observer: MessageTransportObserver): () => void {
+    assert.equal(this.#observer, undefined);
+    this.#observer = observer;
+    return () => {
+      if (this.#observer === observer) {
+        this.#observer = undefined;
+      }
+    };
+  }
+
+  async send(message: string): Promise<void> {
+    this.sent.push(message);
+    await this.#sendGate;
+  }
+
+  async close(): Promise<void> {
+    this.closeCalls += 1;
+  }
+
+  receive(value: unknown): void {
+    this.receiveRaw(JSON.stringify(value));
+  }
+
+  receiveRaw(message: string): void {
+    this.#observer?.message(message);
+  }
+
+  end(cause?: unknown): void {
+    this.#observer?.close(cause);
+  }
+
+  blockSends(): void {
+    this.#sendGate = new Promise((resolve) => {
+      this.#releaseSend = resolve;
+    });
+  }
+
+  releaseSends(): void {
+    this.#releaseSend?.();
+    this.#releaseSend = undefined;
+    this.#sendGate = undefined;
+  }
+}
+
+class SynchronouslyClosingTransport implements MessageTransport {
+  unsubscribeCalls = 0;
+  closeCalls = 0;
+
+  subscribe(observer: MessageTransportObserver): () => void {
+    observer.close(new Error("already closed"));
+    return () => {
+      this.unsubscribeCalls += 1;
+    };
+  }
+
+  async send(): Promise<void> {}
+
+  async close(): Promise<void> {
+    this.closeCalls += 1;
+  }
+}
diff --git a/src/crates/adapters/transport/typescript/test/websocket-message-transport.test.ts b/src/crates/adapters/transport/typescript/test/websocket-message-transport.test.ts
new file mode 100644
index 0000000000..e199bd41f2
--- /dev/null
+++ b/src/crates/adapters/transport/typescript/test/websocket-message-transport.test.ts
@@ -0,0 +1,83 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  WebSocketMessageTransport,
+  type WebSocketLike,
+} from "../src/index.js";
+
+test("WebSocket transport rejects before the browser buffer exceeds its cap", async () => {
+  const socket = new TestWebSocket();
+  socket.bufferedAmount = 10;
+  const transport = createTransport(socket, { maxBufferedBytes: 10 });
+
+  await assert.rejects(
+    transport.send("x"),
+    /send buffer capacity was exceeded/,
+  );
+  assert.deepEqual(socket.sent, []);
+});
+
+test("WebSocket transport bounds a send whose browser buffer never drains", async () => {
+  const socket = new TestWebSocket();
+  socket.bufferedAmount = 1;
+  const transport = createTransport(socket, { drainTimeoutMs: 5 });
+
+  await assert.rejects(
+    transport.send("message"),
+    /drain deadline was exceeded/,
+  );
+  assert.deepEqual(socket.sent, ["message"]);
+});
+
+test("WebSocket transport projects messages and carrier close exactly once", async () => {
+  const socket = new TestWebSocket();
+  const transport = createTransport(socket);
+  const messages: string[] = [];
+  const closes: unknown[] = [];
+  transport.subscribe({
+    message: (message) => messages.push(message),
+    close: (cause) => closes.push(cause),
+  });
+
+  transport.receive("one");
+  const cause = new Error("closed");
+  socket.readyState = 3;
+  transport.carrierClosed(cause);
+  transport.carrierClosed(new Error("duplicate"));
+  transport.receive("late");
+  await Promise.all([transport.close(), transport.close()]);
+
+  assert.deepEqual(messages, ["one"]);
+  assert.deepEqual(closes, [cause]);
+  assert.equal(socket.closeCalls, 0);
+});
+
+function createTransport(
+  socket: TestWebSocket,
+  overrides: Partial<{
+    maxBufferedBytes: number;
+    drainTimeoutMs: number;
+  }> = {},
+): WebSocketMessageTransport {
+  return new WebSocketMessageTransport(socket, {
+    maxBufferedBytes: overrides.maxBufferedBytes ?? 1_024,
+    drainTimeoutMs: overrides.drainTimeoutMs ?? 100,
+  });
+}
+
+class TestWebSocket implements WebSocketLike {
+  readyState = 1;
+  bufferedAmount = 0;
+  readonly sent: string[] = [];
+  closeCalls = 0;
+
+  send(message: string): void {
+    this.sent.push(message);
+  }
+
+  close(): void {
+    this.closeCalls += 1;
+    this.readyState = 3;
+  }
+}
diff --git a/src/crates/adapters/transport/typescript/tsconfig.json b/src/crates/adapters/transport/typescript/tsconfig.json
new file mode 100644
index 0000000000..bcf9e1744f
--- /dev/null
+++ b/src/crates/adapters/transport/typescript/tsconfig.json
@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ES2022",
+    "moduleResolution": "Bundler",
+    "rootDir": ".",
+    "outDir": "dist",
+    "declaration": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noFallthroughCasesInSwitch": true,
+    "noEmitOnError": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true,
+    "typeRoots": [
+      "../../../../../sdk/typescript/node_modules/@types"
+    ]
+  },
+  "include": [
+    "src/**/*.ts",
+    "test/**/*.ts"
+  ]
+}
diff --git a/src/crates/adapters/webdriver/Cargo.toml b/src/crates/adapters/webdriver/Cargo.toml
index ae93483d95..ee7deab76f 100644
--- a/src/crates/adapters/webdriver/Cargo.toml
+++ b/src/crates/adapters/webdriver/Cargo.toml
@@ -24,9 +24,9 @@ image = { workspace = true }
 [target.'cfg(target_os = "macos")'.dependencies]
 block2 = { workspace = true }
 objc2 = { workspace = true }
-objc2-app-kit = { workspace = true, features = ["NSImage", "NSImageRep", "NSBitmapImageRep"] }
-objc2-foundation = { workspace = true, features = ["NSString", "NSData", "NSError", "NSDictionary"] }
-objc2-web-kit = { workspace = true }
+objc2-app-kit = { workspace = true, features = ["std", "NSImage", "NSImageRep", "NSBitmapImageRep"] }
+objc2-foundation = { workspace = true, features = ["std", "NSString", "NSData", "NSError", "NSDictionary"] }
+objc2-web-kit = { workspace = true, features = ["std", "WKContentWorld", "WKWebView", "WKSnapshotConfiguration", "WKPDFConfiguration", "block2", "objc2-app-kit"] }
 
 [target.'cfg(target_os = "windows")'.dependencies]
 tempfile = { workspace = true }
diff --git a/src/crates/assembly/agent-content/prompts/agents/agentic_mode.md b/src/crates/assembly/agent-content/prompts/agents/agentic_mode.md
index 8311e884d8..d0d3ba88c3 100644
--- a/src/crates/assembly/agent-content/prompts/agents/agentic_mode.md
+++ b/src/crates/assembly/agent-content/prompts/agents/agentic_mode.md
@@ -91,7 +91,7 @@ The user will primarily request you perform software engineering tasks. This inc
 - When the user explicitly asks to complete work and review it carefully, finish the implementation first, then dispatch one independent read-only `CodeReview` Task. Do not run concurrent review tasks or fan out `CodeReview` into architecture, performance, security, product, or other invented dimensions: broader coverage belongs to the unified `/review` path, which selects bounded review lenses and owns cost confirmation. Do not launch review by default for every task.
 - Treat reviewer output as adversarial evidence. The reviewer never fixes its own findings. Apply accepted fixes in the implementation agent. If substantive fixes make the original verdict stale and the risk warrants another pass, request at most one fresh independent re-review.
 - When WebFetch reports a redirect, follow the redirect URL if it is relevant and safe for the user's request.
-- For browser and web-page work, route in this order: (0) only opening or showing a URL for the user, with no page reading or interaction: use `ControlHub` with `domain: "browser"`, `action: "open_builtin"`; (1) reading page content that does not require the user's login state: use WebFetch; (2) pages that require the user's login state or JavaScript interaction: use `ControlHub` with `domain: "browser"` (connect, snapshot, then act through `@eN` refs) — `connect` drives BitFun's managed browser profile, which is separate from the user's everyday browser; it persists cookies and logins across runs, so if the page shows a login wall, ask the user to sign in once in that window instead of retrying navigation or entering credentials yourself; (3) non-Chromium browsers (Firefox/Safari) or native desktop apps, including Electron apps: use `ComputerUse` desktop actions only when `ComputerUse` appears in your current tool list; if it does not, tell the user the task needs the Computer Use mode (enabled via the Computer use setting) instead of guessing another path or calling an unavailable tool. `ControlHub` covers ordinary web pages. For a browser-only workflow that `ControlHub` explicitly cannot support, such as a compatible cloud-browser workflow, load `agent-browser` via `Skill(skill="agent-browser")` only when that skill is available; do not use it as a substitute for `ComputerUse` on native desktop apps.
+- For browser and web-page work, route in this order: (0) only opening or showing a URL for the user, with no page reading or interaction: use `ControlHub` with `domain: "browser"`, `action: "open_builtin"`; (1) reading page content that does not require the user's login state: use WebFetch; (2) pages that require the user's login state or JavaScript interaction: use `ControlHub` with `domain: "browser"` (connect, snapshot, then act through `@eN` refs) — Chrome 144+ and Edge request access to the currently running real profile, preserving tabs and login state after the user clicks **Enable default CDP** in BitFun Settings > Browser control, enables Remote debugging in the browser-owned page, and approves BitFun; other supported Chromium browsers reuse a real-profile endpoint when available and otherwise use BitFun's persistent managed profile; (3) non-Chromium browsers (Firefox/Safari) or native desktop apps, including Electron apps: use `ComputerUse` desktop actions only when `ComputerUse` appears in your current tool list; if it does not, tell the user the task needs the Computer Use mode (enabled via the Computer use setting) instead of guessing another path or calling an unavailable tool. `ControlHub` covers ordinary web pages. For a browser-only workflow that `ControlHub` explicitly cannot support, such as a compatible cloud-browser workflow, load `agent-browser` via `Skill(skill="agent-browser")` only when that skill is available; do not use it as a substitute for `ComputerUse` on native desktop apps.
 - When multiple tool calls are independent, run them in parallel. Keep dependent operations sequential, and never use placeholders or guess missing parameters.
 - Use specialized tools for file reads, edits, searches, and deletions because they preserve workspace context and permissions. Use ExecCommand for commands that genuinely need a shell. Do not use shell commands only to communicate with the user.
 - For security-sensitive tasks, support defensive analysis and remediation only. Refuse malicious code, exploit workflows, credential harvesting, or instructions that would facilitate abuse.
diff --git a/src/crates/assembly/agent-content/prompts/agents/claw_mode.md b/src/crates/assembly/agent-content/prompts/agents/claw_mode.md
index 18eba15511..22f68f9ad3 100644
--- a/src/crates/assembly/agent-content/prompts/agents/claw_mode.md
+++ b/src/crates/assembly/agent-content/prompts/agents/claw_mode.md
@@ -16,7 +16,7 @@ When a first-class tool exists for an action, use the tool directly instead of a
 
 Use `ControlHub` for browser automation, terminal signalling, and routing/capability introspection only when it appears in your current tool list:
 
-- `domain: "browser"` for websites and web apps in BitFun's managed browser profile through CDP.
+- `domain: "browser"` for websites and web apps through CDP. Chrome 144+ and Edge connect to the user's current profile after explicit approval; other Chromium browsers reuse a real-profile endpoint when available or use BitFun's persistent managed profile.
 - `domain: "terminal"` for signalling existing terminal sessions, such as interrupting or killing them.
 - `domain: "meta"` for capability and route checks.
 
@@ -24,7 +24,7 @@ For browser and web-page work, route in this order:
 
 1. Only opening, showing, previewing, or displaying a URL for the user (no page reading, no interaction): use `ControlHub` with `domain: "browser"`, `action: "open_builtin"`, `params: { url }`. The page renders in BitFun's built-in right-side browser panel. Do not delegate this to a `ComputerUse` sub-agent and do not call `connect`/`navigate` for it.
 2. Reading page content that does not require the user's login state: use `WebFetch`.
-3. Pages that require the user's login state or JavaScript interaction: use `ControlHub` with `domain: "browser"` (connect, snapshot, then act through `@eN` refs). `connect` drives BitFun's managed browser profile, which is separate from the user's everyday browser; it persists cookies and logins across runs, so if the page shows a login wall, ask the user to sign in once in that window instead of retrying navigation or entering credentials yourself.
+3. Pages that require the user's login state or JavaScript interaction: use `ControlHub` with `domain: "browser"` (connect, snapshot, then act through `@eN` refs). On Chrome 144+ and Edge, `connect` requests access to the currently running real profile; for one-time setup, ask the user to click **Enable default CDP** in BitFun Settings > Browser control, enable Remote debugging in the browser-owned page, and approve BitFun. Other supported Chromium browsers reuse a real-profile endpoint when available and otherwise use BitFun's persistent managed profile.
 4. Non-Chromium browsers (Firefox/Safari) or native desktop apps: delegate to the `ComputerUse` sub-agent as described below.
 
 Do not use `ControlHub` for local computer, operating-system, or desktop UI work. Desktop and system actions have moved to the dedicated `ComputerUse` tool/agent. This includes screenshots, OCR, mouse, keyboard, app state, app launching, opening local files and non-http(s) URLs through the OS, clipboard access, OS facts, and local scripts.
diff --git a/src/crates/assembly/agent-content/prompts/agents/computer_use_mode.md b/src/crates/assembly/agent-content/prompts/agents/computer_use_mode.md
index 08f92ba671..8ccde914e3 100644
--- a/src/crates/assembly/agent-content/prompts/agents/computer_use_mode.md
+++ b/src/crates/assembly/agent-content/prompts/agents/computer_use_mode.md
@@ -18,7 +18,7 @@ Work in a tight observe -> act -> verify loop. Before acting on a desktop UI, ob
 
 Prefer the smallest reliable control surface:
 
-1. When `ControlHub` appears in your current tool list, use it with `domain: "browser"` for websites and web apps in BitFun's managed browser profile.
+1. When `ControlHub` appears in your current tool list, use it with `domain: "browser"` for websites and web apps. Chrome 144+ and Edge can connect to the current real profile after explicit approval; other Chromium browsers reuse a real-profile endpoint when available or use BitFun's persistent managed profile.
 2. Use `ComputerUse` for third-party desktop apps, OS dialogs, system-wide keyboard and mouse, accessibility, OCR, screenshots, app state, app/file opening, clipboard access, OS facts, and local scripts. Use it for URL opening only when the page must land in the system default browser; for display-only http(s) URLs prefer `ControlHub` `browser.open_builtin`.
 3. Use `ExecCommand` for local shell commands when that is the clearest path and does not bypass desktop safety expectations.
 4. When available, use `ControlHub` with `domain: "meta"` to inspect non-desktop control capabilities before long or uncertain automation flows.
@@ -60,6 +60,8 @@ If the same GUI tactic fails twice, switch strategy: use keyboard navigation, ap
 When Runtime Context indicates the primary model does not support image understanding, the vision-only actions — `screenshot`, `build_interactive_view`, `interactive_click`, `build_visual_mark_view`, `visual_click` — are unavailable: they are absent from your tool schema, `screenshot` returns no image (`screenshot_unavailable: true`), and the other four return NOT_AVAILABLE. Do NOT retry them and do NOT call them to verify — they cannot help you see. Instead:
 
 - **Observe with `describe_screen`** — it returns a text snapshot (frontmost app, `ax_tree_text` with `node_idx`s, `ui_tree_text`, pointer, displays) with no image. This is your eyes. Call it before acting when state is unknown, and after an action to verify `ax_state_digest` changed.
+- **An empty `ax_tree_text` is an answer, not a truncated result.** The same result carries `ax_tree_status` and `ax_tree_note` explaining why it is empty — no frontmost app, an app running with no window, a WebView that exposes no tree, or a missing Accessibility permission — and which tactic to switch to. Calling `describe_screen` again returns exactly the same thing. Never conclude your tool output is being cut off; act on the note instead.
+- **Do not build your own eyes out of `screencapture`.** Shelling out to capture the screen and passing the file to an image-analysis tool costs an extra model round-trip per glance, returns prose rather than clickable coordinates, and misreads the screen often enough to send you down false paths. `describe_screen`, `get_app_state`, `locate` and `move_to_text` return exact targets — use them.
 - **Target with AX / OCR, never guessed coordinates** — `click_element`/`app_click` with `node_idx`/`text_contains`/`title_contains`/`role_substring`; `move_to_text`/`click_target` with `target_text` (+ `move_to_text_match_index` when several OCR hits are returned as text candidates).
 - **Prefer keyboard** — `key_chord` shortcuts (command+F search, Tab/Shift+Tab focus, Return confirm, Escape cancel) and `paste` (clipboard) for CJK / long text before `type_text`.
 - **Drive hard-to-reach apps directly** — `run_apple_script` (macOS) for messaging/desktop apps whose AX tree is sparse.
@@ -71,7 +73,7 @@ For websites and web apps, route in this order:
 
 1. Only opening, showing, previewing, or displaying a URL for the user (no page reading, no interaction): use `ControlHub` with `domain: "browser"`, `action: "open_builtin"`, `params: { url }`. The page renders in BitFun's built-in right-side browser panel. Do not call `connect`/`navigate` for this.
 2. Reading page content that does not require the user's login state: use `WebFetch` when it is available.
-3. Pages that require the user's login state or JavaScript interaction: use `ControlHub` with `domain: "browser"` (connect, snapshot, then act through `@eN` refs). `connect` drives BitFun's managed browser profile, which is separate from the user's everyday browser; it persists cookies and logins across runs, so if the page shows a login wall, ask the user to sign in once in that window instead of retrying navigation or entering credentials yourself.
+3. Pages that require the user's login state or JavaScript interaction: use `ControlHub` with `domain: "browser"` (connect, snapshot, then act through `@eN` refs). On Chrome 144+ and Edge, ask the user to click **Enable default CDP** in BitFun Settings > Browser control, enable Remote debugging in the browser-owned page, and approve BitFun if prompted; this preserves the current profile's tabs and login state. Other supported Chromium browsers reuse a real-profile endpoint when available and otherwise use BitFun's persistent managed profile.
 4. Non-Chromium browsers (Firefox/Safari) or native desktop apps: use `ComputerUse` desktop actions.
 
 If `ControlHub` is unavailable, do not claim browser-domain automation; use `ComputerUse` only for browser chrome or OS-level interaction that it can actually observe and verify.
diff --git a/src/crates/assembly/agent-content/prompts/agents/cowork_mode.md b/src/crates/assembly/agent-content/prompts/agents/cowork_mode.md
index f520468517..fe25b81ca8 100644
--- a/src/crates/assembly/agent-content/prompts/agents/cowork_mode.md
+++ b/src/crates/assembly/agent-content/prompts/agents/cowork_mode.md
@@ -76,7 +76,7 @@ For browser and web-page work, route in this order:
 
 1. Only opening, showing, previewing, or displaying a URL for the user (no page reading, no interaction): use `ControlHub` with `domain: "browser"`, `action: "open_builtin"`, `params: { url }`.
 2. Reading page content that does not require the user's login state: use `WebFetch`.
-3. Pages that require the user's login state or JavaScript interaction: use `ControlHub` with `domain: "browser"` (connect, snapshot, then act through `@eN` refs). `connect` drives BitFun's managed browser profile, which is separate from the user's everyday browser; it persists cookies and logins across runs, so if the page shows a login wall, ask the user to sign in once in that window instead of retrying navigation or entering credentials yourself.
+3. Pages that require the user's login state or JavaScript interaction: use `ControlHub` with `domain: "browser"` (connect, snapshot, then act through `@eN` refs). On Chrome 144+ and Edge, ask the user to click **Enable default CDP** in BitFun Settings > Browser control, enable Remote debugging in the browser-owned page, and approve BitFun if prompted; this preserves the current profile's tabs and login state. Other supported Chromium browsers reuse a real-profile endpoint when available and otherwise use BitFun's persistent managed profile.
 4. Non-Chromium browsers (Firefox/Safari) or native desktop apps: Cowork cannot drive these — explain the limitation and suggest Computer Use mode instead.
 
 Do not use `ControlHub` for local computer, operating-system, or desktop UI work, and do not substitute a browser-automation skill for it.
diff --git a/src/crates/assembly/core/AGENTS-CN.md b/src/crates/assembly/core/AGENTS-CN.md
index d9c9eab93c..1447c28504 100644
--- a/src/crates/assembly/core/AGENTS-CN.md
+++ b/src/crates/assembly/core/AGENTS-CN.md
@@ -50,9 +50,11 @@ SessionManager -> Session -> DialogTurn -> ModelRound
 - Remote/service 改动必须保持 external protocol lifecycle、workspace projection、scheduler/session restore、
   terminal pre-warm 和 product execution 边界清晰。
 - Feature 改动必须保持 `product-full` 作为兼容产品组装边界；默认能力选择只有在单独的 product matrix review 后才能变化。
-- `agent-runtime` 负责现有 Core Agent Runtime 兼容 facade，包括 MCP、Remote Connect、
-  workspace-search 与原生 Hook runtime service；`external-sources` 增加第三方发现/导入 adapter，
-  `plugin-runtime` 增加可执行 plugin client wiring，`debug-log` 单独控制调试日志服务。它们都不得启用 `product-full`。
+- `agent-runtime` 只负责 Core Agent 生命周期基线、原生 Hook runtime、基础文件/进程工具和
+  Agent-control 工具。`mcp-runtime`、`remote-connect`、`workspace-search` 等具体网络或产品能力
+  保持独立 owner；`external-sources` 增加第三方发现/导入 adapter，`plugin-runtime` 增加可执行
+  plugin client wiring，`debug-log` 单独控制调试日志服务。不得把这些能力藏回 `agent-runtime`，
+  它们也都不得启用 `product-full`。
 - CLI/ACP 的闭包检查遵循 Cargo resolver-v2，保持 normal 与 host（build/proc-macro）feature context 相互隔离；
   但同一 context 内的所有 target-specific 声明都属于同一个已评审架构边界。平台确实需要不同 owner 时，应拆分清晰的
   package/module 归属；不得用互斥 Cargo `cfg` 隐藏未评审的 Core 能力。
@@ -63,6 +65,21 @@ SessionManager -> Session -> DialogTurn -> ModelRound
 - `product-full` 必须显式组合自身消费的每个能力，包括 `permission`、`session-git`、
   `runtime-ownership` 等产品专属 `services-core` feature。不得把这些 feature 写在依赖声明上，
   否则 Cargo feature union 会迫使所有 core consumer 编译它们。
+- Core 的默认 feature 集合为空。`product-full` 是由真实产品入口显式选择的兼容组装，不能再作为
+  library 的隐式默认值。能力内部使用的工具依赖必须保持 optional 并由 owner feature 激活；
+  `base64`、`futures`、`regex`、`tokio-util` 与 `bitfun-agent-tools` 分别归实际使用它们的
+  Agent Runtime、local-storage、dispatch-store 或 debug-log 闭包。Core 的 feature-free 直接 Tokio
+  依赖只保留 config 与 app-path 状态所需的文件系统和同步能力；被显式选择的 Services Core
+  `json-io` owner 另外持有受限原子 JSON 写入所需的 runtime/time capability。
+- 后端 Fluent bundle 与可变翻译状态归 `i18n-runtime`；locale id、别名、fallback、metadata 与
+  面向模型的语言文案仍是 feature-free 契约。调用 `I18nService` 的 host 必须显式选择
+  `i18n-runtime`。
+- 可复用诊断脱敏和本地 Diff 实现分别通过精确的 `diagnostics`、`diff` feature 保留兼容 facade。
+  Agent Runtime 为受限异步 workspace 读取选择 `bitfun-services-core/workspace-text-runtime`；
+  contract-only consumer 使用同步路径规范化时不需要 Tokio。
+- 平台 transport emitter 属于 host adapter。Desktop 直接导入
+  `bitfun_transport::TransportEmitter`；Core 只暴露稳定的
+  `bitfun_events::EventEmitter` 契约，不得重新导出 host adapter。
 - 保持 `cargo check -p bitfun-core --no-default-features` 可用。产品专属模块必须由 owner feature 控制；轻量 facade
   操作在缺少产品 owner 时若无法安全完成，应明确 fail-closed 并保留持久化恢复状态，不得隐式启用 `product-full`。
 
diff --git a/src/crates/assembly/core/AGENTS.md b/src/crates/assembly/core/AGENTS.md
index 8f71839dc9..d4f93ef57b 100644
--- a/src/crates/assembly/core/AGENTS.md
+++ b/src/crates/assembly/core/AGENTS.md
@@ -90,8 +90,10 @@ SessionManager -> Session -> DialogTurn -> ModelRound
   `mcp-runtime` layers the Core MCP tool bridge on the Agent lifecycle; and
   `remote-connect` layers its phone relay on the Agent lifecycle and model
   catalog. None of these relationships may be hidden in the `agent-runtime`
-  baseline. `scheduled-jobs` is only the additive dependency/source modifier
-  used with that baseline; it is not a standalone service profile.
+  baseline. `scheduled-jobs`, `document-read`, and `subscription-auth` are
+  additive dependency/source modifiers, not standalone runtime profiles. The
+  latter two use Cargo weak dependency forwarding so they refine an already
+  selected tool or adapter owner without activating that owner by themselves.
   Product-owned managed worktree lifecycle is available only when the Agent
   lifecycle and Git service owners are both selected; it is not a tool-pack owner.
   Function Agent adapters use the independent `function-agents` owner;
@@ -122,6 +124,28 @@ SessionManager -> Session -> DialogTurn -> ModelRound
   `runtime-ownership`, every concrete service owner, and every `tools-*` group.
   Do not put those features on the dependency declaration, because Cargo
   feature union would force them into every core consumer.
+- Core's default feature set is empty. `product-full` is an explicit
+  compatibility assembly selected by real product entrypoints, never the
+  library's implicit default. Capability-local utility dependencies remain
+  optional and are activated by their owner features; in particular,
+  `base64`, `futures`, `regex`, `tokio-util`, and `bitfun-agent-tools` belong to
+  the Agent Runtime, local-storage, dispatch-store, or debug-log closures that
+  use them. Core's direct feature-free Tokio edge keeps only filesystem and
+  synchronization support required by config and app-path state; the selected
+  Services Core `json-io` owner separately carries the runtime/time capabilities
+  required for bounded atomic JSON writes.
+- Backend Fluent bundles and mutable translation state are owned by
+  `i18n-runtime`; locale ids, aliases, fallback facts, metadata, and
+  model-facing language copy remain feature-free contracts. Hosts that call
+  `I18nService` must select `i18n-runtime` explicitly.
+- Reusable diagnostic redaction and local Diff implementations remain
+  compatibility facades under the exact `diagnostics` and `diff` features.
+  Agent Runtime selects `bitfun-services-core/workspace-text-runtime` for
+  bounded asynchronous workspace reads; synchronous path normalization stays
+  available to contract-only consumers without Tokio.
+- Platform transport emitters are host adapters. Desktop imports
+  `bitfun_transport::TransportEmitter` directly; Core exposes only the stable
+  `bitfun_events::EventEmitter` contract and must not re-export a host adapter.
 - Keep `cargo check -p bitfun-core --no-default-features` viable. Gate
   product-only modules at their owner feature; if a light facade operation
   cannot safely complete without a product owner, fail closed and preserve any
diff --git a/src/crates/assembly/core/Cargo.toml b/src/crates/assembly/core/Cargo.toml
index 78d53c2044..3bee81aab4 100644
--- a/src/crates/assembly/core/Cargo.toml
+++ b/src/crates/assembly/core/Cargo.toml
@@ -11,13 +11,14 @@ crate-type = ["rlib"]
 
 [dependencies]
 # Inherit shared dependencies from workspace
-tokio = { workspace = true, features = ["fs", "io-util", "macros", "net", "rt", "sync", "time"] }
+tokio = { workspace = true, features = ["fs", "sync"] }
+tokio-util = { workspace = true, optional = true }
 napi-ohos = { workspace = true }
 napi-derive-ohos = { workspace = true }
 tokio-stream = { workspace = true }
 tokio-util = { workspace = true }
 async-trait = { workspace = true }
-futures = { workspace = true }
+futures = { workspace = true, optional = true }
 
 serde = { workspace = true }
 serde_json = { workspace = true }
@@ -34,8 +35,8 @@ uuid = { workspace = true }
 chrono = { workspace = true }
 chrono-tz = { workspace = true, optional = true }
 cron = { workspace = true, optional = true }
-regex = { workspace = true }
-base64 = { workspace = true }
+regex = { workspace = true, optional = true }
+base64 = { workspace = true, optional = true }
 image = { workspace = true, optional = true }
 md5 = { workspace = true, optional = true }
 hex = { workspace = true }
@@ -65,7 +66,6 @@ include_dir = { workspace = true, optional = true }
 
 # Command detection (cross-platform)
 similar = { workspace = true, optional = true }
-urlencoding = { workspace = true }
 
 # Shared AI protocol adapters
 bitfun-ai-adapters = { path = "../../adapters/ai-adapters", optional = true }
@@ -83,35 +83,35 @@ bitfun-agent-runtime = { path = "../../execution/agent-runtime", optional = true
 bitfun-harness = { path = "../../execution/harness", optional = true }
 
 # Product capability pack contracts
-bitfun-product-capabilities = { path = "../product-capabilities", default-features = false, optional = true }
+bitfun-product-capabilities = { path = "../product-capabilities", optional = true }
 
 # Ecosystem-neutral external source lifecycle coordinator
 bitfun-external-sources = { path = "../external-sources", optional = true }
 
 # Agent tool contracts
-bitfun-agent-tools = { path = "../../execution/tool-contracts" }
+bitfun-agent-tools = { path = "../../execution/tool-contracts", optional = true }
 
 # Tool pack provider plan
-bitfun-tool-packs = { path = "../../execution/tool-provider-groups", default-features = false, optional = true }
+bitfun-tool-packs = { path = "../../execution/tool-provider-groups", optional = true }
 
 # Core service owner crate
-bitfun-services-core = { path = "../../services/services-core", default-features = false, features = ["json-io"] }
+bitfun-services-core = { path = "../../services/services-core", features = ["json-io"] }
 
 # Integration service owner crate
-bitfun-services-integrations = { path = "../../services/services-integrations", default-features = false, optional = true }
+bitfun-services-integrations = { path = "../../services/services-integrations", optional = true }
 
 # Product domain owner crate
-bitfun-product-domains = { path = "../../contracts/product-domains", default-features = false, optional = true }
+bitfun-product-domains = { path = "../../contracts/product-domains", optional = true }
 
 # Tool runtime
-tool-runtime = { path = "../../execution/tool-execution", default-features = false, optional = true }
+tool-runtime = { path = "../../execution/tool-execution", optional = true }
 
 # terminal
 terminal-core = { path = "../../services/terminal", optional = true }
 
 # I18n internationalization
-fluent-bundle = { workspace = true }
-unic-langid = { workspace = true }
+fluent-bundle = { workspace = true, optional = true }
+unic-langid = { workspace = true, optional = true }
 
 sha2 = { workspace = true }
 
@@ -123,23 +123,21 @@ tokio-tungstenite = { workspace = true, optional = true }
 # Event layer dependency (lowest layer)
 bitfun-core-types = { path = "../../contracts/core-types" }
 bitfun-events = { path = "../../contracts/events" }
-bitfun-runtime-ports = { path = "../../contracts/runtime-ports", features = ["permission"] }
+bitfun-runtime-ports = { path = "../../contracts/runtime-ports", features = ["permission", "workspace-ports"] }
 bitfun-runtime-services = { path = "../../execution/runtime-services", optional = true }
 
 # Reviewed product-full plugin composition root.
 bitfun-opencode-adapter = { path = "../../adapters/opencode-adapter", optional = true }
+bitfun-dsh-adapter = { path = "../../adapters/dsh-adapter", optional = true }
 bitfun-claude-code-adapter = { path = "../../adapters/claude-code-adapter", optional = true }
 bitfun-codex-adapter = { path = "../../adapters/codex-adapter", optional = true }
 bitfun-plugin-runtime-client = { path = "../../execution/plugin-runtime-client", optional = true }
 
-# Transport layer dependency
-bitfun-transport = { path = "../../adapters/transport" }
-
 [features]
 # Full product runtime compatibility set. Product entrypoints with a narrower
 # construction path select stable owner features instead of inheriting this
 # union.
-default = ["product-full"]
+default = []
 # Derive `ts_rs::TS` on selected wire types (e.g. `AgentProfileView`) for
 # downstream TypeScript binding export. Propagates `ts` to the upstream crates
 # whose types core re-exports (git types live in `services-integrations`,
@@ -157,6 +155,11 @@ ts = [
 ]
 product-full = [
     "agent-runtime",
+    "document-read",
+    "diagnostics",
+    "diff",
+    "subscription-auth",
+    "i18n-runtime",
     "model-catalog",
     "mcp-runtime",
     "remote-connect",
@@ -203,22 +206,38 @@ product-full = [
 agent-runtime = [
     "ai-adapter-runtime",
     "dep:bitfun-agent-runtime",
+    "bitfun-agent-runtime/agent-runtime",
     "dep:bitfun-agent-content",
     "dep:bitfun-agent-stream",
+    "dep:bitfun-agent-tools",
+    "bitfun-agent-tools/computer-use-contract",
+    "bitfun-runtime-ports/agent-api",
+    "bitfun-runtime-ports/git-port",
+    "bitfun-runtime-ports/remote-exec-port",
+    "bitfun-runtime-ports/remote-workspace-ports",
+    "bitfun-runtime-ports/runtime-event-port",
+    "bitfun-runtime-ports/terminal-port",
+    "bitfun-runtime-ports/tool-runtime-handles",
+    "bitfun-runtime-ports/workspace-ports",
+    "dep:base64",
     "dep:bitfun-harness",
     "dep:dashmap",
     "dep:filetime",
     "dep:flate2",
     "dep:fs2",
+    "dep:futures",
     "dep:include_dir",
     "dep:indexmap",
     "dep:image",
     "dep:md5",
     "dep:rusqlite",
+    "dep:regex",
     "dep:similar",
+    "dep:tokio-util",
     "dep:tool-runtime",
     "bitfun-services-core/permission",
     "bitfun-services-core/runtime-ownership",
+    "bitfun-services-core/workspace-text-runtime",
     "bitfun-services-core/session-git",
     "filesystem",
     "local-storage",
@@ -232,13 +251,21 @@ agent-runtime = [
     "tool-packs",
     "tools-basic",
     "tools-agent-control",
+    "tokio/io-util",
+    "tokio/macros",
+    "tokio/rt",
+    "tokio/time",
 ]
+# Backend Fluent translation state. Locale contracts and model-facing language
+# facts remain available without this runtime implementation.
+i18n-runtime = ["dep:fluent-bundle", "dep:unic-langid"]
 external-sources = [
     "agent-runtime",
     "model-catalog",
     "mcp-runtime",
     "script-tool-runtime",
     "dep:bitfun-opencode-adapter",
+    "dep:bitfun-dsh-adapter",
     "dep:bitfun-claude-code-adapter",
     "dep:bitfun-codex-adapter",
     "dep:bitfun-external-sources",
@@ -257,6 +284,7 @@ model-catalog = [
 ]
 mcp-runtime = [
     "agent-runtime",
+    "bitfun-agent-tools/mcp-bridge",
     "dep:axum",
     "dep:reqwest",
     "bitfun-services-integrations/mcp",
@@ -275,23 +303,35 @@ workspace-search = [
 browser-control = [
     "dep:tokio-tungstenite",
     "bitfun-services-integrations/browser-control",
+    "tokio/net",
+    "tokio/rt",
+    "tokio/time",
 ]
 web-tools = [
     "bitfun-services-integrations/web-tools",
     "tool-runtime/web-readable",
 ]
-deep-research = ["bitfun-services-integrations/deep-research"]
-script-tool-runtime = ["bitfun-services-integrations/script-tool-runtime"]
+deep-research = [
+    "bitfun-agent-runtime?/deep-research",
+    "bitfun-services-integrations/deep-research",
+]
+script-tool-runtime = [
+    "bitfun-runtime-ports/script-tool-runtime",
+    "bitfun-services-integrations/script-tool-runtime",
+]
 scheduled-jobs = [
     "dep:chrono-tz",
     "dep:cron",
 ]
+# Additive dependency modifiers. Weak dependency feature references preserve
+# the owning runtime boundary instead of activating that runtime by themselves.
+document-read = ["tool-runtime?/document-read"]
+subscription-auth = ["bitfun-ai-adapters?/subscription-auth"]
 
 # Tool groups mirror the provider-neutral groups in bitfun-tool-packs. They
 # compose concrete service owners but never form a product-shaped umbrella.
 tools-basic = [
     "bitfun-tool-packs/basic",
-    "tool-runtime/document-read",
     "workspace-search",
 ]
 tools-git = [
@@ -336,16 +376,20 @@ tools-agent-control = [
 plugin-runtime = [
     "external-sources",
     "dep:bitfun-plugin-runtime-client",
+    "bitfun-runtime-ports/plugin-runtime",
 ]
 debug-log = [
     "dep:axum",
+    "dep:tokio-util",
     "dep:tower-http",
     "bitfun-services-integrations/debug-log",
+    "tokio/macros",
+    "tokio/net",
+    "tokio/rt",
+    "tokio/time",
 ]
 ai-adapter-runtime = [
     "dep:bitfun-ai-adapters",
-    "bitfun-ai-adapters/subscription-auth",
-    "dep:reqwest",
 ]
 product-capabilities = ["dep:bitfun-product-capabilities"]
 plugin-source = [
@@ -370,11 +414,13 @@ file-watch = ["bitfun-services-integrations/file-watch"]
 git = ["bitfun-services-integrations/git"]
 review-platform = ["bitfun-services-integrations/review-platform"]
 service-integrations = ["announcement", "file-watch", "git", "review-platform"]
-dispatch-store = ["local-storage", "bitfun-services-core/dispatch-workspace"]
+diagnostics = ["bitfun-services-core/diagnostics"]
+diff = ["bitfun-services-core/diff"]
+dispatch-store = ["dep:base64", "local-storage", "bitfun-services-core/dispatch-workspace"]
 filesystem = ["bitfun-services-core/filesystem"]
-local-storage = ["bitfun-services-core/local-storage"]
+local-storage = ["dep:bitfun-agent-tools", "bitfun-services-core/local-storage"]
 process-runtime = ["bitfun-services-core/process-runtime"]
-lsp = ["dep:notify", "bitfun-services-core/lsp"]
+lsp = ["dep:notify", "bitfun-services-core/lsp", "tokio/macros"]
 terminal = ["dep:terminal-core"]
 workspace-runtime = [
     "dep:serde_yaml",
@@ -404,7 +450,7 @@ ssh-remote = [
 [dev-dependencies]
 bitfun-runtime-services = { path = "../../execution/runtime-services", features = ["test-support"] }
 tempfile = { workspace = true }
-tokio = { workspace = true, features = ["rt-multi-thread"] }
+tokio = { workspace = true, features = ["macros", "rt-multi-thread"] }
 
 [[test]]
 name = "git_contracts"
diff --git a/src/crates/assembly/core/src/agentic/agents/definitions/modes/cowork.rs b/src/crates/assembly/core/src/agentic/agents/definitions/modes/cowork.rs
index 2fb8f94582..3d163af356 100644
--- a/src/crates/assembly/core/src/agentic/agents/definitions/modes/cowork.rs
+++ b/src/crates/assembly/core/src/agentic/agents/definitions/modes/cowork.rs
@@ -56,6 +56,11 @@ impl CoworkMode {
                 "WebSearch".to_string(),
                 "WebFetch".to_string(),
                 "ControlHub".to_string(),
+                // Recurring office work ("check these channels every 30
+                // minutes") is squarely this mode's job, and ControlHub's
+                // `wait` sends schedules here rather than pinning a turn open
+                // for the interval.
+                "Cron".to_string(),
                 "InitMiniApp".to_string(),
                 "FinalizeMiniApp".to_string(),
                 "PublishMiniApp".to_string(),
@@ -120,6 +125,15 @@ mod tests {
         }
     }
 
+    #[test]
+    fn cowork_mode_can_schedule_recurring_work() {
+        // Asked to sweep a set of channels every 30 minutes, this mode used to
+        // reply that it had no cron tool — accurately, because Cron was not in
+        // its list — and fall back to chaining long waits.
+        let tools = CoworkMode::new().default_tools();
+        assert!(tools.contains(&"Cron".to_string()));
+    }
+
     #[test]
     fn cowork_mode_includes_miniapp_lifecycle_tools_in_defaults() {
         let tools = CoworkMode::new().default_tools();
diff --git a/src/crates/assembly/core/src/agentic/agents/definitions/modes/deep_research.rs b/src/crates/assembly/core/src/agentic/agents/definitions/modes/deep_research.rs
index 0011473285..5eababbd82 100644
--- a/src/crates/assembly/core/src/agentic/agents/definitions/modes/deep_research.rs
+++ b/src/crates/assembly/core/src/agentic/agents/definitions/modes/deep_research.rs
@@ -39,6 +39,10 @@ impl DeepResearchMode {
                 "WriteStdin".to_string(),
                 "ExecControl".to_string(),
                 "ControlHub".to_string(),
+                // Standing research ("re-check these sources every morning")
+                // belongs on a schedule, and ControlHub's `wait` points here
+                // rather than at an hour-long turn.
+                "Cron".to_string(),
                 "TodoWrite".to_string(),
                 "AskUserQuestion".to_string(),
             ],
diff --git a/src/crates/assembly/core/src/agentic/agents/definitions/modes/team.rs b/src/crates/assembly/core/src/agentic/agents/definitions/modes/team.rs
index 78216eef6b..293fa3d07a 100644
--- a/src/crates/assembly/core/src/agentic/agents/definitions/modes/team.rs
+++ b/src/crates/assembly/core/src/agentic/agents/definitions/modes/team.rs
@@ -44,6 +44,10 @@ impl TeamMode {
                 "AskUserQuestion".to_string(),
                 "Git".to_string(),
                 "ControlHub".to_string(),
+                // Every mode that carries ControlHub needs Cron: ControlHub's
+                // `wait` tells the agent to schedule long or repeating work
+                // here instead of holding the turn open.
+                "Cron".to_string(),
                 "GetFileDiff".to_string(),
             ],
         }
diff --git a/src/crates/assembly/core/src/agentic/agents/mod.rs b/src/crates/assembly/core/src/agentic/agents/mod.rs
index 3475947888..4ec7db7d90 100644
--- a/src/crates/assembly/core/src/agentic/agents/mod.rs
+++ b/src/crates/assembly/core/src/agentic/agents/mod.rs
@@ -145,6 +145,10 @@ pub fn shared_coding_mode_tools() -> Vec<String> {
         "Git".to_string(),
         "ReviewPlatform".to_string(),
         "ControlHub".to_string(),
+        // Pairs with ControlHub: its `wait` sends anything repeating, or
+        // further out than an hour, to Cron rather than holding the turn open
+        // for the interval.
+        "Cron".to_string(),
         "InitMiniApp".to_string(),
         "FinalizeMiniApp".to_string(),
         "PublishMiniApp".to_string(),
diff --git a/src/crates/assembly/core/src/agentic/agents/registry/tests.rs b/src/crates/assembly/core/src/agentic/agents/registry/tests.rs
index 462445ae79..c0636392b3 100644
--- a/src/crates/assembly/core/src/agentic/agents/registry/tests.rs
+++ b/src/crates/assembly/core/src/agentic/agents/registry/tests.rs
@@ -340,6 +340,30 @@ fn every_builtin_primary_mode_defaults_to_the_thread_goal_lifecycle() {
     }
 }
 
+#[test]
+fn every_builtin_mode_with_control_hub_can_also_schedule_with_cron() {
+    // ControlHub's `wait` documentation tells the agent to schedule anything
+    // repeating — or further out than an hour — with Cron instead of holding
+    // the turn open. A mode that offers one without the other sends the agent
+    // after a tool that is not in its list; Cowork answered a "check every 30
+    // minutes" request with "I have no cron tool" for exactly this reason.
+    for spec in builtin_agent_specs()
+        .iter()
+        .filter(|spec| spec.category == AgentCategory::Mode)
+    {
+        let mode = (spec.factory)();
+        let default_tools = mode.default_tools();
+        if !default_tools.iter().any(|tool| tool == "ControlHub") {
+            continue;
+        }
+        assert!(
+            default_tools.iter().any(|tool| tool == "Cron"),
+            "builtin mode {} offers ControlHub but cannot schedule with Cron",
+            mode.id()
+        );
+    }
+}
+
 #[test]
 fn non_deep_review_builtin_subagents_default_to_primary() {
     for agent_type in [
diff --git a/src/crates/assembly/core/src/agentic/coordination/coordinator.rs b/src/crates/assembly/core/src/agentic/coordination/coordinator.rs
index 74d6c4255f..2b7ee2dcee 100644
--- a/src/crates/assembly/core/src/agentic/coordination/coordinator.rs
+++ b/src/crates/assembly/core/src/agentic/coordination/coordinator.rs
@@ -38,10 +38,18 @@ use crate::agentic::memories::{start_memory_startup_task, MemoryStartupRequest};
 use crate::agentic::permission_policy::resolve_effective_permission_policy;
 use crate::agentic::round_preempt::DialogRoundInjectionSource;
 use crate::agentic::session::revert::{
-    resolve_redo, resolve_undo, SessionRevertPhase, SessionRevertTransition,
+    resolve_redo, resolve_targeted, resolve_undo, SessionRevertPhase, SessionRevertTransition,
 };
 use crate::agentic::session::session_store_port::CoreSessionStorePort;
-use crate::agentic::session::{SessionManager, SessionReferenceLocator};
+use crate::agentic::session::{
+    SessionManager, SessionReferenceLocator, TurnAdmissionSessionFacts,
+    INTERRUPTED_TURN_MODEL_BINDING_FINGERPRINT_METADATA_KEY,
+    INTERRUPTED_TURN_PERMISSION_MODE_METADATA_KEY,
+    INTERRUPTED_TURN_REASONING_FINGERPRINT_METADATA_KEY,
+    INTERRUPTED_TURN_REASONING_PRESET_METADATA_KEY,
+    INTERRUPTED_TURN_REASONING_SELECTION_METADATA_KEY,
+    INTERRUPTED_TURN_RESOLVED_MODEL_ID_METADATA_KEY,
+};
 use crate::agentic::side_question::build_btw_user_input;
 use crate::agentic::skill_agent_snapshot::{
     diff_skill_agent_snapshot, resolve_skill_agent_snapshot, TurnSkillAgentSnapshot,
@@ -1076,6 +1084,66 @@ fn lineage_post_admission_cancellation_error(
     ))
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum DialogTurnStopDisposition {
+    Cancelled,
+    Interrupted,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum InterruptedTurnIntentState {
+    Pending,
+    Committed,
+    Revoked,
+}
+
+fn interrupted_turn_intent_is_pending(
+    intents: &DashMap<String, InterruptedTurnIntentState>,
+    key: &str,
+) -> bool {
+    intents
+        .get(key)
+        .is_some_and(|state| *state == InterruptedTurnIntentState::Pending)
+}
+
+fn commit_interrupted_turn_intent(
+    intents: &DashMap<String, InterruptedTurnIntentState>,
+    key: &str,
+) -> bool {
+    let Some(mut state) = intents.get_mut(key) else {
+        return false;
+    };
+    match *state {
+        InterruptedTurnIntentState::Pending => {
+            *state = InterruptedTurnIntentState::Committed;
+            true
+        }
+        InterruptedTurnIntentState::Committed => true,
+        InterruptedTurnIntentState::Revoked => false,
+    }
+}
+
+fn revoke_interrupted_turn_intent_or_observe_commit(
+    intents: &DashMap<String, InterruptedTurnIntentState>,
+    key: &str,
+) -> bool {
+    let Some(mut state) = intents.get_mut(key) else {
+        return false;
+    };
+    match *state {
+        InterruptedTurnIntentState::Pending => {
+            *state = InterruptedTurnIntentState::Revoked;
+            false
+        }
+        InterruptedTurnIntentState::Committed => true,
+        InterruptedTurnIntentState::Revoked => false,
+    }
+}
+
+fn turn_stop_key(session_id: &str, turn_id: &str) -> String {
+    format!("{session_id}\u{1f}{turn_id}")
+}
+
 /// Conversation coordinator
 pub struct ConversationCoordinator {
     session_manager: Arc<SessionManager>,
@@ -1095,7 +1163,7 @@ pub struct ConversationCoordinator {
     /// Parent-owned terminal outcomes consumed only through AgentWait.
     background_subagent_outcomes: Arc<BackgroundSubagentOutcomeStore>,
     /// Notifies DialogScheduler of turn outcomes; injected after construction
-    scheduler_notify_tx: OnceLock<mpsc::Sender<(String, TurnOutcome)>>,
+    scheduler_notify_tx: OnceLock<mpsc::UnboundedSender<(String, TurnOutcome)>>,
     /// Round-boundary user steering source (mid-turn user message injection); injected after construction
     round_injection_source: OnceLock<Arc<dyn DialogRoundInjectionSource>>,
     /// In-flight dialog turn tracker per session, used to serialize cancel→start
@@ -1111,6 +1179,9 @@ pub struct ConversationCoordinator {
     /// Manual-compaction turns need an atomic planning/cancel/commit decision
     /// before the normal cancellation path may expose the Session as idle.
     manual_compaction_controls: Arc<DashMap<String, Arc<ManualCompactionCommitGate>>>,
+    /// Recoverable stop intent observed by the spawned execution owner when
+    /// cancellation reaches its terminal persistence boundary.
+    interrupted_turn_intents: Arc<DashMap<String, InterruptedTurnIntentState>>,
     thread_goal_runtime: Arc<ThreadGoalRuntime>,
     terminal_port: OnceLock<Arc<dyn TerminalPort>>,
     remote_exec_port: OnceLock<Arc<dyn RemoteExecPort>>,
@@ -2150,6 +2221,7 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
             active_turns_per_session: Arc::new(DashMap::new()),
             turn_settlements: Arc::new(TurnSettlementTracker::default()),
             manual_compaction_controls: Arc::new(DashMap::new()),
+            interrupted_turn_intents: Arc::new(DashMap::new()),
             thread_goal_runtime: Arc::new(ThreadGoalRuntime::new()),
             terminal_port: OnceLock::new(),
             remote_exec_port: OnceLock::new(),
@@ -2314,7 +2386,7 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
 
     /// Inject the DialogScheduler notification channel after construction.
     /// Called once during app initialization after the scheduler is created.
-    pub fn set_scheduler_notifier(&self, tx: mpsc::Sender<(String, TurnOutcome)>) {
+    pub fn set_scheduler_notifier(&self, tx: mpsc::UnboundedSender<(String, TurnOutcome)>) {
         let _ = self.scheduler_notify_tx.set(tx);
     }
 
@@ -2797,11 +2869,13 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
     }
 
     async fn persist_completed_dialog_turn(
+        event_queue: &EventQueue,
         session_manager: &SessionManager,
-        scheduler_notify_tx: Option<&mpsc::Sender<(String, TurnOutcome)>>,
+        scheduler_notify_tx: Option<&mpsc::UnboundedSender<(String, TurnOutcome)>>,
         session_id: &str,
         turn_id: &str,
         execution_result: &ExecutionResult,
+        recovery_generation: Option<u32>,
     ) -> (crate::service::session::TurnStatus, String) {
         let final_response = match &execution_result.final_message.content {
             MessageContent::Text(text) => text.clone(),
@@ -2814,25 +2888,84 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
             session_id, turn_id, execution_result.total_rounds
         );
 
-        if let Err(error) = session_manager
-            .complete_dialog_turn(
-                session_id,
-                turn_id,
-                final_response.clone(),
-                &execution_result.new_messages,
-                TurnStats {
-                    total_rounds: execution_result.total_rounds,
-                    total_tools: 0, // TODO: get from execution_result
-                    total_tokens: 0,
-                    duration_ms: 0,
-                },
-            )
-            .await
-        {
+        let stats = TurnStats {
+            total_rounds: execution_result.total_rounds,
+            total_tools: execution_result.total_tools,
+            total_tokens: 0,
+            duration_ms: execution_result.duration_ms,
+        };
+        let persistence_result = match recovery_generation {
+            Some(execution_generation) => {
+                session_manager
+                    .complete_recovered_dialog_turn(
+                        session_id,
+                        turn_id,
+                        execution_generation,
+                        final_response.clone(),
+                        &execution_result.new_messages,
+                        stats,
+                    )
+                    .await
+            }
+            None => {
+                session_manager
+                    .complete_dialog_turn(
+                        session_id,
+                        turn_id,
+                        final_response.clone(),
+                        &execution_result.new_messages,
+                        stats,
+                    )
+                    .await
+            }
+        };
+        if let Err(error) = persistence_result {
             error!(
                 "Failed to complete dialog turn: session_id={}, turn_id={}, error={}",
                 session_id, turn_id, error
             );
+            if recovery_generation.is_some() {
+                // A recovered generation is Runtime-owned. Never acknowledge
+                // completion when its authoritative Turn payload was not made
+                // durable; put the same generation back behind the recovery
+                // gate so the user can retry without losing its prior rounds.
+                let status = Self::persist_interrupted_dialog_turn(
+                    event_queue,
+                    session_manager,
+                    scheduler_notify_tx,
+                    session_id,
+                    turn_id,
+                    &execution_result.new_messages,
+                    None,
+                )
+                .await;
+                return (status, String::new());
+            }
+        }
+
+        if recovery_generation.is_some() {
+            if let Err(error) = event_queue
+                .enqueue(
+                    AgenticEvent::DialogTurnCompleted {
+                        session_id: session_id.to_string(),
+                        turn_id: turn_id.to_string(),
+                        total_rounds: execution_result.total_rounds,
+                        total_tools: execution_result.total_tools,
+                        duration_ms: execution_result.duration_ms,
+                        partial_recovery_reason: execution_result.partial_recovery_reason.clone(),
+                        success: Some(execution_result.success),
+                        finish_reason: Some(execution_result.effective_finish_reason.clone()),
+                        has_final_response: Some(execution_result.has_final_response),
+                    },
+                    None,
+                )
+                .await
+            {
+                error!(
+                    "Failed to emit recovered DialogTurnCompleted event: session_id={}, turn_id={}, error={}",
+                    session_id, turn_id, error
+                );
+            }
         }
 
         match session_manager
@@ -2855,7 +2988,7 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
         }
 
         if let Some(tx) = scheduler_notify_tx {
-            if let Err(error) = tx.try_send((
+            if let Err(error) = tx.send((
                 session_id.to_string(),
                 TurnOutcome::Completed {
                     turn_id: turn_id.to_string(),
@@ -2878,193 +3011,494 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
     async fn persist_cancelled_dialog_turn(
         event_queue: &EventQueue,
         session_manager: &SessionManager,
-        scheduler_notify_tx: Option<&mpsc::Sender<(String, TurnOutcome)>>,
+        scheduler_notify_tx: Option<&mpsc::UnboundedSender<(String, TurnOutcome)>>,
         session_id: &str,
         turn_id: &str,
         emit_lifecycle_events: bool,
     ) -> crate::service::session::TurnStatus {
-        info!(
-            "Dialog turn cancelled: session={}, turn={}",
-            session_id, turn_id
-        );
+        Self::persist_cancelled_dialog_turn_with_messages(
+            event_queue,
+            session_manager,
+            scheduler_notify_tx,
+            session_id,
+            turn_id,
+            emit_lifecycle_events,
+            &[],
+        )
+        .await
+    }
+
+    #[allow(clippy::too_many_arguments)]
+    async fn report_terminal_persistence_failure(
+        event_queue: &EventQueue,
+        session_manager: &SessionManager,
+        scheduler_notify_tx: Option<&mpsc::UnboundedSender<(String, TurnOutcome)>>,
+        session_id: &str,
+        turn_id: &str,
+        terminal_kind: &str,
+        persistence_error: &BitFunError,
+        emit_lifecycle_events: bool,
+    ) -> crate::service::session::TurnStatus {
+        let error = BitFunError::OutcomeUnknown(format!(
+            "Failed to persist authoritative {terminal_kind} outcome: session_id={session_id}, turn_id={turn_id}; {persistence_error}"
+        ));
+        let error_text = error.to_string();
+        error!("{error_text}");
 
         if emit_lifecycle_events {
-            // The execution engine only emits DialogTurnCancelled when cancellation is
-            // detected between rounds. If cancellation interrupted streaming mid-round,
-            // no event was emitted. Emit it here unconditionally; duplicates are harmless.
-            if let Err(error) = event_queue
+            if let Err(queue_error) = event_queue
                 .enqueue(
-                    AgenticEvent::DialogTurnCancelled {
+                    AgenticEvent::DialogTurnFailed {
                         session_id: session_id.to_string(),
                         turn_id: turn_id.to_string(),
+                        error: error_text.clone(),
+                        error_category: Some(error.error_category()),
+                        error_detail: Some(error.error_detail()),
                     },
                     Some(EventPriority::Critical),
                 )
                 .await
             {
                 error!(
-                    "Failed to emit DialogTurnCancelled event: session_id={}, turn_id={}, error={}",
-                    session_id, turn_id, error
+                    "Failed to emit terminal persistence failure: session_id={}, turn_id={}, error={}",
+                    session_id, turn_id, queue_error
                 );
             }
         }
 
-        if let Err(error) = session_manager
-            .cancel_dialog_turn(session_id, turn_id)
+        if let Err(state_error) = session_manager
+            .update_session_state_for_turn_if_processing(
+                session_id,
+                turn_id,
+                SessionState::Error {
+                    error: error_text.clone(),
+                    recoverable: true,
+                },
+            )
             .await
         {
             error!(
-                "Failed to cancel dialog turn in persistence: session_id={}, turn_id={}, error={}",
-                session_id, turn_id, error
+                "Failed to set Session Error after terminal persistence failure: session_id={}, turn_id={}, error={}",
+                session_id, turn_id, state_error
             );
         }
 
-        match session_manager
-            .update_session_state_for_turn_if_processing(session_id, turn_id, SessionState::Idle)
-            .await
-        {
-            Ok(true) => {}
-            Ok(false) => {
-                debug!(
-                    "Skipped setting session Idle after cancellation for stale turn: session_id={}, turn_id={}",
-                    session_id, turn_id
-                );
-            }
-            Err(error) => {
-                error!(
-                    "Failed to set session state to Idle after cancellation: session_id={}, turn_id={}, error={}",
-                    session_id, turn_id, error
-                );
-            }
-        }
-
         if let Some(tx) = scheduler_notify_tx {
-            if let Err(error) = tx.try_send((
+            if let Err(notify_error) = tx.send((
                 session_id.to_string(),
-                TurnOutcome::Cancelled {
+                TurnOutcome::Failed {
                     turn_id: turn_id.to_string(),
+                    error: error_text,
                 },
             )) {
                 error!(
-                    "Failed to notify scheduler of turn cancellation: session_id={}, turn_id={}, error={}",
-                    session_id, turn_id, error
+                    "Failed to notify scheduler of terminal persistence failure: session_id={}, turn_id={}, error={}",
+                    session_id, turn_id, notify_error
                 );
             }
         }
 
-        crate::service::session::TurnStatus::Cancelled
+        crate::service::session::TurnStatus::Error
     }
 
-    async fn persist_failed_dialog_turn(
+    async fn persist_cancelled_dialog_turn_with_messages(
         event_queue: &EventQueue,
         session_manager: &SessionManager,
-        scheduler_notify_tx: Option<&mpsc::Sender<(String, TurnOutcome)>>,
+        scheduler_notify_tx: Option<&mpsc::UnboundedSender<(String, TurnOutcome)>>,
         session_id: &str,
         turn_id: &str,
-        error: &BitFunError,
         emit_lifecycle_events: bool,
+        generation_messages: &[Message],
     ) -> crate::service::session::TurnStatus {
-        let error_text = error.to_string();
-        let recoverable = !matches!(error, BitFunError::AIClient(_) | BitFunError::Timeout(_));
+        Self::persist_cancelled_dialog_turn_with_messages_and_policy(
+            event_queue,
+            session_manager,
+            scheduler_notify_tx,
+            session_id,
+            turn_id,
+            emit_lifecycle_events,
+            generation_messages,
+            false,
+        )
+        .await
+    }
 
-        error!("Dialog turn execution failed: {}", error_text);
+    #[allow(clippy::too_many_arguments)]
+    async fn persist_cancelled_dialog_turn_with_messages_and_policy(
+        event_queue: &EventQueue,
+        session_manager: &SessionManager,
+        scheduler_notify_tx: Option<&mpsc::UnboundedSender<(String, TurnOutcome)>>,
+        session_id: &str,
+        turn_id: &str,
+        emit_lifecycle_events: bool,
+        generation_messages: &[Message],
+        preserve_recovery_on_persist_failure: bool,
+    ) -> crate::service::session::TurnStatus {
+        info!(
+            "Dialog turn cancelled: session={}, turn={}",
+            session_id, turn_id
+        );
+
+        if let Err(error) = session_manager
+            .cancel_dialog_turn_with_messages(session_id, turn_id, generation_messages)
+            .await
+        {
+            error!(
+                "Failed to cancel dialog turn in persistence: session_id={}, turn_id={}, error={}",
+                session_id, turn_id, error
+            );
+            if preserve_recovery_on_persist_failure {
+                return Box::pin(Self::persist_interrupted_dialog_turn(
+                    event_queue,
+                    session_manager,
+                    scheduler_notify_tx,
+                    session_id,
+                    turn_id,
+                    generation_messages,
+                    None,
+                ))
+                .await;
+            }
+            return Self::report_terminal_persistence_failure(
+                event_queue,
+                session_manager,
+                scheduler_notify_tx,
+                session_id,
+                turn_id,
+                "cancelled",
+                &error,
+                emit_lifecycle_events,
+            )
+            .await;
+        }
 
         if emit_lifecycle_events {
-            if let Err(queue_error) = event_queue
+            if let Err(error) = event_queue
                 .enqueue(
-                    AgenticEvent::DialogTurnFailed {
+                    AgenticEvent::DialogTurnCancelled {
                         session_id: session_id.to_string(),
                         turn_id: turn_id.to_string(),
-                        error: error_text.clone(),
-                        error_category: Some(error.error_category()),
-                        error_detail: Some(error.error_detail()),
                     },
                     Some(EventPriority::Critical),
                 )
                 .await
             {
                 error!(
-                    "Failed to emit DialogTurnFailed event: session_id={}, turn_id={}, error={}",
-                    session_id, turn_id, queue_error
+                    "Failed to emit DialogTurnCancelled event: session_id={}, turn_id={}, error={}",
+                    session_id, turn_id, error
                 );
             }
         }
 
-        if let Err(persist_error) = session_manager
-            .fail_dialog_turn(session_id, turn_id, error_text.clone())
-            .await
-        {
-            error!(
-                "Failed to mark dialog turn as failed: session_id={}, turn_id={}, error={}",
-                session_id, turn_id, persist_error
-            );
-        }
-
         match session_manager
-            .update_session_state_for_turn_if_processing(
-                session_id,
-                turn_id,
-                SessionState::Error {
-                    error: error_text.clone(),
-                    recoverable,
-                },
-            )
+            .update_session_state_for_turn_if_processing(session_id, turn_id, SessionState::Idle)
             .await
         {
             Ok(true) => {}
             Ok(false) => {
                 debug!(
-                    "Skipped setting session Error after failure for stale turn: session_id={}, turn_id={}",
+                    "Skipped setting session Idle after cancellation for stale turn: session_id={}, turn_id={}",
                     session_id, turn_id
                 );
             }
-            Err(state_error) => {
+            Err(error) => {
                 error!(
-                    "Failed to set session state to Error: session_id={}, turn_id={}, error={}",
-                    session_id, turn_id, state_error
+                    "Failed to set session state to Idle after cancellation: session_id={}, turn_id={}, error={}",
+                    session_id, turn_id, error
                 );
             }
         }
 
         if let Some(tx) = scheduler_notify_tx {
-            if let Err(notify_error) = tx.try_send((
+            if let Err(error) = tx.send((
                 session_id.to_string(),
-                TurnOutcome::Failed {
+                TurnOutcome::Cancelled {
                     turn_id: turn_id.to_string(),
-                    error: error_text.clone(),
                 },
             )) {
                 error!(
-                    "Failed to notify scheduler of turn failure: session_id={}, turn_id={}, error={}",
-                    session_id, turn_id, notify_error
+                    "Failed to notify scheduler of turn cancellation: session_id={}, turn_id={}, error={}",
+                    session_id, turn_id, error
                 );
             }
         }
 
-        if let Some(coordinator) = get_global_coordinator() {
-            coordinator
-                .maybe_mark_thread_goal_usage_limited(session_id, error)
-                .await;
-        }
-
-        crate::service::session::TurnStatus::Error
+        crate::service::session::TurnStatus::Cancelled
     }
 
-    async fn finalize_persisted_turn_in_workspace_if_needed(
+    async fn persist_interrupted_dialog_turn(
+        event_queue: &EventQueue,
         session_manager: &SessionManager,
+        scheduler_notify_tx: Option<&mpsc::UnboundedSender<(String, TurnOutcome)>>,
         session_id: &str,
         turn_id: &str,
-        turn_index: usize,
-        agent_type: &str,
-        user_input: &str,
-        workspace_path: Option<&str>,
-        resolved_session_storage_path: Option<&std::path::Path>,
-        status: Option<crate::service::session::TurnStatus>,
-        user_message_metadata: Option<serde_json::Value>,
-    ) {
-        if !session_manager.should_persist_session_id(session_id) {
-            return;
-        }
+        generation_messages: &[Message],
+        interruption_intents: Option<&DashMap<String, InterruptedTurnIntentState>>,
+    ) -> crate::service::session::TurnStatus {
+        info!(
+            "Dialog turn interrupted: session={}, turn={}",
+            session_id, turn_id
+        );
+        let recovery = match session_manager
+            .mark_dialog_turn_interrupted_with_messages(session_id, turn_id, generation_messages)
+            .await
+        {
+            Ok(recovery) => recovery,
+            Err(error) => {
+                error!(
+                    "Failed to persist recoverable interruption; falling back to cancellation: session_id={}, turn_id={}, error={}",
+                    session_id, turn_id, error
+                );
+                return Self::persist_cancelled_dialog_turn_with_messages(
+                    event_queue,
+                    session_manager,
+                    scheduler_notify_tx,
+                    session_id,
+                    turn_id,
+                    true,
+                    generation_messages,
+                )
+                .await;
+            }
+        };
+
+        match session_manager
+            .update_session_state_for_turn_if_processing(session_id, turn_id, SessionState::Idle)
+            .await
+        {
+            Ok(true) => {}
+            Ok(false) => debug!(
+                "Interrupted turn no longer owns Processing state: session_id={}, turn_id={}",
+                session_id, turn_id
+            ),
+            Err(error) => error!(
+                "Failed to settle interrupted Session as Idle: session_id={}, turn_id={}, error={}",
+                session_id, turn_id, error
+            ),
+        }
+
+        if let Some(interruption_intents) = interruption_intents {
+            let key = turn_stop_key(session_id, turn_id);
+            if !commit_interrupted_turn_intent(interruption_intents, &key) {
+                interruption_intents.remove(&key);
+                info!(
+                    "Interrupted turn was superseded by hard cancellation before settlement: session_id={}, turn_id={}",
+                    session_id, turn_id
+                );
+                return Self::persist_cancelled_dialog_turn_with_messages_and_policy(
+                    event_queue,
+                    session_manager,
+                    scheduler_notify_tx,
+                    session_id,
+                    turn_id,
+                    true,
+                    generation_messages,
+                    true,
+                )
+                .await;
+            }
+        }
+
+        if let Some(tx) = scheduler_notify_tx {
+            if let Err(error) = tx.send((
+                session_id.to_string(),
+                TurnOutcome::Interrupted {
+                    turn_id: turn_id.to_string(),
+                    execution_generation: recovery.execution_generation,
+                },
+            )) {
+                error!(
+                    "Failed to notify scheduler of turn interruption: session_id={}, turn_id={}, error={}",
+                    session_id, turn_id, error
+                );
+            }
+        }
+
+        if let Err(error) = event_queue
+            .enqueue_with_guaranteed_legacy_storage(
+                AgenticEvent::DialogTurnInterrupted {
+                    session_id: session_id.to_string(),
+                    turn_id: turn_id.to_string(),
+                    execution_generation: recovery.execution_generation,
+                    model_id: recovery.model_id.clone(),
+                },
+                Some(EventPriority::Critical),
+            )
+            .await
+        {
+            error!(
+                "Failed to emit DialogTurnInterrupted event: session_id={}, turn_id={}, error={}",
+                session_id, turn_id, error
+            );
+        }
+
+        crate::service::session::TurnStatus::Cancelled
+    }
+
+    async fn persist_failed_dialog_turn(
+        event_queue: &EventQueue,
+        session_manager: &SessionManager,
+        scheduler_notify_tx: Option<&mpsc::UnboundedSender<(String, TurnOutcome)>>,
+        session_id: &str,
+        turn_id: &str,
+        error: &BitFunError,
+        emit_lifecycle_events: bool,
+    ) -> crate::service::session::TurnStatus {
+        Self::persist_failed_dialog_turn_with_messages(
+            event_queue,
+            session_manager,
+            scheduler_notify_tx,
+            session_id,
+            turn_id,
+            error,
+            emit_lifecycle_events,
+            &[],
+            false,
+        )
+        .await
+    }
+
+    #[allow(clippy::too_many_arguments)]
+    async fn persist_failed_dialog_turn_with_messages(
+        event_queue: &EventQueue,
+        session_manager: &SessionManager,
+        scheduler_notify_tx: Option<&mpsc::UnboundedSender<(String, TurnOutcome)>>,
+        session_id: &str,
+        turn_id: &str,
+        error: &BitFunError,
+        emit_lifecycle_events: bool,
+        generation_messages: &[Message],
+        preserve_recovery_on_persist_failure: bool,
+    ) -> crate::service::session::TurnStatus {
+        let error_text = error.to_string();
+        let recoverable = !matches!(error, BitFunError::AIClient(_) | BitFunError::Timeout(_));
+
+        error!("Dialog turn execution failed: {}", error_text);
+
+        if let Err(persist_error) = session_manager
+            .fail_dialog_turn_with_messages(
+                session_id,
+                turn_id,
+                error_text.clone(),
+                generation_messages,
+            )
+            .await
+        {
+            error!(
+                "Failed to mark dialog turn as failed: session_id={}, turn_id={}, error={}",
+                session_id, turn_id, persist_error
+            );
+            if preserve_recovery_on_persist_failure {
+                return Self::persist_interrupted_dialog_turn(
+                    event_queue,
+                    session_manager,
+                    scheduler_notify_tx,
+                    session_id,
+                    turn_id,
+                    generation_messages,
+                    None,
+                )
+                .await;
+            }
+            return Self::report_terminal_persistence_failure(
+                event_queue,
+                session_manager,
+                scheduler_notify_tx,
+                session_id,
+                turn_id,
+                "failed",
+                &persist_error,
+                emit_lifecycle_events,
+            )
+            .await;
+        }
+
+        if emit_lifecycle_events {
+            if let Err(queue_error) = event_queue
+                .enqueue(
+                    AgenticEvent::DialogTurnFailed {
+                        session_id: session_id.to_string(),
+                        turn_id: turn_id.to_string(),
+                        error: error_text.clone(),
+                        error_category: Some(error.error_category()),
+                        error_detail: Some(error.error_detail()),
+                    },
+                    Some(EventPriority::Critical),
+                )
+                .await
+            {
+                error!(
+                    "Failed to emit DialogTurnFailed event: session_id={}, turn_id={}, error={}",
+                    session_id, turn_id, queue_error
+                );
+            }
+        }
+
+        match session_manager
+            .update_session_state_for_turn_if_processing(
+                session_id,
+                turn_id,
+                SessionState::Error {
+                    error: error_text.clone(),
+                    recoverable,
+                },
+            )
+            .await
+        {
+            Ok(true) => {}
+            Ok(false) => {
+                debug!(
+                    "Skipped setting session Error after failure for stale turn: session_id={}, turn_id={}",
+                    session_id, turn_id
+                );
+            }
+            Err(state_error) => {
+                error!(
+                    "Failed to set session state to Error: session_id={}, turn_id={}, error={}",
+                    session_id, turn_id, state_error
+                );
+            }
+        }
+
+        if let Some(tx) = scheduler_notify_tx {
+            if let Err(notify_error) = tx.send((
+                session_id.to_string(),
+                TurnOutcome::Failed {
+                    turn_id: turn_id.to_string(),
+                    error: error_text.clone(),
+                },
+            )) {
+                error!(
+                    "Failed to notify scheduler of turn failure: session_id={}, turn_id={}, error={}",
+                    session_id, turn_id, notify_error
+                );
+            }
+        }
+
+        if let Some(coordinator) = get_global_coordinator() {
+            coordinator
+                .maybe_mark_thread_goal_usage_limited(session_id, error)
+                .await;
+        }
+
+        crate::service::session::TurnStatus::Error
+    }
+
+    async fn finalize_persisted_turn_in_workspace_if_needed(
+        session_manager: &SessionManager,
+        session_id: &str,
+        turn_id: &str,
+        turn_index: usize,
+        agent_type: &str,
+        user_input: &str,
+        workspace_path: Option<&str>,
+        resolved_session_storage_path: Option<&std::path::Path>,
+        status: Option<crate::service::session::TurnStatus>,
+        user_message_metadata: Option<serde_json::Value>,
+    ) {
+        if !session_manager.should_persist_session_id(session_id) {
+            return;
+        }
 
         if let (Some(workspace_path), Some(status)) = (workspace_path, status) {
             Self::finalize_turn_in_workspace(
@@ -3350,7 +3784,7 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
         let kickoff_query = Self::assistant_bootstrap_kickoff_query(is_chinese);
         let expected_reply_language = if is_chinese { "Chinese" } else { "English" };
         let workspace_binding = WorkspaceBinding::new(None, workspace_root.clone());
-        let model_id = self
+        let (model_id, _) = self
             .execution_engine
             .resolve_model_id_for_turn(
                 &session,
@@ -3358,6 +3792,8 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
                 Some(&workspace_binding),
                 kickoff_query,
                 0,
+                None,
+                None,
             )
             .await?;
 
@@ -4056,7 +4492,7 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
                             final_response: String::new(),
                         }
                     };
-                    if let Err(error) = tx.try_send((session_id.clone(), outcome)) {
+                    if let Err(error) = tx.send((session_id.clone(), outcome)) {
                         error!(
                         "Failed to notify scheduler of delegated command settlement: session_id={}, turn_id={}, error={}",
                         session_id, turn_id, error
@@ -5004,7 +5440,10 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
             turn_index,
             agent_type: runtime_agent_type,
             workspace: manual_workspace,
-            context: HashMap::new(),
+            context: HashMap::from([(
+                "cancel_lifecycle_owner".to_string(),
+                "coordinator".to_string(),
+            )]),
             subagent_parent_info: None,
             permission_delegation: None,
             permission_runtime_ceiling: None,
@@ -5014,7 +5453,7 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
             terminal_port,
             remote_exec_port,
             round_injection: None,
-            emit_lifecycle_events: true,
+            emit_lifecycle_events: false,
             recover_partial_on_cancel: false,
         };
         let session_max_tokens = session.config.max_context_tokens;
@@ -5596,11 +6035,84 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
             user_message_metadata = Some(metadata);
         }
 
+        // Resolve and freeze the concrete model before the Turn becomes
+        // visible. Symbolic selectors such as `auto` may change between
+        // generations; a recovered generation must keep the model selected
+        // for the first generation.
+        let (resolved_model_id, resolved_model_binding_fingerprint) = self
+            .execution_engine
+            .resolve_model_id_for_turn(
+                &session,
+                &effective_agent_type,
+                session_workspace.as_ref(),
+                &original_user_input,
+                turn_index,
+                None,
+                None,
+            )
+            .await?;
+        let reasoning_preset = self
+            .session_manager
+            .reconcile_session_reasoning_preset_for_turn(&session_id, "turn_admission")
+            .await?;
+        let (resolved_reasoning_preset, resolved_reasoning_fingerprint) =
+            SessionManager::resolve_effective_reasoning_preset_for_turn(
+                &resolved_model_id,
+                reasoning_preset.as_deref(),
+            )
+            .await?;
+        let admission_facts = TurnAdmissionSessionFacts::from_session(&session)
+            .with_reasoning_preset(reasoning_preset.clone());
+
+        // Persist the first generation's effective permission as the maximum
+        // authority a recovered generation may use. Ordinary rounds still read
+        // current turn/session/global settings; recovery may tighten this
+        // baseline per round, but can never widen it.
+        let submission_permission_mode = resolve_submission_permission_mode(
+            permission_mode_from_metadata(user_message_metadata.as_ref()),
+            session.config.permission_mode,
+            default_permission_mode_from_global_config().await,
+        );
+        let mut metadata = Self::ensure_user_message_metadata_object(user_message_metadata.take());
+        if let Some(object) = metadata.as_object_mut() {
+            object.insert(
+                INTERRUPTED_TURN_PERMISSION_MODE_METADATA_KEY.to_string(),
+                serde_json::Value::String(submission_permission_mode.mode.as_str().to_string()),
+            );
+            object.insert(
+                INTERRUPTED_TURN_RESOLVED_MODEL_ID_METADATA_KEY.to_string(),
+                serde_json::Value::String(resolved_model_id.clone()),
+            );
+            object.insert(
+                INTERRUPTED_TURN_MODEL_BINDING_FINGERPRINT_METADATA_KEY.to_string(),
+                serde_json::Value::String(resolved_model_binding_fingerprint.clone()),
+            );
+            object.insert(
+                INTERRUPTED_TURN_REASONING_PRESET_METADATA_KEY.to_string(),
+                resolved_reasoning_preset
+                    .clone()
+                    .map(serde_json::Value::String)
+                    .unwrap_or(serde_json::Value::Null),
+            );
+            object.insert(
+                INTERRUPTED_TURN_REASONING_SELECTION_METADATA_KEY.to_string(),
+                reasoning_preset
+                    .clone()
+                    .map(serde_json::Value::String)
+                    .unwrap_or(serde_json::Value::Null),
+            );
+            object.insert(
+                INTERRUPTED_TURN_REASONING_FINGERPRINT_METADATA_KEY.to_string(),
+                serde_json::Value::String(resolved_reasoning_fingerprint.clone()),
+            );
+        }
+        user_message_metadata = Some(metadata);
+
         // Start new dialog turn (sets state to Processing internally)
         // Pass frontend turnId, generate if not provided
         let turn_id = self
             .session_manager
-            .start_dialog_turn_with_prepended_messages(
+            .start_dialog_turn_with_prepended_messages_if_session_matches(
                 &session_id,
                 effective_agent_type.clone(),
                 effective_user_input.clone(),
@@ -5608,8 +6120,25 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
                 image_contexts,
                 prepended_messages,
                 user_message_metadata.clone(),
+                &admission_facts,
             )
             .await?;
+        if let Some(turn_mode) = permission_mode_from_metadata(user_message_metadata.as_ref()) {
+            // A one-off selection is mutable runtime state for this exact turn,
+            // not a frozen submission property. Each model round reads the
+            // latest value and the turn guard removes it on every exit path.
+            if !self.session_manager.set_active_turn_permission_mode(
+                &session_id,
+                &turn_id,
+                turn_mode,
+            ) {
+                self.session_manager
+                    .reset_session_state_if_processing(&session_id, &turn_id);
+                return Err(BitFunError::Session(format!(
+                    "Failed to install active turn permission mode: session_id={session_id}, turn_id={turn_id}"
+                )));
+            }
+        }
         start_memory_startup_task(MemoryStartupRequest {
             session_id: session_id.clone(),
             session_kind: session.kind,
@@ -5743,15 +6272,43 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
             "edit_constraint_revocation_authorized".to_string(),
             revocation_authorized.to_string(),
         );
+        // The coordinator persists and emits exactly one terminal cancellation
+        // kind after settlement: ordinary Cancelled or recoverable Interrupted.
+        context_vars.insert(
+            "cancel_lifecycle_owner".to_string(),
+            "coordinator".to_string(),
+        );
 
         // Pass model_id for token usage tracking
         if let Some(model_id) = &session.config.model_id {
             context_vars.insert("model_name".to_string(), model_id.clone());
         }
-
-        // Pass snapshot session ID
-        if let Some(snapshot_id) = &session.snapshot_session_id {
-            context_vars.insert("snapshot_session_id".to_string(), snapshot_id.clone());
+        context_vars.insert(
+            INTERRUPTED_TURN_RESOLVED_MODEL_ID_METADATA_KEY.to_string(),
+            resolved_model_id,
+        );
+        context_vars.insert(
+            INTERRUPTED_TURN_MODEL_BINDING_FINGERPRINT_METADATA_KEY.to_string(),
+            resolved_model_binding_fingerprint,
+        );
+        context_vars.insert(
+            INTERRUPTED_TURN_REASONING_PRESET_METADATA_KEY.to_string(),
+            serde_json::to_string(&resolved_reasoning_preset)
+                .expect("Option<String> reasoning preset must serialize"),
+        );
+        context_vars.insert(
+            INTERRUPTED_TURN_REASONING_SELECTION_METADATA_KEY.to_string(),
+            serde_json::to_string(&reasoning_preset)
+                .expect("Option<String> reasoning selection must serialize"),
+        );
+        context_vars.insert(
+            INTERRUPTED_TURN_REASONING_FINGERPRINT_METADATA_KEY.to_string(),
+            resolved_reasoning_fingerprint,
+        );
+
+        // Pass snapshot session ID
+        if let Some(snapshot_id) = &session.snapshot_session_id {
+            context_vars.insert("snapshot_session_id".to_string(), snapshot_id.clone());
         }
 
         // Pass turn_index (for operation history/rollback)
@@ -5805,19 +6362,6 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
                 auto_approve_ask.to_string(),
             );
         }
-        // Resolve the permission mode once per submission. Downstream rounds and
-        // delegated subagents read this value instead of re-resolving the layers
-        // with partial context, so a mid-turn configuration or session change
-        // cannot split one turn across two modes.
-        let submission_permission_mode = resolve_submission_permission_mode(
-            permission_mode_from_metadata(user_message_metadata.as_ref()),
-            session.config.permission_mode,
-            default_permission_mode_from_global_config().await,
-        );
-        context_vars.insert(
-            PERMISSION_MODE_CONTEXT_KEY.to_string(),
-            submission_permission_mode.mode.as_str().to_string(),
-        );
         if needs_computer_links_for_source(submission_policy.trigger_source) {
             context_vars.insert(
                 TOOL_CONTEXT_REMOTE_FILE_DELIVERY_KEY.to_string(),
@@ -5877,7 +6421,9 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
                 .unwrap_or_default();
             tokio::spawn(async move {
                 let allow_ai = is_ai_session_title_generation_enabled().await;
-                let resolved = sm.resolve_session_title(&msg, Some(20), allow_ai).await;
+                let resolved = sm
+                    .resolve_session_title(&sid, &msg, Some(20), allow_ai)
+                    .await;
 
                 match sm
                     .update_session_title_if_current(&sid, &expected_title, &resolved.title)
@@ -5917,6 +6463,8 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
         let runtime_agent_type_clone = runtime_agent_type;
         let user_message_metadata_clone = user_message_metadata;
         let scheduler_notify_tx = self.scheduler_notify_tx.get().cloned();
+        let interrupted_turn_intents = Arc::clone(&self.interrupted_turn_intents);
+        let interrupted_turn_key = turn_stop_key(&session_id, &turn_id);
 
         tokio::spawn(async move {
             // Keep the exact approved external prompt/tool/permission/model
@@ -5962,6 +6510,11 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
                     // synchronously reset to Idle so the user is never stuck.
                     self.session_manager
                         .reset_session_state_if_processing(&self.session_id, &self.turn_id);
+                    // Clear after the state transition. This ordering prevents
+                    // an overlapping API update from validating Processing
+                    // immediately after cleanup and publishing a stale entry.
+                    self.session_manager
+                        .clear_active_turn_permission_mode(&self.session_id, &self.turn_id);
                 }
             }
 
@@ -6008,62 +6561,599 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
             {
                 Ok(execution_result) => Some(
                     Self::persist_completed_dialog_turn(
+                        event_queue.as_ref(),
                         session_manager.as_ref(),
                         scheduler_notify_tx.as_ref(),
                         &session_id_clone,
                         &turn_id_clone,
                         &execution_result,
+                        None,
                     )
                     .await
                     .0,
                 ),
                 Err(e) => {
+                    let generation_messages = execution_engine
+                        .take_generation_messages(&session_id_clone, &turn_id_clone);
                     if matches!(&e, BitFunError::Cancelled(_)) {
+                        if interrupted_turn_intent_is_pending(
+                            interrupted_turn_intents.as_ref(),
+                            &interrupted_turn_key,
+                        ) {
+                            Some(
+                                Self::persist_interrupted_dialog_turn(
+                                    event_queue.as_ref(),
+                                    session_manager.as_ref(),
+                                    scheduler_notify_tx.as_ref(),
+                                    &session_id_clone,
+                                    &turn_id_clone,
+                                    &generation_messages,
+                                    Some(interrupted_turn_intents.as_ref()),
+                                )
+                                .await,
+                            )
+                        } else {
+                            Some(
+                                Self::persist_cancelled_dialog_turn_with_messages(
+                                    event_queue.as_ref(),
+                                    session_manager.as_ref(),
+                                    scheduler_notify_tx.as_ref(),
+                                    &session_id_clone,
+                                    &turn_id_clone,
+                                    true,
+                                    &generation_messages,
+                                )
+                                .await,
+                            )
+                        }
+                    } else {
                         Some(
-                            Self::persist_cancelled_dialog_turn(
+                            Self::persist_failed_dialog_turn(
                                 event_queue.as_ref(),
                                 session_manager.as_ref(),
                                 scheduler_notify_tx.as_ref(),
                                 &session_id_clone,
                                 &turn_id_clone,
+                                &e,
                                 true,
                             )
                             .await,
                         )
+                    }
+                }
+            };
+
+            Self::finalize_persisted_turn_in_workspace_if_needed(
+                session_manager.as_ref(),
+                &session_id_clone,
+                &turn_id_clone,
+                turn_index,
+                &effective_agent_type_clone,
+                &user_input_for_workspace,
+                session_workspace_path.as_deref(),
+                session_storage_path_for_finalize.as_deref(),
+                workspace_turn_status,
+                user_message_metadata_clone,
+            )
+            .await;
+        });
+        active_registration.disarm();
+
+        Ok(())
+    }
+
+    /// Recover the latest settled interrupted user turn in place.
+    ///
+    /// This is intentionally separate from `start_dialog_turn_internal`: a
+    /// recovery must not rerun prompt-submit hooks, rematerialize references,
+    /// append another user message, or allocate another dialog turn.
+    pub async fn recover_interrupted_dialog_turn(
+        &self,
+        request: &bitfun_runtime_ports::AgentDialogTurnRecoveryRequest,
+    ) -> BitFunResult<bitfun_runtime_ports::AgentDialogTurnRecoveryOutcome> {
+        bitfun_core_types::validate_session_id(&request.session_id)
+            .map_err(BitFunError::Validation)?;
+        bitfun_core_types::validate_session_id(&request.turn_id)
+            .map_err(|message| BitFunError::Validation(format!("Invalid turn_id: {message}")))?;
+        self.ensure_session_runtime_ownership(&request.session_id, None)?;
+
+        let session = self
+            .session_manager
+            .get_session(&request.session_id)
+            .ok_or_else(|| {
+                BitFunError::NotFound(format!("Session not found: {}", request.session_id))
+            })?;
+        if session.kind != SessionKind::Standard {
+            return Err(BitFunError::Validation(
+                "Interrupted turn recovery is supported only for standard user sessions"
+                    .to_string(),
+            ));
+        }
+        if request.remote_connection_id.is_some()
+            || request.remote_ssh_host.is_some()
+            || session.config.remote_connection_id.is_some()
+            || session.config.remote_ssh_host.is_some()
+        {
+            return Err(BitFunError::Validation(
+                "Interrupted turn recovery is unavailable for remote workspaces".to_string(),
+            ));
+        }
+        if let Some(requested_workspace) = request.workspace_path.as_deref() {
+            let matches_session_workspace = session.config.workspace_path.as_deref()
+                == Some(requested_workspace)
+                || session.config.project_workspace_path.as_deref() == Some(requested_workspace);
+            if !matches_session_workspace {
+                return Err(BitFunError::Validation(
+                    "Interrupted turn recovery workspace does not match the session".to_string(),
+                ));
+            }
+        }
+        if !matches!(session.state, SessionState::Idle) {
+            return Err(BitFunError::Validation(format!(
+                "Session must be idle before recovering an interrupted turn: {:?}",
+                session.state
+            )));
+        }
+        let goal_storage_path = self
+            .require_main_session_storage_path(&request.session_id)
+            .await?;
+        if self
+            .thread_goal_store()
+            .get_thread_goal(&request.session_id, goal_storage_path.as_path())
+            .await?
+            .is_some_and(|goal| {
+                matches!(
+                    goal.status,
+                    ThreadGoalStatus::Active | ThreadGoalStatus::Paused
+                )
+            })
+        {
+            return Err(BitFunError::Validation(
+                "Use the Thread Goal controls to resume goal work".to_string(),
+            ));
+        }
+
+        // The interruption event may reach the UI just before the old spawn
+        // drops its tail-write guards. Recovery is strict: never overlap those
+        // writes with a new execution generation.
+        self.ensure_session_execution_drained(&request.session_id, Duration::from_secs(30))
+            .await?;
+
+        let session_workspace = Self::build_workspace_binding(&session.config).await;
+        if session_workspace
+            .as_ref()
+            .is_some_and(WorkspaceBinding::is_remote)
+        {
+            return Err(BitFunError::Validation(
+                "Interrupted turn recovery is unavailable for remote workspaces".to_string(),
+            ));
+        }
+        let primary_agent_binding =
+            Self::resolve_session_primary_agent(&session, &session.agent_type, &session_workspace)
+                .await?;
+        if primary_agent_binding.route_owner != SessionAgentRouteOwner::Local {
+            return Err(BitFunError::Validation(
+                "Interrupted turn recovery is unavailable for externally owned agent routes"
+                    .to_string(),
+            ));
+        }
+        let runtime_agent_type = primary_agent_binding.runtime_agent_key;
+        let external_agent_generation_lease = primary_agent_binding.lease;
+        let workspace_services = Self::build_workspace_services(&session_workspace).await;
+        let persisted_subagent_context = self
+            .load_persisted_subagent_continuation_context(&session)
+            .await;
+        let session_workspace_path = session_workspace
+            .as_ref()
+            .map(|workspace| workspace.root_path_string());
+        let session_storage_path = session_workspace
+            .as_ref()
+            .map(|workspace| workspace.session_storage_dir().to_path_buf());
+        // This is the compare-and-set boundary. After it succeeds, no fallible
+        // preparation remains before the execution is registered and spawned.
+        let plan = self
+            .session_manager
+            .reopen_interrupted_dialog_turn(
+                &request.session_id,
+                &request.turn_id,
+                request.execution_generation,
+            )
+            .await?;
+        info!(
+            "Recovering interrupted dialog turn: session_id={}, turn_id={}, execution_generation={}, resume_count={}",
+            plan.session_id, plan.turn_id, plan.execution_generation, plan.resume_count
+        );
+        // Recovery admission is serialized by the scheduler, but settings may
+        // have changed while the previous generation drained. Re-read the
+        // authoritative Session after the CAS before deriving permission and
+        // execution facts.
+        let session = self
+            .session_manager
+            .get_session(&request.session_id)
+            .unwrap_or(session);
+
+        let original_user_input = plan
+            .user_message_metadata
+            .as_ref()
+            .and_then(|metadata| metadata.get("original_text"))
+            .and_then(serde_json::Value::as_str)
+            .unwrap_or(&plan.user_input)
+            .to_string();
+        let runtime_tool_restrictions = runtime_tool_restrictions_for_session_lifetime(
+            miniapp_agent_run_tool_restrictions(
+                plan.user_message_metadata.as_ref(),
+                session.created_by.as_deref(),
+            ),
+            self.session_manager
+                .is_transient_session(&request.session_id),
+        );
+        let mut context_vars = HashMap::new();
+        context_vars.insert(
+            "max_context_tokens".to_string(),
+            session.config.max_context_tokens.to_string(),
+        );
+        context_vars.insert(
+            "enable_tools".to_string(),
+            session.config.enable_tools.to_string(),
+        );
+        context_vars.insert("original_user_input".to_string(), original_user_input);
+        context_vars.insert("turn_index".to_string(), plan.turn_index.to_string());
+        context_vars.insert(
+            "initial_round_index".to_string(),
+            plan.initial_round_index.to_string(),
+        );
+        context_vars.insert(
+            "edit_constraint_revocation_authorized".to_string(),
+            "false".to_string(),
+        );
+        context_vars.insert(
+            "cancel_lifecycle_owner".to_string(),
+            "coordinator".to_string(),
+        );
+        context_vars.insert(
+            INTERRUPTED_TURN_PERMISSION_MODE_METADATA_KEY.to_string(),
+            plan.resolved_permission_mode.as_str().to_string(),
+        );
+        if let Some(model_id) = &session.config.model_id {
+            context_vars.insert("model_name".to_string(), model_id.clone());
+        }
+        context_vars.insert(
+            INTERRUPTED_TURN_RESOLVED_MODEL_ID_METADATA_KEY.to_string(),
+            plan.resolved_model_id.clone(),
+        );
+        context_vars.insert(
+            INTERRUPTED_TURN_MODEL_BINDING_FINGERPRINT_METADATA_KEY.to_string(),
+            plan.model_binding_fingerprint.clone(),
+        );
+        if let Some(reasoning_value) = plan
+            .user_message_metadata
+            .as_ref()
+            .and_then(|metadata| metadata.get(INTERRUPTED_TURN_REASONING_PRESET_METADATA_KEY))
+        {
+            context_vars.insert(
+                INTERRUPTED_TURN_REASONING_PRESET_METADATA_KEY.to_string(),
+                reasoning_value.to_string(),
+            );
+        }
+        if let Some(reasoning_selection) = plan
+            .user_message_metadata
+            .as_ref()
+            .and_then(|metadata| metadata.get(INTERRUPTED_TURN_REASONING_SELECTION_METADATA_KEY))
+        {
+            context_vars.insert(
+                INTERRUPTED_TURN_REASONING_SELECTION_METADATA_KEY.to_string(),
+                reasoning_selection.to_string(),
+            );
+        }
+        if let Some(reasoning_fingerprint) = plan
+            .user_message_metadata
+            .as_ref()
+            .and_then(|metadata| metadata.get(INTERRUPTED_TURN_REASONING_FINGERPRINT_METADATA_KEY))
+            .and_then(serde_json::Value::as_str)
+        {
+            context_vars.insert(
+                INTERRUPTED_TURN_REASONING_FINGERPRINT_METADATA_KEY.to_string(),
+                reasoning_fingerprint.to_string(),
+            );
+        }
+        if let Some(snapshot_id) = &session.snapshot_session_id {
+            context_vars.insert("snapshot_session_id".to_string(), snapshot_id.clone());
+        }
+        if let Some(user_input_available) = metadata_bool(
+            plan.user_message_metadata.as_ref(),
+            USER_INPUT_AVAILABLE_CONTEXT_KEY,
+        ) {
+            context_vars.insert(
+                USER_INPUT_AVAILABLE_CONTEXT_KEY.to_string(),
+                user_input_available.to_string(),
+            );
+        }
+        if let Some(auto_approve_ask) = metadata_bool(
+            plan.user_message_metadata.as_ref(),
+            AUTO_APPROVE_ASK_CONTEXT_KEY,
+        ) {
+            context_vars.insert(
+                AUTO_APPROVE_ASK_CONTEXT_KEY.to_string(),
+                auto_approve_ask.to_string(),
+            );
+        }
+
+        let execution_context = ExecutionContext {
+            session_id: plan.session_id.clone(),
+            dialog_turn_id: plan.turn_id.clone(),
+            turn_index: plan.turn_index,
+            agent_type: plan.agent_type.clone(),
+            workspace: session_workspace,
+            context: context_vars,
+            subagent_parent_info: persisted_subagent_context.subagent_parent_info,
+            permission_delegation: persisted_subagent_context.permission_delegation,
+            permission_runtime_ceiling: None,
+            delegation_policy: DelegationPolicy::top_level(),
+            runtime_tool_restrictions,
+            workspace_services,
+            terminal_port: self.terminal_port(),
+            remote_exec_port: self.remote_exec_port(),
+            round_injection: self.round_injection_source.get().cloned(),
+            // Recovered terminal lifecycle is published only after the Runtime-owned
+            // Turn payload is durably committed by the coordinator.
+            emit_lifecycle_events: false,
+            recover_partial_on_cancel: false,
+        };
+
+        let active_counter = self
+            .active_turns_per_session
+            .entry(plan.session_id.clone())
+            .or_insert_with(|| Arc::new(AtomicUsize::new(0)))
+            .clone();
+        active_counter.fetch_add(1, Ordering::SeqCst);
+        let turn_settlement_registration = self
+            .turn_settlements
+            .register_accepted(plan.session_id.clone(), plan.turn_id.clone());
+        let cancellation_token = CancellationToken::new();
+        self.execution_engine
+            .register_cancel_token(&plan.turn_id, cancellation_token);
+
+        let session_manager = self.session_manager.clone();
+        let execution_engine = self.execution_engine.clone();
+        let event_queue = self.event_queue.clone();
+        let scheduler_notify_tx = self.scheduler_notify_tx.get().cloned();
+        let interrupted_turn_intents = Arc::clone(&self.interrupted_turn_intents);
+        let interrupted_turn_key = turn_stop_key(&plan.session_id, &plan.turn_id);
+        let session_id = plan.session_id.clone();
+        let turn_id = plan.turn_id.clone();
+        let turn_index = plan.turn_index;
+        let effective_agent_type = plan.agent_type.clone();
+        let user_input = plan.user_input.clone();
+        let user_message_metadata = plan.user_message_metadata.clone();
+        let execution_generation = plan.execution_generation;
+        let messages = plan.messages;
+
+        tokio::spawn(async move {
+            let _external_agent_generation_lease = external_agent_generation_lease;
+            let _turn_settlement_registration = turn_settlement_registration;
+            struct RecoveredExecutionGuard {
+                session_manager: Arc<SessionManager>,
+                session_id: String,
+                turn_id: String,
+                active_counter: Arc<AtomicUsize>,
+            }
+            impl Drop for RecoveredExecutionGuard {
+                fn drop(&mut self) {
+                    self.active_counter.fetch_sub(1, Ordering::SeqCst);
+                    self.session_manager
+                        .reset_session_state_if_processing(&self.session_id, &self.turn_id);
+                    self.session_manager
+                        .clear_active_turn_permission_mode(&self.session_id, &self.turn_id);
+                }
+            }
+            let _guard = RecoveredExecutionGuard {
+                session_manager: session_manager.clone(),
+                session_id: session_id.clone(),
+                turn_id: turn_id.clone(),
+                active_counter,
+            };
+
+            let recovered_dequeue_ack = match event_queue
+                .enqueue_with_legacy_dequeue_ack(
+                    AgenticEvent::DialogTurnRecovered {
+                        session_id: session_id.clone(),
+                        turn_id: turn_id.clone(),
+                        execution_generation,
+                    },
+                    // Preserve FIFO with any normal-priority data already
+                    // queued by the interrupted generation. The frontend keeps
+                    // the Turn quarantined until this fence arrives, so stale
+                    // text/tool events cannot cross into the recovered one.
+                    Some(EventPriority::Normal),
+                )
+                .await
+            {
+                Ok((_, acknowledgement)) => acknowledgement,
+                Err(error) => {
+                    error!(
+                        "Failed to enqueue DialogTurnRecovered fence: session_id={}, turn_id={}, error={}",
+                        session_id, turn_id, error
+                    );
+                    Self::persist_interrupted_dialog_turn(
+                        event_queue.as_ref(),
+                        session_manager.as_ref(),
+                        scheduler_notify_tx.as_ref(),
+                        &session_id,
+                        &turn_id,
+                        &[],
+                        None,
+                    )
+                    .await;
+                    return;
+                }
+            };
+            let fence_failure =
+                match tokio::time::timeout(Duration::from_secs(5), recovered_dequeue_ack.wait())
+                    .await
+                {
+                    Ok(Ok(())) => None,
+                    Ok(Err(error)) => Some(error.to_string()),
+                    Err(_) => Some("timed out waiting for legacy dequeue".to_string()),
+                };
+            if let Some(error) = fence_failure {
+                error!(
+                    "DialogTurnRecovered fence failed before dequeue: session_id={}, turn_id={}, error={}",
+                    session_id, turn_id, error
+                );
+                Self::persist_interrupted_dialog_turn(
+                    event_queue.as_ref(),
+                    session_manager.as_ref(),
+                    scheduler_notify_tx.as_ref(),
+                    &session_id,
+                    &turn_id,
+                    &[],
+                    None,
+                )
+                .await;
+                return;
+            }
+            if let Err(error) = event_queue
+                .enqueue(
+                    AgenticEvent::SessionStateChanged {
+                        session_id: session_id.clone(),
+                        new_state: "processing".to_string(),
+                    },
+                    Some(EventPriority::Normal),
+                )
+                .await
+            {
+                error!(
+                    "Failed to emit recovered SessionStateChanged event: session_id={}, turn_id={}, error={}",
+                    session_id, turn_id, error
+                );
+            }
+
+            let _ = session_manager
+                .update_session_state_for_turn_if_processing(
+                    &session_id,
+                    &turn_id,
+                    SessionState::Processing {
+                        current_turn_id: turn_id.clone(),
+                        phase: ProcessingPhase::Thinking,
+                    },
+                )
+                .await;
+
+            let workspace_turn_status = match execution_engine
+                .execute_dialog_turn(runtime_agent_type, messages, execution_context)
+                .await
+            {
+                Ok(execution_result) => Some(
+                    Self::persist_completed_dialog_turn(
+                        event_queue.as_ref(),
+                        session_manager.as_ref(),
+                        scheduler_notify_tx.as_ref(),
+                        &session_id,
+                        &turn_id,
+                        &execution_result,
+                        Some(execution_generation),
+                    )
+                    .await
+                    .0,
+                ),
+                Err(error) if matches!(&error, BitFunError::Cancelled(_)) => {
+                    let generation_messages =
+                        execution_engine.take_generation_messages(&session_id, &turn_id);
+                    if interrupted_turn_intent_is_pending(
+                        interrupted_turn_intents.as_ref(),
+                        &interrupted_turn_key,
+                    ) {
+                        Some(
+                            Self::persist_interrupted_dialog_turn(
+                                event_queue.as_ref(),
+                                session_manager.as_ref(),
+                                scheduler_notify_tx.as_ref(),
+                                &session_id,
+                                &turn_id,
+                                &generation_messages,
+                                Some(interrupted_turn_intents.as_ref()),
+                            )
+                            .await,
+                        )
                     } else {
                         Some(
-                            Self::persist_failed_dialog_turn(
+                            Self::persist_cancelled_dialog_turn_with_messages_and_policy(
                                 event_queue.as_ref(),
                                 session_manager.as_ref(),
                                 scheduler_notify_tx.as_ref(),
-                                &session_id_clone,
-                                &turn_id_clone,
-                                &e,
+                                &session_id,
+                                &turn_id,
+                                true,
+                                &generation_messages,
                                 true,
                             )
                             .await,
                         )
-                    }
+                    }
+                }
+                Err(error)
+                    if ExecutionEngine::is_frozen_reasoning_contract_error(&error)
+                        || ExecutionEngine::is_frozen_model_contract_error(&error) =>
+                {
+                    let generation_messages =
+                        execution_engine.take_generation_messages(&session_id, &turn_id);
+                    warn!(
+                        "Recovered dialog turn execution contract changed before execution; preserving recovery eligibility: session_id={}, turn_id={}, error={}",
+                        session_id, turn_id, error
+                    );
+                    Some(
+                        Self::persist_interrupted_dialog_turn(
+                            event_queue.as_ref(),
+                            session_manager.as_ref(),
+                            scheduler_notify_tx.as_ref(),
+                            &session_id,
+                            &turn_id,
+                            &generation_messages,
+                            None,
+                        )
+                        .await,
+                    )
+                }
+                Err(error) => {
+                    let generation_messages =
+                        execution_engine.take_generation_messages(&session_id, &turn_id);
+                    Some(
+                        Self::persist_failed_dialog_turn_with_messages(
+                            event_queue.as_ref(),
+                            session_manager.as_ref(),
+                            scheduler_notify_tx.as_ref(),
+                            &session_id,
+                            &turn_id,
+                            &error,
+                            true,
+                            &generation_messages,
+                            true,
+                        )
+                        .await,
+                    )
                 }
             };
 
             Self::finalize_persisted_turn_in_workspace_if_needed(
                 session_manager.as_ref(),
-                &session_id_clone,
-                &turn_id_clone,
+                &session_id,
+                &turn_id,
                 turn_index,
-                &effective_agent_type_clone,
-                &user_input_for_workspace,
+                &effective_agent_type,
+                &user_input,
                 session_workspace_path.as_deref(),
-                session_storage_path_for_finalize.as_deref(),
+                session_storage_path.as_deref(),
                 workspace_turn_status,
-                user_message_metadata_clone,
+                user_message_metadata,
             )
             .await;
         });
-        active_registration.disarm();
 
-        Ok(())
+        Ok(bitfun_runtime_ports::AgentDialogTurnRecoveryOutcome {
+            session_id: plan.session_id,
+            turn_id: plan.turn_id,
+            execution_generation: plan.execution_generation,
+        })
     }
 
     /// P0-8: Wait until all in-flight spawn tasks for this session have
@@ -6244,6 +7334,23 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
             dialog_turn_id,
             true,
             Duration::from_millis(1500),
+            DialogTurnStopDisposition::Cancelled,
+        )
+        .await
+    }
+
+    pub async fn interrupt_dialog_turn(
+        &self,
+        session_id: &str,
+        dialog_turn_id: &str,
+        drain_timeout: Duration,
+    ) -> BitFunResult<()> {
+        self.cancel_dialog_turn_with_descendant_policy(
+            session_id,
+            dialog_turn_id,
+            true,
+            drain_timeout,
+            DialogTurnStopDisposition::Interrupted,
         )
         .await
     }
@@ -6254,12 +7361,83 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
         dialog_turn_id: &str,
         cancel_descendants: bool,
         drain_timeout: Duration,
+        disposition: DialogTurnStopDisposition,
     ) -> BitFunResult<()> {
         info!(
-            "Received cancel request: dialog_turn_id={}, session_id={}, cancel_descendants={}",
-            dialog_turn_id, session_id, cancel_descendants
+            "Received stop request: dialog_turn_id={}, session_id={}, cancel_descendants={}, disposition={:?}",
+            dialog_turn_id, session_id, cancel_descendants, disposition
         );
 
+        if disposition == DialogTurnStopDisposition::Interrupted {
+            let session = self
+                .session_manager
+                .get_session(session_id)
+                .ok_or_else(|| BitFunError::NotFound(format!("Session not found: {session_id}")))?;
+            if session.kind != SessionKind::Standard {
+                return Err(BitFunError::Validation(
+                    "Recoverable interruption is supported only for standard user sessions"
+                        .to_string(),
+                ));
+            }
+            if session.config.remote_connection_id.is_some()
+                || session.config.remote_ssh_host.is_some()
+            {
+                return Err(BitFunError::Validation(
+                    "Recoverable interruption is not available for remote workspaces".to_string(),
+                ));
+            }
+            if session.config.agent_route_owner != SessionAgentRouteOwner::Local {
+                return Err(BitFunError::Validation(
+                    "Recoverable interruption is unavailable for externally owned agent routes"
+                        .to_string(),
+                ));
+            }
+            if !matches!(
+                session.state,
+                SessionState::Processing { ref current_turn_id, .. }
+                    if current_turn_id == dialog_turn_id
+            ) {
+                if session.dialog_turn_ids.last().map(String::as_str) == Some(dialog_turn_id)
+                    && self
+                        .session_manager
+                        .latest_dialog_turn_holds_dispatch(session_id)
+                        .await?
+                {
+                    debug!(
+                        "Ignoring duplicate interruption for an already interrupted turn: session_id={}, turn_id={}",
+                        session_id, dialog_turn_id
+                    );
+                    return Ok(());
+                }
+                return Err(BitFunError::Validation(format!(
+                    "Dialog turn is not the active turn: {dialog_turn_id}"
+                )));
+            }
+            let goal_storage_path = self.require_main_session_storage_path(session_id).await?;
+            if self
+                .thread_goal_store()
+                .get_thread_goal(session_id, goal_storage_path.as_path())
+                .await?
+                .is_some_and(|goal| {
+                    matches!(
+                        goal.status,
+                        ThreadGoalStatus::Active | ThreadGoalStatus::Paused
+                    )
+                })
+            {
+                return Err(BitFunError::Validation(
+                    "Use the Thread Goal controls to pause or resume goal work".to_string(),
+                ));
+            }
+            self.interrupted_turn_intents.insert(
+                turn_stop_key(session_id, dialog_turn_id),
+                InterruptedTurnIntentState::Pending,
+            );
+        } else {
+            self.interrupted_turn_intents
+                .remove(&turn_stop_key(session_id, dialog_turn_id));
+        }
+
         if let Some(control) = self.manual_compaction_controls.get(dialog_turn_id) {
             if !control.try_cancel() && control.commit_started() {
                 info!(
@@ -6283,14 +7461,17 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
         // cancellation still targets the currently processing turn. A delayed
         // cancel request for an older turn must not clear a newer turn.
         debug!("Conditionally updating session state to Idle for cancelled turn");
-        let state_update_result = self
-            .session_manager
-            .update_session_state_for_turn_if_processing(
-                session_id,
-                dialog_turn_id,
-                SessionState::Idle,
-            )
-            .await;
+        let state_update_result = if disposition == DialogTurnStopDisposition::Cancelled {
+            self.session_manager
+                .update_session_state_for_turn_if_processing(
+                    session_id,
+                    dialog_turn_id,
+                    SessionState::Idle,
+                )
+                .await
+        } else {
+            Ok(false)
+        };
 
         // A persistence failure can occur after SessionManager has already
         // changed the in-memory state. Cancellation has been admitted at that
@@ -6372,6 +7553,31 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
                 drain_timeout.as_millis(),
                 session_id, dialog_turn_id, pending
             );
+            if disposition == DialogTurnStopDisposition::Interrupted {
+                let key = turn_stop_key(session_id, dialog_turn_id);
+                // Atomically revoke a still-pending interrupt, or observe that
+                // the execution owner already committed the durable recovery
+                // fact. A separate persistence read leaves a read-to-revoke
+                // race where hard cancellation can overwrite a committed
+                // Interrupted turn while its terminal event is still in flight.
+                if revoke_interrupted_turn_intent_or_observe_commit(
+                    self.interrupted_turn_intents.as_ref(),
+                    &key,
+                ) {
+                    self.interrupted_turn_intents.remove(&key);
+                    info!(
+                        "Interrupted turn committed before execution tail drained: session_id={}, turn_id={}",
+                        session_id, dialog_turn_id
+                    );
+                    return Ok(());
+                }
+                return Err(BitFunError::Timeout(format!(
+                    "Interrupted turn did not settle within {}ms: session_id={}, turn_id={}",
+                    drain_timeout.as_millis(),
+                    session_id,
+                    dialog_turn_id
+                )));
+            }
         } else {
             debug!(
                 "Cancelled turn fully drained: session_id={}, dialog_turn_id={}",
@@ -6379,6 +7585,11 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
             );
         }
 
+        if disposition == DialogTurnStopDisposition::Interrupted {
+            self.interrupted_turn_intents
+                .remove(&turn_stop_key(session_id, dialog_turn_id));
+        }
+
         if let Some(error) = state_update_error {
             return Err(error);
         }
@@ -6425,6 +7636,7 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
             &current_turn_id,
             cancel_descendants,
             drain_timeout,
+            DialogTurnStopDisposition::Cancelled,
         )
         .await?;
 
@@ -6867,6 +8079,141 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
         }
     }
 
+    pub(crate) async fn apply_targeted_session_revert_locked(
+        &self,
+        session_storage_path: &Path,
+        session_id: &str,
+        target_turn_id: &str,
+        expected_storage_turn_index: Option<usize>,
+        expected_catalog_revision: Option<&str>,
+    ) -> BitFunResult<(
+        AgentSessionComposerUpdate,
+        usize,
+        usize,
+        Vec<String>,
+        Vec<String>,
+    )> {
+        let workspace_path = self.local_revert_workspace(session_id)?;
+        let persistence = self.session_manager.persistence_manager();
+        let current = persistence
+            .load_session_revert_state(session_storage_path, session_id)
+            .await?;
+        if current
+            .as_ref()
+            .is_some_and(|state| state.phase != SessionRevertPhase::Staged)
+        {
+            return Err(BitFunError::OutcomeUnknown(format!(
+                "Session rollback requires reconciliation of an unfinished revert: session_id={session_id}"
+            )));
+        }
+        let turns = persistence
+            .load_session_turns(session_storage_path, session_id)
+            .await?;
+        let visible_turns = current
+            .as_ref()
+            .map(|state| {
+                turns
+                    .iter()
+                    .filter(|turn| turn.turn_index < state.boundary_turn)
+                    .cloned()
+                    .collect::<Vec<_>>()
+            })
+            .unwrap_or_else(|| turns.clone());
+        let catalog = persistence
+            .load_session_turn_catalog(
+                session_storage_path,
+                session_id,
+                &visible_turns,
+                visible_turns.len(),
+            )
+            .await?;
+        if expected_catalog_revision.is_some_and(|revision| revision != catalog.revision) {
+            return Err(BitFunError::Validation(format!(
+                "Session rollback target is stale: session_id={session_id}"
+            )));
+        }
+        let target = visible_turns
+            .iter()
+            .find(|turn| turn.turn_id == target_turn_id)
+            .ok_or_else(|| {
+                BitFunError::NotFound(format!(
+                    "Session rollback target was not found: session_id={session_id} turn_id={target_turn_id}"
+                ))
+            })?;
+        if expected_storage_turn_index.is_some_and(|index| index != target.turn_index) {
+            return Err(BitFunError::Validation(format!(
+                "Session rollback target storage identity is stale: session_id={session_id} turn_id={target_turn_id}"
+            )));
+        }
+        let boundary_turn = target.turn_index;
+        let retired_turn_ids = turns
+            .iter()
+            .filter(|turn| turn.turn_index >= boundary_turn)
+            .map(|turn| turn.turn_id.clone())
+            .collect();
+        let transition = resolve_targeted(&turns, target_turn_id, current.as_ref()).ok_or_else(|| {
+            BitFunError::Validation(format!(
+                "Session rollback target is not a user Turn: session_id={session_id} turn_id={target_turn_id}"
+            ))
+        })?;
+        let SessionRevertTransition::Stage {
+            mut state,
+            replacement_prompt,
+            hidden_turn_count,
+        } = transition
+        else {
+            unreachable!("targeted rollback always stages a boundary")
+        };
+        let snapshot_manager =
+            crate::service::snapshot::get_or_create_snapshot_manager(workspace_path.clone(), None)
+                .await
+                .map_err(|error| BitFunError::service(error.to_string()))?;
+
+        state.phase = SessionRevertPhase::Applying;
+        snapshot_manager
+            .prepare_workspace_revert(session_id, &mut state)
+            .await
+            .map_err(|error| BitFunError::service(error.to_string()))?;
+        persistence
+            .save_session_revert_state(session_storage_path, session_id, &state)
+            .await?;
+        let restored_files = snapshot_manager
+            .apply_workspace_revert(session_id, &state)
+            .await
+            .map_err(|error| {
+                BitFunError::OutcomeUnknown(format!(
+                    "Session rollback was staged but workspace reconciliation failed: session_id={session_id}, error={error}"
+                ))
+            })?;
+        self.session_manager
+            .apply_staged_revert_context_locked(session_storage_path, session_id, boundary_turn)
+            .await
+            .map_err(|error| {
+                BitFunError::OutcomeUnknown(format!(
+                    "Session rollback updated the workspace but runtime context reconciliation failed: session_id={session_id}, error={error}"
+                ))
+            })?;
+        state.phase = SessionRevertPhase::Staged;
+        persistence
+            .save_session_revert_state(session_storage_path, session_id, &state)
+            .await?;
+        self.commit_session_revert_locked(session_storage_path, session_id)
+            .await?;
+
+        Ok((
+            replacement_prompt
+                .map(|text| AgentSessionComposerUpdate::Replace { text })
+                .unwrap_or(AgentSessionComposerUpdate::Preserve),
+            hidden_turn_count,
+            boundary_turn,
+            restored_files
+                .into_iter()
+                .map(|path| path.to_string_lossy().into_owned())
+                .collect(),
+            retired_turn_ids,
+        ))
+    }
+
     pub(crate) async fn reconcile_session_revert_locked(
         &self,
         session_storage_path: &Path,
@@ -7830,7 +9177,7 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
             user_input_text,
             created_by,
             subagent_parent_info,
-            context,
+            mut context,
             permission_runtime_ceiling,
             delegation_policy,
             runtime_tool_restrictions,
@@ -7842,6 +9189,10 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
             execution_lease,
             external_generation_lease: _external_generation_lease,
         } = request;
+        context.insert(
+            "cancel_lifecycle_owner".to_string(),
+            "coordinator".to_string(),
+        );
         let prepared_target_session_id = target_session_id.clone();
         let deep_review_run_manifest = context
             .get("deep_review_run_manifest")
@@ -8452,6 +9803,9 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
             SubagentExecutionOutcome::Completed(join_result) => match join_result {
                 Ok(result) => result,
                 Err(error) => {
+                    let _ = self
+                        .execution_engine
+                        .take_generation_messages(&session_id, &dialog_turn_id);
                     let join_error = BitFunError::tool(format!(
                         "Subagent '{}' failed to join: {}",
                         agent_type, error
@@ -8544,6 +9898,10 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
                     }
                 }
 
+                let _ = self
+                    .execution_engine
+                    .take_generation_messages(&session_id, &dialog_turn_id);
+
                 Self::persist_cancelled_dialog_turn(
                     self.event_queue.as_ref(),
                     self.session_manager.as_ref(),
@@ -8617,11 +9975,13 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
                 {
                     Ok(Ok(Ok(exec_result))) => {
                         let (_status, response_text) = Self::persist_completed_dialog_turn(
+                            self.event_queue.as_ref(),
                             self.session_manager.as_ref(),
                             None,
                             &session_id,
                             &dialog_turn_id,
                             &exec_result,
+                            None,
                         )
                         .await;
                         Self::finalize_persisted_turn_in_workspace_if_needed(
@@ -8671,6 +10031,9 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
                         None
                     }
                 };
+                let _ = self
+                    .execution_engine
+                    .take_generation_messages(&session_id, &dialog_turn_id);
 
                 if let Some(mut partial_result) = partial_timeout_result {
                     warn!(
@@ -8747,15 +10110,20 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
         let (workspace_turn_status, response_text) = match result {
             Ok(exec_result) => {
                 Self::persist_completed_dialog_turn(
+                    self.event_queue.as_ref(),
                     self.session_manager.as_ref(),
                     None,
                     &session_id,
                     &dialog_turn_id,
                     &exec_result,
+                    None,
                 )
                 .await
             }
             Err(e) => {
+                let _ = self
+                    .execution_engine
+                    .take_generation_messages(&session_id, &dialog_turn_id);
                 let turn_status = if matches!(&e, BitFunError::Cancelled(_)) {
                     Self::persist_cancelled_dialog_turn(
                         self.event_queue.as_ref(),
@@ -10559,7 +11927,7 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
         let allow_ai = is_ai_session_title_generation_enabled().await;
         let resolved = self
             .session_manager
-            .resolve_session_title(user_message, max_length, allow_ai)
+            .resolve_session_title(session_id, user_message, max_length, allow_ai)
             .await;
 
         self.session_manager
@@ -12357,6 +13725,32 @@ impl bitfun_runtime_ports::AgentTurnCancellationPort for ConversationCoordinator
             requested,
         })
     }
+
+    async fn interrupt_turn(
+        &self,
+        request: bitfun_runtime_ports::AgentTurnInterruptionRequest,
+    ) -> bitfun_runtime_ports::PortResult<bitfun_runtime_ports::AgentTurnInterruptionResult> {
+        let wait_timeout = Duration::from_millis(request.wait_timeout_ms.unwrap_or(30_000));
+        self.interrupt_dialog_turn(&request.session_id, &request.turn_id, wait_timeout)
+            .await
+            .map_err(|error| {
+                bitfun_runtime_ports::PortError::new(
+                    match error {
+                        BitFunError::Validation(_) => {
+                            bitfun_runtime_ports::PortErrorKind::InvalidRequest
+                        }
+                        BitFunError::NotFound(_) => bitfun_runtime_ports::PortErrorKind::NotFound,
+                        _ => bitfun_runtime_ports::PortErrorKind::Backend,
+                    },
+                    error.to_string(),
+                )
+            })?;
+        Ok(bitfun_runtime_ports::AgentTurnInterruptionResult {
+            session_id: request.session_id,
+            turn_id: request.turn_id,
+            requested: true,
+        })
+    }
 }
 
 #[async_trait::async_trait]
@@ -12783,18 +14177,19 @@ fn merge_prepended_messages_for_turn(
 mod tests {
     use super::{
         apply_primary_agent_model_default, btw_session_memory_mode,
-        build_subagent_session_relationship, lineage_active_turn_after_transcript,
-        lineage_post_admission_cancellation_error,
+        build_subagent_session_relationship, commit_interrupted_turn_intent,
+        lineage_active_turn_after_transcript, lineage_post_admission_cancellation_error,
         lineage_session_is_settling_without_active_state, logical_subagent_type_or_runtime,
         merge_prepended_messages_for_turn, normalize_subagent_max_concurrency,
         permission_mode_from_metadata, resolve_agent_session_create_created_by,
         resolve_agent_submission_turn_id, resolve_subagent_model_selection,
-        resolve_submission_permission_mode, runtime_port_error_preserving_message,
-        runtime_session_summary, runtime_tool_restrictions_for_session_lifetime,
-        runtime_transcript_messages_from_turns, session_storage_workspace_locator,
-        turn_review_manifest_for_agent, validate_required_lineage_turns_settled,
-        ActiveSubagentExecution, BackgroundSubagentWaitMode, ContextCompactionOutcome,
-        ConversationCoordinator, ManualCompactionCommitGate, SessionMemoryMode,
+        resolve_submission_permission_mode, revoke_interrupted_turn_intent_or_observe_commit,
+        runtime_port_error_preserving_message, runtime_session_summary,
+        runtime_tool_restrictions_for_session_lifetime, runtime_transcript_messages_from_turns,
+        session_storage_workspace_locator, turn_review_manifest_for_agent,
+        validate_required_lineage_turns_settled, ActiveSubagentExecution,
+        BackgroundSubagentWaitMode, ContextCompactionOutcome, ConversationCoordinator,
+        InterruptedTurnIntentState, ManualCompactionCommitGate, SessionMemoryMode,
         SessionReferenceLocator, SessionRelationshipKind, SubagentExecutionRequest,
         TEST_AGENT_MODEL_DEFAULTS,
     };
@@ -12809,7 +14204,8 @@ mod tests {
     };
     use crate::agentic::events::{AgenticEvent, EventQueue, EventQueueConfig, EventRouter};
     use crate::agentic::execution::{
-        ExecutionEngine, ExecutionEngineConfig, RoundExecutor, StreamProcessor,
+        restrict_recovered_permission_mode, ExecutionEngine, ExecutionEngineConfig, RoundExecutor,
+        StreamProcessor,
     };
     use crate::agentic::goal_mode::thread_goal_patch;
     use crate::agentic::persistence::PersistenceManager;
@@ -12833,6 +14229,50 @@ mod tests {
     use bitfun_runtime_services::test_support::FakeRuntimePort;
     use bitfun_services_core::permission_store::ProjectPermissionSqliteStore;
 
+    #[test]
+    fn interrupted_turn_intent_commit_wins_over_timeout_revocation() {
+        let intents = dashmap::DashMap::new();
+        intents.insert(
+            "session\u{1f}turn".to_string(),
+            InterruptedTurnIntentState::Pending,
+        );
+
+        assert!(commit_interrupted_turn_intent(
+            &intents,
+            "session\u{1f}turn"
+        ));
+        assert!(revoke_interrupted_turn_intent_or_observe_commit(
+            &intents,
+            "session\u{1f}turn"
+        ));
+        assert_eq!(
+            *intents.get("session\u{1f}turn").unwrap(),
+            InterruptedTurnIntentState::Committed
+        );
+    }
+
+    #[test]
+    fn interrupted_turn_timeout_revocation_blocks_late_commit() {
+        let intents = dashmap::DashMap::new();
+        intents.insert(
+            "session\u{1f}turn".to_string(),
+            InterruptedTurnIntentState::Pending,
+        );
+
+        assert!(!revoke_interrupted_turn_intent_or_observe_commit(
+            &intents,
+            "session\u{1f}turn"
+        ));
+        assert!(!commit_interrupted_turn_intent(
+            &intents,
+            "session\u{1f}turn"
+        ));
+        assert_eq!(
+            *intents.get("session\u{1f}turn").unwrap(),
+            InterruptedTurnIntentState::Revoked
+        );
+    }
+
     #[cfg(not(feature = "remote-workspace"))]
     #[tokio::test]
     async fn remote_session_metadata_never_falls_back_to_a_local_workspace_binding() {
@@ -13585,6 +15025,25 @@ mod tests {
         assert_eq!(turn_scoped.source, PermissionModeSource::Turn);
     }
 
+    #[test]
+    fn recovered_permission_never_exceeds_original_or_current_mode() {
+        assert_eq!(
+            restrict_recovered_permission_mode(PermissionMode::FullAccess, PermissionMode::Ask),
+            PermissionMode::Ask
+        );
+        assert_eq!(
+            restrict_recovered_permission_mode(PermissionMode::Ask, PermissionMode::FullAccess),
+            PermissionMode::Ask
+        );
+        assert_eq!(
+            restrict_recovered_permission_mode(
+                PermissionMode::FullAccess,
+                PermissionMode::AutoApprove,
+            ),
+            PermissionMode::AutoApprove
+        );
+    }
+
     #[test]
     fn submission_metadata_mode_accepts_surface_aliases_and_rejects_unknown_values() {
         assert_eq!(
@@ -14370,6 +15829,57 @@ mod tests {
         storage_path
     }
 
+    #[tokio::test]
+    async fn stale_targeted_revert_keeps_an_existing_staged_suffix() {
+        let (coordinator, session_manager) = test_persistent_coordinator();
+        let workspace = tempfile::tempdir().expect("workspace");
+        let session_id = format!("targeted-stale-{}", uuid::Uuid::new_v4());
+        let storage_path =
+            create_staged_two_turn_session(session_manager.as_ref(), workspace.path(), &session_id)
+                .await;
+        let marker_before = session_manager
+            .persistence_manager()
+            .load_session_revert_state(&storage_path, &session_id)
+            .await
+            .expect("load staged marker")
+            .expect("staged marker");
+
+        let error = coordinator
+            .apply_targeted_session_revert_locked(
+                &storage_path,
+                &session_id,
+                "turn-0",
+                Some(0),
+                Some("stale-catalog-revision"),
+            )
+            .await
+            .expect_err("stale target must fail before mutation");
+        assert!(matches!(
+            error,
+            crate::util::errors::BitFunError::Validation(_)
+        ));
+
+        let marker_after = session_manager
+            .persistence_manager()
+            .load_session_revert_state(&storage_path, &session_id)
+            .await
+            .expect("reload staged marker")
+            .expect("staged marker must remain");
+        assert_eq!(marker_after, marker_before);
+        let turns = session_manager
+            .persistence_manager()
+            .load_session_turns(&storage_path, &session_id)
+            .await
+            .expect("load physical turns");
+        assert_eq!(
+            turns
+                .iter()
+                .map(|turn| turn.turn_id.as_str())
+                .collect::<Vec<_>>(),
+            vec!["turn-0", "turn-1"]
+        );
+    }
+
     #[tokio::test]
     async fn staged_revert_is_committed_before_local_and_maintenance_turns() {
         let (coordinator, session_manager) = test_persistent_coordinator();
diff --git a/src/crates/assembly/core/src/agentic/coordination/scheduler.rs b/src/crates/assembly/core/src/agentic/coordination/scheduler.rs
index 976427c178..8a5a80cc99 100644
--- a/src/crates/assembly/core/src/agentic/coordination/scheduler.rs
+++ b/src/crates/assembly/core/src/agentic/coordination/scheduler.rs
@@ -39,15 +39,16 @@ use std::sync::OnceLock;
 use std::time::{Duration, Instant, SystemTime};
 use tokio::sync::mpsc;
 use tokio::sync::oneshot;
+use tokio::sync::Notify;
 use tokio_util::sync::CancellationToken;
 use uuid::Uuid;
 
 use bitfun_agent_runtime::scheduler::{
     build_thread_goal_objective_updated_delivery_plan, build_thread_goal_resumed_delivery_plan,
     resolve_agent_session_reply_action, resolve_background_delivery_action,
-    resolve_background_delivery_injection, resolve_background_delivery_injection_for_turn,
-    resolve_dialog_start_route, resolve_dialog_steering_action,
-    resolve_turn_outcome_lifecycle_plan, ActiveDialogTurn, ActiveDialogTurnStore,
+    resolve_background_delivery_injection, resolve_dialog_start_route,
+    resolve_dialog_steering_action, resolve_turn_outcome_lifecycle_plan,
+    target_background_delivery_injection_to_turn, ActiveDialogTurn, ActiveDialogTurnStore,
     ActiveDialogTurnTakeResult, AgentSessionReplyAction, AgentSessionReplyPlan,
     BackgroundDeliveryAction, BackgroundDeliveryFacts, BackgroundInjectionKind,
     DialogReplySuppressionSet, DialogStartRoute, DialogStartRouteFacts, DialogSteeringAction,
@@ -336,8 +337,11 @@ pub struct DialogScheduler {
     retired_maintenance_outcomes: Arc<DialogReplySuppressionSet>,
     /// Set when the user cancels an in-flight turn; aborts goal-continuation submit retries.
     goal_continuation_abort: Arc<SessionAbortFlags>,
+    /// Wakes recovery admission after the previous execution generation has
+    /// retired from the authoritative active-turn table.
+    active_turn_retired: Arc<Notify>,
     /// Cloneable sender given to ConversationCoordinator for turn outcome notifications
-    outcome_tx: mpsc::Sender<(String, TurnOutcome)>,
+    outcome_tx: mpsc::UnboundedSender<(String, TurnOutcome)>,
     /// Per-session FIFO buffer of round injections drained at round boundaries
     /// by the engine and injected into the running dialog turn.
     round_injection_buffer: Arc<SessionRoundInjectionBuffer>,
@@ -374,6 +378,32 @@ fn take_active_turn_for_outcome(
     }
 }
 
+struct RecoveryActiveTurnAdmission {
+    active_turns: Arc<ActiveDialogTurnStore>,
+    active_turn_retired: Arc<Notify>,
+    session_id: String,
+    turn_id: String,
+    armed: bool,
+}
+
+impl RecoveryActiveTurnAdmission {
+    fn disarm(&mut self) {
+        self.armed = false;
+    }
+}
+
+impl Drop for RecoveryActiveTurnAdmission {
+    fn drop(&mut self) {
+        if !self.armed {
+            return;
+        }
+        let _ = self
+            .active_turns
+            .take_for_outcome(&self.session_id, &self.turn_id);
+        self.active_turn_retired.notify_waiters();
+    }
+}
+
 fn queued_submission_outcome(
     session_id: String,
     resolved_turn_id: String,
@@ -401,7 +431,10 @@ impl DialogScheduler {
         coordinator: Arc<ConversationCoordinator>,
         session_manager: Arc<SessionManager>,
     ) -> Arc<Self> {
-        let (outcome_tx, outcome_rx) = mpsc::channel(128);
+        // Turn outcomes are lifecycle control messages, not bulk data. They
+        // must never be dropped or back-pressured behind the interrupt RPC:
+        // retirement of the active-turn owner depends on their delivery.
+        let (outcome_tx, outcome_rx) = mpsc::unbounded_channel();
         let round_injection_buffer = Arc::new(SessionRoundInjectionBuffer::default());
         let round_injection_source = Arc::new(SchedulerRoundInjectionSource {
             buffer: round_injection_buffer.clone(),
@@ -417,6 +450,7 @@ impl DialogScheduler {
             suppressed_cancelled_replies: Arc::new(DialogReplySuppressionSet::default()),
             retired_maintenance_outcomes: Arc::new(DialogReplySuppressionSet::default()),
             goal_continuation_abort: Arc::new(SessionAbortFlags::default()),
+            active_turn_retired: Arc::new(Notify::new()),
             outcome_tx,
             round_injection_buffer,
             round_injection_source,
@@ -432,7 +466,7 @@ impl DialogScheduler {
     }
 
     /// Returns a sender to give to ConversationCoordinator for turn outcome notifications.
-    pub fn outcome_sender(&self) -> mpsc::Sender<(String, TurnOutcome)> {
+    pub fn outcome_sender(&self) -> mpsc::UnboundedSender<(String, TurnOutcome)> {
         self.outcome_tx.clone()
     }
 
@@ -460,10 +494,16 @@ impl DialogScheduler {
         turn_id: String,
         content: String,
         display_content: Option<String>,
+        attachments: Vec<AgentInputAttachment>,
+        metadata: serde_json::Map<String, serde_json::Value>,
     ) -> Result<DialogSteerOutcome, String> {
-        if content.trim().is_empty() {
+        if content.trim().is_empty() && attachments.is_empty() {
             return Err("Steering content cannot be empty".to_string());
         }
+        // Reject a malformed attachment here rather than at the round boundary:
+        // the caller is still holding the user's message and can surface the
+        // failure, whereas the injection consumer would have to drop it.
+        agent_dialog_turn_image_contexts(&attachments).map_err(|error| error.to_string())?;
         let _operation_guard = self.lock_session_operation(&session_id).await;
         let active_turn_id = match self
             .session_manager
@@ -488,6 +528,8 @@ impl DialogScheduler {
             &turn_id,
             content,
             display_content,
+            attachments,
+            metadata,
             steering_id,
             SystemTime::now(),
         ) {
@@ -525,6 +567,7 @@ impl DialogScheduler {
         goal: ThreadGoal,
     ) -> Result<(), String> {
         let plan = build_thread_goal_resumed_delivery_plan(&goal);
+        let operation_guard = self.lock_session_operation(&session_id).await;
         let state = self
             .session_manager
             .get_session(&session_id)
@@ -534,19 +577,33 @@ impl DialogScheduler {
             session_state: Self::session_state_fact(state.as_ref()),
         }) {
             BackgroundDeliveryAction::InjectIntoRunningTurn => {
+                let Some(current_turn_id) = state.as_ref().and_then(|state| match state {
+                    SessionState::Processing {
+                        current_turn_id, ..
+                    } => Some(current_turn_id.clone()),
+                    _ => None,
+                }) else {
+                    return Err(format!(
+                        "Thread goal resume resolved to injection without an active turn: session_id={session_id}"
+                    ));
+                };
                 self.round_injection_buffer.push(
                     &session_id,
-                    resolve_background_delivery_injection(
-                        BackgroundInjectionKind::ThreadGoalObjectiveUpdated,
-                        Uuid::new_v4().to_string(),
-                        plan.injection_prompt,
-                        Some(plan.injection_display),
-                        SystemTime::now(),
+                    target_background_delivery_injection_to_turn(
+                        resolve_background_delivery_injection(
+                            BackgroundInjectionKind::ThreadGoalObjectiveUpdated,
+                            Uuid::new_v4().to_string(),
+                            plan.injection_prompt,
+                            Some(plan.injection_display),
+                            SystemTime::now(),
+                        ),
+                        current_turn_id,
                     ),
                 );
                 Ok(())
             }
             BackgroundDeliveryAction::SubmitAgentSessionFollowUp { queue_priority } => {
+                drop(operation_guard);
                 let prepended = thread_goal_delivery_messages(plan.prepended_reminders);
                 self.submit_with_prepended_messages(
                     session_id,
@@ -580,6 +637,7 @@ impl DialogScheduler {
         goal: ThreadGoal,
     ) -> Result<(), String> {
         let plan = build_thread_goal_objective_updated_delivery_plan(&goal);
+        let operation_guard = self.lock_session_operation(&session_id).await;
         let state = self
             .session_manager
             .get_session(&session_id)
@@ -589,19 +647,33 @@ impl DialogScheduler {
             session_state: Self::session_state_fact(state.as_ref()),
         }) {
             BackgroundDeliveryAction::InjectIntoRunningTurn => {
+                let Some(current_turn_id) = state.as_ref().and_then(|state| match state {
+                    SessionState::Processing {
+                        current_turn_id, ..
+                    } => Some(current_turn_id.clone()),
+                    _ => None,
+                }) else {
+                    return Err(format!(
+                        "Thread goal update resolved to injection without an active turn: session_id={session_id}"
+                    ));
+                };
                 self.round_injection_buffer.push(
                     &session_id,
-                    resolve_background_delivery_injection(
-                        BackgroundInjectionKind::ThreadGoalObjectiveUpdated,
-                        Uuid::new_v4().to_string(),
-                        plan.injection_prompt,
-                        Some(plan.injection_display),
-                        SystemTime::now(),
+                    target_background_delivery_injection_to_turn(
+                        resolve_background_delivery_injection(
+                            BackgroundInjectionKind::ThreadGoalObjectiveUpdated,
+                            Uuid::new_v4().to_string(),
+                            plan.injection_prompt,
+                            Some(plan.injection_display),
+                            SystemTime::now(),
+                        ),
+                        current_turn_id,
                     ),
                 );
                 Ok(())
             }
             BackgroundDeliveryAction::SubmitAgentSessionFollowUp { queue_priority } => {
+                drop(operation_guard);
                 let prepended = thread_goal_delivery_messages(plan.prepended_reminders);
                 self.submit_with_prepended_messages(
                     session_id,
@@ -690,12 +762,14 @@ impl DialogScheduler {
                     ));
                 };
                 let injection_id = Uuid::new_v4().to_string();
-                let injection = resolve_background_delivery_injection_for_turn(
-                    BackgroundInjectionKind::BackgroundResult,
-                    injection_id.clone(),
-                    delivery.content.clone(),
-                    delivery.display_content.clone(),
-                    SystemTime::now(),
+                let injection = target_background_delivery_injection_to_turn(
+                    resolve_background_delivery_injection(
+                        BackgroundInjectionKind::BackgroundResult,
+                        injection_id.clone(),
+                        delivery.content.clone(),
+                        delivery.display_content.clone(),
+                        SystemTime::now(),
+                    ),
                     current_turn_id,
                 );
                 self.round_injection_buffer.push(&session_id, injection);
@@ -1020,6 +1094,28 @@ impl DialogScheduler {
             .map_err(SchedulerSubmitError::Port)
     }
 
+    async fn restore_missing_session_before_admission(
+        &self,
+        session_id: &str,
+        requested_storage_path: &Path,
+    ) -> Result<Option<crate::agentic::core::Session>, SchedulerSubmitError> {
+        if self.session_manager.get_session(session_id).is_some() {
+            return Ok(None);
+        }
+        match self
+            .coordinator
+            .restore_session_from_storage_path(requested_storage_path, session_id)
+            .await
+        {
+            Ok(session) => Ok(Some(session)),
+            Err(BitFunError::NotFound(_)) => {
+                // A genuinely new Session has no persisted state to restore.
+                Ok(None)
+            }
+            Err(error) => Err(SchedulerSubmitError::Core(error)),
+        }
+    }
+
     async fn submit_queued_turn(
         &self,
         session_id: String,
@@ -1053,6 +1149,16 @@ impl DialogScheduler {
                 queued_turn.remote_ssh_host.as_deref(),
             )
             .await?;
+            if let Some(restored_session) = self
+                .restore_missing_session_before_admission(&session_id, &requested_storage_path)
+                .await?
+            {
+                queued_turn.workspace_path = session_storage_workspace_locator(
+                    queued_turn.workspace_path.as_deref(),
+                    restored_session.config.workspace_path.as_deref(),
+                    restored_session.config.project_workspace_path.as_deref(),
+                );
+            }
             self.session_manager
                 .validate_session_storage_path_binding(&session_id, &requested_storage_path)
                 .map_err(SchedulerSubmitError::Core)?;
@@ -1061,7 +1167,25 @@ impl DialogScheduler {
             .session_manager
             .get_session(&session_id)
             .map(|s| s.state.clone());
-        let state_fact = if self.active_turns.contains(&session_id) {
+        let mut interrupted_hold = matches!(state, Some(SessionState::Idle))
+            && self
+                .session_manager
+                .latest_dialog_turn_holds_dispatch(&session_id)
+                .await
+                .map_err(SchedulerSubmitError::Core)?;
+        let interrupted_turn_to_abandon = if interrupted_hold
+            && !matches!(
+                queued_turn.policy.trigger_source,
+                DialogTriggerSource::AgentSession | DialogTriggerSource::ScheduledJob
+            ) {
+            interrupted_hold = false;
+            self.session_manager
+                .get_session(&session_id)
+                .and_then(|session| session.dialog_turn_ids.last().cloned())
+        } else {
+            None
+        };
+        let state_fact = if self.active_turns.contains(&session_id) || interrupted_hold {
             DialogSessionStateFact::Processing
         } else {
             Self::session_state_fact(state.as_ref())
@@ -1106,6 +1230,18 @@ impl DialogScheduler {
         match action {
             DialogSubmitQueueAction::StartImmediately => {
                 let tid = self.start_turn(&session_id, &queued_turn).await?;
+                if let Err(error) = self
+                    .abandon_superseded_interrupted_turn(
+                        &session_id,
+                        interrupted_turn_to_abandon.as_deref(),
+                    )
+                    .await
+                {
+                    warn!(
+                        "Failed to clear superseded interrupted turn after starting new user work: session_id={}, error={}",
+                        session_id, error
+                    );
+                }
                 queued_turn.accept_settlement();
                 self.record_last_submitted_agent_type(&session_id, &queued_turn.agent_type)
                     .await;
@@ -1118,6 +1254,18 @@ impl DialogScheduler {
             DialogSubmitQueueAction::ClearQueueAndStartImmediately => {
                 let _ = self.clear_queue(&session_id).await;
                 let tid = self.start_turn(&session_id, &queued_turn).await?;
+                if let Err(error) = self
+                    .abandon_superseded_interrupted_turn(
+                        &session_id,
+                        interrupted_turn_to_abandon.as_deref(),
+                    )
+                    .await
+                {
+                    warn!(
+                        "Failed to clear superseded interrupted turn after starting new user work: session_id={}, error={}",
+                        session_id, error
+                    );
+                }
                 queued_turn.accept_settlement();
                 self.record_last_submitted_agent_type(&session_id, &queued_turn.agent_type)
                     .await;
@@ -1129,6 +1277,12 @@ impl DialogScheduler {
 
             DialogSubmitQueueAction::EnqueueThenStartNext => {
                 self.enqueue(&session_id, queued_turn.clone())?;
+                self.abandon_interrupted_turn_after_enqueue(
+                    &session_id,
+                    &resolved_turn_id,
+                    interrupted_turn_to_abandon.as_deref(),
+                )
+                .await?;
                 queued_turn.accept_settlement();
                 self.record_last_submitted_agent_type(&session_id, &queued_turn.agent_type)
                     .await;
@@ -1141,6 +1295,12 @@ impl DialogScheduler {
             DialogSubmitQueueAction::EnqueueForActiveTurn => {
                 let accepted_agent_type = queued_turn.agent_type.clone();
                 self.enqueue(&session_id, queued_turn.clone())?;
+                self.abandon_interrupted_turn_after_enqueue(
+                    &session_id,
+                    &resolved_turn_id,
+                    interrupted_turn_to_abandon.as_deref(),
+                )
+                .await?;
                 queued_turn.accept_settlement();
                 self.record_last_submitted_agent_type(&session_id, &accepted_agent_type)
                     .await;
@@ -1152,6 +1312,46 @@ impl DialogScheduler {
         }
     }
 
+    async fn abandon_superseded_interrupted_turn(
+        &self,
+        session_id: &str,
+        interrupted_turn_id: Option<&str>,
+    ) -> BitFunResult<()> {
+        let Some(interrupted_turn_id) = interrupted_turn_id else {
+            return Ok(());
+        };
+        if let Some(abandoned_turn_id) = self
+            .session_manager
+            .abandon_interrupted_dialog_turn(session_id, Some(interrupted_turn_id))
+            .await?
+        {
+            self.round_injection_buffer
+                .drain_for_turn(session_id, &abandoned_turn_id);
+        }
+        Ok(())
+    }
+
+    async fn abandon_interrupted_turn_after_enqueue(
+        &self,
+        session_id: &str,
+        queued_turn_id: &str,
+        interrupted_turn_id: Option<&str>,
+    ) -> Result<(), SchedulerSubmitError> {
+        if let Err(error) = self
+            .abandon_superseded_interrupted_turn(session_id, interrupted_turn_id)
+            .await
+        {
+            if let Some(removed_turn) =
+                remove_queued_turn_by_id(&self.queues, session_id, queued_turn_id)
+            {
+                self.finish_removed_queued_turn(session_id, removed_turn)
+                    .await;
+            }
+            return Err(SchedulerSubmitError::Core(error));
+        }
+        Ok(())
+    }
+
     async fn record_last_submitted_agent_type(&self, session_id: &str, agent_type: &str) {
         if let Err(error) = self
             .coordinator
@@ -1231,6 +1431,28 @@ impl DialogScheduler {
         }
 
         if !self.active_turns.matches_turn(session_id, turn_id) {
+            if self
+                .session_manager
+                .abandon_interrupted_dialog_turn(session_id, Some(turn_id))
+                .await
+                .map_err(|error| error.to_string())?
+                .is_some()
+            {
+                self.round_injection_buffer
+                    .drain_for_turn(session_id, turn_id);
+                self.coordinator
+                    .emit_event(AgenticEvent::DialogTurnCancelled {
+                        session_id: session_id.to_string(),
+                        turn_id: turn_id.to_string(),
+                    })
+                    .await;
+                if let Err(error) = self.try_start_next_queued_locked(session_id).await {
+                    warn!(
+                        "Failed to dispatch held queue after abandoning interrupted turn: session_id={}, turn_id={}, error={}",
+                        session_id, turn_id, error
+                    );
+                }
+            }
             debug!(
                 "Ignoring cancellation for a turn that is not active in the requested session: session_id={}, turn_id={}",
                 session_id, turn_id
@@ -1241,6 +1463,34 @@ impl DialogScheduler {
         self.coordinator
             .cancel_dialog_turn(session_id, turn_id)
             .await?;
+        // The coordinator may have committed an Interrupted recovery fact
+        // while this hard-cancel request was waiting for the active execution
+        // to drain. Always attempt the generation-aware abandon after the
+        // drain so the result does not depend on whether the scheduler outcome
+        // retired the active projection first. Ordinary Cancelled turns return
+        // None, making this an idempotent no-op.
+        if self
+            .session_manager
+            .abandon_interrupted_dialog_turn(session_id, Some(turn_id))
+            .await
+            .map_err(|error| error.to_string())?
+            .is_some()
+        {
+            self.round_injection_buffer
+                .drain_for_turn(session_id, turn_id);
+            self.coordinator
+                .emit_event(AgenticEvent::DialogTurnCancelled {
+                    session_id: session_id.to_string(),
+                    turn_id: turn_id.to_string(),
+                })
+                .await;
+            if let Err(error) = self.try_start_next_queued_locked(session_id).await {
+                warn!(
+                    "Failed to dispatch held queue after hard cancellation abandoned interrupted recovery: session_id={}, turn_id={}, error={}",
+                    session_id, turn_id, error
+                );
+            }
+        }
         Ok(false)
     }
 
@@ -1449,8 +1699,11 @@ impl DialogScheduler {
         requested_storage_path: &std::path::Path,
         wait_timeout: Duration,
     ) -> BitFunResult<SessionMaintenancePermit> {
-        self.begin_session_maintenance(session_id, requested_storage_path, wait_timeout)
-            .await
+        let permit = self
+            .begin_session_maintenance(session_id, requested_storage_path, wait_timeout)
+            .await?;
+        self.round_injection_buffer.clear(session_id);
+        Ok(permit)
     }
 
     fn retire_active_turn_for_maintenance(&self, session_id: &str) -> Option<String> {
@@ -1459,6 +1712,7 @@ impl DialogScheduler {
         };
         let turn_id = active_turn.turn_id().to_string();
         self.retired_maintenance_outcomes.mark(session_id, &turn_id);
+        self.active_turn_retired.notify_waiters();
         self.active_internal_turns.remove(session_id);
         self.round_injection_buffer
             .drain_for_turn(session_id, &turn_id);
@@ -1567,6 +1821,13 @@ impl DialogScheduler {
         if matches!(state, Some(SessionState::Processing { .. })) {
             return Ok(None);
         }
+        if self
+            .session_manager
+            .latest_dialog_turn_holds_dispatch(session_id)
+            .await?
+        {
+            return Ok(None);
+        }
 
         let Some(next_turn) = self.dequeue_next(session_id) else {
             return Ok(None);
@@ -1786,18 +2047,14 @@ impl DialogScheduler {
                 .cleanup_prepared_hidden_subagent_session_if_unsubmitted(&execution.request)
                 .await;
             // This path can run while the caller holds the session operation
-            // permit. Never await the bounded outcome channel here: its
-            // receiver may be waiting for the same permit.
-             tauri::async_runtime::spawn(async move {
-                let _ = outcome_tx
-                    .send((
-                        session_id_owned,
-                        TurnOutcome::Cancelled {
-                            turn_id: turn_id_for_task,
-                        },
-                    ))
-                    .await;
-            });
+            // permit. The lifecycle channel is unbounded so retirement never
+            // waits for the receiver to acquire that same permit.
+            let _ = outcome_tx.send((
+                session_id_owned,
+                TurnOutcome::Cancelled {
+                    turn_id: turn_id_for_task,
+                },
+            ));
             result_tx.send(Err(BitFunError::Cancelled(
                 "Subagent task has been cancelled".to_string(),
             )));
@@ -1855,39 +2112,33 @@ impl DialogScheduler {
                 .await;
             match outcome {
                 Ok(result) => {
-                    let _ = outcome_tx
-                        .send((
-                            session_id_owned.clone(),
-                            TurnOutcome::Completed {
-                                turn_id: turn_id_for_task.clone(),
-                                final_response: result.text.clone(),
-                            },
-                        ))
-                        .await;
+                    let _ = outcome_tx.send((
+                        session_id_owned.clone(),
+                        TurnOutcome::Completed {
+                            turn_id: turn_id_for_task.clone(),
+                            final_response: result.text.clone(),
+                        },
+                    ));
                     result_tx.send(Ok(result));
                 }
                 Err(BitFunError::Cancelled(error_text)) => {
-                    let _ = outcome_tx
-                        .send((
-                            session_id_owned.clone(),
-                            TurnOutcome::Cancelled {
-                                turn_id: turn_id_for_task.clone(),
-                            },
-                        ))
-                        .await;
+                    let _ = outcome_tx.send((
+                        session_id_owned.clone(),
+                        TurnOutcome::Cancelled {
+                            turn_id: turn_id_for_task.clone(),
+                        },
+                    ));
                     result_tx.send(Err(BitFunError::Cancelled(error_text)));
                 }
                 Err(error) => {
                     let error_text = error.to_string();
-                    let _ = outcome_tx
-                        .send((
-                            session_id_owned.clone(),
-                            TurnOutcome::Failed {
-                                turn_id: turn_id_for_task.clone(),
-                                error: error_text.clone(),
-                            },
-                        ))
-                        .await;
+                    let _ = outcome_tx.send((
+                        session_id_owned.clone(),
+                        TurnOutcome::Failed {
+                            turn_id: turn_id_for_task.clone(),
+                            error: error_text.clone(),
+                        },
+                    ));
                     result_tx.send(Err(error));
                 }
             }
@@ -1951,7 +2202,10 @@ impl DialogScheduler {
     }
 
     /// Background loop that receives turn outcome notifications from the coordinator.
-    async fn run_outcome_handler(&self, mut outcome_rx: mpsc::Receiver<(String, TurnOutcome)>) {
+    async fn run_outcome_handler(
+        &self,
+        mut outcome_rx: mpsc::UnboundedReceiver<(String, TurnOutcome)>,
+    ) {
         while let Some((session_id, outcome)) = outcome_rx.recv().await {
             let (active_turn, active_internal_turn, lifecycle_plan) = {
                 let _operation_guard = self.lock_session_operation(&session_id).await;
@@ -1972,7 +2226,10 @@ impl DialogScheduler {
                     continue;
                 };
                 let active_turn = match active_turn_result {
-                    ActiveDialogTurnTakeResult::Matched(turn) => Some(turn),
+                    ActiveDialogTurnTakeResult::Matched(turn) => {
+                        self.active_turn_retired.notify_waiters();
+                        Some(turn)
+                    }
                     ActiveDialogTurnTakeResult::Absent => None,
                     ActiveDialogTurnTakeResult::DifferentTurn => {
                         self.round_injection_buffer
@@ -2013,6 +2270,9 @@ impl DialogScheduler {
             if lifecycle_plan.drain_finished_turn_injections {
                 self.round_injection_buffer
                     .drain_for_turn(&session_id, outcome.turn_id());
+            } else if status == TurnOutcomeStatus::Interrupted {
+                self.round_injection_buffer
+                    .discard_current_running(&session_id);
             }
             let suppressed_cancelled_reply =
                 self.take_suppressed_cancelled_reply(&session_id, outcome.turn_id());
@@ -2052,6 +2312,14 @@ impl DialogScheduler {
                             outcome.turn_id()
                         );
                         }
+                        GoalContinuationAfterTurnAction::AbortForInterrupted => {
+                            self.goal_continuation_abort.mark(&session_id);
+                            debug!(
+                                "Holding thread goal continuation after interrupted turn: session_id={}, turn_id={}",
+                                session_id,
+                                outcome.turn_id()
+                            );
+                        }
                         GoalContinuationAfterTurnAction::Evaluate { turn_completed } => {
                             self.goal_continuation_abort.clear(&session_id);
                             match self
@@ -2181,6 +2449,33 @@ impl DialogScheduler {
                         );
                     }
                 }
+                TurnOutcomeQueueAction::HoldQueue => {
+                    match self
+                        .session_manager
+                        .latest_dialog_turn_holds_dispatch(&session_id)
+                        .await
+                    {
+                        Ok(true) => debug!(
+                            "Turn interrupted, holding queued messages until recovery or a new user turn: session_id={}",
+                            session_id
+                        ),
+                        Ok(false) => {
+                            // An explicit user submission can abandon recovery
+                            // after the coordinator has settled Idle but before
+                            // this outcome retires the previous active entry.
+                            if let Err(error) = self.dispatch_next_if_idle(&session_id).await {
+                                warn!(
+                                    "Failed to dispatch queue after interrupted hold was released: session_id={}, error={}",
+                                    session_id, error
+                                );
+                            }
+                        }
+                        Err(error) => warn!(
+                            "Failed to verify interrupted queue hold; keeping queued work parked: session_id={}, error={}",
+                            session_id, error
+                        ),
+                    }
+                }
                 TurnOutcomeQueueAction::ClearQueue => {}
             }
         }
@@ -2233,7 +2528,7 @@ fn image_context_metadata(attachment: &AgentInputAttachment) -> Option<serde_jso
     }
 }
 
-fn agent_dialog_turn_image_contexts(
+pub(crate) fn agent_dialog_turn_image_contexts(
     attachments: &[AgentInputAttachment],
 ) -> PortResult<Option<Vec<ImageContextData>>> {
     if attachments.is_empty() {
@@ -2413,18 +2708,23 @@ impl AgentDialogTurnPort for DialogScheduler {
         &self,
         request: AgentDialogSteerRequest,
     ) -> PortResult<DialogSteerOutcome> {
-        let empty_content = request.content.trim().is_empty();
+        // An empty-but-attachment-free message and a malformed attachment are
+        // both bad requests; only a live-turn mismatch means "session in use".
+        let invalid_request = request.content.trim().is_empty() && request.attachments.is_empty()
+            || agent_dialog_turn_image_contexts(&request.attachments).is_err();
         DialogScheduler::buffer_steering(
             self,
             request.session_id,
             request.turn_id,
             request.content,
             request.display_content,
+            request.attachments,
+            request.metadata,
         )
         .await
         .map_err(|error| {
             PortError::new(
-                if empty_content {
+                if invalid_request {
                     PortErrorKind::InvalidRequest
                 } else {
                     PortErrorKind::SessionInUse
@@ -2433,6 +2733,116 @@ impl AgentDialogTurnPort for DialogScheduler {
             )
         })
     }
+
+    async fn recover_interrupted_turn(
+        &self,
+        request: bitfun_runtime_ports::AgentDialogTurnRecoveryRequest,
+    ) -> PortResult<bitfun_runtime_ports::AgentDialogTurnRecoveryOutcome> {
+        let deadline = Instant::now() + Duration::from_secs(30);
+        loop {
+            let mut retired = Box::pin(self.active_turn_retired.notified());
+            retired.as_mut().enable();
+            let operation_guard = self.lock_session_operation(&request.session_id).await;
+            let session = self
+                .session_manager
+                .get_session(&request.session_id)
+                .ok_or_else(|| {
+                    PortError::new(
+                        PortErrorKind::NotFound,
+                        format!("Session not found: {}", request.session_id),
+                    )
+                })?;
+            if !self.active_turns.contains(&request.session_id) {
+                let active_turn = ActiveDialogTurn::new(
+                    request.turn_id.clone(),
+                    request
+                        .workspace_path
+                        .clone()
+                        .or_else(|| session.config.workspace_path.clone())
+                        .or_else(|| session.config.project_workspace_path.clone()),
+                    request.remote_connection_id.clone(),
+                    request.remote_ssh_host.clone(),
+                    session.agent_type.clone(),
+                    String::new(),
+                    None,
+                    DialogSubmissionPolicy::for_source(DialogTriggerSource::DesktopUi),
+                    None,
+                );
+                self.active_turns.insert(&request.session_id, active_turn);
+                let active_admission = RecoveryActiveTurnAdmission {
+                    active_turns: self.active_turns.clone(),
+                    active_turn_retired: self.active_turn_retired.clone(),
+                    session_id: request.session_id.clone(),
+                    turn_id: request.turn_id.clone(),
+                    armed: true,
+                };
+                let coordinator = self.coordinator.clone();
+                let (recovery_tx, recovery_rx) = oneshot::channel();
+                tokio::spawn(async move {
+                    let mut active_admission = active_admission;
+                    let outcome = coordinator.recover_interrupted_dialog_turn(&request).await;
+                    if outcome.is_ok() {
+                        active_admission.disarm();
+                    }
+                    let _ = recovery_tx.send(outcome);
+                    drop(operation_guard);
+                });
+                let outcome = recovery_rx
+                    .await
+                    .map_err(|_| {
+                        PortError::new(
+                            PortErrorKind::OutcomeUnknown,
+                            "Interrupted turn recovery admission ended without an outcome",
+                        )
+                    })?
+                    .map_err(|error| {
+                        PortError::new(
+                            match error {
+                                BitFunError::Validation(_) => PortErrorKind::InvalidRequest,
+                                BitFunError::NotFound(_) => PortErrorKind::NotFound,
+                                BitFunError::Timeout(_) => PortErrorKind::Timeout,
+                                _ => PortErrorKind::Backend,
+                            },
+                            error.to_string(),
+                        )
+                    })?;
+                return Ok(outcome);
+            }
+            if !self
+                .active_turns
+                .matches_turn(&request.session_id, &request.turn_id)
+            {
+                return Err(PortError::new(
+                    PortErrorKind::SessionInUse,
+                    format!(
+                        "A different dialog turn is active: session_id={}, requested_turn_id={}",
+                        request.session_id, request.turn_id
+                    ),
+                ));
+            }
+            if !matches!(session.state, SessionState::Idle) {
+                return Err(PortError::new(
+                    PortErrorKind::SessionInUse,
+                    format!(
+                        "Session is still executing a dialog turn: {}",
+                        request.session_id
+                    ),
+                ));
+            }
+            drop(operation_guard);
+
+            let remaining = deadline.saturating_duration_since(Instant::now());
+            if remaining.is_zero() || tokio::time::timeout(remaining, retired).await.is_err() {
+                return Err(PortError::new(
+                    PortErrorKind::Timeout,
+                    format!(
+                        "Previous interrupted turn generation did not retire in time: session_id={}, turn_id={}",
+                        request.session_id, request.turn_id
+                    ),
+                ));
+            }
+        }
+    }
 }
 
 #[async_trait::async_trait]
@@ -2532,6 +2942,46 @@ impl AgentTurnCancellationPort for DialogScheduler {
             turn_id: cancelled_turn_id,
         })
     }
+
+    async fn interrupt_turn(
+        &self,
+        request: bitfun_runtime_ports::AgentTurnInterruptionRequest,
+    ) -> PortResult<bitfun_runtime_ports::AgentTurnInterruptionResult> {
+        // Serialize the route check with submit/start registration. Without
+        // this guard an AgentSession turn could be spawned just before its
+        // reply route becomes visible in `active_turns` and then be recovered
+        // without the route required to settle its requester.
+        let _operation_guard = self.lock_session_operation(&request.session_id).await;
+        if self
+            .active_turns
+            .matches_agent_session_request(&request.session_id, &request.turn_id)
+        {
+            return Err(PortError::new(
+                PortErrorKind::InvalidRequest,
+                "Agent-session request turns cannot be recoverably interrupted; cancel them instead",
+            ));
+        }
+        let wait_timeout = Duration::from_millis(request.wait_timeout_ms.unwrap_or(30_000));
+        self.coordinator
+            .interrupt_dialog_turn(&request.session_id, &request.turn_id, wait_timeout)
+            .await
+            .map_err(|error| {
+                PortError::new(
+                    match error {
+                        BitFunError::Validation(_) => PortErrorKind::InvalidRequest,
+                        BitFunError::NotFound(_) => PortErrorKind::NotFound,
+                        BitFunError::Timeout(_) => PortErrorKind::Timeout,
+                        _ => PortErrorKind::Backend,
+                    },
+                    error.to_string(),
+                )
+            })?;
+        Ok(bitfun_runtime_ports::AgentTurnInterruptionResult {
+            session_id: request.session_id,
+            turn_id: request.turn_id,
+            requested: true,
+        })
+    }
 }
 
 fn thread_goal_delivery_messages(reminders: Vec<ThreadGoalDeliveryReminder>) -> Vec<Message> {
@@ -2627,11 +3077,18 @@ mod tests {
         compression::{CompressionConfig, ContextCompressor},
         revert::{SessionRevertPhase, SessionRevertState, SESSION_REVERT_SCHEMA_VERSION},
         PromptCachePolicy, SessionContextStore, SessionManagerConfig,
+        TEST_MODEL_RESOLUTION_AI_CONFIG,
     };
     use crate::agentic::tools::registry::ToolRegistry;
     use crate::agentic::tools::{ToolPipeline, ToolStateManager};
+    use crate::infrastructure::ai::reasoning_catalog::reasoning_preset_runtime_fingerprint;
     use crate::infrastructure::PathManager;
-    use bitfun_runtime_ports::{AgentDialogPrependedReminder, AgentInputAttachment, PortErrorKind};
+    use crate::service::config::types::{
+        model_runtime_binding_fingerprint, AIConfig, AIModelConfig,
+    };
+    use bitfun_runtime_ports::{
+        AgentDialogPrependedReminder, AgentInputAttachment, PortErrorKind, ThreadGoalStatus,
+    };
     use tokio::sync::RwLock as TokioRwLock;
 
     #[test]
@@ -2649,6 +3106,17 @@ mod tests {
         Arc<SessionManager>,
         Arc<EventQueue>,
         tempfile::TempDir,
+    ) {
+        test_scheduler_with_persistence(false)
+    }
+
+    fn test_scheduler_with_persistence(
+        enable_persistence: bool,
+    ) -> (
+        Arc<DialogScheduler>,
+        Arc<SessionManager>,
+        Arc<EventQueue>,
+        tempfile::TempDir,
     ) {
         let root = tempfile::tempdir().expect("test root");
         let event_queue = Arc::new(EventQueue::new(EventQueueConfig::default()));
@@ -2664,7 +3132,7 @@ mod tests {
                 max_active_sessions: 100,
                 session_idle_timeout: Duration::from_secs(3600),
                 auto_save_interval: Duration::from_secs(300),
-                enable_persistence: false,
+                enable_persistence,
                 prompt_cache_policy: PromptCachePolicy::default(),
             },
         ));
@@ -2827,6 +3295,11 @@ mod tests {
             .await
             .expect("inject background Bash result");
 
+        let unrelated = scheduler
+            .round_injection_monitor()
+            .take_pending(session_id, "different-turn");
+        assert!(unrelated.is_empty());
+
         let pending = scheduler
             .round_injection_monitor()
             .take_pending(session_id, turn_id);
@@ -2847,25 +3320,185 @@ mod tests {
                 "agentic".to_string(),
                 SessionConfig {
                     workspace_path: Some(workspace.to_string_lossy().into_owned()),
+                    model_id: Some("model-original".to_string()),
                     ..Default::default()
                 },
             )
             .await
             .expect("create parent session");
 
+        TEST_MODEL_RESOLUTION_AI_CONFIG
+            .scope(
+                AIConfig {
+                    models: vec![AIModelConfig {
+                        id: "model-original".to_string(),
+                        name: "model-original".to_string(),
+                        model_name: "model-original".to_string(),
+                        enabled: true,
+                        ..Default::default()
+                    }],
+                    ..Default::default()
+                },
+                scheduler.deliver_background_result(
+                    session_id.to_string(),
+                    "external::opencode::agentic::generation-v1".to_string(),
+                    None,
+                    None,
+                    None,
+                    "Background Bash command completed".to_string(),
+                    None,
+                    None,
+                ),
+            )
+            .await
+            .expect("lifecycle delivery must follow the persisted logical session route");
+    }
+
+    #[tokio::test]
+    async fn restored_interrupted_session_holds_agent_follow_up_queue() {
+        let (scheduler, session_manager, _, root) = test_scheduler_with_persistence(true);
+        let session_id = "evicted-interrupted-session";
+        let turn_id = "interrupted-turn";
+        let workspace = root.path().join("workspace");
+        let model_binding_fingerprint = model_runtime_binding_fingerprint(&AIModelConfig {
+            id: "model-original".to_string(),
+            name: "model-original".to_string(),
+            model_name: "model-original".to_string(),
+            enabled: true,
+            ..Default::default()
+        });
+        std::fs::create_dir_all(&workspace).expect("workspace");
+        session_manager
+            .create_session_with_id(
+                Some(session_id.to_string()),
+                "Interrupted".to_string(),
+                "agentic".to_string(),
+                SessionConfig {
+                    workspace_path: Some(workspace.to_string_lossy().into_owned()),
+                    ..Default::default()
+                },
+            )
+            .await
+            .expect("create session");
+        session_manager
+            .start_dialog_turn(
+                session_id,
+                "agentic".to_string(),
+                "finish this".to_string(),
+                Some(turn_id.to_string()),
+                None,
+                Some(serde_json::json!({
+                    "resolved_permission_mode": "ask",
+                    "runtime_resolved_model_id": "model-original",
+                    "runtime_model_binding_fingerprint": model_binding_fingerprint,
+                    "runtime_reasoning_preset": null,
+                    "runtime_reasoning_selection": null,
+                    "runtime_reasoning_fingerprint": reasoning_preset_runtime_fingerprint(None)
+                })),
+            )
+            .await
+            .expect("start turn");
+        session_manager
+            .mark_dialog_turn_interrupted(session_id, turn_id)
+            .await
+            .expect("interrupt turn");
+        session_manager
+            .update_session_state_for_turn_if_processing(session_id, turn_id, SessionState::Idle)
+            .await
+            .expect("settle session idle");
+        let storage_path = session_manager
+            .effective_session_storage_path(session_id)
+            .await
+            .expect("resolve persisted session storage path");
+        session_manager.evict_loaded_session_for_test(session_id);
+
         scheduler
-            .deliver_background_result(
+            .restore_missing_session_before_admission(session_id, &storage_path)
+            .await
+            .expect("restore persisted session before admission")
+            .expect("persisted session should restore");
+        let mut queued_turn = standard_queued_turn("follow-up-turn");
+        queued_turn.policy = DialogSubmissionPolicy::for_source(DialogTriggerSource::AgentSession);
+        queued_turn.workspace_path = None;
+        let outcome = scheduler
+            .submit_queued_turn(
                 session_id.to_string(),
-                "external::opencode::agentic::generation-v1".to_string(),
-                None,
-                None,
+                "follow-up-turn".to_string(),
+                queued_turn,
+                false,
+            )
+            .await
+            .expect("agent follow-up should be accepted behind the hold");
+
+        assert!(matches!(outcome, DialogSubmitOutcome::Queued { .. }));
+        assert_eq!(scheduler.queue_depth(session_id), 1);
+        assert!(session_manager
+            .latest_dialog_turn_holds_dispatch(session_id)
+            .await
+            .expect("hold should remain durable"));
+    }
+
+    #[tokio::test]
+    async fn running_thread_goal_delivery_targets_the_concrete_turn() {
+        let (scheduler, session_manager, _, root) = test_scheduler();
+        let session_id = "goal-parent-session";
+        let turn_id = "goal-parent-turn";
+        let workspace = root.path().join("workspace");
+        std::fs::create_dir_all(&workspace).expect("workspace");
+        session_manager
+            .create_session_with_id(
+                Some(session_id.to_string()),
+                "Goal parent".to_string(),
+                "agentic".to_string(),
+                SessionConfig {
+                    workspace_path: Some(workspace.to_string_lossy().into_owned()),
+                    ..Default::default()
+                },
+            )
+            .await
+            .expect("create parent session");
+        session_manager
+            .update_session_state(
+                session_id,
+                SessionState::Processing {
+                    current_turn_id: turn_id.to_string(),
+                    phase: ProcessingPhase::Thinking,
+                },
+            )
+            .await
+            .expect("mark goal turn active");
+
+        scheduler
+            .deliver_thread_goal_objective_updated(
+                session_id.to_string(),
+                "agentic".to_string(),
                 None,
-                "Background Bash command completed".to_string(),
                 None,
                 None,
+                ThreadGoal {
+                    goal_id: "goal-1".to_string(),
+                    session_id: session_id.to_string(),
+                    objective: "Finish the task".to_string(),
+                    status: ThreadGoalStatus::Active,
+                    token_budget: None,
+                    tokens_used: 0,
+                    time_used_seconds: 0,
+                    created_at: 1,
+                    updated_at: 2,
+                    auto_continuation_count: 0,
+                },
             )
             .await
-            .expect("lifecycle delivery must follow the persisted logical session route");
+            .expect("inject goal update");
+
+        assert!(scheduler
+            .round_injection_monitor()
+            .take_pending(session_id, "different-turn")
+            .is_empty());
+        let pending = scheduler
+            .round_injection_monitor()
+            .take_pending(session_id, turn_id);
+        assert_eq!(pending.len(), 1);
     }
 
     fn standard_queued_turn(turn_id: &str) -> QueuedTurn {
@@ -2936,6 +3569,62 @@ mod tests {
         );
     }
 
+    #[tokio::test]
+    async fn interrupted_turn_persistently_holds_later_queued_work() {
+        let (scheduler, session_manager, _, root) = test_scheduler_with_persistence(true);
+        let session_id = "interrupted-queue-hold";
+        let turn_id = "turn-interrupted";
+        let workspace = root.path().join("workspace-interrupted-hold");
+        std::fs::create_dir_all(&workspace).expect("workspace");
+        session_manager
+            .create_session_with_id(
+                Some(session_id.to_string()),
+                "Interrupted queue hold".to_string(),
+                "agentic".to_string(),
+                SessionConfig {
+                    workspace_path: Some(workspace.to_string_lossy().into_owned()),
+                    ..Default::default()
+                },
+            )
+            .await
+            .expect("create session");
+        session_manager
+            .start_dialog_turn(
+                session_id,
+                "agentic".to_string(),
+                "original work".to_string(),
+                Some(turn_id.to_string()),
+                None,
+                None,
+            )
+            .await
+            .expect("start turn");
+        session_manager
+            .mark_dialog_turn_interrupted(session_id, turn_id)
+            .await
+            .expect("interrupt turn");
+        session_manager
+            .update_session_state_for_turn_if_processing(session_id, turn_id, SessionState::Idle)
+            .await
+            .expect("settle idle");
+        scheduler
+            .queues
+            .enqueue(
+                session_id,
+                standard_queued_turn("late-background-result"),
+                DialogQueuePriority::Low,
+            )
+            .expect("queue later work");
+
+        let started = scheduler
+            .try_start_next_queued(session_id)
+            .await
+            .expect("hold check should succeed");
+
+        assert!(started.is_none());
+        assert_eq!(scheduler.queue_depth(session_id), 1);
+    }
+
     #[tokio::test]
     async fn maintenance_does_not_release_parent_while_background_child_is_still_running() {
         let (scheduler, session_manager, _, root) = test_scheduler();
@@ -3597,6 +4286,8 @@ mod tests {
                 turn_id.to_string(),
                 "check tests".to_string(),
                 None,
+                Vec::new(),
+                serde_json::Map::new(),
             )
             .await
             .expect_err("stale processing state must not accept steering");
@@ -3619,6 +4310,8 @@ mod tests {
                 turn_id: "turn-1".to_string(),
                 content: "  ".to_string(),
                 display_content: None,
+                attachments: Vec::new(),
+                metadata: serde_json::Map::new(),
             },
         )
         .await
@@ -3646,6 +4339,8 @@ mod tests {
                     turn_id.to_string(),
                     "check tests".to_string(),
                     None,
+                    Vec::new(),
+                    serde_json::Map::new(),
                 )
                 .await
         });
@@ -3714,6 +4409,43 @@ mod tests {
             .matches_turn(session_id, "turn-active"));
     }
 
+    #[tokio::test]
+    async fn session_deletion_clears_injections_retained_for_an_interrupted_turn() {
+        let (scheduler, session_manager, _, root) = test_scheduler();
+        let session_id = "session-delete-interrupted-injections";
+        let storage = root.path().join("workspace-delete-interrupted-injections");
+        session_manager
+            .ensure_session_storage_path(session_id, &storage)
+            .expect("bind session storage");
+        scheduler.round_injection_buffer.push(
+            session_id,
+            target_background_delivery_injection_to_turn(
+                resolve_background_delivery_injection(
+                    BackgroundInjectionKind::BackgroundResult,
+                    "injection-1".to_string(),
+                    "retained result".to_string(),
+                    None,
+                    std::time::SystemTime::now(),
+                ),
+                "turn-interrupted".to_string(),
+            ),
+        );
+        assert_eq!(
+            scheduler.round_injection_buffer.pending_count(session_id),
+            1
+        );
+
+        let _permit = scheduler
+            .begin_session_deletion(session_id, &storage, Duration::ZERO)
+            .await
+            .expect("deletion maintenance should quiesce the idle session");
+
+        assert_eq!(
+            scheduler.round_injection_buffer.pending_count(session_id),
+            0
+        );
+    }
+
     #[tokio::test]
     async fn maintenance_retires_scheduler_state_even_when_core_cancel_returns_a_turn_id() {
         let (scheduler, session_manager, _, root) = test_scheduler();
diff --git a/src/crates/assembly/core/src/agentic/core/message.rs b/src/crates/assembly/core/src/agentic/core/message.rs
index b940b36a08..1bbe0c5b5c 100644
--- a/src/crates/assembly/core/src/agentic/core/message.rs
+++ b/src/crates/assembly/core/src/agentic/core/message.rs
@@ -436,15 +436,31 @@ impl Message {
     }
 
     pub fn internal_reminder(reminder_kind: InternalReminderKind, text: impl Into<String>) -> Self {
+        Self::user(Self::render_internal_reminder(text))
+            .with_semantic_kind(MessageSemanticKind::InternalReminder)
+            .with_internal_reminder_kind(reminder_kind)
+    }
+
+    /// An internal reminder that also carries images — used when a message that
+    /// arrives mid-turn (steering) has attachments, so the model sees the same
+    /// multimodal payload it would have seen at a turn boundary.
+    pub fn internal_reminder_multimodal(
+        reminder_kind: InternalReminderKind,
+        text: impl Into<String>,
+        images: Vec<ImageContextData>,
+    ) -> Self {
+        Self::user_multimodal(Self::render_internal_reminder(text), images)
+            .with_semantic_kind(MessageSemanticKind::InternalReminder)
+            .with_internal_reminder_kind(reminder_kind)
+    }
+
+    fn render_internal_reminder(text: impl Into<String>) -> String {
         let text = text.into();
-        let rendered = if crate::agentic::core::has_prompt_markup(&text) {
+        if crate::agentic::core::has_prompt_markup(&text) {
             text
         } else {
             crate::agentic::core::render_system_reminder(&text)
-        };
-        Self::user(rendered)
-            .with_semantic_kind(MessageSemanticKind::InternalReminder)
-            .with_internal_reminder_kind(reminder_kind)
+        }
     }
 
     pub fn user_multimodal(text: String, images: Vec<ImageContextData>) -> Self {
diff --git a/src/crates/assembly/core/src/agentic/deep_review/AGENTS.md b/src/crates/assembly/core/src/agentic/deep_review/AGENTS.md
index 449fdf91a3..d0e33b581b 100644
--- a/src/crates/assembly/core/src/agentic/deep_review/AGENTS.md
+++ b/src/crates/assembly/core/src/agentic/deep_review/AGENTS.md
@@ -33,7 +33,7 @@ Use the nearest Web UI check for frontend-only behavior. For shared runtime
 behavior, run:
 
 ```bash
-cargo test -p bitfun-core deep_review -- --nocapture
+cargo test -p bitfun-core --no-default-features --features agent-runtime --lib deep_review -- --nocapture
 ```
 
 Also run the relevant Rust or desktop check when the change touches backend
diff --git a/src/crates/assembly/core/src/agentic/execution/execution_engine.rs b/src/crates/assembly/core/src/agentic/execution/execution_engine.rs
index e5a51d2c08..24667717c4 100644
--- a/src/crates/assembly/core/src/agentic/execution/execution_engine.rs
+++ b/src/crates/assembly/core/src/agentic/execution/execution_engine.rs
@@ -13,6 +13,7 @@ use crate::agentic::agents::{
     UserContextPolicy, UserContextSection,
 };
 use crate::agentic::context_profile::{ContextProfilePolicy, ModelCapabilityProfile};
+use crate::agentic::coordination::scheduler::agent_dialog_turn_image_contexts;
 use crate::agentic::core::{
     render_system_reminder, InternalReminderKind, Message, MessageContent, MessageHelper,
     MessageRole, MessageSemanticKind, RequestReasoningTokenPolicy, Session,
@@ -30,6 +31,12 @@ use crate::agentic::image_analysis::{
 use crate::agentic::round_preempt::RoundInjectionKind;
 use crate::agentic::session::{
     ContextCompressor, SessionManager, TokenAnchor, TokenAnchorInput, UserContextCacheIdentity,
+    INTERRUPTED_TURN_MODEL_BINDING_FINGERPRINT_METADATA_KEY,
+    INTERRUPTED_TURN_PERMISSION_MODE_METADATA_KEY,
+    INTERRUPTED_TURN_REASONING_FINGERPRINT_METADATA_KEY,
+    INTERRUPTED_TURN_REASONING_PRESET_METADATA_KEY,
+    INTERRUPTED_TURN_REASONING_SELECTION_METADATA_KEY,
+    INTERRUPTED_TURN_RESOLVED_MODEL_ID_METADATA_KEY,
 };
 use crate::agentic::skill_agent_snapshot::build_skill_agent_tool_listing_sections_from_snapshot;
 use crate::agentic::tools::implementations::{SkillTool, TaskTool};
@@ -41,6 +48,7 @@ use crate::agentic::tools::{
 };
 use crate::agentic::WorkspaceBinding;
 use crate::infrastructure::ai::get_global_ai_client_factory;
+use crate::infrastructure::ai::reasoning_catalog::reasoning_preset_runtime_fingerprint;
 use crate::native_hooks::{self, NativeHookSessionFacts};
 use crate::service::config::get_global_config_service;
 use crate::service::config::types::{
@@ -57,10 +65,13 @@ use crate::util::types::Message as AIMessage;
 use crate::util::types::ToolDefinition;
 use crate::util::{elapsed_ms_u64, truncate_at_char_boundary};
 use bitfun_agent_runtime::output_surface::TOOL_CONTEXT_INLINE_MARKDOWN_IMAGE_DISPLAY_KEY;
+use bitfun_agent_runtime::permission::PERMISSION_MODE_CONTEXT_KEY;
 use bitfun_agent_runtime::remote_file_delivery::TOOL_CONTEXT_REMOTE_FILE_DELIVERY_KEY;
 use bitfun_agent_runtime::thread_goal_tools::ensure_thread_goal_tools;
 use bitfun_ai_adapters::ModelExchangeTraceConfig;
 use bitfun_core_types::SessionModelBindingPolicy;
+use bitfun_runtime_ports::{resolve_permission_mode, PermissionMode, PermissionModeLayers};
+use dashmap::DashMap;
 use log::{debug, error, info, trace, warn};
 use sha2::{Digest, Sha256};
 use std::collections::{HashMap, HashSet};
@@ -68,6 +79,17 @@ use std::path::Path;
 use std::sync::atomic::{AtomicU8, Ordering};
 use std::sync::Arc;
 use tokio_util::sync::CancellationToken;
+
+fn execution_engine_owns_cancel_lifecycle(context: &HashMap<String, String>) -> bool {
+    !super::types::coordinator_owns_cancel_lifecycle(context)
+}
+
+fn initial_round_index(context: &std::collections::HashMap<String, String>) -> usize {
+    context
+        .get("initial_round_index")
+        .and_then(|value| value.parse::<usize>().ok())
+        .unwrap_or(0)
+}
 use tool_runtime::context::PrimaryModelFacts;
 
 fn ensure_primary_session_goal_tools(allowed_tools: &mut Vec<String>, is_subagent: bool) {
@@ -76,6 +98,39 @@ fn ensure_primary_session_goal_tools(allowed_tools: &mut Vec<String>, is_subagen
     }
 }
 
+fn resolve_round_permission_mode(
+    active_turn_mode: Option<PermissionMode>,
+    fixed_context_mode: Option<PermissionMode>,
+    session_mode: Option<PermissionMode>,
+    global_default: PermissionMode,
+) -> PermissionMode {
+    resolve_permission_mode(
+        PermissionModeLayers::new(global_default)
+            .with_session(session_mode)
+            .with_turn(active_turn_mode.or(fixed_context_mode)),
+    )
+    .mode
+}
+
+pub(crate) fn restrict_recovered_permission_mode(
+    original: PermissionMode,
+    current: PermissionMode,
+) -> PermissionMode {
+    const fn rank(mode: PermissionMode) -> u8 {
+        match mode {
+            PermissionMode::Ask => 0,
+            PermissionMode::AutoApprove => 1,
+            PermissionMode::FullAccess => 2,
+        }
+    }
+
+    if rank(current) < rank(original) {
+        current
+    } else {
+        original
+    }
+}
+
 /// Execution engine configuration
 #[derive(Debug, Clone)]
 pub struct ExecutionEngineConfig {
@@ -465,6 +520,7 @@ pub struct ExecutionEngine {
     session_manager: Arc<SessionManager>,
     context_compressor: Arc<ContextCompressor>,
     config: ExecutionEngineConfig,
+    generation_messages: DashMap<(String, String), Vec<Message>>,
 }
 
 impl ExecutionEngine {
@@ -478,6 +534,47 @@ impl ExecutionEngine {
     const FINALIZE_USER_FOLLOWUP: &'static str =
         "Provide a final answer. You MUST not call any tools.";
 
+    async fn context_vars_for_round(
+        &self,
+        base: &HashMap<String, String>,
+        session_id: &str,
+        turn_id: &str,
+    ) -> HashMap<String, String> {
+        let mut context_vars = base.clone();
+        let fixed_context_mode = base
+            .get(PERMISSION_MODE_CONTEXT_KEY)
+            .map(|value| PermissionMode::parse(value).unwrap_or(PermissionMode::Ask));
+        let active_turn_mode = self
+            .session_manager
+            .active_turn_permission_mode(session_id, turn_id);
+        let global_default = match get_global_config_service().await {
+            Ok(service) => service
+                .get_config(None)
+                .await
+                .map(|config: crate::service::config::types::GlobalConfig| {
+                    PermissionMode::from_config(&config.tool_permissions)
+                })
+                .unwrap_or(PermissionMode::Ask),
+            Err(_) => PermissionMode::Ask,
+        };
+        let current = resolve_round_permission_mode(
+            active_turn_mode,
+            fixed_context_mode,
+            self.session_manager.session_permission_mode(session_id),
+            global_default,
+        );
+        let resolved = base
+            .get(INTERRUPTED_TURN_PERMISSION_MODE_METADATA_KEY)
+            .and_then(|value| PermissionMode::parse(value))
+            .map(|original| restrict_recovered_permission_mode(original, current))
+            .unwrap_or(current);
+        context_vars.insert(
+            PERMISSION_MODE_CONTEXT_KEY.to_string(),
+            resolved.as_str().to_string(),
+        );
+        context_vars
+    }
+
     pub fn new(
         round_executor: Arc<RoundExecutor>,
         event_queue: Arc<EventQueue>,
@@ -491,9 +588,24 @@ impl ExecutionEngine {
             session_manager,
             context_compressor,
             config,
+            generation_messages: DashMap::new(),
         }
     }
 
+    fn remember_generation_message(&self, session_id: &str, turn_id: &str, message: &Message) {
+        self.generation_messages
+            .entry((session_id.to_string(), turn_id.to_string()))
+            .or_default()
+            .push(message.clone());
+    }
+
+    pub(crate) fn take_generation_messages(&self, session_id: &str, turn_id: &str) -> Vec<Message> {
+        self.generation_messages
+            .remove(&(session_id.to_string(), turn_id.to_string()))
+            .map(|(_, messages)| messages)
+            .unwrap_or_default()
+    }
+
     fn estimate_request_tokens_internal(
         messages: &[Message],
         tools: Option<&[ToolDefinition]>,
@@ -1014,6 +1126,160 @@ impl ExecutionEngine {
             .unwrap_or_else(|| "auto".to_string())
     }
 
+    fn resolve_model_id_for_turn_selection(
+        ai_config: &crate::service::config::types::AIConfig,
+        configured_model_id: &str,
+        frozen_model_id: Option<&str>,
+    ) -> BitFunResult<String> {
+        if let Some(frozen_model_id) = frozen_model_id
+            .map(str::trim)
+            .filter(|model_id| !model_id.is_empty())
+        {
+            return ai_config
+                .resolve_model_reference(frozen_model_id)
+                .ok_or_else(|| {
+                    BitFunError::Validation(format!(
+                        "Frozen dialog turn model contract is unavailable: {frozen_model_id}"
+                    ))
+                });
+        }
+
+        let resolved_configured_model_id =
+            Self::resolve_configured_model_id(ai_config, configured_model_id);
+        if configured_model_id == "auto"
+            || configured_model_id == "default"
+            || resolved_configured_model_id == "auto"
+        {
+            ai_config.resolve_model_selection("primary").ok_or_else(|| {
+                BitFunError::AIClient(
+                    "Auto dialog turn model could not resolve a concrete primary model".to_string(),
+                )
+            })
+        } else {
+            Ok(resolved_configured_model_id)
+        }
+    }
+
+    fn validate_frozen_reasoning_contract(
+        context: &ExecutionContext,
+        ai_client: &crate::infrastructure::ai::AIClient,
+    ) -> BitFunResult<()> {
+        let Some(expected_value) = context
+            .context
+            .get(INTERRUPTED_TURN_REASONING_PRESET_METADATA_KEY)
+        else {
+            return Ok(());
+        };
+        let expected = serde_json::from_str::<Option<String>>(expected_value).map_err(|error| {
+            BitFunError::Validation(format!(
+                "Frozen dialog turn reasoning contract is malformed: {error}"
+            ))
+        })?;
+        let actual_descriptor = ai_client
+            .selected_reasoning_preset()
+            .or_else(|| ai_client.model_reasoning_preset());
+        let actual = actual_descriptor.map(|preset| preset.id.as_str());
+        if actual != expected.as_deref() {
+            return Err(BitFunError::Validation(format!(
+                "Frozen dialog turn reasoning contract changed before execution: expected={:?}, actual={actual:?}",
+                expected.as_deref(),
+            )));
+        }
+        let expected_fingerprint = context
+            .context
+            .get(INTERRUPTED_TURN_REASONING_FINGERPRINT_METADATA_KEY)
+            .ok_or_else(|| {
+                BitFunError::Validation(
+                    "Frozen dialog turn reasoning contract has no runtime fingerprint".to_string(),
+                )
+            })?;
+        if reasoning_preset_runtime_fingerprint(actual_descriptor) != expected_fingerprint.as_str()
+        {
+            return Err(BitFunError::Validation(
+                "Frozen dialog turn reasoning contract changed before execution: runtime fingerprint mismatch"
+                    .to_string(),
+            ));
+        }
+        Ok(())
+    }
+
+    async fn resolve_reasoning_selection_for_turn(
+        &self,
+        session_id: &str,
+        context: &ExecutionContext,
+    ) -> BitFunResult<Option<String>> {
+        if let Some(frozen_selection) = context
+            .context
+            .get(INTERRUPTED_TURN_REASONING_SELECTION_METADATA_KEY)
+        {
+            return serde_json::from_str::<Option<String>>(frozen_selection).map_err(|error| {
+                BitFunError::Validation(format!(
+                    "Frozen dialog turn reasoning selection is malformed: {error}"
+                ))
+            });
+        }
+
+        self.session_manager
+            .reconcile_session_reasoning_preset_for_turn(session_id, "turn_resolution")
+            .await
+    }
+
+    pub(crate) fn is_frozen_reasoning_contract_error(error: &BitFunError) -> bool {
+        matches!(error, BitFunError::Validation(message) if message.starts_with("Frozen dialog turn reasoning contract changed before execution:"))
+    }
+
+    async fn validate_frozen_model_contract(context: &ExecutionContext) -> BitFunResult<()> {
+        let Some(expected_model_id) = context
+            .context
+            .get(INTERRUPTED_TURN_RESOLVED_MODEL_ID_METADATA_KEY)
+        else {
+            return Ok(());
+        };
+        let expected_fingerprint = context
+            .context
+            .get(INTERRUPTED_TURN_MODEL_BINDING_FINGERPRINT_METADATA_KEY)
+            .ok_or_else(|| {
+                BitFunError::Validation(
+                    "Frozen dialog turn model contract has no binding fingerprint".to_string(),
+                )
+            })?;
+        let ai_config = SessionManager::load_ai_config_for_model_resolution()
+            .await
+            .ok_or_else(|| {
+                BitFunError::Validation(
+                    "Frozen dialog turn model contract cannot be validated because AI configuration is unavailable"
+                        .to_string(),
+                )
+            })?;
+        let canonical_model_id = ai_config
+            .resolve_model_reference(expected_model_id)
+            .ok_or_else(|| {
+                BitFunError::Validation(format!(
+                    "Frozen dialog turn model contract is unavailable: {expected_model_id}"
+                ))
+            })?;
+        let model = ai_config
+            .models
+            .iter()
+            .find(|model| model.enabled && model.id == canonical_model_id)
+            .ok_or_else(|| {
+                BitFunError::Validation(format!(
+                    "Frozen dialog turn model contract is unavailable: {expected_model_id}"
+                ))
+            })?;
+        let actual_fingerprint = model_runtime_binding_fingerprint(model);
+        if actual_fingerprint != expected_fingerprint.as_str() {
+            return Err(BitFunError::Validation(format!(
+                "Frozen dialog turn model contract changed before execution: model_id={expected_model_id}"
+            )));
+        }
+        Ok(())
+    }
+
+    pub(crate) fn is_frozen_model_contract_error(error: &BitFunError) -> bool {
+        matches!(error, BitFunError::Validation(message) if message.starts_with("Frozen dialog turn model contract"))
+    }
+
     async fn resolve_primary_model_context(
         model_id: &str,
         model_binding_policy: SessionModelBindingPolicy,
@@ -1458,17 +1724,16 @@ impl ExecutionEngine {
         workspace: Option<&WorkspaceBinding>,
         original_user_input: &str,
         turn_index: usize,
-    ) -> BitFunResult<String> {
-        let config_service = get_global_config_service().await.map_err(|e| {
-            BitFunError::AIClient(format!(
-                "Failed to get config service for model resolution: {}",
-                e
-            ))
-        })?;
-        let ai_config: crate::service::config::types::AIConfig = config_service
-            .get_config(Some("ai"))
+        frozen_model_id: Option<&str>,
+        frozen_model_binding_fingerprint: Option<&str>,
+    ) -> BitFunResult<(String, String)> {
+        let ai_config = SessionManager::load_ai_config_for_model_resolution()
             .await
-            .unwrap_or_default();
+            .ok_or_else(|| {
+                BitFunError::AIClient(
+                    "Failed to get config service for model resolution".to_string(),
+                )
+            })?;
         if matches!(
             session.config.model_binding_policy,
             SessionModelBindingPolicy::ApprovedImmutable
@@ -1511,7 +1776,7 @@ impl ExecutionEngine {
                     model_id
                 )));
             }
-            return Ok(model_id.to_string());
+            return Ok((model_id.to_string(), expected_fingerprint.to_string()));
         }
 
         let agent_registry = get_agent_registry();
@@ -1527,39 +1792,50 @@ impl ExecutionEngine {
             .filter(|model_id| !model_id.is_empty())
             .map(str::to_string)
             .unwrap_or(fallback_model_id.clone());
-        let resolved_configured_model_id =
-            Self::resolve_configured_model_id(&ai_config, &configured_model_id);
-
-        let model_id = if configured_model_id == "auto"
-            || configured_model_id == "default"
-            || resolved_configured_model_id == "auto"
+        let model_id = Self::resolve_model_id_for_turn_selection(
+            &ai_config,
+            &configured_model_id,
+            frozen_model_id,
+        )?;
+        let model = ai_config
+            .models
+            .iter()
+            .find(|model| model.enabled && model.id == model_id)
+            .ok_or_else(|| {
+                if frozen_model_id.is_some() {
+                    BitFunError::Validation(format!(
+                        "Frozen dialog turn model contract is unavailable: {model_id}"
+                    ))
+                } else {
+                    BitFunError::AIClient(format!(
+                        "Dialog turn model configuration is unavailable: {model_id}"
+                    ))
+                }
+            })?;
+        let model_binding_fingerprint = model_runtime_binding_fingerprint(model);
+        if frozen_model_binding_fingerprint
+            .is_some_and(|expected| expected != model_binding_fingerprint)
         {
-            let fallback_model = "primary";
-            let resolved_model_id = ai_config.resolve_model_selection(fallback_model);
-
-            if let Some(resolved_model_id) = resolved_model_id {
-                info!(
-                    "Auto model resolved without locking session: session_id={}, turn_index={}, user_input_chars={}, strategy={}, resolved_model_id={}",
-                    session.session_id,
-                    turn_index,
-                    original_user_input.chars().count(),
-                    fallback_model,
-                    resolved_model_id
-                );
-
-                resolved_model_id
-            } else {
-                warn!(
-                    "Auto model strategy unresolved, keeping symbolic selector: session_id={}, strategy={}",
-                    session.session_id, fallback_model
-                );
-                fallback_model.to_string()
-            }
-        } else {
-            resolved_configured_model_id
-        };
+            return Err(BitFunError::Validation(format!(
+                "Frozen dialog turn model contract changed before execution: model_id={model_id}"
+            )));
+        }
+        if frozen_model_id.is_some() {
+            info!(
+                "Using frozen dialog turn model: session_id={}, turn_index={}, resolved_model_id={}",
+                session.session_id, turn_index, model_id
+            );
+        } else if configured_model_id == "auto" || configured_model_id == "default" {
+            info!(
+                "Auto model resolved without locking session: session_id={}, turn_index={}, user_input_chars={}, strategy=primary, resolved_model_id={}",
+                session.session_id,
+                turn_index,
+                original_user_input.chars().count(),
+                model_id
+            );
+        }
 
-        Ok(model_id)
+        Ok((model_id, model_binding_fingerprint))
     }
 
     /// Omit from model request: UI-only verification frames and legacy auto desktop snapshots.
@@ -1571,6 +1847,11 @@ impl ExecutionEngine {
         )
     }
 
+    fn is_stale_interrupted_continue(msg: &Message, current_turn_id: &str) -> bool {
+        msg.internal_reminder_kind() == Some(InternalReminderKind::InterruptedContinue)
+            && msg.metadata.turn_id.as_deref() != Some(current_turn_id)
+    }
+
     /// True if this message would contribute at least one image to the model (before pruning).
     fn message_bears_images(msg: &Message) -> bool {
         if Self::skip_message_for_model_send(msg) {
@@ -1635,6 +1916,13 @@ impl ExecutionEngine {
             .session_manager
             .persistent_model_exchange_trace_dir(&input.context.session_id)
             .await;
+        let round_context_vars = self
+            .context_vars_for_round(
+                input.execution_context_vars,
+                &input.context.session_id,
+                &input.context.dialog_turn_id,
+            )
+            .await;
         let round_context = RoundContext {
             session_id: input.context.session_id.clone(),
             subagent_parent_info: input.context.subagent_parent_info.clone(),
@@ -1652,7 +1940,7 @@ impl ExecutionEngine {
             effective_model_name: input.ai_client.config.model.clone(),
             primary_model_facts: input.primary_model_facts.clone(),
             agent_type: input.agent_type,
-            context_vars: input.execution_context_vars.clone(),
+            context_vars: round_context_vars,
             permission_constraints: input.permission_constraints,
             permission_runtime_ceiling: input.context.permission_runtime_ceiling.clone(),
             delegation_policy: input.context.delegation_policy,
@@ -1716,7 +2004,9 @@ impl ExecutionEngine {
                 prepended_reminders_injected = true;
             }
 
-            if Self::skip_message_for_model_send(msg) {
+            if Self::skip_message_for_model_send(msg)
+                || Self::is_stale_interrupted_continue(msg, current_turn_id)
+            {
                 continue;
             }
             let keep_this_message_images = attach_images && keep_image_messages.contains(&msg_idx);
@@ -2177,13 +2467,21 @@ impl ExecutionEngine {
             .get("original_user_input")
             .cloned()
             .unwrap_or_default();
-        let model_id = self
+        let (model_id, _) = self
             .resolve_model_id_for_turn(
                 session,
                 &context.agent_type,
                 context.workspace.as_ref(),
                 &original_user_input,
                 context.turn_index,
+                context
+                    .context
+                    .get(INTERRUPTED_TURN_RESOLVED_MODEL_ID_METADATA_KEY)
+                    .map(String::as_str),
+                context
+                    .context
+                    .get(INTERRUPTED_TURN_MODEL_BINDING_FINGERPRINT_METADATA_KEY)
+                    .map(String::as_str),
             )
             .await?;
 
@@ -2191,8 +2489,7 @@ impl ExecutionEngine {
             BitFunError::AIClient(format!("Failed to get AI client factory: {}", e))
         })?;
         let reasoning_preset = match self
-            .session_manager
-            .reconcile_session_reasoning_preset_for_turn(&session.session_id, "turn_resolution")
+            .resolve_reasoning_selection_for_turn(&session.session_id, context)
             .await
         {
             Ok(reasoning_preset) => reasoning_preset,
@@ -2224,12 +2521,27 @@ impl ExecutionEngine {
                 .get_client_resolved_with_reasoning_preset(&model_id, reasoning_preset.as_deref())
                 .await
         };
-        let ai_client = ai_client_result.map_err(|e| {
-            BitFunError::AIClient(format!(
-                "Failed to get AI client (model_id={}): {}",
-                model_id, e
-            ))
-        })?;
+        let ai_client = match ai_client_result {
+            Ok(ai_client) => ai_client,
+            Err(error) => {
+                if context
+                    .context
+                    .contains_key(INTERRUPTED_TURN_MODEL_BINDING_FINGERPRINT_METADATA_KEY)
+                {
+                    // Re-check the frozen binding after a factory failure so a
+                    // config race is classified as recoverable contract drift,
+                    // while credentials/provider/client construction failures
+                    // remain ordinary execution failures.
+                    Self::validate_frozen_model_contract(context).await?;
+                }
+                return Err(BitFunError::AIClient(format!(
+                    "Failed to get AI client (model_id={}): {}",
+                    model_id, error
+                )));
+            }
+        };
+        Self::validate_frozen_model_contract(context).await?;
+        Self::validate_frozen_reasoning_contract(context, ai_client.as_ref())?;
 
         let primary_model_facts = Self::resolve_primary_model_context(
             &model_id,
@@ -2952,21 +3264,15 @@ impl ExecutionEngine {
         context: ExecutionContext,
     ) -> BitFunResult<ExecutionResult> {
         let start_time = std::time::Instant::now();
-        let initial_count = initial_messages.len();
-
         let dialog_turn_id = context.dialog_turn_id.clone();
+        self.generation_messages
+            .remove(&(context.session_id.clone(), dialog_turn_id.clone()));
 
         info!("Starting dialog turn: dialog_turn_id={}", dialog_turn_id);
 
         // Execute actual logic
         let result = self
-            .execute_dialog_turn_impl(
-                agent_type,
-                initial_messages,
-                context,
-                start_time,
-                initial_count,
-            )
+            .execute_dialog_turn_impl(agent_type, initial_messages, context, start_time)
             .await;
 
         // Cleanup cancellation token
@@ -2988,9 +3294,9 @@ impl ExecutionEngine {
         initial_messages: Vec<Message>,
         context: ExecutionContext,
         start_time: std::time::Instant,
-        initial_count: usize,
     ) -> BitFunResult<ExecutionResult> {
         let dialog_turn_id = context.dialog_turn_id.clone();
+        let initial_count = initial_messages.len();
 
         debug!(
             "Executing dialog turn implementation: dialog_turn_id={}",
@@ -3076,13 +3382,21 @@ impl ExecutionEngine {
             }
         }
 
-        let model_id = self
+        let (model_id, _) = self
             .resolve_model_id_for_turn(
                 &session,
                 &agent_type,
                 context.workspace.as_ref(),
                 &original_user_input,
                 context.turn_index,
+                context
+                    .context
+                    .get(INTERRUPTED_TURN_RESOLVED_MODEL_ID_METADATA_KEY)
+                    .map(String::as_str),
+                context
+                    .context
+                    .get(INTERRUPTED_TURN_MODEL_BINDING_FINGERPRINT_METADATA_KEY)
+                    .map(String::as_str),
             )
             .await?;
         info!(
@@ -3097,8 +3411,7 @@ impl ExecutionEngine {
 
         // Get AI client by model ID
         let reasoning_preset = match self
-            .session_manager
-            .reconcile_session_reasoning_preset_for_turn(&session.session_id, "turn_resolution")
+            .resolve_reasoning_selection_for_turn(&session.session_id, &context)
             .await
         {
             Ok(reasoning_preset) => reasoning_preset,
@@ -3130,12 +3443,23 @@ impl ExecutionEngine {
                 .get_client_resolved_with_reasoning_preset(&model_id, reasoning_preset.as_deref())
                 .await
         };
-        let ai_client = ai_client_result.map_err(|e| {
-            BitFunError::AIClient(format!(
-                "Failed to get AI client (model_id={}): {}",
-                model_id, e
-            ))
-        })?;
+        let ai_client = match ai_client_result {
+            Ok(ai_client) => ai_client,
+            Err(error) => {
+                if context
+                    .context
+                    .contains_key(INTERRUPTED_TURN_MODEL_BINDING_FINGERPRINT_METADATA_KEY)
+                {
+                    Self::validate_frozen_model_contract(&context).await?;
+                }
+                return Err(BitFunError::AIClient(format!(
+                    "Failed to get AI client (model_id={}): {}",
+                    model_id, error
+                )));
+            }
+        };
+        Self::validate_frozen_model_contract(&context).await?;
+        Self::validate_frozen_reasoning_contract(&context, ai_client.as_ref())?;
 
         // Primary model vision capability (tools + system prompt appendix; also used below for API message stripping).
         let primary_model_facts = Self::resolve_primary_model_context(
@@ -3308,8 +3632,12 @@ impl ExecutionEngine {
         // Add System Prompt to the beginning of message list (only for this execution, not persisted)
         let mut messages = vec![turn_prompt_scaffold.system_prompt_message.clone()];
         messages.extend(initial_messages);
+        // Keep this generation's append-only transcript separate from the
+        // mutable request history. Context compression may replace `messages`
+        // wholesale, but durable recovered-Turn completion must still append
+        // every assistant/tool/injection message produced by this generation.
 
-        let mut round_index = 0;
+        let mut round_index = initial_round_index(&context.context);
         let mut completed_rounds = 0usize;
         let mut total_tools = 0;
         let mut last_partial_recovery_reason: Option<String> = None;
@@ -3664,7 +3992,13 @@ impl ExecutionEngine {
             );
 
             // Create round context
-            let round_context_vars = execution_context_vars.clone();
+            let round_context_vars = self
+                .context_vars_for_round(
+                    &execution_context_vars,
+                    &context.session_id,
+                    &context.dialog_turn_id,
+                )
+                .await;
             let loaded_deferred_tool_specs =
                 collect_product_loaded_deferred_tool_specs(&messages, &deferred_tools);
 
@@ -3881,6 +4215,11 @@ impl ExecutionEngine {
 
             // Add assistant message to history
             messages.push(round_result.assistant_message.clone());
+            self.remember_generation_message(
+                &context.session_id,
+                &context.dialog_turn_id,
+                &round_result.assistant_message,
+            );
 
             // Update the in-memory message caches immediately so subsequent rounds see it.
             if let Err(e) = self
@@ -3894,6 +4233,11 @@ impl ExecutionEngine {
             // Add tool result messages to history
             for tool_result_msg in round_result.tool_result_messages.iter() {
                 messages.push(tool_result_msg.clone());
+                self.remember_generation_message(
+                    &context.session_id,
+                    &context.dialog_turn_id,
+                    tool_result_msg,
+                );
 
                 // Update the in-memory message caches immediately so subsequent rounds see it.
                 if let Err(e) = self
@@ -3906,13 +4250,23 @@ impl ExecutionEngine {
             }
 
             #[cfg(feature = "agent-runtime")]
-            activate_conditional_instructions_after_round(
-                self.session_manager.as_ref(),
-                &context,
-                &round_result,
-                &mut messages,
-            )
-            .await;
+            {
+                let previous_message_count = messages.len();
+                activate_conditional_instructions_after_round(
+                    self.session_manager.as_ref(),
+                    &context,
+                    &round_result,
+                    &mut messages,
+                )
+                .await;
+                for message in &messages[previous_message_count..] {
+                    self.remember_generation_message(
+                        &context.session_id,
+                        &context.dialog_turn_id,
+                        message,
+                    );
+                }
+            }
 
             debug!(
                 "Updated round messages in memory: round_index={}, assistant + {} tool results",
@@ -4000,6 +4354,11 @@ impl ExecutionEngine {
                         )
                         .with_turn_id(context.dialog_turn_id.clone());
                         messages.push(user_msg.clone());
+                        self.remember_generation_message(
+                            &context.session_id,
+                            &context.dialog_turn_id,
+                            &user_msg,
+                        );
                         if let Err(e) = self
                             .session_manager
                             .add_message(&context.session_id, user_msg)
@@ -4056,6 +4415,11 @@ impl ExecutionEngine {
                     )
                     .with_turn_id(context.dialog_turn_id.clone());
                     messages.push(user_msg.clone());
+                    self.remember_generation_message(
+                        &context.session_id,
+                        &context.dialog_turn_id,
+                        &user_msg,
+                    );
                     if let Err(e) = self
                         .session_manager
                         .add_message(&context.session_id, user_msg)
@@ -4096,7 +4460,17 @@ impl ExecutionEngine {
                         let wrapped = match injection.kind {
                             RoundInjectionKind::UserSteering => format!(
                                 "<system_reminder>\nThe user sent a new message while this turn was running. You have just finished the previous atomic action; handle this new user message now as the current direction, while preserving the existing conversation and task context. Do not ignore it or wait for a separate future turn.\n\nNew user message:\n{}\n</system_reminder>",
-                                injection.content
+                                // A steering message carries whatever the
+                                // composer carries, so an image-only message is
+                                // legitimate: name the attachment instead of
+                                // injecting empty text.
+                                if injection.content.trim().is_empty()
+                                    && !injection.attachments.is_empty()
+                                {
+                                    "(image attached)"
+                                } else {
+                                    injection.content.as_str()
+                                }
                             ),
                             RoundInjectionKind::BackgroundResult => format!(
                                 "<system_reminder>\nA background task has finished and returned new information while this turn was running. Incorporate it into your current work immediately when relevant. Do not wait for a separate future turn.\n\nBackground result:\n{}\n</system_reminder>",
@@ -4115,9 +4489,33 @@ impl ExecutionEngine {
                                 InternalReminderKind::GoalObjectiveUpdated
                             }
                         };
-                        let user_msg = Message::internal_reminder(reminder_kind, wrapped)
-                            .with_turn_id(context.dialog_turn_id.clone());
+                        // Attachments rebuild into the same multimodal user
+                        // message a turn-boundary submission would have
+                        // produced; a bad payload degrades to text rather than
+                        // dropping the user's steering message entirely.
+                        let images = match agent_dialog_turn_image_contexts(&injection.attachments)
+                        {
+                            Ok(images) => images.unwrap_or_default(),
+                            Err(error) => {
+                                warn!(
+                                    "Dropping unusable steering attachments, injecting text only: session_id={}, steering_id={}, error={}",
+                                    context.session_id, injection_id, error
+                                );
+                                Vec::new()
+                            }
+                        };
+                        let user_msg = if images.is_empty() {
+                            Message::internal_reminder(reminder_kind, wrapped)
+                        } else {
+                            Message::internal_reminder_multimodal(reminder_kind, wrapped, images)
+                        }
+                        .with_turn_id(context.dialog_turn_id.clone());
                         messages.push(user_msg.clone());
+                        self.remember_generation_message(
+                            &context.session_id,
+                            &context.dialog_turn_id,
+                            &user_msg,
+                        );
                         if let Err(e) = self
                             .session_manager
                             .add_message(&context.session_id, user_msg)
@@ -4182,6 +4580,11 @@ impl ExecutionEngine {
                                 )
                                 .with_turn_id(context.dialog_turn_id.clone());
                                 messages.push(user_msg.clone());
+                                self.remember_generation_message(
+                                    &context.session_id,
+                                    &context.dialog_turn_id,
+                                    &user_msg,
+                                );
                                 if let Err(e) = self
                                     .session_manager
                                     .add_message(&context.session_id, user_msg)
@@ -4254,6 +4657,11 @@ impl ExecutionEngine {
                             )
                             .with_turn_id(context.dialog_turn_id.clone());
                             messages.push(user_msg.clone());
+                            self.remember_generation_message(
+                                &context.session_id,
+                                &context.dialog_turn_id,
+                                &user_msg,
+                            );
                             if let Err(e) = self
                                 .session_manager
                                 .add_message(&context.session_id, user_msg)
@@ -4283,6 +4691,11 @@ impl ExecutionEngine {
                     )
                     .with_turn_id(context.dialog_turn_id.clone());
                     messages.push(user_msg.clone());
+                    self.remember_generation_message(
+                        &context.session_id,
+                        &context.dialog_turn_id,
+                        &user_msg,
+                    );
                     if let Err(e) = self
                         .session_manager
                         .add_message(&context.session_id, user_msg)
@@ -4317,7 +4730,9 @@ impl ExecutionEngine {
                     dialog_turn_id
                 );
 
-                if context.emit_lifecycle_events {
+                if context.emit_lifecycle_events
+                    && execution_engine_owns_cancel_lifecycle(&context.context)
+                {
                     self.emit_event(
                         AgenticEvent::DialogTurnCancelled {
                             session_id: context.session_id.clone(),
@@ -4454,6 +4869,11 @@ impl ExecutionEngine {
                             );
                         for anchor_message in finalize_cache_anchor_messages {
                             messages.push(anchor_message.clone());
+                            self.remember_generation_message(
+                                &context.session_id,
+                                &context.dialog_turn_id,
+                                &anchor_message,
+                            );
                             if let Err(e) = self
                                 .session_manager
                                 .add_message(&context.session_id, anchor_message)
@@ -4468,6 +4888,11 @@ impl ExecutionEngine {
                         last_usage = Some(usage);
                     }
                     messages.push(msg.clone());
+                    self.remember_generation_message(
+                        &context.session_id,
+                        &context.dialog_turn_id,
+                        &msg,
+                    );
                     if let Err(e) = self
                         .session_manager
                         .add_message(&context.session_id, msg)
@@ -4509,11 +4934,20 @@ impl ExecutionEngine {
                 success,
             ) {
                 if let Some(workspace) = context.workspace.as_ref() {
-                    bitfun_services_integrations::deep_research::run_for_session_workspace(
-                        workspace.root_path(),
-                        &context.session_id,
-                    )
-                    .await;
+                    if let Some(workspace_services) = context.workspace_services.as_ref() {
+                        bitfun_services_integrations::deep_research::run_for_session_workspace(
+                            workspace_services.fs.as_ref(),
+                            &workspace.root_path().to_string_lossy(),
+                            &context.session_id,
+                        )
+                        .await;
+                    } else {
+                        warn!(
+                            "citation_renumber: skipped because workspace filesystem services are unavailable: session_id={}, workspace={}",
+                            context.session_id,
+                            workspace.root_path().display()
+                        );
+                    }
                 }
             }
         }
@@ -4530,7 +4964,7 @@ impl ExecutionEngine {
                         total_rounds: completed_rounds,
                         total_tools,
                         duration_ms,
-                        partial_recovery_reason: last_partial_recovery_reason,
+                        partial_recovery_reason: last_partial_recovery_reason.clone(),
                         success: Some(success),
                         finish_reason: Some(effective_finish_reason.to_string()),
                         has_final_response: Some(has_final_response),
@@ -4558,30 +4992,35 @@ impl ExecutionEngine {
             warn!("Dialog turn completed but token stats not available");
         }
 
-        // Calculate newly generated messages
-        let safe_initial_count = initial_count.min(messages.len()); // Ensure no out-of-bounds
-        let new_messages = messages[safe_initial_count..].to_vec();
-
-        if safe_initial_count != initial_count {
-            warn!(
-                "initial_count ({}) exceeds messages length ({}), adjusted to {}",
-                initial_count,
-                messages.len(),
-                safe_initial_count
-            );
-        }
-
         Ok(ExecutionResult {
-            final_message: messages
-                .iter()
-                .rev()
-                .find(|message| message.role == MessageRole::Assistant)
-                .cloned()
+            final_message: self
+                .generation_messages
+                .get(&(context.session_id.clone(), context.dialog_turn_id.clone()))
+                .and_then(|generated| {
+                    generated
+                        .iter()
+                        .rev()
+                        .find(|message| message.role == MessageRole::Assistant)
+                        .cloned()
+                })
+                .or_else(|| {
+                    messages
+                        .iter()
+                        .rev()
+                        .find(|message| message.role == MessageRole::Assistant)
+                        .cloned()
+                })
                 .unwrap_or_else(|| Message::assistant(String::new())),
             total_rounds: completed_rounds,
             success,
-            new_messages,
+            new_messages: self
+                .take_generation_messages(&context.session_id, &context.dialog_turn_id),
             finish_reason,
+            total_tools,
+            duration_ms,
+            partial_recovery_reason: last_partial_recovery_reason,
+            effective_finish_reason: effective_finish_reason.to_string(),
+            has_final_response,
         })
     }
 
@@ -4637,8 +5076,8 @@ impl ExecutionEngine {
 mod tests {
     use super::{
         activate_conditional_instructions_after_round, ensure_primary_session_goal_tools,
-        manual_compaction_terminal_error, ContextHealthSnapshot, ExecutionEngine, RoundResult,
-        TurnPromptScaffold,
+        manual_compaction_terminal_error, resolve_round_permission_mode, ContextHealthSnapshot,
+        ExecutionEngine, RoundResult, TurnPromptScaffold,
     };
     use crate::agentic::agents::{
         PrependedPromptReminders, PromptBuilderContext, UserContextPolicy,
@@ -4659,7 +5098,9 @@ mod tests {
     use crate::service::remote_ssh::workspace_state::workspace_session_identity;
     use crate::util::types::ToolDefinition;
     use bitfun_agent_runtime::thread_goal_tools::THREAD_GOAL_TOOL_NAMES;
-    use bitfun_runtime_ports::{WorkspaceDirEntry, WorkspaceFileSystem, WorkspacePathKind};
+    use bitfun_runtime_ports::{
+        PermissionMode, WorkspaceDirEntry, WorkspaceFileSystem, WorkspacePathKind,
+    };
     use serde_json::json;
     use sha2::{Digest, Sha256};
     use std::collections::HashMap;
@@ -4668,6 +5109,46 @@ mod tests {
     use std::sync::Arc;
     use std::time::Duration;
 
+    #[test]
+    fn recovered_execution_starts_after_existing_model_rounds() {
+        let mut context = std::collections::HashMap::new();
+        context.insert("initial_round_index".to_string(), "3".to_string());
+
+        assert_eq!(super::initial_round_index(&context), 3);
+        assert_eq!(
+            super::initial_round_index(&std::collections::HashMap::new()),
+            0
+        );
+    }
+
+    #[test]
+    fn interrupted_continue_reminder_is_visible_only_to_its_own_turn() {
+        let reminder = Message::internal_reminder(
+            InternalReminderKind::InterruptedContinue,
+            "continue the interrupted work".to_string(),
+        )
+        .with_turn_id("turn-interrupted".to_string());
+
+        assert!(!ExecutionEngine::is_stale_interrupted_continue(
+            &reminder,
+            "turn-interrupted"
+        ));
+        assert!(ExecutionEngine::is_stale_interrupted_continue(
+            &reminder, "turn-new"
+        ));
+    }
+
+    #[test]
+    fn coordinator_owned_cancellation_suppresses_early_cancelled_event() {
+        let mut context = std::collections::HashMap::new();
+        assert!(super::execution_engine_owns_cancel_lifecycle(&context));
+        context.insert(
+            super::super::types::CANCEL_LIFECYCLE_OWNER_CONTEXT_KEY.to_string(),
+            "coordinator".to_string(),
+        );
+        assert!(!super::execution_engine_owns_cancel_lifecycle(&context));
+    }
+
     #[test]
     fn primary_session_tool_policy_restores_goal_tools_but_subagents_stay_scoped() {
         let mut primary_tools = vec!["Read".to_string()];
@@ -4681,6 +5162,37 @@ mod tests {
         assert_eq!(subagent_tools, vec!["Read".to_string()]);
     }
 
+    #[test]
+    fn round_permission_mode_prefers_mutable_turn_then_fixed_child_then_session() {
+        assert_eq!(
+            resolve_round_permission_mode(
+                Some(PermissionMode::Ask),
+                Some(PermissionMode::FullAccess),
+                Some(PermissionMode::AutoApprove),
+                PermissionMode::FullAccess,
+            ),
+            PermissionMode::Ask,
+        );
+        assert_eq!(
+            resolve_round_permission_mode(
+                None,
+                Some(PermissionMode::FullAccess),
+                Some(PermissionMode::Ask),
+                PermissionMode::AutoApprove,
+            ),
+            PermissionMode::FullAccess,
+        );
+        assert_eq!(
+            resolve_round_permission_mode(
+                None,
+                None,
+                Some(PermissionMode::AutoApprove),
+                PermissionMode::Ask,
+            ),
+            PermissionMode::AutoApprove,
+        );
+    }
+
     #[test]
     fn manual_compaction_preserves_cancellation_as_a_terminal_cancellation() {
         let error = manual_compaction_terminal_error(crate::BitFunError::Cancelled(
@@ -5240,6 +5752,57 @@ mod tests {
         );
     }
 
+    #[test]
+    fn frozen_turn_model_wins_when_the_auto_default_changes() {
+        let mut ai_config = AIConfig {
+            models: vec![
+                build_model("model-original", "Original", "claude-sonnet-4.5"),
+                build_model("model-new-default", "New default", "gpt-5.4"),
+            ],
+            ..Default::default()
+        };
+        ai_config.default_models.primary = Some("model-new-default".to_string());
+
+        assert_eq!(
+            ExecutionEngine::resolve_model_id_for_turn_selection(
+                &ai_config,
+                "auto",
+                Some("model-original"),
+            )
+            .expect("the original resolved model remains available"),
+            "model-original"
+        );
+    }
+
+    #[test]
+    fn auto_turn_model_must_resolve_to_a_concrete_model_before_persistence() {
+        let ai_config = AIConfig::default();
+
+        let error = ExecutionEngine::resolve_model_id_for_turn_selection(&ai_config, "auto", None)
+            .expect_err("a symbolic selector cannot become the frozen Turn model");
+
+        assert!(error.to_string().contains("primary model"), "{error}");
+    }
+
+    #[test]
+    fn frozen_turn_model_must_still_be_available_for_recovery() {
+        let mut model = build_model("model-original", "Original", "claude-sonnet-4.5");
+        model.enabled = false;
+        let ai_config = AIConfig {
+            models: vec![model],
+            ..Default::default()
+        };
+
+        let error = ExecutionEngine::resolve_model_id_for_turn_selection(
+            &ai_config,
+            "auto",
+            Some("model-original"),
+        )
+        .expect_err("a disabled frozen model cannot execute another generation");
+
+        assert!(error.to_string().contains("unavailable"), "{error}");
+    }
+
     #[test]
     fn auto_compression_pressure_tracks_total_and_conversation_tokens() {
         let messages = vec![
diff --git a/src/crates/assembly/core/src/agentic/execution/round_executor.rs b/src/crates/assembly/core/src/agentic/execution/round_executor.rs
index 31c3199d16..07fc5d1a76 100644
--- a/src/crates/assembly/core/src/agentic/execution/round_executor.rs
+++ b/src/crates/assembly/core/src/agentic/execution/round_executor.rs
@@ -4,7 +4,7 @@
 
 use super::model_exchange_trace::prepare_model_exchange_trace;
 use super::stream_processor::{StreamProcessOptions, StreamProcessor, StreamResult};
-use super::types::{FinishReason, RoundContext, RoundResult};
+use super::types::{coordinator_owns_cancel_lifecycle, FinishReason, RoundContext, RoundResult};
 use crate::agentic::core::{Message, ToolCall};
 use crate::agentic::events::{
     AgenticEvent, EventPriority, EventQueue, ModelRoundAttemptDiagnostic,
@@ -375,7 +375,7 @@ impl RoundExecutor {
             let request_trace_config = trace_config
                 .clone()
                 .map(|config| config.with_round_attempt(attempt_id.clone(), attempt_number));
-            let send_future = ai_client.send_message_stream(
+            let send_future = ai_client.send_message_stream_once(
                 ai_messages.clone(),
                 tool_definitions.clone(),
                 request_trace_config,
@@ -404,27 +404,24 @@ impl RoundExecutor {
                     error!("AI request failed: {}", e);
                     let provider_error = e.downcast_ref::<AiProviderError>().cloned();
                     let err_msg = e.to_string();
-                    let is_structured_context_overflow = provider_error
-                        .as_ref()
-                        .is_some_and(|error| error.category == ErrorCategory::ContextOverflow);
-                    if !is_structured_context_overflow
-                        && Self::is_transient_network_error(&err_msg)
-                        && local_attempt_index < max_attempts - 1
-                    {
+                    if local_attempt_index < max_attempts - 1 {
                         self.record_retry_diagnostic(
                             &context,
                             &round_id,
                             attempt_id.clone(),
                             attempt_number,
-                            "transient_request_error",
+                            "request_error",
                             Some(err_msg.clone()),
                             &[],
                         )
                         .await;
-                        let delay_ms =
-                            Self::retry_delay_ms_for_error(local_attempt_index, &err_msg);
+                        let delay_ms = Self::retry_delay_ms_for_provider_error(
+                            local_attempt_index,
+                            &err_msg,
+                            provider_error.as_ref(),
+                        );
                         warn!(
-                            "Retrying AI request after connection failure: session_id={}, round_id={}, round_attempt={}, local_retry={}/{}, delay_ms={}, error={}",
+                            "Retrying AI request after error: session_id={}, round_id={}, round_attempt={}, local_retry={}/{}, delay_ms={}, error={}",
                             context.session_id,
                             round_id,
                             attempt_number,
@@ -437,19 +434,6 @@ impl RoundExecutor {
                         local_attempt_index += 1;
                         continue;
                     }
-                    if !is_structured_context_overflow && Self::is_transient_network_error(&err_msg)
-                    {
-                        return Err(BitFunError::AIClient(format!(
-                            "Stream retry budget exhausted after {} attempts: {}",
-                            max_attempts, err_msg
-                        )));
-                    }
-                    // Non-transient errors (429 budget exhausted, context
-                    // overflow, auth, etc.) are returned directly. The error
-                    // message is classified downstream via
-                    // `BitFunError::error_category()` into `ErrorCategory` for
-                    // frontend recovery actions (wait_and_retry, switch_model,
-                    // etc.).
                     let category = provider_error
                         .as_ref()
                         .map(|error| error.category.clone())
@@ -466,9 +450,10 @@ impl RoundExecutor {
                         BitFunError::AIClient(err_msg)
                     };
                     warn!(
-                        "AI request terminal failure: session_id={}, round_id={}, category={:?}, error={}",
+                        "AI request retry budget exhausted: session_id={}, round_id={}, attempts={}, category={:?}, error={}",
                         context.session_id,
                         round_id,
+                        max_attempts,
                         error.error_category(),
                         error
                     );
@@ -522,6 +507,9 @@ impl RoundExecutor {
                     StreamProcessOptions {
                         recover_partial_on_cancel: context.recover_partial_on_cancel,
                         allow_normal_tool_json_repair,
+                        suppress_cancel_lifecycle_event: coordinator_owns_cancel_lifecycle(
+                            &context.context_vars,
+                        ),
                         ..Default::default()
                     },
                 )
@@ -529,22 +517,23 @@ impl RoundExecutor {
             {
                 Ok(result) => {
                     let stream_processing_ms = elapsed_ms_u64(stream_started_at);
-                    if Self::has_interrupted_invalid_tool_calls(&result) {
-                        let err_msg = result.partial_recovery_reason.clone().unwrap_or_else(|| {
-                            "Interrupted while streaming tool arguments".to_string()
-                        });
-
-                        if !Self::has_user_visible_assistant_text(&result.full_text)
-                            && local_attempt_index < max_attempts - 1
-                            && Self::is_transient_network_error(&err_msg)
-                        {
+                    let has_interrupted_invalid_tool_calls =
+                        Self::has_interrupted_invalid_tool_calls(&result);
+                    if let Some(partial_recovery_reason) = result.partial_recovery_reason.as_deref()
+                    {
+                        if local_attempt_index < max_attempts - 1 {
+                            let diagnostic_category = if has_interrupted_invalid_tool_calls {
+                                "interrupted_tool_arguments"
+                            } else {
+                                "partial_stream_error"
+                            };
                             self.record_retry_diagnostic(
                                 &context,
                                 &round_id,
                                 attempt_id.clone(),
                                 attempt_number,
-                                "interrupted_tool_arguments",
-                                Some(err_msg.clone()),
+                                diagnostic_category,
+                                Some(partial_recovery_reason.to_string()),
                                 &result.tool_calls,
                             )
                             .await;
@@ -554,31 +543,36 @@ impl RoundExecutor {
                                 Self::trace_response_from_stream_result("partial", &result),
                             )
                             .await;
-                            let delay_ms =
-                                Self::retry_delay_ms_for_error(local_attempt_index, &err_msg);
+                            let delay_ms = Self::retry_delay_ms_for_error(
+                                local_attempt_index,
+                                partial_recovery_reason,
+                            );
                             warn!(
-                                "Retrying stream because tool arguments were interrupted before valid JSON completed: session_id={}, round_id={}, round_attempt={}, local_retry={}/{}, delay_ms={}, invalid_tool_calls={}, error={}",
+                                "Retrying stream after partial recovery error: session_id={}, round_id={}, round_attempt={}, local_retry={}/{}, delay_ms={}, effective_output={}, tool_calls={}, reason={}",
                                 context.session_id,
                                 round_id,
                                 attempt_number,
                                 local_attempt_index + 1,
                                 max_attempts,
                                 delay_ms,
-                                result
-                                    .tool_calls
-                                    .iter()
-                                    .filter(|tool_call| !tool_call.is_valid())
-                                    .count(),
-                                err_msg
+                                result.has_effective_output,
+                                result.tool_calls.len(),
+                                partial_recovery_reason
                             );
                             Self::sleep_with_cancellation(delay_ms, &cancel_token).await?;
                             local_attempt_index += 1;
                             continue;
                         }
+                    }
+
+                    if has_interrupted_invalid_tool_calls {
+                        let err_msg = result.partial_recovery_reason.clone().unwrap_or_else(|| {
+                            "Interrupted while streaming tool arguments".to_string()
+                        });
 
                         if Self::has_user_visible_assistant_text(&result.full_text) {
                             warn!(
-                                "Dropping invalid partial tool calls from interrupted stream; preserving already-streamed assistant text: session_id={}, round_id={}, invalid_tool_calls={}, error={}",
+                                "Dropping invalid partial tool calls after stream retry budget was exhausted; preserving assistant text: session_id={}, round_id={}, invalid_tool_calls={}, error={}",
                                 context.session_id,
                                 round_id,
                                 result
@@ -632,50 +626,6 @@ impl RoundExecutor {
 
                     let no_effective_output = !result.has_effective_output;
                     let is_partial_recovery = result.partial_recovery_reason.is_some();
-                    let partial_recovery_reason =
-                        result.partial_recovery_reason.as_deref().unwrap_or("");
-
-                    if is_partial_recovery
-                        && !Self::has_user_visible_assistant_text(&result.full_text)
-                        && !result.tool_calls.is_empty()
-                        && Self::is_transient_network_error(partial_recovery_reason)
-                        && local_attempt_index < max_attempts - 1
-                    {
-                        self.record_retry_diagnostic(
-                            &context,
-                            &round_id,
-                            attempt_id.clone(),
-                            attempt_number,
-                            "partial_stream_error",
-                            Some(partial_recovery_reason.to_string()),
-                            &result.tool_calls,
-                        )
-                        .await;
-                        Self::complete_model_exchange_trace(
-                            trace_config.as_ref(),
-                            trace_handle.as_ref(),
-                            Self::trace_response_from_stream_result("partial", &result),
-                        )
-                        .await;
-                        let delay_ms = Self::retry_delay_ms_for_error(
-                            local_attempt_index,
-                            partial_recovery_reason,
-                        );
-                        warn!(
-                            "Retrying stream because tool calls arrived on an interrupted network stream without assistant text: session_id={}, round_id={}, round_attempt={}, local_retry={}/{}, delay_ms={}, tool_calls={}, reason={}",
-                            context.session_id,
-                            round_id,
-                            attempt_number,
-                            local_attempt_index + 1,
-                            max_attempts,
-                            delay_ms,
-                            result.tool_calls.len(),
-                            partial_recovery_reason
-                        );
-                        Self::sleep_with_cancellation(delay_ms, &cancel_token).await?;
-                        local_attempt_index += 1;
-                        continue;
-                    }
 
                     if Self::is_invalid_tool_only_without_text(&result) {
                         let err_msg = "Provider returned only invalid tool arguments".to_string();
@@ -739,44 +689,68 @@ impl RoundExecutor {
                         )));
                     }
 
-                    if no_effective_output && local_attempt_index < max_attempts - 1 {
-                        self.record_retry_diagnostic(
-                            &context,
-                            &round_id,
-                            attempt_id.clone(),
-                            attempt_number,
-                            "no_effective_output",
-                            None,
-                            &[],
-                        )
-                        .await;
+                    if no_effective_output {
+                        let err_msg = result
+                            .partial_recovery_reason
+                            .clone()
+                            .unwrap_or_else(|| "No effective output received".to_string());
+                        if local_attempt_index < max_attempts - 1 {
+                            self.record_retry_diagnostic(
+                                &context,
+                                &round_id,
+                                attempt_id.clone(),
+                                attempt_number,
+                                "no_effective_output",
+                                Some(err_msg.clone()),
+                                &result.tool_calls,
+                            )
+                            .await;
+                            Self::complete_model_exchange_trace(
+                                trace_config.as_ref(),
+                                trace_handle.as_ref(),
+                                Self::error_trace_response_from_stream_result(
+                                    "error",
+                                    err_msg.clone(),
+                                    &result,
+                                ),
+                            )
+                            .await;
+                            let delay_ms =
+                                Self::retry_delay_ms_for_error(local_attempt_index, &err_msg);
+                            warn!(
+                                "Retrying stream because no effective output was received: session_id={}, round_id={}, round_attempt={}, local_retry={}/{}, delay_ms={}, error={}",
+                                context.session_id,
+                                round_id,
+                                attempt_number,
+                                local_attempt_index + 1,
+                                max_attempts,
+                                delay_ms,
+                                err_msg
+                            );
+                            Self::sleep_with_cancellation(delay_ms, &cancel_token).await?;
+                            local_attempt_index += 1;
+                            continue;
+                        }
+
                         Self::complete_model_exchange_trace(
                             trace_config.as_ref(),
                             trace_handle.as_ref(),
-                            Self::error_trace_response(
+                            Self::error_trace_response_from_stream_result(
                                 "error",
-                                "No effective output received".to_string(),
+                                err_msg.clone(),
+                                &result,
                             ),
                         )
                         .await;
-                        let delay_ms = Self::retry_delay_ms(local_attempt_index);
-                        warn!(
-                            "Retrying stream because no effective output was received: session_id={}, round_id={}, round_attempt={}, local_retry={}/{}, delay_ms={}",
-                            context.session_id,
-                            round_id,
-                            attempt_number,
-                            local_attempt_index + 1,
-                            max_attempts,
-                            delay_ms
-                        );
-                        Self::sleep_with_cancellation(delay_ms, &cancel_token).await?;
-                        local_attempt_index += 1;
-                        continue;
+                        return Err(BitFunError::AIClient(format!(
+                            "Stream retry budget exhausted after {} attempts: {}",
+                            max_attempts, err_msg
+                        )));
                     }
 
                     if is_partial_recovery {
                         warn!(
-                            "Accepting stream partial recovery without retry: session_id={}, round_id={}, round_attempt={}, local_retry={}/{}, reason={}",
+                            "Accepting useful partial stream output after retry budget was exhausted: session_id={}, round_id={}, round_attempt={}, local_retry={}/{}, reason={}",
                             context.session_id,
                             round_id,
                             attempt_number,
@@ -799,54 +773,59 @@ impl RoundExecutor {
                 Err(stream_err) => {
                     let err_msg = stream_err.error.to_string();
                     let stream_error_category = stream_err.error.error_category();
-                    let can_retry = !stream_err.has_effective_output
-                        && stream_error_category != ErrorCategory::ContextOverflow
-                        && local_attempt_index < max_attempts - 1
-                        && Self::is_transient_network_error(&err_msg);
+                    let provider_error = match &stream_err.error {
+                        BitFunError::AIProvider(error)
+                        | BitFunError::RecoverableContextOverflow(error) => Some(error),
+                        _ => None,
+                    };
                     Self::complete_model_exchange_trace(
                         trace_config.as_ref(),
                         trace_handle.as_ref(),
                         Self::error_trace_response("error", err_msg.clone()),
                     )
                     .await;
-                    if can_retry {
+                    if local_attempt_index < max_attempts - 1 {
                         self.record_retry_diagnostic(
                             &context,
                             &round_id,
                             attempt_id.clone(),
                             attempt_number,
-                            "transient_stream_error",
+                            "stream_error",
                             Some(err_msg.clone()),
                             &[],
                         )
                         .await;
-                        let delay_ms =
-                            Self::retry_delay_ms_for_error(local_attempt_index, &err_msg);
+                        let delay_ms = Self::retry_delay_ms_for_provider_error(
+                            local_attempt_index,
+                            &err_msg,
+                            provider_error,
+                        );
                         warn!(
-                            "Retrying stream after transient error with no effective output: session_id={}, round_id={}, round_attempt={}, local_retry={}/{}, delay_ms={}, error={}",
+                            "Retrying stream after error: session_id={}, round_id={}, round_attempt={}, local_retry={}/{}, delay_ms={}, effective_output={}, category={:?}, error={}",
                             context.session_id,
                             round_id,
                             attempt_number,
                             local_attempt_index + 1,
                             max_attempts,
                             delay_ms,
+                            stream_err.has_effective_output,
+                            stream_error_category,
                             err_msg
                         );
                         Self::sleep_with_cancellation(delay_ms, &cancel_token).await?;
                         local_attempt_index += 1;
                         continue;
                     }
-                    if stream_error_category != ErrorCategory::ContextOverflow
-                        && Self::is_transient_network_error(&err_msg)
-                    {
-                        return Err(BitFunError::AIClient(format!(
-                            "Stream retry budget exhausted after {} attempts: {}",
-                            max_attempts, err_msg
-                        )));
-                    }
-                    if !stream_err.has_effective_output
-                        && stream_error_category == ErrorCategory::ContextOverflow
-                    {
+                    warn!(
+                        "Stream retry budget exhausted: session_id={}, round_id={}, attempts={}, effective_output={}, category={:?}, error={}",
+                        context.session_id,
+                        round_id,
+                        max_attempts,
+                        stream_err.has_effective_output,
+                        stream_error_category,
+                        err_msg
+                    );
+                    if stream_error_category == ErrorCategory::ContextOverflow {
                         let provider_error = match stream_err.error {
                             BitFunError::AIProvider(error)
                             | BitFunError::RecoverableContextOverflow(error) => error,
@@ -1489,14 +1468,25 @@ impl RoundExecutor {
     }
 
     fn retry_delay_ms_for_error(attempt_index: usize, error_message: &str) -> u64 {
+        Self::retry_delay_ms_for_provider_error(attempt_index, error_message, None)
+    }
+
+    fn retry_delay_ms_for_provider_error(
+        attempt_index: usize,
+        error_message: &str,
+        provider_error: Option<&AiProviderError>,
+    ) -> u64 {
         let shift = u32::try_from(attempt_index)
             .unwrap_or(u32::MAX)
             .min(Self::MAX_RETRY_EXPONENT_SHIFT);
         let msg = error_message.to_lowercase();
-        let is_rate_limit =
-            msg.contains("429") || msg.contains("rate limit") || msg.contains("too many requests");
+        let is_rate_limit = provider_error
+            .is_some_and(|error| error.category == ErrorCategory::RateLimit)
+            || msg.contains("429")
+            || msg.contains("rate limit")
+            || msg.contains("too many requests");
 
-        if is_rate_limit {
+        let fallback = if is_rate_limit {
             Self::RATE_LIMIT_RETRY_BASE_DELAY_MS
                 .saturating_mul(1u64 << shift)
                 .min(Self::MAX_RATE_LIMIT_DELAY_MS)
@@ -1504,113 +1494,17 @@ impl RoundExecutor {
             Self::RETRY_BASE_DELAY_MS
                 .saturating_mul(1u64 << shift)
                 .min(Self::MAX_EXPONENTIAL_DELAY_MS)
-        }
-    }
-
-    /// Check whether an error message represents a transient (retryable) condition.
-    ///
-    /// Errors that already exhausted the SSE-layer retry budget (e.g. "failed
-    /// after N attempts:" or "Stream retry budget exhausted") are **not**
-    /// transient from the round-executor perspective — the SSE transport layer
-    /// already retried with exponential backoff and `Retry-After` parsing.
-    /// Re-entering the send loop would multiply attempts (10 × 10 = 100) and
-    /// hold the user in a long silent stall.
-    fn is_transient_network_error(error_message: &str) -> bool {
-        let msg = error_message.to_lowercase();
-
-        // The SSE layer already exhausted its own retry budget — do not
-        // re-enter another round of attempts from the round executor.
-        // We require BOTH "failed after " and "attempts:" to co-occur,
-        // which uniquely identifies the SSE/round-executor budget-exhausted
-        // format without catching generic errors like "failed after timeout".
-        if msg.contains("failed after ") && msg.contains("attempts:") {
-            return false;
-        }
-        if msg.contains("retry budget exhausted") {
-            return false;
-        }
+        };
 
-        let non_retryable_keywords = [
-            "invalid api key",
-            "unauthorized",
-            "forbidden",
-            "model not found",
-            "unsupported model",
-            "invalid request",
-            "bad request",
-            "prompt is too long",
-            "content policy",
-            "proxy authentication required",
-            "provider quota",
-            "provider billing",
-            "insufficient_quota",
-            "insufficient quota",
-            "insufficient balance",
-            "not_enough_balance",
-            "not enough balance",
-            "余额不足",
-            "无可用资源包",
-            "账户已欠费",
-            "code=1113",
-            "\"code\":\"1113\"",
-            "client error 400",
-            "client error 401",
-            "client error 402",
-            "client error 403",
-            "client error 404",
-            "client error 413",
-            "client error 422",
-            "sse parsing error",
-            "schema error",
-            "unknown api format",
-        ];
-
-        let transient_keywords = [
-            "transport error",
-            "error decoding response body",
-            "stream closed before response completed",
-            "stream processing error",
-            "sse stream error",
-            "sse error",
-            "sse timeout",
-            "stream data timeout",
-            "timeout",
-            "request timeout",
-            "deadline exceeded",
-            "connection reset",
-            "connection closed",
-            "broken pipe",
-            "unexpected eof",
-            "connection refused",
-            "socket closed",
-            "temporarily unavailable",
-            "service unavailable",
-            "bad gateway",
-            "gateway timeout",
-            "overloaded",
-            "proxy",
-            "tunnel",
-            "dns",
-            "network",
-            "econnreset",
-            "econnrefused",
-            "etimedout",
-            "rate limit",
-            "too many requests",
-            "408",
-            "409",
-            "425",
-            "429",
-            "502",
-            "503",
-            "504",
-        ];
-
-        if non_retryable_keywords.iter().any(|k| msg.contains(k)) {
-            return false;
+        match provider_error.and_then(|error| error.retry_after_ms) {
+            Some(retry_after_ms) if is_rate_limit => retry_after_ms
+                .max(fallback)
+                .min(Self::MAX_RATE_LIMIT_DELAY_MS),
+            Some(retry_after_ms) if retry_after_ms > 0 => {
+                retry_after_ms.min(Self::MAX_RATE_LIMIT_DELAY_MS)
+            }
+            Some(_) | None => fallback,
         }
-
-        transient_keywords.iter().any(|k| msg.contains(k))
     }
 }
 
@@ -2146,16 +2040,6 @@ mod tests {
         assert_eq!(trace.error.as_deref(), Some("request failed"));
     }
 
-    #[test]
-    fn is_transient_error_treats_rate_limit_as_transient() {
-        assert!(RoundExecutor::is_transient_network_error(
-            "OpenAI Streaming API error 429 Too Many Requests"
-        ));
-        assert!(RoundExecutor::is_transient_network_error(
-            "rate limit exceeded"
-        ));
-    }
-
     #[test]
     fn retry_delay_grows_beyond_previous_four_second_cap() {
         assert_eq!(RoundExecutor::retry_delay_ms(0), 500);
@@ -2183,43 +2067,37 @@ mod tests {
     }
 
     #[test]
-    fn is_transient_error_treats_network_errors_as_transient() {
-        assert!(RoundExecutor::is_transient_network_error(
-            "connection reset by peer"
-        ));
-        assert!(RoundExecutor::is_transient_network_error("timeout"));
-    }
-
-    #[test]
-    fn is_transient_error_treats_context_overflow_as_non_transient() {
-        assert!(!RoundExecutor::is_transient_network_error(
-            "prompt is too long"
-        ));
-    }
-
-    #[test]
-    fn is_transient_error_treats_budget_exhausted_as_non_transient() {
-        // After SSE layer exhausts its retry budget, the round executor must
-        // NOT re-enter another round of attempts (would cause 10×10 = 100
-        // retries).
-        assert!(!RoundExecutor::is_transient_network_error(
-            "OpenAI Streaming API failed after 10 attempts: \
-             OpenAI Streaming API error 429 Too Many Requests"
-        ));
-        assert!(!RoundExecutor::is_transient_network_error(
-            "Stream retry budget exhausted after 10 attempts: timeout"
-        ));
-    }
+    fn provider_retry_after_is_only_a_delay_hint() {
+        let permission_error = bitfun_core_types::errors::AiProviderError::from_parts(
+            "permission denied".to_string(),
+            Some("openai".to_string()),
+            None,
+            Some(403),
+        )
+        .with_retry_after_ms(Some(1_000));
+        assert_eq!(
+            RoundExecutor::retry_delay_ms_for_provider_error(
+                5,
+                &permission_error.message,
+                Some(&permission_error),
+            ),
+            1_000
+        );
 
-    #[test]
-    fn is_transient_error_does_not_misclassify_failed_after_without_attempts() {
-        // "failed after " without "attempts:" should NOT be treated as budget
-        // exhausted — it may be a legitimately retryable transient error.
-        assert!(RoundExecutor::is_transient_network_error(
-            "stream failed after connection reset"
-        ));
-        assert!(RoundExecutor::is_transient_network_error(
-            "request failed after timeout"
-        ));
+        let rate_limit_error = bitfun_core_types::errors::AiProviderError::from_parts(
+            "too many requests".to_string(),
+            Some("openai".to_string()),
+            None,
+            Some(429),
+        )
+        .with_retry_after_ms(Some(1_000));
+        assert_eq!(
+            RoundExecutor::retry_delay_ms_for_provider_error(
+                3,
+                &rate_limit_error.message,
+                Some(&rate_limit_error),
+            ),
+            16_000
+        );
     }
 }
diff --git a/src/crates/assembly/core/src/agentic/execution/types.rs b/src/crates/assembly/core/src/agentic/execution/types.rs
index dd12ab189b..89820ce545 100644
--- a/src/crates/assembly/core/src/agentic/execution/types.rs
+++ b/src/crates/assembly/core/src/agentic/execution/types.rs
@@ -124,4 +124,18 @@ pub struct ExecutionResult {
     pub new_messages: Vec<Message>,
     /// Why the execution finished
     pub finish_reason: FinishReason,
+    pub total_tools: usize,
+    pub duration_ms: u64,
+    pub partial_recovery_reason: Option<String>,
+    pub effective_finish_reason: String,
+    pub has_final_response: bool,
+}
+
+pub(crate) const CANCEL_LIFECYCLE_OWNER_CONTEXT_KEY: &str = "cancel_lifecycle_owner";
+
+pub(crate) fn coordinator_owns_cancel_lifecycle(context: &HashMap<String, String>) -> bool {
+    context
+        .get(CANCEL_LIFECYCLE_OWNER_CONTEXT_KEY)
+        .map(String::as_str)
+        == Some("coordinator")
 }
diff --git a/src/crates/assembly/core/src/agentic/image_analysis/image_processing.rs b/src/crates/assembly/core/src/agentic/image_analysis/image_processing.rs
index 056130b5c9..1f9c09f48d 100644
--- a/src/crates/assembly/core/src/agentic/image_analysis/image_processing.rs
+++ b/src/crates/assembly/core/src/agentic/image_analysis/image_processing.rs
@@ -21,8 +21,41 @@ use tokio::fs;
 pub struct ProcessedImage {
     pub data: Vec<u8>,
     pub mime_type: String,
+    /// Width of the image **as sent to the model** — not of the source file.
+    /// Downscaling to fit the provider's limits can shrink this a long way
+    /// (repeated 0.75× passes, floor 64px).
     pub width: u32,
+    /// Height as sent to the model. See [`Self::width`].
     pub height: u32,
+    /// Width of the source image, before any resizing.
+    ///
+    /// Reported separately because callers surface these numbers to a model,
+    /// and a resized dimension presented as the file's dimension is silently
+    /// wrong: anything the vision model says about position or size is in the
+    /// resized frame, and the caller has no way to map it back without knowing
+    /// the original.
+    pub original_width: u32,
+    /// Height of the source image, before any resizing.
+    pub original_height: u32,
+}
+
+impl ProcessedImage {
+    /// Linear factor from source pixels to sent pixels (1.0 when untouched).
+    ///
+    /// Aspect ratio is preserved by every resize path here, so one factor
+    /// describes both axes; it is derived from width to avoid disagreeing with
+    /// itself on rounding.
+    pub fn scale(&self) -> f64 {
+        if self.original_width == 0 {
+            return 1.0;
+        }
+        f64::from(self.width) / f64::from(self.original_width)
+    }
+
+    /// Whether the image was downscaled on the way to the model.
+    pub fn was_resized(&self) -> bool {
+        self.width != self.original_width || self.height != self.original_height
+    }
 }
 
 pub fn resolve_vision_model_from_ai_config(
@@ -178,6 +211,8 @@ pub fn optimize_image_with_size_limit(
             mime_type,
             width: orig_width,
             height: orig_height,
+            original_width: orig_width,
+            original_height: orig_height,
         });
     }
 
@@ -231,6 +266,8 @@ pub fn optimize_image_with_size_limit(
         mime_type: encoded.1,
         width: working.width(),
         height: working.height(),
+        original_width: orig_width,
+        original_height: orig_height,
     })
 }
 
@@ -484,3 +521,78 @@ fn encode_dynamic_image(
 
     Ok((buffer, mime))
 }
+
+#[cfg(test)]
+mod resize_reporting_tests {
+    use super::*;
+
+    fn png_of(width: u32, height: u32) -> Vec<u8> {
+        let img =
+            image::DynamicImage::ImageRgb8(image::RgbImage::from_fn(width, height, |x, y| {
+                // Non-uniform content so the encoder cannot collapse it to nothing,
+                // which would let the size-based resize passes be skipped.
+                image::Rgb([(x % 251) as u8, (y % 253) as u8, ((x ^ y) % 247) as u8])
+            }));
+        let mut out = std::io::Cursor::new(Vec::new());
+        img.write_to(&mut out, ImageFormat::Png)
+            .expect("encode test png");
+        out.into_inner()
+    }
+
+    /// A Retina screenshot is wider than every provider's limit, so it always
+    /// takes the resize path. The source dimensions were being computed and
+    /// then dropped, so callers reported the *resized* size as the file's —
+    /// silently wrong data, and the reason a caller mapping a reported position
+    /// back to the screen would land in the wrong place.
+    #[test]
+    fn a_resized_screenshot_still_reports_its_source_dimensions() {
+        let processed = optimize_image_with_size_limit(
+            png_of(3024, 1964),
+            "anthropic",
+            Some("image/png"),
+            Some(1024 * 1024),
+        )
+        .expect("optimize");
+
+        assert_eq!(processed.original_width, 3024);
+        assert_eq!(processed.original_height, 1964);
+        assert!(
+            processed.was_resized(),
+            "3024px exceeds every provider limit"
+        );
+        assert!(
+            processed.width < processed.original_width,
+            "sent {}px for a {}px source",
+            processed.width,
+            processed.original_width
+        );
+
+        // The factor has to actually describe the transform, or mapping back
+        // through it is worse than not having it.
+        let mapped = f64::from(processed.original_width) * processed.scale();
+        assert!(
+            (mapped - f64::from(processed.width)).abs() <= 1.0,
+            "scale {} maps {} to {}, expected ~{}",
+            processed.scale(),
+            processed.original_width,
+            mapped,
+            processed.width
+        );
+    }
+
+    /// An image already within limits must pass through untouched, and say so.
+    #[test]
+    fn a_small_image_is_not_reported_as_resized() {
+        let processed =
+            optimize_image_with_size_limit(png_of(80, 60), "anthropic", Some("image/png"), None)
+                .expect("optimize");
+
+        assert_eq!((processed.width, processed.height), (80, 60));
+        assert_eq!(
+            (processed.original_width, processed.original_height),
+            (80, 60)
+        );
+        assert!(!processed.was_resized());
+        assert!((processed.scale() - 1.0).abs() < f64::EPSILON);
+    }
+}
diff --git a/src/crates/assembly/core/src/agentic/memories/transcript.rs b/src/crates/assembly/core/src/agentic/memories/transcript.rs
index 016f22a35b..af2b475ffa 100644
--- a/src/crates/assembly/core/src/agentic/memories/transcript.rs
+++ b/src/crates/assembly/core/src/agentic/memories/transcript.rs
@@ -365,6 +365,8 @@ mod tests {
             has_final_response: Some(true),
             error: None,
             error_detail: None,
+            recovery: None,
+            recovery_epoch: None,
             status: TurnStatus::Completed,
         }
     }
diff --git a/src/crates/assembly/core/src/agentic/persistence/manager.rs b/src/crates/assembly/core/src/agentic/persistence/manager.rs
index 6ef94eb095..20fc63200d 100644
--- a/src/crates/assembly/core/src/agentic/persistence/manager.rs
+++ b/src/crates/assembly/core/src/agentic/persistence/manager.rs
@@ -488,6 +488,8 @@ pub struct PersistenceManager {
     fail_next_session_metadata_write: std::sync::Mutex<Option<String>>,
     #[cfg(test)]
     fail_next_session_metadata_rollback: std::sync::Mutex<Option<String>>,
+    #[cfg(test)]
+    fail_next_dialog_turn_write: std::sync::Mutex<Option<String>>,
 }
 
 impl PersistenceManager {
@@ -501,6 +503,8 @@ impl PersistenceManager {
             fail_next_session_metadata_write: std::sync::Mutex::new(None),
             #[cfg(test)]
             fail_next_session_metadata_rollback: std::sync::Mutex::new(None),
+            #[cfg(test)]
+            fail_next_dialog_turn_write: std::sync::Mutex::new(None),
         })
     }
 
@@ -541,6 +545,14 @@ impl PersistenceManager {
             .expect("session metadata rollback fault lock") = Some(session_id.to_string());
     }
 
+    #[cfg(test)]
+    pub(crate) fn fail_next_dialog_turn_write_for_test(&self, session_id: &str) {
+        *self
+            .fail_next_dialog_turn_write
+            .lock()
+            .expect("dialog turn fault lock") = Some(session_id.to_string());
+    }
+
     /// Resolve the on-disk sessions directory for `workspace_path`.
     ///
     /// Callers may pass either a logical workspace root or an already-resolved
@@ -3007,6 +3019,17 @@ impl PersistenceManager {
         turn: &DialogTurnData,
     ) -> BitFunResult<()> {
         Self::validate_session_id(&turn.session_id)?;
+        #[cfg(test)]
+        {
+            let mut fault = self
+                .fail_next_dialog_turn_write
+                .lock()
+                .expect("dialog turn fault lock");
+            if fault.as_deref() == Some(turn.session_id.as_str()) {
+                *fault = None;
+                return Err(BitFunError::io("Injected dialog turn write failure"));
+            }
+        }
         let _session_write = self.lock_session_write_operation(workspace_path, &turn.session_id)?;
         let save_started_at = Instant::now();
         self.ensure_runtime_for_write(workspace_path).await?;
diff --git a/src/crates/assembly/core/src/agentic/session/revert.rs b/src/crates/assembly/core/src/agentic/session/revert.rs
index b192266526..c4df1ed0bf 100644
--- a/src/crates/assembly/core/src/agentic/session/revert.rs
+++ b/src/crates/assembly/core/src/agentic/session/revert.rs
@@ -21,6 +21,12 @@ pub(crate) struct SessionWorkspaceCheckpoint {
     pub(crate) snapshot_id: Option<String>,
 }
 
+impl SessionWorkspaceCheckpoint {
+    pub(crate) fn display_path(&self) -> String {
+        self.path.to_string_lossy().into_owned()
+    }
+}
+
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub(crate) struct SessionRevertState {
@@ -42,6 +48,13 @@ impl SessionRevertState {
             workspace_checkpoint: Vec::new(),
         }
     }
+
+    pub(crate) fn diagnostic_mutation_id(&self, session_id: &str) -> String {
+        format!(
+            "session-revert:{session_id}:{}:{}",
+            self.boundary_turn, self.original_turn_end
+        )
+    }
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -130,6 +143,40 @@ pub(crate) fn resolve_undo(
     })
 }
 
+pub(crate) fn resolve_targeted(
+    turns: &[DialogTurnData],
+    target_turn_id: &str,
+    current: Option<&SessionRevertState>,
+) -> Option<SessionRevertTransition> {
+    let target = turns
+        .iter()
+        .find(|turn| turn.kind == DialogTurnKind::UserDialog && turn.turn_id == target_turn_id)?;
+    let mut state = current.cloned().unwrap_or_else(|| {
+        SessionRevertState::initial(target.turn_index, original_turn_end(turns))
+    });
+    state.boundary_turn = target.turn_index;
+    state.phase = SessionRevertPhase::Applying;
+    let hidden_turn_count = turns
+        .iter()
+        .filter(|turn| turn.turn_index >= state.boundary_turn)
+        .count();
+
+    Some(SessionRevertTransition::Stage {
+        state,
+        replacement_prompt: Some(
+            target
+                .user_message
+                .metadata
+                .as_ref()
+                .and_then(|metadata| metadata.get("original_text"))
+                .and_then(serde_json::Value::as_str)
+                .unwrap_or(&target.user_message.content)
+                .to_string(),
+        ),
+        hidden_turn_count,
+    })
+}
+
 pub(crate) fn resolve_redo(
     turns: &[DialogTurnData],
     current: Option<&SessionRevertState>,
@@ -173,7 +220,10 @@ fn original_turn_end(turns: &[DialogTurnData]) -> usize {
 
 #[cfg(test)]
 mod tests {
-    use super::{resolve_redo, resolve_undo, SessionRevertTransition};
+    use super::{
+        resolve_redo, resolve_targeted, resolve_undo, SessionRevertPhase, SessionRevertState,
+        SessionRevertTransition, SessionWorkspaceCheckpoint, SESSION_REVERT_SCHEMA_VERSION,
+    };
     use crate::service::session::{DialogTurnData, DialogTurnKind, TurnStatus, UserMessageData};
 
     fn user_turn(index: usize, prompt: &str) -> DialogTurnData {
@@ -199,6 +249,8 @@ mod tests {
             has_final_response: Some(true),
             error: None,
             error_detail: None,
+            recovery: None,
+            recovery_epoch: None,
             status: TurnStatus::Completed,
         }
     }
@@ -258,4 +310,44 @@ mod tests {
         assert_eq!(clear.hidden_turn_count(), 0);
         assert!(resolve_redo(&turns, None).is_none());
     }
+
+    #[test]
+    fn targeted_resolution_uses_turn_identity_with_sparse_storage_indices() {
+        let turns = vec![
+            user_turn(0, "first"),
+            user_turn(1, "second"),
+            maintenance_turn(7),
+            user_turn(8, "third"),
+        ];
+        let transition = resolve_targeted(&turns, "turn-8", None).expect("target should resolve");
+        assert_eq!(transition.boundary_turn(), Some(8));
+        assert_eq!(transition.hidden_turn_count(), 1);
+        assert_eq!(transition.replacement_prompt(), Some("third"));
+        assert!(resolve_targeted(&turns, "missing", None).is_none());
+        assert!(resolve_targeted(&turns, "turn-7", None).is_none());
+    }
+
+    #[test]
+    fn targeted_resolution_extends_an_existing_staged_revert() {
+        let turns = vec![user_turn(0, "first"), user_turn(1, "second")];
+        let staged = SessionRevertState {
+            schema_version: SESSION_REVERT_SCHEMA_VERSION,
+            boundary_turn: 1,
+            original_turn_end: 2,
+            phase: SessionRevertPhase::Staged,
+            workspace_checkpoint: vec![SessionWorkspaceCheckpoint {
+                path: "src/lib.rs".into(),
+                snapshot_id: Some("snapshot-1".to_string()),
+            }],
+        };
+
+        let transition = resolve_targeted(&turns, "turn-0", Some(&staged))
+            .expect("visible target should extend the staged revert");
+        let state = transition
+            .staged_state()
+            .expect("target should stage a boundary");
+        assert_eq!(state.boundary_turn, 0);
+        assert_eq!(state.original_turn_end, 2);
+        assert_eq!(state.workspace_checkpoint, staged.workspace_checkpoint);
+    }
 }
diff --git a/src/crates/assembly/core/src/agentic/session/session_manager.rs b/src/crates/assembly/core/src/agentic/session/session_manager.rs
index 039f0cb2e0..011a256682 100644
--- a/src/crates/assembly/core/src/agentic/session/session_manager.rs
+++ b/src/crates/assembly/core/src/agentic/session/session_manager.rs
@@ -31,16 +31,20 @@ use crate::agentic::ConversationCoordinator;
 use crate::infrastructure::ai::get_global_ai_client_factory;
 use crate::infrastructure::ai::reasoning_catalog::{
     load_models_dev_reasoning_catalog_without_refresh, normalize_reasoning_preset_for_model,
+    project_model_reasoning_catalog, reasoning_preset_runtime_fingerprint,
+    resolve_default_reasoning_preset, resolve_reasoning_preset,
 };
+use crate::service::config::types::{model_runtime_binding_fingerprint, AIConfig};
 use crate::service::config::{
     get_app_language_code, get_global_config_service, short_model_user_language_instruction,
     subscribe_config_updates, ConfigUpdateEvent,
 };
 use crate::service::remote_ssh::workspace_state::LOCAL_WORKSPACE_SSH_HOST;
 use crate::service::session::{
-    DialogTurnData, DialogTurnKind, ModelRoundData, SessionContextUsage, SessionMemoryMode,
-    SessionMetadata, SessionRelationship, SessionStatus, TextItemData, ThinkingItemData,
-    ToolCallData, ToolItemData, ToolResultData, TranscriptLineRange, TurnStatus, UserMessageData,
+    DialogTurnData, DialogTurnKind, DialogTurnRecoveryData, DialogTurnRecoveryStatus,
+    ModelRoundData, SessionContextUsage, SessionMemoryMode, SessionMetadata, SessionRelationship,
+    SessionStatus, TextItemData, ThinkingItemData, ToolCallData, ToolItemData, ToolResultData,
+    TranscriptLineRange, TurnStatus, UserMessageData,
 };
 use crate::service::snapshot::{
     ensure_snapshot_manager_for_workspace, get_or_create_snapshot_manager,
@@ -72,7 +76,7 @@ use tokio::time;
 
 #[cfg(test)]
 tokio::task_local! {
-    static TEST_MODEL_RESOLUTION_AI_CONFIG: crate::service::config::types::AIConfig;
+    pub(crate) static TEST_MODEL_RESOLUTION_AI_CONFIG: crate::service::config::types::AIConfig;
 }
 
 /// Session manager configuration
@@ -106,6 +110,68 @@ pub struct MaterializedSessionReference {
     pub transcript: MaterializedSessionReferenceTranscript,
 }
 
+pub(crate) const INTERRUPTED_TURN_PERMISSION_MODE_METADATA_KEY: &str = "resolved_permission_mode";
+pub(crate) const INTERRUPTED_TURN_RESOLVED_MODEL_ID_METADATA_KEY: &str =
+    "runtime_resolved_model_id";
+pub(crate) const INTERRUPTED_TURN_MODEL_BINDING_FINGERPRINT_METADATA_KEY: &str =
+    "runtime_model_binding_fingerprint";
+pub(crate) const INTERRUPTED_TURN_REASONING_PRESET_METADATA_KEY: &str = "runtime_reasoning_preset";
+pub(crate) const INTERRUPTED_TURN_REASONING_SELECTION_METADATA_KEY: &str =
+    "runtime_reasoning_selection";
+pub(crate) const INTERRUPTED_TURN_REASONING_FINGERPRINT_METADATA_KEY: &str =
+    "runtime_reasoning_fingerprint";
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct TurnAdmissionSessionFacts {
+    model_id: Option<String>,
+    reasoning_preset: Option<String>,
+    permission_mode: Option<PermissionMode>,
+    agent_type: String,
+    enable_tools: bool,
+}
+
+impl TurnAdmissionSessionFacts {
+    pub(crate) fn from_session(session: &Session) -> Self {
+        Self {
+            model_id: session.config.model_id.clone(),
+            reasoning_preset: session.config.reasoning_preset.clone(),
+            permission_mode: session.config.permission_mode,
+            agent_type: session.agent_type.clone(),
+            enable_tools: session.config.enable_tools,
+        }
+    }
+
+    pub(crate) fn with_reasoning_preset(mut self, reasoning_preset: Option<String>) -> Self {
+        self.reasoning_preset = reasoning_preset;
+        self
+    }
+
+    fn matches(&self, session: &Session) -> bool {
+        self.model_id == session.config.model_id
+            && self.reasoning_preset == session.config.reasoning_preset
+            && self.permission_mode == session.config.permission_mode
+            && self.agent_type == session.agent_type
+            && self.enable_tools == session.config.enable_tools
+    }
+}
+
+#[derive(Debug, Clone)]
+pub(crate) struct InterruptedTurnRecoveryPlan {
+    pub session_id: String,
+    pub turn_id: String,
+    pub turn_index: usize,
+    pub agent_type: String,
+    pub execution_generation: u32,
+    pub resume_count: u32,
+    pub initial_round_index: usize,
+    pub resolved_permission_mode: PermissionMode,
+    pub resolved_model_id: String,
+    pub model_binding_fingerprint: String,
+    pub user_input: String,
+    pub messages: Vec<Message>,
+    pub user_message_metadata: Option<serde_json::Value>,
+}
+
 impl Default for SessionManagerConfig {
     fn default() -> Self {
         Self {
@@ -234,6 +300,12 @@ pub struct SessionManager {
     /// Active sessions in memory
     sessions: Arc<DashMap<String, Session>>,
 
+    /// Ephemeral permission override for the currently executing turn.
+    ///
+    /// This state is intentionally separate from `SessionConfig`: it may change
+    /// between model rounds, and it must disappear when the owning turn ends.
+    active_turn_permission_modes: Arc<DashMap<String, ActiveTurnPermissionMode>>,
+
     /// Process-local durability classification owned by the Session lifecycle.
     /// Entries are installed before a transient Session becomes visible and are
     /// removed with that Session; they are never serialized into public config.
@@ -283,6 +355,12 @@ pub struct SessionManager {
     config: SessionManagerConfig,
 }
 
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ActiveTurnPermissionMode {
+    pub turn_id: String,
+    pub mode: PermissionMode,
+}
+
 fn clear_session_runtime_stores(
     session_id: &str,
     context_store: &SessionContextStore,
@@ -575,8 +653,7 @@ impl SessionManager {
             }))
     }
 
-    async fn load_ai_config_for_model_resolution() -> Option<crate::service::config::types::AIConfig>
-    {
+    pub(crate) async fn load_ai_config_for_model_resolution() -> Option<AIConfig> {
         #[cfg(test)]
         if let Ok(ai_config) = TEST_MODEL_RESOLUTION_AI_CONFIG.try_with(Clone::clone) {
             return Some(ai_config);
@@ -586,6 +663,67 @@ impl SessionManager {
         config_service.get_config(Some("ai")).await.ok()
     }
 
+    pub(crate) async fn resolve_effective_reasoning_preset_for_turn(
+        resolved_model_id: &str,
+        selected_preset: Option<&str>,
+    ) -> BitFunResult<(Option<String>, String)> {
+        let ai_config = Self::load_ai_config_for_model_resolution()
+            .await
+            .ok_or_else(|| {
+                BitFunError::AIClient(
+                    "AI configuration is unavailable for reasoning preset resolution".to_string(),
+                )
+            })?;
+        Self::resolve_effective_reasoning_preset_from_config(
+            &ai_config,
+            resolved_model_id,
+            selected_preset,
+        )
+        .await
+    }
+
+    async fn resolve_effective_reasoning_preset_from_config(
+        ai_config: &AIConfig,
+        resolved_model_id: &str,
+        selected_preset: Option<&str>,
+    ) -> BitFunResult<(Option<String>, String)> {
+        let canonical_model_id = ai_config
+            .resolve_model_reference(resolved_model_id)
+            .ok_or_else(|| {
+                BitFunError::AIClient(format!(
+                    "Dialog turn model is unavailable for reasoning preset resolution: {resolved_model_id}"
+                ))
+            })?;
+        let model = ai_config
+            .models
+            .iter()
+            .find(|model| model.enabled && model.id == canonical_model_id)
+            .ok_or_else(|| {
+                BitFunError::AIClient(format!(
+                    "Dialog turn model configuration is unavailable: {canonical_model_id}"
+                ))
+            })?;
+        let models_dev = load_models_dev_reasoning_catalog_without_refresh().await;
+        let projection = project_model_reasoning_catalog(model, models_dev.catalog.as_deref());
+        let preset = match selected_preset
+            .map(str::trim)
+            .filter(|preset| !preset.is_empty())
+        {
+            Some(selected_preset) => resolve_reasoning_preset(&projection, selected_preset)
+                .ok_or_else(|| {
+                    BitFunError::Validation(format!(
+                        "Reasoning preset is unavailable for the dialog turn model: {selected_preset}"
+                    ))
+                })
+                .map(Some)?,
+            None => resolve_default_reasoning_preset(&projection),
+        };
+        Ok((
+            preset.map(|preset| preset.id.clone()),
+            reasoning_preset_runtime_fingerprint(preset),
+        ))
+    }
+
     fn is_auto_model_selector(model_id: &str) -> bool {
         let trimmed = model_id.trim();
         trimmed.is_empty() || trimmed == "auto" || trimmed == "default"
@@ -1873,6 +2011,7 @@ impl SessionManager {
 
         let manager = Self {
             sessions: Arc::new(DashMap::new()),
+            active_turn_permission_modes: Arc::new(DashMap::new()),
             transient_session_ids: Arc::new(DashMap::new()),
             active_session_capacity: Arc::new(Semaphore::new(config.max_active_sessions)),
             active_session_permits: Arc::new(DashMap::new()),
@@ -2204,6 +2343,7 @@ impl SessionManager {
 
     fn spawn_model_reconciliation_listener(&self) {
         let sessions = self.sessions.clone();
+        let active_turn_permission_modes = self.active_turn_permission_modes.clone();
         let transient_session_ids = self.transient_session_ids.clone();
         let active_session_capacity = self.active_session_capacity.clone();
         let active_session_permits = self.active_session_permits.clone();
@@ -2237,6 +2377,7 @@ impl SessionManager {
             // surface area we need from the cloned shared fields above.
             let manager = Self {
                 sessions,
+                active_turn_permission_modes,
                 transient_session_ids,
                 active_session_capacity,
                 active_session_permits,
@@ -4021,8 +4162,8 @@ impl SessionManager {
     ///
     /// `None` clears the override so the session follows the user-level default
     /// again, including later changes to that default. The value only takes
-    /// effect from the next submission: a running turn already resolved its
-    /// mode and must not change permissions halfway through.
+    /// effect from the next model round. A running round keeps the policy it
+    /// resolved at its boundary, while later rounds read the updated session.
     pub async fn update_session_permission_mode(
         &self,
         session_id: &str,
@@ -4114,6 +4255,69 @@ impl SessionManager {
             .and_then(|session| session.config.permission_mode)
     }
 
+    /// Installs or replaces the ephemeral permission mode for one exact active
+    /// turn. A stale update can never leak into a newer turn in the session.
+    pub fn set_active_turn_permission_mode(
+        &self,
+        session_id: &str,
+        turn_id: &str,
+        permission_mode: PermissionMode,
+    ) -> bool {
+        let Some(session) = self.sessions.get(session_id) else {
+            return false;
+        };
+        if !matches!(
+            &session.state,
+            SessionState::Processing { current_turn_id, .. } if current_turn_id == turn_id
+        ) {
+            return false;
+        }
+
+        // Keep the session shard read-locked through the write. A concurrent
+        // turn-completion state update must happen after this insert, so its
+        // cleanup cannot run just before a stale override is published.
+        self.active_turn_permission_modes.insert(
+            session_id.to_string(),
+            ActiveTurnPermissionMode {
+                turn_id: turn_id.to_string(),
+                mode: permission_mode,
+            },
+        );
+        true
+    }
+
+    pub fn active_turn_permission_mode(
+        &self,
+        session_id: &str,
+        turn_id: &str,
+    ) -> Option<PermissionMode> {
+        let session = self.sessions.get(session_id)?;
+        if !matches!(
+            &session.state,
+            SessionState::Processing { current_turn_id, .. } if current_turn_id == turn_id
+        ) {
+            return None;
+        }
+        self.active_turn_permission_modes
+            .get(session_id)
+            .filter(|entry| entry.turn_id == turn_id)
+            .map(|entry| entry.mode)
+    }
+
+    /// Clears an ephemeral override only when it belongs to the expected turn.
+    pub fn clear_active_turn_permission_mode(&self, session_id: &str, turn_id: &str) -> bool {
+        match self
+            .active_turn_permission_modes
+            .entry(session_id.to_string())
+        {
+            dashmap::mapref::entry::Entry::Occupied(entry) if entry.get().turn_id == turn_id => {
+                entry.remove();
+                true
+            }
+            _ => false,
+        }
+    }
+
     /// Rebind where a session executes (in-memory + persistence).
     ///
     /// Only the workspace roots and the resolved execution target move; session
@@ -4583,6 +4787,7 @@ impl SessionManager {
             return Ok(false);
         }
         self.release_active_session_reservation(session_id);
+        self.active_turn_permission_modes.remove(session_id);
         clear_session_runtime_stores(
             session_id,
             self.context_store.as_ref(),
@@ -4625,6 +4830,7 @@ impl SessionManager {
             }
         }
 
+        self.active_turn_permission_modes.remove(session_id);
         clear_session_runtime_stores(
             session_id,
             self.context_store.as_ref(),
@@ -5562,15 +5768,49 @@ impl SessionManager {
         // Reset session state to Idle
         // After application restart, previous Processing state is invalid and must be reset
         let previous_state_was_not_idle = !matches!(session.state, SessionState::Idle);
+        let mut interrupted_recovery_restored_turn = None;
         if previous_state_was_not_idle {
             let old_state = session.state.clone();
             session.state = SessionState::Idle;
+            should_persist_restored_session = true;
             debug!(
                 "Resetting session state during restore: session_id={}, state={:?} -> Idle",
                 session_id, old_state
             );
         }
 
+        // A process exit can happen after the recovering Turn write but before
+        // the Processing Session write, or after both. No execution survives
+        // restart, so normalize from the durable Turn fact independently of
+        // the stale Session state.
+        if let Some(turn) = persisted_turns.last_mut().filter(|turn| {
+            turn.status == TurnStatus::InProgress
+                && turn
+                    .recovery
+                    .as_ref()
+                    .is_some_and(|recovery| recovery.status == DialogTurnRecoveryStatus::Recovering)
+        }) {
+            let now = SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap_or_default()
+                .as_millis() as u64;
+            turn.status = TurnStatus::Cancelled;
+            turn.finish_reason = Some("interrupted".to_string());
+            turn.end_time = Some(now);
+            turn.duration_ms = Some(now.saturating_sub(turn.start_time));
+            if let Some(recovery) = turn.recovery.as_mut() {
+                recovery.status = DialogTurnRecoveryStatus::Interrupted;
+                recovery.interrupted_at = Some(now);
+                turn.recovery_epoch = Some(recovery.execution_generation);
+            }
+            interrupted_recovery_restored_turn = Some(turn.clone());
+            should_persist_restored_session = true;
+            info!(
+                "Restored abandoned recovery generation as interrupted: session_id={}, turn_id={}",
+                session_id, turn.turn_id
+            );
+        }
+
         // 2. Restore runtime context with snapshot-first semantics.
         // If the latest snapshot lags behind turn persistence, append the missing turn delta
         // instead of truncating session history.
@@ -5701,6 +5941,11 @@ impl SessionManager {
         // Complete all fallible restore migrations before publishing any runtime state.
         // A failed write keeps the session unloaded; restore-time recovery handles any
         // partial metadata/state update left by the existing multi-file persistence format.
+        if let Some(turn) = interrupted_recovery_restored_turn.as_ref() {
+            self.persistence_manager
+                .save_dialog_turn(session_storage_path, turn)
+                .await?;
+        }
         if should_persist_restored_session && self.should_persist_session_id(session_id) {
             self.persistence_manager
                 .save_session(session_storage_path, &session)
@@ -6712,6 +6957,57 @@ impl SessionManager {
         Ok(turn_id)
     }
 
+    /// Persist a Turn only if the execution-affecting Session settings still
+    /// match the snapshot used to resolve its model, permission, prompt, and
+    /// reasoning metadata. The validation and Turn append share one Session
+    /// mutation lock, so a concurrent settings write must retry admission.
+    #[allow(clippy::too_many_arguments)]
+    pub(crate) async fn start_dialog_turn_with_prepended_messages_if_session_matches(
+        &self,
+        session_id: &str,
+        agent_type: String,
+        user_input: String,
+        turn_id: Option<String>,
+        image_contexts: Option<Vec<ImageContextData>>,
+        prepended_messages: Vec<Message>,
+        user_message_metadata: Option<serde_json::Value>,
+        expected: &TurnAdmissionSessionFacts,
+    ) -> BitFunResult<String> {
+        let user_message =
+            if let Some(images) = image_contexts.as_ref().filter(|v| !v.is_empty()).cloned() {
+                Message::user_multimodal(user_input.clone(), images)
+                    .with_semantic_kind(MessageSemanticKind::ActualUserInput)
+            } else {
+                Message::user(user_input.clone())
+                    .with_semantic_kind(MessageSemanticKind::ActualUserInput)
+            };
+        let mut context_messages = prepended_messages;
+        context_messages.push(user_message);
+
+        let _mutation_guard = self.acquire_session_mutation(session_id).await?;
+        let current = self
+            .get_session(session_id)
+            .ok_or_else(|| BitFunError::NotFound(format!("Session not found: {session_id}")))?;
+        if !expected.matches(&current) {
+            return Err(BitFunError::Validation(
+                "Session execution settings changed during turn admission; retry submission"
+                    .to_string(),
+            ));
+        }
+
+        self.start_persisted_turn_locked(
+            session_id,
+            DialogTurnKind::UserDialog,
+            Some(agent_type),
+            user_input,
+            turn_id,
+            context_messages,
+            ProcessingPhase::Starting,
+            user_message_metadata,
+        )
+        .await
+    }
+
     /// Start a new dialog turn when the model-visible user message has already
     /// been inserted into runtime context by the caller.
     ///
@@ -6933,7 +7229,14 @@ impl SessionManager {
             match msg.role {
                 MessageRole::Assistant => {
                     let round_index = rounds.len();
-                    let round_id = format!("{}-round-{}", turn_id, round_index);
+                    let round_id = msg
+                        .metadata
+                        .round_id
+                        .as_deref()
+                        .map(str::trim)
+                        .filter(|round_id| !round_id.is_empty())
+                        .map(str::to_string)
+                        .unwrap_or_else(|| format!("{}-round-{}", turn_id, round_index));
 
                     let mut text_items = Vec::new();
                     let mut thinking_items = Vec::new();
@@ -7228,6 +7531,7 @@ impl SessionManager {
             }
         }
         turn.status = TurnStatus::Completed;
+        turn.recovery = None;
         turn.duration_ms = Some(stats.duration_ms);
         turn.end_time = Some(completion_timestamp);
 
@@ -7253,6 +7557,235 @@ impl SessionManager {
         Ok(())
     }
 
+    fn append_generation_rounds(
+        turn: &mut DialogTurnData,
+        turn_id: &str,
+        new_messages: &[Message],
+        timestamp: u64,
+    ) -> usize {
+        let mut next_round_index = turn
+            .model_rounds
+            .iter()
+            .map(|round| round.round_index)
+            .max()
+            .map_or(0, |index| index.saturating_add(1));
+        let generated_rounds =
+            Self::build_model_rounds_from_messages(new_messages, turn_id, timestamp);
+        let generated_count = generated_rounds.len();
+        for mut round in generated_rounds {
+            if let Some(existing_index) = turn
+                .model_rounds
+                .iter()
+                .position(|existing| existing.id == round.id)
+            {
+                let existing = &turn.model_rounds[existing_index];
+                for text_item in &mut round.text_items {
+                    if let Some(previous) = existing
+                        .text_items
+                        .iter()
+                        .find(|item| item.id == text_item.id)
+                    {
+                        text_item.timestamp = previous.timestamp;
+                        text_item.is_markdown = previous.is_markdown;
+                        text_item.order_index = previous.order_index;
+                        text_item.is_subagent_item = previous.is_subagent_item;
+                        text_item.parent_task_tool_id = previous.parent_task_tool_id.clone();
+                        text_item.subagent_session_id = previous.subagent_session_id.clone();
+                        text_item.status = previous.status.clone().or(text_item.status.clone());
+                        text_item.attempt_id = previous.attempt_id.clone();
+                        text_item.attempt_index = previous.attempt_index;
+                    }
+                }
+                for thinking_item in &mut round.thinking_items {
+                    if let Some(previous) = existing
+                        .thinking_items
+                        .iter()
+                        .find(|item| item.id == thinking_item.id)
+                    {
+                        thinking_item.timestamp = previous.timestamp;
+                        thinking_item.order_index = previous.order_index;
+                        thinking_item.status =
+                            previous.status.clone().or(thinking_item.status.clone());
+                        thinking_item.is_subagent_item = previous.is_subagent_item;
+                        thinking_item.parent_task_tool_id = previous.parent_task_tool_id.clone();
+                        thinking_item.subagent_session_id = previous.subagent_session_id.clone();
+                        thinking_item.attempt_id = previous.attempt_id.clone();
+                        thinking_item.attempt_index = previous.attempt_index;
+                    }
+                }
+                for tool_item in &mut round.tool_items {
+                    if let Some(previous) = existing
+                        .tool_items
+                        .iter()
+                        .find(|item| item.id == tool_item.id)
+                    {
+                        tool_item.ai_intent = previous.ai_intent.clone();
+                        tool_item.start_time = previous.start_time;
+                        tool_item.end_time = previous.end_time.or(tool_item.end_time);
+                        tool_item.duration_ms = previous.duration_ms.or(tool_item.duration_ms);
+                        tool_item.queue_wait_ms = previous.queue_wait_ms;
+                        tool_item.preflight_ms = previous.preflight_ms;
+                        tool_item.confirmation_wait_ms = previous.confirmation_wait_ms;
+                        tool_item.execution_ms = previous.execution_ms;
+                        tool_item.order_index = previous.order_index;
+                        tool_item.is_subagent_item = previous.is_subagent_item;
+                        tool_item.parent_task_tool_id = previous.parent_task_tool_id.clone();
+                        tool_item.subagent_session_id = previous.subagent_session_id.clone();
+                        tool_item.subagent_dialog_turn_id =
+                            previous.subagent_dialog_turn_id.clone();
+                        tool_item.attempt_id = previous.attempt_id.clone();
+                        tool_item.attempt_index = previous.attempt_index;
+                        tool_item.subagent_model_id = previous.subagent_model_id.clone();
+                        tool_item.subagent_model_display_name =
+                            previous.subagent_model_display_name.clone();
+                        tool_item.status = previous.status.clone().or(tool_item.status.clone());
+                        tool_item.interruption_reason = previous.interruption_reason.clone();
+                    }
+                }
+                round.round_index = existing.round_index;
+                round.round_group_id = existing.round_group_id.clone();
+                round.timestamp = existing.timestamp;
+                round.start_time = existing.start_time;
+                round.end_time = existing.end_time.or(round.end_time);
+                round.duration_ms = existing.duration_ms.or(round.duration_ms);
+                round.provider_id = existing.provider_id.clone();
+                round.model_config_id = existing.model_config_id.clone();
+                round.effective_model_name = existing.effective_model_name.clone();
+                round.first_chunk_ms = existing.first_chunk_ms;
+                round.first_visible_output_ms = existing.first_visible_output_ms;
+                round.stream_duration_ms = existing.stream_duration_ms;
+                round.attempt_count = existing.attempt_count;
+                round.attempt_diagnostics = existing.attempt_diagnostics.clone();
+                round.failure_category = existing.failure_category.clone();
+                round.token_details = existing.token_details.clone();
+                if existing.status != "streaming" {
+                    round.status = existing.status.clone();
+                }
+                turn.model_rounds[existing_index] = round;
+            } else {
+                round.round_index = next_round_index;
+                next_round_index = next_round_index.saturating_add(1);
+                turn.model_rounds.push(round);
+            }
+        }
+        generated_count
+    }
+
+    /// Complete a reopened interrupted turn by appending only the messages
+    /// produced by the current execution generation.
+    pub async fn complete_recovered_dialog_turn(
+        &self,
+        session_id: &str,
+        turn_id: &str,
+        execution_generation: u32,
+        final_response: String,
+        new_messages: &[Message],
+        stats: TurnStats,
+    ) -> BitFunResult<()> {
+        let _mutation_guard = self.acquire_session_mutation(session_id).await?;
+        let workspace_path = self
+            .effective_session_storage_path(session_id)
+            .await
+            .ok_or_else(|| {
+                BitFunError::Validation(format!("Session workspace_path is missing: {session_id}"))
+            })?;
+        let turn_index = self
+            .sessions
+            .get(session_id)
+            .and_then(|session| session.dialog_turn_ids.iter().position(|id| id == turn_id))
+            .ok_or_else(|| BitFunError::NotFound(format!("Dialog turn not found: {turn_id}")))?;
+        let mut turn = self
+            .persistence_manager
+            .load_dialog_turn(&workspace_path, session_id, turn_index)
+            .await?
+            .ok_or_else(|| BitFunError::NotFound(format!("Dialog turn not found: {turn_id}")))?;
+
+        if turn.status == TurnStatus::Completed && turn.recovery.is_none() {
+            return Ok(());
+        }
+        let recovery = turn.recovery.as_ref().ok_or_else(|| {
+            BitFunError::Validation(format!(
+                "Recovered dialog turn has no recovery metadata: {turn_id}"
+            ))
+        })?;
+        if recovery.status != DialogTurnRecoveryStatus::Recovering
+            || recovery.execution_generation != execution_generation
+        {
+            return Err(BitFunError::Validation(format!(
+                "Recovered turn generation mismatch: expected={execution_generation}, actual={}",
+                recovery.execution_generation
+            )));
+        }
+
+        let completion_timestamp = SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_millis() as u64;
+        let first_round_index = turn
+            .model_rounds
+            .iter()
+            .map(|round| round.round_index)
+            .max()
+            .map_or(0, |index| index.saturating_add(1));
+        let appended_count =
+            Self::append_generation_rounds(&mut turn, turn_id, new_messages, completion_timestamp);
+        if appended_count == 0 && !final_response.trim().is_empty() {
+            turn.model_rounds.push(ModelRoundData {
+                id: format!("{turn_id}-round-{first_round_index}"),
+                turn_id: turn_id.to_string(),
+                round_index: first_round_index,
+                round_group_id: None,
+                timestamp: completion_timestamp,
+                text_items: vec![Self::make_text_item(
+                    &format!("{turn_id}-round-{first_round_index}-text-0"),
+                    &final_response,
+                    completion_timestamp,
+                    0,
+                )],
+                tool_items: Vec::new(),
+                thinking_items: Vec::new(),
+                start_time: completion_timestamp,
+                end_time: Some(completion_timestamp),
+                duration_ms: Some(0),
+                provider_id: None,
+                model_config_id: None,
+                effective_model_name: None,
+                first_chunk_ms: None,
+                first_visible_output_ms: None,
+                stream_duration_ms: None,
+                attempt_count: None,
+                attempt_diagnostics: vec![],
+                failure_category: None,
+                token_details: None,
+                status: "completed".to_string(),
+            });
+        }
+        turn.status = TurnStatus::Completed;
+        turn.recovery_epoch = Some(execution_generation);
+        turn.recovery = None;
+        turn.duration_ms = Some(stats.duration_ms);
+        turn.end_time = Some(completion_timestamp);
+
+        // A recovered generation is Runtime-owned, so its context snapshot is
+        // part of the completion commit. Persist it before the Completed Turn:
+        // a crash after the snapshot leaves a Recovering Turn that restore can
+        // safely normalize, while a Completed Turn never points at an older
+        // same-index snapshot that omits this generation's tool/results tail.
+        let context_messages = self.context_store.get_context_messages(session_id);
+        self.persistence_manager
+            .save_turn_context_snapshot(
+                &workspace_path,
+                session_id,
+                turn.turn_index,
+                &context_messages,
+            )
+            .await?;
+        self.persistence_manager
+            .save_dialog_turn(&workspace_path, &turn)
+            .await?;
+        Ok(())
+    }
+
     /// Mark a dialog turn as failed and persist it.
     /// Unlike `complete_dialog_turn`, this sets the state to `Failed` with an error message.
     pub async fn fail_dialog_turn(
@@ -7261,6 +7794,18 @@ impl SessionManager {
         turn_id: &str,
         error: String,
     ) -> BitFunResult<()> {
+        self.fail_dialog_turn_with_messages(session_id, turn_id, error, &[])
+            .await
+    }
+
+    pub(crate) async fn fail_dialog_turn_with_messages(
+        &self,
+        session_id: &str,
+        turn_id: &str,
+        error: String,
+        generation_messages: &[Message],
+    ) -> BitFunResult<()> {
+        let _mutation_guard = self.acquire_session_mutation(session_id).await?;
         if !self.should_persist_session_id(session_id) {
             debug!(
                 "Skipping dialog turn persistence for transient session failure: session_id={}, turn_id={}, error={}",
@@ -7288,21 +7833,34 @@ impl SessionManager {
             .load_dialog_turn(&workspace_path, session_id, turn_index)
             .await?
             .ok_or_else(|| BitFunError::NotFound(format!("Dialog turn not found: {}", turn_id)))?;
-
+        let recovered_generation = turn.recovery.is_some();
+        let now = SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_millis() as u64;
+        Self::append_generation_rounds(&mut turn, turn_id, generation_messages, now);
         turn.status = TurnStatus::Error;
-        turn.end_time = Some(
-            SystemTime::now()
-                .duration_since(std::time::UNIX_EPOCH)
-                .unwrap_or_default()
-                .as_millis() as u64,
-        );
+        turn.recovery = None;
+        turn.end_time = Some(now);
 
-        self.persist_context_snapshot_for_turn_best_effort(
-            session_id,
-            turn.turn_index,
-            "turn_failed",
-        )
-        .await;
+        if recovered_generation {
+            let context_messages = self.context_store.get_context_messages(session_id);
+            self.persistence_manager
+                .save_turn_context_snapshot(
+                    &workspace_path,
+                    session_id,
+                    turn.turn_index,
+                    &context_messages,
+                )
+                .await?;
+        } else {
+            self.persist_context_snapshot_for_turn_best_effort(
+                session_id,
+                turn.turn_index,
+                "turn_failed",
+            )
+            .await;
+        }
         if self.should_persist_session_id(session_id) {
             self.persistence_manager
                 .save_dialog_turn(&workspace_path, &turn)
@@ -7323,6 +7881,17 @@ impl SessionManager {
     /// from a fully-completed one. Any partial assistant content that was
     /// already streamed is preserved in `model_rounds`.
     pub async fn cancel_dialog_turn(&self, session_id: &str, turn_id: &str) -> BitFunResult<()> {
+        self.cancel_dialog_turn_with_messages(session_id, turn_id, &[])
+            .await
+    }
+
+    pub(crate) async fn cancel_dialog_turn_with_messages(
+        &self,
+        session_id: &str,
+        turn_id: &str,
+        generation_messages: &[Message],
+    ) -> BitFunResult<()> {
+        let _mutation_guard = self.acquire_session_mutation(session_id).await?;
         if !self.should_persist_session_id(session_id) {
             debug!(
                 "Skipping dialog turn persistence for transient session cancellation: session_id={}, turn_id={}",
@@ -7350,21 +7919,35 @@ impl SessionManager {
             .load_dialog_turn(&workspace_path, session_id, turn_index)
             .await?
             .ok_or_else(|| BitFunError::NotFound(format!("Dialog turn not found: {}", turn_id)))?;
-
+        let recovered_generation = turn.recovery.is_some();
+        let now = SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_millis() as u64;
+        Self::append_generation_rounds(&mut turn, turn_id, generation_messages, now);
         turn.status = TurnStatus::Cancelled;
-        turn.end_time = Some(
-            SystemTime::now()
-                .duration_since(std::time::UNIX_EPOCH)
-                .unwrap_or_default()
-                .as_millis() as u64,
-        );
+        turn.recovery = None;
+        turn.finish_reason = Some("cancelled".to_string());
+        turn.end_time = Some(now);
 
-        self.persist_context_snapshot_for_turn_best_effort(
-            session_id,
-            turn.turn_index,
-            "turn_cancelled",
-        )
-        .await;
+        if recovered_generation {
+            let context_messages = self.context_store.get_context_messages(session_id);
+            self.persistence_manager
+                .save_turn_context_snapshot(
+                    &workspace_path,
+                    session_id,
+                    turn.turn_index,
+                    &context_messages,
+                )
+                .await?;
+        } else {
+            self.persist_context_snapshot_for_turn_best_effort(
+                session_id,
+                turn.turn_index,
+                "turn_cancelled",
+            )
+            .await;
+        }
 
         self.persistence_manager
             .save_dialog_turn(&workspace_path, &turn)
@@ -7378,871 +7961,2400 @@ impl SessionManager {
         Ok(())
     }
 
-    /// Complete a maintenance turn and persist its synthetic model round payload.
-    pub async fn complete_maintenance_turn(
-        &self,
-        session_id: &str,
-        turn_id: &str,
-        model_rounds: Vec<ModelRoundData>,
-        duration_ms: u64,
-    ) -> BitFunResult<()> {
-        self.complete_turn_with_model_rounds(
-            session_id,
-            turn_id,
-            model_rounds,
-            duration_ms,
-            "maintenance_turn_completed",
-        )
-        .await
-    }
-
-    pub(crate) async fn complete_synthetic_dialog_turn(
+    /// Persist a settled, intentionally interrupted user turn without adding a
+    /// new persisted enum variant that older builds cannot deserialize.
+    pub async fn mark_dialog_turn_interrupted(
         &self,
         session_id: &str,
         turn_id: &str,
-        model_rounds: Vec<ModelRoundData>,
-        duration_ms: u64,
-    ) -> BitFunResult<()> {
-        self.complete_turn_with_model_rounds(
-            session_id,
-            turn_id,
-            model_rounds,
-            duration_ms,
-            "synthetic_dialog_turn_completed",
-        )
-        .await
+    ) -> BitFunResult<DialogTurnRecoveryData> {
+        self.mark_dialog_turn_interrupted_with_messages(session_id, turn_id, &[])
+            .await
     }
 
-    async fn complete_turn_with_model_rounds(
+    pub(crate) async fn mark_dialog_turn_interrupted_with_messages(
         &self,
         session_id: &str,
         turn_id: &str,
-        model_rounds: Vec<ModelRoundData>,
-        duration_ms: u64,
-        snapshot_reason: &str,
-    ) -> BitFunResult<()> {
+        generation_messages: &[Message],
+    ) -> BitFunResult<DialogTurnRecoveryData> {
+        let _mutation_guard = self.acquire_session_mutation(session_id).await?;
         if !self.should_persist_session_id(session_id) {
-            debug!(
-                "Skipping turn persistence for transient session completion: session_id={}, turn_id={}, rounds={}, duration_ms={}",
-                session_id,
-                turn_id,
-                model_rounds.len(),
-                duration_ms
-            );
-            return Ok(());
+            return Err(BitFunError::Validation(
+                "Recoverable interruption is unavailable for transient sessions".to_string(),
+            ));
         }
-
-        let workspace_path = self
-            .effective_session_storage_path(session_id)
-            .await
+        let session = self
+            .get_session(session_id)
+            .ok_or_else(|| BitFunError::NotFound(format!("Session not found: {session_id}")))?;
+        let turn_index = session
+            .dialog_turn_ids
+            .len()
+            .checked_sub(1)
+            .filter(|index| session.dialog_turn_ids[*index] == turn_id)
             .ok_or_else(|| {
                 BitFunError::Validation(format!(
-                    "Session workspace_path is missing: {}",
-                    session_id
+                    "Only the latest dialog turn can be interrupted: {turn_id}"
                 ))
             })?;
-        let turn_index = self
-            .sessions
-            .get(session_id)
-            .and_then(|session| session.dialog_turn_ids.iter().position(|id| id == turn_id))
-            .ok_or_else(|| BitFunError::NotFound(format!("Dialog turn not found: {}", turn_id)))?;
+        let workspace_path = self
+            .effective_storage_path_for_config(&session.config)
+            .await
+            .ok_or_else(|| {
+                BitFunError::Validation(format!("Session workspace_path is missing: {session_id}"))
+            })?;
         let mut turn = self
             .persistence_manager
             .load_dialog_turn(&workspace_path, session_id, turn_index)
             .await?
-            .ok_or_else(|| BitFunError::NotFound(format!("Dialog turn not found: {}", turn_id)))?;
+            .ok_or_else(|| BitFunError::NotFound(format!("Dialog turn not found: {turn_id}")))?;
+        if turn.kind != DialogTurnKind::UserDialog {
+            return Err(BitFunError::Validation(
+                "Only a user dialog turn can be interrupted".to_string(),
+            ));
+        }
+        if turn
+            .user_message
+            .metadata
+            .as_ref()
+            .and_then(|metadata| metadata.get("acp_transport"))
+            .and_then(serde_json::Value::as_bool)
+            == Some(true)
+        {
+            return Err(BitFunError::Validation(
+                "Recoverable interruption is unavailable for ACP turns".to_string(),
+            ));
+        }
+        if let Some(recovery) = turn
+            .recovery
+            .as_ref()
+            .filter(|recovery| recovery.status == DialogTurnRecoveryStatus::Interrupted)
+            .cloned()
+        {
+            if turn.recovery_epoch != Some(recovery.execution_generation) {
+                turn.recovery_epoch = Some(recovery.execution_generation);
+                self.persistence_manager
+                    .save_dialog_turn(&workspace_path, &turn)
+                    .await?;
+            }
+            return Ok(recovery);
+        }
+        if turn.status != TurnStatus::InProgress {
+            return Err(BitFunError::Validation(format!(
+                "Dialog turn is not running: {turn_id}"
+            )));
+        }
 
-        let completion_timestamp = SystemTime::now()
+        // Recovery is offered only when the exact settled model context is
+        // durable. If this write fails, the coordinator falls back to an
+        // ordinary non-recoverable cancellation rather than exposing a broken
+        // continue button.
+        let context_messages = self.context_store.get_context_messages(session_id);
+        self.persistence_manager
+            .save_turn_context_snapshot(&workspace_path, session_id, turn_index, &context_messages)
+            .await?;
+        let now = SystemTime::now()
             .duration_since(std::time::UNIX_EPOCH)
             .unwrap_or_default()
             .as_millis() as u64;
-        turn.model_rounds = model_rounds;
-        turn.status = TurnStatus::Completed;
-        turn.duration_ms = Some(duration_ms);
-        turn.end_time = Some(completion_timestamp);
-
-        self.persist_context_snapshot_for_turn_best_effort(
-            session_id,
-            turn.turn_index,
-            snapshot_reason,
-        )
-        .await;
-
-        if self.should_persist_session_id(session_id) {
-            self.persistence_manager
-                .save_dialog_turn(&workspace_path, &turn)
-                .await?;
-        }
-
-        Ok(())
-    }
-
-    /// Mark a maintenance turn as failed while preserving its synthetic tool state.
-    pub async fn fail_maintenance_turn(
-        &self,
-        session_id: &str,
-        turn_id: &str,
-        error: String,
-        model_rounds: Vec<ModelRoundData>,
-    ) -> BitFunResult<()> {
-        self.fail_turn_with_model_rounds(
-            session_id,
-            turn_id,
-            error,
-            model_rounds,
-            "maintenance_turn_failed",
-        )
-        .await
-    }
-
-    pub(crate) async fn fail_synthetic_dialog_turn(
-        &self,
-        session_id: &str,
-        turn_id: &str,
-        error: String,
-        model_rounds: Vec<ModelRoundData>,
-    ) -> BitFunResult<()> {
-        self.fail_turn_with_model_rounds(
-            session_id,
-            turn_id,
-            error,
-            model_rounds,
-            "synthetic_dialog_turn_failed",
-        )
-        .await
+        let recovery = match turn.recovery.take() {
+            Some(mut recovery) => {
+                recovery.status = DialogTurnRecoveryStatus::Interrupted;
+                recovery.interrupted_at = Some(now);
+                recovery
+            }
+            None => DialogTurnRecoveryData {
+                status: DialogTurnRecoveryStatus::Interrupted,
+                execution_generation: 0,
+                resume_count: 0,
+                interrupted_at: Some(now),
+                model_id: session.config.model_id.clone(),
+            },
+        };
+        Self::append_generation_rounds(&mut turn, turn_id, generation_messages, now);
+        turn.status = TurnStatus::Cancelled;
+        turn.finish_reason = Some("interrupted".to_string());
+        turn.end_time = Some(now);
+        turn.duration_ms = Some(now.saturating_sub(turn.start_time));
+        turn.recovery = Some(recovery.clone());
+        turn.recovery_epoch = Some(recovery.execution_generation);
+        self.persistence_manager
+            .save_dialog_turn(&workspace_path, &turn)
+            .await?;
+        Ok(recovery)
     }
 
-    async fn fail_turn_with_model_rounds(
+    /// Reopen the latest settled interrupted user turn from its exact context
+    /// snapshot. This does not run prompt-submit hooks or append a user Turn.
+    pub(crate) async fn reopen_interrupted_dialog_turn(
         &self,
         session_id: &str,
         turn_id: &str,
-        error: String,
-        model_rounds: Vec<ModelRoundData>,
-        snapshot_reason: &str,
-    ) -> BitFunResult<()> {
-        if !self.should_persist_session_id(session_id) {
-            debug!(
-                "Skipping turn persistence for transient session failure: session_id={}, turn_id={}, rounds={}, error={}",
-                session_id,
-                turn_id,
-                model_rounds.len(),
-                error
-            );
-            return Ok(());
-        }
-
-        let workspace_path = self
-            .effective_session_storage_path(session_id)
-            .await
+        expected_execution_generation: u32,
+    ) -> BitFunResult<InterruptedTurnRecoveryPlan> {
+        let _mutation_guard = self.acquire_session_mutation(session_id).await?;
+        let session = self
+            .get_session(session_id)
+            .ok_or_else(|| BitFunError::NotFound(format!("Session not found: {session_id}")))?;
+        let turn_index = session
+            .dialog_turn_ids
+            .len()
+            .checked_sub(1)
+            .filter(|index| session.dialog_turn_ids[*index] == turn_id)
             .ok_or_else(|| {
                 BitFunError::Validation(format!(
-                    "Session workspace_path is missing: {}",
-                    session_id
+                    "Only the latest dialog turn can be recovered: {turn_id}"
                 ))
             })?;
-        let turn_index = self
-            .sessions
-            .get(session_id)
-            .and_then(|session| session.dialog_turn_ids.iter().position(|id| id == turn_id))
-            .ok_or_else(|| BitFunError::NotFound(format!("Dialog turn not found: {}", turn_id)))?;
+        let workspace_path = self
+            .effective_storage_path_for_config(&session.config)
+            .await
+            .ok_or_else(|| {
+                BitFunError::Validation(format!("Session workspace_path is missing: {session_id}"))
+            })?;
         let mut turn = self
             .persistence_manager
             .load_dialog_turn(&workspace_path, session_id, turn_index)
             .await?
-            .ok_or_else(|| BitFunError::NotFound(format!("Dialog turn not found: {}", turn_id)))?;
-
-        let completion_timestamp = SystemTime::now()
-            .duration_since(std::time::UNIX_EPOCH)
-            .unwrap_or_default()
-            .as_millis() as u64;
-        turn.model_rounds = model_rounds;
-        turn.status = TurnStatus::Error;
-        turn.error = Some(error.clone());
-        turn.duration_ms = Some(completion_timestamp.saturating_sub(turn.start_time));
-        turn.end_time = Some(completion_timestamp);
-
-        self.persist_context_snapshot_for_turn_best_effort(
-            session_id,
-            turn.turn_index,
-            snapshot_reason,
-        )
-        .await;
-
-        if self.should_persist_session_id(session_id) {
-            self.persistence_manager
-                .save_dialog_turn(&workspace_path, &turn)
-                .await?;
+            .ok_or_else(|| BitFunError::NotFound(format!("Dialog turn not found: {turn_id}")))?;
+        let original_turn = turn.clone();
+        let recovery = turn.recovery.as_ref().ok_or_else(|| {
+            BitFunError::Validation(format!("Dialog turn has no recovery metadata: {turn_id}"))
+        })?;
+        if recovery.status != DialogTurnRecoveryStatus::Interrupted
+            || recovery.execution_generation != expected_execution_generation
+        {
+            return Err(BitFunError::Validation(format!(
+                "Interrupted turn generation mismatch: expected={}, actual={}",
+                expected_execution_generation, recovery.execution_generation
+            )));
         }
-
-        debug!(
-            "Turn marked as failed: turn_id={}, turn_index={}, error={}",
-            turn_id, turn.turn_index, error
-        );
-
-        Ok(())
-    }
-
-    // ============ Helper Methods ============
-
-    /// Get a best-effort message view for the session.
-    /// When persistence is enabled, rebuild from persisted turns so callers see the
-    /// canonical turn history instead of the runtime context cache.
-    pub async fn get_messages(&self, session_id: &str) -> BitFunResult<Vec<Message>> {
-        if self.config.enable_persistence {
-            if let Some(workspace_path) = self.effective_session_storage_path(session_id).await {
-                let _history_read = self.acquire_session_mutation(session_id).await?;
-                let messages = self
-                    .rebuild_messages_from_turns(&workspace_path, session_id)
-                    .await?;
-                if !messages.is_empty() {
-                    return Ok(messages);
-                }
-            }
+        if recovery.model_id != session.config.model_id {
+            return Err(BitFunError::Validation(
+                "The session model changed after interruption; start a new turn instead"
+                    .to_string(),
+            ));
         }
-
-        Ok(self.context_store.get_context_messages(session_id))
-    }
-
-    /// Load canonical persisted turns for a user-facing transcript.
-    ///
-    /// This is intentionally separate from `get_messages`: runtime context
-    /// reconstruction excludes model-invisible maintenance turns, while a
-    /// transcript must be able to project those turns for the UI.
-    pub(crate) async fn load_persisted_transcript_turns_locked(
-        &self,
-        session_id: &str,
-    ) -> BitFunResult<Option<Vec<DialogTurnData>>> {
-        if !self.config.enable_persistence {
-            return Ok(None);
+        if turn
+            .agent_type
+            .as_deref()
+            .is_some_and(|agent_type| agent_type != session.agent_type)
+        {
+            return Err(BitFunError::Validation(
+                "The session agent mode changed after interruption; start a new turn instead"
+                    .to_string(),
+            ));
         }
-        let Some(workspace_path) = self.effective_session_storage_path(session_id).await else {
-            return Ok(None);
-        };
-        let mut turns = self
-            .persistence_manager
-            .load_session_turns(&workspace_path, session_id)
-            .await?;
-        if let Some(revert) = self
+        if turn.kind != DialogTurnKind::UserDialog || turn.status != TurnStatus::Cancelled {
+            return Err(BitFunError::Validation(format!(
+                "Dialog turn is not recoverably interrupted: {turn_id}"
+            )));
+        }
+        if turn
+            .user_message
+            .metadata
+            .as_ref()
+            .and_then(|metadata| metadata.get("acp_transport"))
+            .and_then(serde_json::Value::as_bool)
+            == Some(true)
+        {
+            return Err(BitFunError::Validation(
+                "Interrupted ACP turns cannot be recovered through the native runtime".to_string(),
+            ));
+        }
+        if !matches!(session.state, SessionState::Idle) {
+            return Err(BitFunError::Validation(format!(
+                "Session must be idle before recovering turn: {turn_id}"
+            )));
+        }
+        let mut messages = self
             .persistence_manager
-            .load_session_revert_state(&workspace_path, session_id)
+            .load_turn_context_snapshot(&workspace_path, session_id, turn_index)
             .await?
+            .ok_or_else(|| {
+                BitFunError::Validation(format!(
+                    "Context snapshot is unavailable for interrupted turn: {turn_id}"
+                ))
+            })?;
+        messages.retain(|message| {
+            message.internal_reminder_kind() != Some(InternalReminderKind::InterruptedContinue)
+        });
+        messages.push(
+            Message::internal_reminder(
+                InternalReminderKind::InterruptedContinue,
+                "Your previous work was interrupted by the user. Continue the same task from the last safe context boundary. Do not repeat completed work or assume that an interrupted tool call had no side effects; verify uncertain external state before acting again.",
+            )
+            .with_turn_id(turn_id.to_string()),
+        );
+
+        let next_generation = recovery.execution_generation.saturating_add(1);
+        let next_resume_count = recovery.resume_count.saturating_add(1);
+        turn.status = TurnStatus::InProgress;
+        turn.finish_reason = None;
+        turn.end_time = None;
+        turn.duration_ms = None;
+        turn.error = None;
+        turn.error_detail = None;
+        turn.recovery = Some(DialogTurnRecoveryData {
+            status: DialogTurnRecoveryStatus::Recovering,
+            execution_generation: next_generation,
+            resume_count: next_resume_count,
+            interrupted_at: recovery.interrupted_at,
+            model_id: recovery.model_id.clone(),
+        });
+        turn.recovery_epoch = Some(next_generation);
+        let initial_round_index = turn
+            .model_rounds
+            .iter()
+            .map(|round| round.round_index)
+            .max()
+            .map_or(0, |index| index.saturating_add(1));
+        let agent_type = turn
+            .agent_type
+            .clone()
+            .filter(|value| !value.trim().is_empty())
+            .ok_or_else(|| {
+                BitFunError::Validation(format!("Interrupted turn has no agent type: {turn_id}"))
+            })?;
+        let user_message_metadata = turn.user_message.metadata.clone();
+        let resolved_permission_mode = user_message_metadata
+            .as_ref()
+            .and_then(|metadata| metadata.get(INTERRUPTED_TURN_PERMISSION_MODE_METADATA_KEY))
+            .and_then(serde_json::Value::as_str)
+            .and_then(PermissionMode::parse)
+            .ok_or_else(|| {
+                BitFunError::Validation(
+                    "Interrupted turn has no frozen permission mode; start a new turn instead"
+                        .to_string(),
+                )
+            })?;
+        let resolved_model_id = user_message_metadata
+            .as_ref()
+            .and_then(|metadata| metadata.get(INTERRUPTED_TURN_RESOLVED_MODEL_ID_METADATA_KEY))
+            .and_then(serde_json::Value::as_str)
+            .map(str::trim)
+            .filter(|model_id| !model_id.is_empty())
+            .map(str::to_string)
+            .ok_or_else(|| {
+                BitFunError::Validation(
+                    "Interrupted turn has no frozen resolved model; start a new turn instead"
+                        .to_string(),
+                )
+            })?;
+        let expected_model_binding_fingerprint = user_message_metadata
+            .as_ref()
+            .and_then(|metadata| {
+                metadata.get(INTERRUPTED_TURN_MODEL_BINDING_FINGERPRINT_METADATA_KEY)
+            })
+            .and_then(serde_json::Value::as_str)
+            .map(str::trim)
+            .filter(|fingerprint| !fingerprint.is_empty())
+            .map(str::to_string)
+            .ok_or_else(|| {
+                BitFunError::Validation(
+                    "Interrupted turn has no frozen model binding; start a new turn instead"
+                        .to_string(),
+                )
+            })?;
+        let ai_config = Self::load_ai_config_for_model_resolution()
+            .await
+            .ok_or_else(|| {
+                BitFunError::AIClient(
+                    "AI configuration is unavailable; retry interrupted turn recovery".to_string(),
+                )
+            })?;
+        let canonical_model_id = ai_config
+            .resolve_model_reference(&resolved_model_id)
+            .ok_or_else(|| {
+                BitFunError::Validation(format!(
+                    "The interrupted turn model is unavailable: {resolved_model_id}"
+                ))
+            })?;
+        let model = ai_config
+            .models
+            .iter()
+            .find(|model| model.enabled && model.id == canonical_model_id)
+            .ok_or_else(|| {
+                BitFunError::Validation(format!(
+                    "The interrupted turn model is unavailable: {resolved_model_id}"
+                ))
+            })?;
+        if model_runtime_binding_fingerprint(model) != expected_model_binding_fingerprint {
+            return Err(BitFunError::Validation(format!(
+                "The interrupted turn model binding changed after interruption: {resolved_model_id}"
+            )));
+        }
+        let resolved_reasoning_preset = match user_message_metadata
+            .as_ref()
+            .and_then(|metadata| metadata.get(INTERRUPTED_TURN_REASONING_PRESET_METADATA_KEY))
         {
-            turns.retain(|turn| turn.turn_index < revert.boundary_turn);
+            Some(serde_json::Value::Null) => None,
+            Some(serde_json::Value::String(value)) => value
+                .trim()
+                .is_empty()
+                .then_some(None)
+                .unwrap_or_else(|| Some(value.trim().to_string())),
+            _ => {
+                return Err(BitFunError::Validation(
+                    "Interrupted turn has no frozen reasoning preset; start a new turn instead"
+                        .to_string(),
+                ))
+            }
+        };
+        let expected_reasoning_fingerprint = user_message_metadata
+            .as_ref()
+            .and_then(|metadata| metadata.get(INTERRUPTED_TURN_REASONING_FINGERPRINT_METADATA_KEY))
+            .and_then(serde_json::Value::as_str)
+            .map(str::trim)
+            .filter(|fingerprint| !fingerprint.is_empty())
+            .ok_or_else(|| {
+                BitFunError::Validation(
+                    "Interrupted turn has no frozen reasoning fingerprint; start a new turn instead"
+                        .to_string(),
+                )
+            })?;
+        let reasoning_selection =
+            match user_message_metadata.as_ref().and_then(|metadata| {
+                metadata.get(INTERRUPTED_TURN_REASONING_SELECTION_METADATA_KEY)
+            }) {
+                Some(serde_json::Value::Null) => None,
+                Some(serde_json::Value::String(value)) => value
+                    .trim()
+                    .is_empty()
+                    .then_some(None)
+                    .unwrap_or_else(|| Some(value.trim().to_string())),
+                _ => return Err(BitFunError::Validation(
+                    "Interrupted turn has no frozen reasoning selection; start a new turn instead"
+                        .to_string(),
+                )),
+            };
+        if reasoning_selection != session.config.reasoning_preset {
+            return Err(BitFunError::Validation(
+                "The session reasoning preset changed after interruption; start a new turn instead"
+                    .to_string(),
+            ));
         }
-        Ok(Some(turns))
-    }
-
-    /// Get a paginated best-effort message view for the session.
-    pub async fn get_messages_paginated(
-        &self,
-        session_id: &str,
-        limit: usize,
-        before_message_id: Option<&str>,
-    ) -> BitFunResult<(Vec<Message>, bool)> {
-        let messages = self.get_messages(session_id).await?;
-        Ok(Self::paginate_messages(&messages, limit, before_message_id))
-    }
-
-    /// Get session's runtime context messages (may already include compressed reminders).
-    pub async fn get_context_messages(&self, session_id: &str) -> BitFunResult<Vec<Message>> {
-        let context_messages = self.context_store.get_context_messages(session_id);
+        let (current_resolved_reasoning_preset, current_reasoning_fingerprint) =
+            Self::resolve_effective_reasoning_preset_from_config(
+                &ai_config,
+                &resolved_model_id,
+                reasoning_selection.as_deref(),
+            )
+            .await?;
+        if current_resolved_reasoning_preset != resolved_reasoning_preset {
+            return Err(BitFunError::Validation(
+                "The dialog turn reasoning contract changed after interruption; start a new turn instead"
+                    .to_string(),
+            ));
+        }
+        if current_reasoning_fingerprint != expected_reasoning_fingerprint {
+            return Err(BitFunError::Validation(
+                "The dialog turn reasoning runtime contract changed after interruption; start a new turn instead"
+                    .to_string(),
+            ));
+        }
+        let user_input = turn.user_message.content.clone();
 
-        Ok(context_messages)
-    }
+        let mut updated_session = session.clone();
+        updated_session.state = SessionState::Processing {
+            current_turn_id: turn_id.to_string(),
+            phase: ProcessingPhase::Starting,
+        };
+        let now = SystemTime::now();
+        updated_session.updated_at = now;
+        updated_session.last_activity_at = now;
 
-    /// Add a semantic message to the runtime context cache and immediately refresh the current
-    /// turn snapshot so crashes do not lose the latest in-memory context change.
-    pub async fn add_message(&self, session_id: &str, message: Message) -> BitFunResult<()> {
-        let memory_citation = message.metadata.memory_citation.clone();
-        let turn_id = message.metadata.turn_id.clone();
-        let round_id = message.metadata.round_id.clone();
-        let message_id = message.id.clone();
-        self.context_store.add_message(session_id, message);
-        if let Some(citation) = memory_citation.as_ref() {
-            if let Err(error) = self
-                .memory_database
-                .record_memory_citation(
-                    session_id,
-                    turn_id.as_deref(),
-                    round_id.as_deref(),
-                    &message_id,
-                    citation,
-                )
+        self.persistence_manager
+            .save_turn_context_snapshot(&workspace_path, session_id, turn_index, &messages)
+            .await?;
+        if let Err(error) = self
+            .persistence_manager
+            .save_dialog_turn(&workspace_path, &turn)
+            .await
+        {
+            if let Err(rollback_error) = self
+                .persistence_manager
+                .save_dialog_turn(&workspace_path, &original_turn)
                 .await
             {
-                warn!(
-                    "Failed to record memory citation: session_id={}, message_id={}, error={}",
-                    session_id, message_id, error
-                );
+                return Err(BitFunError::session(format!(
+                    "Recovery turn persistence failed and rollback did not complete: session_id={session_id}, turn_id={turn_id}, error={error}, rollback_error={rollback_error}"
+                )));
             }
+            return Err(error);
+        }
+        if let Err(error) = self
+            .persistence_manager
+            .save_session(&workspace_path, &updated_session)
+            .await
+        {
+            let session_rollback = self
+                .persistence_manager
+                .save_session(&workspace_path, &session)
+                .await;
+            let turn_rollback = self
+                .persistence_manager
+                .save_dialog_turn(&workspace_path, &original_turn)
+                .await;
+            if session_rollback.is_err() || turn_rollback.is_err() {
+                return Err(BitFunError::session(format!(
+                    "Recovery persistence failed and rollback did not complete: session_id={session_id}, turn_id={turn_id}, error={error}, session_rollback_error={:?}, turn_rollback_error={:?}",
+                    session_rollback.err(),
+                    turn_rollback.err(),
+                )));
+            }
+            return Err(error);
         }
-        self.persist_current_turn_context_snapshot_best_effort(session_id, "context_message_added")
-            .await;
-        Ok(())
-    }
 
-    /// Replace the runtime context cache for a session and immediately refresh the current turn
-    /// snapshot. This is primarily used after compression rewrites the model-visible context.
-    pub async fn replace_context_messages(&self, session_id: &str, messages: Vec<Message>) {
+        self.sessions
+            .insert(session_id.to_string(), updated_session);
         self.context_store
             .replace_context(session_id, messages.clone());
-        self.file_read_state_store.clear_session(session_id);
-        self.prune_token_anchors_to_messages(session_id, &messages)
-            .await;
-        self.persist_current_turn_context_snapshot_best_effort(session_id, "context_replaced")
-            .await;
-    }
 
-    pub fn set_file_read_state(&self, session_id: &str, logical_path: &str, state: FileReadState) {
-        self.file_read_state_store
-            .set(session_id, logical_path, state);
+        Ok(InterruptedTurnRecoveryPlan {
+            session_id: session_id.to_string(),
+            turn_id: turn_id.to_string(),
+            turn_index,
+            agent_type,
+            execution_generation: next_generation,
+            resume_count: next_resume_count,
+            initial_round_index,
+            resolved_permission_mode,
+            resolved_model_id,
+            model_binding_fingerprint: expected_model_binding_fingerprint,
+            user_input,
+            messages,
+            user_message_metadata,
+        })
     }
 
-    pub fn get_file_read_state(
+    pub(crate) async fn latest_dialog_turn_holds_dispatch(
         &self,
         session_id: &str,
-        logical_path: &str,
-    ) -> Option<FileReadState> {
-        self.file_read_state_store.get(session_id, logical_path)
+    ) -> BitFunResult<bool> {
+        if !self.should_persist_session_id(session_id) {
+            return Ok(false);
+        }
+        let Some(session) = self.get_session(session_id) else {
+            return Ok(false);
+        };
+        let Some(turn_index) = session.dialog_turn_ids.len().checked_sub(1) else {
+            return Ok(false);
+        };
+        let Some(workspace_path) = self
+            .effective_storage_path_for_config(&session.config)
+            .await
+        else {
+            return Ok(false);
+        };
+        let Some(turn) = self
+            .persistence_manager
+            .load_dialog_turn(&workspace_path, session_id, turn_index)
+            .await?
+        else {
+            return Ok(false);
+        };
+        Ok(turn.status == TurnStatus::Cancelled
+            && turn
+                .recovery
+                .as_ref()
+                .is_some_and(|recovery| recovery.status == DialogTurnRecoveryStatus::Interrupted))
     }
 
-    pub fn record_review_read(
+    pub(crate) async fn abandon_interrupted_dialog_turn(
         &self,
         session_id: &str,
-        logical_path: &str,
-        revision: FileRevision,
-        start_line: usize,
-        end_line: usize,
-        total_lines: usize,
-    ) {
-        self.file_read_state_store.record_review_read(
-            session_id,
-            logical_path,
-            revision,
-            start_line,
-            end_line,
-            total_lines,
-        );
+        expected_turn_id: Option<&str>,
+    ) -> BitFunResult<Option<String>> {
+        let _mutation_guard = self.acquire_session_mutation(session_id).await?;
+        let Some(session) = self.get_session(session_id) else {
+            return Ok(None);
+        };
+        let turn_index = match expected_turn_id {
+            Some(expected) => session
+                .dialog_turn_ids
+                .iter()
+                .position(|turn_id| turn_id == expected),
+            None => session.dialog_turn_ids.len().checked_sub(1),
+        };
+        let Some(turn_index) = turn_index else {
+            return Ok(None);
+        };
+        let Some(workspace_path) = self
+            .effective_storage_path_for_config(&session.config)
+            .await
+        else {
+            return Ok(None);
+        };
+        let Some(mut turn) = self
+            .persistence_manager
+            .load_dialog_turn(&workspace_path, session_id, turn_index)
+            .await?
+        else {
+            return Ok(None);
+        };
+        if turn.status != TurnStatus::Cancelled
+            || !turn
+                .recovery
+                .as_ref()
+                .is_some_and(|recovery| recovery.status == DialogTurnRecoveryStatus::Interrupted)
+        {
+            return Ok(None);
+        }
+        turn.recovery = None;
+        turn.finish_reason = Some("cancelled".to_string());
+        let turn_id = turn.turn_id.clone();
+        self.persistence_manager
+            .save_dialog_turn(&workspace_path, &turn)
+            .await?;
+        Ok(Some(turn_id))
     }
 
-    pub fn review_read_coverage(
+    /// Complete a maintenance turn and persist its synthetic model round payload.
+    pub async fn complete_maintenance_turn(
         &self,
         session_id: &str,
-        logical_path: &str,
-        revision: FileRevision,
-        start_line: usize,
-        limit: usize,
-    ) -> Option<ReviewReadCoverage> {
-        self.file_read_state_store.review_read_coverage(
+        turn_id: &str,
+        model_rounds: Vec<ModelRoundData>,
+        duration_ms: u64,
+    ) -> BitFunResult<()> {
+        self.complete_turn_with_model_rounds(
             session_id,
-            logical_path,
-            revision,
-            start_line,
-            limit,
+            turn_id,
+            model_rounds,
+            duration_ms,
+            "maintenance_turn_completed",
         )
+        .await
     }
 
-    /// Get dialog turn count
-    pub fn get_turn_count(&self, session_id: &str) -> usize {
-        self.sessions
-            .get(session_id)
-            .map(|s| s.dialog_turn_ids.len())
-            .unwrap_or(0)
-    }
-
-    /// Get session's compression state
-    pub fn get_compression_state(&self, session_id: &str) -> Option<CompressionState> {
-        self.sessions
-            .get(session_id)
-            .map(|s| s.compression_state.clone())
+    pub(crate) async fn complete_synthetic_dialog_turn(
+        &self,
+        session_id: &str,
+        turn_id: &str,
+        model_rounds: Vec<ModelRoundData>,
+        duration_ms: u64,
+    ) -> BitFunResult<()> {
+        self.complete_turn_with_model_rounds(
+            session_id,
+            turn_id,
+            model_rounds,
+            duration_ms,
+            "synthetic_dialog_turn_completed",
+        )
+        .await
     }
 
-    /// Update session's compression state
-    pub async fn update_compression_state(
+    async fn complete_turn_with_model_rounds(
         &self,
         session_id: &str,
-        compression_state: CompressionState,
+        turn_id: &str,
+        model_rounds: Vec<ModelRoundData>,
+        duration_ms: u64,
+        snapshot_reason: &str,
     ) -> BitFunResult<()> {
-        let _mutation_guard = self.acquire_session_mutation(session_id).await?;
-        let effective_path = self.effective_session_storage_path(session_id).await;
+        if !self.should_persist_session_id(session_id) {
+            debug!(
+                "Skipping turn persistence for transient session completion: session_id={}, turn_id={}, rounds={}, duration_ms={}",
+                session_id,
+                turn_id,
+                model_rounds.len(),
+                duration_ms
+            );
+            return Ok(());
+        }
 
-        // IMPORTANT: keep the DashMap guard scope short -- do NOT hold it across .await.
-        let session_snapshot = if let Some(mut session) = self.sessions.get_mut(session_id) {
-            session.compression_state = compression_state;
-            session.updated_at = SystemTime::now();
-            session.last_activity_at = SystemTime::now();
-            if self.config.enable_persistence && self.should_persist_session(&session) {
-                Some(session.clone())
-            } else {
-                None
-            }
-        } else {
-            return Err(BitFunError::NotFound(format!(
-                "Session not found: {}",
-                session_id
-            )));
-        };
-        // RefMut guard released here -- DashMap shard lock is free.
+        let workspace_path = self
+            .effective_session_storage_path(session_id)
+            .await
+            .ok_or_else(|| {
+                BitFunError::Validation(format!(
+                    "Session workspace_path is missing: {}",
+                    session_id
+                ))
+            })?;
+        let turn_index = self
+            .sessions
+            .get(session_id)
+            .and_then(|session| session.dialog_turn_ids.iter().position(|id| id == turn_id))
+            .ok_or_else(|| BitFunError::NotFound(format!("Dialog turn not found: {}", turn_id)))?;
+        let mut turn = self
+            .persistence_manager
+            .load_dialog_turn(&workspace_path, session_id, turn_index)
+            .await?
+            .ok_or_else(|| BitFunError::NotFound(format!("Dialog turn not found: {}", turn_id)))?;
 
-        if let Some(session) = session_snapshot {
-            if let Some(ref workspace_path) = effective_path {
-                self.persistence_manager
-                    .save_session(workspace_path, &session)
-                    .await?;
-            }
+        let completion_timestamp = SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_millis() as u64;
+        turn.model_rounds = model_rounds;
+        turn.status = TurnStatus::Completed;
+        turn.duration_ms = Some(duration_ms);
+        turn.end_time = Some(completion_timestamp);
+
+        self.persist_context_snapshot_for_turn_best_effort(
+            session_id,
+            turn.turn_index,
+            snapshot_reason,
+        )
+        .await;
+
+        if self.should_persist_session_id(session_id) {
+            self.persistence_manager
+                .save_dialog_turn(&workspace_path, &turn)
+                .await?;
         }
 
         Ok(())
     }
 
-    async fn try_generate_session_title_with_ai(
+    /// Mark a maintenance turn as failed while preserving its synthetic tool state.
+    pub async fn fail_maintenance_turn(
         &self,
-        user_message: &str,
-        max_length: usize,
-    ) -> BitFunResult<Option<String>> {
-        use crate::util::types::Message;
-
-        // Match agent `LANGUAGE_PREFERENCE`: use `app.language`, not I18nService (see `app_language` module).
-        let lang_code = get_app_language_code().await;
-        let language_instruction = short_model_user_language_instruction(lang_code.as_str());
+        session_id: &str,
+        turn_id: &str,
+        error: String,
+        model_rounds: Vec<ModelRoundData>,
+    ) -> BitFunResult<()> {
+        self.fail_turn_with_model_rounds(
+            session_id,
+            turn_id,
+            error,
+            model_rounds,
+            "maintenance_turn_failed",
+        )
+        .await
+    }
 
-        // Construct system prompt
-        let system_prompt = format!(
-            "You are a professional session title generation assistant. Based on the user's message content, generate a concise and accurate session title.\n\nRequirements:\n- Title should not exceed {} characters\n- {}\n- Concise and accurate, reflecting the conversation topic\n- Do not add quotes or other decorative symbols\n- Return only the title text, no other content",
-            max_length, language_instruction
-        );
+    pub(crate) async fn fail_synthetic_dialog_turn(
+        &self,
+        session_id: &str,
+        turn_id: &str,
+        error: String,
+        model_rounds: Vec<ModelRoundData>,
+    ) -> BitFunResult<()> {
+        self.fail_turn_with_model_rounds(
+            session_id,
+            turn_id,
+            error,
+            model_rounds,
+            "synthetic_dialog_turn_failed",
+        )
+        .await
+    }
 
-        // Truncate message to save tokens (max 200 characters)
-        let truncated_message = if user_message.chars().count() > 200 {
-            format!("{}...", user_message.chars().take(200).collect::<String>())
-        } else {
-            user_message.to_string()
-        };
+    async fn fail_turn_with_model_rounds(
+        &self,
+        session_id: &str,
+        turn_id: &str,
+        error: String,
+        model_rounds: Vec<ModelRoundData>,
+        snapshot_reason: &str,
+    ) -> BitFunResult<()> {
+        if !self.should_persist_session_id(session_id) {
+            debug!(
+                "Skipping turn persistence for transient session failure: session_id={}, turn_id={}, rounds={}, error={}",
+                session_id,
+                turn_id,
+                model_rounds.len(),
+                error
+            );
+            return Ok(());
+        }
 
-        let user_prompt = format!(
-            "User message: {}\n\nPlease generate session title:",
-            truncated_message
-        );
+        let workspace_path = self
+            .effective_session_storage_path(session_id)
+            .await
+            .ok_or_else(|| {
+                BitFunError::Validation(format!(
+                    "Session workspace_path is missing: {}",
+                    session_id
+                ))
+            })?;
+        let turn_index = self
+            .sessions
+            .get(session_id)
+            .and_then(|session| session.dialog_turn_ids.iter().position(|id| id == turn_id))
+            .ok_or_else(|| BitFunError::NotFound(format!("Dialog turn not found: {}", turn_id)))?;
+        let mut turn = self
+            .persistence_manager
+            .load_dialog_turn(&workspace_path, session_id, turn_index)
+            .await?
+            .ok_or_else(|| BitFunError::NotFound(format!("Dialog turn not found: {}", turn_id)))?;
 
-        // Construct messages (using AIClient's Message type)
-        let messages = vec![
-            Message {
-                role: "system".to_string(),
-                content: Some(system_prompt),
-                reasoning_content: None,
-                thinking_signature: None,
-                tool_calls: None,
-                tool_call_id: None,
-                name: None,
-                is_error: None,
-                tool_image_attachments: None,
-            },
-            Message {
-                role: "user".to_string(),
-                content: Some(user_prompt),
-                reasoning_content: None,
-                thinking_signature: None,
-                tool_calls: None,
-                tool_call_id: None,
-                name: None,
-                is_error: None,
-                tool_image_attachments: None,
-            },
-        ];
-
-        // Dynamically get Agent client to generate title
-        let ai_client_factory = get_global_ai_client_factory().await.map_err(|e| {
-            BitFunError::AIClient(format!("Failed to get AI client factory: {}", e))
-        })?;
-
-        let ai_client = ai_client_factory
-            .get_client_by_func_agent("session-title-func-agent")
-            .await
-            .map_err(|e| BitFunError::AIClient(format!("Failed to get AI client: {}", e)))?;
+        let completion_timestamp = SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_millis() as u64;
+        turn.model_rounds = model_rounds;
+        turn.status = TurnStatus::Error;
+        turn.error = Some(error.clone());
+        turn.duration_ms = Some(completion_timestamp.saturating_sub(turn.start_time));
+        turn.end_time = Some(completion_timestamp);
 
-        let response = ai_client
-            .send_message(messages, None)
-            .await
-            .map_err(|e| BitFunError::ai(format!("AI call failed: {}", e)))?;
+        self.persist_context_snapshot_for_turn_best_effort(
+            session_id,
+            turn.turn_index,
+            snapshot_reason,
+        )
+        .await;
 
-        let title = sanitize_plain_model_output(&response.text);
-        if title.is_empty() {
-            return Ok(None);
+        if self.should_persist_session_id(session_id) {
+            self.persistence_manager
+                .save_dialog_turn(&workspace_path, &turn)
+                .await?;
         }
 
-        // Truncate title
-        let final_title = if title.chars().count() > max_length {
-            title.chars().take(max_length).collect::<String>()
-        } else {
-            title
-        };
+        debug!(
+            "Turn marked as failed: turn_id={}, turn_index={}, error={}",
+            turn_id, turn.turn_index, error
+        );
 
-        Ok(Some(final_title))
+        Ok(())
     }
 
-    /// Generate a concise session title, using AI first and falling back to a local heuristic.
-    pub async fn resolve_session_title(
-        &self,
-        user_message: &str,
-        max_length: Option<usize>,
-        allow_ai: bool,
-    ) -> ResolvedSessionTitle {
-        let max_length = max_length.unwrap_or(20).max(1);
+    // ============ Helper Methods ============
 
-        if allow_ai {
-            match self
-                .try_generate_session_title_with_ai(user_message, max_length)
-                .await
-            {
-                Ok(Some(title)) => {
-                    return ResolvedSessionTitle {
-                        title,
-                        method: SessionTitleMethod::Ai,
-                    };
-                }
-                Ok(None) => {
-                    warn!("AI session title generation returned empty output; using fallback");
-                }
-                Err(error) => {
-                    warn!("AI session title generation failed; using fallback: {error}");
+    /// Get a best-effort message view for the session.
+    /// When persistence is enabled, rebuild from persisted turns so callers see the
+    /// canonical turn history instead of the runtime context cache.
+    pub async fn get_messages(&self, session_id: &str) -> BitFunResult<Vec<Message>> {
+        if self.config.enable_persistence {
+            if let Some(workspace_path) = self.effective_session_storage_path(session_id).await {
+                let _history_read = self.acquire_session_mutation(session_id).await?;
+                let messages = self
+                    .rebuild_messages_from_turns(&workspace_path, session_id)
+                    .await?;
+                if !messages.is_empty() {
+                    return Ok(messages);
                 }
             }
         }
 
-        ResolvedSessionTitle {
-            title: Self::fallback_session_title(user_message, max_length),
-            method: SessionTitleMethod::Fallback,
-        }
+        Ok(self.context_store.get_context_messages(session_id))
     }
 
-    /// Generate session title
+    /// Load canonical persisted turns for a user-facing transcript.
     ///
-    /// Generate a concise and accurate session title based on user message content.
-    pub async fn generate_session_title(
+    /// This is intentionally separate from `get_messages`: runtime context
+    /// reconstruction excludes model-invisible maintenance turns, while a
+    /// transcript must be able to project those turns for the UI.
+    pub(crate) async fn load_persisted_transcript_turns_locked(
         &self,
-        user_message: &str,
-        max_length: Option<usize>,
-    ) -> BitFunResult<String> {
-        Ok(self
-            .resolve_session_title(user_message, max_length, true)
-            .await
-            .title)
+        session_id: &str,
+    ) -> BitFunResult<Option<Vec<DialogTurnData>>> {
+        if !self.config.enable_persistence {
+            return Ok(None);
+        }
+        let Some(workspace_path) = self.effective_session_storage_path(session_id).await else {
+            return Ok(None);
+        };
+        let mut turns = self
+            .persistence_manager
+            .load_session_turns(&workspace_path, session_id)
+            .await?;
+        if let Some(revert) = self
+            .persistence_manager
+            .load_session_revert_state(&workspace_path, session_id)
+            .await?
+        {
+            turns.retain(|turn| turn.turn_index < revert.boundary_turn);
+        }
+        Ok(Some(turns))
     }
 
-    // ============ Background Tasks ============
-
-    /// Start auto-save task
-    fn spawn_auto_save_task(&self) {
-        let sessions = self.sessions.clone();
-        let transient_session_ids = self.transient_session_ids.clone();
-        let persistence = self.persistence_manager.clone();
-        let session_mutation_locks = self.session_mutation_locks.clone();
-        let interval = self.config.auto_save_interval;
+    /// Get a paginated best-effort message view for the session.
+    pub async fn get_messages_paginated(
+        &self,
+        session_id: &str,
+        limit: usize,
+        before_message_id: Option<&str>,
+    ) -> BitFunResult<(Vec<Message>, bool)> {
+        let messages = self.get_messages(session_id).await?;
+        Ok(Self::paginate_messages(&messages, limit, before_message_id))
+    }
 
-        tokio::spawn(async move {
-            let mut ticker = Self::auto_save_interval(interval);
+    /// Get session's runtime context messages (may already include compressed reminders).
+    pub async fn get_context_messages(&self, session_id: &str) -> BitFunResult<Vec<Message>> {
+        let context_messages = self.context_store.get_context_messages(session_id);
 
-            loop {
-                ticker.tick().await;
+        Ok(context_messages)
+    }
 
-                for snapshot in Self::collect_auto_save_snapshots(&sessions, &transient_session_ids)
-                {
-                    let _mutation_guard = session_mutation_locks.lock(&snapshot.session_id).await;
-                    if !Self::auto_save_snapshot_is_current(&sessions, &snapshot) {
-                        continue;
-                    }
-                    if let Some(workspace_path) =
-                        Self::effective_storage_path_for_config_with_persistence(
-                            persistence.as_ref(),
-                            &snapshot.session.config,
-                        )
-                        .await
-                    {
-                        if !Self::auto_save_snapshot_is_current(&sessions, &snapshot) {
-                            continue;
-                        }
-                        if let Err(e) = persistence
-                            .save_session(&workspace_path, &snapshot.session)
-                            .await
-                        {
-                            error!(
-                                "Failed to auto-save session: session_id={}, error={}",
-                                snapshot.session_id, e
-                            );
-                        }
-                    }
-                }
+    /// Add a semantic message to the runtime context cache and immediately refresh the current
+    /// turn snapshot so crashes do not lose the latest in-memory context change.
+    pub async fn add_message(&self, session_id: &str, message: Message) -> BitFunResult<()> {
+        let memory_citation = message.metadata.memory_citation.clone();
+        let turn_id = message.metadata.turn_id.clone();
+        let round_id = message.metadata.round_id.clone();
+        let message_id = message.id.clone();
+        self.context_store.add_message(session_id, message);
+        if let Some(citation) = memory_citation.as_ref() {
+            if let Err(error) = self
+                .memory_database
+                .record_memory_citation(
+                    session_id,
+                    turn_id.as_deref(),
+                    round_id.as_deref(),
+                    &message_id,
+                    citation,
+                )
+                .await
+            {
+                warn!(
+                    "Failed to record memory citation: session_id={}, message_id={}, error={}",
+                    session_id, message_id, error
+                );
             }
-        });
+        }
+        self.persist_current_turn_context_snapshot_best_effort(session_id, "context_message_added")
+            .await;
+        Ok(())
+    }
 
-        debug!("Auto-save task started");
+    /// Replace the runtime context cache for a session and immediately refresh the current turn
+    /// snapshot. This is primarily used after compression rewrites the model-visible context.
+    pub async fn replace_context_messages(&self, session_id: &str, messages: Vec<Message>) {
+        self.context_store
+            .replace_context(session_id, messages.clone());
+        self.file_read_state_store.clear_session(session_id);
+        self.prune_token_anchors_to_messages(session_id, &messages)
+            .await;
+        self.persist_current_turn_context_snapshot_best_effort(session_id, "context_replaced")
+            .await;
     }
 
-    /// Start cleanup task for expired sessions
-    fn spawn_cleanup_task(&self) {
-        let sessions = self.sessions.clone();
-        let transient_session_ids = self.transient_session_ids.clone();
-        let active_session_permits = self.active_session_permits.clone();
-        let timeout = self.config.session_idle_timeout;
-        let persistence = self.persistence_manager.clone();
-        let enable_persistence = self.config.enable_persistence;
-        let session_mutation_locks = self.session_mutation_locks.clone();
-        let session_write_locks = self.session_write_locks.clone();
-        let context_store = self.context_store.clone();
-        let prompt_cache_store = self.prompt_cache_store.clone();
-        let token_anchor_store = self.token_anchor_store.clone();
-        let turn_skill_agent_snapshot_store = self.turn_skill_agent_snapshot_store.clone();
-        let skill_agent_baseline_override_snapshot_store =
-            self.skill_agent_baseline_override_snapshot_store.clone();
-        let edit_constraints_store = self.edit_constraints_store.clone();
-        let file_read_state_store = self.file_read_state_store.clone();
-        let evidence_ledger = self.evidence_ledger.clone();
+    pub fn set_file_read_state(&self, session_id: &str, logical_path: &str, state: FileReadState) {
+        self.file_read_state_store
+            .set(session_id, logical_path, state);
+    }
 
-        tokio::spawn(async move {
-            let mut ticker = time::interval(Duration::from_secs(60));
+    pub fn get_file_read_state(
+        &self,
+        session_id: &str,
+        logical_path: &str,
+    ) -> Option<FileReadState> {
+        self.file_read_state_store.get(session_id, logical_path)
+    }
 
-            loop {
-                ticker.tick().await;
+    pub fn record_review_read(
+        &self,
+        session_id: &str,
+        logical_path: &str,
+        revision: FileRevision,
+        start_line: usize,
+        end_line: usize,
+        total_lines: usize,
+    ) {
+        self.file_read_state_store.record_review_read(
+            session_id,
+            logical_path,
+            revision,
+            start_line,
+            end_line,
+            total_lines,
+        );
+    }
 
-                let now = SystemTime::now();
-                let candidates = Self::collect_expired_session_candidates(
-                    &sessions,
-                    &transient_session_ids,
-                    now,
-                    timeout,
-                );
+    pub fn review_read_coverage(
+        &self,
+        session_id: &str,
+        logical_path: &str,
+        revision: FileRevision,
+        start_line: usize,
+        limit: usize,
+    ) -> Option<ReviewReadCoverage> {
+        self.file_read_state_store.review_read_coverage(
+            session_id,
+            logical_path,
+            revision,
+            start_line,
+            limit,
+        )
+    }
 
-                for candidate in candidates {
-                    let _mutation_guard = session_mutation_locks.lock(&candidate.session_id).await;
-                    debug!(
-                        "Cleaning up expired session: session_id={}",
-                        candidate.session_id
-                    );
+    /// Get dialog turn count
+    pub fn get_turn_count(&self, session_id: &str) -> usize {
+        self.sessions
+            .get(session_id)
+            .map(|s| s.dialog_turn_ids.len())
+            .unwrap_or(0)
+    }
 
-                    let cleanup_now = SystemTime::now();
-                    let Some(session) = Self::cleanup_snapshot_for_candidate(
-                        &sessions,
-                        &candidate,
-                        cleanup_now,
-                        timeout,
-                    ) else {
-                        continue;
-                    };
+    /// Get session's compression state
+    pub fn get_compression_state(&self, session_id: &str) -> Option<CompressionState> {
+        self.sessions
+            .get(session_id)
+            .map(|s| s.compression_state.clone())
+    }
 
-                    let mut can_remove = true;
-                    if enable_persistence
-                        && Self::should_persist_session_with_transient_ids(
-                            &session,
-                            &transient_session_ids,
-                        )
-                    {
-                        if let Some(workspace_path) =
-                            Self::effective_storage_path_for_config_with_persistence(
-                                persistence.as_ref(),
-                                &session.config,
-                            )
-                            .await
-                        {
-                            if Self::cleanup_snapshot_for_candidate(
-                                &sessions,
-                                &candidate,
-                                SystemTime::now(),
-                                timeout,
-                            )
-                            .is_some()
-                            {
-                                if let Err(error) =
-                                    persistence.save_session(&workspace_path, &session).await
-                                {
-                                    error!(
-                                        "Failed to save Session before idle eviction: session_id={}, error={}",
-                                        candidate.session_id, error
-                                    );
-                                    can_remove = false;
-                                }
-                            }
-                        } else {
-                            can_remove = false;
-                        }
-                    }
+    /// Update session's compression state
+    pub async fn update_compression_state(
+        &self,
+        session_id: &str,
+        compression_state: CompressionState,
+    ) -> BitFunResult<()> {
+        let _mutation_guard = self.acquire_session_mutation(session_id).await?;
+        let effective_path = self.effective_session_storage_path(session_id).await;
 
-                    if !can_remove {
-                        continue;
-                    }
+        // IMPORTANT: keep the DashMap guard scope short -- do NOT hold it across .await.
+        let session_snapshot = if let Some(mut session) = self.sessions.get_mut(session_id) {
+            session.compression_state = compression_state;
+            session.updated_at = SystemTime::now();
+            session.last_activity_at = SystemTime::now();
+            if self.config.enable_persistence && self.should_persist_session(&session) {
+                Some(session.clone())
+            } else {
+                None
+            }
+        } else {
+            return Err(BitFunError::NotFound(format!(
+                "Session not found: {}",
+                session_id
+            )));
+        };
+        // RefMut guard released here -- DashMap shard lock is free.
 
-                    let removal_now = SystemTime::now();
-                    if sessions
-                        .remove_if(&candidate.session_id, |_, session| {
-                            Self::cleanup_candidate_matches_session(
-                                session,
-                                &candidate,
-                                removal_now,
-                                timeout,
-                            )
-                        })
-                        .is_some()
-                    {
-                        active_session_permits.remove(&candidate.session_id);
-                        session_write_locks.remove(&candidate.session_id);
-                        clear_session_runtime_stores(
-                            &candidate.session_id,
-                            context_store.as_ref(),
-                            prompt_cache_store.as_ref(),
-                            token_anchor_store.as_ref(),
-                            turn_skill_agent_snapshot_store.as_ref(),
-                            skill_agent_baseline_override_snapshot_store.as_ref(),
-                            file_read_state_store.as_ref(),
-                            evidence_ledger.as_ref(),
-                        );
-                        edit_constraints_store.remove(&candidate.session_id);
-                    }
-                }
+        if let Some(session) = session_snapshot {
+            if let Some(ref workspace_path) = effective_path {
+                self.persistence_manager
+                    .save_session(workspace_path, &session)
+                    .await?;
             }
-        });
+        }
 
-        debug!("Cleanup task started");
+        Ok(())
     }
-}
 
-#[cfg(test)]
-mod tests {
-    use super::{
-        should_auto_migrate_session_model, CoreSessionStorePort, PermissionMode,
-        SessionExecutionBindingError, SessionExecutionBindingUpdate, SessionManager,
-        SessionManagerConfig, TEST_MODEL_RESOLUTION_AI_CONFIG,
-    };
-    use crate::agentic::core::{
-        CompressionState, Message, MessageContent, MessageRole, ProcessingPhase, Session,
-        SessionAgentRouteOwner, SessionConfig, SessionModelBindingPolicy, SessionState, ToolCall,
-        ToolResult,
-    };
-    use crate::agentic::persistence::PersistenceManager;
-    use crate::agentic::session::{
-        revert::{SessionRevertPhase, SessionRevertState, SESSION_REVERT_SCHEMA_VERSION},
-        PromptCachePolicy, PromptCacheScope, SessionContextStore, SystemPromptCacheIdentity,
-        UserContextCacheIdentity,
-    };
-    use crate::agentic::skill_agent_snapshot::{SkillSnapshotEntry, TurnSkillAgentSnapshot};
-    use crate::infrastructure::PathManager;
-    use crate::service::config::types::{
-        AIConfig as ServiceAIConfig, AIModelConfig as ServiceAIModelConfig,
-    };
-    use crate::service::session::{
-        DialogTurnData, DialogTurnKind, ModelRoundData, SessionContextUsage,
-        SessionContextUsageSource, SessionKind, SessionMetadata, SessionRelationship,
-        SessionRelationshipKind, ToolCallData, ToolItemData, ToolResultData, TurnStatus,
-        UserMessageData,
-    };
-    use crate::util::errors::BitFunError;
-    use bitfun_core_types::{
-        ReasoningCatalogBinding, ReasoningConfig, ReasoningPreset, ReasoningPresetAction,
-        SessionExecutionTarget,
-    };
-    use bitfun_runtime_ports::SessionStoragePathRequest;
-    use dashmap::{try_result::TryResult, DashMap};
-    use serde_json::json;
-    use std::collections::HashSet;
-    use std::path::{Path, PathBuf};
-    use std::sync::Arc;
-    use std::time::{Duration, SystemTime};
-    use uuid::Uuid;
+    async fn try_generate_session_title_with_ai(
+        &self,
+        session_id: &str,
+        user_message: &str,
+        max_length: usize,
+    ) -> BitFunResult<Option<String>> {
+        use crate::util::types::Message;
+
+        // Match agent `LANGUAGE_PREFERENCE`: use `app.language`, not I18nService (see `app_language` module).
+        let lang_code = get_app_language_code().await;
+        let language_instruction = short_model_user_language_instruction(lang_code.as_str());
+
+        // Construct system prompt
+        let system_prompt = format!(
+            "You are a professional session title generation assistant. Based on the user's message content, generate a concise and accurate session title.\n\nRequirements:\n- Title should not exceed {} characters\n- {}\n- Concise and accurate, reflecting the conversation topic\n- Do not add quotes or other decorative symbols\n- Return only the title text, no other content",
+            max_length, language_instruction
+        );
+
+        // Truncate message to save tokens (max 200 characters)
+        let truncated_message = if user_message.chars().count() > 200 {
+            format!("{}...", user_message.chars().take(200).collect::<String>())
+        } else {
+            user_message.to_string()
+        };
+
+        let user_prompt = format!(
+            "User message: {}\n\nPlease generate session title:",
+            truncated_message
+        );
+
+        // Construct messages (using AIClient's Message type)
+        let messages = vec![
+            Message {
+                role: "system".to_string(),
+                content: Some(system_prompt),
+                reasoning_content: None,
+                thinking_signature: None,
+                tool_calls: None,
+                tool_call_id: None,
+                name: None,
+                is_error: None,
+                tool_image_attachments: None,
+            },
+            Message {
+                role: "user".to_string(),
+                content: Some(user_prompt),
+                reasoning_content: None,
+                thinking_signature: None,
+                tool_calls: None,
+                tool_call_id: None,
+                name: None,
+                is_error: None,
+                tool_image_attachments: None,
+            },
+        ];
+
+        // Resolve the task model. Inherit uses the session's resolved model
+        // identity but deliberately does not carry its reasoning preset.
+        let ai_client_factory = get_global_ai_client_factory().await.map_err(|e| {
+            BitFunError::AIClient(format!("Failed to get AI client factory: {}", e))
+        })?;
+        let ai_config = Self::load_ai_config_for_model_resolution()
+            .await
+            .ok_or_else(|| BitFunError::AIClient("Failed to load AI configuration".to_string()))?;
+        let ai_client = match &ai_config.task_models.session_title {
+            crate::service::config::types::TaskModelSelection::Fixed { model_id } => {
+                ai_client_factory.get_client_resolved(model_id).await
+            }
+            crate::service::config::types::TaskModelSelection::Inherit => {
+                let session = self.get_session(session_id).ok_or_else(|| {
+                    BitFunError::NotFound(format!("Session not found: {session_id}"))
+                })?;
+                let explicit_model_id = session
+                    .config
+                    .model_id
+                    .as_deref()
+                    .map(str::trim)
+                    .filter(|model_id| !model_id.is_empty());
+                let fallback_model_id = if explicit_model_id.is_none() {
+                    let workspace = session.config.workspace_path.as_deref().map(Path::new);
+                    Some(
+                        get_agent_registry()
+                            .get_model_id_for_agent(&session.agent_type, workspace)
+                            .await
+                            .map_err(|error| {
+                                BitFunError::AIClient(format!(
+                                    "Failed to resolve session Agent model: {error}"
+                                ))
+                            })?,
+                    )
+                } else {
+                    None
+                };
+                let configured_model_id = explicit_model_id
+                    .or(fallback_model_id.as_deref())
+                    .unwrap_or("auto");
+                let selector = if Self::is_auto_model_selector(configured_model_id) {
+                    "primary"
+                } else {
+                    configured_model_id
+                };
+                let resolved_model_id =
+                    ai_config.resolve_model_selection(selector).ok_or_else(|| {
+                        BitFunError::AIClient(format!(
+                            "Failed to resolve inherited session model: {selector}"
+                        ))
+                    })?;
+                if matches!(
+                    session.config.model_binding_policy,
+                    SessionModelBindingPolicy::ApprovedImmutable
+                ) {
+                    let fingerprint = session
+                        .config
+                        .model_binding_fingerprint
+                        .as_deref()
+                        .ok_or_else(|| {
+                            BitFunError::AIClient(
+                                "Inherited immutable session model has no approved fingerprint"
+                                    .to_string(),
+                            )
+                        })?;
+                    ai_client_factory
+                        .get_client_by_approved_binding(&resolved_model_id, fingerprint)
+                        .await
+                } else {
+                    ai_client_factory.get_client_by_id(&resolved_model_id).await
+                }
+            }
+        }
+        .map_err(|e| BitFunError::AIClient(format!("Failed to get AI client: {}", e)))?;
+
+        let response = ai_client
+            .send_message(messages, None)
+            .await
+            .map_err(|e| BitFunError::ai(format!("AI call failed: {}", e)))?;
+
+        let title = sanitize_plain_model_output(&response.text);
+        if title.is_empty() {
+            return Ok(None);
+        }
+
+        // Truncate title
+        let final_title = if title.chars().count() > max_length {
+            title.chars().take(max_length).collect::<String>()
+        } else {
+            title
+        };
+
+        Ok(Some(final_title))
+    }
+
+    /// Generate a concise session title, using AI first and falling back to a local heuristic.
+    pub async fn resolve_session_title(
+        &self,
+        session_id: &str,
+        user_message: &str,
+        max_length: Option<usize>,
+        allow_ai: bool,
+    ) -> ResolvedSessionTitle {
+        let max_length = max_length.unwrap_or(20).max(1);
+
+        if allow_ai {
+            match self
+                .try_generate_session_title_with_ai(session_id, user_message, max_length)
+                .await
+            {
+                Ok(Some(title)) => {
+                    return ResolvedSessionTitle {
+                        title,
+                        method: SessionTitleMethod::Ai,
+                    };
+                }
+                Ok(None) => {
+                    warn!("AI session title generation returned empty output; using fallback");
+                }
+                Err(error) => {
+                    warn!("AI session title generation failed; using fallback: {error}");
+                }
+            }
+        }
+
+        ResolvedSessionTitle {
+            title: Self::fallback_session_title(user_message, max_length),
+            method: SessionTitleMethod::Fallback,
+        }
+    }
+
+    /// Generate session title
+    ///
+    /// Generate a concise and accurate session title based on user message content.
+    pub async fn generate_session_title(
+        &self,
+        session_id: &str,
+        user_message: &str,
+        max_length: Option<usize>,
+    ) -> BitFunResult<String> {
+        Ok(self
+            .resolve_session_title(session_id, user_message, max_length, true)
+            .await
+            .title)
+    }
+
+    // ============ Background Tasks ============
+
+    /// Start auto-save task
+    fn spawn_auto_save_task(&self) {
+        let sessions = self.sessions.clone();
+        let transient_session_ids = self.transient_session_ids.clone();
+        let persistence = self.persistence_manager.clone();
+        let session_mutation_locks = self.session_mutation_locks.clone();
+        let interval = self.config.auto_save_interval;
+
+        tokio::spawn(async move {
+            let mut ticker = Self::auto_save_interval(interval);
+
+            loop {
+                ticker.tick().await;
+
+                for snapshot in Self::collect_auto_save_snapshots(&sessions, &transient_session_ids)
+                {
+                    let _mutation_guard = session_mutation_locks.lock(&snapshot.session_id).await;
+                    if !Self::auto_save_snapshot_is_current(&sessions, &snapshot) {
+                        continue;
+                    }
+                    if let Some(workspace_path) =
+                        Self::effective_storage_path_for_config_with_persistence(
+                            persistence.as_ref(),
+                            &snapshot.session.config,
+                        )
+                        .await
+                    {
+                        if !Self::auto_save_snapshot_is_current(&sessions, &snapshot) {
+                            continue;
+                        }
+                        if let Err(e) = persistence
+                            .save_session(&workspace_path, &snapshot.session)
+                            .await
+                        {
+                            error!(
+                                "Failed to auto-save session: session_id={}, error={}",
+                                snapshot.session_id, e
+                            );
+                        }
+                    }
+                }
+            }
+        });
+
+        debug!("Auto-save task started");
+    }
+
+    /// Start cleanup task for expired sessions
+    fn spawn_cleanup_task(&self) {
+        let sessions = self.sessions.clone();
+        let active_turn_permission_modes = self.active_turn_permission_modes.clone();
+        let transient_session_ids = self.transient_session_ids.clone();
+        let active_session_permits = self.active_session_permits.clone();
+        let timeout = self.config.session_idle_timeout;
+        let persistence = self.persistence_manager.clone();
+        let enable_persistence = self.config.enable_persistence;
+        let session_mutation_locks = self.session_mutation_locks.clone();
+        let session_write_locks = self.session_write_locks.clone();
+        let context_store = self.context_store.clone();
+        let prompt_cache_store = self.prompt_cache_store.clone();
+        let token_anchor_store = self.token_anchor_store.clone();
+        let turn_skill_agent_snapshot_store = self.turn_skill_agent_snapshot_store.clone();
+        let skill_agent_baseline_override_snapshot_store =
+            self.skill_agent_baseline_override_snapshot_store.clone();
+        let edit_constraints_store = self.edit_constraints_store.clone();
+        let file_read_state_store = self.file_read_state_store.clone();
+        let evidence_ledger = self.evidence_ledger.clone();
+
+        tokio::spawn(async move {
+            let mut ticker = time::interval(Duration::from_secs(60));
+
+            loop {
+                ticker.tick().await;
+
+                let now = SystemTime::now();
+                let candidates = Self::collect_expired_session_candidates(
+                    &sessions,
+                    &transient_session_ids,
+                    now,
+                    timeout,
+                );
+
+                for candidate in candidates {
+                    let _mutation_guard = session_mutation_locks.lock(&candidate.session_id).await;
+                    debug!(
+                        "Cleaning up expired session: session_id={}",
+                        candidate.session_id
+                    );
+
+                    let cleanup_now = SystemTime::now();
+                    let Some(session) = Self::cleanup_snapshot_for_candidate(
+                        &sessions,
+                        &candidate,
+                        cleanup_now,
+                        timeout,
+                    ) else {
+                        continue;
+                    };
+
+                    let mut can_remove = true;
+                    if enable_persistence
+                        && Self::should_persist_session_with_transient_ids(
+                            &session,
+                            &transient_session_ids,
+                        )
+                    {
+                        if let Some(workspace_path) =
+                            Self::effective_storage_path_for_config_with_persistence(
+                                persistence.as_ref(),
+                                &session.config,
+                            )
+                            .await
+                        {
+                            if Self::cleanup_snapshot_for_candidate(
+                                &sessions,
+                                &candidate,
+                                SystemTime::now(),
+                                timeout,
+                            )
+                            .is_some()
+                            {
+                                if let Err(error) =
+                                    persistence.save_session(&workspace_path, &session).await
+                                {
+                                    error!(
+                                        "Failed to save Session before idle eviction: session_id={}, error={}",
+                                        candidate.session_id, error
+                                    );
+                                    can_remove = false;
+                                }
+                            }
+                        } else {
+                            can_remove = false;
+                        }
+                    }
+
+                    if !can_remove {
+                        continue;
+                    }
+
+                    let removal_now = SystemTime::now();
+                    if sessions
+                        .remove_if(&candidate.session_id, |_, session| {
+                            Self::cleanup_candidate_matches_session(
+                                session,
+                                &candidate,
+                                removal_now,
+                                timeout,
+                            )
+                        })
+                        .is_some()
+                    {
+                        active_session_permits.remove(&candidate.session_id);
+                        session_write_locks.remove(&candidate.session_id);
+                        active_turn_permission_modes.remove(&candidate.session_id);
+                        clear_session_runtime_stores(
+                            &candidate.session_id,
+                            context_store.as_ref(),
+                            prompt_cache_store.as_ref(),
+                            token_anchor_store.as_ref(),
+                            turn_skill_agent_snapshot_store.as_ref(),
+                            skill_agent_baseline_override_snapshot_store.as_ref(),
+                            file_read_state_store.as_ref(),
+                            evidence_ledger.as_ref(),
+                        );
+                        edit_constraints_store.remove(&candidate.session_id);
+                    }
+                }
+            }
+        });
+
+        debug!("Cleanup task started");
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{
+        should_auto_migrate_session_model, CoreSessionStorePort, PermissionMode,
+        SessionExecutionBindingError, SessionExecutionBindingUpdate, SessionManager,
+        SessionManagerConfig, TurnAdmissionSessionFacts, TEST_MODEL_RESOLUTION_AI_CONFIG,
+    };
+    use crate::agentic::core::{
+        CompressionState, Message, MessageContent, MessageRole, MessageSemanticKind,
+        ProcessingPhase, Session, SessionAgentRouteOwner, SessionConfig, SessionModelBindingPolicy,
+        SessionState, ToolCall, ToolResult, TurnStats,
+    };
+    use crate::agentic::persistence::PersistenceManager;
+    use crate::agentic::session::{
+        revert::{SessionRevertPhase, SessionRevertState, SESSION_REVERT_SCHEMA_VERSION},
+        PromptCachePolicy, PromptCacheScope, SessionContextStore, SystemPromptCacheIdentity,
+        UserContextCacheIdentity,
+    };
+    use crate::agentic::skill_agent_snapshot::{SkillSnapshotEntry, TurnSkillAgentSnapshot};
+    use crate::infrastructure::ai::reasoning_catalog::{
+        project_model_reasoning_catalog as project_test_model_reasoning_catalog,
+        reasoning_preset_runtime_fingerprint as test_reasoning_preset_runtime_fingerprint,
+        resolve_default_reasoning_preset as resolve_test_default_reasoning_preset,
+        resolve_reasoning_preset as resolve_test_reasoning_preset,
+    };
+    use crate::infrastructure::PathManager;
+    use crate::service::config::types::{
+        model_runtime_binding_fingerprint as service_model_runtime_binding_fingerprint,
+        AIConfig as ServiceAIConfig, AIModelConfig as ServiceAIModelConfig,
+    };
+    use crate::service::session::{
+        DialogTurnData, DialogTurnKind, DialogTurnRecoveryStatus, ModelRoundData,
+        SessionContextUsage, SessionContextUsageSource, SessionKind, SessionMetadata,
+        SessionRelationship, SessionRelationshipKind, ToolCallData, ToolItemData, ToolResultData,
+        TurnStatus, UserMessageData,
+    };
+    use crate::util::errors::BitFunError;
+    use bitfun_core_types::{
+        ReasoningCatalogBinding, ReasoningConfig, ReasoningPreset, ReasoningPresetAction,
+        SessionExecutionTarget,
+    };
+    use bitfun_runtime_ports::SessionStoragePathRequest;
+    use dashmap::{try_result::TryResult, DashMap};
+    use serde_json::json;
+    use std::collections::HashSet;
+    use std::path::{Path, PathBuf};
+    use std::sync::Arc;
+    use std::time::{Duration, SystemTime};
+    use uuid::Uuid;
+
+    struct TestWorkspace {
+        path: PathBuf,
+    }
+
+    impl TestWorkspace {
+        fn new() -> Self {
+            let path = std::env::temp_dir()
+                .join(format!("bitfun-session-restore-test-{}", Uuid::new_v4()));
+            std::fs::create_dir_all(&path).expect("test workspace should be created");
+            Self { path }
+        }
+
+        fn path(&self) -> &Path {
+            &self.path
+        }
+
+        fn path_manager(&self) -> Arc<PathManager> {
+            Arc::new(PathManager::with_user_root_for_tests(
+                self.path.join("user-root"),
+            ))
+        }
+    }
+
+    #[test]
+    fn invalidated_model_migration_preserves_approved_external_generation_binding() {
+        let invalidated = HashSet::from(["removed-model"]);
+
+        assert!(should_auto_migrate_session_model(
+            SessionModelBindingPolicy::Mutable,
+            "removed-model",
+            &invalidated,
+        ));
+        assert!(!should_auto_migrate_session_model(
+            SessionModelBindingPolicy::ApprovedImmutable,
+            "removed-model",
+            &invalidated,
+        ));
+        assert!(!should_auto_migrate_session_model(
+            SessionModelBindingPolicy::Mutable,
+            "active-model",
+            &invalidated,
+        ));
+    }
+
+    #[test]
+    fn idle_eviction_only_selects_sessions_that_can_be_restored() {
+        let now = SystemTime::now();
+        let expired_at = now - Duration::from_secs(120);
+        let mut durable = Session::new(
+            "Durable".to_string(),
+            "agentic".to_string(),
+            SessionConfig::default(),
+        );
+        durable.last_activity_at = expired_at;
+        let mut transient = Session::new(
+            "Connection scoped".to_string(),
+            "agentic".to_string(),
+            SessionConfig::default(),
+        );
+        transient.last_activity_at = expired_at;
+        let durable_id = durable.session_id.clone();
+        let transient_id = transient.session_id.clone();
+        let sessions = DashMap::new();
+        sessions.insert(durable_id.clone(), durable);
+        sessions.insert(transient_id.clone(), transient);
+        let transient_session_ids = DashMap::new();
+        transient_session_ids.insert(transient_id.clone(), ());
+
+        let candidates = SessionManager::collect_expired_session_candidates(
+            &sessions,
+            &transient_session_ids,
+            now,
+            Duration::from_secs(60),
+        );
+
+        assert_eq!(
+            candidates
+                .iter()
+                .map(|candidate| candidate.session_id.as_str())
+                .collect::<Vec<_>>(),
+            [durable_id.as_str()]
+        );
+        assert!(sessions.contains_key(&transient_id));
+    }
+
+    #[test]
+    fn persisted_round_preserves_deferred_wire_call_and_effective_identity() {
+        let assistant = Message::assistant_with_tools(
+            String::new(),
+            vec![ToolCall {
+                tool_id: "tool-1".to_string(),
+                tool_name: bitfun_agent_tools::CALL_DEFERRED_TOOL_NAME.to_string(),
+                arguments: json!({
+                    "tool_name": "WebFetch",
+                    "args": { "url": "https://example.test" }
+                }),
+                raw_arguments: None,
+                is_error: false,
+                parse_error: None,
+                recovered_from_truncation: false,
+                repair_kind: Default::default(),
+            }],
+        )
+        .with_turn_id("turn-1".to_string())
+        .with_round_id("round-1".to_string());
+        let result = Message::tool_result(ToolResult {
+            tool_id: "tool-1".to_string(),
+            tool_name: bitfun_agent_tools::CALL_DEFERRED_TOOL_NAME.to_string(),
+            effective_tool_name: Some("WebFetch".to_string()),
+            result: json!({ "content": "external content" }),
+            result_for_assistant: Some("external content".to_string()),
+            is_error: false,
+            duration_ms: Some(1),
+            image_attachments: None,
+        })
+        .with_turn_id("turn-1".to_string())
+        .with_round_id("round-1".to_string());
+
+        let persisted_messages: Vec<Message> = serde_json::from_value(
+            serde_json::to_value(vec![assistant, result]).expect("serialize messages"),
+        )
+        .expect("deserialize messages");
+        let provider_result: crate::util::types::Message = (&persisted_messages[1]).into();
+        assert_eq!(
+            provider_result.name.as_deref(),
+            Some(bitfun_agent_tools::CALL_DEFERRED_TOOL_NAME)
+        );
+
+        let rounds =
+            SessionManager::build_model_rounds_from_messages(&persisted_messages, "turn-1", 1);
+
+        assert_eq!(rounds.len(), 1);
+        assert_eq!(rounds[0].tool_items.len(), 1);
+        let tool = &rounds[0].tool_items[0];
+        assert_eq!(tool.tool_name, bitfun_agent_tools::CALL_DEFERRED_TOOL_NAME);
+        assert_eq!(
+            tool.tool_call.input,
+            json!({
+                "tool_name": "WebFetch",
+                "args": { "url": "https://example.test" }
+            })
+        );
+        let (effective_name, effective_input) =
+            crate::service::session::effective_tool_identity(tool);
+        assert_eq!(effective_name, "WebFetch");
+        assert_eq!(effective_input, &json!({ "url": "https://example.test" }));
+    }
+
+    impl Drop for TestWorkspace {
+        fn drop(&mut self) {
+            let _ = std::fs::remove_dir_all(&self.path);
+        }
+    }
+
+    fn test_manager(persistence_manager: Arc<PersistenceManager>) -> SessionManager {
+        SessionManager::new(
+            Arc::new(SessionContextStore::new()),
+            persistence_manager,
+            SessionManagerConfig {
+                max_active_sessions: 100,
+                session_idle_timeout: Duration::from_secs(3600),
+                auto_save_interval: Duration::from_secs(300),
+                enable_persistence: true,
+                prompt_cache_policy: PromptCachePolicy::default(),
+            },
+        )
+    }
+
+    async fn reopen_interrupted_turn_for_test(
+        manager: &SessionManager,
+        session_id: &str,
+        turn_id: &str,
+        expected_generation: u32,
+    ) -> crate::util::errors::BitFunResult<super::InterruptedTurnRecoveryPlan> {
+        TEST_MODEL_RESOLUTION_AI_CONFIG
+            .scope(
+                ServiceAIConfig {
+                    models: vec![configured_reasoning_model("model-original")],
+                    ..Default::default()
+                },
+                manager.reopen_interrupted_dialog_turn(session_id, turn_id, expected_generation),
+            )
+            .await
+    }
+
+    fn interrupted_turn_test_model_fingerprint() -> String {
+        service_model_runtime_binding_fingerprint(&configured_reasoning_model("model-original"))
+    }
+
+    fn interrupted_turn_test_reasoning_fingerprint(selected_preset: Option<&str>) -> String {
+        let model = configured_reasoning_model("model-original");
+        let projection = project_test_model_reasoning_catalog(&model, None);
+        let preset = selected_preset
+            .and_then(|preset_id| resolve_test_reasoning_preset(&projection, preset_id))
+            .or_else(|| {
+                selected_preset
+                    .is_none()
+                    .then(|| resolve_test_default_reasoning_preset(&projection))
+                    .flatten()
+            });
+        test_reasoning_preset_runtime_fingerprint(preset)
+    }
+
+    fn interrupted_turn_test_auto_reasoning_fingerprint(default_preset: &str) -> String {
+        let model = reasoning_model_with_default("model-original", default_preset);
+        let projection = project_test_model_reasoning_catalog(&model, None);
+        test_reasoning_preset_runtime_fingerprint(resolve_test_default_reasoning_preset(
+            &projection,
+        ))
+    }
+
+    fn test_manager_with_config(
+        persistence_manager: Arc<PersistenceManager>,
+        config: SessionManagerConfig,
+    ) -> SessionManager {
+        SessionManager::new(
+            Arc::new(SessionContextStore::new()),
+            persistence_manager,
+            config,
+        )
+    }
+
+    fn test_path_manager() -> Arc<PathManager> {
+        let root =
+            std::env::temp_dir().join(format!("bitfun-session-manager-test-{}", Uuid::new_v4()));
+        Arc::new(PathManager::with_user_root_for_tests(
+            root.join("user-root"),
+        ))
+    }
+
+    fn in_memory_test_manager() -> SessionManager {
+        let persistence_manager =
+            Arc::new(PersistenceManager::new(test_path_manager()).expect("persistence manager"));
+        SessionManager::new(
+            Arc::new(SessionContextStore::new()),
+            persistence_manager,
+            SessionManagerConfig {
+                max_active_sessions: 100,
+                session_idle_timeout: Duration::from_secs(3600),
+                auto_save_interval: Duration::from_secs(300),
+                enable_persistence: false,
+                prompt_cache_policy: PromptCachePolicy::default(),
+            },
+        )
+    }
+
+    #[tokio::test]
+    async fn current_context_usage_is_persisted_by_the_session_owner() {
+        let workspace = TestWorkspace::new();
+        let persistence_manager = Arc::new(
+            PersistenceManager::new(workspace.path_manager()).expect("persistence manager"),
+        );
+        let manager = test_manager(persistence_manager.clone());
+        let session = manager
+            .create_session(
+                "Usage persistence".to_string(),
+                "agentic".to_string(),
+                SessionConfig {
+                    workspace_path: Some(workspace.path().to_string_lossy().to_string()),
+                    ..SessionConfig::default()
+                },
+            )
+            .await
+            .expect("session should create");
+        let usage = SessionContextUsage {
+            turn_id: "turn-1".to_string(),
+            input_tokens: 42_000,
+            output_tokens: Some(1_500),
+            total_tokens: 43_500,
+            timestamp: 123,
+            source: SessionContextUsageSource::ModelRequest,
+        };
+        manager
+            .sessions
+            .get_mut(&session.session_id)
+            .expect("session should be active")
+            .dialog_turn_ids
+            .push(usage.turn_id.clone());
+
+        manager
+            .persist_current_context_usage(&session.session_id, usage.clone())
+            .await
+            .expect("usage should persist");
+
+        let metadata = persistence_manager
+            .load_session_metadata(workspace.path(), &session.session_id)
+            .await
+            .expect("metadata should load")
+            .expect("metadata should exist");
+        assert_eq!(metadata.current_context_usage, Some(usage));
+    }
+
+    #[tokio::test]
+    async fn interrupted_turn_reopens_same_turn_from_snapshot_with_generation_cas() {
+        let workspace = TestWorkspace::new();
+        let persistence_manager = Arc::new(
+            PersistenceManager::new(workspace.path_manager()).expect("persistence manager"),
+        );
+        let manager = test_manager(persistence_manager.clone());
+        let session = manager
+            .create_session(
+                "Recovery".to_string(),
+                "agentic".to_string(),
+                SessionConfig {
+                    workspace_path: Some(workspace.path().to_string_lossy().to_string()),
+                    ..SessionConfig::default()
+                },
+            )
+            .await
+            .expect("session should create");
+        let turn_id = manager
+            .start_dialog_turn(
+                &session.session_id,
+                "agentic".to_string(),
+                "finish the task".to_string(),
+                Some("turn-1".to_string()),
+                None,
+                Some(serde_json::json!({
+                    "resolved_permission_mode": "ask",
+                    "runtime_resolved_model_id": "model-original",
+                    "runtime_model_binding_fingerprint": interrupted_turn_test_model_fingerprint(),
+                    "runtime_reasoning_preset": null,
+                    "runtime_reasoning_selection": null,
+                    "runtime_reasoning_fingerprint": interrupted_turn_test_reasoning_fingerprint(None)
+                })),
+            )
+            .await
+            .expect("turn should start");
+        manager
+            .add_message(
+                &session.session_id,
+                Message::assistant("safe completed fragment".to_string())
+                    .with_turn_id(turn_id.clone())
+                    .with_round_id("round-0".to_string()),
+            )
+            .await
+            .expect("safe boundary should persist");
+
+        let interrupted = manager
+            .mark_dialog_turn_interrupted(&session.session_id, &turn_id)
+            .await
+            .expect("turn should become interrupted");
+        assert_eq!(interrupted.execution_generation, 0);
+        manager
+            .update_session_state_for_turn_if_processing(
+                &session.session_id,
+                &turn_id,
+                SessionState::Idle,
+            )
+            .await
+            .expect("session should settle idle");
+        manager
+            .update_session_permission_mode(&session.session_id, Some(PermissionMode::FullAccess))
+            .await
+            .expect("session permission should change after interruption");
+
+        let plan = reopen_interrupted_turn_for_test(&manager, &session.session_id, &turn_id, 0)
+            .await
+            .expect("same generation should recover");
+
+        assert_eq!(plan.turn_id, turn_id);
+        assert_eq!(plan.turn_index, 0);
+        assert_eq!(plan.execution_generation, 1);
+        assert_eq!(plan.resume_count, 1);
+        assert_eq!(plan.initial_round_index, 0);
+        assert_eq!(plan.resolved_permission_mode, PermissionMode::Ask);
+        assert_eq!(plan.resolved_model_id, "model-original");
+        assert_eq!(
+            plan.messages
+                .iter()
+                .filter(|message| {
+                    message.metadata.semantic_kind == Some(MessageSemanticKind::ActualUserInput)
+                })
+                .count(),
+            1,
+            "recovery must not duplicate the original user message"
+        );
+        assert!(plan.messages.iter().any(|message| {
+            message
+                .content
+                .to_string()
+                .contains("previous work was interrupted")
+        }));
+
+        let duplicate =
+            reopen_interrupted_turn_for_test(&manager, &session.session_id, &plan.turn_id, 0)
+                .await
+                .expect_err("stale generation must be rejected");
+        assert!(duplicate.to_string().contains("generation"), "{duplicate}");
+
+        manager
+            .cancel_dialog_turn(&session.session_id, &plan.turn_id)
+            .await
+            .expect("ordinary cancellation should settle recovered work");
+        let persisted = persistence_manager
+            .load_dialog_turn(workspace.path(), &session.session_id, 0)
+            .await
+            .expect("turn should load")
+            .expect("turn should exist");
+        assert!(
+            persisted.recovery.is_none(),
+            "ordinary cancellation must remove the recoverable state"
+        );
+    }
+
+    #[tokio::test]
+    async fn interrupted_turn_recovery_does_not_narrow_its_frozen_permission_mode() {
+        let workspace = TestWorkspace::new();
+        let persistence_manager = Arc::new(
+            PersistenceManager::new(workspace.path_manager()).expect("persistence manager"),
+        );
+        let manager = test_manager(persistence_manager);
+        let session = manager
+            .create_session(
+                "Recovery permission".to_string(),
+                "agentic".to_string(),
+                SessionConfig {
+                    workspace_path: Some(workspace.path().to_string_lossy().to_string()),
+                    permission_mode: Some(PermissionMode::FullAccess),
+                    ..SessionConfig::default()
+                },
+            )
+            .await
+            .expect("session should create");
+        let turn_id = manager
+            .start_dialog_turn(
+                &session.session_id,
+                "agentic".to_string(),
+                "finish with the original permission".to_string(),
+                Some("turn-permission".to_string()),
+                None,
+                Some(serde_json::json!({
+                    "resolved_permission_mode": "full_access",
+                    "runtime_resolved_model_id": "model-original",
+                    "runtime_model_binding_fingerprint": interrupted_turn_test_model_fingerprint(),
+                    "runtime_reasoning_preset": null,
+                    "runtime_reasoning_selection": null,
+                    "runtime_reasoning_fingerprint": interrupted_turn_test_reasoning_fingerprint(None)
+                })),
+            )
+            .await
+            .expect("turn should start");
+        manager
+            .mark_dialog_turn_interrupted(&session.session_id, &turn_id)
+            .await
+            .expect("turn should become interrupted");
+        manager
+            .update_session_state_for_turn_if_processing(
+                &session.session_id,
+                &turn_id,
+                SessionState::Idle,
+            )
+            .await
+            .expect("session should settle idle");
+        manager
+            .update_session_permission_mode(&session.session_id, Some(PermissionMode::Ask))
+            .await
+            .expect("session permission should change after interruption");
+
+        let plan = reopen_interrupted_turn_for_test(&manager, &session.session_id, &turn_id, 0)
+            .await
+            .expect("turn should keep its original permission contract");
+        assert_eq!(plan.resolved_permission_mode, PermissionMode::FullAccess);
+    }
+
+    #[tokio::test]
+    async fn interrupted_turn_recovery_rejects_a_changed_reasoning_preset() {
+        let workspace = TestWorkspace::new();
+        let persistence_manager = Arc::new(
+            PersistenceManager::new(workspace.path_manager()).expect("persistence manager"),
+        );
+        let manager = test_manager(persistence_manager);
+        let session = manager
+            .create_session(
+                "Recovery reasoning preset".to_string(),
+                "agentic".to_string(),
+                SessionConfig {
+                    workspace_path: Some(workspace.path().to_string_lossy().to_string()),
+                    reasoning_preset: Some("high".to_string()),
+                    ..SessionConfig::default()
+                },
+            )
+            .await
+            .expect("session should create");
+        let turn_id = manager
+            .start_dialog_turn(
+                &session.session_id,
+                "agentic".to_string(),
+                "continue with one reasoning contract".to_string(),
+                Some("turn-reasoning".to_string()),
+                None,
+                Some(serde_json::json!({
+                    "resolved_permission_mode": "ask",
+                    "runtime_resolved_model_id": "model-original",
+                    "runtime_model_binding_fingerprint": interrupted_turn_test_model_fingerprint(),
+                    "runtime_reasoning_preset": "high",
+                    "runtime_reasoning_selection": "high",
+                    "runtime_reasoning_fingerprint": interrupted_turn_test_reasoning_fingerprint(Some("high"))
+                })),
+            )
+            .await
+            .expect("turn should start");
+        manager
+            .mark_dialog_turn_interrupted(&session.session_id, &turn_id)
+            .await
+            .expect("turn should become interrupted");
+        manager
+            .update_session_state_for_turn_if_processing(
+                &session.session_id,
+                &turn_id,
+                SessionState::Idle,
+            )
+            .await
+            .expect("session should settle idle");
+        manager
+            .sessions
+            .get_mut(&session.session_id)
+            .expect("session should remain loaded")
+            .config
+            .reasoning_preset = Some("low".to_string());
+
+        let error = reopen_interrupted_turn_for_test(&manager, &session.session_id, &turn_id, 0)
+            .await
+            .expect_err("same Turn must not silently change reasoning preset");
+
+        assert!(error.to_string().contains("reasoning preset"), "{error}");
+    }
+
+    #[tokio::test]
+    async fn interrupted_turn_recovery_rejects_a_changed_auto_reasoning_default() {
+        let workspace = TestWorkspace::new();
+        let persistence_manager = Arc::new(
+            PersistenceManager::new(workspace.path_manager()).expect("persistence manager"),
+        );
+        let manager = test_manager(persistence_manager);
+        let session = manager
+            .create_session(
+                "Recovery auto reasoning".to_string(),
+                "agentic".to_string(),
+                SessionConfig {
+                    model_id: Some("model-original".to_string()),
+                    workspace_path: Some(workspace.path().to_string_lossy().to_string()),
+                    ..SessionConfig::default()
+                },
+            )
+            .await
+            .expect("session should create");
+        let turn_id = manager
+            .start_dialog_turn(
+                &session.session_id,
+                "agentic".to_string(),
+                "continue with the original auto reasoning default".to_string(),
+                Some("turn-auto-reasoning".to_string()),
+                None,
+                Some(serde_json::json!({
+                    "resolved_permission_mode": "ask",
+                    "runtime_resolved_model_id": "model-original",
+                    "runtime_model_binding_fingerprint": service_model_runtime_binding_fingerprint(
+                        &reasoning_model_with_default("model-original", "low")
+                    ),
+                    "runtime_reasoning_preset": "high",
+                    "runtime_reasoning_selection": null,
+                    "runtime_reasoning_fingerprint": interrupted_turn_test_auto_reasoning_fingerprint("high")
+                })),
+            )
+            .await
+            .expect("turn should start");
+        manager
+            .mark_dialog_turn_interrupted(&session.session_id, &turn_id)
+            .await
+            .expect("turn should become interrupted");
+        manager
+            .update_session_state_for_turn_if_processing(
+                &session.session_id,
+                &turn_id,
+                SessionState::Idle,
+            )
+            .await
+            .expect("session should settle idle");
+
+        let error = TEST_MODEL_RESOLUTION_AI_CONFIG
+            .scope(
+                ServiceAIConfig {
+                    models: vec![reasoning_model_with_default("model-original", "low")],
+                    ..Default::default()
+                },
+                manager.reopen_interrupted_dialog_turn(&session.session_id, &turn_id, 0),
+            )
+            .await
+            .expect_err("Auto must not resolve to a different preset for the same Turn");
+
+        assert!(error.to_string().contains("reasoning contract"), "{error}");
+    }
+
+    #[tokio::test]
+    async fn interrupted_turn_recovery_rejects_a_changed_model_binding() {
+        let workspace = TestWorkspace::new();
+        let persistence_manager = Arc::new(
+            PersistenceManager::new(workspace.path_manager()).expect("persistence manager"),
+        );
+        let manager = test_manager(persistence_manager);
+        let session = manager
+            .create_session(
+                "Recovery model binding".to_string(),
+                "agentic".to_string(),
+                SessionConfig {
+                    model_id: Some("model-original".to_string()),
+                    workspace_path: Some(workspace.path().to_string_lossy().to_string()),
+                    ..SessionConfig::default()
+                },
+            )
+            .await
+            .expect("session should create");
+        let turn_id = manager
+            .start_dialog_turn(
+                &session.session_id,
+                "agentic".to_string(),
+                "continue with the original model binding".to_string(),
+                Some("turn-model-binding".to_string()),
+                None,
+                Some(serde_json::json!({
+                    "resolved_permission_mode": "ask",
+                    "runtime_resolved_model_id": "model-original",
+                    "runtime_model_binding_fingerprint": interrupted_turn_test_model_fingerprint(),
+                    "runtime_reasoning_preset": null,
+                    "runtime_reasoning_selection": null,
+                    "runtime_reasoning_fingerprint": interrupted_turn_test_reasoning_fingerprint(None)
+                })),
+            )
+            .await
+            .expect("turn should start");
+        manager
+            .mark_dialog_turn_interrupted(&session.session_id, &turn_id)
+            .await
+            .expect("turn should become interrupted");
+        manager
+            .update_session_state_for_turn_if_processing(
+                &session.session_id,
+                &turn_id,
+                SessionState::Idle,
+            )
+            .await
+            .expect("session should settle idle");
 
-    struct TestWorkspace {
-        path: PathBuf,
+        let mut changed_model = configured_reasoning_model("model-original");
+        changed_model.model_name = "provider-model-v2".to_string();
+        let error = TEST_MODEL_RESOLUTION_AI_CONFIG
+            .scope(
+                ServiceAIConfig {
+                    models: vec![changed_model],
+                    ..Default::default()
+                },
+                manager.reopen_interrupted_dialog_turn(&session.session_id, &turn_id, 0),
+            )
+            .await
+            .expect_err("same model ID must not silently change its runtime binding");
+
+        assert!(error.to_string().contains("model binding"), "{error}");
     }
 
-    impl TestWorkspace {
-        fn new() -> Self {
-            let path = std::env::temp_dir()
-                .join(format!("bitfun-session-restore-test-{}", Uuid::new_v4()));
-            std::fs::create_dir_all(&path).expect("test workspace should be created");
-            Self { path }
-        }
+    #[tokio::test]
+    async fn dialog_turn_admission_rejects_a_concurrent_session_model_change() {
+        let workspace = TestWorkspace::new();
+        let persistence_manager = Arc::new(
+            PersistenceManager::new(workspace.path_manager()).expect("persistence manager"),
+        );
+        let manager = test_manager(persistence_manager);
+        let session = manager
+            .create_session(
+                "Turn admission CAS".to_string(),
+                "agentic".to_string(),
+                SessionConfig {
+                    workspace_path: Some(workspace.path().to_string_lossy().to_string()),
+                    model_id: Some("model-original".to_string()),
+                    reasoning_preset: Some("high".to_string()),
+                    ..SessionConfig::default()
+                },
+            )
+            .await
+            .expect("session should create");
+        let expected = TurnAdmissionSessionFacts::from_session(&session);
+        manager
+            .sessions
+            .get_mut(&session.session_id)
+            .expect("session should remain loaded")
+            .config
+            .model_id = Some("model-updated".to_string());
 
-        fn path(&self) -> &Path {
-            &self.path
-        }
+        let error = manager
+            .start_dialog_turn_with_prepended_messages_if_session_matches(
+                &session.session_id,
+                "agentic".to_string(),
+                "must retry admission".to_string(),
+                Some("turn-admission-race".to_string()),
+                None,
+                Vec::new(),
+                Some(serde_json::json!({"runtime_resolved_model_id": "model-original"})),
+                &expected,
+            )
+            .await
+            .expect_err("a concurrent settings update must invalidate admission");
 
-        fn path_manager(&self) -> Arc<PathManager> {
-            Arc::new(PathManager::with_user_root_for_tests(
-                self.path.join("user-root"),
-            ))
-        }
+        assert!(error.to_string().contains("changed during turn admission"));
+        assert_eq!(manager.get_turn_count(&session.session_id), 0);
     }
 
-    #[test]
-    fn invalidated_model_migration_preserves_approved_external_generation_binding() {
-        let invalidated = HashSet::from(["removed-model"]);
+    #[tokio::test]
+    async fn recovery_persistence_failure_keeps_memory_and_disk_interrupted() {
+        let workspace = TestWorkspace::new();
+        let persistence_manager = Arc::new(
+            PersistenceManager::new(workspace.path_manager()).expect("persistence manager"),
+        );
+        let manager = test_manager(persistence_manager.clone());
+        let session = manager
+            .create_session(
+                "Recovery rollback".to_string(),
+                "agentic".to_string(),
+                SessionConfig {
+                    workspace_path: Some(workspace.path().to_string_lossy().to_string()),
+                    ..SessionConfig::default()
+                },
+            )
+            .await
+            .expect("session should create");
+        let turn_id = manager
+            .start_dialog_turn(
+                &session.session_id,
+                "agentic".to_string(),
+                "finish the task".to_string(),
+                Some("turn-rollback".to_string()),
+                None,
+                Some(serde_json::json!({
+                    "resolved_permission_mode": "ask",
+                    "runtime_resolved_model_id": "model-original",
+                    "runtime_model_binding_fingerprint": interrupted_turn_test_model_fingerprint(),
+                    "runtime_reasoning_preset": null,
+                    "runtime_reasoning_selection": null,
+                    "runtime_reasoning_fingerprint": interrupted_turn_test_reasoning_fingerprint(None)
+                })),
+            )
+            .await
+            .expect("turn should start");
+        manager
+            .mark_dialog_turn_interrupted(&session.session_id, &turn_id)
+            .await
+            .expect("turn should become interrupted");
+        manager
+            .update_session_state_for_turn_if_processing(
+                &session.session_id,
+                &turn_id,
+                SessionState::Idle,
+            )
+            .await
+            .expect("session should settle idle");
 
-        assert!(should_auto_migrate_session_model(
-            SessionModelBindingPolicy::Mutable,
-            "removed-model",
-            &invalidated,
-        ));
-        assert!(!should_auto_migrate_session_model(
-            SessionModelBindingPolicy::ApprovedImmutable,
-            "removed-model",
-            &invalidated,
-        ));
-        assert!(!should_auto_migrate_session_model(
-            SessionModelBindingPolicy::Mutable,
-            "active-model",
-            &invalidated,
-        ));
-    }
+        persistence_manager.fail_next_session_state_write_for_test(&session.session_id);
+        reopen_interrupted_turn_for_test(&manager, &session.session_id, &turn_id, 0)
+            .await
+            .expect_err("injected session write must reject recovery");
 
-    #[test]
-    fn idle_eviction_only_selects_sessions_that_can_be_restored() {
-        let now = SystemTime::now();
-        let expired_at = now - Duration::from_secs(120);
-        let mut durable = Session::new(
-            "Durable".to_string(),
-            "agentic".to_string(),
-            SessionConfig::default(),
+        let active = manager
+            .get_session(&session.session_id)
+            .expect("session should remain active");
+        assert!(matches!(active.state, SessionState::Idle));
+        let persisted_session = persistence_manager
+            .load_session(workspace.path(), &session.session_id)
+            .await
+            .expect("session should reload");
+        assert!(matches!(persisted_session.state, SessionState::Idle));
+        let persisted_turn = persistence_manager
+            .load_dialog_turn(workspace.path(), &session.session_id, 0)
+            .await
+            .expect("turn should load")
+            .expect("turn should exist");
+        assert_eq!(persisted_turn.status, TurnStatus::Cancelled);
+        assert_eq!(
+            persisted_turn
+                .recovery
+                .as_ref()
+                .map(|recovery| recovery.status),
+            Some(DialogTurnRecoveryStatus::Interrupted),
         );
-        durable.last_activity_at = expired_at;
-        let mut transient = Session::new(
-            "Connection scoped".to_string(),
-            "agentic".to_string(),
-            SessionConfig::default(),
+
+        let plan = reopen_interrupted_turn_for_test(&manager, &session.session_id, &turn_id, 0)
+            .await
+            .expect("retry should reopen after rollback");
+        persistence_manager.fail_next_dialog_turn_write_for_test(&session.session_id);
+        manager
+            .complete_recovered_dialog_turn(
+                &session.session_id,
+                &turn_id,
+                plan.execution_generation,
+                "completion that cannot persist".to_string(),
+                &[],
+                TurnStats {
+                    total_rounds: 1,
+                    total_tools: 0,
+                    total_tokens: 0,
+                    duration_ms: 1,
+                },
+            )
+            .await
+            .expect_err("injected recovered completion write must fail");
+        manager
+            .mark_dialog_turn_interrupted(&session.session_id, &turn_id)
+            .await
+            .expect("failed recovered completion should return to interruption");
+        manager
+            .update_session_state_for_turn_if_processing(
+                &session.session_id,
+                &turn_id,
+                SessionState::Idle,
+            )
+            .await
+            .expect("fallback interruption should settle idle");
+        let persisted_turn = persistence_manager
+            .load_dialog_turn(workspace.path(), &session.session_id, 0)
+            .await
+            .expect("turn should load")
+            .expect("turn should exist");
+        assert_eq!(persisted_turn.status, TurnStatus::Cancelled);
+        assert_eq!(
+            persisted_turn.recovery_epoch,
+            Some(plan.execution_generation)
         );
-        transient.last_activity_at = expired_at;
-        let durable_id = durable.session_id.clone();
-        let transient_id = transient.session_id.clone();
-        let sessions = DashMap::new();
-        sessions.insert(durable_id.clone(), durable);
-        sessions.insert(transient_id.clone(), transient);
-        let transient_session_ids = DashMap::new();
-        transient_session_ids.insert(transient_id.clone(), ());
+        assert_eq!(
+            persisted_turn
+                .recovery
+                .as_ref()
+                .map(|recovery| (recovery.status, recovery.execution_generation)),
+            Some((
+                DialogTurnRecoveryStatus::Interrupted,
+                plan.execution_generation
+            )),
+        );
+    }
 
-        let candidates = SessionManager::collect_expired_session_candidates(
-            &sessions,
-            &transient_session_ids,
-            now,
-            Duration::from_secs(60),
+    #[tokio::test]
+    async fn recovered_completion_appends_rounds_after_the_existing_history() {
+        let workspace = TestWorkspace::new();
+        let persistence_manager = Arc::new(
+            PersistenceManager::new(workspace.path_manager()).expect("persistence manager"),
+        );
+        let manager = test_manager(persistence_manager.clone());
+        let session = manager
+            .create_session(
+                "Recovery append".to_string(),
+                "agentic".to_string(),
+                SessionConfig {
+                    workspace_path: Some(workspace.path().to_string_lossy().to_string()),
+                    ..SessionConfig::default()
+                },
+            )
+            .await
+            .expect("session should create");
+        let turn_id = manager
+            .start_dialog_turn(
+                &session.session_id,
+                "agentic".to_string(),
+                "finish the task".to_string(),
+                Some("turn-append".to_string()),
+                None,
+                Some(serde_json::json!({
+                    "resolved_permission_mode": "ask",
+                    "runtime_resolved_model_id": "model-original",
+                    "runtime_model_binding_fingerprint": interrupted_turn_test_model_fingerprint(),
+                    "runtime_reasoning_preset": null,
+                    "runtime_reasoning_selection": null,
+                    "runtime_reasoning_fingerprint": interrupted_turn_test_reasoning_fingerprint(None)
+                })),
+            )
+            .await
+            .expect("turn should start");
+        let mut persisted_turn = persistence_manager
+            .load_dialog_turn(workspace.path(), &session.session_id, 0)
+            .await
+            .expect("turn should load")
+            .expect("turn should exist");
+        persisted_turn.model_rounds = SessionManager::build_model_rounds_from_messages(
+            &[Message::assistant("before interruption".to_string())
+                .with_turn_id(turn_id.clone())
+                .with_round_id("round-before".to_string())],
+            &turn_id,
+            1,
         );
+        persistence_manager
+            .save_dialog_turn(workspace.path(), &persisted_turn)
+            .await
+            .expect("existing round should persist");
+        manager
+            .mark_dialog_turn_interrupted(&session.session_id, &turn_id)
+            .await
+            .expect("turn should become interrupted");
+        manager
+            .update_session_state_for_turn_if_processing(
+                &session.session_id,
+                &turn_id,
+                SessionState::Idle,
+            )
+            .await
+            .expect("session should settle idle");
+        let plan = reopen_interrupted_turn_for_test(&manager, &session.session_id, &turn_id, 0)
+            .await
+            .expect("turn should reopen");
+
+        manager
+            .complete_recovered_dialog_turn(
+                &session.session_id,
+                &turn_id,
+                plan.execution_generation,
+                "after recovery".to_string(),
+                &[Message::assistant("after recovery".to_string())
+                    .with_turn_id(turn_id.clone())
+                    .with_round_id("round-after".to_string())],
+                TurnStats {
+                    total_rounds: 1,
+                    total_tools: 0,
+                    total_tokens: 0,
+                    duration_ms: 1,
+                },
+            )
+            .await
+            .expect("recovered completion should persist");
 
+        let completed = persistence_manager
+            .load_dialog_turn(workspace.path(), &session.session_id, 0)
+            .await
+            .expect("turn should load")
+            .expect("turn should exist");
+        assert_eq!(completed.model_rounds.len(), 2);
+        assert_eq!(completed.model_rounds[0].round_index, 0);
+        assert_eq!(completed.model_rounds[1].round_index, 1);
         assert_eq!(
-            candidates
-                .iter()
-                .map(|candidate| candidate.session_id.as_str())
-                .collect::<Vec<_>>(),
-            [durable_id.as_str()]
+            completed.model_rounds[1].text_items[0].content,
+            "after recovery"
         );
-        assert!(sessions.contains_key(&transient_id));
+        assert!(completed.recovery.is_none());
+        assert_eq!(completed.recovery_epoch, Some(plan.execution_generation));
     }
 
-    #[test]
-    fn persisted_round_preserves_deferred_wire_call_and_effective_identity() {
+    #[tokio::test]
+    async fn repeated_interruption_persists_recovered_generation_rounds() {
+        let workspace = TestWorkspace::new();
+        let persistence_manager = Arc::new(
+            PersistenceManager::new(workspace.path_manager()).expect("persistence manager"),
+        );
+        let manager = test_manager(persistence_manager.clone());
+        let session = manager
+            .create_session(
+                "Repeated recovery".to_string(),
+                "agentic".to_string(),
+                SessionConfig {
+                    workspace_path: Some(workspace.path().to_string_lossy().to_string()),
+                    ..SessionConfig::default()
+                },
+            )
+            .await
+            .expect("session should create");
+        let turn_id = manager
+            .start_dialog_turn(
+                &session.session_id,
+                "agentic".to_string(),
+                "continue through two interruptions".to_string(),
+                Some("turn-repeat-interruption".to_string()),
+                None,
+                Some(serde_json::json!({
+                    "resolved_permission_mode": "ask",
+                    "runtime_resolved_model_id": "model-original",
+                    "runtime_model_binding_fingerprint": interrupted_turn_test_model_fingerprint(),
+                    "runtime_reasoning_preset": null,
+                    "runtime_reasoning_selection": null,
+                    "runtime_reasoning_fingerprint": interrupted_turn_test_reasoning_fingerprint(None)
+                })),
+            )
+            .await
+            .expect("turn should start");
+        manager
+            .mark_dialog_turn_interrupted(&session.session_id, &turn_id)
+            .await
+            .expect("first generation should interrupt");
+        manager
+            .update_session_state_for_turn_if_processing(
+                &session.session_id,
+                &turn_id,
+                SessionState::Idle,
+            )
+            .await
+            .expect("session should settle idle");
+        let first_recovery =
+            reopen_interrupted_turn_for_test(&manager, &session.session_id, &turn_id, 0)
+                .await
+                .expect("first recovery should reopen");
+
         let assistant = Message::assistant_with_tools(
             String::new(),
             vec![ToolCall {
-                tool_id: "tool-1".to_string(),
-                tool_name: bitfun_agent_tools::CALL_DEFERRED_TOOL_NAME.to_string(),
-                arguments: json!({
-                    "tool_name": "WebFetch",
-                    "args": { "url": "https://example.test" }
-                }),
+                tool_id: "tool-recovered".to_string(),
+                tool_name: "Read".to_string(),
+                arguments: json!({"path": "README.md"}),
                 raw_arguments: None,
                 is_error: false,
                 parse_error: None,
@@ -8250,108 +10362,148 @@ mod tests {
                 repair_kind: Default::default(),
             }],
         )
-        .with_turn_id("turn-1".to_string())
-        .with_round_id("round-1".to_string());
-        let result = Message::tool_result(ToolResult {
-            tool_id: "tool-1".to_string(),
-            tool_name: bitfun_agent_tools::CALL_DEFERRED_TOOL_NAME.to_string(),
-            effective_tool_name: Some("WebFetch".to_string()),
-            result: json!({ "content": "external content" }),
-            result_for_assistant: Some("external content".to_string()),
+        .with_turn_id(turn_id.clone())
+        .with_round_id("recovered-round".to_string());
+        let tool_result = Message::tool_result(ToolResult {
+            tool_id: "tool-recovered".to_string(),
+            tool_name: "Read".to_string(),
+            effective_tool_name: None,
+            result: json!({"content": "safe boundary"}),
+            result_for_assistant: Some("safe boundary".to_string()),
             is_error: false,
             duration_ms: Some(1),
             image_attachments: None,
         })
-        .with_turn_id("turn-1".to_string())
-        .with_round_id("round-1".to_string());
-
-        let persisted_messages: Vec<Message> = serde_json::from_value(
-            serde_json::to_value(vec![assistant, result]).expect("serialize messages"),
-        )
-        .expect("deserialize messages");
-        let provider_result: crate::util::types::Message = (&persisted_messages[1]).into();
-        assert_eq!(
-            provider_result.name.as_deref(),
-            Some(bitfun_agent_tools::CALL_DEFERRED_TOOL_NAME)
-        );
-
-        let rounds =
-            SessionManager::build_model_rounds_from_messages(&persisted_messages, "turn-1", 1);
+        .with_turn_id(turn_id.clone())
+        .with_round_id("recovered-round".to_string());
+        manager
+            .mark_dialog_turn_interrupted_with_messages(
+                &session.session_id,
+                &turn_id,
+                &[assistant, tool_result],
+            )
+            .await
+            .expect("recovered generation should interrupt durably");
+        manager
+            .update_session_state_for_turn_if_processing(
+                &session.session_id,
+                &turn_id,
+                SessionState::Idle,
+            )
+            .await
+            .expect("session should settle idle again");
 
-        assert_eq!(rounds.len(), 1);
-        assert_eq!(rounds[0].tool_items.len(), 1);
-        let tool = &rounds[0].tool_items[0];
-        assert_eq!(tool.tool_name, bitfun_agent_tools::CALL_DEFERRED_TOOL_NAME);
+        let persisted = persistence_manager
+            .load_dialog_turn(workspace.path(), &session.session_id, 0)
+            .await
+            .expect("turn should load")
+            .expect("turn should exist");
+        assert_eq!(persisted.model_rounds.len(), 1);
+        assert_eq!(persisted.model_rounds[0].round_index, 0);
         assert_eq!(
-            tool.tool_call.input,
-            json!({
-                "tool_name": "WebFetch",
-                "args": { "url": "https://example.test" }
-            })
+            persisted.model_rounds[0].tool_items[0]
+                .tool_result
+                .as_ref()
+                .map(|result| result.success),
+            Some(true),
         );
-        let (effective_name, effective_input) =
-            crate::service::session::effective_tool_identity(tool);
-        assert_eq!(effective_name, "WebFetch");
-        assert_eq!(effective_input, &json!({ "url": "https://example.test" }));
-    }
-
-    impl Drop for TestWorkspace {
-        fn drop(&mut self) {
-            let _ = std::fs::remove_dir_all(&self.path);
-        }
-    }
-
-    fn test_manager(persistence_manager: Arc<PersistenceManager>) -> SessionManager {
-        SessionManager::new(
-            Arc::new(SessionContextStore::new()),
-            persistence_manager,
-            SessionManagerConfig {
-                max_active_sessions: 100,
-                session_idle_timeout: Duration::from_secs(3600),
-                auto_save_interval: Duration::from_secs(300),
-                enable_persistence: true,
-                prompt_cache_policy: PromptCachePolicy::default(),
-            },
+        let next_recovery = reopen_interrupted_turn_for_test(
+            &manager,
+            &session.session_id,
+            &turn_id,
+            first_recovery.execution_generation,
         )
+        .await
+        .expect("second recovery should reopen after appended history");
+        assert_eq!(next_recovery.initial_round_index, 1);
     }
 
-    fn test_manager_with_config(
-        persistence_manager: Arc<PersistenceManager>,
-        config: SessionManagerConfig,
-    ) -> SessionManager {
-        SessionManager::new(
-            Arc::new(SessionContextStore::new()),
-            persistence_manager,
-            config,
-        )
-    }
+    #[tokio::test]
+    async fn first_interruption_merges_a_partially_persisted_round_prefix() {
+        let workspace = TestWorkspace::new();
+        let persistence_manager = Arc::new(
+            PersistenceManager::new(workspace.path_manager()).expect("persistence manager"),
+        );
+        let manager = test_manager(persistence_manager.clone());
+        let session = manager
+            .create_session(
+                "Interrupted merge".to_string(),
+                "agentic".to_string(),
+                SessionConfig {
+                    workspace_path: Some(workspace.path().to_string_lossy().to_string()),
+                    ..SessionConfig::default()
+                },
+            )
+            .await
+            .expect("session should create");
+        let turn_id = manager
+            .start_dialog_turn(
+                &session.session_id,
+                "agentic".to_string(),
+                "merge frontend and runtime rounds".to_string(),
+                Some("turn-prefix-merge".to_string()),
+                None,
+                Some(serde_json::json!({
+                    "resolved_permission_mode": "ask",
+                    "runtime_resolved_model_id": "model-original",
+                    "runtime_model_binding_fingerprint": interrupted_turn_test_model_fingerprint(),
+                    "runtime_reasoning_preset": null,
+                    "runtime_reasoning_selection": null,
+                    "runtime_reasoning_fingerprint": interrupted_turn_test_reasoning_fingerprint(None)
+                })),
+            )
+            .await
+            .expect("turn should start");
+        let persisted_prefix = Message::assistant("frontend prefix".to_string())
+            .with_turn_id(turn_id.clone())
+            .with_round_id("round-shared".to_string());
+        let mut persisted_turn = persistence_manager
+            .load_dialog_turn(workspace.path(), &session.session_id, 0)
+            .await
+            .expect("turn should load")
+            .expect("turn should exist");
+        persisted_turn.model_rounds =
+            SessionManager::build_model_rounds_from_messages(&[persisted_prefix], &turn_id, 1);
+        persistence_manager
+            .save_dialog_turn(workspace.path(), &persisted_turn)
+            .await
+            .expect("frontend prefix should persist");
 
-    fn test_path_manager() -> Arc<PathManager> {
-        let root =
-            std::env::temp_dir().join(format!("bitfun-session-manager-test-{}", Uuid::new_v4()));
-        Arc::new(PathManager::with_user_root_for_tests(
-            root.join("user-root"),
-        ))
-    }
+        let runtime_rounds = [
+            Message::assistant("runtime authoritative prefix".to_string())
+                .with_turn_id(turn_id.clone())
+                .with_round_id("round-shared".to_string()),
+            Message::assistant("runtime missing tail".to_string())
+                .with_turn_id(turn_id.clone())
+                .with_round_id("round-tail".to_string()),
+        ];
+        manager
+            .mark_dialog_turn_interrupted_with_messages(
+                &session.session_id,
+                &turn_id,
+                &runtime_rounds,
+            )
+            .await
+            .expect("interruption should merge the runtime journal");
 
-    fn in_memory_test_manager() -> SessionManager {
-        let persistence_manager =
-            Arc::new(PersistenceManager::new(test_path_manager()).expect("persistence manager"));
-        SessionManager::new(
-            Arc::new(SessionContextStore::new()),
-            persistence_manager,
-            SessionManagerConfig {
-                max_active_sessions: 100,
-                session_idle_timeout: Duration::from_secs(3600),
-                auto_save_interval: Duration::from_secs(300),
-                enable_persistence: false,
-                prompt_cache_policy: PromptCachePolicy::default(),
-            },
-        )
+        let persisted = persistence_manager
+            .load_dialog_turn(workspace.path(), &session.session_id, 0)
+            .await
+            .expect("turn should load")
+            .expect("turn should exist");
+        assert_eq!(persisted.model_rounds.len(), 2);
+        assert_eq!(persisted.model_rounds[0].id, "round-shared");
+        assert_eq!(persisted.model_rounds[0].round_index, 0);
+        assert_eq!(
+            persisted.model_rounds[0].text_items[0].content,
+            "runtime authoritative prefix"
+        );
+        assert_eq!(persisted.model_rounds[1].id, "round-tail");
+        assert_eq!(persisted.model_rounds[1].round_index, 1);
     }
 
     #[tokio::test]
-    async fn current_context_usage_is_persisted_by_the_session_owner() {
+    async fn restore_reopens_a_recovering_turn_when_the_session_write_was_lost() {
         let workspace = TestWorkspace::new();
         let persistence_manager = Arc::new(
             PersistenceManager::new(workspace.path_manager()).expect("persistence manager"),
@@ -8359,41 +10511,89 @@ mod tests {
         let manager = test_manager(persistence_manager.clone());
         let session = manager
             .create_session(
-                "Usage persistence".to_string(),
+                "Recovery restart".to_string(),
                 "agentic".to_string(),
                 SessionConfig {
+                    model_id: Some("auto".to_string()),
                     workspace_path: Some(workspace.path().to_string_lossy().to_string()),
                     ..SessionConfig::default()
                 },
             )
             .await
             .expect("session should create");
-        let usage = SessionContextUsage {
-            turn_id: "turn-1".to_string(),
-            input_tokens: 42_000,
-            output_tokens: Some(1_500),
-            total_tokens: 43_500,
-            timestamp: 123,
-            source: SessionContextUsageSource::ModelRequest,
-        };
+        let turn_id = manager
+            .start_dialog_turn(
+                &session.session_id,
+                "agentic".to_string(),
+                "finish after restart".to_string(),
+                Some("turn-restart".to_string()),
+                None,
+                Some(serde_json::json!({
+                    "resolved_permission_mode": "ask",
+                    "runtime_resolved_model_id": "model-original",
+                    "runtime_model_binding_fingerprint": interrupted_turn_test_model_fingerprint(),
+                    "runtime_reasoning_preset": null,
+                    "runtime_reasoning_selection": null,
+                    "runtime_reasoning_fingerprint": interrupted_turn_test_reasoning_fingerprint(None)
+                })),
+            )
+            .await
+            .expect("turn should start");
         manager
-            .sessions
-            .get_mut(&session.session_id)
-            .expect("session should be active")
-            .dialog_turn_ids
-            .push(usage.turn_id.clone());
-
+            .mark_dialog_turn_interrupted(&session.session_id, &turn_id)
+            .await
+            .expect("turn should become interrupted");
         manager
-            .persist_current_context_usage(&session.session_id, usage.clone())
+            .update_session_state_for_turn_if_processing(
+                &session.session_id,
+                &turn_id,
+                SessionState::Idle,
+            )
             .await
-            .expect("usage should persist");
+            .expect("session should settle idle");
+        let first_recovery =
+            reopen_interrupted_turn_for_test(&manager, &session.session_id, &turn_id, 0)
+                .await
+                .expect("turn should start recovering");
+        assert_eq!(first_recovery.execution_generation, 1);
 
-        let metadata = persistence_manager
-            .load_session_metadata(workspace.path(), &session.session_id)
+        // Simulate a crash after the recovering Turn rename but before the
+        // Processing Session rename. The older Idle Session file must not hide
+        // the abandoned execution generation forever.
+        let mut stale_session = persistence_manager
+            .load_session(workspace.path(), &session.session_id)
             .await
-            .expect("metadata should load")
-            .expect("metadata should exist");
-        assert_eq!(metadata.current_context_usage, Some(usage));
+            .expect("persisted session should load");
+        stale_session.state = SessionState::Idle;
+        persistence_manager
+            .save_session(workspace.path(), &stale_session)
+            .await
+            .expect("stale idle session should persist");
+        manager.evict_loaded_session_for_test(&session.session_id);
+        drop(manager);
+
+        let restored_manager = test_manager(persistence_manager.clone());
+        let (restored_session, restored_turns) = restored_manager
+            .restore_session_with_turns(workspace.path(), &session.session_id)
+            .await
+            .expect("restart should restore the session");
+
+        assert!(matches!(restored_session.state, SessionState::Idle));
+        let restored_turn = restored_turns.last().expect("latest turn should restore");
+        assert_eq!(restored_turn.status, TurnStatus::Cancelled);
+        assert_eq!(
+            restored_turn
+                .recovery
+                .as_ref()
+                .map(|recovery| (recovery.status, recovery.execution_generation)),
+            Some((DialogTurnRecoveryStatus::Interrupted, 1)),
+        );
+
+        let second_recovery =
+            reopen_interrupted_turn_for_test(&restored_manager, &session.session_id, &turn_id, 1)
+                .await
+                .expect("the interrupted generation should remain recoverable");
+        assert_eq!(second_recovery.execution_generation, 2);
     }
 
     #[tokio::test]
@@ -9130,6 +11330,71 @@ mod tests {
         ));
     }
 
+    #[tokio::test]
+    async fn active_turn_permission_mode_is_exact_mutable_and_stale_safe() {
+        let manager = in_memory_test_manager();
+        let session_id = Uuid::new_v4().to_string();
+        let mut session = Session::new_with_id(
+            session_id.clone(),
+            "Active permission session".to_string(),
+            "agentic".to_string(),
+            SessionConfig::default(),
+        );
+        session.state = SessionState::Processing {
+            current_turn_id: "turn-1".to_string(),
+            phase: ProcessingPhase::Thinking,
+        };
+        manager.sessions.insert(session_id.clone(), session);
+
+        assert!(manager.set_active_turn_permission_mode(
+            &session_id,
+            "turn-1",
+            PermissionMode::Ask,
+        ));
+        assert!(manager.set_active_turn_permission_mode(
+            &session_id,
+            "turn-1",
+            PermissionMode::FullAccess,
+        ));
+        assert_eq!(
+            manager.active_turn_permission_mode(&session_id, "turn-1"),
+            Some(PermissionMode::FullAccess),
+        );
+        assert!(!manager.set_active_turn_permission_mode(
+            &session_id,
+            "stale-turn",
+            PermissionMode::AutoApprove,
+        ));
+
+        manager
+            .sessions
+            .get_mut(&session_id)
+            .expect("active session")
+            .state = SessionState::Processing {
+            current_turn_id: "turn-2".to_string(),
+            phase: ProcessingPhase::Thinking,
+        };
+        assert_eq!(
+            manager.active_turn_permission_mode(&session_id, "turn-1"),
+            None,
+        );
+        assert!(manager.set_active_turn_permission_mode(
+            &session_id,
+            "turn-2",
+            PermissionMode::AutoApprove,
+        ));
+        assert!(!manager.clear_active_turn_permission_mode(&session_id, "turn-1"));
+        assert_eq!(
+            manager.active_turn_permission_mode(&session_id, "turn-2"),
+            Some(PermissionMode::AutoApprove),
+        );
+        assert!(manager.clear_active_turn_permission_mode(&session_id, "turn-2"));
+        assert_eq!(
+            manager.active_turn_permission_mode(&session_id, "turn-2"),
+            None,
+        );
+    }
+
     #[tokio::test]
     async fn transient_session_cannot_bypass_owned_discard_through_unload() {
         let workspace = TestWorkspace::new();
@@ -10397,6 +12662,30 @@ mod tests {
         }
     }
 
+    fn reasoning_model_with_default(id: &str, default_preset: &str) -> ServiceAIModelConfig {
+        ServiceAIModelConfig {
+            id: id.to_string(),
+            name: id.to_string(),
+            model_name: id.to_string(),
+            enabled: true,
+            reasoning: Some(ReasoningConfig {
+                catalog: ReasoningCatalogBinding::Disabled,
+                default_preset: Some(default_preset.to_string()),
+                presets: ["low", "high"]
+                    .into_iter()
+                    .map(|preset_id| ReasoningPreset {
+                        id: preset_id.to_string(),
+                        actions: vec![ReasoningPresetAction::Effort {
+                            value: preset_id.to_string(),
+                        }],
+                        ..Default::default()
+                    })
+                    .collect(),
+            }),
+            ..Default::default()
+        }
+    }
+
     #[cfg(feature = "model-catalog")]
     #[tokio::test]
     async fn reasoning_preset_normalization_uses_the_updated_model() {
diff --git a/src/crates/assembly/core/src/agentic/tools/browser_control/actions.rs b/src/crates/assembly/core/src/agentic/tools/browser_control/actions.rs
index 887d3d2abf..3917e1c196 100644
--- a/src/crates/assembly/core/src/agentic/tools/browser_control/actions.rs
+++ b/src/crates/assembly/core/src/agentic/tools/browser_control/actions.rs
@@ -7,6 +7,16 @@ use serde_json::{json, Value};
 use std::collections::BTreeMap;
 use tokio::sync::broadcast;
 
+/// Upper bound for an explicit `wait` duration. Pacing waits ("check again in
+/// 30 minutes") are a legitimate agent pattern, so the ceiling is generous;
+/// it exists only so a nonsense duration cannot wedge the session forever.
+/// Kept in step with `AgentWaitTool::MAX_TIMEOUT_MS`.
+pub const MAX_WAIT_MS: u64 = 60 * 60 * 1_000;
+
+/// How long a `wait { condition }` runs before giving up when the caller does
+/// not say. Matches the previous hard-coded lifecycle and selector budgets.
+pub const DEFAULT_CONDITION_TIMEOUT_MS: u64 = 15_000;
+
 /// Result of waiting for a CDP `Page.lifecycleEvent`.
 enum LifecycleOutcome {
     /// One of the requested lifecycle names fired in time. Carries the name
@@ -1054,17 +1064,35 @@ impl<'a> BrowserActions<'a> {
     }
 
     /// Wait for a duration or a condition.
+    ///
+    /// Callers that can observe cancellation should sleep themselves rather
+    /// than routing a plain duration through here — see ControlHub's
+    /// `browser.wait`, which owns the cancellable, session-free duration path.
+    ///
+    /// `condition_timeout_ms` bounds the condition wait; it defaults to
+    /// [`DEFAULT_CONDITION_TIMEOUT_MS`] and is ignored for duration waits.
     pub async fn wait(
         &self,
         duration_ms: Option<u64>,
         condition: Option<&str>,
+        condition_timeout_ms: Option<u64>,
     ) -> BitFunResult<Value> {
         if let Some(ms) = duration_ms {
-            let clamped = ms.min(30_000);
+            let clamped = ms.min(MAX_WAIT_MS);
             tokio::time::sleep(std::time::Duration::from_millis(clamped)).await;
-            return Ok(json!({ "success": true, "action": "wait", "ms": clamped }));
+            return Ok(json!({
+                "success": true,
+                "action": "wait",
+                "ms": clamped,
+                "requested_ms": ms,
+                "clamped": clamped != ms,
+            }));
         }
         if let Some(cond) = condition {
+            let timeout_ms = condition_timeout_ms
+                .filter(|ms| *ms > 0)
+                .unwrap_or(DEFAULT_CONDITION_TIMEOUT_MS)
+                .min(MAX_WAIT_MS);
             match cond {
                 "networkidle" | "load" | "domcontentloaded" => {
                     // Phase 1: replace the previous "sleep 2s and hope" with
@@ -1085,7 +1113,7 @@ impl<'a> BrowserActions<'a> {
                         "domcontentloaded" => &["DOMContentLoaded", "load"],
                         _ => &["load"],
                     };
-                    let outcome = wait_for_lifecycle(&mut events, None, wanted, 15_000).await;
+                    let outcome = wait_for_lifecycle(&mut events, None, wanted, timeout_ms).await;
                     let (success, lifecycle_event, timed_out) = match outcome {
                         LifecycleOutcome::Reached(n) => (true, Some(n), false),
                         LifecycleOutcome::Timeout => (false, None, true),
@@ -1097,11 +1125,15 @@ impl<'a> BrowserActions<'a> {
                         "condition": cond,
                         "lifecycle_event": lifecycle_event,
                         "timed_out": timed_out,
+                        "timeout_ms": timeout_ms,
                     }));
                 }
                 selector => {
+                    const POLL_INTERVAL_MS: u64 = 500;
                     let js = Self::element_exists_js(selector);
-                    for _ in 0..30 {
+                    let deadline =
+                        tokio::time::Instant::now() + std::time::Duration::from_millis(timeout_ms);
+                    loop {
                         let result = self.evaluate(&js).await?;
                         let found = result
                             .get("result")
@@ -1109,11 +1141,23 @@ impl<'a> BrowserActions<'a> {
                             .and_then(|v| v.as_bool())
                             .unwrap_or(false);
                         if found {
-                            return Ok(
-                                json!({ "success": true, "action": "wait", "condition": cond }),
-                            );
+                            return Ok(json!({
+                                "success": true,
+                                "action": "wait",
+                                "condition": cond,
+                                "timeout_ms": timeout_ms,
+                            }));
                         }
-                        tokio::time::sleep(std::time::Duration::from_millis(500)).await;
+                        let remaining = deadline
+                            .saturating_duration_since(tokio::time::Instant::now())
+                            .as_millis() as u64;
+                        if remaining == 0 {
+                            break;
+                        }
+                        tokio::time::sleep(std::time::Duration::from_millis(
+                            remaining.min(POLL_INTERVAL_MS),
+                        ))
+                        .await;
                     }
                     return Err(structured_error(
                         ErrorCode::Timeout,
@@ -1123,7 +1167,18 @@ impl<'a> BrowserActions<'a> {
                 }
             }
         }
-        Ok(json!({ "success": true, "action": "wait" }))
+        // No duration and no condition: there is nothing to wait for. Reporting
+        // success here used to make a mis-keyed duration (`ms` instead of
+        // `duration_ms`) look like a completed wait that in fact returned
+        // instantly, so the agent silently skipped its pause.
+        Err(structured_error(
+            ErrorCode::InvalidParams,
+            "wait requires a duration or a condition",
+            &[
+                "Pass `duration_ms` (alias `ms`) to pause, e.g. { \"duration_ms\": 1800000 } for 30 minutes",
+                "Or pass `condition`: 'load' | 'domcontentloaded' | 'networkidle' | a CSS/@ref selector",
+            ],
+        ))
     }
 
     // ── Capture ────────────────────────────────────────────────────────
diff --git a/src/crates/assembly/core/src/agentic/tools/browser_control/browser_launcher.rs b/src/crates/assembly/core/src/agentic/tools/browser_control/browser_launcher.rs
index 5d0f36ecbd..f25a72903e 100644
--- a/src/crates/assembly/core/src/agentic/tools/browser_control/browser_launcher.rs
+++ b/src/crates/assembly/core/src/agentic/tools/browser_control/browser_launcher.rs
@@ -7,7 +7,8 @@
 
 use bitfun_services_integrations::browser_control::launcher as provider;
 pub use provider::{
-    BrowserInfo, BrowserKind, BrowserLaunchOptions, LaunchResult, DEFAULT_CDP_PORT,
+    BrowserDebugEndpoint, BrowserInfo, BrowserKind, BrowserLaunchOptions, LaunchResult,
+    DEFAULT_CDP_PORT,
 };
 use std::path::PathBuf;
 
@@ -52,6 +53,21 @@ impl BrowserLauncher {
         provider::BrowserLauncher::browser_executable(kind)
     }
 
+    pub fn supports_default_cdp(kind: &BrowserKind) -> bool {
+        provider::BrowserLauncher::supports_default_cdp(kind)
+    }
+
+    pub fn is_default_cdp_enabled(kind: &BrowserKind) -> bool {
+        provider::BrowserLauncher::is_default_cdp_enabled(kind)
+    }
+
+    /// Browser-level endpoint published by a browser that is running right now
+    /// with remote debugging enabled. `None` means there is nothing to attach
+    /// to without going through the launch flow.
+    pub fn user_profile_debug_endpoint(kind: &BrowserKind) -> Option<BrowserDebugEndpoint> {
+        provider::BrowserLauncher::user_profile_debug_endpoint(kind)
+    }
+
     pub async fn launch_with_cdp(kind: &BrowserKind, port: u16) -> BitFunResult<LaunchResult> {
         Ok(provider::BrowserLauncher::launch_with_cdp_options(
             kind,
@@ -78,17 +94,20 @@ impl BrowserLauncher {
         Self::launch_with_cdp(kind, port).await
     }
 
-    #[cfg(target_os = "macos")]
-    pub fn create_cdp_launcher_app(kind: &BrowserKind, port: u16) -> BitFunResult<String> {
-        Ok(provider::BrowserLauncher::create_cdp_launcher_app(
-            kind, port,
-        )?)
+    /// Explicit Settings flow: keep the browser settings page open long enough
+    /// for the user-owned consent toggle, then continue with the guarded
+    /// real-profile connection as soon as the endpoint appears.
+    pub async fn enable_default_cdp(kind: &BrowserKind, port: u16) -> BitFunResult<LaunchResult> {
+        let mut options = Self::launch_options(None);
+        options.wait_for_user_profile_setup = true;
+        Ok(provider::BrowserLauncher::launch_with_cdp_options(kind, port, options).await?)
     }
 
     fn launch_options(user_data_dir: Option<&str>) -> BrowserLaunchOptions {
         BrowserLaunchOptions {
             user_data_dir: user_data_dir.map(PathBuf::from),
             managed_profile_root: Some(get_path_manager_arc().user_data_dir()),
+            wait_for_user_profile_setup: false,
         }
     }
 }
diff --git a/src/crates/assembly/core/src/agentic/tools/browser_control/cdp_client.rs b/src/crates/assembly/core/src/agentic/tools/browser_control/cdp_client.rs
index 118d35adce..408233289a 100644
--- a/src/crates/assembly/core/src/agentic/tools/browser_control/cdp_client.rs
+++ b/src/crates/assembly/core/src/agentic/tools/browser_control/cdp_client.rs
@@ -8,15 +8,24 @@ use futures::{SinkExt, StreamExt};
 use log::{debug, info, warn};
 use serde_json::{json, Value};
 use std::collections::HashMap;
-use std::sync::atomic::{AtomicI64, Ordering};
-use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicI64, Ordering};
+use std::sync::{Arc, OnceLock, Weak};
+use std::time::Duration;
 use tokio::net::TcpStream;
 use tokio::sync::{broadcast, Mutex, RwLock};
 use tokio_tungstenite::tungstenite::Message;
 use tokio_tungstenite::{connect_async, MaybeTlsStream, WebSocketStream};
 
+use super::browser_launcher::BrowserKind;
+
 type WsSink = SplitSink<WebSocketStream<MaybeTlsStream<TcpStream>>, Message>;
 type WsStream = SplitStream<WebSocketStream<MaybeTlsStream<TcpStream>>>;
+type PendingResponses = Arc<RwLock<HashMap<i64, tokio::sync::oneshot::Sender<Value>>>>;
+type EventChannels = Arc<RwLock<HashMap<Option<String>, broadcast::Sender<CdpEvent>>>>;
+type SessionStatuses = Arc<RwLock<HashMap<String, Weak<AtomicBool>>>>;
+
+const PAGE_CDP_CONNECT_TIMEOUT: Duration = Duration::from_secs(30);
+const USER_PROFILE_APPROVAL_TIMEOUT: Duration = Duration::from_secs(90);
 
 /// A single CDP event emitted by the browser (no `id`, has `method` + `params`).
 #[derive(Debug, Clone)]
@@ -25,88 +34,231 @@ pub struct CdpEvent {
     pub params: Value,
 }
 
-/// A CDP WebSocket client connected to a single page target.
-pub struct CdpClient {
+struct CdpTransport {
     sink: Arc<Mutex<WsSink>>,
-    pending: Arc<RwLock<HashMap<i64, tokio::sync::oneshot::Sender<Value>>>>,
+    pending: PendingResponses,
     next_id: AtomicI64,
-    /// Broadcast bus for unsolicited CDP events. Subscribers may filter by
-    /// `method` (e.g. `"Page.lifecycleEvent"`).
+    event_channels: EventChannels,
+    session_statuses: SessionStatuses,
+    alive: Arc<AtomicBool>,
+    reader_handle: tokio::task::JoinHandle<()>,
+}
+
+impl Drop for CdpTransport {
+    fn drop(&mut self) {
+        self.reader_handle.abort();
+    }
+}
+
+/// A CDP client connected either directly to a page WebSocket or to a flattened
+/// target session carried by a browser-level WebSocket. The latter is required
+/// for user-approved real-profile connections because guarded endpoints do not
+/// necessarily expose the legacy `/json` HTTP API.
+pub struct CdpClient {
+    transport: Arc<CdpTransport>,
+    session_id: Option<String>,
     events: broadcast::Sender<CdpEvent>,
-    _reader_handle: tokio::task::JoinHandle<()>,
+    session_alive: Option<Arc<AtomicBool>>,
+}
+
+/// Process-wide browser connection retained after the user approves BitFun.
+/// Keeping one browser WebSocket avoids repeated approval prompts and lets
+/// settings commands and agent tools share the same live profile.
+#[derive(Clone)]
+pub struct CdpBrowserConnection {
+    pub actual_port: u16,
+    pub browser_kind: BrowserKind,
+    pub client: Arc<CdpClient>,
+}
+
+static BROWSER_CONNECTIONS: OnceLock<RwLock<HashMap<u16, CdpBrowserConnection>>> = OnceLock::new();
+
+fn browser_connections() -> &'static RwLock<HashMap<u16, CdpBrowserConnection>> {
+    BROWSER_CONNECTIONS.get_or_init(|| RwLock::new(HashMap::new()))
 }
 
 impl CdpClient {
-    /// Discover browser version on the given debug port.
+    /// Discover browser version on a legacy fixed debug port.
     pub async fn get_version(port: u16) -> BitFunResult<CdpVersionInfo> {
         CdpEndpointProvider::get_version(port)
             .await
             .map_err(|error| BitFunError::tool(error.to_string()))
     }
 
-    /// List all pages/tabs on the given debug port.
+    /// List all pages/tabs on a legacy fixed debug port.
     pub async fn list_pages(port: u16) -> BitFunResult<Vec<CdpPageInfo>> {
         CdpEndpointProvider::list_pages(port)
             .await
             .map_err(|error| BitFunError::tool(error.to_string()))
     }
 
-    /// Create a new page/tab on the given debug port.
+    /// Create a new page/tab on a legacy fixed debug port.
     pub async fn create_page(port: u16, url: Option<&str>) -> BitFunResult<CdpPageInfo> {
         CdpEndpointProvider::create_page(port, url)
             .await
             .map_err(|error| BitFunError::tool(error.to_string()))
     }
 
-    /// Connect to a specific page by its WebSocket debugger URL.
+    /// Connect to a specific page by its legacy WebSocket debugger URL.
     pub async fn connect(ws_url: &str) -> BitFunResult<Self> {
-        info!("CDP connecting to {}", ws_url);
-        let (ws_stream, _) = connect_async(ws_url)
+        info!("CDP connecting to page WebSocket");
+        Self::connect_with_timeout(ws_url, PAGE_CDP_CONNECT_TIMEOUT).await
+    }
+
+    /// Connect to a guarded browser-level endpoint and retain it under the
+    /// logical port used by BitFun's browser tools. The WebSocket handshake
+    /// waits for the user to approve the request in their browser.
+    pub async fn connect_user_profile_browser(
+        logical_port: u16,
+        actual_port: u16,
+        browser_kind: &BrowserKind,
+        ws_url: &str,
+    ) -> BitFunResult<CdpBrowserConnection> {
+        if let Some(existing) = Self::browser_connection(logical_port).await {
+            if existing.actual_port == actual_port && existing.browser_kind == *browser_kind {
+                return Ok(existing);
+            }
+        }
+
+        info!(
+            "Requesting user-approved browser profile connection on port {}",
+            actual_port
+        );
+        let client = Arc::new(
+            Self::connect_with_timeout(ws_url, USER_PROFILE_APPROVAL_TIMEOUT)
+                .await
+                .map_err(|error| {
+                    BitFunError::tool(format!(
+                        "Could not connect to the current browser profile. Approve BitFun's remote debugging request in the browser, then try again: {}",
+                        error
+                    ))
+                })?,
+        );
+        // Validate that this is a browser-level CDP endpoint before retaining
+        // it. This also fails quickly if the DevToolsActivePort file was stale.
+        client.browser_version().await?;
+
+        let connection = CdpBrowserConnection {
+            actual_port,
+            browser_kind: browser_kind.clone(),
+            client,
+        };
+        browser_connections()
+            .write()
+            .await
+            .insert(logical_port, connection.clone());
+        Ok(connection)
+    }
+
+    /// Return a healthy retained browser connection, pruning it if the browser
+    /// has closed the underlying WebSocket.
+    pub async fn browser_connection(logical_port: u16) -> Option<CdpBrowserConnection> {
+        let existing = browser_connections()
+            .read()
+            .await
+            .get(&logical_port)
+            .cloned();
+        match existing {
+            Some(connection) if connection.client.is_connected() => Some(connection),
+            Some(_) => {
+                browser_connections().write().await.remove(&logical_port);
+                None
+            }
+            None => None,
+        }
+    }
+
+    /// Return the retained connection only when it belongs to the browser the
+    /// caller selected. A logical tool port is shared by every browser option,
+    /// so blindly reusing it after a Chrome/Edge switch would control the wrong
+    /// profile.
+    pub async fn browser_connection_for_kind(
+        logical_port: u16,
+        browser_kind: &BrowserKind,
+    ) -> Option<CdpBrowserConnection> {
+        Self::browser_connection(logical_port)
+            .await
+            .filter(|connection| connection.browser_kind == *browser_kind)
+    }
+
+    /// Forget the browser-level connection assigned to a logical tool port.
+    /// Existing page sessions retain their own transport references, while
+    /// subsequent browser actions resolve against the newly selected browser.
+    pub async fn remove_browser_connection(logical_port: u16) {
+        browser_connections().write().await.remove(&logical_port);
+    }
+
+    async fn connect_with_timeout(ws_url: &str, timeout: Duration) -> BitFunResult<Self> {
+        let (ws_stream, _) = tokio::time::timeout(timeout, connect_async(ws_url))
             .await
-            .map_err(|e| BitFunError::tool(format!("CDP WebSocket connect failed: {}", e)))?;
+            .map_err(|_| {
+                BitFunError::tool("Timed out waiting for the CDP WebSocket connection".to_string())
+            })?
+            .map_err(|error| {
+                BitFunError::tool(format!("CDP WebSocket connect failed: {}", error))
+            })?;
 
         let (sink, stream) = ws_stream.split();
         let sink = Arc::new(Mutex::new(sink));
-        let pending: Arc<RwLock<HashMap<i64, tokio::sync::oneshot::Sender<Value>>>> =
-            Arc::new(RwLock::new(HashMap::new()));
+        let pending: PendingResponses = Arc::new(RwLock::new(HashMap::new()));
+        let event_channels: EventChannels = Arc::new(RwLock::new(HashMap::new()));
+        let session_statuses: SessionStatuses = Arc::new(RwLock::new(HashMap::new()));
+        let alive = Arc::new(AtomicBool::new(true));
 
-        let pending_clone = pending.clone();
-        // Buffer up to 256 events per subscriber. Lifecycle / network events
-        // arrive in bursts during page load; older entries can be dropped from
-        // a subscriber lagging behind without affecting the protocol.
+        // Buffer up to 256 events per target subscriber. Lifecycle / network
+        // events arrive in bursts during page load; older entries can be
+        // dropped from a lagging subscriber without affecting the protocol.
         let (events_tx, _) = broadcast::channel::<CdpEvent>(256);
-        let events_for_reader = events_tx.clone();
-        let reader_handle =
-            tokio::spawn(Self::reader_loop(stream, pending_clone, events_for_reader));
+        event_channels.write().await.insert(None, events_tx.clone());
+
+        let reader_handle = tokio::spawn(Self::reader_loop(
+            stream,
+            pending.clone(),
+            event_channels.clone(),
+            session_statuses.clone(),
+            alive.clone(),
+        ));
 
         Ok(Self {
-            sink,
-            pending,
-            next_id: AtomicI64::new(1),
+            transport: Arc::new(CdpTransport {
+                sink,
+                pending,
+                next_id: AtomicI64::new(1),
+                event_channels,
+                session_statuses,
+                alive,
+                reader_handle,
+            }),
+            session_id: None,
             events: events_tx,
-            _reader_handle: reader_handle,
+            session_alive: None,
         })
     }
 
-    /// Subscribe to *all* CDP events. Filter on `method` at the call site.
+    /// Subscribe to events for this page session only.
     pub fn subscribe_events(&self) -> broadcast::Receiver<CdpEvent> {
         self.events.subscribe()
     }
 
-    /// Returns `true` while the WebSocket reader task is still running.
-    /// `BrowserSessionRegistry` uses this to evict sessions whose tab the
-    /// user closed out-of-band (without going through `browser.close`),
-    /// avoiding a 30-second `CDP timeout` on the next call.
+    /// Returns `true` while the underlying WebSocket and, for a flattened page
+    /// session, that specific target session are still alive.
     pub fn is_connected(&self) -> bool {
-        !self._reader_handle.is_finished()
+        self.transport.alive.load(Ordering::SeqCst)
+            && self
+                .session_alive
+                .as_ref()
+                .map(|alive| alive.load(Ordering::SeqCst))
+                .unwrap_or(true)
     }
 
-    /// Connect to the first available page on a debug port.
+    /// Connect to the first available page on a legacy debug port.
     pub async fn connect_to_first_page(port: u16) -> BitFunResult<Self> {
         let pages = Self::list_pages(port).await?;
         let page = pages
             .iter()
-            .find(|p| p.page_type.as_deref() == Some("page") && p.web_socket_debugger_url.is_some())
+            .find(|page| {
+                page.page_type.as_deref() == Some("page") && page.web_socket_debugger_url.is_some()
+            })
             .or_else(|| pages.first())
             .ok_or_else(|| BitFunError::tool("No browser pages found via CDP".to_string()))?;
 
@@ -118,33 +270,182 @@ impl CdpClient {
         Self::connect(ws_url).await
     }
 
+    /// Query version metadata from a browser-level CDP connection.
+    pub async fn browser_version(&self) -> BitFunResult<CdpVersionInfo> {
+        self.require_browser_connection()?;
+        let result = self.send("Browser.getVersion", None).await?;
+        Ok(CdpVersionInfo {
+            browser: result
+                .get("product")
+                .and_then(Value::as_str)
+                .map(str::to_string),
+            protocol_version: result
+                .get("protocolVersion")
+                .and_then(Value::as_str)
+                .map(str::to_string),
+            web_socket_debugger_url: None,
+        })
+    }
+
+    /// List targets through the browser WebSocket. This replaces `/json` for
+    /// an approval-only real-profile endpoint.
+    pub async fn browser_pages(&self) -> BitFunResult<Vec<CdpPageInfo>> {
+        self.require_browser_connection()?;
+        let result = self.send("Target.getTargets", None).await?;
+        Ok(Self::page_infos_from_target_result(&result))
+    }
+
+    /// Create a target through the browser WebSocket and return its metadata.
+    pub async fn create_browser_page(&self, url: Option<&str>) -> BitFunResult<CdpPageInfo> {
+        self.require_browser_connection()?;
+        let target_url = url.unwrap_or("about:blank");
+        let result = self
+            .send("Target.createTarget", Some(json!({ "url": target_url })))
+            .await?;
+        let target_id = result
+            .get("targetId")
+            .and_then(Value::as_str)
+            .ok_or_else(|| {
+                BitFunError::tool("Target.createTarget returned no target id".to_string())
+            })?
+            .to_string();
+
+        for _ in 0..10 {
+            if let Some(page) = self
+                .browser_pages()
+                .await?
+                .into_iter()
+                .find(|page| page.id == target_id)
+            {
+                return Ok(page);
+            }
+            tokio::time::sleep(Duration::from_millis(50)).await;
+        }
+
+        Ok(CdpPageInfo {
+            id: target_id,
+            title: String::new(),
+            url: target_url.to_string(),
+            web_socket_debugger_url: None,
+            page_type: Some("page".to_string()),
+        })
+    }
+
+    /// Attach to one target using a flattened CDP session carried over the
+    /// retained browser WebSocket. All subsequent page commands are tagged with
+    /// the returned `sessionId`, while events are routed to this client only.
+    pub async fn attach_to_page(&self, target_id: &str) -> BitFunResult<Self> {
+        self.require_browser_connection()?;
+        let result = self
+            .send(
+                "Target.attachToTarget",
+                Some(json!({ "targetId": target_id, "flatten": true })),
+            )
+            .await?;
+        let session_id = result
+            .get("sessionId")
+            .and_then(Value::as_str)
+            .ok_or_else(|| {
+                BitFunError::tool("Target.attachToTarget returned no session id".to_string())
+            })?
+            .to_string();
+
+        let (events_tx, _) = broadcast::channel::<CdpEvent>(256);
+        self.transport
+            .event_channels
+            .write()
+            .await
+            .insert(Some(session_id.clone()), events_tx.clone());
+        let session_alive = Arc::new(AtomicBool::new(true));
+        self.transport
+            .session_statuses
+            .write()
+            .await
+            .insert(session_id.clone(), Arc::downgrade(&session_alive));
+
+        Ok(Self {
+            transport: self.transport.clone(),
+            session_id: Some(session_id),
+            events: events_tx,
+            session_alive: Some(session_alive),
+        })
+    }
+
+    fn require_browser_connection(&self) -> BitFunResult<()> {
+        if self.session_id.is_some() {
+            return Err(BitFunError::tool(
+                "This CDP operation requires the browser-level connection".to_string(),
+            ));
+        }
+        Ok(())
+    }
+
+    fn page_infos_from_target_result(result: &Value) -> Vec<CdpPageInfo> {
+        result
+            .get("targetInfos")
+            .and_then(Value::as_array)
+            .into_iter()
+            .flatten()
+            .filter_map(|target| {
+                let id = target.get("targetId")?.as_str()?.to_string();
+                Some(CdpPageInfo {
+                    id,
+                    title: target
+                        .get("title")
+                        .and_then(Value::as_str)
+                        .unwrap_or_default()
+                        .to_string(),
+                    url: target
+                        .get("url")
+                        .and_then(Value::as_str)
+                        .unwrap_or_default()
+                        .to_string(),
+                    web_socket_debugger_url: None,
+                    page_type: target
+                        .get("type")
+                        .and_then(Value::as_str)
+                        .map(str::to_string),
+                })
+            })
+            .collect()
+    }
+
     /// Send a CDP method call and wait for the response.
     pub async fn send(&self, method: &str, params: Option<Value>) -> BitFunResult<Value> {
-        let id = self.next_id.fetch_add(1, Ordering::SeqCst);
-        let msg = json!({
+        let id = self.transport.next_id.fetch_add(1, Ordering::SeqCst);
+        let mut msg = json!({
             "id": id,
             "method": method,
             "params": params.unwrap_or(json!({})),
         });
+        if let Some(session_id) = &self.session_id {
+            msg["sessionId"] = json!(session_id);
+        }
 
         let (tx, rx) = tokio::sync::oneshot::channel();
-        {
-            let mut pending = self.pending.write().await;
-            pending.insert(id, tx);
-        }
+        self.transport.pending.write().await.insert(id, tx);
 
         debug!("CDP send id={} method={}", id, method);
-        {
-            let mut sink = self.sink.lock().await;
-            sink.send(Message::Text(msg.to_string().into()))
-                .await
-                .map_err(|e| BitFunError::tool(format!("CDP send failed: {}", e)))?;
+        let send_result = {
+            let mut sink = self.transport.sink.lock().await;
+            sink.send(Message::Text(msg.to_string().into())).await
+        };
+        if let Err(error) = send_result {
+            self.transport.pending.write().await.remove(&id);
+            return Err(BitFunError::tool(format!("CDP send failed: {}", error)));
         }
 
-        let result = tokio::time::timeout(std::time::Duration::from_secs(30), rx)
-            .await
-            .map_err(|_| BitFunError::tool(format!("CDP timeout for method {}", method)))?
-            .map_err(|_| BitFunError::tool("CDP response channel closed".to_string()))?;
+        let result = match tokio::time::timeout(Duration::from_secs(30), rx).await {
+            Ok(Ok(result)) => result,
+            Ok(Err(_)) => return Err(BitFunError::tool("CDP response channel closed".to_string())),
+            Err(_) => {
+                self.transport.pending.write().await.remove(&id);
+                return Err(BitFunError::tool(format!(
+                    "CDP timeout for method {}",
+                    method
+                )));
+            }
+        };
 
         if let Some(error) = result.get("error") {
             return Err(BitFunError::tool(format!("CDP error: {}", error)));
@@ -155,31 +456,56 @@ impl CdpClient {
 
     async fn reader_loop(
         mut stream: WsStream,
-        pending: Arc<RwLock<HashMap<i64, tokio::sync::oneshot::Sender<Value>>>>,
-        events: broadcast::Sender<CdpEvent>,
+        pending: PendingResponses,
+        event_channels: EventChannels,
+        session_statuses: SessionStatuses,
+        alive: Arc<AtomicBool>,
     ) {
         while let Some(msg_result) = stream.next().await {
             match msg_result {
                 Ok(Message::Text(text)) => {
-                    if let Ok(val) = serde_json::from_str::<Value>(&text) {
-                        if let Some(id) = val.get("id").and_then(|v| v.as_i64()) {
-                            let sender = {
-                                let mut pending = pending.write().await;
-                                pending.remove(&id)
-                            };
-                            if let Some(tx) = sender {
-                                let _ = tx.send(val);
+                    if let Ok(value) = serde_json::from_str::<Value>(&text) {
+                        if let Some(id) = value.get("id").and_then(Value::as_i64) {
+                            let sender = pending.write().await.remove(&id);
+                            if let Some(sender) = sender {
+                                let _ = sender.send(value);
                             }
-                        } else if let Some(method) = val
+                            continue;
+                        }
+
+                        let Some(method) = value
                             .get("method")
-                            .and_then(|v| v.as_str())
+                            .and_then(Value::as_str)
                             .map(str::to_string)
-                        {
-                            // Unsolicited CDP event — broadcast to subscribers
-                            // (no-op if nobody is listening). Used by
-                            // `BrowserActions::navigate` / `wait` to react
-                            // to `Page.lifecycleEvent` instead of polling.
-                            let params = val.get("params").cloned().unwrap_or(json!({}));
+                        else {
+                            continue;
+                        };
+                        let params = value.get("params").cloned().unwrap_or(json!({}));
+
+                        if method == "Target.detachedFromTarget" {
+                            if let Some(session_id) =
+                                params.get("sessionId").and_then(Value::as_str)
+                            {
+                                if let Some(status) = session_statuses
+                                    .write()
+                                    .await
+                                    .remove(session_id)
+                                    .and_then(|status| status.upgrade())
+                                {
+                                    status.store(false, Ordering::SeqCst);
+                                }
+                                event_channels
+                                    .write()
+                                    .await
+                                    .remove(&Some(session_id.to_string()));
+                            }
+                        }
+
+                        let route = value
+                            .get("sessionId")
+                            .and_then(Value::as_str)
+                            .map(str::to_string);
+                        if let Some(events) = event_channels.read().await.get(&route).cloned() {
                             let _ = events.send(CdpEvent { method, params });
                         }
                     }
@@ -188,18 +514,169 @@ impl CdpClient {
                     debug!("CDP WebSocket closed by server");
                     break;
                 }
-                Err(e) => {
-                    warn!("CDP WebSocket read error: {}", e);
+                Err(error) => {
+                    warn!("CDP WebSocket read error: {}", error);
                     break;
                 }
                 _ => {}
             }
         }
+
+        alive.store(false, Ordering::SeqCst);
+        pending.write().await.clear();
+        for status in session_statuses
+            .write()
+            .await
+            .drain()
+            .map(|(_, status)| status)
+        {
+            if let Some(status) = status.upgrade() {
+                status.store(false, Ordering::SeqCst);
+            }
+        }
     }
 }
 
-impl Drop for CdpClient {
-    fn drop(&mut self) {
-        self._reader_handle.abort();
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn browser_target_metadata_maps_to_page_info() {
+        let pages = CdpClient::page_infos_from_target_result(&json!({
+            "targetInfos": [
+                {
+                    "targetId": "page-1",
+                    "type": "page",
+                    "title": "Inbox",
+                    "url": "https://mail.example.test/"
+                },
+                {
+                    "targetId": "worker-1",
+                    "type": "service_worker",
+                    "title": "Service Worker",
+                    "url": "https://mail.example.test/sw.js"
+                }
+            ]
+        }));
+
+        assert_eq!(pages.len(), 2);
+        assert_eq!(pages[0].id, "page-1");
+        assert_eq!(pages[0].page_type.as_deref(), Some("page"));
+        assert_eq!(pages[0].web_socket_debugger_url, None);
+    }
+
+    #[tokio::test]
+    async fn browser_websocket_flattens_commands_and_routes_page_events() {
+        let listener = tokio::net::TcpListener::bind(("127.0.0.1", 0))
+            .await
+            .expect("bind mock CDP server");
+        let address = listener.local_addr().expect("mock CDP address");
+        let server = tokio::spawn(async move {
+            let (stream, _) = listener.accept().await.expect("accept CDP client");
+            let mut socket = tokio_tungstenite::accept_async(stream)
+                .await
+                .expect("accept WebSocket");
+
+            while let Some(message) = socket.next().await {
+                let Message::Text(text) = message.expect("read CDP command") else {
+                    continue;
+                };
+                let command: Value = serde_json::from_str(&text).expect("parse CDP command");
+                let id = command
+                    .get("id")
+                    .and_then(Value::as_i64)
+                    .expect("command id");
+                let method = command
+                    .get("method")
+                    .and_then(Value::as_str)
+                    .expect("command method");
+
+                let result = match method {
+                    "Browser.getVersion" => json!({
+                        "product": "Chrome/151.0.0.0",
+                        "protocolVersion": "1.3"
+                    }),
+                    "Target.getTargets" => json!({
+                        "targetInfos": [{
+                            "targetId": "page-1",
+                            "type": "page",
+                            "title": "Signed-in page",
+                            "url": "https://example.test/"
+                        }]
+                    }),
+                    "Target.attachToTarget" => {
+                        assert_eq!(command["params"]["targetId"], "page-1");
+                        assert_eq!(command["params"]["flatten"], true);
+                        json!({ "sessionId": "session-1" })
+                    }
+                    "Runtime.enable" => {
+                        assert_eq!(command["sessionId"], "session-1");
+                        socket
+                            .send(Message::Text(
+                                json!({
+                                    "method": "Runtime.consoleAPICalled",
+                                    "sessionId": "session-1",
+                                    "params": { "type": "log" }
+                                })
+                                .to_string()
+                                .into(),
+                            ))
+                            .await
+                            .expect("send flattened page event");
+                        json!({})
+                    }
+                    other => panic!("unexpected CDP command: {other}"),
+                };
+
+                socket
+                    .send(Message::Text(
+                        json!({ "id": id, "result": result }).to_string().into(),
+                    ))
+                    .await
+                    .expect("send CDP response");
+
+                if method == "Runtime.enable" {
+                    break;
+                }
+            }
+        });
+
+        let browser = CdpClient::connect(&format!("ws://{address}"))
+            .await
+            .expect("connect browser WebSocket");
+        assert_eq!(
+            browser
+                .browser_version()
+                .await
+                .expect("browser version")
+                .browser
+                .as_deref(),
+            Some("Chrome/151.0.0.0")
+        );
+        let pages = browser.browser_pages().await.expect("browser targets");
+        assert_eq!(pages.len(), 1);
+
+        let mut browser_events = browser.subscribe_events();
+        let page = browser
+            .attach_to_page(&pages[0].id)
+            .await
+            .expect("attach flattened page session");
+        let mut page_events = page.subscribe_events();
+        page.send("Runtime.enable", None)
+            .await
+            .expect("send flattened command");
+
+        let event = tokio::time::timeout(Duration::from_secs(1), page_events.recv())
+            .await
+            .expect("page event timeout")
+            .expect("page event");
+        assert_eq!(event.method, "Runtime.consoleAPICalled");
+        assert!(matches!(
+            browser_events.try_recv(),
+            Err(tokio::sync::broadcast::error::TryRecvError::Empty)
+        ));
+
+        server.await.expect("mock CDP server");
     }
 }
diff --git a/src/crates/assembly/core/src/agentic/tools/browser_control/mod.rs b/src/crates/assembly/core/src/agentic/tools/browser_control/mod.rs
index 596a5499c8..a20745e6a7 100644
--- a/src/crates/assembly/core/src/agentic/tools/browser_control/mod.rs
+++ b/src/crates/assembly/core/src/agentic/tools/browser_control/mod.rs
@@ -1,9 +1,10 @@
 //! Browser control via Chrome DevTools Protocol (CDP).
 //!
-//! Connects to the user's default browser (Chrome, Edge, etc.) over a
-//! CDP WebSocket, enabling page navigation, DOM interaction, screenshots,
-//! JS evaluation and more — all while preserving the user's existing
-//! cookies, extensions, and login sessions.
+//! Connects to a Chromium-family browser over CDP, enabling page navigation,
+//! DOM interaction, screenshots, JS evaluation and more. Chrome 144+ and Edge
+//! use user-approved live-profile endpoints so existing tabs, cookies,
+//! extensions and login sessions are preserved. Other Chromium browsers reuse
+//! a real-profile endpoint when available and retain a managed fallback.
 
 pub mod actions;
 pub mod browser_launcher;
diff --git a/src/crates/assembly/core/src/agentic/tools/computer_use_host.rs b/src/crates/assembly/core/src/agentic/tools/computer_use_host.rs
index 88b02c6496..8bf08aa447 100644
--- a/src/crates/assembly/core/src/agentic/tools/computer_use_host.rs
+++ b/src/crates/assembly/core/src/agentic/tools/computer_use_host.rs
@@ -210,6 +210,19 @@ pub trait ComputerUseHost: Send + Sync + std::fmt::Debug {
     /// is not blocked solely because of a prior click / scroll.
     fn computer_use_trust_pointer_after_text_input(&self) {}
 
+    /// Clear the stale-capture guard because it **cannot be satisfied** on this
+    /// run, not because the pointer became trustworthy.
+    ///
+    /// The guard exists to force a fresh look before a committing action. That
+    /// only means something for a model that can look. When the primary model
+    /// is text-only, `screenshot` returns no image and never reaches
+    /// `transition_after_screenshot`, so the guard latches on forever: the
+    /// error says "call `screenshot` first", the model calls `screenshot`,
+    /// nothing changes, and every `click` / Enter `key_chord` is refused for the
+    /// rest of the session. Text-only observation (`describe_screen`) is the
+    /// real equivalent of a capture there, so it waives the guard instead.
+    fn computer_use_waive_fresh_capture_guard(&self) {}
+
     /// Refuse `mouse_click` if the pointer moved (or a click happened) since the last screenshot,
     /// or if the latest capture is not a valid “fine” basis (desktop: ~500×500 point crop **or**
     /// quadrant navigation region with longest side < [`COMPUTER_USE_QUADRANT_CLICK_READY_MAX_LONG_EDGE`]).
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/analyze_image_tool.rs b/src/crates/assembly/core/src/agentic/tools/implementations/analyze_image_tool.rs
index dec2b96e91..518713fc59 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/analyze_image_tool.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/analyze_image_tool.rs
@@ -368,16 +368,48 @@ impl Tool for AnalyzeImageTool {
             .take(180)
             .collect::<String>();
 
-        let data = json!({
+        // Coordinate contract. Two separate traps live here:
+        //
+        // 1. `width`/`height` are the dimensions of the image **the model
+        //    saw**, which is often not the file's — large screenshots get
+        //    downscaled to fit the provider's limits. Reporting only those, as
+        //    this did, silently hands back numbers that do not describe the
+        //    file the caller passed in.
+        // 2. Any position or size in `analysis` is prose from a vision model:
+        //    estimated, not measured, and expressed in the resized frame. It is
+        //    not a click target, and treating it as one means compounding a
+        //    guess with a scale factor and (on Retina) a device-pixel ratio.
+        let mut data = json!({
             "path": resolved.display_path(),
             "model_id": vision_model.id,
             "model_name": vision_model.model_name,
             "mime_type": processed.mime_type,
             "width": processed.width,
             "height": processed.height,
+            "original_width": processed.original_width,
+            "original_height": processed.original_height,
+            "was_resized": processed.was_resized(),
             "summary": summary,
             "analysis": analysis,
+            "coordinate_note": "Any position or size mentioned in `analysis` is the vision model's estimate, in the frame of the image it was shown (`width`x`height`). It is not a measurement and not a click target. To act on something on screen, use `ComputerUse` `locate` / `move_to_text` / `describe_screen`, which return real coordinates.",
         });
+        if processed.was_resized() {
+            if let Some(obj) = data.as_object_mut() {
+                obj.insert("scale_from_original".to_string(), json!(processed.scale()));
+                obj.insert(
+                    "resize_note".to_string(),
+                    json!(format!(
+                        "The image was downscaled {}x{} -> {}x{} (x{:.4}) to fit the vision model. \
+Divide by that factor to map anything in `analysis` back to source pixels — but prefer not to: see `coordinate_note`.",
+                        processed.original_width,
+                        processed.original_height,
+                        processed.width,
+                        processed.height,
+                        processed.scale(),
+                    )),
+                );
+            }
+        }
 
         Ok(vec![ToolResult::ok(
             data,
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/computer_use_actions.rs b/src/crates/assembly/core/src/agentic/tools/implementations/computer_use_actions.rs
index f14275447a..263e2d2eab 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/computer_use_actions.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/computer_use_actions.rs
@@ -160,10 +160,10 @@ impl ComputerUseActions {
         )
         .with_hints([
             "If your target is NOT the browser: the guard only looks at the app this action would drive, so switch focus with `key_chord` [\"alt\",\"tab\"] / [\"command\",\"tab\"] (never guarded) or `open_app`, or skip focus entirely and pass an explicit non-browser `app` selector ({pid|bundle_id|name}, from `list_apps`) to `app_click` / `app_type_text` / `app_scroll` / `app_key_chord`",
-            "Page content: call ControlHub browser.connect first — it starts/attaches BitFun's managed browser profile with CDP enabled — then drive the page with snapshot/click/fill/press_key",
+            "Page content: call ControlHub browser.connect first — Chrome 144+ and Edge use a user-approved connection to the current real profile; other supported Chromium browsers reuse a real-profile endpoint when available and otherwise fall back to BitFun's persistent managed profile — then drive the page with snapshot/click/fill/press_key",
             "Browser chrome (address bar, tabs, back/forward, reload, downloads): use browser.navigate / tab_new / switch_page / back / forward / reload / close instead of mouse+keyboard",
             "File picker or <input type=file>: do NOT drive the native dialog — use browser.set_file_input_files { selector, files: [\"/abs/path\"] }. For JS alert/confirm/prompt use browser.dialog",
-            "For login/cookies/extensions keep using the CDP browser path; do not ask the user to enable a debug port on their everyday browser profile",
+            "For Chrome or Edge login/cookies/extensions, keep using the guarded CDP path; for one-time setup, ask the user to click Enable default CDP in BitFun Settings > Browser control, enable Remote debugging in the browser-owned page, and approve BitFun",
             "For isolated project Web UI testing, use the headless browser flow instead of desktop automation",
         ])
     }
@@ -427,8 +427,15 @@ impl ComputerUseActions {
                     host.key_chord(select_all).await?;
                 }
                 host.key_chord(paste_chord).await?;
+                // A paste lands in whatever already had focus and never moves
+                // the pointer, so it is not a reason to demand a fresh capture.
+                // This must run for *every* paste, not just `submit: true`:
+                // pasting and then sending a separate Enter `key_chord` is the
+                // common shape, and leaving the guard armed refuses that Enter
+                // with advice ("call `screenshot` first") that a text-only model
+                // cannot act on.
+                host.computer_use_trust_pointer_after_text_input();
                 if submit {
-                    host.computer_use_trust_pointer_after_text_input();
                     host.key_chord(submit_keys.clone()).await?;
                 }
 
@@ -542,9 +549,9 @@ impl ComputerUseActions {
     // ── Desktop AX-first dispatch (Codex parity) ──────────────────────
     // Routes the seven new app-targeted actions through the typed
     // `ComputerUseHost` API. Every successful response carries a
-    // unified envelope: `target_app`, `background_input`,
-    // `before_digest` and (for state queries) `app_state` /
-    // `app_state_nodes` so the model can reason about the AX tree
+    // unified envelope: `target_app`, `background_input`, `before_digest`
+    // and (for state queries) `app_state`, whose `tree_text` is the single
+    // rendering of the AX tree — so the model can reason about state
     // before/after each action without re-querying.
     async fn handle_desktop_ax(
         &self,
@@ -755,15 +762,34 @@ impl ComputerUseActions {
         // the heavy `screenshot` payload (it is attached out-of-band as a
         // multimodal image, not as base64 inside the JSON tree, to keep token
         // budgets under control and let the provider deliver it as `image_url`).
+        //
+        // `tree_text` is the **only** rendering of the AX tree we send. Results
+        // used to carry a sibling `app_state_nodes` array holding the same
+        // nodes as verbose JSON — one object per node, ~15 lines each. It was
+        // strictly redundant (`render_tree_text` already emits idx, role,
+        // title, value, identifier, description, help, url, frame and the
+        // enabled/focused/selected/expanded flags, with parentage implied by
+        // indentation) and nothing consumed it, yet it accounted for ~78% of a
+        // `get_app_state` result: a single observation of a windowless app
+        // measured 107 KB, of which 82 KB was that duplicate.
         fn snap_state_json(
             snap: &crate::agentic::tools::computer_use_host::AppStateSnapshot,
         ) -> serde_json::Value {
+            // Bounded here rather than at the `get_app_state` call site: every
+            // `app_click` / `app_type_text` / `app_scroll` / `app_key_chord` /
+            // `app_wait_for` result carries this same post-action tree, so they
+            // all shared the same unbounded-payload risk.
+            let tree_text = super::computer_use_tool::clip_tree_text(
+                snap.tree_text.clone(),
+                super::computer_use_tool::APP_STATE_TREE_TEXT_MAX_BYTES,
+            );
             let mut v = json!({
                 "app": snap.app,
                 "window_title": snap.window_title,
                 "digest": snap.digest,
                 "captured_at_ms": snap.captured_at_ms,
-                "tree_text": snap.tree_text,
+                "tree_text": tree_text,
+                "node_count": snap.nodes.len(),
                 "has_screenshot": snap.screenshot.is_some(),
             });
             if let Some(shot) = snap.screenshot.as_ref() {
@@ -904,7 +930,6 @@ impl ComputerUseActions {
             let mut v = json!({
                 "target_app": app,
                 "app_state": snap_state_json(&res.snapshot),
-                "app_state_nodes": res.snapshot.nodes,
                 "loop_warning": res.snapshot.loop_warning,
                 "execution_note": res.execution_note,
                 "interactive_view": res.view.as_ref().map(build_interactive_view_json),
@@ -925,7 +950,6 @@ impl ComputerUseActions {
             let mut v = json!({
                 "target_app": app,
                 "app_state": snap_state_json(&res.snapshot),
-                "app_state_nodes": res.snapshot.nodes,
                 "loop_warning": res.snapshot.loop_warning,
                 "execution_note": res.execution_note,
                 "visual_mark_view": res.view.as_ref().map(build_visual_mark_view_json),
@@ -1069,7 +1093,6 @@ impl ComputerUseActions {
                     "background_input": bg,
                     "ax_tree": ax,
                     "app_state": snap_state_json(&snap),
-                    "app_state_nodes": snap.nodes,
                     "before_digest": snap.digest,
                     "loop_warning": snap.loop_warning,
                 });
@@ -1164,7 +1187,6 @@ impl ComputerUseActions {
                     "background_input": bg,
                     "before_digest": before,
                     "app_state": snap_state_json(&after),
-                    "app_state_nodes": after.nodes,
                     "loop_warning": after.loop_warning,
                 });
                 Ok(vec![snap_result(data, Some("clicked".to_string()), &after)])
@@ -1212,7 +1234,6 @@ impl ComputerUseActions {
                     "focus": focus,
                     "before_digest": before,
                     "app_state": snap_state_json(&after),
-                    "app_state_nodes": after.nodes,
                     "loop_warning": after.loop_warning,
                 });
                 Ok(vec![snap_result(
@@ -1237,7 +1258,6 @@ impl ComputerUseActions {
                     "dy": dy,
                     "focus": focus,
                     "app_state": snap_state_json(&after),
-                    "app_state_nodes": after.nodes,
                     "loop_warning": after.loop_warning,
                 });
                 Ok(vec![snap_result(
@@ -1268,7 +1288,6 @@ impl ComputerUseActions {
                     "keys": keys,
                     "focus_idx": focus_idx,
                     "app_state": snap_state_json(&after),
-                    "app_state_nodes": after.nodes,
                     "loop_warning": after.loop_warning,
                 });
                 Ok(vec![snap_result(
@@ -1302,7 +1321,6 @@ impl ComputerUseActions {
                     "background_input": bg,
                     "predicate": predicate,
                     "app_state": snap_state_json(&after),
-                    "app_state_nodes": after.nodes,
                     "loop_warning": after.loop_warning,
                 });
                 Ok(vec![snap_result(
@@ -2008,12 +2026,14 @@ mod tests {
 
     /// The rejection must lead somewhere: a non-browser escape route, the
     /// ControlHub actions that own browser chrome / file pickers / dialogs, and
-    /// no contradiction with `browser.connect`'s "never ask for a debug port".
+    /// no contradiction with `browser.connect`'s guarded approval flow.
     #[test]
     fn browser_guard_hints_offer_an_executable_way_out() {
         let error = ComputerUseActions::desktop_browser_guard_error("click", None);
         assert!(
-            error.message.contains("not because your task is browser-related"),
+            error
+                .message
+                .contains("not because your task is browser-related"),
             "{}",
             error.message
         );
@@ -2026,7 +2046,7 @@ mod tests {
         assert!(hints.contains("app_click"), "{hints}");
         assert!(
             !hints.contains("test port enabled") && !hints.contains("--remote-debugging-port"),
-            "must not contradict browser.connect's managed-profile rule: {hints}"
+            "must not teach the unsafe legacy default-profile debug-port flow: {hints}"
         );
     }
 
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/computer_use_tool.rs b/src/crates/assembly/core/src/agentic/tools/implementations/computer_use_tool.rs
index cf9ce31d5f..3af01d8740 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/computer_use_tool.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/computer_use_tool.rs
@@ -119,6 +119,85 @@ const COMPUTER_USE_DEBUG_SCREENSHOTS_ENV: &str = "BITFUN_COMPUTER_USE_DEBUG_SCRE
 /// Newest debug screenshots retained in [`COMPUTER_USE_DEBUG_SUBDIR`]; older files are deleted.
 const COMPUTER_USE_DEBUG_MAX_FILES: usize = 20;
 
+/// AX depth `describe_screen` walks into the focused window.
+///
+/// This was 8, which is fine for a native Cocoa app but far too shallow for
+/// Electron / WebView clients — the ones agents are most often asked to drive.
+/// Measured against a real Electron window (focused window only):
+///
+/// | depth | nodes | actionable | tree_text |
+/// |------:|------:|-----------:|----------:|
+/// |     8 |    17 |          7 |      1 KB |
+/// |    12 |    25 |         15 |      2 KB |
+/// |    16 |    50 |         40 |      5 KB |
+/// |    20 |   207 |        197 |     27 KB |
+/// |    24 |   233 |        223 |     31 KB |
+/// |    32 |  1289 |       1279 |    206 KB |
+///
+/// At 8 the agent could see seven actionable elements in an entire app — not
+/// enough to find a search field or a send button, which reads as "this app has
+/// no AX tree" and pushes it onto OCR or screenshot guessing. The actionable
+/// layer appears around 20; past that the payload grows far faster than the
+/// number of things worth clicking.
+const DESCRIBE_SCREEN_AX_DEPTH: u32 = 20;
+
+/// Byte ceiling on the AX tree `describe_screen` returns.
+///
+/// The depth above is tuned against a typical rich window (~27 KB), but depth
+/// is a poor proxy for size: a document, a long list or a deeply nested canvas
+/// can multiply that. `describe_screen` is the action an agent calls most, so
+/// it needs a bound that does not depend on the app behaving reasonably.
+const DESCRIBE_SCREEN_TREE_TEXT_MAX_BYTES: usize = 60_000;
+
+/// Byte ceiling on the AX tree carried by `get_app_state` and every `app_*`
+/// action result.
+///
+/// Higher than the `describe_screen` cap because these are explicit requests
+/// for an app's tree rather than a routine observation — but still a ceiling.
+/// Measured unbounded output on a real Electron app was 390 KB from a single
+/// `get_app_state`, roughly 100k tokens, which is most of a context window
+/// spent on one look at one app.
+pub(crate) const APP_STATE_TREE_TEXT_MAX_BYTES: usize = 120_000;
+
+/// A routine observation must never be allowed a bigger tree than an explicit
+/// query for one. Checked at compile time so reordering the two constants is a
+/// build error rather than something a test has to notice.
+const _: () = assert!(DESCRIBE_SCREEN_TREE_TEXT_MAX_BYTES < APP_STATE_TREE_TEXT_MAX_BYTES);
+
+/// Trim an AX tree to `max_bytes` on a line boundary, appending a note that
+/// says what was dropped and how to get it.
+///
+/// Silent truncation would be worse than the problem it solves: the agent would
+/// read a partial tree as the whole UI and conclude a control does not exist.
+pub(crate) fn clip_tree_text(text: String, max_bytes: usize) -> String {
+    if text.len() <= max_bytes {
+        return text;
+    }
+    // Walk back to a char boundary before slicing. The cap is a byte count, and
+    // slicing a `str` at a byte index inside a multi-byte character panics —
+    // which CJK app trees (the ones most likely to be large) would hit
+    // constantly.
+    let mut end = max_bytes;
+    while end > 0 && !text.is_char_boundary(end) {
+        end -= 1;
+    }
+    // A newline is single-byte, so its index is always a valid boundary too.
+    let cut = text[..end].rfind('\n').unwrap_or(end);
+    let kept_lines = text[..cut].lines().count();
+    let total_lines = text.lines().count();
+    format!(
+        "{}\n[truncated] showing the first {} of {} AX nodes ({} of {} bytes). \
+This is a size limit, not the end of the UI — a control you cannot find here may still exist. \
+Narrow the view with `get_app_state` (`focus_window_only`, a smaller `max_depth`) or target it \
+directly with `locate` / `move_to_text`.\n",
+        &text[..cut],
+        kept_lines,
+        total_lines,
+        cut,
+        text.len(),
+    )
+}
+
 pub struct ComputerUseTool;
 
 impl Default for ComputerUseTool {
@@ -446,7 +525,14 @@ The **primary model cannot consume images** in tool results — **do not** use *
     async fn describe_screen(
         host: &dyn ComputerUseHost,
         _input: &Value,
+        text_only: bool,
     ) -> BitFunResult<Vec<ToolResult>> {
+        // For a text-only model this *is* the observation step, so it clears
+        // the same guard a `screenshot` would. Without this the guard can only
+        // ever be cleared by a capture the model cannot consume.
+        if text_only {
+            host.computer_use_waive_fresh_capture_guard();
+        }
         let session_snap = host.computer_use_session_snapshot().await;
         let interaction = host.computer_use_interaction_state();
         let pointer = session_snap.pointer_global.clone();
@@ -469,24 +555,66 @@ The **primary model cannot consume images** in tool results — **do not** use *
         let mut ax_nodes_count: Option<usize> = None;
         let mut ax_digest: Option<String> = None;
         let mut window_title: Option<String> = None;
-        if let Some(app) = selector.as_ref() {
-            match host.get_app_state(app.clone(), 8, true).await {
+        // Why `ax_tree_text` is empty, when it is. A bare `null` here reads as
+        // truncated tool output, and an agent that believes its own results are
+        // being cut off will keep re-issuing the same call instead of switching
+        // tactic — which is exactly what a null `ax_tree_text` used to cause.
+        let ax_tree_status: &str = match selector.as_ref() {
+            None => "no_foreground_app",
+            Some(app) => match host
+                .get_app_state(app.clone(), DESCRIBE_SCREEN_AX_DEPTH, true)
+                .await
+            {
                 Ok(snap) => {
                     // Deliberately drop `snap.screenshot` (JPEG) — describe_screen
                     // never returns image bytes so text-only models are safe.
                     window_title = snap.window_title.clone();
                     ax_nodes_count = Some(snap.nodes.len());
                     ax_digest = Some(snap.digest.clone());
-                    ax_tree_text = Some(snap.tree_text).filter(|t| !t.trim().is_empty());
+                    ax_tree_text = Some(clip_tree_text(
+                        snap.tree_text,
+                        DESCRIBE_SCREEN_TREE_TEXT_MAX_BYTES,
+                    ))
+                    .filter(|t| !t.trim().is_empty());
+                    if ax_tree_text.is_some() {
+                        "ok"
+                    } else {
+                        "empty_tree"
+                    }
                 }
                 Err(e) => {
                     debug!("describe_screen: get_app_state failed: {}", e);
+                    "query_failed"
                 }
-            }
-        }
+            },
+        };
 
         let ui_tree_text = host.enumerate_ui_tree_text().await;
 
+        // Turn each non-`ok` status into the tactic that actually works there,
+        // so a sparse tree costs one redirect instead of a search.
+        let ax_tree_note = match ax_tree_status {
+            "ok" => None,
+            "no_foreground_app" => Some(
+                "No application is frontmost, so there is no AX tree to read. Use `list_apps` to \
+find the target, then `open_app` (or `app_click` with an explicit `app` selector) to bring it forward."
+                    .to_string(),
+            ),
+            "empty_tree" => Some(
+                "The frontmost app exposes an empty accessibility tree — usual for Electron / \
+WebView apps that have not enabled their web-content AX tree, and for an app running with no \
+window. This is NOT truncated output: re-calling `describe_screen` returns the same thing. \
+Check `window_count` via `open_app`, or target visible text with `move_to_text` / `click_target`."
+                    .to_string(),
+            ),
+            "query_failed" => Some(
+                "The AX query failed (commonly missing Accessibility trust, or the app exited). \
+Grant Accessibility permission, or fall back to `move_to_text` / `click_target` on visible text."
+                    .to_string(),
+            ),
+            _ => None,
+        };
+
         let mut body = json!({
             "success": true,
             "action": "describe_screen",
@@ -496,9 +624,12 @@ The **primary model cannot consume images** in tool results — **do not** use *
             "displays": displays,
             "window_title": window_title,
             "ax_tree_text": ax_tree_text,
+            "ax_tree_status": ax_tree_status,
+            "ax_tree_note": ax_tree_note,
             "ax_nodes_count": ax_nodes_count,
             "ax_state_digest": ax_digest,
             "ui_tree_text": ui_tree_text,
+            "output_is_complete": true,
         });
 
         let input_coords = json!({
@@ -510,8 +641,18 @@ The **primary model cannot consume images** in tool results — **do not** use *
         // pick `node_idx` from `ax_tree_text` for `app_click`/`click_element`, or
         // match visible text via `move_to_text`, and compare `ax_state_digest`
         // before/after an action to verify a mutation.
-        let hint = "describe_screen: text snapshot returned (no image). Use `ax_tree_text` node indices for `app_click`/`click_element`, match visible text with `move_to_text`, and compare `ax_state_digest` across actions to verify state changes.";
-        Ok(vec![ToolResult::ok(body, Some(hint.to_string()))])
+        let hint = format!(
+            "describe_screen: complete text snapshot returned (no image, ax_tree_status={}). \
+Use `ax_tree_text` node indices for `app_click`/`click_element`, match visible text with `move_to_text`, \
+and compare `ax_state_digest` across actions to verify state changes.{}",
+            ax_tree_status,
+            if ax_tree_status == "ok" {
+                ""
+            } else {
+                " No AX tree available — read `ax_tree_note` and switch tactic rather than repeating this call."
+            }
+        );
+        Ok(vec![ToolResult::ok(body, Some(hint))])
     }
 
     /// Screenshot tool results attach JPEGs via `tool_image_attachments`; only providers whose
@@ -1216,7 +1357,8 @@ impl Tool for ComputerUseTool {
             // + pointer + displays) with NO image bytes. This is the observe and
             // verify step that closes the cowork loop for text-only models.
             "describe_screen" => {
-                return Self::describe_screen(host_ref, input).await;
+                let text_only = !context.primary_model_supports_image_understanding();
+                return Self::describe_screen(host_ref, input, text_only).await;
             }
 
             // Unified target resolver: AX first, OCR second, explicit screen
@@ -1715,12 +1857,19 @@ impl Tool for ComputerUseTool {
                 // at the text-only observe action. The model keeps its turn and
                 // switches to `describe_screen` / AX / OCR / keyboard tactics.
                 if !context.primary_model_supports_image_understanding() {
+                    // A text-only `screenshot` never captures anything, so it
+                    // can never clear the stale-capture guard the usual way.
+                    // Waive it here: otherwise the guard's own recovery advice
+                    // ("call `screenshot` first") is an instruction the model
+                    // can follow forever without ever being allowed to click.
+                    host_ref.computer_use_waive_fresh_capture_guard();
                     let body = json!({
                         "success": true,
                         "action": "screenshot",
                         "screenshot_unavailable": true,
                         "reason": "primary_model_is_text_only",
-                        "instruction": "The primary model cannot consume image bytes, so `screenshot` produced nothing. Use `describe_screen` to observe the desktop as text (frontmost app + AX tree + UI tree text + pointer), then act with `click_target`/`click_element`/`move_to_text`/`key_chord`/`paste`. Never retry `screenshot`."
+                        "stale_capture_guard": "waived",
+                        "instruction": "The primary model cannot consume image bytes, so `screenshot` produced nothing. Use `describe_screen` to observe the desktop as text (frontmost app + AX tree + UI tree text + pointer), then act with `click_target`/`click_element`/`move_to_text`/`key_chord`/`paste`. Never retry `screenshot`. The fresh-capture guard has been waived, so `click` and Enter `key_chord` are unblocked."
                     });
                     let input_coords = json!({ "kind": "screenshot", "text_only": true });
                     let body =
@@ -1937,6 +2086,25 @@ impl Tool for ComputerUseTool {
                         BitFunError::tool("open_app requires `app_name` parameter.".to_string())
                     })?;
                 let result = host_ref.open_app(app_name).await?;
+                // A live process with zero windows is the one launch outcome
+                // that looks like success but leaves nothing to act on. Name it
+                // explicitly and say what to do, rather than letting the agent
+                // rediscover it through a chain of failing AX queries.
+                let windowless = result.success && result.window_count == Some(0);
+                let next_step = if windowless {
+                    Some(format!(
+                        "'{}' is running (PID {}) but owns no window, so there is nothing on screen to click. \
+The host already retried via `open -b`. Re-run `open_app`, or ask the user to open the app's main window (e.g. from its Dock icon). \
+Do not fall back to screen-coordinate clicks — there is no window to hit.",
+                        result.app_name,
+                        result
+                            .process_id
+                            .map(|p| p.to_string())
+                            .unwrap_or_else(|| "?".to_string()),
+                    ))
+                } else {
+                    None
+                };
                 let body = computer_use_augment_result_json(
                     host_ref,
                     json!({
@@ -1945,13 +2113,28 @@ impl Tool for ComputerUseTool {
                         "app_name": result.app_name,
                         "process_id": result.process_id,
                         "error_message": result.error_message,
+                        // Address the app by `bundle_id` from here on: the name
+                        // used to launch it, its executable name and its bundle
+                        // id are often three different strings.
+                        "bundle_id": result.bundle_id,
+                        "process_name": result.process_name,
+                        "window_count": result.window_count,
+                        "launch_path": result.launch_path,
+                        "windowless": windowless,
+                        "next_step": next_step,
                     }),
                     None,
                 )
                 .await;
-                let summary = if result.success {
+                let summary = if !result.success {
+                    format!(
+                        "Failed to open '{}': {}",
+                        result.app_name,
+                        result.error_message.as_deref().unwrap_or("unknown error")
+                    )
+                } else if windowless {
                     format!(
-                        "Opened app '{}'{}.",
+                        "Opened '{}'{} but it has NO window — nothing is on screen to act on.",
                         result.app_name,
                         result
                             .process_id
@@ -1960,9 +2143,16 @@ impl Tool for ComputerUseTool {
                     )
                 } else {
                     format!(
-                        "Failed to open '{}': {}",
+                        "Opened app '{}'{}{}.",
                         result.app_name,
-                        result.error_message.as_deref().unwrap_or("unknown error")
+                        result
+                            .process_id
+                            .map(|p| format!(" (PID {})", p))
+                            .unwrap_or_default(),
+                        result
+                            .window_count
+                            .map(|n| format!(", {} window(s)", n))
+                            .unwrap_or_default()
                     )
                 };
                 Ok(vec![ToolResult::ok(body, Some(summary))])
@@ -2074,7 +2264,10 @@ fn req_i32(input: &Value, key: &str) -> BitFunResult<i32> {
 
 #[cfg(test)]
 mod tests {
-    use super::ComputerUseTool;
+    use super::{
+        clip_tree_text, ComputerUseTool, APP_STATE_TREE_TEXT_MAX_BYTES,
+        DESCRIBE_SCREEN_TREE_TEXT_MAX_BYTES,
+    };
     use crate::agentic::tools::computer_use_host::{
         ComputerScreenshot, ComputerUseForegroundApplication, ComputerUseHost,
         ComputerUsePermissionSnapshot, ComputerUseScreenshotParams, ComputerUseSessionSnapshot,
@@ -2360,6 +2553,265 @@ mod tests {
         }
     }
 
+    /// Host that records whether the stale-capture guard was waived, and
+    /// reports no frontmost app so `describe_screen` exercises its
+    /// nothing-to-observe branch.
+    #[derive(Debug, Default)]
+    struct GuardRecordingHost {
+        waived: std::sync::atomic::AtomicBool,
+    }
+
+    #[async_trait::async_trait]
+    impl ComputerUseHost for GuardRecordingHost {
+        async fn permission_snapshot(&self) -> BitFunResult<ComputerUsePermissionSnapshot> {
+            not_expected()
+        }
+        async fn request_accessibility_permission(&self) -> BitFunResult<()> {
+            not_expected()
+        }
+        async fn request_screen_capture_permission(&self) -> BitFunResult<()> {
+            not_expected()
+        }
+        async fn screenshot_display(
+            &self,
+            _params: ComputerUseScreenshotParams,
+        ) -> BitFunResult<ComputerScreenshot> {
+            not_expected()
+        }
+        fn map_image_coords_to_pointer(&self, _x: i32, _y: i32) -> BitFunResult<(i32, i32)> {
+            not_expected()
+        }
+        fn map_normalized_coords_to_pointer(&self, _x: i32, _y: i32) -> BitFunResult<(i32, i32)> {
+            not_expected()
+        }
+        async fn mouse_move(&self, _x: i32, _y: i32) -> BitFunResult<()> {
+            not_expected()
+        }
+        async fn pointer_move_relative(&self, _dx: i32, _dy: i32) -> BitFunResult<()> {
+            not_expected()
+        }
+        async fn mouse_click(&self, _button: &str) -> BitFunResult<()> {
+            not_expected()
+        }
+        async fn scroll(&self, _delta_x: i32, _delta_y: i32) -> BitFunResult<()> {
+            not_expected()
+        }
+        async fn key_chord(&self, _keys: Vec<String>) -> BitFunResult<()> {
+            not_expected()
+        }
+        async fn type_text(&self, _text: &str) -> BitFunResult<()> {
+            not_expected()
+        }
+        async fn wait_ms(&self, _ms: u64) -> BitFunResult<()> {
+            not_expected()
+        }
+        async fn computer_use_session_snapshot(&self) -> ComputerUseSessionSnapshot {
+            ComputerUseSessionSnapshot::default()
+        }
+        fn computer_use_waive_fresh_capture_guard(&self) {
+            self.waived.store(true, std::sync::atomic::Ordering::SeqCst);
+        }
+    }
+
+    fn text_only_context(
+        host: std::sync::Arc<GuardRecordingHost>,
+    ) -> (ToolUseContext, std::sync::Arc<GuardRecordingHost>) {
+        let mut context = ToolUseContext::for_tool_listing(None, None);
+        context.primary_model_facts =
+            tool_runtime::context::PrimaryModelFacts::new("m", "m", "anthropic", false);
+        context.computer_use_host = Some(host.clone());
+        (context, host)
+    }
+
+    /// A text-only `screenshot` captures nothing, so it can never clear the
+    /// stale-capture guard through the normal path — yet the guard's own error
+    /// tells the model to "call `screenshot` first". Left as it was, that is a
+    /// closed loop: every `click` and Enter `key_chord` stays refused for the
+    /// rest of the session, and the only way out is to bypass the tool entirely
+    /// (the observed failure was an agent falling back to raw
+    /// `osascript … keystroke return`, which skips every safety check the guard
+    /// exists to enforce).
+    #[tokio::test]
+    async fn text_only_screenshot_waives_the_unsatisfiable_capture_guard() {
+        let (context, host) = text_only_context(std::sync::Arc::new(GuardRecordingHost::default()));
+        let results = ComputerUseTool::new()
+            .call_impl(&json!({ "action": "screenshot" }), &context)
+            .await
+            .expect("text-only screenshot returns a soft envelope");
+        assert!(
+            host.waived.load(std::sync::atomic::Ordering::SeqCst),
+            "text-only screenshot must waive the guard it can never satisfy"
+        );
+        let body = results[0].content();
+        assert_eq!(
+            body.get("stale_capture_guard").and_then(Value::as_str),
+            Some("waived"),
+            "the waiver must be visible to the model: {body}"
+        );
+        // The guard's own error text says "call `screenshot` first"; the
+        // instruction here has to say that path is now open, or the model has
+        // no reason to believe retrying the click will work.
+        let instruction = body
+            .get("instruction")
+            .and_then(Value::as_str)
+            .unwrap_or_default();
+        assert!(
+            instruction.contains("waived"),
+            "instruction must tell the model the guard is cleared: {instruction}"
+        );
+    }
+
+    /// `describe_screen` is the text-only equivalent of taking a look, so it
+    /// clears the same guard a capture would.
+    #[tokio::test]
+    async fn text_only_describe_screen_waives_the_capture_guard() {
+        let (context, host) = text_only_context(std::sync::Arc::new(GuardRecordingHost::default()));
+        let _ = ComputerUseTool::new()
+            .call_impl(&json!({ "action": "describe_screen" }), &context)
+            .await
+            .expect("describe_screen should succeed");
+        assert!(
+            host.waived.load(std::sync::atomic::Ordering::SeqCst),
+            "describe_screen is the text-only observation step and must waive the guard"
+        );
+    }
+
+    #[test]
+    fn tree_text_under_the_cap_is_returned_verbatim() {
+        let small = "[0] AXApplication\n  [1] AXWindow\n".to_string();
+        assert_eq!(
+            clip_tree_text(small.clone(), DESCRIBE_SCREEN_TREE_TEXT_MAX_BYTES),
+            small
+        );
+    }
+
+    /// Both caps must actually bound the payload. `get_app_state` is allowed a
+    /// larger tree than a routine `describe_screen` because it is an explicit
+    /// request for one, but "larger" is not "unbounded" — an uncapped
+    /// `get_app_state` measured 390 KB on a real Electron app, roughly 100k
+    /// tokens for a single look.
+    #[test]
+    fn both_ax_tree_caps_bound_the_payload() {
+        let line = "[0] AXButton title=\"x\" frame=(0,0,10x10)\n";
+        let huge = line.repeat(APP_STATE_TREE_TEXT_MAX_BYTES / line.len() + 5_000);
+        for cap in [
+            DESCRIBE_SCREEN_TREE_TEXT_MAX_BYTES,
+            APP_STATE_TREE_TEXT_MAX_BYTES,
+        ] {
+            let out = clip_tree_text(huge.clone(), cap);
+            assert!(out.contains("[truncated]"), "cap={cap}");
+            let body = out.split("\n[truncated]").next().unwrap();
+            assert!(
+                body.len() <= cap,
+                "cap={cap} but kept {} bytes of tree",
+                body.len()
+            );
+        }
+    }
+
+    /// Truncation must announce itself. An agent that reads a clipped tree as
+    /// the whole UI concludes a control does not exist and gives up on it.
+    #[test]
+    fn oversized_tree_text_is_clipped_on_a_line_boundary_and_says_so() {
+        let line = "[0] AXButton title=\"x\" frame=(0,0,10x10)\n";
+        let big = line.repeat(DESCRIBE_SCREEN_TREE_TEXT_MAX_BYTES / line.len() + 500);
+        let out = clip_tree_text(big.clone(), DESCRIBE_SCREEN_TREE_TEXT_MAX_BYTES);
+
+        assert!(out.len() < big.len(), "must actually shrink");
+        assert!(
+            out.contains("[truncated]"),
+            "must announce the clip: {out:.200}"
+        );
+        assert!(
+            out.contains("not the end of the UI"),
+            "must warn that a missing control may still exist"
+        );
+        // Cutting mid-line would hand the model a malformed node.
+        let body = out.split("\n[truncated]").next().unwrap();
+        assert!(
+            body.lines()
+                .all(|l| l.is_empty() || l.starts_with("[0] AXButton")),
+            "clip must land on a line boundary"
+        );
+    }
+
+    /// The cap is a byte count but the tree is a `str`, so the clip has to land
+    /// on a char boundary. A CJK app — exactly the kind whose tree gets large —
+    /// would otherwise panic the whole tool call on a mid-character slice.
+    #[test]
+    fn oversized_cjk_tree_text_clips_without_panicking() {
+        for label in ["范明裕", "飞书 · 消息", "🙂 emoji", "混合 mixed 内容"] {
+            let line = format!("[0] AXStaticText title=\"{label}\"\n");
+            let big = line.repeat(DESCRIBE_SCREEN_TREE_TEXT_MAX_BYTES / line.len() + 500);
+            assert!(big.len() > DESCRIBE_SCREEN_TREE_TEXT_MAX_BYTES);
+
+            let out = clip_tree_text(big.clone(), DESCRIBE_SCREEN_TREE_TEXT_MAX_BYTES);
+            assert!(out.contains("[truncated]"), "must announce the clip");
+            assert!(out.len() < big.len(), "must actually shrink");
+        }
+    }
+
+    /// The cut offset must be safe for *every* alignment, not the one a given
+    /// repeated line happens to produce.
+    ///
+    /// Shifting the content by one and two bytes is what makes this bite: a
+    /// 3-byte character misaligns against the byte cap at two of every three
+    /// offsets, and only those two panic. An unshifted string of `范` lands
+    /// exactly on 60_000 and sails through a completely broken implementation —
+    /// which is how the first version of this test passed without the fix.
+    #[test]
+    fn clip_lands_on_a_char_boundary_at_every_alignment() {
+        for pad in 0..3 {
+            // No newline anywhere, so the cut falls back to the boundary walk
+            // rather than being rescued by `rfind('\n')`.
+            let mut s = "a".repeat(pad);
+            s.push_str(&"范".repeat(DESCRIBE_SCREEN_TREE_TEXT_MAX_BYTES / 3 + 10));
+            assert!(s.len() > DESCRIBE_SCREEN_TREE_TEXT_MAX_BYTES);
+
+            let out = clip_tree_text(s.clone(), DESCRIBE_SCREEN_TREE_TEXT_MAX_BYTES);
+            assert!(out.contains("[truncated]"), "pad={pad}");
+            let body = out.split("\n[truncated]").next().unwrap();
+            assert!(
+                body.chars().all(|c| c == 'a' || c == '范'),
+                "clip split a character at pad={pad}"
+            );
+        }
+    }
+
+    /// An empty snapshot must say *why* it is empty. A bare `ax_tree_text:
+    /// null` reads as truncated tool output, and an agent that believes its
+    /// results are being cut off re-issues the same call instead of changing
+    /// tactic.
+    #[tokio::test]
+    async fn describe_screen_explains_an_empty_ax_tree_instead_of_returning_bare_nulls() {
+        let (context, _host) =
+            text_only_context(std::sync::Arc::new(GuardRecordingHost::default()));
+        let results = ComputerUseTool::new()
+            .call_impl(&json!({ "action": "describe_screen" }), &context)
+            .await
+            .expect("describe_screen should succeed");
+        let body = results[0].content();
+        let data = body.get("data").unwrap_or(&body);
+        assert_eq!(
+            data.get("ax_tree_status").and_then(Value::as_str),
+            Some("no_foreground_app"),
+            "status must name the reason the tree is empty: {body}"
+        );
+        assert_eq!(
+            data.get("output_is_complete").and_then(Value::as_bool),
+            Some(true),
+            "result must assert it is not truncated: {body}"
+        );
+        let note = data
+            .get("ax_tree_note")
+            .and_then(Value::as_str)
+            .unwrap_or_default();
+        assert!(
+            note.contains("list_apps") || note.contains("open_app"),
+            "note must offer a concrete next action: {note}"
+        );
+    }
+
     /// The browser-boundary guard must be reachable from `call_impl`: a
     /// physical input action while a Chromium-family browser is frontmost is
     /// rejected with the ControlHub browser-domain redirect instead of
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/control_hub_tool.rs b/src/crates/assembly/core/src/agentic/tools/implementations/control_hub_tool.rs
index 87735daa69..7f3132c58a 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/control_hub_tool.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/control_hub_tool.rs
@@ -8,11 +8,11 @@
 //! Local desktop and OS/system actions are intentionally surfaced through the
 //! dedicated ComputerUse tool/agent, not through public ControlHub domains.
 
-use crate::agentic::tools::browser_control::actions::BrowserActions;
+use crate::agentic::tools::browser_control::actions::{BrowserActions, MAX_WAIT_MS};
 use crate::agentic::tools::browser_control::browser_launcher::{
     BrowserKind, BrowserLauncher, LaunchResult, DEFAULT_CDP_PORT,
 };
-use crate::agentic::tools::browser_control::cdp_client::{CdpClient, CdpVersionInfo};
+use crate::agentic::tools::browser_control::cdp_client::{CdpClient, CdpPageInfo, CdpVersionInfo};
 use crate::agentic::tools::browser_control::session_registry::{
     BrowserSession, BrowserSessionRegistry, BrowserSessionState, DialogHandler,
 };
@@ -41,10 +41,10 @@ static BROWSER_SESSIONS: std::sync::OnceLock<Arc<BrowserSessionRegistry>> =
 const OPEN_BUILT_IN_BROWSER_EVENT: &str = "agentic://open-built-in-browser";
 
 /// `connect { mode: "headless" }` only attaches, it never launches. It must
-/// therefore not default to the port the `default` mode's managed browser
-/// occupies: otherwise a session that already ran `connect { mode: "default" }`
-/// can never reach a headless browser, because `verify_headless_cdp_browser`
-/// hard-rejects the headed browser sitting on that port.
+/// therefore not default to the logical port used by the `default` mode:
+/// otherwise a session that already connected the user's browser can never
+/// reach a headless browser, because `verify_headless_cdp_browser` hard-rejects
+/// the headed browser sitting on that port.
 const DEFAULT_HEADLESS_CDP_PORT: u16 = DEFAULT_CDP_PORT + 1;
 
 /// Computer Use is an independent switch from browser control (`ai.computer_use_enabled`
@@ -80,15 +80,75 @@ impl ControlHubTool {
     }
 
     fn default_browser_connect_hints(kind: &BrowserKind, port: u16) -> Vec<String> {
-        let exe = BrowserLauncher::browser_executable(kind);
-        vec![
-            "Drive pages over CDP rather than desktop mouse/keyboard automation. Note this is BitFun's managed browser profile, not the user's everyday profile: it keeps its own cookies and logins across runs, so on a login wall ask the user to sign in once in that window instead of retrying or typing credentials.".to_string(),
-            format!(
-                "If CDP is not ready on test port {}, retry browser.connect — it starts \"{}\" against BitFun's managed profile with CDP enabled. Do not ask the user to enable a debug port on their everyday browser profile.",
-                port, exe
-            ),
-            "After the browser is listening on the test port, use browser.connect / snapshot / click / fill to drive the DOM directly.".to_string(),
-        ]
+        match kind {
+            BrowserKind::Chrome | BrowserKind::Edge => {
+                let setup_url = if matches!(kind, BrowserKind::Chrome) {
+                    "chrome://inspect/#remote-debugging"
+                } else {
+                    "edge://inspect/#remote-debugging"
+                };
+                vec![
+                    format!(
+                        "{} can connect BitFun to the current real profile, preserving its open tabs, cookies, extensions, and login state.",
+                        kind
+                    ),
+                    format!(
+                        "For one-time setup, ask the user to click Enable default CDP in BitFun Settings > Browser control. BitFun opens {}; enable Remote debugging there (the browser remembers this for normal future starts), then approve BitFun's connection dialog in {}.",
+                        setup_url, kind
+                    ),
+                    "After approval, keep using browser.connect / snapshot / click / fill; BitFun retains one guarded browser connection to avoid repeated prompts.".to_string(),
+                ]
+            }
+            _ => {
+                let exe = BrowserLauncher::browser_executable(kind);
+                vec![
+                    format!(
+                        "If {} already publishes DevToolsActivePort from its normal user-data directory, BitFun reuses that real profile automatically; otherwise it starts a persistent managed profile.",
+                        kind
+                    ),
+                    format!(
+                        "If CDP is not ready on test port {}, retry browser.connect — it starts \"{}\" with BitFun's managed profile.",
+                        port, exe
+                    ),
+                    "After the browser is listening, use browser.connect / snapshot / click / fill to drive the DOM directly.".to_string(),
+                ]
+            }
+        }
+    }
+
+    async fn browser_version(port: u16) -> BitFunResult<CdpVersionInfo> {
+        if let Some(connection) = CdpClient::browser_connection(port).await {
+            connection.client.browser_version().await
+        } else {
+            CdpClient::get_version(port).await
+        }
+    }
+
+    async fn browser_pages(port: u16) -> BitFunResult<Vec<CdpPageInfo>> {
+        if let Some(connection) = CdpClient::browser_connection(port).await {
+            connection.client.browser_pages().await
+        } else {
+            CdpClient::list_pages(port).await
+        }
+    }
+
+    async fn create_browser_page(port: u16, url: Option<&str>) -> BitFunResult<CdpPageInfo> {
+        if let Some(connection) = CdpClient::browser_connection(port).await {
+            connection.client.create_browser_page(url).await
+        } else {
+            CdpClient::create_page(port, url).await
+        }
+    }
+
+    async fn connect_page(port: u16, page: &CdpPageInfo) -> BitFunResult<CdpClient> {
+        if let Some(connection) = CdpClient::browser_connection(port).await {
+            connection.client.attach_to_page(&page.id).await
+        } else {
+            let ws_url = page.web_socket_debugger_url.as_ref().ok_or_else(|| {
+                BitFunError::tool("Page has no WebSocket debugger URL".to_string())
+            })?;
+            CdpClient::connect(ws_url).await
+        }
     }
 
     fn headless_browser_connect_hints(port: u16) -> Vec<String> {
@@ -134,7 +194,11 @@ impl ControlHubTool {
         if browser.to_ascii_lowercase().contains("headless") {
             return Ok(());
         }
-        let reported = if browser.is_empty() { "unknown" } else { browser };
+        let reported = if browser.is_empty() {
+            "unknown"
+        } else {
+            browser
+        };
         Err(ControlHubError::new(
             ErrorCode::NotAvailable,
             format!(
@@ -144,7 +208,7 @@ impl ControlHubTool {
         )
         .with_hints(Self::headless_browser_connect_hints(port))
         .with_hint(
-            "Use connect { mode: \"default\" } to drive the BitFun-managed browser profile instead.",
+            "Use connect { mode: \"default\" } for the user-approved current Chrome or Edge profile, or the compatible managed-profile fallback instead.",
         ))
     }
 
@@ -198,11 +262,16 @@ Use this tool via `{ domain, action, params }` for browser automation, terminal
   * Do not call `connect`, `tab_new`, or `navigate` merely to display a URL. Use the CDP workflow only when the agent must read page content or interact with the DOM.
 - UI action:
   * `open_builtin { url, title?, replace_existing? }` — open an http(s) URL in BitFun's built-in right-side browser panel. This changes the BitFun UI only; it does not fetch page text for reasoning. The panel is display-only for the user — the agent cannot snapshot, read, or interact with it; use `connect` + `snapshot` when page content is needed.
-- Automation modes (external managed browser):
-  * `connect { mode: "default" }` (default) — start or attach BitFun's managed browser profile with CDP enabled on port 9222.
+- Automation modes (external browser):
+  * `connect { mode: "default" }` (default) — on Chrome 144+ and current Edge, request a user-approved connection to the currently running real profile so existing tabs and login state are preserved. Other supported Chromium browsers also reuse the real profile when it publishes DevToolsActivePort; otherwise BitFun starts or attaches its persistent managed profile on port 9222.
   * `connect { mode: "headless" }` — attach to an already-running headless browser on the headless test port 9223. This mode never starts a browser; when nothing is listening it returns `NOT_AVAILABLE` together with the exact launch command.
   * `params.port` overrides the CDP port for `connect` and for every other CDP action; after `connect`, actions reuse the connected session's port automatically.
 - Actions: open_builtin, connect, tab_new, navigate, back, forward, reload, snapshot, click, hover, fill, type, check, uncheck, select, press_key, scroll, auto_scroll, wait, get, get_text, get_url, get_title, get_html, screenshot, evaluate, fetch, cookies, set_cookies, set_file_input_files, cdp, network, console, errors, trace, dialog, read_article, close, list_pages, tab_query, switch_page, list_sessions.
+- Pausing:
+  * `wait { duration_ms }` — pause for a fixed time, up to 60 minutes (`ms` and `seconds` are accepted spellings). This is the action to use when you must idle between rounds of work, e.g. `{ "duration_ms": 1800000 }` to resume in 30 minutes. It needs no browser session, and the result reports the `ms` actually waited, so check that figure before assuming the full pause happened.
+  * `wait { condition, timeout_ms? }` — wait on the page instead: 'load' | 'domcontentloaded' | 'networkidle' | a CSS/@ref selector, bounded by `timeout_ms` (default 15s). Requires a connected session. When a `condition` is present it always wins, and any duration you pass becomes its timeout rather than a separate sleep.
+  * A `wait` carrying neither is rejected with `INVALID_PARAMS` — it never silently returns.
+  * `wait` holds the turn open for its whole duration, so it suits a one-off pause, not a schedule. For work that should repeat ("produce another round every 30 minutes") or resume more than an hour out, create a job with the `Cron` tool instead, then **end your turn** — creating the job does not end it for you. The job re-invokes you when it fires, so a turn left running is idling with the context loaded and only delays the next round. Every built-in mode that has ControlHub also has `Cron`; if it is genuinely absent from your tool list, say so rather than substituting a chain of long `wait` calls.
 - Automation workflow: connect -> navigate -> snapshot (returns @e1, @e2 ... refs) -> click/fill with `{ "selector": "@e1" }` (the key `ref` is accepted too).
 - Take a fresh snapshot after any DOM mutation; a stale `@eN` ref returns `error.code = STALE_REF`, while a selector that matches nothing returns `NOT_FOUND`.
 
@@ -402,8 +471,8 @@ Branch on `ok` and `error.code`, not on English messages.
                 // The value of a capability probe is entirely in the field
                 // values, so the assistant-visible text must be the payload
                 // itself — a one-line summary tells the model nothing.
-                let assistant = serde_json::to_string_pretty(&body)
-                    .unwrap_or_else(|_| body.to_string());
+                let assistant =
+                    serde_json::to_string_pretty(&body).unwrap_or_else(|_| body.to_string());
                 Ok(vec![ToolResult::ok(body, Some(assistant))])
             }
             "route_hint" => {
@@ -425,13 +494,14 @@ Branch on `ok` and `error.code`, not on English messages.
                 // otherwise send an unroutable request.
                 let mut suggestions: Vec<(&'static str, Option<&'static str>, u32, &'static str)> =
                     vec![];
-                let push = |s: &mut Vec<(&'static str, Option<&'static str>, u32, &'static str)>,
-                            domain: &'static str,
-                            tool: Option<&'static str>,
-                            score: u32,
-                            why: &'static str| {
-                    s.push((domain, tool, score, why));
-                };
+                let push =
+                    |s: &mut Vec<(&'static str, Option<&'static str>, u32, &'static str)>,
+                     domain: &'static str,
+                     tool: Option<&'static str>,
+                     score: u32,
+                     why: &'static str| {
+                        s.push((domain, tool, score, why));
+                    };
 
                 let browser_kw = [
                     "http",
@@ -617,12 +687,100 @@ Branch on `ok` and `error.code`, not on English messages.
         )
     }
 
+    /// Sleep for `requested_ms`, interruptibly.
+    ///
+    /// The sleep races the turn's cancellation token: a 30-minute pace wait
+    /// that ignored it would leave the user unable to stop the agent for half
+    /// an hour. Cancellation surfaces as `BitFunError::Cancelled`, which the
+    /// pipeline already records as a terminal cancelled state rather than a
+    /// tool failure.
+    async fn wait_for_duration(
+        requested_ms: u64,
+        context: &ToolUseContext,
+    ) -> BitFunResult<Vec<ToolResult>> {
+        let waited_ms = requested_ms.min(MAX_WAIT_MS);
+        let sleep = tokio::time::sleep(std::time::Duration::from_millis(waited_ms));
+
+        if let Some(token) = context.cancellation_token() {
+            tokio::select! {
+                _ = sleep => {}
+                _ = token.cancelled() => {
+                    return Err(BitFunError::Cancelled(format!(
+                        "browser.wait cancelled before the {} pause elapsed",
+                        format_duration_ms(waited_ms)
+                    )));
+                }
+            }
+        } else {
+            sleep.await;
+        }
+
+        let (data, summary) = Self::wait_outcome(requested_ms);
+        Ok(vec![ToolResult::ok(data, Some(summary))])
+    }
+
+    /// Describe a completed duration wait.
+    ///
+    /// The old payload carried no duration at all, so a wait that returned
+    /// instantly was indistinguishable from one that ran to completion; both
+    /// printed "Wait completed". State the elapsed time, and say plainly when
+    /// the request was clamped instead of quietly waiting less than asked.
+    fn wait_outcome(requested_ms: u64) -> (Value, String) {
+        let waited_ms = requested_ms.min(MAX_WAIT_MS);
+        let clamped = waited_ms != requested_ms;
+        let summary = if clamped {
+            format!(
+                "Waited {} (requested {} — clamped to the {} maximum)",
+                format_duration_ms(waited_ms),
+                format_duration_ms(requested_ms),
+                format_duration_ms(MAX_WAIT_MS)
+            )
+        } else {
+            format!("Waited {}", format_duration_ms(waited_ms))
+        };
+        (
+            json!({
+                "success": true,
+                "action": "wait",
+                "ms": waited_ms,
+                "requested_ms": requested_ms,
+                "clamped": clamped,
+            }),
+            summary,
+        )
+    }
+
     async fn handle_browser(
         &self,
         action: &str,
         params: &Value,
         context: &ToolUseContext,
     ) -> BitFunResult<Vec<ToolResult>> {
+        // A duration wait is a pure pause: it touches no page, so it must not
+        // require (or even resolve) a CDP session — agents pace themselves with
+        // this long before they open a browser. Condition waits fall through to
+        // the session-backed path below, where any duration the caller also
+        // passed becomes the condition's timeout rather than a separate sleep.
+        if action == "wait" && wait_condition(params).is_none() {
+            if let Some(requested_ms) = wait_duration_ms(params) {
+                return Self::wait_for_duration(requested_ms, context).await;
+            }
+            return Ok(err_response(
+                "browser",
+                "wait",
+                ControlHubError::new(
+                    ErrorCode::InvalidParams,
+                    "browser.wait requires either a duration or a `condition`.",
+                )
+                .with_hint(
+                    "To pause, pass `duration_ms` (alias `ms`), e.g. { \"duration_ms\": 1800000 } for 30 minutes.",
+                )
+                .with_hint(
+                    "To wait on the page, pass `condition`: 'load' | 'domcontentloaded' | 'networkidle' | a CSS/@ref selector.",
+                ),
+            ));
+        }
+
         let session_id_param = params
             .get("session_id")
             .and_then(|v| v.as_str())
@@ -738,10 +896,71 @@ Branch on `ok` and `error.code`, not on English messages.
                 let user_data_dir = params.get("user_data_dir").and_then(|v| v.as_str());
                 let launch_result = if mode == "headless" {
                     LaunchResult::AlreadyConnected
+                } else if user_data_dir.is_none()
+                    && CdpClient::browser_connection_for_kind(port, &kind)
+                        .await
+                        .is_some()
+                {
+                    LaunchResult::AlreadyConnected
                 } else {
+                    // Every browser shares the same logical tool port. When
+                    // the selection or explicit profile changes, stop routing
+                    // new actions through the previously retained browser.
+                    if CdpClient::browser_connection(port).await.is_some() {
+                        CdpClient::remove_browser_connection(port).await;
+                    }
                     BrowserLauncher::launch_with_cdp_opts(&kind, port, user_data_dir).await?
                 };
 
+                let uses_user_profile = match &launch_result {
+                    LaunchResult::UserProfileReady { endpoint } => {
+                        if let Err(error) = CdpClient::connect_user_profile_browser(
+                            port,
+                            endpoint.port,
+                            &kind,
+                            &endpoint.web_socket_url,
+                        )
+                        .await
+                        {
+                            return Ok(err_response(
+                                "browser",
+                                "connect",
+                                ControlHubError::new(
+                                    ErrorCode::NotAvailable,
+                                    format!(
+                                        "{} did not approve the connection to the current profile, or the approval request timed out.",
+                                        kind
+                                    ),
+                                )
+                                .with_hint(error.to_string())
+                                .with_hints(Self::default_browser_connect_hints(&kind, port)),
+                            ));
+                        }
+                        true
+                    }
+                    LaunchResult::UserProfileSetupRequired {
+                        setup_url,
+                        instructions,
+                        ..
+                    } => {
+                        return Ok(err_response(
+                            "browser",
+                            "connect",
+                            ControlHubError::new(
+                                ErrorCode::NotAvailable,
+                                format!(
+                                    "{} needs one-time setup before BitFun can use the current logged-in profile.",
+                                    kind
+                                ),
+                            )
+                            .with_hint(instructions)
+                            .with_hint(format!("{} setup page: {setup_url}", kind))
+                            .with_hints(Self::default_browser_connect_hints(&kind, port)),
+                        ));
+                    }
+                    _ => CdpClient::browser_connection(port).await.is_some(),
+                };
+
                 // UX shortcut: a frequent flow is "drive my Gmail tab" /
                 // "drive the GitHub PR I'm looking at". Without `target_*`
                 // the model needed `connect` → `list_pages` → `switch_page`
@@ -764,14 +983,16 @@ Branch on `ok` and `error.code`, not on English messages.
                     .unwrap_or(true);
 
                 match &launch_result {
-                    LaunchResult::AlreadyConnected | LaunchResult::Launched => {
-                        let version = CdpClient::get_version(port).await?;
+                    LaunchResult::AlreadyConnected
+                    | LaunchResult::Launched
+                    | LaunchResult::UserProfileReady { .. } => {
+                        let version = Self::browser_version(port).await?;
                         if mode == "headless" {
                             if let Err(error) = Self::verify_headless_cdp_browser(&version, port) {
                                 return Ok(err_response("browser", "connect", error));
                             }
                         }
-                        let pages = CdpClient::list_pages(port).await?;
+                        let pages = Self::browser_pages(port).await?;
                         let connected_browser = if mode == "headless" {
                             "Headless test browser".to_string()
                         } else {
@@ -781,7 +1002,7 @@ Branch on `ok` and `error.code`, not on English messages.
                         // Selection: explicit target_* > first real page > first.
                         let matched_by_target = if target_url.is_some() || target_title.is_some() {
                             pages.iter().find(|p| {
-                                if p.web_socket_debugger_url.is_none() {
+                                if !uses_user_profile && p.web_socket_debugger_url.is_none() {
                                     return false;
                                 }
                                 let url_ok = target_url
@@ -825,17 +1046,15 @@ Branch on `ok` and `error.code`, not on English messages.
                             .or_else(|| {
                                 pages.iter().find(|p| {
                                     p.page_type.as_deref() == Some("page")
-                                        && p.web_socket_debugger_url.is_some()
+                                        && (uses_user_profile
+                                            || p.web_socket_debugger_url.is_some())
                                 })
                             })
                             .or_else(|| pages.first())
                             .ok_or_else(|| {
                                 BitFunError::tool("No browser pages found via CDP".to_string())
                             })?;
-                        let ws_url = page.web_socket_debugger_url.as_ref().ok_or_else(|| {
-                            BitFunError::tool("Page has no WebSocket debugger URL".to_string())
-                        })?;
-                        let client = CdpClient::connect(ws_url).await?;
+                        let client = Self::connect_page(port, page).await?;
                         let session = BrowserSession {
                             session_id: page.id.clone(),
                             port,
@@ -874,6 +1093,7 @@ Branch on `ok` and `error.code`, not on English messages.
                             "success": true,
                             "browser": connected_browser,
                             "browser_mode": mode,
+                            "browser_profile": if uses_user_profile { "current_user" } else { "managed" },
                             "browser_version": version.browser,
                             "port": port,
                             "session_id": session.session_id,
@@ -883,6 +1103,8 @@ Branch on `ok` and `error.code`, not on English messages.
                             "activated": activated,
                             "status": if mode == "headless" {
                                 "attached"
+                            } else if uses_user_profile {
+                                "connected_user_profile"
                             } else if matches!(launch_result, LaunchResult::AlreadyConnected) {
                                 "already_connected"
                             } else {
@@ -892,7 +1114,12 @@ Branch on `ok` and `error.code`, not on English messages.
                         if let Some(w) = activate_warning {
                             result["warning"] = json!(w);
                         }
-                        let summary = if targeted {
+                        let summary = if uses_user_profile {
+                            format!(
+                                "Connected to the current {} profile via user-approved DOM/CDP (session {}, page '{}')",
+                                connected_browser, session.session_id, page.title
+                            )
+                        } else if targeted {
                             format!(
                                 "Connected to {} via DOM/CDP (session {}, page '{}')",
                                 connected_browser, session.session_id, page.title
@@ -905,6 +1132,24 @@ Branch on `ok` and `error.code`, not on English messages.
                         };
                         Ok(vec![ToolResult::ok(result, Some(summary))])
                     }
+                    LaunchResult::UserProfileSetupRequired {
+                        setup_url,
+                        instructions,
+                        ..
+                    } => Ok(err_response(
+                        "browser",
+                        "connect",
+                        ControlHubError::new(
+                            ErrorCode::NotAvailable,
+                            format!(
+                                "{} needs one-time setup before BitFun can use the current logged-in profile.",
+                                kind
+                            ),
+                        )
+                        .with_hint(instructions)
+                        .with_hint(format!("{} setup page: {setup_url}", kind))
+                        .with_hints(Self::default_browser_connect_hints(&kind, port)),
+                    )),
                     LaunchResult::LaunchedButCdpNotReady { message, .. } => Ok(err_response(
                         "browser",
                         "connect",
@@ -925,7 +1170,7 @@ Branch on `ok` and `error.code`, not on English messages.
             }
 
             "list_pages" => {
-                let pages = CdpClient::list_pages(port).await?;
+                let pages = Self::browser_pages(port).await?;
                 let default_id = browser_sessions().default_id().await;
                 let summary: Vec<Value> = pages
                     .iter()
@@ -976,7 +1221,7 @@ Branch on `ok` and `error.code`, not on English messages.
                     .unwrap_or(20)
                     .max(1);
 
-                let pages = CdpClient::list_pages(port).await?;
+                let pages = Self::browser_pages(port).await?;
                 let default_id = browser_sessions().default_id().await;
                 let total = pages.len();
                 let filtered: Vec<Value> = pages
@@ -1031,12 +1276,8 @@ Branch on `ok` and `error.code`, not on English messages.
                     .get("activate")
                     .and_then(|v| v.as_bool())
                     .unwrap_or(true);
-                let page = CdpClient::create_page(port, url).await?;
-                let ws_url = page
-                    .web_socket_debugger_url
-                    .as_ref()
-                    .ok_or_else(|| BitFunError::tool("New tab has no WebSocket URL".to_string()))?;
-                let client = CdpClient::connect(ws_url).await?;
+                let page = Self::create_browser_page(port, url).await?;
+                let client = Self::connect_page(port, &page).await?;
                 let session = BrowserSession {
                     session_id: page.id.clone(),
                     port,
@@ -1089,14 +1330,11 @@ Branch on `ok` and `error.code`, not on English messages.
                     reused = true;
                     registry.get(Some(page_id)).await?
                 } else {
-                    let pages = CdpClient::list_pages(port).await?;
+                    let pages = Self::browser_pages(port).await?;
                     let page = pages.iter().find(|p| p.id == page_id).ok_or_else(|| {
                         BitFunError::tool(format!("Page '{}' not found", page_id))
                     })?;
-                    let ws_url = page.web_socket_debugger_url.as_ref().ok_or_else(|| {
-                        BitFunError::tool("Page has no WebSocket URL".to_string())
-                    })?;
-                    let client = CdpClient::connect(ws_url).await?;
+                    let client = Self::connect_page(port, page).await?;
                     let session = BrowserSession {
                         session_id: page.id.clone(),
                         port,
@@ -1497,10 +1735,23 @@ Branch on `ok` and `error.code`, not on English messages.
                         )])
                     }
                     "wait" => {
-                        let ms = params.get("duration_ms").and_then(|v| v.as_u64());
-                        let cond = params.get("condition").and_then(|v| v.as_str());
-                        let result = actions.wait(ms, cond).await?;
-                        Ok(vec![ToolResult::ok(result, Some("Wait completed".to_string()))])
+                        // Duration waits already returned from the session-free
+                        // path in `handle_browser`; only condition waits, which
+                        // genuinely need the page, reach here. A duration passed
+                        // alongside the condition bounds it instead of being
+                        // dropped.
+                        let cond = wait_condition(params);
+                        let result = actions
+                            .wait(None, cond, wait_condition_timeout_ms(params))
+                            .await?;
+                        let summary = match result.get("timed_out").and_then(|v| v.as_bool()) {
+                            Some(true) => format!(
+                                "Timed out waiting for '{}'",
+                                cond.unwrap_or("condition")
+                            ),
+                            _ => format!("Waited for '{}'", cond.unwrap_or("condition")),
+                        };
+                        Ok(vec![ToolResult::ok(result, Some(summary))])
                     }
                     "get_text" => {
                         let selector = match selector_param(params) {
@@ -2271,6 +2522,11 @@ impl Tool for ControlHubTool {
         // Wrap legacy handler results into the unified envelope.
         match dispatched {
             Ok(results) => Ok(envelope_wrap_results(domain, action, results)),
+            // Cancellation is the pipeline's own terminal state, not a tool
+            // failure. Folding it into an `ok: false` envelope would both hide
+            // the user's stop from the pipeline and invite the model to
+            // "recover" from a turn that is already being torn down.
+            Err(err @ BitFunError::Cancelled(_)) => Err(err),
             Err(err) => Ok(err_response(
                 domain,
                 action,
@@ -2326,6 +2582,94 @@ fn selector_param(params: &Value) -> Option<&str> {
         .filter(|selector| !selector.is_empty())
 }
 
+/// A duration parameter, in milliseconds, under any of `keys`.
+///
+/// A model that writes `"1800000"` as a string still means 1_800_000 ms, and
+/// one that writes `1.5` seconds means 1500 ms.
+fn duration_param_ms(params: &Value, keys: &[&str], unit_ms: f64) -> Option<u64> {
+    keys.iter()
+        .find_map(|key| {
+            let value = params.get(*key)?;
+            value
+                .as_f64()
+                .or_else(|| value.as_str()?.trim().parse::<f64>().ok())
+                .filter(|n| n.is_finite() && *n >= 0.0)
+        })
+        .map(|n| (n * unit_ms).round() as u64)
+}
+
+/// Read a `wait` pause duration out of `params`, in milliseconds.
+///
+/// The action used to read `duration_ms` and nothing else, so the very
+/// plausible `{ "ms": 1800000 }` was dropped on the floor and the call
+/// returned instantly while still reporting success. Accept the obvious
+/// spellings instead — a wait that silently does not wait is far worse than a
+/// slightly wide parameter surface. Millisecond keys are checked before second
+/// keys so a call carrying both cannot be read in the wrong unit.
+///
+/// A `condition` always wins: next to one, every duration key reads as "wait
+/// for this, but no longer than" rather than as a pause, so this returns
+/// `None` and [`wait_condition_timeout_ms`] takes the value instead. Sleeping
+/// on `{ condition, timeout_ms }` would never look at the page at all.
+fn wait_duration_ms(params: &Value) -> Option<u64> {
+    const MS_KEYS: [&str; 5] = ["duration_ms", "ms", "wait_ms", "sleep_ms", "timeout_ms"];
+    const SECOND_KEYS: [&str; 6] = [
+        "duration_seconds",
+        "duration_s",
+        "seconds",
+        "secs",
+        "sleep_seconds",
+        "wait_seconds",
+    ];
+
+    if wait_condition(params).is_some() {
+        return None;
+    }
+    duration_param_ms(params, &MS_KEYS, 1.0)
+        .or_else(|| duration_param_ms(params, &SECOND_KEYS, 1_000.0))
+}
+
+/// The `condition` a `wait` should watch for, if the caller named a usable one.
+fn wait_condition(params: &Value) -> Option<&str> {
+    params
+        .get("condition")
+        .and_then(|v| v.as_str())
+        .map(str::trim)
+        .filter(|cond| !cond.is_empty())
+}
+
+/// Read the bound on a `wait { condition }` — how long to keep waiting for the
+/// page before giving up.
+fn wait_condition_timeout_ms(params: &Value) -> Option<u64> {
+    duration_param_ms(
+        params,
+        &["condition_timeout_ms", "timeout_ms", "duration_ms", "ms"],
+        1.0,
+    )
+    .or_else(|| duration_param_ms(params, &["timeout_seconds", "seconds"], 1_000.0))
+}
+
+/// Render a wait duration the way a person would say it, so the tool summary
+/// reads as "Waited 30m" rather than "Wait completed" — the latter is exactly
+/// what a zero-length wait used to print.
+fn format_duration_ms(ms: u64) -> String {
+    let total_secs = ms / 1_000;
+    let (hours, minutes, seconds) = (
+        total_secs / 3_600,
+        (total_secs % 3_600) / 60,
+        total_secs % 60,
+    );
+    if hours > 0 {
+        format!("{hours}h{minutes:02}m")
+    } else if minutes > 0 {
+        format!("{minutes}m{seconds:02}s")
+    } else if total_secs > 0 {
+        format!("{total_secs}s")
+    } else {
+        format!("{ms}ms")
+    }
+}
+
 /// An `@eN` ref that no longer resolves means the snapshot it came from is
 /// stale, which the model recovers from by re-snapshotting; a CSS selector
 /// that matches nothing is simply not found.
@@ -2509,7 +2853,10 @@ mod control_hub_tests {
             .unwrap_or_default();
         assert!(msg.contains("Unknown domain"), "got: {msg}");
         for d in ["browser", "terminal", "meta"] {
-            assert!(msg.contains(d), "valid domain {d} missing from error: {msg}");
+            assert!(
+                msg.contains(d),
+                "valid domain {d} missing from error: {msg}"
+            );
         }
         // ComputerUse is a separate tool, not a ControlHub domain — listing it
         // as one sent models chasing a domain that never existed.
@@ -2519,6 +2866,182 @@ mod control_hub_tests {
         );
     }
 
+    #[test]
+    fn wait_duration_accepts_the_spellings_models_actually_emit() {
+        // `ms` is what the model reached for in the field; reading only
+        // `duration_ms` dropped it and turned a 30-minute pause into a no-op.
+        for key in ["duration_ms", "ms", "wait_ms", "sleep_ms"] {
+            assert_eq!(
+                wait_duration_ms(&json!({ key: 1_800_000u64 })),
+                Some(1_800_000),
+                "millisecond key {key} must be honoured"
+            );
+        }
+        for key in [
+            "duration_seconds",
+            "duration_s",
+            "seconds",
+            "secs",
+            "sleep_seconds",
+            "wait_seconds",
+        ] {
+            assert_eq!(
+                wait_duration_ms(&json!({ key: 90 })),
+                Some(90_000),
+                "second key {key} must be converted to milliseconds"
+            );
+        }
+        assert_eq!(wait_duration_ms(&json!({ "ms": "1500" })), Some(1_500));
+        assert_eq!(wait_duration_ms(&json!({ "seconds": 1.5 })), Some(1_500));
+        // Both units present: milliseconds win, so the wait can never be read
+        // a thousand times too short.
+        assert_eq!(
+            wait_duration_ms(&json!({ "seconds": 5, "duration_ms": 1_800_000u64 })),
+            Some(1_800_000)
+        );
+        assert_eq!(wait_duration_ms(&json!({ "condition": "load" })), None);
+        assert_eq!(wait_duration_ms(&json!({ "ms": -5 })), None);
+        assert_eq!(wait_duration_ms(&json!({ "ms": "soon" })), None);
+        // On its own `timeout_ms` can only mean the pause itself.
+        assert_eq!(
+            wait_duration_ms(&json!({ "timeout_ms": 5_000 })),
+            Some(5_000)
+        );
+    }
+
+    #[test]
+    fn a_condition_wait_keeps_its_timeout_instead_of_becoming_a_sleep() {
+        // `{ condition, timeout_ms }` means "wait for this, but no longer
+        // than". Reading `timeout_ms` as a pause would sleep and never look at
+        // the page at all.
+        let params = json!({ "condition": "networkidle", "timeout_ms": 30_000 });
+        assert_eq!(wait_duration_ms(&params), None);
+        assert_eq!(wait_condition_timeout_ms(&params), Some(30_000));
+
+        // A duration passed next to a condition bounds it rather than being
+        // dropped on the floor.
+        let params = json!({ "condition": "#done", "duration_ms": 45_000 });
+        assert_eq!(wait_duration_ms(&params), None);
+        assert_eq!(wait_condition_timeout_ms(&params), Some(45_000));
+
+        // Nothing given: the action falls back to its own default.
+        assert_eq!(
+            wait_condition_timeout_ms(&json!({ "condition": "load" })),
+            None
+        );
+        assert_eq!(
+            wait_condition_timeout_ms(&json!({ "condition": "load", "timeout_seconds": 20 })),
+            Some(20_000)
+        );
+    }
+
+    #[tokio::test]
+    async fn browser_wait_actually_sleeps_and_reports_the_elapsed_time() {
+        let tool = ControlHubTool::new();
+        let ctx = empty_context();
+        let started = std::time::Instant::now();
+        let results = tool
+            // No browser session exists in this test: a duration wait must not
+            // need one.
+            .dispatch("browser", "wait", &json!({ "ms": 250 }), &ctx)
+            .await
+            .expect("duration wait should succeed");
+        assert!(
+            started.elapsed() >= std::time::Duration::from_millis(240),
+            "wait returned after only {:?}",
+            started.elapsed()
+        );
+        // `dispatch` returns the raw handler payload; `call_impl` is what adds
+        // the `{ ok, domain, action, data }` envelope.
+        let data = results.first().expect("one result").content();
+        assert_eq!(data.get("ms").and_then(|v| v.as_u64()), Some(250));
+        assert_eq!(data.get("clamped").and_then(|v| v.as_bool()), Some(false));
+        assert_eq!(data.get("success").and_then(|v| v.as_bool()), Some(true));
+    }
+
+    #[test]
+    fn browser_wait_clamps_absurd_durations_and_says_so() {
+        // Asserted on the reporting helper rather than through `dispatch`, so
+        // the test does not have to sit through the wait itself.
+        let (data, summary) = ControlHubTool::wait_outcome(MAX_WAIT_MS * 3);
+        assert_eq!(data.get("ms").and_then(|v| v.as_u64()), Some(MAX_WAIT_MS));
+        assert_eq!(
+            data.get("requested_ms").and_then(|v| v.as_u64()),
+            Some(MAX_WAIT_MS * 3)
+        );
+        assert_eq!(data.get("clamped").and_then(|v| v.as_bool()), Some(true));
+        // A shortened wait must announce itself; silently waiting less than
+        // asked is how the agent ends up out of step with the schedule.
+        assert!(summary.contains("clamped"), "got: {summary}");
+
+        let (data, summary) = ControlHubTool::wait_outcome(1_800_000);
+        assert_eq!(data.get("clamped").and_then(|v| v.as_bool()), Some(false));
+        assert_eq!(summary, "Waited 30m00s");
+    }
+
+    #[tokio::test]
+    async fn browser_wait_without_duration_or_condition_is_rejected() {
+        let tool = ControlHubTool::new();
+        let ctx = empty_context();
+        let results = tool
+            .dispatch("browser", "wait", &json!({}), &ctx)
+            .await
+            .expect("reported in-band");
+        let payload = results.first().unwrap().content();
+        // Reporting success for a wait that did not wait is the failure this
+        // guards: the agent moved straight on believing it had paused.
+        assert_eq!(payload.get("ok").and_then(|v| v.as_bool()), Some(false));
+        let error = payload.get("error").expect("error envelope");
+        assert_eq!(
+            error.get("code").and_then(|v| v.as_str()),
+            Some("INVALID_PARAMS")
+        );
+    }
+
+    #[tokio::test]
+    async fn browser_wait_is_interrupted_by_cancellation() {
+        let token = tokio_util::sync::CancellationToken::new();
+        let mut ctx = empty_context();
+        ctx.runtime_handles =
+            bitfun_runtime_ports::ToolRuntimeHandles::new(None, Some(token.clone()));
+
+        let started = std::time::Instant::now();
+        // Driven through `call_impl` so this also covers the envelope layer,
+        // which must let a cancellation through instead of reporting it as an
+        // ordinary `ok: false` tool error.
+        let waiter = tokio::spawn(async move {
+            ControlHubTool::new()
+                .call_impl(
+                    &json!({
+                        "domain": "browser",
+                        "action": "wait",
+                        "params": { "seconds": 600 },
+                    }),
+                    &ctx,
+                )
+                .await
+        });
+        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
+        token.cancel();
+        let outcome = waiter.await.expect("wait task joins");
+
+        // Without this, stopping the agent could not take effect until the
+        // pause elapsed — ten minutes of an unstoppable turn.
+        assert!(
+            matches!(outcome, Err(BitFunError::Cancelled(_))),
+            "a long pace wait must stay interruptible"
+        );
+        assert!(started.elapsed() < std::time::Duration::from_secs(30));
+    }
+
+    #[test]
+    fn wait_durations_are_formatted_for_humans() {
+        assert_eq!(format_duration_ms(1_800_000), "30m00s");
+        assert_eq!(format_duration_ms(MAX_WAIT_MS), "1h00m");
+        assert_eq!(format_duration_ms(1_500), "1s");
+        assert_eq!(format_duration_ms(250), "250ms");
+    }
+
     #[tokio::test]
     async fn meta_capabilities_reports_local_client_and_domain_table() {
         let tool = ControlHubTool::new();
@@ -2799,9 +3322,7 @@ mod control_hub_tests {
             .expect("open_builtin succeeds without a frontend emitter");
         let payload = results.first().expect("one result").content();
         assert_eq!(
-            payload
-                .get("observable_by_agent")
-                .and_then(|v| v.as_bool()),
+            payload.get("observable_by_agent").and_then(|v| v.as_bool()),
             Some(false),
             "open_builtin must state the panel is not agent-observable: {payload}"
         );
@@ -2829,6 +3350,23 @@ mod control_hub_tests {
         );
     }
 
+    #[tokio::test]
+    async fn description_documents_wait_params_and_routes_schedules_to_cron() {
+        let desc = ControlHubTool::new().description().await.unwrap();
+        // The action took `duration_ms` and documented nothing, so the model
+        // guessed `ms` and got a silent no-op.
+        assert!(
+            desc.contains("`wait { duration_ms }`") && desc.contains("`ms`"),
+            "description must name the wait duration parameter and its aliases"
+        );
+        // A recurring pace should not be built out of hour-long waits that pin
+        // the turn open.
+        assert!(
+            desc.contains("`Cron` tool"),
+            "description must point repeating schedules at Cron"
+        );
+    }
+
     #[tokio::test]
     async fn description_defaults_url_opening_to_builtin_browser() {
         let desc = ControlHubTool::new().description().await.unwrap();
@@ -2920,7 +3458,7 @@ mod control_hub_tests {
             );
             assert!(
                 err.hints.iter().any(|h| h.contains("mode: \"default\"")),
-                "hints must offer the default managed-profile mode: {:?}",
+                "hints must offer the default interactive-browser mode: {:?}",
                 err.hints
             );
         }
@@ -2944,12 +3482,14 @@ mod control_hub_tests {
     }
 
     #[test]
-    fn default_connect_hints_point_to_managed_profile_not_user_debug_port() {
+    fn default_connect_hints_point_to_guarded_user_profile_not_raw_debug_port() {
         let hints = ControlHubTool::default_browser_connect_hints(&BrowserKind::Chrome, 9222);
         let joined = hints.join(" | ");
         assert!(
-            joined.contains("managed profile"),
-            "hints must guide toward BitFun's managed profile launch: {joined}"
+            joined.contains("current real profile")
+                && joined.contains("chrome://inspect/#remote-debugging")
+                && joined.contains("approve"),
+            "hints must guide toward Chrome's guarded real-profile connection: {joined}"
         );
         assert!(
             !joined.contains("--remote-debugging-port"),
@@ -2957,6 +3497,19 @@ mod control_hub_tests {
         );
     }
 
+    #[test]
+    fn edge_connect_hints_use_its_guarded_real_profile_setup() {
+        let hints = ControlHubTool::default_browser_connect_hints(&BrowserKind::Edge, 9222);
+        let joined = hints.join(" | ");
+        assert!(joined.contains("current real profile"), "{joined}");
+        assert!(
+            joined.contains("edge://inspect/#remote-debugging"),
+            "{joined}"
+        );
+        assert!(joined.contains("approve"), "{joined}");
+        assert!(!joined.contains("--remote-debugging-port"), "{joined}");
+    }
+
     #[test]
     fn browser_open_builtin_normalizes_domain_url() {
         assert_eq!(
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/cron_tool.rs b/src/crates/assembly/core/src/agentic/tools/implementations/cron_tool.rs
index 4aa05675fb..7dd0e3198f 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/cron_tool.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/cron_tool.rs
@@ -221,6 +221,45 @@ impl CronTool {
         Ok(resolved)
     }
 
+    /// Whether a schedule fires more than once.
+    ///
+    /// Only a repeating schedule takes over a cadence the agent would
+    /// otherwise drive by hand; a one-shot `at` job is a reminder and says
+    /// nothing about what the agent should do with the rest of its turn.
+    fn schedule_repeats(schedule: &CronSchedule) -> bool {
+        match schedule {
+            CronSchedule::At { .. } => false,
+            CronSchedule::Every { .. } | CronSchedule::Cron { .. } => true,
+        }
+    }
+
+    /// Describe a created job to the model.
+    ///
+    /// Handing a cadence to the scheduler is a handoff, but creating the job
+    /// does not end the turn — no tool can. Saying only "created job X" leaves
+    /// `add` looking like any other successful call, so the agent keeps
+    /// driving the loop the schedule was meant to take over, and a turn that
+    /// outruns the interval delays the very trigger it is racing (a scheduled
+    /// run is queued at low priority, never run concurrently).
+    fn add_result_summary(job: &CronJob, current_session_id: Option<&str>) -> String {
+        let mut summary = format!(
+            "Created scheduled job '{}' ({}) for session '{}' in workspace '{}'.",
+            job.name,
+            job.id,
+            job.session_id().unwrap_or(""),
+            job.workspace().workspace_path
+        );
+        if Self::schedule_repeats(&job.schedule) && job.session_id() == current_session_id {
+            summary.push_str(
+                " The schedule owns this cadence now. Creating the job did not end your turn — finish only what is \
+                 already in flight and then end it, instead of starting another round or waiting for one. When the job \
+                 fires it delivers its payload to this session as a new user message, and that is what begins the next \
+                 round; a turn still running when it fires just makes that round start late.",
+            );
+        }
+        summary
+    }
+
     fn normalize_add_name(name: Option<String>) -> String {
         match name {
             Some(name) if !name.trim().is_empty() => name.trim().to_string(),
@@ -633,6 +672,12 @@ impl Tool for CronTool {
     async fn description(&self) -> BitFunResult<String> {
         Ok(r#"Manage scheduled jobs.
 
+Scheduling is a handoff, not a step:
+- Creating a job does NOT end the current turn. No tool can end a turn — only you can, by stopping.
+- After scheduling a repeating job for this session, finish what is already in flight and then end your turn. Do not start the next round yourself and do not wait for it.
+- A job delivers its payload to the target session as a new user message when it fires; that message is what starts the next round.
+- A run that fires while the session is still busy is queued, never run in parallel, so a turn that outlives the interval only makes the next round start late. Pick an interval comfortably longer than one round takes.
+
 Defaults:
 - "session_id": defaults to the current session for "list" and "add".
 
@@ -1101,13 +1146,8 @@ Patch schema for "update":
                     })
                     .await?;
                 let serialized_job = Self::serialize_job(&created)?;
-                let result_for_assistant = format!(
-                    "Created scheduled job '{}' ({}) for session '{}' in workspace '{}'.",
-                    created.name,
-                    created.id,
-                    created.session_id().unwrap_or(""),
-                    created.workspace().workspace_path
-                );
+                let result_for_assistant =
+                    Self::add_result_summary(&created, context.session_id.as_deref());
 
                 Ok(vec![ToolResult::Result {
                     data: json!({
@@ -1389,4 +1429,105 @@ mod tests {
         );
         assert_eq!(workspace_ref.remote_ssh_host.as_deref(), Some("ssh.dev"));
     }
+
+    fn job_with_schedule(schedule: CronSchedule, session_id: &str) -> CronJob {
+        CronJob {
+            id: "cron_4d437971".to_string(),
+            name: "round every 30min".to_string(),
+            schedule,
+            payload: CronJobPayload {
+                text: "run the next round".to_string(),
+            },
+            enabled: true,
+            target: CronJobTarget::Session {
+                session_id: session_id.to_string(),
+                workspace: CronWorkspaceRef {
+                    workspace_id: None,
+                    workspace_path: "/home/wsp/projects/test".to_string(),
+                    project_workspace_path: None,
+                    execution_target: None,
+                    remote_connection_id: None,
+                    remote_ssh_host: None,
+                },
+            },
+            created_at_ms: 0,
+            config_updated_at_ms: 0,
+            updated_at_ms: 0,
+            state: Default::default(),
+        }
+    }
+
+    fn every_30_minutes() -> CronSchedule {
+        CronSchedule::Every {
+            every_ms: 30 * 60 * 1_000,
+            anchor_ms: None,
+        }
+    }
+
+    #[test]
+    fn a_recurring_job_for_this_session_tells_the_agent_to_end_its_turn() {
+        // Without this, `add` reads as an ordinary success and the agent keeps
+        // driving the loop it just handed to the scheduler — the round then
+        // outruns the interval and delays the trigger it is racing.
+        let summary = CronTool::add_result_summary(
+            &job_with_schedule(every_30_minutes(), "session_1"),
+            Some("session_1"),
+        );
+
+        assert!(summary.contains("cron_4d437971"), "got: {summary}");
+        assert!(summary.contains("end your turn"), "got: {summary}");
+        // The turn does not end by itself, and the guidance has to say so:
+        // no tool can end a turn, only the model choosing to stop.
+        assert!(summary.contains("did not end your turn"), "got: {summary}");
+    }
+
+    #[test]
+    fn a_cron_expression_schedule_also_hands_over_the_cadence() {
+        let summary = CronTool::add_result_summary(
+            &job_with_schedule(
+                CronSchedule::Cron {
+                    expr: "0 9 * * 1-5".to_string(),
+                    tz: None,
+                },
+                "session_1",
+            ),
+            Some("session_1"),
+        );
+
+        assert!(summary.contains("end your turn"), "got: {summary}");
+    }
+
+    #[test]
+    fn a_one_shot_job_leaves_the_current_turn_alone() {
+        // A single reminder says nothing about what to do with the rest of the
+        // turn, so telling the agent to stop would cut real work short.
+        let summary = CronTool::add_result_summary(
+            &job_with_schedule(
+                CronSchedule::At {
+                    at: "2026-03-17T12:00:00+08:00".to_string(),
+                },
+                "session_1",
+            ),
+            Some("session_1"),
+        );
+
+        assert!(!summary.contains("end your turn"), "got: {summary}");
+    }
+
+    #[test]
+    fn scheduling_work_for_another_session_leaves_the_current_turn_alone() {
+        // The cadence being handed over is not this turn's, so this agent has
+        // no reason to stop what it is doing.
+        let summary = CronTool::add_result_summary(
+            &job_with_schedule(every_30_minutes(), "session_other"),
+            Some("session_1"),
+        );
+
+        assert!(!summary.contains("end your turn"), "got: {summary}");
+
+        // Same when the caller has no session identity to compare against.
+        let summary =
+            CronTool::add_result_summary(&job_with_schedule(every_30_minutes(), "session_1"), None);
+        assert!(!summary.contains("end your turn"), "got: {summary}");
+    }
 }
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/file_read_tool.rs b/src/crates/assembly/core/src/agentic/tools/implementations/file_read_tool.rs
index b7c5477a74..fe598a2fe3 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/file_read_tool.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/file_read_tool.rs
@@ -14,16 +14,22 @@ use log::{debug, warn};
 use serde_json::{json, Value};
 use std::convert::TryFrom;
 use std::path::Path;
-use std::time::{Duration, Instant};
+#[cfg(feature = "document-read")]
+use std::time::Duration;
+use std::time::Instant;
+use tool_runtime::fs::document::is_supported_document_path;
+#[cfg(feature = "document-read")]
 use tool_runtime::fs::document::{
-    convert_document_to_markdown, is_supported_document_path, DocumentConversionError,
-    MAX_DOCUMENT_INPUT_BYTES, MAX_DOCUMENT_MARKDOWN_BYTES,
+    convert_document_to_markdown, DocumentConversionError, MAX_DOCUMENT_INPUT_BYTES,
+    MAX_DOCUMENT_MARKDOWN_BYTES,
 };
 use tool_runtime::fs::read_file::{
     build_read_file_presentation, build_remote_read_command, build_remote_tail_read_command,
-    parse_remote_read_output, parse_remote_tail_read_output, read_file, read_file_bytes_bounded,
-    read_file_tail, read_text, read_text_tail, ReadFileResult,
+    parse_remote_read_output, parse_remote_tail_read_output, read_file, read_file_tail,
+    ReadFileResult,
 };
+#[cfg(feature = "document-read")]
+use tool_runtime::fs::read_file::{read_file_bytes_bounded, read_text, read_text_tail};
 
 pub struct FileReadTool {
     default_max_lines_to_read: usize,
@@ -33,6 +39,7 @@ pub struct FileReadTool {
 
 /// Default cap on characters returned by a single Read call (excluding wrapper text).
 pub const DEFAULT_READ_MAX_TOTAL_CHARS: usize = 64_000;
+#[cfg(feature = "document-read")]
 // anydoc is synchronous, so this bounds the caller's wait rather than terminating the parser.
 // The worker retains the global conversion permit until it actually exits, keeping failures closed.
 const DOCUMENT_CONVERSION_TIMEOUT: Duration = Duration::from_secs(30);
@@ -300,6 +307,7 @@ impl FileReadTool {
         Ok(result)
     }
 
+    #[cfg(feature = "document-read")]
     async fn read_document_window(
         &self,
         resolved_path: &str,
@@ -410,6 +418,7 @@ impl FileReadTool {
         ))
     }
 
+    #[cfg(feature = "document-read")]
     fn document_conversion_error(
         logical_path: &str,
         resolved_path: &str,
@@ -441,16 +450,29 @@ impl Tool for FileReadTool {
     }
 
     async fn description(&self) -> BitFunResult<String> {
+        #[cfg(feature = "document-read")]
+        let document_summary = " Office documents, OpenDocument files, RTF, EPUB, and PDFs are converted locally to GitHub-Flavored Markdown before reading.";
+        #[cfg(not(feature = "document-read"))]
+        let document_summary = "";
+        #[cfg(feature = "document-read")]
+        let document_guidance = format!(
+            r#"- Supported document extensions are .doc, .docx, .docm, .ppt, .pps, .pot, .pptx, .pptm, .ppsx, .ppsm, .xls, .xlsx, .xlsm, .xlsb, .odt, .ods, .odp, .rtf, .epub, .csv, and .pdf. Document input is capped at {} MiB and extracted Markdown at {} MiB. Conversion is offline and never fetches linked resources.
+- render defaults to auto. auto converts supported documents but preserves CSV as exact source text for editing compatibility. Use render=markdown to turn CSV into a Markdown table or to content-detect a document with a missing/wrong extension. Use render=source to bypass conversion for a textual document such as CSV or RTF.
+- For converted documents, offset, limit, tail, line numbers, and total_lines refer to the extracted Markdown, not source pages or rows. The Markdown is a read-only representation; do not use it as exact source text for Edit. Embedded objects are represented by text, and scanned/image-only PDF pages require OCR.
+"#,
+            MAX_DOCUMENT_INPUT_BYTES / (1024 * 1024),
+            MAX_DOCUMENT_MARKDOWN_BYTES / (1024 * 1024),
+        );
+        #[cfg(not(feature = "document-read"))]
+        let document_guidance = "";
+
         Ok(format!(
-            r#"Reads a file from the current workspace filesystem. Office documents, OpenDocument files, RTF, EPUB, and PDFs are converted locally to GitHub-Flavored Markdown before reading. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
+            r#"Reads a file from the current workspace filesystem.{document_summary} If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
 
 Usage:
 - The file_path parameter must be workspace-relative, an absolute path inside the current workspace, or an exact `bitfun://...` URI returned by another tool.
 - Do not read host roots or placeholder paths such as `/workspace`.
-- Supported document extensions are .doc, .docx, .docm, .ppt, .pps, .pot, .pptx, .pptm, .ppsx, .ppsm, .xls, .xlsx, .xlsm, .xlsb, .odt, .ods, .odp, .rtf, .epub, .csv, and .pdf. Document input is capped at {} MiB and extracted Markdown at {} MiB. Conversion is offline and never fetches linked resources.
-- render defaults to auto. auto converts supported documents but preserves CSV as exact source text for editing compatibility. Use render=markdown to turn CSV into a Markdown table or to content-detect a document with a missing/wrong extension. Use render=source to bypass conversion for a textual document such as CSV or RTF.
-- For converted documents, offset, limit, tail, line numbers, and total_lines refer to the extracted Markdown, not source pages or rows. The Markdown is a read-only representation; do not use it as exact source text for Edit. Embedded objects are represented by text, and scanned/image-only PDF pages require OCR.
-- By default, it reads up to {} lines starting from the beginning of the file. When you plan to Edit a file, prefer this default full read so you see the exact bytes you will need to match.
+{document_guidance}- By default, it reads up to {} lines starting from the beginning of the file. When you plan to Edit a file, prefer this default full read so you see the exact bytes you will need to match.
 - You can optionally specify an offset and limit. offset is a 1-based line number. Use a range only when you already know the target lines; the range must include every line you will copy into Edit `old_string`.
 - You can set tail=true with limit to read the last N lines. This is useful for command output and logs. Do not combine tail=true with offset.
 - Any lines longer than {} characters will be truncated.
@@ -461,31 +483,25 @@ Usage:
 - Avoid tiny repeated slices (e.g. 30-100 line chunks). If you need more context, read a larger window that covers the whole block you will edit.
 - Do not use `limit` with a small value (e.g. < 50) to probe file type or structure. Source files typically begin with copyright headers — a probe read returns no useful code.
 "#,
-            MAX_DOCUMENT_INPUT_BYTES / (1024 * 1024),
-            MAX_DOCUMENT_MARKDOWN_BYTES / (1024 * 1024),
-            self.default_max_lines_to_read,
-            self.max_line_chars,
-            self.max_total_chars
+            self.default_max_lines_to_read, self.max_line_chars, self.max_total_chars
         ))
     }
 
     fn short_description(&self) -> String {
-        "Read text files and extract documents.".to_string()
+        #[cfg(feature = "document-read")]
+        return "Read text files and extract documents.".to_string();
+        #[cfg(not(feature = "document-read"))]
+        return "Read text files.".to_string();
     }
 
     fn input_schema(&self) -> Value {
-        json!({
+        let schema = json!({
             "type": "object",
             "properties": {
                 "file_path": {
                     "type": "string",
                     "description": "The file to read. Use a workspace-relative path, an absolute path inside the current workspace, or an exact bitfun:// URI returned by another tool."
                 },
-                "render": {
-                    "type": "string",
-                    "enum": ["auto", "source", "markdown"],
-                    "description": "How to represent the file. auto converts supported documents but preserves CSV source text; source bypasses conversion; markdown forces local anydoc conversion and enables content detection. Defaults to auto."
-                },
                 "offset": {
                     "type": "number",
                     "description": "The 1-based line number to start reading from. offset=0 is accepted as offset=1. Only provide if the file is too large to read at once."
@@ -501,7 +517,28 @@ Usage:
             },
             "required": ["file_path"],
             "additionalProperties": false
-        })
+        });
+        #[cfg(feature = "document-read")]
+        let schema = {
+            let mut schema = schema;
+            schema["properties"]["render"] = json!({
+                "type": "string",
+                "enum": ["auto", "source", "markdown"],
+                "description": "How to represent the file. auto converts supported documents but preserves CSV source text; source bypasses conversion; markdown forces local anydoc conversion and enables content detection. Defaults to auto."
+            });
+            schema
+        };
+        #[cfg(not(feature = "document-read"))]
+        let schema = {
+            let mut schema = schema;
+            schema["properties"]["render"] = json!({
+                "type": "string",
+                "enum": ["auto", "source"],
+                "description": "How to read the file. auto reads ordinary text and reports known document formats as unavailable; source bypasses document detection for text-based formats. Defaults to auto."
+            });
+            schema
+        };
+        schema
     }
 
     fn is_readonly(&self) -> bool {
@@ -683,6 +720,13 @@ Usage:
             ReadRenderMode::Source => false,
             ReadRenderMode::Markdown => true,
         };
+        #[cfg(not(feature = "document-read"))]
+        if reads_document_representation {
+            return Err(BitFunError::tool(format!(
+                "Document Markdown conversion is not available in this product build: {}. Use a product that includes document-read, or render=source for text-based formats.",
+                resolved.logical_path
+            )));
+        }
         let revision_before_read = if reads_document_representation
             || resolved.uses_remote_workspace_backend()
             || tail
@@ -701,9 +745,10 @@ Usage:
             )]);
         }
 
-        let (read_file_result, document_metadata) = if reads_document_representation {
-            let (result, metadata) = self
-                .read_document_window(
+        #[cfg(feature = "document-read")]
+        let document_read = if reads_document_representation {
+            Some(
+                self.read_document_window(
                     &resolved.resolved_path,
                     &resolved.logical_path,
                     start_line,
@@ -712,7 +757,16 @@ Usage:
                     resolved.uses_remote_workspace_backend(),
                     context,
                 )
-                .await?;
+                .await?,
+            )
+        } else {
+            None
+        };
+        #[cfg(not(feature = "document-read"))]
+        let document_read: Option<(ReadFileResult, DocumentReadMetadata)> = None;
+
+        let (read_file_result, document_metadata) = if let Some((result, metadata)) = document_read
+        {
             (result, Some(metadata))
         } else if resolved.uses_remote_workspace_backend() {
             if tail {
@@ -827,20 +881,27 @@ Usage:
 
 #[cfg(test)]
 mod tests {
-    use super::{FileReadTool, ReadRenderMode, MAX_DOCUMENT_INPUT_BYTES};
+    #[cfg(feature = "document-read")]
+    use super::MAX_DOCUMENT_INPUT_BYTES;
+    use super::{FileReadTool, ReadRenderMode};
     use crate::agentic::tools::framework::{Tool, ToolResult, ToolUseContext};
     use crate::agentic::tools::ToolRuntimeRestrictions;
     use crate::agentic::WorkspaceBinding;
+    #[cfg(feature = "document-read")]
     use async_trait::async_trait;
+    use bitfun_runtime_ports::ToolRuntimeHandles;
+    #[cfg(feature = "document-read")]
     use bitfun_runtime_ports::{
-        ToolRuntimeHandles, WorkspaceCommandOptions, WorkspaceCommandResult, WorkspaceDirEntry,
-        WorkspaceFileSystem, WorkspaceServices, WorkspaceShell,
+        WorkspaceCommandOptions, WorkspaceCommandResult, WorkspaceDirEntry, WorkspaceFileSystem,
+        WorkspaceServices, WorkspaceShell,
     };
     use serde_json::{json, Value};
     use std::collections::HashMap;
     use std::fs;
     use std::path::PathBuf;
+    #[cfg(feature = "document-read")]
     use std::sync::atomic::{AtomicUsize, Ordering};
+    #[cfg(feature = "document-read")]
     use std::sync::Arc;
 
     fn local_context(root: PathBuf) -> ToolUseContext {
@@ -862,11 +923,13 @@ mod tests {
         }
     }
 
+    #[cfg(feature = "document-read")]
     struct FakeRemoteFs {
         bytes: Vec<u8>,
         bounded_limit: Arc<AtomicUsize>,
     }
 
+    #[cfg(feature = "document-read")]
     #[async_trait]
     impl WorkspaceFileSystem for FakeRemoteFs {
         async fn read_file(&self, _path: &str) -> anyhow::Result<Vec<u8>> {
@@ -907,8 +970,10 @@ mod tests {
         }
     }
 
+    #[cfg(feature = "document-read")]
     struct PanicRemoteShell;
 
+    #[cfg(feature = "document-read")]
     #[async_trait]
     impl WorkspaceShell for PanicRemoteShell {
         async fn exec_with_options(
@@ -920,6 +985,7 @@ mod tests {
         }
     }
 
+    #[cfg(feature = "document-read")]
     fn remote_context(bytes: Vec<u8>, bounded_limit: Arc<AtomicUsize>) -> ToolUseContext {
         let root = "/remote/workspace";
         let session_identity =
@@ -960,12 +1026,79 @@ mod tests {
 
         assert!(properties.contains_key("offset"));
         assert!(properties.contains_key("tail"));
+        #[cfg(feature = "document-read")]
         assert_eq!(
             properties["render"]["enum"],
             json!(["auto", "source", "markdown"])
         );
     }
 
+    #[cfg(not(feature = "document-read"))]
+    #[tokio::test]
+    async fn read_tool_without_document_support_does_not_advertise_conversion() {
+        let tool = FileReadTool::new();
+        let schema = tool.input_schema();
+        let properties = schema
+            .get("properties")
+            .and_then(Value::as_object)
+            .expect("properties");
+
+        assert_eq!(properties["render"]["enum"], json!(["auto", "source"]));
+        assert!(!properties["render"]["description"]
+            .as_str()
+            .expect("render description")
+            .contains("Markdown"));
+        assert!(!tool
+            .description()
+            .await
+            .expect("description")
+            .contains("converted locally"));
+        assert_eq!(tool.short_description(), "Read text files.");
+    }
+
+    #[cfg(not(feature = "document-read"))]
+    #[tokio::test]
+    async fn read_tool_without_document_support_fails_closed_for_document_rendering() {
+        let dir = tempfile::tempdir().expect("tempdir");
+        fs::write(dir.path().join("notes.rtf"), br"{\rtf1\ansi Hello}").expect("write RTF");
+        fs::write(dir.path().join("notes.txt"), "plain text").expect("write text");
+        let context = local_context(dir.path().to_path_buf());
+        let tool = FileReadTool::new();
+
+        let auto_error = tool
+            .call_impl(&json!({ "file_path": "notes.rtf" }), &context)
+            .await
+            .expect_err("known document path must not fall back to source text");
+        assert!(auto_error
+            .to_string()
+            .contains("Document Markdown conversion is not available"));
+
+        let markdown_error = tool
+            .call_impl(
+                &json!({ "file_path": "notes.txt", "render": "markdown" }),
+                &context,
+            )
+            .await
+            .expect_err("forced Markdown conversion must be unavailable");
+        assert!(markdown_error
+            .to_string()
+            .contains("Document Markdown conversion is not available"));
+
+        let source = tool
+            .call_impl(
+                &json!({ "file_path": "notes.rtf", "render": "source" }),
+                &context,
+            )
+            .await
+            .expect("explicit source reads remain available");
+        let ToolResult::Result { data, .. } = &source[0] else {
+            panic!("expected result");
+        };
+        assert!(data["content"]
+            .as_str()
+            .is_some_and(|content| content.contains("Hello")));
+    }
+
     #[test]
     fn read_window_start_line_prefers_offset_and_normalizes_zero() {
         assert_eq!(
@@ -1007,6 +1140,7 @@ mod tests {
         assert!(FileReadTool::read_render_mode(&json!({ "render": 1 })).is_err());
     }
 
+    #[cfg(feature = "document-read")]
     #[tokio::test]
     async fn read_converts_rtf_to_a_markdown_representation() {
         let dir = tempfile::tempdir().expect("tempdir");
@@ -1041,6 +1175,22 @@ mod tests {
             .is_some_and(|result| result.contains("from RTF to GitHub-Flavored Markdown")));
     }
 
+    #[cfg(feature = "document-read")]
+    #[tokio::test]
+    async fn document_conversion_failure_does_not_fallback_to_source_bytes() {
+        let dir = tempfile::tempdir().expect("tempdir");
+        fs::write(dir.path().join("broken.pdf"), b"not a PDF").expect("write invalid PDF");
+        let context = local_context(dir.path().to_path_buf());
+
+        let error = FileReadTool::new()
+            .call_impl(&json!({ "file_path": "broken.pdf" }), &context)
+            .await
+            .expect_err("invalid document must not be returned as source text");
+
+        assert!(error.to_string().contains("Failed to convert document"));
+    }
+
+    #[cfg(feature = "document-read")]
     #[tokio::test]
     async fn csv_auto_preserves_source_while_markdown_render_extracts_a_table() {
         let dir = tempfile::tempdir().expect("tempdir");
@@ -1088,6 +1238,7 @@ mod tests {
             .is_some_and(|content| content.contains("| name | value |")));
     }
 
+    #[cfg(feature = "document-read")]
     #[tokio::test]
     async fn remote_document_uses_bounded_file_transfer_and_host_side_conversion() {
         let bounded_limit = Arc::new(AtomicUsize::new(0));
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/view_image_tool.rs b/src/crates/assembly/core/src/agentic/tools/implementations/view_image_tool.rs
index 468fba6e31..1b7dae2e86 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/view_image_tool.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/view_image_tool.rs
@@ -404,11 +404,19 @@ impl Tool for ViewImageTool {
         let mime_type = processed.mime_type.clone();
         let data_base64 = base64::engine::general_purpose::STANDARD.encode(&processed.data);
         let summary = format!("Attached image: {}", path.display_path());
+        // `width`/`height` describe the attached image, which is downscaled
+        // when the source exceeds the provider's limits — so on its own it
+        // reads as the file's size and is not. The source dimensions ride
+        // alongside so a caller reasoning about the picture knows which frame
+        // it is looking at.
         let data = json!({
             "path": path.display_path(),
             "mime_type": mime_type.clone(),
             "width": processed.width,
             "height": processed.height,
+            "original_width": processed.original_width,
+            "original_height": processed.original_height,
+            "was_resized": processed.was_resized(),
             "size": processed.data.len(),
             "summary": summary,
         });
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/web/fetch.rs b/src/crates/assembly/core/src/agentic/tools/implementations/web/fetch.rs
index 04f847b940..c648d7b22c 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/web/fetch.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/web/fetch.rs
@@ -40,7 +40,7 @@ Use this tool to:
 - Download readable content from web pages
 - Access online resources
 
-Best for static pages that need no login. For pages requiring the user's login session or JavaScript rendering, use ControlHub domain="browser" instead: connect -> navigate -> snapshot / read_article. That drives BitFun's managed browser profile, which is separate from the user's everyday browser, so a first-time sign-in by the user may be required. (browser.fetch only works when a session is already connected and the current page is same-origin with the target URL — it runs inside that page and is subject to its CORS policy.)
+Best for static pages that need no login. For pages requiring the user's login session or JavaScript rendering, use ControlHub domain="browser" instead: connect -> navigate -> snapshot / read_article. Chrome 144+ and Edge can connect to the user's current profile after explicit approval, preserving tabs and login state; other supported Chromium browsers reuse a real-profile endpoint when available and otherwise use BitFun's persistent managed profile. (browser.fetch only works when a session is already connected and the current page is same-origin with the target URL — it runs inside that page and is subject to its CORS policy.)
 
 Supports different output formats:
 - raw: Raw response content (original HTML or text)
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/web/mod.rs b/src/crates/assembly/core/src/agentic/tools/implementations/web/mod.rs
index 07ca1af81f..ee57ad1ad5 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/web/mod.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/web/mod.rs
@@ -183,9 +183,10 @@ mod tests {
         assert!(description.contains("connect -> navigate -> snapshot"));
         assert!(description.contains("same-origin"));
         assert!(description.contains("CORS"));
-        // connect drives BitFun's managed profile, not the user's everyday
-        // browser, so the description must not promise their login state.
-        assert!(description.contains("managed browser profile"));
+        // Guarded Chrome/Edge connections preserve the current profile while
+        // other browsers may use a persistent managed profile.
+        assert!(description.contains("current profile"));
+        assert!(description.contains("managed profile"));
     }
 
     #[test]
diff --git a/src/crates/assembly/core/src/agentic/tools/pipeline/tool_pipeline.rs b/src/crates/assembly/core/src/agentic/tools/pipeline/tool_pipeline.rs
index 66a8d5c2bd..34208d14f7 100644
--- a/src/crates/assembly/core/src/agentic/tools/pipeline/tool_pipeline.rs
+++ b/src/crates/assembly/core/src/agentic/tools/pipeline/tool_pipeline.rs
@@ -4028,6 +4028,8 @@ mod tests {
             target: RoundInjectionTarget::CurrentRunningTurn,
             content: "test injection".to_string(),
             display_content: "test injection".to_string(),
+            attachments: Vec::new(),
+            metadata: serde_json::Map::new(),
             created_at: SystemTime::now(),
         }
     }
diff --git a/src/crates/assembly/core/src/external_mcp.rs b/src/crates/assembly/core/src/external_mcp.rs
index 77a75dbc38..4208e49aa4 100644
--- a/src/crates/assembly/core/src/external_mcp.rs
+++ b/src/crates/assembly/core/src/external_mcp.rs
@@ -10,6 +10,7 @@ use bitfun_product_domains::external_sources::{
     ExternalMcpConflictCandidate, ExternalMcpServerDefinition, ExternalMcpStaticStatus,
     ExternalSourceDiagnostic, PreparedExternalMcpServer, PreparedExternalMcpTransport,
 };
+use bitfun_services_integrations::mcp::server::MCPServerStartFailure;
 use serde::{Deserialize, Serialize};
 use sha2::{Digest, Sha256};
 use std::collections::{BTreeMap, BTreeSet};
@@ -61,6 +62,22 @@ pub(super) enum ExternalMcpRuntimeStatus {
     Unavailable(String),
 }
 
+pub(super) const EXTERNAL_MCP_RUNTIME_CONFIGURATION_CHANGED: &str =
+    "external_mcp.runtime.configuration_changed";
+pub(super) const EXTERNAL_MCP_RUNTIME_CONFIGURATION_INVALID: &str =
+    "external_mcp.runtime.configuration_invalid";
+pub(super) const EXTERNAL_MCP_RUNTIME_HOST_UNAVAILABLE: &str =
+    "external_mcp.runtime.host_unavailable";
+pub(super) const EXTERNAL_MCP_RUNTIME_INSTALL_FAILED: &str = "external_mcp.runtime.install_failed";
+pub(super) const EXTERNAL_MCP_RUNTIME_PREPARATION_FAILED: &str =
+    "external_mcp.runtime.preparation_failed";
+pub(super) const EXTERNAL_MCP_RUNTIME_RETIRE_FAILED: &str = "external_mcp.runtime.retire_failed";
+pub(super) const EXTERNAL_MCP_RUNTIME_SERVER_MISSING: &str = "external_mcp.runtime.server_missing";
+pub(super) const EXTERNAL_MCP_RUNTIME_FAILED: &str = "external_mcp.runtime.failed";
+pub(super) const EXTERNAL_MCP_RUNTIME_STOPPED: &str = "external_mcp.runtime.stopped";
+pub(super) const EXTERNAL_MCP_RUNTIME_STATUS_UNAVAILABLE: &str =
+    "external_mcp.runtime.status_unavailable";
+
 /// Narrow product-to-runtime port. Product reconciliation works only with
 /// source-neutral prepared MCP data; the concrete BitFun MCP manager remains
 /// behind this implementation boundary.
@@ -98,26 +115,32 @@ impl ExternalMcpRuntimePort for BitFunExternalMcpRuntime {
         if prepared.id != candidate.definition.id
             || prepared.behavior_version != candidate.definition.behavior_version
         {
-            return Err("The external MCP configuration changed before activation".to_string());
+            return Err(EXTERNAL_MCP_RUNTIME_CONFIGURATION_CHANGED.to_string());
         }
-        let config = prepared_mcp_config(candidate, prepared)?;
+        let config = prepared_mcp_config(candidate, prepared)
+            .map_err(|_| EXTERNAL_MCP_RUNTIME_CONFIGURATION_INVALID.to_string())?;
         mcp_manager()?
             .install_external_ephemeral_server(config, workspace_key.to_string())
             .await
             // Runtime errors may contain a URL or command line. Keep the
             // product-facing error actionable without echoing sensitive data.
-            .map_err(|_| "The external MCP server could not be started".to_string())
+            .map_err(|_| EXTERNAL_MCP_RUNTIME_INSTALL_FAILED.to_string())
     }
 
     async fn retire(&self, runtime_id: &str) -> Result<(), String> {
         mcp_manager()?
             .retire_external_ephemeral_server(runtime_id)
             .await
-            .map_err(|_| "The external MCP server could not be stopped cleanly".to_string())
+            .map_err(|_| EXTERNAL_MCP_RUNTIME_RETIRE_FAILED.to_string())
     }
 
     async fn status(&self, runtime_id: &str) -> Result<ExternalMcpRuntimeStatus, String> {
         let manager = mcp_manager()?;
+        if let Some(failure) = manager.external_server_start_failure(runtime_id).await {
+            return Ok(ExternalMcpRuntimeStatus::Unavailable(
+                external_mcp_start_failure_reason(failure).to_string(),
+            ));
+        }
         if manager.external_server_readiness(runtime_id).await == Some(false) {
             return Ok(ExternalMcpRuntimeStatus::Loading);
         }
@@ -128,28 +151,10 @@ impl ExternalMcpRuntimePort for BitFunExternalMcpRuntime {
         .await
         {
             Ok(Ok(status)) => status,
-            Ok(Err(_)) => return Err("The external MCP server is no longer available".to_string()),
+            Ok(Err(_)) => return Err(EXTERNAL_MCP_RUNTIME_SERVER_MISSING.to_string()),
             Err(_) => return Ok(ExternalMcpRuntimeStatus::Loading),
         };
-        Ok(match status {
-            MCPServerStatus::Connected | MCPServerStatus::Healthy => {
-                ExternalMcpRuntimeStatus::Active
-            }
-            MCPServerStatus::Uninitialized
-            | MCPServerStatus::Starting
-            | MCPServerStatus::Reconnecting => ExternalMcpRuntimeStatus::Loading,
-            MCPServerStatus::NeedsAuth => ExternalMcpRuntimeStatus::Unavailable(
-                "Authentication is required for this MCP server".to_string(),
-            ),
-            MCPServerStatus::Failed => ExternalMcpRuntimeStatus::Unavailable(
-                "The MCP server failed to start or stopped unexpectedly".to_string(),
-            ),
-            MCPServerStatus::Stopping | MCPServerStatus::Stopped => {
-                ExternalMcpRuntimeStatus::Unavailable(
-                    "The MCP server is not currently running".to_string(),
-                )
-            }
-        })
+        Ok(external_mcp_runtime_status(status))
     }
 
     async fn replace_workspace_route(
@@ -169,10 +174,67 @@ impl ExternalMcpRuntimePort for BitFunExternalMcpRuntime {
     }
 }
 
+fn external_mcp_runtime_status(status: MCPServerStatus) -> ExternalMcpRuntimeStatus {
+    match status {
+        MCPServerStatus::Connected | MCPServerStatus::Healthy => ExternalMcpRuntimeStatus::Active,
+        MCPServerStatus::Uninitialized
+        | MCPServerStatus::Starting
+        | MCPServerStatus::Reconnecting => ExternalMcpRuntimeStatus::Loading,
+        MCPServerStatus::NeedsAuth => ExternalMcpRuntimeStatus::Unavailable(
+            external_mcp_start_failure_reason(MCPServerStartFailure::Authentication).to_string(),
+        ),
+        MCPServerStatus::Failed => {
+            ExternalMcpRuntimeStatus::Unavailable(EXTERNAL_MCP_RUNTIME_FAILED.to_string())
+        }
+        MCPServerStatus::Stopping | MCPServerStatus::Stopped => {
+            ExternalMcpRuntimeStatus::Unavailable(EXTERNAL_MCP_RUNTIME_STOPPED.to_string())
+        }
+    }
+}
+
+fn external_mcp_start_failure_reason(failure: MCPServerStartFailure) -> &'static str {
+    match failure {
+        MCPServerStartFailure::Authentication => "external_mcp.start.authentication",
+        MCPServerStartFailure::Timeout => "external_mcp.start.timeout",
+        MCPServerStartFailure::CommandUnavailable => "external_mcp.start.command_unavailable",
+        MCPServerStartFailure::WorkingDirectoryUnavailable => {
+            "external_mcp.start.working_directory_unavailable"
+        }
+        MCPServerStartFailure::ConnectionFailed => "external_mcp.start.connection_failed",
+        MCPServerStartFailure::ProtocolFailed => "external_mcp.start.protocol_failed",
+        MCPServerStartFailure::Other => "external_mcp.start.other",
+    }
+}
+
 fn mcp_manager() -> Result<std::sync::Arc<crate::service::mcp::MCPServerManager>, String> {
     get_global_mcp_service()
         .map(|service| service.server_manager())
-        .ok_or_else(|| "The BitFun MCP runtime is not available in this product host".to_string())
+        .ok_or_else(|| EXTERNAL_MCP_RUNTIME_HOST_UNAVAILABLE.to_string())
+}
+
+#[cfg(test)]
+mod runtime_reason_tests {
+    use super::*;
+
+    #[test]
+    fn terminal_runtime_statuses_use_stable_product_reason_codes() {
+        let cases = [
+            (
+                MCPServerStatus::NeedsAuth,
+                "external_mcp.start.authentication",
+            ),
+            (MCPServerStatus::Failed, EXTERNAL_MCP_RUNTIME_FAILED),
+            (MCPServerStatus::Stopping, EXTERNAL_MCP_RUNTIME_STOPPED),
+            (MCPServerStatus::Stopped, EXTERNAL_MCP_RUNTIME_STOPPED),
+        ];
+
+        for (status, expected) in cases {
+            assert_eq!(
+                external_mcp_runtime_status(status),
+                ExternalMcpRuntimeStatus::Unavailable(expected.to_string())
+            );
+        }
+    }
 }
 
 pub(super) fn prepared_mcp_config(
diff --git a/src/crates/assembly/core/src/external_sources.rs b/src/crates/assembly/core/src/external_sources.rs
index 0d1016cf4b..791ee9da04 100644
--- a/src/crates/assembly/core/src/external_sources.rs
+++ b/src/crates/assembly/core/src/external_sources.rs
@@ -44,7 +44,8 @@ use crate::agentic::workspace::workspace_route_key;
 use crate::external_mcp::{
     reconcile_external_mcp_catalog, BitFunExternalMcpRuntime, ExternalMcpDecision,
     ExternalMcpDecisions, ExternalMcpProductState, ExternalMcpRuntimePort,
-    ExternalMcpRuntimeStatus, NativeMcpCandidate,
+    ExternalMcpRuntimeStatus, NativeMcpCandidate, EXTERNAL_MCP_RUNTIME_FAILED,
+    EXTERNAL_MCP_RUNTIME_PREPARATION_FAILED, EXTERNAL_MCP_RUNTIME_STATUS_UNAVAILABLE,
 };
 use crate::external_subagents::{
     project_external_subagents_read_only, reconcile_external_subagents, ExternalSubagentDecisions,
@@ -1999,7 +2000,7 @@ impl WorkspaceExternalSourceService {
                     conflict_choices: &preferences.mcp_conflict_choices,
                 },
             ),
-            Err(error) => {
+            Err(_) => {
                 let mut state = reconcile_external_mcp_catalog(
                     self.execution_domain_id.as_str(),
                     &mcp_workspace_key,
@@ -2014,7 +2015,7 @@ impl WorkspaceExternalSourceService {
                 for entry in &mut state.entries {
                     entry.runtime_id = None;
                     entry.activation_state = ExternalMcpActivationState::RuntimeUnavailable {
-                        reason: error.clone(),
+                        reason: "external_mcp.native_configuration_unavailable".to_string(),
                     };
                 }
                 state.active.clear();
@@ -2253,7 +2254,7 @@ impl WorkspaceExternalSourceService {
                 ExternalMcpActivationState::Active | ExternalMcpActivationState::Starting
             ) {
                 entry.activation_state = ExternalMcpActivationState::RuntimeUnavailable {
-                    reason: "This Host exposes discovery only; use Desktop or an authenticated Peer Host to run external MCP servers".to_string(),
+                    reason: "external_mcp.runtime.host_read_only".to_string(),
                 };
             }
         }
@@ -2390,9 +2391,7 @@ impl WorkspaceExternalSourceService {
                 let status = managed_statuses
                     .get(&candidate.runtime_id)
                     .cloned()
-                    .unwrap_or_else(|| {
-                        Err("The external MCP server status is unavailable".to_string())
-                    });
+                    .unwrap_or_else(|| Err(EXTERNAL_MCP_RUNTIME_STATUS_UNAVAILABLE.to_string()));
                 // Keep failed registrations managed until the user disables
                 // them. Re-installing from a status error would turn a
                 // persistent startup failure into an unbounded retry loop.
@@ -2408,8 +2407,10 @@ impl WorkspaceExternalSourceService {
                     .prepare_server_guarded(&server_id, &behavior_version)
             })
             .await
-            .map_err(|_| "The external MCP configuration could not be prepared".to_string())
-            .and_then(|result| result.map_err(|error| error.message));
+            .map_err(|_| EXTERNAL_MCP_RUNTIME_PREPARATION_FAILED.to_string())
+            .and_then(|result| {
+                result.map_err(|_| EXTERNAL_MCP_RUNTIME_PREPARATION_FAILED.to_string())
+            });
 
             let activation = match prepared {
                 Ok(prepared) => {
@@ -3348,6 +3349,149 @@ impl WorkspaceExternalSourceService {
         self.rebuild_product_snapshot(command_snapshot).await
     }
 
+    async fn set_tool_targets_enabled(
+        &self,
+        decisions: Vec<(String, String)>,
+        enabled: bool,
+        expected_catalog_generation: u64,
+        expected_preference_revision: u64,
+    ) -> Result<ExternalSourceCatalogSnapshot, String> {
+        let _refresh_guard = self.refresh_gate.lock().await;
+        let snapshot = self.snapshot();
+        if snapshot.generation != expected_catalog_generation
+            || snapshot.preference_revision != expected_preference_revision
+        {
+            return Err(stale_operation_error(
+                "External tool catalog changed; refresh before retrying",
+            ));
+        }
+        for (approval_key, decision_key) in &decisions {
+            let source = snapshot
+                .tools
+                .iter()
+                .find(|tool| {
+                    tool.approval_key == *approval_key && tool.decision_key == *decision_key
+                })
+                .map(|tool| &tool.definition.id.target.source)
+                .ok_or_else(|| {
+                    missing_candidate_error("External tool decision is no longer available")
+                })?;
+            if enabled {
+                ensure_source_capability_active(&snapshot, source, EXTERNAL_CAPABILITY_TOOL)?;
+            }
+        }
+        let preferences = persist_capability_bulk_decisions(
+            ExternalCapabilityBulkDecisionSet::Tool(decisions),
+            enabled,
+            expected_preference_revision,
+        )
+        .await?;
+        propagate_tool_preferences(&preferences);
+        let command_snapshot = lock_coordinator(&self.control_plane).snapshot();
+        self.rebuild_product_snapshot(command_snapshot).await
+    }
+
+    async fn set_subagents_enabled(
+        &self,
+        decisions: Vec<(String, String)>,
+        enabled: bool,
+        expected_subagent_generation: u64,
+        expected_preference_revision: u64,
+    ) -> Result<ExternalSourceCatalogSnapshot, String> {
+        let _refresh_guard = self.refresh_gate.lock().await;
+        let snapshot = self.snapshot();
+        if snapshot.subagent_generation != expected_subagent_generation
+            || snapshot.preference_revision != expected_preference_revision
+        {
+            return Err(stale_operation_error(
+                "External subagent catalog changed; refresh before retrying",
+            ));
+        }
+        for (candidate_id, decision_key) in &decisions {
+            let summary = snapshot
+                .subagents
+                .iter()
+                .find(|summary| {
+                    summary.candidate_id.as_str() == candidate_id
+                        && summary.decision_key == *decision_key
+                })
+                .ok_or_else(|| {
+                    missing_candidate_error("External subagent decision is no longer available")
+                })?;
+            if enabled {
+                ensure_source_set_capability_active(
+                    &snapshot,
+                    &summary.source_keys,
+                    EXTERNAL_CAPABILITY_SUBAGENT,
+                )?;
+            }
+        }
+        let preferences = persist_capability_bulk_decisions(
+            ExternalCapabilityBulkDecisionSet::Subagent(
+                decisions
+                    .into_iter()
+                    .map(|(_, decision_key)| decision_key)
+                    .collect(),
+            ),
+            enabled,
+            expected_preference_revision,
+        )
+        .await?;
+        propagate_subagent_preferences(&preferences);
+        let command_snapshot = lock_coordinator(&self.control_plane).snapshot();
+        self.rebuild_product_snapshot(command_snapshot).await
+    }
+
+    async fn set_mcp_servers_enabled(
+        &self,
+        decisions: Vec<(String, String)>,
+        enabled: bool,
+        expected_mcp_generation: u64,
+        expected_preference_revision: u64,
+    ) -> Result<ExternalSourceCatalogSnapshot, String> {
+        let _refresh_guard = self.refresh_gate.lock().await;
+        let snapshot = self.snapshot();
+        if snapshot.mcp_generation != expected_mcp_generation
+            || snapshot.preference_revision != expected_preference_revision
+        {
+            return Err(stale_operation_error(
+                "External MCP catalog changed; refresh before retrying",
+            ));
+        }
+        for (candidate_id, decision_key) in &decisions {
+            let server = snapshot
+                .mcp_servers
+                .iter()
+                .find(|server| {
+                    server.candidate_id == *candidate_id && server.decision_key == *decision_key
+                })
+                .ok_or_else(|| {
+                    missing_candidate_error("External MCP decision is no longer available")
+                })?;
+            if enabled {
+                ensure_source_capability_active(
+                    &snapshot,
+                    &server.definition.id.source,
+                    EXTERNAL_CAPABILITY_MCP,
+                )?;
+            }
+        }
+        let preferences = persist_capability_bulk_decisions(
+            ExternalCapabilityBulkDecisionSet::Mcp(
+                decisions
+                    .into_iter()
+                    .map(|(_, decision_key)| decision_key)
+                    .collect(),
+            ),
+            enabled,
+            expected_preference_revision,
+        )
+        .await?;
+        propagate_mcp_preferences(&preferences);
+        let command_snapshot = lock_coordinator(&self.control_plane).snapshot();
+        self.rebuild_product_snapshot(command_snapshot).await
+    }
+
     async fn set_tool_conflict_choice(
         &self,
         conflict_key: &str,
@@ -4490,6 +4634,7 @@ fn mark_external_mcp_runtime_unavailable(
     candidate: &crate::external_mcp::ActiveExternalMcpCandidate,
     reason: String,
 ) {
+    let reason = stable_external_mcp_runtime_reason(&reason).to_string();
     if let Some(entry) = state
         .entries
         .iter_mut()
@@ -4509,6 +4654,31 @@ fn mark_external_mcp_runtime_unavailable(
     );
 }
 
+fn stable_external_mcp_runtime_reason(reason: &str) -> &str {
+    match reason {
+        "external_mcp.start.authentication"
+        | "external_mcp.start.timeout"
+        | "external_mcp.start.command_unavailable"
+        | "external_mcp.start.working_directory_unavailable"
+        | "external_mcp.start.connection_failed"
+        | "external_mcp.start.protocol_failed"
+        | "external_mcp.start.other"
+        | "external_mcp.native_configuration_unavailable"
+        | "external_mcp.runtime.host_read_only"
+        | "external_mcp.runtime.configuration_changed"
+        | "external_mcp.runtime.configuration_invalid"
+        | "external_mcp.runtime.host_unavailable"
+        | "external_mcp.runtime.install_failed"
+        | "external_mcp.runtime.preparation_failed"
+        | "external_mcp.runtime.retire_failed"
+        | "external_mcp.runtime.server_missing"
+        | "external_mcp.runtime.failed"
+        | "external_mcp.runtime.stopped"
+        | "external_mcp.runtime.status_unavailable" => reason,
+        _ => EXTERNAL_MCP_RUNTIME_FAILED,
+    }
+}
+
 fn merge_mcp_state(
     snapshot: &mut ExternalSourceCatalogSnapshot,
     coordinator_snapshot: &bitfun_external_sources::ExternalMcpCoordinatorSnapshot,
@@ -5081,6 +5251,88 @@ async fn persist_tool_target_decision(
         })
 }
 
+#[derive(Debug, Clone, PartialEq, Eq)]
+enum ExternalCapabilityBulkDecisionSet {
+    Tool(Vec<(String, String)>),
+    Subagent(Vec<String>),
+    Mcp(Vec<String>),
+}
+
+fn apply_capability_bulk_decisions(
+    config: &mut ExternalSourcesConfig,
+    decisions: ExternalCapabilityBulkDecisionSet,
+    enabled: bool,
+) -> bool {
+    let changed = match decisions {
+        ExternalCapabilityBulkDecisionSet::Tool(decisions) => {
+            let previous_approved = config.approved_tool_targets.clone();
+            let previous_declined = config.declined_tool_decisions.clone();
+            for (approval_key, decision_key) in decisions {
+                reconcile_tool_target_decision(config, approval_key, decision_key, enabled);
+            }
+            config.approved_tool_targets != previous_approved
+                || config.declined_tool_decisions != previous_declined
+        }
+        ExternalCapabilityBulkDecisionSet::Subagent(decisions) => {
+            let previous_approved = config.approved_subagent_envelopes.clone();
+            let previous_declined = config.declined_subagent_decisions.clone();
+            for decision_key in decisions {
+                if enabled {
+                    config
+                        .approved_subagent_envelopes
+                        .insert(decision_key.clone());
+                    config.declined_subagent_decisions.remove(&decision_key);
+                } else {
+                    config.approved_subagent_envelopes.remove(&decision_key);
+                    config
+                        .declined_subagent_decisions
+                        .insert(decision_key.clone(), decision_key);
+                }
+            }
+            config.approved_subagent_envelopes != previous_approved
+                || config.declined_subagent_decisions != previous_declined
+        }
+        ExternalCapabilityBulkDecisionSet::Mcp(decisions) => {
+            let previous = config.mcp_server_decisions.clone();
+            for decision_key in decisions {
+                reconcile_versioned_mcp_server_decision(
+                    &mut config.mcp_server_decisions,
+                    decision_key,
+                    enabled,
+                );
+            }
+            config.mcp_server_decisions != previous
+        }
+    };
+    if changed {
+        config.preference_revision = config.preference_revision.saturating_add(1);
+    }
+    changed
+}
+
+async fn persist_capability_bulk_decisions(
+    decisions: ExternalCapabilityBulkDecisionSet,
+    enabled: bool,
+    expected_preference_revision: u64,
+) -> Result<ExternalSourcesConfig, String> {
+    ExternalSourcePreferenceStore::global()?
+        .update(move |config| {
+            if config.preference_revision != expected_preference_revision {
+                return false;
+            }
+            apply_capability_bulk_decisions(config, decisions, enabled);
+            true
+        })
+        .await
+        .and_then(|(applied, config)| {
+            applied.then_some(config).ok_or_else(|| {
+                stale_operation_error(
+                    "External capability preferences changed; refresh before retrying",
+                )
+            })
+        })
+}
+
 fn reconcile_tool_target_decision(
     config: &mut ExternalSourcesConfig,
     approval_key: String,
@@ -6472,6 +6724,24 @@ pub async fn set_external_tool_target_decision(
         .await
 }
 
+pub async fn set_external_tool_targets_enabled(
+    workspace_root: Option<&Path>,
+    decisions: Vec<(String, String)>,
+    enabled: bool,
+    expected_catalog_generation: u64,
+    expected_preference_revision: u64,
+) -> Result<ExternalSourceCatalogSnapshot, String> {
+    service_for(workspace_root)
+        .await?
+        .set_tool_targets_enabled(
+            decisions,
+            enabled,
+            expected_catalog_generation,
+            expected_preference_revision,
+        )
+        .await
+}
+
 pub async fn set_external_tool_conflict_choice(
     workspace_root: Option<&Path>,
     conflict_key: &str,
@@ -6504,6 +6774,24 @@ pub async fn set_external_mcp_server_decision(
         .await
 }
 
+pub async fn set_external_mcp_servers_enabled(
+    workspace_root: Option<&Path>,
+    decisions: Vec<(String, String)>,
+    enabled: bool,
+    expected_mcp_generation: u64,
+    expected_preference_revision: u64,
+) -> Result<ExternalSourceCatalogSnapshot, String> {
+    service_for(workspace_root)
+        .await?
+        .set_mcp_servers_enabled(
+            decisions,
+            enabled,
+            expected_mcp_generation,
+            expected_preference_revision,
+        )
+        .await
+}
+
 pub async fn choose_external_mcp_conflict(
     workspace_root: Option<&Path>,
     conflict_key: &str,
@@ -6544,6 +6832,24 @@ pub async fn set_external_subagent_activation(
         .await
 }
 
+pub async fn set_external_subagents_enabled(
+    workspace_root: Option<&Path>,
+    decisions: Vec<(String, String)>,
+    enabled: bool,
+    expected_subagent_generation: u64,
+    expected_preference_revision: u64,
+) -> Result<ExternalSourceCatalogSnapshot, String> {
+    service_for(workspace_root)
+        .await?
+        .set_subagents_enabled(
+            decisions,
+            enabled,
+            expected_subagent_generation,
+            expected_preference_revision,
+        )
+        .await
+}
+
 pub async fn set_external_subagent_model_binding(
     workspace_root: Option<&Path>,
     binding_key: &str,
@@ -7086,6 +7392,24 @@ mod tests {
     use bitfun_product_domains::workspace_references::ExternalWorkspaceReferenceDefinition;
     use std::sync::atomic::{AtomicUsize, Ordering};
 
+    #[test]
+    fn runtime_reason_projection_preserves_known_codes_and_hides_raw_errors() {
+        for reason in [
+            "external_mcp.start.authentication",
+            "external_mcp.start.timeout",
+            "external_mcp.runtime.host_unavailable",
+            "external_mcp.runtime.server_missing",
+            "external_mcp.runtime.failed",
+            "external_mcp.runtime.stopped",
+        ] {
+            assert_eq!(stable_external_mcp_runtime_reason(reason), reason);
+        }
+        assert_eq!(
+            stable_external_mcp_runtime_reason("failed to read D:/private/mcp.json: access denied"),
+            EXTERNAL_MCP_RUNTIME_FAILED
+        );
+    }
+
     fn native_mcp_config_with_pin(pin: &str) -> MCPServerConfig {
         MCPServerConfig {
             id: "native-secret-test".to_string(),
@@ -9769,6 +10093,115 @@ mod tests {
         );
     }
 
+    #[test]
+    fn capability_bulk_decisions_update_multiple_items_with_one_revision() {
+        let mut config = ExternalSourcesConfig {
+            preference_revision: 7,
+            ..Default::default()
+        };
+
+        assert!(apply_capability_bulk_decisions(
+            &mut config,
+            ExternalCapabilityBulkDecisionSet::Tool(vec![
+                ("tool-approval-a".to_string(), "tool-decision-a".to_string()),
+                ("tool-approval-b".to_string(), "tool-decision-b".to_string()),
+            ]),
+            true,
+        ));
+        assert_eq!(config.preference_revision, 8);
+        assert_eq!(
+            config.approved_tool_targets,
+            BTreeSet::from(["tool-approval-a".to_string(), "tool-approval-b".to_string(),])
+        );
+
+        assert!(!apply_capability_bulk_decisions(
+            &mut config,
+            ExternalCapabilityBulkDecisionSet::Tool(vec![
+                ("tool-approval-a".to_string(), "tool-decision-a".to_string()),
+                ("tool-approval-b".to_string(), "tool-decision-b".to_string()),
+            ]),
+            true,
+        ));
+        assert_eq!(config.preference_revision, 8);
+
+        assert!(apply_capability_bulk_decisions(
+            &mut config,
+            ExternalCapabilityBulkDecisionSet::Mcp(vec![
+                "external_mcp_approval:local-user:workspace:docs:v1".to_string(),
+                "external_mcp_approval:local-user:workspace:search:v1".to_string(),
+            ]),
+            false,
+        ));
+        assert_eq!(config.preference_revision, 9);
+        assert!(config
+            .mcp_server_decisions
+            .values()
+            .all(|decision| !decision.approved));
+
+        assert!(apply_capability_bulk_decisions(
+            &mut config,
+            ExternalCapabilityBulkDecisionSet::Subagent(vec![
+                "agent-decision-a".to_string(),
+                "agent-decision-b".to_string(),
+            ]),
+            true,
+        ));
+        assert_eq!(config.preference_revision, 10);
+        assert_eq!(
+            config.approved_subagent_envelopes,
+            BTreeSet::from([
+                "agent-decision-a".to_string(),
+                "agent-decision-b".to_string(),
+            ])
+        );
+        assert!(apply_capability_bulk_decisions(
+            &mut config,
+            ExternalCapabilityBulkDecisionSet::Subagent(vec![
+                "agent-decision-a".to_string(),
+                "agent-decision-b".to_string(),
+            ]),
+            false,
+        ));
+        assert_eq!(config.preference_revision, 11);
+        assert!(config.approved_subagent_envelopes.is_empty());
+    }
+
+    #[tokio::test]
+    async fn capability_bulk_actions_reject_catalog_drift_without_expanding_the_decision_set() {
+        let service = test_service(Vec::new());
+        {
+            let mut snapshot = lock_snapshot(&service.snapshot);
+            snapshot.generation = 12;
+            snapshot.subagent_generation = 13;
+            snapshot.mcp_generation = 14;
+            snapshot.preference_revision = 7;
+        }
+
+        let errors = [
+            service
+                .set_tool_targets_enabled(Vec::new(), true, 11, 7)
+                .await
+                .expect_err("tool catalog drift must require a new review"),
+            service
+                .set_subagents_enabled(Vec::new(), true, 12, 7)
+                .await
+                .expect_err("subagent catalog drift must require a new review"),
+            service
+                .set_mcp_servers_enabled(Vec::new(), true, 13, 7)
+                .await
+                .expect_err("MCP catalog drift must require a new review"),
+        ];
+
+        for error in errors {
+            assert_eq!(
+                ExternalSourceOperationError::decode(&error)
+                    .expect("bulk catalog drift uses the typed error contract")
+                    .code,
+                ExternalSourceOperationErrorCode::StaleRevision
+            );
+        }
+    }
+
     #[tokio::test]
     async fn tool_approval_waits_for_refresh_and_rejects_a_changed_decision() {
         let service = test_service(Vec::new());
diff --git a/src/crates/assembly/core/src/external_subagents.rs b/src/crates/assembly/core/src/external_subagents.rs
index 5330526cd9..71953f3501 100644
--- a/src/crates/assembly/core/src/external_subagents.rs
+++ b/src/crates/assembly/core/src/external_subagents.rs
@@ -33,6 +33,7 @@ use bitfun_product_domains::external_subagents::{
     ExternalSubagentDiagnosticSummary, ExternalSubagentModelBindingGroup,
     ExternalSubagentModelBindingMethod, ExternalSubagentModelBindingOption,
     ExternalSubagentModelBindingTarget, ExternalSubagentModelRequest, ExternalSubagentSummary,
+    ExternalSubagentToolCapability,
 };
 use sha2::{Digest, Sha256};
 use std::collections::{BTreeMap, BTreeSet};
@@ -248,12 +249,11 @@ async fn gather_product_facts(
         .iter()
         .flat_map(|definition| &definition.requested_tools.selectors)
         .filter(|selector| selector.allowed)
-        .map(|selector| {
+        .filter_map(|selector| {
             selector
-                .canonical_host_name
-                .as_deref()
-                .unwrap_or(&selector.source_name)
-                .to_string()
+                .canonical_capability
+                .map(host_tool_name)
+                .map(str::to_string)
         })
         .collect::<BTreeSet<_>>();
     let mut tools = BTreeMap::new();
@@ -334,6 +334,18 @@ async fn gather_product_facts(
     }
 }
 
+fn host_tool_name(capability: ExternalSubagentToolCapability) -> &'static str {
+    match capability {
+        ExternalSubagentToolCapability::DirectoryList => "LS",
+        ExternalSubagentToolCapability::ReadFile => "Read",
+        ExternalSubagentToolCapability::GlobFiles => "Glob",
+        ExternalSubagentToolCapability::SearchText => "Grep",
+        ExternalSubagentToolCapability::ExecuteCommand => "ExecCommand",
+        ExternalSubagentToolCapability::EditFile => "Edit",
+        ExternalSubagentToolCapability::WriteFile => "Write",
+    }
+}
+
 fn log_model_config_unavailable(stage: &str, error: &BitFunError) {
     if claim_model_config_outage_log(&MODEL_CONFIG_UNAVAILABLE_LOGGED) {
         log::warn!(
@@ -1031,10 +1043,18 @@ fn resolve_external_candidate(
         .iter()
         .filter(|selector| selector.allowed)
     {
-        let name = selector
-            .canonical_host_name
-            .as_deref()
-            .unwrap_or(&selector.source_name);
+        let Some(capability) = selector.canonical_capability else {
+            if matches!(compatibility, ExternalSubagentCompatibilityState::Ready) {
+                compatibility = ExternalSubagentCompatibilityState::ReadyWithDegradation;
+            }
+            unavailable_tool_labels.push(selector.source_name.clone());
+            diagnostics.push(ExternalSubagentDiagnosticSummary {
+                code: "external_subagent.tool_unavailable".to_string(),
+                blocks_activation: false,
+            });
+            continue;
+        };
+        let name = host_tool_name(capability);
         match facts.tools.get(name) {
             Some(tool) => tools.push(tool.clone()),
             None => {
@@ -1482,8 +1502,8 @@ mod tests {
         ExternalSubagentContributionId, ExternalSubagentContributionRole, ExternalSubagentLocalId,
         ExternalSubagentMode, ExternalSubagentModelBindingMethod,
         ExternalSubagentModelBindingTarget, ExternalSubagentModelProfileRequest,
-        ExternalSubagentProvenanceRef, ExternalSubagentToolRequest, ExternalSubagentToolSelector,
-        SecretText,
+        ExternalSubagentProvenanceRef, ExternalSubagentToolCapability, ExternalSubagentToolRequest,
+        ExternalSubagentToolSelector, SecretText,
     };
     use bitfun_product_domains::tool_permissions::{
         PermissionConstraintLayer, PermissionEffect, PermissionRule,
@@ -1517,7 +1537,7 @@ mod tests {
                 requested_tools: ExternalSubagentToolRequest {
                     selectors: vec![ExternalSubagentToolSelector {
                         source_name: "read".to_string(),
-                        canonical_host_name: Some("Read".to_string()),
+                        canonical_capability: Some(ExternalSubagentToolCapability::ReadFile),
                         allowed: true,
                     }],
                     uses_conservative_default: false,
@@ -2285,18 +2305,16 @@ mod tests {
     }
 
     #[test]
-    fn unavailable_tool_labels_are_preserved_for_product_diagnostics() {
+    fn unknown_source_tool_degrades_without_borrowing_a_same_named_host_tool() {
         let empty_set = BTreeSet::new();
         let empty_map = BTreeMap::new();
         let mut definition_snapshot = snapshot("behavior-v1", "catalog-v1");
-        definition_snapshot.definitions[0]
-            .requested_tools
-            .selectors
-            .push(ExternalSubagentToolSelector {
-                source_name: "shell".to_string(),
-                canonical_host_name: Some("Shell".to_string()),
+        definition_snapshot.definitions[0].requested_tools.selectors[0] =
+            ExternalSubagentToolSelector {
+                source_name: "Read".to_string(),
+                canonical_capability: None,
                 allowed: true,
-            });
+            };
 
         let state = reconcile_with_facts(
             Some(Path::new("C:/repo")),
@@ -2313,12 +2331,33 @@ mod tests {
             &facts(),
         );
 
-        assert_eq!(state.summaries[0].unavailable_tool_labels, ["Shell"]);
+        assert_eq!(state.summaries[0].unavailable_tool_labels, ["Read"]);
+        assert_eq!(
+            state.summaries[0].compatibility_state,
+            ExternalSubagentCompatibilityState::ReadyWithDegradation
+        );
+        assert!(state.summaries[0].effective_tool_labels.is_empty());
         assert!(state.summaries[0].diagnostics.iter().any(|diagnostic| {
-            diagnostic.code == "external_subagent.tool_unavailable" && diagnostic.blocks_activation
+            diagnostic.code == "external_subagent.tool_unavailable" && !diagnostic.blocks_activation
         }));
     }
 
+    #[test]
+    fn executable_and_file_mutation_capabilities_use_bitfun_builtin_tools() {
+        assert_eq!(
+            host_tool_name(ExternalSubagentToolCapability::ExecuteCommand),
+            "ExecCommand"
+        );
+        assert_eq!(
+            host_tool_name(ExternalSubagentToolCapability::EditFile),
+            "Edit"
+        );
+        assert_eq!(
+            host_tool_name(ExternalSubagentToolCapability::WriteFile),
+            "Write"
+        );
+    }
+
     #[test]
     fn model_config_outage_logging_is_deduplicated_and_does_not_expose_error_values() {
         let logged = AtomicBool::new(false);
diff --git a/src/crates/assembly/core/src/function_agents/mod.rs b/src/crates/assembly/core/src/function_agents/mod.rs
index 622c6ecfc4..d6ca9c1b0e 100644
--- a/src/crates/assembly/core/src/function_agents/mod.rs
+++ b/src/crates/assembly/core/src/function_agents/mod.rs
@@ -9,9 +9,6 @@ pub use bitfun_product_domains::function_agents::common;
 #[path = "git-func-agent/mod.rs"]
 pub mod git_func_agent;
 
-#[path = "startchat-func-agent/mod.rs"]
-pub mod startchat_func_agent;
-
 pub mod port_adapters;
 
 // Re-export shared types from common module
@@ -21,7 +18,3 @@ pub use common::{AgentError, AgentErrorType, AgentResult, Language};
 pub use git_func_agent::{
     CommitFormat, CommitMessage, CommitMessageOptions, CommitType, GitFunctionAgent,
 };
-pub use startchat_func_agent::{
-    CurrentWorkState, GitWorkState, GreetingMessage, PredictedAction, QuickAction,
-    StartchatFunctionAgent, WorkStateAnalysis, WorkStateOptions,
-};
diff --git a/src/crates/assembly/core/src/function_agents/port_adapters.rs b/src/crates/assembly/core/src/function_agents/port_adapters.rs
index da9ae169a5..0b205a6f32 100644
--- a/src/crates/assembly/core/src/function_agents/port_adapters.rs
+++ b/src/crates/assembly/core/src/function_agents/port_adapters.rs
@@ -9,16 +9,12 @@ use bitfun_product_domains::function_agents::git_func_agent::{
 };
 use bitfun_product_domains::function_agents::ports::{
     CommitAiAnalysisRequest, FunctionAgentAiPort, FunctionAgentFuture, FunctionAgentGitPort,
-    GitCommitSnapshot, StartchatGitSnapshot, StartchatTimeSnapshot, WorkStateAiAnalysisRequest,
-};
-use bitfun_product_domains::function_agents::startchat_func_agent::{
-    build_work_state_analysis_prompt, parse_work_state_analysis_response, AIGeneratedAnalysis,
-    GitWorkState,
+    GitCommitSnapshot,
 };
 use bitfun_services_integrations::function_agents::FunctionAgentGitService;
 use log::{debug, error, warn};
 
-use crate::function_agents::common::{AgentError, AgentResult, Language};
+use crate::function_agents::common::{AgentError, AgentResult};
 use crate::infrastructure::ai::{AIClient, AIClientFactory};
 use crate::util::types::Message;
 
@@ -27,11 +23,8 @@ pub struct CoreCommitAiAnalysisService {
 }
 
 impl CoreCommitAiAnalysisService {
-    pub async fn new_with_agent_config(
-        factory: Arc<AIClientFactory>,
-        agent_name: &str,
-    ) -> AgentResult<Self> {
-        let ai_client = match factory.get_client_by_func_agent(agent_name).await {
+    pub async fn new_with_task_config(factory: Arc<AIClientFactory>) -> AgentResult<Self> {
+        let ai_client = match factory.get_git_commit_task_client().await {
             Ok(client) => client,
             Err(e) => {
                 error!("Failed to get AI client: {}", e);
@@ -102,115 +95,6 @@ impl CoreCommitAiAnalysisService {
     }
 }
 
-pub struct CoreWorkStateAiAnalysisService {
-    ai_client: Arc<AIClient>,
-}
-
-impl CoreWorkStateAiAnalysisService {
-    pub async fn new_with_agent_config(
-        factory: Arc<AIClientFactory>,
-        agent_name: &str,
-    ) -> AgentResult<Self> {
-        let ai_client = match factory.get_client_by_func_agent(agent_name).await {
-            Ok(client) => client,
-            Err(e) => {
-                error!("Failed to get AI client: {}", e);
-                return Err(AgentError::internal_error(format!(
-                    "Failed to get AI client: {}",
-                    e
-                )));
-            }
-        };
-
-        Ok(Self { ai_client })
-    }
-
-    pub async fn generate_complete_analysis(
-        &self,
-        git_state: &Option<GitWorkState>,
-        git_diff: &str,
-        language: &Language,
-    ) -> AgentResult<AIGeneratedAnalysis> {
-        let prompt = build_work_state_analysis_prompt(git_state, git_diff, language);
-
-        debug!(
-            "Calling AI to generate complete analysis: prompt_length={}",
-            prompt.len()
-        );
-
-        let response = self.call_ai(&prompt).await?;
-
-        self.parse_complete_analysis(&response)
-    }
-
-    async fn call_ai(&self, prompt: &str) -> AgentResult<String> {
-        debug!("Sending request to AI: prompt_length={}", prompt.len());
-
-        let messages = vec![Message::user(prompt.to_string())];
-        let response = self
-            .ai_client
-            .send_message(messages, None)
-            .await
-            .map_err(|e| {
-                error!("AI call failed: {}", e);
-                AgentError::internal_error(format!("AI call failed: {}", e))
-            })?;
-
-        debug!(
-            "AI response received: response_length={}",
-            response.text.len()
-        );
-
-        if response.text.is_empty() {
-            error!("AI response is empty");
-            Err(AgentError::internal_error(
-                "AI response is empty".to_string(),
-            ))
-        } else {
-            Ok(response.text)
-        }
-    }
-
-    fn parse_complete_analysis(&self, response: &str) -> AgentResult<AIGeneratedAnalysis> {
-        let parsed_analysis =
-            parse_work_state_analysis_response(response).inspect_err(|error| {
-                error!("{}, response: {}", error.message, response);
-            })?;
-
-        if parsed_analysis.predicted_actions_count < 3 {
-            warn!(
-                "AI generated insufficient predicted actions ({}), adding defaults",
-                parsed_analysis.predicted_actions_count
-            );
-        } else if parsed_analysis.predicted_actions_count > 3 {
-            warn!(
-                "AI generated too many predicted actions ({}), truncating to 3",
-                parsed_analysis.predicted_actions_count
-            );
-        }
-
-        if parsed_analysis.quick_actions_count < 6 {
-            warn!(
-                "AI generated insufficient quick actions ({}), frontend will use defaults",
-                parsed_analysis.quick_actions_count
-            );
-        } else if parsed_analysis.quick_actions_count > 6 {
-            warn!(
-                "AI generated too many quick actions ({}), truncating to 6",
-                parsed_analysis.quick_actions_count
-            );
-        }
-
-        debug!(
-            "Parsing completed: predicted_actions={}, quick_actions={}",
-            parsed_analysis.analysis.predicted_actions.len(),
-            parsed_analysis.analysis.quick_actions.len()
-        );
-
-        Ok(parsed_analysis.analysis)
-    }
-}
-
 #[derive(Debug, Default, Clone)]
 pub struct CoreFunctionAgentGitAdapter;
 
@@ -221,20 +105,6 @@ impl FunctionAgentGitPort for CoreFunctionAgentGitAdapter {
     ) -> FunctionAgentFuture<'_, GitCommitSnapshot> {
         Box::pin(async move { FunctionAgentGitService::git_commit_snapshot(repo_path).await })
     }
-
-    fn startchat_git_snapshot(
-        &self,
-        repo_path: PathBuf,
-    ) -> FunctionAgentFuture<'_, StartchatGitSnapshot> {
-        Box::pin(async move { FunctionAgentGitService::startchat_git_snapshot(repo_path).await })
-    }
-
-    fn startchat_time_snapshot(
-        &self,
-        repo_path: PathBuf,
-    ) -> FunctionAgentFuture<'_, StartchatTimeSnapshot> {
-        Box::pin(async move { Ok(FunctionAgentGitService::startchat_time_snapshot(&repo_path)) })
-    }
 }
 
 #[derive(Clone)]
@@ -255,9 +125,7 @@ impl FunctionAgentAiPort for CoreFunctionAgentAiAdapter {
     ) -> FunctionAgentFuture<'_, AICommitAnalysis> {
         let factory = self.factory.clone();
         Box::pin(async move {
-            let service =
-                CoreCommitAiAnalysisService::new_with_agent_config(factory, "git-func-agent")
-                    .await?;
+            let service = CoreCommitAiAnalysisService::new_with_task_config(factory).await?;
             service
                 .generate_commit_message_ai(
                     &request.diff_content,
@@ -267,27 +135,6 @@ impl FunctionAgentAiPort for CoreFunctionAgentAiAdapter {
                 .await
         })
     }
-
-    fn analyze_work_state(
-        &self,
-        request: WorkStateAiAnalysisRequest,
-    ) -> FunctionAgentFuture<'_, AIGeneratedAnalysis> {
-        let factory = self.factory.clone();
-        Box::pin(async move {
-            let service = CoreWorkStateAiAnalysisService::new_with_agent_config(
-                factory,
-                "startchat-func-agent",
-            )
-            .await?;
-            service
-                .generate_complete_analysis(
-                    &request.git_state,
-                    &request.git_diff,
-                    &request.language,
-                )
-                .await
-        })
-    }
 }
 
 #[cfg(test)]
@@ -302,9 +149,7 @@ mod tests {
     use crate::product_domain_runtime::CoreProductDomainRuntime;
     use crate::util::types::AIConfig;
 
-    use super::{
-        CoreCommitAiAnalysisService, CoreFunctionAgentGitAdapter, CoreWorkStateAiAnalysisService,
-    };
+    use super::{CoreCommitAiAnalysisService, CoreFunctionAgentGitAdapter};
 
     fn test_ai_client() -> Arc<super::AIClient> {
         Arc::new(super::AIClient::new(AIConfig {
@@ -365,54 +210,6 @@ mod tests {
         assert_eq!(missing_title.message, "Missing title field");
     }
 
-    #[test]
-    fn parse_complete_analysis_preserves_product_domain_response_policy() {
-        let service = CoreWorkStateAiAnalysisService {
-            ai_client: test_ai_client(),
-        };
-        let analysis = service
-            .parse_complete_analysis(
-                r#"The answer is:
-```json
-{
-  "summary": "Working on product-domain owner closure.",
-  "predicted_actions": [
-    {"description": "Run checks", "priority": "High", "icon": "check", "is_reminder": false}
-  ],
-  "quick_actions": [
-    {"title": "Status", "command": "git status", "icon": "git", "action_type": "ViewStatus"}
-  ]
-}
-```
-"#,
-            )
-            .unwrap();
-
-        assert_eq!(analysis.summary, "Working on product-domain owner closure.");
-        assert_eq!(analysis.predicted_actions.len(), 3);
-        assert_eq!(analysis.quick_actions.len(), 1);
-
-        let missing_json = service.parse_complete_analysis("no json here").unwrap_err();
-        assert_eq!(missing_json.error_type, AgentErrorType::InternalError);
-        assert_eq!(
-            missing_json.message,
-            "Failed to extract JSON from analysis response"
-        );
-
-        let invalid_json = service
-            .parse_complete_analysis(
-                r#"```json
-not json
-```"#,
-            )
-            .unwrap_err();
-        assert_eq!(invalid_json.error_type, AgentErrorType::InternalError);
-        assert_eq!(
-            invalid_json.message,
-            "Failed to extract JSON from analysis response"
-        );
-    }
-
     struct TestTempDir {
         path: PathBuf,
     }
@@ -492,73 +289,6 @@ not json
         assert!(!snapshot.diff_content.contains("unstaged only"));
     }
 
-    #[tokio::test]
-    async fn git_adapter_builds_startchat_snapshot_without_changing_git_semantics() {
-        let repo = TestTempDir::new("startchat-snapshot");
-        init_git_repo(repo.path());
-        fs::write(repo.path().join("tracked.txt"), "base\n").unwrap();
-        git(repo.path(), &["add", "tracked.txt"]);
-        git(repo.path(), &["commit", "-m", "initial"]);
-        fs::write(repo.path().join("tracked.txt"), "base\nchange\n").unwrap();
-        fs::write(repo.path().join("staged.txt"), "staged\n").unwrap();
-        git(repo.path(), &["add", "staged.txt"]);
-
-        let adapter = CoreFunctionAgentGitAdapter;
-        let snapshot = adapter
-            .startchat_git_snapshot(repo.path().to_path_buf())
-            .await
-            .unwrap();
-
-        assert_eq!(snapshot.current_branch, "main");
-        assert!(snapshot.status_porcelain.contains(" M tracked.txt"));
-        assert!(snapshot.status_porcelain.contains("A  staged.txt"));
-        assert!(snapshot.unstaged_diff.contains("change"));
-        assert!(snapshot.staged_diff.contains("staged.txt"));
-        assert_eq!(snapshot.unpushed_commits, 0);
-        assert!(snapshot.ahead_behind.is_none());
-        assert!(snapshot.last_commit_timestamp.is_some());
-    }
-
-    #[tokio::test]
-    async fn git_adapter_startchat_snapshot_preserves_git_state_when_diff_has_no_head() {
-        let repo = TestTempDir::new("startchat-no-head-diff");
-        init_git_repo(repo.path());
-        fs::write(repo.path().join("new.txt"), "new\n").unwrap();
-
-        let adapter = CoreFunctionAgentGitAdapter;
-        let snapshot = adapter
-            .startchat_git_snapshot(repo.path().to_path_buf())
-            .await
-            .unwrap();
-
-        assert_eq!(snapshot.current_branch, "main");
-        assert!(snapshot.status_porcelain.contains("?? new.txt"));
-        assert!(snapshot.unstaged_diff.is_empty());
-        assert!(snapshot.staged_diff.is_empty());
-        assert_eq!(snapshot.unpushed_commits, 0);
-        assert!(snapshot.ahead_behind.is_none());
-        assert!(snapshot.last_commit_timestamp.is_none());
-    }
-
-    #[tokio::test]
-    async fn git_adapter_startchat_snapshot_matches_legacy_empty_state_when_not_git_repo() {
-        let repo = TestTempDir::new("not-a-git-repo");
-
-        let adapter = CoreFunctionAgentGitAdapter;
-        let snapshot = adapter
-            .startchat_git_snapshot(repo.path().to_path_buf())
-            .await
-            .unwrap();
-
-        assert!(snapshot.current_branch.is_empty());
-        assert!(snapshot.status_porcelain.is_empty());
-        assert!(snapshot.unstaged_diff.is_empty());
-        assert!(snapshot.staged_diff.is_empty());
-        assert_eq!(snapshot.unpushed_commits, 0);
-        assert!(snapshot.ahead_behind.is_none());
-        assert!(snapshot.last_commit_timestamp.is_none());
-    }
-
     #[test]
     fn core_product_domain_runtime_owner_constructs_function_agent_git_adapter() {
         let _adapter = CoreProductDomainRuntime::function_agent_git_adapter();
diff --git a/src/crates/assembly/core/src/function_agents/startchat-func-agent/ai_service.rs b/src/crates/assembly/core/src/function_agents/startchat-func-agent/ai_service.rs
deleted file mode 100644
index 85b8c5538a..0000000000
--- a/src/crates/assembly/core/src/function_agents/startchat-func-agent/ai_service.rs
+++ /dev/null
@@ -1 +0,0 @@
-pub use crate::function_agents::port_adapters::CoreWorkStateAiAnalysisService as AIWorkStateService;
diff --git a/src/crates/assembly/core/src/function_agents/startchat-func-agent/mod.rs b/src/crates/assembly/core/src/function_agents/startchat-func-agent/mod.rs
deleted file mode 100644
index 714e1854bd..0000000000
--- a/src/crates/assembly/core/src/function_agents/startchat-func-agent/mod.rs
+++ /dev/null
@@ -1,68 +0,0 @@
-pub mod ai_service;
-/**
- * Startchat Function Agent - module entry
- *
- * Provides work state analysis and greeting generation on session start
- */
-pub use bitfun_product_domains::function_agents::startchat_func_agent::types;
-pub mod utils;
-pub mod work_state_analyzer;
-
-pub use ai_service::AIWorkStateService;
-pub use types::*;
-pub use work_state_analyzer::WorkStateAnalyzer;
-
-use crate::infrastructure::ai::AIClientFactory;
-use crate::product_domain_runtime::CoreProductDomainRuntime;
-use std::path::Path;
-use std::sync::Arc;
-
-/// Combines work state analysis and greeting generation
-pub struct StartchatFunctionAgent {
-    factory: Arc<AIClientFactory>,
-}
-
-impl StartchatFunctionAgent {
-    pub fn new(factory: Arc<AIClientFactory>) -> Self {
-        Self { factory }
-    }
-
-    /// Analyze work state and generate greeting
-    pub async fn analyze_work_state(
-        &self,
-        repo_path: &Path,
-        options: WorkStateOptions,
-    ) -> AgentResult<WorkStateAnalysis> {
-        CoreProductDomainRuntime::analyze_function_agent_work_state(
-            self.factory.clone(),
-            repo_path,
-            options,
-        )
-        .await
-    }
-
-    /// Quickly analyze work state (use default options with specified language)
-    pub async fn quick_analyze(
-        &self,
-        repo_path: &Path,
-        language: crate::function_agents::Language,
-    ) -> AgentResult<WorkStateAnalysis> {
-        let options = WorkStateOptions {
-            language,
-            ..WorkStateOptions::default()
-        };
-        self.analyze_work_state(repo_path, options).await
-    }
-
-    /// Generate greeting only (do not analyze Git status)
-    pub async fn generate_greeting_only(&self, repo_path: &Path) -> AgentResult<WorkStateAnalysis> {
-        let options = WorkStateOptions {
-            analyze_git: false,
-            predict_next_actions: false,
-            include_quick_actions: false,
-            language: crate::function_agents::Language::Chinese,
-        };
-
-        self.analyze_work_state(repo_path, options).await
-    }
-}
diff --git a/src/crates/assembly/core/src/function_agents/startchat-func-agent/utils.rs b/src/crates/assembly/core/src/function_agents/startchat-func-agent/utils.rs
deleted file mode 100644
index b3da324834..0000000000
--- a/src/crates/assembly/core/src/function_agents/startchat-func-agent/utils.rs
+++ /dev/null
@@ -1,3 +0,0 @@
-//! Startchat function-agent helper compatibility facade.
-
-pub use bitfun_product_domains::function_agents::startchat_func_agent::utils::*;
diff --git a/src/crates/assembly/core/src/function_agents/startchat-func-agent/work_state_analyzer.rs b/src/crates/assembly/core/src/function_agents/startchat-func-agent/work_state_analyzer.rs
deleted file mode 100644
index 6a93874ad0..0000000000
--- a/src/crates/assembly/core/src/function_agents/startchat-func-agent/work_state_analyzer.rs
+++ /dev/null
@@ -1,20 +0,0 @@
-use super::types::*;
-use crate::function_agents::common::AgentResult;
-use crate::infrastructure::ai::AIClientFactory;
-use crate::product_domain_runtime::CoreProductDomainRuntime;
-use std::path::Path;
-use std::sync::Arc;
-
-/// Compatibility facade for the legacy work-state analyzer import path.
-pub struct WorkStateAnalyzer;
-
-impl WorkStateAnalyzer {
-    pub async fn analyze_work_state(
-        factory: Arc<AIClientFactory>,
-        repo_path: &Path,
-        options: WorkStateOptions,
-    ) -> AgentResult<WorkStateAnalysis> {
-        CoreProductDomainRuntime::analyze_function_agent_work_state(factory, repo_path, options)
-            .await
-    }
-}
diff --git a/src/crates/assembly/core/src/infrastructure/ai/client_factory.rs b/src/crates/assembly/core/src/infrastructure/ai/client_factory.rs
index c2d4c6a5f6..d595314ad3 100644
--- a/src/crates/assembly/core/src/infrastructure/ai/client_factory.rs
+++ b/src/crates/assembly/core/src/infrastructure/ai/client_factory.rs
@@ -12,13 +12,14 @@ use crate::infrastructure::ai::reasoning_catalog::{
     resolve_default_reasoning_preset,
 };
 use crate::infrastructure::ai::{build_stream_options_for_model, AIClient};
+#[cfg(feature = "subscription-auth")]
 use crate::infrastructure::subscription_auth::{
     self, OpenCodePlan as AdapterOpenCodePlan, SubscriptionHttpOptions,
     SubscriptionProvider as AdapterProvider,
 };
-use crate::service::config::types::{
-    model_runtime_binding_fingerprint, AuthConfig, OpenCodePlan, SubscriptionProvider,
-};
+use crate::service::config::types::{model_runtime_binding_fingerprint, AuthConfig};
+#[cfg(feature = "subscription-auth")]
+use crate::service::config::types::{OpenCodePlan, SubscriptionProvider};
 use crate::service::config::{get_global_config_service, ConfigService};
 use crate::util::errors::{BitFunError, BitFunResult};
 use crate::util::types::AIConfig;
@@ -37,8 +38,8 @@ struct CachedAIClient {
     configuration_fingerprint: String,
     default_reasoning_preset: Option<bitfun_core_types::ReasoningPresetDescriptor>,
     client: Arc<AIClient>,
-    /// Unix seconds when the resolved subscription credential expires;
-    /// `None` for API-key auth or non-expiring credentials.
+    /// Unix seconds when the resolved subscription credential expires.
+    #[cfg(feature = "subscription-auth")]
     credential_expires_at: Option<i64>,
 }
 
@@ -46,8 +47,10 @@ struct CachedAIClient {
 /// client is rebuilt so subscription authentication refreshes the token. Kept
 /// equal to the providers' refresh leeway so the rebuilt client always gets a
 /// fresh token.
+#[cfg(feature = "subscription-auth")]
 const SUBSCRIPTION_CREDENTIAL_STALE_LEEWAY_SECS: i64 = 5 * 60;
 
+#[cfg(feature = "subscription-auth")]
 fn now_unix_secs() -> i64 {
     std::time::SystemTime::now()
         .duration_since(std::time::UNIX_EPOCH)
@@ -55,6 +58,7 @@ fn now_unix_secs() -> i64 {
         .unwrap_or(0)
 }
 
+#[cfg(feature = "subscription-auth")]
 fn subscription_credential_stale(auth: &AuthConfig, cached: &CachedAIClient) -> bool {
     if !matches!(auth, AuthConfig::Subscription { .. }) {
         return false;
@@ -64,15 +68,9 @@ fn subscription_credential_stale(auth: &AuthConfig, cached: &CachedAIClient) ->
     })
 }
 
-fn functional_agent_model_selector<'a>(
-    ai_config: &'a crate::service::config::types::AIConfig,
-    func_agent_name: &str,
-) -> &'a str {
-    ai_config
-        .func_agent_models
-        .get(func_agent_name)
-        .map(String::as_str)
-        .unwrap_or("fast")
+#[cfg(not(feature = "subscription-auth"))]
+fn subscription_credential_stale(auth: &AuthConfig, _cached: &CachedAIClient) -> bool {
+    matches!(auth, AuthConfig::Subscription { .. })
 }
 
 impl AIClientFactory {
@@ -83,20 +81,23 @@ impl AIClientFactory {
         }
     }
 
-    /// Get a functional agent's AI client using its dedicated mapping or fast.
-    pub async fn get_client_by_func_agent(&self, func_agent_name: &str) -> Result<Arc<AIClient>> {
+    pub async fn get_client_by_id(&self, model_id: &str) -> Result<Arc<AIClient>> {
+        self.get_or_create_client(model_id, None).await
+    }
+
+    /// Resolve the fixed model configured for Git commit-message generation.
+    pub async fn get_git_commit_task_client(&self) -> Result<Arc<AIClient>> {
         let global_config: crate::service::config::GlobalConfig =
             self.config_service.get_config(None).await?;
-
-        let model_id = functional_agent_model_selector(&global_config.ai, func_agent_name);
-
+        let model_id = global_config
+            .ai
+            .task_models
+            .git_commit
+            .fixed_model_id()
+            .ok_or_else(|| anyhow!("Git commit task model cannot inherit a session model"))?;
         self.get_client_resolved(model_id).await
     }
 
-    pub async fn get_client_by_id(&self, model_id: &str) -> Result<Arc<AIClient>> {
-        self.get_or_create_client(model_id, None).await
-    }
-
     /// Resolves an immutable concrete model id only when its current runtime
     /// identity still matches the user-approved binding.
     pub async fn get_client_by_approved_binding(
@@ -317,14 +318,15 @@ impl AIClientFactory {
         } else {
             None
         };
-        let subscription_options =
-            SubscriptionHttpOptions::new(proxy_config.clone(), skip_ssl_verify);
-        let credential_expires_at = apply_subscription_auth_with_options(
+        let credential_expires_at = apply_configured_auth(
             &model_config.auth,
             &mut ai_config,
-            &subscription_options,
+            proxy_config.clone(),
+            skip_ssl_verify,
         )
         .await?;
+        #[cfg(not(feature = "subscription-auth"))]
+        let _ = credential_expires_at;
 
         let stream_options = build_stream_options_for_model(&global_config.ai, Some(model_config));
         let client = apply_default_reasoning_preset(
@@ -349,6 +351,7 @@ impl AIClientFactory {
                     configuration_fingerprint,
                     default_reasoning_preset,
                     client: client.clone(),
+                    #[cfg(feature = "subscription-auth")]
                     credential_expires_at,
                 },
             );
@@ -434,6 +437,7 @@ pub async fn initialize_global_ai_client_factory() -> BitFunResult<()> {
     AIClientFactory::initialize_global().await
 }
 
+#[cfg(feature = "subscription-auth")]
 fn to_adapter_provider(provider: SubscriptionProvider) -> AdapterProvider {
     match provider {
         SubscriptionProvider::Codex => AdapterProvider::Codex,
@@ -442,6 +446,7 @@ fn to_adapter_provider(provider: SubscriptionProvider) -> AdapterProvider {
     }
 }
 
+#[cfg(feature = "subscription-auth")]
 fn to_adapter_opencode_plan(plan: OpenCodePlan) -> AdapterOpenCodePlan {
     match plan {
         OpenCodePlan::Zen => AdapterOpenCodePlan::Zen,
@@ -457,10 +462,49 @@ pub async fn apply_subscription_auth(
     auth: &AuthConfig,
     ai_config: &mut AIConfig,
 ) -> Result<Option<i64>> {
-    apply_subscription_auth_with_options(auth, ai_config, &SubscriptionHttpOptions::default()).await
+    #[cfg(feature = "subscription-auth")]
+    return apply_subscription_auth_with_options(
+        auth,
+        ai_config,
+        &SubscriptionHttpOptions::default(),
+    )
+    .await;
+
+    #[cfg(not(feature = "subscription-auth"))]
+    {
+        let _ = ai_config;
+        match auth {
+            AuthConfig::ApiKey => Ok(None),
+            AuthConfig::Subscription { .. } => Err(anyhow!(
+                "Subscription authentication is not available in this product build"
+            )),
+        }
+    }
+}
+
+#[cfg(feature = "subscription-auth")]
+async fn apply_configured_auth(
+    auth: &AuthConfig,
+    ai_config: &mut AIConfig,
+    proxy_config: Option<bitfun_core_types::ProxyConfig>,
+    skip_ssl_verify: bool,
+) -> Result<Option<i64>> {
+    let options = SubscriptionHttpOptions::new(proxy_config, skip_ssl_verify);
+    apply_subscription_auth_with_options(auth, ai_config, &options).await
+}
+
+#[cfg(not(feature = "subscription-auth"))]
+async fn apply_configured_auth(
+    auth: &AuthConfig,
+    ai_config: &mut AIConfig,
+    _proxy_config: Option<bitfun_core_types::ProxyConfig>,
+    _skip_ssl_verify: bool,
+) -> Result<Option<i64>> {
+    apply_subscription_auth(auth, ai_config).await
 }
 
 /// Resolves subscription authentication with an explicit transport policy.
+#[cfg(feature = "subscription-auth")]
 pub async fn apply_subscription_auth_with_options(
     auth: &AuthConfig,
     ai_config: &mut AIConfig,
@@ -527,15 +571,20 @@ pub async fn apply_subscription_auth_with_options(
 }
 
 /// List subscription accounts (Codex / Antigravity / OpenCode).
+#[cfg(feature = "subscription-auth")]
 pub async fn list_subscription_accounts() -> Vec<subscription_auth::SubscriptionAccount> {
     subscription_auth::list_accounts().await
 }
 
 #[cfg(test)]
 mod tests {
+    use super::apply_subscription_auth;
+    #[cfg(not(feature = "subscription-auth"))]
+    use crate::service::config::types::SubscriptionProvider;
     use crate::service::config::types::{
-        model_runtime_binding_fingerprint, AIModelConfig, GlobalConfig,
+        model_runtime_binding_fingerprint, AIModelConfig, AuthConfig, GlobalConfig,
     };
+    use crate::util::types::AIConfig;
     use bitfun_ai_adapters::{
         classify_model_selector, resolve_required_model_selector, ModelSelectorKind,
     };
@@ -551,6 +600,60 @@ mod tests {
         }
     }
 
+    fn test_runtime_ai_config() -> AIConfig {
+        AIConfig {
+            name: "test".to_string(),
+            base_url: "https://example.test".to_string(),
+            request_url: String::new(),
+            api_key: "unchanged".to_string(),
+            model: "test-model".to_string(),
+            format: "openai".to_string(),
+            context_window: 4096,
+            max_tokens: None,
+            temperature: None,
+            top_p: None,
+            inline_think_in_text: false,
+            custom_headers: None,
+            custom_headers_mode: None,
+            skip_ssl_verify: false,
+            custom_request_body: None,
+            custom_request_body_mode: None,
+        }
+    }
+
+    #[cfg(feature = "subscription-auth")]
+    #[tokio::test]
+    async fn api_key_auth_remains_a_noop_when_subscription_support_is_compiled() {
+        let mut config = test_runtime_ai_config();
+
+        let expires_at = apply_subscription_auth(&AuthConfig::ApiKey, &mut config)
+            .await
+            .expect("API-key auth");
+
+        assert_eq!(expires_at, None);
+        assert_eq!(config.api_key, "unchanged");
+        assert_eq!(config.base_url, "https://example.test");
+    }
+
+    #[cfg(not(feature = "subscription-auth"))]
+    #[tokio::test]
+    async fn subscription_auth_fails_closed_when_not_compiled() {
+        let auth = AuthConfig::Subscription {
+            provider: SubscriptionProvider::Codex,
+            plan: None,
+        };
+        let mut config = test_runtime_ai_config();
+
+        let error = apply_subscription_auth(&auth, &mut config)
+            .await
+            .expect_err("subscription auth must not degrade to an API-key client");
+
+        assert!(error
+            .to_string()
+            .contains("Subscription authentication is not available"));
+        assert_eq!(config.api_key, "unchanged");
+    }
+
     #[test]
     fn resolve_model_reference_requires_a_config_id() {
         let mut config = GlobalConfig::default();
diff --git a/src/crates/assembly/core/src/infrastructure/ai/reasoning_catalog.rs b/src/crates/assembly/core/src/infrastructure/ai/reasoning_catalog.rs
index 587165e759..e903d9a312 100644
--- a/src/crates/assembly/core/src/infrastructure/ai/reasoning_catalog.rs
+++ b/src/crates/assembly/core/src/infrastructure/ai/reasoning_catalog.rs
@@ -8,6 +8,8 @@ use bitfun_ai_adapters::models_dev::{
     project_reasoning_catalog_with_limit_and_auto_binding, ModelsDevCatalog,
 };
 #[cfg(feature = "model-catalog")]
+use bitfun_core_types::ReasoningCatalogProjectionRequest;
+#[cfg(feature = "model-catalog")]
 use bitfun_core_types::{
     ModelsDevCatalogSource, ModelsDevCatalogStatus, ModelsDevRefreshResult, ModelsDevRefreshStatus,
 };
@@ -22,6 +24,7 @@ use bitfun_services_integrations::models_dev::{
 };
 #[cfg(feature = "model-catalog")]
 use log::debug;
+use sha2::{Digest, Sha256};
 
 use crate::infrastructure::ai::provider_catalog::trusted_models_dev_binding;
 use crate::infrastructure::ai::AIClient;
@@ -317,6 +320,25 @@ pub(crate) fn project_model_reasoning_catalog(
     )
 }
 
+#[cfg(feature = "model-catalog")]
+pub(crate) async fn project_reasoning_catalog_request(
+    request: ReasoningCatalogProjectionRequest,
+) -> ReasoningCatalogProjection {
+    let models_dev = load_models_dev_reasoning_catalog().await;
+    project_model_reasoning_catalog(
+        &AIModelConfig {
+            provider: request.provider,
+            model_name: request.model_name,
+            base_url: request.base_url,
+            context_window: request.context_window,
+            max_tokens: request.max_tokens,
+            reasoning: Some(request.reasoning),
+            ..Default::default()
+        },
+        models_dev.catalog.as_deref(),
+    )
+}
+
 pub(crate) fn resolve_reasoning_preset<'a>(
     projection: &'a ReasoningCatalogProjection,
     preset_id: &str,
@@ -328,6 +350,22 @@ pub(crate) fn resolve_reasoning_preset<'a>(
         .find(|preset| preset.id == preset_id)
 }
 
+pub(crate) fn reasoning_preset_runtime_fingerprint(
+    preset: Option<&ReasoningPresetDescriptor>,
+) -> String {
+    let value = preset.map_or(serde_json::Value::Null, |preset| {
+        serde_json::json!({
+            "id": preset.id,
+            "actions": preset.actions,
+            "source": preset.source,
+            "execution_provider": preset.execution_provider,
+            "execution_model": preset.execution_model,
+        })
+    });
+    let encoded = serde_json::to_vec(&value).unwrap_or_default();
+    format!("{:x}", Sha256::digest(encoded))
+}
+
 /// Normalizes a session-scoped reasoning preset against one concrete model.
 ///
 /// `None` is the canonical Auto state. A configured preset can always be
@@ -406,19 +444,46 @@ pub(crate) fn apply_selected_reasoning_preset(
 #[cfg(test)]
 mod tests {
     use bitfun_core_types::{
-        ReasoningCatalogBinding, ReasoningConfig, ReasoningPreset, ReasoningPresetAction,
-        ReasoningPresetSource,
+        ReasoningCatalogBinding, ReasoningCatalogProjectionRequest, ReasoningConfig,
+        ReasoningPreset, ReasoningPresetAction, ReasoningPresetDescriptor, ReasoningPresetSource,
     };
 
     use super::{
         apply_default_reasoning_preset, apply_selected_reasoning_preset,
         normalize_reasoning_preset_for_model, project_model_reasoning_catalog,
-        resolve_default_reasoning_preset, resolve_reasoning_preset, ModelsDevCatalog,
+        reasoning_preset_runtime_fingerprint, resolve_default_reasoning_preset,
+        resolve_reasoning_preset, ModelsDevCatalog,
     };
     use crate::infrastructure::ai::AIClient;
     use crate::service::config::types::AIModelConfig;
     use crate::util::types::AIConfig;
 
+    #[test]
+    fn runtime_fingerprint_detects_same_id_action_drift() {
+        let preset = ReasoningPresetDescriptor {
+            id: "high".to_string(),
+            label: "High".to_string(),
+            order: 1,
+            actions: vec![ReasoningPresetAction::Effort {
+                value: "high".to_string(),
+            }],
+            source: ReasoningPresetSource::ModelsDev,
+            execution_provider: Some("openai".to_string()),
+            execution_model: Some("model-v1".to_string()),
+        };
+        let mut changed = preset.clone();
+        changed.actions = vec![ReasoningPresetAction::BudgetTokens { value: 32_000 }];
+
+        assert_ne!(
+            reasoning_preset_runtime_fingerprint(Some(&preset)),
+            reasoning_preset_runtime_fingerprint(Some(&changed)),
+        );
+        assert_ne!(
+            reasoning_preset_runtime_fingerprint(None),
+            reasoning_preset_runtime_fingerprint(Some(&preset)),
+        );
+    }
+
     fn catalog() -> ModelsDevCatalog {
         ModelsDevCatalog::parse_str(
             r#"{
@@ -494,6 +559,45 @@ mod tests {
         assert_eq!(resolve_default_reasoning_preset(&projection), Some(high));
     }
 
+    #[test]
+    fn projection_request_shape_projects_explicit_models_dev_presets() {
+        let request = ReasoningCatalogProjectionRequest {
+            provider: "responses".to_string(),
+            model_name: "gateway-alias".to_string(),
+            base_url: "https://gateway.example.com/v1/responses".to_string(),
+            context_window: Some(128_000),
+            max_tokens: Some(8_192),
+            reasoning: ReasoningConfig {
+                catalog: ReasoningCatalogBinding::ModelsDev {
+                    provider: "openai".to_string(),
+                    model: "gpt-test".to_string(),
+                },
+                ..Default::default()
+            },
+        };
+        let projection = project_model_reasoning_catalog(
+            &AIModelConfig {
+                provider: request.provider,
+                model_name: request.model_name,
+                base_url: request.base_url,
+                context_window: request.context_window,
+                max_tokens: request.max_tokens,
+                reasoning: Some(request.reasoning),
+                ..Default::default()
+            },
+            Some(&catalog()),
+        );
+
+        assert_eq!(
+            projection
+                .presets
+                .iter()
+                .map(|preset| preset.id.as_str())
+                .collect::<Vec<_>>(),
+            ["low", "high"]
+        );
+    }
+
     #[test]
     fn openbitfun_models_use_their_exact_upstream_reasoning_catalogs() {
         for (provider, base_url) in [
diff --git a/src/crates/assembly/core/src/infrastructure/debug_log/types.rs b/src/crates/assembly/core/src/infrastructure/debug_log/types.rs
index 2229811829..250f15f279 100644
--- a/src/crates/assembly/core/src/infrastructure/debug_log/types.rs
+++ b/src/crates/assembly/core/src/infrastructure/debug_log/types.rs
@@ -4,6 +4,7 @@
 //! and writes them to the local NDJSON log file.
 
 use super::{DebugLogConfig, DebugLogEntry};
+#[cfg(feature = "workspace-runtime")]
 use crate::service::workspace::get_global_workspace_service;
 use anyhow::Result;
 use log::debug;
@@ -108,14 +109,16 @@ pub async fn handle_ingest(
     request: IngestLogRequest,
     config: &DebugLogConfig,
 ) -> Result<IngestResponse> {
+    let log_config = config.clone();
+    #[cfg(feature = "workspace-runtime")]
     let log_config = if let Some(workspace_path) =
         get_global_workspace_service().and_then(|service| service.try_get_current_workspace_path())
     {
-        let mut cfg = config.clone();
+        let mut cfg = log_config;
         cfg.log_path = workspace_path.join(".bitfun").join("debug.log");
         cfg
     } else {
-        config.clone()
+        log_config
     };
 
     let entry: DebugLogEntry = request.into();
@@ -128,3 +131,38 @@ pub async fn handle_ingest(
         error: None,
     })
 }
+
+#[cfg(all(test, not(feature = "workspace-runtime")))]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn standalone_debug_log_uses_the_configured_path() {
+        let temp = tempfile::tempdir().expect("temp directory");
+        let log_path = temp.path().join("standalone").join("debug.log");
+        let config = DebugLogConfig {
+            log_path: log_path.clone(),
+            ingest_url: None,
+            session_id: "standalone-session".to_string(),
+        };
+
+        handle_ingest(
+            IngestLogRequest {
+                location: "standalone-test".to_string(),
+                message: "uses configured path".to_string(),
+                data: serde_json::Value::Null,
+                session_id: None,
+                run_id: None,
+                hypothesis_id: None,
+                timestamp: Some(1),
+            },
+            &config,
+        )
+        .await
+        .expect("ingest succeeds without the workspace runtime");
+
+        let contents = std::fs::read_to_string(log_path).expect("configured log is written");
+        assert!(contents.contains("\"location\":\"standalone-test\""));
+        assert!(contents.contains("\"sessionId\":\"standalone-session\""));
+    }
+}
diff --git a/src/crates/assembly/core/src/infrastructure/events/mod.rs b/src/crates/assembly/core/src/infrastructure/events/mod.rs
index 15d868255a..3f647954ab 100644
--- a/src/crates/assembly/core/src/infrastructure/events/mod.rs
+++ b/src/crates/assembly/core/src/infrastructure/events/mod.rs
@@ -4,7 +4,6 @@ pub mod emitter;
 #[cfg(feature = "runtime-services")]
 pub mod event_system;
 
-pub use bitfun_transport::TransportEmitter;
 pub use emitter::EventEmitter;
 #[cfg(feature = "runtime-services")]
 pub use event_system::BackendEventSystem as BackendEventManager;
diff --git a/src/crates/assembly/core/src/infrastructure/mod.rs b/src/crates/assembly/core/src/infrastructure/mod.rs
index d3ca11ed52..d4161db898 100644
--- a/src/crates/assembly/core/src/infrastructure/mod.rs
+++ b/src/crates/assembly/core/src/infrastructure/mod.rs
@@ -12,7 +12,7 @@ pub mod events;
 pub mod filesystem;
 #[cfg(feature = "local-storage")]
 pub mod storage;
-#[cfg(feature = "ai-adapter-runtime")]
+#[cfg(all(feature = "ai-adapter-runtime", feature = "subscription-auth"))]
 pub mod subscription_auth;
 
 #[cfg(feature = "ai-adapter-runtime")]
diff --git a/src/crates/assembly/core/src/lib.rs b/src/crates/assembly/core/src/lib.rs
index ac5bb707c7..77ef2c8c49 100644
--- a/src/crates/assembly/core/src/lib.rs
+++ b/src/crates/assembly/core/src/lib.rs
@@ -78,6 +78,13 @@ pub async fn get_ai_model_catalog() -> Result<AIModelCatalog, String> {
     service_agent_runtime::CoreServiceAgentRuntime::load_remote_model_catalog(None).await
 }
 
+#[cfg(feature = "model-catalog")]
+pub async fn project_ai_model_reasoning_catalog(
+    request: bitfun_core_types::ReasoningCatalogProjectionRequest,
+) -> bitfun_core_types::ReasoningCatalogProjection {
+    infrastructure::ai::reasoning_catalog::project_reasoning_catalog_request(request).await
+}
+
 #[cfg(feature = "model-catalog")]
 pub async fn get_models_dev_catalog_status() -> bitfun_core_types::ModelsDevCatalogStatus {
     infrastructure::ai::reasoning_catalog::get_models_dev_catalog_status().await
diff --git a/src/crates/assembly/core/src/plugin_runtime.rs b/src/crates/assembly/core/src/plugin_runtime.rs
index a366d9d394..af1bf8e1d4 100644
--- a/src/crates/assembly/core/src/plugin_runtime.rs
+++ b/src/crates/assembly/core/src/plugin_runtime.rs
@@ -1,14 +1,15 @@
 //! Managed plugin composition.
 //!
-//! This is the only plugin-runtime root that selects the OpenCode-compatible
-//! adapter and PluginRuntimeClient. Workspace identity here scopes source,
+//! This is the only plugin-runtime root that selects managed-package ecosystem
+//! adapters and PluginRuntimeClient. Workspace identity here scopes source,
 //! approval, and logical client state; it is not a process ownership boundary.
 //! This module projects candidates for product surfaces; it does not register
 //! tools or execute plugin code.
 
 use async_trait::async_trait;
+use bitfun_dsh_adapter::load_dsh_package_adapter;
 use bitfun_opencode_adapter::load_opencode_package_adapter;
-use bitfun_plugin_runtime_client::DefaultPluginRuntimeClient;
+use bitfun_plugin_runtime_client::{DefaultPluginRuntimeClient, PluginRuntimeAdapter};
 use bitfun_product_domains::plugin_source::{
     PluginActivationAuthority, PluginPackageInput, PluginPackageSourceIdentity,
 };
@@ -16,8 +17,8 @@ use bitfun_runtime_ports::{
     PluginCapabilityRef, PluginDispatchEnvelope, PluginEffectCandidatePayload,
     PluginPermissionGate, PluginResponseEnvelope, PluginRiskLevel, PluginRuntimeAvailability,
     PluginRuntimeBinding, PluginRuntimeClient, PluginRuntimeEpochs, PluginRuntimeReadRequest,
-    PluginRuntimeReadResponse, PluginSourceRef, PluginTargetRef, PortError, PortErrorKind,
-    PortResult,
+    PluginRuntimeReadResponse, PluginSourceRef, PluginStatusKind, PluginTargetRef, PortError,
+    PortErrorKind, PortResult,
 };
 use bitfun_services_integrations::plugin_source::{
     ManagedPluginSourceError, ManagedPluginSourceIssue, ManagedPluginSourceService,
@@ -28,6 +29,8 @@ use std::time::{Duration, SystemTime, UNIX_EPOCH};
 
 const PREVIEW_PROJECT_ID: &str = "managed-plugin-preview";
 const PREVIEW_WORKSPACE_ID: &str = "managed-plugin-preview";
+const DSH_MANIFEST_ADAPTER_ID: &str = "dsh_compatible";
+const OPENCODE_MANIFEST_ADAPTER_ID: &str = "opencode_compatible";
 type PluginDispatchTarget = (
     PluginSourceRef,
     String,
@@ -35,6 +38,29 @@ type PluginDispatchTarget = (
     Vec<(PluginTargetRef, PluginRiskLevel)>,
 );
 
+fn load_package_adapter(
+    input: PluginPackageInput,
+    activation: Option<PluginActivationAuthority>,
+    observed_at_ms: u64,
+) -> Result<(Arc<dyn PluginRuntimeAdapter>, Vec<PluginDispatchTarget>), ManagedPluginSourceError> {
+    let (adapter, package_id) = {
+        let (manifest, source, _files) = input.clone().into_parts();
+        (manifest.adapter, source.package_id)
+    };
+    match adapter.as_str() {
+        OPENCODE_MANIFEST_ADAPTER_ID => {
+            load_opencode_package_adapter(input, activation, observed_at_ms)
+                .map_err(|error| invalid_package(&package_id, error.to_string()))
+        }
+        DSH_MANIFEST_ADAPTER_ID => load_dsh_package_adapter(input, activation, observed_at_ms)
+            .map_err(|error| invalid_package(&package_id, error.to_string())),
+        other => Err(invalid_package(
+            &package_id,
+            format!("unsupported managed package adapter: {other}"),
+        )),
+    }
+}
+
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ManagedPluginCandidateView {
     pub entry_id: String,
@@ -57,6 +83,11 @@ pub struct ManagedPluginActivationView {
     pub diagnostics: Vec<String>,
 }
 
+struct ManagedPluginPreview {
+    view: ManagedPluginActivationView,
+    activation_config_valid: bool,
+}
+
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum ManagedPluginDeactivationResult {
     Deactivated {
@@ -111,25 +142,41 @@ async fn preview_with_service(
     workspace: &Path,
     package_id: &str,
 ) -> Result<ManagedPluginActivationView, ManagedPluginSourceError> {
+    Ok(project_preview_with_service(service, workspace, package_id)
+        .await?
+        .view)
+}
+
+async fn project_preview_with_service(
+    service: Arc<ManagedPluginSourceService>,
+    workspace: &Path,
+    package_id: &str,
+) -> Result<ManagedPluginPreview, ManagedPluginSourceError> {
     let input = service.load_package(workspace, package_id).await?;
     let source = input.clone().into_parts().1;
-    let (adapter, dispatch_targets) = load_opencode_package_adapter(input, None, current_time_ms())
-        .map_err(|error| invalid_package(package_id, error.to_string()))?;
+    let (adapter, dispatch_targets) = load_package_adapter(input, None, current_time_ms())?;
     let binding = PluginRuntimeBinding::client(Arc::new(DefaultPluginRuntimeClient::new(adapter)));
     let response = binding
         .as_client()
         .read_plugins(read_request(PREVIEW_PROJECT_ID, PREVIEW_WORKSPACE_ID, 1))
         .await
         .map_err(|error| unavailable(package_id, error.to_string()))?;
+    let activation_config_valid = response
+        .plugin_statuses
+        .iter()
+        .all(|status| status.status != PluginStatusKind::InvalidConfig);
     let candidates = preview_candidates(&dispatch_targets);
-    Ok(project_view(
-        source,
-        false,
-        None,
-        !dispatch_targets.is_empty(),
-        response,
-        candidates,
-    ))
+    Ok(ManagedPluginPreview {
+        view: project_view(
+            source,
+            false,
+            None,
+            !dispatch_targets.is_empty(),
+            response,
+            candidates,
+        ),
+        activation_config_valid,
+    })
 }
 
 async fn activate_with_service(
@@ -144,14 +191,23 @@ async fn activate_with_service(
             "activation requires the exact content hash from the preview".to_string(),
         )
     })?;
-    let preview = preview_with_service(Arc::clone(&service), workspace, package_id).await?;
+    let ManagedPluginPreview {
+        view: preview,
+        activation_config_valid,
+    } = project_preview_with_service(Arc::clone(&service), workspace, package_id).await?;
     if preview.content_hash != expected_content_hash {
         return Err(invalid_package(
             package_id,
             "activation confirmation does not match the current package content".to_string(),
         ));
     }
-    if !preview.provider_candidates_supported {
+    if preview.adapter == DSH_MANIFEST_ADAPTER_ID && !activation_config_valid {
+        return Err(invalid_package(
+            package_id,
+            "the package projection contains invalid configuration".to_string(),
+        ));
+    }
+    if preview.adapter == OPENCODE_MANIFEST_ADAPTER_ID && !preview.provider_candidates_supported {
         return Err(invalid_package(
             package_id,
             "the package contains no supported OpenCode custom tool declaration".to_string(),
@@ -252,6 +308,7 @@ async fn project_activated(
         authority.clone().into_parts();
     let (binding, dispatch_targets) =
         activated_binding(service, workspace, package_id, input, authority)?;
+    let provider_candidates_supported = !dispatch_targets.is_empty();
     let client = binding.as_client();
     let read = client
         .read_plugins(read_request(
@@ -293,10 +350,15 @@ async fn project_activated(
     }
     diagnostics.sort();
     diagnostics.dedup();
-    Ok(
-        project_view(source, true, Some(activation_epoch), true, read, candidates)
-            .with_diagnostics(diagnostics),
+    Ok(project_view(
+        source,
+        true,
+        Some(activation_epoch),
+        provider_candidates_supported,
+        read,
+        candidates,
     )
+    .with_diagnostics(diagnostics))
 }
 
 fn preview_candidates(
@@ -324,8 +386,7 @@ fn activated_binding(
     authority: PluginActivationAuthority,
 ) -> Result<(PluginRuntimeBinding, Vec<PluginDispatchTarget>), ManagedPluginSourceError> {
     let (adapter, dispatch_targets) =
-        load_opencode_package_adapter(input, Some(authority.clone()), current_time_ms())
-            .map_err(|error| invalid_package(package_id, error.to_string()))?;
+        load_package_adapter(input, Some(authority.clone()), current_time_ms())?;
     let client: Arc<dyn PluginRuntimeClient> = Arc::new(DefaultPluginRuntimeClient::new(adapter));
     Ok((
         PluginRuntimeBinding::client(Arc::new(ActivationGatedPluginRuntimeClient {
@@ -542,6 +603,7 @@ impl PluginRuntimeClient for ActivationGatedPluginRuntimeClient {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use bitfun_product_domains::plugin_source::{PluginPackageFile, PluginPackageManifest};
     use bitfun_services_integrations::plugin_source::ManagedPluginTrustDecision;
     use sha2::{Digest, Sha256};
     use std::fs;
@@ -602,30 +664,41 @@ export const WorkspaceToolsPlugin: Plugin = async () => ({
         }
 
         async fn with_source(plugin_source: &str) -> Self {
+            Self::with_managed_package(
+                "opencode_compatible",
+                &[(".opencode/plugins/workspace-tools.ts", plugin_source)],
+            )
+            .await
+        }
+
+        async fn with_managed_package(adapter: &str, files: &[(&str, &str)]) -> Self {
             let temp = tempfile::tempdir().expect("tempdir");
             let workspace = temp.path().join("workspace");
             let user = temp.path().join("user");
             let package = workspace.join(".bitfun/plugins/acme.demo");
-            let source_path = package.join(".opencode/plugins/workspace-tools.ts");
-            fs::create_dir_all(source_path.parent().expect("source parent"))
-                .expect("create package");
+            let source_path = package.join(files[0].0);
             fs::create_dir_all(user.join("plugins")).expect("create user plugins");
-            fs::write(&source_path, plugin_source).expect("write plugin source");
-            let file_hash = format!(
-                "sha256:{}",
-                hex::encode(Sha256::digest(plugin_source.as_bytes()))
-            );
+            let mut manifest_files = Vec::new();
+            for (relative_path, contents) in files {
+                let path = package.join(relative_path);
+                fs::create_dir_all(path.parent().expect("source parent")).expect("create package");
+                fs::write(&path, contents).expect("write plugin source");
+                manifest_files.push(serde_json::json!({
+                    "path": relative_path,
+                    "sha256": format!(
+                        "sha256:{}",
+                        hex::encode(Sha256::digest(contents.as_bytes()))
+                    )
+                }));
+            }
             fs::write(
                 package.join("bitfun.plugin.json"),
                 serde_json::to_vec_pretty(&serde_json::json!({
                     "schemaVersion": 1,
                     "id": "acme.demo",
                     "version": "1.0.0",
-                    "adapter": "opencode_compatible",
-                    "files": [{
-                        "path": ".opencode/plugins/workspace-tools.ts",
-                        "sha256": file_hash
-                    }]
+                    "adapter": adapter,
+                    "files": manifest_files
                 }))
                 .expect("serialize manifest"),
             )
@@ -978,4 +1051,140 @@ export const WorkspaceToolsPlugin: Plugin = async () => ({
             .expect_err("revoked dispatch result must be discarded");
         assert_eq!(error.kind, PortErrorKind::NotAvailable);
     }
+
+    #[tokio::test]
+    async fn dsh_packages_route_to_the_dsh_adapter() {
+        let manifest = PluginPackageManifest {
+            schema_version: 1,
+            id: "acme.dsh".to_string(),
+            version: "1.0.0".to_string(),
+            adapter: "dsh_compatible".to_string(),
+            files: vec![PluginPackageFile {
+                path: "package.json".to_string(),
+                sha256: format!(
+                    "sha256:{}",
+                    hex::encode(Sha256::digest(
+                        br#"{ "dsh": { "profile": { "bundles": ["@acme/dsh-base"] } } }"#
+                    ))
+                ),
+            }],
+        };
+        let source = PluginPackageSourceIdentity {
+            package_id: "acme.dsh".to_string(),
+            version: "1.0.0".to_string(),
+            adapter: "dsh_compatible".to_string(),
+            source_path: "/managed/acme.dsh".to_string(),
+            content_hash: manifest.content_hash().expect("content hash"),
+        };
+        let files = std::collections::BTreeMap::from([(
+            "package.json".to_string(),
+            br#"{ "dsh": { "profile": { "bundles": ["@acme/dsh-base"] } } }"#.to_vec(),
+        )]);
+        let input = PluginPackageInput::new(manifest, source, files).expect("dsh input");
+
+        let (adapter, dispatch_targets) =
+            load_package_adapter(input, None, current_time_ms()).expect("route dsh adapter");
+        assert_eq!(adapter.adapter_id(), "dsh-compatible");
+        assert!(dispatch_targets.is_empty());
+    }
+
+    #[tokio::test]
+    async fn valid_dsh_projection_can_activate_without_tool_candidates() {
+        let fixture = Fixture::with_managed_package(
+            "dsh_compatible",
+            &[(
+                "package.json",
+                r#"{ "dsh": { "profile": { "bundles": ["@acme/dsh-base"] } } }"#,
+            )],
+        )
+        .await;
+        let preview = preview_with_service(
+            Arc::clone(&fixture.service),
+            &fixture.workspace,
+            "acme.demo",
+        )
+        .await
+        .expect("preview dsh package");
+        assert!(!preview.provider_candidates_supported);
+        assert!(!preview.entry_ids.is_empty());
+
+        let activated = activate_with_service(
+            Arc::clone(&fixture.service),
+            &fixture.workspace,
+            "acme.demo",
+            Some(&preview.content_hash),
+        )
+        .await
+        .expect("activate valid dsh projection");
+        assert!(activated.activated);
+        assert!(!activated.provider_candidates_supported);
+        assert!(!activated.permission_required);
+    }
+
+    #[tokio::test]
+    async fn invalid_dsh_projection_does_not_persist_activation() {
+        let fixture = Fixture::with_managed_package(
+            "dsh_compatible",
+            &[("package.json", r#"{ "name": "plain-package" }"#)],
+        )
+        .await;
+        let preview = preview_with_service(
+            Arc::clone(&fixture.service),
+            &fixture.workspace,
+            "acme.demo",
+        )
+        .await
+        .expect("preview invalid dsh package");
+        let activation_epoch_before = fixture
+            .service
+            .refresh(&fixture.workspace)
+            .await
+            .activation_epoch;
+
+        let error = activate_with_service(
+            Arc::clone(&fixture.service),
+            &fixture.workspace,
+            "acme.demo",
+            Some(&preview.content_hash),
+        )
+        .await
+        .expect_err("invalid dsh package must not remain active");
+        assert!(matches!(
+            error,
+            ManagedPluginSourceError::PackageInvalid { .. }
+        ));
+        let snapshot = fixture.service.refresh(&fixture.workspace).await;
+        assert!(!snapshot.packages[0].activated);
+        assert_eq!(snapshot.activation_epoch, activation_epoch_before);
+    }
+
+    #[tokio::test]
+    async fn unsupported_managed_package_adapter_is_rejected() {
+        let manifest = PluginPackageManifest {
+            schema_version: 1,
+            id: "acme.unknown".to_string(),
+            version: "1.0.0".to_string(),
+            adapter: "unknown_compatible".to_string(),
+            files: vec![PluginPackageFile {
+                path: "package.json".to_string(),
+                sha256: format!("sha256:{}", hex::encode(Sha256::digest(b"{}"))),
+            }],
+        };
+        let source = PluginPackageSourceIdentity {
+            package_id: "acme.unknown".to_string(),
+            version: "1.0.0".to_string(),
+            adapter: "unknown_compatible".to_string(),
+            source_path: "/managed/acme.unknown".to_string(),
+            content_hash: manifest.content_hash().expect("content hash"),
+        };
+        let files =
+            std::collections::BTreeMap::from([("package.json".to_string(), b"{}".to_vec())]);
+        let input = PluginPackageInput::new(manifest, source, files).expect("unknown input");
+        let error = load_package_adapter(input, None, current_time_ms())
+            .err()
+            .expect("unsupported adapter must fail");
+        assert!(error
+            .to_string()
+            .contains("unsupported managed package adapter"));
+    }
 }
diff --git a/src/crates/assembly/core/src/product_domain_runtime.rs b/src/crates/assembly/core/src/product_domain_runtime.rs
index 600cbdcd41..1c01b3b171 100644
--- a/src/crates/assembly/core/src/product_domain_runtime.rs
+++ b/src/crates/assembly/core/src/product_domain_runtime.rs
@@ -16,8 +16,6 @@ use bitfun_product_domains::function_agents::ports::{
 #[cfg(feature = "tools-miniapp")]
 use bitfun_product_domains::miniapp::ports::{MiniAppRuntimeFacade, MiniAppStoragePort};
 #[cfg(feature = "function-agents")]
-use chrono::{Local, Timelike};
-#[cfg(feature = "function-agents")]
 use log::info;
 
 #[cfg(feature = "function-agents")]
@@ -27,9 +25,7 @@ use crate::function_agents::port_adapters::{
     CoreFunctionAgentAiAdapter, CoreFunctionAgentGitAdapter,
 };
 #[cfg(feature = "function-agents")]
-use crate::function_agents::{
-    CommitMessage, CommitMessageOptions, WorkStateAnalysis, WorkStateOptions,
-};
+use crate::function_agents::{CommitMessage, CommitMessageOptions};
 #[cfg(feature = "function-agents")]
 use crate::infrastructure::ai::AIClientFactory;
 
@@ -81,30 +77,4 @@ impl CoreProductDomainRuntime {
             .generate_commit_message(repo_path.to_path_buf(), options)
             .await
     }
-
-    #[cfg(feature = "function-agents")]
-    pub(crate) async fn analyze_function_agent_work_state(
-        factory: Arc<AIClientFactory>,
-        repo_path: &Path,
-        options: WorkStateOptions,
-    ) -> AgentResult<WorkStateAnalysis> {
-        info!("Analyzing work state: repo_path={:?}", repo_path);
-
-        let now = Local::now();
-        let git_adapter = Self::function_agent_git_adapter();
-        let ai_adapter = Self::function_agent_ai_adapter(factory);
-        let facade = Self::function_agent_runtime_facade(&git_adapter, &ai_adapter);
-        // Keep the legacy analyzed_at timing in core: assign it after AI analysis completes.
-        let mut analysis = facade
-            .analyze_work_state(
-                repo_path.to_path_buf(),
-                options,
-                now.timestamp(),
-                now.hour(),
-                String::new(),
-            )
-            .await?;
-        analysis.analyzed_at = Local::now().to_rfc3339();
-        Ok(analysis)
-    }
 }
diff --git a/src/crates/assembly/core/src/product_runtime.rs b/src/crates/assembly/core/src/product_runtime.rs
index af3332354e..7d76a1f58e 100644
--- a/src/crates/assembly/core/src/product_runtime.rs
+++ b/src/crates/assembly/core/src/product_runtime.rs
@@ -21,6 +21,7 @@ use bitfun_agent_runtime::sdk::{
     AgentSessionUsagePort, AgentSessionUsageRequest, AgentTurnCancellationResult,
     AgentTurnSettlementPort, AgentTurnSettlementRequest, SessionTranscript,
 };
+use bitfun_core_types::{SESSION_PROVIDER_ACP, SESSION_PROVIDER_METADATA_KEY};
 use bitfun_harness::HarnessRegistry;
 use bitfun_runtime_ports::{
     AgentContextReloadPort, AgentContextReloadRequest, ClockPort, LocalWorkspaceSnapshotPort,
@@ -45,11 +46,19 @@ use crate::agentic::events::EventQueue;
 use crate::agentic::keyed_lock::KeyedAsyncLockGuard;
 use crate::agentic::persistence::session_branch::SessionBranchRequest;
 use crate::agentic::persistence::{PersistenceManager, SessionMetadataPage};
-use crate::agentic::session::{CoreSessionStorePort, PromptCacheScope};
+use crate::agentic::session::{
+    CoreSessionStorePort, PromptCacheScope,
+    INTERRUPTED_TURN_MODEL_BINDING_FINGERPRINT_METADATA_KEY,
+    INTERRUPTED_TURN_PERMISSION_MODE_METADATA_KEY,
+    INTERRUPTED_TURN_REASONING_FINGERPRINT_METADATA_KEY,
+    INTERRUPTED_TURN_REASONING_PRESET_METADATA_KEY,
+    INTERRUPTED_TURN_REASONING_SELECTION_METADATA_KEY,
+    INTERRUPTED_TURN_RESOLVED_MODEL_ID_METADATA_KEY,
+};
 use crate::agentic::tools::implementations::skills::SkillRegistry;
 use crate::service::session::{
     DialogTurnData, SessionMetadata, SessionTranscriptExport, SessionTranscriptExportOptions,
-    SessionTurnCatalog, SessionTurnWindowResponse,
+    SessionTurnCatalog, SessionTurnWindowResponse, TurnStatus,
 };
 use crate::service::session_usage::{
     generate_session_usage_report_from_storage_path, SessionUsageReport,
@@ -65,6 +74,60 @@ use crate::util::errors::{BitFunError, BitFunResult};
 pub use bitfun_product_capabilities::ProductRuntimeAssembly as CoreProductRuntimeAssembly;
 pub use runtime_services::{build_local_runtime_services, CoreRuntimeServicesProvider};
 
+fn projected_turn_save_would_overwrite_runtime_state(
+    persisted: &DialogTurnData,
+    projected: &DialogTurnData,
+) -> bool {
+    persisted.recovery.is_some()
+        || persisted.recovery_epoch.is_some()
+        || projected.recovery.is_some()
+        || projected.recovery_epoch.is_some()
+        || (matches!(
+            persisted.status,
+            TurnStatus::Completed | TurnStatus::Cancelled | TurnStatus::Error
+        ) && projected.status == TurnStatus::InProgress)
+}
+
+fn merge_runtime_owned_turn_facts(
+    persisted: &DialogTurnData,
+    projected: &DialogTurnData,
+) -> DialogTurnData {
+    let mut merged = projected.clone();
+    merged.agent_type = persisted.agent_type.clone();
+
+    let Some(persisted_metadata) = persisted
+        .user_message
+        .metadata
+        .as_ref()
+        .and_then(serde_json::Value::as_object)
+    else {
+        return merged;
+    };
+    let projected_metadata = merged
+        .user_message
+        .metadata
+        .get_or_insert_with(|| serde_json::json!({}));
+    if !projected_metadata.is_object() {
+        *projected_metadata = serde_json::json!({});
+    }
+    let target = projected_metadata
+        .as_object_mut()
+        .expect("projected metadata was normalized to an object");
+    for key in [
+        INTERRUPTED_TURN_PERMISSION_MODE_METADATA_KEY,
+        INTERRUPTED_TURN_RESOLVED_MODEL_ID_METADATA_KEY,
+        INTERRUPTED_TURN_MODEL_BINDING_FINGERPRINT_METADATA_KEY,
+        INTERRUPTED_TURN_REASONING_PRESET_METADATA_KEY,
+        INTERRUPTED_TURN_REASONING_SELECTION_METADATA_KEY,
+        INTERRUPTED_TURN_REASONING_FINGERPRINT_METADATA_KEY,
+    ] {
+        if let Some(value) = persisted_metadata.get(key) {
+            target.insert(key.to_string(), value.clone());
+        }
+    }
+    merged
+}
+
 struct ProductEventQueueDrain {
     task: tokio::task::JoinHandle<()>,
 }
@@ -489,7 +552,7 @@ impl LocalWorkspaceSnapshotPort for CoreLocalWorkspaceSnapshot {
         validate_persisted_session_id(&request.session_id).map_err(runtime_port_error)?;
         ensure_local_snapshot_manager(&request.workspace_path)
             .await?
-            .rollback_to_turn(&request.session_id, request.turn_index)
+            .rollback_workspace_files_to_boundary(&request.session_id, request.turn_index)
             .await
             .map_err(snapshot_port_error)
     }
@@ -925,6 +988,28 @@ impl CoreAgentRuntimeCompatibility {
             .await
     }
 
+    /// True when an external agent (ACP), not this Runtime, drives the Session.
+    ///
+    /// The Runtime never starts or completes those Turns, so it holds no
+    /// history branch for them and loading them into the Session manager only
+    /// rewrites their mode to a local fallback. Their history is projected by
+    /// the frontend, which is its only writer.
+    pub async fn is_externally_projected_session(
+        &self,
+        workspace_path: &Path,
+        session_id: &str,
+    ) -> BitFunResult<bool> {
+        let metadata = self
+            .load_persisted_session_metadata(workspace_path, session_id)
+            .await?;
+        Ok(metadata
+            .as_ref()
+            .and_then(|metadata| metadata.custom_metadata.as_ref())
+            .and_then(|custom| custom.get(SESSION_PROVIDER_METADATA_KEY))
+            .and_then(serde_json::Value::as_str)
+            == Some(SESSION_PROVIDER_ACP))
+    }
+
     pub async fn update_persisted_session_metadata(
         &self,
         workspace_path: &Path,
@@ -1246,6 +1331,17 @@ impl CoreAgentRuntimeCompatibility {
                 turn.session_id, permit.session_id
             )));
         }
+        if self
+            .is_externally_projected_session(&permit.storage_path, &permit.session_id)
+            .await?
+        {
+            // No Runtime history branch exists to validate against: the external
+            // agent owns the conversation and the projection is the only writer.
+            return self
+                .persistence
+                .save_dialog_turn(&permit.storage_path, turn)
+                .await;
+        }
         let session = self
             .coordinator
             .get_session_manager()
@@ -1263,8 +1359,26 @@ impl CoreAgentRuntimeCompatibility {
                 permit.session_id, turn.turn_index, turn.turn_id
             )));
         }
+        let mut projected = turn.clone();
+        if let Some(persisted) = self
+            .persistence
+            .load_dialog_turn(&permit.storage_path, &permit.session_id, turn.turn_index)
+            .await?
+        {
+            if projected_turn_save_would_overwrite_runtime_state(&persisted, turn) {
+                log::debug!(
+                    "Ignoring stale projected Turn save owned by the runtime: session_id={}, turn_id={}, persisted_status={:?}, projected_status={:?}",
+                    permit.session_id,
+                    turn.turn_id,
+                    persisted.status,
+                    turn.status
+                );
+                return Ok(());
+            }
+            projected = merge_runtime_owned_turn_facts(&persisted, turn);
+        }
         self.persistence
-            .save_dialog_turn(&permit.storage_path, turn)
+            .save_dialog_turn(&permit.storage_path, &projected)
             .await
     }
 
@@ -1904,10 +2018,12 @@ mod tests {
     use super::CoreProductAgentEventSource;
     use super::{
         build_session_lineage_snapshot, generate_core_session_usage_report,
-        get_snapshot_manager_for_workspace, latest_persisted_turn_id, runtime_lineage_snapshot,
-        runtime_port_error, validate_latest_turn_fork_scope, validate_persisted_session_id,
-        CoreAgentRuntimeCompatibility, CoreLocalWorkspaceSnapshot, CoreProductAgentRuntime,
-        CoreProductEventQueueOwner, CoreSessionOperationsPort,
+        get_snapshot_manager_for_workspace, latest_persisted_turn_id,
+        merge_runtime_owned_turn_facts, projected_turn_save_would_overwrite_runtime_state,
+        runtime_lineage_snapshot, runtime_port_error, validate_latest_turn_fork_scope,
+        validate_persisted_session_id, CoreAgentRuntimeCompatibility, CoreLocalWorkspaceSnapshot,
+        CoreProductAgentRuntime, CoreProductEventQueueOwner, CoreSessionOperationsPort,
+        SESSION_PROVIDER_ACP, SESSION_PROVIDER_METADATA_KEY,
     };
     use crate::agentic::coordination::{ConversationCoordinator, DialogScheduler};
     use crate::agentic::events::{EventQueue, EventQueueConfig, EventRouter};
@@ -1923,7 +2039,10 @@ mod tests {
     use crate::agentic::tools::registry::ToolRegistry;
     use crate::agentic::tools::{ToolPipeline, ToolStateManager};
     use crate::infrastructure::PathManager;
-    use crate::service::session::{DialogTurnData, SessionMetadata, UserMessageData};
+    use crate::service::session::{
+        DialogTurnData, DialogTurnRecoveryData, DialogTurnRecoveryStatus, SessionMetadata,
+        TurnStatus, UserMessageData,
+    };
     use crate::service::session_usage::UsageTokenSource;
     use crate::service::snapshot::manager::clear_snapshot_manager_for_test;
     use crate::service::token_usage::TokenUsageService;
@@ -1970,6 +2089,103 @@ mod tests {
         }
     }
 
+    #[test]
+    fn stale_projected_turn_saves_cannot_overwrite_runtime_recovery_state() {
+        let mut persisted = DialogTurnData::new(
+            "turn-1".to_string(),
+            0,
+            "session-1".to_string(),
+            UserMessageData {
+                id: "user-1".to_string(),
+                content: "continue".to_string(),
+                timestamp: 1,
+                metadata: None,
+            },
+        );
+        let projected = persisted.clone();
+        persisted.status = TurnStatus::Cancelled;
+        persisted.recovery = Some(DialogTurnRecoveryData {
+            status: DialogTurnRecoveryStatus::Interrupted,
+            execution_generation: 0,
+            resume_count: 0,
+            interrupted_at: Some(2),
+            model_id: Some("model-a".to_string()),
+        });
+        persisted.recovery_epoch = Some(0);
+        assert!(projected_turn_save_would_overwrite_runtime_state(
+            &persisted, &projected
+        ));
+
+        let mut completed = persisted.clone();
+        completed.status = TurnStatus::Completed;
+        completed.recovery = None;
+        assert!(projected_turn_save_would_overwrite_runtime_state(
+            &completed, &projected
+        ));
+
+        let mut projected_with_recovery = projected.clone();
+        projected_with_recovery.recovery = persisted.recovery.clone();
+        assert!(projected_turn_save_would_overwrite_runtime_state(
+            &projected,
+            &projected_with_recovery
+        ));
+        assert!(!projected_turn_save_would_overwrite_runtime_state(
+            &projected, &projected
+        ));
+    }
+
+    #[test]
+    fn projected_turn_saves_preserve_runtime_execution_contract() {
+        let mut persisted = DialogTurnData::new(
+            "turn-1".to_string(),
+            0,
+            "session-1".to_string(),
+            UserMessageData {
+                id: "user-1".to_string(),
+                content: "continue".to_string(),
+                timestamp: 1,
+                metadata: Some(serde_json::json!({
+                    "runtime_resolved_model_id": "model-a",
+                    "runtime_model_binding_fingerprint": "binding-a",
+                    "runtime_reasoning_preset": "high",
+                    "runtime_reasoning_selection": "high",
+                    "runtime_reasoning_fingerprint": "reasoning-a",
+                    "resolved_permission_mode": "ask",
+                })),
+            },
+        );
+        persisted.agent_type = Some("runtime-agent".to_string());
+        let mut projected = persisted.clone();
+        projected.agent_type = Some("stale-agent".to_string());
+        projected.user_message.metadata = Some(serde_json::json!({
+            "canvas_context": { "node": "selected" }
+        }));
+
+        let merged = merge_runtime_owned_turn_facts(&persisted, &projected);
+        let metadata = merged
+            .user_message
+            .metadata
+            .and_then(|value| value.as_object().cloned())
+            .expect("merged metadata");
+        assert_eq!(merged.agent_type.as_deref(), Some("runtime-agent"));
+        assert_eq!(
+            metadata.get("runtime_resolved_model_id"),
+            Some(&serde_json::json!("model-a"))
+        );
+        assert_eq!(
+            metadata.get("runtime_reasoning_fingerprint"),
+            Some(&serde_json::json!("reasoning-a"))
+        );
+        assert_eq!(
+            metadata.get("resolved_permission_mode"),
+            Some(&serde_json::json!("ask"))
+        );
+        assert_eq!(
+            metadata.get("canvas_context"),
+            Some(&serde_json::json!({ "node": "selected" }))
+        );
+    }
+
     #[tokio::test]
     async fn product_event_queue_owner_broadcasts_while_draining_the_legacy_queue() {
         let queue = Arc::new(EventQueue::new(EventQueueConfig {
@@ -3101,4 +3317,138 @@ mod tests {
         assert_eq!(report.tokens.output_tokens, Some(5));
         assert_eq!(report.tokens.total_tokens, Some(15));
     }
+
+    #[tokio::test]
+    async fn externally_projected_turns_persist_without_a_runtime_history_branch() {
+        let workspace = TestWorkspace::new();
+        let storage_path = workspace.path().join("sessions");
+        std::fs::create_dir_all(&storage_path).expect("session storage");
+        let persistence = Arc::new(
+            PersistenceManager::new(workspace.path_manager()).expect("persistence manager"),
+        );
+        let session_manager = Arc::new(SessionManager::new(
+            Arc::new(SessionContextStore::new()),
+            persistence.clone(),
+            SessionManagerConfig {
+                max_active_sessions: 100,
+                session_idle_timeout: Duration::from_secs(3600),
+                auto_save_interval: Duration::from_secs(300),
+                enable_persistence: false,
+                prompt_cache_policy: PromptCachePolicy::default(),
+            },
+        ));
+        let event_queue = Arc::new(EventQueue::new(EventQueueConfig::default()));
+        let tool_pipeline = Arc::new(ToolPipeline::new(
+            Arc::new(TokioRwLock::new(ToolRegistry::new())),
+            Arc::new(ToolStateManager::new(event_queue.clone())),
+            None,
+        ));
+        let execution_engine = Arc::new(ExecutionEngine::new(
+            Arc::new(RoundExecutor::new(
+                Arc::new(StreamProcessor::new(event_queue.clone())),
+                event_queue.clone(),
+                tool_pipeline.clone(),
+            )),
+            event_queue.clone(),
+            session_manager.clone(),
+            Arc::new(ContextCompressor::new(CompressionConfig::default())),
+            ExecutionEngineConfig::default(),
+        ));
+        let coordinator = Arc::new(ConversationCoordinator::new(
+            session_manager.clone(),
+            execution_engine,
+            tool_pipeline,
+            event_queue,
+            Arc::new(EventRouter::new()),
+            Arc::new(
+                crate::runtime_ownership::CoreRuntimeOwnership::embedded_with_facts(
+                    std::env::temp_dir().join(format!(
+                        "bitfun-product-runtime-ownership-test-{}",
+                        uuid::Uuid::new_v4()
+                    )),
+                    "bitfun".to_string(),
+                    "test",
+                ),
+            ),
+        ));
+        let scheduler = DialogScheduler::new(coordinator.clone(), session_manager.clone());
+        let compatibility = CoreAgentRuntimeCompatibility::build(coordinator, scheduler);
+
+        let save_first_turn = |session_id: &'static str| {
+            let compatibility = compatibility.clone();
+            let storage_path = storage_path.clone();
+            async move {
+                let turn = DialogTurnData::new(
+                    format!("{session_id}-turn-0"),
+                    0,
+                    session_id.to_string(),
+                    UserMessageData {
+                        id: format!("{session_id}-user-0"),
+                        content: "hello".to_string(),
+                        timestamp: 1,
+                        metadata: None,
+                    },
+                );
+                let permit = compatibility
+                    .begin_persisted_session_mutation(&storage_path, session_id)
+                    .await
+                    .expect("mutation permit");
+                compatibility
+                    .save_persisted_dialog_turn(&permit, &turn)
+                    .await
+            }
+        };
+
+        let acp_session_id = "acp_dsh_projected";
+        let mut acp_metadata = SessionMetadata::new(
+            acp_session_id.to_string(),
+            "Projected".to_string(),
+            "acp:dsh".to_string(),
+            "deepseek".to_string(),
+        );
+        let mut custom_metadata = serde_json::Map::new();
+        custom_metadata.insert(
+            SESSION_PROVIDER_METADATA_KEY.to_string(),
+            serde_json::Value::String(SESSION_PROVIDER_ACP.to_string()),
+        );
+        acp_metadata.custom_metadata = Some(serde_json::Value::Object(custom_metadata));
+        persistence
+            .save_session_metadata(&storage_path, &acp_metadata)
+            .await
+            .expect("acp metadata");
+
+        save_first_turn(acp_session_id)
+            .await
+            .expect("a projected first turn has no branch to validate against");
+        assert_eq!(
+            persistence
+                .load_session_turns(&storage_path, acp_session_id)
+                .await
+                .expect("projected turns")
+                .len(),
+            1
+        );
+
+        let runtime_session_id = "runtime-owned";
+        persistence
+            .save_session_metadata(
+                &storage_path,
+                &SessionMetadata::new(
+                    runtime_session_id.to_string(),
+                    "Runtime owned".to_string(),
+                    "agentic".to_string(),
+                    "model-a".to_string(),
+                ),
+            )
+            .await
+            .expect("runtime metadata");
+
+        let error = save_first_turn(runtime_session_id)
+            .await
+            .expect_err("a Runtime-owned Session still needs its history branch");
+        assert!(
+            matches!(error, BitFunError::OutcomeUnknown(_)),
+            "unexpected error: {error}"
+        );
+    }
 }
diff --git a/src/crates/assembly/core/src/service/config/global.rs b/src/crates/assembly/core/src/service/config/global.rs
index 045d0ef36e..f2f0a97698 100644
--- a/src/crates/assembly/core/src/service/config/global.rs
+++ b/src/crates/assembly/core/src/service/config/global.rs
@@ -70,7 +70,7 @@ pub enum ConfigUpdateEvent {
     /// AI models / default-model slots / agent-model defaults were reconciled
     /// after a model became unavailable (disabled, deleted, or otherwise
     /// invalid). Emitted whenever the config layer had to silently rewrite
-    /// `ai.default_models`, `ai.agent_model_defaults`, or `ai.func_agent_models`
+    /// `ai.default_models`, `ai.agent_model_defaults`, or `ai.task_models`
     /// so they only reference enabled models.
     ModelsReconciled {
         /// Model ids that just became unusable (disabled or deleted) and that
@@ -79,8 +79,8 @@ pub enum ConfigUpdateEvent {
         invalidated_model_ids: Vec<String>,
         /// Whether `ai.default_models` was rewritten as part of the reconcile.
         default_models_changed: bool,
-        /// Whether `ai.func_agent_models` was rewritten as part of the reconcile.
-        func_agent_models_changed: bool,
+        /// Whether `ai.task_models` was rewritten as part of the reconcile.
+        task_models_changed: bool,
         /// Whether `ai.agent_model_defaults` was rewritten as part of the reconcile.
         agent_model_defaults_changed: bool,
     },
diff --git a/src/crates/assembly/core/src/service/config/manager.rs b/src/crates/assembly/core/src/service/config/manager.rs
index f2fb4c5375..35e13cae1c 100644
--- a/src/crates/assembly/core/src/service/config/manager.rs
+++ b/src/crates/assembly/core/src/service/config/manager.rs
@@ -278,7 +278,6 @@ impl ConfigManager {
 
     /// Creates the first config file using the already initialized defaults.
     async fn create_default_config(&mut self) -> BitFunResult<()> {
-        Self::add_default_func_agent_models_config(&mut self.config.ai.func_agent_models);
         self.config.version = env!("CARGO_PKG_VERSION").to_string();
         self.save_config().await?;
         debug!("Created default config file");
@@ -338,8 +337,6 @@ impl ConfigManager {
         match serde_json::from_value::<GlobalConfig>(config_value.clone()) {
             Ok(mut config) => {
                 load_diagnostics.extend(normalize_typed_config(&mut config));
-                Self::add_default_func_agent_models_config(&mut config.ai.func_agent_models);
-
                 load_diagnostics.extend(isolate_invalid_ai_models(&mut config).await?);
                 load_diagnostics.extend(reconcile_model_references(&mut config).diagnostics);
 
@@ -425,7 +422,6 @@ impl ConfigManager {
         })?;
 
         let mut load_diagnostics = normalize_typed_config(&mut config);
-        Self::add_default_func_agent_models_config(&mut config.ai.func_agent_models);
         load_diagnostics.extend(isolate_invalid_ai_models(&mut config).await?);
         load_diagnostics.extend(reconcile_model_references(&mut config).diagnostics);
 
@@ -455,7 +451,6 @@ impl ConfigManager {
     ) -> BitFunResult<()> {
         let backup_path = self.backup_raw_config(raw_content, reason).await?;
         self.config = self.providers.get_default_config();
-        Self::add_default_func_agent_models_config(&mut self.config.ai.func_agent_models);
         self.config.version = env!("CARGO_PKG_VERSION").to_string();
         self.config.schema_version = CURRENT_CONFIG_SCHEMA_VERSION;
         self.load_diagnostics = vec![ConfigDiagnostic {
@@ -476,23 +471,6 @@ impl ConfigManager {
         Ok(())
     }
 
-    /// Adds default configuration for functional agents (`func_agent_models`).
-    fn add_default_func_agent_models_config(
-        func_agent_models: &mut std::collections::HashMap<String, String>,
-    ) {
-        let func_agents_using_fast = vec![
-            "compression",
-            "startchat-func-agent",
-            "session-title-func-agent",
-            "git-func-agent",
-        ];
-        for key in func_agents_using_fast {
-            if !func_agent_models.contains_key(key) {
-                func_agent_models.insert(key.to_string(), "fast".to_string());
-            }
-        }
-    }
-
     /// Saves the configuration file.
     async fn save_config(&self) -> BitFunResult<()> {
         let content = serde_json::to_string_pretty(&config_value_for_persistence(&self.config)?)
@@ -1198,6 +1176,24 @@ mod tests {
         assert!(value.get("memories").is_none());
         assert!(value["ai"].get("agent_models").is_none());
         assert!(value["ai"].get("allow_tool_json_repair").is_none());
+        assert!(value["ai"].get("task_models").is_none());
+    }
+
+    #[test]
+    fn persistence_keeps_only_non_default_task_model_fields() {
+        let mut config = GlobalConfig::default();
+        config.ai.task_models.session_title =
+            crate::service::config::types::TaskModelSelection::Inherit;
+
+        let value =
+            config_value_for_persistence(&config).expect("config should serialize for persistence");
+
+        assert_eq!(
+            value["ai"].get("task_models"),
+            Some(&serde_json::json!({
+                "session_title": { "kind": "inherit" }
+            }))
+        );
     }
 
     #[test]
diff --git a/src/crates/assembly/core/src/service/config/mode_config_canonicalizer.rs b/src/crates/assembly/core/src/service/config/mode_config_canonicalizer.rs
index 5498251c42..158c60b593 100644
--- a/src/crates/assembly/core/src/service/config/mode_config_canonicalizer.rs
+++ b/src/crates/assembly/core/src/service/config/mode_config_canonicalizer.rs
@@ -19,6 +19,8 @@ use serde::{Deserialize, Serialize};
 use serde_json::{Map, Value};
 use std::collections::{HashMap, HashSet};
 
+const DYNAMIC_MCP_TOOL_PREFIX: &str = "mcp__";
+
 /// Agent-profile config canonicalization report.
 #[derive(Debug, Serialize, Deserialize, Default)]
 pub struct AgentProfileConfigCanonicalizationReport {
@@ -60,6 +62,16 @@ fn normalize_tools(tools: Vec<String>, valid_tools: &HashSet<String>) -> Vec<Str
         .collect()
 }
 
+fn normalize_added_tool_overrides(
+    tools: Vec<String>,
+    valid_tools: &HashSet<String>,
+) -> Vec<String> {
+    dedupe_preserving_order(tools)
+        .into_iter()
+        .filter(|tool| valid_tools.contains(tool) || tool.starts_with(DYNAMIC_MCP_TOOL_PREFIX))
+        .collect()
+}
+
 fn normalize_skill_override_lists(
     disabled_user_skills: Vec<String>,
     enabled_user_skills: Vec<String>,
@@ -198,7 +210,10 @@ fn stored_agent_profile_from_overrides(
     } = overrides;
     let profile_id = resolve_profile_id(agent_id);
     let default_set: HashSet<String> = default_tools.iter().cloned().collect();
-    let mut added_tools = normalize_tools(added_tools, valid_tools);
+    // MCP tools are registered only after deferred server initialization. Keep
+    // their stored overrides during startup canonicalization even when the
+    // current registry snapshot cannot validate them yet.
+    let mut added_tools = normalize_added_tool_overrides(added_tools, valid_tools);
     let mut removed_tools = normalize_tools(removed_tools, valid_tools);
     let (disabled_user_skills, enabled_user_skills) =
         normalize_skill_override_lists(disabled_user_skills, enabled_user_skills);
@@ -314,11 +329,26 @@ async fn get_mode_defaults() -> HashMap<String, Vec<String>> {
         .collect()
 }
 
+/// Default tool lists for every agent that can own a stored profile.
+///
+/// Profiles are not a mode-only concept: sub-agents carry their own skill
+/// selection, so a mode-only lookup rejects writes for agents the UI already
+/// lets users configure (`ComputerUse` being the built-in case).
+async fn get_agent_defaults() -> HashMap<String, Vec<String>> {
+    let mut defaults = get_mode_defaults().await;
+    for subagent in get_agent_registry().get_subagents_info(None).await {
+        defaults
+            .entry(subagent.id)
+            .or_insert(subagent.default_tools);
+    }
+    defaults
+}
+
 async fn get_profile_defaults() -> HashMap<String, Vec<String>> {
     let mut defaults = HashMap::new();
-    for (mode_id, default_tools) in get_mode_defaults().await {
+    for (agent_id, default_tools) in get_agent_defaults().await {
         defaults
-            .entry(resolve_profile_id(&mode_id))
+            .entry(resolve_profile_id(&agent_id))
             .or_insert(default_tools);
     }
     defaults
@@ -363,8 +393,8 @@ pub async fn get_agent_profile_view(agent_id: &str) -> BitFunResult<AgentProfile
 pub async fn persist_agent_profile_from_value(agent_id: &str, config: Value) -> BitFunResult<()> {
     let config_service = GlobalConfigManager::get_service().await?;
     let mut stored_configs = get_agent_profile_configs().await?;
-    let mode_defaults = get_mode_defaults().await;
-    let default_tools = mode_defaults
+    let agent_defaults = get_agent_defaults().await;
+    let default_tools = agent_defaults
         .get(agent_id)
         .ok_or_else(|| BitFunError::config(format!("Agent does not exist: {}", agent_id)))?;
     let valid_tools = get_valid_tool_names().await;
@@ -552,9 +582,20 @@ pub async fn canonicalize_agent_profile_configs(
         }
     }
 
-    for profile_id in raw_agent_profiles.keys() {
-        if !profile_defaults.contains_key(profile_id) {
-            removed_profile_configs.push(profile_id.clone());
+    // Profiles we cannot resolve defaults for are kept, not dropped. Canonicalization
+    // runs at startup with no workspace, so project-scoped sub-agents are invisible
+    // here; pruning them would silently discard the user's stored selection every
+    // launch. Records that no longer deserialize are still removed, so one bad entry
+    // cannot take the whole map down when it is read back.
+    for (profile_id, raw_profile) in &raw_agent_profiles {
+        if profile_defaults.contains_key(profile_id) {
+            continue;
+        }
+        match serde_json::from_value::<AgentProfileConfig>(raw_profile.clone()) {
+            Ok(config) => {
+                rewritten_agent_profiles.insert(profile_id.clone(), serde_json::to_value(config)?);
+            }
+            Err(_) => removed_profile_configs.push(profile_id.clone()),
         }
     }
 
@@ -589,16 +630,41 @@ pub fn agent_profile_member_mode_ids_for(agent_id: &str) -> Vec<String> {
 #[cfg(test)]
 mod tests {
     use super::{
-        agent_profile_member_mode_ids_for, canonicalize_agent_profile,
+        agent_profile_member_mode_ids_for, canonicalize_agent_profile, get_agent_defaults,
         normalize_skill_override_lists, resolve_effective_tools,
         stored_agent_profile_from_overrides, StoredAgentProfileOverrides,
     };
+    use crate::agentic::agents::get_agent_registry;
     use crate::service::config::types::{AgentProfileConfig, AgentSubagentOverrideState};
     use bitfun_agent_runtime::thread_goal_tools::THREAD_GOAL_TOOL_NAMES;
     use bitfun_runtime_ports::{PermissionEffect, PermissionRule};
     use serde_json::Value;
     use std::collections::HashSet;
 
+    /// Skill selection is stored per agent profile, so every agent whose default
+    /// tools include `Skill` must resolve to a profile default. Otherwise saving
+    /// its selection fails with "Agent does not exist" — which is what happened
+    /// to `ComputerUse`, a sub-agent the agents scene renders as a core card.
+    #[tokio::test]
+    async fn agents_shipping_the_skill_tool_can_own_a_stored_profile() {
+        let defaults = get_agent_defaults().await;
+
+        assert!(
+            defaults.contains_key("ComputerUse"),
+            "ComputerUse ships the Skill tool but cannot own a stored profile"
+        );
+
+        for subagent in get_agent_registry().get_subagents_info(None).await {
+            if subagent.default_tools.iter().any(|tool| tool == "Skill") {
+                assert!(
+                    defaults.contains_key(&subagent.id),
+                    "sub-agent '{}' ships the Skill tool but cannot own a stored profile",
+                    subagent.id
+                );
+            }
+        }
+    }
+
     #[test]
     fn mode_profiles_cannot_remove_required_thread_goal_tools() {
         let default_tools = vec![
@@ -762,6 +828,27 @@ mod tests {
         assert!(canonical.is_none());
     }
 
+    #[test]
+    fn canonicalize_agent_profile_preserves_mcp_override_before_registration() {
+        let raw = serde_json::json!({
+            "profile_id": "coding_shared",
+            "added_tools": ["mcp__github__list_issues", "missing_static_tool"]
+        });
+        let canonical = canonicalize_agent_profile(
+            "coding_shared",
+            Some(&raw),
+            &["Read".to_string()],
+            &HashSet::from(["Read".to_string()]),
+        )
+        .expect("profile should canonicalize")
+        .expect("the MCP override should keep the profile");
+
+        assert_eq!(
+            canonical.added_tools,
+            vec!["mcp__github__list_issues".to_string()]
+        );
+    }
+
     #[test]
     fn shared_modes_report_shared_profile_members() {
         assert_eq!(
diff --git a/src/crates/assembly/core/src/service/config/normalization.rs b/src/crates/assembly/core/src/service/config/normalization.rs
index 3d776c04bc..761274ea2f 100644
--- a/src/crates/assembly/core/src/service/config/normalization.rs
+++ b/src/crates/assembly/core/src/service/config/normalization.rs
@@ -161,7 +161,7 @@ pub async fn isolate_invalid_ai_models(
 pub struct ModelReferenceReconcileResult {
     pub invalidated_model_ids: Vec<String>,
     pub default_models_changed: bool,
-    pub func_agent_models_changed: bool,
+    pub task_models_changed: bool,
     pub agent_model_defaults_changed: bool,
     pub diagnostics: Vec<ConfigDiagnostic>,
 }
@@ -169,7 +169,7 @@ pub struct ModelReferenceReconcileResult {
 impl ModelReferenceReconcileResult {
     pub fn is_noop(&self) -> bool {
         !self.default_models_changed
-            && !self.func_agent_models_changed
+            && !self.task_models_changed
             && !self.agent_model_defaults_changed
     }
 }
@@ -226,20 +226,43 @@ pub fn reconcile_model_references(config: &mut GlobalConfig) -> ModelReferenceRe
             || enabled_model_with_capability(&snapshot, reference, ModelCapability::TextChat)
     };
 
-    config.ai.func_agent_models.retain(|agent, model_ref| {
-        let valid = direct_text_reference_is_valid(model_ref);
-        if !valid {
-            invalidated.insert(model_ref.clone());
-            result.func_agent_models_changed = true;
-            diagnose_reference_repair(
-                &mut result.diagnostics,
-                &format!("ai.func_agent_models.{agent}"),
-                Some(model_ref),
-                None,
-            );
-        }
-        valid
-    });
+    let mut reconcile_task_model =
+        |selection: &mut crate::service::config::types::TaskModelSelection,
+         path: &str,
+         allow_inherit: bool| {
+            let previous = selection.fixed_model_id().map(str::to_string);
+            let valid = match selection {
+                crate::service::config::types::TaskModelSelection::Inherit => allow_inherit,
+                crate::service::config::types::TaskModelSelection::Fixed { model_id } => {
+                    model_id != "auto" && direct_text_reference_is_valid(model_id)
+                }
+            };
+            if !valid {
+                if let Some(model_id) = previous.as_ref() {
+                    invalidated.insert(model_id.clone());
+                }
+                *selection = crate::service::config::types::TaskModelSelection::Fixed {
+                    model_id: "fast".to_string(),
+                };
+                result.task_models_changed = true;
+                diagnose_reference_repair(
+                    &mut result.diagnostics,
+                    path,
+                    previous.as_deref().or(Some("inherit")),
+                    Some("fast"),
+                );
+            }
+        };
+    reconcile_task_model(
+        &mut config.ai.task_models.session_title,
+        "ai.task_models.session_title",
+        true,
+    );
+    reconcile_task_model(
+        &mut config.ai.task_models.git_commit,
+        "ai.task_models.git_commit",
+        false,
+    );
 
     if !direct_text_reference_is_valid(&config.ai.agent_model_defaults.mode) {
         invalidated.insert(config.ai.agent_model_defaults.mode.clone());
@@ -488,6 +511,32 @@ mod tests {
         assert!(result.default_models_changed);
     }
 
+    #[test]
+    fn task_models_reconcile_invalid_fixed_and_git_inherit_to_fast() {
+        let mut config = GlobalConfig::default();
+        config.ai.task_models.session_title =
+            crate::service::config::types::TaskModelSelection::Fixed {
+                model_id: "missing".to_string(),
+            };
+        config.ai.task_models.git_commit =
+            crate::service::config::types::TaskModelSelection::Inherit;
+
+        let result = reconcile_model_references(&mut config);
+
+        assert!(result.task_models_changed);
+        assert_eq!(
+            config.ai.task_models.session_title.fixed_model_id(),
+            Some("fast")
+        );
+        assert_eq!(
+            config.ai.task_models.git_commit.fixed_model_id(),
+            Some("fast")
+        );
+        assert!(result
+            .invalidated_model_ids
+            .contains(&"missing".to_string()));
+    }
+
     #[tokio::test]
     async fn global_ai_errors_do_not_disable_individually_valid_models() {
         let mut config = GlobalConfig::default();
diff --git a/src/crates/assembly/core/src/service/config/providers.rs b/src/crates/assembly/core/src/service/config/providers.rs
index 974833cbd1..4c9e42926a 100644
--- a/src/crates/assembly/core/src/service/config/providers.rs
+++ b/src/crates/assembly/core/src/service/config/providers.rs
@@ -80,15 +80,17 @@ fn ai_validation_error_location(message: &str) -> (String, String) {
             "AI_STREAM_TTFT_TIMEOUT_INVALID".to_string(),
         );
     }
-    if message.starts_with("Function Agent '") {
-        if let Some((_, suffix)) = message.split_once("Function Agent '") {
-            if let Some((agent, _)) = suffix.split_once('\'') {
-                return (
-                    format!("ai.func_agent_models.{agent}"),
-                    "FUNC_AGENT_MODEL_INVALID".to_string(),
-                );
-            }
-        }
+    if message.contains("session-title task model") {
+        return (
+            "ai.task_models.session_title".to_string(),
+            "TASK_MODEL_INVALID".to_string(),
+        );
+    }
+    if message.contains("Git commit task model") {
+        return (
+            "ai.task_models.git_commit".to_string(),
+            "TASK_MODEL_INVALID".to_string(),
+        );
     }
 
     ("ai".to_string(), "VALIDATION_ERROR".to_string())
@@ -279,19 +281,36 @@ impl ConfigProvider for AIConfigProvider {
                 }
             }
 
-            for (func_agent_name, model_id) in &ai_config.func_agent_models {
-                if !ai_config
-                    .models
-                    .iter()
-                    .any(|m| m.enabled && m.id == *model_id)
-                    && model_id != "primary"
-                    && model_id != "fast"
+            let valid_task_model = |model_id: &str| {
+                matches!(model_id, "primary" | "fast")
+                    || ai_config
+                        .models
+                        .iter()
+                        .any(|model| model.enabled && model.id == model_id)
+            };
+            if let Some(model_id) = ai_config.task_models.session_title.fixed_model_id() {
+                if !valid_task_model(model_id) {
+                    return Err(BitFunError::validation(format!(
+                        "The session-title task model '{}' does not exist",
+                        model_id
+                    )));
+                }
+            }
+            match &ai_config.task_models.git_commit {
+                crate::service::config::types::TaskModelSelection::Inherit => {
+                    return Err(BitFunError::validation(
+                        "The Git commit task model cannot inherit a session model".to_string(),
+                    ));
+                }
+                crate::service::config::types::TaskModelSelection::Fixed { model_id }
+                    if !valid_task_model(model_id) =>
                 {
                     return Err(BitFunError::validation(format!(
-                        "Function Agent '{}' configured model '{}' does not exist",
-                        func_agent_name, model_id
+                        "The Git commit task model '{}' does not exist",
+                        model_id
                     )));
                 }
+                crate::service::config::types::TaskModelSelection::Fixed { .. } => {}
             }
         } else {
             return Err(BitFunError::validation(
diff --git a/src/crates/assembly/core/src/service/config/service.rs b/src/crates/assembly/core/src/service/config/service.rs
index 8aa5306c54..8414f8af99 100644
--- a/src/crates/assembly/core/src/service/config/service.rs
+++ b/src/crates/assembly/core/src/service/config/service.rs
@@ -150,7 +150,7 @@ impl ConfigService {
             || path.starts_with("ai.models")
             || path.starts_with("ai.default_models")
             || path.starts_with("ai.agent_model_defaults")
-            || path.starts_with("ai.func_agent_models")
+            || path.starts_with("ai.task_models")
     }
 
     /// Resets configuration.
@@ -499,11 +499,10 @@ impl ConfigService {
     }
 
     /// Bring `ai.default_models`, `ai.agent_model_defaults`, and
-    /// `ai.func_agent_models` back into a consistent state with `ai.models`.
+    /// `ai.task_models` back into a consistent state with `ai.models`.
     ///
     /// This is the single integrity guard the rest of the system relies on:
-    /// - any func-agent mapping pointing at a model that no longer exists or
-    ///   that became disabled is dropped;
+    /// - invalid task-model selectors are reset to their defaults;
     /// - `default_models.primary` / `.fast` are repointed to the first enabled
     ///   model when their current target is missing or disabled (or cleared
     ///   when no enabled model exists at all);
@@ -526,7 +525,7 @@ impl ConfigService {
         let report = ReconcileModelsReport {
             invalidated_model_ids: reconciliation.invalidated_model_ids,
             default_models_changed: reconciliation.default_models_changed,
-            func_agent_models_changed: reconciliation.func_agent_models_changed,
+            task_models_changed: reconciliation.task_models_changed,
             agent_model_defaults_changed: reconciliation.agent_model_defaults_changed,
         };
 
@@ -534,17 +533,17 @@ impl ConfigService {
             log::debug!("Reconcile ({caller}): no changes");
         } else {
             info!(
-                "Reconcile ({caller}): invalidated={:?}, default_changed={}, func_agent_changed={}, agent_defaults_changed={}",
+                "Reconcile ({caller}): invalidated={:?}, default_changed={}, task_models_changed={}, agent_defaults_changed={}",
                 report.invalidated_model_ids,
                 report.default_models_changed,
-                report.func_agent_models_changed,
+                report.task_models_changed,
                 report.agent_model_defaults_changed
             );
             super::global::GlobalConfigManager::broadcast_update(
                 super::global::ConfigUpdateEvent::ModelsReconciled {
                     invalidated_model_ids: report.invalidated_model_ids.clone(),
                     default_models_changed: report.default_models_changed,
-                    func_agent_models_changed: report.func_agent_models_changed,
+                    task_models_changed: report.task_models_changed,
                     agent_model_defaults_changed: report.agent_model_defaults_changed,
                 },
             )
@@ -578,7 +577,7 @@ impl bitfun_runtime_ports::ConfigReadPort for ConfigService {
 pub struct ReconcileModelsReport {
     pub invalidated_model_ids: Vec<String>,
     pub default_models_changed: bool,
-    pub func_agent_models_changed: bool,
+    pub task_models_changed: bool,
     pub agent_model_defaults_changed: bool,
 }
 
@@ -586,7 +585,7 @@ impl ReconcileModelsReport {
     pub fn is_noop(&self) -> bool {
         self.invalidated_model_ids.is_empty()
             && !self.default_models_changed
-            && !self.func_agent_models_changed
+            && !self.task_models_changed
             && !self.agent_model_defaults_changed
     }
 }
@@ -868,11 +867,14 @@ mod tests {
             after.ai.default_models.speech_recognition.as_deref(),
             Some("reused-model")
         );
-        assert!(after
-            .ai
-            .func_agent_models
-            .values()
-            .all(|model_id| { !matches!(model_id.as_str(), "reused-model") }));
+        assert_ne!(
+            after.ai.task_models.session_title.fixed_model_id(),
+            Some("reused-model")
+        );
+        assert_ne!(
+            after.ai.task_models.git_commit.fixed_model_id(),
+            Some("reused-model")
+        );
     }
 
     #[tokio::test]
diff --git a/src/crates/assembly/core/src/service/config/types.rs b/src/crates/assembly/core/src/service/config/types.rs
index cfb540d906..038a8aff24 100644
--- a/src/crates/assembly/core/src/service/config/types.rs
+++ b/src/crates/assembly/core/src/service/config/types.rs
@@ -732,6 +732,64 @@ fn default_review_team_rate_limit_status() -> serde_json::Value {
     serde_json::Value::Object(serde_json::Map::new())
 }
 
+/// Model selection for a product-owned AI task.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub enum TaskModelSelection {
+    Inherit,
+    Fixed { model_id: String },
+}
+
+impl TaskModelSelection {
+    pub fn fixed_model_id(&self) -> Option<&str> {
+        match self {
+            Self::Inherit => None,
+            Self::Fixed { model_id } => Some(model_id),
+        }
+    }
+}
+
+fn default_task_model_selection() -> TaskModelSelection {
+    TaskModelSelection::Fixed {
+        model_id: "fast".to_string(),
+    }
+}
+
+fn is_default_task_model_selection(selection: &TaskModelSelection) -> bool {
+    *selection == default_task_model_selection()
+}
+
+/// Model selectors for small product-owned AI tasks.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(default)]
+pub struct TaskModelsConfig {
+    #[serde(
+        default = "default_task_model_selection",
+        skip_serializing_if = "is_default_task_model_selection"
+    )]
+    pub session_title: TaskModelSelection,
+    #[serde(
+        default = "default_task_model_selection",
+        skip_serializing_if = "is_default_task_model_selection"
+    )]
+    pub git_commit: TaskModelSelection,
+}
+
+impl Default for TaskModelsConfig {
+    fn default() -> Self {
+        Self {
+            session_title: default_task_model_selection(),
+            git_commit: default_task_model_selection(),
+        }
+    }
+}
+
+impl TaskModelsConfig {
+    fn is_default(&self) -> bool {
+        *self == Self::default()
+    }
+}
+
 /// AI configuration.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(default)]
@@ -739,10 +797,9 @@ pub struct AIConfig {
     /// All configured models.
     pub models: Vec<AIModelConfig>,
 
-    /// Model mapping for functional agents (e.g. startchat-func-agent, session-title-func-agent).
-    /// func_agent_name -> model_id
-    #[serde(default)]
-    pub func_agent_models: HashMap<String, String>,
+    /// Model selectors for product-owned AI tasks.
+    #[serde(default, skip_serializing_if = "TaskModelsConfig::is_default")]
+    pub task_models: TaskModelsConfig,
 
     /// Default model configuration.
     #[serde(default)]
@@ -815,6 +872,13 @@ pub struct AIConfig {
     #[serde(default)]
     pub browser_control_preferred_browser: String,
 
+    /// Reattach to an already-running browser when BitFun starts. Off by
+    /// default: the browser forgets its approval when it restarts, so this can
+    /// put an approval dialog in front of the user before they asked for the
+    /// browser at all.
+    #[serde(default)]
+    pub browser_control_auto_connect_on_startup: bool,
+
     /// Maximum number of rounds per dialog turn before soft-pausing.
     #[serde(default = "default_max_rounds")]
     pub max_rounds: usize,
@@ -1824,7 +1888,7 @@ impl Default for AIConfig {
     fn default() -> Self {
         Self {
             models: vec![],
-            func_agent_models: std::collections::HashMap::new(),
+            task_models: TaskModelsConfig::default(),
             default_models: DefaultModelsConfig::default(),
             agent_model_defaults: AgentModelDefaultsConfig::default(),
             agent_profiles: std::collections::HashMap::new(),
@@ -1842,6 +1906,7 @@ impl Default for AIConfig {
             debug_mode_config: DebugModeConfig::default(),
             computer_use_enabled: false,
             browser_control_preferred_browser: String::new(),
+            browser_control_auto_connect_on_startup: false,
             max_rounds: default_max_rounds(),
         }
     }
@@ -2775,7 +2840,6 @@ mod tests {
     fn deserializes_missing_stream_timeouts_as_generous_defaults() {
         let config: AIConfig = serde_json::from_value(serde_json::json!({
             "models": [],
-            "func_agent_models": {},
             "default_models": {},
             "agent_profiles": {},
             "proxy": {
@@ -2796,11 +2860,29 @@ mod tests {
         assert!(config.review_teams.contains_key("default"));
     }
 
+    #[test]
+    fn task_models_default_to_fast_and_ignore_removed_mapping() {
+        let removed_key = ["func", "_agent_models"].concat();
+        let mut value = serde_json::json!({});
+        value[&removed_key] = serde_json::json!({ "title": "primary" });
+        let config: AIConfig =
+            serde_json::from_value(value).expect("removed field should be ignored");
+
+        assert_eq!(
+            config.task_models.session_title.fixed_model_id(),
+            Some("fast")
+        );
+        assert_eq!(config.task_models.git_commit.fixed_model_id(), Some("fast"));
+        assert!(serde_json::to_value(config)
+            .expect("config should serialize")
+            .get(&removed_key)
+            .is_none());
+    }
+
     #[test]
     fn preserves_explicit_disabled_tool_json_repair() {
         let config: AIConfig = serde_json::from_value(serde_json::json!({
             "models": [],
-            "func_agent_models": {},
             "default_models": {},
             "agent_profiles": {},
             "allow_tool_json_repair": false,
@@ -2818,7 +2900,6 @@ mod tests {
     fn deserializes_explicit_null_stream_ttft_timeout_as_none() {
         let config: AIConfig = serde_json::from_value(serde_json::json!({
             "models": [],
-            "func_agent_models": {},
             "default_models": {},
             "agent_profiles": {},
             "proxy": {
@@ -2852,7 +2933,6 @@ mod tests {
     fn deserializes_explicit_subagent_max_concurrency() {
         let config: AIConfig = serde_json::from_value(serde_json::json!({
             "models": [],
-            "func_agent_models": {},
             "default_models": {},
             "agent_profiles": {},
             "subagent_max_concurrency": 9,
@@ -2870,7 +2950,6 @@ mod tests {
     fn deserializes_explicit_subagent_batch_execution_policy() {
         let config: AIConfig = serde_json::from_value(serde_json::json!({
             "models": [],
-            "func_agent_models": {},
             "default_models": {},
             "agent_profiles": {},
             "subagent_batch_execution_policy": "force_parallel",
@@ -2891,7 +2970,6 @@ mod tests {
     fn deserializes_mode_profiles_with_null_entries() {
         let config: AIConfig = serde_json::from_value(serde_json::json!({
             "models": [],
-            "func_agent_models": {},
             "default_models": {},
             "agent_profiles": {
                 "Claw": null,
@@ -2922,7 +3000,6 @@ mod tests {
     fn deserializes_explicit_default_review_team_config() {
         let config: AIConfig = serde_json::from_value(serde_json::json!({
             "models": [],
-            "func_agent_models": {},
             "default_models": {},
             "agent_profiles": {},
             "review_teams": {
diff --git a/src/crates/assembly/core/src/service/dispatch/controller.rs b/src/crates/assembly/core/src/service/dispatch/controller.rs
index a3c407dfa1..dc2866b438 100644
--- a/src/crates/assembly/core/src/service/dispatch/controller.rs
+++ b/src/crates/assembly/core/src/service/dispatch/controller.rs
@@ -163,6 +163,10 @@ pub struct DispatchAppendRequest {
     pub content: String,
     #[serde(default)]
     pub display_content: Option<String>,
+    /// Attachments injected with the message into the running turn, under the
+    /// same structural limits as a turn submission's.
+    #[serde(default)]
+    pub attachments: Vec<DispatchAttachmentPayload>,
 }
 
 /// The wire shape and structural limits come from the shared contract; the
@@ -319,12 +323,7 @@ pub(super) async fn push_model_config(
     let ai = serde_json::to_value(&config.ai)
         .map_err(|error| anyhow::anyhow!("encode controller model configuration: {error}"))?;
     let mut payload = serde_json::Map::new();
-    for key in [
-        "models",
-        "default_models",
-        "agent_model_defaults",
-        "func_agent_models",
-    ] {
+    for key in ["models", "default_models", "agent_model_defaults"] {
         if let Some(value) = ai.get(key) {
             payload.insert(key.to_string(), value.clone());
         }
@@ -1461,7 +1460,9 @@ pub(super) fn validate_append_request(request: &DispatchAppendRequest) -> anyhow
     if request.message_id.trim().is_empty() || request.message_id.len() > 128 {
         anyhow::bail!("Dispatch messageId must contain 1-128 bytes");
     }
-    if request.content.trim().is_empty() {
+    // An attachment-only message is a real message; only one with neither text
+    // nor attachments is empty.
+    if request.content.trim().is_empty() && request.attachments.is_empty() {
         anyhow::bail!("Dispatch appended message cannot be empty");
     }
     let total_bytes = request
@@ -1471,6 +1472,7 @@ pub(super) fn validate_append_request(request: &DispatchAppendRequest) -> anyhow
     if total_bytes > MAX_DISPATCH_TEXT_BYTES {
         anyhow::bail!("Dispatch appended message exceeds the 32 KiB request limit");
     }
+    validate_attachment_payloads(&request.attachments)?;
     Ok(())
 }
 
diff --git a/src/crates/assembly/core/src/service/dispatch/device_controller.rs b/src/crates/assembly/core/src/service/dispatch/device_controller.rs
index 220e7d54da..cd2a0b1f8f 100644
--- a/src/crates/assembly/core/src/service/dispatch/device_controller.rs
+++ b/src/crates/assembly/core/src/service/dispatch/device_controller.rs
@@ -465,6 +465,7 @@ pub async fn append_device(
     request: DispatchAppendRequest,
 ) -> anyhow::Result<Value> {
     validate_append_request(&request)?;
+    validate_device_attachment_budget(&request.attachments)?;
     let record = load_device_record(store, &request.job_id).await?;
     let DispatchTarget::Device { device_id, .. } = &record.target else {
         unreachable!("load_device_record validates target kind")
diff --git a/src/crates/assembly/core/src/service/filesystem/service.rs b/src/crates/assembly/core/src/service/filesystem/service.rs
index 9767ba7939..ff18bfb703 100644
--- a/src/crates/assembly/core/src/service/filesystem/service.rs
+++ b/src/crates/assembly/core/src/service/filesystem/service.rs
@@ -23,11 +23,30 @@ async fn read_remote_directory_contents(
     path: &str,
     preferred_remote_connection_id: Option<&str>,
 ) -> Option<BitFunResult<Vec<FileTreeNode>>> {
-    let entry = crate::service::remote_ssh::workspace_state::lookup_remote_connection_with_hint(
-        path,
-        preferred_remote_connection_id,
-    )
-    .await?;
+    let explicit_connection_id = preferred_remote_connection_id
+        .map(str::trim)
+        .filter(|value| !value.is_empty());
+    let remote_entry = if let Some(connection_id) = explicit_connection_id {
+        crate::service::remote_ssh::workspace_state::lookup_remote_connection_scoped(
+            path,
+            connection_id,
+        )
+        .await
+    } else {
+        crate::service::remote_ssh::workspace_state::lookup_remote_connection_with_hint(path, None)
+            .await
+    };
+    let entry = match remote_entry {
+        Some(entry) => entry,
+        None if explicit_connection_id.is_some() => {
+            return Some(Err(BitFunError::service(format!(
+                "Remote workspace connection '{}' is unavailable or does not own path '{}'; local filesystem fallback was not attempted",
+                explicit_connection_id.unwrap_or_default(),
+                path
+            ))));
+        }
+        None => return None,
+    };
 
     let Some(manager) = crate::service::remote_ssh::workspace_state::get_remote_workspace_manager()
     else {
@@ -526,4 +545,39 @@ mod tests {
             "unexpected error: {error}"
         );
     }
+
+    #[tokio::test]
+    async fn explicit_remote_scope_never_falls_back_to_a_local_directory() {
+        let temp = tempfile::tempdir().expect("tempdir");
+        let remote_root = temp.path().to_string_lossy().to_string();
+        let registered_connection_id = "filesystem-exact-scope-registered";
+        let requested_connection_id = "filesystem-exact-scope-requested";
+        let manager = init_remote_workspace_manager();
+        manager
+            .register_remote_workspace(
+                remote_root.clone(),
+                registered_connection_id.to_string(),
+                "Other remote".to_string(),
+                "other-remote-host".to_string(),
+            )
+            .await;
+
+        let error = FileSystemService::default()
+            .get_directory_contents_with_remote_hint(&remote_root, Some(requested_connection_id))
+            .await
+            .expect_err("an explicit remote scope must not read the controller filesystem");
+
+        manager
+            .unregister_remote_workspace(registered_connection_id, &remote_root)
+            .await;
+        let message = error.to_string();
+        assert!(
+            message.contains(requested_connection_id),
+            "unexpected error: {message}"
+        );
+        assert!(
+            message.contains("local filesystem fallback was not attempted"),
+            "unexpected error: {message}"
+        );
+    }
 }
diff --git a/src/crates/assembly/core/src/service/i18n/mod.rs b/src/crates/assembly/core/src/service/i18n/mod.rs
index 783acbec53..3d55307dd7 100644
--- a/src/crates/assembly/core/src/service/i18n/mod.rs
+++ b/src/crates/assembly/core/src/service/i18n/mod.rs
@@ -3,12 +3,16 @@
 //! Provides i18n support for backend text.
 
 pub mod generated_locale_contract;
+#[cfg(feature = "i18n-runtime")]
 mod locale_registry;
 mod model_copy;
+#[cfg(feature = "i18n-runtime")]
 mod service;
 mod types;
 
+#[cfg(feature = "i18n-runtime")]
 pub use locale_registry::*;
 pub use model_copy::*;
+#[cfg(feature = "i18n-runtime")]
 pub use service::*;
 pub use types::*;
diff --git a/src/crates/assembly/core/src/service/i18n/types.rs b/src/crates/assembly/core/src/service/i18n/types.rs
index f8e44629ea..d9b13c49f3 100644
--- a/src/crates/assembly/core/src/service/i18n/types.rs
+++ b/src/crates/assembly/core/src/service/i18n/types.rs
@@ -158,19 +158,22 @@ impl Default for I18nConfig {
     }
 }
 
-/// Translation arguments
+/// Translation arguments passed to backend Fluent messages.
+#[cfg(feature = "i18n-runtime")]
 #[derive(Debug, Clone, Default)]
 pub struct TranslationArgs {
     args: std::collections::HashMap<String, FluentValue>,
 }
 
-/// Fluent value type
+/// Fluent-compatible backend value type.
+#[cfg(feature = "i18n-runtime")]
 #[derive(Debug, Clone)]
 pub enum FluentValue {
     String(String),
     Number(f64),
 }
 
+#[cfg(feature = "i18n-runtime")]
 impl TranslationArgs {
     pub fn new() -> Self {
         Self::default()
diff --git a/src/crates/assembly/core/src/service/mcp/server/manager/external_lifecycle.rs b/src/crates/assembly/core/src/service/mcp/server/manager/external_lifecycle.rs
index bba62016fc..1775e53f6f 100644
--- a/src/crates/assembly/core/src/service/mcp/server/manager/external_lifecycle.rs
+++ b/src/crates/assembly/core/src/service/mcp/server/manager/external_lifecycle.rs
@@ -48,11 +48,22 @@ impl MCPServerManager {
         external_start_token_is_current(start_tokens.get(server_id), expected)
     }
 
-    async fn remove_ephemeral_server_for_start(&self, server_id: &str, expected: &Arc<()>) -> bool {
+    async fn remove_ephemeral_server_for_start(
+        &self,
+        server_id: &str,
+        expected: &Arc<()>,
+        failure: MCPServerStartFailure,
+    ) -> bool {
         let _lifecycle_guard = self.ephemeral_lifecycle.lock().await;
         if !self.external_start_token_matches(server_id, expected).await {
             return false;
         }
+        // Publish the safe failure fact before cleanup. Cleanup may itself
+        // fail, but the product surface must still be able to explain why the
+        // server left Starting.
+        self.runtime
+            .set_start_failure(server_id.to_string(), failure)
+            .await;
         if let Err(error) = self.remove_ephemeral_server(server_id).await {
             warn!(
                 "Could not clean up failed external MCP startup: id={} error={}",
@@ -73,6 +84,7 @@ impl MCPServerManager {
         config.validate()?;
         let _lifecycle_guard = self.ephemeral_lifecycle.lock().await;
         let server_id = config.id.clone();
+        self.runtime.clear_start_failure(&server_id).await;
         let start_token = Arc::new(());
         self.ephemeral_start_tokens
             .write()
@@ -183,12 +195,13 @@ impl MCPServerManager {
                         }
                     }
                     Ok(Err(error)) => {
+                        let failure = MCPServerStartFailure::classify(&error.to_string());
                         warn!(
                             "External ephemeral MCP server failed to start: id={} error={}",
                             server_id, error
                         );
                         if manager
-                            .remove_ephemeral_server_for_start(&server_id, &start_token)
+                            .remove_ephemeral_server_for_start(&server_id, &start_token, failure)
                             .await
                         {
                             notify_external_tool_registry_changed();
@@ -200,7 +213,11 @@ impl MCPServerManager {
                             server_id
                         );
                         if manager
-                            .remove_ephemeral_server_for_start(&server_id, &start_token)
+                            .remove_ephemeral_server_for_start(
+                                &server_id,
+                                &start_token,
+                                MCPServerStartFailure::Timeout,
+                            )
                             .await
                         {
                             notify_external_tool_registry_changed();
@@ -220,6 +237,7 @@ impl MCPServerManager {
         const RETIREMENT_RECLAIM_ATTEMPTS: usize = 3;
         const RETIREMENT_RETRY_DELAY: std::time::Duration = std::time::Duration::from_millis(250);
         let _lifecycle_guard = self.ephemeral_lifecycle.lock().await;
+        self.runtime.clear_start_failure(server_id).await;
         self.ephemeral_start_tokens.write().await.remove(server_id);
         if !self.runtime.contains(server_id).await {
             self.runtime.remove_runtime_config(server_id).await;
diff --git a/src/crates/assembly/core/src/service/mcp/server/manager/mod.rs b/src/crates/assembly/core/src/service/mcp/server/manager/mod.rs
index 0127e2112a..d890ebc8af 100644
--- a/src/crates/assembly/core/src/service/mcp/server/manager/mod.rs
+++ b/src/crates/assembly/core/src/service/mcp/server/manager/mod.rs
@@ -24,7 +24,7 @@ use crate::service::mcp::protocol::{MCPError, MCPPrompt, MCPResource};
 use crate::service::workspace::get_global_workspace_service;
 use crate::util::errors::{BitFunError, BitFunResult};
 use bitfun_services_integrations::mcp::server::MCPConnectionEvent;
-use bitfun_services_integrations::mcp::server::MCPServerRuntimeState;
+use bitfun_services_integrations::mcp::server::{MCPServerRuntimeState, MCPServerStartFailure};
 use log::{debug, error, info, warn};
 use serde_json::{json, Value};
 use std::collections::{HashMap, HashSet};
@@ -156,6 +156,13 @@ impl MCPServerManager {
                 .contains(server_id),
         )
     }
+
+    pub async fn external_server_start_failure(
+        &self,
+        server_id: &str,
+    ) -> Option<MCPServerStartFailure> {
+        self.runtime.start_failure(server_id).await
+    }
 }
 
 fn should_finish_ephemeral_retirement(
diff --git a/src/crates/assembly/core/src/service/mcp/server/manager/tests.rs b/src/crates/assembly/core/src/service/mcp/server/manager/tests.rs
index b8cc537e95..6b71ad30f4 100644
--- a/src/crates/assembly/core/src/service/mcp/server/manager/tests.rs
+++ b/src/crates/assembly/core/src/service/mcp/server/manager/tests.rs
@@ -40,6 +40,75 @@ fn superseded_external_start_token_cannot_clean_up_current_instance() {
     assert!(!super::external_start_token_is_current(None, &first));
 }
 
+#[tokio::test]
+async fn failed_external_start_publishes_a_reason_before_runtime_cleanup() {
+    use crate::service::mcp::{ConfigLocation, MCPServerConfig, MCPServerTimeouts, MCPServerType};
+    use std::collections::HashMap;
+
+    let root = tempfile::tempdir().expect("tempdir");
+    let path_manager = Arc::new(
+        crate::infrastructure::PathManager::with_user_root_for_tests(root.path().join("config")),
+    );
+    let config_service = Arc::new(
+        crate::service::config::ConfigService::with_settings(
+            crate::service::config::ConfigManagerSettings {
+                path_manager: Some(path_manager),
+                auto_save: false,
+                backup_count: 0,
+            },
+        )
+        .await
+        .expect("config service"),
+    );
+    let mcp_config_service = Arc::new(
+        crate::service::mcp::config::MCPConfigService::new(config_service)
+            .expect("MCP config service"),
+    );
+    let manager = super::MCPServerManager::assemble(mcp_config_service, None);
+    let server_id = "external-mcp-failed-start";
+
+    manager
+        .install_external_ephemeral_server(
+            MCPServerConfig {
+                id: server_id.to_string(),
+                name: "Unavailable external MCP".to_string(),
+                server_type: MCPServerType::Local,
+                transport: None,
+                command: Some("bitfun-command-that-does-not-exist".to_string()),
+                args: Vec::new(),
+                env: HashMap::new(),
+                working_directory: None,
+                inherit_parent_environment: Some(false),
+                headers: HashMap::new(),
+                url: None,
+                auto_start: true,
+                enabled: true,
+                location: ConfigLocation::User,
+                capabilities: Vec::new(),
+                settings: HashMap::new(),
+                oauth: None,
+                oauth_enabled: None,
+                xaa: None,
+                timeouts: MCPServerTimeouts::default(),
+            },
+            "workspace-a".to_string(),
+        )
+        .await
+        .expect("registration is asynchronous");
+
+    let reason = tokio::time::timeout(Duration::from_secs(5), async {
+        loop {
+            if let Some(failure) = manager.external_server_start_failure(server_id).await {
+                break failure;
+            }
+            tokio::task::yield_now().await;
+        }
+    })
+    .await
+    .expect("failed startup should publish a reason");
+    assert_eq!(reason, super::MCPServerStartFailure::CommandUnavailable);
+}
+
 #[tokio::test]
 async fn oauth_credentials_follow_the_manager_injected_data_dir() {
     let root = tempfile::tempdir().expect("tempdir");
diff --git a/src/crates/assembly/core/src/service/mod.rs b/src/crates/assembly/core/src/service/mod.rs
index 3189351035..d1c2db94dc 100644
--- a/src/crates/assembly/core/src/service/mod.rs
+++ b/src/crates/assembly/core/src/service/mod.rs
@@ -62,9 +62,12 @@ pub use terminal_core as terminal;
 // Re-export main components.
 #[cfg(feature = "announcement")]
 pub use announcement::{AnnouncementCard, AnnouncementScheduler, AnnouncementSchedulerRef};
+#[cfg(feature = "diagnostics")]
+pub use bitfun_services_core::diagnostics;
+#[cfg(feature = "diff")]
+pub use bitfun_services_core::diff;
 #[cfg(feature = "process-runtime")]
 pub use bitfun_services_core::system;
-pub use bitfun_services_core::{diagnostics, diff};
 #[cfg(feature = "file-watch")]
 pub use bitfun_services_integrations::file_watch;
 #[cfg(feature = "workspace-runtime")]
@@ -76,6 +79,7 @@ pub use config::{ConfigManager, ConfigProvider, ConfigService};
 pub use cron::{
     get_global_cron_service, set_global_cron_service, CronEventSubscriber, CronService,
 };
+#[cfg(feature = "diff")]
 pub use diff::{
     DiffConfig, DiffHunk, DiffLine, DiffLineType, DiffOptions, DiffResult, DiffService,
 };
@@ -89,7 +93,9 @@ pub use file_watch::{
 pub use filesystem::{DirectoryStats, FileSystemService, FileSystemServiceFactory};
 #[cfg(feature = "git")]
 pub use git::GitService;
-pub use i18n::{get_global_i18n_service, I18nConfig, I18nService, LocaleId, LocaleMetadata};
+#[cfg(feature = "i18n-runtime")]
+pub use i18n::{get_global_i18n_service, I18nService};
+pub use i18n::{I18nConfig, LocaleId, LocaleMetadata};
 #[cfg(feature = "lsp")]
 pub use lsp::LspManager;
 #[cfg(feature = "mcp-runtime")]
diff --git a/src/crates/assembly/core/src/service/remote_connect/mod.rs b/src/crates/assembly/core/src/service/remote_connect/mod.rs
index 4509929b9f..bd33da147a 100644
--- a/src/crates/assembly/core/src/service/remote_connect/mod.rs
+++ b/src/crates/assembly/core/src/service/remote_connect/mod.rs
@@ -242,7 +242,7 @@ impl DelegatedIdentityAuthorization {
         }
     }
 
-    fn into_response(self, local_device_id: &str) -> DelegatedIdentityResolution {
+    fn into_response(self, local_device_id: &str) -> AuthorizedCredentialResolution {
         use base64::{engine::general_purpose::STANDARD as B64, Engine};
 
         let Self {
@@ -251,7 +251,7 @@ impl DelegatedIdentityAuthorization {
             master_key,
             host_lease,
         } = self;
-        DelegatedIdentityResolution {
+        AuthorizedCredentialResolution {
             response: remote_server::RemoteResponse::DelegateIdentity {
                 token,
                 user_id,
@@ -263,12 +263,85 @@ impl DelegatedIdentityAuthorization {
     }
 }
 
-struct DelegatedIdentityResolution {
+/// A full account device credential minted for a peer device that cannot
+/// authenticate on its own, together with the host account lease that
+/// authorized it. Deliberately a distinct type from
+/// [`DelegatedIdentityAuthorization`]: that one carries a 24-hour delegated
+/// token limited to device discovery and RPC, this one carries a 30-day full
+/// device credential. They must never be routed into each other's response.
+pub struct ProvisionedDeviceAuthorization {
+    token: String,
+    user_id: String,
+    master_key: [u8; 32],
+    /// The device the credential was minted *for*, echoed back so the caller
+    /// can verify the relay registered the id it asked for.
+    device_id: String,
+    host_lease: Option<Box<dyn Send>>,
+}
+
+impl ProvisionedDeviceAuthorization {
+    pub fn new(token: String, user_id: String, master_key: [u8; 32], device_id: String) -> Self {
+        Self {
+            token,
+            user_id,
+            master_key,
+            device_id,
+            host_lease: None,
+        }
+    }
+
+    pub fn with_host_lease<L>(
+        token: String,
+        user_id: String,
+        master_key: [u8; 32],
+        device_id: String,
+        lease: L,
+    ) -> Self
+    where
+        L: Send + 'static,
+    {
+        Self {
+            token,
+            user_id,
+            master_key,
+            device_id,
+            host_lease: Some(Box::new(lease)),
+        }
+    }
+
+    fn into_response(self) -> AuthorizedCredentialResolution {
+        use base64::{engine::general_purpose::STANDARD as B64, Engine};
+
+        let Self {
+            token,
+            user_id,
+            master_key,
+            device_id,
+            host_lease,
+        } = self;
+        AuthorizedCredentialResolution {
+            response: remote_server::RemoteResponse::PeerDeviceProvisioned {
+                token,
+                user_id,
+                master_key: B64.encode(master_key),
+                device_id,
+            },
+            _host_lease: host_lease,
+        }
+    }
+}
+
+/// An authorized credential response together with the host account lease that
+/// authorized it. The lease is retained after the provider returns and released
+/// only after the encrypted room response has been sent, so an account
+/// transition cannot clear state and then be overwritten by a retiring
+/// verifier. Carries either credential kind.
+struct AuthorizedCredentialResolution {
     response: remote_server::RemoteResponse,
     _host_lease: Option<Box<dyn Send>>,
 }
 
-impl DelegatedIdentityResolution {
+impl AuthorizedCredentialResolution {
     fn error(message: impl Into<String>) -> Self {
         Self {
             response: remote_server::RemoteResponse::Error {
@@ -323,6 +396,11 @@ pub struct RemoteConnectService {
     /// login. Resolved on demand when a paired client sends
     /// `get_delegated_identity` over the room channel.
     delegated_identity_fn: Arc<RwLock<Option<DelegatedIdentityFn>>>,
+    /// Callback that mints a full account device credential for a peer device
+    /// on behalf of a paired client. Set by the desktop layer after account
+    /// login. Resolved on demand when a paired client sends
+    /// `provision_peer_device` over the room channel.
+    peer_device_provision_fn: Arc<RwLock<Option<PeerDeviceProvisionFn>>>,
     /// Non-secret username embedded in the QR when the desktop is logged in.
     account_pairing_username: Arc<RwLock<Option<String>>>,
     /// When set, pairing requires BitFun account username+password and the
@@ -342,6 +420,24 @@ type DelegatedIdentityFn = Arc<
         + Sync,
 >;
 
+/// Provider minting a full account device credential for a peer device.
+/// Takes `(device_id, device_name, request_id)`; `request_id` comes from the
+/// device being provisioned so retries stay idempotent at the relay.
+type PeerDeviceProvisionFn = Arc<
+    dyn Fn(
+            String,
+            String,
+            String,
+        ) -> std::pin::Pin<
+            Box<
+                dyn std::future::Future<Output = Result<ProvisionedDeviceAuthorization, String>>
+                    + Send
+                    + Sync,
+            >,
+        > + Send
+        + Sync,
+>;
+
 /// Verifies mobile-submitted account credentials. Returns the canonical
 /// account `user_id` when the credentials match the logged-in desktop account.
 type AccountPairingVerifierFn = Arc<
@@ -397,6 +493,7 @@ impl RemoteConnectService {
             active_device_connection_id: Arc::new(RwLock::new(None)),
             online_devices: Arc::new(RwLock::new(Vec::new())),
             delegated_identity_fn: Arc::new(RwLock::new(None)),
+            peer_device_provision_fn: Arc::new(RwLock::new(None)),
             account_pairing_username: Arc::new(RwLock::new(None)),
             account_pairing_verifier: Arc::new(RwLock::new(None)),
         })
@@ -415,6 +512,24 @@ impl RemoteConnectService {
         *self.delegated_identity_fn.write().await = Some(Arc::new(move || Box::pin(f())));
     }
 
+    /// Set the peer-device provisioning provider (called by desktop after
+    /// login). Mints a full account device credential with a host account lease
+    /// for a device the paired client vouches for.
+    pub async fn set_peer_device_provisioner<F, Fut>(&self, f: F)
+    where
+        F: Fn(String, String, String) -> Fut + Send + Sync + 'static,
+        Fut: std::future::Future<Output = Result<ProvisionedDeviceAuthorization, String>>
+            + Send
+            + Sync
+            + 'static,
+    {
+        *self.peer_device_provision_fn.write().await = Some(Arc::new(
+            move |device_id, device_name, request_id| {
+                Box::pin(f(device_id, device_name, request_id))
+            },
+        ));
+    }
+
     /// Enable account-password pairing in the QR.
     /// `None` disables account mode; `Some(username)` enables it (username may
     /// be empty when only `auth=account` should be advertised without prefill).
@@ -579,26 +694,26 @@ impl RemoteConnectService {
         delegated_identity_fn: &Arc<RwLock<Option<DelegatedIdentityFn>>>,
         trusted_mobile_identity: &Arc<RwLock<Option<TrustedMobileIdentity>>>,
         local_device_id: &str,
-    ) -> DelegatedIdentityResolution {
+    ) -> AuthorizedCredentialResolution {
         let trusted_identity = trusted_mobile_identity.read().await.clone();
         let Some(trusted_identity) = trusted_identity else {
-            return DelegatedIdentityResolution::error(
+            return AuthorizedCredentialResolution::error(
                 "Pairing authorization expired; scan a new QR code",
             );
         };
         let provider = delegated_identity_fn.read().await.clone();
         let Some(get_identity) = provider else {
-            return DelegatedIdentityResolution::error(
+            return AuthorizedCredentialResolution::error(
                 "Desktop is not logged into a BitFun account",
             );
         };
         let Some(authorization) = get_identity().await else {
-            return DelegatedIdentityResolution::error(
+            return AuthorizedCredentialResolution::error(
                 "Desktop is not logged into a BitFun account",
             );
         };
         if authorization.user_id != trusted_identity.user_id {
-            return DelegatedIdentityResolution::error(
+            return AuthorizedCredentialResolution::error(
                 "Paired mobile identity no longer matches the desktop account",
             );
         }
@@ -606,6 +721,76 @@ impl RemoteConnectService {
         authorization.into_response(local_device_id)
     }
 
+    /// Answer a paired client's `provision_peer_device` request using the
+    /// provider registered by the desktop layer after account login.
+    ///
+    /// Gated exactly like `resolve_delegated_identity_response`: only a client
+    /// that completed pairing (which requires the account password whenever the
+    /// desktop is logged in) may ask the desktop to add a device to its account.
+    async fn resolve_provisioned_device_response(
+        peer_device_provision_fn: &Arc<RwLock<Option<PeerDeviceProvisionFn>>>,
+        trusted_mobile_identity: &Arc<RwLock<Option<TrustedMobileIdentity>>>,
+        device_id: &str,
+        device_name: &str,
+        request_id: &str,
+    ) -> AuthorizedCredentialResolution {
+        let trusted_identity = trusted_mobile_identity.read().await.clone();
+        let Some(trusted_identity) = trusted_identity else {
+            return AuthorizedCredentialResolution::error(
+                "Pairing authorization expired; scan a new QR code",
+            );
+        };
+
+        // Checked here as well as at the relay so a malformed id fails with a
+        // usable message instead of an opaque HTTP 400 one hop away.
+        if device_id.len() != 32 || !device_id.bytes().all(|b| b.is_ascii_hexdigit()) {
+            return AuthorizedCredentialResolution::error(
+                "Device id must be 32 hexadecimal characters",
+            );
+        }
+        if device_id.bytes().any(|b| b.is_ascii_uppercase()) {
+            return AuthorizedCredentialResolution::error("Device id must be lowercase");
+        }
+        if device_name.trim().is_empty() {
+            return AuthorizedCredentialResolution::error("Device name is required");
+        }
+        if request_id.trim().is_empty() {
+            return AuthorizedCredentialResolution::error("Request id is required");
+        }
+
+        let provider = peer_device_provision_fn.read().await.clone();
+        let Some(provision) = provider else {
+            return AuthorizedCredentialResolution::error(
+                "Desktop is not logged into a BitFun account",
+            );
+        };
+        let authorization = match provision(
+            device_id.to_string(),
+            device_name.to_string(),
+            request_id.to_string(),
+        )
+        .await
+        {
+            Ok(authorization) => authorization,
+            Err(message) => return AuthorizedCredentialResolution::error(message),
+        };
+        if authorization.user_id != trusted_identity.user_id {
+            return AuthorizedCredentialResolution::error(
+                "Paired mobile identity no longer matches the desktop account",
+            );
+        }
+        // The credential is only useful for the device that asked for it; a
+        // mismatch means the account switched mid-flight or the relay answered
+        // for someone else.
+        if authorization.device_id != device_id {
+            return AuthorizedCredentialResolution::error(
+                "Provisioned credential does not match the requested device",
+            );
+        }
+        info!("Provisioned account device credential for paired client");
+        authorization.into_response()
+    }
+
     async fn send_pairing_error_response(
         relay_arc: &Arc<RwLock<Option<RelayClient>>>,
         correlation_id: &str,
@@ -866,6 +1051,7 @@ impl RemoteConnectService {
         let active_room_owner = self.active_room_owner.clone();
         let trusted_mobile_identity_arc = self.trusted_mobile_identity.clone();
         let delegated_identity_fn_arc = self.delegated_identity_fn.clone();
+        let peer_device_provision_fn_arc = self.peer_device_provision_fn.clone();
         let account_pairing_verifier_arc = self.account_pairing_verifier.clone();
         let local_device_id = self.device_identity.device_id.clone();
         tokio::spawn(async move {
@@ -921,21 +1107,37 @@ impl RemoteConnectService {
                                     Ok((cmd, request_id)) => {
                                         handled_as_active_command = true;
                                         debug!("Remote command decrypted");
-                                        let response_resolution = if matches!(
-                                            cmd,
-                                            remote_server::RemoteCommand::GetDelegatedIdentity
-                                        ) {
-                                            RemoteConnectService::resolve_delegated_identity_response(
-                                                &delegated_identity_fn_arc,
-                                                &trusted_mobile_identity_arc,
-                                                &local_device_id,
-                                            )
-                                            .await
-                                        } else {
-                                            DelegatedIdentityResolution {
+                                        // Account-credential commands are answered
+                                        // here, before dispatch: this loop owns the
+                                        // trusted pairing identity that authorizes
+                                        // them. Everything else routes normally.
+                                        let response_resolution = match &cmd {
+                                            remote_server::RemoteCommand::GetDelegatedIdentity => {
+                                                RemoteConnectService::resolve_delegated_identity_response(
+                                                    &delegated_identity_fn_arc,
+                                                    &trusted_mobile_identity_arc,
+                                                    &local_device_id,
+                                                )
+                                                .await
+                                            }
+                                            remote_server::RemoteCommand::ProvisionPeerDevice {
+                                                device_id,
+                                                device_name,
+                                                request_id,
+                                            } => {
+                                                RemoteConnectService::resolve_provisioned_device_response(
+                                                    &peer_device_provision_fn_arc,
+                                                    &trusted_mobile_identity_arc,
+                                                    device_id,
+                                                    device_name,
+                                                    request_id,
+                                                )
+                                                .await
+                                            }
+                                            _ => AuthorizedCredentialResolution {
                                                 response: server.dispatch(&cmd).await,
                                                 _host_lease: None,
-                                            }
+                                            },
                                         };
                                         match server
                                             .encrypt_response(
@@ -2361,5 +2563,268 @@ mod tests {
         .await
         .expect("account replacement should proceed after the response is released");
     }
+
+    const WATCH_DEVICE_ID: &str = "0123456789abcdef0123456789abcdef";
+
+    fn peer_provisioner(user_id: &'static str, device_id: &'static str) -> PeerDeviceProvisionFn {
+        Arc::new(move |_device_id, _device_name, _request_id| {
+            Box::pin(async move {
+                Ok(ProvisionedDeviceAuthorization::new(
+                    "watch-device-token".to_string(),
+                    user_id.to_string(),
+                    [9_u8; 32],
+                    device_id.to_string(),
+                ))
+            })
+        })
+    }
+
+    fn trusted_as(user_id: &str) -> Arc<RwLock<Option<TrustedMobileIdentity>>> {
+        Arc::new(RwLock::new(Some(TrustedMobileIdentity {
+            mobile_install_id: "install-1".to_string(),
+            user_id: user_id.to_string(),
+        })))
+    }
+
+    #[tokio::test]
+    async fn provisioning_requires_a_trusted_pairing_before_minting_credentials() {
+        let provider_called = Arc::new(AtomicBool::new(false));
+        let called = provider_called.clone();
+        let provider: PeerDeviceProvisionFn =
+            Arc::new(move |_device_id, _device_name, _request_id| {
+                let called = called.clone();
+                Box::pin(async move {
+                    called.store(true, Ordering::SeqCst);
+                    Ok(ProvisionedDeviceAuthorization::new(
+                        "watch-device-token".to_string(),
+                        "account-user".to_string(),
+                        [9_u8; 32],
+                        WATCH_DEVICE_ID.to_string(),
+                    ))
+                })
+            });
+        let provider = Arc::new(RwLock::new(Some(provider)));
+        let trusted = Arc::new(RwLock::new(None));
+
+        let response = RemoteConnectService::resolve_provisioned_device_response(
+            &provider,
+            &trusted,
+            WATCH_DEVICE_ID,
+            "HarmonyOS Watch",
+            "5f0d1c1a-0000-4000-8000-000000000001",
+        )
+        .await;
+
+        assert!(matches!(
+            response.response,
+            remote_server::RemoteResponse::Error { .. }
+        ));
+        assert!(
+            !provider_called.load(Ordering::SeqCst),
+            "an unpaired caller must never reach the relay"
+        );
+    }
+
+    #[tokio::test]
+    async fn provisioning_uses_the_account_bound_during_pairing() {
+        let provider = Arc::new(RwLock::new(Some(peer_provisioner(
+            "paired-user",
+            WATCH_DEVICE_ID,
+        ))));
+
+        let response = RemoteConnectService::resolve_provisioned_device_response(
+            &provider,
+            &trusted_as("paired-user"),
+            WATCH_DEVICE_ID,
+            "HarmonyOS Watch",
+            "5f0d1c1a-0000-4000-8000-000000000001",
+        )
+        .await;
+
+        match response.response {
+            remote_server::RemoteResponse::PeerDeviceProvisioned {
+                token,
+                user_id,
+                device_id,
+                ..
+            } => {
+                assert_eq!(token, "watch-device-token");
+                assert_eq!(user_id, "paired-user");
+                // The provisioned device, not the delegating desktop.
+                assert_eq!(device_id, WATCH_DEVICE_ID);
+            }
+            other => panic!("expected a provisioned credential, got {other:?}"),
+        }
+    }
+
+    #[tokio::test]
+    async fn provisioning_rejects_a_provider_for_another_account() {
+        let provider = Arc::new(RwLock::new(Some(peer_provisioner(
+            "other-user",
+            WATCH_DEVICE_ID,
+        ))));
+
+        let response = RemoteConnectService::resolve_provisioned_device_response(
+            &provider,
+            &trusted_as("paired-user"),
+            WATCH_DEVICE_ID,
+            "HarmonyOS Watch",
+            "5f0d1c1a-0000-4000-8000-000000000001",
+        )
+        .await;
+
+        assert!(matches!(
+            response.response,
+            remote_server::RemoteResponse::Error { .. }
+        ));
+    }
+
+    #[tokio::test]
+    async fn provisioning_rejects_a_credential_minted_for_a_different_device() {
+        let provider = Arc::new(RwLock::new(Some(peer_provisioner(
+            "paired-user",
+            "ffffffffffffffffffffffffffffffff",
+        ))));
+
+        let response = RemoteConnectService::resolve_provisioned_device_response(
+            &provider,
+            &trusted_as("paired-user"),
+            WATCH_DEVICE_ID,
+            "HarmonyOS Watch",
+            "5f0d1c1a-0000-4000-8000-000000000001",
+        )
+        .await;
+
+        assert!(matches!(
+            response.response,
+            remote_server::RemoteResponse::Error { .. }
+        ));
+    }
+
+    #[tokio::test]
+    async fn provisioning_rejects_device_ids_the_relay_would_refuse() {
+        let provider_called = Arc::new(AtomicBool::new(false));
+        let called = provider_called.clone();
+        let provider: PeerDeviceProvisionFn =
+            Arc::new(move |_device_id, _device_name, _request_id| {
+                let called = called.clone();
+                Box::pin(async move {
+                    called.store(true, Ordering::SeqCst);
+                    Ok(ProvisionedDeviceAuthorization::new(
+                        "watch-device-token".to_string(),
+                        "paired-user".to_string(),
+                        [9_u8; 32],
+                        WATCH_DEVICE_ID.to_string(),
+                    ))
+                })
+            });
+        let provider = Arc::new(RwLock::new(Some(provider)));
+
+        // Too short, non-hex, and uppercase: the three shapes the relay's
+        // `provision_device` validator rejects.
+        for bad_id in [
+            "watch-0123456789abcdef",
+            "0123456789abcdef0123456789abcdeg",
+            "0123456789ABCDEF0123456789ABCDEF",
+        ] {
+            let response = RemoteConnectService::resolve_provisioned_device_response(
+                &provider,
+                &trusted_as("paired-user"),
+                bad_id,
+                "HarmonyOS Watch",
+                "5f0d1c1a-0000-4000-8000-000000000001",
+            )
+            .await;
+            assert!(
+                matches!(
+                    response.response,
+                    remote_server::RemoteResponse::Error { .. }
+                ),
+                "{bad_id} should be rejected before the relay sees it"
+            );
+        }
+        assert!(
+            !provider_called.load(Ordering::SeqCst),
+            "a malformed id must fail locally rather than at the relay"
+        );
+    }
+
+    #[tokio::test]
+    async fn provisioning_surfaces_the_relay_failure_reason() {
+        let provider: PeerDeviceProvisionFn =
+            Arc::new(move |_device_id, _device_name, _request_id| {
+                Box::pin(async move { Err("relay rejected the request".to_string()) })
+            });
+        let provider = Arc::new(RwLock::new(Some(provider)));
+
+        let response = RemoteConnectService::resolve_provisioned_device_response(
+            &provider,
+            &trusted_as("paired-user"),
+            WATCH_DEVICE_ID,
+            "HarmonyOS Watch",
+            "5f0d1c1a-0000-4000-8000-000000000001",
+        )
+        .await;
+
+        match response.response {
+            // The person is standing there watching a watch spin; a generic
+            // failure would send them to the wrong fix.
+            remote_server::RemoteResponse::Error { message } => {
+                assert!(message.contains("relay rejected the request"), "{message}");
+            }
+            other => panic!("expected the relay reason to survive, got {other:?}"),
+        }
+    }
+
+    #[tokio::test]
+    async fn provisioning_keeps_account_lease_until_response_is_released() {
+        let account_lifecycle = Arc::new(Mutex::new(()));
+        let provider_lifecycle = account_lifecycle.clone();
+        let provider: PeerDeviceProvisionFn =
+            Arc::new(move |_device_id, _device_name, _request_id| {
+                let provider_lifecycle = provider_lifecycle.clone();
+                Box::pin(async move {
+                    let lease = provider_lifecycle.lock_owned().await;
+                    Ok(ProvisionedDeviceAuthorization::with_host_lease(
+                        "watch-device-token".to_string(),
+                        "paired-user".to_string(),
+                        [9_u8; 32],
+                        WATCH_DEVICE_ID.to_string(),
+                        lease,
+                    ))
+                })
+            });
+        let provider = Arc::new(RwLock::new(Some(provider)));
+
+        let response = RemoteConnectService::resolve_provisioned_device_response(
+            &provider,
+            &trusted_as("paired-user"),
+            WATCH_DEVICE_ID,
+            "HarmonyOS Watch",
+            "5f0d1c1a-0000-4000-8000-000000000001",
+        )
+        .await;
+        assert!(matches!(
+            &response.response,
+            remote_server::RemoteResponse::PeerDeviceProvisioned { .. }
+        ));
+        assert!(
+            tokio::time::timeout(
+                std::time::Duration::from_millis(20),
+                account_lifecycle.clone().lock_owned(),
+            )
+            .await
+            .is_err(),
+            "account replacement must remain blocked while the response is in flight"
+        );
+
+        drop(response);
+        tokio::time::timeout(
+            std::time::Duration::from_secs(1),
+            account_lifecycle.lock_owned(),
+        )
+        .await
+        .expect("account replacement should proceed after the response is released");
+    }
 }
 
diff --git a/src/crates/assembly/core/src/service/remote_ssh/mod.rs b/src/crates/assembly/core/src/service/remote_ssh/mod.rs
index d00635410e..13f4d7f365 100644
--- a/src/crates/assembly/core/src/service/remote_ssh/mod.rs
+++ b/src/crates/assembly/core/src/service/remote_ssh/mod.rs
@@ -13,7 +13,9 @@ pub mod remote_terminal;
 pub mod types;
 pub mod workspace_state;
 
-pub use bitfun_services_integrations::remote_ssh::{build_remote_git_command, shell_quote_posix};
+pub use bitfun_services_integrations::remote_ssh::{
+    build_remote_git_command, search_remote_file_names, shell_quote_posix, RemoteFileNameSearch,
+};
 #[cfg(feature = "ssh-remote")]
 pub use bitfun_services_integrations::remote_ssh::{dispatch_ssh, relay_deploy};
 #[cfg(not(feature = "ssh-remote"))]
diff --git a/src/crates/assembly/core/src/service/remote_ssh/workspace_state.rs b/src/crates/assembly/core/src/service/remote_ssh/workspace_state.rs
index 037c5a6602..9de0ccae05 100644
--- a/src/crates/assembly/core/src/service/remote_ssh/workspace_state.rs
+++ b/src/crates/assembly/core/src/service/remote_ssh/workspace_state.rs
@@ -221,6 +221,18 @@ impl RemoteWorkspaceStateManager {
             .await
     }
 
+    /// Resolve an exact `(connection_id, path)` workspace scope without
+    /// selecting a different connection through legacy hint behavior.
+    pub async fn lookup_scoped_connection(
+        &self,
+        path: &str,
+        connection_id: &str,
+    ) -> Option<RemoteWorkspaceEntry> {
+        self.registry
+            .lookup_scoped_connection(path, connection_id)
+            .await
+    }
+
     /// True if `path` could belong to **any** registered remote root (before disambiguation).
     pub async fn is_remote_path(&self, path: &str) -> bool {
         if get_path_manager_arc().is_local_assistant_workspace_path(path) {
@@ -402,6 +414,15 @@ pub async fn lookup_remote_connection_with_hint(
         .await
 }
 
+/// Look up an exact `(connection_id, path)` remote workspace scope.
+pub async fn lookup_remote_connection_scoped(
+    path: &str,
+    connection_id: &str,
+) -> Option<RemoteWorkspaceEntry> {
+    let manager = get_remote_workspace_manager()?;
+    manager.lookup_scoped_connection(path, connection_id).await
+}
+
 /// Look up using path only (uses active hint when ambiguous).
 pub async fn lookup_remote_connection(path: &str) -> Option<RemoteWorkspaceEntry> {
     lookup_remote_connection_with_hint(path, None).await
diff --git a/src/crates/assembly/core/src/service/session_usage/service.rs b/src/crates/assembly/core/src/service/session_usage/service.rs
index cf9753173f..ccbf385377 100644
--- a/src/crates/assembly/core/src/service/session_usage/service.rs
+++ b/src/crates/assembly/core/src/service/session_usage/service.rs
@@ -2794,6 +2794,8 @@ mod tests {
             has_final_response: None,
             error: None,
             error_detail: None,
+            recovery: None,
+            recovery_epoch: None,
             status: TurnStatus::Completed,
         }
     }
diff --git a/src/crates/assembly/core/src/service/snapshot/manager.rs b/src/crates/assembly/core/src/service/snapshot/manager.rs
index 6507a89aa3..5d78b63888 100644
--- a/src/crates/assembly/core/src/service/snapshot/manager.rs
+++ b/src/crates/assembly/core/src/service/snapshot/manager.rs
@@ -79,14 +79,14 @@ impl SnapshotManager {
     }
 
     /// Rolls back to a specific turn.
-    pub async fn rollback_to_turn(
+    pub async fn rollback_workspace_files_to_boundary(
         &self,
         session_id: &str,
         turn_index: usize,
     ) -> SnapshotResult<Vec<PathBuf>> {
         let snapshot_service = self.snapshot_service.read().await;
         snapshot_service
-            .rollback_to_turn(session_id, turn_index)
+            .rollback_workspace_files_to_boundary(session_id, turn_index)
             .await
     }
 
diff --git a/src/crates/assembly/core/src/service/snapshot/service.rs b/src/crates/assembly/core/src/service/snapshot/service.rs
index 7b7ef454a1..34b59b4086 100644
--- a/src/crates/assembly/core/src/service/snapshot/service.rs
+++ b/src/crates/assembly/core/src/service/snapshot/service.rs
@@ -342,7 +342,7 @@ impl SnapshotService {
         Ok(restored_files)
     }
 
-    pub async fn rollback_to_turn(
+    pub async fn rollback_workspace_files_to_boundary(
         &self,
         session_id: &str,
         turn_index: usize,
@@ -354,7 +354,9 @@ impl SnapshotService {
         );
 
         let mut snapshot_core = self.snapshot_core.write().await;
-        snapshot_core.rollback_to_turn(session_id, turn_index).await
+        snapshot_core
+            .rollback_workspace_files_to_boundary(session_id, turn_index)
+            .await
     }
 
     pub(crate) async fn prepare_workspace_revert(
diff --git a/src/crates/assembly/core/src/service/snapshot/snapshot_core.rs b/src/crates/assembly/core/src/service/snapshot/snapshot_core.rs
index a247b79703..ae3292bcd8 100644
--- a/src/crates/assembly/core/src/service/snapshot/snapshot_core.rs
+++ b/src/crates/assembly/core/src/service/snapshot/snapshot_core.rs
@@ -810,7 +810,7 @@ impl SnapshotCore {
     }
 
     /// Rollback to the start of `target_turn` (undo target_turn and later turns).
-    pub async fn rollback_to_turn(
+    pub async fn rollback_workspace_files_to_boundary(
         &mut self,
         session_id: &str,
         target_turn: usize,
diff --git a/src/crates/assembly/core/src/service/worktree/mod.rs b/src/crates/assembly/core/src/service/worktree/mod.rs
index d7e153b31e..94e3f5ec0c 100644
--- a/src/crates/assembly/core/src/service/worktree/mod.rs
+++ b/src/crates/assembly/core/src/service/worktree/mod.rs
@@ -1680,6 +1680,13 @@ async fn managed_target_path(
                 format!("Failed to resolve the managed worktree root: {io_error}"),
             )
         })?;
+    // `std::fs::canonicalize` (and Tokio's wrapper) returns a verbatim
+    // `\\?\C:\...` path on Windows. Git for Windows does not accept that form
+    // as a `worktree add` target after the Git adapter normalizes separators,
+    // because it becomes `//?/C:/...`. Keep the resolved path used for the
+    // containment checks, but prefer the ordinary drive-letter representation
+    // whenever it can address the same path.
+    let canonical_root = dunce::simplified(&canonical_root).to_path_buf();
     let repository_root = canonical_root.join(repository_id);
     match tokio::fs::symlink_metadata(&repository_root).await {
         Ok(metadata) if metadata.file_type().is_symlink() || !metadata.is_dir() => {
@@ -1715,6 +1722,7 @@ async fn managed_target_path(
                     format!("Failed to resolve the repository worktree root: {io_error}"),
                 )
             })?;
+    let canonical_repository_root = dunce::simplified(&canonical_repository_root).to_path_buf();
     if !canonical_repository_root.starts_with(&canonical_root) {
         return Err(error(
             WorktreeErrorCode::InvalidPath,
@@ -2092,6 +2100,32 @@ mod tests {
         assert_eq!(collision.code, WorktreeErrorCode::InvalidPath);
     }
 
+    #[cfg(windows)]
+    #[tokio::test]
+    async fn managed_target_path_is_compatible_with_git_for_windows() {
+        let root = tempfile::tempdir().expect("temp root");
+        let settings = WorktreeSettings {
+            root_path: root.path().join("managed-worktrees").display().to_string(),
+            ..WorktreeSettings::default()
+        };
+
+        let target = managed_target_path(
+            &settings,
+            "repository-id",
+            &root.path().join("projects/BitFun"),
+            "48e8b457e87649aebf801b408698f46c",
+        )
+        .await
+        .expect("managed target path");
+        let git_argument = target.to_string_lossy().replace('\\', "/");
+
+        assert!(
+            !git_argument.starts_with("//?/"),
+            "managed worktree targets passed to Git must not use a Windows verbatim path: {}",
+            target.display()
+        );
+    }
+
     #[test]
     fn managed_directory_name_falls_back_for_paths_without_a_project_name() {
         assert!(managed_worktree_directory_name(
diff --git a/src/crates/assembly/core/src/service/worktree/session_binding.rs b/src/crates/assembly/core/src/service/worktree/session_binding.rs
index 496065e596..394c2e64e5 100644
--- a/src/crates/assembly/core/src/service/worktree/session_binding.rs
+++ b/src/crates/assembly/core/src/service/worktree/session_binding.rs
@@ -62,6 +62,16 @@ pub struct WorktreeSessionBindingResult {
 struct SessionBindingContext {
     project_workspace_path: String,
     execution_target: SessionExecutionTarget,
+    /// Why an actual transition is forbidden. An already-satisfied binding
+    /// request remains a safe, read-only no-op even when this is set.
+    transition_blocker: Option<WorktreeError>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum SessionBindingAction {
+    AlreadyBound,
+    Enable,
+    Disable,
 }
 
 fn error(code: WorktreeErrorCode, message: impl Into<String>) -> WorktreeError {
@@ -84,46 +94,51 @@ async fn load_binding_context(
     let session_manager = coordinator.get_session_manager();
     let session = session_manager.get_session(&request.session_id);
 
-    let (workspace_path, project_workspace_path, execution_target) = if let Some(session) = session
-    {
-        if !session.dialog_turn_ids.is_empty() {
-            return Err(error(
-                WorktreeErrorCode::WorktreeBusy,
-                "Worktree isolation can only be changed before the session's first message",
-            ));
-        }
-        if !matches!(session.state, crate::agentic::core::SessionState::Idle) {
-            return Err(error(
-                WorktreeErrorCode::WorktreeBusy,
-                "Worktree isolation cannot be changed while the session is processing",
-            ));
-        }
-        if session.config.remote_connection_id.is_some() {
-            return Err(error(
-                WorktreeErrorCode::RemoteUnsupported,
-                "Managed worktrees are not supported for remote SSH workspaces yet",
-            ));
-        }
-
-        let workspace_path = session.config.workspace_path.clone().ok_or_else(|| {
-            error(
-                WorktreeErrorCode::InvalidPath,
-                "Session is not bound to a workspace",
+    let (workspace_path, project_workspace_path, execution_target, mut transition_blocker) =
+        if let Some(session) = session {
+            let transition_blocker = if !session.dialog_turn_ids.is_empty() {
+                Some(error(
+                    WorktreeErrorCode::WorktreeBusy,
+                    "Worktree isolation can only be changed before the session's first message",
+                ))
+            } else if !matches!(session.state, crate::agentic::core::SessionState::Idle) {
+                Some(error(
+                    WorktreeErrorCode::WorktreeBusy,
+                    "Worktree isolation cannot be changed while the session is processing",
+                ))
+            } else if session.config.remote_connection_id.is_some() {
+                Some(error(
+                    WorktreeErrorCode::RemoteUnsupported,
+                    "Managed worktrees are not supported for remote SSH workspaces yet",
+                ))
+            } else {
+                None
+            };
+
+            let workspace_path = session.config.workspace_path.clone().ok_or_else(|| {
+                error(
+                    WorktreeErrorCode::InvalidPath,
+                    "Session is not bound to a workspace",
+                )
+            })?;
+            let project_workspace_path = session
+                .config
+                .project_workspace_path
+                .clone()
+                .unwrap_or_else(|| workspace_path.clone());
+            let execution_target = session
+                .config
+                .execution_target
+                .clone()
+                .unwrap_or_else(|| SessionExecutionTarget::local(workspace_path.clone()));
+            (
+                workspace_path,
+                project_workspace_path,
+                execution_target,
+                transition_blocker,
             )
-        })?;
-        let project_workspace_path = session
-            .config
-            .project_workspace_path
-            .clone()
-            .unwrap_or_else(|| workspace_path.clone());
-        let execution_target = session
-            .config
-            .execution_target
-            .clone()
-            .unwrap_or_else(|| SessionExecutionTarget::local(workspace_path.clone()));
-        (workspace_path, project_workspace_path, execution_target)
-    } else {
-        let project_workspace_path = request
+        } else {
+            let project_workspace_path = request
                 .project_workspace_path
                 .as_deref()
                 .map(str::trim)
@@ -138,45 +153,53 @@ async fn load_binding_context(
                     )
                 })?
                 .to_string();
-        let metadata = session_manager
-            .load_session_metadata(Path::new(&project_workspace_path), &request.session_id)
-            .await
-            .map_err(|metadata_error| {
-                error(
-                    WorktreeErrorCode::IoFailed,
-                    format!("Failed to load session metadata: {metadata_error}"),
-                )
-            })?
-            .ok_or_else(|| {
+            let metadata = session_manager
+                .load_session_metadata(Path::new(&project_workspace_path), &request.session_id)
+                .await
+                .map_err(|metadata_error| {
+                    error(
+                        WorktreeErrorCode::IoFailed,
+                        format!("Failed to load session metadata: {metadata_error}"),
+                    )
+                })?
+                .ok_or_else(|| {
+                    error(
+                        WorktreeErrorCode::WorktreeNotFound,
+                        format!("Session not found: {}", request.session_id),
+                    )
+                })?;
+            let transition_blocker = (metadata.turn_count > 0).then(|| {
                 error(
-                    WorktreeErrorCode::WorktreeNotFound,
-                    format!("Session not found: {}", request.session_id),
+                    WorktreeErrorCode::WorktreeBusy,
+                    "Worktree isolation can only be changed before the session's first message",
                 )
-            })?;
-        if metadata.turn_count > 0 {
-            return Err(error(
-                WorktreeErrorCode::WorktreeBusy,
-                "Worktree isolation can only be changed before the session's first message",
-            ));
-        }
+            });
 
-        let workspace_path = metadata
-            .workspace_path
-            .clone()
-            .unwrap_or_else(|| project_workspace_path.clone());
-        let persisted_project_path = metadata
-            .project_workspace_path
-            .clone()
-            .unwrap_or(project_workspace_path);
-        let execution_target = metadata
-            .execution_target
-            .clone()
-            .unwrap_or_else(|| SessionExecutionTarget::local(workspace_path.clone()));
-        (workspace_path, persisted_project_path, execution_target)
-    };
+            let workspace_path = metadata
+                .workspace_path
+                .clone()
+                .unwrap_or_else(|| project_workspace_path.clone());
+            let persisted_project_path = metadata
+                .project_workspace_path
+                .clone()
+                .unwrap_or(project_workspace_path);
+            let execution_target = metadata
+                .execution_target
+                .clone()
+                .unwrap_or_else(|| SessionExecutionTarget::local(workspace_path.clone()));
+            (
+                workspace_path,
+                persisted_project_path,
+                execution_target,
+                transition_blocker,
+            )
+        };
 
-    if crate::service::remote_ssh::workspace_state::is_remote_path(&project_workspace_path).await {
-        return Err(error(
+    if transition_blocker.is_none()
+        && crate::service::remote_ssh::workspace_state::is_remote_path(&project_workspace_path)
+            .await
+    {
+        transition_blocker = Some(error(
             WorktreeErrorCode::RemoteUnsupported,
             "Managed worktrees are not supported for remote SSH workspaces yet",
         ));
@@ -192,6 +215,27 @@ async fn load_binding_context(
     Ok(SessionBindingContext {
         project_workspace_path,
         execution_target,
+        transition_blocker,
+    })
+}
+
+fn binding_action(
+    context: &SessionBindingContext,
+    enabled: bool,
+) -> Result<SessionBindingAction, WorktreeError> {
+    let is_worktree = context.execution_target.worktree_id.is_some();
+    if enabled == is_worktree {
+        return Ok(SessionBindingAction::AlreadyBound);
+    }
+
+    if let Some(blocker) = context.transition_blocker.as_ref() {
+        return Err(blocker.clone());
+    }
+
+    Ok(if enabled {
+        SessionBindingAction::Enable
+    } else {
+        SessionBindingAction::Disable
     })
 }
 
@@ -262,24 +306,22 @@ impl WorktreeService {
             .map_err(|message| error(WorktreeErrorCode::InvalidPath, message))?;
         let _binding_guard = SESSION_BINDING_LOCKS.lock(&request.session_id).await;
         let context = load_binding_context(&request).await?;
-        let is_worktree = context.execution_target.worktree_id.is_some();
-
-        if request.enabled == is_worktree {
-            // Already in the requested state; report it rather than churn Git.
-            return Ok(WorktreeSessionBindingResult {
-                session_id: request.session_id,
-                workspace_path: context.execution_target.root_path.clone(),
-                project_workspace_path: context.project_workspace_path,
-                workspace_id: current_workspace_id(&context.execution_target.root_path).await,
-                execution_target: context.execution_target,
-                retained_worktree_path: None,
-            });
-        }
-
-        if request.enabled {
-            Self::enable_session_worktree(&request, &context).await
-        } else {
-            Self::disable_session_worktree(&request, &context).await
+        match binding_action(&context, request.enabled)? {
+            SessionBindingAction::AlreadyBound => {
+                // Already in the requested state; report it rather than churn Git.
+                Ok(WorktreeSessionBindingResult {
+                    session_id: request.session_id,
+                    workspace_path: context.execution_target.root_path.clone(),
+                    project_workspace_path: context.project_workspace_path,
+                    workspace_id: current_workspace_id(&context.execution_target.root_path).await,
+                    execution_target: context.execution_target,
+                    retained_worktree_path: None,
+                })
+            }
+            SessionBindingAction::Enable => Self::enable_session_worktree(&request, &context).await,
+            SessionBindingAction::Disable => {
+                Self::disable_session_worktree(&request, &context).await
+            }
         }
     }
 
@@ -395,7 +437,11 @@ impl WorktreeService {
 
 #[cfg(test)]
 mod tests {
-    use super::{WorktreeSessionBindingRequest, SESSION_BINDING_LOCKS};
+    use super::{
+        binding_action, error, SessionBindingAction, SessionBindingContext,
+        WorktreeSessionBindingRequest, SESSION_BINDING_LOCKS,
+    };
+    use bitfun_core_types::{SessionExecutionTarget, WorktreeErrorCode};
     use std::time::Duration;
 
     #[test]
@@ -426,6 +472,29 @@ mod tests {
         );
     }
 
+    #[test]
+    fn already_satisfied_binding_is_a_no_op_after_the_first_message() {
+        let context = SessionBindingContext {
+            project_workspace_path: "/repo".to_string(),
+            execution_target: SessionExecutionTarget::local("/repo"),
+            transition_blocker: Some(error(
+                WorktreeErrorCode::WorktreeBusy,
+                "Worktree isolation can only be changed before the session's first message",
+            )),
+        };
+
+        assert_eq!(
+            binding_action(&context, false),
+            Ok(SessionBindingAction::AlreadyBound)
+        );
+        assert_eq!(
+            binding_action(&context, true)
+                .expect_err("an actual transition must stay blocked")
+                .code,
+            WorktreeErrorCode::WorktreeBusy
+        );
+    }
+
     #[tokio::test]
     async fn binding_transitions_for_the_same_session_are_serialized() {
         let session_id = format!("binding-lock-{}", uuid::Uuid::new_v4());
diff --git a/src/crates/assembly/core/src/service_agent_runtime.rs b/src/crates/assembly/core/src/service_agent_runtime.rs
index 16f5f68f51..fa41f70fec 100644
--- a/src/crates/assembly/core/src/service_agent_runtime.rs
+++ b/src/crates/assembly/core/src/service_agent_runtime.rs
@@ -20,9 +20,10 @@ use bitfun_events::AgenticEvent;
 use bitfun_runtime_ports::{
     AgentDialogTurnPort, AgentDialogTurnRequest, AgentLifecycleDeliveryPort,
     AgentLocalCommandTurnPort, AgentSessionClosePort, AgentSessionManagementPort,
-    AgentSessionRevertRequest, AgentSessionRevertResult, AgentSubmissionPort,
-    AgentThreadGoalManagementPort, AgentTurnCancellationPort, AgentUserShellCommandPort,
-    AgentWorkspaceReferencePort, SessionStoragePathRequest, SessionStorePort,
+    AgentSessionRevertRequest, AgentSessionRevertResult, AgentSessionRollbackToTurnOutcome,
+    AgentSessionRollbackToTurnRequest, AgentSubmissionPort, AgentThreadGoalManagementPort,
+    AgentTurnCancellationPort, AgentUserShellCommandPort, AgentWorkspaceReferencePort,
+    SessionStoragePathRequest, SessionStorePort,
 };
 #[cfg(feature = "remote-connect")]
 use bitfun_runtime_ports::{
@@ -593,6 +594,11 @@ impl ScheduledSessionManagementPort {
             retired_turn_ids: maintenance.retired_turn_ids().to_vec(),
             changed,
             hidden_turn_count,
+            boundary_storage_turn_index: None,
+            target_turn_id: None,
+            restored_files: Vec::new(),
+            reload_required: false,
+            reload_reason: None,
         })
     }
 }
@@ -612,6 +618,153 @@ impl AgentSessionRevertPort for ScheduledSessionManagementPort {
     ) -> bitfun_runtime_ports::PortResult<AgentSessionRevertResult> {
         self.apply_session_revert(request, false).await
     }
+
+    async fn rollback_session_to_turn(
+        &self,
+        request: AgentSessionRollbackToTurnRequest,
+    ) -> bitfun_runtime_ports::PortResult<AgentSessionRollbackToTurnOutcome> {
+        bitfun_core_types::validate_session_id(&request.session_id).map_err(|message| {
+            bitfun_runtime_ports::PortError::new(
+                bitfun_runtime_ports::PortErrorKind::InvalidRequest,
+                message,
+            )
+        })?;
+        if request.remote_connection_id.is_some() || request.remote_ssh_host.is_some() {
+            return Err(bitfun_runtime_ports::PortError::new(
+                bitfun_runtime_ports::PortErrorKind::NotAvailable,
+                "Session rollback is unavailable for remote workspaces",
+            ));
+        }
+        let storage_path = CoreSessionStorePort::default()
+            .resolve_session_storage_path(SessionStoragePathRequest {
+                workspace_path: std::path::PathBuf::from(&request.workspace_path),
+                remote_connection_id: None,
+                remote_ssh_host: None,
+            })
+            .await
+            .map(|resolution| resolution.effective_storage_path)?;
+        let session_manager = self.coordinator.get_session_manager();
+        if !session_manager
+            .is_session_loaded_from_storage_path(&storage_path, &request.session_id)
+            .map_err(map_session_close_error)?
+        {
+            self.coordinator
+                .restore_session_from_storage_path(&storage_path, &request.session_id)
+                .await
+                .map_err(map_session_close_error)?;
+        }
+        self.coordinator
+            .local_revert_workspace(&request.session_id)
+            .map_err(map_session_close_error)?;
+        session_manager
+            .validate_session_storage_path_binding(&request.session_id, &storage_path)
+            .map_err(map_session_close_error)?;
+        let maintenance = self
+            .scheduler
+            .begin_session_maintenance(&request.session_id, &storage_path, Duration::from_secs(30))
+            .await
+            .map_err(map_session_close_error)?;
+        let _mutation = session_manager
+            .acquire_session_mutation(&request.session_id)
+            .await
+            .map_err(map_session_close_error)?;
+        session_manager
+            .validate_session_storage_path_binding(&request.session_id, &storage_path)
+            .map_err(map_session_close_error)?;
+        let marker_before = session_manager
+            .persistence_manager()
+            .load_session_revert_state(&storage_path, &request.session_id)
+            .await
+            .map_err(map_session_close_error)?;
+
+        let applied = self
+            .coordinator
+            .apply_targeted_session_revert_locked(
+                &storage_path,
+                &request.session_id,
+                &request.target_turn_id,
+                request.expected_storage_turn_index,
+                request.expected_catalog_revision.as_deref(),
+            )
+            .await;
+        let (composer, hidden_turn_count, boundary, restored_files, persisted_retired_turn_ids) =
+            match applied {
+                Ok(result) => result,
+                Err(error) => {
+                    let marker = session_manager
+                        .persistence_manager()
+                        .load_session_revert_state(&storage_path, &request.session_id)
+                        .await
+                        .map_err(map_session_close_error)?;
+                    if let Some(marker) = marker {
+                        if marker.phase
+                            == crate::agentic::session::revert::SessionRevertPhase::Staged
+                            && marker_before.as_ref() == Some(&marker)
+                        {
+                            return Err(map_session_close_error(error));
+                        }
+                        let mutation_id = marker.diagnostic_mutation_id(&request.session_id);
+                        let affected_files = marker
+                            .workspace_checkpoint
+                            .into_iter()
+                            .map(|checkpoint| checkpoint.display_path())
+                            .collect();
+                        return Ok(AgentSessionRollbackToTurnOutcome::RecoveryRequired {
+                            session_id: request.session_id,
+                            mutation_id,
+                            affected_files,
+                            reason: error.to_string(),
+                        });
+                    }
+                    return Err(map_session_close_error(error));
+                }
+            };
+        self.coordinator
+            .emit_event(AgenticEvent::SessionHistoryChanged {
+                session_id: request.session_id.clone(),
+            })
+            .await;
+        let mut retired_turn_ids = maintenance.retired_turn_ids().to_vec();
+        for turn_id in persisted_retired_turn_ids {
+            if !retired_turn_ids.contains(&turn_id) {
+                retired_turn_ids.push(turn_id);
+            }
+        }
+        let (transcript, reload_reason) = match self
+            .coordinator
+            .read_session_transcript_locked(bitfun_runtime_ports::SessionTranscriptRequest {
+                session_id: request.session_id.clone(),
+                turn_id: None,
+            })
+            .await
+        {
+            Ok(transcript) => (transcript, None),
+            Err(error) => (
+                bitfun_runtime_ports::SessionTranscript {
+                    session_id: request.session_id.clone(),
+                    messages: Vec::new(),
+                },
+                Some(format!(
+                    "Session rollback completed but the authoritative transcript could not be read: {error}"
+                )),
+            ),
+        };
+        Ok(AgentSessionRollbackToTurnOutcome::Completed {
+            result: AgentSessionRevertResult {
+                session_id: request.session_id,
+                transcript,
+                composer,
+                retired_turn_ids,
+                changed: true,
+                hidden_turn_count,
+                boundary_storage_turn_index: Some(boundary),
+                target_turn_id: Some(request.target_turn_id),
+                restored_files,
+                reload_required: reload_reason.is_some(),
+                reload_reason,
+            },
+        })
+    }
 }
 
 /// ACP accepts one prompt at a time per session. Keep that protocol-specific
@@ -2388,6 +2541,32 @@ mod tests {
         );
     }
 
+    #[test]
+    fn targeted_rollback_restores_before_requiring_an_in_memory_session() {
+        let source = include_str!("service_agent_runtime.rs");
+        let body = source
+            .split("async fn rollback_session_to_turn")
+            .nth(1)
+            .and_then(|source| source.split("impl AgentSessionManagementPort").next())
+            .expect("targeted rollback implementation");
+        let resolve_storage = body
+            .find("resolve_session_storage_path")
+            .expect("storage path resolution");
+        let restore_session = body
+            .find("restore_session_from_storage_path")
+            .expect("disk Session restore");
+        let local_workspace = body
+            .find("local_revert_workspace")
+            .expect("local workspace validation");
+        let maintenance = body
+            .find("begin_session_maintenance")
+            .expect("maintenance admission");
+
+        assert!(resolve_storage < restore_session);
+        assert!(restore_session < local_workspace);
+        assert!(local_workspace < maintenance);
+    }
+
     #[test]
     fn core_service_agent_runtime_owner_keeps_coordinator_port_contracts() {
         fn assert_runtime_ports<T>()
@@ -2857,6 +3036,8 @@ mod tests {
             has_final_response: None,
             error: None,
             error_detail: None,
+            recovery: None,
+            recovery_epoch: None,
             status,
         }
     }
diff --git a/src/crates/assembly/core/src/util/errors.rs b/src/crates/assembly/core/src/util/errors.rs
index 5158a47ec1..3651e07a87 100644
--- a/src/crates/assembly/core/src/util/errors.rs
+++ b/src/crates/assembly/core/src/util/errors.rs
@@ -224,6 +224,7 @@ impl From<bitfun_agent_runtime::event_bus::EventBusError> for BitFunError {
     }
 }
 
+#[cfg(feature = "agent-runtime")]
 impl From<bitfun_agent_tools::computer_use::ComputerUseContractError> for BitFunError {
     fn from(error: bitfun_agent_tools::computer_use::ComputerUseContractError) -> Self {
         Self::Tool(error.to_string())
diff --git a/src/crates/assembly/external-sources/Cargo.toml b/src/crates/assembly/external-sources/Cargo.toml
index 3dcdc619c8..47c0554c53 100644
--- a/src/crates/assembly/external-sources/Cargo.toml
+++ b/src/crates/assembly/external-sources/Cargo.toml
@@ -4,13 +4,14 @@ version.workspace = true
 authors.workspace = true
 edition.workspace = true
 description = "Ecosystem-neutral external source lifecycle coordination"
+autotests = false
 
 [lib]
 name = "bitfun_external_sources"
 crate-type = ["rlib"]
 
 [dependencies]
-bitfun-product-domains = { path = "../../contracts/product-domains", default-features = false, features = ["external-sources"] }
+bitfun-product-domains = { path = "../../contracts/product-domains", features = ["external-sources"] }
 futures = { workspace = true }
 log = { workspace = true }
 tokio = { workspace = true, features = ["rt", "sync", "time"] }
@@ -18,5 +19,9 @@ tokio = { workspace = true, features = ["rt", "sync", "time"] }
 [dev-dependencies]
 tokio = { workspace = true, features = ["macros"] }
 
+[[test]]
+name = "external_source_coordination_contracts"
+path = "tests/external_source_coordination_contracts.rs"
+
 [lints]
 workspace = true
diff --git a/src/crates/assembly/external-sources/tests/external_source_coordination_contracts.rs b/src/crates/assembly/external-sources/tests/external_source_coordination_contracts.rs
new file mode 100644
index 0000000000..28c08e6eb0
--- /dev/null
+++ b/src/crates/assembly/external-sources/tests/external_source_coordination_contracts.rs
@@ -0,0 +1,14 @@
+#[path = "external_source_coordination_contracts/control_plane.rs"]
+mod control_plane;
+#[path = "external_source_coordination_contracts/coordinator_contracts.rs"]
+mod coordinator_contracts;
+#[path = "external_source_coordination_contracts/hook_coordinator.rs"]
+mod hook_coordinator;
+#[path = "external_source_coordination_contracts/mcp_coordinator.rs"]
+mod mcp_coordinator;
+#[path = "external_source_coordination_contracts/subagent_coordinator.rs"]
+mod subagent_coordinator;
+#[path = "external_source_coordination_contracts/tool_coordinator_contracts.rs"]
+mod tool_coordinator_contracts;
+#[path = "external_source_coordination_contracts/workspace_reference.rs"]
+mod workspace_reference;
diff --git a/src/crates/assembly/external-sources/tests/control_plane.rs b/src/crates/assembly/external-sources/tests/external_source_coordination_contracts/control_plane.rs
similarity index 100%
rename from src/crates/assembly/external-sources/tests/control_plane.rs
rename to src/crates/assembly/external-sources/tests/external_source_coordination_contracts/control_plane.rs
diff --git a/src/crates/assembly/external-sources/tests/coordinator_contracts.rs b/src/crates/assembly/external-sources/tests/external_source_coordination_contracts/coordinator_contracts.rs
similarity index 100%
rename from src/crates/assembly/external-sources/tests/coordinator_contracts.rs
rename to src/crates/assembly/external-sources/tests/external_source_coordination_contracts/coordinator_contracts.rs
diff --git a/src/crates/assembly/external-sources/tests/hook_coordinator.rs b/src/crates/assembly/external-sources/tests/external_source_coordination_contracts/hook_coordinator.rs
similarity index 100%
rename from src/crates/assembly/external-sources/tests/hook_coordinator.rs
rename to src/crates/assembly/external-sources/tests/external_source_coordination_contracts/hook_coordinator.rs
diff --git a/src/crates/assembly/external-sources/tests/mcp_coordinator.rs b/src/crates/assembly/external-sources/tests/external_source_coordination_contracts/mcp_coordinator.rs
similarity index 100%
rename from src/crates/assembly/external-sources/tests/mcp_coordinator.rs
rename to src/crates/assembly/external-sources/tests/external_source_coordination_contracts/mcp_coordinator.rs
diff --git a/src/crates/assembly/external-sources/tests/subagent_coordinator.rs b/src/crates/assembly/external-sources/tests/external_source_coordination_contracts/subagent_coordinator.rs
similarity index 100%
rename from src/crates/assembly/external-sources/tests/subagent_coordinator.rs
rename to src/crates/assembly/external-sources/tests/external_source_coordination_contracts/subagent_coordinator.rs
diff --git a/src/crates/assembly/external-sources/tests/tool_coordinator_contracts.rs b/src/crates/assembly/external-sources/tests/external_source_coordination_contracts/tool_coordinator_contracts.rs
similarity index 100%
rename from src/crates/assembly/external-sources/tests/tool_coordinator_contracts.rs
rename to src/crates/assembly/external-sources/tests/external_source_coordination_contracts/tool_coordinator_contracts.rs
diff --git a/src/crates/assembly/external-sources/tests/workspace_reference.rs b/src/crates/assembly/external-sources/tests/external_source_coordination_contracts/workspace_reference.rs
similarity index 100%
rename from src/crates/assembly/external-sources/tests/workspace_reference.rs
rename to src/crates/assembly/external-sources/tests/external_source_coordination_contracts/workspace_reference.rs
diff --git a/src/crates/assembly/product-capabilities/Cargo.toml b/src/crates/assembly/product-capabilities/Cargo.toml
index 4d8e17738e..c7ba01588c 100644
--- a/src/crates/assembly/product-capabilities/Cargo.toml
+++ b/src/crates/assembly/product-capabilities/Cargo.toml
@@ -4,20 +4,29 @@ version.workspace = true
 authors.workspace = true
 edition.workspace = true
 description = "BitFun product capability pack contracts"
+autotests = false
 
 [lib]
 name = "bitfun_product_capabilities"
 crate-type = ["rlib"]
 
+[[test]]
+name = "product_capability_contracts"
+path = "tests/product_capability_contracts.rs"
+
+[features]
+default = []
+
 [dependencies]
 bitfun-harness = { path = "../../execution/harness" }
-bitfun-runtime-ports = { path = "../../contracts/runtime-ports" }
+bitfun-runtime-ports = { path = "../../contracts/runtime-ports", features = ["plugin-runtime"] }
 bitfun-runtime-services = { path = "../../execution/runtime-services" }
-bitfun-tool-packs = { path = "../../execution/tool-provider-groups", default-features = false }
+bitfun-tool-packs = { path = "../../execution/tool-provider-groups" }
 
 [dev-dependencies]
 async-trait = { workspace = true }
-bitfun-agent-runtime = { path = "../../execution/agent-runtime" }
+bitfun-agent-runtime = { path = "../../execution/agent-runtime", features = ["agent-runtime"] }
+bitfun-runtime-ports = { path = "../../contracts/runtime-ports", features = ["agent-api"] }
 bitfun-runtime-services = { path = "../../execution/runtime-services", features = ["test-support"] }
 tokio = { workspace = true, features = ["macros", "rt"] }
 
diff --git a/src/crates/assembly/product-capabilities/src/lib.rs b/src/crates/assembly/product-capabilities/src/lib.rs
index 14b74a9062..7800a07ecc 100644
--- a/src/crates/assembly/product-capabilities/src/lib.rs
+++ b/src/crates/assembly/product-capabilities/src/lib.rs
@@ -276,7 +276,7 @@ const PRODUCT_DELIVERY_PROFILE_ENTRIES: &[ProductDeliveryProfileEntry] = &[
     ),
     ProductDeliveryProfileEntry::new(
         DeliveryProfile::Sdk,
-        ProductCoreDependencyMode::ProductFullCompatibility,
+        ProductCoreDependencyMode::ExplicitCoreCapabilityClosure,
     ),
 ];
 
diff --git a/src/crates/assembly/product-capabilities/tests/product_capability_contracts.rs b/src/crates/assembly/product-capabilities/tests/product_capability_contracts.rs
new file mode 100644
index 0000000000..91f73bb649
--- /dev/null
+++ b/src/crates/assembly/product-capabilities/tests/product_capability_contracts.rs
@@ -0,0 +1,6 @@
+#[path = "product_capability_contracts/plugin_product_shape.rs"]
+mod plugin_product_shape;
+#[path = "product_capability_contracts/product_capabilities.rs"]
+mod product_capabilities;
+#[path = "product_capability_contracts/product_sdk_assembly.rs"]
+mod product_sdk_assembly;
diff --git a/src/crates/assembly/product-capabilities/tests/plugin_product_shape.rs b/src/crates/assembly/product-capabilities/tests/product_capability_contracts/plugin_product_shape.rs
similarity index 100%
rename from src/crates/assembly/product-capabilities/tests/plugin_product_shape.rs
rename to src/crates/assembly/product-capabilities/tests/product_capability_contracts/plugin_product_shape.rs
diff --git a/src/crates/assembly/product-capabilities/tests/product_capabilities.rs b/src/crates/assembly/product-capabilities/tests/product_capability_contracts/product_capabilities.rs
similarity index 99%
rename from src/crates/assembly/product-capabilities/tests/product_capabilities.rs
rename to src/crates/assembly/product-capabilities/tests/product_capability_contracts/product_capabilities.rs
index a31d3c36a7..59b4b436c3 100644
--- a/src/crates/assembly/product-capabilities/tests/product_capabilities.rs
+++ b/src/crates/assembly/product-capabilities/tests/product_capability_contracts/product_capabilities.rs
@@ -408,7 +408,7 @@ fn product_delivery_profile_matrix_documents_current_core_dependency_shape() {
             ),
             (
                 DeliveryProfile::Sdk,
-                ProductCoreDependencyMode::ProductFullCompatibility,
+                ProductCoreDependencyMode::ExplicitCoreCapabilityClosure,
             ),
         ]
     );
diff --git a/src/crates/assembly/product-capabilities/tests/product_sdk_assembly.rs b/src/crates/assembly/product-capabilities/tests/product_capability_contracts/product_sdk_assembly.rs
similarity index 100%
rename from src/crates/assembly/product-capabilities/tests/product_sdk_assembly.rs
rename to src/crates/assembly/product-capabilities/tests/product_capability_contracts/product_sdk_assembly.rs
diff --git a/src/crates/contracts/core-types/Cargo.toml b/src/crates/contracts/core-types/Cargo.toml
index 22486a9531..d714504e6f 100644
--- a/src/crates/contracts/core-types/Cargo.toml
+++ b/src/crates/contracts/core-types/Cargo.toml
@@ -3,11 +3,16 @@ name = "bitfun-core-types"
 version.workspace = true
 edition.workspace = true
 description = "BitFun shared low-level product DTOs"
+autotests = false
 
 [lib]
 name = "bitfun_core_types"
 crate-type = ["rlib"]
 
+[[test]]
+name = "core_type_contracts"
+path = "tests/core_type_contracts.rs"
+
 [dependencies]
 serde = { workspace = true }
 serde_json = { workspace = true }
diff --git a/src/crates/contracts/core-types/src/ai.rs b/src/crates/contracts/core-types/src/ai.rs
index f5234af1d1..6406df7e63 100644
--- a/src/crates/contracts/core-types/src/ai.rs
+++ b/src/crates/contracts/core-types/src/ai.rs
@@ -198,6 +198,26 @@ pub struct ReasoningCatalogProjection {
     pub default_preset: Option<String>,
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub presets: Vec<ReasoningPresetDescriptor>,
+    /// Presets declared by the selected models.dev model that the active
+    /// request adapter cannot compile reliably. These are informational only
+    /// and must not be offered as selectable presets.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub unavailable_presets: Vec<ReasoningPresetDescriptor>,
+}
+
+/// Secret-free model facts used to preview the effective reasoning presets
+/// while a model configuration is still being edited.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct ReasoningCatalogProjectionRequest {
+    pub provider: String,
+    pub model_name: String,
+    pub base_url: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub context_window: Option<u32>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub max_tokens: Option<u32>,
+    pub reasoning: ReasoningConfig,
 }
 
 #[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
diff --git a/src/crates/contracts/core-types/src/errors.rs b/src/crates/contracts/core-types/src/errors.rs
index 36d1d8dc6c..78da964a94 100644
--- a/src/crates/contracts/core-types/src/errors.rs
+++ b/src/crates/contracts/core-types/src/errors.rs
@@ -69,6 +69,12 @@ pub struct AiProviderError {
     pub provider_code: Option<String>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub http_status: Option<u16>,
+    /// Provider-requested delay before another attempt, in milliseconds.
+    ///
+    /// This is transport metadata only. Runtime owners decide whether to retry;
+    /// the hint must never be used as retry-admission policy.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub retry_after_ms: Option<u64>,
 }
 
 impl AiProviderError {
@@ -85,6 +91,7 @@ impl AiProviderError {
             provider,
             provider_code,
             http_status,
+            retry_after_ms: None,
         }
     }
 
@@ -95,9 +102,15 @@ impl AiProviderError {
             provider: None,
             provider_code: None,
             http_status: None,
+            retry_after_ms: None,
         }
     }
 
+    pub fn with_retry_after_ms(mut self, retry_after_ms: Option<u64>) -> Self {
+        self.retry_after_ms = retry_after_ms;
+        self
+    }
+
     pub fn detail(&self) -> AiErrorDetail {
         AiErrorDetail {
             category: self.category.clone(),
@@ -639,6 +652,7 @@ mod tests {
         );
 
         assert_eq!(error.category, ErrorCategory::ContextOverflow);
+        assert_eq!(error.retry_after_ms, None);
         let detail = error.detail();
         assert_eq!(detail.provider.as_deref(), Some("openai"));
         assert_eq!(
@@ -647,4 +661,21 @@ mod tests {
         );
         assert_eq!(detail.http_status, Some(400));
     }
+
+    #[test]
+    fn provider_error_preserves_retry_after_hint() {
+        let error = AiProviderError::from_parts(
+            "Request failed".to_string(),
+            Some("openai".to_string()),
+            Some("permission_denied".to_string()),
+            Some(403),
+        )
+        .with_retry_after_ms(Some(1_500));
+
+        assert_eq!(error.retry_after_ms, Some(1_500));
+        assert_eq!(
+            serde_json::to_value(&error).expect("serialize provider error")["retryAfterMs"],
+            1_500
+        );
+    }
 }
diff --git a/src/crates/contracts/core-types/src/lib.rs b/src/crates/contracts/core-types/src/lib.rs
index b27f05d7a9..44e8510716 100644
--- a/src/crates/contracts/core-types/src/lib.rs
+++ b/src/crates/contracts/core-types/src/lib.rs
@@ -21,14 +21,14 @@ pub use ai::{
     ProviderCatalogModelLimits, ProviderCatalogModelPricing, ProviderCatalogModelSource,
     ProviderCatalogProvider, ProviderCatalogSource, ProviderCatalogUpstreamProvider, ProxyConfig,
     ReasoningCapabilityStatus, ReasoningCatalogBinding, ReasoningCatalogProjection,
-    ReasoningConfig, ReasoningPreset, ReasoningPresetAction, ReasoningPresetDescriptor,
-    ReasoningPresetSource, RemoteModelInfo, ToolCall, ToolCallConfirmationDetails,
-    ToolCallRequestInfo, ToolCallResponseInfo, ToolDefinition,
+    ReasoningCatalogProjectionRequest, ReasoningConfig, ReasoningPreset, ReasoningPresetAction,
+    ReasoningPresetDescriptor, ReasoningPresetSource, RemoteModelInfo, ToolCall,
+    ToolCallConfirmationDetails, ToolCallRequestInfo, ToolCallResponseInfo, ToolDefinition,
 };
 pub use errors::{AiErrorDetail, ErrorCategory};
 pub use session::{
     validate_session_id, SessionAgentRouteOwner, SessionContinuationPolicy, SessionKind,
-    SessionModelBindingPolicy,
+    SessionModelBindingPolicy, SESSION_PROVIDER_ACP, SESSION_PROVIDER_METADATA_KEY,
 };
 pub use session_usage::*;
 pub use speech::*;
diff --git a/src/crates/contracts/core-types/src/session.rs b/src/crates/contracts/core-types/src/session.rs
index 54fcc354aa..aeb8e8487d 100644
--- a/src/crates/contracts/core-types/src/session.rs
+++ b/src/crates/contracts/core-types/src/session.rs
@@ -40,6 +40,16 @@ pub enum SessionAgentRouteOwner {
     External,
 }
 
+/// Custom-metadata key naming the subsystem that drives a persisted Session.
+pub const SESSION_PROVIDER_METADATA_KEY: &str = "provider";
+
+/// `provider` value of a Session driven by an external ACP agent.
+///
+/// The Runtime neither starts nor completes those Turns — the frontend
+/// projection is their only writer — so persistence treats them as projected
+/// history instead of a Runtime history branch.
+pub const SESSION_PROVIDER_ACP: &str = "acp";
+
 pub fn validate_session_id(session_id: &str) -> Result<(), String> {
     if session_id.is_empty() {
         return Err("session_id cannot be empty".to_string());
diff --git a/src/crates/contracts/core-types/tests/core_type_contracts.rs b/src/crates/contracts/core-types/tests/core_type_contracts.rs
new file mode 100644
index 0000000000..9cc3a95460
--- /dev/null
+++ b/src/crates/contracts/core-types/tests/core_type_contracts.rs
@@ -0,0 +1,8 @@
+#[path = "core_type_contracts/lsp_contracts.rs"]
+mod lsp_contracts;
+#[path = "core_type_contracts/session_contracts.rs"]
+mod session_contracts;
+#[path = "core_type_contracts/session_usage_contracts.rs"]
+mod session_usage_contracts;
+#[path = "core_type_contracts/surface_contracts.rs"]
+mod surface_contracts;
diff --git a/src/crates/contracts/core-types/tests/lsp_contracts.rs b/src/crates/contracts/core-types/tests/core_type_contracts/lsp_contracts.rs
similarity index 100%
rename from src/crates/contracts/core-types/tests/lsp_contracts.rs
rename to src/crates/contracts/core-types/tests/core_type_contracts/lsp_contracts.rs
diff --git a/src/crates/contracts/core-types/tests/session_contracts.rs b/src/crates/contracts/core-types/tests/core_type_contracts/session_contracts.rs
similarity index 100%
rename from src/crates/contracts/core-types/tests/session_contracts.rs
rename to src/crates/contracts/core-types/tests/core_type_contracts/session_contracts.rs
diff --git a/src/crates/contracts/core-types/tests/session_usage_contracts.rs b/src/crates/contracts/core-types/tests/core_type_contracts/session_usage_contracts.rs
similarity index 100%
rename from src/crates/contracts/core-types/tests/session_usage_contracts.rs
rename to src/crates/contracts/core-types/tests/core_type_contracts/session_usage_contracts.rs
diff --git a/src/crates/contracts/core-types/tests/surface_contracts.rs b/src/crates/contracts/core-types/tests/core_type_contracts/surface_contracts.rs
similarity index 100%
rename from src/crates/contracts/core-types/tests/surface_contracts.rs
rename to src/crates/contracts/core-types/tests/core_type_contracts/surface_contracts.rs
diff --git a/src/crates/contracts/events/src/agentic.rs b/src/crates/contracts/events/src/agentic.rs
index c022a5c14f..a5671ef878 100644
--- a/src/crates/contracts/events/src/agentic.rs
+++ b/src/crates/contracts/events/src/agentic.rs
@@ -188,6 +188,19 @@ pub enum AgenticEvent {
         turn_id: String,
     },
 
+    DialogTurnInterrupted {
+        session_id: String,
+        turn_id: String,
+        execution_generation: u32,
+        model_id: Option<String>,
+    },
+
+    DialogTurnRecovered {
+        session_id: String,
+        turn_id: String,
+        execution_generation: u32,
+    },
+
     DialogTurnFailed {
         session_id: String,
         turn_id: String,
@@ -629,6 +642,8 @@ impl AgenticEvent {
             | Self::ContextCompressionFailed { session_id, .. }
             | Self::ThreadGoalUpdated { session_id, .. }
             | Self::DialogTurnCancelled { session_id, .. }
+            | Self::DialogTurnInterrupted { session_id, .. }
+            | Self::DialogTurnRecovered { session_id, .. }
             | Self::DialogTurnFailed { session_id, .. }
             | Self::ModelRoundStarted { session_id, .. }
             | Self::ModelRoundAttemptSuperseded { session_id, .. }
@@ -650,6 +665,8 @@ impl AgenticEvent {
             Self::DialogTurnStarted { turn_id, .. }
             | Self::DialogTurnCompleted { turn_id, .. }
             | Self::DialogTurnCancelled { turn_id, .. }
+            | Self::DialogTurnInterrupted { turn_id, .. }
+            | Self::DialogTurnRecovered { turn_id, .. }
             | Self::DialogTurnFailed { turn_id, .. }
             | Self::TokenUsageUpdated { turn_id, .. }
             | Self::ContextCompressionStarted { turn_id, .. }
@@ -674,6 +691,10 @@ impl AgenticEvent {
             | Self::DialogTurnFailed { .. }
             | Self::DialogTurnCancelled { .. } => AgenticEventPriority::Critical,
 
+            Self::DialogTurnInterrupted { .. } | Self::DialogTurnRecovered { .. } => {
+                AgenticEventPriority::Critical
+            }
+
             Self::SessionStateChanged { .. }
             | Self::SessionHistoryChanged { .. }
             | Self::SessionTitleGenerated { .. }
diff --git a/src/crates/contracts/events/src/frontend_projection.rs b/src/crates/contracts/events/src/frontend_projection.rs
index c606c2566a..221c0b42e3 100644
--- a/src/crates/contracts/events/src/frontend_projection.rs
+++ b/src/crates/contracts/events/src/frontend_projection.rs
@@ -239,6 +239,32 @@ pub fn project_agentic_frontend_event(event: AgenticEvent) -> Option<AgenticFron
                 "turnId": turn_id,
             }),
         )),
+        AgenticEvent::DialogTurnInterrupted {
+            session_id,
+            turn_id,
+            execution_generation,
+            model_id,
+        } => Some(AgenticFrontendEvent::new(
+            "agentic://dialog-turn-interrupted",
+            json!({
+                "sessionId": session_id,
+                "turnId": turn_id,
+                "executionGeneration": execution_generation,
+                "modelId": model_id,
+            }),
+        )),
+        AgenticEvent::DialogTurnRecovered {
+            session_id,
+            turn_id,
+            execution_generation,
+        } => Some(AgenticFrontendEvent::new(
+            "agentic://dialog-turn-recovered",
+            json!({
+                "sessionId": session_id,
+                "turnId": turn_id,
+                "executionGeneration": execution_generation,
+            }),
+        )),
         AgenticEvent::DialogTurnFailed {
             session_id,
             turn_id,
@@ -582,6 +608,29 @@ mod tests {
         assert_eq!(projected.payload["durationMs"], 21_206);
     }
 
+    #[test]
+    fn interrupted_turn_lifecycle_projects_generation() {
+        let interrupted = project_agentic_frontend_event(AgenticEvent::DialogTurnInterrupted {
+            session_id: "session-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            execution_generation: 2,
+            model_id: Some("model-a".to_string()),
+        })
+        .expect("interrupted event should project");
+        let recovered = project_agentic_frontend_event(AgenticEvent::DialogTurnRecovered {
+            session_id: "session-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            execution_generation: 3,
+        })
+        .expect("recovered event should project");
+
+        assert_eq!(interrupted.event_name, "agentic://dialog-turn-interrupted");
+        assert_eq!(interrupted.payload["executionGeneration"], 2);
+        assert_eq!(interrupted.payload["modelId"], "model-a");
+        assert_eq!(recovered.event_name, "agentic://dialog-turn-recovered");
+        assert_eq!(recovered.payload["executionGeneration"], 3);
+    }
+
     #[test]
     fn subagent_session_linked_projects_the_child_model() {
         let projected = project_agentic_frontend_event(AgenticEvent::SubagentSessionLinked {
diff --git a/src/crates/contracts/product-domains/Cargo.toml b/src/crates/contracts/product-domains/Cargo.toml
index 856fc2667a..132a99f39e 100644
--- a/src/crates/contracts/product-domains/Cargo.toml
+++ b/src/crates/contracts/product-domains/Cargo.toml
@@ -4,11 +4,16 @@ version.workspace = true
 authors.workspace = true
 edition.workspace = true
 description = "BitFun product domain owner crate"
+autotests = false
 
 [lib]
 name = "bitfun_product_domains"
 crate-type = ["rlib"]
 
+[[test]]
+name = "product_domain_contracts"
+path = "tests/product_domain_contracts.rs"
+
 [[test]]
 name = "plugin_source_contracts"
 path = "tests/plugin_source_contracts.rs"
@@ -19,27 +24,14 @@ name = "external_source_contracts"
 path = "tests/external_source_contracts.rs"
 required-features = ["external-sources"]
 
-[[test]]
-name = "external_hook_contribution_contracts"
-path = "tests/external_hook_contribution_contracts.rs"
-required-features = ["external-sources"]
-
-[[test]]
-name = "external_hook_catalog_contracts"
-path = "tests/external_hook_catalog_contracts.rs"
-required-features = ["external-sources"]
-
-[[test]]
-name = "workspace_reference_contracts"
-path = "tests/workspace_reference_contracts.rs"
-required-features = ["external-sources"]
-
 [[test]]
 name = "function_agent_contracts"
+path = "tests/function_agent_contracts.rs"
 required-features = ["function-agents"]
 
 [[test]]
 name = "miniapp_contracts"
+path = "tests/miniapp_contracts.rs"
 required-features = ["miniapp"]
 
 [dependencies]
diff --git a/src/crates/contracts/product-domains/src/external_subagents.rs b/src/crates/contracts/product-domains/src/external_subagents.rs
index 3560cca140..0a35b284bd 100644
--- a/src/crates/contracts/product-domains/src/external_subagents.rs
+++ b/src/crates/contracts/product-domains/src/external_subagents.rs
@@ -417,12 +417,24 @@ pub fn external_subagent_model_binding_key(
     ))
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ExternalSubagentToolCapability {
+    DirectoryList,
+    ReadFile,
+    GlobFiles,
+    SearchText,
+    ExecuteCommand,
+    EditFile,
+    WriteFile,
+}
+
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct ExternalSubagentToolSelector {
     pub source_name: String,
     #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub canonical_host_name: Option<String>,
+    pub canonical_capability: Option<ExternalSubagentToolCapability>,
     pub allowed: bool,
 }
 
@@ -571,14 +583,8 @@ impl ExternalSubagentDefinition {
                     && !value.chars().any(char::is_control)
             };
             if !valid_name(&selector.source_name)
-                || selector
-                    .canonical_host_name
-                    .as_deref()
-                    .is_some_and(|name| !valid_name(name))
-                || !tool_selectors.insert((
-                    selector.source_name.as_str(),
-                    selector.canonical_host_name.as_deref(),
-                ))
+                || !tool_selectors
+                    .insert((selector.source_name.as_str(), selector.canonical_capability))
             {
                 return Err(ExternalSourceContractError::InvalidText(
                     "external subagent tool selector",
diff --git a/src/crates/contracts/product-domains/src/function_agents/mod.rs b/src/crates/contracts/product-domains/src/function_agents/mod.rs
index f32aee326e..fdfe68bce7 100644
--- a/src/crates/contracts/product-domains/src/function_agents/mod.rs
+++ b/src/crates/contracts/product-domains/src/function_agents/mod.rs
@@ -1,6 +1,5 @@
 pub mod common;
 pub mod git_func_agent;
 pub mod ports;
-pub mod startchat_func_agent;
 
 pub use common::{AgentError, AgentErrorType, AgentResult, Language};
diff --git a/src/crates/contracts/product-domains/src/function_agents/ports.rs b/src/crates/contracts/product-domains/src/function_agents/ports.rs
index 39f24a5c5b..1a81514ac2 100644
--- a/src/crates/contracts/product-domains/src/function_agents/ports.rs
+++ b/src/crates/contracts/product-domains/src/function_agents/ports.rs
@@ -6,16 +6,11 @@
 //! ports define the runtime boundary that future adapters must satisfy before
 //! concrete Git/AI implementations move.
 
-use crate::function_agents::common::{AgentError, AgentResult, Language};
+use crate::function_agents::common::{AgentError, AgentResult};
 use crate::function_agents::git_func_agent::{
     assemble_commit_message, build_changes_summary_from_paths, AICommitAnalysis, CommitMessage,
     CommitMessageOptions, ProjectContext,
 };
-use crate::function_agents::startchat_func_agent::{
-    combine_git_diffs, parse_git_status_porcelain, time_of_day_for_hour, AIGeneratedAnalysis,
-    AheadBehind, CurrentWorkState, GitWorkState, GreetingMessage, TimeInfo, WorkStateAnalysis,
-    WorkStateOptions,
-};
 use serde::{Deserialize, Serialize};
 use std::future::Future;
 use std::path::PathBuf;
@@ -41,43 +36,9 @@ pub struct CommitAiAnalysisRequest {
     pub options: CommitMessageOptions,
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct StartchatGitSnapshot {
-    pub current_branch: String,
-    pub status_porcelain: String,
-    pub unstaged_diff: String,
-    pub staged_diff: String,
-    pub unpushed_commits: u32,
-    pub ahead_behind: Option<AheadBehind>,
-    pub last_commit_timestamp: Option<i64>,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct StartchatTimeSnapshot {
-    pub last_commit_timestamp: Option<i64>,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct WorkStateAiAnalysisRequest {
-    pub git_state: Option<GitWorkState>,
-    pub git_diff: String,
-    pub language: Language,
-}
-
 pub trait FunctionAgentGitPort: Send + Sync {
     fn git_commit_snapshot(&self, repo_path: PathBuf)
         -> FunctionAgentFuture<'_, GitCommitSnapshot>;
-    fn startchat_git_snapshot(
-        &self,
-        repo_path: PathBuf,
-    ) -> FunctionAgentFuture<'_, StartchatGitSnapshot>;
-    fn startchat_time_snapshot(
-        &self,
-        repo_path: PathBuf,
-    ) -> FunctionAgentFuture<'_, StartchatTimeSnapshot>;
 }
 
 /// Future AI boundary for function agents.
@@ -90,19 +51,13 @@ pub trait FunctionAgentAiPort: Send + Sync {
         &self,
         request: CommitAiAnalysisRequest,
     ) -> FunctionAgentFuture<'_, AICommitAnalysis>;
-    fn analyze_work_state(
-        &self,
-        request: WorkStateAiAnalysisRequest,
-    ) -> FunctionAgentFuture<'_, AIGeneratedAnalysis>;
 }
 
 /// Port-backed function-agent facade for future runtime owner migration.
 ///
 /// It owns only pure orchestration over function-agent ports and DTO helpers.
 /// Core still owns Git/AI service calls, provider acquisition, and AI transport
-/// errors. Startchat product-path rewiring depends on core adapters preserving
-/// legacy Git state, diff fallback, time-info, and `analyzed_at` timing
-/// semantics.
+/// errors.
 pub struct FunctionAgentRuntimeFacade<'a> {
     git: &'a dyn FunctionAgentGitPort,
     ai: &'a dyn FunctionAgentAiPort,
@@ -159,102 +114,4 @@ impl<'a> FunctionAgentRuntimeFacade<'a> {
             changes_summary,
         })
     }
-
-    pub async fn analyze_work_state(
-        &self,
-        repo_path: PathBuf,
-        options: WorkStateOptions,
-        now_timestamp: i64,
-        current_hour: u32,
-        analyzed_at: String,
-    ) -> AgentResult<WorkStateAnalysis> {
-        let time_snapshot = self
-            .git
-            .startchat_time_snapshot(repo_path.clone())
-            .await
-            .ok();
-        let snapshot = if options.analyze_git {
-            self.git.startchat_git_snapshot(repo_path).await.ok()
-        } else {
-            None
-        };
-        let git_state = snapshot.as_ref().map(git_work_state_from_snapshot);
-        let git_diff = if git_state
-            .as_ref()
-            .is_some_and(|state| state.unstaged_files > 0 || state.staged_files > 0)
-        {
-            snapshot
-                .as_ref()
-                .map(|snapshot| combine_git_diffs(&snapshot.unstaged_diff, &snapshot.staged_diff))
-                .unwrap_or_default()
-        } else {
-            String::new()
-        };
-        let time_info =
-            time_info_from_snapshot(time_snapshot.as_ref(), now_timestamp, current_hour);
-
-        let ai_analysis = self
-            .ai
-            .analyze_work_state(WorkStateAiAnalysisRequest {
-                git_state: git_state.clone(),
-                git_diff,
-                language: options.language.clone(),
-            })
-            .await?;
-
-        Ok(WorkStateAnalysis {
-            greeting: GreetingMessage {
-                title: String::new(),
-                subtitle: String::new(),
-                tagline: None,
-            },
-            current_state: CurrentWorkState {
-                summary: ai_analysis.summary,
-                git_state,
-                ongoing_work: ai_analysis.ongoing_work,
-                time_info,
-            },
-            predicted_actions: if options.predict_next_actions {
-                ai_analysis.predicted_actions
-            } else {
-                Vec::new()
-            },
-            quick_actions: if options.include_quick_actions {
-                ai_analysis.quick_actions
-            } else {
-                Vec::new()
-            },
-            analyzed_at,
-        })
-    }
-}
-
-pub fn git_work_state_from_snapshot(snapshot: &StartchatGitSnapshot) -> GitWorkState {
-    let (unstaged_files, staged_files, modified_files) =
-        parse_git_status_porcelain(&snapshot.status_porcelain);
-    GitWorkState {
-        current_branch: snapshot.current_branch.clone(),
-        unstaged_files,
-        staged_files,
-        unpushed_commits: snapshot.unpushed_commits,
-        ahead_behind: snapshot.ahead_behind.clone(),
-        modified_files,
-    }
-}
-
-pub fn time_info_from_snapshot(
-    snapshot: Option<&StartchatTimeSnapshot>,
-    now_timestamp: i64,
-    current_hour: u32,
-) -> TimeInfo {
-    let minutes_since_last_commit = snapshot
-        .and_then(|snapshot| snapshot.last_commit_timestamp)
-        .map(|timestamp| (now_timestamp - timestamp) / 60)
-        .map(|minutes| minutes as u64);
-
-    TimeInfo {
-        minutes_since_last_commit,
-        last_commit_time_desc: None,
-        time_of_day: time_of_day_for_hour(current_hour),
-    }
 }
diff --git a/src/crates/contracts/product-domains/src/function_agents/startchat_func_agent/mod.rs b/src/crates/contracts/product-domains/src/function_agents/startchat_func_agent/mod.rs
deleted file mode 100644
index b0e5751e4f..0000000000
--- a/src/crates/contracts/product-domains/src/function_agents/startchat_func_agent/mod.rs
+++ /dev/null
@@ -1,5 +0,0 @@
-pub mod types;
-pub mod utils;
-
-pub use types::*;
-pub use utils::*;
diff --git a/src/crates/contracts/product-domains/src/function_agents/startchat_func_agent/types.rs b/src/crates/contracts/product-domains/src/function_agents/startchat_func_agent/types.rs
deleted file mode 100644
index 3a6a504e2b..0000000000
--- a/src/crates/contracts/product-domains/src/function_agents/startchat_func_agent/types.rs
+++ /dev/null
@@ -1,277 +0,0 @@
-/**
- * Startchat Function Agent - type definitions
- *
- * Defines data structures for work state analysis and greeting info at session start
- */
-use serde::{Deserialize, Serialize};
-use std::fmt;
-
-// Re-export shared types for backward compatibility and relative import
-pub use crate::function_agents::common::{AgentError, AgentErrorType, AgentResult, Language};
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct WorkStateOptions {
-    #[serde(default = "default_true")]
-    pub analyze_git: bool,
-
-    #[serde(default = "default_true")]
-    pub predict_next_actions: bool,
-
-    #[serde(default = "default_true")]
-    pub include_quick_actions: bool,
-
-    #[serde(default = "default_language")]
-    pub language: Language,
-}
-
-fn default_true() -> bool {
-    true
-}
-
-fn default_language() -> Language {
-    Language::English
-}
-
-impl Default for WorkStateOptions {
-    fn default() -> Self {
-        Self {
-            analyze_git: true,
-            predict_next_actions: true,
-            include_quick_actions: true,
-            language: Language::English,
-        }
-    }
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct WorkStateAnalysis {
-    pub greeting: GreetingMessage,
-
-    pub current_state: CurrentWorkState,
-
-    pub predicted_actions: Vec<PredictedAction>,
-
-    pub quick_actions: Vec<QuickAction>,
-
-    pub analyzed_at: String,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct GreetingMessage {
-    pub title: String,
-
-    pub subtitle: String,
-
-    pub tagline: Option<String>,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct CurrentWorkState {
-    pub summary: String,
-
-    pub git_state: Option<GitWorkState>,
-
-    pub ongoing_work: Vec<WorkItem>,
-
-    pub time_info: TimeInfo,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct GitWorkState {
-    pub current_branch: String,
-
-    pub unstaged_files: u32,
-
-    pub staged_files: u32,
-
-    pub unpushed_commits: u32,
-
-    pub ahead_behind: Option<AheadBehind>,
-
-    /// List of modified files (show at most the first few)
-    pub modified_files: Vec<FileModification>,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AheadBehind {
-    pub ahead: u32,
-
-    pub behind: u32,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct FileModification {
-    pub path: String,
-
-    pub change_type: FileChangeType,
-
-    pub module: Option<String>,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
-pub enum FileChangeType {
-    Added,
-    Modified,
-    Deleted,
-    Renamed,
-    Untracked,
-}
-
-impl fmt::Display for FileChangeType {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        let s = match self {
-            FileChangeType::Added => "Added",
-            FileChangeType::Modified => "Modified",
-            FileChangeType::Deleted => "Deleted",
-            FileChangeType::Renamed => "Renamed",
-            FileChangeType::Untracked => "Untracked",
-        };
-        write!(f, "{}", s)
-    }
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct WorkItem {
-    pub title: String,
-
-    pub description: String,
-
-    pub related_files: Vec<String>,
-
-    pub category: WorkCategory,
-
-    pub icon: String,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
-pub enum WorkCategory {
-    Backend,
-    Frontend,
-    API,
-    Database,
-    Infrastructure,
-    Testing,
-    Documentation,
-    Other,
-}
-
-impl fmt::Display for WorkCategory {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        let s = match self {
-            WorkCategory::Backend => "Backend",
-            WorkCategory::Frontend => "Frontend",
-            WorkCategory::API => "API",
-            WorkCategory::Database => "Database",
-            WorkCategory::Infrastructure => "Infrastructure",
-            WorkCategory::Testing => "Testing",
-            WorkCategory::Documentation => "Documentation",
-            WorkCategory::Other => "Other",
-        };
-        write!(f, "{}", s)
-    }
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct TimeInfo {
-    /// Minutes since last commit
-    pub minutes_since_last_commit: Option<u64>,
-
-    /// Last commit time description (e.g., "2 hours ago")
-    pub last_commit_time_desc: Option<String>,
-
-    /// Current time of day (morning/afternoon/evening)
-    pub time_of_day: TimeOfDay,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
-pub enum TimeOfDay {
-    Morning,
-    Afternoon,
-    Evening,
-    Night,
-}
-
-impl fmt::Display for TimeOfDay {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        let s = match self {
-            TimeOfDay::Morning => "Morning",
-            TimeOfDay::Afternoon => "Afternoon",
-            TimeOfDay::Evening => "Evening",
-            TimeOfDay::Night => "Night",
-        };
-        write!(f, "{}", s)
-    }
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct PredictedAction {
-    pub description: String,
-
-    pub priority: ActionPriority,
-
-    pub icon: String,
-
-    pub is_reminder: bool,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, PartialOrd)]
-pub enum ActionPriority {
-    High,
-    Medium,
-    Low,
-}
-
-impl fmt::Display for ActionPriority {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        let s = match self {
-            ActionPriority::High => "High",
-            ActionPriority::Medium => "Medium",
-            ActionPriority::Low => "Low",
-        };
-        write!(f, "{}", s)
-    }
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct QuickAction {
-    pub title: String,
-
-    /// Action command (natural language)
-    pub command: String,
-
-    pub icon: String,
-
-    pub action_type: QuickActionType,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
-pub enum QuickActionType {
-    Continue,
-    ViewStatus,
-    Commit,
-    Visualize,
-    Custom,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AIGeneratedAnalysis {
-    pub summary: String,
-
-    pub ongoing_work: Vec<WorkItem>,
-
-    pub predicted_actions: Vec<PredictedAction>,
-
-    pub quick_actions: Vec<QuickAction>,
-}
diff --git a/src/crates/contracts/product-domains/src/function_agents/startchat_func_agent/utils.rs b/src/crates/contracts/product-domains/src/function_agents/startchat_func_agent/utils.rs
deleted file mode 100644
index 276bc63d2d..0000000000
--- a/src/crates/contracts/product-domains/src/function_agents/startchat_func_agent/utils.rs
+++ /dev/null
@@ -1,375 +0,0 @@
-//! Pure Startchat function-agent helper utilities.
-
-use crate::function_agents::common::{
-    extract_json_from_ai_response, AgentError, AgentResult, Language,
-};
-use crate::function_agents::startchat_func_agent::types::*;
-
-pub const WORK_STATE_ANALYSIS_PROMPT: &str = include_str!("prompts/work_state_analysis.md");
-
-pub fn language_instruction(language: &Language) -> &'static str {
-    match language {
-        Language::Chinese => "Please respond in Chinese.",
-        Language::English => "Please respond in English.",
-    }
-}
-
-pub fn build_complete_analysis_prompt(
-    template: &str,
-    git_state: &Option<GitWorkState>,
-    git_diff: &str,
-    language: &Language,
-) -> String {
-    template
-        .replace("{lang_instruction}", language_instruction(language))
-        .replace("{git_state_section}", &build_git_state_section(git_state))
-        .replace(
-            "{git_diff_section}",
-            &build_git_diff_section(git_diff, 8000),
-        )
-}
-
-pub fn build_work_state_analysis_prompt(
-    git_state: &Option<GitWorkState>,
-    git_diff: &str,
-    language: &Language,
-) -> String {
-    build_complete_analysis_prompt(WORK_STATE_ANALYSIS_PROMPT, git_state, git_diff, language)
-}
-
-pub fn build_git_state_section(git_state: &Option<GitWorkState>) -> String {
-    let Some(git) = git_state else {
-        return String::new();
-    };
-
-    let mut section = format!(
-        "## Git Status\n\n- Current branch: {}\n- Unstaged files: {}\n- Staged files: {}\n- Unpushed commits: {}\n",
-        git.current_branch, git.unstaged_files, git.staged_files, git.unpushed_commits
-    );
-
-    if !git.modified_files.is_empty() {
-        section.push_str("\nModified files:\n");
-        for file in git.modified_files.iter().take(10) {
-            section.push_str(&format!("  - {} ({:?})\n", file.path, file.change_type));
-        }
-    }
-
-    section
-}
-
-pub fn build_git_diff_section(git_diff: &str, max_diff_length: usize) -> String {
-    if git_diff.is_empty() {
-        return String::new();
-    }
-
-    if git_diff.len() > max_diff_length {
-        let truncated_diff = git_diff
-            .char_indices()
-            .take_while(|(idx, _)| *idx < max_diff_length)
-            .map(|(_, c)| c)
-            .collect::<String>();
-        format!(
-            "## Code Changes (Git Diff)\n\n{}\n\n... (diff content too long, truncated, total length: {} characters)\n",
-            truncated_diff,
-            git_diff.len()
-        )
-    } else {
-        format!("## Code Changes (Git Diff)\n\n{}", git_diff)
-    }
-}
-
-pub fn combine_git_diffs(unstaged_diff: &str, staged_diff: &str) -> String {
-    let mut diff = unstaged_diff.to_string();
-
-    if !staged_diff.is_empty() {
-        diff.push_str("\n\n=== Staged Changes ===\n\n");
-        diff.push_str(staged_diff);
-    }
-
-    diff
-}
-
-pub fn parse_predicted_actions_from_values(
-    actions_array: &[serde_json::Value],
-) -> Vec<PredictedAction> {
-    actions_array
-        .iter()
-        .map(|action_value| PredictedAction {
-            description: action_value["description"]
-                .as_str()
-                .unwrap_or("Continue current work")
-                .to_string(),
-            priority: parse_action_priority_label(
-                action_value["priority"].as_str().unwrap_or("Medium"),
-            ),
-            icon: action_value["icon"].as_str().unwrap_or("").to_string(),
-            is_reminder: action_value["is_reminder"].as_bool().unwrap_or(false),
-        })
-        .collect()
-}
-
-pub fn normalize_predicted_actions(mut actions: Vec<PredictedAction>) -> Vec<PredictedAction> {
-    while actions.len() < 3 {
-        actions.push(PredictedAction {
-            description: "Continue current development".to_string(),
-            priority: ActionPriority::Medium,
-            icon: String::new(),
-            is_reminder: false,
-        });
-    }
-
-    if actions.len() > 3 {
-        actions.truncate(3);
-    }
-
-    actions
-}
-
-pub fn parse_quick_actions_from_values(actions_array: &[serde_json::Value]) -> Vec<QuickAction> {
-    actions_array
-        .iter()
-        .map(|action_value| QuickAction {
-            title: action_value["title"]
-                .as_str()
-                .unwrap_or("Quick Action")
-                .to_string(),
-            command: action_value["command"].as_str().unwrap_or("").to_string(),
-            icon: action_value["icon"].as_str().unwrap_or("").to_string(),
-            action_type: parse_quick_action_type_label(
-                action_value["action_type"].as_str().unwrap_or("Custom"),
-            ),
-        })
-        .collect()
-}
-
-pub fn limit_quick_actions(mut actions: Vec<QuickAction>) -> Vec<QuickAction> {
-    if actions.len() > 6 {
-        actions.truncate(6);
-    }
-    actions
-}
-
-#[derive(Debug, Clone)]
-pub struct ParsedCompleteAnalysis {
-    pub analysis: AIGeneratedAnalysis,
-    pub predicted_actions_count: usize,
-    pub quick_actions_count: usize,
-}
-
-pub fn parse_complete_analysis_value(parsed: &serde_json::Value) -> ParsedCompleteAnalysis {
-    let summary = parsed["summary"]
-        .as_str()
-        .unwrap_or("You were working on development, with multiple files modified.")
-        .to_string();
-
-    let predicted_actions = parsed["predicted_actions"]
-        .as_array()
-        .map(|actions_array| parse_predicted_actions_from_values(actions_array))
-        .unwrap_or_default();
-    let predicted_actions_count = predicted_actions.len();
-    let predicted_actions = normalize_predicted_actions(predicted_actions);
-
-    let quick_actions = parsed["quick_actions"]
-        .as_array()
-        .map(|actions_array| parse_quick_actions_from_values(actions_array))
-        .unwrap_or_default();
-    let quick_actions_count = quick_actions.len();
-    let quick_actions = limit_quick_actions(quick_actions);
-
-    ParsedCompleteAnalysis {
-        analysis: AIGeneratedAnalysis {
-            summary,
-            ongoing_work: Vec::new(),
-            predicted_actions,
-            quick_actions,
-        },
-        predicted_actions_count,
-        quick_actions_count,
-    }
-}
-
-pub fn parse_complete_analysis_json(json: &str) -> Result<ParsedCompleteAnalysis, String> {
-    let parsed = serde_json::from_str::<serde_json::Value>(json)
-        .map_err(|error| format!("Failed to parse complete analysis response: {}", error))?;
-    Ok(parse_complete_analysis_value(&parsed))
-}
-
-pub fn parse_work_state_analysis_response(response: &str) -> AgentResult<ParsedCompleteAnalysis> {
-    let json_str = extract_json_from_ai_response(response).ok_or_else(|| {
-        AgentError::internal_error("Failed to extract JSON from analysis response")
-    })?;
-
-    log::debug!(
-        "Parsing function-agent work state JSON response: length={}",
-        json_str.len()
-    );
-
-    parse_complete_analysis_json(&json_str).map_err(AgentError::internal_error)
-}
-
-pub fn parse_action_priority_label(label: &str) -> ActionPriority {
-    match label {
-        "High" => ActionPriority::High,
-        "Low" => ActionPriority::Low,
-        _ => ActionPriority::Medium,
-    }
-}
-
-pub fn parse_quick_action_type_label(label: &str) -> QuickActionType {
-    match label {
-        "Continue" => QuickActionType::Continue,
-        "ViewStatus" => QuickActionType::ViewStatus,
-        "Commit" => QuickActionType::Commit,
-        "Visualize" => QuickActionType::Visualize,
-        _ => QuickActionType::Custom,
-    }
-}
-
-pub fn parse_git_status_porcelain(status: &str) -> (u32, u32, Vec<FileModification>) {
-    let mut unstaged_files = 0;
-    let mut staged_files = 0;
-    let mut modified_files = Vec::new();
-
-    for line in status.lines() {
-        if line.is_empty() || line.len() <= 3 {
-            continue;
-        }
-
-        let Some((change_type, is_staged, file_path)) = parse_git_status_line(line) else {
-            continue;
-        };
-
-        if is_staged {
-            staged_files += 1;
-        } else {
-            unstaged_files += 1;
-        }
-
-        if modified_files.len() < 10 {
-            modified_files.push(FileModification {
-                module: extract_top_level_module(&file_path),
-                path: file_path,
-                change_type,
-            });
-        }
-    }
-
-    (unstaged_files, staged_files, modified_files)
-}
-
-pub fn parse_git_status_line(line: &str) -> Option<(FileChangeType, bool, String)> {
-    if line.len() <= 3 {
-        return None;
-    }
-
-    let status_code = &line[0..2];
-    let file_path = line[3..].trim().to_string();
-
-    let (change_type, is_staged) = match status_code {
-        "A " => (FileChangeType::Added, true),
-        " M" => (FileChangeType::Modified, false),
-        "M " => (FileChangeType::Modified, true),
-        "MM" => (FileChangeType::Modified, true),
-        " D" => (FileChangeType::Deleted, false),
-        "D " => (FileChangeType::Deleted, true),
-        "??" => (FileChangeType::Untracked, false),
-        "R " => (FileChangeType::Renamed, true),
-        _ => (FileChangeType::Modified, false),
-    };
-
-    Some((change_type, is_staged, file_path))
-}
-
-pub fn extract_top_level_module(file_path: &str) -> Option<String> {
-    let path = std::path::Path::new(file_path);
-    path.components()
-        .next()
-        .map(|component| component.as_os_str().to_string_lossy().to_string())
-}
-
-pub fn time_of_day_for_hour(hour: u32) -> TimeOfDay {
-    match hour {
-        5..=11 => TimeOfDay::Morning,
-        12..=17 => TimeOfDay::Afternoon,
-        18..=22 => TimeOfDay::Evening,
-        _ => TimeOfDay::Night,
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::function_agents::common::AgentErrorType;
-
-    #[test]
-    fn work_state_ai_prompt_uses_product_domain_template() {
-        let git_state = Some(GitWorkState {
-            current_branch: "feature/runtime".to_string(),
-            unstaged_files: 1,
-            staged_files: 2,
-            unpushed_commits: 3,
-            ahead_behind: None,
-            modified_files: vec![FileModification {
-                module: Some("src".to_string()),
-                path: "src/lib.rs".to_string(),
-                change_type: FileChangeType::Modified,
-            }],
-        });
-
-        let prompt = build_work_state_analysis_prompt(
-            &git_state,
-            "diff --git a/src/lib.rs b/src/lib.rs",
-            &Language::English,
-        );
-
-        assert!(prompt.contains("BitFun AI assistant"));
-        assert!(prompt.contains("Current branch: feature/runtime"));
-        assert!(prompt.contains("diff --git a/src/lib.rs b/src/lib.rs"));
-    }
-
-    #[test]
-    fn work_state_ai_response_policy_extracts_json_and_maps_domain_errors() {
-        let analysis = parse_work_state_analysis_response(
-            r#"The answer is:
-```json
-{
-  "summary": "Working on product-domain owner closure.",
-  "predicted_actions": [
-    {"description": "Run checks", "priority": "High", "icon": "check", "is_reminder": false}
-  ],
-  "quick_actions": [
-    {"title": "Status", "command": "git status", "icon": "git", "action_type": "ViewStatus"}
-  ]
-}
-```
-"#,
-        )
-        .unwrap();
-
-        assert_eq!(
-            analysis.analysis.summary,
-            "Working on product-domain owner closure."
-        );
-        assert_eq!(analysis.analysis.predicted_actions.len(), 3);
-        assert_eq!(analysis.analysis.quick_actions.len(), 1);
-
-        let missing_json = parse_work_state_analysis_response("no json here").unwrap_err();
-        assert_eq!(missing_json.error_type, AgentErrorType::InternalError);
-        assert_eq!(
-            missing_json.message,
-            "Failed to extract JSON from analysis response"
-        );
-
-        let invalid_json = parse_work_state_analysis_response(
-            r#"```json
-not json
-```"#,
-        )
-        .unwrap_err();
-        assert_eq!(invalid_json.error_type, AgentErrorType::InternalError);
-        assert_eq!(
-            invalid_json.message,
-            "Failed to extract JSON from analysis response"
-        );
-    }
-}
diff --git a/src/crates/contracts/product-domains/tests/external_source_contracts.rs b/src/crates/contracts/product-domains/tests/external_source_contracts.rs
index e9f9cc074b..0ba4a81aa8 100644
--- a/src/crates/contracts/product-domains/tests/external_source_contracts.rs
+++ b/src/crates/contracts/product-domains/tests/external_source_contracts.rs
@@ -1,2074 +1,10 @@
-use bitfun_product_domains::external_integration_policy::{
-    evaluate_external_integration_policy, external_integration_policy_snapshot,
-    ExternalEcosystemPolicy, ExternalEcosystemPolicyOverride, ExternalIntegrationAccess,
-    ExternalIntegrationCapabilityDescriptor, ExternalIntegrationEcosystemDescriptor,
-    ExternalIntegrationMode, ExternalIntegrationPolicyDocument, ExternalIntegrationPolicyOverride,
-    ExternalIntegrationPolicyStatus,
-};
-use bitfun_product_domains::external_source_control::{
-    ExternalSourceControlActionV1, ExternalSourceControlRequestV1, ExternalSourceControlSnapshotV1,
-    ExternalSourceDesiredState, ExternalSourceDiscoveryState, ExternalSourceOperationStage,
-    ExternalSourceRecoveryActionV1, ExternalSourceReviewState, EXTERNAL_SOURCE_CONTROL_SCHEMA_V1,
-};
-use bitfun_product_domains::external_sources::{
-    external_mcp_approval_key, external_mcp_conflict_key, external_tool_approval_key,
-    external_tool_conflict_key, prompt_command_conflict_key, EcosystemId, ExecutionDomainId,
-    ExpandedPromptCommand, ExternalIntegrationCapabilityId, ExternalMcpActivationState,
-    ExternalMcpApprovalRequest, ExternalMcpCatalogEntry, ExternalMcpConflict,
-    ExternalMcpConflictCandidate, ExternalMcpDiscoveryInput, ExternalMcpImportApplyRequestV1,
-    ExternalMcpImportSelectionV1, ExternalMcpProviderIdentity, ExternalMcpProviderSnapshot,
-    ExternalMcpRevisionKey, ExternalMcpServerDefinition, ExternalMcpStaticStatus,
-    ExternalMcpTimeouts, ExternalMcpTransportKind, ExternalSourceAssetKind,
-    ExternalSourceCatalogEntry, ExternalSourceCatalogSnapshot, ExternalSourceContext,
-    ExternalSourceDiagnostic, ExternalSourceHealth, ExternalSourceHostCapabilities,
-    ExternalSourceLifecycleState, ExternalSourceOperationError, ExternalSourceOperationErrorCode,
-    ExternalSourceProviderError, ExternalSourcePublicSnapshot, ExternalSourceRecord,
-    ExternalSourceScope, ExternalToolCapability, ExternalToolDefinition, ExternalToolRuntimeKind,
-    ExternalToolStaticStatus, ExternalWatchRoot, NativePromptCommandDescriptor,
-    PreparedExternalMcpImportServer, PreparedExternalMcpImportTransport, PreparedExternalMcpServer,
-    PreparedExternalMcpTransport, PromptCommandAvailability, PromptCommandCatalogEntry,
-    PromptCommandDefinition, PromptCommandExpansion, PromptCommandProviderIdentity,
-    PromptCommandProviderSnapshot, PromptCommandSourceProvider, SecretValue, SourceKey,
-    SourceQualifiedCommandId, SourceQualifiedMcpServerId, SourceQualifiedToolId,
-    SourceQualifiedToolTargetId,
-};
-use bitfun_product_domains::external_subagents::{
-    external_subagent_approval_key, external_subagent_candidate_id, external_subagent_conflict_key,
-    external_subagent_model_binding_key, ExternalSubagentBehaviorVersion,
-    ExternalSubagentCandidateId, ExternalSubagentCompatibilityState,
-    ExternalSubagentContributionId, ExternalSubagentContributionRole, ExternalSubagentDefinition,
-    ExternalSubagentDiscoveryInput, ExternalSubagentLocalId, ExternalSubagentMode,
-    ExternalSubagentModelBindingGroup, ExternalSubagentModelBindingMethod,
-    ExternalSubagentModelBindingOption, ExternalSubagentModelBindingTarget,
-    ExternalSubagentModelProfileRequest, ExternalSubagentModelRequest,
-    ExternalSubagentProvenanceRef, ExternalSubagentProviderIdentity,
-    ExternalSubagentProviderSnapshot, ExternalSubagentToolRequest, ExternalSubagentToolSelector,
-    SecretText,
-};
-use bitfun_product_domains::tool_permissions::{
-    PermissionConstraintLayer, PermissionEffect, PermissionRule,
-};
-use sha2::{Digest, Sha256};
-use std::path::PathBuf;
-
-#[test]
-fn native_prompt_command_descriptors_reject_external_candidate_namespaces() {
-    let descriptor = NativePromptCommandDescriptor {
-        command_name: "review".to_string(),
-        candidate_id: "opencode.commands:project:review".to_string(),
-        behavior_version: "v1".to_string(),
-    };
-
-    assert!(descriptor.validate().is_err());
-}
-
-#[test]
-fn external_mcp_import_contract_keeps_private_values_out_of_debug_and_requests() {
-    let source = SourceKey::new("opencode.mcp", "user-config").unwrap();
-    let prepared = PreparedExternalMcpImportServer {
-        id: SourceQualifiedMcpServerId::new(source, "docs").unwrap(),
-        behavior_version: "sha256:behavior-v1".to_string(),
-        transport: PreparedExternalMcpImportTransport::Local {
-            command: "secret-command".to_string(),
-            args: vec!["secret-argument".to_string()],
-        },
-    };
-    let debug = format!("{prepared:?}");
-    assert!(!debug.contains("secret-command"));
-    assert!(!debug.contains("secret-argument"));
-    prepared.validate().unwrap();
-
-    let request = ExternalMcpImportApplyRequestV1 {
-        schema_version: 1,
-        plan_fingerprint: "sha256:plan-v1".to_string(),
-        selections: vec![ExternalMcpImportSelectionV1 {
-            candidate_id: "opencode:mcp:docs".to_string(),
-            requested_native_id: None,
-        }],
-    };
-    request.validate().unwrap();
-    let encoded = serde_json::to_string(&request).unwrap();
-    assert!(!encoded.contains("command"));
-    assert!(!encoded.contains("argument"));
-}
-
-#[test]
-fn external_mcp_import_contract_rejects_urls_that_cannot_be_copied_losslessly() {
-    let prepared = |url: &str| PreparedExternalMcpImportServer {
-        id: SourceQualifiedMcpServerId::new(
-            SourceKey::new("codex.mcp", "user-config").unwrap(),
-            "docs",
-        )
-        .unwrap(),
-        behavior_version: "sha256:behavior-v1".to_string(),
-        transport: PreparedExternalMcpImportTransport::Remote {
-            url: url.to_string(),
-        },
-    };
-
-    prepared("https://docs.example.test/mcp")
-        .validate()
-        .unwrap();
-    for url in [
-        "http://docs.example.test/mcp",
-        "https://user@docs.example.test/mcp",
-        "https://user:secret@docs.example.test/mcp",
-        "https://docs.example.test/mcp?token=secret",
-        "https://docs.example.test/mcp#private",
-    ] {
-        assert!(
-            prepared(url).validate().is_err(),
-            "unexpectedly safe: {url}"
-        );
-    }
-}
-
-fn source(provider_id: &str, ecosystem_id: &str, source_id: &str) -> ExternalSourceRecord {
-    ExternalSourceRecord {
-        key: SourceKey::new(provider_id, source_id).expect("valid source key"),
-        ecosystem_id: EcosystemId::new(ecosystem_id).expect("valid ecosystem id"),
-        display_name: format!("{provider_id} commands"),
-        source_kind: "prompt_commands".to_string(),
-        scope: ExternalSourceScope::Project,
-        location: format!("/workspace/{provider_id}"),
-        execution_domain_id: ExecutionDomainId::new("local-user").expect("valid domain"),
-        health: ExternalSourceHealth::Available,
-        content_version: format!("{provider_id}-v1"),
-        diagnostics: Vec::new(),
-    }
-}
-
-fn command(provider_id: &str, source_id: &str, precedence: i32) -> PromptCommandDefinition {
-    PromptCommandDefinition {
-        id: SourceQualifiedCommandId::new(
-            SourceKey::new(provider_id, source_id).unwrap(),
-            "review",
-        )
-        .unwrap(),
-        name: "review".to_string(),
-        description: format!("Review from {provider_id}"),
-        template: format!("{provider_id}: $ARGUMENTS"),
-        shell_preference: None,
-        execution_target: Default::default(),
-        availability: PromptCommandAvailability::Available,
-        content_version: format!("command-v{precedence}"),
-    }
-}
-
-fn context() -> ExternalSourceContext {
-    ExternalSourceContext {
-        workspace_root: Some(PathBuf::from("/workspace")),
-        execution_domain_id: ExecutionDomainId::new("local-user").unwrap(),
-    }
-}
-
-#[test]
-fn opaque_ids_are_validated_without_closing_the_ecosystem_set() {
-    assert_eq!(
-        EcosystemId::new("future.product/v2")
-            .expect("future ecosystem ids remain open")
-            .as_str(),
-        "future.product/v2"
-    );
-    assert!(EcosystemId::new("  ").is_err());
-    assert!(ExecutionDomainId::new("domain\nwith-control").is_err());
-}
-
-#[test]
-fn source_and_command_identity_remain_provider_qualified() {
-    let left = SourceQualifiedCommandId::new(
-        SourceKey::new("adapter-a", "project-commands").unwrap(),
-        "review",
-    )
-    .unwrap();
-    let right = SourceQualifiedCommandId::new(
-        SourceKey::new("adapter-b", "project-commands").unwrap(),
-        "review",
-    )
-    .unwrap();
-
-    assert_ne!(left, right);
-    assert_ne!(left.stable_key(), right.stable_key());
-}
-
-#[test]
-fn presentation_group_id_is_optional_and_uses_the_camel_case_wire_name() {
-    let mut entry = ExternalSourceCatalogEntry {
-        stable_key: "opencode.commands:project".to_string(),
-        presentation_group_id: None,
-        record: source("opencode.commands", "opencode", "project"),
-        lifecycle: ExternalSourceLifecycleState::Available,
-    };
-
-    let legacy_value = serde_json::to_value(&entry).unwrap();
-    assert!(legacy_value.get("presentationGroupId").is_none());
-    let legacy_entry: ExternalSourceCatalogEntry = serde_json::from_value(legacy_value).unwrap();
-    assert!(legacy_entry.presentation_group_id.is_none());
-
-    entry.presentation_group_id = Some("external-source:[\"source\"]".to_string());
-    let current_value = serde_json::to_value(&entry).unwrap();
-    assert_eq!(
-        current_value["presentationGroupId"],
-        "external-source:[\"source\"]"
-    );
-}
-
-#[test]
-fn conflict_fingerprint_is_order_independent_and_changes_with_content() {
-    let first = prompt_command_conflict_key("local-user", "review", [("a", "v1"), ("b", "v2")]);
-    let reordered = prompt_command_conflict_key("local-user", "REVIEW", [("b", "v2"), ("a", "v1")]);
-    let updated = prompt_command_conflict_key("local-user", "review", [("a", "v1"), ("b", "v3")]);
-    let remote = prompt_command_conflict_key("remote-user", "review", [("a", "v1"), ("b", "v2")]);
-
-    assert_eq!(first, reordered);
-    assert_ne!(first, updated);
-    assert_ne!(first, remote);
-}
-
-#[test]
-fn prompt_commands_use_a_typed_contract_instead_of_an_arbitrary_asset_payload() {
-    let command = PromptCommandDefinition {
-        id: SourceQualifiedCommandId::new(
-            SourceKey::new("example-provider", "project-commands").unwrap(),
-            "review",
-        )
-        .unwrap(),
-        name: "review".to_string(),
-        description: "Review the current change".to_string(),
-        template: "Review $ARGUMENTS".to_string(),
-        shell_preference: None,
-        execution_target: Default::default(),
-        availability: PromptCommandAvailability::Restricted {
-            reason: "Shell expansion is not supported yet".to_string(),
-            required_capabilities: vec!["command.shell".to_string()],
-        },
-        content_version: "sha256:command-v1".to_string(),
-    };
-
-    let encoded = serde_json::to_value(&command).expect("serialize command contract");
-    assert_eq!(encoded["name"], "review");
-    assert_eq!(encoded["availability"]["state"], "restricted");
-    assert!(encoded.get("payload").is_none());
-}
-
-struct FakeProvider {
-    identity: PromptCommandProviderIdentity,
-    snapshot: PromptCommandProviderSnapshot,
-}
-
-impl FakeProvider {
-    fn new(provider_id: &str, ecosystem_id: &str, source_id: &str, precedence: i32) -> Self {
-        let identity = PromptCommandProviderIdentity::new(
-            provider_id,
-            ecosystem_id,
-            format!("{provider_id} display"),
-        )
-        .unwrap();
-        Self {
-            identity: identity.clone(),
-            snapshot: PromptCommandProviderSnapshot {
-                provider: identity,
-                sources: vec![source(provider_id, ecosystem_id, source_id)],
-                commands: vec![command(provider_id, source_id, precedence)],
-                unavailable_command_ids: Vec::new(),
-                diagnostics: Vec::new(),
-            },
-        }
-    }
-}
-
-impl PromptCommandSourceProvider for FakeProvider {
-    fn identity(&self) -> PromptCommandProviderIdentity {
-        self.identity.clone()
-    }
-
-    fn discover(
-        &self,
-        _context: &ExternalSourceContext,
-    ) -> Result<PromptCommandProviderSnapshot, ExternalSourceProviderError> {
-        Ok(self.snapshot.clone())
-    }
-
-    fn expand(
-        &self,
-        _context: &ExternalSourceContext,
-        command: &PromptCommandDefinition,
-        arguments: &str,
-    ) -> Result<PromptCommandExpansion, ExternalSourceProviderError> {
-        Ok(PromptCommandExpansion {
-            content: command.template.replace("$ARGUMENTS", arguments),
-            workspace_file_references: vec!["src/lib.rs".to_string()],
-            shell: None,
-        })
-    }
-
-    fn watch_roots(&self, context: &ExternalSourceContext) -> Vec<ExternalWatchRoot> {
-        vec![ExternalWatchRoot {
-            path: context.workspace_root.clone().unwrap(),
-            recursive: true,
-        }]
-    }
-}
-
-#[test]
-fn capability_provider_contract_does_not_require_core_or_an_ecosystem_enum() {
-    let provider: Box<dyn PromptCommandSourceProvider> = Box::new(FakeProvider::new(
-        "fake-provider",
-        "fake.ecosystem",
-        "project-commands",
-        1,
-    ));
-
-    let snapshot = provider.discover(&context()).expect("discover fake source");
-    assert_eq!(snapshot.provider.ecosystem_id.as_str(), "fake.ecosystem");
-    assert_eq!(provider.watch_roots(&context()).len(), 1);
-    let expansion = provider
-        .expand(&context(), &snapshot.commands[0], "change")
-        .expect("prepare fake command expansion");
-    assert_eq!(expansion.content, "fake-provider: change");
-    assert_eq!(expansion.workspace_file_references, ["src/lib.rs"]);
-
-    let final_result = ExpandedPromptCommand {
-        content: expansion.content,
-    };
-    assert_eq!(
-        serde_json::to_value(final_result).unwrap(),
-        serde_json::json!({"content": "fake-provider: change"})
-    );
-}
-
-#[test]
-fn persisted_source_preference_keys_round_trip_without_path_guessing() {
-    let record = source(
-        "provider.with.dots",
-        "fake.ecosystem",
-        "project/source:agents",
-    );
-    assert_eq!(
-        ExternalSourceRecord::source_key_from_preference_key(&record.preference_key()),
-        Some(record.key)
-    );
-    assert!(ExternalSourceRecord::source_key_from_preference_key("malformed").is_none());
-}
-
-#[test]
-fn external_subagent_identity_preserves_ordered_provenance_and_separate_revisions() {
-    let provider =
-        ExternalSubagentProviderIdentity::new("fake.agents", "fake.ecosystem", "Fake Agents")
-            .unwrap();
-    let first = ExternalSubagentContributionId::new(
-        SourceKey::new("fake.agents", "global-config").unwrap(),
-        ExternalSubagentLocalId::new("review").unwrap(),
-    );
-    let second = ExternalSubagentContributionId::new(
-        SourceKey::new("fake.agents", "project-config").unwrap(),
-        ExternalSubagentLocalId::new("review").unwrap(),
-    );
-    let provenance = vec![
-        ExternalSubagentProvenanceRef {
-            contribution_id: first,
-            role: ExternalSubagentContributionRole::Base,
-        },
-        ExternalSubagentProvenanceRef {
-            contribution_id: second,
-            role: ExternalSubagentContributionRole::Overlay,
-        },
-    ];
-    let candidate_id = external_subagent_candidate_id(&provider.provider_id, "review", &provenance);
-    let reversed = external_subagent_candidate_id(
-        &provider.provider_id,
-        "review",
-        &provenance.iter().cloned().rev().collect::<Vec<_>>(),
-    );
-    assert_ne!(
-        candidate_id, reversed,
-        "provenance order changes behavior identity"
-    );
-
-    let definition = ExternalSubagentDefinition {
-        candidate_id,
-        logical_id: "review".to_string(),
-        provenance,
-        display_name: "Review".to_string(),
-        description: "Reviews a change".to_string(),
-        prompt: SecretText::new("Review carefully"),
-        mode: ExternalSubagentMode::Subagent,
-        disabled: false,
-        hidden: false,
-        requested_model: ExternalSubagentModelRequest::Default,
-        requested_model_profile: None,
-        requested_tools: ExternalSubagentToolRequest {
-            selectors: vec![ExternalSubagentToolSelector {
-                source_name: "read".to_string(),
-                canonical_host_name: Some("Read".to_string()),
-                allowed: true,
-            }],
-            uses_conservative_default: false,
-        },
-        permission_constraints: PermissionConstraintLayer::new(vec![PermissionRule::new(
-            "read",
-            "C:/sensitive/private/*",
-            PermissionEffect::Deny,
-        )]),
-        compatibility: ExternalSubagentCompatibilityState::Ready,
-        diagnostic_codes: Vec::new(),
-        behavior_version: ExternalSubagentBehaviorVersion::new("behavior-v1").unwrap(),
-    };
-    assert_eq!(definition.prompt.expose(), "Review carefully");
-    assert!(!format!("{definition:?}").contains("Review carefully"));
-    assert!(!format!("{definition:?}").contains("C:/sensitive/private"));
-
-    let mut invalid_model = definition.clone();
-    invalid_model.requested_model = ExternalSubagentModelRequest::Reference {
-        provider_hint: Some("fake\nprovider".to_string()),
-        model_name: "model".to_string(),
-    };
-    assert!(invalid_model.validate().is_err());
-
-    let mut invalid_tool = definition.clone();
-    invalid_tool.requested_tools.selectors[0].source_name = "read\nsecret".to_string();
-    assert!(invalid_tool.validate().is_err());
-
-    let mut invalid_permission = definition.clone();
-    invalid_permission.permission_constraints =
-        PermissionConstraintLayer::new(vec![PermissionRule::new(
-            "read\nsecret",
-            "*",
-            PermissionEffect::Deny,
-        )]);
-    assert!(invalid_permission.validate().is_err());
-
-    let mut invalid_diagnostic = definition.clone();
-    invalid_diagnostic.diagnostic_codes = vec!["provider.invalid:raw-source-key".to_string()];
-    assert!(invalid_diagnostic.validate().is_err());
-
-    let mut excessive_tools = definition.clone();
-    excessive_tools.requested_tools.selectors = (0..257)
-        .map(|index| ExternalSubagentToolSelector {
-            source_name: format!("tool-{index}"),
-            canonical_host_name: None,
-            allowed: true,
-        })
-        .collect();
-    assert!(excessive_tools.validate().is_err());
-
-    let snapshot = ExternalSubagentProviderSnapshot {
-        provider,
-        sources: vec![
-            source("fake.agents", "fake.ecosystem", "global-config"),
-            source("fake.agents", "fake.ecosystem", "project-config"),
-        ],
-        definitions: vec![definition],
-        diagnostics: Vec::new(),
-    };
-    snapshot
-        .validate()
-        .expect("valid external subagent provider snapshot");
-
-    let source_key = snapshot.sources[0].key.clone();
-    let mut valid_diagnostic = snapshot.clone();
-    valid_diagnostic.diagnostics.push(
-        ExternalSourceDiagnostic::warning(
-            "fake.agent.degraded",
-            "An optional field is not supported",
-            Some(source_key),
-        )
-        .with_asset_kind(ExternalSourceAssetKind::Subagent),
-    );
-    valid_diagnostic
-        .validate()
-        .expect("bounded provider diagnostics with a known source are valid");
-
-    let mut valid_source_diagnostic = snapshot.clone();
-    let valid_source_key = valid_source_diagnostic.sources[0].key.clone();
-    valid_source_diagnostic.sources[0].diagnostics.push(
-        ExternalSourceDiagnostic::warning(
-            "fake.agent.source_degraded",
-            "This source has a recoverable warning",
-            Some(valid_source_key),
-        )
-        .with_asset_kind(ExternalSourceAssetKind::Subagent),
-    );
-    valid_source_diagnostic
-        .validate()
-        .expect("source-owned diagnostics use the same provider contract");
-
-    let mut invalid_provider_diagnostic = snapshot.clone();
-    invalid_provider_diagnostic.diagnostics.push(
-        ExternalSourceDiagnostic::warning(
-            "fake.agent:raw-source",
-            "Invalid diagnostic code",
-            Some(SourceKey::new("other.agents", "project").unwrap()),
-        )
-        .with_asset_kind(ExternalSourceAssetKind::Command),
-    );
-    assert!(invalid_provider_diagnostic.validate().is_err());
-
-    let mut wrong_provider_diagnostic = snapshot.clone();
-    wrong_provider_diagnostic.diagnostics.push(
-        ExternalSourceDiagnostic::warning(
-            "fake.agent.invalid_source",
-            "Unknown provider source",
-            Some(SourceKey::new("other.agents", "project").unwrap()),
-        )
-        .with_asset_kind(ExternalSourceAssetKind::Subagent),
-    );
-    assert!(wrong_provider_diagnostic.validate().is_err());
-
-    let mut unknown_source_diagnostic = snapshot.clone();
-    unknown_source_diagnostic.diagnostics.push(
-        ExternalSourceDiagnostic::warning(
-            "fake.agent.unknown_source",
-            "Unknown source",
-            Some(SourceKey::new("fake.agents", "missing").unwrap()),
-        )
-        .with_asset_kind(ExternalSourceAssetKind::Subagent),
-    );
-    assert!(unknown_source_diagnostic.validate().is_err());
-
-    let mut invalid_diagnostic_message = snapshot.clone();
-    invalid_diagnostic_message.diagnostics.push(
-        ExternalSourceDiagnostic::warning("fake.agent.invalid_message", "invalid\nmessage", None)
-            .with_asset_kind(ExternalSourceAssetKind::Subagent),
-    );
-    assert!(invalid_diagnostic_message.validate().is_err());
-
-    let mut wrong_asset_kind = snapshot.clone();
-    wrong_asset_kind.diagnostics.push(
-        ExternalSourceDiagnostic::warning(
-            "fake.agent.wrong_kind",
-            "Diagnostic belongs to another asset kind",
-            None,
-        )
-        .with_asset_kind(ExternalSourceAssetKind::Tool),
-    );
-    assert!(wrong_asset_kind.validate().is_err());
-
-    let mut excessive_sources = snapshot.clone();
-    excessive_sources.sources = vec![snapshot.sources[0].clone(); 1025];
-    assert!(excessive_sources.validate().is_err());
-
-    let mut excessive_definitions = snapshot.clone();
-    excessive_definitions.definitions = vec![snapshot.definitions[0].clone(); 1025];
-    assert!(excessive_definitions.validate().is_err());
-
-    let mut excessive_diagnostics = snapshot.clone();
-    excessive_diagnostics.diagnostics = vec![
-        ExternalSourceDiagnostic::warning(
-            "fake.agent.degraded",
-            "An optional field is not supported",
-            None,
-        )
-        .with_asset_kind(ExternalSourceAssetKind::Subagent);
-        1025
-    ];
-    assert!(excessive_diagnostics.validate().is_err());
-
-    let mut excessive_provenance = snapshot.clone();
-    excessive_provenance.definitions[0].provenance =
-        vec![snapshot.definitions[0].provenance[0].clone(); 257];
-    assert!(excessive_provenance.validate().is_err());
-
-    let input = ExternalSubagentDiscoveryInput {
-        context: context(),
-        suppressed_sources: [SourceKey::new("fake.agents", "suppressed").unwrap()]
-            .into_iter()
-            .collect(),
-    };
-    assert_eq!(input.suppressed_sources.len(), 1);
-}
-
-#[test]
-fn external_subagent_model_contract_preserves_control_and_opaque_reference_semantics() {
-    let requests = [
-        ExternalSubagentModelRequest::Default,
-        ExternalSubagentModelRequest::Inherit,
-        ExternalSubagentModelRequest::Reference {
-            provider_hint: Some("openrouter".to_string()),
-            model_name: "anthropic/claude-sonnet-4".to_string(),
-        },
-        ExternalSubagentModelRequest::Reference {
-            provider_hint: None,
-            model_name: "gpt-5.6-codex".to_string(),
-        },
-        ExternalSubagentModelRequest::Reference {
-            provider_hint: None,
-            model_name: "glm-5".to_string(),
-        },
-        ExternalSubagentModelRequest::Reference {
-            provider_hint: None,
-            model_name: "deepseek-v4".to_string(),
-        },
-        ExternalSubagentModelRequest::Reference {
-            provider_hint: None,
-            model_name: "future-model-that-does-not-exist-yet".to_string(),
-        },
-    ];
-
-    for request in requests {
-        let encoded = serde_json::to_value(&request).unwrap();
-        if let ExternalSubagentModelRequest::Reference {
-            provider_hint,
-            model_name,
-        } = &request
-        {
-            assert_eq!(encoded["modelName"], model_name.as_str());
-            assert!(encoded.get("model_name").is_none());
-            if let Some(provider_hint) = provider_hint {
-                assert_eq!(encoded["providerHint"], provider_hint.as_str());
-                assert!(encoded.get("provider_hint").is_none());
-            }
-        }
-        let decoded: ExternalSubagentModelRequest = serde_json::from_value(encoded).unwrap();
-        assert_eq!(decoded, request);
-    }
-
-    assert_ne!(
-        ExternalSubagentModelRequest::Inherit,
-        ExternalSubagentModelRequest::Reference {
-            provider_hint: None,
-            model_name: "inherit".to_string(),
-        }
-    );
-}
-
-#[test]
-fn external_subagent_model_profile_contract_keeps_variant_and_effort_semantics_distinct() {
-    let profiles = [
-        ExternalSubagentModelProfileRequest::NamedVariant {
-            name: "high".to_string(),
-        },
-        ExternalSubagentModelProfileRequest::ReasoningEffort {
-            value: "high".to_string(),
-        },
-    ];
-
-    let encoded = profiles
-        .iter()
-        .map(|profile| serde_json::to_value(profile).unwrap())
-        .collect::<Vec<_>>();
-    assert_eq!(
-        encoded[0],
-        serde_json::json!({ "kind": "named_variant", "name": "high" })
-    );
-    assert_eq!(
-        encoded[1],
-        serde_json::json!({ "kind": "reasoning_effort", "value": "high" })
-    );
-    assert_ne!(profiles[0], profiles[1]);
-
-    for (profile, encoded) in profiles.into_iter().zip(encoded) {
-        let decoded: ExternalSubagentModelProfileRequest = serde_json::from_value(encoded).unwrap();
-        assert_eq!(decoded, profile);
-    }
-
-    assert!(ExternalSubagentModelProfileRequest::NamedVariant {
-        name: "x".repeat(4097),
-    }
-    .validate()
-    .is_err());
-    assert!(ExternalSubagentModelProfileRequest::ReasoningEffort {
-        value: "bad\u{0001}".to_string(),
-    }
-    .validate()
-    .is_err());
-}
-
-#[test]
-fn external_subagent_model_binding_contract_groups_only_matching_scope_identity() {
-    let ecosystem = EcosystemId::new("opencode").unwrap();
-    let request = ExternalSubagentModelRequest::Reference {
-        provider_hint: Some("openrouter".to_string()),
-        model_name: "vendor/model".to_string(),
-    };
-    let global_a = external_subagent_model_binding_key(
-        &ecosystem,
-        &request,
-        None,
-        "local-user",
-        ExternalSourceScope::UserGlobal,
-        "D:/workspace/a",
-    )
-    .unwrap();
-    assert_eq!(
-        global_a,
-        "external_subagent_model_binding:408ebedb7c2644acda3b4c0c5a78e8eb83fb2ece8b3a1671a866ed0d6cc08f56",
-        "profile-free bindings must retain their pre-profile persisted identity"
-    );
-    let global_b = external_subagent_model_binding_key(
-        &ecosystem,
-        &request,
-        None,
-        "local-user",
-        ExternalSourceScope::UserGlobal,
-        "D:/workspace/b",
-    )
-    .unwrap();
-    assert_eq!(
-        global_a, global_b,
-        "user bindings belong to the execution domain"
-    );
-
-    let project_a = external_subagent_model_binding_key(
-        &ecosystem,
-        &request,
-        None,
-        "local-user",
-        ExternalSourceScope::Project,
-        "D:/workspace/a",
-    )
-    .unwrap();
-    let project_b = external_subagent_model_binding_key(
-        &ecosystem,
-        &request,
-        None,
-        "local-user",
-        ExternalSourceScope::Project,
-        "D:/workspace/b",
-    )
-    .unwrap();
-    assert_ne!(
-        project_a, project_b,
-        "project bindings stay workspace-scoped"
-    );
-    assert_ne!(
-        global_a, project_a,
-        "global and project bindings never alias"
-    );
-    let remote_global = external_subagent_model_binding_key(
-        &ecosystem,
-        &request,
-        None,
-        "remote:user@example",
-        ExternalSourceScope::RemoteUser,
-        "D:/workspace/a",
-    )
-    .unwrap();
-    assert_ne!(
-        global_a, remote_global,
-        "remote and local execution domains never share bindings"
-    );
-
-    let option = ExternalSubagentModelBindingOption {
-        target: ExternalSubagentModelBindingTarget::Primary,
-        effective_model_label: "Provider / Model".to_string(),
-        configured_reasoning_effort: Some("high".to_string()),
-    };
-    let group = ExternalSubagentModelBindingGroup {
-        binding_key: project_a,
-        request,
-        profile_request: Some(ExternalSubagentModelProfileRequest::ReasoningEffort {
-            value: "high".to_string(),
-        }),
-        scope: ExternalSourceScope::Project,
-        method: ExternalSubagentModelBindingMethod::Explicit,
-        selected_target: Some(option.target.clone()),
-        effective_model_label: Some(option.effective_model_label.clone()),
-        affected_candidate_ids: vec!["candidate-a".to_string(), "candidate-b".to_string()],
-    };
-    let encoded = serde_json::to_value((&option, &group)).unwrap();
-    let decoded: (
-        ExternalSubagentModelBindingOption,
-        ExternalSubagentModelBindingGroup,
-    ) = serde_json::from_value(encoded).unwrap();
-    assert_eq!(decoded, (option, group));
-}
-
-#[test]
-fn external_subagent_profile_binding_identity_extends_existing_model_binding_scope() {
-    let ecosystem = EcosystemId::new("opencode").unwrap();
-    let default_request = ExternalSubagentModelRequest::Default;
-    assert!(external_subagent_model_binding_key(
-        &ecosystem,
-        &default_request,
-        None,
-        "local-user",
-        ExternalSourceScope::Project,
-        "D:/workspace/a",
-    )
-    .is_none());
-
-    let variant = ExternalSubagentModelProfileRequest::NamedVariant {
-        name: "high".to_string(),
-    };
-    let effort = ExternalSubagentModelProfileRequest::ReasoningEffort {
-        value: "high".to_string(),
-    };
-    let variant_key = external_subagent_model_binding_key(
-        &ecosystem,
-        &default_request,
-        Some(&variant),
-        "local-user",
-        ExternalSourceScope::Project,
-        "D:/workspace/a",
-    )
-    .unwrap();
-    let effort_key = external_subagent_model_binding_key(
-        &ecosystem,
-        &default_request,
-        Some(&effort),
-        "local-user",
-        ExternalSourceScope::Project,
-        "D:/workspace/a",
-    )
-    .unwrap();
-    assert_ne!(variant_key, effort_key);
-    let delimited_provider = ExternalSubagentModelRequest::Reference {
-        provider_hint: Some("a:b".to_string()),
-        model_name: "c".to_string(),
-    };
-    let delimited_model = ExternalSubagentModelRequest::Reference {
-        provider_hint: Some("a".to_string()),
-        model_name: "b:c".to_string(),
-    };
-    let key_for = |request| {
-        external_subagent_model_binding_key(
-            &ecosystem,
-            request,
-            Some(&effort),
-            "local-user",
-            ExternalSourceScope::Project,
-            "D:/workspace/a",
-        )
-        .unwrap()
-    };
-    assert_ne!(key_for(&delimited_provider), key_for(&delimited_model));
-}
-
-#[test]
-fn external_subagent_decision_keys_bind_behavior_but_not_catalog_copy() {
-    let candidate = ExternalSubagentCandidateId::new("candidate-v1").unwrap();
-    let behavior = ExternalSubagentBehaviorVersion::new("behavior-v1").unwrap();
-    let approval = external_subagent_approval_key(&candidate, &behavior, "envelope-v1");
-    let same = external_subagent_approval_key(&candidate, &behavior, "envelope-v1");
-    let changed = external_subagent_approval_key(
-        &candidate,
-        &ExternalSubagentBehaviorVersion::new("behavior-v2").unwrap(),
-        "envelope-v1",
-    );
-    assert_eq!(approval, same);
-    assert_ne!(approval, changed);
-
-    let first = external_subagent_conflict_key(
-        "local-user",
-        "/workspace",
-        "review",
-        [("local", "v1"), (candidate.as_str(), behavior.as_str())],
-    );
-    let reordered = external_subagent_conflict_key(
-        "local-user",
-        "/workspace",
-        "REVIEW",
-        [(candidate.as_str(), behavior.as_str()), ("local", "v1")],
-    );
-    assert_eq!(first, reordered);
-}
-
-#[test]
-fn diagnostics_remain_source_qualified() {
-    let diagnostic = ExternalSourceDiagnostic::warning(
-        "fake.warning",
-        "A non-blocking fake diagnostic",
-        Some(SourceKey::new("fake", "source").unwrap()),
-    );
-    assert_eq!(diagnostic.source.unwrap().provider_id.as_str(), "fake");
-}
-
-#[test]
-fn provider_snapshot_rejects_duplicate_sources_and_commands() {
-    let provider = FakeProvider::new("fake", "fake.ecosystem", "project", 1);
-    let mut duplicate_source = provider.snapshot.clone();
-    duplicate_source
-        .sources
-        .push(duplicate_source.sources[0].clone());
-    assert!(duplicate_source.validate().is_err());
-
-    let mut duplicate_command = provider.snapshot;
-    duplicate_command
-        .commands
-        .push(duplicate_command.commands[0].clone());
-    assert!(duplicate_command.validate().is_err());
-}
-
-#[test]
-fn unavailable_command_must_be_unique_absent_and_source_qualified() {
-    let provider = FakeProvider::new("fake", "fake.ecosystem", "project", 1);
-    let mut invalid = provider.snapshot;
-    invalid
-        .unavailable_command_ids
-        .push(invalid.commands[0].id.clone());
-    assert!(invalid.validate().is_err());
-}
-
-#[test]
-fn standalone_tool_contract_separates_static_preview_from_executable_source() {
-    let target = SourceQualifiedToolTargetId::new(
-        SourceKey::new("opencode.tools", "project-tools").unwrap(),
-        "weather.js",
-    )
-    .unwrap();
-    let tool = ExternalToolDefinition {
-        id: SourceQualifiedToolId::new(target, "default").unwrap(),
-        name: "weather".to_string(),
-        description_preview: "Get the weather for a location".to_string(),
-        module_path: "/workspace/.opencode/tools/weather.js".to_string(),
-        working_directory: "/workspace".to_string(),
-        runtime_kind: ExternalToolRuntimeKind::JavaScript,
-        capabilities: vec![
-            ExternalToolCapability::FileSystem,
-            ExternalToolCapability::Network,
-            ExternalToolCapability::Process,
-        ],
-        content_version: "sha256:v1".to_string(),
-        static_status: ExternalToolStaticStatus::Ready,
-    };
-
-    let encoded = serde_json::to_value(&tool).expect("serialize tool preview");
-    assert_eq!(encoded["name"], "weather");
-    assert_eq!(encoded["runtimeKind"], "java_script");
-    assert!(encoded.get("moduleSource").is_none());
-    assert!(encoded.get("payload").is_none());
-    tool.validate().expect("valid standalone tool preview");
-}
-
-#[test]
-fn legacy_public_snapshot_downprojects_new_tool_review_variants() {
-    let snapshot: ExternalSourcePublicSnapshot = serde_json::from_value(serde_json::json!({
-        "generation": 1,
-        "discoveryPending": false,
-        "sources": [],
-        "commands": [{
-            "candidateId": "17:opencode.commands6:global6:review",
-            "definition": {
-                "id": {
-                    "source": { "providerId": "opencode.commands", "sourceId": "global" },
-                    "localId": "review"
-                },
-                "name": "review",
-                "description": "Review changes",
-                "availability": { "state": "available" },
-                "contentVersion": "v1"
-            }
-        }],
-        "tools": [{
-            "definition": {
-                "id": {
-                    "target": {
-                        "source": { "providerId": "opencode.tools", "sourceId": "project" },
-                        "localId": "weather.js"
-                    },
-                    "exportId": "default"
-                },
-                "name": "weather",
-                "descriptionPreview": "Get weather",
-                "modulePath": "<workspace>/.opencode/tools/weather.js",
-                "workingDirectory": "<workspace>",
-                "runtimeKind": "java_script",
-                "capabilities": [],
-                "contentVersion": "sha256:v1",
-                "staticStatus": { "state": "ready" }
-            },
-            "approvalKey": "approval-v1",
-            "decisionKey": "decision-v1",
-            "activation": { "state": "declined" }
-        }],
-        "subagents": [{
-            "candidateId": "external-review",
-            "logicalId": "review",
-            "displayName": "External Review",
-            "description": "Review changes",
-            "providerLabel": "OpenCode",
-            "scope": "project",
-            "sourceKeys": [],
-            "sourceLocationLabels": [],
-            "sourceCount": 1,
-            "requestedModel": {
-                "kind": "reference",
-                "providerHint": "anthropic",
-                "modelName": "claude-sonnet-4"
-            },
-            "requestedModelProfile": {
-                "kind": "reasoning_effort",
-                "value": "high"
-            },
-            "modelBindingMethod": "binding_required",
-            "modelBindingKey": "external_subagent_model_binding:review",
-            "effectiveToolLabels": ["Read"],
-            "unavailableToolLabels": ["Shell"],
-            "supportsFollowUp": false,
-            "compatibilityState": "blocked",
-            "diagnostics": [{
-                "code": "external_subagent.tool_unavailable",
-                "blocksActivation": true
-            }],
-            "activationState": { "state": "blocked" },
-            "decisionKey": "agent-decision-v1"
-        }],
-        "subagentModelBindingGroups": [{
-            "bindingKey": "external_subagent_model_binding:review",
-            "request": { "kind": "reference", "modelName": "claude-sonnet-4" },
-            "profileRequest": { "kind": "reasoning_effort", "value": "high" },
-            "scope": "project",
-            "method": "binding_required",
-            "affectedCandidateIds": ["external-review"]
-        }],
-        "subagentModelBindingOptions": [{
-            "target": { "kind": "fast" },
-            "effectiveModelLabel": "Fast",
-            "configuredReasoningEffort": "high"
-        }]
-    }))
-    .expect("new public snapshot");
-
-    let legacy =
-        serde_json::to_value(snapshot.into_legacy_v0_compatible()).expect("legacy public snapshot");
-    assert!(legacy["commands"][0].get("candidateId").is_none());
-    assert_eq!(legacy["tools"][0]["activation"]["state"], "disabled");
-    assert!(legacy["subagents"][0]
-        .get("unavailableToolLabels")
-        .is_none());
-    assert!(legacy["subagents"][0].get("requestedModel").is_none());
-    assert!(legacy["subagents"][0]
-        .get("requestedModelProfile")
-        .is_none());
-    assert!(legacy["subagents"][0].get("modelBindingMethod").is_none());
-    assert!(legacy["subagents"][0].get("modelBindingKey").is_none());
-    assert!(legacy.get("subagentModelBindingGroups").is_none());
-    assert!(legacy.get("subagentModelBindingOptions").is_none());
-}
-
-#[test]
-fn standalone_tool_contract_rejects_names_that_are_not_model_callable() {
-    let target = SourceQualifiedToolTargetId::new(
-        SourceKey::new("fake.tools", "project-tools").unwrap(),
-        "unsafe.js",
-    )
-    .unwrap();
-    let mut tool = ExternalToolDefinition {
-        id: SourceQualifiedToolId::new(target, "default").unwrap(),
-        name: "unsafe tool".to_string(),
-        description_preview: String::new(),
-        module_path: "/workspace/unsafe.js".to_string(),
-        working_directory: "/workspace".to_string(),
-        runtime_kind: ExternalToolRuntimeKind::JavaScript,
-        capabilities: vec![ExternalToolCapability::FileSystem],
-        content_version: "sha256:v1".to_string(),
-        static_status: ExternalToolStaticStatus::Ready,
-    };
-
-    assert!(tool.validate().is_err());
-    tool.name = "safe_tool-1".to_string();
-    tool.validate()
-        .expect("portable tool name should be accepted");
-}
-
-#[test]
-fn tool_approval_is_stable_for_safe_updates_but_changes_with_capabilities_or_domain() {
-    let target = SourceQualifiedToolTargetId::new(
-        SourceKey::new("opencode.tools", "project-tools").unwrap(),
-        "weather.js",
-    )
-    .unwrap();
-    let first = external_tool_approval_key(
-        "local-user",
-        &target,
-        ExternalToolRuntimeKind::JavaScript,
-        [
-            ExternalToolCapability::FileSystem,
-            ExternalToolCapability::Network,
-        ],
-    );
-    let reordered = external_tool_approval_key(
-        "local-user",
-        &target,
-        ExternalToolRuntimeKind::JavaScript,
-        [
-            ExternalToolCapability::Network,
-            ExternalToolCapability::FileSystem,
-        ],
-    );
-    let expanded = external_tool_approval_key(
-        "local-user",
-        &target,
-        ExternalToolRuntimeKind::JavaScript,
-        [
-            ExternalToolCapability::FileSystem,
-            ExternalToolCapability::Network,
-            ExternalToolCapability::Process,
-        ],
-    );
-    let remote = external_tool_approval_key(
-        "remote-user",
-        &target,
-        ExternalToolRuntimeKind::JavaScript,
-        [
-            ExternalToolCapability::FileSystem,
-            ExternalToolCapability::Network,
-        ],
-    );
-
-    assert_eq!(first, reordered);
-    assert_ne!(first, expanded);
-    assert_ne!(first, remote);
-}
-
-#[test]
-fn tool_conflict_choice_is_invalidated_when_name_or_candidate_changes() {
-    let first = external_tool_conflict_key(
-        "local-user",
-        "weather",
-        [
-            ("builtin:weather", "builtin-v1"),
-            ("opencode:weather", "tool-v1"),
-        ],
-    );
-    let reordered = external_tool_conflict_key(
-        "local-user",
-        "WEATHER",
-        [
-            ("opencode:weather", "tool-v1"),
-            ("builtin:weather", "builtin-v1"),
-        ],
-    );
-    let updated = external_tool_conflict_key(
-        "local-user",
-        "weather",
-        [
-            ("builtin:weather", "builtin-v1"),
-            ("opencode:weather", "tool-v2"),
-        ],
-    );
-
-    assert_ne!(first, reordered);
-    assert_ne!(first, updated);
-}
-
-#[test]
-fn external_mcp_contract_keeps_runtime_secrets_out_of_static_snapshots() {
-    let source = source("opencode.mcp", "opencode", "project-config");
-    let definition = ExternalMcpServerDefinition {
-        id: SourceQualifiedMcpServerId::new(source.key.clone(), "github").unwrap(),
-        provenance: vec![source.key.clone()],
-        name: "github".to_string(),
-        transport: ExternalMcpTransportKind::StreamableHttp,
-        command_preview: None,
-        argument_count: 0,
-        working_directory: None,
-        environment_keys: Vec::new(),
-        environment_reference_names: Vec::new(),
-        remote_url_preview: Some("https://mcp.example.com/mcp".to_string()),
-        header_names: vec!["Authorization".to_string()],
-        timeouts: ExternalMcpTimeouts::default(),
-        source_enabled: true,
-        behavior_version: "sha256:behavior-v1".to_string(),
-        static_status: ExternalMcpStaticStatus::Ready,
-    };
-    let provider =
-        ExternalMcpProviderIdentity::new("opencode.mcp", "opencode", "OpenCode MCP servers")
-            .unwrap();
-    let snapshot = ExternalMcpProviderSnapshot {
-        provider,
-        sources: vec![source],
-        servers: vec![definition.clone()],
-        diagnostics: Vec::new(),
-    };
-
-    snapshot.validate().expect("valid MCP provider snapshot");
-    let encoded = serde_json::to_string(&snapshot).expect("serialize MCP snapshot");
-    assert!(encoded.contains("Authorization"));
-    assert!(!encoded.contains("Bearer secret"));
-    assert!(encoded.contains("mcp.example.com"));
-
-    let prepared = PreparedExternalMcpServer {
-        id: definition.id,
-        behavior_version: definition.behavior_version,
-        timeouts: ExternalMcpTimeouts::default(),
-        transport: PreparedExternalMcpTransport::Remote {
-            url: "https://mcp.example.com/mcp?token=url-secret".to_string(),
-            headers: [(
-                "Authorization".to_string(),
-                SecretValue::new("Bearer secret"),
-            )]
-            .into_iter()
-            .collect(),
-            oauth_enabled: true,
-        },
-    };
-    assert_eq!(
-        prepared.transport.remote_headers().unwrap()["Authorization"].expose(),
-        "Bearer secret"
-    );
-    assert!(!format!("{prepared:?}").contains("Bearer secret"));
-    assert!(!format!("{prepared:?}").contains("url-secret"));
-}
-
-#[test]
-fn external_mcp_timeouts_are_positive_optional_millisecond_facts() {
-    let timeouts = ExternalMcpTimeouts {
-        startup_ms: Some(2_000),
-        catalog_ms: None,
-        execution_ms: Some(30_000),
-    };
-
-    timeouts.validate().expect("positive timeouts are valid");
-    assert_eq!(
-        serde_json::to_value(&timeouts).unwrap(),
-        serde_json::json!({
-            "startupMs": 2_000,
-            "executionMs": 30_000,
-        })
-    );
-    assert!(ExternalMcpTimeouts {
-        startup_ms: Some(0),
-        ..Default::default()
-    }
-    .validate()
-    .is_err());
-    assert!(ExternalMcpTimeouts {
-        execution_ms: Some(9_007_199_254_740_991),
-        ..Default::default()
-    }
-    .validate()
-    .is_ok());
-    assert!(ExternalMcpTimeouts {
-        execution_ms: Some(9_007_199_254_740_992),
-        ..Default::default()
-    }
-    .validate()
-    .is_err());
-    assert!(ExternalMcpTimeouts::default().is_empty());
-}
-
-#[test]
-fn external_mcp_revision_key_never_exposes_material_through_debug_output() {
-    let key = ExternalMcpRevisionKey::new([0x5a; 32]);
-    assert_eq!(format!("{key:?}"), "ExternalMcpRevisionKey([REDACTED])");
-    assert!(!format!("{key:?}").contains("5a"));
-}
-
-#[test]
-fn external_mcp_revision_is_stable_secret_sensitive_and_not_an_unkeyed_oracle() {
-    let key = ExternalMcpRevisionKey::new([7; 32]);
-    let first = key.opaque_revision(
-        "test.mcp.behavior.v1",
-        [b"server".as_slice(), b"PIN=0007".as_slice()],
-    );
-    let repeated = key.opaque_revision(
-        "test.mcp.behavior.v1",
-        [b"server".as_slice(), b"PIN=0007".as_slice()],
-    );
-    let changed = key.opaque_revision(
-        "test.mcp.behavior.v1",
-        [b"server".as_slice(), b"PIN=0008".as_slice()],
-    );
-    let raw_candidate = format!(
-        "sha256:{}",
-        hex::encode(Sha256::digest(b"server\0PIN=0007"))
-    );
-
-    assert_eq!(first, repeated);
-    assert_ne!(first, changed);
-    assert_ne!(first, raw_candidate);
-    assert!(first.starts_with("hmac-sha256:"));
-}
-
-#[test]
-fn external_mcp_snapshot_rejects_cross_provider_and_duplicate_servers() {
-    let provider =
-        ExternalMcpProviderIdentity::new("opencode.mcp", "opencode", "OpenCode MCP").unwrap();
-    let source = source("opencode.mcp", "opencode", "project-config");
-    let definition = ExternalMcpServerDefinition {
-        id: SourceQualifiedMcpServerId::new(source.key.clone(), "github").unwrap(),
-        provenance: vec![source.key.clone()],
-        name: "github".to_string(),
-        transport: ExternalMcpTransportKind::LocalStdio,
-        command_preview: Some("npx".to_string()),
-        argument_count: 2,
-        working_directory: Some("/workspace".to_string()),
-        environment_keys: vec!["GITHUB_TOKEN".to_string()],
-        environment_reference_names: Vec::new(),
-        remote_url_preview: None,
-        header_names: Vec::new(),
-        timeouts: ExternalMcpTimeouts::default(),
-        source_enabled: true,
-        behavior_version: "sha256:behavior-v1".to_string(),
-        static_status: ExternalMcpStaticStatus::Ready,
-    };
-    let snapshot = ExternalMcpProviderSnapshot {
-        provider,
-        sources: vec![source],
-        servers: vec![definition.clone(), definition],
-        diagnostics: Vec::new(),
-    };
-
-    assert!(snapshot.validate().is_err());
-
-    let input = ExternalMcpDiscoveryInput {
-        context: context(),
-        suppressed_sources: [SourceKey::new("opencode.mcp", "suppressed").unwrap()]
-            .into_iter()
-            .collect(),
-        revision_key: ExternalMcpRevisionKey::new([7; 32]),
-    };
-    assert_eq!(input.suppressed_sources.len(), 1);
-}
-
-#[test]
-fn external_mcp_decisions_change_only_with_behavior_domain_or_conflict_participants() {
-    let id = SourceQualifiedMcpServerId::new(
-        SourceKey::new("opencode.mcp", "project-config").unwrap(),
-        "github",
-    )
-    .unwrap();
-    let first = external_mcp_approval_key("local-user", "/workspace-a", &id, "behavior-v1");
-    let same = external_mcp_approval_key("local-user", "/workspace-a", &id, "behavior-v1");
-    let updated = external_mcp_approval_key("local-user", "/workspace-a", &id, "behavior-v2");
-    let other_workspace =
-        external_mcp_approval_key("local-user", "/workspace-b", &id, "behavior-v1");
-    let remote = external_mcp_approval_key("remote-user", "/workspace-a", &id, "behavior-v1");
-    assert_eq!(first, same);
-    assert_ne!(first, updated);
-    assert_ne!(first, other_workspace);
-    assert_ne!(first, remote);
-
-    let stable_id = id.stable_key();
-    let conflict = external_mcp_conflict_key(
-        "local-user",
-        "/workspace-a",
-        "github",
-        [
-            ("bitfun:github", "native-v1"),
-            (stable_id.as_str(), "behavior-v1"),
-        ],
-    );
-    let reordered = external_mcp_conflict_key(
-        "local-user",
-        "/workspace-a",
-        "GITHUB",
-        [
-            (stable_id.as_str(), "behavior-v1"),
-            ("bitfun:github", "native-v1"),
-        ],
-    );
-    let participant_updated = external_mcp_conflict_key(
-        "local-user",
-        "/workspace-a",
-        "github",
-        [
-            ("bitfun:github", "native-v1"),
-            (stable_id.as_str(), "behavior-v2"),
-        ],
-    );
-    assert_eq!(conflict, reordered);
-    assert_ne!(conflict, participant_updated);
-    assert_ne!(
-        conflict,
-        external_mcp_conflict_key(
-            "local-user",
-            "/workspace-b",
-            "github",
-            [
-                ("bitfun:github", "native-v1"),
-                (stable_id.as_str(), "behavior-v1"),
-            ],
-        )
-    );
-}
-
-#[test]
-fn external_mcp_product_view_is_version_guarded_and_contains_only_disclosed_fields() {
-    let source = source("opencode.mcp", "opencode", "project-config");
-    let definition = ExternalMcpServerDefinition {
-        id: SourceQualifiedMcpServerId::new(source.key.clone(), "github").unwrap(),
-        provenance: vec![source.key],
-        name: "github".to_string(),
-        transport: ExternalMcpTransportKind::LocalStdio,
-        command_preview: Some("npx".to_string()),
-        argument_count: 2,
-        working_directory: Some("<workspace>".to_string()),
-        environment_keys: vec!["GITHUB_TOKEN".to_string()],
-        environment_reference_names: Vec::new(),
-        remote_url_preview: None,
-        header_names: Vec::new(),
-        timeouts: ExternalMcpTimeouts::default(),
-        source_enabled: true,
-        behavior_version: "sha256:behavior-v1".to_string(),
-        static_status: ExternalMcpStaticStatus::Ready,
-    };
-    let entry = ExternalMcpCatalogEntry {
-        candidate_id: definition.candidate_id(),
-        definition: definition.clone(),
-        approval_key: "external_mcp_approval:local-user:v1".to_string(),
-        decision_key: "external_mcp_approval:local-user:v1".to_string(),
-        runtime_id: None,
-        activation_state: ExternalMcpActivationState::ApprovalRequired,
-    };
-    let request = ExternalMcpApprovalRequest {
-        candidate_id: entry.candidate_id.clone(),
-        approval_key: entry.approval_key.clone(),
-        decision_key: entry.decision_key.clone(),
-        definition,
-    };
-    let conflict = ExternalMcpConflict {
-        conflict_key: "external_mcp:local-user:github:v1".to_string(),
-        server_name: "github".to_string(),
-        candidates: vec![
-            ExternalMcpConflictCandidate {
-                candidate_id: "native_mcp:github".to_string(),
-                display_name: "BitFun: github".to_string(),
-                external: false,
-                source: None,
-                behavior_version: "native-v1".to_string(),
-                available: true,
-                unavailable_reason: None,
-            },
-            ExternalMcpConflictCandidate {
-                candidate_id: entry.candidate_id.clone(),
-                display_name: "OpenCode: github".to_string(),
-                external: true,
-                source: Some(entry.definition.id.source.clone()),
-                behavior_version: entry.definition.behavior_version.clone(),
-                available: true,
-                unavailable_reason: None,
-            },
-        ],
-        selected_candidate_id: None,
-    };
-
-    let encoded = serde_json::to_string(&(entry, request, conflict)).unwrap();
-    assert!(encoded.contains("GITHUB_TOKEN"));
-    assert!(!encoded.contains("Bearer secret"));
-    assert!(encoded.contains("approval_required"));
-}
-
-fn external_capability(value: &str) -> ExternalIntegrationCapabilityId {
-    ExternalIntegrationCapabilityId::new(value).expect("valid external capability id")
-}
-
-const TEST_ECOSYSTEM_ID: &str = "test-ecosystem";
-const EXTERNAL_CAPABILITY_COMMAND: &str = "command";
-const EXTERNAL_CAPABILITY_TOOL: &str = "tool";
-const EXTERNAL_CAPABILITY_SUBAGENT: &str = "subagent";
-const EXTERNAL_CAPABILITY_MCP: &str = "mcp";
-
-fn test_external_integration_ecosystems() -> Vec<ExternalIntegrationEcosystemDescriptor> {
-    let capability =
-        |id, recommended_access, safety_ceiling| ExternalIntegrationCapabilityDescriptor {
-            capability_id: external_capability(id),
-            recommended_access,
-            safety_ceiling,
-        };
-    vec![ExternalIntegrationEcosystemDescriptor {
-        ecosystem_id: EcosystemId::new(TEST_ECOSYSTEM_ID).unwrap(),
-        display_name: "Test ecosystem".to_string(),
-        adapter_revision: "1".to_string(),
-        capabilities: vec![
-            capability(
-                EXTERNAL_CAPABILITY_COMMAND,
-                ExternalIntegrationAccess::Auto,
-                ExternalIntegrationAccess::Auto,
-            ),
-            capability(
-                EXTERNAL_CAPABILITY_TOOL,
-                ExternalIntegrationAccess::AskBeforeUse,
-                ExternalIntegrationAccess::AskBeforeUse,
-            ),
-            capability(
-                EXTERNAL_CAPABILITY_SUBAGENT,
-                ExternalIntegrationAccess::AskBeforeUse,
-                ExternalIntegrationAccess::AskBeforeUse,
-            ),
-            capability(
-                EXTERNAL_CAPABILITY_MCP,
-                ExternalIntegrationAccess::AskBeforeUse,
-                ExternalIntegrationAccess::AskBeforeUse,
-            ),
-        ],
-    }]
-}
-
-#[test]
-fn external_integration_policy_is_disabled_by_default() {
-    let effective = evaluate_external_integration_policy(
-        &ExternalIntegrationPolicyDocument::default(),
-        Some("workspace-a"),
-        &test_external_integration_ecosystems(),
-    )
-    .expect("default policy evaluates");
-    let opencode = effective
-        .ecosystems
-        .get(&EcosystemId::new(TEST_ECOSYSTEM_ID).unwrap())
-        .expect("test ecosystem is registered");
-
-    assert!(!effective.enabled);
-    assert_eq!(opencode.mode, ExternalIntegrationMode::Disabled);
-    for capability in [
-        EXTERNAL_CAPABILITY_COMMAND,
-        EXTERNAL_CAPABILITY_TOOL,
-        EXTERNAL_CAPABILITY_SUBAGENT,
-        EXTERNAL_CAPABILITY_MCP,
-    ] {
-        assert_eq!(
-            opencode.capabilities[&external_capability(capability)],
-            ExternalIntegrationAccess::Disabled
-        );
-    }
-}
-
-#[test]
-fn explicitly_enabled_recommended_policy_keeps_registered_access_defaults() {
-    let mut document = ExternalIntegrationPolicyDocument::default();
-    document.user_defaults.enabled = true;
-
-    let effective = evaluate_external_integration_policy(
-        &document,
-        Some("workspace-a"),
-        &test_external_integration_ecosystems(),
-    )
-    .expect("enabled recommended policy evaluates");
-    let opencode = effective
-        .ecosystems
-        .get(&EcosystemId::new(TEST_ECOSYSTEM_ID).unwrap())
-        .expect("test ecosystem is registered");
-
-    assert!(effective.enabled);
-    assert_eq!(opencode.mode, ExternalIntegrationMode::Recommended);
-    assert_eq!(
-        opencode.capabilities[&external_capability(EXTERNAL_CAPABILITY_COMMAND)],
-        ExternalIntegrationAccess::Auto
-    );
-    for capability in [
-        EXTERNAL_CAPABILITY_TOOL,
-        EXTERNAL_CAPABILITY_SUBAGENT,
-        EXTERNAL_CAPABILITY_MCP,
-    ] {
-        assert_eq!(
-            opencode.capabilities[&external_capability(capability)],
-            ExternalIntegrationAccess::AskBeforeUse
-        );
-    }
-}
-
-#[test]
-fn workspace_policy_overrides_only_the_fields_the_user_changed() {
-    let ecosystem = EcosystemId::new(TEST_ECOSYSTEM_ID).unwrap();
-    let mut document = ExternalIntegrationPolicyDocument::default();
-    document.user_defaults.enabled = true;
-    document.user_defaults.ecosystems.insert(
-        ecosystem.clone(),
-        ExternalEcosystemPolicy {
-            mode: ExternalIntegrationMode::DiscoverOnly,
-            ..ExternalEcosystemPolicy::default()
-        },
-    );
-    document.workspace_overrides.insert(
-        "workspace-a".to_string(),
-        ExternalIntegrationPolicyOverride {
-            ecosystems: [(
-                ecosystem.clone(),
-                ExternalEcosystemPolicyOverride {
-                    mode: Some(ExternalIntegrationMode::Custom),
-                    capability_overrides: [(
-                        external_capability(EXTERNAL_CAPABILITY_COMMAND),
-                        ExternalIntegrationAccess::Auto,
-                    )]
-                    .into_iter()
-                    .collect(),
-                    ..ExternalEcosystemPolicyOverride::default()
-                },
-            )]
-            .into_iter()
-            .collect(),
-            ..ExternalIntegrationPolicyOverride::default()
-        },
-    );
-
-    let effective = evaluate_external_integration_policy(
-        &document,
-        Some("workspace-a"),
-        &test_external_integration_ecosystems(),
-    )
-    .unwrap();
-    let opencode = &effective.ecosystems[&ecosystem];
-    assert_eq!(opencode.mode, ExternalIntegrationMode::Custom);
-    assert_eq!(
-        opencode.capabilities[&external_capability(EXTERNAL_CAPABILITY_COMMAND)],
-        ExternalIntegrationAccess::Auto
-    );
-    assert_eq!(
-        opencode.capabilities[&external_capability(EXTERNAL_CAPABILITY_MCP)],
-        ExternalIntegrationAccess::DiscoverOnly
-    );
-
-    let inherited = evaluate_external_integration_policy(
-        &document,
-        Some("workspace-b"),
-        &test_external_integration_ecosystems(),
-    )
-    .unwrap();
-    assert_eq!(
-        inherited.ecosystems[&ecosystem].mode,
-        ExternalIntegrationMode::DiscoverOnly
-    );
-}
-
-#[test]
-fn high_risk_auto_access_is_limited_by_the_capability_owner() {
-    let ecosystem = EcosystemId::new(TEST_ECOSYSTEM_ID).unwrap();
-    let mcp = external_capability(EXTERNAL_CAPABILITY_MCP);
-    let mut document = ExternalIntegrationPolicyDocument::default();
-    document.user_defaults.enabled = true;
-    document.user_defaults.ecosystems.insert(
-        ecosystem.clone(),
-        ExternalEcosystemPolicy {
-            mode: ExternalIntegrationMode::Custom,
-            capability_overrides: [(mcp.clone(), ExternalIntegrationAccess::Auto)]
-                .into_iter()
-                .collect(),
-            ..ExternalEcosystemPolicy::default()
-        },
-    );
-
-    let effective = evaluate_external_integration_policy(
-        &document,
-        None,
-        &test_external_integration_ecosystems(),
-    )
-    .unwrap();
-    let opencode = &effective.ecosystems[&ecosystem];
-    assert_eq!(
-        opencode.capabilities[&mcp],
-        ExternalIntegrationAccess::AskBeforeUse
-    );
-    assert!(opencode.policy_limited_capabilities.contains(&mcp));
-}
-
-#[test]
-fn future_policy_values_and_minor_fields_survive_read_modify_write() {
-    let raw = serde_json::json!({
-        "schemaMajor": 1,
-        "userDefaults": {
-            "enabled": true,
-            "ecosystems": {
-                "opencode": {
-                    "mode": "future_mode",
-                    "capabilityOverrides": {
-                        "future-capability": "future_access"
-                    },
-                    "futureEcosystemField": { "enabled": true }
-                }
-            },
-            "futureSettingsField": "preserve-me"
-        },
-        "workspaceOverrides": {},
-        "futureDocumentField": [1, 2, 3]
-    });
-    let mut document: ExternalIntegrationPolicyDocument =
-        serde_json::from_value(raw.clone()).expect("future minor data remains readable");
-    document.user_defaults.enabled = false;
-    let encoded = serde_json::to_value(&document).expect("policy remains serializable");
-
-    assert_eq!(
-        encoded["userDefaults"]["ecosystems"]["opencode"]["mode"],
-        "future_mode"
-    );
-    assert_eq!(
-        encoded["userDefaults"]["ecosystems"]["opencode"]["capabilityOverrides"]
-            ["future-capability"],
-        "future_access"
-    );
-    assert_eq!(
-        encoded["userDefaults"]["ecosystems"]["opencode"]["futureEcosystemField"],
-        raw["userDefaults"]["ecosystems"]["opencode"]["futureEcosystemField"]
-    );
-    assert_eq!(
-        encoded["userDefaults"]["futureSettingsField"],
-        "preserve-me"
-    );
-    assert_eq!(encoded["futureDocumentField"], raw["futureDocumentField"]);
-
-    let effective = evaluate_external_integration_policy(
-        &document,
-        None,
-        &test_external_integration_ecosystems(),
-    )
-    .unwrap();
-    assert!(!effective.enabled);
-}
-
-#[test]
-fn incompatible_policy_schema_major_is_rejected_without_downgrade() {
-    let document = ExternalIntegrationPolicyDocument {
-        schema_major: 2,
-        ..ExternalIntegrationPolicyDocument::default()
-    };
-    let error = evaluate_external_integration_policy(
-        &document,
-        None,
-        &test_external_integration_ecosystems(),
-    )
-    .expect_err("future major schemas must fail closed");
-    assert!(error.to_string().contains("schema major: 2"));
-}
-
-#[test]
-fn incompatible_policy_schema_has_a_safe_read_only_public_snapshot() {
-    let raw = serde_json::json!({
-        "schemaMajor": 2,
-        "userDefaults": {
-            "enabled": true,
-            "futureSecretHostField": "persistence-only"
-        },
-        "futureDocumentField": { "keep": true }
-    });
-    let document: ExternalIntegrationPolicyDocument = serde_json::from_value(raw).unwrap();
-    let snapshot = external_integration_policy_snapshot(
-        &document,
-        Some("workspace-a"),
-        test_external_integration_ecosystems(),
-    )
-    .expect("incompatible schemas remain inspectable through a safe snapshot");
-
-    assert_eq!(
-        snapshot.status,
-        ExternalIntegrationPolicyStatus::IncompatibleSchema
-    );
-    assert!(!snapshot.global_effective.enabled);
-    assert!(!snapshot.effective.enabled);
-    assert!(snapshot
-        .effective
-        .ecosystems
-        .values()
-        .all(|ecosystem| ecosystem
-            .capabilities
-            .values()
-            .all(|access| { matches!(access, ExternalIntegrationAccess::Disabled) })));
-
-    let public = serde_json::to_string(&snapshot).unwrap();
-    assert!(!public.contains("futureSecretHostField"));
-    assert!(!public.contains("futureDocumentField"));
-
-    let persisted = serde_json::to_string(&document).unwrap();
-    assert!(persisted.contains("futureSecretHostField"));
-    assert!(persisted.contains("futureDocumentField"));
-}
-
-#[test]
-fn integration_registry_rejects_ambiguous_or_unsafe_descriptors() {
-    let mut duplicate_ecosystem = test_external_integration_ecosystems();
-    duplicate_ecosystem.push(duplicate_ecosystem[0].clone());
-    let duplicate_error = evaluate_external_integration_policy(
-        &ExternalIntegrationPolicyDocument::default(),
-        None,
-        &duplicate_ecosystem,
-    )
-    .expect_err("duplicate ecosystem registrations must fail closed");
-    assert!(duplicate_error.to_string().contains("duplicate ecosystem"));
-
-    let mut unsafe_recommendation = test_external_integration_ecosystems();
-    unsafe_recommendation[0].capabilities[1].recommended_access = ExternalIntegrationAccess::Auto;
-    let unsafe_error = evaluate_external_integration_policy(
-        &ExternalIntegrationPolicyDocument::default(),
-        None,
-        &unsafe_recommendation,
-    )
-    .expect_err("registry defaults cannot exceed their safety ceiling");
-    assert!(unsafe_error
-        .to_string()
-        .contains("exceeds the safety ceiling"));
-}
-
-#[test]
-fn public_snapshot_never_exposes_executable_prompt_templates() {
-    let snapshot = ExternalSourceCatalogSnapshot {
-        generation: 1,
-        discovery_pending: false,
-        sources: Vec::new(),
-        commands: vec![PromptCommandCatalogEntry {
-            definition: command("opencode", "project-commands", 1),
-        }],
-        command_conflicts: Vec::new(),
-        tools: Vec::new(),
-        tool_approval_requests: Vec::new(),
-        tool_conflicts: Vec::new(),
-        mcp_generation: 0,
-        mcp_servers: Vec::new(),
-        mcp_approval_requests: Vec::new(),
-        mcp_conflicts: Vec::new(),
-        subagent_generation: 0,
-        preference_revision: 0,
-        subagents: Vec::new(),
-        subagent_model_binding_groups: vec![ExternalSubagentModelBindingGroup {
-            binding_key: "external_subagent_model_binding:review".to_string(),
-            request: ExternalSubagentModelRequest::Reference {
-                provider_hint: Some("anthropic".to_string()),
-                model_name: "claude-sonnet-4".to_string(),
-            },
-            profile_request: None,
-            scope: ExternalSourceScope::Project,
-            method: ExternalSubagentModelBindingMethod::BindingRequired,
-            selected_target: None,
-            effective_model_label: None,
-            affected_candidate_ids: vec!["opencode-review".to_string()],
-        }],
-        subagent_model_binding_options: vec![ExternalSubagentModelBindingOption {
-            target: ExternalSubagentModelBindingTarget::Fast,
-            effective_model_label: "GLM-4.5-Air".to_string(),
-            configured_reasoning_effort: None,
-        }],
-        subagent_conflicts: Vec::new(),
-        pending_subagent_approvals: Vec::new(),
-        integration_policy: Default::default(),
-        diagnostics: Vec::new(),
-    };
-
-    let public = ExternalSourcePublicSnapshot::from(snapshot);
-    let encoded = serde_json::to_value(public).expect("serialize public projection");
-
-    assert_eq!(encoded["commands"][0]["definition"]["name"], "review");
-    assert!(encoded["commands"][0]["definition"]
-        .get("template")
-        .is_none());
-    assert_eq!(
-        encoded["subagentModelBindingGroups"][0]["bindingKey"],
-        "external_subagent_model_binding:review"
-    );
-    assert_eq!(
-        encoded["subagentModelBindingOptions"][0]["effectiveModelLabel"],
-        "GLM-4.5-Air"
-    );
-}
-
-#[test]
-fn control_projection_keeps_lifecycle_facts_orthogonal() {
-    let catalog = ExternalSourceCatalogSnapshot {
-        generation: 7,
-        discovery_pending: false,
-        sources: vec![ExternalSourceCatalogEntry {
-            stable_key: "opencode.commands:project".to_string(),
-            presentation_group_id: None,
-            record: source("opencode.commands", "opencode", "project"),
-            lifecycle: ExternalSourceLifecycleState::UsingLastValidVersion,
-        }],
-        commands: vec![PromptCommandCatalogEntry {
-            definition: command("opencode.commands", "project", 1),
-        }],
-        command_conflicts: Vec::new(),
-        tools: Vec::new(),
-        tool_approval_requests: Vec::new(),
-        tool_conflicts: Vec::new(),
-        mcp_generation: 2,
-        mcp_servers: Vec::new(),
-        mcp_approval_requests: Vec::new(),
-        mcp_conflicts: Vec::new(),
-        subagent_generation: 3,
-        preference_revision: 11,
-        subagents: Vec::new(),
-        subagent_model_binding_groups: Vec::new(),
-        subagent_model_binding_options: Vec::new(),
-        subagent_conflicts: Vec::new(),
-        pending_subagent_approvals: Vec::new(),
-        integration_policy: Default::default(),
-        diagnostics: Vec::new(),
-    };
-
-    let control = ExternalSourceControlSnapshotV1::from_catalog(
-        &catalog,
-        ExecutionDomainId::new("local-user").unwrap(),
-        false,
-        ExternalSourceHostCapabilities::read_write(),
-    );
-
-    assert_eq!(control.schema_version, EXTERNAL_SOURCE_CONTROL_SCHEMA_V1);
-    assert_eq!(control.refresh_generation, 7);
-    assert_eq!(control.preference_revision, 11);
-    assert_eq!(control.sources.len(), 1);
-    assert_eq!(
-        control.sources[0].discovery,
-        ExternalSourceDiscoveryState::LastKnownGood
-    );
-    assert_eq!(
-        control.sources[0].desired,
-        ExternalSourceDesiredState::Enabled
-    );
-    assert_eq!(
-        control.sources[0].review,
-        ExternalSourceReviewState::NotRequired
-    );
-    assert_eq!(control.capabilities.len(), 4);
-}
-
-#[test]
-fn control_projection_does_not_infer_review_facts_from_runtime_activation() {
-    let record = source("opencode.mcp", "opencode", "project-config");
-    let definition = ExternalMcpServerDefinition {
-        id: SourceQualifiedMcpServerId::new(record.key.clone(), "docs").unwrap(),
-        provenance: vec![record.key.clone()],
-        name: "docs".to_string(),
-        transport: ExternalMcpTransportKind::StreamableHttp,
-        command_preview: None,
-        argument_count: 0,
-        working_directory: None,
-        environment_keys: Vec::new(),
-        environment_reference_names: Vec::new(),
-        remote_url_preview: Some("https://mcp.example.com".to_string()),
-        header_names: Vec::new(),
-        timeouts: ExternalMcpTimeouts::default(),
-        source_enabled: true,
-        behavior_version: "behavior-v1".to_string(),
-        static_status: ExternalMcpStaticStatus::Ready,
-    };
-    let catalog = ExternalSourceCatalogSnapshot {
-        generation: 1,
-        discovery_pending: false,
-        sources: vec![ExternalSourceCatalogEntry {
-            stable_key: "opencode.mcp:project-config".to_string(),
-            presentation_group_id: None,
-            record: record.clone(),
-            lifecycle: ExternalSourceLifecycleState::Available,
-        }],
-        commands: Vec::new(),
-        command_conflicts: Vec::new(),
-        tools: Vec::new(),
-        tool_approval_requests: Vec::new(),
-        tool_conflicts: Vec::new(),
-        mcp_generation: 1,
-        mcp_servers: vec![ExternalMcpCatalogEntry {
-            candidate_id: "external_mcp:docs".to_string(),
-            definition,
-            approval_key: "approval-v1".to_string(),
-            decision_key: "decision-v1".to_string(),
-            runtime_id: None,
-            activation_state: ExternalMcpActivationState::Declined,
-        }],
-        mcp_approval_requests: Vec::new(),
-        mcp_conflicts: Vec::new(),
-        subagent_generation: 1,
-        preference_revision: 1,
-        subagents: Vec::new(),
-        subagent_model_binding_groups: Vec::new(),
-        subagent_model_binding_options: Vec::new(),
-        subagent_conflicts: Vec::new(),
-        pending_subagent_approvals: Vec::new(),
-        integration_policy: Default::default(),
-        diagnostics: Vec::new(),
-    };
-
-    let control = ExternalSourceControlSnapshotV1::from_catalog(
-        &catalog,
-        ExecutionDomainId::new("local-user").unwrap(),
-        false,
-        ExternalSourceHostCapabilities::read_write(),
-    );
-
-    assert_eq!(
-        control.sources[0].review,
-        ExternalSourceReviewState::NotRequired
-    );
-}
-
-#[test]
-fn desktop_local_host_capability_is_additive_on_the_wire() {
-    let portable = serde_json::to_value(ExternalSourceHostCapabilities::read_write()).unwrap();
-    let read_only =
-        serde_json::to_value(ExternalSourceHostCapabilities::read_only_projection()).unwrap();
-    let desktop = serde_json::to_value(ExternalSourceHostCapabilities::local_desktop()).unwrap();
-
-    assert!(portable.get("canRevealSourceLocation").is_none());
-    assert!(read_only.get("canRevealSourceLocation").is_none());
-    assert_eq!(desktop["canRevealSourceLocation"], true);
-
-    let legacy: ExternalSourceHostCapabilities = serde_json::from_value(serde_json::json!({
-        "canRefresh": true,
-        "canMutatePolicy": true,
-        "canManageSources": true,
-        "canApproveRuntime": true,
-        "canExecuteExternalAssets": true,
-        "canSetSafeMode": true
-    }))
-    .unwrap();
-    assert!(!legacy.can_reveal_source_location);
-}
-
-#[test]
-fn operation_error_round_trip_preserves_typed_recovery_without_message_parsing() {
-    let error = ExternalSourceOperationError::new(
-        ExternalSourceOperationErrorCode::StaleRevision,
-        "refresh required",
-        true,
-    )
-    .with_stage(ExternalSourceOperationStage::ApplyPreference)
-    .with_causation_id("refresh-generation-7")
-    .with_recovery_action(ExternalSourceRecoveryActionV1::Refresh);
-
-    let encoded = error.encode();
-    assert_eq!(ExternalSourceOperationError::decode(&encoded), Some(error));
-    assert!(!encoded.contains("metadata"));
-}
-
-#[test]
-fn control_action_uses_one_camel_case_dto_across_product_surfaces() {
-    let request = ExternalSourceControlRequestV1 {
-        schema_version: EXTERNAL_SOURCE_CONTROL_SCHEMA_V1,
-        operation_id: "surface-operation-1".to_string(),
-        expected_preference_revision: Some(8),
-        action: ExternalSourceControlActionV1::SetSourceEnabled {
-            source_key: "opencode.commands:project".to_string(),
-            enabled: false,
-        },
-    };
-
-    let encoded = serde_json::to_value(&request).expect("serialize control request");
-    assert_eq!(encoded["schemaVersion"], 1);
-    assert_eq!(encoded["operationId"], "surface-operation-1");
-    assert_eq!(encoded["expectedPreferenceRevision"], 8);
-    assert_eq!(encoded["action"]["type"], "set_source_enabled");
-    assert_eq!(encoded["action"]["sourceKey"], "opencode.commands:project");
-    assert!(encoded["action"].get("source_key").is_none());
-    assert_eq!(
-        serde_json::from_value::<ExternalSourceControlRequestV1>(encoded)
-            .expect("deserialize the shared control request"),
-        request
-    );
-}
-
-#[test]
-fn legacy_operation_errors_decode_with_empty_extension_fields() {
-    let decoded = ExternalSourceOperationError::decode(
-        r#"{"code":"unavailable","detail":"retry","retryable":true}"#,
-    )
-    .expect("legacy operation error remains readable");
-
-    assert_eq!(decoded.code, ExternalSourceOperationErrorCode::Unavailable);
-    assert!(decoded.stage.is_none());
-    assert!(decoded.causation_id.is_none());
-    assert!(decoded.recovery_actions.is_empty());
-}
-
-#[test]
-fn decoded_operation_errors_bound_untrusted_extension_fields() {
-    let oversized = "x".repeat(5000);
-    let encoded = serde_json::json!({
-        "code": "stale_revision",
-        "detail": oversized,
-        "retryable": true,
-        "correlationId": "forged\nreference",
-        "recoveryActions": [
-            { "type": "refresh" },
-            { "type": "refresh" },
-            { "type": "retry" }
-        ]
-    })
-    .to_string();
-
-    let decoded = ExternalSourceOperationError::decode(&encoded).unwrap();
-    assert_eq!(decoded.detail.chars().count(), 4096);
-    assert!(decoded.correlation_id.is_none());
-    assert_eq!(
-        decoded.recovery_actions,
-        vec![
-            ExternalSourceRecoveryActionV1::Refresh,
-            ExternalSourceRecoveryActionV1::Retry,
-        ]
-    );
-}
+#![cfg(feature = "external-sources")]
+
+#[path = "external_source_contracts/external_hook_catalog_contracts.rs"]
+mod external_hook_catalog_contracts;
+#[path = "external_source_contracts/external_hook_contribution_contracts.rs"]
+mod external_hook_contribution_contracts;
+#[path = "external_source_contracts/external_source_contracts.rs"]
+mod external_source_contracts;
+#[path = "external_source_contracts/workspace_reference_contracts.rs"]
+mod workspace_reference_contracts;
diff --git a/src/crates/contracts/product-domains/tests/external_hook_catalog_contracts.rs b/src/crates/contracts/product-domains/tests/external_source_contracts/external_hook_catalog_contracts.rs
similarity index 100%
rename from src/crates/contracts/product-domains/tests/external_hook_catalog_contracts.rs
rename to src/crates/contracts/product-domains/tests/external_source_contracts/external_hook_catalog_contracts.rs
diff --git a/src/crates/contracts/product-domains/tests/external_hook_contribution_contracts.rs b/src/crates/contracts/product-domains/tests/external_source_contracts/external_hook_contribution_contracts.rs
similarity index 100%
rename from src/crates/contracts/product-domains/tests/external_hook_contribution_contracts.rs
rename to src/crates/contracts/product-domains/tests/external_source_contracts/external_hook_contribution_contracts.rs
diff --git a/src/crates/contracts/product-domains/tests/external_source_contracts/external_source_contracts.rs b/src/crates/contracts/product-domains/tests/external_source_contracts/external_source_contracts.rs
new file mode 100644
index 0000000000..205c9d0040
--- /dev/null
+++ b/src/crates/contracts/product-domains/tests/external_source_contracts/external_source_contracts.rs
@@ -0,0 +1,2074 @@
+use bitfun_product_domains::external_integration_policy::{
+    evaluate_external_integration_policy, external_integration_policy_snapshot,
+    ExternalEcosystemPolicy, ExternalEcosystemPolicyOverride, ExternalIntegrationAccess,
+    ExternalIntegrationCapabilityDescriptor, ExternalIntegrationEcosystemDescriptor,
+    ExternalIntegrationMode, ExternalIntegrationPolicyDocument, ExternalIntegrationPolicyOverride,
+    ExternalIntegrationPolicyStatus,
+};
+use bitfun_product_domains::external_source_control::{
+    ExternalSourceControlActionV1, ExternalSourceControlRequestV1, ExternalSourceControlSnapshotV1,
+    ExternalSourceDesiredState, ExternalSourceDiscoveryState, ExternalSourceOperationStage,
+    ExternalSourceRecoveryActionV1, ExternalSourceReviewState, EXTERNAL_SOURCE_CONTROL_SCHEMA_V1,
+};
+use bitfun_product_domains::external_sources::{
+    external_mcp_approval_key, external_mcp_conflict_key, external_tool_approval_key,
+    external_tool_conflict_key, prompt_command_conflict_key, EcosystemId, ExecutionDomainId,
+    ExpandedPromptCommand, ExternalIntegrationCapabilityId, ExternalMcpActivationState,
+    ExternalMcpApprovalRequest, ExternalMcpCatalogEntry, ExternalMcpConflict,
+    ExternalMcpConflictCandidate, ExternalMcpDiscoveryInput, ExternalMcpImportApplyRequestV1,
+    ExternalMcpImportSelectionV1, ExternalMcpProviderIdentity, ExternalMcpProviderSnapshot,
+    ExternalMcpRevisionKey, ExternalMcpServerDefinition, ExternalMcpStaticStatus,
+    ExternalMcpTimeouts, ExternalMcpTransportKind, ExternalSourceAssetKind,
+    ExternalSourceCatalogEntry, ExternalSourceCatalogSnapshot, ExternalSourceContext,
+    ExternalSourceDiagnostic, ExternalSourceHealth, ExternalSourceHostCapabilities,
+    ExternalSourceLifecycleState, ExternalSourceOperationError, ExternalSourceOperationErrorCode,
+    ExternalSourceProviderError, ExternalSourcePublicSnapshot, ExternalSourceRecord,
+    ExternalSourceScope, ExternalToolCapability, ExternalToolDefinition, ExternalToolRuntimeKind,
+    ExternalToolStaticStatus, ExternalWatchRoot, NativePromptCommandDescriptor,
+    PreparedExternalMcpImportServer, PreparedExternalMcpImportTransport, PreparedExternalMcpServer,
+    PreparedExternalMcpTransport, PromptCommandAvailability, PromptCommandCatalogEntry,
+    PromptCommandDefinition, PromptCommandExpansion, PromptCommandProviderIdentity,
+    PromptCommandProviderSnapshot, PromptCommandSourceProvider, SecretValue, SourceKey,
+    SourceQualifiedCommandId, SourceQualifiedMcpServerId, SourceQualifiedToolId,
+    SourceQualifiedToolTargetId,
+};
+use bitfun_product_domains::external_subagents::{
+    external_subagent_approval_key, external_subagent_candidate_id, external_subagent_conflict_key,
+    external_subagent_model_binding_key, ExternalSubagentBehaviorVersion,
+    ExternalSubagentCandidateId, ExternalSubagentCompatibilityState,
+    ExternalSubagentContributionId, ExternalSubagentContributionRole, ExternalSubagentDefinition,
+    ExternalSubagentDiscoveryInput, ExternalSubagentLocalId, ExternalSubagentMode,
+    ExternalSubagentModelBindingGroup, ExternalSubagentModelBindingMethod,
+    ExternalSubagentModelBindingOption, ExternalSubagentModelBindingTarget,
+    ExternalSubagentModelProfileRequest, ExternalSubagentModelRequest,
+    ExternalSubagentProvenanceRef, ExternalSubagentProviderIdentity,
+    ExternalSubagentProviderSnapshot, ExternalSubagentToolCapability, ExternalSubagentToolRequest,
+    ExternalSubagentToolSelector, SecretText,
+};
+use bitfun_product_domains::tool_permissions::{
+    PermissionConstraintLayer, PermissionEffect, PermissionRule,
+};
+use sha2::{Digest, Sha256};
+use std::path::PathBuf;
+
+#[test]
+fn native_prompt_command_descriptors_reject_external_candidate_namespaces() {
+    let descriptor = NativePromptCommandDescriptor {
+        command_name: "review".to_string(),
+        candidate_id: "opencode.commands:project:review".to_string(),
+        behavior_version: "v1".to_string(),
+    };
+
+    assert!(descriptor.validate().is_err());
+}
+
+#[test]
+fn external_mcp_import_contract_keeps_private_values_out_of_debug_and_requests() {
+    let source = SourceKey::new("opencode.mcp", "user-config").unwrap();
+    let prepared = PreparedExternalMcpImportServer {
+        id: SourceQualifiedMcpServerId::new(source, "docs").unwrap(),
+        behavior_version: "sha256:behavior-v1".to_string(),
+        transport: PreparedExternalMcpImportTransport::Local {
+            command: "secret-command".to_string(),
+            args: vec!["secret-argument".to_string()],
+        },
+    };
+    let debug = format!("{prepared:?}");
+    assert!(!debug.contains("secret-command"));
+    assert!(!debug.contains("secret-argument"));
+    prepared.validate().unwrap();
+
+    let request = ExternalMcpImportApplyRequestV1 {
+        schema_version: 1,
+        plan_fingerprint: "sha256:plan-v1".to_string(),
+        selections: vec![ExternalMcpImportSelectionV1 {
+            candidate_id: "opencode:mcp:docs".to_string(),
+            requested_native_id: None,
+        }],
+    };
+    request.validate().unwrap();
+    let encoded = serde_json::to_string(&request).unwrap();
+    assert!(!encoded.contains("command"));
+    assert!(!encoded.contains("argument"));
+}
+
+#[test]
+fn external_mcp_import_contract_rejects_urls_that_cannot_be_copied_losslessly() {
+    let prepared = |url: &str| PreparedExternalMcpImportServer {
+        id: SourceQualifiedMcpServerId::new(
+            SourceKey::new("codex.mcp", "user-config").unwrap(),
+            "docs",
+        )
+        .unwrap(),
+        behavior_version: "sha256:behavior-v1".to_string(),
+        transport: PreparedExternalMcpImportTransport::Remote {
+            url: url.to_string(),
+        },
+    };
+
+    prepared("https://docs.example.test/mcp")
+        .validate()
+        .unwrap();
+    for url in [
+        "http://docs.example.test/mcp",
+        "https://user@docs.example.test/mcp",
+        "https://user:secret@docs.example.test/mcp",
+        "https://docs.example.test/mcp?token=secret",
+        "https://docs.example.test/mcp#private",
+    ] {
+        assert!(
+            prepared(url).validate().is_err(),
+            "unexpectedly safe: {url}"
+        );
+    }
+}
+
+fn source(provider_id: &str, ecosystem_id: &str, source_id: &str) -> ExternalSourceRecord {
+    ExternalSourceRecord {
+        key: SourceKey::new(provider_id, source_id).expect("valid source key"),
+        ecosystem_id: EcosystemId::new(ecosystem_id).expect("valid ecosystem id"),
+        display_name: format!("{provider_id} commands"),
+        source_kind: "prompt_commands".to_string(),
+        scope: ExternalSourceScope::Project,
+        location: format!("/workspace/{provider_id}"),
+        execution_domain_id: ExecutionDomainId::new("local-user").expect("valid domain"),
+        health: ExternalSourceHealth::Available,
+        content_version: format!("{provider_id}-v1"),
+        diagnostics: Vec::new(),
+    }
+}
+
+fn command(provider_id: &str, source_id: &str, precedence: i32) -> PromptCommandDefinition {
+    PromptCommandDefinition {
+        id: SourceQualifiedCommandId::new(
+            SourceKey::new(provider_id, source_id).unwrap(),
+            "review",
+        )
+        .unwrap(),
+        name: "review".to_string(),
+        description: format!("Review from {provider_id}"),
+        template: format!("{provider_id}: $ARGUMENTS"),
+        shell_preference: None,
+        execution_target: Default::default(),
+        availability: PromptCommandAvailability::Available,
+        content_version: format!("command-v{precedence}"),
+    }
+}
+
+fn context() -> ExternalSourceContext {
+    ExternalSourceContext {
+        workspace_root: Some(PathBuf::from("/workspace")),
+        execution_domain_id: ExecutionDomainId::new("local-user").unwrap(),
+    }
+}
+
+#[test]
+fn opaque_ids_are_validated_without_closing_the_ecosystem_set() {
+    assert_eq!(
+        EcosystemId::new("future.product/v2")
+            .expect("future ecosystem ids remain open")
+            .as_str(),
+        "future.product/v2"
+    );
+    assert!(EcosystemId::new("  ").is_err());
+    assert!(ExecutionDomainId::new("domain\nwith-control").is_err());
+}
+
+#[test]
+fn source_and_command_identity_remain_provider_qualified() {
+    let left = SourceQualifiedCommandId::new(
+        SourceKey::new("adapter-a", "project-commands").unwrap(),
+        "review",
+    )
+    .unwrap();
+    let right = SourceQualifiedCommandId::new(
+        SourceKey::new("adapter-b", "project-commands").unwrap(),
+        "review",
+    )
+    .unwrap();
+
+    assert_ne!(left, right);
+    assert_ne!(left.stable_key(), right.stable_key());
+}
+
+#[test]
+fn presentation_group_id_is_optional_and_uses_the_camel_case_wire_name() {
+    let mut entry = ExternalSourceCatalogEntry {
+        stable_key: "opencode.commands:project".to_string(),
+        presentation_group_id: None,
+        record: source("opencode.commands", "opencode", "project"),
+        lifecycle: ExternalSourceLifecycleState::Available,
+    };
+
+    let legacy_value = serde_json::to_value(&entry).unwrap();
+    assert!(legacy_value.get("presentationGroupId").is_none());
+    let legacy_entry: ExternalSourceCatalogEntry = serde_json::from_value(legacy_value).unwrap();
+    assert!(legacy_entry.presentation_group_id.is_none());
+
+    entry.presentation_group_id = Some("external-source:[\"source\"]".to_string());
+    let current_value = serde_json::to_value(&entry).unwrap();
+    assert_eq!(
+        current_value["presentationGroupId"],
+        "external-source:[\"source\"]"
+    );
+}
+
+#[test]
+fn conflict_fingerprint_is_order_independent_and_changes_with_content() {
+    let first = prompt_command_conflict_key("local-user", "review", [("a", "v1"), ("b", "v2")]);
+    let reordered = prompt_command_conflict_key("local-user", "REVIEW", [("b", "v2"), ("a", "v1")]);
+    let updated = prompt_command_conflict_key("local-user", "review", [("a", "v1"), ("b", "v3")]);
+    let remote = prompt_command_conflict_key("remote-user", "review", [("a", "v1"), ("b", "v2")]);
+
+    assert_eq!(first, reordered);
+    assert_ne!(first, updated);
+    assert_ne!(first, remote);
+}
+
+#[test]
+fn prompt_commands_use_a_typed_contract_instead_of_an_arbitrary_asset_payload() {
+    let command = PromptCommandDefinition {
+        id: SourceQualifiedCommandId::new(
+            SourceKey::new("example-provider", "project-commands").unwrap(),
+            "review",
+        )
+        .unwrap(),
+        name: "review".to_string(),
+        description: "Review the current change".to_string(),
+        template: "Review $ARGUMENTS".to_string(),
+        shell_preference: None,
+        execution_target: Default::default(),
+        availability: PromptCommandAvailability::Restricted {
+            reason: "Shell expansion is not supported yet".to_string(),
+            required_capabilities: vec!["command.shell".to_string()],
+        },
+        content_version: "sha256:command-v1".to_string(),
+    };
+
+    let encoded = serde_json::to_value(&command).expect("serialize command contract");
+    assert_eq!(encoded["name"], "review");
+    assert_eq!(encoded["availability"]["state"], "restricted");
+    assert!(encoded.get("payload").is_none());
+}
+
+struct FakeProvider {
+    identity: PromptCommandProviderIdentity,
+    snapshot: PromptCommandProviderSnapshot,
+}
+
+impl FakeProvider {
+    fn new(provider_id: &str, ecosystem_id: &str, source_id: &str, precedence: i32) -> Self {
+        let identity = PromptCommandProviderIdentity::new(
+            provider_id,
+            ecosystem_id,
+            format!("{provider_id} display"),
+        )
+        .unwrap();
+        Self {
+            identity: identity.clone(),
+            snapshot: PromptCommandProviderSnapshot {
+                provider: identity,
+                sources: vec![source(provider_id, ecosystem_id, source_id)],
+                commands: vec![command(provider_id, source_id, precedence)],
+                unavailable_command_ids: Vec::new(),
+                diagnostics: Vec::new(),
+            },
+        }
+    }
+}
+
+impl PromptCommandSourceProvider for FakeProvider {
+    fn identity(&self) -> PromptCommandProviderIdentity {
+        self.identity.clone()
+    }
+
+    fn discover(
+        &self,
+        _context: &ExternalSourceContext,
+    ) -> Result<PromptCommandProviderSnapshot, ExternalSourceProviderError> {
+        Ok(self.snapshot.clone())
+    }
+
+    fn expand(
+        &self,
+        _context: &ExternalSourceContext,
+        command: &PromptCommandDefinition,
+        arguments: &str,
+    ) -> Result<PromptCommandExpansion, ExternalSourceProviderError> {
+        Ok(PromptCommandExpansion {
+            content: command.template.replace("$ARGUMENTS", arguments),
+            workspace_file_references: vec!["src/lib.rs".to_string()],
+            shell: None,
+        })
+    }
+
+    fn watch_roots(&self, context: &ExternalSourceContext) -> Vec<ExternalWatchRoot> {
+        vec![ExternalWatchRoot {
+            path: context.workspace_root.clone().unwrap(),
+            recursive: true,
+        }]
+    }
+}
+
+#[test]
+fn capability_provider_contract_does_not_require_core_or_an_ecosystem_enum() {
+    let provider: Box<dyn PromptCommandSourceProvider> = Box::new(FakeProvider::new(
+        "fake-provider",
+        "fake.ecosystem",
+        "project-commands",
+        1,
+    ));
+
+    let snapshot = provider.discover(&context()).expect("discover fake source");
+    assert_eq!(snapshot.provider.ecosystem_id.as_str(), "fake.ecosystem");
+    assert_eq!(provider.watch_roots(&context()).len(), 1);
+    let expansion = provider
+        .expand(&context(), &snapshot.commands[0], "change")
+        .expect("prepare fake command expansion");
+    assert_eq!(expansion.content, "fake-provider: change");
+    assert_eq!(expansion.workspace_file_references, ["src/lib.rs"]);
+
+    let final_result = ExpandedPromptCommand {
+        content: expansion.content,
+    };
+    assert_eq!(
+        serde_json::to_value(final_result).unwrap(),
+        serde_json::json!({"content": "fake-provider: change"})
+    );
+}
+
+#[test]
+fn persisted_source_preference_keys_round_trip_without_path_guessing() {
+    let record = source(
+        "provider.with.dots",
+        "fake.ecosystem",
+        "project/source:agents",
+    );
+    assert_eq!(
+        ExternalSourceRecord::source_key_from_preference_key(&record.preference_key()),
+        Some(record.key)
+    );
+    assert!(ExternalSourceRecord::source_key_from_preference_key("malformed").is_none());
+}
+
+#[test]
+fn external_subagent_identity_preserves_ordered_provenance_and_separate_revisions() {
+    let provider =
+        ExternalSubagentProviderIdentity::new("fake.agents", "fake.ecosystem", "Fake Agents")
+            .unwrap();
+    let first = ExternalSubagentContributionId::new(
+        SourceKey::new("fake.agents", "global-config").unwrap(),
+        ExternalSubagentLocalId::new("review").unwrap(),
+    );
+    let second = ExternalSubagentContributionId::new(
+        SourceKey::new("fake.agents", "project-config").unwrap(),
+        ExternalSubagentLocalId::new("review").unwrap(),
+    );
+    let provenance = vec![
+        ExternalSubagentProvenanceRef {
+            contribution_id: first,
+            role: ExternalSubagentContributionRole::Base,
+        },
+        ExternalSubagentProvenanceRef {
+            contribution_id: second,
+            role: ExternalSubagentContributionRole::Overlay,
+        },
+    ];
+    let candidate_id = external_subagent_candidate_id(&provider.provider_id, "review", &provenance);
+    let reversed = external_subagent_candidate_id(
+        &provider.provider_id,
+        "review",
+        &provenance.iter().cloned().rev().collect::<Vec<_>>(),
+    );
+    assert_ne!(
+        candidate_id, reversed,
+        "provenance order changes behavior identity"
+    );
+
+    let definition = ExternalSubagentDefinition {
+        candidate_id,
+        logical_id: "review".to_string(),
+        provenance,
+        display_name: "Review".to_string(),
+        description: "Reviews a change".to_string(),
+        prompt: SecretText::new("Review carefully"),
+        mode: ExternalSubagentMode::Subagent,
+        disabled: false,
+        hidden: false,
+        requested_model: ExternalSubagentModelRequest::Default,
+        requested_model_profile: None,
+        requested_tools: ExternalSubagentToolRequest {
+            selectors: vec![ExternalSubagentToolSelector {
+                source_name: "read".to_string(),
+                canonical_capability: Some(ExternalSubagentToolCapability::ReadFile),
+                allowed: true,
+            }],
+            uses_conservative_default: false,
+        },
+        permission_constraints: PermissionConstraintLayer::new(vec![PermissionRule::new(
+            "read",
+            "C:/sensitive/private/*",
+            PermissionEffect::Deny,
+        )]),
+        compatibility: ExternalSubagentCompatibilityState::Ready,
+        diagnostic_codes: Vec::new(),
+        behavior_version: ExternalSubagentBehaviorVersion::new("behavior-v1").unwrap(),
+    };
+    assert_eq!(definition.prompt.expose(), "Review carefully");
+    assert!(!format!("{definition:?}").contains("Review carefully"));
+    assert!(!format!("{definition:?}").contains("C:/sensitive/private"));
+
+    let mut invalid_model = definition.clone();
+    invalid_model.requested_model = ExternalSubagentModelRequest::Reference {
+        provider_hint: Some("fake\nprovider".to_string()),
+        model_name: "model".to_string(),
+    };
+    assert!(invalid_model.validate().is_err());
+
+    let mut invalid_tool = definition.clone();
+    invalid_tool.requested_tools.selectors[0].source_name = "read\nsecret".to_string();
+    assert!(invalid_tool.validate().is_err());
+
+    let mut invalid_permission = definition.clone();
+    invalid_permission.permission_constraints =
+        PermissionConstraintLayer::new(vec![PermissionRule::new(
+            "read\nsecret",
+            "*",
+            PermissionEffect::Deny,
+        )]);
+    assert!(invalid_permission.validate().is_err());
+
+    let mut invalid_diagnostic = definition.clone();
+    invalid_diagnostic.diagnostic_codes = vec!["provider.invalid:raw-source-key".to_string()];
+    assert!(invalid_diagnostic.validate().is_err());
+
+    let mut excessive_tools = definition.clone();
+    excessive_tools.requested_tools.selectors = (0..257)
+        .map(|index| ExternalSubagentToolSelector {
+            source_name: format!("tool-{index}"),
+            canonical_capability: None,
+            allowed: true,
+        })
+        .collect();
+    assert!(excessive_tools.validate().is_err());
+
+    let snapshot = ExternalSubagentProviderSnapshot {
+        provider,
+        sources: vec![
+            source("fake.agents", "fake.ecosystem", "global-config"),
+            source("fake.agents", "fake.ecosystem", "project-config"),
+        ],
+        definitions: vec![definition],
+        diagnostics: Vec::new(),
+    };
+    snapshot
+        .validate()
+        .expect("valid external subagent provider snapshot");
+
+    let source_key = snapshot.sources[0].key.clone();
+    let mut valid_diagnostic = snapshot.clone();
+    valid_diagnostic.diagnostics.push(
+        ExternalSourceDiagnostic::warning(
+            "fake.agent.degraded",
+            "An optional field is not supported",
+            Some(source_key),
+        )
+        .with_asset_kind(ExternalSourceAssetKind::Subagent),
+    );
+    valid_diagnostic
+        .validate()
+        .expect("bounded provider diagnostics with a known source are valid");
+
+    let mut valid_source_diagnostic = snapshot.clone();
+    let valid_source_key = valid_source_diagnostic.sources[0].key.clone();
+    valid_source_diagnostic.sources[0].diagnostics.push(
+        ExternalSourceDiagnostic::warning(
+            "fake.agent.source_degraded",
+            "This source has a recoverable warning",
+            Some(valid_source_key),
+        )
+        .with_asset_kind(ExternalSourceAssetKind::Subagent),
+    );
+    valid_source_diagnostic
+        .validate()
+        .expect("source-owned diagnostics use the same provider contract");
+
+    let mut invalid_provider_diagnostic = snapshot.clone();
+    invalid_provider_diagnostic.diagnostics.push(
+        ExternalSourceDiagnostic::warning(
+            "fake.agent:raw-source",
+            "Invalid diagnostic code",
+            Some(SourceKey::new("other.agents", "project").unwrap()),
+        )
+        .with_asset_kind(ExternalSourceAssetKind::Command),
+    );
+    assert!(invalid_provider_diagnostic.validate().is_err());
+
+    let mut wrong_provider_diagnostic = snapshot.clone();
+    wrong_provider_diagnostic.diagnostics.push(
+        ExternalSourceDiagnostic::warning(
+            "fake.agent.invalid_source",
+            "Unknown provider source",
+            Some(SourceKey::new("other.agents", "project").unwrap()),
+        )
+        .with_asset_kind(ExternalSourceAssetKind::Subagent),
+    );
+    assert!(wrong_provider_diagnostic.validate().is_err());
+
+    let mut unknown_source_diagnostic = snapshot.clone();
+    unknown_source_diagnostic.diagnostics.push(
+        ExternalSourceDiagnostic::warning(
+            "fake.agent.unknown_source",
+            "Unknown source",
+            Some(SourceKey::new("fake.agents", "missing").unwrap()),
+        )
+        .with_asset_kind(ExternalSourceAssetKind::Subagent),
+    );
+    assert!(unknown_source_diagnostic.validate().is_err());
+
+    let mut invalid_diagnostic_message = snapshot.clone();
+    invalid_diagnostic_message.diagnostics.push(
+        ExternalSourceDiagnostic::warning("fake.agent.invalid_message", "invalid\nmessage", None)
+            .with_asset_kind(ExternalSourceAssetKind::Subagent),
+    );
+    assert!(invalid_diagnostic_message.validate().is_err());
+
+    let mut wrong_asset_kind = snapshot.clone();
+    wrong_asset_kind.diagnostics.push(
+        ExternalSourceDiagnostic::warning(
+            "fake.agent.wrong_kind",
+            "Diagnostic belongs to another asset kind",
+            None,
+        )
+        .with_asset_kind(ExternalSourceAssetKind::Tool),
+    );
+    assert!(wrong_asset_kind.validate().is_err());
+
+    let mut excessive_sources = snapshot.clone();
+    excessive_sources.sources = vec![snapshot.sources[0].clone(); 1025];
+    assert!(excessive_sources.validate().is_err());
+
+    let mut excessive_definitions = snapshot.clone();
+    excessive_definitions.definitions = vec![snapshot.definitions[0].clone(); 1025];
+    assert!(excessive_definitions.validate().is_err());
+
+    let mut excessive_diagnostics = snapshot.clone();
+    excessive_diagnostics.diagnostics = vec![
+        ExternalSourceDiagnostic::warning(
+            "fake.agent.degraded",
+            "An optional field is not supported",
+            None,
+        )
+        .with_asset_kind(ExternalSourceAssetKind::Subagent);
+        1025
+    ];
+    assert!(excessive_diagnostics.validate().is_err());
+
+    let mut excessive_provenance = snapshot.clone();
+    excessive_provenance.definitions[0].provenance =
+        vec![snapshot.definitions[0].provenance[0].clone(); 257];
+    assert!(excessive_provenance.validate().is_err());
+
+    let input = ExternalSubagentDiscoveryInput {
+        context: context(),
+        suppressed_sources: [SourceKey::new("fake.agents", "suppressed").unwrap()]
+            .into_iter()
+            .collect(),
+    };
+    assert_eq!(input.suppressed_sources.len(), 1);
+}
+
+#[test]
+fn external_subagent_model_contract_preserves_control_and_opaque_reference_semantics() {
+    let requests = [
+        ExternalSubagentModelRequest::Default,
+        ExternalSubagentModelRequest::Inherit,
+        ExternalSubagentModelRequest::Reference {
+            provider_hint: Some("openrouter".to_string()),
+            model_name: "anthropic/claude-sonnet-4".to_string(),
+        },
+        ExternalSubagentModelRequest::Reference {
+            provider_hint: None,
+            model_name: "gpt-5.6-codex".to_string(),
+        },
+        ExternalSubagentModelRequest::Reference {
+            provider_hint: None,
+            model_name: "glm-5".to_string(),
+        },
+        ExternalSubagentModelRequest::Reference {
+            provider_hint: None,
+            model_name: "deepseek-v4".to_string(),
+        },
+        ExternalSubagentModelRequest::Reference {
+            provider_hint: None,
+            model_name: "future-model-that-does-not-exist-yet".to_string(),
+        },
+    ];
+
+    for request in requests {
+        let encoded = serde_json::to_value(&request).unwrap();
+        if let ExternalSubagentModelRequest::Reference {
+            provider_hint,
+            model_name,
+        } = &request
+        {
+            assert_eq!(encoded["modelName"], model_name.as_str());
+            assert!(encoded.get("model_name").is_none());
+            if let Some(provider_hint) = provider_hint {
+                assert_eq!(encoded["providerHint"], provider_hint.as_str());
+                assert!(encoded.get("provider_hint").is_none());
+            }
+        }
+        let decoded: ExternalSubagentModelRequest = serde_json::from_value(encoded).unwrap();
+        assert_eq!(decoded, request);
+    }
+
+    assert_ne!(
+        ExternalSubagentModelRequest::Inherit,
+        ExternalSubagentModelRequest::Reference {
+            provider_hint: None,
+            model_name: "inherit".to_string(),
+        }
+    );
+}
+
+#[test]
+fn external_subagent_model_profile_contract_keeps_variant_and_effort_semantics_distinct() {
+    let profiles = [
+        ExternalSubagentModelProfileRequest::NamedVariant {
+            name: "high".to_string(),
+        },
+        ExternalSubagentModelProfileRequest::ReasoningEffort {
+            value: "high".to_string(),
+        },
+    ];
+
+    let encoded = profiles
+        .iter()
+        .map(|profile| serde_json::to_value(profile).unwrap())
+        .collect::<Vec<_>>();
+    assert_eq!(
+        encoded[0],
+        serde_json::json!({ "kind": "named_variant", "name": "high" })
+    );
+    assert_eq!(
+        encoded[1],
+        serde_json::json!({ "kind": "reasoning_effort", "value": "high" })
+    );
+    assert_ne!(profiles[0], profiles[1]);
+
+    for (profile, encoded) in profiles.into_iter().zip(encoded) {
+        let decoded: ExternalSubagentModelProfileRequest = serde_json::from_value(encoded).unwrap();
+        assert_eq!(decoded, profile);
+    }
+
+    assert!(ExternalSubagentModelProfileRequest::NamedVariant {
+        name: "x".repeat(4097),
+    }
+    .validate()
+    .is_err());
+    assert!(ExternalSubagentModelProfileRequest::ReasoningEffort {
+        value: "bad\u{0001}".to_string(),
+    }
+    .validate()
+    .is_err());
+}
+
+#[test]
+fn external_subagent_model_binding_contract_groups_only_matching_scope_identity() {
+    let ecosystem = EcosystemId::new("opencode").unwrap();
+    let request = ExternalSubagentModelRequest::Reference {
+        provider_hint: Some("openrouter".to_string()),
+        model_name: "vendor/model".to_string(),
+    };
+    let global_a = external_subagent_model_binding_key(
+        &ecosystem,
+        &request,
+        None,
+        "local-user",
+        ExternalSourceScope::UserGlobal,
+        "D:/workspace/a",
+    )
+    .unwrap();
+    assert_eq!(
+        global_a,
+        "external_subagent_model_binding:408ebedb7c2644acda3b4c0c5a78e8eb83fb2ece8b3a1671a866ed0d6cc08f56",
+        "profile-free bindings must retain their pre-profile persisted identity"
+    );
+    let global_b = external_subagent_model_binding_key(
+        &ecosystem,
+        &request,
+        None,
+        "local-user",
+        ExternalSourceScope::UserGlobal,
+        "D:/workspace/b",
+    )
+    .unwrap();
+    assert_eq!(
+        global_a, global_b,
+        "user bindings belong to the execution domain"
+    );
+
+    let project_a = external_subagent_model_binding_key(
+        &ecosystem,
+        &request,
+        None,
+        "local-user",
+        ExternalSourceScope::Project,
+        "D:/workspace/a",
+    )
+    .unwrap();
+    let project_b = external_subagent_model_binding_key(
+        &ecosystem,
+        &request,
+        None,
+        "local-user",
+        ExternalSourceScope::Project,
+        "D:/workspace/b",
+    )
+    .unwrap();
+    assert_ne!(
+        project_a, project_b,
+        "project bindings stay workspace-scoped"
+    );
+    assert_ne!(
+        global_a, project_a,
+        "global and project bindings never alias"
+    );
+    let remote_global = external_subagent_model_binding_key(
+        &ecosystem,
+        &request,
+        None,
+        "remote:user@example",
+        ExternalSourceScope::RemoteUser,
+        "D:/workspace/a",
+    )
+    .unwrap();
+    assert_ne!(
+        global_a, remote_global,
+        "remote and local execution domains never share bindings"
+    );
+
+    let option = ExternalSubagentModelBindingOption {
+        target: ExternalSubagentModelBindingTarget::Primary,
+        effective_model_label: "Provider / Model".to_string(),
+        configured_reasoning_effort: Some("high".to_string()),
+    };
+    let group = ExternalSubagentModelBindingGroup {
+        binding_key: project_a,
+        request,
+        profile_request: Some(ExternalSubagentModelProfileRequest::ReasoningEffort {
+            value: "high".to_string(),
+        }),
+        scope: ExternalSourceScope::Project,
+        method: ExternalSubagentModelBindingMethod::Explicit,
+        selected_target: Some(option.target.clone()),
+        effective_model_label: Some(option.effective_model_label.clone()),
+        affected_candidate_ids: vec!["candidate-a".to_string(), "candidate-b".to_string()],
+    };
+    let encoded = serde_json::to_value((&option, &group)).unwrap();
+    let decoded: (
+        ExternalSubagentModelBindingOption,
+        ExternalSubagentModelBindingGroup,
+    ) = serde_json::from_value(encoded).unwrap();
+    assert_eq!(decoded, (option, group));
+}
+
+#[test]
+fn external_subagent_profile_binding_identity_extends_existing_model_binding_scope() {
+    let ecosystem = EcosystemId::new("opencode").unwrap();
+    let default_request = ExternalSubagentModelRequest::Default;
+    assert!(external_subagent_model_binding_key(
+        &ecosystem,
+        &default_request,
+        None,
+        "local-user",
+        ExternalSourceScope::Project,
+        "D:/workspace/a",
+    )
+    .is_none());
+
+    let variant = ExternalSubagentModelProfileRequest::NamedVariant {
+        name: "high".to_string(),
+    };
+    let effort = ExternalSubagentModelProfileRequest::ReasoningEffort {
+        value: "high".to_string(),
+    };
+    let variant_key = external_subagent_model_binding_key(
+        &ecosystem,
+        &default_request,
+        Some(&variant),
+        "local-user",
+        ExternalSourceScope::Project,
+        "D:/workspace/a",
+    )
+    .unwrap();
+    let effort_key = external_subagent_model_binding_key(
+        &ecosystem,
+        &default_request,
+        Some(&effort),
+        "local-user",
+        ExternalSourceScope::Project,
+        "D:/workspace/a",
+    )
+    .unwrap();
+    assert_ne!(variant_key, effort_key);
+    let delimited_provider = ExternalSubagentModelRequest::Reference {
+        provider_hint: Some("a:b".to_string()),
+        model_name: "c".to_string(),
+    };
+    let delimited_model = ExternalSubagentModelRequest::Reference {
+        provider_hint: Some("a".to_string()),
+        model_name: "b:c".to_string(),
+    };
+    let key_for = |request| {
+        external_subagent_model_binding_key(
+            &ecosystem,
+            request,
+            Some(&effort),
+            "local-user",
+            ExternalSourceScope::Project,
+            "D:/workspace/a",
+        )
+        .unwrap()
+    };
+    assert_ne!(key_for(&delimited_provider), key_for(&delimited_model));
+}
+
+#[test]
+fn external_subagent_decision_keys_bind_behavior_but_not_catalog_copy() {
+    let candidate = ExternalSubagentCandidateId::new("candidate-v1").unwrap();
+    let behavior = ExternalSubagentBehaviorVersion::new("behavior-v1").unwrap();
+    let approval = external_subagent_approval_key(&candidate, &behavior, "envelope-v1");
+    let same = external_subagent_approval_key(&candidate, &behavior, "envelope-v1");
+    let changed = external_subagent_approval_key(
+        &candidate,
+        &ExternalSubagentBehaviorVersion::new("behavior-v2").unwrap(),
+        "envelope-v1",
+    );
+    assert_eq!(approval, same);
+    assert_ne!(approval, changed);
+
+    let first = external_subagent_conflict_key(
+        "local-user",
+        "/workspace",
+        "review",
+        [("local", "v1"), (candidate.as_str(), behavior.as_str())],
+    );
+    let reordered = external_subagent_conflict_key(
+        "local-user",
+        "/workspace",
+        "REVIEW",
+        [(candidate.as_str(), behavior.as_str()), ("local", "v1")],
+    );
+    assert_eq!(first, reordered);
+}
+
+#[test]
+fn diagnostics_remain_source_qualified() {
+    let diagnostic = ExternalSourceDiagnostic::warning(
+        "fake.warning",
+        "A non-blocking fake diagnostic",
+        Some(SourceKey::new("fake", "source").unwrap()),
+    );
+    assert_eq!(diagnostic.source.unwrap().provider_id.as_str(), "fake");
+}
+
+#[test]
+fn provider_snapshot_rejects_duplicate_sources_and_commands() {
+    let provider = FakeProvider::new("fake", "fake.ecosystem", "project", 1);
+    let mut duplicate_source = provider.snapshot.clone();
+    duplicate_source
+        .sources
+        .push(duplicate_source.sources[0].clone());
+    assert!(duplicate_source.validate().is_err());
+
+    let mut duplicate_command = provider.snapshot;
+    duplicate_command
+        .commands
+        .push(duplicate_command.commands[0].clone());
+    assert!(duplicate_command.validate().is_err());
+}
+
+#[test]
+fn unavailable_command_must_be_unique_absent_and_source_qualified() {
+    let provider = FakeProvider::new("fake", "fake.ecosystem", "project", 1);
+    let mut invalid = provider.snapshot;
+    invalid
+        .unavailable_command_ids
+        .push(invalid.commands[0].id.clone());
+    assert!(invalid.validate().is_err());
+}
+
+#[test]
+fn standalone_tool_contract_separates_static_preview_from_executable_source() {
+    let target = SourceQualifiedToolTargetId::new(
+        SourceKey::new("opencode.tools", "project-tools").unwrap(),
+        "weather.js",
+    )
+    .unwrap();
+    let tool = ExternalToolDefinition {
+        id: SourceQualifiedToolId::new(target, "default").unwrap(),
+        name: "weather".to_string(),
+        description_preview: "Get the weather for a location".to_string(),
+        module_path: "/workspace/.opencode/tools/weather.js".to_string(),
+        working_directory: "/workspace".to_string(),
+        runtime_kind: ExternalToolRuntimeKind::JavaScript,
+        capabilities: vec![
+            ExternalToolCapability::FileSystem,
+            ExternalToolCapability::Network,
+            ExternalToolCapability::Process,
+        ],
+        content_version: "sha256:v1".to_string(),
+        static_status: ExternalToolStaticStatus::Ready,
+    };
+
+    let encoded = serde_json::to_value(&tool).expect("serialize tool preview");
+    assert_eq!(encoded["name"], "weather");
+    assert_eq!(encoded["runtimeKind"], "java_script");
+    assert!(encoded.get("moduleSource").is_none());
+    assert!(encoded.get("payload").is_none());
+    tool.validate().expect("valid standalone tool preview");
+}
+
+#[test]
+fn legacy_public_snapshot_downprojects_new_tool_review_variants() {
+    let snapshot: ExternalSourcePublicSnapshot = serde_json::from_value(serde_json::json!({
+        "generation": 1,
+        "discoveryPending": false,
+        "sources": [],
+        "commands": [{
+            "candidateId": "17:opencode.commands6:global6:review",
+            "definition": {
+                "id": {
+                    "source": { "providerId": "opencode.commands", "sourceId": "global" },
+                    "localId": "review"
+                },
+                "name": "review",
+                "description": "Review changes",
+                "availability": { "state": "available" },
+                "contentVersion": "v1"
+            }
+        }],
+        "tools": [{
+            "definition": {
+                "id": {
+                    "target": {
+                        "source": { "providerId": "opencode.tools", "sourceId": "project" },
+                        "localId": "weather.js"
+                    },
+                    "exportId": "default"
+                },
+                "name": "weather",
+                "descriptionPreview": "Get weather",
+                "modulePath": "<workspace>/.opencode/tools/weather.js",
+                "workingDirectory": "<workspace>",
+                "runtimeKind": "java_script",
+                "capabilities": [],
+                "contentVersion": "sha256:v1",
+                "staticStatus": { "state": "ready" }
+            },
+            "approvalKey": "approval-v1",
+            "decisionKey": "decision-v1",
+            "activation": { "state": "declined" }
+        }],
+        "subagents": [{
+            "candidateId": "external-review",
+            "logicalId": "review",
+            "displayName": "External Review",
+            "description": "Review changes",
+            "providerLabel": "OpenCode",
+            "scope": "project",
+            "sourceKeys": [],
+            "sourceLocationLabels": [],
+            "sourceCount": 1,
+            "requestedModel": {
+                "kind": "reference",
+                "providerHint": "anthropic",
+                "modelName": "claude-sonnet-4"
+            },
+            "requestedModelProfile": {
+                "kind": "reasoning_effort",
+                "value": "high"
+            },
+            "modelBindingMethod": "binding_required",
+            "modelBindingKey": "external_subagent_model_binding:review",
+            "effectiveToolLabels": ["Read"],
+            "unavailableToolLabels": ["Shell"],
+            "supportsFollowUp": false,
+            "compatibilityState": "blocked",
+            "diagnostics": [{
+                "code": "external_subagent.tool_unavailable",
+                "blocksActivation": true
+            }],
+            "activationState": { "state": "blocked" },
+            "decisionKey": "agent-decision-v1"
+        }],
+        "subagentModelBindingGroups": [{
+            "bindingKey": "external_subagent_model_binding:review",
+            "request": { "kind": "reference", "modelName": "claude-sonnet-4" },
+            "profileRequest": { "kind": "reasoning_effort", "value": "high" },
+            "scope": "project",
+            "method": "binding_required",
+            "affectedCandidateIds": ["external-review"]
+        }],
+        "subagentModelBindingOptions": [{
+            "target": { "kind": "fast" },
+            "effectiveModelLabel": "Fast",
+            "configuredReasoningEffort": "high"
+        }]
+    }))
+    .expect("new public snapshot");
+
+    let legacy =
+        serde_json::to_value(snapshot.into_legacy_v0_compatible()).expect("legacy public snapshot");
+    assert!(legacy["commands"][0].get("candidateId").is_none());
+    assert_eq!(legacy["tools"][0]["activation"]["state"], "disabled");
+    assert!(legacy["subagents"][0]
+        .get("unavailableToolLabels")
+        .is_none());
+    assert!(legacy["subagents"][0].get("requestedModel").is_none());
+    assert!(legacy["subagents"][0]
+        .get("requestedModelProfile")
+        .is_none());
+    assert!(legacy["subagents"][0].get("modelBindingMethod").is_none());
+    assert!(legacy["subagents"][0].get("modelBindingKey").is_none());
+    assert!(legacy.get("subagentModelBindingGroups").is_none());
+    assert!(legacy.get("subagentModelBindingOptions").is_none());
+}
+
+#[test]
+fn standalone_tool_contract_rejects_names_that_are_not_model_callable() {
+    let target = SourceQualifiedToolTargetId::new(
+        SourceKey::new("fake.tools", "project-tools").unwrap(),
+        "unsafe.js",
+    )
+    .unwrap();
+    let mut tool = ExternalToolDefinition {
+        id: SourceQualifiedToolId::new(target, "default").unwrap(),
+        name: "unsafe tool".to_string(),
+        description_preview: String::new(),
+        module_path: "/workspace/unsafe.js".to_string(),
+        working_directory: "/workspace".to_string(),
+        runtime_kind: ExternalToolRuntimeKind::JavaScript,
+        capabilities: vec![ExternalToolCapability::FileSystem],
+        content_version: "sha256:v1".to_string(),
+        static_status: ExternalToolStaticStatus::Ready,
+    };
+
+    assert!(tool.validate().is_err());
+    tool.name = "safe_tool-1".to_string();
+    tool.validate()
+        .expect("portable tool name should be accepted");
+}
+
+#[test]
+fn tool_approval_is_stable_for_safe_updates_but_changes_with_capabilities_or_domain() {
+    let target = SourceQualifiedToolTargetId::new(
+        SourceKey::new("opencode.tools", "project-tools").unwrap(),
+        "weather.js",
+    )
+    .unwrap();
+    let first = external_tool_approval_key(
+        "local-user",
+        &target,
+        ExternalToolRuntimeKind::JavaScript,
+        [
+            ExternalToolCapability::FileSystem,
+            ExternalToolCapability::Network,
+        ],
+    );
+    let reordered = external_tool_approval_key(
+        "local-user",
+        &target,
+        ExternalToolRuntimeKind::JavaScript,
+        [
+            ExternalToolCapability::Network,
+            ExternalToolCapability::FileSystem,
+        ],
+    );
+    let expanded = external_tool_approval_key(
+        "local-user",
+        &target,
+        ExternalToolRuntimeKind::JavaScript,
+        [
+            ExternalToolCapability::FileSystem,
+            ExternalToolCapability::Network,
+            ExternalToolCapability::Process,
+        ],
+    );
+    let remote = external_tool_approval_key(
+        "remote-user",
+        &target,
+        ExternalToolRuntimeKind::JavaScript,
+        [
+            ExternalToolCapability::FileSystem,
+            ExternalToolCapability::Network,
+        ],
+    );
+
+    assert_eq!(first, reordered);
+    assert_ne!(first, expanded);
+    assert_ne!(first, remote);
+}
+
+#[test]
+fn tool_conflict_choice_is_invalidated_when_name_or_candidate_changes() {
+    let first = external_tool_conflict_key(
+        "local-user",
+        "weather",
+        [
+            ("builtin:weather", "builtin-v1"),
+            ("opencode:weather", "tool-v1"),
+        ],
+    );
+    let reordered = external_tool_conflict_key(
+        "local-user",
+        "WEATHER",
+        [
+            ("opencode:weather", "tool-v1"),
+            ("builtin:weather", "builtin-v1"),
+        ],
+    );
+    let updated = external_tool_conflict_key(
+        "local-user",
+        "weather",
+        [
+            ("builtin:weather", "builtin-v1"),
+            ("opencode:weather", "tool-v2"),
+        ],
+    );
+
+    assert_ne!(first, reordered);
+    assert_ne!(first, updated);
+}
+
+#[test]
+fn external_mcp_contract_keeps_runtime_secrets_out_of_static_snapshots() {
+    let source = source("opencode.mcp", "opencode", "project-config");
+    let definition = ExternalMcpServerDefinition {
+        id: SourceQualifiedMcpServerId::new(source.key.clone(), "github").unwrap(),
+        provenance: vec![source.key.clone()],
+        name: "github".to_string(),
+        transport: ExternalMcpTransportKind::StreamableHttp,
+        command_preview: None,
+        argument_count: 0,
+        working_directory: None,
+        environment_keys: Vec::new(),
+        environment_reference_names: Vec::new(),
+        remote_url_preview: Some("https://mcp.example.com/mcp".to_string()),
+        header_names: vec!["Authorization".to_string()],
+        timeouts: ExternalMcpTimeouts::default(),
+        source_enabled: true,
+        behavior_version: "sha256:behavior-v1".to_string(),
+        static_status: ExternalMcpStaticStatus::Ready,
+    };
+    let provider =
+        ExternalMcpProviderIdentity::new("opencode.mcp", "opencode", "OpenCode MCP servers")
+            .unwrap();
+    let snapshot = ExternalMcpProviderSnapshot {
+        provider,
+        sources: vec![source],
+        servers: vec![definition.clone()],
+        diagnostics: Vec::new(),
+    };
+
+    snapshot.validate().expect("valid MCP provider snapshot");
+    let encoded = serde_json::to_string(&snapshot).expect("serialize MCP snapshot");
+    assert!(encoded.contains("Authorization"));
+    assert!(!encoded.contains("Bearer secret"));
+    assert!(encoded.contains("mcp.example.com"));
+
+    let prepared = PreparedExternalMcpServer {
+        id: definition.id,
+        behavior_version: definition.behavior_version,
+        timeouts: ExternalMcpTimeouts::default(),
+        transport: PreparedExternalMcpTransport::Remote {
+            url: "https://mcp.example.com/mcp?token=url-secret".to_string(),
+            headers: [(
+                "Authorization".to_string(),
+                SecretValue::new("Bearer secret"),
+            )]
+            .into_iter()
+            .collect(),
+            oauth_enabled: true,
+        },
+    };
+    assert_eq!(
+        prepared.transport.remote_headers().unwrap()["Authorization"].expose(),
+        "Bearer secret"
+    );
+    assert!(!format!("{prepared:?}").contains("Bearer secret"));
+    assert!(!format!("{prepared:?}").contains("url-secret"));
+}
+
+#[test]
+fn external_mcp_timeouts_are_positive_optional_millisecond_facts() {
+    let timeouts = ExternalMcpTimeouts {
+        startup_ms: Some(2_000),
+        catalog_ms: None,
+        execution_ms: Some(30_000),
+    };
+
+    timeouts.validate().expect("positive timeouts are valid");
+    assert_eq!(
+        serde_json::to_value(&timeouts).unwrap(),
+        serde_json::json!({
+            "startupMs": 2_000,
+            "executionMs": 30_000,
+        })
+    );
+    assert!(ExternalMcpTimeouts {
+        startup_ms: Some(0),
+        ..Default::default()
+    }
+    .validate()
+    .is_err());
+    assert!(ExternalMcpTimeouts {
+        execution_ms: Some(9_007_199_254_740_991),
+        ..Default::default()
+    }
+    .validate()
+    .is_ok());
+    assert!(ExternalMcpTimeouts {
+        execution_ms: Some(9_007_199_254_740_992),
+        ..Default::default()
+    }
+    .validate()
+    .is_err());
+    assert!(ExternalMcpTimeouts::default().is_empty());
+}
+
+#[test]
+fn external_mcp_revision_key_never_exposes_material_through_debug_output() {
+    let key = ExternalMcpRevisionKey::new([0x5a; 32]);
+    assert_eq!(format!("{key:?}"), "ExternalMcpRevisionKey([REDACTED])");
+    assert!(!format!("{key:?}").contains("5a"));
+}
+
+#[test]
+fn external_mcp_revision_is_stable_secret_sensitive_and_not_an_unkeyed_oracle() {
+    let key = ExternalMcpRevisionKey::new([7; 32]);
+    let first = key.opaque_revision(
+        "test.mcp.behavior.v1",
+        [b"server".as_slice(), b"PIN=0007".as_slice()],
+    );
+    let repeated = key.opaque_revision(
+        "test.mcp.behavior.v1",
+        [b"server".as_slice(), b"PIN=0007".as_slice()],
+    );
+    let changed = key.opaque_revision(
+        "test.mcp.behavior.v1",
+        [b"server".as_slice(), b"PIN=0008".as_slice()],
+    );
+    let raw_candidate = format!(
+        "sha256:{}",
+        hex::encode(Sha256::digest(b"server\0PIN=0007"))
+    );
+
+    assert_eq!(first, repeated);
+    assert_ne!(first, changed);
+    assert_ne!(first, raw_candidate);
+    assert!(first.starts_with("hmac-sha256:"));
+}
+
+#[test]
+fn external_mcp_snapshot_rejects_cross_provider_and_duplicate_servers() {
+    let provider =
+        ExternalMcpProviderIdentity::new("opencode.mcp", "opencode", "OpenCode MCP").unwrap();
+    let source = source("opencode.mcp", "opencode", "project-config");
+    let definition = ExternalMcpServerDefinition {
+        id: SourceQualifiedMcpServerId::new(source.key.clone(), "github").unwrap(),
+        provenance: vec![source.key.clone()],
+        name: "github".to_string(),
+        transport: ExternalMcpTransportKind::LocalStdio,
+        command_preview: Some("npx".to_string()),
+        argument_count: 2,
+        working_directory: Some("/workspace".to_string()),
+        environment_keys: vec!["GITHUB_TOKEN".to_string()],
+        environment_reference_names: Vec::new(),
+        remote_url_preview: None,
+        header_names: Vec::new(),
+        timeouts: ExternalMcpTimeouts::default(),
+        source_enabled: true,
+        behavior_version: "sha256:behavior-v1".to_string(),
+        static_status: ExternalMcpStaticStatus::Ready,
+    };
+    let snapshot = ExternalMcpProviderSnapshot {
+        provider,
+        sources: vec![source],
+        servers: vec![definition.clone(), definition],
+        diagnostics: Vec::new(),
+    };
+
+    assert!(snapshot.validate().is_err());
+
+    let input = ExternalMcpDiscoveryInput {
+        context: context(),
+        suppressed_sources: [SourceKey::new("opencode.mcp", "suppressed").unwrap()]
+            .into_iter()
+            .collect(),
+        revision_key: ExternalMcpRevisionKey::new([7; 32]),
+    };
+    assert_eq!(input.suppressed_sources.len(), 1);
+}
+
+#[test]
+fn external_mcp_decisions_change_only_with_behavior_domain_or_conflict_participants() {
+    let id = SourceQualifiedMcpServerId::new(
+        SourceKey::new("opencode.mcp", "project-config").unwrap(),
+        "github",
+    )
+    .unwrap();
+    let first = external_mcp_approval_key("local-user", "/workspace-a", &id, "behavior-v1");
+    let same = external_mcp_approval_key("local-user", "/workspace-a", &id, "behavior-v1");
+    let updated = external_mcp_approval_key("local-user", "/workspace-a", &id, "behavior-v2");
+    let other_workspace =
+        external_mcp_approval_key("local-user", "/workspace-b", &id, "behavior-v1");
+    let remote = external_mcp_approval_key("remote-user", "/workspace-a", &id, "behavior-v1");
+    assert_eq!(first, same);
+    assert_ne!(first, updated);
+    assert_ne!(first, other_workspace);
+    assert_ne!(first, remote);
+
+    let stable_id = id.stable_key();
+    let conflict = external_mcp_conflict_key(
+        "local-user",
+        "/workspace-a",
+        "github",
+        [
+            ("bitfun:github", "native-v1"),
+            (stable_id.as_str(), "behavior-v1"),
+        ],
+    );
+    let reordered = external_mcp_conflict_key(
+        "local-user",
+        "/workspace-a",
+        "GITHUB",
+        [
+            (stable_id.as_str(), "behavior-v1"),
+            ("bitfun:github", "native-v1"),
+        ],
+    );
+    let participant_updated = external_mcp_conflict_key(
+        "local-user",
+        "/workspace-a",
+        "github",
+        [
+            ("bitfun:github", "native-v1"),
+            (stable_id.as_str(), "behavior-v2"),
+        ],
+    );
+    assert_eq!(conflict, reordered);
+    assert_ne!(conflict, participant_updated);
+    assert_ne!(
+        conflict,
+        external_mcp_conflict_key(
+            "local-user",
+            "/workspace-b",
+            "github",
+            [
+                ("bitfun:github", "native-v1"),
+                (stable_id.as_str(), "behavior-v1"),
+            ],
+        )
+    );
+}
+
+#[test]
+fn external_mcp_product_view_is_version_guarded_and_contains_only_disclosed_fields() {
+    let source = source("opencode.mcp", "opencode", "project-config");
+    let definition = ExternalMcpServerDefinition {
+        id: SourceQualifiedMcpServerId::new(source.key.clone(), "github").unwrap(),
+        provenance: vec![source.key],
+        name: "github".to_string(),
+        transport: ExternalMcpTransportKind::LocalStdio,
+        command_preview: Some("npx".to_string()),
+        argument_count: 2,
+        working_directory: Some("<workspace>".to_string()),
+        environment_keys: vec!["GITHUB_TOKEN".to_string()],
+        environment_reference_names: Vec::new(),
+        remote_url_preview: None,
+        header_names: Vec::new(),
+        timeouts: ExternalMcpTimeouts::default(),
+        source_enabled: true,
+        behavior_version: "sha256:behavior-v1".to_string(),
+        static_status: ExternalMcpStaticStatus::Ready,
+    };
+    let entry = ExternalMcpCatalogEntry {
+        candidate_id: definition.candidate_id(),
+        definition: definition.clone(),
+        approval_key: "external_mcp_approval:local-user:v1".to_string(),
+        decision_key: "external_mcp_approval:local-user:v1".to_string(),
+        runtime_id: None,
+        activation_state: ExternalMcpActivationState::ApprovalRequired,
+    };
+    let request = ExternalMcpApprovalRequest {
+        candidate_id: entry.candidate_id.clone(),
+        approval_key: entry.approval_key.clone(),
+        decision_key: entry.decision_key.clone(),
+        definition,
+    };
+    let conflict = ExternalMcpConflict {
+        conflict_key: "external_mcp:local-user:github:v1".to_string(),
+        server_name: "github".to_string(),
+        candidates: vec![
+            ExternalMcpConflictCandidate {
+                candidate_id: "native_mcp:github".to_string(),
+                display_name: "BitFun: github".to_string(),
+                external: false,
+                source: None,
+                behavior_version: "native-v1".to_string(),
+                available: true,
+                unavailable_reason: None,
+            },
+            ExternalMcpConflictCandidate {
+                candidate_id: entry.candidate_id.clone(),
+                display_name: "OpenCode: github".to_string(),
+                external: true,
+                source: Some(entry.definition.id.source.clone()),
+                behavior_version: entry.definition.behavior_version.clone(),
+                available: true,
+                unavailable_reason: None,
+            },
+        ],
+        selected_candidate_id: None,
+    };
+
+    let encoded = serde_json::to_string(&(entry, request, conflict)).unwrap();
+    assert!(encoded.contains("GITHUB_TOKEN"));
+    assert!(!encoded.contains("Bearer secret"));
+    assert!(encoded.contains("approval_required"));
+}
+
+fn external_capability(value: &str) -> ExternalIntegrationCapabilityId {
+    ExternalIntegrationCapabilityId::new(value).expect("valid external capability id")
+}
+
+const TEST_ECOSYSTEM_ID: &str = "test-ecosystem";
+const EXTERNAL_CAPABILITY_COMMAND: &str = "command";
+const EXTERNAL_CAPABILITY_TOOL: &str = "tool";
+const EXTERNAL_CAPABILITY_SUBAGENT: &str = "subagent";
+const EXTERNAL_CAPABILITY_MCP: &str = "mcp";
+
+fn test_external_integration_ecosystems() -> Vec<ExternalIntegrationEcosystemDescriptor> {
+    let capability =
+        |id, recommended_access, safety_ceiling| ExternalIntegrationCapabilityDescriptor {
+            capability_id: external_capability(id),
+            recommended_access,
+            safety_ceiling,
+        };
+    vec![ExternalIntegrationEcosystemDescriptor {
+        ecosystem_id: EcosystemId::new(TEST_ECOSYSTEM_ID).unwrap(),
+        display_name: "Test ecosystem".to_string(),
+        adapter_revision: "1".to_string(),
+        capabilities: vec![
+            capability(
+                EXTERNAL_CAPABILITY_COMMAND,
+                ExternalIntegrationAccess::Auto,
+                ExternalIntegrationAccess::Auto,
+            ),
+            capability(
+                EXTERNAL_CAPABILITY_TOOL,
+                ExternalIntegrationAccess::AskBeforeUse,
+                ExternalIntegrationAccess::AskBeforeUse,
+            ),
+            capability(
+                EXTERNAL_CAPABILITY_SUBAGENT,
+                ExternalIntegrationAccess::AskBeforeUse,
+                ExternalIntegrationAccess::AskBeforeUse,
+            ),
+            capability(
+                EXTERNAL_CAPABILITY_MCP,
+                ExternalIntegrationAccess::AskBeforeUse,
+                ExternalIntegrationAccess::AskBeforeUse,
+            ),
+        ],
+    }]
+}
+
+#[test]
+fn external_integration_policy_is_disabled_by_default() {
+    let effective = evaluate_external_integration_policy(
+        &ExternalIntegrationPolicyDocument::default(),
+        Some("workspace-a"),
+        &test_external_integration_ecosystems(),
+    )
+    .expect("default policy evaluates");
+    let opencode = effective
+        .ecosystems
+        .get(&EcosystemId::new(TEST_ECOSYSTEM_ID).unwrap())
+        .expect("test ecosystem is registered");
+
+    assert!(!effective.enabled);
+    assert_eq!(opencode.mode, ExternalIntegrationMode::Disabled);
+    for capability in [
+        EXTERNAL_CAPABILITY_COMMAND,
+        EXTERNAL_CAPABILITY_TOOL,
+        EXTERNAL_CAPABILITY_SUBAGENT,
+        EXTERNAL_CAPABILITY_MCP,
+    ] {
+        assert_eq!(
+            opencode.capabilities[&external_capability(capability)],
+            ExternalIntegrationAccess::Disabled
+        );
+    }
+}
+
+#[test]
+fn explicitly_enabled_recommended_policy_keeps_registered_access_defaults() {
+    let mut document = ExternalIntegrationPolicyDocument::default();
+    document.user_defaults.enabled = true;
+
+    let effective = evaluate_external_integration_policy(
+        &document,
+        Some("workspace-a"),
+        &test_external_integration_ecosystems(),
+    )
+    .expect("enabled recommended policy evaluates");
+    let opencode = effective
+        .ecosystems
+        .get(&EcosystemId::new(TEST_ECOSYSTEM_ID).unwrap())
+        .expect("test ecosystem is registered");
+
+    assert!(effective.enabled);
+    assert_eq!(opencode.mode, ExternalIntegrationMode::Recommended);
+    assert_eq!(
+        opencode.capabilities[&external_capability(EXTERNAL_CAPABILITY_COMMAND)],
+        ExternalIntegrationAccess::Auto
+    );
+    for capability in [
+        EXTERNAL_CAPABILITY_TOOL,
+        EXTERNAL_CAPABILITY_SUBAGENT,
+        EXTERNAL_CAPABILITY_MCP,
+    ] {
+        assert_eq!(
+            opencode.capabilities[&external_capability(capability)],
+            ExternalIntegrationAccess::AskBeforeUse
+        );
+    }
+}
+
+#[test]
+fn workspace_policy_overrides_only_the_fields_the_user_changed() {
+    let ecosystem = EcosystemId::new(TEST_ECOSYSTEM_ID).unwrap();
+    let mut document = ExternalIntegrationPolicyDocument::default();
+    document.user_defaults.enabled = true;
+    document.user_defaults.ecosystems.insert(
+        ecosystem.clone(),
+        ExternalEcosystemPolicy {
+            mode: ExternalIntegrationMode::DiscoverOnly,
+            ..ExternalEcosystemPolicy::default()
+        },
+    );
+    document.workspace_overrides.insert(
+        "workspace-a".to_string(),
+        ExternalIntegrationPolicyOverride {
+            ecosystems: [(
+                ecosystem.clone(),
+                ExternalEcosystemPolicyOverride {
+                    mode: Some(ExternalIntegrationMode::Custom),
+                    capability_overrides: [(
+                        external_capability(EXTERNAL_CAPABILITY_COMMAND),
+                        ExternalIntegrationAccess::Auto,
+                    )]
+                    .into_iter()
+                    .collect(),
+                    ..ExternalEcosystemPolicyOverride::default()
+                },
+            )]
+            .into_iter()
+            .collect(),
+            ..ExternalIntegrationPolicyOverride::default()
+        },
+    );
+
+    let effective = evaluate_external_integration_policy(
+        &document,
+        Some("workspace-a"),
+        &test_external_integration_ecosystems(),
+    )
+    .unwrap();
+    let opencode = &effective.ecosystems[&ecosystem];
+    assert_eq!(opencode.mode, ExternalIntegrationMode::Custom);
+    assert_eq!(
+        opencode.capabilities[&external_capability(EXTERNAL_CAPABILITY_COMMAND)],
+        ExternalIntegrationAccess::Auto
+    );
+    assert_eq!(
+        opencode.capabilities[&external_capability(EXTERNAL_CAPABILITY_MCP)],
+        ExternalIntegrationAccess::DiscoverOnly
+    );
+
+    let inherited = evaluate_external_integration_policy(
+        &document,
+        Some("workspace-b"),
+        &test_external_integration_ecosystems(),
+    )
+    .unwrap();
+    assert_eq!(
+        inherited.ecosystems[&ecosystem].mode,
+        ExternalIntegrationMode::DiscoverOnly
+    );
+}
+
+#[test]
+fn high_risk_auto_access_is_limited_by_the_capability_owner() {
+    let ecosystem = EcosystemId::new(TEST_ECOSYSTEM_ID).unwrap();
+    let mcp = external_capability(EXTERNAL_CAPABILITY_MCP);
+    let mut document = ExternalIntegrationPolicyDocument::default();
+    document.user_defaults.enabled = true;
+    document.user_defaults.ecosystems.insert(
+        ecosystem.clone(),
+        ExternalEcosystemPolicy {
+            mode: ExternalIntegrationMode::Custom,
+            capability_overrides: [(mcp.clone(), ExternalIntegrationAccess::Auto)]
+                .into_iter()
+                .collect(),
+            ..ExternalEcosystemPolicy::default()
+        },
+    );
+
+    let effective = evaluate_external_integration_policy(
+        &document,
+        None,
+        &test_external_integration_ecosystems(),
+    )
+    .unwrap();
+    let opencode = &effective.ecosystems[&ecosystem];
+    assert_eq!(
+        opencode.capabilities[&mcp],
+        ExternalIntegrationAccess::AskBeforeUse
+    );
+    assert!(opencode.policy_limited_capabilities.contains(&mcp));
+}
+
+#[test]
+fn future_policy_values_and_minor_fields_survive_read_modify_write() {
+    let raw = serde_json::json!({
+        "schemaMajor": 1,
+        "userDefaults": {
+            "enabled": true,
+            "ecosystems": {
+                "opencode": {
+                    "mode": "future_mode",
+                    "capabilityOverrides": {
+                        "future-capability": "future_access"
+                    },
+                    "futureEcosystemField": { "enabled": true }
+                }
+            },
+            "futureSettingsField": "preserve-me"
+        },
+        "workspaceOverrides": {},
+        "futureDocumentField": [1, 2, 3]
+    });
+    let mut document: ExternalIntegrationPolicyDocument =
+        serde_json::from_value(raw.clone()).expect("future minor data remains readable");
+    document.user_defaults.enabled = false;
+    let encoded = serde_json::to_value(&document).expect("policy remains serializable");
+
+    assert_eq!(
+        encoded["userDefaults"]["ecosystems"]["opencode"]["mode"],
+        "future_mode"
+    );
+    assert_eq!(
+        encoded["userDefaults"]["ecosystems"]["opencode"]["capabilityOverrides"]
+            ["future-capability"],
+        "future_access"
+    );
+    assert_eq!(
+        encoded["userDefaults"]["ecosystems"]["opencode"]["futureEcosystemField"],
+        raw["userDefaults"]["ecosystems"]["opencode"]["futureEcosystemField"]
+    );
+    assert_eq!(
+        encoded["userDefaults"]["futureSettingsField"],
+        "preserve-me"
+    );
+    assert_eq!(encoded["futureDocumentField"], raw["futureDocumentField"]);
+
+    let effective = evaluate_external_integration_policy(
+        &document,
+        None,
+        &test_external_integration_ecosystems(),
+    )
+    .unwrap();
+    assert!(!effective.enabled);
+}
+
+#[test]
+fn incompatible_policy_schema_major_is_rejected_without_downgrade() {
+    let document = ExternalIntegrationPolicyDocument {
+        schema_major: 2,
+        ..ExternalIntegrationPolicyDocument::default()
+    };
+    let error = evaluate_external_integration_policy(
+        &document,
+        None,
+        &test_external_integration_ecosystems(),
+    )
+    .expect_err("future major schemas must fail closed");
+    assert!(error.to_string().contains("schema major: 2"));
+}
+
+#[test]
+fn incompatible_policy_schema_has_a_safe_read_only_public_snapshot() {
+    let raw = serde_json::json!({
+        "schemaMajor": 2,
+        "userDefaults": {
+            "enabled": true,
+            "futureSecretHostField": "persistence-only"
+        },
+        "futureDocumentField": { "keep": true }
+    });
+    let document: ExternalIntegrationPolicyDocument = serde_json::from_value(raw).unwrap();
+    let snapshot = external_integration_policy_snapshot(
+        &document,
+        Some("workspace-a"),
+        test_external_integration_ecosystems(),
+    )
+    .expect("incompatible schemas remain inspectable through a safe snapshot");
+
+    assert_eq!(
+        snapshot.status,
+        ExternalIntegrationPolicyStatus::IncompatibleSchema
+    );
+    assert!(!snapshot.global_effective.enabled);
+    assert!(!snapshot.effective.enabled);
+    assert!(snapshot
+        .effective
+        .ecosystems
+        .values()
+        .all(|ecosystem| ecosystem
+            .capabilities
+            .values()
+            .all(|access| { matches!(access, ExternalIntegrationAccess::Disabled) })));
+
+    let public = serde_json::to_string(&snapshot).unwrap();
+    assert!(!public.contains("futureSecretHostField"));
+    assert!(!public.contains("futureDocumentField"));
+
+    let persisted = serde_json::to_string(&document).unwrap();
+    assert!(persisted.contains("futureSecretHostField"));
+    assert!(persisted.contains("futureDocumentField"));
+}
+
+#[test]
+fn integration_registry_rejects_ambiguous_or_unsafe_descriptors() {
+    let mut duplicate_ecosystem = test_external_integration_ecosystems();
+    duplicate_ecosystem.push(duplicate_ecosystem[0].clone());
+    let duplicate_error = evaluate_external_integration_policy(
+        &ExternalIntegrationPolicyDocument::default(),
+        None,
+        &duplicate_ecosystem,
+    )
+    .expect_err("duplicate ecosystem registrations must fail closed");
+    assert!(duplicate_error.to_string().contains("duplicate ecosystem"));
+
+    let mut unsafe_recommendation = test_external_integration_ecosystems();
+    unsafe_recommendation[0].capabilities[1].recommended_access = ExternalIntegrationAccess::Auto;
+    let unsafe_error = evaluate_external_integration_policy(
+        &ExternalIntegrationPolicyDocument::default(),
+        None,
+        &unsafe_recommendation,
+    )
+    .expect_err("registry defaults cannot exceed their safety ceiling");
+    assert!(unsafe_error
+        .to_string()
+        .contains("exceeds the safety ceiling"));
+}
+
+#[test]
+fn public_snapshot_never_exposes_executable_prompt_templates() {
+    let snapshot = ExternalSourceCatalogSnapshot {
+        generation: 1,
+        discovery_pending: false,
+        sources: Vec::new(),
+        commands: vec![PromptCommandCatalogEntry {
+            definition: command("opencode", "project-commands", 1),
+        }],
+        command_conflicts: Vec::new(),
+        tools: Vec::new(),
+        tool_approval_requests: Vec::new(),
+        tool_conflicts: Vec::new(),
+        mcp_generation: 0,
+        mcp_servers: Vec::new(),
+        mcp_approval_requests: Vec::new(),
+        mcp_conflicts: Vec::new(),
+        subagent_generation: 0,
+        preference_revision: 0,
+        subagents: Vec::new(),
+        subagent_model_binding_groups: vec![ExternalSubagentModelBindingGroup {
+            binding_key: "external_subagent_model_binding:review".to_string(),
+            request: ExternalSubagentModelRequest::Reference {
+                provider_hint: Some("anthropic".to_string()),
+                model_name: "claude-sonnet-4".to_string(),
+            },
+            profile_request: None,
+            scope: ExternalSourceScope::Project,
+            method: ExternalSubagentModelBindingMethod::BindingRequired,
+            selected_target: None,
+            effective_model_label: None,
+            affected_candidate_ids: vec!["opencode-review".to_string()],
+        }],
+        subagent_model_binding_options: vec![ExternalSubagentModelBindingOption {
+            target: ExternalSubagentModelBindingTarget::Fast,
+            effective_model_label: "GLM-4.5-Air".to_string(),
+            configured_reasoning_effort: None,
+        }],
+        subagent_conflicts: Vec::new(),
+        pending_subagent_approvals: Vec::new(),
+        integration_policy: Default::default(),
+        diagnostics: Vec::new(),
+    };
+
+    let public = ExternalSourcePublicSnapshot::from(snapshot);
+    let encoded = serde_json::to_value(public).expect("serialize public projection");
+
+    assert_eq!(encoded["commands"][0]["definition"]["name"], "review");
+    assert!(encoded["commands"][0]["definition"]
+        .get("template")
+        .is_none());
+    assert_eq!(
+        encoded["subagentModelBindingGroups"][0]["bindingKey"],
+        "external_subagent_model_binding:review"
+    );
+    assert_eq!(
+        encoded["subagentModelBindingOptions"][0]["effectiveModelLabel"],
+        "GLM-4.5-Air"
+    );
+}
+
+#[test]
+fn control_projection_keeps_lifecycle_facts_orthogonal() {
+    let catalog = ExternalSourceCatalogSnapshot {
+        generation: 7,
+        discovery_pending: false,
+        sources: vec![ExternalSourceCatalogEntry {
+            stable_key: "opencode.commands:project".to_string(),
+            presentation_group_id: None,
+            record: source("opencode.commands", "opencode", "project"),
+            lifecycle: ExternalSourceLifecycleState::UsingLastValidVersion,
+        }],
+        commands: vec![PromptCommandCatalogEntry {
+            definition: command("opencode.commands", "project", 1),
+        }],
+        command_conflicts: Vec::new(),
+        tools: Vec::new(),
+        tool_approval_requests: Vec::new(),
+        tool_conflicts: Vec::new(),
+        mcp_generation: 2,
+        mcp_servers: Vec::new(),
+        mcp_approval_requests: Vec::new(),
+        mcp_conflicts: Vec::new(),
+        subagent_generation: 3,
+        preference_revision: 11,
+        subagents: Vec::new(),
+        subagent_model_binding_groups: Vec::new(),
+        subagent_model_binding_options: Vec::new(),
+        subagent_conflicts: Vec::new(),
+        pending_subagent_approvals: Vec::new(),
+        integration_policy: Default::default(),
+        diagnostics: Vec::new(),
+    };
+
+    let control = ExternalSourceControlSnapshotV1::from_catalog(
+        &catalog,
+        ExecutionDomainId::new("local-user").unwrap(),
+        false,
+        ExternalSourceHostCapabilities::read_write(),
+    );
+
+    assert_eq!(control.schema_version, EXTERNAL_SOURCE_CONTROL_SCHEMA_V1);
+    assert_eq!(control.refresh_generation, 7);
+    assert_eq!(control.preference_revision, 11);
+    assert_eq!(control.sources.len(), 1);
+    assert_eq!(
+        control.sources[0].discovery,
+        ExternalSourceDiscoveryState::LastKnownGood
+    );
+    assert_eq!(
+        control.sources[0].desired,
+        ExternalSourceDesiredState::Enabled
+    );
+    assert_eq!(
+        control.sources[0].review,
+        ExternalSourceReviewState::NotRequired
+    );
+    assert_eq!(control.capabilities.len(), 4);
+}
+
+#[test]
+fn control_projection_does_not_infer_review_facts_from_runtime_activation() {
+    let record = source("opencode.mcp", "opencode", "project-config");
+    let definition = ExternalMcpServerDefinition {
+        id: SourceQualifiedMcpServerId::new(record.key.clone(), "docs").unwrap(),
+        provenance: vec![record.key.clone()],
+        name: "docs".to_string(),
+        transport: ExternalMcpTransportKind::StreamableHttp,
+        command_preview: None,
+        argument_count: 0,
+        working_directory: None,
+        environment_keys: Vec::new(),
+        environment_reference_names: Vec::new(),
+        remote_url_preview: Some("https://mcp.example.com".to_string()),
+        header_names: Vec::new(),
+        timeouts: ExternalMcpTimeouts::default(),
+        source_enabled: true,
+        behavior_version: "behavior-v1".to_string(),
+        static_status: ExternalMcpStaticStatus::Ready,
+    };
+    let catalog = ExternalSourceCatalogSnapshot {
+        generation: 1,
+        discovery_pending: false,
+        sources: vec![ExternalSourceCatalogEntry {
+            stable_key: "opencode.mcp:project-config".to_string(),
+            presentation_group_id: None,
+            record: record.clone(),
+            lifecycle: ExternalSourceLifecycleState::Available,
+        }],
+        commands: Vec::new(),
+        command_conflicts: Vec::new(),
+        tools: Vec::new(),
+        tool_approval_requests: Vec::new(),
+        tool_conflicts: Vec::new(),
+        mcp_generation: 1,
+        mcp_servers: vec![ExternalMcpCatalogEntry {
+            candidate_id: "external_mcp:docs".to_string(),
+            definition,
+            approval_key: "approval-v1".to_string(),
+            decision_key: "decision-v1".to_string(),
+            runtime_id: None,
+            activation_state: ExternalMcpActivationState::Declined,
+        }],
+        mcp_approval_requests: Vec::new(),
+        mcp_conflicts: Vec::new(),
+        subagent_generation: 1,
+        preference_revision: 1,
+        subagents: Vec::new(),
+        subagent_model_binding_groups: Vec::new(),
+        subagent_model_binding_options: Vec::new(),
+        subagent_conflicts: Vec::new(),
+        pending_subagent_approvals: Vec::new(),
+        integration_policy: Default::default(),
+        diagnostics: Vec::new(),
+    };
+
+    let control = ExternalSourceControlSnapshotV1::from_catalog(
+        &catalog,
+        ExecutionDomainId::new("local-user").unwrap(),
+        false,
+        ExternalSourceHostCapabilities::read_write(),
+    );
+
+    assert_eq!(
+        control.sources[0].review,
+        ExternalSourceReviewState::NotRequired
+    );
+}
+
+#[test]
+fn desktop_local_host_capability_is_additive_on_the_wire() {
+    let portable = serde_json::to_value(ExternalSourceHostCapabilities::read_write()).unwrap();
+    let read_only =
+        serde_json::to_value(ExternalSourceHostCapabilities::read_only_projection()).unwrap();
+    let desktop = serde_json::to_value(ExternalSourceHostCapabilities::local_desktop()).unwrap();
+
+    assert!(portable.get("canRevealSourceLocation").is_none());
+    assert!(read_only.get("canRevealSourceLocation").is_none());
+    assert_eq!(desktop["canRevealSourceLocation"], true);
+
+    let legacy: ExternalSourceHostCapabilities = serde_json::from_value(serde_json::json!({
+        "canRefresh": true,
+        "canMutatePolicy": true,
+        "canManageSources": true,
+        "canApproveRuntime": true,
+        "canExecuteExternalAssets": true,
+        "canSetSafeMode": true
+    }))
+    .unwrap();
+    assert!(!legacy.can_reveal_source_location);
+}
+
+#[test]
+fn operation_error_round_trip_preserves_typed_recovery_without_message_parsing() {
+    let error = ExternalSourceOperationError::new(
+        ExternalSourceOperationErrorCode::StaleRevision,
+        "refresh required",
+        true,
+    )
+    .with_stage(ExternalSourceOperationStage::ApplyPreference)
+    .with_causation_id("refresh-generation-7")
+    .with_recovery_action(ExternalSourceRecoveryActionV1::Refresh);
+
+    let encoded = error.encode();
+    assert_eq!(ExternalSourceOperationError::decode(&encoded), Some(error));
+    assert!(!encoded.contains("metadata"));
+}
+
+#[test]
+fn control_action_uses_one_camel_case_dto_across_product_surfaces() {
+    let request = ExternalSourceControlRequestV1 {
+        schema_version: EXTERNAL_SOURCE_CONTROL_SCHEMA_V1,
+        operation_id: "surface-operation-1".to_string(),
+        expected_preference_revision: Some(8),
+        action: ExternalSourceControlActionV1::SetSourceEnabled {
+            source_key: "opencode.commands:project".to_string(),
+            enabled: false,
+        },
+    };
+
+    let encoded = serde_json::to_value(&request).expect("serialize control request");
+    assert_eq!(encoded["schemaVersion"], 1);
+    assert_eq!(encoded["operationId"], "surface-operation-1");
+    assert_eq!(encoded["expectedPreferenceRevision"], 8);
+    assert_eq!(encoded["action"]["type"], "set_source_enabled");
+    assert_eq!(encoded["action"]["sourceKey"], "opencode.commands:project");
+    assert!(encoded["action"].get("source_key").is_none());
+    assert_eq!(
+        serde_json::from_value::<ExternalSourceControlRequestV1>(encoded)
+            .expect("deserialize the shared control request"),
+        request
+    );
+}
+
+#[test]
+fn legacy_operation_errors_decode_with_empty_extension_fields() {
+    let decoded = ExternalSourceOperationError::decode(
+        r#"{"code":"unavailable","detail":"retry","retryable":true}"#,
+    )
+    .expect("legacy operation error remains readable");
+
+    assert_eq!(decoded.code, ExternalSourceOperationErrorCode::Unavailable);
+    assert!(decoded.stage.is_none());
+    assert!(decoded.causation_id.is_none());
+    assert!(decoded.recovery_actions.is_empty());
+}
+
+#[test]
+fn decoded_operation_errors_bound_untrusted_extension_fields() {
+    let oversized = "x".repeat(5000);
+    let encoded = serde_json::json!({
+        "code": "stale_revision",
+        "detail": oversized,
+        "retryable": true,
+        "correlationId": "forged\nreference",
+        "recoveryActions": [
+            { "type": "refresh" },
+            { "type": "refresh" },
+            { "type": "retry" }
+        ]
+    })
+    .to_string();
+
+    let decoded = ExternalSourceOperationError::decode(&encoded).unwrap();
+    assert_eq!(decoded.detail.chars().count(), 4096);
+    assert!(decoded.correlation_id.is_none());
+    assert_eq!(
+        decoded.recovery_actions,
+        vec![
+            ExternalSourceRecoveryActionV1::Refresh,
+            ExternalSourceRecoveryActionV1::Retry,
+        ]
+    );
+}
diff --git a/src/crates/contracts/product-domains/tests/workspace_reference_contracts.rs b/src/crates/contracts/product-domains/tests/external_source_contracts/workspace_reference_contracts.rs
similarity index 100%
rename from src/crates/contracts/product-domains/tests/workspace_reference_contracts.rs
rename to src/crates/contracts/product-domains/tests/external_source_contracts/workspace_reference_contracts.rs
diff --git a/src/crates/contracts/product-domains/tests/function_agent_contracts.rs b/src/crates/contracts/product-domains/tests/function_agent_contracts.rs
index d3db55730b..c787fe1edf 100644
--- a/src/crates/contracts/product-domains/tests/function_agent_contracts.rs
+++ b/src/crates/contracts/product-domains/tests/function_agent_contracts.rs
@@ -2,23 +2,12 @@
 
 use bitfun_product_domains::function_agents::{
     git_func_agent::{
-        assemble_commit_message, build_changes_summary_from_paths, build_commit_prompt,
-        detect_change_patterns, extract_module_name, infer_file_type, parse_commit_analysis_json,
-        parse_commit_analysis_value, parse_commit_type_label, prepare_commit_prompt,
-        truncate_diff_for_commit_prompt, ChangePattern, CommitFormat, CommitMessageOptions,
-        CommitType, FileChange, FileChangeType, ProjectContext,
+        assemble_commit_message, build_changes_summary_from_paths, parse_commit_analysis_json,
+        CommitFormat, CommitMessageOptions, CommitType, ProjectContext,
     },
     ports::{
         CommitAiAnalysisRequest, FunctionAgentAiPort, FunctionAgentFuture, FunctionAgentGitPort,
-        FunctionAgentRuntimeFacade, GitCommitSnapshot, StartchatGitSnapshot, StartchatTimeSnapshot,
-        WorkStateAiAnalysisRequest,
-    },
-    startchat_func_agent::{
-        build_complete_analysis_prompt, combine_git_diffs, limit_quick_actions,
-        normalize_predicted_actions, parse_complete_analysis_json, parse_complete_analysis_value,
-        parse_git_status_porcelain, parse_predicted_actions_from_values,
-        parse_quick_actions_from_values, time_of_day_for_hour, ActionPriority, AheadBehind,
-        GitWorkState, QuickActionType, TimeOfDay, WorkStateOptions,
+        FunctionAgentRuntimeFacade, GitCommitSnapshot,
     },
     AgentErrorType, Language,
 };
@@ -44,37 +33,6 @@ impl FunctionAgentGitPort for FunctionAgentPortStub {
             })
         })
     }
-
-    fn startchat_git_snapshot(
-        &self,
-        _repo_path: PathBuf,
-    ) -> FunctionAgentFuture<'_, StartchatGitSnapshot> {
-        Box::pin(async {
-            Ok(StartchatGitSnapshot {
-                current_branch: "main".to_string(),
-                status_porcelain: " M src/lib.rs\nA  staged.rs\n".to_string(),
-                unstaged_diff: "unstaged".to_string(),
-                staged_diff: "staged".to_string(),
-                unpushed_commits: 2,
-                ahead_behind: Some(AheadBehind {
-                    ahead: 1,
-                    behind: 0,
-                }),
-                last_commit_timestamp: Some(900),
-            })
-        })
-    }
-
-    fn startchat_time_snapshot(
-        &self,
-        _repo_path: PathBuf,
-    ) -> FunctionAgentFuture<'_, StartchatTimeSnapshot> {
-        Box::pin(async {
-            Ok(StartchatTimeSnapshot {
-                last_commit_timestamp: Some(900),
-            })
-        })
-    }
 }
 
 impl FunctionAgentAiPort for FunctionAgentPortStub {
@@ -99,25 +57,6 @@ impl FunctionAgentAiPort for FunctionAgentPortStub {
             )
         })
     }
-
-    fn analyze_work_state(
-        &self,
-        _request: WorkStateAiAnalysisRequest,
-    ) -> FunctionAgentFuture<
-        '_,
-        bitfun_product_domains::function_agents::startchat_func_agent::AIGeneratedAnalysis,
-    > {
-        Box::pin(async {
-            Ok(
-                bitfun_product_domains::function_agents::startchat_func_agent::AIGeneratedAnalysis {
-                    summary: "stub".to_string(),
-                    ongoing_work: Vec::new(),
-                    predicted_actions: Vec::new(),
-                    quick_actions: Vec::new(),
-                },
-            )
-        })
-    }
 }
 
 struct EmptyCommitPortStub;
@@ -137,49 +76,6 @@ impl FunctionAgentGitPort for EmptyCommitPortStub {
             })
         })
     }
-
-    fn startchat_git_snapshot(
-        &self,
-        _repo_path: PathBuf,
-    ) -> FunctionAgentFuture<'_, StartchatGitSnapshot> {
-        FunctionAgentPortStub.startchat_git_snapshot(_repo_path)
-    }
-
-    fn startchat_time_snapshot(
-        &self,
-        _repo_path: PathBuf,
-    ) -> FunctionAgentFuture<'_, StartchatTimeSnapshot> {
-        FunctionAgentPortStub.startchat_time_snapshot(_repo_path)
-    }
-}
-
-struct NoGitStateExpectedPortStub;
-
-impl FunctionAgentGitPort for NoGitStateExpectedPortStub {
-    fn git_commit_snapshot(
-        &self,
-        _repo_path: PathBuf,
-    ) -> FunctionAgentFuture<'_, GitCommitSnapshot> {
-        panic!("git_commit_snapshot should not be called")
-    }
-
-    fn startchat_git_snapshot(
-        &self,
-        _repo_path: PathBuf,
-    ) -> FunctionAgentFuture<'_, StartchatGitSnapshot> {
-        panic!("startchat_git_snapshot should not be called")
-    }
-
-    fn startchat_time_snapshot(
-        &self,
-        _repo_path: PathBuf,
-    ) -> FunctionAgentFuture<'_, StartchatTimeSnapshot> {
-        Box::pin(async {
-            Ok(StartchatTimeSnapshot {
-                last_commit_timestamp: Some(900),
-            })
-        })
-    }
 }
 
 fn block_on<F: Future>(future: F) -> F::Output {
@@ -201,7 +97,6 @@ fn noop_waker() -> Waker {
     unsafe fn wake(_: *const ()) {}
     unsafe fn wake_by_ref(_: *const ()) {}
     unsafe fn drop(_: *const ()) {}
-
     static VTABLE: RawWakerVTable = RawWakerVTable::new(clone, wake, wake_by_ref, drop);
     unsafe { Waker::from_raw(RawWaker::new(std::ptr::null(), &VTABLE)) }
 }
@@ -209,7 +104,6 @@ fn noop_waker() -> Waker {
 #[test]
 fn git_commit_options_preserve_existing_defaults() {
     let options = CommitMessageOptions::default();
-
     assert_eq!(options.format, CommitFormat::Conventional);
     assert!(options.include_files);
     assert!(options.include_body);
@@ -218,315 +112,34 @@ fn git_commit_options_preserve_existing_defaults() {
 }
 
 #[test]
-fn git_function_agent_prompt_helpers_preserve_ai_contract() {
-    let options = CommitMessageOptions {
-        format: CommitFormat::Angular,
-        max_title_length: 64,
-        language: Language::English,
-        ..CommitMessageOptions::default()
-    };
-    let context = ProjectContext {
-        project_type: "rust-workspace".to_string(),
-        tech_stack: vec!["Rust".to_string(), "React".to_string()],
-        ..ProjectContext::default()
-    };
-
-    let prompt = build_commit_prompt(
-        "type={project_type}; stack={tech_stack}; format={format_desc}; lang={language_desc}; max={max_title_length}; diff={diff_content}",
-        "diff --git a/lib.rs b/lib.rs",
-        &context,
-        &options,
-    );
-
-    assert_eq!(
-        prompt,
-        "type=rust-workspace; stack=Rust, React; format=Angular Style; lang=English; max=64; diff=diff --git a/lib.rs b/lib.rs"
-    );
-    assert_eq!(parse_commit_type_label("feature"), CommitType::Feat);
-    assert_eq!(parse_commit_type_label("performance"), CommitType::Perf);
-    assert_eq!(parse_commit_type_label("unknown"), CommitType::Chore);
-}
-
-#[test]
-fn git_function_agent_summary_helpers_preserve_commit_shape() {
-    let changed_files = vec![
-        "src/crates/assembly/core/lib.rs".to_string(),
-        "README.md".to_string(),
-    ];
-    let summary = build_changes_summary_from_paths(&changed_files, 2, 1);
-
-    assert_eq!(summary.total_additions, 30);
-    assert_eq!(summary.total_deletions, 15);
-    assert_eq!(summary.files_changed, 2);
-    assert_eq!(
-        summary.file_changes[0].path,
-        "src/crates/assembly/core/lib.rs"
-    );
-    assert_eq!(summary.file_changes[0].file_type, "rs");
-    assert!(summary.affected_modules.contains(&"core".to_string()));
-    assert!(summary
-        .change_patterns
-        .contains(&ChangePattern::DocumentationUpdate));
-
-    let message = assemble_commit_message(
-        "feat(core): add boundary helper",
-        &Some("Move pure helper to owner crate.".to_string()),
-        &Some("BREAKING CHANGE: none".to_string()),
-    );
-    assert_eq!(
-        message,
-        "feat(core): add boundary helper\n\nMove pure helper to owner crate.\n\nBREAKING CHANGE: none"
-    );
-
-    let title_only = assemble_commit_message("chore: tidy", &Some(String::new()), &None);
-    assert_eq!(title_only, "chore: tidy");
-}
-
-#[test]
-fn git_function_agent_analysis_parser_preserves_defaults_and_required_title() {
-    let analysis = parse_commit_analysis_value(&serde_json::json!({
-        "type": "feature",
-        "scope": "core",
-        "title": "feat(core): add helper",
-        "body": "Move pure parsing policy.",
-        "breaking_changes": "none",
-        "confidence": 0.95
-    }))
-    .expect("valid commit analysis");
-
+fn git_commit_helpers_preserve_contract() {
+    let analysis = parse_commit_analysis_json(
+        r#"{"type":"feat","scope":"core","title":"feat(core): add task models","confidence":0.9}"#,
+    )
+    .unwrap();
     assert_eq!(analysis.commit_type, CommitType::Feat);
     assert_eq!(analysis.scope.as_deref(), Some("core"));
-    assert_eq!(analysis.title, "feat(core): add helper");
-    assert_eq!(analysis.reasoning, "AI analysis");
-    assert!((analysis.confidence - 0.95).abs() < f32::EPSILON);
-
-    let fallback = parse_commit_analysis_value(&serde_json::json!({
-        "title": "chore: tidy"
-    }))
-    .expect("fallback commit analysis");
-    assert_eq!(fallback.commit_type, CommitType::Chore);
-    assert_eq!(fallback.confidence, 0.8);
-
-    let missing_title = parse_commit_analysis_value(&serde_json::json!({
-        "type": "fix"
-    }));
-    assert_eq!(missing_title.unwrap_err(), "Missing title field");
-}
-
-#[test]
-fn git_function_agent_diff_truncation_preserves_legacy_marker() {
-    let short = "diff --git a/lib.rs b/lib.rs";
-    assert_eq!(truncate_diff_for_commit_prompt(short, 50), short);
-
-    let long = "a".repeat(140);
-    let truncated = truncate_diff_for_commit_prompt(&long, 120);
-    assert!(truncated.starts_with(&"a".repeat(20)));
-    assert!(truncated.ends_with("\n\n... [content truncated] ..."));
-}
-
-#[test]
-fn git_function_agent_commit_prompt_preparation_preserves_truncation_boundary() {
-    let context = ProjectContext {
-        project_type: "library".to_string(),
-        tech_stack: vec!["Rust".to_string(), "Cargo".to_string()],
-        project_docs: Some("Use conventional commits.".to_string()),
-        code_standards: Some("Keep modules small.".to_string()),
-    };
-    let options = CommitMessageOptions::default();
-    let template = "Project: {project_type}\nStack: {tech_stack}\nDiff: {diff_content}\nLanguage: {language_desc}\n";
-    let prepared = prepare_commit_prompt(template, &"x".repeat(140), &context, &options, 120);
-
-    assert!(prepared.truncated);
-    assert!(prepared
-        .diff_content
-        .ends_with("\n\n... [content truncated] ..."));
-    assert!(prepared.prompt.contains("Diff: "));
-    assert!(prepared.prompt.contains("library"));
-
-    let short = prepare_commit_prompt(template, "short diff", &context, &options, 120);
-    assert!(!short.truncated);
-    assert_eq!(short.diff_content, "short diff");
-}
-
-#[test]
-fn startchat_options_preserve_existing_defaults() {
-    let options = WorkStateOptions::default();
-
-    assert!(options.analyze_git);
-    assert!(options.predict_next_actions);
-    assert!(options.include_quick_actions);
-    assert_eq!(options.language, Language::English);
-}
-
-#[test]
-fn startchat_prompt_helpers_preserve_ai_contract() {
-    let git_state = Some(GitWorkState {
-        current_branch: "main".to_string(),
-        unstaged_files: 2,
-        staged_files: 1,
-        unpushed_commits: 3,
-        ahead_behind: None,
-        modified_files: Vec::new(),
-    });
-
-    let prompt = build_complete_analysis_prompt(
-        "{lang_instruction}\n{git_state_section}\n{git_diff_section}",
-        &git_state,
-        "diff --git a/file b/file",
-        &Language::Chinese,
-    );
-
-    assert!(prompt.contains("Please respond in Chinese."));
-    assert!(prompt.contains("Current branch: main"));
-    assert!(prompt.contains("Staged files: 1"));
-    assert!(prompt.contains("## Code Changes (Git Diff)"));
-}
-
-#[test]
-fn startchat_action_helpers_preserve_limits_and_defaults() {
-    let predicted = parse_predicted_actions_from_values(&[serde_json::json!({
-        "description": "Review changes",
-        "priority": "High",
-        "icon": "search",
-        "is_reminder": true
-    })]);
-    let predicted = normalize_predicted_actions(predicted);
-
-    assert_eq!(predicted.len(), 3);
-    assert_eq!(predicted[0].priority, ActionPriority::High);
-    assert!(predicted[0].is_reminder);
-    assert_eq!(predicted[1].description, "Continue current development");
-
-    let quick = parse_quick_actions_from_values(&[
-        serde_json::json!({"title": "Continue", "command": "/continue", "action_type": "Continue"}),
-        serde_json::json!({"title": "Status", "command": "/status", "action_type": "ViewStatus"}),
-        serde_json::json!({"title": "Commit", "command": "/commit", "action_type": "Commit"}),
-        serde_json::json!({"title": "Visualize", "command": "/visualize", "action_type": "Visualize"}),
-        serde_json::json!({"title": "Custom 1", "command": "one"}),
-        serde_json::json!({"title": "Custom 2", "command": "two"}),
-        serde_json::json!({"title": "Custom 3", "command": "three"}),
-    ]);
-    let quick = limit_quick_actions(quick);
-
-    assert_eq!(quick.len(), 6);
-    assert_eq!(quick[0].action_type, QuickActionType::Continue);
-    assert_eq!(quick[1].action_type, QuickActionType::ViewStatus);
-    assert_eq!(quick[5].title, "Custom 2");
-}
-
-#[test]
-fn startchat_complete_analysis_parser_preserves_defaults_and_limits() {
-    let parsed = parse_complete_analysis_value(&serde_json::json!({
-        "summary": "Working on refactor boundaries.",
-        "predicted_actions": [
-            {"description": "Review changes", "priority": "High", "icon": "search", "is_reminder": true},
-            {"description": "Run tests", "priority": "Medium", "icon": "check"},
-            {"description": "Open PR", "priority": "Low", "icon": "git-pull-request"},
-            {"description": "Extra", "priority": "Low", "icon": "more"}
-        ],
-        "quick_actions": [
-            {"title": "Continue", "command": "/continue", "action_type": "Continue"},
-            {"title": "Status", "command": "/status", "action_type": "ViewStatus"},
-            {"title": "Commit", "command": "/commit", "action_type": "Commit"},
-            {"title": "Visualize", "command": "/visualize", "action_type": "Visualize"},
-            {"title": "Custom 1", "command": "one"},
-            {"title": "Custom 2", "command": "two"},
-            {"title": "Custom 3", "command": "three"}
-        ]
-    }));
-
-    assert_eq!(parsed.predicted_actions_count, 4);
-    assert_eq!(parsed.quick_actions_count, 7);
-    assert_eq!(parsed.analysis.summary, "Working on refactor boundaries.");
-    assert_eq!(parsed.analysis.predicted_actions.len(), 3);
+    assert_eq!(analysis.title, "feat(core): add task models");
     assert_eq!(
-        parsed.analysis.predicted_actions[0].priority,
-        ActionPriority::High
+        assemble_commit_message("title", &Some("body".into()), &None),
+        "title\n\nbody"
     );
-    assert!(parsed.analysis.predicted_actions[0].is_reminder);
-    assert_eq!(parsed.analysis.quick_actions.len(), 6);
-    assert_eq!(parsed.analysis.quick_actions[5].title, "Custom 2");
-
-    let fallback = parse_complete_analysis_value(&serde_json::json!({}));
-    assert_eq!(fallback.predicted_actions_count, 0);
-    assert_eq!(fallback.quick_actions_count, 0);
-    assert_eq!(
-        fallback.analysis.summary,
-        "You were working on development, with multiple files modified."
-    );
-    assert_eq!(fallback.analysis.predicted_actions.len(), 3);
-    assert!(fallback.analysis.quick_actions.is_empty());
-}
-
-#[test]
-fn startchat_git_status_helpers_preserve_porcelain_contract() {
-    let (unstaged, staged, files) = parse_git_status_porcelain(
-        " M src/lib.rs\nM  Cargo.toml\n?? README.md\nR  old.rs -> new.rs\n",
-    );
-
-    assert_eq!(unstaged, 2);
-    assert_eq!(staged, 2);
-    assert_eq!(files[0].path, "src/lib.rs");
-    assert_eq!(files[0].module.as_deref(), Some("src"));
-    assert_eq!(files[1].change_type.to_string(), "Modified");
-    assert_eq!(files[2].path, "README.md");
-    assert_eq!(files[3].change_type.to_string(), "Renamed");
-
-    assert_eq!(time_of_day_for_hour(4), TimeOfDay::Night);
-    assert_eq!(time_of_day_for_hour(9), TimeOfDay::Morning);
-    assert_eq!(time_of_day_for_hour(14), TimeOfDay::Afternoon);
-    assert_eq!(time_of_day_for_hour(20), TimeOfDay::Evening);
-
-    assert_eq!(combine_git_diffs("unstaged", ""), "unstaged");
-    assert_eq!(
-        combine_git_diffs("unstaged", "staged"),
-        "unstaged\n\n=== Staged Changes ===\n\nstaged"
-    );
-}
-
-#[test]
-fn function_agent_ports_keep_ai_and_git_boundaries_explicit() {
-    let commit_request = CommitAiAnalysisRequest {
-        diff_content: "diff".to_string(),
-        project_context: ProjectContext::default(),
-        options: CommitMessageOptions::default(),
-    };
-    let json = serde_json::to_value(&commit_request).unwrap();
-    assert_eq!(json["diffContent"], "diff");
-    assert_eq!(json["options"]["maxTitleLength"], 72);
-
-    let work_state_request = WorkStateAiAnalysisRequest {
-        git_state: None,
-        git_diff: "diff".to_string(),
-        language: Language::English,
-    };
-    let json = serde_json::to_value(&work_state_request).unwrap();
-    assert_eq!(json["gitDiff"], "diff");
-    assert_eq!(json["language"], "English");
-
-    let port: &dyn FunctionAgentGitPort = &FunctionAgentPortStub;
-    let _future = port.git_commit_snapshot(PathBuf::from("."));
-
-    let ai_port: &dyn FunctionAgentAiPort = &FunctionAgentPortStub;
-    let _future = ai_port.analyze_work_state(work_state_request);
+    let summary = build_changes_summary_from_paths(&["src/lib.rs".into()], 1, 0);
+    assert_eq!(summary.files_changed, 1);
 }
 
 #[test]
 fn function_agent_runtime_facade_generates_commit_message_from_ports() {
     let ports = FunctionAgentPortStub;
     let facade = FunctionAgentRuntimeFacade::new(&ports, &ports);
-
     let message = block_on(
         facade.generate_commit_message(PathBuf::from("repo"), CommitMessageOptions::default()),
     )
     .unwrap();
-
     assert_eq!(message.title, "chore: test");
     assert_eq!(message.full_message, "chore: test");
     assert_eq!(message.commit_type, CommitType::Chore);
-    assert_eq!(message.confidence, 1.0);
     assert_eq!(message.changes_summary.files_changed, 1);
-    assert_eq!(message.changes_summary.file_changes[0].path, "src/lib.rs");
 }
 
 #[test]
@@ -534,171 +147,13 @@ fn function_agent_runtime_facade_preserves_empty_staging_error() {
     let git = EmptyCommitPortStub;
     let ai = FunctionAgentPortStub;
     let facade = FunctionAgentRuntimeFacade::new(&git, &ai);
-
     let error = block_on(
         facade.generate_commit_message(PathBuf::from("repo"), CommitMessageOptions::default()),
     )
     .unwrap_err();
-
     assert_eq!(error.error_type, AgentErrorType::InvalidInput);
     assert_eq!(
         error.message,
         "Staging area is empty, please stage files first"
     );
 }
-
-#[test]
-fn function_agent_runtime_facade_builds_work_state_from_ports_without_surface_logic() {
-    let ports = FunctionAgentPortStub;
-    let facade = FunctionAgentRuntimeFacade::new(&ports, &ports);
-    let options = WorkStateOptions {
-        predict_next_actions: false,
-        include_quick_actions: false,
-        ..WorkStateOptions::default()
-    };
-
-    let analysis = block_on(facade.analyze_work_state(
-        PathBuf::from("repo"),
-        options,
-        960,
-        14,
-        "2026-05-19T12:00:00+08:00".to_string(),
-    ))
-    .unwrap();
-
-    let git_state = analysis.current_state.git_state.unwrap();
-    assert_eq!(analysis.current_state.summary, "stub");
-    assert_eq!(git_state.current_branch, "main");
-    assert_eq!(git_state.unstaged_files, 1);
-    assert_eq!(git_state.staged_files, 1);
-    assert_eq!(git_state.unpushed_commits, 2);
-    assert_eq!(git_state.ahead_behind.unwrap().ahead, 1);
-    assert_eq!(
-        analysis.current_state.time_info.minutes_since_last_commit,
-        Some(1)
-    );
-    assert_eq!(
-        analysis.current_state.time_info.time_of_day,
-        TimeOfDay::Afternoon
-    );
-    assert!(analysis.predicted_actions.is_empty());
-    assert!(analysis.quick_actions.is_empty());
-    assert_eq!(analysis.analyzed_at, "2026-05-19T12:00:00+08:00");
-}
-
-#[test]
-fn function_agent_runtime_facade_honors_disabled_git_state_boundary_and_preserves_time_info() {
-    let git = NoGitStateExpectedPortStub;
-    let ai = FunctionAgentPortStub;
-    let facade = FunctionAgentRuntimeFacade::new(&git, &ai);
-    let options = WorkStateOptions {
-        analyze_git: false,
-        predict_next_actions: false,
-        include_quick_actions: false,
-        ..WorkStateOptions::default()
-    };
-
-    let analysis = block_on(facade.analyze_work_state(
-        PathBuf::from("repo"),
-        options,
-        960,
-        9,
-        "2026-05-19T09:00:00+08:00".to_string(),
-    ))
-    .unwrap();
-
-    assert_eq!(analysis.current_state.summary, "stub");
-    assert!(analysis.current_state.git_state.is_none());
-    assert_eq!(
-        analysis.current_state.time_info.minutes_since_last_commit,
-        Some(1)
-    );
-    assert_eq!(
-        analysis.current_state.time_info.time_of_day,
-        TimeOfDay::Morning
-    );
-    assert!(analysis.predicted_actions.is_empty());
-    assert!(analysis.quick_actions.is_empty());
-}
-
-#[test]
-fn git_function_agent_utils_preserve_change_classification() {
-    assert_eq!(infer_file_type("src/main.rs"), "rs");
-    assert_eq!(
-        extract_module_name("src/crates/assembly/core/lib.rs").as_deref(),
-        Some("core")
-    );
-
-    let patterns = detect_change_patterns(&[
-        FileChange {
-            path: "src/lib.rs".to_string(),
-            change_type: FileChangeType::Modified,
-            additions: 20,
-            deletions: 2,
-            file_type: "rs".to_string(),
-        },
-        FileChange {
-            path: "README.md".to_string(),
-            change_type: FileChangeType::Modified,
-            additions: 4,
-            deletions: 1,
-            file_type: "md".to_string(),
-        },
-    ]);
-
-    assert!(patterns.contains(&ChangePattern::BugFix));
-    assert!(patterns.contains(&ChangePattern::DocumentationUpdate));
-}
-
-#[test]
-fn function_agent_json_helpers_parse_ai_payloads_without_core_runtime() {
-    let commit = parse_commit_analysis_json(
-        r#"{
-            "type": "refactor",
-            "title": "refactor(product-domains): move parse helpers",
-            "body": "Keep runtime adapters in core.",
-            "confidence": 0.92
-        }"#,
-    )
-    .unwrap();
-    assert_eq!(commit.commit_type, CommitType::Refactor);
-    assert_eq!(
-        commit.title,
-        "refactor(product-domains): move parse helpers"
-    );
-    assert_eq!(
-        commit.body.as_deref(),
-        Some("Keep runtime adapters in core.")
-    );
-    assert_eq!(commit.confidence, 0.92);
-
-    let missing_title = parse_commit_analysis_json(r#"{"type":"fix"}"#).unwrap_err();
-    assert_eq!(missing_title, "Missing title field");
-
-    let invalid_commit = parse_commit_analysis_json("not json").unwrap_err();
-    assert!(invalid_commit.starts_with("Failed to parse AI response:"));
-
-    let work_state = parse_complete_analysis_json(
-        r#"{
-            "summary": "Working on product-domain owner closure.",
-            "predicted_actions": [
-                {"description": "Run checks", "priority": "High", "icon": "check", "is_reminder": false}
-            ],
-            "quick_actions": [
-                {"title": "Status", "command": "git status", "icon": "git", "action_type": "ViewStatus"}
-            ]
-        }"#,
-    )
-    .unwrap();
-    assert_eq!(
-        work_state.analysis.summary,
-        "Working on product-domain owner closure."
-    );
-    assert_eq!(work_state.predicted_actions_count, 1);
-    assert_eq!(work_state.quick_actions_count, 1);
-    assert_eq!(work_state.analysis.predicted_actions.len(), 3);
-    assert_eq!(work_state.analysis.quick_actions.len(), 1);
-
-    let invalid_work_state = parse_complete_analysis_json("not json").unwrap_err();
-    assert!(invalid_work_state.starts_with("Failed to parse complete analysis response:"));
-}
diff --git a/src/crates/contracts/product-domains/tests/plugin_source_contracts.rs b/src/crates/contracts/product-domains/tests/plugin_source_contracts.rs
index 6788520f06..75fa47a874 100644
--- a/src/crates/contracts/product-domains/tests/plugin_source_contracts.rs
+++ b/src/crates/contracts/product-domains/tests/plugin_source_contracts.rs
@@ -1,3 +1,5 @@
+#![cfg(feature = "plugin-source")]
+
 use bitfun_product_domains::plugin_source::{
     PluginPackageInput, PluginPackageManifest, PluginPackageSourceIdentity,
     PluginPackageTrustLevel, PluginTrustDecision, PluginTrustStore,
@@ -428,7 +430,8 @@ fn activation_lifecycle_is_exact_independent_and_idempotent() {
     assert_eq!((store.epoch(), store.activation_epoch()), (trust_epoch, 9));
     assert!(store
         .clear_activation_record(PROJECT, WORKSPACE, &package.package_id, None)
-        .expect("repeat deactivation").is_none());
+        .expect("repeat deactivation")
+        .is_none());
     assert_eq!((store.epoch(), store.activation_epoch()), (trust_epoch, 9));
 }
 
@@ -496,7 +499,8 @@ fn stale_residual_cleanup_cannot_clear_a_newer_activation() {
 
     assert!(store
         .clear_activation_record(PROJECT, WORKSPACE, &package.package_id, Some(stale_epoch),)
-        .expect("stale cleanup is a no-op").is_none());
+        .expect("stale cleanup is a no-op")
+        .is_none());
     assert!(store.is_activated(PROJECT, WORKSPACE, &package));
     assert_eq!(store.activation_epoch(), current_epoch);
 }
diff --git a/src/crates/contracts/product-domains/tests/product_domain_contracts.rs b/src/crates/contracts/product-domains/tests/product_domain_contracts.rs
new file mode 100644
index 0000000000..476faa8865
--- /dev/null
+++ b/src/crates/contracts/product-domains/tests/product_domain_contracts.rs
@@ -0,0 +1,4 @@
+#[path = "product_domain_contracts/canvas_contracts.rs"]
+mod canvas_contracts;
+#[path = "product_domain_contracts/tool_permission_contracts.rs"]
+mod tool_permission_contracts;
diff --git a/src/crates/contracts/product-domains/tests/canvas_contracts.rs b/src/crates/contracts/product-domains/tests/product_domain_contracts/canvas_contracts.rs
similarity index 100%
rename from src/crates/contracts/product-domains/tests/canvas_contracts.rs
rename to src/crates/contracts/product-domains/tests/product_domain_contracts/canvas_contracts.rs
diff --git a/src/crates/contracts/product-domains/tests/tool_permission_contracts.rs b/src/crates/contracts/product-domains/tests/product_domain_contracts/tool_permission_contracts.rs
similarity index 100%
rename from src/crates/contracts/product-domains/tests/tool_permission_contracts.rs
rename to src/crates/contracts/product-domains/tests/product_domain_contracts/tool_permission_contracts.rs
diff --git a/src/crates/contracts/runtime-ports/AGENTS.md b/src/crates/contracts/runtime-ports/AGENTS.md
index 82afbbb89f..bbcec6650a 100644
--- a/src/crates/contracts/runtime-ports/AGENTS.md
+++ b/src/crates/contracts/runtime-ports/AGENTS.md
@@ -30,11 +30,21 @@ facts. It is an interface crate, not a runtime implementation crate.
   concrete behavior, product policy, permission decisions, audit outcomes, UI
   extension behavior, UI implementation, or UI command logic here.
 - Preserve serialization compatibility for persisted or cross-process DTOs.
+- Keep `default = []`. Select `agent-api`, `workspace-ports`,
+  `terminal-port`, `remote-exec-port`, `remote-workspace-ports`, `git-port`,
+  `runtime-event-port`, `plugin-runtime`, or `script-tool-runtime` only from
+  the capability owner that consumes that surface.
+- `tool-runtime-handles` is the only reviewed aggregate: it is the stable
+  handle bundle shared by the tool-runtime owners. Do not add a general
+  `service-ports`, `full`, or compatibility umbrella.
 
 ## Verification
 
 ```bash
-cargo test -p bitfun-runtime-ports
+cargo check --locked -p bitfun-runtime-ports --no-default-features
+cargo test --locked -p bitfun-runtime-ports --no-default-features --features agent-api --lib
+cargo test --locked -p bitfun-runtime-ports --no-default-features --features workspace-ports --test session_store_contracts
+cargo test --locked -p bitfun-runtime-ports --no-default-features --features plugin-runtime --test plugin_runtime_contracts
 node scripts/check-core-boundaries.mjs
 ```
 
diff --git a/src/crates/contracts/runtime-ports/Cargo.toml b/src/crates/contracts/runtime-ports/Cargo.toml
index b142db5da6..aef7843ee7 100644
--- a/src/crates/contracts/runtime-ports/Cargo.toml
+++ b/src/crates/contracts/runtime-ports/Cargo.toml
@@ -4,24 +4,59 @@ version.workspace = true
 authors.workspace = true
 edition.workspace = true
 description = "Thin runtime ports for BitFun core decomposition"
+autotests = false
 
 [lib]
 name = "bitfun_runtime_ports"
 crate-type = ["rlib"]
 
+[[test]]
+name = "plugin_runtime_contracts"
+path = "tests/runtime_port_contracts.rs"
+required-features = ["plugin-runtime"]
+
+[[test]]
+name = "git_port_contracts"
+path = "tests/git_port_contracts.rs"
+required-features = ["git-port"]
+
+[[test]]
+name = "script_tool_port_contracts"
+path = "tests/script_tool_port_contracts.rs"
+required-features = ["script-tool-runtime"]
+
+[[test]]
+name = "session_store_contracts"
+path = "tests/session_store_contracts.rs"
+required-features = ["workspace-ports"]
+
 [dependencies]
-anyhow = { workspace = true }
+anyhow = { workspace = true, optional = true }
 async-trait = { workspace = true }
-bitfun-product-domains = { path = "../product-domains", default-features = false, optional = true }
-bitfun-core-types = { path = "../core-types" }
+bitfun-product-domains = { path = "../product-domains", optional = true }
+bitfun-core-types = { path = "../core-types", optional = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
-tokio = { workspace = true, features = ["sync"] }
-tokio-util = { workspace = true }
+tokio = { workspace = true, features = ["sync"], optional = true }
+tokio-util = { workspace = true, optional = true }
 ts-rs = { workspace = true, optional = true }
 
 [features]
 default = []
+agent-api = ["dep:bitfun-core-types"]
+plugin-runtime = []
+script-tool-runtime = []
+workspace-ports = ["dep:anyhow", "dep:tokio-util"]
+terminal-port = ["dep:tokio"]
+remote-exec-port = ["dep:tokio"]
+tool-runtime-handles = [
+    "workspace-ports",
+    "terminal-port",
+    "remote-exec-port",
+]
+remote-workspace-ports = []
+git-port = []
+runtime-event-port = []
 permission = ["dep:bitfun-product-domains"]
 # Derive `ts_rs::TS` on the wire types so downstream crates (app-server) can
 # export TypeScript bindings. The `permission` feature gates the product
@@ -32,6 +67,7 @@ permission = ["dep:bitfun-product-domains"]
 # undeclared owner of the optional product-domain dependency.
 ts = [
     "dep:ts-rs",
+    "agent-api",
     "permission",
     "bitfun-core-types/ts",
     "bitfun-product-domains?/ts",
diff --git a/src/crates/contracts/runtime-ports/src/agent_api.rs b/src/crates/contracts/runtime-ports/src/agent_api.rs
new file mode 100644
index 0000000000..c736008515
--- /dev/null
+++ b/src/crates/contracts/runtime-ports/src/agent_api.rs
@@ -0,0 +1,3410 @@
+use super::*;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSessionCreateRequest {
+    pub session_name: String,
+    pub agent_type: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub workspace_path: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub project_workspace_path: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub execution_target: Option<SessionExecutionTarget>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub workspace_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_connection_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_ssh_host: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub model_id: Option<String>,
+    #[serde(default, skip_serializing_if = "serde_json::Map::is_empty")]
+    pub metadata: serde_json::Map<String, serde_json::Value>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSessionCreateResult {
+    pub session_id: String,
+    #[serde(default)]
+    pub session_name: String,
+    pub agent_type: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub model_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub workspace_path: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub workspace_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub project_workspace_path: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub execution_target: Option<SessionExecutionTarget>,
+}
+
+impl AgentSessionCreateResult {
+    pub fn new(
+        session_id: impl Into<String>,
+        session_name: impl Into<String>,
+        agent_type: impl Into<String>,
+    ) -> Self {
+        Self {
+            session_id: session_id.into(),
+            session_name: session_name.into(),
+            agent_type: agent_type.into(),
+            model_id: None,
+            workspace_path: None,
+            workspace_id: None,
+            project_workspace_path: None,
+            execution_target: None,
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSessionListRequest {
+    pub workspace_path: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_connection_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_ssh_host: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSessionSummary {
+    pub session_id: String,
+    pub session_name: String,
+    pub agent_type: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub model_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub reasoning_preset: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub last_user_dialog_agent_type: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub last_submitted_agent_type: Option<String>,
+    #[serde(default)]
+    pub turn_count: usize,
+    pub created_at_ms: u64,
+    pub last_active_at_ms: u64,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSessionDeleteRequest {
+    pub workspace_path: String,
+    pub session_id: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_connection_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_ssh_host: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSessionRenameRequest {
+    pub workspace_path: String,
+    pub session_id: String,
+    pub session_name: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_connection_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_ssh_host: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSessionArchiveRequest {
+    pub workspace_path: String,
+    pub session_id: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_connection_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_ssh_host: Option<String>,
+}
+
+/// Sets the persisted archive state without exposing product-specific archive UI.
+///
+/// This is separate from [`AgentSessionArchiveRequest`] so existing archive-only
+/// consumers keep their current request shape and behavior.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSessionArchiveStateRequest {
+    pub workspace_path: String,
+    pub session_id: String,
+    pub archived: bool,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_connection_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_ssh_host: Option<String>,
+}
+
+/// Records one completed local command result in user-visible session history.
+///
+/// This request intentionally cannot select another turn kind or opt the turn
+/// into model context. It is not a generic transcript-writing contract.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentLocalCommandTurnRecordRequest {
+    pub session_id: String,
+    pub content: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub turn_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub timestamp_ms: Option<u64>,
+    #[serde(default, skip_serializing_if = "serde_json::Map::is_empty")]
+    pub metadata: serde_json::Map<String, serde_json::Value>,
+}
+
+/// The authoritative persisted identity assigned to a completed local command Turn.
+///
+/// The product-facing adapter may use this result to reconcile a provisional UI
+/// projection. Catalog data remains owned by the session persistence boundary.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentLocalCommandTurnRecordResult {
+    pub turn_id: String,
+    pub storage_turn_index: usize,
+}
+
+/// Starts one user-authored shell command as a normal, model-visible tool turn.
+///
+/// The caller provides the exact turn identity so interactive adapters can
+/// register cancellation before the side effect is admitted. Implementations
+/// must route execution through the normal tool, permission, and audit owners;
+/// this is not a generic process-spawn or arbitrary-tool contract.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AgentUserShellCommandRequest {
+    pub session_id: String,
+    pub turn_id: String,
+    pub command: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AgentUserShellCommandResult {
+    pub session_id: String,
+    pub turn_id: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSessionModelUpdateRequest {
+    pub session_id: String,
+    pub model_id: String,
+}
+
+/// Atomically selects a model and an optional reasoning preset for the next
+/// turn. The legacy model-only request remains available for older clients.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSessionModelSelection {
+    pub model_id: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub reasoning_preset: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSessionModelSelectionUpdateRequest {
+    pub session_id: String,
+    pub selection: AgentSessionModelSelection,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSessionModeUpdateRequest {
+    pub session_id: String,
+    pub mode_id: String,
+}
+
+/// Starts one audited manual context-compaction maintenance turn.
+///
+/// The caller supplies the exact turn identity so process adapters can register
+/// cancellation ownership before the side effect is admitted.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AgentSessionCompactionRequest {
+    pub session_id: String,
+    pub turn_id: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AgentSessionCompactionResult {
+    pub session_id: String,
+    pub turn_id: String,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum AgentContextReloadTarget {
+    All,
+    Skills,
+    Instructions,
+}
+
+impl AgentContextReloadTarget {
+    pub const fn includes_skills(self) -> bool {
+        matches!(self, Self::All | Self::Skills)
+    }
+
+    pub const fn includes_instructions(self) -> bool {
+        matches!(self, Self::All | Self::Instructions)
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AgentContextReloadRequest {
+    pub session_id: String,
+    pub target: AgentContextReloadTarget,
+}
+
+#[async_trait::async_trait]
+pub trait AgentContextReloadPort: Send + Sync {
+    async fn reload_session_context(&self, request: AgentContextReloadRequest) -> PortResult<()>;
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+/// Delivers answers to a pending user-question tool call.
+pub struct AgentUserAnswersRequest {
+    pub tool_id: String,
+    pub answers: serde_json::Value,
+}
+
+#[async_trait::async_trait]
+/// Routes product responses to the existing user-input owner.
+///
+/// Implementations do not own approval policy or interaction lifecycle state.
+pub trait AgentInteractionResponsePort: Send + Sync {
+    async fn submit_user_answers(&self, request: AgentUserAnswersRequest) -> PortResult<()>;
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSessionForkRequest {
+    pub workspace_path: String,
+    pub source_session_id: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_connection_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_ssh_host: Option<String>,
+}
+
+/// Forks a session at an explicitly selected persisted turn.
+///
+/// This is additive to [`AgentSessionForkRequest`] so existing Rust SDK
+/// consumers keep the source-compatible latest-turn request shape.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSessionForkAtTurnRequest {
+    pub workspace_path: String,
+    pub source_session_id: String,
+    pub source_turn_id: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_connection_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_ssh_host: Option<String>,
+}
+
+/// Forks a session immediately before an explicitly selected persisted turn.
+///
+/// The selected turn is the replayable prompt boundary and is not copied into
+/// the fork. This stays separate from [`AgentSessionForkAtTurnRequest`] so its
+/// inclusive behavior remains source- and behavior-compatible.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSessionForkBeforeTurnRequest {
+    pub workspace_path: String,
+    pub source_session_id: String,
+    pub source_turn_id: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_connection_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_ssh_host: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSessionForkResult {
+    pub session_id: String,
+    pub session_name: String,
+    pub agent_type: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSessionUsageRequest {
+    pub session_id: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub workspace_path: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_connection_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_ssh_host: Option<String>,
+    #[serde(default)]
+    pub include_hidden_subagents: bool,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentTurnSettlementRequest {
+    pub session_id: String,
+    pub turn_id: String,
+    pub wait_timeout_ms: u64,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSessionWorkspaceRequest {
+    pub session_id: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSessionWorkspaceBinding {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub workspace_id: Option<String>,
+    pub workspace_path: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub project_workspace_path: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub execution_target: Option<SessionExecutionTarget>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_connection_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_ssh_host: Option<String>,
+}
+
+pub const AGENT_WORKSPACE_REFERENCES_METADATA_KEY: &str = "workspace_references";
+pub const MAX_AGENT_WORKSPACE_REFERENCES_PER_TURN: usize = 20;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum AgentWorkspaceReferenceKind {
+    File,
+    Directory,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentWorkspaceReferenceSourceRange {
+    /// Zero-based character offset in the original user input.
+    pub start: usize,
+    /// Exclusive zero-based character offset in the original user input.
+    pub end: usize,
+    pub value: String,
+}
+
+/// A user-selected workspace path carried as structured turn metadata.
+///
+/// The path is workspace-relative and slash-normalized. It is not an
+/// authorization token: the runtime owner validates the current Session
+/// binding and path again before accepting the turn.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentWorkspaceReference {
+    pub path: String,
+    pub kind: AgentWorkspaceReferenceKind,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub start_line: Option<u32>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub end_line: Option<u32>,
+    pub source: AgentWorkspaceReferenceSourceRange,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentWorkspaceReferenceSearchRequest {
+    pub session_id: String,
+    #[serde(default)]
+    pub query: String,
+    pub limit: usize,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentWorkspaceReferenceSearchEntry {
+    pub path: String,
+    pub kind: AgentWorkspaceReferenceKind,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentWorkspaceReferenceSearchResult {
+    #[serde(default)]
+    pub entries: Vec<AgentWorkspaceReferenceSearchEntry>,
+    #[serde(default)]
+    pub truncated: bool,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentMessageWorkspaceReferencesRequest {
+    pub session_id: String,
+    pub message_id: String,
+}
+
+pub fn put_agent_workspace_references(
+    metadata: &mut serde_json::Map<String, serde_json::Value>,
+    references: &[AgentWorkspaceReference],
+) -> PortResult<()> {
+    if references.is_empty() {
+        metadata.remove(AGENT_WORKSPACE_REFERENCES_METADATA_KEY);
+        return Ok(());
+    }
+    if references.len() > MAX_AGENT_WORKSPACE_REFERENCES_PER_TURN {
+        return Err(PortError::new(
+            PortErrorKind::InvalidRequest,
+            format!(
+                "a message can reference at most {MAX_AGENT_WORKSPACE_REFERENCES_PER_TURN} workspace paths"
+            ),
+        ));
+    }
+    let value = serde_json::to_value(references).map_err(|error| {
+        PortError::new(
+            PortErrorKind::InvalidRequest,
+            format!("failed to serialize workspace references: {error}"),
+        )
+    })?;
+    metadata.insert(AGENT_WORKSPACE_REFERENCES_METADATA_KEY.to_string(), value);
+    Ok(())
+}
+
+pub fn agent_workspace_references_from_metadata(
+    metadata: &serde_json::Map<String, serde_json::Value>,
+) -> PortResult<Vec<AgentWorkspaceReference>> {
+    let Some(value) = metadata.get(AGENT_WORKSPACE_REFERENCES_METADATA_KEY) else {
+        return Ok(Vec::new());
+    };
+    let references: Vec<AgentWorkspaceReference> =
+        serde_json::from_value(value.clone()).map_err(|error| {
+            PortError::new(
+                PortErrorKind::InvalidRequest,
+                format!("invalid workspace reference metadata: {error}"),
+            )
+        })?;
+    if references.len() > MAX_AGENT_WORKSPACE_REFERENCES_PER_TURN {
+        return Err(PortError::new(
+            PortErrorKind::InvalidRequest,
+            format!(
+                "a message can reference at most {MAX_AGENT_WORKSPACE_REFERENCES_PER_TURN} workspace paths"
+            ),
+        ));
+    }
+    Ok(references)
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSubmissionRequest {
+    pub session_id: String,
+    pub message: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub turn_id: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub source: Option<AgentSubmissionSource>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub attachments: Vec<AgentInputAttachment>,
+    #[serde(default, skip_serializing_if = "serde_json::Map::is_empty")]
+    pub metadata: serde_json::Map<String, serde_json::Value>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(
+    tag = "kind",
+    rename_all = "snake_case",
+    rename_all_fields = "camelCase",
+    deny_unknown_fields
+)]
+pub enum AgentDialogTurnExecution {
+    Standard,
+    FreshExternalSubagent {
+        ecosystem_id: String,
+        logical_id: String,
+    },
+}
+
+impl Default for AgentDialogTurnExecution {
+    fn default() -> Self {
+        Self::Standard
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentDialogTurnRequest {
+    pub session_id: String,
+    pub message: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub original_message: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub turn_id: Option<String>,
+    #[serde(default, skip_serializing_if = "AgentDialogTurnExecution::is_standard")]
+    pub execution: AgentDialogTurnExecution,
+    pub agent_type: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub workspace_path: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_connection_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_ssh_host: Option<String>,
+    pub policy: DialogSubmissionPolicy,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub reply_route: Option<AgentSessionReplyRoute>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub prepended_reminders: Vec<AgentDialogPrependedReminder>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub attachments: Vec<AgentInputAttachment>,
+    #[serde(default, skip_serializing_if = "serde_json::Map::is_empty")]
+    pub metadata: serde_json::Map<String, serde_json::Value>,
+}
+
+/// Recover one settled interrupted user dialog without creating a new Turn.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "camelCase")]
+pub struct AgentDialogTurnRecoveryRequest {
+    pub session_id: String,
+    pub turn_id: String,
+    /// Compare-and-set generation observed by the caller.
+    pub execution_generation: u32,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub workspace_path: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_connection_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_ssh_host: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "camelCase")]
+pub struct AgentDialogTurnRecoveryOutcome {
+    pub session_id: String,
+    pub turn_id: String,
+    pub execution_generation: u32,
+}
+
+/// Steering request for one exact running dialog turn.
+///
+/// Carries the same payload shape as a turn submission: a mid-turn steering
+/// message is an ordinary user message that happens to arrive while a turn is
+/// running, so attachments and message metadata ride along with the text
+/// rather than forcing the user to wait for a turn boundary.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AgentDialogSteerRequest {
+    pub session_id: String,
+    pub turn_id: String,
+    pub content: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub display_content: Option<String>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub attachments: Vec<AgentInputAttachment>,
+    #[serde(default, skip_serializing_if = "serde_json::Map::is_empty")]
+    pub metadata: serde_json::Map<String, serde_json::Value>,
+}
+
+impl AgentDialogTurnExecution {
+    pub fn is_standard(&self) -> bool {
+        matches!(self, Self::Standard)
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentDialogPrependedReminder {
+    pub kind: String,
+    pub text: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentBackgroundResultRequest {
+    pub session_id: String,
+    pub agent_type: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub workspace_path: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_connection_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_ssh_host: Option<String>,
+    pub content: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub display_content: Option<String>,
+    #[serde(default, skip_serializing_if = "serde_json::Map::is_empty")]
+    pub metadata: serde_json::Map<String, serde_json::Value>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum AgentThreadGoalDeliveryKind {
+    Resumed,
+    ObjectiveUpdated,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentThreadGoalDeliveryRequest {
+    pub session_id: String,
+    pub agent_type: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub workspace_path: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_connection_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_ssh_host: Option<String>,
+    pub kind: AgentThreadGoalDeliveryKind,
+    pub goal: ThreadGoal,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "snake_case")]
+pub enum DialogQueuePriority {
+    Low = 0,
+    Normal = 1,
+    High = 2,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "camelCase")]
+pub struct DialogSubmissionPolicy {
+    pub trigger_source: DialogTriggerSource,
+    pub queue_priority: DialogQueuePriority,
+}
+
+impl DialogSubmissionPolicy {
+    pub const fn new(
+        trigger_source: DialogTriggerSource,
+        queue_priority: DialogQueuePriority,
+    ) -> Self {
+        Self {
+            trigger_source,
+            queue_priority,
+        }
+    }
+
+    pub const fn for_source(trigger_source: DialogTriggerSource) -> Self {
+        let queue_priority = match trigger_source {
+            DialogTriggerSource::AgentSession => DialogQueuePriority::Low,
+            DialogTriggerSource::ScheduledJob => DialogQueuePriority::Low,
+            DialogTriggerSource::DesktopUi
+            | DialogTriggerSource::DesktopApi
+            | DialogTriggerSource::Cli
+            | DialogTriggerSource::SdkHost => DialogQueuePriority::Normal,
+            DialogTriggerSource::RemoteRelay | DialogTriggerSource::Bot => {
+                DialogQueuePriority::Normal
+            }
+        };
+        Self::new(trigger_source, queue_priority)
+    }
+
+    pub const fn with_queue_priority(mut self, queue_priority: DialogQueuePriority) -> Self {
+        self.queue_priority = queue_priority;
+        self
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum DialogSubmitOutcome {
+    Started { session_id: String, turn_id: String },
+    Queued { session_id: String, turn_id: String },
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum DialogSessionStateFact {
+    Missing,
+    Idle,
+    Processing,
+    Error,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct DialogSubmitQueueFacts {
+    pub session_state: DialogSessionStateFact,
+    pub queue_has_items: bool,
+    pub policy: DialogSubmissionPolicy,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum DialogSubmitQueueAction {
+    StartImmediately,
+    ClearQueueAndStartImmediately,
+    EnqueueThenStartNext,
+    EnqueueForActiveTurn,
+}
+
+pub const fn resolve_dialog_submit_queue_action(
+    facts: DialogSubmitQueueFacts,
+) -> DialogSubmitQueueAction {
+    match facts.session_state {
+        DialogSessionStateFact::Missing => DialogSubmitQueueAction::StartImmediately,
+        DialogSessionStateFact::Error => DialogSubmitQueueAction::ClearQueueAndStartImmediately,
+        DialogSessionStateFact::Idle => {
+            if facts.queue_has_items {
+                DialogSubmitQueueAction::EnqueueThenStartNext
+            } else {
+                DialogSubmitQueueAction::StartImmediately
+            }
+        }
+        DialogSessionStateFact::Processing => DialogSubmitQueueAction::EnqueueForActiveTurn,
+    }
+}
+
+pub fn should_suppress_agent_session_cancelled_reply(
+    policy: &DialogSubmissionPolicy,
+    reply_source_session_id: Option<&str>,
+    requester_session_id: &str,
+) -> bool {
+    policy.trigger_source == DialogTriggerSource::AgentSession
+        && reply_source_session_id.is_some_and(|source| source == requester_session_id)
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum DialogTurnOutcomeKind {
+    Completed,
+    Cancelled,
+    Interrupted,
+    Failed,
+}
+
+pub const fn should_skip_agent_session_reply(
+    outcome_kind: DialogTurnOutcomeKind,
+    suppressed_cancelled_reply: bool,
+) -> bool {
+    matches!(outcome_kind, DialogTurnOutcomeKind::Interrupted)
+        || matches!(outcome_kind, DialogTurnOutcomeKind::Cancelled) && suppressed_cancelled_reply
+}
+
+/// Source session route used when an agent-session request should reply to the
+/// requester after the target session finishes.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSessionReplyRoute {
+    pub source_session_id: String,
+    pub source_workspace_path: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub source_remote_connection_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub source_remote_ssh_host: Option<String>,
+}
+
+/// Outcome for steering a message into an already-running dialog turn.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(
+    tag = "kind",
+    rename_all = "snake_case",
+    rename_all_fields = "camelCase",
+    deny_unknown_fields
+)]
+pub enum DialogSteerOutcome {
+    /// Steering was buffered for the running turn and will be consumed at the
+    /// next model-round boundary.
+    Buffered {
+        session_id: String,
+        turn_id: String,
+        steering_id: String,
+    },
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RoundInjectionKind {
+    UserSteering,
+    BackgroundResult,
+    ThreadGoalObjectiveUpdated,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub enum RoundInjectionToolPreemption {
+    None,
+    InterruptAfterCurrentAtomicUnit,
+    CancelRunningCooperatively,
+    CancelRunningForcefully,
+}
+
+impl RoundInjectionToolPreemption {
+    pub const fn should_interrupt_after_current_atomic_unit(self) -> bool {
+        !matches!(self, Self::None)
+    }
+
+    pub const fn should_cancel_running_tools(self) -> bool {
+        matches!(
+            self,
+            Self::CancelRunningCooperatively | Self::CancelRunningForcefully
+        )
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct RoundInjectionExecutionPolicy {
+    pub tool_preemption: RoundInjectionToolPreemption,
+}
+
+impl RoundInjectionExecutionPolicy {
+    pub const fn new(tool_preemption: RoundInjectionToolPreemption) -> Self {
+        Self { tool_preemption }
+    }
+}
+
+impl Default for RoundInjectionExecutionPolicy {
+    fn default() -> Self {
+        Self::new(RoundInjectionToolPreemption::None)
+    }
+}
+
+impl RoundInjectionKind {
+    pub const fn default_execution_policy(self) -> RoundInjectionExecutionPolicy {
+        match self {
+            Self::UserSteering => RoundInjectionExecutionPolicy::new(
+                RoundInjectionToolPreemption::InterruptAfterCurrentAtomicUnit,
+            ),
+            Self::BackgroundResult | Self::ThreadGoalObjectiveUpdated => {
+                RoundInjectionExecutionPolicy::new(RoundInjectionToolPreemption::None)
+            }
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum RoundInjectionTarget {
+    /// Only inject into the exact targeted running turn.
+    ExactTurn(String),
+    /// Inject into whichever turn is currently running for the session.
+    CurrentRunningTurn,
+}
+
+/// A message to inject into the currently running dialog turn at the next
+/// model-round boundary.
+#[derive(Debug, Clone, PartialEq)]
+pub struct RoundInjection {
+    pub id: String,
+    pub kind: RoundInjectionKind,
+    pub execution_policy: RoundInjectionExecutionPolicy,
+    pub target: RoundInjectionTarget,
+    pub content: String,
+    pub display_content: String,
+    /// Attachments that ride into the running turn with the injected message.
+    /// Consumers rebuild them into a multimodal user message, so a steering
+    /// message with images is no different from one sent at a turn boundary.
+    pub attachments: Vec<AgentInputAttachment>,
+    /// Message metadata carried alongside the injected content (same shape as
+    /// a turn submission's `metadata`).
+    pub metadata: serde_json::Map<String, serde_json::Value>,
+    pub created_at: std::time::SystemTime,
+}
+
+/// Observes round-boundary injections for a given running turn.
+pub trait DialogRoundInjectionSource: Send + Sync {
+    fn has_pending(&self, session_id: &str, turn_id: &str) -> bool;
+    fn pending_tool_preemption(
+        &self,
+        session_id: &str,
+        turn_id: &str,
+    ) -> RoundInjectionToolPreemption;
+    fn take_pending(&self, session_id: &str, turn_id: &str) -> Vec<RoundInjection>;
+
+    fn acknowledge_consumed(
+        &self,
+        _session_id: &str,
+        _turn_id: &str,
+        _injection_id: &str,
+        _kind: RoundInjectionKind,
+    ) {
+    }
+}
+
+/// Legacy session metadata key for the pre-Codex goal mode experiment.
+pub const GOAL_MODE_METADATA_KEY: &str = "goal_mode";
+
+/// Persisted thread goal stored in session custom metadata.
+pub const THREAD_GOAL_METADATA_KEY: &str = "thread_goal";
+
+pub const MAX_THREAD_GOAL_OBJECTIVE_CHARS: usize = 4_000;
+
+pub const MAX_CONTEXT_SUMMARY_CHARS: usize = 12_000;
+
+/// Max automatic goal continuation dialog turns per objective (legacy goal_mode parity).
+pub const MAX_THREAD_GOAL_AUTO_CONTINUATIONS: u32 = 100;
+
+/// Alias retained for migration from legacy `goal_mode` metadata and docs.
+pub const MAX_GOAL_CONTINUATIONS: u32 = MAX_THREAD_GOAL_AUTO_CONTINUATIONS;
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub enum ThreadGoalStatus {
+    Active,
+    Paused,
+    Blocked,
+    UsageLimited,
+    BudgetLimited,
+    Complete,
+}
+
+impl ThreadGoalStatus {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Active => "active",
+            Self::Paused => "paused",
+            Self::Blocked => "blocked",
+            Self::UsageLimited => "usageLimited",
+            Self::BudgetLimited => "budgetLimited",
+            Self::Complete => "complete",
+        }
+    }
+}
+
+pub fn validate_thread_goal_objective(value: &str) -> Result<(), String> {
+    if value.trim().is_empty() {
+        return Err("goal objective must not be empty".to_string());
+    }
+    if value.chars().count() > MAX_THREAD_GOAL_OBJECTIVE_CHARS {
+        return Err(format!(
+            "goal objective must be at most {MAX_THREAD_GOAL_OBJECTIVE_CHARS} characters"
+        ));
+    }
+    Ok(())
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct ThreadGoal {
+    pub goal_id: String,
+    pub session_id: String,
+    pub objective: String,
+    pub status: ThreadGoalStatus,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub token_budget: Option<i64>,
+    #[serde(default)]
+    pub tokens_used: i64,
+    #[serde(default)]
+    pub time_used_seconds: i64,
+    pub created_at: i64,
+    pub updated_at: i64,
+    /// Auto-continuation dialog turns scheduled toward this goal (resets on new objective).
+    #[serde(default)]
+    pub auto_continuation_count: u32,
+}
+
+impl ThreadGoal {
+    pub fn is_active(&self) -> bool {
+        matches!(
+            self.status,
+            ThreadGoalStatus::Active | ThreadGoalStatus::BudgetLimited
+        )
+    }
+
+    pub fn remaining_tokens(&self) -> Option<i64> {
+        self.token_budget
+            .map(|budget| (budget - self.tokens_used).max(0))
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SetThreadGoalResult {
+    pub goal: ThreadGoal,
+    pub replaced_existing: bool,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ThreadGoalContinuationPlan {
+    pub prepended_reminders: Vec<String>,
+    pub display_message: String,
+    pub user_message_metadata: serde_json::Value,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct ThreadGoalToolResponse {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub goal: Option<ThreadGoal>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remaining_tokens: Option<i64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub completion_budget_report: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentThreadGoalGetRequest {
+    pub session_id: String,
+    pub workspace_path: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_connection_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_ssh_host: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentThreadGoalCreateRequest {
+    pub session_id: String,
+    pub workspace_path: String,
+    pub objective: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub token_budget: Option<i64>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentThreadGoalUpdateStatusRequest {
+    pub session_id: String,
+    pub workspace_path: String,
+    pub status: ThreadGoalStatus,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub turn_id: Option<String>,
+}
+
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct CompressionContract {
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub touched_files: Vec<String>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub verification_commands: Vec<CompressionContractItem>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub blocking_failures: Vec<CompressionContractItem>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub subagent_statuses: Vec<CompressionContractItem>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct CompressionContractItem {
+    pub target: String,
+    pub status: String,
+    pub summary: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub error_kind: Option<String>,
+}
+
+impl CompressionContract {
+    pub fn is_empty(&self) -> bool {
+        self.touched_files.is_empty()
+            && self.verification_commands.is_empty()
+            && self.blocking_failures.is_empty()
+            && self.subagent_statuses.is_empty()
+    }
+
+    pub fn render_for_model(&self) -> String {
+        let mut lines = vec![
+            "The following facts were retained during compression. Use them as authoritative context when continuing the task."
+                .to_string(),
+        ];
+
+        if !self.touched_files.is_empty() {
+            lines.push("Touched files:".to_string());
+            for file in &self.touched_files {
+                lines.push(format!("- {}", file));
+            }
+        }
+
+        render_contract_items(
+            &mut lines,
+            "Verification commands:",
+            &self.verification_commands,
+        );
+        render_contract_items(&mut lines, "Blocking failures:", &self.blocking_failures);
+        render_contract_items(&mut lines, "Subagent statuses:", &self.subagent_statuses);
+
+        lines.join("\n")
+    }
+}
+
+fn render_contract_items(lines: &mut Vec<String>, title: &str, items: &[CompressionContractItem]) {
+    if items.is_empty() {
+        return;
+    }
+
+    lines.push(title.to_string());
+    for item in items {
+        let mut rendered = format!("- {} [{}]: {}", item.target, item.status, item.summary);
+        if let Some(error_kind) = item.error_kind.as_ref() {
+            rendered.push_str(&format!(" ({})", error_kind));
+        }
+        lines.push(rendered);
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "camelCase")]
+pub struct AgentInputAttachment {
+    pub kind: String,
+    pub id: String,
+    #[serde(default, skip_serializing_if = "serde_json::Map::is_empty")]
+    pub metadata: serde_json::Map<String, serde_json::Value>,
+}
+
+impl AgentInputAttachment {
+    pub fn remote_image(
+        id: impl Into<String>,
+        name: impl Into<String>,
+        data_url: impl Into<String>,
+    ) -> Self {
+        let mut metadata = serde_json::Map::new();
+        metadata.insert("name".to_string(), serde_json::Value::String(name.into()));
+        metadata.insert(
+            "dataUrl".to_string(),
+            serde_json::Value::String(data_url.into()),
+        );
+
+        Self {
+            kind: "remote_image".to_string(),
+            id: id.into(),
+            metadata,
+        }
+    }
+
+    /// Build a `remote_image` attachment from a renderer image context.
+    ///
+    /// Either `image_path` or `data_url` must be present — consumers reject an
+    /// attachment carrying neither.
+    pub fn image_context(
+        id: impl Into<String>,
+        image_path: Option<String>,
+        data_url: Option<String>,
+        mime_type: impl Into<String>,
+        context_metadata: Option<serde_json::Value>,
+    ) -> Self {
+        let mut metadata = serde_json::Map::new();
+        if let Some(image_path) = image_path {
+            metadata.insert(
+                "imagePath".to_string(),
+                serde_json::Value::String(image_path),
+            );
+        }
+        if let Some(data_url) = data_url {
+            metadata.insert("dataUrl".to_string(), serde_json::Value::String(data_url));
+        }
+        metadata.insert(
+            "mimeType".to_string(),
+            serde_json::Value::String(mime_type.into()),
+        );
+        if let Some(context_metadata) = context_metadata {
+            metadata.insert("metadata".to_string(), context_metadata);
+        }
+
+        Self {
+            kind: "remote_image".to_string(),
+            id: id.into(),
+            metadata,
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSubmissionResult {
+    pub turn_id: String,
+    #[serde(default)]
+    pub accepted: bool,
+}
+
+#[async_trait::async_trait]
+pub trait AgentSubmissionPort: Send + Sync {
+    async fn create_session(
+        &self,
+        request: AgentSessionCreateRequest,
+    ) -> PortResult<AgentSessionCreateResult>;
+
+    /// Creates a session with an exact caller-provided identity.
+    ///
+    /// Providers that do not support exact identity creation keep the default
+    /// typed unsupported response. A successful response must preserve
+    /// `session_id` exactly.
+    async fn create_session_with_id(
+        &self,
+        session_id: String,
+        request: AgentSessionCreateRequest,
+    ) -> PortResult<AgentSessionCreateResult> {
+        let _ = (session_id, request);
+        Err(PortError::new(
+            PortErrorKind::NotAvailable,
+            "exact session identity creation is not supported by this provider",
+        ))
+    }
+
+    /// Creates one caller-identified connection-scoped Session.
+    ///
+    /// The Session uses the normal Runtime owners but must not become durable
+    /// product state. This narrow operation lets process adapters provide
+    /// bounded cleanup without pretending that crash-safe durable creation has
+    /// already been specified.
+    async fn create_transient_session_with_id(
+        &self,
+        session_id: String,
+        request: AgentSessionCreateRequest,
+    ) -> PortResult<AgentSessionCreateResult> {
+        let _ = (session_id, request);
+        Err(PortError::new(
+            PortErrorKind::NotAvailable,
+            "transient exact session creation is not supported by this provider",
+        ))
+    }
+
+    async fn submit_message(
+        &self,
+        request: AgentSubmissionRequest,
+    ) -> PortResult<AgentSubmissionResult>;
+
+    async fn resolve_session_agent_type(&self, session_id: &str) -> PortResult<Option<String>>;
+}
+
+#[async_trait::async_trait]
+pub trait AgentSessionManagementPort: Send + Sync {
+    async fn list_sessions(
+        &self,
+        request: AgentSessionListRequest,
+    ) -> PortResult<Vec<AgentSessionSummary>>;
+
+    async fn delete_session(&self, request: AgentSessionDeleteRequest) -> PortResult<()>;
+
+    async fn rename_session(&self, request: AgentSessionRenameRequest) -> PortResult<()> {
+        let _ = request;
+        Err(PortError::new(
+            PortErrorKind::NotAvailable,
+            "session rename is not supported by this provider",
+        ))
+    }
+
+    async fn archive_session(&self, request: AgentSessionArchiveRequest) -> PortResult<()> {
+        let _ = request;
+        Err(PortError::new(
+            PortErrorKind::NotAvailable,
+            "session archive is not supported by this provider",
+        ))
+    }
+
+    async fn set_session_archived(
+        &self,
+        request: AgentSessionArchiveStateRequest,
+    ) -> PortResult<()> {
+        if request.archived {
+            return self
+                .archive_session(AgentSessionArchiveRequest {
+                    workspace_path: request.workspace_path,
+                    session_id: request.session_id,
+                    remote_connection_id: request.remote_connection_id,
+                    remote_ssh_host: request.remote_ssh_host,
+                })
+                .await;
+        }
+        Err(PortError::new(
+            PortErrorKind::NotAvailable,
+            "session unarchive is not supported by this provider",
+        ))
+    }
+
+    async fn resolve_session_workspace_binding(
+        &self,
+        request: AgentSessionWorkspaceRequest,
+    ) -> PortResult<Option<AgentSessionWorkspaceBinding>>;
+}
+
+/// Provider-neutral lifecycle facts needed to render a Session lineage.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum AgentSessionLifecycleStatus {
+    Active,
+    Archived,
+    Completed,
+}
+
+/// Minimal Session facts exposed by the Runtime lineage capability.
+///
+/// This intentionally does not mirror the persistence owner's full metadata
+/// object. Product surfaces receive only the stable facts required for
+/// navigation and status display.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSessionLineageEntry {
+    pub session_id: String,
+    pub session_name: String,
+    pub agent_type: String,
+    pub created_at_ms: u64,
+    pub status: AgentSessionLifecycleStatus,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub active_turn_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub parent_session_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub parent_tool_call_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub subagent_type: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub workspace_path: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_connection_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_ssh_host: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub unread_completion: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub needs_user_attention: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSessionLineageSnapshot {
+    pub root_session_id: String,
+    #[serde(default)]
+    pub sessions: Vec<AgentSessionLineageEntry>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSessionLineageRequest {
+    pub workspace_path: String,
+    pub anchor_session_id: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_connection_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_ssh_host: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSessionLineageTranscriptRequest {
+    pub workspace_path: String,
+    pub root_session_id: String,
+    pub session_id: String,
+    /// Terminal Turns that an authoritative read must prove settled. This is a
+    /// read-consistency precondition; settlement and transcript construction
+    /// remain Runtime-owned.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub required_settled_turn_ids: Vec<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_connection_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_ssh_host: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSessionLineageInspection {
+    pub transcript: SessionTranscript,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub active_turn_id: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSessionLineageCancellationRequest {
+    pub workspace_path: String,
+    pub root_session_id: String,
+    pub session_id: String,
+    /// Exact Turn shown as active when the user requested interruption. The
+    /// Runtime rejects a changed target instead of cancelling a newer Turn.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub expected_active_turn_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub source: Option<AgentSubmissionSource>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub reason: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub wait_timeout_ms: Option<u64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_connection_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_ssh_host: Option<String>,
+}
+
+/// Authoritative Session-lineage use cases shared by product surfaces.
+///
+/// The provider owns persistence scope, legacy relationship normalization,
+/// membership/order, and consistent transcript reads. Surfaces may project
+/// the returned flat snapshot into their own tree presentation, but must not
+/// recompute lineage facts or read Session files directly.
+#[async_trait::async_trait]
+pub trait AgentSessionLineagePort: Send + Sync {
+    async fn get_session_lineage(
+        &self,
+        request: AgentSessionLineageRequest,
+    ) -> PortResult<Option<AgentSessionLineageSnapshot>>;
+
+    async fn read_lineage_session_transcript(
+        &self,
+        request: AgentSessionLineageTranscriptRequest,
+    ) -> PortResult<AgentSessionLineageInspection>;
+
+    async fn cancel_lineage_session(
+        &self,
+        request: AgentSessionLineageCancellationRequest,
+    ) -> PortResult<AgentTurnCancellationResult>;
+}
+
+/// Narrow workspace-reference use cases shared by first-party interactive
+/// adapters. Implementations keep filesystem search and persisted message
+/// lookup behind the authoritative Session owner.
+#[async_trait::async_trait]
+pub trait AgentWorkspaceReferencePort: Send + Sync {
+    async fn search_workspace_references(
+        &self,
+        request: AgentWorkspaceReferenceSearchRequest,
+    ) -> PortResult<AgentWorkspaceReferenceSearchResult>;
+
+    async fn workspace_references_for_message(
+        &self,
+        request: AgentMessageWorkspaceReferencesRequest,
+    ) -> PortResult<Vec<AgentWorkspaceReference>>;
+}
+
+/// Deadline-bearing request for discarding a connection-scoped transient
+/// Session. This is separate from [`AgentSessionDeleteRequest`] so adding Host
+/// cleanup policy cannot break the established Rust Session-management API.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AgentTransientSessionDiscardRequest {
+    pub workspace_path: String,
+    pub session_id: String,
+    pub remote_connection_id: Option<String>,
+    pub remote_ssh_host: Option<String>,
+    pub wait_timeout_ms: u64,
+}
+
+/// Runtime lifecycle owner for connection-scoped Session cleanup.
+#[async_trait::async_trait]
+pub trait AgentSessionClosePort: Send + Sync {
+    /// Quiesces and discards only a loaded transient Session owned by the
+    /// caller. Implementations must reject durable Sessions and must never
+    /// remove persisted Session storage through this operation.
+    async fn discard_transient_session(
+        &self,
+        request: AgentTransientSessionDiscardRequest,
+    ) -> PortResult<bool> {
+        let _ = request;
+        Err(PortError::new(
+            PortErrorKind::NotAvailable,
+            "transient session discard is not supported by this provider",
+        ))
+    }
+}
+
+#[async_trait::async_trait]
+pub trait AgentLocalCommandTurnPort: Send + Sync {
+    async fn record_completed_local_command_turn(
+        &self,
+        request: AgentLocalCommandTurnRecordRequest,
+    ) -> PortResult<AgentLocalCommandTurnRecordResult>;
+}
+
+#[async_trait::async_trait]
+pub trait AgentUserShellCommandPort: Send + Sync {
+    async fn run_user_shell_command(
+        &self,
+        request: AgentUserShellCommandRequest,
+    ) -> PortResult<AgentUserShellCommandResult>;
+}
+
+#[async_trait::async_trait]
+pub trait AgentSessionModelPort: Send + Sync {
+    async fn update_session_model_selection(
+        &self,
+        request: AgentSessionModelSelectionUpdateRequest,
+    ) -> PortResult<()>;
+
+    async fn update_session_model(
+        &self,
+        request: AgentSessionModelUpdateRequest,
+    ) -> PortResult<()> {
+        self.update_session_model_selection(AgentSessionModelSelectionUpdateRequest {
+            session_id: request.session_id,
+            selection: AgentSessionModelSelection {
+                model_id: request.model_id,
+                reasoning_preset: None,
+            },
+        })
+        .await
+    }
+}
+
+#[async_trait::async_trait]
+pub trait AgentSessionModePort: Send + Sync {
+    async fn update_session_mode(&self, request: AgentSessionModeUpdateRequest) -> PortResult<()>;
+}
+
+#[async_trait::async_trait]
+pub trait AgentSessionCompactionPort: Send + Sync {
+    async fn start_session_compaction(
+        &self,
+        request: AgentSessionCompactionRequest,
+    ) -> PortResult<AgentSessionCompactionResult>;
+}
+
+/// Local Session history mutation requested by an interactive product surface.
+///
+/// This is deliberately narrower than a generic checkpoint or workspace rewind
+/// API: one Core-owned operation keeps the persisted transcript, model context,
+/// and tracked workspace files on the same staged boundary.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSessionRevertRequest {
+    pub workspace_path: String,
+    pub session_id: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_connection_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_ssh_host: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSessionRollbackToTurnRequest {
+    pub workspace_path: String,
+    pub session_id: String,
+    pub target_turn_id: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub expected_storage_turn_index: Option<usize>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub expected_catalog_revision: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_connection_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_ssh_host: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub enum AgentSessionComposerUpdate {
+    Preserve,
+    Replace { text: String },
+    Clear,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentSessionRevertResult {
+    pub session_id: String,
+    pub transcript: SessionTranscript,
+    pub composer: AgentSessionComposerUpdate,
+    /// Active and queued Turns retired by the maintenance boundary. Consumers
+    /// use this as an event-stream fence after replacing their local projection.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub retired_turn_ids: Vec<String>,
+    pub changed: bool,
+    pub hidden_turn_count: usize,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub boundary_storage_turn_index: Option<usize>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub target_turn_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub restored_files: Vec<String>,
+    /// The mutation committed, but the response could not include an
+    /// authoritative transcript. Consumers must reload before using their
+    /// local Session projection.
+    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+    pub reload_required: bool,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub reload_reason: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(
+    tag = "status",
+    rename_all = "snake_case",
+    rename_all_fields = "camelCase"
+)]
+pub enum AgentSessionRollbackToTurnOutcome {
+    Completed {
+        #[serde(flatten)]
+        result: AgentSessionRevertResult,
+    },
+    RecoveryRequired {
+        session_id: String,
+        mutation_id: String,
+        #[serde(default, skip_serializing_if = "Vec::is_empty")]
+        affected_files: Vec<String>,
+        reason: String,
+    },
+}
+
+#[async_trait::async_trait]
+pub trait AgentSessionRevertPort: Send + Sync {
+    async fn undo_session(
+        &self,
+        request: AgentSessionRevertRequest,
+    ) -> PortResult<AgentSessionRevertResult>;
+
+    async fn redo_session(
+        &self,
+        request: AgentSessionRevertRequest,
+    ) -> PortResult<AgentSessionRevertResult>;
+
+    async fn rollback_session_to_turn(
+        &self,
+        request: AgentSessionRollbackToTurnRequest,
+    ) -> PortResult<AgentSessionRollbackToTurnOutcome> {
+        let _ = request;
+        Err(PortError::new(
+            PortErrorKind::NotAvailable,
+            "targeted Session rollback is not supported",
+        ))
+    }
+}
+
+#[async_trait::async_trait]
+pub trait AgentSessionForkPort: Send + Sync {
+    async fn fork_session(
+        &self,
+        request: AgentSessionForkRequest,
+    ) -> PortResult<AgentSessionForkResult>;
+
+    async fn fork_session_at_turn(
+        &self,
+        request: AgentSessionForkAtTurnRequest,
+    ) -> PortResult<AgentSessionForkResult> {
+        let _ = request;
+        Err(PortError::new(
+            PortErrorKind::NotAvailable,
+            "exact-turn session fork is not supported by this provider",
+        ))
+    }
+
+    async fn fork_session_before_turn(
+        &self,
+        request: AgentSessionForkBeforeTurnRequest,
+    ) -> PortResult<AgentSessionForkResult> {
+        let _ = request;
+        Err(PortError::new(
+            PortErrorKind::NotAvailable,
+            "before-turn session fork is not supported by this provider",
+        ))
+    }
+}
+
+#[async_trait::async_trait]
+pub trait AgentSessionUsagePort: Send + Sync {
+    async fn generate_session_usage(
+        &self,
+        request: AgentSessionUsageRequest,
+    ) -> PortResult<bitfun_core_types::SessionUsageReport>;
+}
+
+#[async_trait::async_trait]
+pub trait AgentTurnSettlementPort: Send + Sync {
+    async fn wait_for_turn_settlement(&self, request: AgentTurnSettlementRequest)
+        -> PortResult<()>;
+}
+
+#[async_trait::async_trait]
+pub trait AgentDialogTurnPort: Send + Sync {
+    async fn submit_dialog_turn(
+        &self,
+        request: AgentDialogTurnRequest,
+    ) -> PortResult<DialogSubmitOutcome>;
+
+    async fn steer_dialog_turn(
+        &self,
+        _request: AgentDialogSteerRequest,
+    ) -> PortResult<DialogSteerOutcome> {
+        Err(PortError::new(
+            PortErrorKind::NotAvailable,
+            "dialog turn steering is not supported by this provider",
+        ))
+    }
+
+    async fn recover_interrupted_turn(
+        &self,
+        _request: AgentDialogTurnRecoveryRequest,
+    ) -> PortResult<AgentDialogTurnRecoveryOutcome> {
+        Err(PortError::new(
+            PortErrorKind::NotAvailable,
+            "interrupted dialog turn recovery is not supported by this provider",
+        ))
+    }
+}
+
+#[async_trait::async_trait]
+pub trait AgentLifecycleDeliveryPort: Send + Sync {
+    async fn deliver_background_result(
+        &self,
+        request: AgentBackgroundResultRequest,
+    ) -> PortResult<()>;
+
+    async fn deliver_thread_goal(&self, request: AgentThreadGoalDeliveryRequest) -> PortResult<()>;
+}
+
+#[async_trait::async_trait]
+pub trait AgentThreadGoalManagementPort: Send + Sync {
+    async fn get_thread_goal(
+        &self,
+        request: AgentThreadGoalGetRequest,
+    ) -> PortResult<Option<ThreadGoal>>;
+
+    async fn create_thread_goal(
+        &self,
+        request: AgentThreadGoalCreateRequest,
+    ) -> PortResult<ThreadGoal>;
+
+    async fn update_thread_goal_status(
+        &self,
+        request: AgentThreadGoalUpdateStatusRequest,
+    ) -> PortResult<ThreadGoal>;
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "camelCase")]
+pub struct AgentTurnCancellationRequest {
+    pub session_id: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub turn_id: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub source: Option<AgentSubmissionSource>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub requester_session_id: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub reason: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub wait_timeout_ms: Option<u64>,
+    /// Whether a Session-wide cancellation also cascades into descendants.
+    #[serde(default = "default_cancel_descendants")]
+    pub cancel_descendants: bool,
+}
+
+fn default_cancel_descendants() -> bool {
+    true
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "camelCase")]
+pub struct AgentTurnCancellationResult {
+    pub session_id: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub turn_id: Option<String>,
+    #[serde(default)]
+    pub requested: bool,
+}
+
+/// Request an intentional, recoverable interruption of one active Turn.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "camelCase")]
+pub struct AgentTurnInterruptionRequest {
+    pub session_id: String,
+    pub turn_id: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub source: Option<AgentSubmissionSource>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub wait_timeout_ms: Option<u64>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "camelCase")]
+pub struct AgentTurnInterruptionResult {
+    pub session_id: String,
+    pub turn_id: String,
+    pub requested: bool,
+}
+
+#[async_trait::async_trait]
+pub trait AgentTurnCancellationPort: Send + Sync {
+    async fn cancel_turn(
+        &self,
+        request: AgentTurnCancellationRequest,
+    ) -> PortResult<AgentTurnCancellationResult>;
+
+    async fn interrupt_turn(
+        &self,
+        _request: AgentTurnInterruptionRequest,
+    ) -> PortResult<AgentTurnInterruptionResult> {
+        Err(PortError::new(
+            PortErrorKind::NotAvailable,
+            "recoverable interruption is not supported by this provider",
+        ))
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum RemoteControlSessionState {
+    Idle,
+    Processing,
+    Error,
+    Missing,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RemoteControlStateRequest {
+    pub session_id: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RemoteControlStateSnapshot {
+    pub session_id: String,
+    pub state: RemoteControlSessionState,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub active_turn_id: Option<String>,
+    #[serde(default)]
+    pub queue_depth: usize,
+    #[serde(default, skip_serializing_if = "serde_json::Map::is_empty")]
+    pub metadata: serde_json::Map<String, serde_json::Value>,
+}
+
+#[async_trait::async_trait]
+pub trait RemoteControlStatePort: Send + Sync {
+    async fn read_remote_control_state(
+        &self,
+        request: RemoteControlStateRequest,
+    ) -> PortResult<Option<RemoteControlStateSnapshot>>;
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SessionTranscriptRequest {
+    pub session_id: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub turn_id: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SessionTranscript {
+    pub session_id: String,
+    #[serde(default)]
+    pub messages: Vec<TranscriptMessage>,
+}
+
+/// Read-only transcript content shared by runtime consumers.
+///
+/// This projection preserves portable history facts without exposing the Core persistence
+/// message type. Multimodal entries report attachment counts rather than transporting image
+/// payloads; callers that need attachment content require a separate, authorized capability.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub enum TranscriptContent {
+    Text(String),
+    Multimodal {
+        text: String,
+        image_count: usize,
+    },
+    ToolResult {
+        tool_id: String,
+        tool_name: String,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        effective_tool_name: Option<String>,
+        result: serde_json::Value,
+        is_error: bool,
+    },
+    Mixed {
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        reasoning_content: Option<String>,
+        text: String,
+        #[serde(default)]
+        tool_calls: Vec<TranscriptToolCall>,
+    },
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct TranscriptToolCall {
+    pub tool_id: String,
+    pub tool_name: String,
+    #[serde(default)]
+    pub arguments: serde_json::Value,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct TranscriptMessage {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub id: Option<String>,
+    pub role: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub turn_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub timestamp_ms: Option<u64>,
+    pub content: TranscriptContent,
+}
+
+#[async_trait::async_trait]
+pub trait SessionTranscriptReader: Send + Sync {
+    async fn read_session_transcript(
+        &self,
+        request: SessionTranscriptRequest,
+    ) -> PortResult<SessionTranscript>;
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::Mutex;
+
+    #[test]
+    fn session_revert_contract_preserves_authoritative_transcript_and_composer_intent() {
+        let result = AgentSessionRevertResult {
+            session_id: "session-1".to_string(),
+            transcript: SessionTranscript {
+                session_id: "session-1".to_string(),
+                messages: Vec::new(),
+            },
+            composer: AgentSessionComposerUpdate::Replace {
+                text: "restore this prompt".to_string(),
+            },
+            retired_turn_ids: vec!["turn-2".to_string(), "turn-queued".to_string()],
+            changed: true,
+            hidden_turn_count: 2,
+            boundary_storage_turn_index: Some(7),
+            target_turn_id: Some("turn-1".to_string()),
+            restored_files: vec!["src/lib.rs".to_string()],
+            reload_required: false,
+            reload_reason: None,
+        };
+
+        let value = serde_json::to_value(&result).expect("session revert result should serialize");
+        assert_eq!(value["sessionId"], "session-1");
+        assert_eq!(value["composer"]["kind"], "replace");
+        assert_eq!(value["composer"]["text"], "restore this prompt");
+        assert_eq!(value["hiddenTurnCount"], 2);
+        assert_eq!(value["retiredTurnIds"][1], "turn-queued");
+        assert!(value.get("reloadRequired").is_none());
+        assert!(value.get("reloadReason").is_none());
+        assert_eq!(
+            serde_json::from_value::<AgentSessionRevertResult>(value)
+                .expect("session revert result should deserialize"),
+            result
+        );
+    }
+
+    #[test]
+    fn targeted_session_rollback_contract_uses_camel_case_and_typed_outcomes() {
+        let request = AgentSessionRollbackToTurnRequest {
+            workspace_path: "E:/workspace".to_string(),
+            session_id: "session-1".to_string(),
+            target_turn_id: "turn-7".to_string(),
+            expected_storage_turn_index: Some(7),
+            expected_catalog_revision: Some("catalog-3".to_string()),
+            remote_connection_id: None,
+            remote_ssh_host: None,
+        };
+        let request_json = serde_json::to_value(&request).expect("serialize rollback request");
+        assert_eq!(request_json["workspacePath"], "E:/workspace");
+        assert_eq!(request_json["targetTurnId"], "turn-7");
+        assert_eq!(request_json["expectedStorageTurnIndex"], 7);
+        assert_eq!(request_json["expectedCatalogRevision"], "catalog-3");
+        assert_eq!(
+            serde_json::from_value::<AgentSessionRollbackToTurnRequest>(request_json)
+                .expect("deserialize rollback request"),
+            request
+        );
+
+        let completed = AgentSessionRollbackToTurnOutcome::Completed {
+            result: AgentSessionRevertResult {
+                session_id: "session-1".to_string(),
+                transcript: SessionTranscript {
+                    session_id: "session-1".to_string(),
+                    messages: Vec::new(),
+                },
+                composer: AgentSessionComposerUpdate::Preserve,
+                retired_turn_ids: vec!["turn-7".to_string()],
+                changed: true,
+                hidden_turn_count: 1,
+                boundary_storage_turn_index: Some(7),
+                target_turn_id: Some("turn-7".to_string()),
+                restored_files: vec!["src/lib.rs".to_string()],
+                reload_required: true,
+                reload_reason: Some("transcript read failed".to_string()),
+            },
+        };
+        let completed_json =
+            serde_json::to_value(&completed).expect("serialize completed rollback");
+        assert_eq!(completed_json["status"], "completed");
+        assert_eq!(completed_json["boundaryStorageTurnIndex"], 7);
+        assert_eq!(completed_json["retiredTurnIds"][0], "turn-7");
+        assert_eq!(completed_json["reloadRequired"], true);
+        assert_eq!(completed_json["reloadReason"], "transcript read failed");
+
+        let recovery = AgentSessionRollbackToTurnOutcome::RecoveryRequired {
+            session_id: "session-1".to_string(),
+            mutation_id: "mutation-1".to_string(),
+            affected_files: vec!["src/lib.rs".to_string()],
+            reason: "authoritative reload failed".to_string(),
+        };
+        let recovery_json = serde_json::to_value(&recovery).expect("serialize recovery rollback");
+        assert_eq!(recovery_json["status"], "recovery_required");
+        assert_eq!(recovery_json["mutationId"], "mutation-1");
+        assert_eq!(recovery_json["affectedFiles"][0], "src/lib.rs");
+    }
+
+    #[test]
+    fn workspace_reference_metadata_round_trips_without_expanding_dialog_turn_dto() {
+        let references = vec![AgentWorkspaceReference {
+            path: "src/lib.rs".to_string(),
+            kind: AgentWorkspaceReferenceKind::File,
+            start_line: Some(12),
+            end_line: Some(24),
+            source: AgentWorkspaceReferenceSourceRange {
+                start: 7,
+                end: 28,
+                value: "@src/lib.rs#12-24".to_string(),
+            },
+        }];
+        let mut metadata = serde_json::Map::new();
+
+        put_agent_workspace_references(&mut metadata, &references)
+            .expect("workspace reference metadata should serialize");
+
+        assert_eq!(
+            agent_workspace_references_from_metadata(&metadata)
+                .expect("workspace reference metadata should deserialize"),
+            references
+        );
+        assert_eq!(
+            metadata[AGENT_WORKSPACE_REFERENCES_METADATA_KEY][0]["startLine"],
+            12
+        );
+    }
+
+    #[test]
+    fn workspace_reference_metadata_rejects_invalid_shapes() {
+        let metadata = serde_json::Map::from_iter([(
+            AGENT_WORKSPACE_REFERENCES_METADATA_KEY.to_string(),
+            serde_json::json!([{"path": 7}]),
+        )]);
+
+        let error = agent_workspace_references_from_metadata(&metadata)
+            .expect_err("invalid workspace reference metadata must fail closed");
+
+        assert_eq!(error.kind, PortErrorKind::InvalidRequest);
+
+        let too_many = vec![
+            serde_json::json!({
+                "path": "src/lib.rs",
+                "kind": "file",
+                "source": {"start": 0, "end": 11, "value": "@src/lib.rs"}
+            });
+            MAX_AGENT_WORKSPACE_REFERENCES_PER_TURN + 1
+        ];
+        let metadata = serde_json::Map::from_iter([(
+            AGENT_WORKSPACE_REFERENCES_METADATA_KEY.to_string(),
+            serde_json::Value::Array(too_many),
+        )]);
+        assert!(agent_workspace_references_from_metadata(&metadata).is_err());
+
+        let references = vec![
+            AgentWorkspaceReference {
+                path: "src/lib.rs".to_string(),
+                kind: AgentWorkspaceReferenceKind::File,
+                start_line: None,
+                end_line: None,
+                source: AgentWorkspaceReferenceSourceRange {
+                    start: 0,
+                    end: 11,
+                    value: "@src/lib.rs".to_string(),
+                },
+            };
+            MAX_AGENT_WORKSPACE_REFERENCES_PER_TURN + 1
+        ];
+        assert!(put_agent_workspace_references(&mut serde_json::Map::new(), &references).is_err());
+    }
+
+    #[test]
+    fn context_reload_contract_is_closed_and_target_specific() {
+        let cases = [
+            (AgentContextReloadTarget::All, "all", true, true),
+            (AgentContextReloadTarget::Skills, "skills", true, false),
+            (
+                AgentContextReloadTarget::Instructions,
+                "instructions",
+                false,
+                true,
+            ),
+        ];
+
+        for (target, serialized_target, skills, instructions) in cases {
+            assert_eq!(target.includes_skills(), skills);
+            assert_eq!(target.includes_instructions(), instructions);
+            let request = AgentContextReloadRequest {
+                session_id: "session-1".to_string(),
+                target,
+            };
+            assert_eq!(
+                serde_json::to_value(&request).expect("serialize request"),
+                serde_json::json!({
+                    "sessionId": "session-1",
+                    "target": serialized_target,
+                })
+            );
+            assert_eq!(
+                serde_json::from_value::<AgentContextReloadRequest>(serde_json::json!({
+                    "sessionId": "session-1",
+                    "target": serialized_target,
+                }))
+                .expect("deserialize request"),
+                request
+            );
+        }
+
+        assert!(
+            serde_json::from_value::<AgentContextReloadRequest>(serde_json::json!({
+                "sessionId": "session-1",
+                "target": "all",
+                "unexpected": true,
+            }))
+            .is_err()
+        );
+    }
+
+    #[derive(Default)]
+    struct ArchiveOnlySessionProvider {
+        archived_requests: Mutex<Vec<AgentSessionArchiveRequest>>,
+    }
+
+    #[async_trait::async_trait]
+    impl AgentSessionManagementPort for ArchiveOnlySessionProvider {
+        async fn list_sessions(
+            &self,
+            _request: AgentSessionListRequest,
+        ) -> PortResult<Vec<AgentSessionSummary>> {
+            Ok(Vec::new())
+        }
+
+        async fn delete_session(&self, _request: AgentSessionDeleteRequest) -> PortResult<()> {
+            Ok(())
+        }
+
+        async fn archive_session(&self, request: AgentSessionArchiveRequest) -> PortResult<()> {
+            self.archived_requests.lock().unwrap().push(request);
+            Ok(())
+        }
+
+        async fn resolve_session_workspace_binding(
+            &self,
+            _request: AgentSessionWorkspaceRequest,
+        ) -> PortResult<Option<AgentSessionWorkspaceBinding>> {
+            Ok(None)
+        }
+    }
+
+    struct LatestTurnForkOnlyProvider;
+
+    #[async_trait::async_trait]
+    impl AgentSessionForkPort for LatestTurnForkOnlyProvider {
+        async fn fork_session(
+            &self,
+            request: AgentSessionForkRequest,
+        ) -> PortResult<AgentSessionForkResult> {
+            Ok(AgentSessionForkResult {
+                session_id: format!("{}-fork", request.source_session_id),
+                session_name: "Fork".to_string(),
+                agent_type: "agentic".to_string(),
+            })
+        }
+    }
+
+    fn archive_state_request(archived: bool) -> AgentSessionArchiveStateRequest {
+        AgentSessionArchiveStateRequest {
+            workspace_path: "/workspace/project".to_string(),
+            session_id: "session_1".to_string(),
+            archived,
+            remote_connection_id: Some("conn-1".to_string()),
+            remote_ssh_host: Some("host-1".to_string()),
+        }
+    }
+
+    #[tokio::test]
+    async fn archive_state_default_preserves_archive_only_provider_compatibility() {
+        let provider = ArchiveOnlySessionProvider::default();
+
+        AgentSessionManagementPort::set_session_archived(&provider, archive_state_request(true))
+            .await
+            .expect("archive=true should delegate to the legacy provider");
+        // Scoped so the guard is provably released before the await below.
+        {
+            let requests = provider.archived_requests.lock().unwrap();
+            assert_eq!(requests.len(), 1);
+            assert_eq!(requests[0].workspace_path, "/workspace/project");
+            assert_eq!(requests[0].session_id, "session_1");
+            assert_eq!(requests[0].remote_connection_id.as_deref(), Some("conn-1"));
+            assert_eq!(requests[0].remote_ssh_host.as_deref(), Some("host-1"));
+        }
+
+        let error = AgentSessionManagementPort::set_session_archived(
+            &provider,
+            archive_state_request(false),
+        )
+        .await
+        .expect_err("legacy providers must reject unarchive by default");
+        assert_eq!(error.kind, PortErrorKind::NotAvailable);
+        assert_eq!(provider.archived_requests.lock().unwrap().len(), 1);
+    }
+
+    #[tokio::test]
+    async fn exact_turn_fork_default_preserves_latest_turn_only_provider_compatibility() {
+        let provider = LatestTurnForkOnlyProvider;
+        let error = AgentSessionForkPort::fork_session_at_turn(
+            &provider,
+            AgentSessionForkAtTurnRequest {
+                workspace_path: "/workspace/project".to_string(),
+                source_session_id: "session_1".to_string(),
+                source_turn_id: "turn_1".to_string(),
+                remote_connection_id: None,
+                remote_ssh_host: None,
+            },
+        )
+        .await
+        .expect_err("legacy providers must reject exact-turn fork by default");
+
+        assert_eq!(error.kind, PortErrorKind::NotAvailable);
+    }
+
+    #[tokio::test]
+    async fn before_turn_fork_default_preserves_existing_provider_compatibility() {
+        let provider = LatestTurnForkOnlyProvider;
+        let error = AgentSessionForkPort::fork_session_before_turn(
+            &provider,
+            AgentSessionForkBeforeTurnRequest {
+                workspace_path: "/workspace/project".to_string(),
+                source_session_id: "session_1".to_string(),
+                source_turn_id: "turn_1".to_string(),
+                remote_connection_id: None,
+                remote_ssh_host: None,
+            },
+        )
+        .await
+        .expect_err("existing providers must reject before-turn fork by default");
+
+        assert_eq!(error.kind, PortErrorKind::NotAvailable);
+    }
+
+    #[test]
+    fn agent_session_create_request_keeps_rust_literal_compatible() {
+        let request = AgentSessionCreateRequest {
+            session_name: "Generated session".to_string(),
+            agent_type: "agentic".to_string(),
+            workspace_path: Some("/workspace/project".to_string()),
+            project_workspace_path: None,
+            execution_target: None,
+            workspace_id: Some("workspace-1".to_string()),
+            remote_connection_id: None,
+            remote_ssh_host: None,
+            model_id: Some("provider/model".to_string()),
+            metadata: serde_json::Map::new(),
+        };
+
+        let json = serde_json::to_value(request).expect("serialize create request");
+
+        assert!(json.get("sessionId").is_none());
+        assert_eq!(json["workspaceId"], "workspace-1");
+        assert_eq!(json["modelId"], "provider/model");
+    }
+
+    #[test]
+    fn agent_session_create_request_keeps_legacy_payload_compatible() {
+        let request: AgentSessionCreateRequest = serde_json::from_value(serde_json::json!({
+            "sessionName": "Generated session",
+            "agentType": "agentic",
+            "workspacePath": "/workspace/project"
+        }))
+        .expect("deserialize legacy create request");
+
+        let json = serde_json::to_value(request).expect("serialize create request");
+        assert!(json.get("sessionId").is_none());
+        assert!(json.get("workspaceId").is_none());
+        assert!(json.get("modelId").is_none());
+    }
+
+    #[test]
+    fn agent_session_create_result_keeps_legacy_payload_shape() {
+        let legacy = serde_json::json!({
+            "sessionId": "session_1",
+            "sessionName": "Main",
+            "agentType": "agentic"
+        });
+
+        let result: AgentSessionCreateResult =
+            serde_json::from_value(legacy.clone()).expect("deserialize legacy create result");
+
+        assert_eq!(result.workspace_path, None);
+        assert_eq!(result.model_id, None);
+        assert_eq!(result.workspace_id, None);
+        assert_eq!(result.project_workspace_path, None);
+        assert_eq!(result.execution_target, None);
+        assert_eq!(
+            serde_json::to_value(result).expect("serialize legacy create result"),
+            legacy
+        );
+    }
+
+    #[test]
+    fn agent_session_create_result_carries_normalized_workspace_facts() {
+        let result: AgentSessionCreateResult = serde_json::from_value(serde_json::json!({
+            "sessionId": "session_1",
+            "sessionName": "Main",
+            "agentType": "agentic",
+            "modelId": "provider/model",
+            "workspacePath": "/worktrees/session_1",
+            "workspaceId": "workspace_1",
+            "projectWorkspacePath": "/workspace/project",
+            "executionTarget": {
+                "kind": "managedWorktree",
+                "worktreeId": "worktree_1",
+                "rootPath": "/worktrees/session_1",
+                "baseRef": "main",
+                "baseCommit": "0123456789abcdef",
+                "branch": "bitfun/session_1",
+                "lifecycle": "managed"
+            }
+        }))
+        .expect("deserialize complete create result");
+
+        assert_eq!(
+            result.workspace_path.as_deref(),
+            Some("/worktrees/session_1")
+        );
+        assert_eq!(result.model_id.as_deref(), Some("provider/model"));
+        assert_eq!(result.workspace_id.as_deref(), Some("workspace_1"));
+        assert_eq!(
+            result.project_workspace_path.as_deref(),
+            Some("/workspace/project")
+        );
+        let target = result.execution_target.expect("resolved execution target");
+        assert_eq!(target.kind, SessionExecutionTargetKind::ManagedWorktree);
+        assert_eq!(target.worktree_id.as_deref(), Some("worktree_1"));
+        assert_eq!(target.root_path, "/worktrees/session_1");
+    }
+
+    #[test]
+    fn agent_submission_request_serializes_with_stable_camel_case() {
+        let request = AgentSubmissionRequest {
+            session_id: "session_1".to_string(),
+            message: "hello".to_string(),
+            turn_id: None,
+            source: None,
+            attachments: Vec::new(),
+            metadata: serde_json::Map::new(),
+        };
+
+        let json = serde_json::to_value(request).expect("serialize request");
+
+        assert_eq!(json["sessionId"], "session_1");
+        assert_eq!(json["message"], "hello");
+        assert!(json.get("source").is_none());
+        assert!(json.get("attachments").is_none());
+    }
+
+    #[test]
+    fn agent_submission_request_serializes_source_without_changing_field_case() {
+        let request = AgentSubmissionRequest {
+            session_id: "session_1".to_string(),
+            message: "hello".to_string(),
+            turn_id: None,
+            source: Some(AgentSubmissionSource::RemoteRelay),
+            attachments: Vec::new(),
+            metadata: serde_json::Map::new(),
+        };
+
+        let json = serde_json::to_value(request).expect("serialize request");
+
+        assert_eq!(json["source"], "remote_relay");
+        assert!(json.get("turnId").is_none());
+    }
+
+    #[test]
+    fn delegated_dialog_turn_target_is_typed_and_provider_neutral() {
+        let target = AgentDialogTurnExecution::FreshExternalSubagent {
+            ecosystem_id: "opencode".to_string(),
+            logical_id: "reviewer".to_string(),
+        };
+
+        assert_eq!(
+            serde_json::to_value(target).expect("serialize delegated execution"),
+            serde_json::json!({
+                "kind": "fresh_external_subagent",
+                "ecosystemId": "opencode",
+                "logicalId": "reviewer",
+            })
+        );
+        assert_eq!(
+            AgentDialogTurnExecution::default(),
+            AgentDialogTurnExecution::Standard
+        );
+        assert!(
+            serde_json::from_value::<AgentDialogTurnExecution>(serde_json::json!({
+                "kind": "fresh_external_subagent",
+                "ecosystemId": "opencode",
+                "logicalId": "reviewer",
+                "model": "provider/model"
+            }))
+            .is_err()
+        );
+    }
+
+    #[test]
+    fn dialog_submission_policy_preserves_current_surface_queue_defaults() {
+        let remote = DialogSubmissionPolicy::for_source(DialogTriggerSource::RemoteRelay);
+        assert_eq!(remote.queue_priority, DialogQueuePriority::Normal);
+
+        let bot = DialogSubmissionPolicy::for_source(DialogTriggerSource::Bot);
+        assert_eq!(bot.queue_priority, DialogQueuePriority::Normal);
+
+        let agent_session = DialogSubmissionPolicy::for_source(DialogTriggerSource::AgentSession);
+        assert_eq!(agent_session.queue_priority, DialogQueuePriority::Low);
+
+        let cli = DialogSubmissionPolicy::for_source(DialogTriggerSource::Cli);
+        assert_eq!(cli.queue_priority, DialogQueuePriority::Normal);
+
+        let sdk_host = DialogSubmissionPolicy::for_source(DialogTriggerSource::SdkHost);
+        assert_eq!(sdk_host.queue_priority, DialogQueuePriority::Normal);
+    }
+
+    #[test]
+    fn dialog_submit_outcome_preserves_started_and_queued_fields() {
+        let started = DialogSubmitOutcome::Started {
+            session_id: "session_1".to_string(),
+            turn_id: "turn_1".to_string(),
+        };
+        let queued = DialogSubmitOutcome::Queued {
+            session_id: "session_1".to_string(),
+            turn_id: "turn_2".to_string(),
+        };
+
+        assert_eq!(
+            started,
+            DialogSubmitOutcome::Started {
+                session_id: "session_1".to_string(),
+                turn_id: "turn_1".to_string(),
+            }
+        );
+        assert_ne!(started, queued);
+    }
+
+    #[test]
+    fn dialog_submit_queue_action_preserves_current_scheduler_routing_policy() {
+        let remote = DialogSubmissionPolicy::for_source(DialogTriggerSource::RemoteRelay);
+
+        let agent_session = DialogSubmissionPolicy::for_source(DialogTriggerSource::AgentSession);
+
+        assert_eq!(
+            resolve_dialog_submit_queue_action(DialogSubmitQueueFacts {
+                session_state: DialogSessionStateFact::Missing,
+                queue_has_items: true,
+                policy: remote,
+            }),
+            DialogSubmitQueueAction::StartImmediately
+        );
+        assert_eq!(
+            resolve_dialog_submit_queue_action(DialogSubmitQueueFacts {
+                session_state: DialogSessionStateFact::Error,
+                queue_has_items: true,
+                policy: remote,
+            }),
+            DialogSubmitQueueAction::ClearQueueAndStartImmediately
+        );
+        assert_eq!(
+            resolve_dialog_submit_queue_action(DialogSubmitQueueFacts {
+                session_state: DialogSessionStateFact::Idle,
+                queue_has_items: false,
+                policy: remote,
+            }),
+            DialogSubmitQueueAction::StartImmediately
+        );
+        assert_eq!(
+            resolve_dialog_submit_queue_action(DialogSubmitQueueFacts {
+                session_state: DialogSessionStateFact::Idle,
+                queue_has_items: true,
+                policy: remote,
+            }),
+            DialogSubmitQueueAction::EnqueueThenStartNext
+        );
+        assert_eq!(
+            resolve_dialog_submit_queue_action(DialogSubmitQueueFacts {
+                session_state: DialogSessionStateFact::Processing,
+                queue_has_items: false,
+                policy: remote,
+            }),
+            DialogSubmitQueueAction::EnqueueForActiveTurn
+        );
+        assert_eq!(
+            resolve_dialog_submit_queue_action(DialogSubmitQueueFacts {
+                session_state: DialogSessionStateFact::Processing,
+                queue_has_items: false,
+                policy: agent_session,
+            }),
+            DialogSubmitQueueAction::EnqueueForActiveTurn
+        );
+    }
+
+    #[test]
+    fn agent_session_reply_decisions_preserve_cancel_suppression_boundary() {
+        let policy = DialogSubmissionPolicy::for_source(DialogTriggerSource::AgentSession);
+        assert!(should_suppress_agent_session_cancelled_reply(
+            &policy,
+            Some("requester"),
+            "requester",
+        ));
+        assert!(!should_suppress_agent_session_cancelled_reply(
+            &policy,
+            Some("requester"),
+            "other",
+        ));
+
+        let remote = DialogSubmissionPolicy::for_source(DialogTriggerSource::RemoteRelay);
+        assert!(!should_suppress_agent_session_cancelled_reply(
+            &remote,
+            Some("requester"),
+            "requester",
+        ));
+
+        assert!(should_skip_agent_session_reply(
+            DialogTurnOutcomeKind::Cancelled,
+            true,
+        ));
+        assert!(!should_skip_agent_session_reply(
+            DialogTurnOutcomeKind::Cancelled,
+            false,
+        ));
+        assert!(!should_skip_agent_session_reply(
+            DialogTurnOutcomeKind::Completed,
+            true,
+        ));
+        assert!(!should_skip_agent_session_reply(
+            DialogTurnOutcomeKind::Failed,
+            true,
+        ));
+    }
+
+    #[test]
+    fn agent_session_reply_route_keeps_requester_fields() {
+        let route = AgentSessionReplyRoute {
+            source_session_id: "requester_session".to_string(),
+            source_workspace_path: "/workspace/requester".to_string(),
+            source_remote_connection_id: Some("conn-1".to_string()),
+            source_remote_ssh_host: Some("host-1".to_string()),
+        };
+
+        assert_eq!(route.source_session_id, "requester_session");
+        assert_eq!(route.source_workspace_path, "/workspace/requester");
+        assert_eq!(route.source_remote_connection_id.as_deref(), Some("conn-1"));
+        assert_eq!(route.source_remote_ssh_host.as_deref(), Some("host-1"));
+    }
+
+    #[test]
+    fn dialog_steer_outcome_preserves_buffered_fields() {
+        let outcome = DialogSteerOutcome::Buffered {
+            session_id: "session_1".to_string(),
+            turn_id: "turn_1".to_string(),
+            steering_id: "steer_1".to_string(),
+        };
+
+        assert_eq!(
+            outcome,
+            DialogSteerOutcome::Buffered {
+                session_id: "session_1".to_string(),
+                turn_id: "turn_1".to_string(),
+                steering_id: "steer_1".to_string(),
+            }
+        );
+    }
+
+    #[test]
+    fn round_injection_contract_keeps_kind_and_target_identity() {
+        assert_eq!(
+            RoundInjectionKind::UserSteering,
+            RoundInjectionKind::UserSteering
+        );
+        assert_ne!(
+            RoundInjectionKind::UserSteering,
+            RoundInjectionKind::BackgroundResult
+        );
+
+        let target = RoundInjectionTarget::ExactTurn("turn_1".to_string());
+        assert_eq!(
+            target,
+            RoundInjectionTarget::ExactTurn("turn_1".to_string())
+        );
+        assert_ne!(target, RoundInjectionTarget::CurrentRunningTurn);
+        assert_eq!(
+            RoundInjectionKind::UserSteering
+                .default_execution_policy()
+                .tool_preemption,
+            RoundInjectionToolPreemption::InterruptAfterCurrentAtomicUnit
+        );
+        assert_eq!(
+            RoundInjectionKind::BackgroundResult
+                .default_execution_policy()
+                .tool_preemption,
+            RoundInjectionToolPreemption::None
+        );
+    }
+
+    #[test]
+    fn round_injection_source_contract_drains_portable_injections() {
+        struct StaticInjectionSource {
+            injection: RoundInjection,
+        }
+
+        impl DialogRoundInjectionSource for StaticInjectionSource {
+            fn has_pending(&self, session_id: &str, turn_id: &str) -> bool {
+                session_id == "session_1" && turn_id == "turn_1"
+            }
+
+            fn pending_tool_preemption(
+                &self,
+                session_id: &str,
+                turn_id: &str,
+            ) -> RoundInjectionToolPreemption {
+                if self.has_pending(session_id, turn_id) {
+                    self.injection.execution_policy.tool_preemption
+                } else {
+                    RoundInjectionToolPreemption::None
+                }
+            }
+
+            fn take_pending(&self, session_id: &str, turn_id: &str) -> Vec<RoundInjection> {
+                if self.has_pending(session_id, turn_id) {
+                    vec![self.injection.clone()]
+                } else {
+                    Vec::new()
+                }
+            }
+        }
+
+        let source = StaticInjectionSource {
+            injection: RoundInjection {
+                id: "injection_1".to_string(),
+                kind: RoundInjectionKind::BackgroundResult,
+                execution_policy: RoundInjectionKind::BackgroundResult.default_execution_policy(),
+                target: RoundInjectionTarget::CurrentRunningTurn,
+                content: "result".to_string(),
+                display_content: "result".to_string(),
+                attachments: Vec::new(),
+                metadata: serde_json::Map::new(),
+                created_at: std::time::SystemTime::UNIX_EPOCH,
+            },
+        };
+
+        assert!(source.has_pending("session_1", "turn_1"));
+        assert!(!source.has_pending("session_2", "turn_1"));
+        assert_eq!(
+            source.pending_tool_preemption("session_1", "turn_1"),
+            RoundInjectionToolPreemption::None
+        );
+        let drained = source.take_pending("session_1", "turn_1");
+        assert_eq!(drained.len(), 1);
+        assert_eq!(drained[0].id, "injection_1");
+        assert_eq!(drained[0].kind, RoundInjectionKind::BackgroundResult);
+    }
+
+    #[test]
+    fn thread_goal_active_status_includes_budget_limited() {
+        let active = ThreadGoal {
+            goal_id: "goal_1".to_string(),
+            session_id: "session_1".to_string(),
+            objective: "Ship feature".to_string(),
+            status: ThreadGoalStatus::Active,
+            token_budget: Some(10_000),
+            tokens_used: 100,
+            time_used_seconds: 5,
+            created_at: 1,
+            updated_at: 2,
+            auto_continuation_count: 0,
+        };
+        assert!(active.is_active());
+        assert_eq!(active.remaining_tokens(), Some(9_900));
+
+        let budget_limited = ThreadGoal {
+            status: ThreadGoalStatus::BudgetLimited,
+            ..active.clone()
+        };
+        assert!(budget_limited.is_active());
+
+        let paused = ThreadGoal {
+            status: ThreadGoalStatus::Paused,
+            ..active
+        };
+        assert!(!paused.is_active());
+    }
+
+    #[test]
+    fn thread_goal_tool_response_serializes_optional_fields() {
+        let response = ThreadGoalToolResponse {
+            goal: None,
+            remaining_tokens: Some(42),
+            completion_budget_report: None,
+        };
+        let json = serde_json::to_value(response).expect("serialize thread goal tool response");
+        assert!(json.get("goal").is_none());
+        assert_eq!(json["remainingTokens"], 42);
+        assert!(json.get("completionBudgetReport").is_none());
+    }
+
+    #[test]
+    fn compression_contract_renders_model_visible_fields() {
+        let contract = CompressionContract {
+            touched_files: vec!["src/lib.rs".to_string()],
+            verification_commands: vec![CompressionContractItem {
+                target: "cargo test -p bitfun-runtime-ports".to_string(),
+                status: "passed".to_string(),
+                summary: "runtime ports contract tests passed".to_string(),
+                error_kind: None,
+            }],
+            blocking_failures: vec![CompressionContractItem {
+                target: "cargo check".to_string(),
+                status: "failed".to_string(),
+                summary: "compile error before migration".to_string(),
+                error_kind: Some("compile".to_string()),
+            }],
+            subagent_statuses: Vec::new(),
+        };
+
+        let rendered = contract.render_for_model();
+
+        assert!(rendered.contains("The following facts were retained during compression."));
+        assert!(rendered.contains("Touched files:"));
+        assert!(rendered.contains("- src/lib.rs"));
+        assert!(rendered.contains(
+            "- cargo test -p bitfun-runtime-ports [passed]: runtime ports contract tests passed"
+        ));
+        assert!(
+            rendered.contains("- cargo check [failed]: compile error before migration (compile)")
+        );
+    }
+
+    #[test]
+    fn agent_submission_request_serializes_explicit_turn_id_contract() {
+        let mut metadata = serde_json::Map::new();
+        metadata.insert(
+            "turnId".to_string(),
+            serde_json::Value::String("legacy_metadata_turn".to_string()),
+        );
+        let request = AgentSubmissionRequest {
+            session_id: "session_1".to_string(),
+            message: "hello".to_string(),
+            turn_id: Some("explicit_turn".to_string()),
+            source: Some(AgentSubmissionSource::RemoteRelay),
+            attachments: Vec::new(),
+            metadata,
+        };
+
+        let json = serde_json::to_value(request).expect("serialize request");
+
+        assert_eq!(json["turnId"], "explicit_turn");
+        assert_eq!(json["metadata"]["turnId"], "legacy_metadata_turn");
+    }
+
+    #[test]
+    fn remote_image_attachment_serializes_portable_metadata_contract() {
+        let attachment =
+            AgentInputAttachment::remote_image("image-1", "clip.png", "data:image/png;base64,abc");
+
+        let json = serde_json::to_value(attachment).expect("serialize attachment");
+
+        assert_eq!(json["kind"], "remote_image");
+        assert_eq!(json["id"], "image-1");
+        assert_eq!(json["metadata"]["name"], "clip.png");
+        assert_eq!(json["metadata"]["dataUrl"], "data:image/png;base64,abc");
+    }
+
+    #[test]
+    fn agent_dialog_turn_request_serializes_lifecycle_contract() {
+        let request = AgentDialogTurnRequest {
+            session_id: "session_1".to_string(),
+            message: "hello".to_string(),
+            original_message: Some("raw hello".to_string()),
+            turn_id: Some("turn_1".to_string()),
+            execution: Default::default(),
+            agent_type: "agentic".to_string(),
+            workspace_path: Some("/workspace/project".to_string()),
+            remote_connection_id: Some("conn-1".to_string()),
+            remote_ssh_host: Some("host-1".to_string()),
+            policy: DialogSubmissionPolicy::new(
+                AgentSubmissionSource::RemoteRelay,
+                DialogQueuePriority::High,
+            ),
+            reply_route: Some(AgentSessionReplyRoute {
+                source_session_id: "source_session".to_string(),
+                source_workspace_path: "/workspace/source".to_string(),
+                source_remote_connection_id: Some("conn-1".to_string()),
+                source_remote_ssh_host: Some("host-1".to_string()),
+            }),
+            prepended_reminders: vec![AgentDialogPrependedReminder {
+                kind: "session_message_request".to_string(),
+                text: "sent by another agent".to_string(),
+            }],
+            attachments: vec![AgentInputAttachment::remote_image(
+                "image-1",
+                "clip.png",
+                "data:image/png;base64,abc",
+            )],
+            metadata: serde_json::Map::new(),
+        };
+
+        let json = serde_json::to_value(request).expect("serialize dialog turn request");
+
+        assert_eq!(json["sessionId"], "session_1");
+        assert_eq!(json["message"], "hello");
+        assert_eq!(json["originalMessage"], "raw hello");
+        assert_eq!(json["turnId"], "turn_1");
+        assert_eq!(json["agentType"], "agentic");
+        assert_eq!(json["workspacePath"], "/workspace/project");
+        assert_eq!(json["remoteConnectionId"], "conn-1");
+        assert_eq!(json["remoteSshHost"], "host-1");
+        assert_eq!(json["policy"]["triggerSource"], "remote_relay");
+        assert_eq!(json["policy"]["queuePriority"], "high");
+        assert!(json["policy"].get("skipToolConfirmation").is_none());
+        assert_eq!(json["replyRoute"]["sourceSessionId"], "source_session");
+        assert_eq!(json["replyRoute"]["sourceRemoteConnectionId"], "conn-1");
+        assert_eq!(json["replyRoute"]["sourceRemoteSshHost"], "host-1");
+        assert_eq!(
+            json["prependedReminders"][0]["kind"],
+            "session_message_request"
+        );
+        assert_eq!(json["attachments"][0]["kind"], "remote_image");
+    }
+
+    #[test]
+    fn agent_dialog_steer_contract_round_trips_exact_turn_identity() {
+        let mut metadata = serde_json::Map::new();
+        metadata.insert(
+            "kind".to_string(),
+            serde_json::Value::String("steering".to_string()),
+        );
+        let request = AgentDialogSteerRequest {
+            session_id: "session_1".to_string(),
+            turn_id: "turn_1".to_string(),
+            content: "Please also check the tests".to_string(),
+            display_content: Some("Also check tests".to_string()),
+            attachments: vec![AgentInputAttachment::remote_image(
+                "image-1",
+                "shot.png",
+                "data:image/png;base64,abc",
+            )],
+            metadata,
+        };
+        let outcome = DialogSteerOutcome::Buffered {
+            session_id: "session_1".to_string(),
+            turn_id: "turn_1".to_string(),
+            steering_id: "steer_1".to_string(),
+        };
+
+        let request_json = serde_json::to_value(&request).expect("serialize steer request");
+        let outcome_json = serde_json::to_value(&outcome).expect("serialize steer outcome");
+
+        assert_eq!(request_json["sessionId"], "session_1");
+        assert_eq!(request_json["turnId"], "turn_1");
+        assert_eq!(request_json["content"], "Please also check the tests");
+        assert_eq!(request_json["displayContent"], "Also check tests");
+        // A steering message carries the same payload a turn submission does.
+        assert_eq!(request_json["attachments"][0]["kind"], "remote_image");
+        assert_eq!(request_json["metadata"]["kind"], "steering");
+        assert_eq!(outcome_json["kind"], "buffered");
+        assert_eq!(outcome_json["sessionId"], "session_1");
+        assert_eq!(outcome_json["turnId"], "turn_1");
+        assert_eq!(outcome_json["steeringId"], "steer_1");
+
+        assert_eq!(
+            serde_json::from_value::<AgentDialogSteerRequest>(request_json)
+                .expect("deserialize steer request"),
+            request
+        );
+        assert_eq!(
+            serde_json::from_value::<DialogSteerOutcome>(outcome_json)
+                .expect("deserialize steer outcome"),
+            outcome
+        );
+    }
+
+    #[test]
+    fn agent_background_result_request_serializes_lifecycle_contract() {
+        let mut metadata = serde_json::Map::new();
+        metadata.insert(
+            "kind".to_string(),
+            serde_json::Value::String("background_result".to_string()),
+        );
+        let request = AgentBackgroundResultRequest {
+            session_id: "session_1".to_string(),
+            agent_type: "agentic".to_string(),
+            workspace_path: Some("/workspace/project".to_string()),
+            remote_connection_id: Some("conn-1".to_string()),
+            remote_ssh_host: Some("host-1".to_string()),
+            content: "full result".to_string(),
+            display_content: Some("short result".to_string()),
+            metadata,
+        };
+
+        let json = serde_json::to_value(request).expect("serialize background result request");
+
+        assert_eq!(json["sessionId"], "session_1");
+        assert_eq!(json["agentType"], "agentic");
+        assert_eq!(json["workspacePath"], "/workspace/project");
+        assert_eq!(json["remoteConnectionId"], "conn-1");
+        assert_eq!(json["remoteSshHost"], "host-1");
+        assert_eq!(json["content"], "full result");
+        assert_eq!(json["displayContent"], "short result");
+        assert_eq!(json["metadata"]["kind"], "background_result");
+    }
+
+    #[test]
+    fn agent_thread_goal_delivery_request_serializes_lifecycle_contract() {
+        let request = AgentThreadGoalDeliveryRequest {
+            session_id: "session_1".to_string(),
+            agent_type: "agentic".to_string(),
+            workspace_path: Some("/workspace/project".to_string()),
+            remote_connection_id: Some("conn-1".to_string()),
+            remote_ssh_host: Some("host-1".to_string()),
+            kind: AgentThreadGoalDeliveryKind::ObjectiveUpdated,
+            goal: ThreadGoal {
+                goal_id: "goal_1".to_string(),
+                session_id: "session_1".to_string(),
+                objective: "Ship the refactor".to_string(),
+                status: ThreadGoalStatus::Active,
+                token_budget: Some(1000),
+                tokens_used: 10,
+                time_used_seconds: 0,
+                created_at: 1,
+                updated_at: 2,
+                auto_continuation_count: 0,
+            },
+        };
+
+        let json = serde_json::to_value(request).expect("serialize thread goal delivery request");
+
+        assert_eq!(json["sessionId"], "session_1");
+        assert_eq!(json["agentType"], "agentic");
+        assert_eq!(json["workspacePath"], "/workspace/project");
+        assert_eq!(json["remoteConnectionId"], "conn-1");
+        assert_eq!(json["remoteSshHost"], "host-1");
+        assert_eq!(json["kind"], "objective_updated");
+        assert_eq!(json["goal"]["goalId"], "goal_1");
+    }
+
+    #[test]
+    fn agent_thread_goal_management_requests_serialize_stable_shape() {
+        let get_request = AgentThreadGoalGetRequest {
+            session_id: "session_1".to_string(),
+            workspace_path: "/workspace/project".to_string(),
+            remote_connection_id: Some("conn-1".to_string()),
+            remote_ssh_host: Some("host-1".to_string()),
+        };
+        let create_request = AgentThreadGoalCreateRequest {
+            session_id: "session_1".to_string(),
+            workspace_path: "/workspace/project".to_string(),
+            objective: "Ship the refactor".to_string(),
+            token_budget: Some(1000),
+        };
+        let update_request = AgentThreadGoalUpdateStatusRequest {
+            session_id: "session_1".to_string(),
+            workspace_path: "/workspace/project".to_string(),
+            status: ThreadGoalStatus::Complete,
+            turn_id: Some("turn_1".to_string()),
+        };
+
+        let get_json = serde_json::to_value(get_request).expect("serialize get request");
+        let create_json = serde_json::to_value(create_request).expect("serialize create request");
+        let update_json = serde_json::to_value(update_request).expect("serialize update request");
+
+        assert_eq!(get_json["sessionId"], "session_1");
+        assert_eq!(get_json["workspacePath"], "/workspace/project");
+        assert_eq!(get_json["remoteConnectionId"], "conn-1");
+        assert_eq!(get_json["remoteSshHost"], "host-1");
+        assert_eq!(create_json["objective"], "Ship the refactor");
+        assert_eq!(create_json["tokenBudget"], 1000);
+        assert_eq!(update_json["status"], "complete");
+        assert_eq!(update_json["turnId"], "turn_1");
+    }
+
+    #[test]
+    fn agent_turn_cancellation_request_serializes_current_contract() {
+        let request = AgentTurnCancellationRequest {
+            session_id: "session_1".to_string(),
+            turn_id: Some("turn_1".to_string()),
+            source: Some(AgentSubmissionSource::Bot),
+            requester_session_id: Some("requester_session".to_string()),
+            reason: Some("user_cancelled".to_string()),
+            wait_timeout_ms: Some(1500),
+            cancel_descendants: false,
+        };
+
+        let json = serde_json::to_value(request).expect("serialize cancel request");
+
+        assert_eq!(json["sessionId"], "session_1");
+        assert_eq!(json["turnId"], "turn_1");
+        assert_eq!(json["source"], "bot");
+        assert_eq!(json["requesterSessionId"], "requester_session");
+        assert_eq!(json["reason"], "user_cancelled");
+        assert_eq!(json["waitTimeoutMs"], 1500);
+        assert_eq!(json["cancelDescendants"], false);
+
+        let legacy = serde_json::from_value::<AgentTurnCancellationRequest>(serde_json::json!({
+            "sessionId": "session_1"
+        }))
+        .expect("deserialize legacy cancel request");
+        assert!(legacy.cancel_descendants);
+    }
+
+    #[test]
+    fn interrupted_turn_requests_are_typed_and_generation_scoped() {
+        let interrupt = AgentTurnInterruptionRequest {
+            session_id: "session_1".to_string(),
+            turn_id: "turn_1".to_string(),
+            source: Some(AgentSubmissionSource::DesktopUi),
+            wait_timeout_ms: Some(30_000),
+        };
+        let recover = AgentDialogTurnRecoveryRequest {
+            session_id: "session_1".to_string(),
+            turn_id: "turn_1".to_string(),
+            execution_generation: 1,
+            workspace_path: Some("/workspace/project".to_string()),
+            remote_connection_id: None,
+            remote_ssh_host: None,
+        };
+
+        let interrupt_json = serde_json::to_value(interrupt).expect("serialize interruption");
+        let recover_json = serde_json::to_value(recover).expect("serialize recovery");
+
+        assert_eq!(interrupt_json["turnId"], "turn_1");
+        assert_eq!(interrupt_json["source"], "desktop_ui");
+        assert_eq!(recover_json["executionGeneration"], 1);
+        assert_eq!(recover_json["workspacePath"], "/workspace/project");
+    }
+
+    #[test]
+    fn session_lineage_contracts_serialize_provider_neutral_facts() {
+        let request = AgentSessionLineageRequest {
+            workspace_path: "/workspace/project".to_string(),
+            anchor_session_id: "child_1".to_string(),
+            remote_connection_id: Some("conn-1".to_string()),
+            remote_ssh_host: Some("host-1".to_string()),
+        };
+        let snapshot = AgentSessionLineageSnapshot {
+            root_session_id: "root_1".to_string(),
+            sessions: vec![AgentSessionLineageEntry {
+                session_id: "child_1".to_string(),
+                session_name: "Research".to_string(),
+                agent_type: "explore".to_string(),
+                created_at_ms: 1_000,
+                status: AgentSessionLifecycleStatus::Completed,
+                active_turn_id: None,
+                parent_session_id: Some("root_1".to_string()),
+                parent_tool_call_id: Some("tool_1".to_string()),
+                subagent_type: Some("explore".to_string()),
+                workspace_path: Some("/workspace/project".to_string()),
+                remote_connection_id: Some("conn-1".to_string()),
+                remote_ssh_host: Some("host-1".to_string()),
+                unread_completion: Some("interrupted".to_string()),
+                needs_user_attention: None,
+            }],
+        };
+        let transcript_request = AgentSessionLineageTranscriptRequest {
+            workspace_path: "/workspace/project".to_string(),
+            root_session_id: "root_1".to_string(),
+            session_id: "child_1".to_string(),
+            required_settled_turn_ids: vec!["turn-terminal".to_string()],
+            remote_connection_id: None,
+            remote_ssh_host: None,
+        };
+        let cancellation_request = AgentSessionLineageCancellationRequest {
+            workspace_path: "/workspace/project".to_string(),
+            root_session_id: "root_1".to_string(),
+            session_id: "child_1".to_string(),
+            expected_active_turn_id: Some("turn-live".to_string()),
+            source: Some(AgentSubmissionSource::Cli),
+            reason: Some("user_cancelled".to_string()),
+            wait_timeout_ms: Some(5_000),
+            remote_connection_id: None,
+            remote_ssh_host: None,
+        };
+        let inspection = AgentSessionLineageInspection {
+            transcript: SessionTranscript {
+                session_id: "child_1".to_string(),
+                messages: Vec::new(),
+            },
+            active_turn_id: Some("turn-live".to_string()),
+        };
+
+        let request_json = serde_json::to_value(request).expect("serialize lineage request");
+        let snapshot_json = serde_json::to_value(snapshot).expect("serialize lineage snapshot");
+        let transcript_json =
+            serde_json::to_value(transcript_request).expect("serialize transcript request");
+        let cancellation_json =
+            serde_json::to_value(cancellation_request).expect("serialize cancellation request");
+        let inspection_json =
+            serde_json::to_value(inspection).expect("serialize lineage inspection");
+
+        assert_eq!(request_json["anchorSessionId"], "child_1");
+        assert_eq!(request_json["remoteConnectionId"], "conn-1");
+        assert_eq!(snapshot_json["rootSessionId"], "root_1");
+        assert_eq!(snapshot_json["sessions"][0]["status"], "completed");
+        assert_eq!(snapshot_json["sessions"][0]["parentSessionId"], "root_1");
+        assert_eq!(
+            snapshot_json["sessions"][0]["unreadCompletion"],
+            "interrupted"
+        );
+        assert_eq!(transcript_json["sessionId"], "child_1");
+        assert_eq!(transcript_json["rootSessionId"], "root_1");
+        assert_eq!(
+            transcript_json["requiredSettledTurnIds"],
+            serde_json::json!(["turn-terminal"])
+        );
+        let legacy_transcript =
+            serde_json::from_value::<AgentSessionLineageTranscriptRequest>(serde_json::json!({
+                "workspacePath": "/workspace/project",
+                "rootSessionId": "root_1",
+                "sessionId": "child_1"
+            }))
+            .expect("deserialize precondition-free lineage transcript request");
+        assert!(legacy_transcript.required_settled_turn_ids.is_empty());
+        assert_eq!(cancellation_json["source"], "cli");
+        assert_eq!(cancellation_json["waitTimeoutMs"], 5_000);
+        assert_eq!(cancellation_json["expectedActiveTurnId"], "turn-live");
+        let legacy_cancellation =
+            serde_json::from_value::<AgentSessionLineageCancellationRequest>(serde_json::json!({
+                "workspacePath": "/workspace/project",
+                "rootSessionId": "root_1",
+                "sessionId": "child_1"
+            }))
+            .expect("deserialize pre-exact-target lineage cancellation request");
+        assert!(legacy_cancellation.expected_active_turn_id.is_none());
+        assert_eq!(inspection_json["transcript"]["sessionId"], "child_1");
+        assert_eq!(inspection_json["activeTurnId"], "turn-live");
+    }
+
+    #[test]
+    fn agent_session_management_contracts_serialize_stable_shape() {
+        let list_request = AgentSessionListRequest {
+            workspace_path: "/workspace/project".to_string(),
+            remote_connection_id: Some("conn-1".to_string()),
+            remote_ssh_host: Some("host-1".to_string()),
+        };
+        let summary = AgentSessionSummary {
+            session_id: "session_1".to_string(),
+            session_name: "Main".to_string(),
+            agent_type: "agentic".to_string(),
+            model_id: Some("provider/model".to_string()),
+            reasoning_preset: Some("high".to_string()),
+            last_user_dialog_agent_type: Some("plan".to_string()),
+            last_submitted_agent_type: Some("agentic".to_string()),
+            turn_count: 3,
+            created_at_ms: 1000,
+            last_active_at_ms: 2000,
+        };
+        let delete_request = AgentSessionDeleteRequest {
+            workspace_path: "/workspace/project".to_string(),
+            session_id: "session_1".to_string(),
+            remote_connection_id: Some("conn-1".to_string()),
+            remote_ssh_host: Some("host-1".to_string()),
+        };
+        let rename_request = AgentSessionRenameRequest {
+            workspace_path: "/workspace/project".to_string(),
+            session_id: "session_1".to_string(),
+            session_name: "Renamed".to_string(),
+            remote_connection_id: Some("conn-1".to_string()),
+            remote_ssh_host: Some("host-1".to_string()),
+        };
+        let archive_request = AgentSessionArchiveRequest {
+            workspace_path: "/workspace/project".to_string(),
+            session_id: "session_1".to_string(),
+            remote_connection_id: Some("conn-1".to_string()),
+            remote_ssh_host: Some("host-1".to_string()),
+        };
+        let archive_state_request = AgentSessionArchiveStateRequest {
+            workspace_path: "/workspace/project".to_string(),
+            session_id: "session_1".to_string(),
+            archived: false,
+            remote_connection_id: Some("conn-1".to_string()),
+            remote_ssh_host: Some("host-1".to_string()),
+        };
+        let fork_request = AgentSessionForkRequest {
+            workspace_path: "/workspace/project".to_string(),
+            source_session_id: "session_1".to_string(),
+            remote_connection_id: None,
+            remote_ssh_host: None,
+        };
+        let fork_at_turn_request = AgentSessionForkAtTurnRequest {
+            workspace_path: "/workspace/project".to_string(),
+            source_session_id: "session_1".to_string(),
+            source_turn_id: "turn_2".to_string(),
+            remote_connection_id: Some("conn-1".to_string()),
+            remote_ssh_host: Some("host-1".to_string()),
+        };
+        let fork_before_turn_request = AgentSessionForkBeforeTurnRequest {
+            workspace_path: "/workspace/project".to_string(),
+            source_session_id: "session_1".to_string(),
+            source_turn_id: "turn_2".to_string(),
+            remote_connection_id: None,
+            remote_ssh_host: None,
+        };
+        let model_request = AgentSessionModelUpdateRequest {
+            session_id: "session_1".to_string(),
+            model_id: "provider/model".to_string(),
+        };
+        let mode_request = AgentSessionModeUpdateRequest {
+            session_id: "session_1".to_string(),
+            mode_id: "agentic".to_string(),
+        };
+        let workspace_request = AgentSessionWorkspaceRequest {
+            session_id: "session_1".to_string(),
+        };
+        let workspace_binding = AgentSessionWorkspaceBinding {
+            workspace_id: Some("workspace_1".to_string()),
+            workspace_path: "/workspace/project".to_string(),
+            project_workspace_path: None,
+            execution_target: None,
+            remote_connection_id: Some("conn-1".to_string()),
+            remote_ssh_host: Some("host-1".to_string()),
+        };
+
+        let list_json = serde_json::to_value(list_request).expect("serialize list request");
+        let summary_json = serde_json::to_value(summary).expect("serialize summary");
+        let delete_json = serde_json::to_value(delete_request).expect("serialize delete request");
+        let rename_json = serde_json::to_value(rename_request).expect("serialize rename request");
+        let archive_json =
+            serde_json::to_value(archive_request).expect("serialize archive request");
+        let archive_state_json =
+            serde_json::to_value(archive_state_request).expect("serialize archive-state request");
+        let fork_json = serde_json::to_value(fork_request).expect("serialize fork request");
+        let fork_at_turn_json =
+            serde_json::to_value(fork_at_turn_request).expect("serialize exact-turn fork request");
+        let fork_before_turn_json = serde_json::to_value(fork_before_turn_request)
+            .expect("serialize before-turn fork request");
+        let model_json = serde_json::to_value(model_request).expect("serialize model request");
+        let mode_json = serde_json::to_value(mode_request).expect("serialize mode request");
+        let workspace_json =
+            serde_json::to_value(workspace_request).expect("serialize workspace request");
+        let binding_json =
+            serde_json::to_value(workspace_binding).expect("serialize workspace binding");
+
+        assert_eq!(list_json["workspacePath"], "/workspace/project");
+        assert_eq!(list_json["remoteConnectionId"], "conn-1");
+        assert_eq!(summary_json["modelId"], "provider/model");
+        assert_eq!(summary_json["lastUserDialogAgentType"], "plan");
+        assert_eq!(summary_json["lastSubmittedAgentType"], "agentic");
+        assert_eq!(list_json["remoteSshHost"], "host-1");
+        assert_eq!(summary_json["sessionId"], "session_1");
+        assert_eq!(summary_json["turnCount"], 3);
+        assert_eq!(summary_json["createdAtMs"], 1000);
+        assert_eq!(summary_json["lastActiveAtMs"], 2000);
+        assert_eq!(delete_json["sessionId"], "session_1");
+        assert_eq!(delete_json["remoteConnectionId"], "conn-1");
+        assert_eq!(delete_json["remoteSshHost"], "host-1");
+        assert_eq!(rename_json["sessionName"], "Renamed");
+        assert_eq!(rename_json["remoteConnectionId"], "conn-1");
+        assert_eq!(archive_json["sessionId"], "session_1");
+        assert_eq!(archive_json["remoteSshHost"], "host-1");
+        assert_eq!(archive_state_json["archived"], false);
+        assert!(fork_json.get("sourceTurnId").is_none());
+        assert_eq!(fork_at_turn_json["sourceTurnId"], "turn_2");
+        assert_eq!(fork_before_turn_json["sourceTurnId"], "turn_2");
+        assert_eq!(fork_before_turn_json["sourceSessionId"], "session_1");
+        assert_eq!(model_json["sessionId"], "session_1");
+        assert_eq!(model_json["modelId"], "provider/model");
+        assert_eq!(mode_json["sessionId"], "session_1");
+        assert_eq!(mode_json["modeId"], "agentic");
+        assert_eq!(workspace_json["sessionId"], "session_1");
+        assert_eq!(binding_json["workspaceId"], "workspace_1");
+        assert_eq!(binding_json["workspacePath"], "/workspace/project");
+        assert_eq!(binding_json["remoteConnectionId"], "conn-1");
+        assert_eq!(binding_json["remoteSshHost"], "host-1");
+    }
+
+    #[test]
+    fn local_command_turn_contract_has_fixed_narrow_shape() {
+        let mut metadata = serde_json::Map::new();
+        metadata.insert("kind".to_string(), serde_json::json!("usage_report"));
+        let request = AgentLocalCommandTurnRecordRequest {
+            session_id: "session_1".to_string(),
+            content: "Usage report".to_string(),
+            turn_id: Some("turn_1".to_string()),
+            timestamp_ms: Some(1000),
+            metadata,
+        };
+
+        let json = serde_json::to_value(request).expect("serialize local command turn");
+
+        assert_eq!(json["sessionId"], "session_1");
+        assert_eq!(json["content"], "Usage report");
+        assert_eq!(json["turnId"], "turn_1");
+        assert_eq!(json["timestampMs"], 1000);
+        assert_eq!(json["metadata"]["kind"], "usage_report");
+        assert!(json.get("turnKind").is_none());
+        assert!(json.get("modelVisible").is_none());
+    }
+
+    #[test]
+    fn local_command_turn_result_serializes_authoritative_identity() {
+        let result = AgentLocalCommandTurnRecordResult {
+            turn_id: "turn_8".to_string(),
+            storage_turn_index: 7,
+        };
+
+        let json = serde_json::to_value(result).expect("serialize local command turn result");
+
+        assert_eq!(json["turnId"], "turn_8");
+        assert_eq!(json["storageTurnIndex"], 7);
+        assert_eq!(json.as_object().map(|value| value.len()), Some(2));
+    }
+
+    #[test]
+    fn remote_control_state_snapshot_serializes_active_turn_contract() {
+        let snapshot = RemoteControlStateSnapshot {
+            session_id: "session_1".to_string(),
+            state: RemoteControlSessionState::Processing,
+            active_turn_id: Some("turn_1".to_string()),
+            queue_depth: 2,
+            metadata: serde_json::Map::new(),
+        };
+
+        let json = serde_json::to_value(snapshot).expect("serialize state snapshot");
+
+        assert_eq!(json["sessionId"], "session_1");
+        assert_eq!(json["state"], "processing");
+        assert_eq!(json["activeTurnId"], "turn_1");
+        assert_eq!(json["queueDepth"], 2);
+    }
+
+    #[test]
+    fn session_transcript_request_serializes_turn_id_contract() {
+        let request = SessionTranscriptRequest {
+            session_id: "session_1".to_string(),
+            turn_id: Some("turn_1".to_string()),
+        };
+
+        let json = serde_json::to_value(request).expect("serialize transcript request");
+
+        assert_eq!(json["sessionId"], "session_1");
+        assert_eq!(json["turnId"], "turn_1");
+        assert!(json.get("fromTurnId").is_none());
+    }
+
+    #[test]
+    fn transcript_contract_keeps_portable_message_identity_and_content() {
+        let message = TranscriptMessage {
+            id: Some("message_1".to_string()),
+            role: "assistant".to_string(),
+            turn_id: Some("turn_1".to_string()),
+            timestamp_ms: Some(3000),
+            content: TranscriptContent::Text("done".to_string()),
+        };
+
+        let message_json = serde_json::to_value(message).expect("serialize transcript message");
+
+        assert_eq!(message_json["id"], "message_1");
+        assert_eq!(message_json["timestampMs"], 3000);
+        assert_eq!(message_json["content"]["Text"], "done");
+    }
+}
diff --git a/src/crates/contracts/runtime-ports/src/git_port.rs b/src/crates/contracts/runtime-ports/src/git_port.rs
new file mode 100644
index 0000000000..806bb6fc04
--- /dev/null
+++ b/src/crates/contracts/runtime-ports/src/git_port.rs
@@ -0,0 +1,51 @@
+use super::*;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum WorkspaceDiffFileStatus {
+    Added,
+    Modified,
+    Deleted,
+    Renamed,
+    Conflicted,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub enum WorkspaceDiffContent {
+    Text { patch: String },
+    Binary,
+    TooLarge,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct WorkspaceDiffFile {
+    pub path: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub old_path: Option<String>,
+    pub status: WorkspaceDiffFileStatus,
+    pub staged: bool,
+    pub unstaged: bool,
+    pub untracked: bool,
+    pub additions: usize,
+    pub deletions: usize,
+    pub content: WorkspaceDiffContent,
+}
+
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct WorkspaceDiffSnapshot {
+    pub files: Vec<WorkspaceDiffFile>,
+    pub truncated: bool,
+}
+
+#[async_trait::async_trait]
+pub trait GitPort: RuntimeServicePort {
+    async fn workspace_diff(&self) -> PortResult<WorkspaceDiffSnapshot> {
+        Err(PortError::new(
+            PortErrorKind::NotAvailable,
+            "workspace diff is not supported by this provider",
+        ))
+    }
+}
diff --git a/src/crates/contracts/runtime-ports/src/lib.rs b/src/crates/contracts/runtime-ports/src/lib.rs
index 28c0c5b003..f9e6a03472 100644
--- a/src/crates/contracts/runtime-ports/src/lib.rs
+++ b/src/crates/contracts/runtime-ports/src/lib.rs
@@ -5,22 +5,21 @@
 //! on concrete managers, platform adapters, `bitfun-core`, or app crates.
 
 use serde::{Deserialize, Serialize};
-use std::collections::HashMap;
-use std::path::{Path, PathBuf};
-use std::sync::Arc;
-use tokio::sync::mpsc;
-use tokio_util::sync::CancellationToken;
 
+#[cfg(feature = "agent-api")]
 pub use bitfun_core_types::{
     SessionExecutionTarget, SessionExecutionTargetKind, SessionExecutionTargetRequest,
     SessionUsageReport, WorktreeError, WorktreeErrorCode, WorktreeLifecycle, WorktreeSettings,
     WorktreeSummary,
 };
 
+#[cfg(feature = "workspace-ports")]
 mod local_workspace_snapshot;
 #[cfg(feature = "permission")]
 mod permission;
+#[cfg(feature = "plugin-runtime")]
 mod plugin;
+#[cfg(feature = "script-tool-runtime")]
 mod script_tool;
 #[cfg(feature = "permission")]
 pub use bitfun_product_domains::tool_permissions::{
@@ -35,6 +34,7 @@ pub use bitfun_product_domains::tool_permissions::{
     PermissionRuleset, PermissionRuntimeCeiling, PermissionRuntimeCeilingValidationError,
     ResolvedPermissionMode, ResolvedPermissionPolicy, ToolPermissionConfig,
 };
+#[cfg(feature = "workspace-ports")]
 pub use local_workspace_snapshot::{
     LocalWorkspaceSnapshotPort, LocalWorkspaceSnapshotSessionRequest, LocalWorkspaceSnapshotStats,
     LocalWorkspaceSnapshotTurnRequest,
@@ -43,6 +43,7 @@ pub use local_workspace_snapshot::{
 pub use permission::{
     PermissionAuditStorePort, PermissionGrantStorePort, PermissionReplyStorePort,
 };
+#[cfg(feature = "plugin-runtime")]
 pub use plugin::{
     validate_plugin_dispatch_response, validate_plugin_runtime_read_response,
     DisabledPluginRuntimeClient, ExtensionCapabilityAvailability, PermissionPromptDenyState,
@@ -59,6 +60,7 @@ pub use plugin::{
     PluginRuntimeUnavailableReason, PluginSourceKind, PluginSourceRef, PluginStatusKind,
     PluginStatusSnapshot, PluginTargetRef, PluginTrustLevel, ProjectionOnlyPluginRuntimeClient,
 };
+#[cfg(feature = "script-tool-runtime")]
 pub use script_tool::{
     ScriptToolDescriptor, ScriptToolExpectedExport, ScriptToolInvokeRequest,
     ScriptToolInvokeResponse, ScriptToolLoadRequest, ScriptToolLoadResponse, ScriptToolRuntime,
@@ -158,3654 +160,161 @@ pub trait RuntimeServicePort: Send + Sync {
     fn capability(&self) -> RuntimeServiceCapability;
 }
 
-pub trait FileSystemPort: RuntimeServicePort {}
-
-pub trait WorkspacePort: RuntimeServicePort {}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct SessionStoragePathRequest {
-    pub workspace_path: PathBuf,
-    pub remote_connection_id: Option<String>,
-    pub remote_ssh_host: Option<String>,
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "snake_case")]
-pub enum SessionStorageKind {
-    Local,
-    Remote,
-    UnresolvedRemote,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct SessionStoragePathResolution {
-    pub requested_workspace_path: PathBuf,
-    pub effective_storage_path: PathBuf,
-    pub storage_kind: SessionStorageKind,
-    pub remote_connection_id: Option<String>,
-    pub remote_ssh_host: Option<String>,
-}
-
-impl SessionStoragePathResolution {
-    pub fn new(
-        requested_workspace_path: PathBuf,
-        effective_storage_path: PathBuf,
-        storage_kind: SessionStorageKind,
-        remote_connection_id: Option<String>,
-        remote_ssh_host: Option<String>,
-    ) -> Self {
-        Self {
-            requested_workspace_path,
-            effective_storage_path,
-            storage_kind,
-            remote_connection_id,
-            remote_ssh_host,
-        }
-    }
-
-    pub fn is_remote_storage(&self) -> bool {
-        matches!(
-            self.storage_kind,
-            SessionStorageKind::Remote | SessionStorageKind::UnresolvedRemote
-        )
-    }
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct SessionViewRestoreRequest {
-    pub workspace_path: PathBuf,
-    pub session_id: String,
-    pub include_internal: bool,
-    pub tail_turn_count: Option<usize>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct SessionTurnLoadRequest {
-    pub workspace_path: PathBuf,
-    pub session_id: String,
-    pub tail_turn_count: Option<usize>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct SessionTurnWindowRequest {
-    pub workspace_path: PathBuf,
-    pub session_id: String,
-    pub include_internal: bool,
-    pub target_storage_turn_index: usize,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub expected_turn_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub expected_catalog_revision: Option<String>,
-    pub before: usize,
-    pub after: usize,
-}
-
-#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct SessionTurnLoadTiming {
-    pub requested_tail_turn_count: Option<usize>,
-    pub loaded_turn_count: usize,
-    pub total_turn_count: usize,
-    pub turn_file_count: usize,
-    pub missing_turn_file_count: usize,
-    pub fast_path: bool,
-    pub metadata_duration_ms: u64,
-    pub state_duration_ms: u64,
-    pub scan_duration_ms: u64,
-    pub read_duration_ms: u64,
-    pub max_turn_read_duration_ms: u64,
-    pub build_session_duration_ms: u64,
-    pub total_duration_ms: u64,
-}
-
-#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct SessionViewRestoreTiming {
-    pub resolve_storage_path_duration_ms: u64,
-    pub visibility_metadata_duration_ms: u64,
-    pub load_session_with_turns_duration_ms: u64,
-    pub normalize_turn_ids_duration_ms: u64,
-    #[serde(default)]
-    pub turn_catalog_duration_ms: u64,
-    pub total_duration_ms: u64,
-    pub turn_load: SessionTurnLoadTiming,
-}
-
-#[async_trait::async_trait]
-pub trait SessionStorePort: RuntimeServicePort {
-    async fn resolve_session_storage_path(
-        &self,
-        request: SessionStoragePathRequest,
-    ) -> PortResult<SessionStoragePathResolution>;
-}
-
-/// One row from [`WorkspaceFileSystem::read_dir`] (POSIX paths when the backend is remote SSH).
-#[derive(Debug, Clone)]
-pub struct WorkspaceDirEntry {
-    pub name: String,
-    pub path: String,
-    pub is_dir: bool,
-    pub is_symlink: bool,
-}
-
-/// File type for one exact path without following its final symbolic link.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum WorkspacePathKind {
-    File,
-    Directory,
-    Symlink,
-    Other,
-}
-
-/// Unified file system operations that work for both local and remote workspaces.
-#[async_trait::async_trait]
-pub trait WorkspaceFileSystem: Send + Sync {
-    async fn read_file(&self, path: &str) -> anyhow::Result<Vec<u8>>;
-    /// Read binary content up to `max_bytes`.
-    ///
-    /// `Ok(None)` means the file exceeded the bound; missing paths, non-files, and transport
-    /// failures remain errors. Production providers should enforce the bound before or while
-    /// transferring the file.
-    async fn read_file_bounded(
-        &self,
-        path: &str,
-        max_bytes: usize,
-    ) -> anyhow::Result<Option<Vec<u8>>> {
-        let bytes = self.read_file(path).await?;
-        Ok((bytes.len() <= max_bytes).then_some(bytes))
-    }
-    async fn read_file_text(&self, path: &str) -> anyhow::Result<String>;
-    /// Read UTF-8 text up to `max_bytes`. Production filesystem providers
-    /// should enforce the bound before or while transferring the file.
-    async fn read_file_text_bounded(
-        &self,
-        path: &str,
-        max_bytes: usize,
-    ) -> anyhow::Result<Option<String>> {
-        let content = self.read_file_text(path).await?;
-        Ok((content.len() <= max_bytes).then_some(content))
-    }
-    async fn write_file(&self, path: &str, contents: &[u8]) -> anyhow::Result<()>;
-    async fn exists(&self, path: &str) -> anyhow::Result<bool>;
-    async fn is_file(&self, path: &str) -> anyhow::Result<bool>;
-    async fn is_dir(&self, path: &str) -> anyhow::Result<bool>;
-    /// Inspect one exact path without following its final symbolic link.
-    /// Providers that cannot guarantee no-follow semantics must return an
-    /// error instead of falling back to link-following metadata.
-    async fn path_kind_no_follow(&self, _path: &str) -> anyhow::Result<Option<WorkspacePathKind>> {
-        Err(anyhow::anyhow!(
-            "exact no-follow path metadata is not supported by this workspace filesystem"
-        ))
-    }
-    /// List immediate children (non-recursive). Symlinks may be included; callers often skip them.
-    async fn read_dir(&self, path: &str) -> anyhow::Result<Vec<WorkspaceDirEntry>>;
-    /// List at most `max_entries` immediate children. Production providers
-    /// should stop local iteration or remote directory-batch requests once the
-    /// bound is met.
-    async fn read_dir_bounded(
-        &self,
-        path: &str,
-        max_entries: usize,
-    ) -> anyhow::Result<Vec<WorkspaceDirEntry>> {
-        let mut entries = self.read_dir(path).await?;
-        entries.truncate(max_entries);
-        Ok(entries)
-    }
-}
-
-/// Unified shell execution options for local and remote workspaces.
-#[derive(Clone, Default)]
-pub struct WorkspaceCommandOptions {
-    pub timeout_ms: Option<u64>,
-    pub cancellation_token: Option<CancellationToken>,
-}
-
-impl std::fmt::Debug for WorkspaceCommandOptions {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        f.debug_struct("WorkspaceCommandOptions")
-            .field("timeout_ms", &self.timeout_ms)
-            .field(
-                "cancellation_token",
-                &self
-                    .cancellation_token
-                    .as_ref()
-                    .map(|_| "<CancellationToken>"),
-            )
-            .finish()
-    }
-}
-
-#[derive(Debug, Clone)]
-pub struct WorkspaceCommandResult {
-    pub stdout: String,
-    pub stderr: String,
-    pub exit_code: i32,
-    pub interrupted: bool,
-    pub timed_out: bool,
-}
-
-impl WorkspaceCommandResult {
-    pub fn combined_output(&self) -> String {
-        if self.stderr.is_empty() {
-            self.stdout.clone()
-        } else if self.stdout.is_empty() {
-            self.stderr.clone()
-        } else {
-            format!("{}\n{}", self.stdout, self.stderr)
-        }
-    }
-}
-
-/// Unified shell execution for both local and remote workspaces.
-#[async_trait::async_trait]
-pub trait WorkspaceShell: Send + Sync {
-    /// Execute a command and return a structured result.
-    async fn exec_with_options(
-        &self,
-        command: &str,
-        options: WorkspaceCommandOptions,
-    ) -> anyhow::Result<WorkspaceCommandResult>;
-
-    /// Execute a command and return (stdout, stderr, exit_code).
-    async fn exec(
-        &self,
-        command: &str,
-        timeout_ms: Option<u64>,
-    ) -> anyhow::Result<(String, String, i32)> {
-        let result = self
-            .exec_with_options(
-                command,
-                WorkspaceCommandOptions {
-                    timeout_ms,
-                    ..Default::default()
-                },
-            )
-            .await?;
-
-        if result.timed_out {
-            anyhow::bail!(
-                "Command timed out after {}ms",
-                timeout_ms.unwrap_or_default()
-            );
-        }
-        if result.interrupted {
-            anyhow::bail!("Command was cancelled");
-        }
-
-        Ok((result.stdout, result.stderr, result.exit_code))
-    }
-}
-
-/// Bundle of workspace I/O services injected into tool runtime context.
-pub struct WorkspaceServices {
-    pub fs: Arc<dyn WorkspaceFileSystem>,
-    pub shell: Arc<dyn WorkspaceShell>,
-}
-
-impl Clone for WorkspaceServices {
-    fn clone(&self) -> Self {
-        Self {
-            fs: Arc::clone(&self.fs),
-            shell: Arc::clone(&self.shell),
-        }
-    }
-}
-
-impl std::fmt::Debug for WorkspaceServices {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        f.debug_struct("WorkspaceServices")
-            .field("fs", &"<dyn WorkspaceFileSystem>")
-            .field("shell", &"<dyn WorkspaceShell>")
-            .finish()
-    }
-}
-
-#[derive(Debug, Clone)]
-pub struct TerminalExecCommandRequest {
-    pub argv: Vec<String>,
-    pub cwd: PathBuf,
-    pub env: HashMap<String, String>,
-    pub tty: bool,
-    pub yield_time_ms: Option<u64>,
-    pub max_output_chars: Option<usize>,
-    pub lifecycle_sink: Option<TerminalExecLifecycleSink>,
-    pub output_sink: Option<TerminalExecOutputSink>,
-}
-
-#[derive(Debug, Clone)]
-pub struct TerminalWriteStdinRequest {
-    pub session_id: i32,
-    pub chars: String,
-    pub append_enter: bool,
-    pub yield_time_ms: Option<u64>,
-    pub max_output_chars: Option<usize>,
-}
-
-#[derive(Debug, Clone)]
-pub struct TerminalSendStdinRequest {
-    pub session_id: i32,
-    pub chars: String,
-    pub append_enter: bool,
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum TerminalExecControlAction {
-    Interrupt,
-    Kill,
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum TerminalExecControlOrigin {
-    ModelTool,
-    OutOfBand,
-}
-
-#[derive(Debug, Clone)]
-pub struct TerminalExecControlRequest {
-    pub session_id: i32,
-    pub action: TerminalExecControlAction,
-    pub origin: TerminalExecControlOrigin,
-    pub yield_time_ms: Option<u64>,
-    pub max_output_chars: Option<usize>,
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum TerminalExecSessionCompletionStatus {
-    Exited,
-    Interrupted,
-    Killed,
-    Pruned,
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum TerminalExecSessionCompletionSource {
-    Process,
-    OutOfBandControl,
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub struct TerminalExecSessionCompletion {
-    pub status: TerminalExecSessionCompletionStatus,
-    pub source: TerminalExecSessionCompletionSource,
-}
-
-#[derive(Debug, Clone, PartialEq)]
-pub struct TerminalExecCommandResponse {
-    pub chunk_id: String,
-    pub wall_time_seconds: f64,
-    pub output: String,
-    pub session_id: Option<i32>,
-    pub exit_code: Option<i32>,
-    pub original_output_chars: usize,
-    pub completion: Option<TerminalExecSessionCompletion>,
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum TerminalExecProcessLifecycleStatus {
-    Running,
-    Exited,
-    Interrupted,
-    Killed,
-    Pruned,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct TerminalExecProcessLifecycleEvent {
-    pub session_id: i32,
-    pub status: TerminalExecProcessLifecycleStatus,
-    pub exit_code: Option<i32>,
-}
-
-pub type TerminalExecLifecycleSink = mpsc::UnboundedSender<TerminalExecProcessLifecycleEvent>;
-pub type TerminalExecOutputSink = mpsc::UnboundedSender<String>;
-pub type TerminalExecStreamingOutputSink = mpsc::Sender<String>;
-
-#[derive(Debug, Clone)]
-pub struct RemoteExecCommandRequest {
-    pub connection_id: String,
-    pub command: String,
-    pub tty: bool,
-    pub yield_time_ms: Option<u64>,
-    pub max_output_chars: Option<usize>,
-    pub lifecycle_sink: Option<RemoteExecLifecycleSink>,
-    pub output_sink: Option<RemoteExecOutputSink>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct RemoteExecOneShotCommandRequest {
-    pub connection_id: String,
-    pub command: String,
-    pub timeout_ms: Option<u64>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct RemoteExecOneShotCommandResponse {
-    pub stdout: String,
-    pub stderr: String,
-    pub exit_code: i32,
-    pub interrupted: bool,
-    pub timed_out: bool,
-}
-
-#[derive(Debug, Clone)]
-pub struct RemoteWriteStdinRequest {
-    pub session_id: i32,
-    pub chars: String,
-    pub append_enter: bool,
-    pub yield_time_ms: Option<u64>,
-    pub max_output_chars: Option<usize>,
-}
-
-#[derive(Debug, Clone)]
-pub struct RemoteSendStdinRequest {
-    pub session_id: i32,
-    pub chars: String,
-    pub append_enter: bool,
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum RemoteExecControlAction {
-    Interrupt,
-    Kill,
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum RemoteExecControlOrigin {
-    ModelTool,
-    OutOfBand,
-}
-
-#[derive(Debug, Clone)]
-pub struct RemoteExecControlRequest {
-    pub session_id: i32,
-    pub action: RemoteExecControlAction,
-    pub origin: RemoteExecControlOrigin,
-    pub yield_time_ms: Option<u64>,
-    pub max_output_chars: Option<usize>,
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum RemoteExecSessionCompletionStatus {
-    Exited,
-    Interrupted,
-    Killed,
-    Pruned,
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum RemoteExecSessionCompletionSource {
-    Process,
-    OutOfBandControl,
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub struct RemoteExecSessionCompletion {
-    pub status: RemoteExecSessionCompletionStatus,
-    pub source: RemoteExecSessionCompletionSource,
-}
-
-#[derive(Debug, Clone, PartialEq)]
-pub struct RemoteExecCommandResponse {
-    pub chunk_id: String,
-    pub wall_time_seconds: f64,
-    pub output: String,
-    pub session_id: Option<i32>,
-    pub exit_code: Option<i32>,
-    pub original_output_chars: usize,
-    pub completion: Option<RemoteExecSessionCompletion>,
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum RemoteExecProcessLifecycleStatus {
-    Running,
-    Exited,
-    Interrupted,
-    Killed,
-    Pruned,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct RemoteExecProcessLifecycleEvent {
-    pub session_id: i32,
-    pub status: RemoteExecProcessLifecycleStatus,
-    pub exit_code: Option<i32>,
-}
-
-pub type RemoteExecLifecycleSink = mpsc::UnboundedSender<RemoteExecProcessLifecycleEvent>;
-pub type RemoteExecOutputSink = mpsc::UnboundedSender<String>;
-pub type RemoteExecStreamingOutputSink = mpsc::Sender<String>;
-
-/// Runtime handles injected into tool execution contexts.
-///
-/// This bundle is intentionally handle-only. Concrete local or remote
-/// implementations are still assembled by product/runtime owners outside this
-/// crate.
-#[derive(Clone, Default)]
-pub struct ToolRuntimeHandles {
-    workspace_services: Option<WorkspaceServices>,
-    cancellation_token: Option<CancellationToken>,
-    terminal_port: Option<Arc<dyn TerminalPort>>,
-    remote_exec_port: Option<Arc<dyn RemoteExecPort>>,
-}
-
-impl ToolRuntimeHandles {
-    pub fn new(
-        workspace_services: Option<WorkspaceServices>,
-        cancellation_token: Option<CancellationToken>,
-    ) -> Self {
-        Self {
-            workspace_services,
-            cancellation_token,
-            terminal_port: None,
-            remote_exec_port: None,
-        }
-    }
-
-    pub fn with_terminal_port(mut self, terminal_port: Option<Arc<dyn TerminalPort>>) -> Self {
-        self.terminal_port = terminal_port;
-        self
-    }
-
-    pub fn with_remote_exec_port(
-        mut self,
-        remote_exec_port: Option<Arc<dyn RemoteExecPort>>,
-    ) -> Self {
-        self.remote_exec_port = remote_exec_port;
-        self
-    }
-
-    pub fn workspace_services(&self) -> Option<&WorkspaceServices> {
-        self.workspace_services.as_ref()
-    }
-
-    pub fn cancellation_token(&self) -> Option<&CancellationToken> {
-        self.cancellation_token.as_ref()
-    }
-
-    pub fn terminal_port(&self) -> Option<&Arc<dyn TerminalPort>> {
-        self.terminal_port.as_ref()
-    }
-
-    pub fn remote_exec_port(&self) -> Option<&Arc<dyn RemoteExecPort>> {
-        self.remote_exec_port.as_ref()
-    }
-}
-
-impl std::fmt::Debug for ToolRuntimeHandles {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        f.debug_struct("ToolRuntimeHandles")
-            .field(
-                "workspace_services",
-                &self
-                    .workspace_services
-                    .as_ref()
-                    .map(|_| "<WorkspaceServices>"),
-            )
-            .field(
-                "cancellation_token",
-                &self
-                    .cancellation_token
-                    .as_ref()
-                    .map(|_| "<CancellationToken>"),
-            )
-            .field(
-                "terminal_port",
-                &self.terminal_port.as_ref().map(|_| "<dyn TerminalPort>"),
-            )
-            .field(
-                "remote_exec_port",
-                &self
-                    .remote_exec_port
-                    .as_ref()
-                    .map(|_| "<dyn RemoteExecPort>"),
-            )
-            .finish()
-    }
-}
-
-pub trait ClockPort: RuntimeServicePort {
-    fn now_unix_millis(&self) -> i64;
-}
-
-#[async_trait::async_trait]
-pub trait TerminalPort: RuntimeServicePort + std::fmt::Debug {
-    async fn exec_command(
-        &self,
-        request: TerminalExecCommandRequest,
-    ) -> PortResult<TerminalExecCommandResponse>;
-
-    async fn exec_command_streaming(
-        &self,
-        request: TerminalExecCommandRequest,
-        output_sink: TerminalExecStreamingOutputSink,
-    ) -> PortResult<TerminalExecCommandResponse>;
-
-    async fn write_stdin(
-        &self,
-        request: TerminalWriteStdinRequest,
-    ) -> PortResult<TerminalExecCommandResponse>;
-
-    async fn write_stdin_streaming(
-        &self,
-        request: TerminalWriteStdinRequest,
-        output_sink: TerminalExecStreamingOutputSink,
-    ) -> PortResult<TerminalExecCommandResponse>;
-
-    async fn send_stdin(&self, request: TerminalSendStdinRequest) -> PortResult<()>;
-
-    async fn control_session(
-        &self,
-        request: TerminalExecControlRequest,
-    ) -> PortResult<TerminalExecCommandResponse>;
-}
-
-#[async_trait::async_trait]
-pub trait RemoteExecPort: RuntimeServicePort + std::fmt::Debug {
-    async fn exec_command_once(
-        &self,
-        request: RemoteExecOneShotCommandRequest,
-    ) -> PortResult<RemoteExecOneShotCommandResponse>;
-
-    async fn exec_command(
-        &self,
-        request: RemoteExecCommandRequest,
-    ) -> PortResult<RemoteExecCommandResponse>;
-
-    async fn exec_command_streaming(
-        &self,
-        request: RemoteExecCommandRequest,
-        output_sink: RemoteExecStreamingOutputSink,
-    ) -> PortResult<RemoteExecCommandResponse>;
-
-    async fn write_stdin(
-        &self,
-        request: RemoteWriteStdinRequest,
-    ) -> PortResult<RemoteExecCommandResponse>;
-
-    async fn write_stdin_streaming(
-        &self,
-        request: RemoteWriteStdinRequest,
-        output_sink: RemoteExecStreamingOutputSink,
-    ) -> PortResult<RemoteExecCommandResponse>;
-
-    async fn send_stdin(&self, request: RemoteSendStdinRequest) -> PortResult<()>;
-
-    async fn control_session(
-        &self,
-        request: RemoteExecControlRequest,
-    ) -> PortResult<RemoteExecCommandResponse>;
-}
-
-pub trait NetworkPort: RuntimeServicePort {}
+#[cfg(feature = "agent-api")]
+mod agent_api;
+#[cfg(feature = "git-port")]
+mod git_port;
+#[cfg(feature = "remote-exec-port")]
+mod remote_exec_port;
+#[cfg(feature = "remote-workspace-ports")]
+mod remote_workspace_ports;
+#[cfg(feature = "runtime-event-port")]
+mod runtime_event_port;
+mod service_markers;
+#[cfg(feature = "terminal-port")]
+mod terminal_port;
+#[cfg(feature = "tool-runtime-handles")]
+mod tool_runtime_handles;
+#[cfg(feature = "workspace-ports")]
+mod workspace_ports;
+
+#[cfg(feature = "agent-api")]
+pub use agent_api::*;
+#[cfg(feature = "git-port")]
+pub use git_port::*;
+#[cfg(feature = "remote-exec-port")]
+pub use remote_exec_port::*;
+#[cfg(feature = "remote-workspace-ports")]
+pub use remote_workspace_ports::*;
+#[cfg(feature = "runtime-event-port")]
+pub use runtime_event_port::*;
+pub use service_markers::*;
+#[cfg(feature = "terminal-port")]
+pub use terminal_port::*;
+#[cfg(feature = "tool-runtime-handles")]
+pub use tool_runtime_handles::*;
+#[cfg(feature = "workspace-ports")]
+pub use workspace_ports::*;
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[serde(rename_all = "snake_case")]
-pub enum WorkspaceDiffFileStatus {
-    Added,
-    Modified,
-    Deleted,
-    Renamed,
-    Conflicted,
+pub enum AgentSubmissionSource {
+    DesktopUi,
+    DesktopApi,
+    AgentSession,
+    ScheduledJob,
+    RemoteRelay,
+    Bot,
+    Cli,
+    SdkHost,
 }
 
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(tag = "kind", rename_all = "snake_case")]
-pub enum WorkspaceDiffContent {
-    Text { patch: String },
-    Binary,
-    TooLarge,
-}
+pub type DialogTriggerSource = AgentSubmissionSource;
 
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+/// User-managed related directory reference for request-context prompts.
+#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
 #[serde(rename_all = "camelCase")]
-pub struct WorkspaceDiffFile {
+pub struct RelatedPath {
     pub path: String,
     #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub old_path: Option<String>,
-    pub status: WorkspaceDiffFileStatus,
-    pub staged: bool,
-    pub unstaged: bool,
-    pub untracked: bool,
-    pub additions: usize,
-    pub deletions: usize,
-    pub content: WorkspaceDiffContent,
-}
-
-#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct WorkspaceDiffSnapshot {
-    pub files: Vec<WorkspaceDiffFile>,
-    pub truncated: bool,
-}
-
-#[async_trait::async_trait]
-pub trait GitPort: RuntimeServicePort {
-    async fn workspace_diff(&self) -> PortResult<WorkspaceDiffSnapshot> {
-        Err(PortError::new(
-            PortErrorKind::NotAvailable,
-            "workspace diff is not supported by this provider",
-        ))
-    }
-}
-
-pub trait McpCatalogPort: RuntimeServicePort {}
-
-/// Typed registration boundary for remote connection providers.
-///
-/// PR1 intentionally keeps this trait handle-free; PR2 adds owner-specific
-/// lifecycle methods once behavior-equivalence tests are in place.
-pub trait RemoteConnectionPort: RuntimeServicePort {}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "snake_case")]
-pub enum RemoteWorkspaceKind {
-    Normal,
-    Assistant,
-    Remote,
-}
-
-impl RemoteWorkspaceKind {
-    pub const fn as_wire_str(self) -> &'static str {
-        match self {
-            Self::Normal => "normal",
-            Self::Assistant => "assistant",
-            Self::Remote => "remote",
-        }
-    }
+    pub description: Option<String>,
 }
 
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
-pub struct RemoteWorkspaceFacts {
-    pub path: String,
+pub struct DynamicToolDescriptor {
     pub name: String,
+    pub description: String,
+    pub input_schema: serde_json::Value,
     #[serde(skip_serializing_if = "Option::is_none")]
-    pub git_branch: Option<String>,
-    pub kind: RemoteWorkspaceKind,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub assistant_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_connection_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_ssh_host: Option<String>,
-}
-
-#[derive(Debug, Clone, Default, PartialEq, Eq)]
-pub struct RemoteSessionWorkspaceIdentity {
-    pub remote_connection_id: Option<String>,
-    pub remote_ssh_host: Option<String>,
-}
-
-impl RemoteSessionWorkspaceIdentity {
-    pub fn new(remote_connection_id: Option<String>, remote_ssh_host: Option<String>) -> Self {
-        Self {
-            remote_connection_id,
-            remote_ssh_host,
-        }
-    }
-
-    pub fn from_workspace(workspace: &RemoteWorkspaceFacts) -> Self {
-        Self::new(
-            workspace.remote_connection_id.clone(),
-            workspace.remote_ssh_host.clone(),
-        )
-    }
-
-    pub fn is_empty(&self) -> bool {
-        self.remote_connection_id.is_none() && self.remote_ssh_host.is_none()
-    }
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct RemoteRecentWorkspaceFacts {
-    pub path: String,
-    pub name: String,
-    pub last_opened: String,
-    pub kind: RemoteWorkspaceKind,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_connection_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_ssh_host: Option<String>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct RemoteAssistantWorkspaceFacts {
-    pub path: String,
-    pub name: String,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub assistant_id: Option<String>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct RemoteWorkspaceUpdate {
-    pub path: String,
-    pub name: String,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_connection_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_ssh_host: Option<String>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct RemoteSessionMetadata {
-    pub session_id: String,
-    pub name: String,
-    pub agent_type: String,
-    pub created_at_ms: u64,
-    pub last_active_at_ms: u64,
-    pub turn_count: usize,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct RemoteWorkspaceFileContent {
-    pub name: String,
-    pub bytes: Vec<u8>,
-    pub mime_type: &'static str,
-    pub size: u64,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct RemoteWorkspaceFileChunk {
-    pub name: String,
-    pub bytes: Vec<u8>,
-    pub offset: u64,
-    pub chunk_size: u64,
-    pub total_size: u64,
-    pub mime_type: &'static str,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct RemoteWorkspaceFileInfo {
-    pub name: String,
-    pub size: u64,
-    pub mime_type: &'static str,
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub struct RemoteFileChunkRange {
-    pub start: usize,
-    pub end: usize,
-    pub chunk_size: u64,
-}
-
-/// Old remote-connect host compatibility trait for workspace commands.
-#[async_trait::async_trait]
-pub trait RemoteWorkspaceRuntimeHost: Send + Sync {
-    async fn current_workspace(&self) -> Option<RemoteWorkspaceFacts>;
-    async fn recent_workspaces(&self) -> Vec<RemoteRecentWorkspaceFacts>;
-    async fn open_workspace(
-        &self,
-        path: &str,
-        remote_connection_id: Option<&str>,
-        remote_ssh_host: Option<&str>,
-    ) -> Result<RemoteWorkspaceUpdate, String>;
-    async fn assistant_workspaces(&self) -> Vec<RemoteAssistantWorkspaceFacts>;
-    async fn open_assistant_workspace(&self, path: &str) -> Result<RemoteWorkspaceUpdate, String>;
-}
-
-/// Typed registration boundary for remote workspace providers.
-pub trait RemoteWorkspacePort: RuntimeServicePort + RemoteWorkspaceRuntimeHost {}
-
-impl<T> RemoteWorkspacePort for T where T: RuntimeServicePort + RemoteWorkspaceRuntimeHost + ?Sized {}
-
-/// Old remote-connect host compatibility trait for initial sync.
-#[async_trait::async_trait]
-pub trait RemoteInitialSyncRuntimeHost: Send + Sync {
-    async fn current_workspace(&self) -> Option<RemoteWorkspaceFacts>;
-    async fn list_session_metadata(
-        &self,
-        workspace_path: &Path,
-        workspace_identity: RemoteSessionWorkspaceIdentity,
-    ) -> Result<Vec<RemoteSessionMetadata>, String>;
-}
-
-/// Old remote-connect host compatibility trait for remote file projection.
-#[async_trait::async_trait]
-pub trait RemoteWorkspaceFileRuntimeHost: Send + Sync {
-    async fn resolve_remote_file_workspace_root(&self, session_id: Option<&str>)
-        -> Option<PathBuf>;
-}
-
-/// Typed registration boundary for remote filesystem/terminal/image projection providers.
-pub trait RemoteProjectionPort: RuntimeServicePort + RemoteWorkspaceFileRuntimeHost {}
-
-impl<T> RemoteProjectionPort for T where
-    T: RuntimeServicePort + RemoteWorkspaceFileRuntimeHost + ?Sized
-{
-}
-
-/// Typed registration boundary for remote host capability facts.
-pub trait RemoteCapabilityPort: RuntimeServicePort {}
-
-#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[serde(rename_all = "camelCase")]
-pub struct AgentSessionCreateRequest {
-    pub session_name: String,
-    pub agent_type: String,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub workspace_path: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub project_workspace_path: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub execution_target: Option<SessionExecutionTarget>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub workspace_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_connection_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_ssh_host: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub model_id: Option<String>,
-    #[serde(default, skip_serializing_if = "serde_json::Map::is_empty")]
-    pub metadata: serde_json::Map<String, serde_json::Value>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[serde(rename_all = "camelCase")]
-pub struct AgentSessionCreateResult {
-    pub session_id: String,
-    #[serde(default)]
-    pub session_name: String,
-    pub agent_type: String,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub model_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub workspace_path: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub workspace_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub project_workspace_path: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub execution_target: Option<SessionExecutionTarget>,
-}
-
-impl AgentSessionCreateResult {
-    pub fn new(
-        session_id: impl Into<String>,
-        session_name: impl Into<String>,
-        agent_type: impl Into<String>,
-    ) -> Self {
-        Self {
-            session_id: session_id.into(),
-            session_name: session_name.into(),
-            agent_type: agent_type.into(),
-            model_id: None,
-            workspace_path: None,
-            workspace_id: None,
-            project_workspace_path: None,
-            execution_target: None,
-        }
-    }
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[serde(rename_all = "camelCase")]
-pub struct AgentSessionListRequest {
-    pub workspace_path: String,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_connection_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_ssh_host: Option<String>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[serde(rename_all = "camelCase")]
-pub struct AgentSessionSummary {
-    pub session_id: String,
-    pub session_name: String,
-    pub agent_type: String,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub model_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub reasoning_preset: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub last_user_dialog_agent_type: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub last_submitted_agent_type: Option<String>,
-    #[serde(default)]
-    pub turn_count: usize,
-    pub created_at_ms: u64,
-    pub last_active_at_ms: u64,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[serde(rename_all = "camelCase")]
-pub struct AgentSessionDeleteRequest {
-    pub workspace_path: String,
-    pub session_id: String,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_connection_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_ssh_host: Option<String>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[serde(rename_all = "camelCase")]
-pub struct AgentSessionRenameRequest {
-    pub workspace_path: String,
-    pub session_id: String,
-    pub session_name: String,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_connection_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_ssh_host: Option<String>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentSessionArchiveRequest {
-    pub workspace_path: String,
-    pub session_id: String,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_connection_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_ssh_host: Option<String>,
-}
-
-/// Sets the persisted archive state without exposing product-specific archive UI.
-///
-/// This is separate from [`AgentSessionArchiveRequest`] so existing archive-only
-/// consumers keep their current request shape and behavior.
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[serde(rename_all = "camelCase")]
-pub struct AgentSessionArchiveStateRequest {
-    pub workspace_path: String,
-    pub session_id: String,
-    pub archived: bool,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_connection_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_ssh_host: Option<String>,
-}
-
-/// Records one completed local command result in user-visible session history.
-///
-/// This request intentionally cannot select another turn kind or opt the turn
-/// into model context. It is not a generic transcript-writing contract.
-#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentLocalCommandTurnRecordRequest {
-    pub session_id: String,
-    pub content: String,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub turn_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub timestamp_ms: Option<u64>,
-    #[serde(default, skip_serializing_if = "serde_json::Map::is_empty")]
-    pub metadata: serde_json::Map<String, serde_json::Value>,
-}
-
-/// The authoritative persisted identity assigned to a completed local command Turn.
-///
-/// The product-facing adapter may use this result to reconcile a provisional UI
-/// projection. Catalog data remains owned by the session persistence boundary.
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentLocalCommandTurnRecordResult {
-    pub turn_id: String,
-    pub storage_turn_index: usize,
-}
-
-/// Starts one user-authored shell command as a normal, model-visible tool turn.
-///
-/// The caller provides the exact turn identity so interactive adapters can
-/// register cancellation before the side effect is admitted. Implementations
-/// must route execution through the normal tool, permission, and audit owners;
-/// this is not a generic process-spawn or arbitrary-tool contract.
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase", deny_unknown_fields)]
-pub struct AgentUserShellCommandRequest {
-    pub session_id: String,
-    pub turn_id: String,
-    pub command: String,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase", deny_unknown_fields)]
-pub struct AgentUserShellCommandResult {
-    pub session_id: String,
-    pub turn_id: String,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[serde(rename_all = "camelCase")]
-pub struct AgentSessionModelUpdateRequest {
-    pub session_id: String,
-    pub model_id: String,
-}
-
-/// Atomically selects a model and an optional reasoning preset for the next
-/// turn. The legacy model-only request remains available for older clients.
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentSessionModelSelection {
-    pub model_id: String,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub reasoning_preset: Option<String>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentSessionModelSelectionUpdateRequest {
-    pub session_id: String,
-    pub selection: AgentSessionModelSelection,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[serde(rename_all = "camelCase")]
-pub struct AgentSessionModeUpdateRequest {
-    pub session_id: String,
-    pub mode_id: String,
-}
-
-/// Starts one audited manual context-compaction maintenance turn.
-///
-/// The caller supplies the exact turn identity so process adapters can register
-/// cancellation ownership before the side effect is admitted.
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase", deny_unknown_fields)]
-pub struct AgentSessionCompactionRequest {
-    pub session_id: String,
-    pub turn_id: String,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase", deny_unknown_fields)]
-pub struct AgentSessionCompactionResult {
-    pub session_id: String,
-    pub turn_id: String,
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "snake_case")]
-pub enum AgentContextReloadTarget {
-    All,
-    Skills,
-    Instructions,
-}
-
-impl AgentContextReloadTarget {
-    pub const fn includes_skills(self) -> bool {
-        matches!(self, Self::All | Self::Skills)
-    }
-
-    pub const fn includes_instructions(self) -> bool {
-        matches!(self, Self::All | Self::Instructions)
-    }
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase", deny_unknown_fields)]
-pub struct AgentContextReloadRequest {
-    pub session_id: String,
-    pub target: AgentContextReloadTarget,
-}
-
-#[async_trait::async_trait]
-pub trait AgentContextReloadPort: Send + Sync {
-    async fn reload_session_context(&self, request: AgentContextReloadRequest) -> PortResult<()>;
-}
-
-#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-/// Delivers answers to a pending user-question tool call.
-pub struct AgentUserAnswersRequest {
-    pub tool_id: String,
-    pub answers: serde_json::Value,
-}
-
-#[async_trait::async_trait]
-/// Routes product responses to the existing user-input owner.
-///
-/// Implementations do not own approval policy or interaction lifecycle state.
-pub trait AgentInteractionResponsePort: Send + Sync {
-    async fn submit_user_answers(&self, request: AgentUserAnswersRequest) -> PortResult<()>;
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[serde(rename_all = "camelCase")]
-pub struct AgentSessionForkRequest {
-    pub workspace_path: String,
-    pub source_session_id: String,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_connection_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_ssh_host: Option<String>,
-}
-
-/// Forks a session at an explicitly selected persisted turn.
-///
-/// This is additive to [`AgentSessionForkRequest`] so existing Rust SDK
-/// consumers keep the source-compatible latest-turn request shape.
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[serde(rename_all = "camelCase")]
-pub struct AgentSessionForkAtTurnRequest {
-    pub workspace_path: String,
-    pub source_session_id: String,
-    pub source_turn_id: String,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_connection_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_ssh_host: Option<String>,
-}
-
-/// Forks a session immediately before an explicitly selected persisted turn.
-///
-/// The selected turn is the replayable prompt boundary and is not copied into
-/// the fork. This stays separate from [`AgentSessionForkAtTurnRequest`] so its
-/// inclusive behavior remains source- and behavior-compatible.
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[serde(rename_all = "camelCase")]
-pub struct AgentSessionForkBeforeTurnRequest {
-    pub workspace_path: String,
-    pub source_session_id: String,
-    pub source_turn_id: String,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_connection_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_ssh_host: Option<String>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[serde(rename_all = "camelCase")]
-pub struct AgentSessionForkResult {
-    pub session_id: String,
-    pub session_name: String,
-    pub agent_type: String,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentSessionUsageRequest {
-    pub session_id: String,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub workspace_path: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_connection_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_ssh_host: Option<String>,
-    #[serde(default)]
-    pub include_hidden_subagents: bool,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentTurnSettlementRequest {
-    pub session_id: String,
-    pub turn_id: String,
-    pub wait_timeout_ms: u64,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentSessionWorkspaceRequest {
-    pub session_id: String,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentSessionWorkspaceBinding {
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub workspace_id: Option<String>,
-    pub workspace_path: String,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub project_workspace_path: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub execution_target: Option<SessionExecutionTarget>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_connection_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_ssh_host: Option<String>,
-}
-
-pub const AGENT_WORKSPACE_REFERENCES_METADATA_KEY: &str = "workspace_references";
-pub const MAX_AGENT_WORKSPACE_REFERENCES_PER_TURN: usize = 20;
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "snake_case")]
-pub enum AgentWorkspaceReferenceKind {
-    File,
-    Directory,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentWorkspaceReferenceSourceRange {
-    /// Zero-based character offset in the original user input.
-    pub start: usize,
-    /// Exclusive zero-based character offset in the original user input.
-    pub end: usize,
-    pub value: String,
-}
-
-/// A user-selected workspace path carried as structured turn metadata.
-///
-/// The path is workspace-relative and slash-normalized. It is not an
-/// authorization token: the runtime owner validates the current Session
-/// binding and path again before accepting the turn.
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentWorkspaceReference {
-    pub path: String,
-    pub kind: AgentWorkspaceReferenceKind,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub start_line: Option<u32>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub end_line: Option<u32>,
-    pub source: AgentWorkspaceReferenceSourceRange,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentWorkspaceReferenceSearchRequest {
-    pub session_id: String,
-    #[serde(default)]
-    pub query: String,
-    pub limit: usize,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentWorkspaceReferenceSearchEntry {
-    pub path: String,
-    pub kind: AgentWorkspaceReferenceKind,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentWorkspaceReferenceSearchResult {
-    #[serde(default)]
-    pub entries: Vec<AgentWorkspaceReferenceSearchEntry>,
-    #[serde(default)]
-    pub truncated: bool,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentMessageWorkspaceReferencesRequest {
-    pub session_id: String,
-    pub message_id: String,
-}
-
-pub fn put_agent_workspace_references(
-    metadata: &mut serde_json::Map<String, serde_json::Value>,
-    references: &[AgentWorkspaceReference],
-) -> PortResult<()> {
-    if references.is_empty() {
-        metadata.remove(AGENT_WORKSPACE_REFERENCES_METADATA_KEY);
-        return Ok(());
-    }
-    if references.len() > MAX_AGENT_WORKSPACE_REFERENCES_PER_TURN {
-        return Err(PortError::new(
-            PortErrorKind::InvalidRequest,
-            format!(
-                "a message can reference at most {MAX_AGENT_WORKSPACE_REFERENCES_PER_TURN} workspace paths"
-            ),
-        ));
-    }
-    let value = serde_json::to_value(references).map_err(|error| {
-        PortError::new(
-            PortErrorKind::InvalidRequest,
-            format!("failed to serialize workspace references: {error}"),
-        )
-    })?;
-    metadata.insert(AGENT_WORKSPACE_REFERENCES_METADATA_KEY.to_string(), value);
-    Ok(())
-}
-
-pub fn agent_workspace_references_from_metadata(
-    metadata: &serde_json::Map<String, serde_json::Value>,
-) -> PortResult<Vec<AgentWorkspaceReference>> {
-    let Some(value) = metadata.get(AGENT_WORKSPACE_REFERENCES_METADATA_KEY) else {
-        return Ok(Vec::new());
-    };
-    let references: Vec<AgentWorkspaceReference> =
-        serde_json::from_value(value.clone()).map_err(|error| {
-            PortError::new(
-                PortErrorKind::InvalidRequest,
-                format!("invalid workspace reference metadata: {error}"),
-            )
-        })?;
-    if references.len() > MAX_AGENT_WORKSPACE_REFERENCES_PER_TURN {
-        return Err(PortError::new(
-            PortErrorKind::InvalidRequest,
-            format!(
-                "a message can reference at most {MAX_AGENT_WORKSPACE_REFERENCES_PER_TURN} workspace paths"
-            ),
-        ));
-    }
-    Ok(references)
-}
-
-#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[serde(rename_all = "camelCase")]
-pub struct AgentSubmissionRequest {
-    pub session_id: String,
-    pub message: String,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub turn_id: Option<String>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub source: Option<AgentSubmissionSource>,
-    #[serde(default, skip_serializing_if = "Vec::is_empty")]
-    pub attachments: Vec<AgentInputAttachment>,
-    #[serde(default, skip_serializing_if = "serde_json::Map::is_empty")]
-    pub metadata: serde_json::Map<String, serde_json::Value>,
-}
-
-#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[serde(
-    tag = "kind",
-    rename_all = "snake_case",
-    rename_all_fields = "camelCase",
-    deny_unknown_fields
-)]
-pub enum AgentDialogTurnExecution {
-    Standard,
-    FreshExternalSubagent {
-        ecosystem_id: String,
-        logical_id: String,
-    },
-}
-
-impl Default for AgentDialogTurnExecution {
-    fn default() -> Self {
-        Self::Standard
-    }
-}
-
-#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentDialogTurnRequest {
-    pub session_id: String,
-    pub message: String,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub original_message: Option<String>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub turn_id: Option<String>,
-    #[serde(default, skip_serializing_if = "AgentDialogTurnExecution::is_standard")]
-    pub execution: AgentDialogTurnExecution,
-    pub agent_type: String,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub workspace_path: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_connection_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_ssh_host: Option<String>,
-    pub policy: DialogSubmissionPolicy,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub reply_route: Option<AgentSessionReplyRoute>,
-    #[serde(default, skip_serializing_if = "Vec::is_empty")]
-    pub prepended_reminders: Vec<AgentDialogPrependedReminder>,
-    #[serde(default, skip_serializing_if = "Vec::is_empty")]
-    pub attachments: Vec<AgentInputAttachment>,
-    #[serde(default, skip_serializing_if = "serde_json::Map::is_empty")]
-    pub metadata: serde_json::Map<String, serde_json::Value>,
-}
-
-/// Text-only steering request for one exact running dialog turn.
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase", deny_unknown_fields)]
-pub struct AgentDialogSteerRequest {
-    pub session_id: String,
-    pub turn_id: String,
-    pub content: String,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub display_content: Option<String>,
-}
-
-impl AgentDialogTurnExecution {
-    pub fn is_standard(&self) -> bool {
-        matches!(self, Self::Standard)
-    }
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentDialogPrependedReminder {
-    pub kind: String,
-    pub text: String,
-}
-
-#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentBackgroundResultRequest {
-    pub session_id: String,
-    pub agent_type: String,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub workspace_path: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_connection_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_ssh_host: Option<String>,
-    pub content: String,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub display_content: Option<String>,
-    #[serde(default, skip_serializing_if = "serde_json::Map::is_empty")]
-    pub metadata: serde_json::Map<String, serde_json::Value>,
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "snake_case")]
-pub enum AgentThreadGoalDeliveryKind {
-    Resumed,
-    ObjectiveUpdated,
-}
-
-#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentThreadGoalDeliveryRequest {
-    pub session_id: String,
-    pub agent_type: String,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub workspace_path: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_connection_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_ssh_host: Option<String>,
-    pub kind: AgentThreadGoalDeliveryKind,
-    pub goal: ThreadGoal,
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[serde(rename_all = "snake_case")]
-pub enum AgentSubmissionSource {
-    DesktopUi,
-    DesktopApi,
-    AgentSession,
-    ScheduledJob,
-    RemoteRelay,
-    Bot,
-    Cli,
-    SdkHost,
-}
-
-pub type DialogTriggerSource = AgentSubmissionSource;
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[serde(rename_all = "snake_case")]
-pub enum DialogQueuePriority {
-    Low = 0,
-    Normal = 1,
-    High = 2,
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[serde(rename_all = "camelCase")]
-pub struct DialogSubmissionPolicy {
-    pub trigger_source: DialogTriggerSource,
-    pub queue_priority: DialogQueuePriority,
-}
-
-impl DialogSubmissionPolicy {
-    pub const fn new(
-        trigger_source: DialogTriggerSource,
-        queue_priority: DialogQueuePriority,
-    ) -> Self {
-        Self {
-            trigger_source,
-            queue_priority,
-        }
-    }
-
-    pub const fn for_source(trigger_source: DialogTriggerSource) -> Self {
-        let queue_priority = match trigger_source {
-            DialogTriggerSource::AgentSession => DialogQueuePriority::Low,
-            DialogTriggerSource::ScheduledJob => DialogQueuePriority::Low,
-            DialogTriggerSource::DesktopUi
-            | DialogTriggerSource::DesktopApi
-            | DialogTriggerSource::Cli
-            | DialogTriggerSource::SdkHost => DialogQueuePriority::Normal,
-            DialogTriggerSource::RemoteRelay | DialogTriggerSource::Bot => {
-                DialogQueuePriority::Normal
-            }
-        };
-        Self::new(trigger_source, queue_priority)
-    }
-
-    pub const fn with_queue_priority(mut self, queue_priority: DialogQueuePriority) -> Self {
-        self.queue_priority = queue_priority;
-        self
-    }
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub enum DialogSubmitOutcome {
-    Started { session_id: String, turn_id: String },
-    Queued { session_id: String, turn_id: String },
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "snake_case")]
-pub enum DialogSessionStateFact {
-    Missing,
-    Idle,
-    Processing,
-    Error,
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub struct DialogSubmitQueueFacts {
-    pub session_state: DialogSessionStateFact,
-    pub queue_has_items: bool,
-    pub policy: DialogSubmissionPolicy,
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum DialogSubmitQueueAction {
-    StartImmediately,
-    ClearQueueAndStartImmediately,
-    EnqueueThenStartNext,
-    EnqueueForActiveTurn,
-}
-
-pub const fn resolve_dialog_submit_queue_action(
-    facts: DialogSubmitQueueFacts,
-) -> DialogSubmitQueueAction {
-    match facts.session_state {
-        DialogSessionStateFact::Missing => DialogSubmitQueueAction::StartImmediately,
-        DialogSessionStateFact::Error => DialogSubmitQueueAction::ClearQueueAndStartImmediately,
-        DialogSessionStateFact::Idle => {
-            if facts.queue_has_items {
-                DialogSubmitQueueAction::EnqueueThenStartNext
-            } else {
-                DialogSubmitQueueAction::StartImmediately
-            }
-        }
-        DialogSessionStateFact::Processing => DialogSubmitQueueAction::EnqueueForActiveTurn,
-    }
-}
-
-pub fn should_suppress_agent_session_cancelled_reply(
-    policy: &DialogSubmissionPolicy,
-    reply_source_session_id: Option<&str>,
-    requester_session_id: &str,
-) -> bool {
-    policy.trigger_source == DialogTriggerSource::AgentSession
-        && reply_source_session_id.is_some_and(|source| source == requester_session_id)
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum DialogTurnOutcomeKind {
-    Completed,
-    Cancelled,
-    Failed,
-}
-
-pub const fn should_skip_agent_session_reply(
-    outcome_kind: DialogTurnOutcomeKind,
-    suppressed_cancelled_reply: bool,
-) -> bool {
-    matches!(outcome_kind, DialogTurnOutcomeKind::Cancelled) && suppressed_cancelled_reply
-}
-
-/// Source session route used when an agent-session request should reply to the
-/// requester after the target session finishes.
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentSessionReplyRoute {
-    pub source_session_id: String,
-    pub source_workspace_path: String,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub source_remote_connection_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub source_remote_ssh_host: Option<String>,
-}
-
-/// Outcome for steering a message into an already-running dialog turn.
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(
-    tag = "kind",
-    rename_all = "snake_case",
-    rename_all_fields = "camelCase",
-    deny_unknown_fields
-)]
-pub enum DialogSteerOutcome {
-    /// Steering was buffered for the running turn and will be consumed at the
-    /// next model-round boundary.
-    Buffered {
-        session_id: String,
-        turn_id: String,
-        steering_id: String,
-    },
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum RoundInjectionKind {
-    UserSteering,
-    BackgroundResult,
-    ThreadGoalObjectiveUpdated,
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
-pub enum RoundInjectionToolPreemption {
-    None,
-    InterruptAfterCurrentAtomicUnit,
-    CancelRunningCooperatively,
-    CancelRunningForcefully,
-}
-
-impl RoundInjectionToolPreemption {
-    pub const fn should_interrupt_after_current_atomic_unit(self) -> bool {
-        !matches!(self, Self::None)
-    }
-
-    pub const fn should_cancel_running_tools(self) -> bool {
-        matches!(
-            self,
-            Self::CancelRunningCooperatively | Self::CancelRunningForcefully
-        )
-    }
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub struct RoundInjectionExecutionPolicy {
-    pub tool_preemption: RoundInjectionToolPreemption,
-}
-
-impl RoundInjectionExecutionPolicy {
-    pub const fn new(tool_preemption: RoundInjectionToolPreemption) -> Self {
-        Self { tool_preemption }
-    }
-}
-
-impl Default for RoundInjectionExecutionPolicy {
-    fn default() -> Self {
-        Self::new(RoundInjectionToolPreemption::None)
-    }
-}
-
-impl RoundInjectionKind {
-    pub const fn default_execution_policy(self) -> RoundInjectionExecutionPolicy {
-        match self {
-            Self::UserSteering => RoundInjectionExecutionPolicy::new(
-                RoundInjectionToolPreemption::InterruptAfterCurrentAtomicUnit,
-            ),
-            Self::BackgroundResult | Self::ThreadGoalObjectiveUpdated => {
-                RoundInjectionExecutionPolicy::new(RoundInjectionToolPreemption::None)
-            }
-        }
-    }
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub enum RoundInjectionTarget {
-    /// Only inject into the exact targeted running turn.
-    ExactTurn(String),
-    /// Inject into whichever turn is currently running for the session.
-    CurrentRunningTurn,
-}
-
-/// A message to inject into the currently running dialog turn at the next
-/// model-round boundary.
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct RoundInjection {
-    pub id: String,
-    pub kind: RoundInjectionKind,
-    pub execution_policy: RoundInjectionExecutionPolicy,
-    pub target: RoundInjectionTarget,
-    pub content: String,
-    pub display_content: String,
-    pub created_at: std::time::SystemTime,
-}
-
-/// Observes round-boundary injections for a given running turn.
-pub trait DialogRoundInjectionSource: Send + Sync {
-    fn has_pending(&self, session_id: &str, turn_id: &str) -> bool;
-    fn pending_tool_preemption(
-        &self,
-        session_id: &str,
-        turn_id: &str,
-    ) -> RoundInjectionToolPreemption;
-    fn take_pending(&self, session_id: &str, turn_id: &str) -> Vec<RoundInjection>;
-
-    fn acknowledge_consumed(
-        &self,
-        _session_id: &str,
-        _turn_id: &str,
-        _injection_id: &str,
-        _kind: RoundInjectionKind,
-    ) {
-    }
-}
-
-/// Legacy session metadata key for the pre-Codex goal mode experiment.
-pub const GOAL_MODE_METADATA_KEY: &str = "goal_mode";
-
-/// Persisted thread goal stored in session custom metadata.
-pub const THREAD_GOAL_METADATA_KEY: &str = "thread_goal";
-
-pub const MAX_THREAD_GOAL_OBJECTIVE_CHARS: usize = 4_000;
-
-pub const MAX_CONTEXT_SUMMARY_CHARS: usize = 12_000;
-
-/// Max automatic goal continuation dialog turns per objective (legacy goal_mode parity).
-pub const MAX_THREAD_GOAL_AUTO_CONTINUATIONS: u32 = 100;
-
-/// Alias retained for migration from legacy `goal_mode` metadata and docs.
-pub const MAX_GOAL_CONTINUATIONS: u32 = MAX_THREAD_GOAL_AUTO_CONTINUATIONS;
-
-#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
-#[serde(rename_all = "camelCase")]
-pub enum ThreadGoalStatus {
-    Active,
-    Paused,
-    Blocked,
-    UsageLimited,
-    BudgetLimited,
-    Complete,
-}
-
-impl ThreadGoalStatus {
-    pub fn as_str(self) -> &'static str {
-        match self {
-            Self::Active => "active",
-            Self::Paused => "paused",
-            Self::Blocked => "blocked",
-            Self::UsageLimited => "usageLimited",
-            Self::BudgetLimited => "budgetLimited",
-            Self::Complete => "complete",
-        }
-    }
-}
-
-pub fn validate_thread_goal_objective(value: &str) -> Result<(), String> {
-    if value.trim().is_empty() {
-        return Err("goal objective must not be empty".to_string());
-    }
-    if value.chars().count() > MAX_THREAD_GOAL_OBJECTIVE_CHARS {
-        return Err(format!(
-            "goal objective must be at most {MAX_THREAD_GOAL_OBJECTIVE_CHARS} characters"
-        ));
-    }
-    Ok(())
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
-#[serde(rename_all = "camelCase")]
-pub struct ThreadGoal {
-    pub goal_id: String,
-    pub session_id: String,
-    pub objective: String,
-    pub status: ThreadGoalStatus,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub token_budget: Option<i64>,
-    #[serde(default)]
-    pub tokens_used: i64,
-    #[serde(default)]
-    pub time_used_seconds: i64,
-    pub created_at: i64,
-    pub updated_at: i64,
-    /// Auto-continuation dialog turns scheduled toward this goal (resets on new objective).
-    #[serde(default)]
-    pub auto_continuation_count: u32,
-}
-
-impl ThreadGoal {
-    pub fn is_active(&self) -> bool {
-        matches!(
-            self.status,
-            ThreadGoalStatus::Active | ThreadGoalStatus::BudgetLimited
-        )
-    }
-
-    pub fn remaining_tokens(&self) -> Option<i64> {
-        self.token_budget
-            .map(|budget| (budget - self.tokens_used).max(0))
-    }
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct SetThreadGoalResult {
-    pub goal: ThreadGoal,
-    pub replaced_existing: bool,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct ThreadGoalContinuationPlan {
-    pub prepended_reminders: Vec<String>,
-    pub display_message: String,
-    pub user_message_metadata: serde_json::Value,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
-#[serde(rename_all = "camelCase")]
-pub struct ThreadGoalToolResponse {
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub goal: Option<ThreadGoal>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remaining_tokens: Option<i64>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub completion_budget_report: Option<String>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentThreadGoalGetRequest {
-    pub session_id: String,
-    pub workspace_path: String,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_connection_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_ssh_host: Option<String>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentThreadGoalCreateRequest {
-    pub session_id: String,
-    pub workspace_path: String,
-    pub objective: String,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub token_budget: Option<i64>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentThreadGoalUpdateStatusRequest {
-    pub session_id: String,
-    pub workspace_path: String,
-    pub status: ThreadGoalStatus,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub turn_id: Option<String>,
-}
-
-#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
-pub struct CompressionContract {
-    #[serde(default, skip_serializing_if = "Vec::is_empty")]
-    pub touched_files: Vec<String>,
-    #[serde(default, skip_serializing_if = "Vec::is_empty")]
-    pub verification_commands: Vec<CompressionContractItem>,
-    #[serde(default, skip_serializing_if = "Vec::is_empty")]
-    pub blocking_failures: Vec<CompressionContractItem>,
-    #[serde(default, skip_serializing_if = "Vec::is_empty")]
-    pub subagent_statuses: Vec<CompressionContractItem>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-pub struct CompressionContractItem {
-    pub target: String,
-    pub status: String,
-    pub summary: String,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub error_kind: Option<String>,
-}
-
-impl CompressionContract {
-    pub fn is_empty(&self) -> bool {
-        self.touched_files.is_empty()
-            && self.verification_commands.is_empty()
-            && self.blocking_failures.is_empty()
-            && self.subagent_statuses.is_empty()
-    }
-
-    pub fn render_for_model(&self) -> String {
-        let mut lines = vec![
-            "The following facts were retained during compression. Use them as authoritative context when continuing the task."
-                .to_string(),
-        ];
-
-        if !self.touched_files.is_empty() {
-            lines.push("Touched files:".to_string());
-            for file in &self.touched_files {
-                lines.push(format!("- {}", file));
-            }
-        }
-
-        render_contract_items(
-            &mut lines,
-            "Verification commands:",
-            &self.verification_commands,
-        );
-        render_contract_items(&mut lines, "Blocking failures:", &self.blocking_failures);
-        render_contract_items(&mut lines, "Subagent statuses:", &self.subagent_statuses);
-
-        lines.join("\n")
-    }
-}
-
-fn render_contract_items(lines: &mut Vec<String>, title: &str, items: &[CompressionContractItem]) {
-    if items.is_empty() {
-        return;
-    }
-
-    lines.push(title.to_string());
-    for item in items {
-        let mut rendered = format!("- {} [{}]: {}", item.target, item.status, item.summary);
-        if let Some(error_kind) = item.error_kind.as_ref() {
-            rendered.push_str(&format!(" ({})", error_kind));
-        }
-        lines.push(rendered);
-    }
-}
-
-/// User-managed related directory reference for request-context prompts.
-#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
-#[serde(rename_all = "camelCase")]
-pub struct RelatedPath {
-    pub path: String,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub description: Option<String>,
-}
-
-#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[serde(rename_all = "camelCase")]
-pub struct AgentInputAttachment {
-    pub kind: String,
-    pub id: String,
-    #[serde(default, skip_serializing_if = "serde_json::Map::is_empty")]
-    pub metadata: serde_json::Map<String, serde_json::Value>,
-}
-
-impl AgentInputAttachment {
-    pub fn remote_image(
-        id: impl Into<String>,
-        name: impl Into<String>,
-        data_url: impl Into<String>,
-    ) -> Self {
-        let mut metadata = serde_json::Map::new();
-        metadata.insert("name".to_string(), serde_json::Value::String(name.into()));
-        metadata.insert(
-            "dataUrl".to_string(),
-            serde_json::Value::String(data_url.into()),
-        );
-
-        Self {
-            kind: "remote_image".to_string(),
-            id: id.into(),
-            metadata,
-        }
-    }
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[serde(rename_all = "camelCase")]
-pub struct AgentSubmissionResult {
-    pub turn_id: String,
-    #[serde(default)]
-    pub accepted: bool,
-}
-
-#[async_trait::async_trait]
-pub trait AgentSubmissionPort: Send + Sync {
-    async fn create_session(
-        &self,
-        request: AgentSessionCreateRequest,
-    ) -> PortResult<AgentSessionCreateResult>;
-
-    /// Creates a session with an exact caller-provided identity.
-    ///
-    /// Providers that do not support exact identity creation keep the default
-    /// typed unsupported response. A successful response must preserve
-    /// `session_id` exactly.
-    async fn create_session_with_id(
-        &self,
-        session_id: String,
-        request: AgentSessionCreateRequest,
-    ) -> PortResult<AgentSessionCreateResult> {
-        let _ = (session_id, request);
-        Err(PortError::new(
-            PortErrorKind::NotAvailable,
-            "exact session identity creation is not supported by this provider",
-        ))
-    }
-
-    /// Creates one caller-identified connection-scoped Session.
-    ///
-    /// The Session uses the normal Runtime owners but must not become durable
-    /// product state. This narrow operation lets process adapters provide
-    /// bounded cleanup without pretending that crash-safe durable creation has
-    /// already been specified.
-    async fn create_transient_session_with_id(
-        &self,
-        session_id: String,
-        request: AgentSessionCreateRequest,
-    ) -> PortResult<AgentSessionCreateResult> {
-        let _ = (session_id, request);
-        Err(PortError::new(
-            PortErrorKind::NotAvailable,
-            "transient exact session creation is not supported by this provider",
-        ))
-    }
-
-    async fn submit_message(
-        &self,
-        request: AgentSubmissionRequest,
-    ) -> PortResult<AgentSubmissionResult>;
-
-    async fn resolve_session_agent_type(&self, session_id: &str) -> PortResult<Option<String>>;
-}
-
-#[async_trait::async_trait]
-pub trait AgentSessionManagementPort: Send + Sync {
-    async fn list_sessions(
-        &self,
-        request: AgentSessionListRequest,
-    ) -> PortResult<Vec<AgentSessionSummary>>;
-
-    async fn delete_session(&self, request: AgentSessionDeleteRequest) -> PortResult<()>;
-
-    async fn rename_session(&self, request: AgentSessionRenameRequest) -> PortResult<()> {
-        let _ = request;
-        Err(PortError::new(
-            PortErrorKind::NotAvailable,
-            "session rename is not supported by this provider",
-        ))
-    }
-
-    async fn archive_session(&self, request: AgentSessionArchiveRequest) -> PortResult<()> {
-        let _ = request;
-        Err(PortError::new(
-            PortErrorKind::NotAvailable,
-            "session archive is not supported by this provider",
-        ))
-    }
-
-    async fn set_session_archived(
-        &self,
-        request: AgentSessionArchiveStateRequest,
-    ) -> PortResult<()> {
-        if request.archived {
-            return self
-                .archive_session(AgentSessionArchiveRequest {
-                    workspace_path: request.workspace_path,
-                    session_id: request.session_id,
-                    remote_connection_id: request.remote_connection_id,
-                    remote_ssh_host: request.remote_ssh_host,
-                })
-                .await;
-        }
-        Err(PortError::new(
-            PortErrorKind::NotAvailable,
-            "session unarchive is not supported by this provider",
-        ))
-    }
-
-    async fn resolve_session_workspace_binding(
-        &self,
-        request: AgentSessionWorkspaceRequest,
-    ) -> PortResult<Option<AgentSessionWorkspaceBinding>>;
-}
-
-/// Provider-neutral lifecycle facts needed to render a Session lineage.
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "snake_case")]
-pub enum AgentSessionLifecycleStatus {
-    Active,
-    Archived,
-    Completed,
-}
-
-/// Minimal Session facts exposed by the Runtime lineage capability.
-///
-/// This intentionally does not mirror the persistence owner's full metadata
-/// object. Product surfaces receive only the stable facts required for
-/// navigation and status display.
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentSessionLineageEntry {
-    pub session_id: String,
-    pub session_name: String,
-    pub agent_type: String,
-    pub created_at_ms: u64,
-    pub status: AgentSessionLifecycleStatus,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub active_turn_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub parent_session_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub parent_tool_call_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub subagent_type: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub workspace_path: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_connection_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_ssh_host: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub unread_completion: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub needs_user_attention: Option<String>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentSessionLineageSnapshot {
-    pub root_session_id: String,
-    #[serde(default)]
-    pub sessions: Vec<AgentSessionLineageEntry>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentSessionLineageRequest {
-    pub workspace_path: String,
-    pub anchor_session_id: String,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_connection_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_ssh_host: Option<String>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentSessionLineageTranscriptRequest {
-    pub workspace_path: String,
-    pub root_session_id: String,
-    pub session_id: String,
-    /// Terminal Turns that an authoritative read must prove settled. This is a
-    /// read-consistency precondition; settlement and transcript construction
-    /// remain Runtime-owned.
-    #[serde(default, skip_serializing_if = "Vec::is_empty")]
-    pub required_settled_turn_ids: Vec<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_connection_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_ssh_host: Option<String>,
-}
-
-#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentSessionLineageInspection {
-    pub transcript: SessionTranscript,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub active_turn_id: Option<String>,
-}
-
-#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentSessionLineageCancellationRequest {
-    pub workspace_path: String,
-    pub root_session_id: String,
-    pub session_id: String,
-    /// Exact Turn shown as active when the user requested interruption. The
-    /// Runtime rejects a changed target instead of cancelling a newer Turn.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub expected_active_turn_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub source: Option<AgentSubmissionSource>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub reason: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub wait_timeout_ms: Option<u64>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_connection_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_ssh_host: Option<String>,
-}
-
-/// Authoritative Session-lineage use cases shared by product surfaces.
-///
-/// The provider owns persistence scope, legacy relationship normalization,
-/// membership/order, and consistent transcript reads. Surfaces may project
-/// the returned flat snapshot into their own tree presentation, but must not
-/// recompute lineage facts or read Session files directly.
-#[async_trait::async_trait]
-pub trait AgentSessionLineagePort: Send + Sync {
-    async fn get_session_lineage(
-        &self,
-        request: AgentSessionLineageRequest,
-    ) -> PortResult<Option<AgentSessionLineageSnapshot>>;
-
-    async fn read_lineage_session_transcript(
-        &self,
-        request: AgentSessionLineageTranscriptRequest,
-    ) -> PortResult<AgentSessionLineageInspection>;
-
-    async fn cancel_lineage_session(
-        &self,
-        request: AgentSessionLineageCancellationRequest,
-    ) -> PortResult<AgentTurnCancellationResult>;
-}
-
-/// Narrow workspace-reference use cases shared by first-party interactive
-/// adapters. Implementations keep filesystem search and persisted message
-/// lookup behind the authoritative Session owner.
-#[async_trait::async_trait]
-pub trait AgentWorkspaceReferencePort: Send + Sync {
-    async fn search_workspace_references(
-        &self,
-        request: AgentWorkspaceReferenceSearchRequest,
-    ) -> PortResult<AgentWorkspaceReferenceSearchResult>;
-
-    async fn workspace_references_for_message(
-        &self,
-        request: AgentMessageWorkspaceReferencesRequest,
-    ) -> PortResult<Vec<AgentWorkspaceReference>>;
-}
-
-/// Deadline-bearing request for discarding a connection-scoped transient
-/// Session. This is separate from [`AgentSessionDeleteRequest`] so adding Host
-/// cleanup policy cannot break the established Rust Session-management API.
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct AgentTransientSessionDiscardRequest {
-    pub workspace_path: String,
-    pub session_id: String,
-    pub remote_connection_id: Option<String>,
-    pub remote_ssh_host: Option<String>,
-    pub wait_timeout_ms: u64,
-}
-
-/// Runtime lifecycle owner for connection-scoped Session cleanup.
-#[async_trait::async_trait]
-pub trait AgentSessionClosePort: Send + Sync {
-    /// Quiesces and discards only a loaded transient Session owned by the
-    /// caller. Implementations must reject durable Sessions and must never
-    /// remove persisted Session storage through this operation.
-    async fn discard_transient_session(
-        &self,
-        request: AgentTransientSessionDiscardRequest,
-    ) -> PortResult<bool> {
-        let _ = request;
-        Err(PortError::new(
-            PortErrorKind::NotAvailable,
-            "transient session discard is not supported by this provider",
-        ))
-    }
-}
-
-#[async_trait::async_trait]
-pub trait AgentLocalCommandTurnPort: Send + Sync {
-    async fn record_completed_local_command_turn(
-        &self,
-        request: AgentLocalCommandTurnRecordRequest,
-    ) -> PortResult<AgentLocalCommandTurnRecordResult>;
-}
-
-#[async_trait::async_trait]
-pub trait AgentUserShellCommandPort: Send + Sync {
-    async fn run_user_shell_command(
-        &self,
-        request: AgentUserShellCommandRequest,
-    ) -> PortResult<AgentUserShellCommandResult>;
-}
-
-#[async_trait::async_trait]
-pub trait AgentSessionModelPort: Send + Sync {
-    async fn update_session_model_selection(
-        &self,
-        request: AgentSessionModelSelectionUpdateRequest,
-    ) -> PortResult<()>;
-
-    async fn update_session_model(
-        &self,
-        request: AgentSessionModelUpdateRequest,
-    ) -> PortResult<()> {
-        self.update_session_model_selection(AgentSessionModelSelectionUpdateRequest {
-            session_id: request.session_id,
-            selection: AgentSessionModelSelection {
-                model_id: request.model_id,
-                reasoning_preset: None,
-            },
-        })
-        .await
-    }
-}
-
-#[async_trait::async_trait]
-pub trait AgentSessionModePort: Send + Sync {
-    async fn update_session_mode(&self, request: AgentSessionModeUpdateRequest) -> PortResult<()>;
-}
-
-#[async_trait::async_trait]
-pub trait AgentSessionCompactionPort: Send + Sync {
-    async fn start_session_compaction(
-        &self,
-        request: AgentSessionCompactionRequest,
-    ) -> PortResult<AgentSessionCompactionResult>;
-}
-
-/// Local Session history mutation requested by an interactive product surface.
-///
-/// This is deliberately narrower than a generic checkpoint or workspace rewind
-/// API: one Core-owned operation keeps the persisted transcript, model context,
-/// and tracked workspace files on the same staged boundary.
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentSessionRevertRequest {
-    pub workspace_path: String,
-    pub session_id: String,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_connection_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_ssh_host: Option<String>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(tag = "kind", rename_all = "snake_case")]
-pub enum AgentSessionComposerUpdate {
-    Preserve,
-    Replace { text: String },
-    Clear,
-}
-
-#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentSessionRevertResult {
-    pub session_id: String,
-    pub transcript: SessionTranscript,
-    pub composer: AgentSessionComposerUpdate,
-    /// Active and queued Turns retired by the maintenance boundary. Consumers
-    /// use this as an event-stream fence after replacing their local projection.
-    #[serde(default, skip_serializing_if = "Vec::is_empty")]
-    pub retired_turn_ids: Vec<String>,
-    pub changed: bool,
-    pub hidden_turn_count: usize,
-}
-
-#[async_trait::async_trait]
-pub trait AgentSessionRevertPort: Send + Sync {
-    async fn undo_session(
-        &self,
-        request: AgentSessionRevertRequest,
-    ) -> PortResult<AgentSessionRevertResult>;
-
-    async fn redo_session(
-        &self,
-        request: AgentSessionRevertRequest,
-    ) -> PortResult<AgentSessionRevertResult>;
-}
-
-#[async_trait::async_trait]
-pub trait AgentSessionForkPort: Send + Sync {
-    async fn fork_session(
-        &self,
-        request: AgentSessionForkRequest,
-    ) -> PortResult<AgentSessionForkResult>;
-
-    async fn fork_session_at_turn(
-        &self,
-        request: AgentSessionForkAtTurnRequest,
-    ) -> PortResult<AgentSessionForkResult> {
-        let _ = request;
-        Err(PortError::new(
-            PortErrorKind::NotAvailable,
-            "exact-turn session fork is not supported by this provider",
-        ))
-    }
-
-    async fn fork_session_before_turn(
-        &self,
-        request: AgentSessionForkBeforeTurnRequest,
-    ) -> PortResult<AgentSessionForkResult> {
-        let _ = request;
-        Err(PortError::new(
-            PortErrorKind::NotAvailable,
-            "before-turn session fork is not supported by this provider",
-        ))
-    }
-}
-
-#[async_trait::async_trait]
-pub trait AgentSessionUsagePort: Send + Sync {
-    async fn generate_session_usage(
-        &self,
-        request: AgentSessionUsageRequest,
-    ) -> PortResult<bitfun_core_types::SessionUsageReport>;
-}
-
-#[async_trait::async_trait]
-pub trait AgentTurnSettlementPort: Send + Sync {
-    async fn wait_for_turn_settlement(&self, request: AgentTurnSettlementRequest)
-        -> PortResult<()>;
-}
-
-#[async_trait::async_trait]
-pub trait AgentDialogTurnPort: Send + Sync {
-    async fn submit_dialog_turn(
-        &self,
-        request: AgentDialogTurnRequest,
-    ) -> PortResult<DialogSubmitOutcome>;
-
-    async fn steer_dialog_turn(
-        &self,
-        _request: AgentDialogSteerRequest,
-    ) -> PortResult<DialogSteerOutcome> {
-        Err(PortError::new(
-            PortErrorKind::NotAvailable,
-            "dialog turn steering is not supported by this provider",
-        ))
-    }
-}
-
-#[async_trait::async_trait]
-pub trait AgentLifecycleDeliveryPort: Send + Sync {
-    async fn deliver_background_result(
-        &self,
-        request: AgentBackgroundResultRequest,
-    ) -> PortResult<()>;
-
-    async fn deliver_thread_goal(&self, request: AgentThreadGoalDeliveryRequest) -> PortResult<()>;
-}
-
-#[async_trait::async_trait]
-pub trait AgentThreadGoalManagementPort: Send + Sync {
-    async fn get_thread_goal(
-        &self,
-        request: AgentThreadGoalGetRequest,
-    ) -> PortResult<Option<ThreadGoal>>;
-
-    async fn create_thread_goal(
-        &self,
-        request: AgentThreadGoalCreateRequest,
-    ) -> PortResult<ThreadGoal>;
-
-    async fn update_thread_goal_status(
-        &self,
-        request: AgentThreadGoalUpdateStatusRequest,
-    ) -> PortResult<ThreadGoal>;
-}
-
-#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[serde(rename_all = "camelCase")]
-pub struct AgentTurnCancellationRequest {
-    pub session_id: String,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub turn_id: Option<String>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub source: Option<AgentSubmissionSource>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub requester_session_id: Option<String>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub reason: Option<String>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub wait_timeout_ms: Option<u64>,
-    /// Whether a Session-wide cancellation also cascades into descendants.
-    #[serde(default = "default_cancel_descendants")]
-    pub cancel_descendants: bool,
-}
-
-fn default_cancel_descendants() -> bool {
-    true
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[serde(rename_all = "camelCase")]
-pub struct AgentTurnCancellationResult {
-    pub session_id: String,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub turn_id: Option<String>,
-    #[serde(default)]
-    pub requested: bool,
-}
-
-#[async_trait::async_trait]
-pub trait AgentTurnCancellationPort: Send + Sync {
-    async fn cancel_turn(
-        &self,
-        request: AgentTurnCancellationRequest,
-    ) -> PortResult<AgentTurnCancellationResult>;
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "snake_case")]
-pub enum RemoteControlSessionState {
-    Idle,
-    Processing,
-    Error,
-    Missing,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct RemoteControlStateRequest {
-    pub session_id: String,
-}
-
-#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct RemoteControlStateSnapshot {
-    pub session_id: String,
-    pub state: RemoteControlSessionState,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub active_turn_id: Option<String>,
-    #[serde(default)]
-    pub queue_depth: usize,
-    #[serde(default, skip_serializing_if = "serde_json::Map::is_empty")]
-    pub metadata: serde_json::Map<String, serde_json::Value>,
-}
-
-#[async_trait::async_trait]
-pub trait RemoteControlStatePort: Send + Sync {
-    async fn read_remote_control_state(
-        &self,
-        request: RemoteControlStateRequest,
-    ) -> PortResult<Option<RemoteControlStateSnapshot>>;
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "snake_case")]
-pub enum RuntimeEventType {
-    TurnStarted,
-    TurnCompleted,
-    TurnFailed,
-    TurnCancelled,
-    SessionStateChanged,
-}
-
-#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct RuntimeEventEnvelope {
-    pub session_id: String,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub turn_id: Option<String>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub source: Option<AgentSubmissionSource>,
-    pub event_type: RuntimeEventType,
-    #[serde(default)]
-    pub payload: serde_json::Value,
-}
-
-#[async_trait::async_trait]
-pub trait RuntimeEventSink: Send + Sync {
-    async fn publish_runtime_event(&self, event: RuntimeEventEnvelope) -> PortResult<()>;
-}
-
-#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct DynamicToolDescriptor {
-    pub name: String,
-    pub description: String,
-    pub input_schema: serde_json::Value,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub provider_id: Option<String>,
-}
-
-#[async_trait::async_trait]
-pub trait DynamicToolProvider: Send + Sync {
-    async fn list_dynamic_tools(&self) -> PortResult<Vec<DynamicToolDescriptor>>;
-}
-
-pub trait ToolDecorator<Tool>: Send + Sync {
-    fn decorate(&self, tool: Tool) -> Tool;
-}
-
-#[async_trait::async_trait]
-pub trait ConfigReadPort: Send + Sync {
-    async fn get_config_value(&self, key: &str) -> PortResult<Option<serde_json::Value>>;
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct SessionTranscriptRequest {
-    pub session_id: String,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub turn_id: Option<String>,
-}
-
-#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct SessionTranscript {
-    pub session_id: String,
-    #[serde(default)]
-    pub messages: Vec<TranscriptMessage>,
-}
-
-/// Read-only transcript content shared by runtime consumers.
-///
-/// This projection preserves portable history facts without exposing the Core persistence
-/// message type. Multimodal entries report attachment counts rather than transporting image
-/// payloads; callers that need attachment content require a separate, authorized capability.
-#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
-pub enum TranscriptContent {
-    Text(String),
-    Multimodal {
-        text: String,
-        image_count: usize,
-    },
-    ToolResult {
-        tool_id: String,
-        tool_name: String,
-        #[serde(default, skip_serializing_if = "Option::is_none")]
-        effective_tool_name: Option<String>,
-        result: serde_json::Value,
-        is_error: bool,
-    },
-    Mixed {
-        #[serde(default, skip_serializing_if = "Option::is_none")]
-        reasoning_content: Option<String>,
-        text: String,
-        #[serde(default)]
-        tool_calls: Vec<TranscriptToolCall>,
-    },
-}
-
-#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
-pub struct TranscriptToolCall {
-    pub tool_id: String,
-    pub tool_name: String,
-    #[serde(default)]
-    pub arguments: serde_json::Value,
-}
-
-#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct TranscriptMessage {
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub id: Option<String>,
-    pub role: String,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub turn_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub timestamp_ms: Option<u64>,
-    pub content: TranscriptContent,
+    pub provider_id: Option<String>,
 }
 
 #[async_trait::async_trait]
-pub trait SessionTranscriptReader: Send + Sync {
-    async fn read_session_transcript(
-        &self,
-        request: SessionTranscriptRequest,
-    ) -> PortResult<SessionTranscript>;
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "snake_case")]
-pub struct DelegationPolicy {
-    pub allow_subagent_spawn: bool,
-    pub nesting_depth: u8,
-}
-
-impl Default for DelegationPolicy {
-    fn default() -> Self {
-        Self::top_level()
-    }
-}
-
-impl DelegationPolicy {
-    pub fn top_level() -> Self {
-        Self {
-            allow_subagent_spawn: true,
-            nesting_depth: 0,
-        }
-    }
-
-    pub fn spawn_child(self) -> Self {
-        Self {
-            allow_subagent_spawn: false,
-            nesting_depth: self.nesting_depth.saturating_add(1),
-        }
-    }
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
-#[serde(rename_all = "snake_case")]
-pub enum SubagentContextMode {
-    #[default]
-    Fresh,
-    Fork,
-}
-
-impl SubagentContextMode {
-    pub fn as_str(self) -> &'static str {
-        match self {
-            Self::Fresh => "fresh",
-            Self::Fork => "fork",
-        }
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use std::sync::Mutex;
-
-    #[test]
-    fn session_revert_contract_preserves_authoritative_transcript_and_composer_intent() {
-        let result = AgentSessionRevertResult {
-            session_id: "session-1".to_string(),
-            transcript: SessionTranscript {
-                session_id: "session-1".to_string(),
-                messages: Vec::new(),
-            },
-            composer: AgentSessionComposerUpdate::Replace {
-                text: "restore this prompt".to_string(),
-            },
-            retired_turn_ids: vec!["turn-2".to_string(), "turn-queued".to_string()],
-            changed: true,
-            hidden_turn_count: 2,
-        };
-
-        let value = serde_json::to_value(&result).expect("session revert result should serialize");
-        assert_eq!(value["sessionId"], "session-1");
-        assert_eq!(value["composer"]["kind"], "replace");
-        assert_eq!(value["composer"]["text"], "restore this prompt");
-        assert_eq!(value["hiddenTurnCount"], 2);
-        assert_eq!(value["retiredTurnIds"][1], "turn-queued");
-        assert_eq!(
-            serde_json::from_value::<AgentSessionRevertResult>(value)
-                .expect("session revert result should deserialize"),
-            result
-        );
-    }
-
-    #[test]
-    fn workspace_reference_metadata_round_trips_without_expanding_dialog_turn_dto() {
-        let references = vec![AgentWorkspaceReference {
-            path: "src/lib.rs".to_string(),
-            kind: AgentWorkspaceReferenceKind::File,
-            start_line: Some(12),
-            end_line: Some(24),
-            source: AgentWorkspaceReferenceSourceRange {
-                start: 7,
-                end: 28,
-                value: "@src/lib.rs#12-24".to_string(),
-            },
-        }];
-        let mut metadata = serde_json::Map::new();
-
-        put_agent_workspace_references(&mut metadata, &references)
-            .expect("workspace reference metadata should serialize");
-
-        assert_eq!(
-            agent_workspace_references_from_metadata(&metadata)
-                .expect("workspace reference metadata should deserialize"),
-            references
-        );
-        assert_eq!(
-            metadata[AGENT_WORKSPACE_REFERENCES_METADATA_KEY][0]["startLine"],
-            12
-        );
-    }
-
-    #[test]
-    fn workspace_reference_metadata_rejects_invalid_shapes() {
-        let metadata = serde_json::Map::from_iter([(
-            AGENT_WORKSPACE_REFERENCES_METADATA_KEY.to_string(),
-            serde_json::json!([{"path": 7}]),
-        )]);
-
-        let error = agent_workspace_references_from_metadata(&metadata)
-            .expect_err("invalid workspace reference metadata must fail closed");
-
-        assert_eq!(error.kind, PortErrorKind::InvalidRequest);
-
-        let too_many = vec![
-            serde_json::json!({
-                "path": "src/lib.rs",
-                "kind": "file",
-                "source": {"start": 0, "end": 11, "value": "@src/lib.rs"}
-            });
-            MAX_AGENT_WORKSPACE_REFERENCES_PER_TURN + 1
-        ];
-        let metadata = serde_json::Map::from_iter([(
-            AGENT_WORKSPACE_REFERENCES_METADATA_KEY.to_string(),
-            serde_json::Value::Array(too_many),
-        )]);
-        assert!(agent_workspace_references_from_metadata(&metadata).is_err());
-
-        let references = vec![
-            AgentWorkspaceReference {
-                path: "src/lib.rs".to_string(),
-                kind: AgentWorkspaceReferenceKind::File,
-                start_line: None,
-                end_line: None,
-                source: AgentWorkspaceReferenceSourceRange {
-                    start: 0,
-                    end: 11,
-                    value: "@src/lib.rs".to_string(),
-                },
-            };
-            MAX_AGENT_WORKSPACE_REFERENCES_PER_TURN + 1
-        ];
-        assert!(put_agent_workspace_references(&mut serde_json::Map::new(), &references).is_err());
-    }
-
-    #[test]
-    fn context_reload_contract_is_closed_and_target_specific() {
-        let cases = [
-            (AgentContextReloadTarget::All, "all", true, true),
-            (AgentContextReloadTarget::Skills, "skills", true, false),
-            (
-                AgentContextReloadTarget::Instructions,
-                "instructions",
-                false,
-                true,
-            ),
-        ];
-
-        for (target, serialized_target, skills, instructions) in cases {
-            assert_eq!(target.includes_skills(), skills);
-            assert_eq!(target.includes_instructions(), instructions);
-            let request = AgentContextReloadRequest {
-                session_id: "session-1".to_string(),
-                target,
-            };
-            assert_eq!(
-                serde_json::to_value(&request).expect("serialize request"),
-                serde_json::json!({
-                    "sessionId": "session-1",
-                    "target": serialized_target,
-                })
-            );
-            assert_eq!(
-                serde_json::from_value::<AgentContextReloadRequest>(serde_json::json!({
-                    "sessionId": "session-1",
-                    "target": serialized_target,
-                }))
-                .expect("deserialize request"),
-                request
-            );
-        }
-
-        assert!(
-            serde_json::from_value::<AgentContextReloadRequest>(serde_json::json!({
-                "sessionId": "session-1",
-                "target": "all",
-                "unexpected": true,
-            }))
-            .is_err()
-        );
-    }
-
-    #[derive(Default)]
-    struct ArchiveOnlySessionProvider {
-        archived_requests: Mutex<Vec<AgentSessionArchiveRequest>>,
-    }
-
-    #[async_trait::async_trait]
-    impl AgentSessionManagementPort for ArchiveOnlySessionProvider {
-        async fn list_sessions(
-            &self,
-            _request: AgentSessionListRequest,
-        ) -> PortResult<Vec<AgentSessionSummary>> {
-            Ok(Vec::new())
-        }
-
-        async fn delete_session(&self, _request: AgentSessionDeleteRequest) -> PortResult<()> {
-            Ok(())
-        }
-
-        async fn archive_session(&self, request: AgentSessionArchiveRequest) -> PortResult<()> {
-            self.archived_requests.lock().unwrap().push(request);
-            Ok(())
-        }
-
-        async fn resolve_session_workspace_binding(
-            &self,
-            _request: AgentSessionWorkspaceRequest,
-        ) -> PortResult<Option<AgentSessionWorkspaceBinding>> {
-            Ok(None)
-        }
-    }
-
-    struct LatestTurnForkOnlyProvider;
-
-    #[async_trait::async_trait]
-    impl AgentSessionForkPort for LatestTurnForkOnlyProvider {
-        async fn fork_session(
-            &self,
-            request: AgentSessionForkRequest,
-        ) -> PortResult<AgentSessionForkResult> {
-            Ok(AgentSessionForkResult {
-                session_id: format!("{}-fork", request.source_session_id),
-                session_name: "Fork".to_string(),
-                agent_type: "agentic".to_string(),
-            })
-        }
-    }
-
-    fn archive_state_request(archived: bool) -> AgentSessionArchiveStateRequest {
-        AgentSessionArchiveStateRequest {
-            workspace_path: "/workspace/project".to_string(),
-            session_id: "session_1".to_string(),
-            archived,
-            remote_connection_id: Some("conn-1".to_string()),
-            remote_ssh_host: Some("host-1".to_string()),
-        }
-    }
-
-    #[tokio::test]
-    async fn archive_state_default_preserves_archive_only_provider_compatibility() {
-        let provider = ArchiveOnlySessionProvider::default();
-
-        AgentSessionManagementPort::set_session_archived(&provider, archive_state_request(true))
-            .await
-            .expect("archive=true should delegate to the legacy provider");
-        // Scoped so the guard is provably released before the await below.
-        {
-            let requests = provider.archived_requests.lock().unwrap();
-            assert_eq!(requests.len(), 1);
-            assert_eq!(requests[0].workspace_path, "/workspace/project");
-            assert_eq!(requests[0].session_id, "session_1");
-            assert_eq!(requests[0].remote_connection_id.as_deref(), Some("conn-1"));
-            assert_eq!(requests[0].remote_ssh_host.as_deref(), Some("host-1"));
-        }
-
-        let error = AgentSessionManagementPort::set_session_archived(
-            &provider,
-            archive_state_request(false),
-        )
-        .await
-        .expect_err("legacy providers must reject unarchive by default");
-        assert_eq!(error.kind, PortErrorKind::NotAvailable);
-        assert_eq!(provider.archived_requests.lock().unwrap().len(), 1);
-    }
-
-    #[tokio::test]
-    async fn exact_turn_fork_default_preserves_latest_turn_only_provider_compatibility() {
-        let provider = LatestTurnForkOnlyProvider;
-        let error = AgentSessionForkPort::fork_session_at_turn(
-            &provider,
-            AgentSessionForkAtTurnRequest {
-                workspace_path: "/workspace/project".to_string(),
-                source_session_id: "session_1".to_string(),
-                source_turn_id: "turn_1".to_string(),
-                remote_connection_id: None,
-                remote_ssh_host: None,
-            },
-        )
-        .await
-        .expect_err("legacy providers must reject exact-turn fork by default");
-
-        assert_eq!(error.kind, PortErrorKind::NotAvailable);
-    }
-
-    #[tokio::test]
-    async fn before_turn_fork_default_preserves_existing_provider_compatibility() {
-        let provider = LatestTurnForkOnlyProvider;
-        let error = AgentSessionForkPort::fork_session_before_turn(
-            &provider,
-            AgentSessionForkBeforeTurnRequest {
-                workspace_path: "/workspace/project".to_string(),
-                source_session_id: "session_1".to_string(),
-                source_turn_id: "turn_1".to_string(),
-                remote_connection_id: None,
-                remote_ssh_host: None,
-            },
-        )
-        .await
-        .expect_err("existing providers must reject before-turn fork by default");
-
-        assert_eq!(error.kind, PortErrorKind::NotAvailable);
-    }
-
-    #[test]
-    fn agent_session_create_request_keeps_rust_literal_compatible() {
-        let request = AgentSessionCreateRequest {
-            session_name: "Generated session".to_string(),
-            agent_type: "agentic".to_string(),
-            workspace_path: Some("/workspace/project".to_string()),
-            project_workspace_path: None,
-            execution_target: None,
-            workspace_id: Some("workspace-1".to_string()),
-            remote_connection_id: None,
-            remote_ssh_host: None,
-            model_id: Some("provider/model".to_string()),
-            metadata: serde_json::Map::new(),
-        };
-
-        let json = serde_json::to_value(request).expect("serialize create request");
-
-        assert!(json.get("sessionId").is_none());
-        assert_eq!(json["workspaceId"], "workspace-1");
-        assert_eq!(json["modelId"], "provider/model");
-    }
-
-    #[test]
-    fn agent_session_create_request_keeps_legacy_payload_compatible() {
-        let request: AgentSessionCreateRequest = serde_json::from_value(serde_json::json!({
-            "sessionName": "Generated session",
-            "agentType": "agentic",
-            "workspacePath": "/workspace/project"
-        }))
-        .expect("deserialize legacy create request");
-
-        let json = serde_json::to_value(request).expect("serialize create request");
-        assert!(json.get("sessionId").is_none());
-        assert!(json.get("workspaceId").is_none());
-        assert!(json.get("modelId").is_none());
-    }
-
-    #[test]
-    fn agent_session_create_result_keeps_legacy_payload_shape() {
-        let legacy = serde_json::json!({
-            "sessionId": "session_1",
-            "sessionName": "Main",
-            "agentType": "agentic"
-        });
-
-        let result: AgentSessionCreateResult =
-            serde_json::from_value(legacy.clone()).expect("deserialize legacy create result");
-
-        assert_eq!(result.workspace_path, None);
-        assert_eq!(result.model_id, None);
-        assert_eq!(result.workspace_id, None);
-        assert_eq!(result.project_workspace_path, None);
-        assert_eq!(result.execution_target, None);
-        assert_eq!(
-            serde_json::to_value(result).expect("serialize legacy create result"),
-            legacy
-        );
-    }
-
-    #[test]
-    fn agent_session_create_result_carries_normalized_workspace_facts() {
-        let result: AgentSessionCreateResult = serde_json::from_value(serde_json::json!({
-            "sessionId": "session_1",
-            "sessionName": "Main",
-            "agentType": "agentic",
-            "modelId": "provider/model",
-            "workspacePath": "/worktrees/session_1",
-            "workspaceId": "workspace_1",
-            "projectWorkspacePath": "/workspace/project",
-            "executionTarget": {
-                "kind": "managedWorktree",
-                "worktreeId": "worktree_1",
-                "rootPath": "/worktrees/session_1",
-                "baseRef": "main",
-                "baseCommit": "0123456789abcdef",
-                "branch": "bitfun/session_1",
-                "lifecycle": "managed"
-            }
-        }))
-        .expect("deserialize complete create result");
-
-        assert_eq!(
-            result.workspace_path.as_deref(),
-            Some("/worktrees/session_1")
-        );
-        assert_eq!(result.model_id.as_deref(), Some("provider/model"));
-        assert_eq!(result.workspace_id.as_deref(), Some("workspace_1"));
-        assert_eq!(
-            result.project_workspace_path.as_deref(),
-            Some("/workspace/project")
-        );
-        let target = result.execution_target.expect("resolved execution target");
-        assert_eq!(target.kind, SessionExecutionTargetKind::ManagedWorktree);
-        assert_eq!(target.worktree_id.as_deref(), Some("worktree_1"));
-        assert_eq!(target.root_path, "/worktrees/session_1");
-    }
-
-    #[test]
-    fn port_error_display_keeps_kind_and_message() {
-        let error = PortError::new(PortErrorKind::NotAvailable, "coordinator missing");
-
-        assert_eq!(
-            error.to_string(),
-            "NotAvailable: coordinator missing".to_string()
-        );
-    }
-
-    #[test]
-    fn agent_submission_request_serializes_with_stable_camel_case() {
-        let request = AgentSubmissionRequest {
-            session_id: "session_1".to_string(),
-            message: "hello".to_string(),
-            turn_id: None,
-            source: None,
-            attachments: Vec::new(),
-            metadata: serde_json::Map::new(),
-        };
-
-        let json = serde_json::to_value(request).expect("serialize request");
-
-        assert_eq!(json["sessionId"], "session_1");
-        assert_eq!(json["message"], "hello");
-        assert!(json.get("source").is_none());
-        assert!(json.get("attachments").is_none());
-    }
-
-    #[test]
-    fn agent_submission_request_serializes_source_without_changing_field_case() {
-        let request = AgentSubmissionRequest {
-            session_id: "session_1".to_string(),
-            message: "hello".to_string(),
-            turn_id: None,
-            source: Some(AgentSubmissionSource::RemoteRelay),
-            attachments: Vec::new(),
-            metadata: serde_json::Map::new(),
-        };
-
-        let json = serde_json::to_value(request).expect("serialize request");
-
-        assert_eq!(json["source"], "remote_relay");
-        assert!(json.get("turnId").is_none());
-    }
-
-    #[test]
-    fn dialog_trigger_source_reuses_agent_submission_source_contract() {
-        let json = serde_json::to_value(DialogTriggerSource::Cli)
-            .expect("serialize dialog trigger source");
-
-        assert_eq!(json, serde_json::json!("cli"));
-
-        let sdk_host = serde_json::to_value(DialogTriggerSource::SdkHost)
-            .expect("serialize SDK Host trigger source");
-        assert_eq!(sdk_host, serde_json::json!("sdk_host"));
-    }
-
-    #[test]
-    fn delegated_dialog_turn_target_is_typed_and_provider_neutral() {
-        let target = AgentDialogTurnExecution::FreshExternalSubagent {
-            ecosystem_id: "opencode".to_string(),
-            logical_id: "reviewer".to_string(),
-        };
-
-        assert_eq!(
-            serde_json::to_value(target).expect("serialize delegated execution"),
-            serde_json::json!({
-                "kind": "fresh_external_subagent",
-                "ecosystemId": "opencode",
-                "logicalId": "reviewer",
-            })
-        );
-        assert_eq!(
-            AgentDialogTurnExecution::default(),
-            AgentDialogTurnExecution::Standard
-        );
-        assert!(
-            serde_json::from_value::<AgentDialogTurnExecution>(serde_json::json!({
-                "kind": "fresh_external_subagent",
-                "ecosystemId": "opencode",
-                "logicalId": "reviewer",
-                "model": "provider/model"
-            }))
-            .is_err()
-        );
-    }
-
-    #[test]
-    fn dialog_submission_policy_preserves_current_surface_queue_defaults() {
-        let remote = DialogSubmissionPolicy::for_source(DialogTriggerSource::RemoteRelay);
-        assert_eq!(remote.queue_priority, DialogQueuePriority::Normal);
-
-        let bot = DialogSubmissionPolicy::for_source(DialogTriggerSource::Bot);
-        assert_eq!(bot.queue_priority, DialogQueuePriority::Normal);
-
-        let agent_session = DialogSubmissionPolicy::for_source(DialogTriggerSource::AgentSession);
-        assert_eq!(agent_session.queue_priority, DialogQueuePriority::Low);
-
-        let cli = DialogSubmissionPolicy::for_source(DialogTriggerSource::Cli);
-        assert_eq!(cli.queue_priority, DialogQueuePriority::Normal);
-
-        let sdk_host = DialogSubmissionPolicy::for_source(DialogTriggerSource::SdkHost);
-        assert_eq!(sdk_host.queue_priority, DialogQueuePriority::Normal);
-    }
-
-    #[test]
-    fn dialog_submit_outcome_preserves_started_and_queued_fields() {
-        let started = DialogSubmitOutcome::Started {
-            session_id: "session_1".to_string(),
-            turn_id: "turn_1".to_string(),
-        };
-        let queued = DialogSubmitOutcome::Queued {
-            session_id: "session_1".to_string(),
-            turn_id: "turn_2".to_string(),
-        };
-
-        assert_eq!(
-            started,
-            DialogSubmitOutcome::Started {
-                session_id: "session_1".to_string(),
-                turn_id: "turn_1".to_string(),
-            }
-        );
-        assert_ne!(started, queued);
-    }
-
-    #[test]
-    fn dialog_submit_queue_action_preserves_current_scheduler_routing_policy() {
-        let remote = DialogSubmissionPolicy::for_source(DialogTriggerSource::RemoteRelay);
-
-        let agent_session = DialogSubmissionPolicy::for_source(DialogTriggerSource::AgentSession);
-
-        assert_eq!(
-            resolve_dialog_submit_queue_action(DialogSubmitQueueFacts {
-                session_state: DialogSessionStateFact::Missing,
-                queue_has_items: true,
-                policy: remote,
-            }),
-            DialogSubmitQueueAction::StartImmediately
-        );
-        assert_eq!(
-            resolve_dialog_submit_queue_action(DialogSubmitQueueFacts {
-                session_state: DialogSessionStateFact::Error,
-                queue_has_items: true,
-                policy: remote,
-            }),
-            DialogSubmitQueueAction::ClearQueueAndStartImmediately
-        );
-        assert_eq!(
-            resolve_dialog_submit_queue_action(DialogSubmitQueueFacts {
-                session_state: DialogSessionStateFact::Idle,
-                queue_has_items: false,
-                policy: remote,
-            }),
-            DialogSubmitQueueAction::StartImmediately
-        );
-        assert_eq!(
-            resolve_dialog_submit_queue_action(DialogSubmitQueueFacts {
-                session_state: DialogSessionStateFact::Idle,
-                queue_has_items: true,
-                policy: remote,
-            }),
-            DialogSubmitQueueAction::EnqueueThenStartNext
-        );
-        assert_eq!(
-            resolve_dialog_submit_queue_action(DialogSubmitQueueFacts {
-                session_state: DialogSessionStateFact::Processing,
-                queue_has_items: false,
-                policy: remote,
-            }),
-            DialogSubmitQueueAction::EnqueueForActiveTurn
-        );
-        assert_eq!(
-            resolve_dialog_submit_queue_action(DialogSubmitQueueFacts {
-                session_state: DialogSessionStateFact::Processing,
-                queue_has_items: false,
-                policy: agent_session,
-            }),
-            DialogSubmitQueueAction::EnqueueForActiveTurn
-        );
-    }
-
-    #[test]
-    fn agent_session_reply_decisions_preserve_cancel_suppression_boundary() {
-        let policy = DialogSubmissionPolicy::for_source(DialogTriggerSource::AgentSession);
-        assert!(should_suppress_agent_session_cancelled_reply(
-            &policy,
-            Some("requester"),
-            "requester",
-        ));
-        assert!(!should_suppress_agent_session_cancelled_reply(
-            &policy,
-            Some("requester"),
-            "other",
-        ));
-
-        let remote = DialogSubmissionPolicy::for_source(DialogTriggerSource::RemoteRelay);
-        assert!(!should_suppress_agent_session_cancelled_reply(
-            &remote,
-            Some("requester"),
-            "requester",
-        ));
-
-        assert!(should_skip_agent_session_reply(
-            DialogTurnOutcomeKind::Cancelled,
-            true,
-        ));
-        assert!(!should_skip_agent_session_reply(
-            DialogTurnOutcomeKind::Cancelled,
-            false,
-        ));
-        assert!(!should_skip_agent_session_reply(
-            DialogTurnOutcomeKind::Completed,
-            true,
-        ));
-        assert!(!should_skip_agent_session_reply(
-            DialogTurnOutcomeKind::Failed,
-            true,
-        ));
-    }
-
-    #[test]
-    fn agent_session_reply_route_keeps_requester_fields() {
-        let route = AgentSessionReplyRoute {
-            source_session_id: "requester_session".to_string(),
-            source_workspace_path: "/workspace/requester".to_string(),
-            source_remote_connection_id: Some("conn-1".to_string()),
-            source_remote_ssh_host: Some("host-1".to_string()),
-        };
-
-        assert_eq!(route.source_session_id, "requester_session");
-        assert_eq!(route.source_workspace_path, "/workspace/requester");
-        assert_eq!(route.source_remote_connection_id.as_deref(), Some("conn-1"));
-        assert_eq!(route.source_remote_ssh_host.as_deref(), Some("host-1"));
-    }
-
-    #[test]
-    fn remote_workspace_contracts_preserve_workspace_and_session_facts() {
-        let workspace = RemoteWorkspaceFacts {
-            path: "/workspace/project".to_string(),
-            name: "project".to_string(),
-            git_branch: Some("main".to_string()),
-            kind: RemoteWorkspaceKind::Remote,
-            assistant_id: Some("assistant_1".to_string()),
-            remote_connection_id: Some("conn-1".to_string()),
-            remote_ssh_host: Some("host-1".to_string()),
-        };
-        let session = RemoteSessionMetadata {
-            session_id: "session_1".to_string(),
-            name: "Research".to_string(),
-            agent_type: "CodeAgent".to_string(),
-            created_at_ms: 10,
-            last_active_at_ms: 20,
-            turn_count: 3,
-        };
-
-        assert_eq!(workspace.kind.as_wire_str(), "remote");
-        assert_eq!(workspace.assistant_id.as_deref(), Some("assistant_1"));
-        assert_eq!(workspace.remote_connection_id.as_deref(), Some("conn-1"));
-        assert_eq!(workspace.remote_ssh_host.as_deref(), Some("host-1"));
-        assert_eq!(session.turn_count, 3);
-    }
-
-    #[test]
-    fn remote_projection_contract_preserves_file_chunk_identity() {
-        let chunk = RemoteWorkspaceFileChunk {
-            name: "report.md".to_string(),
-            bytes: b"chunk".to_vec(),
-            offset: 6,
-            chunk_size: 5,
-            total_size: 11,
-            mime_type: "text/markdown",
-        };
-
-        assert_eq!(chunk.name, "report.md");
-        assert_eq!(chunk.bytes, b"chunk");
-        assert_eq!(chunk.offset + chunk.chunk_size, chunk.total_size);
-    }
+pub trait DynamicToolProvider: Send + Sync {
+    async fn list_dynamic_tools(&self) -> PortResult<Vec<DynamicToolDescriptor>>;
+}
 
-    #[test]
-    fn dialog_steer_outcome_preserves_buffered_fields() {
-        let outcome = DialogSteerOutcome::Buffered {
-            session_id: "session_1".to_string(),
-            turn_id: "turn_1".to_string(),
-            steering_id: "steer_1".to_string(),
-        };
+pub trait ToolDecorator<Tool>: Send + Sync {
+    fn decorate(&self, tool: Tool) -> Tool;
+}
 
-        assert_eq!(
-            outcome,
-            DialogSteerOutcome::Buffered {
-                session_id: "session_1".to_string(),
-                turn_id: "turn_1".to_string(),
-                steering_id: "steer_1".to_string(),
-            }
-        );
-    }
+#[async_trait::async_trait]
+pub trait ConfigReadPort: Send + Sync {
+    async fn get_config_value(&self, key: &str) -> PortResult<Option<serde_json::Value>>;
+}
 
-    #[test]
-    fn round_injection_contract_keeps_kind_and_target_identity() {
-        assert_eq!(
-            RoundInjectionKind::UserSteering,
-            RoundInjectionKind::UserSteering
-        );
-        assert_ne!(
-            RoundInjectionKind::UserSteering,
-            RoundInjectionKind::BackgroundResult
-        );
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub struct DelegationPolicy {
+    pub allow_subagent_spawn: bool,
+    pub nesting_depth: u8,
+}
 
-        let target = RoundInjectionTarget::ExactTurn("turn_1".to_string());
-        assert_eq!(
-            target,
-            RoundInjectionTarget::ExactTurn("turn_1".to_string())
-        );
-        assert_ne!(target, RoundInjectionTarget::CurrentRunningTurn);
-        assert_eq!(
-            RoundInjectionKind::UserSteering
-                .default_execution_policy()
-                .tool_preemption,
-            RoundInjectionToolPreemption::InterruptAfterCurrentAtomicUnit
-        );
-        assert_eq!(
-            RoundInjectionKind::BackgroundResult
-                .default_execution_policy()
-                .tool_preemption,
-            RoundInjectionToolPreemption::None
-        );
+impl Default for DelegationPolicy {
+    fn default() -> Self {
+        Self::top_level()
     }
+}
 
-    #[test]
-    fn round_injection_source_contract_drains_portable_injections() {
-        struct StaticInjectionSource {
-            injection: RoundInjection,
+impl DelegationPolicy {
+    pub fn top_level() -> Self {
+        Self {
+            allow_subagent_spawn: true,
+            nesting_depth: 0,
         }
+    }
 
-        impl DialogRoundInjectionSource for StaticInjectionSource {
-            fn has_pending(&self, session_id: &str, turn_id: &str) -> bool {
-                session_id == "session_1" && turn_id == "turn_1"
-            }
-
-            fn pending_tool_preemption(
-                &self,
-                session_id: &str,
-                turn_id: &str,
-            ) -> RoundInjectionToolPreemption {
-                if self.has_pending(session_id, turn_id) {
-                    self.injection.execution_policy.tool_preemption
-                } else {
-                    RoundInjectionToolPreemption::None
-                }
-            }
-
-            fn take_pending(&self, session_id: &str, turn_id: &str) -> Vec<RoundInjection> {
-                if self.has_pending(session_id, turn_id) {
-                    vec![self.injection.clone()]
-                } else {
-                    Vec::new()
-                }
-            }
+    pub fn spawn_child(self) -> Self {
+        Self {
+            allow_subagent_spawn: false,
+            nesting_depth: self.nesting_depth.saturating_add(1),
         }
-
-        let source = StaticInjectionSource {
-            injection: RoundInjection {
-                id: "injection_1".to_string(),
-                kind: RoundInjectionKind::BackgroundResult,
-                execution_policy: RoundInjectionKind::BackgroundResult.default_execution_policy(),
-                target: RoundInjectionTarget::CurrentRunningTurn,
-                content: "result".to_string(),
-                display_content: "result".to_string(),
-                created_at: std::time::SystemTime::UNIX_EPOCH,
-            },
-        };
-
-        assert!(source.has_pending("session_1", "turn_1"));
-        assert!(!source.has_pending("session_2", "turn_1"));
-        assert_eq!(
-            source.pending_tool_preemption("session_1", "turn_1"),
-            RoundInjectionToolPreemption::None
-        );
-        let drained = source.take_pending("session_1", "turn_1");
-        assert_eq!(drained.len(), 1);
-        assert_eq!(drained[0].id, "injection_1");
-        assert_eq!(drained[0].kind, RoundInjectionKind::BackgroundResult);
     }
+}
 
-    #[test]
-    fn thread_goal_active_status_includes_budget_limited() {
-        let active = ThreadGoal {
-            goal_id: "goal_1".to_string(),
-            session_id: "session_1".to_string(),
-            objective: "Ship feature".to_string(),
-            status: ThreadGoalStatus::Active,
-            token_budget: Some(10_000),
-            tokens_used: 100,
-            time_used_seconds: 5,
-            created_at: 1,
-            updated_at: 2,
-            auto_continuation_count: 0,
-        };
-        assert!(active.is_active());
-        assert_eq!(active.remaining_tokens(), Some(9_900));
-
-        let budget_limited = ThreadGoal {
-            status: ThreadGoalStatus::BudgetLimited,
-            ..active.clone()
-        };
-        assert!(budget_limited.is_active());
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum SubagentContextMode {
+    #[default]
+    Fresh,
+    Fork,
+}
 
-        let paused = ThreadGoal {
-            status: ThreadGoalStatus::Paused,
-            ..active
-        };
-        assert!(!paused.is_active());
+impl SubagentContextMode {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Fresh => "fresh",
+            Self::Fork => "fork",
+        }
     }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
 
     #[test]
-    fn thread_goal_tool_response_serializes_optional_fields() {
-        let response = ThreadGoalToolResponse {
-            goal: None,
-            remaining_tokens: Some(42),
-            completion_budget_report: None,
-        };
-        let json = serde_json::to_value(response).expect("serialize thread goal tool response");
-        assert!(json.get("goal").is_none());
-        assert_eq!(json["remainingTokens"], 42);
-        assert!(json.get("completionBudgetReport").is_none());
+    fn port_error_display_keeps_kind_and_message() {
+        let error = PortError::new(PortErrorKind::NotAvailable, "coordinator missing");
+
+        assert_eq!(
+            error.to_string(),
+            "NotAvailable: coordinator missing".to_string()
+        );
     }
 
     #[test]
-    fn compression_contract_renders_model_visible_fields() {
-        let contract = CompressionContract {
-            touched_files: vec!["src/lib.rs".to_string()],
-            verification_commands: vec![CompressionContractItem {
-                target: "cargo test -p bitfun-runtime-ports".to_string(),
-                status: "passed".to_string(),
-                summary: "runtime ports contract tests passed".to_string(),
-                error_kind: None,
-            }],
-            blocking_failures: vec![CompressionContractItem {
-                target: "cargo check".to_string(),
-                status: "failed".to_string(),
-                summary: "compile error before migration".to_string(),
-                error_kind: Some("compile".to_string()),
-            }],
-            subagent_statuses: Vec::new(),
-        };
+    fn dialog_trigger_source_reuses_agent_submission_source_contract() {
+        let json = serde_json::to_value(DialogTriggerSource::Cli)
+            .expect("serialize dialog trigger source");
 
-        let rendered = contract.render_for_model();
+        assert_eq!(json, serde_json::json!("cli"));
 
-        assert!(rendered.contains("The following facts were retained during compression."));
-        assert!(rendered.contains("Touched files:"));
-        assert!(rendered.contains("- src/lib.rs"));
-        assert!(rendered.contains(
-            "- cargo test -p bitfun-runtime-ports [passed]: runtime ports contract tests passed"
-        ));
-        assert!(
-            rendered.contains("- cargo check [failed]: compile error before migration (compile)")
-        );
+        let sdk_host = serde_json::to_value(DialogTriggerSource::SdkHost)
+            .expect("serialize SDK Host trigger source");
+        assert_eq!(sdk_host, serde_json::json!("sdk_host"));
     }
 
     #[test]
@@ -3822,608 +331,6 @@ mod tests {
         assert!(json.get("related_path").is_none());
     }
 
-    #[test]
-    fn agent_submission_request_serializes_explicit_turn_id_contract() {
-        let mut metadata = serde_json::Map::new();
-        metadata.insert(
-            "turnId".to_string(),
-            serde_json::Value::String("legacy_metadata_turn".to_string()),
-        );
-        let request = AgentSubmissionRequest {
-            session_id: "session_1".to_string(),
-            message: "hello".to_string(),
-            turn_id: Some("explicit_turn".to_string()),
-            source: Some(AgentSubmissionSource::RemoteRelay),
-            attachments: Vec::new(),
-            metadata,
-        };
-
-        let json = serde_json::to_value(request).expect("serialize request");
-
-        assert_eq!(json["turnId"], "explicit_turn");
-        assert_eq!(json["metadata"]["turnId"], "legacy_metadata_turn");
-    }
-
-    #[test]
-    fn remote_image_attachment_serializes_portable_metadata_contract() {
-        let attachment =
-            AgentInputAttachment::remote_image("image-1", "clip.png", "data:image/png;base64,abc");
-
-        let json = serde_json::to_value(attachment).expect("serialize attachment");
-
-        assert_eq!(json["kind"], "remote_image");
-        assert_eq!(json["id"], "image-1");
-        assert_eq!(json["metadata"]["name"], "clip.png");
-        assert_eq!(json["metadata"]["dataUrl"], "data:image/png;base64,abc");
-    }
-
-    #[test]
-    fn agent_dialog_turn_request_serializes_lifecycle_contract() {
-        let request = AgentDialogTurnRequest {
-            session_id: "session_1".to_string(),
-            message: "hello".to_string(),
-            original_message: Some("raw hello".to_string()),
-            turn_id: Some("turn_1".to_string()),
-            execution: Default::default(),
-            agent_type: "agentic".to_string(),
-            workspace_path: Some("/workspace/project".to_string()),
-            remote_connection_id: Some("conn-1".to_string()),
-            remote_ssh_host: Some("host-1".to_string()),
-            policy: DialogSubmissionPolicy::new(
-                AgentSubmissionSource::RemoteRelay,
-                DialogQueuePriority::High,
-            ),
-            reply_route: Some(AgentSessionReplyRoute {
-                source_session_id: "source_session".to_string(),
-                source_workspace_path: "/workspace/source".to_string(),
-                source_remote_connection_id: Some("conn-1".to_string()),
-                source_remote_ssh_host: Some("host-1".to_string()),
-            }),
-            prepended_reminders: vec![AgentDialogPrependedReminder {
-                kind: "session_message_request".to_string(),
-                text: "sent by another agent".to_string(),
-            }],
-            attachments: vec![AgentInputAttachment::remote_image(
-                "image-1",
-                "clip.png",
-                "data:image/png;base64,abc",
-            )],
-            metadata: serde_json::Map::new(),
-        };
-
-        let json = serde_json::to_value(request).expect("serialize dialog turn request");
-
-        assert_eq!(json["sessionId"], "session_1");
-        assert_eq!(json["message"], "hello");
-        assert_eq!(json["originalMessage"], "raw hello");
-        assert_eq!(json["turnId"], "turn_1");
-        assert_eq!(json["agentType"], "agentic");
-        assert_eq!(json["workspacePath"], "/workspace/project");
-        assert_eq!(json["remoteConnectionId"], "conn-1");
-        assert_eq!(json["remoteSshHost"], "host-1");
-        assert_eq!(json["policy"]["triggerSource"], "remote_relay");
-        assert_eq!(json["policy"]["queuePriority"], "high");
-        assert!(json["policy"].get("skipToolConfirmation").is_none());
-        assert_eq!(json["replyRoute"]["sourceSessionId"], "source_session");
-        assert_eq!(json["replyRoute"]["sourceRemoteConnectionId"], "conn-1");
-        assert_eq!(json["replyRoute"]["sourceRemoteSshHost"], "host-1");
-        assert_eq!(
-            json["prependedReminders"][0]["kind"],
-            "session_message_request"
-        );
-        assert_eq!(json["attachments"][0]["kind"], "remote_image");
-    }
-
-    #[test]
-    fn agent_dialog_steer_contract_round_trips_exact_turn_identity() {
-        let request = AgentDialogSteerRequest {
-            session_id: "session_1".to_string(),
-            turn_id: "turn_1".to_string(),
-            content: "Please also check the tests".to_string(),
-            display_content: Some("Also check tests".to_string()),
-        };
-        let outcome = DialogSteerOutcome::Buffered {
-            session_id: "session_1".to_string(),
-            turn_id: "turn_1".to_string(),
-            steering_id: "steer_1".to_string(),
-        };
-
-        let request_json = serde_json::to_value(&request).expect("serialize steer request");
-        let outcome_json = serde_json::to_value(&outcome).expect("serialize steer outcome");
-
-        assert_eq!(request_json["sessionId"], "session_1");
-        assert_eq!(request_json["turnId"], "turn_1");
-        assert_eq!(request_json["content"], "Please also check the tests");
-        assert_eq!(request_json["displayContent"], "Also check tests");
-        assert_eq!(outcome_json["kind"], "buffered");
-        assert_eq!(outcome_json["sessionId"], "session_1");
-        assert_eq!(outcome_json["turnId"], "turn_1");
-        assert_eq!(outcome_json["steeringId"], "steer_1");
-
-        assert_eq!(
-            serde_json::from_value::<AgentDialogSteerRequest>(request_json)
-                .expect("deserialize steer request"),
-            request
-        );
-        assert_eq!(
-            serde_json::from_value::<DialogSteerOutcome>(outcome_json)
-                .expect("deserialize steer outcome"),
-            outcome
-        );
-    }
-
-    #[test]
-    fn agent_background_result_request_serializes_lifecycle_contract() {
-        let mut metadata = serde_json::Map::new();
-        metadata.insert(
-            "kind".to_string(),
-            serde_json::Value::String("background_result".to_string()),
-        );
-        let request = AgentBackgroundResultRequest {
-            session_id: "session_1".to_string(),
-            agent_type: "agentic".to_string(),
-            workspace_path: Some("/workspace/project".to_string()),
-            remote_connection_id: Some("conn-1".to_string()),
-            remote_ssh_host: Some("host-1".to_string()),
-            content: "full result".to_string(),
-            display_content: Some("short result".to_string()),
-            metadata,
-        };
-
-        let json = serde_json::to_value(request).expect("serialize background result request");
-
-        assert_eq!(json["sessionId"], "session_1");
-        assert_eq!(json["agentType"], "agentic");
-        assert_eq!(json["workspacePath"], "/workspace/project");
-        assert_eq!(json["remoteConnectionId"], "conn-1");
-        assert_eq!(json["remoteSshHost"], "host-1");
-        assert_eq!(json["content"], "full result");
-        assert_eq!(json["displayContent"], "short result");
-        assert_eq!(json["metadata"]["kind"], "background_result");
-    }
-
-    #[test]
-    fn agent_thread_goal_delivery_request_serializes_lifecycle_contract() {
-        let request = AgentThreadGoalDeliveryRequest {
-            session_id: "session_1".to_string(),
-            agent_type: "agentic".to_string(),
-            workspace_path: Some("/workspace/project".to_string()),
-            remote_connection_id: Some("conn-1".to_string()),
-            remote_ssh_host: Some("host-1".to_string()),
-            kind: AgentThreadGoalDeliveryKind::ObjectiveUpdated,
-            goal: ThreadGoal {
-                goal_id: "goal_1".to_string(),
-                session_id: "session_1".to_string(),
-                objective: "Ship the refactor".to_string(),
-                status: ThreadGoalStatus::Active,
-                token_budget: Some(1000),
-                tokens_used: 10,
-                time_used_seconds: 0,
-                created_at: 1,
-                updated_at: 2,
-                auto_continuation_count: 0,
-            },
-        };
-
-        let json = serde_json::to_value(request).expect("serialize thread goal delivery request");
-
-        assert_eq!(json["sessionId"], "session_1");
-        assert_eq!(json["agentType"], "agentic");
-        assert_eq!(json["workspacePath"], "/workspace/project");
-        assert_eq!(json["remoteConnectionId"], "conn-1");
-        assert_eq!(json["remoteSshHost"], "host-1");
-        assert_eq!(json["kind"], "objective_updated");
-        assert_eq!(json["goal"]["goalId"], "goal_1");
-    }
-
-    #[test]
-    fn agent_thread_goal_management_requests_serialize_stable_shape() {
-        let get_request = AgentThreadGoalGetRequest {
-            session_id: "session_1".to_string(),
-            workspace_path: "/workspace/project".to_string(),
-            remote_connection_id: Some("conn-1".to_string()),
-            remote_ssh_host: Some("host-1".to_string()),
-        };
-        let create_request = AgentThreadGoalCreateRequest {
-            session_id: "session_1".to_string(),
-            workspace_path: "/workspace/project".to_string(),
-            objective: "Ship the refactor".to_string(),
-            token_budget: Some(1000),
-        };
-        let update_request = AgentThreadGoalUpdateStatusRequest {
-            session_id: "session_1".to_string(),
-            workspace_path: "/workspace/project".to_string(),
-            status: ThreadGoalStatus::Complete,
-            turn_id: Some("turn_1".to_string()),
-        };
-
-        let get_json = serde_json::to_value(get_request).expect("serialize get request");
-        let create_json = serde_json::to_value(create_request).expect("serialize create request");
-        let update_json = serde_json::to_value(update_request).expect("serialize update request");
-
-        assert_eq!(get_json["sessionId"], "session_1");
-        assert_eq!(get_json["workspacePath"], "/workspace/project");
-        assert_eq!(get_json["remoteConnectionId"], "conn-1");
-        assert_eq!(get_json["remoteSshHost"], "host-1");
-        assert_eq!(create_json["objective"], "Ship the refactor");
-        assert_eq!(create_json["tokenBudget"], 1000);
-        assert_eq!(update_json["status"], "complete");
-        assert_eq!(update_json["turnId"], "turn_1");
-    }
-
-    #[test]
-    fn agent_turn_cancellation_request_serializes_current_contract() {
-        let request = AgentTurnCancellationRequest {
-            session_id: "session_1".to_string(),
-            turn_id: Some("turn_1".to_string()),
-            source: Some(AgentSubmissionSource::Bot),
-            requester_session_id: Some("requester_session".to_string()),
-            reason: Some("user_cancelled".to_string()),
-            wait_timeout_ms: Some(1500),
-            cancel_descendants: false,
-        };
-
-        let json = serde_json::to_value(request).expect("serialize cancel request");
-
-        assert_eq!(json["sessionId"], "session_1");
-        assert_eq!(json["turnId"], "turn_1");
-        assert_eq!(json["source"], "bot");
-        assert_eq!(json["requesterSessionId"], "requester_session");
-        assert_eq!(json["reason"], "user_cancelled");
-        assert_eq!(json["waitTimeoutMs"], 1500);
-        assert_eq!(json["cancelDescendants"], false);
-
-        let legacy = serde_json::from_value::<AgentTurnCancellationRequest>(serde_json::json!({
-            "sessionId": "session_1"
-        }))
-        .expect("deserialize legacy cancel request");
-        assert!(legacy.cancel_descendants);
-    }
-
-    #[test]
-    fn session_lineage_contracts_serialize_provider_neutral_facts() {
-        let request = AgentSessionLineageRequest {
-            workspace_path: "/workspace/project".to_string(),
-            anchor_session_id: "child_1".to_string(),
-            remote_connection_id: Some("conn-1".to_string()),
-            remote_ssh_host: Some("host-1".to_string()),
-        };
-        let snapshot = AgentSessionLineageSnapshot {
-            root_session_id: "root_1".to_string(),
-            sessions: vec![AgentSessionLineageEntry {
-                session_id: "child_1".to_string(),
-                session_name: "Research".to_string(),
-                agent_type: "explore".to_string(),
-                created_at_ms: 1_000,
-                status: AgentSessionLifecycleStatus::Completed,
-                active_turn_id: None,
-                parent_session_id: Some("root_1".to_string()),
-                parent_tool_call_id: Some("tool_1".to_string()),
-                subagent_type: Some("explore".to_string()),
-                workspace_path: Some("/workspace/project".to_string()),
-                remote_connection_id: Some("conn-1".to_string()),
-                remote_ssh_host: Some("host-1".to_string()),
-                unread_completion: Some("interrupted".to_string()),
-                needs_user_attention: None,
-            }],
-        };
-        let transcript_request = AgentSessionLineageTranscriptRequest {
-            workspace_path: "/workspace/project".to_string(),
-            root_session_id: "root_1".to_string(),
-            session_id: "child_1".to_string(),
-            required_settled_turn_ids: vec!["turn-terminal".to_string()],
-            remote_connection_id: None,
-            remote_ssh_host: None,
-        };
-        let cancellation_request = AgentSessionLineageCancellationRequest {
-            workspace_path: "/workspace/project".to_string(),
-            root_session_id: "root_1".to_string(),
-            session_id: "child_1".to_string(),
-            expected_active_turn_id: Some("turn-live".to_string()),
-            source: Some(AgentSubmissionSource::Cli),
-            reason: Some("user_cancelled".to_string()),
-            wait_timeout_ms: Some(5_000),
-            remote_connection_id: None,
-            remote_ssh_host: None,
-        };
-        let inspection = AgentSessionLineageInspection {
-            transcript: SessionTranscript {
-                session_id: "child_1".to_string(),
-                messages: Vec::new(),
-            },
-            active_turn_id: Some("turn-live".to_string()),
-        };
-
-        let request_json = serde_json::to_value(request).expect("serialize lineage request");
-        let snapshot_json = serde_json::to_value(snapshot).expect("serialize lineage snapshot");
-        let transcript_json =
-            serde_json::to_value(transcript_request).expect("serialize transcript request");
-        let cancellation_json =
-            serde_json::to_value(cancellation_request).expect("serialize cancellation request");
-        let inspection_json =
-            serde_json::to_value(inspection).expect("serialize lineage inspection");
-
-        assert_eq!(request_json["anchorSessionId"], "child_1");
-        assert_eq!(request_json["remoteConnectionId"], "conn-1");
-        assert_eq!(snapshot_json["rootSessionId"], "root_1");
-        assert_eq!(snapshot_json["sessions"][0]["status"], "completed");
-        assert_eq!(snapshot_json["sessions"][0]["parentSessionId"], "root_1");
-        assert_eq!(
-            snapshot_json["sessions"][0]["unreadCompletion"],
-            "interrupted"
-        );
-        assert_eq!(transcript_json["sessionId"], "child_1");
-        assert_eq!(transcript_json["rootSessionId"], "root_1");
-        assert_eq!(
-            transcript_json["requiredSettledTurnIds"],
-            serde_json::json!(["turn-terminal"])
-        );
-        let legacy_transcript =
-            serde_json::from_value::<AgentSessionLineageTranscriptRequest>(serde_json::json!({
-                "workspacePath": "/workspace/project",
-                "rootSessionId": "root_1",
-                "sessionId": "child_1"
-            }))
-            .expect("deserialize precondition-free lineage transcript request");
-        assert!(legacy_transcript.required_settled_turn_ids.is_empty());
-        assert_eq!(cancellation_json["source"], "cli");
-        assert_eq!(cancellation_json["waitTimeoutMs"], 5_000);
-        assert_eq!(cancellation_json["expectedActiveTurnId"], "turn-live");
-        let legacy_cancellation =
-            serde_json::from_value::<AgentSessionLineageCancellationRequest>(serde_json::json!({
-                "workspacePath": "/workspace/project",
-                "rootSessionId": "root_1",
-                "sessionId": "child_1"
-            }))
-            .expect("deserialize pre-exact-target lineage cancellation request");
-        assert!(legacy_cancellation.expected_active_turn_id.is_none());
-        assert_eq!(inspection_json["transcript"]["sessionId"], "child_1");
-        assert_eq!(inspection_json["activeTurnId"], "turn-live");
-    }
-
-    #[test]
-    fn agent_session_management_contracts_serialize_stable_shape() {
-        let list_request = AgentSessionListRequest {
-            workspace_path: "/workspace/project".to_string(),
-            remote_connection_id: Some("conn-1".to_string()),
-            remote_ssh_host: Some("host-1".to_string()),
-        };
-        let summary = AgentSessionSummary {
-            session_id: "session_1".to_string(),
-            session_name: "Main".to_string(),
-            agent_type: "agentic".to_string(),
-            model_id: Some("provider/model".to_string()),
-            reasoning_preset: Some("high".to_string()),
-            last_user_dialog_agent_type: Some("plan".to_string()),
-            last_submitted_agent_type: Some("agentic".to_string()),
-            turn_count: 3,
-            created_at_ms: 1000,
-            last_active_at_ms: 2000,
-        };
-        let delete_request = AgentSessionDeleteRequest {
-            workspace_path: "/workspace/project".to_string(),
-            session_id: "session_1".to_string(),
-            remote_connection_id: Some("conn-1".to_string()),
-            remote_ssh_host: Some("host-1".to_string()),
-        };
-        let rename_request = AgentSessionRenameRequest {
-            workspace_path: "/workspace/project".to_string(),
-            session_id: "session_1".to_string(),
-            session_name: "Renamed".to_string(),
-            remote_connection_id: Some("conn-1".to_string()),
-            remote_ssh_host: Some("host-1".to_string()),
-        };
-        let archive_request = AgentSessionArchiveRequest {
-            workspace_path: "/workspace/project".to_string(),
-            session_id: "session_1".to_string(),
-            remote_connection_id: Some("conn-1".to_string()),
-            remote_ssh_host: Some("host-1".to_string()),
-        };
-        let archive_state_request = AgentSessionArchiveStateRequest {
-            workspace_path: "/workspace/project".to_string(),
-            session_id: "session_1".to_string(),
-            archived: false,
-            remote_connection_id: Some("conn-1".to_string()),
-            remote_ssh_host: Some("host-1".to_string()),
-        };
-        let fork_request = AgentSessionForkRequest {
-            workspace_path: "/workspace/project".to_string(),
-            source_session_id: "session_1".to_string(),
-            remote_connection_id: None,
-            remote_ssh_host: None,
-        };
-        let fork_at_turn_request = AgentSessionForkAtTurnRequest {
-            workspace_path: "/workspace/project".to_string(),
-            source_session_id: "session_1".to_string(),
-            source_turn_id: "turn_2".to_string(),
-            remote_connection_id: Some("conn-1".to_string()),
-            remote_ssh_host: Some("host-1".to_string()),
-        };
-        let fork_before_turn_request = AgentSessionForkBeforeTurnRequest {
-            workspace_path: "/workspace/project".to_string(),
-            source_session_id: "session_1".to_string(),
-            source_turn_id: "turn_2".to_string(),
-            remote_connection_id: None,
-            remote_ssh_host: None,
-        };
-        let model_request = AgentSessionModelUpdateRequest {
-            session_id: "session_1".to_string(),
-            model_id: "provider/model".to_string(),
-        };
-        let mode_request = AgentSessionModeUpdateRequest {
-            session_id: "session_1".to_string(),
-            mode_id: "agentic".to_string(),
-        };
-        let workspace_request = AgentSessionWorkspaceRequest {
-            session_id: "session_1".to_string(),
-        };
-        let workspace_binding = AgentSessionWorkspaceBinding {
-            workspace_id: Some("workspace_1".to_string()),
-            workspace_path: "/workspace/project".to_string(),
-            project_workspace_path: None,
-            execution_target: None,
-            remote_connection_id: Some("conn-1".to_string()),
-            remote_ssh_host: Some("host-1".to_string()),
-        };
-
-        let list_json = serde_json::to_value(list_request).expect("serialize list request");
-        let summary_json = serde_json::to_value(summary).expect("serialize summary");
-        let delete_json = serde_json::to_value(delete_request).expect("serialize delete request");
-        let rename_json = serde_json::to_value(rename_request).expect("serialize rename request");
-        let archive_json =
-            serde_json::to_value(archive_request).expect("serialize archive request");
-        let archive_state_json =
-            serde_json::to_value(archive_state_request).expect("serialize archive-state request");
-        let fork_json = serde_json::to_value(fork_request).expect("serialize fork request");
-        let fork_at_turn_json =
-            serde_json::to_value(fork_at_turn_request).expect("serialize exact-turn fork request");
-        let fork_before_turn_json = serde_json::to_value(fork_before_turn_request)
-            .expect("serialize before-turn fork request");
-        let model_json = serde_json::to_value(model_request).expect("serialize model request");
-        let mode_json = serde_json::to_value(mode_request).expect("serialize mode request");
-        let workspace_json =
-            serde_json::to_value(workspace_request).expect("serialize workspace request");
-        let binding_json =
-            serde_json::to_value(workspace_binding).expect("serialize workspace binding");
-
-        assert_eq!(list_json["workspacePath"], "/workspace/project");
-        assert_eq!(list_json["remoteConnectionId"], "conn-1");
-        assert_eq!(summary_json["modelId"], "provider/model");
-        assert_eq!(summary_json["lastUserDialogAgentType"], "plan");
-        assert_eq!(summary_json["lastSubmittedAgentType"], "agentic");
-        assert_eq!(list_json["remoteSshHost"], "host-1");
-        assert_eq!(summary_json["sessionId"], "session_1");
-        assert_eq!(summary_json["turnCount"], 3);
-        assert_eq!(summary_json["createdAtMs"], 1000);
-        assert_eq!(summary_json["lastActiveAtMs"], 2000);
-        assert_eq!(delete_json["sessionId"], "session_1");
-        assert_eq!(delete_json["remoteConnectionId"], "conn-1");
-        assert_eq!(delete_json["remoteSshHost"], "host-1");
-        assert_eq!(rename_json["sessionName"], "Renamed");
-        assert_eq!(rename_json["remoteConnectionId"], "conn-1");
-        assert_eq!(archive_json["sessionId"], "session_1");
-        assert_eq!(archive_json["remoteSshHost"], "host-1");
-        assert_eq!(archive_state_json["archived"], false);
-        assert!(fork_json.get("sourceTurnId").is_none());
-        assert_eq!(fork_at_turn_json["sourceTurnId"], "turn_2");
-        assert_eq!(fork_before_turn_json["sourceTurnId"], "turn_2");
-        assert_eq!(fork_before_turn_json["sourceSessionId"], "session_1");
-        assert_eq!(model_json["sessionId"], "session_1");
-        assert_eq!(model_json["modelId"], "provider/model");
-        assert_eq!(mode_json["sessionId"], "session_1");
-        assert_eq!(mode_json["modeId"], "agentic");
-        assert_eq!(workspace_json["sessionId"], "session_1");
-        assert_eq!(binding_json["workspaceId"], "workspace_1");
-        assert_eq!(binding_json["workspacePath"], "/workspace/project");
-        assert_eq!(binding_json["remoteConnectionId"], "conn-1");
-        assert_eq!(binding_json["remoteSshHost"], "host-1");
-    }
-
-    #[test]
-    fn local_command_turn_contract_has_fixed_narrow_shape() {
-        let mut metadata = serde_json::Map::new();
-        metadata.insert("kind".to_string(), serde_json::json!("usage_report"));
-        let request = AgentLocalCommandTurnRecordRequest {
-            session_id: "session_1".to_string(),
-            content: "Usage report".to_string(),
-            turn_id: Some("turn_1".to_string()),
-            timestamp_ms: Some(1000),
-            metadata,
-        };
-
-        let json = serde_json::to_value(request).expect("serialize local command turn");
-
-        assert_eq!(json["sessionId"], "session_1");
-        assert_eq!(json["content"], "Usage report");
-        assert_eq!(json["turnId"], "turn_1");
-        assert_eq!(json["timestampMs"], 1000);
-        assert_eq!(json["metadata"]["kind"], "usage_report");
-        assert!(json.get("turnKind").is_none());
-        assert!(json.get("modelVisible").is_none());
-    }
-
-    #[test]
-    fn local_command_turn_result_serializes_authoritative_identity() {
-        let result = AgentLocalCommandTurnRecordResult {
-            turn_id: "turn_8".to_string(),
-            storage_turn_index: 7,
-        };
-
-        let json = serde_json::to_value(result).expect("serialize local command turn result");
-
-        assert_eq!(json["turnId"], "turn_8");
-        assert_eq!(json["storageTurnIndex"], 7);
-        assert_eq!(json.as_object().map(|value| value.len()), Some(2));
-    }
-
-    #[test]
-    fn remote_control_state_snapshot_serializes_active_turn_contract() {
-        let snapshot = RemoteControlStateSnapshot {
-            session_id: "session_1".to_string(),
-            state: RemoteControlSessionState::Processing,
-            active_turn_id: Some("turn_1".to_string()),
-            queue_depth: 2,
-            metadata: serde_json::Map::new(),
-        };
-
-        let json = serde_json::to_value(snapshot).expect("serialize state snapshot");
-
-        assert_eq!(json["sessionId"], "session_1");
-        assert_eq!(json["state"], "processing");
-        assert_eq!(json["activeTurnId"], "turn_1");
-        assert_eq!(json["queueDepth"], 2);
-    }
-
-    #[test]
-    fn runtime_event_envelope_serializes_observational_surface_facts() {
-        let event = RuntimeEventEnvelope {
-            session_id: "session_1".to_string(),
-            turn_id: Some("turn_1".to_string()),
-            source: Some(AgentSubmissionSource::RemoteRelay),
-            event_type: RuntimeEventType::TurnCancelled,
-            payload: serde_json::json!({ "reason": "user_cancelled" }),
-        };
-
-        let json = serde_json::to_value(event).expect("serialize event");
-
-        assert_eq!(json["sessionId"], "session_1");
-        assert_eq!(json["turnId"], "turn_1");
-        assert_eq!(json["source"], "remote_relay");
-        assert_eq!(json["eventType"], "turn_cancelled");
-        assert_eq!(json["payload"]["reason"], "user_cancelled");
-    }
-
-    #[test]
-    fn session_transcript_request_serializes_turn_id_contract() {
-        let request = SessionTranscriptRequest {
-            session_id: "session_1".to_string(),
-            turn_id: Some("turn_1".to_string()),
-        };
-
-        let json = serde_json::to_value(request).expect("serialize transcript request");
-
-        assert_eq!(json["sessionId"], "session_1");
-        assert_eq!(json["turnId"], "turn_1");
-        assert!(json.get("fromTurnId").is_none());
-    }
-
-    #[test]
-    fn transcript_contract_keeps_portable_message_identity_and_content() {
-        let message = TranscriptMessage {
-            id: Some("message_1".to_string()),
-            role: "assistant".to_string(),
-            turn_id: Some("turn_1".to_string()),
-            timestamp_ms: Some(3000),
-            content: TranscriptContent::Text("done".to_string()),
-        };
-
-        let message_json = serde_json::to_value(message).expect("serialize transcript message");
-
-        assert_eq!(message_json["id"], "message_1");
-        assert_eq!(message_json["timestampMs"], 3000);
-        assert_eq!(message_json["content"]["Text"], "done");
-    }
-
     #[test]
     fn dynamic_tool_descriptor_serializes_current_wire_shape() {
         let descriptor = DynamicToolDescriptor {
@@ -4480,114 +387,4 @@ mod tests {
 
         assert!(json.get("providerId").is_none());
     }
-
-    #[derive(Debug)]
-    struct FakeWorkspaceFileSystem;
-
-    #[async_trait::async_trait]
-    impl WorkspaceFileSystem for FakeWorkspaceFileSystem {
-        async fn read_file(&self, _path: &str) -> anyhow::Result<Vec<u8>> {
-            Ok(b"hello".to_vec())
-        }
-
-        async fn read_file_text(&self, _path: &str) -> anyhow::Result<String> {
-            Ok("hello".to_string())
-        }
-
-        async fn write_file(&self, _path: &str, _contents: &[u8]) -> anyhow::Result<()> {
-            Ok(())
-        }
-
-        async fn exists(&self, _path: &str) -> anyhow::Result<bool> {
-            Ok(true)
-        }
-
-        async fn is_file(&self, _path: &str) -> anyhow::Result<bool> {
-            Ok(true)
-        }
-
-        async fn is_dir(&self, _path: &str) -> anyhow::Result<bool> {
-            Ok(false)
-        }
-
-        async fn read_dir(&self, _path: &str) -> anyhow::Result<Vec<WorkspaceDirEntry>> {
-            Ok(vec![WorkspaceDirEntry {
-                name: "file.txt".to_string(),
-                path: "/workspace/file.txt".to_string(),
-                is_dir: false,
-                is_symlink: false,
-            }])
-        }
-    }
-
-    #[derive(Debug)]
-    struct FakeWorkspaceShell;
-
-    #[async_trait::async_trait]
-    impl WorkspaceShell for FakeWorkspaceShell {
-        async fn exec_with_options(
-            &self,
-            _command: &str,
-            options: WorkspaceCommandOptions,
-        ) -> anyhow::Result<WorkspaceCommandResult> {
-            assert_eq!(options.timeout_ms, Some(100));
-            assert!(options.cancellation_token.is_none());
-            Ok(WorkspaceCommandResult {
-                stdout: "ok".to_string(),
-                stderr: String::new(),
-                exit_code: 0,
-                interrupted: false,
-                timed_out: false,
-            })
-        }
-    }
-
-    #[test]
-    fn workspace_services_contract_is_runtime_port_owned() {
-        let services = WorkspaceServices {
-            fs: std::sync::Arc::new(FakeWorkspaceFileSystem),
-            shell: std::sync::Arc::new(FakeWorkspaceShell),
-        };
-
-        let cloned = services.clone();
-        assert!(std::sync::Arc::ptr_eq(&services.fs, &cloned.fs));
-        assert!(std::sync::Arc::ptr_eq(&services.shell, &cloned.shell));
-        assert_eq!(
-            format!("{:?}", services),
-            "WorkspaceServices { fs: \"<dyn WorkspaceFileSystem>\", shell: \"<dyn WorkspaceShell>\" }"
-        );
-    }
-
-    #[test]
-    fn tool_runtime_handles_keep_workspace_services_and_cancellation_contracts() {
-        let cancellation_token = tokio_util::sync::CancellationToken::new();
-        let services = WorkspaceServices {
-            fs: std::sync::Arc::new(FakeWorkspaceFileSystem),
-            shell: std::sync::Arc::new(FakeWorkspaceShell),
-        };
-
-        let handles =
-            ToolRuntimeHandles::new(Some(services.clone()), Some(cancellation_token.clone()));
-
-        assert!(handles.cancellation_token().is_some());
-        assert!(handles.workspace_services().is_some());
-        assert!(std::sync::Arc::ptr_eq(
-            &services.fs,
-            &handles.workspace_services().expect("workspace services").fs
-        ));
-
-        let cloned = handles.clone();
-        assert!(cloned.cancellation_token().is_some());
-        assert!(std::sync::Arc::ptr_eq(
-            &services.shell,
-            &cloned
-                .workspace_services()
-                .expect("workspace services")
-                .shell
-        ));
-        assert_eq!(
-            format!("{:?}", handles),
-            "ToolRuntimeHandles { workspace_services: Some(\"<WorkspaceServices>\"), cancellation_token: Some(\"<CancellationToken>\"), terminal_port: None, remote_exec_port: None }"
-        );
-    }
 }
diff --git a/src/crates/contracts/runtime-ports/src/plugin.rs b/src/crates/contracts/runtime-ports/src/plugin.rs
index 4883d2764c..674d8edf60 100644
--- a/src/crates/contracts/runtime-ports/src/plugin.rs
+++ b/src/crates/contracts/runtime-ports/src/plugin.rs
@@ -67,6 +67,7 @@ pub type PluginRuntimeAvailability = ExtensionCapabilityAvailability;
 pub enum PluginSourceKind {
     LocalPath,
     OpenCodeCompatible,
+    DeepSeekHarnessCompatible,
     RemoteRegistry,
     BitFunNative,
 }
diff --git a/src/crates/contracts/runtime-ports/src/remote_exec_port.rs b/src/crates/contracts/runtime-ports/src/remote_exec_port.rs
new file mode 100644
index 0000000000..4b1b55c39c
--- /dev/null
+++ b/src/crates/contracts/runtime-ports/src/remote_exec_port.rs
@@ -0,0 +1,153 @@
+use super::*;
+use tokio::sync::mpsc;
+
+#[derive(Debug, Clone)]
+pub struct RemoteExecCommandRequest {
+    pub connection_id: String,
+    pub command: String,
+    pub tty: bool,
+    pub yield_time_ms: Option<u64>,
+    pub max_output_chars: Option<usize>,
+    pub lifecycle_sink: Option<RemoteExecLifecycleSink>,
+    pub output_sink: Option<RemoteExecOutputSink>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RemoteExecOneShotCommandRequest {
+    pub connection_id: String,
+    pub command: String,
+    pub timeout_ms: Option<u64>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RemoteExecOneShotCommandResponse {
+    pub stdout: String,
+    pub stderr: String,
+    pub exit_code: i32,
+    pub interrupted: bool,
+    pub timed_out: bool,
+}
+
+#[derive(Debug, Clone)]
+pub struct RemoteWriteStdinRequest {
+    pub session_id: i32,
+    pub chars: String,
+    pub append_enter: bool,
+    pub yield_time_ms: Option<u64>,
+    pub max_output_chars: Option<usize>,
+}
+
+#[derive(Debug, Clone)]
+pub struct RemoteSendStdinRequest {
+    pub session_id: i32,
+    pub chars: String,
+    pub append_enter: bool,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RemoteExecControlAction {
+    Interrupt,
+    Kill,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RemoteExecControlOrigin {
+    ModelTool,
+    OutOfBand,
+}
+
+#[derive(Debug, Clone)]
+pub struct RemoteExecControlRequest {
+    pub session_id: i32,
+    pub action: RemoteExecControlAction,
+    pub origin: RemoteExecControlOrigin,
+    pub yield_time_ms: Option<u64>,
+    pub max_output_chars: Option<usize>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RemoteExecSessionCompletionStatus {
+    Exited,
+    Interrupted,
+    Killed,
+    Pruned,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RemoteExecSessionCompletionSource {
+    Process,
+    OutOfBandControl,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct RemoteExecSessionCompletion {
+    pub status: RemoteExecSessionCompletionStatus,
+    pub source: RemoteExecSessionCompletionSource,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct RemoteExecCommandResponse {
+    pub chunk_id: String,
+    pub wall_time_seconds: f64,
+    pub output: String,
+    pub session_id: Option<i32>,
+    pub exit_code: Option<i32>,
+    pub original_output_chars: usize,
+    pub completion: Option<RemoteExecSessionCompletion>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RemoteExecProcessLifecycleStatus {
+    Running,
+    Exited,
+    Interrupted,
+    Killed,
+    Pruned,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RemoteExecProcessLifecycleEvent {
+    pub session_id: i32,
+    pub status: RemoteExecProcessLifecycleStatus,
+    pub exit_code: Option<i32>,
+}
+
+pub type RemoteExecLifecycleSink = mpsc::UnboundedSender<RemoteExecProcessLifecycleEvent>;
+pub type RemoteExecOutputSink = mpsc::UnboundedSender<String>;
+pub type RemoteExecStreamingOutputSink = mpsc::Sender<String>;
+#[async_trait::async_trait]
+pub trait RemoteExecPort: RuntimeServicePort + std::fmt::Debug {
+    async fn exec_command_once(
+        &self,
+        request: RemoteExecOneShotCommandRequest,
+    ) -> PortResult<RemoteExecOneShotCommandResponse>;
+
+    async fn exec_command(
+        &self,
+        request: RemoteExecCommandRequest,
+    ) -> PortResult<RemoteExecCommandResponse>;
+
+    async fn exec_command_streaming(
+        &self,
+        request: RemoteExecCommandRequest,
+        output_sink: RemoteExecStreamingOutputSink,
+    ) -> PortResult<RemoteExecCommandResponse>;
+
+    async fn write_stdin(
+        &self,
+        request: RemoteWriteStdinRequest,
+    ) -> PortResult<RemoteExecCommandResponse>;
+
+    async fn write_stdin_streaming(
+        &self,
+        request: RemoteWriteStdinRequest,
+        output_sink: RemoteExecStreamingOutputSink,
+    ) -> PortResult<RemoteExecCommandResponse>;
+
+    async fn send_stdin(&self, request: RemoteSendStdinRequest) -> PortResult<()>;
+
+    async fn control_session(
+        &self,
+        request: RemoteExecControlRequest,
+    ) -> PortResult<RemoteExecCommandResponse>;
+}
diff --git a/src/crates/contracts/runtime-ports/src/remote_workspace_ports.rs b/src/crates/contracts/runtime-ports/src/remote_workspace_ports.rs
new file mode 100644
index 0000000000..aeeca21363
--- /dev/null
+++ b/src/crates/contracts/runtime-ports/src/remote_workspace_ports.rs
@@ -0,0 +1,232 @@
+use super::*;
+use std::path::{Path, PathBuf};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum RemoteWorkspaceKind {
+    Normal,
+    Assistant,
+    Remote,
+}
+
+impl RemoteWorkspaceKind {
+    pub const fn as_wire_str(self) -> &'static str {
+        match self {
+            Self::Normal => "normal",
+            Self::Assistant => "assistant",
+            Self::Remote => "remote",
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RemoteWorkspaceFacts {
+    pub path: String,
+    pub name: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub git_branch: Option<String>,
+    pub kind: RemoteWorkspaceKind,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub assistant_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_connection_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_ssh_host: Option<String>,
+}
+
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct RemoteSessionWorkspaceIdentity {
+    pub remote_connection_id: Option<String>,
+    pub remote_ssh_host: Option<String>,
+}
+
+impl RemoteSessionWorkspaceIdentity {
+    pub fn new(remote_connection_id: Option<String>, remote_ssh_host: Option<String>) -> Self {
+        Self {
+            remote_connection_id,
+            remote_ssh_host,
+        }
+    }
+
+    pub fn from_workspace(workspace: &RemoteWorkspaceFacts) -> Self {
+        Self::new(
+            workspace.remote_connection_id.clone(),
+            workspace.remote_ssh_host.clone(),
+        )
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.remote_connection_id.is_none() && self.remote_ssh_host.is_none()
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RemoteRecentWorkspaceFacts {
+    pub path: String,
+    pub name: String,
+    pub last_opened: String,
+    pub kind: RemoteWorkspaceKind,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_connection_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_ssh_host: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RemoteAssistantWorkspaceFacts {
+    pub path: String,
+    pub name: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub assistant_id: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RemoteWorkspaceUpdate {
+    pub path: String,
+    pub name: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_connection_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_ssh_host: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RemoteSessionMetadata {
+    pub session_id: String,
+    pub name: String,
+    pub agent_type: String,
+    pub created_at_ms: u64,
+    pub last_active_at_ms: u64,
+    pub turn_count: usize,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RemoteWorkspaceFileContent {
+    pub name: String,
+    pub bytes: Vec<u8>,
+    pub mime_type: &'static str,
+    pub size: u64,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RemoteWorkspaceFileChunk {
+    pub name: String,
+    pub bytes: Vec<u8>,
+    pub offset: u64,
+    pub chunk_size: u64,
+    pub total_size: u64,
+    pub mime_type: &'static str,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RemoteWorkspaceFileInfo {
+    pub name: String,
+    pub size: u64,
+    pub mime_type: &'static str,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct RemoteFileChunkRange {
+    pub start: usize,
+    pub end: usize,
+    pub chunk_size: u64,
+}
+
+/// Old remote-connect host compatibility trait for workspace commands.
+#[async_trait::async_trait]
+pub trait RemoteWorkspaceRuntimeHost: Send + Sync {
+    async fn current_workspace(&self) -> Option<RemoteWorkspaceFacts>;
+    async fn recent_workspaces(&self) -> Vec<RemoteRecentWorkspaceFacts>;
+    async fn open_workspace(
+        &self,
+        path: &str,
+        remote_connection_id: Option<&str>,
+        remote_ssh_host: Option<&str>,
+    ) -> Result<RemoteWorkspaceUpdate, String>;
+    async fn assistant_workspaces(&self) -> Vec<RemoteAssistantWorkspaceFacts>;
+    async fn open_assistant_workspace(&self, path: &str) -> Result<RemoteWorkspaceUpdate, String>;
+}
+
+/// Typed registration boundary for remote workspace providers.
+pub trait RemoteWorkspacePort: RuntimeServicePort + RemoteWorkspaceRuntimeHost {}
+
+impl<T> RemoteWorkspacePort for T where T: RuntimeServicePort + RemoteWorkspaceRuntimeHost + ?Sized {}
+
+/// Old remote-connect host compatibility trait for initial sync.
+#[async_trait::async_trait]
+pub trait RemoteInitialSyncRuntimeHost: Send + Sync {
+    async fn current_workspace(&self) -> Option<RemoteWorkspaceFacts>;
+    async fn list_session_metadata(
+        &self,
+        workspace_path: &Path,
+        workspace_identity: RemoteSessionWorkspaceIdentity,
+    ) -> Result<Vec<RemoteSessionMetadata>, String>;
+}
+
+/// Old remote-connect host compatibility trait for remote file projection.
+#[async_trait::async_trait]
+pub trait RemoteWorkspaceFileRuntimeHost: Send + Sync {
+    async fn resolve_remote_file_workspace_root(&self, session_id: Option<&str>)
+        -> Option<PathBuf>;
+}
+
+/// Typed registration boundary for remote filesystem/terminal/image projection providers.
+pub trait RemoteProjectionPort: RuntimeServicePort + RemoteWorkspaceFileRuntimeHost {}
+
+impl<T> RemoteProjectionPort for T where
+    T: RuntimeServicePort + RemoteWorkspaceFileRuntimeHost + ?Sized
+{
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn remote_workspace_contracts_preserve_workspace_and_session_facts() {
+        let workspace = RemoteWorkspaceFacts {
+            path: "/workspace/project".to_string(),
+            name: "project".to_string(),
+            git_branch: Some("main".to_string()),
+            kind: RemoteWorkspaceKind::Remote,
+            assistant_id: Some("assistant_1".to_string()),
+            remote_connection_id: Some("conn-1".to_string()),
+            remote_ssh_host: Some("host-1".to_string()),
+        };
+        let session = RemoteSessionMetadata {
+            session_id: "session_1".to_string(),
+            name: "Research".to_string(),
+            agent_type: "CodeAgent".to_string(),
+            created_at_ms: 10,
+            last_active_at_ms: 20,
+            turn_count: 3,
+        };
+
+        assert_eq!(workspace.kind.as_wire_str(), "remote");
+        assert_eq!(workspace.assistant_id.as_deref(), Some("assistant_1"));
+        assert_eq!(workspace.remote_connection_id.as_deref(), Some("conn-1"));
+        assert_eq!(workspace.remote_ssh_host.as_deref(), Some("host-1"));
+        assert_eq!(session.turn_count, 3);
+    }
+
+    #[test]
+    fn remote_projection_contract_preserves_file_chunk_identity() {
+        let chunk = RemoteWorkspaceFileChunk {
+            name: "report.md".to_string(),
+            bytes: b"chunk".to_vec(),
+            offset: 6,
+            chunk_size: 5,
+            total_size: 11,
+            mime_type: "text/markdown",
+        };
+
+        assert_eq!(chunk.name, "report.md");
+        assert_eq!(chunk.bytes, b"chunk");
+        assert_eq!(chunk.offset + chunk.chunk_size, chunk.total_size);
+    }
+}
diff --git a/src/crates/contracts/runtime-ports/src/runtime_event_port.rs b/src/crates/contracts/runtime-ports/src/runtime_event_port.rs
new file mode 100644
index 0000000000..7c18cb7a11
--- /dev/null
+++ b/src/crates/contracts/runtime-ports/src/runtime_event_port.rs
@@ -0,0 +1,53 @@
+use super::*;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum RuntimeEventType {
+    TurnStarted,
+    TurnCompleted,
+    TurnFailed,
+    TurnCancelled,
+    SessionStateChanged,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RuntimeEventEnvelope {
+    pub session_id: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub turn_id: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub source: Option<AgentSubmissionSource>,
+    pub event_type: RuntimeEventType,
+    #[serde(default)]
+    pub payload: serde_json::Value,
+}
+
+#[async_trait::async_trait]
+pub trait RuntimeEventSink: Send + Sync {
+    async fn publish_runtime_event(&self, event: RuntimeEventEnvelope) -> PortResult<()>;
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn runtime_event_envelope_serializes_observational_surface_facts() {
+        let event = RuntimeEventEnvelope {
+            session_id: "session_1".to_string(),
+            turn_id: Some("turn_1".to_string()),
+            source: Some(AgentSubmissionSource::RemoteRelay),
+            event_type: RuntimeEventType::TurnCancelled,
+            payload: serde_json::json!({ "reason": "user_cancelled" }),
+        };
+
+        let json = serde_json::to_value(event).expect("serialize event");
+
+        assert_eq!(json["sessionId"], "session_1");
+        assert_eq!(json["turnId"], "turn_1");
+        assert_eq!(json["source"], "remote_relay");
+        assert_eq!(json["eventType"], "turn_cancelled");
+        assert_eq!(json["payload"]["reason"], "user_cancelled");
+    }
+}
diff --git a/src/crates/contracts/runtime-ports/src/service_markers.rs b/src/crates/contracts/runtime-ports/src/service_markers.rs
new file mode 100644
index 0000000000..8fe438f609
--- /dev/null
+++ b/src/crates/contracts/runtime-ports/src/service_markers.rs
@@ -0,0 +1,21 @@
+use super::*;
+
+pub trait FileSystemPort: RuntimeServicePort {}
+
+pub trait WorkspacePort: RuntimeServicePort {}
+
+pub trait ClockPort: RuntimeServicePort {
+    fn now_unix_millis(&self) -> i64;
+}
+
+pub trait NetworkPort: RuntimeServicePort {}
+
+pub trait McpCatalogPort: RuntimeServicePort {}
+
+/// Typed registration boundary for remote connection providers.
+///
+/// PR1 intentionally keeps this trait handle-free; PR2 adds owner-specific
+/// lifecycle methods once behavior-equivalence tests are in place.
+pub trait RemoteConnectionPort: RuntimeServicePort {}
+
+pub trait RemoteCapabilityPort: RuntimeServicePort {}
diff --git a/src/crates/contracts/runtime-ports/src/terminal_port.rs b/src/crates/contracts/runtime-ports/src/terminal_port.rs
new file mode 100644
index 0000000000..8bf7107ac5
--- /dev/null
+++ b/src/crates/contracts/runtime-ports/src/terminal_port.rs
@@ -0,0 +1,136 @@
+use super::*;
+use std::collections::HashMap;
+use std::path::PathBuf;
+use tokio::sync::mpsc;
+
+#[derive(Debug, Clone)]
+pub struct TerminalExecCommandRequest {
+    pub argv: Vec<String>,
+    pub cwd: PathBuf,
+    pub env: HashMap<String, String>,
+    pub tty: bool,
+    pub yield_time_ms: Option<u64>,
+    pub max_output_chars: Option<usize>,
+    pub lifecycle_sink: Option<TerminalExecLifecycleSink>,
+    pub output_sink: Option<TerminalExecOutputSink>,
+}
+
+#[derive(Debug, Clone)]
+pub struct TerminalWriteStdinRequest {
+    pub session_id: i32,
+    pub chars: String,
+    pub append_enter: bool,
+    pub yield_time_ms: Option<u64>,
+    pub max_output_chars: Option<usize>,
+}
+
+#[derive(Debug, Clone)]
+pub struct TerminalSendStdinRequest {
+    pub session_id: i32,
+    pub chars: String,
+    pub append_enter: bool,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum TerminalExecControlAction {
+    Interrupt,
+    Kill,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum TerminalExecControlOrigin {
+    ModelTool,
+    OutOfBand,
+}
+
+#[derive(Debug, Clone)]
+pub struct TerminalExecControlRequest {
+    pub session_id: i32,
+    pub action: TerminalExecControlAction,
+    pub origin: TerminalExecControlOrigin,
+    pub yield_time_ms: Option<u64>,
+    pub max_output_chars: Option<usize>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum TerminalExecSessionCompletionStatus {
+    Exited,
+    Interrupted,
+    Killed,
+    Pruned,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum TerminalExecSessionCompletionSource {
+    Process,
+    OutOfBandControl,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct TerminalExecSessionCompletion {
+    pub status: TerminalExecSessionCompletionStatus,
+    pub source: TerminalExecSessionCompletionSource,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct TerminalExecCommandResponse {
+    pub chunk_id: String,
+    pub wall_time_seconds: f64,
+    pub output: String,
+    pub session_id: Option<i32>,
+    pub exit_code: Option<i32>,
+    pub original_output_chars: usize,
+    pub completion: Option<TerminalExecSessionCompletion>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum TerminalExecProcessLifecycleStatus {
+    Running,
+    Exited,
+    Interrupted,
+    Killed,
+    Pruned,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct TerminalExecProcessLifecycleEvent {
+    pub session_id: i32,
+    pub status: TerminalExecProcessLifecycleStatus,
+    pub exit_code: Option<i32>,
+}
+
+pub type TerminalExecLifecycleSink = mpsc::UnboundedSender<TerminalExecProcessLifecycleEvent>;
+pub type TerminalExecOutputSink = mpsc::UnboundedSender<String>;
+pub type TerminalExecStreamingOutputSink = mpsc::Sender<String>;
+
+#[async_trait::async_trait]
+pub trait TerminalPort: RuntimeServicePort + std::fmt::Debug {
+    async fn exec_command(
+        &self,
+        request: TerminalExecCommandRequest,
+    ) -> PortResult<TerminalExecCommandResponse>;
+
+    async fn exec_command_streaming(
+        &self,
+        request: TerminalExecCommandRequest,
+        output_sink: TerminalExecStreamingOutputSink,
+    ) -> PortResult<TerminalExecCommandResponse>;
+
+    async fn write_stdin(
+        &self,
+        request: TerminalWriteStdinRequest,
+    ) -> PortResult<TerminalExecCommandResponse>;
+
+    async fn write_stdin_streaming(
+        &self,
+        request: TerminalWriteStdinRequest,
+        output_sink: TerminalExecStreamingOutputSink,
+    ) -> PortResult<TerminalExecCommandResponse>;
+
+    async fn send_stdin(&self, request: TerminalSendStdinRequest) -> PortResult<()>;
+
+    async fn control_session(
+        &self,
+        request: TerminalExecControlRequest,
+    ) -> PortResult<TerminalExecCommandResponse>;
+}
diff --git a/src/crates/contracts/runtime-ports/src/tool_runtime_handles.rs b/src/crates/contracts/runtime-ports/src/tool_runtime_handles.rs
new file mode 100644
index 0000000000..c348b42f67
--- /dev/null
+++ b/src/crates/contracts/runtime-ports/src/tool_runtime_handles.rs
@@ -0,0 +1,126 @@
+use super::*;
+use std::sync::Arc;
+use tokio_util::sync::CancellationToken;
+
+/// Runtime handles injected into tool execution contexts.
+///
+/// This bundle is intentionally handle-only. Concrete local or remote
+/// implementations are still assembled by product/runtime owners outside this
+/// crate.
+#[derive(Clone, Default)]
+pub struct ToolRuntimeHandles {
+    workspace_services: Option<WorkspaceServices>,
+    cancellation_token: Option<CancellationToken>,
+    terminal_port: Option<Arc<dyn TerminalPort>>,
+    remote_exec_port: Option<Arc<dyn RemoteExecPort>>,
+}
+
+impl ToolRuntimeHandles {
+    pub fn new(
+        workspace_services: Option<WorkspaceServices>,
+        cancellation_token: Option<CancellationToken>,
+    ) -> Self {
+        Self {
+            workspace_services,
+            cancellation_token,
+            terminal_port: None,
+            remote_exec_port: None,
+        }
+    }
+
+    pub fn with_terminal_port(mut self, terminal_port: Option<Arc<dyn TerminalPort>>) -> Self {
+        self.terminal_port = terminal_port;
+        self
+    }
+
+    pub fn with_remote_exec_port(
+        mut self,
+        remote_exec_port: Option<Arc<dyn RemoteExecPort>>,
+    ) -> Self {
+        self.remote_exec_port = remote_exec_port;
+        self
+    }
+
+    pub fn workspace_services(&self) -> Option<&WorkspaceServices> {
+        self.workspace_services.as_ref()
+    }
+
+    pub fn cancellation_token(&self) -> Option<&CancellationToken> {
+        self.cancellation_token.as_ref()
+    }
+
+    pub fn terminal_port(&self) -> Option<&Arc<dyn TerminalPort>> {
+        self.terminal_port.as_ref()
+    }
+
+    pub fn remote_exec_port(&self) -> Option<&Arc<dyn RemoteExecPort>> {
+        self.remote_exec_port.as_ref()
+    }
+}
+
+impl std::fmt::Debug for ToolRuntimeHandles {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("ToolRuntimeHandles")
+            .field(
+                "workspace_services",
+                &self
+                    .workspace_services
+                    .as_ref()
+                    .map(|_| "<WorkspaceServices>"),
+            )
+            .field(
+                "cancellation_token",
+                &self
+                    .cancellation_token
+                    .as_ref()
+                    .map(|_| "<CancellationToken>"),
+            )
+            .field(
+                "terminal_port",
+                &self.terminal_port.as_ref().map(|_| "<dyn TerminalPort>"),
+            )
+            .field(
+                "remote_exec_port",
+                &self
+                    .remote_exec_port
+                    .as_ref()
+                    .map(|_| "<dyn RemoteExecPort>"),
+            )
+            .finish()
+    }
+}
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::workspace_ports::tests::fake_workspace_services;
+
+    #[test]
+    fn tool_runtime_handles_keep_workspace_services_and_cancellation_contracts() {
+        let cancellation_token = tokio_util::sync::CancellationToken::new();
+        let services = fake_workspace_services();
+
+        let handles =
+            ToolRuntimeHandles::new(Some(services.clone()), Some(cancellation_token.clone()));
+
+        assert!(handles.cancellation_token().is_some());
+        assert!(handles.workspace_services().is_some());
+        assert!(std::sync::Arc::ptr_eq(
+            &services.fs,
+            &handles.workspace_services().expect("workspace services").fs
+        ));
+
+        let cloned = handles.clone();
+        assert!(cloned.cancellation_token().is_some());
+        assert!(std::sync::Arc::ptr_eq(
+            &services.shell,
+            &cloned
+                .workspace_services()
+                .expect("workspace services")
+                .shell
+        ));
+        assert_eq!(
+            format!("{:?}", handles),
+            "ToolRuntimeHandles { workspace_services: Some(\"<WorkspaceServices>\"), cancellation_token: Some(\"<CancellationToken>\"), terminal_port: None, remote_exec_port: None }"
+        );
+    }
+}
diff --git a/src/crates/contracts/runtime-ports/src/workspace_ports.rs b/src/crates/contracts/runtime-ports/src/workspace_ports.rs
new file mode 100644
index 0000000000..a78259bb54
--- /dev/null
+++ b/src/crates/contracts/runtime-ports/src/workspace_ports.rs
@@ -0,0 +1,404 @@
+use super::*;
+use std::path::PathBuf;
+use std::sync::Arc;
+use tokio_util::sync::CancellationToken;
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SessionStoragePathRequest {
+    pub workspace_path: PathBuf,
+    pub remote_connection_id: Option<String>,
+    pub remote_ssh_host: Option<String>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum SessionStorageKind {
+    Local,
+    Remote,
+    UnresolvedRemote,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SessionStoragePathResolution {
+    pub requested_workspace_path: PathBuf,
+    pub effective_storage_path: PathBuf,
+    pub storage_kind: SessionStorageKind,
+    pub remote_connection_id: Option<String>,
+    pub remote_ssh_host: Option<String>,
+}
+
+impl SessionStoragePathResolution {
+    pub fn new(
+        requested_workspace_path: PathBuf,
+        effective_storage_path: PathBuf,
+        storage_kind: SessionStorageKind,
+        remote_connection_id: Option<String>,
+        remote_ssh_host: Option<String>,
+    ) -> Self {
+        Self {
+            requested_workspace_path,
+            effective_storage_path,
+            storage_kind,
+            remote_connection_id,
+            remote_ssh_host,
+        }
+    }
+
+    pub fn is_remote_storage(&self) -> bool {
+        matches!(
+            self.storage_kind,
+            SessionStorageKind::Remote | SessionStorageKind::UnresolvedRemote
+        )
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SessionViewRestoreRequest {
+    pub workspace_path: PathBuf,
+    pub session_id: String,
+    pub include_internal: bool,
+    pub tail_turn_count: Option<usize>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SessionTurnLoadRequest {
+    pub workspace_path: PathBuf,
+    pub session_id: String,
+    pub tail_turn_count: Option<usize>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SessionTurnWindowRequest {
+    pub workspace_path: PathBuf,
+    pub session_id: String,
+    pub include_internal: bool,
+    pub target_storage_turn_index: usize,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub expected_turn_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub expected_catalog_revision: Option<String>,
+    pub before: usize,
+    pub after: usize,
+}
+
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SessionTurnLoadTiming {
+    pub requested_tail_turn_count: Option<usize>,
+    pub loaded_turn_count: usize,
+    pub total_turn_count: usize,
+    pub turn_file_count: usize,
+    pub missing_turn_file_count: usize,
+    pub fast_path: bool,
+    pub metadata_duration_ms: u64,
+    pub state_duration_ms: u64,
+    pub scan_duration_ms: u64,
+    pub read_duration_ms: u64,
+    pub max_turn_read_duration_ms: u64,
+    pub build_session_duration_ms: u64,
+    pub total_duration_ms: u64,
+}
+
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SessionViewRestoreTiming {
+    pub resolve_storage_path_duration_ms: u64,
+    pub visibility_metadata_duration_ms: u64,
+    pub load_session_with_turns_duration_ms: u64,
+    pub normalize_turn_ids_duration_ms: u64,
+    #[serde(default)]
+    pub turn_catalog_duration_ms: u64,
+    pub total_duration_ms: u64,
+    pub turn_load: SessionTurnLoadTiming,
+}
+
+#[async_trait::async_trait]
+pub trait SessionStorePort: RuntimeServicePort {
+    async fn resolve_session_storage_path(
+        &self,
+        request: SessionStoragePathRequest,
+    ) -> PortResult<SessionStoragePathResolution>;
+}
+
+/// One row from [`WorkspaceFileSystem::read_dir`] (POSIX paths when the backend is remote SSH).
+#[derive(Debug, Clone)]
+pub struct WorkspaceDirEntry {
+    pub name: String,
+    pub path: String,
+    pub is_dir: bool,
+    pub is_symlink: bool,
+}
+
+/// File type for one exact path without following its final symbolic link.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum WorkspacePathKind {
+    File,
+    Directory,
+    Symlink,
+    Other,
+}
+
+/// Unified file system operations that work for both local and remote workspaces.
+#[async_trait::async_trait]
+pub trait WorkspaceFileSystem: Send + Sync {
+    /// Join path components using the syntax understood by this provider.
+    ///
+    /// Local providers inherit the host path syntax. Remote providers must
+    /// override this when their filesystem uses a different syntax than the
+    /// host process.
+    fn join_path(&self, root: &str, components: &[&str]) -> String {
+        let mut path = PathBuf::from(root);
+        path.extend(components);
+        path.to_string_lossy().into_owned()
+    }
+
+    async fn read_file(&self, path: &str) -> anyhow::Result<Vec<u8>>;
+    /// Read binary content up to `max_bytes`.
+    ///
+    /// `Ok(None)` means the file exceeded the bound; missing paths, non-files, and transport
+    /// failures remain errors. Production providers should enforce the bound before or while
+    /// transferring the file.
+    async fn read_file_bounded(
+        &self,
+        path: &str,
+        max_bytes: usize,
+    ) -> anyhow::Result<Option<Vec<u8>>> {
+        let bytes = self.read_file(path).await?;
+        Ok((bytes.len() <= max_bytes).then_some(bytes))
+    }
+    async fn read_file_text(&self, path: &str) -> anyhow::Result<String>;
+    /// Read UTF-8 text up to `max_bytes`. Production filesystem providers
+    /// should enforce the bound before or while transferring the file.
+    async fn read_file_text_bounded(
+        &self,
+        path: &str,
+        max_bytes: usize,
+    ) -> anyhow::Result<Option<String>> {
+        let content = self.read_file_text(path).await?;
+        Ok((content.len() <= max_bytes).then_some(content))
+    }
+    async fn write_file(&self, path: &str, contents: &[u8]) -> anyhow::Result<()>;
+    async fn exists(&self, path: &str) -> anyhow::Result<bool>;
+    async fn is_file(&self, path: &str) -> anyhow::Result<bool>;
+    async fn is_dir(&self, path: &str) -> anyhow::Result<bool>;
+    /// Inspect one exact path without following its final symbolic link.
+    /// Providers that cannot guarantee no-follow semantics must return an
+    /// error instead of falling back to link-following metadata.
+    async fn path_kind_no_follow(&self, _path: &str) -> anyhow::Result<Option<WorkspacePathKind>> {
+        Err(anyhow::anyhow!(
+            "exact no-follow path metadata is not supported by this workspace filesystem"
+        ))
+    }
+    /// List immediate children (non-recursive). Symlinks may be included; callers often skip them.
+    async fn read_dir(&self, path: &str) -> anyhow::Result<Vec<WorkspaceDirEntry>>;
+    /// List at most `max_entries` immediate children. Production providers
+    /// should stop local iteration or remote directory-batch requests once the
+    /// bound is met.
+    async fn read_dir_bounded(
+        &self,
+        path: &str,
+        max_entries: usize,
+    ) -> anyhow::Result<Vec<WorkspaceDirEntry>> {
+        let mut entries = self.read_dir(path).await?;
+        entries.truncate(max_entries);
+        Ok(entries)
+    }
+}
+
+/// Unified shell execution options for local and remote workspaces.
+#[derive(Clone, Default)]
+pub struct WorkspaceCommandOptions {
+    pub timeout_ms: Option<u64>,
+    pub cancellation_token: Option<CancellationToken>,
+}
+
+impl std::fmt::Debug for WorkspaceCommandOptions {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("WorkspaceCommandOptions")
+            .field("timeout_ms", &self.timeout_ms)
+            .field(
+                "cancellation_token",
+                &self
+                    .cancellation_token
+                    .as_ref()
+                    .map(|_| "<CancellationToken>"),
+            )
+            .finish()
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct WorkspaceCommandResult {
+    pub stdout: String,
+    pub stderr: String,
+    pub exit_code: i32,
+    pub interrupted: bool,
+    pub timed_out: bool,
+}
+
+impl WorkspaceCommandResult {
+    pub fn combined_output(&self) -> String {
+        if self.stderr.is_empty() {
+            self.stdout.clone()
+        } else if self.stdout.is_empty() {
+            self.stderr.clone()
+        } else {
+            format!("{}\n{}", self.stdout, self.stderr)
+        }
+    }
+}
+
+/// Unified shell execution for both local and remote workspaces.
+#[async_trait::async_trait]
+pub trait WorkspaceShell: Send + Sync {
+    /// Execute a command and return a structured result.
+    async fn exec_with_options(
+        &self,
+        command: &str,
+        options: WorkspaceCommandOptions,
+    ) -> anyhow::Result<WorkspaceCommandResult>;
+
+    /// Execute a command and return (stdout, stderr, exit_code).
+    async fn exec(
+        &self,
+        command: &str,
+        timeout_ms: Option<u64>,
+    ) -> anyhow::Result<(String, String, i32)> {
+        let result = self
+            .exec_with_options(
+                command,
+                WorkspaceCommandOptions {
+                    timeout_ms,
+                    ..Default::default()
+                },
+            )
+            .await?;
+
+        if result.timed_out {
+            anyhow::bail!(
+                "Command timed out after {}ms",
+                timeout_ms.unwrap_or_default()
+            );
+        }
+        if result.interrupted {
+            anyhow::bail!("Command was cancelled");
+        }
+
+        Ok((result.stdout, result.stderr, result.exit_code))
+    }
+}
+
+/// Bundle of workspace I/O services injected into tool runtime context.
+pub struct WorkspaceServices {
+    pub fs: Arc<dyn WorkspaceFileSystem>,
+    pub shell: Arc<dyn WorkspaceShell>,
+}
+
+impl Clone for WorkspaceServices {
+    fn clone(&self) -> Self {
+        Self {
+            fs: Arc::clone(&self.fs),
+            shell: Arc::clone(&self.shell),
+        }
+    }
+}
+
+impl std::fmt::Debug for WorkspaceServices {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("WorkspaceServices")
+            .field("fs", &"<dyn WorkspaceFileSystem>")
+            .field("shell", &"<dyn WorkspaceShell>")
+            .finish()
+    }
+}
+
+#[cfg(test)]
+pub(crate) mod tests {
+    use super::*;
+
+    #[derive(Debug)]
+    struct FakeWorkspaceFileSystem;
+
+    #[async_trait::async_trait]
+    impl WorkspaceFileSystem for FakeWorkspaceFileSystem {
+        async fn read_file(&self, _path: &str) -> anyhow::Result<Vec<u8>> {
+            Ok(b"hello".to_vec())
+        }
+
+        async fn read_file_text(&self, _path: &str) -> anyhow::Result<String> {
+            Ok("hello".to_string())
+        }
+
+        async fn write_file(&self, _path: &str, _contents: &[u8]) -> anyhow::Result<()> {
+            Ok(())
+        }
+
+        async fn exists(&self, _path: &str) -> anyhow::Result<bool> {
+            Ok(true)
+        }
+
+        async fn is_file(&self, _path: &str) -> anyhow::Result<bool> {
+            Ok(true)
+        }
+
+        async fn is_dir(&self, _path: &str) -> anyhow::Result<bool> {
+            Ok(false)
+        }
+
+        async fn read_dir(&self, _path: &str) -> anyhow::Result<Vec<WorkspaceDirEntry>> {
+            Ok(vec![WorkspaceDirEntry {
+                name: "file.txt".to_string(),
+                path: "/workspace/file.txt".to_string(),
+                is_dir: false,
+                is_symlink: false,
+            }])
+        }
+    }
+
+    #[derive(Debug)]
+    struct FakeWorkspaceShell;
+
+    #[async_trait::async_trait]
+    impl WorkspaceShell for FakeWorkspaceShell {
+        async fn exec_with_options(
+            &self,
+            _command: &str,
+            options: WorkspaceCommandOptions,
+        ) -> anyhow::Result<WorkspaceCommandResult> {
+            assert_eq!(options.timeout_ms, Some(100));
+            assert!(options.cancellation_token.is_none());
+            Ok(WorkspaceCommandResult {
+                stdout: "ok".to_string(),
+                stderr: String::new(),
+                exit_code: 0,
+                interrupted: false,
+                timed_out: false,
+            })
+        }
+    }
+
+    pub(crate) fn fake_workspace_services() -> WorkspaceServices {
+        WorkspaceServices {
+            fs: Arc::new(FakeWorkspaceFileSystem),
+            shell: Arc::new(FakeWorkspaceShell),
+        }
+    }
+
+    #[test]
+    fn workspace_services_contract_is_runtime_port_owned() {
+        let services = fake_workspace_services();
+
+        let cloned = services.clone();
+        assert!(Arc::ptr_eq(&services.fs, &cloned.fs));
+        assert!(Arc::ptr_eq(&services.shell, &cloned.shell));
+        assert_eq!(
+            format!("{:?}", services),
+            "WorkspaceServices { fs: \"<dyn WorkspaceFileSystem>\", shell: \"<dyn WorkspaceShell>\" }"
+        );
+    }
+}
diff --git a/src/crates/contracts/runtime-ports/tests/git_port_contracts.rs b/src/crates/contracts/runtime-ports/tests/git_port_contracts.rs
index 24712dcb21..1f603a1d97 100644
--- a/src/crates/contracts/runtime-ports/tests/git_port_contracts.rs
+++ b/src/crates/contracts/runtime-ports/tests/git_port_contracts.rs
@@ -1,3 +1,5 @@
+#![cfg(feature = "git-port")]
+
 use bitfun_runtime_ports::{
     WorkspaceDiffContent, WorkspaceDiffFile, WorkspaceDiffFileStatus, WorkspaceDiffSnapshot,
 };
diff --git a/src/crates/contracts/runtime-ports/tests/runtime_port_contracts.rs b/src/crates/contracts/runtime-ports/tests/runtime_port_contracts.rs
new file mode 100644
index 0000000000..5adb642538
--- /dev/null
+++ b/src/crates/contracts/runtime-ports/tests/runtime_port_contracts.rs
@@ -0,0 +1,6 @@
+#![cfg(feature = "plugin-runtime")]
+
+#[path = "runtime_port_contracts/plugin_runtime_contracts.rs"]
+mod plugin_runtime_contracts;
+#[path = "runtime_port_contracts/plugin_runtime_diagnostics_contracts.rs"]
+mod plugin_runtime_diagnostics_contracts;
diff --git a/src/crates/contracts/runtime-ports/tests/plugin_runtime_contracts.rs b/src/crates/contracts/runtime-ports/tests/runtime_port_contracts/plugin_runtime_contracts.rs
similarity index 98%
rename from src/crates/contracts/runtime-ports/tests/plugin_runtime_contracts.rs
rename to src/crates/contracts/runtime-ports/tests/runtime_port_contracts/plugin_runtime_contracts.rs
index e2c62277e5..6bda80f9d1 100644
--- a/src/crates/contracts/runtime-ports/tests/plugin_runtime_contracts.rs
+++ b/src/crates/contracts/runtime-ports/tests/runtime_port_contracts/plugin_runtime_contracts.rs
@@ -32,6 +32,21 @@ fn source_ref() -> PluginSourceRef {
     }
 }
 
+#[test]
+fn deep_seek_harness_source_kind_has_a_stable_wire_name() {
+    let mut source = source_ref();
+    source.source_kind = PluginSourceKind::DeepSeekHarnessCompatible;
+
+    let json = serde_json::to_value(&source).expect("serialize dsh source");
+    assert_eq!(json["sourceKind"], "deep_seek_harness_compatible");
+
+    let roundtrip: PluginSourceRef = serde_json::from_value(json).expect("deserialize dsh source");
+    assert_eq!(
+        roundtrip.source_kind,
+        PluginSourceKind::DeepSeekHarnessCompatible
+    );
+}
+
 fn capability_ref() -> PluginCapabilityRef {
     PluginCapabilityRef {
         capability_id: "tools.provider".to_string(),
diff --git a/src/crates/contracts/runtime-ports/tests/plugin_runtime_diagnostics_contracts.rs b/src/crates/contracts/runtime-ports/tests/runtime_port_contracts/plugin_runtime_diagnostics_contracts.rs
similarity index 100%
rename from src/crates/contracts/runtime-ports/tests/plugin_runtime_diagnostics_contracts.rs
rename to src/crates/contracts/runtime-ports/tests/runtime_port_contracts/plugin_runtime_diagnostics_contracts.rs
diff --git a/src/crates/contracts/runtime-ports/tests/script_tool_port_contracts.rs b/src/crates/contracts/runtime-ports/tests/script_tool_port_contracts.rs
index 639fe1268d..112cbd6ef7 100644
--- a/src/crates/contracts/runtime-ports/tests/script_tool_port_contracts.rs
+++ b/src/crates/contracts/runtime-ports/tests/script_tool_port_contracts.rs
@@ -1,3 +1,5 @@
+#![cfg(feature = "script-tool-runtime")]
+
 use async_trait::async_trait;
 use bitfun_runtime_ports::{
     PortResult, ScriptToolDescriptor, ScriptToolExpectedExport, ScriptToolInvokeRequest,
diff --git a/src/crates/contracts/runtime-ports/tests/session_store_contracts.rs b/src/crates/contracts/runtime-ports/tests/session_store_contracts.rs
index dadfa796c3..570a41531d 100644
--- a/src/crates/contracts/runtime-ports/tests/session_store_contracts.rs
+++ b/src/crates/contracts/runtime-ports/tests/session_store_contracts.rs
@@ -1,3 +1,5 @@
+#![cfg(feature = "workspace-ports")]
+
 use std::path::PathBuf;
 
 use bitfun_runtime_ports::{
diff --git a/src/crates/execution/agent-runtime/AGENTS.md b/src/crates/execution/agent-runtime/AGENTS.md
index de5ab03d3e..5025d990fb 100644
--- a/src/crates/execution/agent-runtime/AGENTS.md
+++ b/src/crates/execution/agent-runtime/AGENTS.md
@@ -7,6 +7,19 @@ session/config/context facts, lifecycle helper state, and the narrow
 port-backed `sdk` / `AgentRuntime` facade that can be built and tested without
 `bitfun-core`.
 
+## Feature Boundaries
+
+- `deep-research` exposes only provider-neutral citation renumbering.
+- `native-hook-settings` exposes Codex-compatible hook settings parsing and
+  validation without process execution.
+- `native-hook-runtime` extends settings with payload, output, and managed
+  child-process execution.
+- `agent-runtime` selects the complete portable runtime and includes
+  `native-hook-runtime`; it intentionally does not include `deep-research`.
+- `default` stays empty. Consumers select the smallest owner feature they use;
+  do not add a compatibility `full` feature or rely on another workspace
+  consumer to create a Cargo feature union.
+
 ## Guardrails
 
 - Do not depend on `bitfun-core`, app crates, Tauri, ACP protocol, web UI,
@@ -64,7 +77,7 @@ port-backed `sdk` / `AgentRuntime` facade that can be built and tested without
 
 ## Test Target Layout
 
-Integration contracts use five explicit Cargo targets so package-level checks
+Integration contracts use seven explicit Cargo targets so package-level checks
 do not relink the same feature-free dependency closure for every source file,
 while platform-specific process tests retain executable-level isolation:
 
@@ -72,8 +85,10 @@ while platform-specific process tests retain executable-level isolation:
 |---|---|
 | `agent_definition_contracts` | Agent definitions, discovery, prompts, prompt cache, and skills |
 | `agent_session_contracts` | Events, scheduling, sessions, SDK behavior, and workspace-reference ports |
-| `agent_interaction_contracts` | Permissions, questions, and hook execution |
-| `agent_long_horizon_contracts` | DeepResearch, DeepReview, and long-running thread-goal behavior |
+| `agent_interaction_contracts` | Permissions, questions, hook payloads, and post-call hook behavior (`agent-runtime`) |
+| `agent_long_horizon_contracts` | DeepReview and long-running thread-goal behavior (`agent-runtime`) |
+| `deep_research_contracts` | Citation numbering without the complete Agent Runtime (`deep-research`) |
+| `native_hook_settings_contracts` | Hook settings parsing without process execution (`native-hook-settings`) |
 | `native_hook_execution_contracts` | Unix-only native process execution, timeout, and cleanup behavior |
 
 Add a contract to the nearest existing target. Do not add another top-level
@@ -94,8 +109,10 @@ Use the focused contract form by default. Run the package-wide form only when a
 change crosses several runtime targets:
 
 ```bash
-cargo test --locked -p bitfun-agent-runtime --test <target> <module>::<test>
-cargo test --locked -p bitfun-agent-runtime
+cargo test --locked -p bitfun-agent-runtime --no-default-features --features agent-runtime,deep-research --lib --tests
+cargo test --locked -p bitfun-agent-runtime --no-default-features --features deep-research --test deep_research_contracts
+cargo test --locked -p bitfun-agent-runtime --no-default-features --features native-hook-settings --test native_hook_settings_contracts
+cargo test --locked -p bitfun-agent-runtime --no-default-features --features agent-runtime --test <target> <module>::<test>
 ```
 
 Run `pnpm run check:core-boundaries` only when Cargo dependencies, explicit test
diff --git a/src/crates/execution/agent-runtime/Cargo.toml b/src/crates/execution/agent-runtime/Cargo.toml
index cb06d24f71..dacf62db2e 100644
--- a/src/crates/execution/agent-runtime/Cargo.toml
+++ b/src/crates/execution/agent-runtime/Cargo.toml
@@ -10,54 +10,110 @@ autotests = false
 name = "bitfun_agent_runtime"
 crate-type = ["rlib"]
 
+[[example]]
+name = "sdk_minimal"
+path = "examples/sdk_minimal.rs"
+required-features = ["agent-runtime"]
+
 [features]
 default = []
+deep-research = ["dep:regex"]
+native-hook-settings = ["dep:regex", "dep:serde_json"]
+native-hook-runtime = [
+    "native-hook-settings",
+    "dep:log",
+    "dep:serde",
+    "dep:serde_json",
+    "dep:tokio",
+    "tokio/io-util",
+    "tokio/macros",
+    "tokio/process",
+    "tokio/rt",
+    "tokio/time",
+]
+agent-runtime = [
+    "native-hook-runtime",
+    "dep:async-trait",
+    "dep:bitfun-agent-stream",
+    "dep:bitfun-agent-tools",
+    "dep:bitfun-core-types",
+    "dep:bitfun-events",
+    "dep:bitfun-harness",
+    "dep:bitfun-runtime-ports",
+    "dep:bitfun-runtime-services",
+    "dep:dashmap",
+    "dep:hex",
+    "dep:log",
+    "dep:regex",
+    "dep:serde",
+    "dep:serde_json",
+    "dep:serde_yaml",
+    "dep:sha2",
+    "dep:thiserror",
+    "dep:tokio",
+    "dep:tokio-util",
+    "dep:uuid",
+    "tokio/macros",
+    "tokio/rt",
+    "tokio/sync",
+]
 
 [dependencies]
-async-trait = { workspace = true }
-bitfun-agent-stream = { path = "../agent-stream" }
-bitfun-agent-tools = { path = "../tool-contracts" }
-bitfun-core-types = { path = "../../contracts/core-types" }
-bitfun-events = { path = "../../contracts/events" }
-bitfun-harness = { path = "../harness" }
-bitfun-runtime-ports = { path = "../../contracts/runtime-ports", features = ["permission"] }
-bitfun-runtime-services = { path = "../runtime-services" }
-dashmap = { workspace = true }
-hex = { workspace = true }
-log = { workspace = true }
-regex = { workspace = true }
-serde = { workspace = true }
-serde_json = { workspace = true }
-serde_yaml = { workspace = true }
-sha2 = { workspace = true }
-thiserror = { workspace = true }
-uuid = { workspace = true }
-tokio = { workspace = true, features = ["io-util", "macros", "process", "rt", "sync", "time"] }
-tokio-util = { workspace = true }
-
-[dev-dependencies]
-bitfun-runtime-services = { path = "../runtime-services", features = ["test-support"] }
-tokio = { workspace = true, features = ["rt-multi-thread"] }
+async-trait = { workspace = true, optional = true }
+bitfun-agent-stream = { path = "../agent-stream", optional = true }
+bitfun-agent-tools = { path = "../tool-contracts", optional = true }
+bitfun-core-types = { path = "../../contracts/core-types", optional = true }
+bitfun-events = { path = "../../contracts/events", optional = true }
+bitfun-harness = { path = "../harness", optional = true }
+bitfun-runtime-ports = { path = "../../contracts/runtime-ports", optional = true, features = ["agent-api", "git-port", "permission", "plugin-runtime", "remote-workspace-ports", "runtime-event-port", "terminal-port", "workspace-ports"] }
+bitfun-runtime-services = { path = "../runtime-services", optional = true }
+dashmap = { workspace = true, optional = true }
+hex = { workspace = true, optional = true }
+log = { workspace = true, optional = true }
+regex = { workspace = true, optional = true }
+serde = { workspace = true, optional = true }
+serde_json = { workspace = true, optional = true }
+serde_yaml = { workspace = true, optional = true }
+sha2 = { workspace = true, optional = true }
+thiserror = { workspace = true, optional = true }
+uuid = { workspace = true, optional = true }
+tokio = { workspace = true, optional = true }
+tokio-util = { workspace = true, optional = true }
 
 [[test]]
 name = "agent_definition_contracts"
 path = "tests/agent_definition_contracts.rs"
+required-features = ["agent-runtime"]
 
 [[test]]
 name = "agent_session_contracts"
 path = "tests/agent_session_contracts.rs"
+required-features = ["agent-runtime"]
 
 [[test]]
 name = "agent_interaction_contracts"
 path = "tests/agent_interaction_contracts.rs"
+required-features = ["agent-runtime"]
 
 [[test]]
 name = "agent_long_horizon_contracts"
 path = "tests/agent_long_horizon_contracts.rs"
+required-features = ["agent-runtime"]
 
 [[test]]
 name = "native_hook_execution_contracts"
 path = "tests/native_hook_execution_contracts.rs"
+required-features = ["native-hook-runtime"]
+
+[[test]]
+name = "deep_research_contracts"
+path = "tests/deep_research_contracts.rs"
+required-features = ["deep-research"]
+
+[[test]]
+name = "native_hook_settings_contracts"
+path = "tests/native_hook_settings_contracts.rs"
+required-features = ["native-hook-settings"]
 
 [lints]
 workspace = true
diff --git a/src/crates/execution/agent-runtime/examples/sdk_minimal.rs b/src/crates/execution/agent-runtime/examples/sdk_minimal.rs
index 3005ac6d10..00a8d01ced 100644
--- a/src/crates/execution/agent-runtime/examples/sdk_minimal.rs
+++ b/src/crates/execution/agent-runtime/examples/sdk_minimal.rs
@@ -46,10 +46,10 @@ impl AgentSubmissionPort for ExampleAgentProvider {
     }
 }
 
-#[tokio::main]
+#[tokio::main(flavor = "current_thread")]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
     let compatibility = AgentRuntimeSdkCompatibility::current();
-    assert_eq!(compatibility.api_version, 5);
+    assert_eq!(compatibility.api_version, 6);
 
     let provider = Arc::new(ExampleAgentProvider::default());
     let events = AgentEventStream::new();
diff --git a/src/crates/execution/agent-runtime/src/event_queue.rs b/src/crates/execution/agent-runtime/src/event_queue.rs
index 53b5ca667b..b62aefe225 100644
--- a/src/crates/execution/agent-runtime/src/event_queue.rs
+++ b/src/crates/execution/agent-runtime/src/event_queue.rs
@@ -11,7 +11,7 @@ use std::sync::{
     atomic::{AtomicBool, Ordering},
     Arc, RwLock as StdRwLock, Weak,
 };
-use tokio::sync::{broadcast, Mutex, Notify};
+use tokio::sync::{broadcast, oneshot, Mutex, Notify};
 
 const MIN_EVENT_BROADCAST_BUFFER: usize = 1024;
 // Session-scoped protocol consumers can pause while servicing an RPC. Keep a
@@ -107,6 +107,100 @@ pub struct QueueStats {
     pub total_processed: u64,
 }
 
+/// Completion handle for an event that must enter the legacy dequeue stream
+/// before a producer may publish dependent events.
+pub struct LegacyDequeueAck {
+    receiver: oneshot::Receiver<()>,
+}
+
+impl LegacyDequeueAck {
+    pub async fn wait(self) -> EventBusResult<()> {
+        self.receiver
+            .await
+            .map_err(|_| crate::event_bus::EventBusError::subscriber("legacy dequeue fence closed"))
+    }
+}
+
+#[derive(Clone, Copy)]
+enum LegacyQueuePolicy {
+    BestEffort,
+    RequireImmediateAck,
+    AuthoritativeControl,
+}
+
+fn interrupted_control_identity(event: &AgenticEvent) -> Option<(&str, &str, u32)> {
+    match event {
+        AgenticEvent::DialogTurnInterrupted {
+            session_id,
+            turn_id,
+            execution_generation,
+            ..
+        }
+        | AgenticEvent::DialogTurnRecovered {
+            session_id,
+            turn_id,
+            execution_generation,
+        } => Some((session_id, turn_id, *execution_generation)),
+        _ => None,
+    }
+}
+
+fn authoritative_control_supersedes(authoritative: &AgenticEvent, pending: &AgenticEvent) -> bool {
+    let AgenticEvent::DialogTurnInterrupted {
+        session_id,
+        turn_id,
+        execution_generation,
+        ..
+    } = authoritative
+    else {
+        return false;
+    };
+    interrupted_control_identity(pending).is_some_and(
+        |(pending_session_id, pending_turn_id, pending_generation)| {
+            pending_session_id == session_id
+                && (pending_turn_id != turn_id || pending_generation <= *execution_generation)
+        },
+    )
+}
+
+fn authoritative_control_is_stale(authoritative: &AgenticEvent, pending: &AgenticEvent) -> bool {
+    let Some((session_id, turn_id, execution_generation)) =
+        interrupted_control_identity(authoritative)
+    else {
+        return false;
+    };
+    interrupted_control_identity(pending).is_some_and(
+        |(pending_session_id, pending_turn_id, pending_generation)| {
+            pending_session_id == session_id
+                && pending_turn_id == turn_id
+                && pending_generation > execution_generation
+        },
+    )
+}
+
+fn is_reclaimable_stream_data(authoritative: &AgenticEvent, pending: &AgenticEvent) -> bool {
+    let AgenticEvent::DialogTurnInterrupted {
+        session_id,
+        turn_id,
+        ..
+    } = authoritative
+    else {
+        return false;
+    };
+    matches!(
+        pending,
+        AgenticEvent::TextChunk {
+            session_id: pending_session_id,
+            turn_id: pending_turn_id,
+            ..
+        } | AgenticEvent::ThinkingChunk {
+            session_id: pending_session_id,
+            turn_id: pending_turn_id,
+            ..
+        } if pending_session_id == session_id && pending_turn_id == turn_id
+    )
+}
+
 /// Event queue
 ///
 /// Core functionality:
@@ -120,6 +214,10 @@ pub struct EventQueue {
     /// Notifier (used to wake up waiting consumers)
     notify: Arc<Notify>,
 
+    /// One-shot acknowledgements completed when a fenced event is removed
+    /// from the legacy priority queue into a concrete delivery batch.
+    legacy_dequeue_acks: Arc<Mutex<HashMap<String, oneshot::Sender<()>>>>,
+
     /// Broadcast stream for non-consuming subscribers.
     broadcast_tx: broadcast::Sender<EventEnvelope>,
 
@@ -148,6 +246,7 @@ impl EventQueue {
         Self {
             queue: Arc::new(Mutex::new(BinaryHeap::new())),
             notify: Arc::new(Notify::new()),
+            legacy_dequeue_acks: Arc::new(Mutex::new(HashMap::new())),
             broadcast_tx,
             session_broadcasts: Arc::new(StdRwLock::new(HashMap::new())),
             has_session_broadcasts: Arc::new(AtomicBool::new(false)),
@@ -162,22 +261,173 @@ impl EventQueue {
         event: AgenticEvent,
         priority: Option<EventPriority>,
     ) -> EventBusResult<String> {
+        self.enqueue_internal(event, priority, LegacyQueuePolicy::BestEffort)
+            .await
+            .map(|(event_id, _)| event_id)
+    }
+
+    /// Enqueue an ordering fence into the legacy dequeue stream.
+    ///
+    /// Unlike ordinary events, a fence fails closed when the legacy queue is
+    /// full. Awaiting the returned acknowledgement guarantees that the fence
+    /// is already part of the current delivery batch, so later higher-priority
+    /// events cannot overtake it in the priority heap.
+    pub async fn enqueue_with_legacy_dequeue_ack(
+        &self,
+        event: AgenticEvent,
+        priority: Option<EventPriority>,
+    ) -> EventBusResult<(String, LegacyDequeueAck)> {
+        let (event_id, ack) = self
+            .enqueue_internal(event, priority, LegacyQueuePolicy::RequireImmediateAck)
+            .await?;
+        Ok((
+            event_id,
+            ack.expect("legacy dequeue acknowledgement requested"),
+        ))
+    }
+
+    /// Enqueue an authoritative control event without allowing the bounded
+    /// best-effort data budget to discard or block it. The queue first
+    /// coalesces older session recovery controls and reclaims same-turn stream
+    /// chunks. A separate bounded reserve protects unrelated lifecycle events.
+    ///
+    /// Broadcast happens only after legacy storage succeeds, keeping the
+    /// Desktop WebView and non-consuming subscribers on the same lifecycle.
+    pub async fn enqueue_with_guaranteed_legacy_storage(
+        &self,
+        event: AgenticEvent,
+        priority: Option<EventPriority>,
+    ) -> EventBusResult<String> {
+        self.enqueue_internal(event, priority, LegacyQueuePolicy::AuthoritativeControl)
+            .await
+            .map(|(event_id, _)| event_id)
+    }
+
+    async fn enqueue_internal(
+        &self,
+        event: AgenticEvent,
+        priority: Option<EventPriority>,
+        legacy_policy: LegacyQueuePolicy,
+    ) -> EventBusResult<(String, Option<LegacyDequeueAck>)> {
         let priority = priority.unwrap_or_else(|| event.default_priority());
         let envelope = EventEnvelope::new(event, priority);
         let event_id = envelope.id.clone();
+        let require_legacy_ack = matches!(legacy_policy, LegacyQueuePolicy::RequireImmediateAck);
+        let (mut ack_sender, ack) = if require_legacy_ack {
+            let (sender, receiver) = oneshot::channel();
+            (Some(sender), Some(LegacyDequeueAck { receiver }))
+        } else {
+            (None, None)
+        };
 
         let (queue_len, queued) = {
             let mut queue = self.queue.lock().await;
-            if queue.len() >= self.config.max_queue_size {
-                warn!(
-                    "Event queue full, skipping legacy queue storage: event_id={}",
-                    event_id
-                );
-                (queue.len(), false)
+            if matches!(legacy_policy, LegacyQueuePolicy::AuthoritativeControl) {
+                if let Some(pending) = queue
+                    .iter()
+                    .map(|std::cmp::Reverse(pending)| pending)
+                    .find(|pending| authoritative_control_is_stale(&envelope.event, &pending.event))
+                {
+                    return Ok((pending.id.clone(), None));
+                }
+                let mut retained = BinaryHeap::with_capacity(queue.len());
+                let mut removed_ids = Vec::new();
+                while let Some(std::cmp::Reverse(pending)) = queue.pop() {
+                    if authoritative_control_supersedes(&envelope.event, &pending.event) {
+                        removed_ids.push(pending.id);
+                    } else {
+                        retained.push(std::cmp::Reverse(pending));
+                    }
+                }
+                *queue = retained;
+
+                if queue.len() >= self.config.max_queue_size {
+                    let reclaim_id = queue
+                        .iter()
+                        .map(|std::cmp::Reverse(pending)| pending)
+                        .filter(|pending| {
+                            is_reclaimable_stream_data(&envelope.event, &pending.event)
+                        })
+                        .max()
+                        .map(|pending| pending.id.clone());
+                    if let Some(reclaim_id) = reclaim_id {
+                        queue.retain(|std::cmp::Reverse(pending)| pending.id != reclaim_id);
+                        warn!(
+                            "Event queue full, reclaiming same-turn legacy stream data for authoritative control: event_id={}, reclaimed_event_id={}",
+                            event_id, reclaim_id
+                        );
+                        removed_ids.push(reclaim_id);
+                    }
+                }
+
+                let control_reserve = self.config.max_queue_size.max(1);
+                let mut pending_controls = queue
+                    .iter()
+                    .filter(|std::cmp::Reverse(pending)| {
+                        matches!(pending.event, AgenticEvent::DialogTurnInterrupted { .. })
+                    })
+                    .count();
+                while queue.len() >= self.config.max_queue_size
+                    && pending_controls >= control_reserve
+                {
+                    let oldest_control_id = queue
+                        .iter()
+                        .map(|std::cmp::Reverse(pending)| pending)
+                        .filter(|pending| {
+                            matches!(pending.event, AgenticEvent::DialogTurnInterrupted { .. })
+                        })
+                        .min_by_key(|pending| pending.timestamp)
+                        .map(|pending| pending.id.clone());
+                    let Some(oldest_control_id) = oldest_control_id else {
+                        break;
+                    };
+                    queue.retain(|std::cmp::Reverse(pending)| pending.id != oldest_control_id);
+                    removed_ids.push(oldest_control_id);
+                    pending_controls -= 1;
+                }
+
+                if !removed_ids.is_empty() {
+                    let mut acknowledgements = self.legacy_dequeue_acks.lock().await;
+                    for removed_id in removed_ids {
+                        acknowledgements.remove(&removed_id);
+                    }
+                }
+            }
+            let queued = if queue.len() >= self.config.max_queue_size {
+                match legacy_policy {
+                    LegacyQueuePolicy::RequireImmediateAck => {
+                        return Err(crate::event_bus::EventBusError::subscriber(
+                            "legacy event queue is full",
+                        ));
+                    }
+                    LegacyQueuePolicy::AuthoritativeControl => {
+                        warn!(
+                            "Event queue data capacity full, using bounded authoritative legacy control reserve: event_id={}, reserve_limit={}",
+                            event_id, self.config.max_queue_size.max(1)
+                        );
+                        true
+                    }
+                    LegacyQueuePolicy::BestEffort => {
+                        warn!(
+                            "Event queue full, skipping legacy queue storage: event_id={}",
+                            event_id
+                        );
+                        false
+                    }
+                }
             } else {
+                true
+            };
+            if queued {
+                if let Some(sender) = ack_sender.take() {
+                    self.legacy_dequeue_acks
+                        .lock()
+                        .await
+                        .insert(event_id.clone(), sender);
+                }
                 queue.push(std::cmp::Reverse(envelope.clone()));
-                (queue.len(), true)
             }
+            (queue.len(), queued)
         };
 
         // Broadcast delivery is authoritative for non-consuming runtime
@@ -216,7 +466,7 @@ impl EventQueue {
             priority
         );
 
-        Ok(event_id)
+        Ok((event_id, ack))
     }
 
     /// Dequeue batch of events
@@ -234,6 +484,15 @@ impl EventQueue {
         let remaining_queue_len = queue.len();
         drop(queue);
 
+        if !batch.is_empty() {
+            let mut acknowledgements = self.legacy_dequeue_acks.lock().await;
+            for envelope in &batch {
+                if let Some(sender) = acknowledgements.remove(&envelope.id) {
+                    let _ = sender.send(());
+                }
+            }
+        }
+
         if let Some((max_age_ms, event_id, priority)) = batch
             .iter()
             .filter_map(|envelope| {
@@ -335,20 +594,30 @@ impl EventQueue {
     /// Clear all events for a session
     pub async fn clear_session(&self, session_id: &str) -> EventBusResult<()> {
         // Remove all events for this session from the queue
-        let queue_len = {
+        let (queue_len, removed_ids) = {
             let mut queue = self.queue.lock().await;
             let mut new_queue = BinaryHeap::new();
+            let mut removed_ids = Vec::new();
 
             while let Some(std::cmp::Reverse(envelope)) = queue.pop() {
                 if envelope.event.session_id() != Some(session_id) {
                     new_queue.push(std::cmp::Reverse(envelope));
+                } else {
+                    removed_ids.push(envelope.id);
                 }
             }
 
             *queue = new_queue;
-            queue.len() // Get size before releasing queue lock
+            (queue.len(), removed_ids)
         };
 
+        if !removed_ids.is_empty() {
+            let mut acknowledgements = self.legacy_dequeue_acks.lock().await;
+            for removed_id in removed_ids {
+                acknowledgements.remove(&removed_id);
+            }
+        }
+
         // Update statistics: use the size obtained earlier
         {
             let mut stats = self.stats.lock().await;
@@ -391,9 +660,372 @@ impl StreamEventSink for EventQueue {
 #[cfg(test)]
 mod tests {
     use super::{EventQueue, EventQueueConfig};
-    use bitfun_events::AgenticEvent;
-    use std::sync::Arc;
-    use tokio::sync::Barrier;
+    use bitfun_events::{AgenticEvent, AgenticEventPriority};
+    use std::sync::{Arc, Barrier};
+    use std::time::Duration;
+
+    #[tokio::test]
+    async fn legacy_dequeue_ack_separates_later_high_priority_events() {
+        let queue = EventQueue::new(EventQueueConfig {
+            max_queue_size: 8,
+            batch_size: 8,
+        });
+        queue
+            .enqueue(
+                AgenticEvent::SessionStateChanged {
+                    session_id: "session".to_string(),
+                    new_state: "old-data".to_string(),
+                },
+                Some(AgenticEventPriority::Normal),
+            )
+            .await
+            .expect("old event should enqueue");
+        let (_, acknowledgement) = queue
+            .enqueue_with_legacy_dequeue_ack(
+                AgenticEvent::DialogTurnRecovered {
+                    session_id: "session".to_string(),
+                    turn_id: "turn".to_string(),
+                    execution_generation: 1,
+                },
+                Some(AgenticEventPriority::Normal),
+            )
+            .await
+            .expect("fence should enqueue");
+        let mut acknowledgement = Box::pin(acknowledgement.wait());
+        assert!(
+            tokio::time::timeout(Duration::from_millis(1), &mut acknowledgement)
+                .await
+                .is_err(),
+            "fence must not acknowledge before dequeue"
+        );
+
+        let batch = queue.dequeue_configured_batch().await;
+        acknowledgement
+            .await
+            .expect("fence should acknowledge its delivery batch");
+        assert_eq!(batch.len(), 2);
+        assert!(matches!(
+            &batch[0].event,
+            AgenticEvent::SessionStateChanged { new_state, .. } if new_state == "old-data"
+        ));
+        assert!(matches!(
+            &batch[1].event,
+            AgenticEvent::DialogTurnRecovered {
+                execution_generation: 1,
+                ..
+            }
+        ));
+
+        queue
+            .enqueue(
+                AgenticEvent::DialogTurnCancelled {
+                    session_id: "session".to_string(),
+                    turn_id: "turn".to_string(),
+                },
+                Some(AgenticEventPriority::Critical),
+            )
+            .await
+            .expect("later event should enqueue");
+        let next_batch = queue.dequeue_configured_batch().await;
+        assert!(matches!(
+            &next_batch[0].event,
+            AgenticEvent::DialogTurnCancelled { .. }
+        ));
+    }
+
+    #[tokio::test]
+    async fn legacy_dequeue_fence_fails_before_broadcast_when_queue_is_full() {
+        let queue = EventQueue::new(EventQueueConfig {
+            max_queue_size: 1,
+            batch_size: 1,
+        });
+        let mut events = queue.subscribe();
+        queue
+            .enqueue(
+                AgenticEvent::TextChunk {
+                    session_id: "session".to_string(),
+                    turn_id: "turn".to_string(),
+                    round_id: "round".to_string(),
+                    attempt_id: None,
+                    attempt_index: None,
+                    text: "occupied".to_string(),
+                },
+                None,
+            )
+            .await
+            .expect("first event should enqueue");
+        events.recv().await.expect("first broadcast should arrive");
+
+        let result = queue
+            .enqueue_with_legacy_dequeue_ack(
+                AgenticEvent::DialogTurnRecovered {
+                    session_id: "session".to_string(),
+                    turn_id: "turn".to_string(),
+                    execution_generation: 1,
+                },
+                Some(AgenticEventPriority::Normal),
+            )
+            .await;
+
+        assert!(result.is_err());
+        assert!(
+            tokio::time::timeout(Duration::from_millis(1), events.recv())
+                .await
+                .is_err(),
+            "a rejected fence must not be broadcast as recovered"
+        );
+    }
+
+    #[tokio::test]
+    async fn authoritative_legacy_control_bypasses_data_capacity_without_losing_delivery() {
+        let queue = EventQueue::new(EventQueueConfig {
+            max_queue_size: 1,
+            batch_size: 1,
+        });
+        let mut events = queue.subscribe();
+        queue
+            .enqueue(
+                AgenticEvent::TextChunk {
+                    session_id: "session".to_string(),
+                    turn_id: "turn".to_string(),
+                    round_id: "round".to_string(),
+                    attempt_id: None,
+                    attempt_index: None,
+                    text: "occupied".to_string(),
+                },
+                None,
+            )
+            .await
+            .expect("first event should enqueue");
+        events.recv().await.expect("first broadcast should arrive");
+
+        tokio::time::timeout(
+            Duration::from_millis(10),
+            queue.enqueue_with_guaranteed_legacy_storage(
+                AgenticEvent::DialogTurnInterrupted {
+                    session_id: "session".to_string(),
+                    turn_id: "turn".to_string(),
+                    execution_generation: 1,
+                    model_id: Some("model".to_string()),
+                },
+                Some(AgenticEventPriority::Critical),
+            ),
+        )
+        .await
+        .expect("authoritative control event must not wait for data capacity")
+        .expect("authoritative control event should enqueue");
+        assert_eq!(
+            queue.len().await,
+            1,
+            "authoritative control should reclaim lower-priority data capacity"
+        );
+        assert!(matches!(
+            events
+                .recv()
+                .await
+                .expect("authoritative broadcast should arrive")
+                .event,
+            AgenticEvent::DialogTurnInterrupted { .. }
+        ));
+
+        queue
+            .enqueue_with_guaranteed_legacy_storage(
+                AgenticEvent::DialogTurnInterrupted {
+                    session_id: "session".to_string(),
+                    turn_id: "turn".to_string(),
+                    execution_generation: 2,
+                    model_id: Some("model".to_string()),
+                },
+                Some(AgenticEventPriority::Critical),
+            )
+            .await
+            .expect("newer authoritative control event should enqueue");
+        events
+            .recv()
+            .await
+            .expect("newer authoritative broadcast should arrive");
+        assert_eq!(
+            queue.len().await,
+            1,
+            "a newer generation must replace the queued control event for the same turn"
+        );
+
+        queue
+            .enqueue_with_guaranteed_legacy_storage(
+                AgenticEvent::DialogTurnInterrupted {
+                    session_id: "session".to_string(),
+                    turn_id: "turn".to_string(),
+                    execution_generation: 1,
+                    model_id: Some("model".to_string()),
+                },
+                Some(AgenticEventPriority::Critical),
+            )
+            .await
+            .expect("stale authoritative control should be ignored idempotently");
+        assert_eq!(queue.len().await, 1);
+        assert!(
+            tokio::time::timeout(Duration::from_millis(1), events.recv())
+                .await
+                .is_err(),
+            "a stale generation must not be broadcast"
+        );
+
+        let delivered = queue.dequeue_configured_batch().await;
+        assert!(matches!(
+            &delivered[0].event,
+            AgenticEvent::DialogTurnInterrupted {
+                execution_generation: 2,
+                ..
+            }
+        ));
+        assert!(queue.dequeue_configured_batch().await.is_empty());
+    }
+
+    #[tokio::test]
+    async fn authoritative_control_preserves_unrelated_lifecycle_events() {
+        let queue = EventQueue::new(EventQueueConfig {
+            max_queue_size: 1,
+            batch_size: 1,
+        });
+        queue
+            .enqueue(
+                AgenticEvent::SessionStateChanged {
+                    session_id: "other-session".to_string(),
+                    new_state: "idle".to_string(),
+                },
+                None,
+            )
+            .await
+            .expect("lifecycle event should enqueue");
+        queue
+            .enqueue_with_guaranteed_legacy_storage(
+                AgenticEvent::DialogTurnInterrupted {
+                    session_id: "session".to_string(),
+                    turn_id: "turn".to_string(),
+                    execution_generation: 1,
+                    model_id: Some("model".to_string()),
+                },
+                Some(AgenticEventPriority::Critical),
+            )
+            .await
+            .expect("authoritative control should use its reserve");
+
+        assert_eq!(queue.len().await, 2);
+        assert!(matches!(
+            queue.dequeue_configured_batch().await[0].event,
+            AgenticEvent::DialogTurnInterrupted { .. }
+        ));
+        assert!(matches!(
+            queue.dequeue_configured_batch().await[0].event,
+            AgenticEvent::SessionStateChanged { .. }
+        ));
+    }
+
+    #[tokio::test]
+    async fn authoritative_control_reserve_is_bounded_across_distinct_turns() {
+        let queue = EventQueue::new(EventQueueConfig {
+            max_queue_size: 1,
+            batch_size: 1,
+        });
+        for index in 0..3 {
+            queue
+                .enqueue_with_guaranteed_legacy_storage(
+                    AgenticEvent::DialogTurnInterrupted {
+                        session_id: format!("session-{index}"),
+                        turn_id: format!("turn-{index}"),
+                        execution_generation: 1,
+                        model_id: Some("model".to_string()),
+                    },
+                    Some(AgenticEventPriority::Critical),
+                )
+                .await
+                .expect("authoritative control should remain bounded");
+            assert_eq!(queue.len().await, 1);
+        }
+
+        let delivered = queue.dequeue_configured_batch().await;
+        assert!(matches!(
+            &delivered[0].event,
+            AgenticEvent::DialogTurnInterrupted {
+                session_id,
+                turn_id,
+                ..
+            } if session_id == "session-2" && turn_id == "turn-2"
+        ));
+    }
+
+    #[tokio::test]
+    async fn authoritative_interruption_replaces_the_same_turn_recovery_fence() {
+        let queue = EventQueue::new(EventQueueConfig {
+            max_queue_size: 1,
+            batch_size: 1,
+        });
+        let (_, recovery_ack) = queue
+            .enqueue_with_legacy_dequeue_ack(
+                AgenticEvent::DialogTurnRecovered {
+                    session_id: "session".to_string(),
+                    turn_id: "turn".to_string(),
+                    execution_generation: 1,
+                },
+                Some(AgenticEventPriority::Normal),
+            )
+            .await
+            .expect("recovery fence should enqueue");
+
+        queue
+            .enqueue_with_guaranteed_legacy_storage(
+                AgenticEvent::DialogTurnInterrupted {
+                    session_id: "session".to_string(),
+                    turn_id: "turn".to_string(),
+                    execution_generation: 1,
+                    model_id: Some("model".to_string()),
+                },
+                Some(AgenticEventPriority::Critical),
+            )
+            .await
+            .expect("authoritative interruption should replace its recovery fence");
+
+        assert_eq!(queue.len().await, 1);
+        tokio::time::timeout(Duration::from_millis(10), recovery_ack.wait())
+            .await
+            .expect("superseded fence acknowledgement should close promptly")
+            .expect_err("a superseded fence must not acknowledge delivery");
+        let delivered = queue.dequeue_configured_batch().await;
+        assert!(matches!(
+            &delivered[0].event,
+            AgenticEvent::DialogTurnInterrupted { .. }
+        ));
+    }
+
+    #[tokio::test]
+    async fn clearing_a_session_closes_its_pending_recovery_fence() {
+        let queue = EventQueue::new(EventQueueConfig {
+            max_queue_size: 1,
+            batch_size: 1,
+        });
+        let (_, recovery_ack) = queue
+            .enqueue_with_legacy_dequeue_ack(
+                AgenticEvent::DialogTurnRecovered {
+                    session_id: "session".to_string(),
+                    turn_id: "turn".to_string(),
+                    execution_generation: 1,
+                },
+                Some(AgenticEventPriority::Normal),
+            )
+            .await
+            .expect("recovery fence should enqueue");
+
+        queue
+            .clear_session("session")
+            .await
+            .expect("session events should clear");
+
+        assert!(queue.is_empty().await);
+        tokio::time::timeout(Duration::from_millis(10), recovery_ack.wait())
+            .await
+            .expect("cleared fence acknowledgement should close promptly")
+            .expect_err("a cleared fence must not acknowledge delivery");
+    }
 
     #[tokio::test]
     async fn full_legacy_queue_does_not_drop_broadcast_delivery() {
@@ -466,43 +1098,55 @@ mod tests {
         }
     }
 
-    #[tokio::test(flavor = "multi_thread", worker_threads = 4)]
-    async fn concurrent_publishers_have_one_order_for_all_subscribers() {
+    #[test]
+    fn concurrent_publishers_have_one_order_for_all_subscribers() {
         const EVENT_COUNT: usize = 64;
         let queue = Arc::new(EventQueue::new(EventQueueConfig::default()));
         let mut first = queue.subscribe();
         let mut second = queue.subscribe();
         let barrier = Arc::new(Barrier::new(EVENT_COUNT));
-        let mut tasks = Vec::with_capacity(EVENT_COUNT);
+        let mut publishers = Vec::with_capacity(EVENT_COUNT);
 
         for index in 0..EVENT_COUNT {
             let queue = queue.clone();
             let barrier = barrier.clone();
-            tasks.push(tokio::spawn(async move {
-                barrier.wait().await;
-                queue
-                    .enqueue(
-                        AgenticEvent::SessionStateChanged {
-                            session_id: format!("event-{index}"),
-                            new_state: "idle".to_string(),
-                        },
-                        None,
-                    )
-                    .await
-                    .expect("event should enqueue")
+            publishers.push(std::thread::spawn(move || {
+                barrier.wait();
+                tokio::runtime::Builder::new_current_thread()
+                    .enable_all()
+                    .build()
+                    .expect("publisher runtime")
+                    .block_on(async move {
+                        queue
+                            .enqueue(
+                                AgenticEvent::SessionStateChanged {
+                                    session_id: format!("event-{index}"),
+                                    new_state: "idle".to_string(),
+                                },
+                                None,
+                            )
+                            .await
+                            .expect("event should enqueue")
+                    })
             }));
         }
-        for task in tasks {
-            task.await.expect("publisher should complete");
+        for publisher in publishers {
+            publisher.join().expect("publisher should complete");
         }
 
-        let mut first_ids = Vec::with_capacity(EVENT_COUNT);
-        let mut second_ids = Vec::with_capacity(EVENT_COUNT);
-        for _ in 0..EVENT_COUNT {
-            first_ids.push(first.recv().await.expect("first broadcast").id);
-            second_ids.push(second.recv().await.expect("second broadcast").id);
-        }
-        assert_eq!(first_ids, second_ids);
+        tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .expect("subscriber runtime")
+            .block_on(async move {
+                let mut first_ids = Vec::with_capacity(EVENT_COUNT);
+                let mut second_ids = Vec::with_capacity(EVENT_COUNT);
+                for _ in 0..EVENT_COUNT {
+                    first_ids.push(first.recv().await.expect("first broadcast").id);
+                    second_ids.push(second.recv().await.expect("second broadcast").id);
+                }
+                assert_eq!(first_ids, second_ids);
+            });
     }
 
     #[test]
diff --git a/src/crates/execution/agent-runtime/src/events.rs b/src/crates/execution/agent-runtime/src/events.rs
index 0f08823e14..f9379066eb 100644
--- a/src/crates/execution/agent-runtime/src/events.rs
+++ b/src/crates/execution/agent-runtime/src/events.rs
@@ -47,6 +47,7 @@ pub const fn turn_outcome_status_kind(status: TurnOutcomeStatus) -> DialogTurnOu
     match status {
         TurnOutcomeStatus::Completed => DialogTurnOutcomeKind::Completed,
         TurnOutcomeStatus::Cancelled => DialogTurnOutcomeKind::Cancelled,
+        TurnOutcomeStatus::Interrupted => DialogTurnOutcomeKind::Interrupted,
         TurnOutcomeStatus::Failed => DialogTurnOutcomeKind::Failed,
     }
 }
diff --git a/src/crates/execution/agent-runtime/src/lib.rs b/src/crates/execution/agent-runtime/src/lib.rs
index 7c4b2e6b62..6685e7657d 100644
--- a/src/crates/execution/agent-runtime/src/lib.rs
+++ b/src/crates/execution/agent-runtime/src/lib.rs
@@ -3,42 +3,81 @@
 //! This crate owns runtime decisions that can be built and tested without
 //! depending on `bitfun-core` concrete session or scheduler lifecycle.
 
+#[cfg(feature = "agent-runtime")]
 pub mod agents;
+#[cfg(feature = "agent-runtime")]
 pub mod checkpoint;
+#[cfg(feature = "agent-runtime")]
 pub mod context_profile;
+#[cfg(feature = "agent-runtime")]
 pub mod custom_agent;
+#[cfg(feature = "agent-runtime")]
 pub mod custom_subagent;
+#[cfg(feature = "deep-research")]
 pub mod deep_research;
+#[cfg(feature = "agent-runtime")]
 pub mod deep_review;
+#[cfg(feature = "agent-runtime")]
 pub mod dialog_turn;
+#[cfg(feature = "agent-runtime")]
 pub mod event_bus;
+#[cfg(feature = "agent-runtime")]
 pub mod event_queue;
+#[cfg(feature = "agent-runtime")]
 pub mod event_router;
+#[cfg(feature = "agent-runtime")]
 pub mod event_source;
+#[cfg(feature = "agent-runtime")]
 pub mod events;
+#[cfg(feature = "agent-runtime")]
 pub mod evidence_ledger;
+#[cfg(feature = "agent-runtime")]
 pub mod file_read_state;
+#[cfg(feature = "native-hook-settings")]
 pub mod native_hooks;
+#[cfg(feature = "agent-runtime")]
 pub mod output_surface;
+#[cfg(feature = "agent-runtime")]
 pub mod permission;
+#[cfg(feature = "agent-runtime")]
 pub mod post_call_hooks;
+#[cfg(feature = "agent-runtime")]
 pub mod prompt;
+#[cfg(feature = "agent-runtime")]
 pub mod prompt_cache;
+#[cfg(feature = "agent-runtime")]
 pub mod prompt_markup;
+#[cfg(feature = "agent-runtime")]
 pub mod remote_file_delivery;
+#[cfg(feature = "agent-runtime")]
 pub mod runtime;
+#[cfg(feature = "agent-runtime")]
 pub mod scheduled_job;
+#[cfg(feature = "agent-runtime")]
 pub mod scheduler;
+#[cfg(feature = "agent-runtime")]
 pub mod sdk;
+#[cfg(feature = "agent-runtime")]
 pub mod session;
+#[cfg(feature = "agent-runtime")]
 pub mod session_control;
+#[cfg(feature = "agent-runtime")]
 pub mod session_state;
+#[cfg(feature = "agent-runtime")]
 pub mod session_state_manager;
+#[cfg(feature = "agent-runtime")]
 pub mod side_question;
+#[cfg(feature = "agent-runtime")]
 pub mod skill_agent_snapshot;
+#[cfg(feature = "agent-runtime")]
 pub mod skills;
+#[cfg(feature = "agent-runtime")]
 pub mod subagent_task;
+#[cfg(feature = "agent-runtime")]
 pub mod thread_goal;
+#[cfg(feature = "agent-runtime")]
 pub mod thread_goal_tools;
+#[cfg(feature = "agent-runtime")]
 pub mod turn_cancellation;
+#[cfg(feature = "agent-runtime")]
 pub mod user_questions;
diff --git a/src/crates/execution/agent-runtime/src/native_hooks/mod.rs b/src/crates/execution/agent-runtime/src/native_hooks/mod.rs
index e20a8e39c3..c3f0a2cc70 100644
--- a/src/crates/execution/agent-runtime/src/native_hooks/mod.rs
+++ b/src/crates/execution/agent-runtime/src/native_hooks/mod.rs
@@ -16,13 +16,19 @@
 //! - the external hook catalog (`bitfun-product-domains`): read-only
 //!   inspection of other AI applications' hook configuration.
 
+#[cfg(feature = "native-hook-runtime")]
 mod engine;
+#[cfg(feature = "native-hook-runtime")]
 mod output;
+#[cfg(feature = "native-hook-runtime")]
 mod payload;
 mod settings;
 
+#[cfg(feature = "native-hook-runtime")]
 pub use engine::{AgentHookEngine, MAX_HOOK_MODEL_OUTPUT_BYTES};
+#[cfg(feature = "native-hook-runtime")]
 pub use output::{AgentHookOutcome, AgentHookPermissionOutcome};
+#[cfg(feature = "native-hook-runtime")]
 pub use payload::{
     AgentHookEventPayload, AgentHookPayload, AgentHookPayloadCommon, AgentHookPermissionMode,
 };
diff --git a/src/crates/execution/agent-runtime/src/prompt.rs b/src/crates/execution/agent-runtime/src/prompt.rs
index a576206bcc..d2f4a6939b 100644
--- a/src/crates/execution/agent-runtime/src/prompt.rs
+++ b/src/crates/execution/agent-runtime/src/prompt.rs
@@ -493,7 +493,16 @@ fn computer_use_text_only_model_guidance() -> Vec<String> {
     vec![
         "- The configured primary model does not accept image inputs.".to_string(),
         "- When using `ComputerUse` or `ControlHub` with `domain: \"browser\"`, do not use `screenshot` and avoid `domain:\"browser\" action:\"screenshot\"`; image bytes will be unreadable.".to_string(),
+        // Banning `screenshot` without naming the replacement is what pushes a
+        // text-only agent into improvising `screencapture` + `analyze_image` as
+        // a substitute for eyes — a loop that costs an extra model call per
+        // look, returns prose instead of coordinates, and misreads the screen
+        // often enough to send the run down false paths.
+        "- `describe_screen` is your eyes: it returns the frontmost app, the AX tree (`ax_tree_text`, with `node_idx`s you can click by), `ui_tree_text` and the pointer, as text with no image. Call it when UI state is unknown, and again after an action to confirm `ax_state_digest` changed.".to_string(),
+        "- Do NOT shell out to `screencapture` and feed the file to an image-analysis tool as a substitute for looking. It costs an extra model round-trip per glance and returns descriptions, not clickable coordinates. Use `describe_screen`, `get_app_state`, `locate` and `move_to_text` — they return exact targets.".to_string(),
+        "- If `ax_tree_text` is empty, read `ax_tree_status` / `ax_tree_note` in the same result: they say why (no frontmost app, an app with no window, a WebView that exposes no tree, or a permission failure) and which tactic to switch to. The result is never truncated — re-calling returns the same thing.".to_string(),
         "- Action priority: 1) Terminal/CLI/system commands (`ExecCommand`, or `ComputerUse` `run_script`; use `WriteStdin`/`ExecControl` for running ExecCommand sessions) 2) Keyboard shortcuts (`key_chord`, `type_text`) 3) UI control: `click_element` (AX) -> `locate` -> `move_to_text` (use `move_to_text_match_index` when multiple OCR hits are listed) -> `mouse_move` (`use_screen_coordinates: true` with coordinates from tool JSON) -> `click`. For browser work, prefer `snapshot` then click by `@e*` ref over screenshots.".to_string(),
+        "- To type and send in one step use `paste` with `submit: true` (and `submit_keys` when the app sends on a chord, e.g. `[\"command\",\"return\"]`). `paste` is also the reliable path for CJK and emoji.".to_string(),
         "- Never guess coordinates. Always use precise methods: AX, OCR, system coordinates from tool results, or browser snapshot refs.".to_string(),
     ]
 }
diff --git a/src/crates/execution/agent-runtime/src/runtime.rs b/src/crates/execution/agent-runtime/src/runtime.rs
index 18419c1e01..f87d877757 100644
--- a/src/crates/execution/agent-runtime/src/runtime.rs
+++ b/src/crates/execution/agent-runtime/src/runtime.rs
@@ -11,8 +11,9 @@ use bitfun_agent_tools::{ToolRegistry, ToolRegistryItem};
 use bitfun_harness::HarnessRegistry;
 use bitfun_runtime_ports::{
     AgentBackgroundResultRequest, AgentDialogSteerRequest, AgentDialogTurnPort,
-    AgentDialogTurnRequest, AgentInputAttachment, AgentInteractionResponsePort,
-    AgentLifecycleDeliveryPort, AgentLocalCommandTurnPort, AgentLocalCommandTurnRecordRequest,
+    AgentDialogTurnRecoveryOutcome, AgentDialogTurnRecoveryRequest, AgentDialogTurnRequest,
+    AgentInputAttachment, AgentInteractionResponsePort, AgentLifecycleDeliveryPort,
+    AgentLocalCommandTurnPort, AgentLocalCommandTurnRecordRequest,
     AgentLocalCommandTurnRecordResult, AgentMessageWorkspaceReferencesRequest,
     AgentSessionArchiveRequest, AgentSessionArchiveStateRequest, AgentSessionClosePort,
     AgentSessionCompactionPort, AgentSessionCompactionRequest, AgentSessionCompactionResult,
@@ -24,20 +25,21 @@ use bitfun_runtime_ports::{
     AgentSessionManagementPort, AgentSessionModePort, AgentSessionModeUpdateRequest,
     AgentSessionModelPort, AgentSessionModelSelectionUpdateRequest, AgentSessionModelUpdateRequest,
     AgentSessionRenameRequest, AgentSessionRevertPort, AgentSessionRevertRequest,
-    AgentSessionRevertResult, AgentSessionSummary, AgentSessionUsagePort, AgentSessionUsageRequest,
+    AgentSessionRevertResult, AgentSessionRollbackToTurnOutcome, AgentSessionRollbackToTurnRequest,
+    AgentSessionSummary, AgentSessionUsagePort, AgentSessionUsageRequest,
     AgentSessionWorkspaceBinding, AgentSessionWorkspaceRequest, AgentSubmissionPort,
     AgentSubmissionRequest, AgentSubmissionResult, AgentSubmissionSource,
     AgentThreadGoalCreateRequest, AgentThreadGoalDeliveryRequest, AgentThreadGoalGetRequest,
     AgentThreadGoalManagementPort, AgentThreadGoalUpdateStatusRequest,
     AgentTransientSessionDiscardRequest, AgentTurnCancellationPort, AgentTurnCancellationRequest,
-    AgentTurnCancellationResult, AgentTurnSettlementPort, AgentTurnSettlementRequest,
-    AgentUserAnswersRequest, AgentUserShellCommandPort, AgentUserShellCommandRequest,
-    AgentUserShellCommandResult, AgentWorkspaceReference, AgentWorkspaceReferencePort,
-    AgentWorkspaceReferenceSearchRequest, AgentWorkspaceReferenceSearchResult, DialogSteerOutcome,
-    DialogSubmitOutcome, PermissionAuditRecord, PermissionGrant, PermissionGrantKey,
-    PluginRuntimeBinding, PortError, PortErrorKind, PortResult, RuntimeEventEnvelope,
-    SessionTranscript, SessionTranscriptReader, SessionTranscriptRequest, ThreadGoal,
-    WorkspaceDiffSnapshot,
+    AgentTurnCancellationResult, AgentTurnInterruptionRequest, AgentTurnInterruptionResult,
+    AgentTurnSettlementPort, AgentTurnSettlementRequest, AgentUserAnswersRequest,
+    AgentUserShellCommandPort, AgentUserShellCommandRequest, AgentUserShellCommandResult,
+    AgentWorkspaceReference, AgentWorkspaceReferencePort, AgentWorkspaceReferenceSearchRequest,
+    AgentWorkspaceReferenceSearchResult, DialogSteerOutcome, DialogSubmitOutcome,
+    PermissionAuditRecord, PermissionGrant, PermissionGrantKey, PluginRuntimeBinding, PortError,
+    PortErrorKind, PortResult, RuntimeEventEnvelope, SessionTranscript, SessionTranscriptReader,
+    SessionTranscriptRequest, ThreadGoal, WorkspaceDiffSnapshot,
 };
 use bitfun_runtime_services::RuntimeServices;
 
@@ -1247,6 +1249,21 @@ impl AgentRuntime {
         port.redo_session(request).await.map_err(RuntimeError::from)
     }
 
+    pub async fn rollback_session_to_turn(
+        &self,
+        request: AgentSessionRollbackToTurnRequest,
+    ) -> Result<AgentSessionRollbackToTurnOutcome, RuntimeError> {
+        let port = self.session_revert.as_ref().ok_or_else(|| {
+            RuntimeError::Port(PortError::new(
+                PortErrorKind::NotAvailable,
+                "agent session revert port is not registered",
+            ))
+        })?;
+        port.rollback_session_to_turn(request)
+            .await
+            .map_err(RuntimeError::from)
+    }
+
     pub async fn fork_session(
         &self,
         request: AgentSessionForkRequest,
@@ -1486,6 +1503,33 @@ impl AgentRuntime {
         Ok(outcome)
     }
 
+    pub async fn recover_interrupted_turn(
+        &self,
+        request: AgentDialogTurnRecoveryRequest,
+    ) -> Result<AgentDialogTurnRecoveryOutcome, RuntimeError> {
+        let requested_session_id = request.session_id.clone();
+        let requested_turn_id = request.turn_id.clone();
+        let dialog_turn = self
+            .dialog_turn
+            .as_ref()
+            .ok_or(RuntimeError::MissingDialogTurnPort)?;
+        let outcome = dialog_turn
+            .recover_interrupted_turn(request)
+            .await
+            .map_err(RuntimeError::from)?;
+        if outcome.session_id != requested_session_id || outcome.turn_id != requested_turn_id {
+            return Err(PortError::new(
+                PortErrorKind::Backend,
+                format!(
+                    "agent dialog recovery provider returned session_id '{}' and turn_id '{}' for requested session_id '{}' and turn_id '{}'",
+                    outcome.session_id, outcome.turn_id, requested_session_id, requested_turn_id
+                ),
+            )
+            .into());
+        }
+        Ok(outcome)
+    }
+
     pub async fn deliver_background_result(
         &self,
         request: AgentBackgroundResultRequest,
@@ -1580,6 +1624,20 @@ impl AgentRuntime {
             .map_err(RuntimeError::from)
     }
 
+    pub async fn interrupt_turn(
+        &self,
+        request: AgentTurnInterruptionRequest,
+    ) -> Result<AgentTurnInterruptionResult, RuntimeError> {
+        let cancellation = self
+            .cancellation
+            .as_ref()
+            .ok_or(RuntimeError::MissingCancellationPort)?;
+        cancellation
+            .interrupt_turn(request)
+            .await
+            .map_err(RuntimeError::from)
+    }
+
     /// Cancels one inspected descendant through the authoritative lineage
     /// owner, which keeps workspace binding and membership validation adjacent
     /// to the existing cancellation execution owner.
@@ -1686,11 +1744,54 @@ mod tests {
         ClockPort, DialogQueuePriority, DialogSubmissionPolicy, DialogSubmitOutcome,
         FileSystemPort, PluginDispatchEnvelope, PluginResponseEnvelope, PluginRuntimeAvailability,
         PluginRuntimeClient, PluginRuntimeUnavailableReason, PortErrorKind, PortResult,
-        RuntimeEventSink, RuntimeEventType, RuntimeServiceCapability, SessionStorePort,
-        SessionTranscript, SessionTranscriptReader, SessionTranscriptRequest, ThreadGoal,
-        ThreadGoalStatus, TranscriptContent, TranscriptMessage, WorkspacePort,
+        RuntimeEventSink, RuntimeEventType, RuntimeServiceCapability, RuntimeServicePort,
+        SessionStorageKind, SessionStoragePathRequest, SessionStoragePathResolution,
+        SessionStorePort, SessionTranscript, SessionTranscriptReader, SessionTranscriptRequest,
+        ThreadGoal, ThreadGoalStatus, TranscriptContent, TranscriptMessage, WorkspacePort,
     };
-    use bitfun_runtime_services::{test_support::FakeRuntimePort, RuntimeServicesBuilder};
+    use bitfun_runtime_services::RuntimeServicesBuilder;
+
+    #[derive(Debug)]
+    struct TestRuntimePort {
+        capability: RuntimeServiceCapability,
+    }
+
+    impl TestRuntimePort {
+        fn new(capability: RuntimeServiceCapability) -> Self {
+            Self { capability }
+        }
+    }
+
+    impl RuntimeServicePort for TestRuntimePort {
+        fn capability(&self) -> RuntimeServiceCapability {
+            self.capability
+        }
+    }
+
+    impl FileSystemPort for TestRuntimePort {}
+    impl WorkspacePort for TestRuntimePort {}
+
+    #[async_trait::async_trait]
+    impl SessionStorePort for TestRuntimePort {
+        async fn resolve_session_storage_path(
+            &self,
+            request: SessionStoragePathRequest,
+        ) -> PortResult<SessionStoragePathResolution> {
+            Ok(SessionStoragePathResolution::new(
+                request.workspace_path.clone(),
+                request.workspace_path,
+                SessionStorageKind::Local,
+                request.remote_connection_id,
+                request.remote_ssh_host,
+            ))
+        }
+    }
+
+    impl ClockPort for TestRuntimePort {
+        fn now_unix_millis(&self) -> i64 {
+            0
+        }
+    }
 
     #[derive(Debug, Default)]
     struct FakeAgentRuntimePorts {
@@ -1698,6 +1799,7 @@ mod tests {
         exact_session_result_id: Mutex<Option<String>>,
         submitted_messages: Mutex<Vec<AgentSubmissionRequest>>,
         cancelled_turns: Mutex<Vec<AgentTurnCancellationRequest>>,
+        interrupted_turns: Mutex<Vec<AgentTurnInterruptionRequest>>,
         compaction_requests: Mutex<Vec<AgentSessionCompactionRequest>>,
         before_turn_fork_requests: Mutex<Vec<AgentSessionForkBeforeTurnRequest>>,
         listed_sessions: Mutex<Vec<AgentSessionListRequest>>,
@@ -1918,6 +2020,11 @@ mod tests {
                 retired_turn_ids: Vec::new(),
                 changed: true,
                 hidden_turn_count: 1,
+                boundary_storage_turn_index: None,
+                target_turn_id: None,
+                restored_files: Vec::new(),
+                reload_required: false,
+                reload_reason: None,
             })
         }
 
@@ -2219,6 +2326,18 @@ mod tests {
                 requested: true,
             })
         }
+
+        async fn interrupt_turn(
+            &self,
+            request: AgentTurnInterruptionRequest,
+        ) -> PortResult<AgentTurnInterruptionResult> {
+            self.interrupted_turns.lock().unwrap().push(request.clone());
+            Ok(AgentTurnInterruptionResult {
+                session_id: request.session_id,
+                turn_id: request.turn_id,
+                requested: true,
+            })
+        }
     }
 
     #[derive(Debug, Default)]
@@ -2242,13 +2361,13 @@ mod tests {
 
     fn runtime_services_with_events(events: Arc<dyn RuntimeEventSink>) -> RuntimeServices {
         let filesystem: Arc<dyn FileSystemPort> =
-            Arc::new(FakeRuntimePort::new(RuntimeServiceCapability::FileSystem));
+            Arc::new(TestRuntimePort::new(RuntimeServiceCapability::FileSystem));
         let workspace: Arc<dyn WorkspacePort> =
-            Arc::new(FakeRuntimePort::new(RuntimeServiceCapability::Workspace));
+            Arc::new(TestRuntimePort::new(RuntimeServiceCapability::Workspace));
         let session_store: Arc<dyn SessionStorePort> =
-            Arc::new(FakeRuntimePort::new(RuntimeServiceCapability::SessionStore));
+            Arc::new(TestRuntimePort::new(RuntimeServiceCapability::SessionStore));
         let clock: Arc<dyn ClockPort> =
-            Arc::new(FakeRuntimePort::new(RuntimeServiceCapability::Clock));
+            Arc::new(TestRuntimePort::new(RuntimeServiceCapability::Clock));
 
         RuntimeServicesBuilder::new()
             .with_filesystem(filesystem)
@@ -2634,6 +2753,30 @@ mod tests {
         );
     }
 
+    #[tokio::test]
+    async fn interrupt_turn_delegates_to_cancellation_owner() {
+        let ports = Arc::new(FakeAgentRuntimePorts::default());
+        let runtime = AgentRuntimeBuilder::new()
+            .with_submission_port(ports.clone())
+            .with_cancellation_port(ports.clone())
+            .build()
+            .expect("runtime");
+
+        let result = runtime
+            .interrupt_turn(AgentTurnInterruptionRequest {
+                session_id: "session_1".to_string(),
+                turn_id: "turn_1".to_string(),
+                source: Some(AgentSubmissionSource::DesktopUi),
+                wait_timeout_ms: Some(30_000),
+            })
+            .await
+            .expect("interrupt");
+
+        assert!(result.requested);
+        assert_eq!(result.turn_id, "turn_1");
+        assert_eq!(ports.interrupted_turns.lock().unwrap().len(), 1);
+    }
+
     #[tokio::test]
     async fn session_management_requires_registered_port() {
         let ports = Arc::new(FakeAgentRuntimePorts::default());
@@ -3316,6 +3459,54 @@ mod tests {
         );
     }
 
+    #[tokio::test]
+    async fn recover_interrupted_turn_delegates_and_validates_identity() {
+        #[derive(Debug)]
+        struct RecoveryPort;
+
+        #[async_trait::async_trait]
+        impl bitfun_runtime_ports::AgentDialogTurnPort for RecoveryPort {
+            async fn submit_dialog_turn(
+                &self,
+                _request: AgentDialogTurnRequest,
+            ) -> PortResult<DialogSubmitOutcome> {
+                unreachable!("recovery must not submit a new turn")
+            }
+
+            async fn recover_interrupted_turn(
+                &self,
+                request: AgentDialogTurnRecoveryRequest,
+            ) -> PortResult<AgentDialogTurnRecoveryOutcome> {
+                Ok(AgentDialogTurnRecoveryOutcome {
+                    session_id: request.session_id,
+                    turn_id: request.turn_id,
+                    execution_generation: request.execution_generation + 1,
+                })
+            }
+        }
+
+        let runtime = AgentRuntimeBuilder::new()
+            .with_submission_port(Arc::new(FakeAgentRuntimePorts::default()))
+            .with_dialog_turn_port(Arc::new(RecoveryPort))
+            .build()
+            .expect("runtime");
+        let result = runtime
+            .recover_interrupted_turn(AgentDialogTurnRecoveryRequest {
+                session_id: "session_1".to_string(),
+                turn_id: "turn_1".to_string(),
+                execution_generation: 0,
+                workspace_path: Some("/workspace/project".to_string()),
+                remote_connection_id: None,
+                remote_ssh_host: None,
+            })
+            .await
+            .expect("recover");
+
+        assert_eq!(result.session_id, "session_1");
+        assert_eq!(result.turn_id, "turn_1");
+        assert_eq!(result.execution_generation, 1);
+    }
+
     #[tokio::test]
     async fn submit_dialog_turn_rejects_provider_session_identity_mismatch() {
         #[derive(Debug)]
@@ -3383,6 +3574,8 @@ mod tests {
                 turn_id: "turn_1".to_string(),
                 content: "check tests".to_string(),
                 display_content: None,
+                attachments: Vec::new(),
+                metadata: serde_json::Map::new(),
             })
             .await
             .expect_err("steering without a dialog-turn provider must fail");
@@ -3433,6 +3626,8 @@ mod tests {
             turn_id: "turn_1".to_string(),
             content: "check tests".to_string(),
             display_content: Some("Check tests".to_string()),
+            attachments: Vec::new(),
+            metadata: serde_json::Map::new(),
         };
 
         let result = runtime
@@ -3492,6 +3687,8 @@ mod tests {
                 turn_id: "turn_1".to_string(),
                 content: "check tests".to_string(),
                 display_content: None,
+                attachments: Vec::new(),
+                metadata: serde_json::Map::new(),
             })
             .await
             .expect_err("provider turn mismatch must fail closed");
diff --git a/src/crates/execution/agent-runtime/src/scheduler.rs b/src/crates/execution/agent-runtime/src/scheduler.rs
index 3cb6f9e1a3..f9d8f9838c 100644
--- a/src/crates/execution/agent-runtime/src/scheduler.rs
+++ b/src/crates/execution/agent-runtime/src/scheduler.rs
@@ -4,7 +4,7 @@ use crate::events::turn_outcome_kind;
 use crate::thread_goal::{build_objective_updated_plan, build_thread_goal_continuation_plan};
 use bitfun_runtime_ports::{
     should_skip_agent_session_reply, should_suppress_agent_session_cancelled_reply,
-    AgentSessionReplyRoute, DialogQueuePriority, DialogRoundInjectionSource,
+    AgentInputAttachment, AgentSessionReplyRoute, DialogQueuePriority, DialogRoundInjectionSource,
     DialogSessionStateFact, DialogSteerOutcome, DialogSubmissionPolicy, DialogTriggerSource,
     RoundInjection, RoundInjectionKind, RoundInjectionTarget, RoundInjectionToolPreemption,
     ThreadGoal,
@@ -164,6 +164,12 @@ impl ActiveDialogTurnStore {
             .is_some_and(|turn| turn.turn_id() == turn_id)
     }
 
+    pub fn matches_agent_session_request(&self, session_id: &str, turn_id: &str) -> bool {
+        self.inner
+            .get(session_id)
+            .is_some_and(|turn| turn.turn_id() == turn_id && turn.is_agent_session_request())
+    }
+
     pub fn suppression_key_for_requester(
         &self,
         target_session_id: &str,
@@ -371,7 +377,7 @@ pub enum AgentSessionReplyAction {
     Forward(AgentSessionReplyPlan),
 }
 
-#[derive(Debug, Clone, PartialEq, Eq)]
+#[derive(Debug, Clone, PartialEq)]
 pub enum DialogSteeringAction {
     Reject {
         error: String,
@@ -592,6 +598,17 @@ impl SessionRoundInjectionBuffer {
         taken
     }
 
+    /// Drop injections whose target was only "whatever turn is currently
+    /// running" while retaining messages explicitly bound to a Turn. An
+    /// interrupted Turn may resume later, but an unscoped injection must not
+    /// leak into a different Turn if the user abandons it.
+    pub fn discard_current_running(&self, session_id: &str) {
+        let Some(mut entry) = self.inner.get_mut(session_id) else {
+            return;
+        };
+        entry.retain(|message| matches!(message.target, RoundInjectionTarget::ExactTurn(_)));
+    }
+
     pub fn remove_by_id(&self, session_id: &str, injection_id: &str) -> Option<RoundInjection> {
         let mut entry = self.inner.get_mut(session_id)?;
         let index = entry
@@ -700,10 +717,20 @@ pub fn resolve_background_delivery_injection(
         target: RoundInjectionTarget::CurrentRunningTurn,
         content,
         display_content,
+        attachments: Vec::new(),
+        metadata: serde_json::Map::new(),
         created_at,
     }
 }
 
+pub fn target_background_delivery_injection_to_turn(
+    mut injection: RoundInjection,
+    turn_id: String,
+) -> RoundInjection {
+    injection.target = RoundInjectionTarget::ExactTurn(turn_id);
+    injection
+}
+
 pub fn resolve_background_delivery_injection_for_turn(
     kind: BackgroundInjectionKind,
     injection_id: String,
@@ -712,15 +739,16 @@ pub fn resolve_background_delivery_injection_for_turn(
     created_at: SystemTime,
     turn_id: String,
 ) -> RoundInjection {
-    let mut injection = resolve_background_delivery_injection(
-        kind,
-        injection_id,
-        content,
-        display_content,
-        created_at,
-    );
-    injection.target = RoundInjectionTarget::ExactTurn(turn_id);
-    injection
+    target_background_delivery_injection_to_turn(
+        resolve_background_delivery_injection(
+            kind,
+            injection_id,
+            content,
+            display_content,
+            created_at,
+        ),
+        turn_id,
+    )
 }
 
 pub fn is_background_result_injection(kind: RoundInjectionKind) -> bool {
@@ -737,6 +765,11 @@ pub enum TurnOutcome {
     },
     /// Turn was cancelled by user.
     Cancelled { turn_id: String },
+    /// Turn was intentionally interrupted and may be recovered in place.
+    Interrupted {
+        turn_id: String,
+        execution_generation: u32,
+    },
     /// Turn failed with an error.
     Failed { turn_id: String, error: String },
 }
@@ -744,6 +777,7 @@ pub enum TurnOutcome {
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum TurnOutcomeQueueAction {
     DispatchNext,
+    HoldQueue,
     ClearQueue,
 }
 
@@ -751,6 +785,7 @@ pub enum TurnOutcomeQueueAction {
 pub enum TurnOutcomeStatus {
     Completed,
     Cancelled,
+    Interrupted,
     Failed,
 }
 
@@ -759,6 +794,7 @@ impl TurnOutcomeStatus {
         match self {
             Self::Completed => "completed",
             Self::Cancelled => "cancelled",
+            Self::Interrupted => "interrupted",
             Self::Failed => "failed",
         }
     }
@@ -775,6 +811,7 @@ impl TurnOutcome {
         match self {
             Self::Completed { turn_id, .. }
             | Self::Cancelled { turn_id }
+            | Self::Interrupted { turn_id, .. }
             | Self::Failed { turn_id, .. } => turn_id,
         }
     }
@@ -783,6 +820,7 @@ impl TurnOutcome {
         match self {
             Self::Completed { .. } => TurnOutcomeStatus::Completed,
             Self::Cancelled { .. } => TurnOutcomeStatus::Cancelled,
+            Self::Interrupted { .. } => TurnOutcomeStatus::Interrupted,
             Self::Failed { .. } => TurnOutcomeStatus::Failed,
         }
     }
@@ -804,6 +842,10 @@ impl TurnOutcome {
                 "The target session cancelled this request before producing a final answer."
                     .to_string()
             }
+            Self::Interrupted { .. } => {
+                "The target session interrupted this request before producing a final answer."
+                    .to_string()
+            }
             Self::Failed { error, .. } => {
                 format!("The target session failed to complete this request.\nError: {error}")
             }
@@ -813,6 +855,7 @@ impl TurnOutcome {
     pub fn queue_action(&self) -> TurnOutcomeQueueAction {
         match self {
             Self::Completed { .. } | Self::Cancelled { .. } => TurnOutcomeQueueAction::DispatchNext,
+            Self::Interrupted { .. } => TurnOutcomeQueueAction::HoldQueue,
             Self::Failed { .. } => TurnOutcomeQueueAction::ClearQueue,
         }
     }
@@ -822,6 +865,7 @@ impl TurnOutcome {
 pub enum GoalContinuationAfterTurnAction {
     SkipNoActiveTurn,
     AbortForCancelled,
+    AbortForInterrupted,
     Evaluate { turn_completed: bool },
 }
 
@@ -876,6 +920,7 @@ pub fn resolve_turn_outcome_lifecycle_plan(
     } else {
         match status {
             TurnOutcomeStatus::Cancelled => GoalContinuationAfterTurnAction::AbortForCancelled,
+            TurnOutcomeStatus::Interrupted => GoalContinuationAfterTurnAction::AbortForInterrupted,
             TurnOutcomeStatus::Completed => GoalContinuationAfterTurnAction::Evaluate {
                 turn_completed: true,
             },
@@ -888,7 +933,10 @@ pub fn resolve_turn_outcome_lifecycle_plan(
     TurnOutcomeLifecyclePlan {
         status,
         queue_action: outcome.queue_action(),
-        drain_finished_turn_injections: true,
+        // Interrupted is a resumable generation of the same Turn. Steering
+        // and background results already accepted for that Turn remain valid
+        // until the user either resumes it or explicitly abandons it.
+        drain_finished_turn_injections: status != TurnOutcomeStatus::Interrupted,
         goal_continuation,
     }
 }
@@ -937,6 +985,8 @@ pub fn resolve_dialog_steering_action(
     turn_id: &str,
     content: String,
     display_content: Option<String>,
+    attachments: Vec<AgentInputAttachment>,
+    metadata: serde_json::Map<String, serde_json::Value>,
     steering_id: String,
     created_at: SystemTime,
 ) -> DialogSteeringAction {
@@ -957,6 +1007,8 @@ pub fn resolve_dialog_steering_action(
             target: RoundInjectionTarget::ExactTurn(turn_id.to_string()),
             content,
             display_content: display,
+            attachments,
+            metadata,
             created_at,
         },
         outcome: DialogSteerOutcome::Buffered {
@@ -1064,6 +1116,63 @@ mod tests {
         assert!(!plan.clear_queue());
     }
 
+    #[test]
+    fn outcome_lifecycle_holds_queue_for_interrupted_turn() {
+        let outcome = TurnOutcome::Interrupted {
+            turn_id: "turn_1".to_string(),
+            execution_generation: 1,
+        };
+
+        let plan = resolve_turn_outcome_lifecycle_plan(&outcome, true);
+
+        assert_eq!(plan.status, TurnOutcomeStatus::Interrupted);
+        assert_eq!(plan.queue_action, TurnOutcomeQueueAction::HoldQueue);
+        assert!(
+            !plan.drain_finished_turn_injections,
+            "same-turn injections must survive until recovery or explicit abandonment"
+        );
+        assert_eq!(
+            plan.goal_continuation,
+            GoalContinuationAfterTurnAction::AbortForInterrupted
+        );
+        assert!(!plan.dispatch_next());
+        assert!(!plan.clear_queue());
+    }
+
+    #[test]
+    fn interrupted_turn_discards_only_unscoped_current_turn_injections() {
+        let buffer = SessionRoundInjectionBuffer::default();
+        buffer.push(
+            "session-1",
+            resolve_background_delivery_injection(
+                BackgroundInjectionKind::ThreadGoalObjectiveUpdated,
+                "current".to_string(),
+                "current-only".to_string(),
+                None,
+                SystemTime::now(),
+            ),
+        );
+        buffer.push(
+            "session-1",
+            target_background_delivery_injection_to_turn(
+                resolve_background_delivery_injection(
+                    BackgroundInjectionKind::BackgroundResult,
+                    "exact".to_string(),
+                    "resume-me".to_string(),
+                    None,
+                    SystemTime::now(),
+                ),
+                "turn-1".to_string(),
+            ),
+        );
+
+        buffer.discard_current_running("session-1");
+
+        assert!(buffer.has_pending_for_turn("session-1", "turn-1"));
+        assert!(!buffer.has_pending_for_turn("session-1", "turn-2"));
+        assert_eq!(buffer.pending_count("session-1"), 1);
+    }
+
     #[test]
     fn outcome_lifecycle_clears_queue_for_failed_turn_and_verifies_goal() {
         let outcome = TurnOutcome::Failed {
diff --git a/src/crates/execution/agent-runtime/src/sdk.rs b/src/crates/execution/agent-runtime/src/sdk.rs
index cc9f1eacd1..e11086f827 100644
--- a/src/crates/execution/agent-runtime/src/sdk.rs
+++ b/src/crates/execution/agent-runtime/src/sdk.rs
@@ -8,7 +8,7 @@
 
 use std::sync::Arc;
 
-pub const AGENT_RUNTIME_SDK_API_VERSION: u32 = 5;
+pub const AGENT_RUNTIME_SDK_API_VERSION: u32 = 6;
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 #[non_exhaustive]
@@ -64,7 +64,8 @@ pub use bitfun_harness::{
 };
 pub use bitfun_runtime_ports::{
     AgentBackgroundResultRequest, AgentContextReloadPort, AgentDialogSteerRequest,
-    AgentDialogTurnExecution, AgentDialogTurnPort, AgentDialogTurnRequest, AgentInputAttachment,
+    AgentDialogTurnExecution, AgentDialogTurnPort, AgentDialogTurnRecoveryOutcome,
+    AgentDialogTurnRecoveryRequest, AgentDialogTurnRequest, AgentInputAttachment,
     AgentInteractionResponsePort, AgentLifecycleDeliveryPort, AgentLocalCommandTurnPort,
     AgentLocalCommandTurnRecordRequest, AgentLocalCommandTurnRecordResult,
     AgentMessageWorkspaceReferencesRequest, AgentSessionArchiveRequest,
@@ -79,13 +80,14 @@ pub use bitfun_runtime_ports::{
     AgentSessionManagementPort, AgentSessionModePort, AgentSessionModeUpdateRequest,
     AgentSessionModelPort, AgentSessionModelSelection, AgentSessionModelSelectionUpdateRequest,
     AgentSessionModelUpdateRequest, AgentSessionRenameRequest, AgentSessionRevertPort,
-    AgentSessionRevertRequest, AgentSessionRevertResult, AgentSessionSummary,
-    AgentSessionUsagePort, AgentSessionUsageRequest, AgentSessionWorkspaceBinding,
-    AgentSessionWorkspaceRequest, AgentSubmissionPort, AgentSubmissionRequest,
-    AgentSubmissionResult, AgentSubmissionSource, AgentThreadGoalCreateRequest,
-    AgentThreadGoalDeliveryRequest, AgentThreadGoalGetRequest, AgentThreadGoalManagementPort,
-    AgentThreadGoalUpdateStatusRequest, AgentTransientSessionDiscardRequest,
-    AgentTurnCancellationPort, AgentTurnCancellationRequest, AgentTurnCancellationResult,
+    AgentSessionRevertRequest, AgentSessionRevertResult, AgentSessionRollbackToTurnOutcome,
+    AgentSessionRollbackToTurnRequest, AgentSessionSummary, AgentSessionUsagePort,
+    AgentSessionUsageRequest, AgentSessionWorkspaceBinding, AgentSessionWorkspaceRequest,
+    AgentSubmissionPort, AgentSubmissionRequest, AgentSubmissionResult, AgentSubmissionSource,
+    AgentThreadGoalCreateRequest, AgentThreadGoalDeliveryRequest, AgentThreadGoalGetRequest,
+    AgentThreadGoalManagementPort, AgentThreadGoalUpdateStatusRequest,
+    AgentTransientSessionDiscardRequest, AgentTurnCancellationPort, AgentTurnCancellationRequest,
+    AgentTurnCancellationResult, AgentTurnInterruptionRequest, AgentTurnInterruptionResult,
     AgentTurnSettlementPort, AgentTurnSettlementRequest, AgentUserAnswersRequest,
     AgentUserShellCommandPort, AgentUserShellCommandRequest, AgentUserShellCommandResult,
     AgentWorkspaceReference, AgentWorkspaceReferenceKind, AgentWorkspaceReferencePort,
@@ -553,6 +555,13 @@ impl AgentRuntime {
         self.inner.redo_session(request).await
     }
 
+    pub async fn rollback_session_to_turn(
+        &self,
+        request: AgentSessionRollbackToTurnRequest,
+    ) -> Result<AgentSessionRollbackToTurnOutcome, RuntimeError> {
+        self.inner.rollback_session_to_turn(request).await
+    }
+
     pub async fn fork_session(
         &self,
         request: AgentSessionForkRequest,
@@ -658,6 +667,13 @@ impl AgentRuntime {
         self.inner.steer_dialog_turn(request).await
     }
 
+    pub async fn recover_interrupted_turn(
+        &self,
+        request: AgentDialogTurnRecoveryRequest,
+    ) -> Result<AgentDialogTurnRecoveryOutcome, RuntimeError> {
+        self.inner.recover_interrupted_turn(request).await
+    }
+
     pub async fn deliver_background_result(
         &self,
         request: AgentBackgroundResultRequest,
@@ -707,6 +723,13 @@ impl AgentRuntime {
         self.inner.cancel_turn(request).await
     }
 
+    pub async fn interrupt_turn(
+        &self,
+        request: AgentTurnInterruptionRequest,
+    ) -> Result<AgentTurnInterruptionResult, RuntimeError> {
+        self.inner.interrupt_turn(request).await
+    }
+
     pub async fn cancel_lineage_session(
         &self,
         request: AgentSessionLineageCancellationRequest,
diff --git a/src/crates/execution/agent-runtime/tests/agent_definition_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_definition_contracts.rs
index 519ec16eb3..5d8fc901f2 100644
--- a/src/crates/execution/agent-runtime/tests/agent_definition_contracts.rs
+++ b/src/crates/execution/agent-runtime/tests/agent_definition_contracts.rs
@@ -1,4 +1,5 @@
 //! Agent definition, discovery, prompt, and skill contracts.
+#![cfg(feature = "agent-runtime")]
 
 #[path = "agent_definition_contracts/agent_registry_contracts.rs"]
 mod agent_registry_contracts;
diff --git a/src/crates/execution/agent-runtime/tests/agent_interaction_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_interaction_contracts.rs
index 4ff9513d38..7667b7ecf7 100644
--- a/src/crates/execution/agent-runtime/tests/agent_interaction_contracts.rs
+++ b/src/crates/execution/agent-runtime/tests/agent_interaction_contracts.rs
@@ -1,9 +1,8 @@
 //! Permission, question, and hook interaction contracts.
+#![cfg(feature = "agent-runtime")]
 
 #[path = "agent_interaction_contracts/native_hook_payload_contracts.rs"]
 mod native_hook_payload_contracts;
-#[path = "agent_interaction_contracts/native_hook_settings_contracts.rs"]
-mod native_hook_settings_contracts;
 #[path = "agent_interaction_contracts/permission_contracts.rs"]
 mod permission_contracts;
 #[path = "agent_interaction_contracts/post_call_hook_contracts.rs"]
diff --git a/src/crates/execution/agent-runtime/tests/agent_long_horizon_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_long_horizon_contracts.rs
index dec83990f2..dac35ae7b4 100644
--- a/src/crates/execution/agent-runtime/tests/agent_long_horizon_contracts.rs
+++ b/src/crates/execution/agent-runtime/tests/agent_long_horizon_contracts.rs
@@ -1,7 +1,6 @@
-//! DeepResearch, DeepReview, and long-running thread-goal contracts.
+//! DeepReview and long-running thread-goal contracts.
+#![cfg(feature = "agent-runtime")]
 
-#[path = "agent_long_horizon_contracts/deep_research_contracts.rs"]
-mod deep_research_contracts;
 #[path = "agent_long_horizon_contracts/deep_review_policy_contracts.rs"]
 mod deep_review_policy_contracts;
 #[path = "agent_long_horizon_contracts/thread_goal_contracts.rs"]
diff --git a/src/crates/execution/agent-runtime/tests/agent_session_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_session_contracts.rs
index 9cad89f6dc..ee1919c7e7 100644
--- a/src/crates/execution/agent-runtime/tests/agent_session_contracts.rs
+++ b/src/crates/execution/agent-runtime/tests/agent_session_contracts.rs
@@ -1,4 +1,5 @@
 //! Session, scheduler, event, SDK, and workspace-reference contracts.
+#![cfg(feature = "agent-runtime")]
 
 #[path = "agent_session_contracts/events_contracts.rs"]
 mod events_contracts;
diff --git a/src/crates/execution/agent-runtime/tests/agent_session_contracts/scheduler_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_session_contracts/scheduler_contracts.rs
index 8d36501b94..aa37afe695 100644
--- a/src/crates/execution/agent-runtime/tests/agent_session_contracts/scheduler_contracts.rs
+++ b/src/crates/execution/agent-runtime/tests/agent_session_contracts/scheduler_contracts.rs
@@ -11,9 +11,10 @@ use bitfun_agent_runtime::scheduler::{
     DEFAULT_MAX_DIALOG_QUEUE_DEPTH,
 };
 use bitfun_runtime_ports::{
-    AgentSessionReplyRoute, DialogQueuePriority, DialogSessionStateFact, DialogSteerOutcome,
-    DialogSubmissionPolicy, DialogTriggerSource, RoundInjection, RoundInjectionKind,
-    RoundInjectionTarget, RoundInjectionToolPreemption, ThreadGoal, ThreadGoalStatus,
+    AgentInputAttachment, AgentSessionReplyRoute, DialogQueuePriority, DialogSessionStateFact,
+    DialogSteerOutcome, DialogSubmissionPolicy, DialogTriggerSource, RoundInjection,
+    RoundInjectionKind, RoundInjectionTarget, RoundInjectionToolPreemption, ThreadGoal,
+    ThreadGoalStatus,
 };
 use std::sync::Arc;
 use std::time::SystemTime;
@@ -516,6 +517,15 @@ fn dialog_steering_action_buffers_exact_running_turn_with_display_fallback() {
         "turn-1",
         "steer content".to_string(),
         None,
+        vec![AgentInputAttachment::remote_image(
+            "image-1",
+            "shot.png",
+            "data:image/png;base64,abc",
+        )],
+        serde_json::Map::from_iter([(
+            "kind".to_string(),
+            serde_json::Value::String("steering".to_string()),
+        )]),
         "steer-id".to_string(),
         created_at,
     );
@@ -531,6 +541,14 @@ fn dialog_steering_action_buffers_exact_running_turn_with_display_fallback() {
     );
     assert_eq!(injection.content, "steer content");
     assert_eq!(injection.display_content, "steer content");
+    // Attachments and metadata ride the injection so the running turn sees the
+    // same payload a turn-boundary submission would have carried.
+    assert_eq!(injection.attachments.len(), 1);
+    assert_eq!(injection.attachments[0].id, "image-1");
+    assert_eq!(
+        injection.metadata.get("kind").and_then(|v| v.as_str()),
+        Some("steering")
+    );
     assert_eq!(injection.created_at, created_at);
     assert_eq!(
         injection.execution_policy.tool_preemption,
@@ -554,6 +572,8 @@ fn dialog_steering_action_rejects_when_target_turn_is_not_running() {
         "turn-1",
         "steer content".to_string(),
         Some("display".to_string()),
+        Vec::new(),
+        serde_json::Map::new(),
         "steer-id".to_string(),
         SystemTime::UNIX_EPOCH,
     );
@@ -658,6 +678,8 @@ fn exact_turn_msg(turn_id: &str, content: &str) -> RoundInjection {
         target: RoundInjectionTarget::ExactTurn(turn_id.to_string()),
         content: content.to_string(),
         display_content: content.to_string(),
+        attachments: Vec::new(),
+        metadata: serde_json::Map::new(),
         created_at: SystemTime::now(),
     }
 }
@@ -670,6 +692,8 @@ fn current_turn_msg(content: &str) -> RoundInjection {
         target: RoundInjectionTarget::CurrentRunningTurn,
         content: content.to_string(),
         display_content: content.to_string(),
+        attachments: Vec::new(),
+        metadata: serde_json::Map::new(),
         created_at: SystemTime::now(),
     }
 }
diff --git a/src/crates/execution/agent-runtime/tests/agent_session_contracts/sdk_smoke.rs b/src/crates/execution/agent-runtime/tests/agent_session_contracts/sdk_smoke.rs
index 5d886846f6..14d841523e 100644
--- a/src/crates/execution/agent-runtime/tests/agent_session_contracts/sdk_smoke.rs
+++ b/src/crates/execution/agent-runtime/tests/agent_session_contracts/sdk_smoke.rs
@@ -53,7 +53,7 @@ struct FakeSessionClosePort {
 fn sdk_facade_exposes_versioned_preview_compatibility_contract() {
     let compatibility = AgentRuntimeSdkCompatibility::current();
 
-    assert_eq!(compatibility.api_version, 5);
+    assert_eq!(compatibility.api_version, 6);
     assert_eq!(compatibility.crate_version, env!("CARGO_PKG_VERSION"));
     assert_eq!(compatibility.stability, AgentRuntimeSdkStability::Preview);
 }
diff --git a/src/crates/execution/agent-runtime/tests/agent_long_horizon_contracts/deep_research_contracts.rs b/src/crates/execution/agent-runtime/tests/deep_research_contracts.rs
similarity index 96%
rename from src/crates/execution/agent-runtime/tests/agent_long_horizon_contracts/deep_research_contracts.rs
rename to src/crates/execution/agent-runtime/tests/deep_research_contracts.rs
index 35e8e4a917..4e13effc21 100644
--- a/src/crates/execution/agent-runtime/tests/agent_long_horizon_contracts/deep_research_contracts.rs
+++ b/src/crates/execution/agent-runtime/tests/deep_research_contracts.rs
@@ -1,3 +1,6 @@
+//! DeepResearch report and citation contracts.
+#![cfg(feature = "deep-research")]
+
 use bitfun_agent_runtime::deep_research::renumber_research_report;
 
 #[test]
diff --git a/src/crates/execution/agent-runtime/tests/native_hook_execution_contracts.rs b/src/crates/execution/agent-runtime/tests/native_hook_execution_contracts.rs
index 9c85ae9e64..0fc2c31b84 100644
--- a/src/crates/execution/agent-runtime/tests/native_hook_execution_contracts.rs
+++ b/src/crates/execution/agent-runtime/tests/native_hook_execution_contracts.rs
@@ -7,6 +7,7 @@
 //!
 //! Unix-only: the fixtures are `sh` one-liners.
 #![cfg(unix)]
+#![cfg(feature = "native-hook-runtime")]
 
 use bitfun_agent_runtime::native_hooks::{
     AgentHookEngine, AgentHookEventPayload, AgentHookOutcome, AgentHookPayload,
diff --git a/src/crates/execution/agent-runtime/tests/agent_interaction_contracts/native_hook_settings_contracts.rs b/src/crates/execution/agent-runtime/tests/native_hook_settings_contracts.rs
similarity index 99%
rename from src/crates/execution/agent-runtime/tests/agent_interaction_contracts/native_hook_settings_contracts.rs
rename to src/crates/execution/agent-runtime/tests/native_hook_settings_contracts.rs
index 3346160854..af76a10b74 100644
--- a/src/crates/execution/agent-runtime/tests/agent_interaction_contracts/native_hook_settings_contracts.rs
+++ b/src/crates/execution/agent-runtime/tests/native_hook_settings_contracts.rs
@@ -4,6 +4,8 @@
 //! shape, the fixed event list, matcher semantics, handler fields, timeout
 //! defaults, and the layer/limit rules.
 
+#![cfg(feature = "native-hook-settings")]
+
 use bitfun_agent_runtime::native_hooks::{
     AgentHookEvent, AgentHookScope, AgentHookSettings, AgentHookSettingsIssue,
     AgentHookSettingsLayer, MAX_HOOK_HANDLERS,
diff --git a/src/crates/execution/agent-stream/src/lib.rs b/src/crates/execution/agent-stream/src/lib.rs
index f10b2cad9c..fa4f6cd849 100644
--- a/src/crates/execution/agent-stream/src/lib.rs
+++ b/src/crates/execution/agent-stream/src/lib.rs
@@ -290,6 +290,9 @@ impl StreamProcessError {
 #[derive(Debug, Clone, Default)]
 pub struct StreamProcessOptions {
     pub recover_partial_on_cancel: bool,
+    /// Suppress the stream-owned terminal cancellation event when a higher
+    /// layer owns the authoritative cancellation lifecycle.
+    pub suppress_cancel_lifecycle_event: bool,
     /// Allow broad JSON repair for non-Write tools, but only after a provider
     /// confirms a normal tool-use completion.
     pub allow_normal_tool_json_repair: bool,
@@ -333,6 +336,7 @@ struct StreamContext {
     /// output token limit (e.g. "length", "max_tokens", "MAX_TOKENS").
     token_limit_finish_reason: Option<String>,
     allow_normal_tool_json_repair: bool,
+    suppress_cancel_lifecycle_event: bool,
 }
 
 impl StreamContext {
@@ -371,6 +375,7 @@ impl StreamContext {
             partial_recovery_reason: None,
             token_limit_finish_reason: None,
             allow_normal_tool_json_repair: options.allow_normal_tool_json_repair,
+            suppress_cancel_lifecycle_event: options.suppress_cancel_lifecycle_event,
         }
     }
 
@@ -512,6 +517,7 @@ struct GracefulShutdownInput {
     attempt_index: u32,
     tool_calls: Vec<ToolCall>,
     reason: String,
+    suppress_cancel_lifecycle_event: bool,
 }
 
 impl StreamProcessor {
@@ -607,6 +613,7 @@ impl StreamProcessor {
             attempt_index: ctx.attempt_index,
             tool_calls: ctx.tool_calls.clone(),
             reason,
+            suppress_cancel_lifecycle_event: ctx.suppress_cancel_lifecycle_event,
         })
         .await;
     }
@@ -621,6 +628,7 @@ impl StreamProcessor {
             attempt_index,
             tool_calls,
             reason,
+            suppress_cancel_lifecycle_event,
         } = input;
         debug!(
             "Starting graceful shutdown: session_id={}, reason={}",
@@ -679,7 +687,7 @@ impl StreamProcessor {
         }
 
         // 2. Send dialog turn status update (if tools were cleaned up)
-        if tool_call_count > 0 {
+        if tool_call_count > 0 && !(is_user_cancellation && suppress_cancel_lifecycle_event) {
             let event = if is_user_cancellation {
                 AgenticEvent::DialogTurnCancelled {
                     session_id: session_id.clone(),
@@ -1324,6 +1332,7 @@ mod tests {
                     repair_kind: Default::default(),
                 }],
                 reason: "User cancelled stream processing".to_string(),
+                suppress_cancel_lifecycle_event: false,
             })
             .await;
 
@@ -1343,6 +1352,44 @@ mod tests {
         ));
     }
 
+    #[tokio::test]
+    async fn graceful_shutdown_suppresses_turn_cancellation_for_coordinator_owned_lifecycle() {
+        let sink = Arc::new(RecordingEventSink::default());
+        let processor = StreamProcessor::new(sink.clone());
+
+        processor
+            .graceful_shutdown(GracefulShutdownInput {
+                session_id: "session_1".to_string(),
+                turn_id: "turn_1".to_string(),
+                round_id: "round_1".to_string(),
+                attempt_id: "attempt_1".to_string(),
+                attempt_index: 1,
+                tool_calls: vec![ToolCall {
+                    tool_id: "tool_1".to_string(),
+                    tool_name: "Read".to_string(),
+                    arguments: json!({}),
+                    raw_arguments: None,
+                    is_error: false,
+                    parse_error: None,
+                    recovered_from_truncation: false,
+                    repair_kind: Default::default(),
+                }],
+                reason: "User cancelled stream processing".to_string(),
+                suppress_cancel_lifecycle_event: true,
+            })
+            .await;
+
+        let events = sink.events.lock().await;
+        assert_eq!(events.len(), 1);
+        assert!(matches!(
+            &events[0],
+            AgenticEvent::ToolEvent {
+                tool_event: ToolEventData::Cancelled { identity, .. },
+                ..
+            } if identity.tool_id == "tool_1"
+        ));
+    }
+
     #[test]
     fn derives_watchdog_timeout_from_stream_idle_timeout() {
         assert_eq!(StreamProcessor::derive_watchdog_timeout(None), None);
diff --git a/src/crates/execution/plugin-runtime-client/Cargo.toml b/src/crates/execution/plugin-runtime-client/Cargo.toml
index 2bb8dbab52..6ac82e4db5 100644
--- a/src/crates/execution/plugin-runtime-client/Cargo.toml
+++ b/src/crates/execution/plugin-runtime-client/Cargo.toml
@@ -11,7 +11,7 @@ crate-type = ["rlib"]
 
 [dependencies]
 async-trait = { workspace = true }
-bitfun-runtime-ports = { path = "../../contracts/runtime-ports" }
+bitfun-runtime-ports = { path = "../../contracts/runtime-ports", features = ["plugin-runtime"] }
 tokio = { workspace = true, features = ["sync", "time"] }
 
 [dev-dependencies]
diff --git a/src/crates/execution/runtime-services/Cargo.toml b/src/crates/execution/runtime-services/Cargo.toml
index e9f7f0a1cf..78a4bbdaf0 100644
--- a/src/crates/execution/runtime-services/Cargo.toml
+++ b/src/crates/execution/runtime-services/Cargo.toml
@@ -15,7 +15,7 @@ test-support = []
 
 [dependencies]
 bitfun-events = { path = "../../contracts/events" }
-bitfun-runtime-ports = { path = "../../contracts/runtime-ports" }
+bitfun-runtime-ports = { path = "../../contracts/runtime-ports", features = ["git-port", "remote-exec-port", "remote-workspace-ports", "runtime-event-port", "terminal-port", "workspace-ports"] }
 anyhow = { workspace = true }
 async-trait = { workspace = true }
 log = { workspace = true }
diff --git a/src/crates/execution/tool-contracts/AGENTS.md b/src/crates/execution/tool-contracts/AGENTS.md
index ed8f66e8c7..f323c51be8 100644
--- a/src/crates/execution/tool-contracts/AGENTS.md
+++ b/src/crates/execution/tool-contracts/AGENTS.md
@@ -31,11 +31,17 @@ the product tool runtime.
   `services-integrations`; this crate owns only the model/tool bridge contract.
 - ACP protocol/client lifecycle stays in `bitfun-acp`; this crate owns only the
   external-agent tool bridge contract.
+- Keep `default = []`. ACP and MCP bridges, Computer Use contracts, and element
+  tokens are independent capability slices; do not combine them into a
+  `full` or compatibility feature.
 
 ## Verification
 
 ```bash
-cargo test -p bitfun-agent-tools
-cargo test -p bitfun-agent-tools --test tool_contracts
+cargo test --locked -p bitfun-agent-tools --no-default-features
+cargo test --locked -p bitfun-agent-tools --no-default-features --features acp-bridge --test tool_contracts acp_external_agent_bridge_preserves_tool_contract
+cargo test --locked -p bitfun-agent-tools --no-default-features --features mcp-bridge --test tool_contracts mcp_tool_bridge
+cargo test --locked -p bitfun-agent-tools --no-default-features --features computer-use-contract --lib computer_use::
+cargo test --locked -p bitfun-agent-tools --no-default-features --features element-token --lib element_token::
 node scripts/check-core-boundaries.mjs
 ```
diff --git a/src/crates/execution/tool-contracts/Cargo.toml b/src/crates/execution/tool-contracts/Cargo.toml
index 5a1f594ec2..4ef3cf024c 100644
--- a/src/crates/execution/tool-contracts/Cargo.toml
+++ b/src/crates/execution/tool-contracts/Cargo.toml
@@ -17,6 +17,13 @@ bitfun-runtime-ports = { path = "../../contracts/runtime-ports" }
 async-trait = { workspace = true }
 indexmap = { workspace = true }
 
+[features]
+default = []
+acp-bridge = []
+computer-use-contract = []
+element-token = []
+mcp-bridge = []
+
 [dev-dependencies]
 tokio = { workspace = true, features = ["macros", "rt"] }
 
diff --git a/src/crates/execution/tool-contracts/src/computer_use.rs b/src/crates/execution/tool-contracts/src/computer_use.rs
index fbfbc617e8..e8349f0e74 100644
--- a/src/crates/execution/tool-contracts/src/computer_use.rs
+++ b/src/crates/execution/tool-contracts/src/computer_use.rs
@@ -1094,6 +1094,11 @@ pub enum AppWaitPredicate {
 /// `interaction_state.displays` so it can pick the right screen explicitly
 /// instead of falling back to whichever screen the mouse pointer happens
 /// to be on (the original "computer use 在多屏时搞错操作的屏幕" failure mode).
+///
+/// `interaction_state.displays` is populated **only when more than one display
+/// is attached** — it rides on every result, and on a single-screen machine
+/// repeating it says nothing `active_display_id` does not already say. Callers
+/// that need the list unconditionally should use `list_displays`.
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
 pub struct ComputerUseDisplayInfo {
     /// Stable per-session id of the display. Pass back to
@@ -1131,6 +1136,28 @@ pub struct OpenAppResult {
     pub process_id: Option<i32>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub error_message: Option<String>,
+    /// Bundle identifier of the launched app (macOS). The agent needs this to
+    /// address the app afterwards: the name it launched by (`Lark`), the
+    /// executable name (`Feishu`) and the bundle id (`com.electron.lark`) are
+    /// routinely three different strings, and only the bundle id works with
+    /// every follow-up path.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub bundle_id: Option<String>,
+    /// Process name as the OS reports it — the identity AppleScript's
+    /// `tell process "…"` and `ps` expect, which is often **not** `app_name`.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub process_name: Option<String>,
+    /// Windows the app owns once the launch settled. `Some(0)` means the
+    /// process is alive but has nothing on screen — a real state for Electron
+    /// apps whose window was closed while the process stayed resident, and one
+    /// the agent otherwise has no way to distinguish from a healthy launch.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub window_count: Option<usize>,
+    /// How the app ended up in front. Diagnostic: tells the agent whether a
+    /// plain activate sufficed or the host had to re-open the bundle to force
+    /// a window.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub launch_path: Option<String>,
 }
 
 /// Whether the latest screenshot JPEG was the full display, a point crop, or a quadrant-drill region.
diff --git a/src/crates/execution/tool-contracts/src/lib.rs b/src/crates/execution/tool-contracts/src/lib.rs
index 397fd4aea7..4bbdaf97ec 100644
--- a/src/crates/execution/tool-contracts/src/lib.rs
+++ b/src/crates/execution/tool-contracts/src/lib.rs
@@ -3,21 +3,26 @@
 //! Pure tool DTOs and helpers live here before the concrete tool framework and
 //! tool packs are moved out of the core facade.
 
+#[cfg(feature = "acp-bridge")]
 pub mod acp_tool_bridge;
+#[cfg(feature = "computer-use-contract")]
 pub mod computer_use;
 pub mod deferred_tool;
+#[cfg(feature = "element-token")]
 pub mod element_token;
 pub mod execution_gate;
 pub mod file_guidance;
 pub mod file_read_freshness;
 pub mod framework;
 pub mod input_validator;
+#[cfg(feature = "mcp-bridge")]
 pub mod mcp_tool_bridge;
 pub mod permission_intent;
 pub mod tool_execution_presentation;
 pub mod tool_result_storage;
 pub mod tool_snapshot;
 
+#[cfg(feature = "acp-bridge")]
 pub use acp_tool_bridge::{
     acp_external_agent_tool_input_schema, build_acp_external_agent_tool_definition,
     build_acp_external_agent_tool_name, build_acp_external_agent_tool_result,
@@ -93,6 +98,7 @@ pub use framework::{
     BITFUN_CURRENT_SESSION_URI_PREFIX, BITFUN_RUNTIME_URI_PREFIX, GET_TOOL_SPEC_TOOL_NAME,
 };
 pub use input_validator::InputValidator;
+#[cfg(feature = "mcp-bridge")]
 pub use mcp_tool_bridge::{
     build_mcp_tool_bridge_definition, build_mcp_tool_bridge_name, build_mcp_tool_bridge_result,
     mcp_tool_bridge_dynamic_tool_info, mcp_tool_bridge_short_description, normalize_name_for_mcp,
diff --git a/src/crates/execution/tool-contracts/tests/tool_contracts.rs b/src/crates/execution/tool-contracts/tests/tool_contracts.rs
index c4778a2f34..0813321566 100644
--- a/src/crates/execution/tool-contracts/tests/tool_contracts.rs
+++ b/src/crates/execution/tool-contracts/tests/tool_contracts.rs
@@ -1,3 +1,6 @@
+#[cfg(feature = "mcp-bridge")]
+use bitfun_agent_tools::validate_mcp_tool_bridge_input;
+#[cfg(feature = "acp-bridge")]
 use bitfun_agent_tools::{
     acp_external_agent_tool_input_schema, build_acp_external_agent_tool_definition,
     build_acp_external_agent_tool_name, build_acp_external_agent_tool_result,
@@ -26,13 +29,11 @@ use bitfun_agent_tools::{
     resolve_tool_path_with_context_roots, resolve_workspace_tool_path,
     sort_tool_manifest_definitions, summarize_get_tool_spec_deferred_tools,
     tool_path_is_effectively_absolute, validate_deferred_tool_usage, validate_get_tool_spec_input,
-    validate_mcp_tool_bridge_input, validate_tool_allowed_by_list,
-    validate_tool_execution_admission, CallDeferredToolInputError, DynamicMcpToolInfo,
-    DynamicToolInfo, GetToolSpecDeferredToolSummary, GetToolSpecExecutionError,
+    validate_tool_allowed_by_list, validate_tool_execution_admission, CallDeferredToolInputError,
+    DynamicMcpToolInfo, DynamicToolInfo, GetToolSpecDeferredToolSummary, GetToolSpecExecutionError,
     GetToolSpecExecutionPlan, GetToolSpecLoadObservation, GetToolSpecRuntime, InputValidator,
-    LoadedDeferredToolSpec, McpToolBridgeBehaviorHints, McpToolBridgeDefinitionInput,
-    PromptVisibleToolManifestItem, ResolvedToolInvocation, ToolContextFacts,
-    ToolExecutionAdmissionRejection, ToolExecutionAdmissionRequest, ToolExposure,
+    LoadedDeferredToolSpec, PromptVisibleToolManifestItem, ResolvedToolInvocation,
+    ToolContextFacts, ToolExecutionAdmissionRejection, ToolExecutionAdmissionRequest, ToolExposure,
     ToolImageAttachment, ToolManifestDefinition, ToolManifestPolicyTool, ToolPathBackend,
     ToolPathOperation, ToolPathResolution, ToolRenderOptions, ToolResult, ToolRuntimeRestrictions,
     ToolWorkspaceKind, ValidationResult, CALL_DEFERRED_TOOL_NAME, GET_TOOL_SPEC_TOOL_NAME,
@@ -46,11 +47,13 @@ use bitfun_agent_tools::{
     TOOL_ERROR_ARGUMENTS_PREVIEW_BYTES, USER_REJECTED_TOOL_MESSAGE,
     USER_STEERING_INTERRUPTED_MESSAGE,
 };
+#[cfg(feature = "mcp-bridge")]
 use bitfun_agent_tools::{
     build_mcp_tool_bridge_definition, build_mcp_tool_bridge_name, build_mcp_tool_bridge_result,
     mcp_tool_bridge_dynamic_tool_info, mcp_tool_bridge_short_description, normalize_name_for_mcp,
     render_mcp_tool_bridge_rejected_message, render_mcp_tool_bridge_result_message,
-    render_mcp_tool_bridge_use_message, MCP_TOOL_DELIMITER, MCP_TOOL_PREFIX,
+    render_mcp_tool_bridge_use_message, McpToolBridgeBehaviorHints, McpToolBridgeDefinitionInput,
+    MCP_TOOL_DELIMITER, MCP_TOOL_PREFIX,
 };
 use bitfun_agent_tools::{
     build_persisted_tool_output_message, count_tool_result_lines, file_tool_guidance_message,
@@ -185,6 +188,7 @@ fn resolved_tool_invocation_updates_effective_arguments_without_losing_wire_iden
 }
 
 #[test]
+#[cfg(feature = "mcp-bridge")]
 fn mcp_tool_bridge_preserves_prompt_visible_name_and_descriptor_contract() {
     assert_eq!(MCP_TOOL_PREFIX, "mcp__");
     assert_eq!(MCP_TOOL_DELIMITER, "__");
@@ -239,6 +243,7 @@ fn mcp_tool_bridge_preserves_prompt_visible_name_and_descriptor_contract() {
 }
 
 #[test]
+#[cfg(feature = "mcp-bridge")]
 fn mcp_tool_bridge_preserves_dynamic_info_validation_and_rendering_contract() {
     let definition = build_mcp_tool_bridge_definition(McpToolBridgeDefinitionInput {
         server_id: "github",
@@ -309,6 +314,7 @@ fn mcp_tool_bridge_preserves_dynamic_info_validation_and_rendering_contract() {
 }
 
 #[test]
+#[cfg(feature = "acp-bridge")]
 fn acp_external_agent_bridge_preserves_tool_contract() {
     assert_eq!(ACP_TOOL_PREFIX, "acp__");
     assert_eq!(ACP_TOOL_SUFFIX, "__prompt");
diff --git a/src/crates/execution/tool-execution/src/fs/document.rs b/src/crates/execution/tool-execution/src/fs/document.rs
index 62112ec30e..0e72985c1b 100644
--- a/src/crates/execution/tool-execution/src/fs/document.rs
+++ b/src/crates/execution/tool-execution/src/fs/document.rs
@@ -1,46 +1,66 @@
-//! Local, provider-neutral document-to-Markdown conversion for the Read tool.
+//! Document path recognition and optional provider-neutral Markdown conversion.
 
+#[cfg(feature = "document-read")]
 use std::collections::VecDeque;
+#[cfg(feature = "document-read")]
 use std::fmt;
 use std::path::Path;
+#[cfg(feature = "document-read")]
 use std::sync::{Arc, Mutex, OnceLock};
 
+#[cfg(feature = "document-read")]
 use anydoc::Format;
+#[cfg(feature = "document-read")]
 use sha2::{Digest, Sha256};
+#[cfg(feature = "document-read")]
 use tokio::sync::Semaphore;
 
 /// Maximum source-document size accepted by the Read tool conversion path.
+#[cfg(feature = "document-read")]
 pub const MAX_DOCUMENT_INPUT_BYTES: usize = 64 * 1024 * 1024;
 
 /// Maximum retained Markdown for one conversion and across the in-memory conversion cache.
+#[cfg(feature = "document-read")]
 pub const MAX_DOCUMENT_MARKDOWN_BYTES: usize = 16 * 1024 * 1024;
 
+#[cfg(feature = "document-read")]
 const MAX_DOCUMENT_CACHE_ENTRIES: usize = 4;
 
+/// Extensions recognized as documents even when conversion support is not compiled.
+pub const SUPPORTED_DOCUMENT_EXTENSIONS: &[&str] = &[
+    "doc", "docx", "docm", "odt", "pdf", "pptx", "pptm", "ppsx", "ppsm", "ppt", "pps", "pot",
+    "rtf", "epub", "xlsx", "xlsm", "xlsb", "xls", "ods", "odp", "csv",
+];
+
 /// A document representation that can be paged by the normal Read primitives.
+#[cfg(feature = "document-read")]
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ConvertedDocument {
     pub markdown: Arc<str>,
     pub source_format: &'static str,
 }
 
+#[cfg(feature = "document-read")]
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 struct DocumentCacheKey {
     source_sha256: [u8; 32],
     format: Format,
 }
 
+#[cfg(feature = "document-read")]
 struct DocumentCacheEntry {
     key: DocumentCacheKey,
     document: ConvertedDocument,
 }
 
+#[cfg(feature = "document-read")]
 #[derive(Default)]
 struct DocumentCache {
     entries: VecDeque<DocumentCacheEntry>,
     retained_markdown_bytes: usize,
 }
 
+#[cfg(feature = "document-read")]
 impl DocumentCache {
     fn get(&mut self, key: DocumentCacheKey) -> Option<ConvertedDocument> {
         let index = self.entries.iter().position(|entry| entry.key == key)?;
@@ -74,12 +94,14 @@ impl DocumentCache {
 }
 
 /// Provider-neutral document conversion failure.
+#[cfg(feature = "document-read")]
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct DocumentConversionError {
     code: &'static str,
     message: String,
 }
 
+#[cfg(feature = "document-read")]
 impl DocumentConversionError {
     fn new(code: &'static str, message: impl Into<String>) -> Self {
         Self {
@@ -93,21 +115,31 @@ impl DocumentConversionError {
     }
 }
 
+#[cfg(feature = "document-read")]
 impl fmt::Display for DocumentConversionError {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         f.write_str(&self.message)
     }
 }
 
+#[cfg(feature = "document-read")]
 impl std::error::Error for DocumentConversionError {}
 
-/// Whether the path extension names a format handled by anydoc.
+/// Whether the path extension names a supported document format.
 pub fn is_supported_document_path(path: &str) -> bool {
-    Format::from_path(Path::new(path)).is_some()
+    Path::new(path)
+        .extension()
+        .and_then(|extension| extension.to_str())
+        .is_some_and(|extension| {
+            SUPPORTED_DOCUMENT_EXTENSIONS
+                .iter()
+                .any(|supported| extension.eq_ignore_ascii_case(supported))
+        })
 }
 
 /// Convert document bytes on the blocking pool. Conversion is serialized process-wide because
 /// parsers can temporarily retain substantially more decompressed data than the source file.
+#[cfg(feature = "document-read")]
 pub async fn convert_document_to_markdown(
     bytes: Vec<u8>,
     path_hint: String,
@@ -148,11 +180,13 @@ pub async fn convert_document_to_markdown(
     })?
 }
 
+#[cfg(feature = "document-read")]
 fn document_conversion_semaphore() -> &'static Arc<Semaphore> {
     static SEMAPHORE: OnceLock<Arc<Semaphore>> = OnceLock::new();
     SEMAPHORE.get_or_init(|| Arc::new(Semaphore::new(1)))
 }
 
+#[cfg(feature = "document-read")]
 fn convert_document_to_markdown_sync(
     bytes: &[u8],
     path_hint: &str,
@@ -201,11 +235,13 @@ fn convert_document_to_markdown_sync(
     Ok(document)
 }
 
+#[cfg(feature = "document-read")]
 fn document_cache() -> &'static Mutex<DocumentCache> {
     static CACHE: OnceLock<Mutex<DocumentCache>> = OnceLock::new();
     CACHE.get_or_init(|| Mutex::new(DocumentCache::default()))
 }
 
+#[cfg(feature = "document-read")]
 fn format_name(format: Format) -> &'static str {
     match format {
         Format::Doc => "doc",
@@ -251,6 +287,15 @@ mod tests {
         assert!(!is_supported_document_path("README.md"));
     }
 
+    #[cfg(feature = "document-read")]
+    #[test]
+    fn recognized_extensions_match_anydoc() {
+        for extension in SUPPORTED_DOCUMENT_EXTENSIONS {
+            assert!(Format::from_extension(extension).is_some(), "{extension}");
+        }
+    }
+
+    #[cfg(feature = "document-read")]
     #[test]
     fn content_detection_takes_precedence_over_a_wrong_extension_hint() {
         let converted =
@@ -261,6 +306,7 @@ mod tests {
         assert!(converted.markdown.contains("Hello from RTF"));
     }
 
+    #[cfg(feature = "document-read")]
     #[test]
     fn csv_uses_the_path_hint_because_it_has_no_content_signature() {
         let converted =
@@ -272,6 +318,7 @@ mod tests {
         assert!(converted.markdown.contains("| alpha | 1 |"));
     }
 
+    #[cfg(feature = "document-read")]
     #[test]
     fn repeated_conversion_reuses_cached_markdown_for_offset_reads() {
         let first =
diff --git a/src/crates/execution/tool-execution/src/fs/mod.rs b/src/crates/execution/tool-execution/src/fs/mod.rs
index a51bb0690e..f40c7bb80b 100644
--- a/src/crates/execution/tool-execution/src/fs/mod.rs
+++ b/src/crates/execution/tool-execution/src/fs/mod.rs
@@ -1,6 +1,5 @@
 pub mod backend;
 pub mod delete_path;
-#[cfg(feature = "document-read")]
 pub mod document;
 pub mod edit_file;
 pub mod list_dir;
@@ -65,3 +64,13 @@ pub fn path_has_multiple_hard_links(path: &std::path::Path) -> std::io::Result<b
         ))
     }
 }
+
+#[cfg(test)]
+mod tests {
+    #[test]
+    fn document_path_recognition_is_available_without_conversion_support() {
+        assert!(super::document::is_supported_document_path("report.DOCX"));
+        assert!(super::document::is_supported_document_path("paper.pdf"));
+        assert!(!super::document::is_supported_document_path("src/lib.rs"));
+    }
+}
diff --git a/src/crates/interfaces/AGENTS-CN.md b/src/crates/interfaces/AGENTS-CN.md
index 3faaaeb2aa..410e5a7568 100644
--- a/src/crates/interfaces/AGENTS-CN.md
+++ b/src/crates/interfaces/AGENTS-CN.md
@@ -9,6 +9,9 @@
 | Crate | 职责 | 本地文档 |
 |---|---|---|
 | `acp` | 基于已组装产品 runtime 的 Agent Client Protocol 接口 | [AGENTS.md](acp/AGENTS.md) |
+| `app-server-protocol` | behavior-light App Server method、wire DTO、错误、事件和 protocol role | [AGENTS.md](app-server/AGENTS.md) |
+| `app-server-client` | transport-agnostic 类型化 App Server client 和事件分发 | [AGENTS.md](app-server/AGENTS.md) |
+| `app-server` | 生产 App Server handler 注册、生命周期和 owner-to-wire adapter | [AGENTS.md](app-server/AGENTS.md) |
 | `sdk-host` | 版本化的本地 Agent SDK Host 协议与连接用例；进程启动和 stdio framing 仍由 `src/apps/sdk-host` 负责 | — |
 
 ## 放置规则
diff --git a/src/crates/interfaces/AGENTS.md b/src/crates/interfaces/AGENTS.md
index 231ecea2ce..6bb083499b 100644
--- a/src/crates/interfaces/AGENTS.md
+++ b/src/crates/interfaces/AGENTS.md
@@ -12,7 +12,9 @@ product behavior. UI apps and delivery hosts remain under `src/apps`,
 | Crate | Responsibility | Local doc |
 |---|---|---|
 | `acp` | Agent Client Protocol interface over the assembled product runtime | [AGENTS.md](acp/AGENTS.md) |
-| `app-server` | Protocol-agnostic JSON-RPC app-server/client scaffold over `agent_client_protocol` custom roles | [AGENTS.md](app-server/AGENTS.md) |
+| `app-server-protocol` | Behavior-light App Server methods, wire DTOs, errors, events, and protocol roles | [AGENTS.md](app-server/AGENTS.md) |
+| `app-server-client` | Transport-agnostic typed App Server client and event distribution | [AGENTS.md](app-server/AGENTS.md) |
+| `app-server` | Production App Server handler registration, lifecycle, and owner-to-wire adapters | [AGENTS.md](app-server/AGENTS.md) |
 | `sdk-host` | Versioned local Agent SDK Host protocol and connection use cases; process bootstrap and stdio framing remain in `src/apps/sdk-host` | — |
 
 ## Placement Rules
diff --git a/src/crates/interfaces/acp/AGENTS-CN.md b/src/crates/interfaces/acp/AGENTS-CN.md
index f71972f39d..51392ff76f 100644
--- a/src/crates/interfaces/acp/AGENTS-CN.md
+++ b/src/crates/interfaces/acp/AGENTS-CN.md
@@ -6,12 +6,11 @@
 
 `bitfun-acp` 负责基于已组装产品 runtime 的 Agent Client Protocol 入口与 ACP client 行为。ACP protocol / client 细节留在这里或应用入口 adapter 中；跨层只共享稳定 capability facts。
 
-CLI 托管的 ACP 服务端已通过 `ProductAssembler` 消费 `DeliveryProfile::Acp`，并使用 Agent Runtime SDK
-完成会话创建/列举、活动会话模型/模式更新、轮次提交/取消、交互响应和 Agent 事件订阅。`bitfun-acp` 仍直接依赖
-`bitfun-core` 的 `agent-runtime`、`canvas-runtime`、`external-sources` 与 `ssh-remote` owner feature，
-用于一次性恢复完整持久化历史、模型/模式目录、Canvas 工具物化、提供方与兼容指令来源读取、MCP 配置、
-远程工作区，以及本 crate 的 ACP 客户端路径。
-在这些生产路径分别获得可移植替代并证明等价前，不得宣称整个 crate 已与 Core 解耦。
+本 crate 暴露两个可加性的角色 feature。`client` 负责 ACP 进程发现、配置、远程探测、会话传输和
+tool-card 投影，选择 Core Agent Runtime 与具体 SSH 能力；`server` 负责 CLI 托管的 ACP 服务端，
+通过 `DeliveryProfile::Acp` 投影 runtime，并精确选择该路径使用的工具、文档、订阅、LSP 与外部来源 owner，
+但不选择 SSH。兼容默认值必须精确等于 `client + server`；Desktop 只选择 `client`，CLI 选择两者。
+两个角色保持加法语义，不得用 `product-full` 替代任一闭包。
 
 ## 护栏
 
@@ -24,6 +23,7 @@ CLI 托管的 ACP 服务端已通过 `ProductAssembler` 消费 `DeliveryProfile:
 ## 验证
 
 ```bash
-cargo check -p bitfun-acp
+cargo check -p bitfun-acp --no-default-features --features client
+cargo check -p bitfun-acp --no-default-features --features server
 cargo test -p bitfun-acp
 ```
diff --git a/src/crates/interfaces/acp/AGENTS.md b/src/crates/interfaces/acp/AGENTS.md
index fd6febe6d0..a695abeb4b 100644
--- a/src/crates/interfaces/acp/AGENTS.md
+++ b/src/crates/interfaces/acp/AGENTS.md
@@ -8,16 +8,15 @@ Scope: this guide applies to `src/crates/interfaces/acp`.
 runtime. Keep ACP protocol/client details here or in app-surface adapters;
 share only stable capability facts through contract crates.
 
-The CLI-hosted ACP server consumes `DeliveryProfile::Acp` through
-`ProductAssembler` and uses the Agent Runtime SDK for session creation/listing,
-active session model/mode updates, dialog submission/cancellation, interaction
-responses, and agent event subscription. `bitfun-acp` still depends directly on
-the `bitfun-core` `agent-runtime`, `canvas-runtime`, `external-sources`, and
-`ssh-remote` owner features for single-pass full persisted-history restore,
-model/mode catalog, Canvas tool materialization, provider and compatible
-instruction-source reads, MCP provisioning, remote workspace support, and the
-ACP client half of this crate. Do not describe the crate as Core-independent
-until those production paths have separately proven portable replacements.
+The crate exposes two additive roles. `client` owns ACP process discovery,
+configuration, remote probing, session transport, and tool-card projection; it
+selects the Core Agent Runtime plus concrete SSH support. `server` owns the
+CLI-hosted ACP server and runtime projection through `DeliveryProfile::Acp`; it
+selects the exact Core tool, document, subscription, LSP, and external-source
+owners used by that path, but does not select SSH. The compatibility default is
+exactly `client + server`. Desktop selects only `client`; CLI selects both.
+Keep these role features additive and do not replace either closure with
+`product-full`.
 
 ## Guardrails
 
@@ -39,6 +38,7 @@ until those production paths have separately proven portable replacements.
 ## Verification
 
 ```bash
-cargo check -p bitfun-acp
+cargo check -p bitfun-acp --no-default-features --features client
+cargo check -p bitfun-acp --no-default-features --features server
 cargo test -p bitfun-acp
 ```
diff --git a/src/crates/interfaces/acp/Cargo.toml b/src/crates/interfaces/acp/Cargo.toml
index cdc525cfe7..254beb1715 100644
--- a/src/crates/interfaces/acp/Cargo.toml
+++ b/src/crates/interfaces/acp/Cargo.toml
@@ -5,43 +5,68 @@ authors.workspace = true
 edition.workspace = true
 description = "BitFun Agent Client Protocol surface"
 
+[features]
+default = ["client", "server"]
+client = [
+    "bitfun-agent-tools/acp-bridge",
+    "dep:futures",
+    "dep:serde",
+    "dep:dirs",
+    "dep:semver",
+    "dep:tar",
+    "dep:bitfun-core",
+    "bitfun-core/agent-runtime",
+    "bitfun-core/ssh-remote",
+]
+server = [
+    "dep:bitfun-agent-tools",
+    "dep:bitfun-agent-runtime",
+    "bitfun-agent-runtime/agent-runtime",
+    "dep:bitfun-core-types",
+    "dep:bitfun-core",
+    "dep:sha2",
+    "bitfun-core/agent-runtime",
+    "bitfun-core/document-read",
+    "bitfun-core/subscription-auth",
+    "bitfun-core/deep-research",
+    "bitfun-core/lsp",
+    "bitfun-core/external-sources",
+    "bitfun-core/tools-basic",
+    "bitfun-core/tools-git",
+    "bitfun-core/tools-mcp",
+    "bitfun-core/tools-browser-web",
+    "bitfun-core/tools-computer-use",
+    "bitfun-core/tools-image-analysis",
+    "bitfun-core/tools-miniapp",
+    "bitfun-core/tools-canvas",
+    "bitfun-core/tools-agent-control",
+]
+
 [lib]
 name = "bitfun_acp"
 
 [dependencies]
-bitfun-core = { path = "../../assembly/core", default-features = false, features = [
-    "agent-runtime",
-    "deep-research",
-    "lsp",
-    "external-sources",
-    "ssh-remote",
-    "tools-basic",
-    "tools-git",
-    "tools-mcp",
-    "tools-browser-web",
-    "tools-computer-use",
-    "tools-image-analysis",
-    "tools-miniapp",
-    "tools-canvas",
-    "tools-agent-control",
-] }
-bitfun-agent-runtime = { path = "../../execution/agent-runtime" }
-bitfun-agent-tools = { path = "../../execution/tool-contracts" }
+bitfun-core = { path = "../../assembly/core", optional = true }
+bitfun-agent-runtime = { path = "../../execution/agent-runtime", optional = true }
+bitfun-agent-tools = { path = "../../execution/tool-contracts", optional = true }
 bitfun-events = { path = "../../contracts/events" }
-bitfun-core-types = { path = "../../contracts/core-types" }
+bitfun-core-types = { path = "../../contracts/core-types", optional = true }
 
 agent-client-protocol = { workspace = true }
 tokio = { workspace = true, features = ["fs", "io-std", "io-util", "macros", "process", "rt", "sync", "time"] }
 tokio-util = { workspace = true, features = ["compat"] }
-futures = { workspace = true }
+futures = { workspace = true, optional = true }
 async-trait = { workspace = true }
-serde = { workspace = true }
+serde = { workspace = true, optional = true }
+dirs = { workspace = true, optional = true }
+semver = { workspace = true, optional = true }
+tar = { workspace = true, optional = true }
 serde_json = { workspace = true }
 chrono = { workspace = true }
 dashmap = { workspace = true }
 log = { workspace = true }
 uuid = { workspace = true }
-sha2 = { workspace = true }
+sha2 = { workspace = true, optional = true }
 
 [dev-dependencies]
 tokio = { workspace = true, features = ["rt-multi-thread"] }
diff --git a/src/crates/interfaces/acp/src/client/builtin_clients.rs b/src/crates/interfaces/acp/src/client/builtin_clients.rs
index e1aafbb8ec..e01f719db0 100644
--- a/src/crates/interfaces/acp/src/client/builtin_clients.rs
+++ b/src/crates/interfaces/acp/src/client/builtin_clients.rs
@@ -20,8 +20,16 @@ pub(crate) struct BuiltinAcpClientPreset {
     pub(crate) install_package: Option<&'static str>,
     pub(crate) adapter_package: Option<&'static str>,
     pub(crate) adapter_bin: Option<&'static str>,
+    /// A profile directory BitFun ships and copies into the agent's own home
+    /// before launching it. `None` — every preset but dsh — means the CLI is
+    /// self-contained and the command runs as-is.
+    pub(crate) bundled_profile: Option<&'static str>,
 }
 
+/// The profile directory BitFun materializes for DeepSeek Harness. See
+/// `dsh_profile.rs`: the bridge ships with BitFun, the harness does not.
+pub(crate) const DSH_BUNDLED_PROFILE: &str = "bitfun-acp";
+
 const BUILTIN_ACP_CLIENT_PRESETS: &[BuiltinAcpClientPreset] = &[
     BuiltinAcpClientPreset {
         id: "opencode",
@@ -31,6 +39,22 @@ const BUILTIN_ACP_CLIENT_PRESETS: &[BuiltinAcpClientPreset] = &[
         install_package: Some("opencode-ai"),
         adapter_package: None,
         adapter_bin: None,
+        bundled_profile: None,
+    },
+    // DeepSeek Harness (dsh) — the harness has no ACP entry point of its own,
+    // so BitFun ships one as a dsh PROFILE (packages/dsh-acp) and launches it
+    // through the user's own installation. The model and the API key stay in
+    // dsh, where the user configured them; BitFun stores neither. Installable
+    // from npm like codex, hence install_package; native ACP, hence no adapter.
+    BuiltinAcpClientPreset {
+        id: "dsh",
+        command: "dsh",
+        args: &["--profile", DSH_BUNDLED_PROFILE],
+        tool_command: "dsh",
+        install_package: Some("@deepseek-ai/dsh"),
+        adapter_package: None,
+        adapter_bin: None,
+        bundled_profile: Some(DSH_BUNDLED_PROFILE),
     },
     // Oh My Pi (omp) — a terminal coding agent that speaks ACP natively via
     // `omp acp` (no adapter needed, like opencode). User-managed: omp targets
@@ -46,6 +70,7 @@ const BUILTIN_ACP_CLIENT_PRESETS: &[BuiltinAcpClientPreset] = &[
         install_package: None,
         adapter_package: None,
         adapter_bin: None,
+        bundled_profile: None,
     },
     BuiltinAcpClientPreset {
         id: "claude-code",
@@ -55,6 +80,7 @@ const BUILTIN_ACP_CLIENT_PRESETS: &[BuiltinAcpClientPreset] = &[
         install_package: Some("@anthropic-ai/claude-code"),
         adapter_package: Some(CLAUDE_ACP_PACKAGE),
         adapter_bin: Some("claude-agent-acp"),
+        bundled_profile: None,
     },
     BuiltinAcpClientPreset {
         id: "codex",
@@ -64,6 +90,7 @@ const BUILTIN_ACP_CLIENT_PRESETS: &[BuiltinAcpClientPreset] = &[
         install_package: Some("@openai/codex"),
         adapter_package: Some(CODEX_ACP_PACKAGE),
         adapter_bin: Some("codex-acp"),
+        bundled_profile: None,
     },
 ];
 
@@ -152,6 +179,30 @@ mod tests {
         assert_eq!(config.args, vec!["acp"]);
     }
 
+    #[test]
+    fn dsh_preset_launches_the_bitfun_profile() {
+        let preset = builtin_acp_client_preset("dsh").expect("dsh preset registered");
+        assert_eq!(preset.command, "dsh");
+        assert_eq!(preset.tool_command, "dsh");
+        // The launch IS the profile: BitFun ships the bridge, dsh runs it.
+        assert_eq!(preset.args, &["--profile", DSH_BUNDLED_PROFILE]);
+        assert_eq!(preset.bundled_profile, Some(DSH_BUNDLED_PROFILE));
+        // Native ACP — the bridge is the profile, not a separate adapter.
+        assert!(preset.adapter_package.is_none());
+        assert!(preset.adapter_bin.is_none());
+        // The harness itself is a plain npm global, so the installer applies.
+        assert_eq!(preset.install_package, Some("@deepseek-ai/dsh"));
+
+        // Every other preset is self-contained: nothing to materialize.
+        for preset in BUILTIN_ACP_CLIENT_PRESETS.iter().filter(|p| p.id != "dsh") {
+            assert!(
+                preset.bundled_profile.is_none(),
+                "{} needs no profile",
+                preset.id
+            );
+        }
+    }
+
     #[test]
     fn migrates_only_exact_legacy_builtin_commands() {
         let mut config_file = AcpClientConfigFile {
diff --git a/src/crates/interfaces/acp/src/client/dsh_profile.rs b/src/crates/interfaces/acp/src/client/dsh_profile.rs
new file mode 100644
index 0000000000..fcd23dc5a8
--- /dev/null
+++ b/src/crates/interfaces/acp/src/client/dsh_profile.rs
@@ -0,0 +1,910 @@
+//! Materialize the bundled DeepSeek Harness bridge into the user's dsh install.
+//!
+//! BitFun ships a compiled ACP bridge, but it does not ship a harness: `dsh` is
+//! a profile launcher, and a profile is just a directory under
+//! `$DSH_HOME/profiles/`. So instead of publishing the bridge to a registry, we
+//! copy the built profile next to the harness the user already installed and
+//! launch it with `dsh --profile bitfun-acp`. Every `@deepseek-ai/dsh-*` row in
+//! that profile resolves out of the user's own installation through the flat
+//! `profiles/node_modules` fallback the launcher maintains, so nothing here
+//! installs a second harness, and the user's model and credentials — which live
+//! in dsh, not in BitFun — apply unchanged.
+//!
+//! The copy is idempotent: the built profile carries a content digest, and a
+//! destination already stamped with the same digest is left alone.
+//!
+//! A remote workspace gets the same treatment over its own transport — see
+//! [`ensure_bundled_profile_remote`] — so "works on my machine" and "works on
+//! the box I ssh into" are the same feature and not two.
+
+use std::collections::HashMap;
+use std::path::{Path, PathBuf};
+use std::time::Duration;
+
+use bitfun_core::service::remote_ssh::SSHConnectionManager;
+use bitfun_core::util::errors::{BitFunError, BitFunResult};
+use serde::Deserialize;
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+
+use super::remote_shell::{remote_user_shell_command, render_remote_env_assignments, shell_escape};
+use super::requirements::probe_executable;
+
+/// Points directly at a built profile directory, overriding every other
+/// candidate. This is how a packaged build that lays resources out unusually —
+/// or a developer testing an unbuilt tree — names the source explicitly.
+const SOURCE_DIR_ENV: &str = "BITFUN_DSH_PROFILE_DIR";
+
+/// dsh's own state directory variable. Respecting it matters: a user who moved
+/// `$DSH_HOME` keeps their models and credentials there, and a profile written
+/// under `~/.dsh` instead would simply not be found by the launcher.
+const DSH_HOME_ENV: &str = "DSH_HOME";
+
+/// Basename of the build stamp `scripts/build-profile.mjs` writes.
+const STAMP_FILENAME: &str = ".bitfun-bridge.json";
+
+/// Directories the build owns end to end, replaced rather than merged.
+///
+/// Merging would leave a previous build's emit behind — a `lib/*.js` that no
+/// longer exists in the source still resolves, and the profile boots a mix of
+/// two versions. Everything outside these three is left untouched, so anything
+/// the user added to the profile directory survives an upgrade.
+const MANAGED_SUBDIRECTORIES: &[&str] = &["lib", "presets", "node_modules"];
+
+/// What `scripts/build-profile.mjs` records about a build.
+#[derive(Debug, Deserialize)]
+struct BridgeStamp {
+    /// Digest over every path and its bytes in the built profile. A version
+    /// string would not do: during development the bridge version stands still
+    /// while its code changes, and a stale profile would look current.
+    content: String,
+    /// The oldest `@deepseek-ai/dsh` this build is known to boot against.
+    #[serde(rename = "minDshVersion")]
+    min_dsh_version: String,
+}
+
+/// Copy the bundled profile into the user's dsh install if it is not there yet.
+///
+/// Returns the profile directory the launcher will boot. Errors are the ones
+/// worth stopping for: no bundled profile to copy, a dsh too old to run it, or
+/// a filesystem that refused the write — each of which would otherwise surface
+/// as `dsh` complaining about a profile that does not exist, or as a pile of
+/// module resolution failures with no hint about the cause.
+pub(crate) async fn ensure_bundled_profile(profile: &str) -> BitFunResult<PathBuf> {
+    let (source, stamp) = bundled_build(profile)?;
+
+    // Checked on every launch, not just when copying: the pairing can break
+    // later by the user downgrading dsh under a profile that is already current.
+    require_supported_dsh(&stamp.min_dsh_version).await?;
+
+    let destination = dsh_profiles_directory()?.join(profile);
+    if read_stamp(&destination)
+        .ok()
+        .flatten()
+        .is_some_and(|installed| installed.content == stamp.content)
+    {
+        return Ok(destination);
+    }
+
+    let target = destination.clone();
+    tokio::task::spawn_blocking(move || install_profile(&source, &target))
+        .await
+        .map_err(|error| {
+            BitFunError::service(format!(
+                "Failed to install the DeepSeek Harness profile: {error}"
+            ))
+        })??;
+
+    log::info!(
+        "Installed the bundled DeepSeek Harness profile at {}",
+        destination.display()
+    );
+    Ok(destination)
+}
+
+/// The built profile this BitFun ships, and what it says about itself.
+fn bundled_build(profile: &str) -> BitFunResult<(PathBuf, BridgeStamp)> {
+    let source = bundled_profile_source(profile).ok_or_else(|| {
+        BitFunError::service(format!(
+            "The bundled DeepSeek Harness profile '{profile}' is missing from this BitFun build. \
+             Build it with `npm run build && node scripts/build-profile.mjs` in packages/dsh-acp, \
+             or point {SOURCE_DIR_ENV} at a built profile directory."
+        ))
+    })?;
+    let stamp = read_stamp(&source)?.ok_or_else(|| {
+        BitFunError::service(format!(
+            "The bundled DeepSeek Harness profile at {} has no {STAMP_FILENAME}; it is not a \
+             finished build.",
+            source.display()
+        ))
+    })?;
+    Ok((source, stamp))
+}
+
+/// Fail with an actionable message when the installed dsh predates this build.
+///
+/// A dsh we cannot find, or whose version we cannot parse, is not treated as a
+/// failure here: a missing `dsh` already surfaces as an install prompt in the
+/// agent list, and guessing about an unrecognized version string would block a
+/// launch that may well work.
+async fn require_supported_dsh(minimum: &str) -> BitFunResult<()> {
+    let Some(installed) = probe_executable("dsh").await.version else {
+        return Ok(());
+    };
+    if version_is_supported(&installed, minimum) {
+        return Ok(());
+    }
+    Err(BitFunError::service(format!(
+        "DeepSeek Harness {installed} is older than {minimum}, which this BitFun build requires. \
+         Update it with `npm install -g @deepseek-ai/dsh`."
+    )))
+}
+
+/// The oldest Node the harness can boot on.
+///
+/// `@deepseek-ai/dsh-app-boot` imports `util.parseEnv` on its very first line,
+/// and Node added that in 20.12. The harness declares no `engines` of its own,
+/// so npm installs it happily onto anything and the mismatch only surfaces as a
+/// `SyntaxError` from inside the launcher — which is not a sentence anyone can
+/// act on. Its toolchain targets Node 22 LTS; this is the floor, not the
+/// recommendation.
+const MIN_NODE_VERSION: &str = "20.12.0";
+
+/// The reported Node version, when it is too old to boot the harness.
+///
+/// Anything unparsable is not a verdict and passes: a host with no `node` on
+/// the login shell's PATH may still resolve one for `dsh` itself, and a launch
+/// that fails now says why on its own.
+fn unsupported_node_version(reported: &str) -> Option<String> {
+    let reported = reported.trim();
+    let version = semver::Version::parse(reported.trim_start_matches('v')).ok()?;
+    let minimum = semver::Version::parse(MIN_NODE_VERSION).ok()?;
+    (version < minimum).then(|| reported.to_string())
+}
+
+/// Whether `installed` is new enough for a build that needs `minimum`.
+///
+/// Unparsable on either side means "assume yes" — see the caller.
+fn version_is_supported(installed: &str, minimum: &str) -> bool {
+    let Ok(minimum) = semver::Version::parse(minimum.trim_start_matches('v')) else {
+        return true;
+    };
+    let Ok(installed) = semver::Version::parse(installed.trim().trim_start_matches('v')) else {
+        return true;
+    };
+    installed >= minimum
+}
+
+/// Locate the built profile that ships with this BitFun.
+fn bundled_profile_source(profile: &str) -> Option<PathBuf> {
+    if let Some(configured) = std::env::var_os(SOURCE_DIR_ENV) {
+        let configured = PathBuf::from(configured);
+        return configured.is_dir().then_some(configured);
+    }
+
+    let mut candidates: Vec<PathBuf> = Vec::new();
+    if let Ok(executable) = std::env::current_exe() {
+        if let Some(directory) = executable.parent() {
+            candidates.push(directory.join("resources").join("dsh-profile"));
+            if let Some(parent) = directory.parent() {
+                candidates.push(
+                    parent
+                        .join("Resources")
+                        .join("resources")
+                        .join("dsh-profile"),
+                );
+                candidates.push(parent.join("Resources").join("dsh-profile"));
+                if let Some(name) = executable.file_name().and_then(|name| name.to_str()) {
+                    candidates.push(
+                        parent
+                            .join("lib")
+                            .join(name)
+                            .join("resources")
+                            .join("dsh-profile"),
+                    );
+                    candidates.push(
+                        parent
+                            .join("share")
+                            .join(name)
+                            .join("resources")
+                            .join("dsh-profile"),
+                    );
+                }
+            }
+        }
+    }
+    // The development tree, where the build writes straight into the package.
+    candidates.push(
+        PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../../../packages/dsh-acp/dist-profile"),
+    );
+
+    candidates
+        .into_iter()
+        // A profile directory is only the right one if it is the named profile.
+        .find(|candidate| {
+            candidate.is_dir() && profile_name_of(candidate) == Some(profile.to_string())
+        })
+}
+
+/// The profile a built directory declares itself to be.
+fn profile_name_of(directory: &Path) -> Option<String> {
+    #[derive(Deserialize)]
+    struct NamedProfile {
+        profile: String,
+    }
+    let contents = std::fs::read(directory.join(STAMP_FILENAME)).ok()?;
+    serde_json::from_slice::<NamedProfile>(&contents)
+        .ok()
+        .map(|stamp| stamp.profile)
+}
+
+/// Read a build stamp, distinguishing "not installed" from "unreadable".
+fn read_stamp(directory: &Path) -> BitFunResult<Option<BridgeStamp>> {
+    let path = directory.join(STAMP_FILENAME);
+    let contents = match std::fs::read(&path) {
+        Ok(contents) => contents,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(None),
+        Err(error) => {
+            return Err(BitFunError::service(format!(
+                "Failed to read {}: {error}",
+                path.display()
+            )))
+        }
+    };
+    serde_json::from_slice(&contents)
+        .map(Some)
+        .map_err(|error| {
+            BitFunError::service(format!("Failed to parse {}: {error}", path.display()))
+        })
+}
+
+/// `$DSH_HOME/profiles`, created if the user has not run dsh yet.
+fn dsh_profiles_directory() -> BitFunResult<PathBuf> {
+    let home = match std::env::var_os(DSH_HOME_ENV) {
+        Some(home) if !home.is_empty() => PathBuf::from(home),
+        _ => dirs::home_dir()
+            .ok_or_else(|| {
+                BitFunError::service(
+                    "Cannot locate the home directory that holds the DeepSeek Harness install"
+                        .to_string(),
+                )
+            })?
+            .join(".dsh"),
+    };
+    Ok(home.join("profiles"))
+}
+
+/// Write the built profile into `destination`, stamp last.
+///
+/// The stamp is copied only after every other file lands, so an interrupted
+/// install reads as absent rather than current and is simply redone.
+fn install_profile(source: &Path, destination: &Path) -> BitFunResult<()> {
+    let write_error = |error: std::io::Error| {
+        BitFunError::service(format!(
+            "Failed to install the DeepSeek Harness profile into {}: {error}",
+            destination.display()
+        ))
+    };
+
+    // A half-written stamp is the one file that must never be believed, so drop
+    // it up front: everything below runs with the destination marked stale.
+    match std::fs::remove_file(destination.join(STAMP_FILENAME)) {
+        Ok(()) => {}
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
+        Err(error) => return Err(write_error(error)),
+    }
+    std::fs::create_dir_all(destination).map_err(write_error)?;
+    for managed in MANAGED_SUBDIRECTORIES {
+        match std::fs::remove_dir_all(destination.join(managed)) {
+            Ok(()) => {}
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
+            Err(error) => return Err(write_error(error)),
+        }
+    }
+
+    copy_tree(source, destination, true).map_err(write_error)?;
+    std::fs::copy(
+        source.join(STAMP_FILENAME),
+        destination.join(STAMP_FILENAME),
+    )
+    .map_err(write_error)?;
+    Ok(())
+}
+
+/// Copy `source` over `destination`, overwriting files and keeping extras.
+///
+/// `skip_stamp` holds for the top level only — the stamp is the install marker
+/// and its own step.
+fn copy_tree(source: &Path, destination: &Path, skip_stamp: bool) -> std::io::Result<()> {
+    std::fs::create_dir_all(destination)?;
+    for entry in std::fs::read_dir(source)? {
+        let entry = entry?;
+        let name = entry.file_name();
+        if skip_stamp && name == STAMP_FILENAME {
+            continue;
+        }
+        let target = destination.join(&name);
+        if entry.file_type()?.is_dir() {
+            copy_tree(&entry.path(), &target, false)?;
+        } else {
+            // Remove first: overwriting in place would follow a symlink the
+            // user (or a previous vendoring step) left behind.
+            match std::fs::remove_file(&target) {
+                Ok(()) => {}
+                Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
+                Err(error) => return Err(error),
+            }
+            std::fs::copy(entry.path(), &target)?;
+        }
+    }
+    Ok(())
+}
+
+// --- Remote workspaces -------------------------------------------------------
+
+/// Ceiling for the upload, so a stalled channel surfaces as an error instead of
+/// a session that silently never starts.
+const REMOTE_INSTALL_TIMEOUT: Duration = Duration::from_secs(180);
+
+/// Put the bundled profile on the far side of a remote workspace.
+///
+/// Same contract as [`ensure_bundled_profile`], expressed over a shell instead
+/// of a filesystem: a host already carrying this exact build is left alone. The
+/// harness itself stays the user's — only the bridge travels, and it travels as
+/// one tar stream over the same transport the session will use, which is what
+/// makes this work for container connections where SFTP is not available.
+///
+/// Unlike the local path, a missing remote `dsh` is fatal here: there is no
+/// install prompt in front of a remote workspace, so the only way the user
+/// learns about it is this message.
+pub(crate) async fn ensure_bundled_profile_remote(
+    profile: &str,
+    launcher: &str,
+    env: &HashMap<String, String>,
+    ssh: &SSHConnectionManager,
+    connection_id: &str,
+) -> BitFunResult<()> {
+    let (source, stamp) = bundled_build(profile)?;
+    let exports = remote_exports(env);
+
+    let probe_command =
+        remote_user_shell_command(&remote_probe_script(profile, launcher, &exports));
+    let (stdout, stderr, code) = ssh
+        .execute_command(connection_id, &probe_command)
+        .await
+        .map_err(|error| {
+            BitFunError::service(format!(
+                "Failed to inspect the DeepSeek Harness install on the remote host: {error}"
+            ))
+        })?;
+    if code != 0 {
+        return Err(BitFunError::service(format!(
+            "Failed to inspect the DeepSeek Harness install on the remote host: {}",
+            remote_failure_summary(&stderr, &stdout)
+        )));
+    }
+    let probe = parse_remote_probe(&stdout);
+
+    // Presence is `command -v`, the same question the agent list asks. Asking a
+    // different one here is how the list ends up saying "installed" while the
+    // launch says "not installed".
+    if probe.launcher.is_empty() {
+        return Err(BitFunError::service(format!(
+            "DeepSeek Harness is not installed on the remote host: `{launcher}` is not on the login \
+             shell's PATH. Install it there with `npm install -g @deepseek-ai/dsh`; BitFun ships \
+             the bridge, not the harness."
+        )));
+    }
+    // The harness is a Node program, and it declares no `engines`, so an old
+    // Node installs it without complaint and then fails to boot it. Say that
+    // here rather than letting the user read a SyntaxError out of a log.
+    if let Some(node) = unsupported_node_version(&probe.node) {
+        return Err(BitFunError::service(format!(
+            "The remote host runs Node {node}, and DeepSeek Harness needs at least \
+             {MIN_NODE_VERSION} to start (its own toolchain targets Node 22 LTS). Install a newer \
+             Node on that host, then start the session again."
+        )));
+    }
+    if !version_is_supported(&probe.version, &stamp.min_dsh_version) {
+        return Err(BitFunError::service(format!(
+            "The remote host runs DeepSeek Harness {}, which is older than {}, the version this \
+             BitFun build requires. Update it there with `npm install -g @deepseek-ai/dsh`.",
+            probe.version, stamp.min_dsh_version
+        )));
+    }
+    if serde_json::from_str::<BridgeStamp>(&probe.stamp)
+        .is_ok_and(|installed| installed.content == stamp.content)
+    {
+        return Ok(());
+    }
+
+    let archive = tokio::task::spawn_blocking(move || archive_profile(&source))
+        .await
+        .map_err(|error| {
+            BitFunError::service(format!(
+                "Failed to package the DeepSeek Harness profile for upload: {error}"
+            ))
+        })??;
+
+    let install_command = remote_user_shell_command(&remote_install_script(profile, &exports));
+    let transport = ssh
+        .open_workspace_stdio(connection_id, &install_command)
+        .await
+        .map_err(|error| {
+            BitFunError::service(format!(
+                "Failed to install the DeepSeek Harness profile on the remote host: {error}"
+            ))
+        })?;
+    // Every stream stays bound: dropping all three cancels the command, and the
+    // extraction is only over once `completion` says so.
+    let (mut stdin, _stdout, mut stderr, _control, completion) = transport.into_parts();
+
+    let upload = async {
+        stdin.write_all(&archive).await.map_err(|error| {
+            BitFunError::service(format!(
+                "Failed to send the DeepSeek Harness profile to the remote host: {error}"
+            ))
+        })?;
+        // The remote `tar` reads until end of input, so the shutdown is what
+        // ends the extraction rather than a timeout.
+        stdin.shutdown().await.map_err(|error| {
+            BitFunError::service(format!(
+                "Failed to send the DeepSeek Harness profile to the remote host: {error}"
+            ))
+        })?;
+        Ok::<_, BitFunError>(completion.wait().await)
+    };
+
+    let exit = tokio::time::timeout(REMOTE_INSTALL_TIMEOUT, upload)
+        .await
+        .map_err(|_| {
+            BitFunError::service(
+                "Timed out installing the DeepSeek Harness profile on the remote host".to_string(),
+            )
+        })??;
+
+    if exit.exit_code != Some(0) {
+        // The launch path sinks remote stderr, so without this the failure would
+        // reach the user as an unexplained missing profile.
+        let mut diagnostics = String::new();
+        let _ = tokio::time::timeout(
+            Duration::from_secs(5),
+            stderr.read_to_string(&mut diagnostics),
+        )
+        .await;
+        let summary = remote_failure_summary(&diagnostics, "");
+        return Err(BitFunError::service(format!(
+            "Failed to install the DeepSeek Harness profile on the remote host (exit {}){}",
+            exit.exit_code
+                .map(|code| code.to_string())
+                .unwrap_or_else(|| "unknown".to_string()),
+            if summary.is_empty() {
+                String::new()
+            } else {
+                format!(": {summary}")
+            }
+        )));
+    }
+
+    log::info!(
+        "Installed the bundled DeepSeek Harness profile on the remote host at {}/{profile}",
+        probe.profiles
+    );
+    Ok(())
+}
+
+/// What the remote host says about its dsh install and this profile.
+#[derive(Debug, Default, PartialEq)]
+struct RemoteProbe {
+    /// `$DSH_HOME/profiles` as the remote shell expands it. Reported for the
+    /// log line only — the install script resolves it again on its own, so the
+    /// two never travel through a quoting round trip.
+    profiles: String,
+    /// Where the remote login shell resolves the launcher, or empty when it
+    /// resolves nowhere. This — not the version below — is what "installed"
+    /// means, because it is what the agent list's own probe asks.
+    launcher: String,
+    /// First line of `dsh --version`, on either stream. Best effort: a launcher
+    /// that answers nothing is still a launcher.
+    version: String,
+    /// What `node --version` says on that host, or empty. The harness is a Node
+    /// program, so this is half of whether it can start at all.
+    node: String,
+    /// The installed build stamp, verbatim, or empty when the profile is new.
+    stamp: String,
+}
+
+/// Environment the workspace configures, applied to the profile shell too.
+///
+/// A workspace that points `DSH_HOME` or `PATH` somewhere unusual has to reach
+/// the same install the session will boot from, or we would upload the bridge
+/// next to a harness nobody runs.
+fn remote_exports(env: &HashMap<String, String>) -> String {
+    let assignments = render_remote_env_assignments(env);
+    if assignments.is_empty() {
+        return String::new();
+    }
+    format!("export {}\n", assignments.join(" "))
+}
+
+/// One round trip that answers all three questions.
+fn remote_probe_script(profile: &str, launcher: &str, exports: &str) -> String {
+    let profile = shell_escape(profile);
+    let launcher = shell_escape(launcher);
+    format!(
+        "{exports}profiles=\"${{DSH_HOME:-$HOME/.dsh}}/profiles\"\n\
+         printf 'profiles=%s\\n' \"$profiles\"\n\
+         printf 'launcher=%s\\n' \"$(command -v {launcher} 2>/dev/null | head -n 1 | tr -d '\\r')\"\n\
+         printf 'version=%s\\n' \"$({launcher} --version 2>&1 | head -n 1 | tr -d '\\r')\"\n\
+         printf 'node=%s\\n' \"$(node --version 2>/dev/null | head -n 1 | tr -d '\\r')\"\n\
+         printf 'stamp=%s\\n' \"$(cat \"$profiles\"/{profile}/{STAMP_FILENAME} 2>/dev/null | tr -d '\\n\\r')\"\n"
+    )
+}
+
+/// Read the probe's answers, ignoring whatever the login shell printed around
+/// them.
+fn parse_remote_probe(stdout: &str) -> RemoteProbe {
+    let mut probe = RemoteProbe::default();
+    for line in stdout.lines() {
+        let line = line.trim();
+        if let Some(value) = line.strip_prefix("profiles=") {
+            probe.profiles = value.to_string();
+        } else if let Some(value) = line.strip_prefix("launcher=") {
+            probe.launcher = value.to_string();
+        } else if let Some(value) = line.strip_prefix("version=") {
+            probe.version = value.to_string();
+        } else if let Some(value) = line.strip_prefix("node=") {
+            probe.node = value.to_string();
+        } else if let Some(value) = line.strip_prefix("stamp=") {
+            probe.stamp = value.to_string();
+        }
+    }
+    probe
+}
+
+/// Clear the managed directories, then extract what arrives on stdin.
+///
+/// The mirror of [`install_profile`]: same directories replaced rather than
+/// merged, same everything-else left alone, and the stamp removed up front so
+/// an interrupted upload reads as stale.
+fn remote_install_script(profile: &str, exports: &str) -> String {
+    let profile = shell_escape(profile);
+    let managed = MANAGED_SUBDIRECTORIES
+        .iter()
+        .map(|directory| format!("\"$destination\"/{directory}"))
+        .collect::<Vec<_>>()
+        .join(" ");
+    format!(
+        "set -e\n\
+         {exports}profiles=\"${{DSH_HOME:-$HOME/.dsh}}/profiles\"\n\
+         destination=\"$profiles\"/{profile}\n\
+         mkdir -p \"$destination\"\n\
+         rm -f \"$destination\"/{STAMP_FILENAME}\n\
+         rm -rf {managed}\n\
+         exec tar -xf - -C \"$destination\"\n"
+    )
+}
+
+/// Pack the built profile, stamp last.
+///
+/// Ordering is the whole point: `tar` writes entries in the order they appear,
+/// so a transfer that dies halfway leaves a destination without a current stamp
+/// and the next launch simply redoes it.
+fn archive_profile(source: &Path) -> BitFunResult<Vec<u8>> {
+    let pack_error = |error: std::io::Error| {
+        BitFunError::service(format!(
+            "Failed to package the DeepSeek Harness profile at {}: {error}",
+            source.display()
+        ))
+    };
+
+    let mut paths = Vec::new();
+    collect_relative_files(source, Path::new(""), &mut paths).map_err(pack_error)?;
+    // Deterministic order, so an unchanged build produces an identical stream.
+    paths.sort();
+
+    let stamp = Path::new(STAMP_FILENAME);
+    let mut builder = tar::Builder::new(Vec::new());
+    for relative in paths.iter().filter(|path| path.as_path() != stamp) {
+        builder
+            .append_path_with_name(source.join(relative), relative)
+            .map_err(pack_error)?;
+    }
+    builder
+        .append_path_with_name(source.join(stamp), stamp)
+        .map_err(pack_error)?;
+    builder.into_inner().map_err(pack_error)
+}
+
+/// Every file under `root/relative`, as paths relative to `root`.
+fn collect_relative_files(
+    root: &Path,
+    relative: &Path,
+    out: &mut Vec<PathBuf>,
+) -> std::io::Result<()> {
+    for entry in std::fs::read_dir(root.join(relative))? {
+        let entry = entry?;
+        let child = relative.join(entry.file_name());
+        if entry.file_type()?.is_dir() {
+            collect_relative_files(root, &child, out)?;
+        } else {
+            out.push(child);
+        }
+    }
+    Ok(())
+}
+
+/// The most useful line of a failed remote command, bounded in length.
+fn remote_failure_summary(stderr: &str, stdout: &str) -> String {
+    let text = if stderr.trim().is_empty() {
+        stdout.trim()
+    } else {
+        stderr.trim()
+    };
+    if text.len() <= 400 {
+        return text.to_string();
+    }
+    let mut cut = 400;
+    while cut > 0 && !text.is_char_boundary(cut) {
+        cut -= 1;
+    }
+    format!("{}…", &text[..cut])
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn scratch_directory(label: &str) -> PathBuf {
+        let path =
+            std::env::temp_dir().join(format!("bitfun-dsh-{label}-{}", uuid::Uuid::new_v4()));
+        std::fs::create_dir_all(&path).expect("scratch directory should be created");
+        path
+    }
+
+    fn write_built_profile(root: &Path, content: &str) {
+        std::fs::create_dir_all(root.join("lib")).expect("lib should be created");
+        std::fs::write(root.join("lib/app.js"), content).expect("app should be written");
+        std::fs::write(root.join("cordis.patch.yml"), "- insert: []\n").expect("patch");
+        std::fs::write(
+            root.join(STAMP_FILENAME),
+            format!(
+                r#"{{"bridge":"0.0.1","content":"{content}","minDshVersion":"0.1.0-rc.6","profile":"bitfun-acp"}}"#
+            ),
+        )
+        .expect("stamp should be written");
+    }
+
+    #[test]
+    fn installs_the_built_profile_and_replaces_a_previous_build() {
+        let source = scratch_directory("source");
+        let destination = scratch_directory("destination");
+        write_built_profile(&source, "first");
+
+        install_profile(&source, &destination).expect("first install");
+        assert_eq!(
+            std::fs::read_to_string(destination.join("lib/app.js")).expect("app"),
+            "first"
+        );
+
+        // A file the previous build emitted but this one does not must not
+        // survive into a tree that now claims to be the new build.
+        std::fs::write(destination.join("lib/stale.js"), "stale").expect("stale file");
+        // Anything outside the managed directories is the user's, and stays.
+        std::fs::write(destination.join("notes.md"), "mine").expect("user file");
+
+        write_built_profile(&source, "second");
+        install_profile(&source, &destination).expect("second install");
+
+        assert_eq!(
+            std::fs::read_to_string(destination.join("lib/app.js")).expect("app"),
+            "second"
+        );
+        assert!(!destination.join("lib/stale.js").exists());
+        assert_eq!(
+            std::fs::read_to_string(destination.join("notes.md")).expect("user file"),
+            "mine"
+        );
+
+        let _ = std::fs::remove_dir_all(&source);
+        let _ = std::fs::remove_dir_all(&destination);
+    }
+
+    #[test]
+    fn reads_the_content_digest_that_decides_whether_to_reinstall() {
+        let source = scratch_directory("stamp");
+        write_built_profile(&source, "digest");
+
+        let stamp = read_stamp(&source)
+            .expect("stamp should be readable")
+            .expect("stamp should be present");
+        assert_eq!(stamp.content, "digest");
+        assert_eq!(stamp.min_dsh_version, "0.1.0-rc.6");
+        assert_eq!(profile_name_of(&source).as_deref(), Some("bitfun-acp"));
+
+        let empty = scratch_directory("stamp-empty");
+        assert!(read_stamp(&empty)
+            .expect("a missing stamp is not an error")
+            .is_none());
+
+        let _ = std::fs::remove_dir_all(&source);
+        let _ = std::fs::remove_dir_all(&empty);
+    }
+
+    #[test]
+    fn compares_prerelease_harness_versions() {
+        assert!(version_is_supported("0.1.0-rc.6", "0.1.0-rc.6"));
+        assert!(version_is_supported("0.1.0-rc.7", "0.1.0-rc.6"));
+        assert!(version_is_supported("0.1.0", "0.1.0-rc.6"));
+        assert!(version_is_supported("1.2.3", "0.1.0-rc.6"));
+        assert!(!version_is_supported("0.1.0-rc.5", "0.1.0-rc.6"));
+        assert!(!version_is_supported("0.0.9", "0.1.0-rc.6"));
+        // A version we cannot read must not block a launch that may work.
+        assert!(version_is_supported("dsh dev build", "0.1.0-rc.6"));
+    }
+
+    #[test]
+    fn source_lookup_honours_the_override_and_checks_the_profile_name() {
+        let source = scratch_directory("override");
+        write_built_profile(&source, "override");
+
+        temp_env(
+            SOURCE_DIR_ENV,
+            Some(source.to_string_lossy().as_ref()),
+            || {
+                assert_eq!(
+                    bundled_profile_source("bitfun-acp").as_deref(),
+                    Some(source.as_path())
+                );
+            },
+        );
+        // Without the override, a directory that names a different profile is
+        // not a match — the repo checkout below it may still be.
+        assert_ne!(profile_name_of(&source).as_deref(), Some("other"));
+
+        let _ = std::fs::remove_dir_all(&source);
+    }
+
+    #[test]
+    fn the_remote_probe_answers_every_question_in_one_round_trip() {
+        let script = remote_probe_script("bitfun-acp", "dsh", "");
+
+        // $DSH_HOME is resolved on the far side: reading it here would point at
+        // the developer's own install, not the workspace's.
+        assert!(script.contains("profiles=\"${DSH_HOME:-$HOME/.dsh}/profiles\""));
+        assert!(script.contains("command -v dsh"));
+        // Both streams: a launcher that prints its version on stderr is still
+        // installed, and treating that as absent blocks a working host.
+        assert!(script.contains("dsh --version 2>&1"));
+        // The harness is a Node program; asking in the same round trip costs
+        // nothing and is the difference between a sentence and a stack trace.
+        assert!(script.contains("node --version"));
+        assert!(script.contains(STAMP_FILENAME));
+
+        let probe = parse_remote_probe(concat!(
+            "Welcome to Ubuntu\n",
+            "profiles=/home/dev/.dsh/profiles\n",
+            "launcher=/usr/local/bin/dsh\n",
+            "version=0.1.0-rc.6\n",
+            "node=v22.19.0\n",
+            r#"stamp={"content":"abc","minDshVersion":"0.1.0-rc.6"}"#,
+            "\n",
+        ));
+        assert_eq!(probe.profiles, "/home/dev/.dsh/profiles");
+        assert_eq!(probe.launcher, "/usr/local/bin/dsh");
+        assert_eq!(probe.version, "0.1.0-rc.6");
+        assert_eq!(probe.node, "v22.19.0");
+        assert_eq!(
+            probe.stamp,
+            r#"{"content":"abc","minDshVersion":"0.1.0-rc.6"}"#
+        );
+
+        // A host without dsh reports empty rather than nothing at all, so the
+        // caller can tell "not installed" from "the probe never ran".
+        let missing =
+            parse_remote_probe("profiles=/root/.dsh/profiles\nlauncher=\nversion=\nstamp=\n");
+        assert_eq!(missing.launcher, "");
+        assert_eq!(missing.version, "");
+        assert_eq!(missing.stamp, "");
+
+        // Installed but mute: the version gate lets an unparsable answer
+        // through, so this host launches instead of being turned away.
+        let mute = parse_remote_probe("launcher=/usr/local/bin/dsh\nversion=\nstamp=\n");
+        assert!(!mute.launcher.is_empty());
+        assert!(version_is_supported(&mute.version, "0.1.0-rc.6"));
+    }
+
+    #[test]
+    fn a_node_too_old_for_the_harness_is_named_before_the_launch() {
+        // The version that sent us here: dsh's first import is `util.parseEnv`,
+        // which this Node does not have, and npm installed it anyway.
+        assert_eq!(
+            unsupported_node_version("v18.19.1").as_deref(),
+            Some("v18.19.1")
+        );
+        assert_eq!(
+            unsupported_node_version("v20.11.1").as_deref(),
+            Some("v20.11.1")
+        );
+
+        // At or above the floor, and anything we cannot read, launches. A host
+        // whose login shell has no `node` may still resolve one for `dsh`.
+        assert_eq!(unsupported_node_version("v20.12.0"), None);
+        assert_eq!(unsupported_node_version("v24.4.0"), None);
+        assert_eq!(unsupported_node_version(""), None);
+        assert_eq!(
+            unsupported_node_version("bash: node: command not found"),
+            None
+        );
+    }
+
+    #[test]
+    fn the_remote_install_replaces_exactly_what_the_local_one_replaces() {
+        let script = remote_install_script("bitfun-acp", "export DSH_HOME=/opt/dsh\n");
+
+        assert!(script.starts_with("set -e\n"));
+        assert!(script.contains("export DSH_HOME=/opt/dsh"));
+        assert!(script.contains(&format!("rm -f \"$destination\"/{STAMP_FILENAME}")));
+        for managed in MANAGED_SUBDIRECTORIES {
+            assert!(script.contains(&format!("\"$destination\"/{managed}")));
+        }
+        // Nothing outside the managed set is removed — a user's own files in
+        // the profile directory survive an upgrade here too.
+        assert!(!script.contains("rm -rf \"$destination\"\n"));
+        assert!(script.contains("exec tar -xf - -C \"$destination\""));
+    }
+
+    #[test]
+    fn the_uploaded_archive_carries_the_stamp_last() {
+        let source = scratch_directory("archive");
+        write_built_profile(&source, "packed");
+
+        let archive = archive_profile(&source).expect("profile should pack");
+        let entries: Vec<String> = tar::Archive::new(archive.as_slice())
+            .entries()
+            .expect("entries")
+            .map(|entry| {
+                entry
+                    .expect("entry")
+                    .path()
+                    .expect("path")
+                    .display()
+                    .to_string()
+            })
+            .collect();
+
+        assert!(entries.contains(&"lib/app.js".to_string()));
+        assert!(entries.contains(&"cordis.patch.yml".to_string()));
+        // Last, so an interrupted upload leaves a profile that reads as stale.
+        assert_eq!(entries.last().map(String::as_str), Some(STAMP_FILENAME));
+
+        let _ = std::fs::remove_dir_all(&source);
+    }
+
+    #[test]
+    fn remote_exports_only_carry_what_the_workspace_configured() {
+        assert_eq!(remote_exports(&HashMap::new()), "");
+        assert_eq!(
+            remote_exports(&HashMap::from([(
+                "DSH_HOME".to_string(),
+                "/opt/dsh home".to_string()
+            )])),
+            "export DSH_HOME='/opt/dsh home'\n"
+        );
+    }
+
+    /// Set an environment variable for the duration of `body`.
+    ///
+    /// Tests in one binary share a process, so this restores what it found.
+    fn temp_env(key: &str, value: Option<&str>, body: impl FnOnce()) {
+        let previous = std::env::var_os(key);
+        match value {
+            Some(value) => std::env::set_var(key, value),
+            None => std::env::remove_var(key),
+        }
+        body();
+        match previous {
+            Some(previous) => std::env::set_var(key, previous),
+            None => std::env::remove_var(key),
+        }
+    }
+}
diff --git a/src/crates/interfaces/acp/src/client/manager.rs b/src/crates/interfaces/acp/src/client/manager.rs
index 8e6563ec3d..28641b80b2 100644
--- a/src/crates/interfaces/acp/src/client/manager.rs
+++ b/src/crates/interfaces/acp/src/client/manager.rs
@@ -36,12 +36,14 @@ use tokio::sync::{oneshot, Mutex, RwLock};
 use tokio_util::compat::{TokioAsyncReadCompatExt, TokioAsyncWriteCompatExt};
 
 use super::builtin_clients::{
-    builtin_client_ids, default_config_for_builtin_client, migrate_legacy_builtin_client_configs,
+    builtin_acp_client_preset, builtin_client_ids, default_config_for_builtin_client,
+    migrate_legacy_builtin_client_configs,
 };
 use super::config::{
     AcpClientConfig, AcpClientConfigFile, AcpClientInfo, AcpClientPermissionMode,
     AcpClientRequirementProbe, AcpClientStatus, RemoteAcpClientRequirementSnapshot,
 };
+use super::dsh_profile::{ensure_bundled_profile, ensure_bundled_profile_remote};
 use super::remote_capability_store::RemoteAcpCapabilityStore;
 use super::remote_session::{preferred_resume_strategies, AcpRemoteSessionStrategy};
 use super::remote_shell::{remote_user_shell_command, render_remote_env_assignments, shell_escape};
@@ -625,7 +627,7 @@ impl AcpClientService {
                 .await
             }
         };
-        let (transport, child) = match transport_result {
+        let (transport, child, stderr_tail) = match transport_result {
             Ok(result) => result,
             Err(error) => {
                 *connection.status.write().await = AcpClientStatus::Failed;
@@ -696,9 +698,12 @@ impl AcpClientService {
             Ok(Err(_)) => {
                 connect_task.abort();
                 self.cleanup_failed_startup(connection_id).await;
-                return Err(BitFunError::service(format!(
-                    "ACP client '{}' exited before initialization completed",
-                    client_id
+                // The agent is gone; whatever it managed to say on the way out
+                // is all anyone has to go on, so put it in front of the user
+                // rather than only in the log.
+                return Err(BitFunError::service(startup_exit_error_message(
+                    client_id,
+                    &stderr_tail.drained_detail().await,
                 )));
             }
             Err(_) => {
@@ -1716,14 +1721,29 @@ impl AcpClientService {
         client_id: &str,
         connection_id: &str,
         config: &AcpClientConfig,
-    ) -> BitFunResult<(ByteStreams<AcpOutgoingStream, AcpIncomingStream>, Child)> {
+    ) -> BitFunResult<(
+        ByteStreams<AcpOutgoingStream, AcpIncomingStream>,
+        Child,
+        StderrTail,
+    )> {
+        // An agent whose runtime BitFun ships (dsh) needs it in place before the
+        // command runs, because the command's only job is to boot it.
+        if let Some(profile) = builtin_acp_client_preset(client_id).and_then(|p| p.bundled_profile)
+        {
+            ensure_bundled_profile(profile).await?;
+        }
+
         let program = resolve_configured_command(&config.command, &config.env);
         let mut command = bitfun_core::util::process_manager::create_tokio_command(&program);
         command
             .args(&config.args)
             .stdin(Stdio::piped())
             .stdout(Stdio::piped())
-            .stderr(Stdio::inherit());
+            // Inheriting sent this to a terminal that a packaged app does not
+            // have, so a local agent that died at startup was as silent as a
+            // remote one. Read it instead: it goes to the log, and its tail
+            // goes into the error the user is shown.
+            .stderr(Stdio::piped());
         apply_command_environment(&mut command, Some(&config.env));
         configure_process_group(&mut command);
 
@@ -1755,9 +1775,15 @@ impl AcpClientService {
             }
         };
 
+        let stderr_tail = match child.stderr.take() {
+            Some(stderr) => spawn_stderr_reader(client_id, stderr),
+            None => StderrTail::default(),
+        };
+
         Ok((
             ByteStreams::new(Box::pin(stdin.compat_write()), Box::pin(stdout.compat())),
             child,
+            stderr_tail,
         ))
     }
 
@@ -1771,16 +1797,17 @@ impl AcpClientService {
     ) -> BitFunResult<(
         ByteStreams<AcpOutgoingStream, AcpIncomingStream>,
         Option<Child>,
+        StderrTail,
     )> {
         match remote_connection_id {
             Some(remote_connection_id) => self
                 .start_remote_transport(client_id, config, workspace_path, remote_connection_id)
                 .await
-                .map(|transport| (transport, None)),
+                .map(|(transport, stderr_tail)| (transport, None, stderr_tail)),
             None => self
                 .start_local_transport(client_id, connection_id, config)
                 .await
-                .map(|(transport, child)| (transport, Some(child))),
+                .map(|(transport, child, stderr_tail)| (transport, Some(child), stderr_tail)),
         }
     }
 
@@ -1790,7 +1817,10 @@ impl AcpClientService {
         config: &AcpClientConfig,
         workspace_path: Option<&str>,
         remote_connection_id: &str,
-    ) -> BitFunResult<ByteStreams<AcpOutgoingStream, AcpIncomingStream>> {
+    ) -> BitFunResult<(
+        ByteStreams<AcpOutgoingStream, AcpIncomingStream>,
+        StderrTail,
+    )> {
         let command = render_remote_client_command(config, workspace_path)?;
         let remote_manager = get_remote_workspace_manager().ok_or_else(|| {
             BitFunError::service("Remote workspace manager is not initialized".to_string())
@@ -1798,6 +1828,19 @@ impl AcpClientService {
         let ssh_manager = remote_manager.get_ssh_manager().await.ok_or_else(|| {
             BitFunError::service("SSH manager is not available for remote ACP".to_string())
         })?;
+        // Same reason as `start_local_transport`: the command below only boots
+        // the runtime BitFun ships, so it has to be on that host first.
+        if let Some(profile) = builtin_acp_client_preset(client_id).and_then(|p| p.bundled_profile)
+        {
+            ensure_bundled_profile_remote(
+                profile,
+                config.command.trim(),
+                &config.env,
+                &ssh_manager,
+                remote_connection_id,
+            )
+            .await?;
+        }
         let transport = ssh_manager
             .open_workspace_stdio(remote_connection_id, &command)
             .await
@@ -1807,14 +1850,24 @@ impl AcpClientService {
                     client_id, error
                 ))
             })?;
-        let (writer, reader, mut stderr, _control, _completion) = transport.into_parts();
+        let (writer, reader, stderr, _control, completion) = transport.into_parts();
+        // Whatever the remote agent says on its way out is the only explanation
+        // a user gets when it dies at startup; sinking it leaves nothing behind
+        // but an unexplained broken pipe.
+        let stderr_tail = spawn_stderr_reader(client_id, stderr);
+        // An agent that dies mid-session leaves the same broken pipe behind as
+        // one that never started, so record which it was.
+        let exit_client_id = client_id.to_string();
         tokio::spawn(async move {
-            let mut sink = tokio::io::sink();
-            let _ = tokio::io::copy(&mut stderr, &mut sink).await;
+            let exit = completion.wait().await;
+            log::info!(
+                "Remote ACP client exited: id={exit_client_id} exit_code={:?}",
+                exit.exit_code
+            );
         });
-        Ok(ByteStreams::new(
-            Box::pin(writer.compat_write()),
-            Box::pin(reader.compat()),
+        Ok((
+            ByteStreams::new(Box::pin(writer.compat_write()), Box::pin(reader.compat())),
+            stderr_tail,
         ))
     }
 
@@ -2508,6 +2561,114 @@ fn protocol_error(error: impl std::fmt::Display) -> BitFunError {
     BitFunError::service(format!("ACP protocol error: {}", error))
 }
 
+/// The last lines an agent wrote to stderr, kept so a startup failure can say
+/// why it failed rather than only that it did.
+///
+/// An agent that dies before answering `initialize` leaves nothing behind but a
+/// closed pipe. Its stderr is the whole account of what went wrong — a missing
+/// runtime, a Node too old for it, a config it refused — and a log file is not
+/// where the user is looking when the dialog says the session did not start.
+#[derive(Clone)]
+struct StderrTail {
+    lines: Arc<std::sync::Mutex<std::collections::VecDeque<String>>>,
+    /// Turns true once the reader reaches EOF.
+    drained: tokio::sync::watch::Receiver<bool>,
+}
+
+impl Default for StderrTail {
+    fn default() -> Self {
+        // Nothing will ever be written to this one, so it starts drained: the
+        // wait below sees a value that already satisfies it and returns at once.
+        let (_sender, drained) = tokio::sync::watch::channel(true);
+        Self {
+            lines: Arc::default(),
+            drained,
+        }
+    }
+}
+
+/// How many lines to keep, and how many of those to put in an error message.
+/// A stack trace is worth keeping whole in the log and worth quoting only in
+/// part in a dialog.
+const STDERR_TAIL_LINES: usize = 20;
+const STDERR_DETAIL_LINES: usize = 8;
+/// How long to let stderr finish arriving after the agent's pipes close.
+const STDERR_DRAIN_GRACE: Duration = Duration::from_millis(500);
+
+impl StderrTail {
+    fn record(&self, line: &str) {
+        let Ok(mut lines) = self.lines.lock() else {
+            return;
+        };
+        if lines.len() == STDERR_TAIL_LINES {
+            lines.pop_front();
+        }
+        lines.push_back(line.to_string());
+    }
+
+    /// Wait for the reader to reach EOF, then quote the tail.
+    ///
+    /// The pipe closing is what tells the connect task the agent is gone, and
+    /// the last lines it wrote can still be in flight when that happens — a
+    /// stack trace quoted without its final line is the one line that mattered.
+    async fn drained_detail(&self) -> String {
+        let mut drained = self.drained.clone();
+        let _ =
+            tokio::time::timeout(STDERR_DRAIN_GRACE, drained.wait_for(|drained| *drained)).await;
+        self.detail()
+    }
+
+    fn detail(&self) -> String {
+        let Ok(lines) = self.lines.lock() else {
+            return String::new();
+        };
+        let start = lines.len().saturating_sub(STDERR_DETAIL_LINES);
+        lines
+            .iter()
+            .skip(start)
+            .cloned()
+            .collect::<Vec<_>>()
+            .join("\n")
+    }
+}
+
+/// Drain an agent's stderr into the log, keeping the tail for the error message.
+fn spawn_stderr_reader<R>(client_id: &str, stderr: R) -> StderrTail
+where
+    R: tokio::io::AsyncRead + Unpin + Send + 'static,
+{
+    let (drained_tx, drained_rx) = tokio::sync::watch::channel(false);
+    let tail = StderrTail {
+        lines: Arc::default(),
+        drained: drained_rx,
+    };
+    let client_id = client_id.to_string();
+    let sink = tail.clone();
+    tokio::spawn(async move {
+        use tokio::io::AsyncBufReadExt;
+
+        let mut lines = tokio::io::BufReader::new(stderr).lines();
+        while let Ok(Some(line)) = lines.next_line().await {
+            let line = line.trim_end();
+            if line.trim().is_empty() {
+                continue;
+            }
+            warn!("ACP client stderr: id={client_id} {line}");
+            sink.record(line);
+        }
+        let _ = drained_tx.send(true);
+    });
+    tail
+}
+
+fn startup_exit_error_message(client_id: &str, stderr_detail: &str) -> String {
+    let base = format!("ACP client '{client_id}' exited before initialization completed");
+    if stderr_detail.trim().is_empty() {
+        return base;
+    }
+    format!("{base}. It said:\n{stderr_detail}")
+}
+
 const STARTUP_TIMEOUT_ERROR_PREFIX: &str = "ACP startup timed out:";
 
 fn startup_timeout_error(client_id: &str, phase: &str) -> BitFunError {
@@ -2652,6 +2813,50 @@ mod tests {
         );
     }
 
+    #[test]
+    fn a_startup_failure_quotes_what_the_agent_said() {
+        // Verbatim from a remote host whose Node was too old for the harness.
+        // Without these lines the message is "it exited", which is the one
+        // thing the user already knows.
+        let said = "SyntaxError: The requested module 'node:util' does not provide an export named 'parseEnv'\nNode.js v18.19.1";
+        assert_eq!(
+            startup_exit_error_message("dsh", said),
+            format!("ACP client 'dsh' exited before initialization completed. It said:\n{said}")
+        );
+
+        // An agent that died silently gets the plain sentence, not a dangling
+        // colon over an empty quote.
+        assert_eq!(
+            startup_exit_error_message("dsh", "   "),
+            "ACP client 'dsh' exited before initialization completed"
+        );
+    }
+
+    #[tokio::test]
+    async fn the_stderr_tail_keeps_the_last_lines_and_waits_for_eof() {
+        let (mut writer, reader) = tokio::io::duplex(1024);
+        let tail = spawn_stderr_reader("dsh", reader);
+
+        let mut written = String::new();
+        for line in 0..STDERR_TAIL_LINES + 4 {
+            written.push_str(&format!("line {line}\n"));
+        }
+        tokio::io::AsyncWriteExt::write_all(&mut writer, written.as_bytes())
+            .await
+            .unwrap();
+        drop(writer);
+
+        // The wait is what makes this deterministic: the reader is still
+        // draining when a dead agent's pipes close.
+        let detail = tail.drained_detail().await;
+        let lines = detail.lines().collect::<Vec<_>>();
+        assert_eq!(lines.len(), STDERR_DETAIL_LINES);
+        assert_eq!(
+            lines.last().copied(),
+            Some(format!("line {}", STDERR_TAIL_LINES + 3).as_str())
+        );
+    }
+
     #[test]
     fn maps_session_config_values_to_acp_protocol_values() {
         let select = AcpSessionConfigValue::Select {
@@ -2721,4 +2926,18 @@ mod tests {
         assert_eq!(resolved.env.get("BASE").map(String::as_str), Some("1"));
         assert!(resolved.enabled);
     }
+
+    #[test]
+    fn resolves_builtin_dsh_config_for_remote_workspace() {
+        let resolved =
+            resolve_config_for_client(&AcpClientConfigFile::default(), "dsh", Some("remote-host"))
+                .expect("built-in DSH config");
+
+        assert_eq!(resolved.command, "dsh");
+        // A remote workspace resolves the same launch as a local one, and both
+        // transports materialize the profile first, so the command finds it
+        // there either way.
+        assert_eq!(resolved.args, vec!["--profile", "bitfun-acp"]);
+        assert!(resolved.enabled);
+    }
 }
diff --git a/src/crates/interfaces/acp/src/client/mod.rs b/src/crates/interfaces/acp/src/client/mod.rs
index 12fce4ead6..5723ab5866 100644
--- a/src/crates/interfaces/acp/src/client/mod.rs
+++ b/src/crates/interfaces/acp/src/client/mod.rs
@@ -1,5 +1,6 @@
 mod builtin_clients;
 mod config;
+mod dsh_profile;
 mod manager;
 mod remote_capability_store;
 mod remote_session;
diff --git a/src/crates/interfaces/acp/src/client/session_persistence.rs b/src/crates/interfaces/acp/src/client/session_persistence.rs
index 6855be1bdd..41302ffb92 100644
--- a/src/crates/interfaces/acp/src/client/session_persistence.rs
+++ b/src/crates/interfaces/acp/src/client/session_persistence.rs
@@ -3,13 +3,19 @@ use std::sync::Arc;
 
 use bitfun_core::agentic::persistence::PersistenceManager;
 use bitfun_core::infrastructure::PathManager;
-use bitfun_core::service::session::SessionMetadata;
+use bitfun_core::service::session::{
+    SessionMetadata, SESSION_PROVIDER_ACP, SESSION_PROVIDER_METADATA_KEY,
+};
 use bitfun_core::util::errors::{BitFunError, BitFunResult};
 use serde::{Deserialize, Serialize};
 use serde_json::{json, Value};
 
-pub(super) const CUSTOM_METADATA_PROVIDER_KEY: &str = "provider";
-pub(super) const CUSTOM_METADATA_PROVIDER_VALUE: &str = "acp";
+// Persistence reads these back to tell an externally projected Session from a
+// Runtime-owned one, so both sides share one definition. It reaches this crate
+// through the Session module it already reads metadata types from, because the
+// ACP client owns no direct dependency on the core contracts.
+pub(super) const CUSTOM_METADATA_PROVIDER_KEY: &str = SESSION_PROVIDER_METADATA_KEY;
+pub(super) const CUSTOM_METADATA_PROVIDER_VALUE: &str = SESSION_PROVIDER_ACP;
 pub(super) const CUSTOM_METADATA_CLIENT_ID_KEY: &str = "acpClientId";
 pub(super) const CUSTOM_METADATA_REMOTE_SESSION_ID_KEY: &str = "acpRemoteSessionId";
 pub(super) const CUSTOM_METADATA_RESUME_STRATEGY_KEY: &str = "acpResumeStrategy";
diff --git a/src/crates/interfaces/acp/src/client/stream.rs b/src/crates/interfaces/acp/src/client/stream.rs
index 9eee7f98ec..520ed57d94 100644
--- a/src/crates/interfaces/acp/src/client/stream.rs
+++ b/src/crates/interfaces/acp/src/client/stream.rs
@@ -10,7 +10,7 @@ use bitfun_core::util::errors::{BitFunError, BitFunResult};
 use bitfun_events::ToolEventData;
 
 use super::session_options::{AcpAvailableCommand, AcpPlanEntry, AcpSessionContextUsage};
-use super::tool_card_bridge::{acp_tool_name, normalize_tool_params};
+use super::tool_card_bridge::{acp_tool_name, normalize_tool_params, normalize_tool_result};
 
 #[derive(Debug, Clone)]
 pub enum AcpClientStreamEvent {
@@ -264,13 +264,15 @@ fn acp_tool_call_events(
 
     match tool_call.status {
         ToolCallStatus::Completed => {
+            let result = acp_tool_result_value(
+                &tool_name,
+                tool_call.raw_output,
+                Some(tool_call.content),
+                Some(tool_call.locations),
+            );
             events.push(AcpClientStreamEvent::ToolEvent(ToolEventData::Completed {
                 identity: bitfun_events::ToolEventIdentity::direct(tool_id, tool_name),
-                result: acp_tool_result_value(
-                    tool_call.raw_output,
-                    Some(tool_call.content),
-                    Some(tool_call.locations),
-                ),
+                result,
                 result_for_assistant: None,
                 image_attachments: None,
                 duration_ms: 0,
@@ -324,13 +326,15 @@ fn acp_tool_call_update_events(
                     timeout_seconds: None,
                 }));
             }
+            let result = acp_tool_result_value(
+                &tool_name,
+                update.fields.raw_output,
+                update.fields.content,
+                update.fields.locations,
+            );
             events.push(AcpClientStreamEvent::ToolEvent(ToolEventData::Completed {
                 identity: bitfun_events::ToolEventIdentity::direct(tool_id, tool_name),
-                result: acp_tool_result_value(
-                    update.fields.raw_output,
-                    update.fields.content,
-                    update.fields.locations,
-                ),
+                result,
                 result_for_assistant: None,
                 image_attachments: None,
                 duration_ms: 0,
@@ -400,24 +404,27 @@ fn acp_tool_call_update_events(
 }
 
 fn acp_tool_result_value(
+    tool_name: &str,
     raw_output: Option<serde_json::Value>,
     content: Option<Vec<ToolCallContent>>,
     locations: Option<Vec<agent_client_protocol::schema::ToolCallLocation>>,
 ) -> serde_json::Value {
-    if let Some(raw_output) = raw_output {
-        return raw_output;
-    }
-
-    let content = content.unwrap_or_default();
-    let locations = locations.unwrap_or_default();
-    if content.is_empty() && locations.is_empty() {
-        return serde_json::Value::Null;
-    }
+    let value = match raw_output {
+        Some(raw_output) => raw_output,
+        None => {
+            let content = content.unwrap_or_default();
+            let locations = locations.unwrap_or_default();
+            if content.is_empty() && locations.is_empty() {
+                return serde_json::Value::Null;
+            }
+            serde_json::json!({
+                "content": content,
+                "locations": locations,
+            })
+        }
+    };
 
-    serde_json::json!({
-        "content": content,
-        "locations": locations,
-    })
+    normalize_tool_result(tool_name, value)
 }
 
 fn acp_tool_error_text(
diff --git a/src/crates/interfaces/acp/src/client/tool_card_bridge/mod.rs b/src/crates/interfaces/acp/src/client/tool_card_bridge/mod.rs
index e57901e277..2eb357a450 100644
--- a/src/crates/interfaces/acp/src/client/tool_card_bridge/mod.rs
+++ b/src/crates/interfaces/acp/src/client/tool_card_bridge/mod.rs
@@ -1,5 +1,6 @@
 mod tool_name;
 mod tool_params;
+mod tool_result;
 
 pub(super) fn acp_tool_name(
     title: &str,
@@ -16,6 +17,16 @@ pub(super) fn normalize_tool_params(
     tool_params::normalize_tool_params(tool_name, params)
 }
 
+/// Translate a completed tool's result into the shape its native card reads.
+/// Results the card already understands, and results this cannot parse, are
+/// returned unchanged.
+pub(super) fn normalize_tool_result(
+    tool_name: &str,
+    result: serde_json::Value,
+) -> serde_json::Value {
+    tool_result::normalize_tool_result(tool_name, result)
+}
+
 #[cfg(test)]
 mod tests {
     use super::{acp_tool_name, normalize_tool_params};
@@ -116,4 +127,156 @@ mod tests {
         assert_eq!(params["old_string"], "before");
         assert_eq!(params["new_string"], "after");
     }
+
+    #[test]
+    fn resolves_the_tool_identity_from_a_title_that_names_the_tool() {
+        // DeepSeek Harness over ACP puts the tool name in the title and only
+        // the arguments in rawInput, so the alias table has to reach the title.
+        let todo_input = json!({ "todos": [{ "content": "ship it", "status": "pending" }] });
+        assert_eq!(
+            acp_tool_name("todo_write", Some(&todo_input), Some(&ToolKind::Other)),
+            "TodoWrite"
+        );
+        assert_eq!(acp_tool_name("TodoWrite", None, None), "TodoWrite");
+
+        let read_input = json!({ "file_path": "src/main.rs", "offset": 40 });
+        assert_eq!(
+            acp_tool_name("read", Some(&read_input), Some(&ToolKind::Read)),
+            "Read"
+        );
+
+        let bash_input = json!({ "command": "cargo test" });
+        assert_eq!(
+            acp_tool_name("bash", Some(&bash_input), Some(&ToolKind::Execute)),
+            "Bash"
+        );
+
+        // An unknown harness tool keeps its own name rather than being forced
+        // into a native card.
+        assert_eq!(
+            acp_tool_name(
+                "subagent",
+                Some(&json!({ "task": "review" })),
+                Some(&ToolKind::Other)
+            ),
+            "subagent"
+        );
+    }
+
+    #[test]
+    fn splits_the_str_replace_editor_family_by_its_command() {
+        // One tool name, several operations. Without the split every call would
+        // land on Bash, because the `command` key looks like a shell call.
+        let edit_input = json!({
+            "command": "str_replace",
+            "path": "/repo/src/lib.rs",
+            "old_str": "before",
+            "new_str": "after"
+        });
+        assert_eq!(
+            acp_tool_name(
+                "str_replace_editor",
+                Some(&edit_input),
+                Some(&ToolKind::Edit)
+            ),
+            "Edit"
+        );
+        let params = normalize_tool_params("Edit", edit_input);
+        assert_eq!(params["file_path"], "/repo/src/lib.rs");
+        assert_eq!(params["old_string"], "before");
+        assert_eq!(params["new_string"], "after");
+
+        let view_input = json!({ "command": "view", "path": "/repo/README.md" });
+        assert_eq!(
+            acp_tool_name(
+                "str_replace_editor",
+                Some(&view_input),
+                Some(&ToolKind::Read)
+            ),
+            "Read"
+        );
+
+        let create_input = json!({
+            "command": "create",
+            "path": "/repo/notes.md",
+            "file_text": "hi"
+        });
+        assert_eq!(
+            acp_tool_name(
+                "str_replace_editor",
+                Some(&create_input),
+                Some(&ToolKind::Edit)
+            ),
+            "Write"
+        );
+        let params = normalize_tool_params("Write", create_input);
+        assert_eq!(params["file_path"], "/repo/notes.md");
+        assert_eq!(params["content"], "hi");
+    }
+
+    #[test]
+    fn code_mode_gets_its_own_card_rather_than_an_empty_terminal() {
+        // DeepSeek Harness's PTC preset answers every step with one `run_code`
+        // call whose argument is a TypeScript program. As an Execute kind with
+        // no `command`, it used to land on the Bash card and render blank.
+        let input = json!({
+            "code": "const files = await tools.bash({ command: \"ls\" });",
+            "description": "List the project root",
+        });
+        assert_eq!(
+            acp_tool_name("run_code", Some(&input), Some(&ToolKind::Execute)),
+            "RunCode"
+        );
+        let params = normalize_tool_params("RunCode", input);
+        assert_eq!(params["description"], "List the project root");
+
+        // The shape alone is enough when the tool is named something else.
+        assert_eq!(
+            acp_tool_name(
+                "python",
+                Some(&json!({ "code": "print(1)" })),
+                Some(&ToolKind::Execute)
+            ),
+            "RunCode"
+        );
+        // …and a harness that spells the program differently still fills the
+        // field the card reads.
+        assert_eq!(
+            normalize_tool_params("RunCode", json!({ "source": "print(1)" }))["code"],
+            "print(1)"
+        );
+
+        // A shell call that happens to carry a `code` argument is still Bash:
+        // the command is what ran.
+        assert_eq!(
+            acp_tool_name(
+                "bash",
+                Some(&json!({ "command": "echo hi", "code": "unused" })),
+                Some(&ToolKind::Execute)
+            ),
+            "Bash"
+        );
+    }
+
+    #[test]
+    fn descriptive_titles_still_reach_the_heuristics() {
+        // Whole-string aliasing only: a prose title is not a tool name, so the
+        // rawInput shape keeps deciding these.
+        assert_eq!(
+            acp_tool_name(
+                "Run Bash",
+                Some(&json!({ "command": "ls" })),
+                Some(&ToolKind::Execute)
+            ),
+            "Bash"
+        );
+        assert_eq!(
+            acp_tool_name(
+                "Write to file",
+                Some(&json!({ "file_path": "a.txt", "content": "hi" })),
+                Some(&ToolKind::Edit)
+            ),
+            "Write"
+        );
+    }
 }
diff --git a/src/crates/interfaces/acp/src/client/tool_card_bridge/tool_name.rs b/src/crates/interfaces/acp/src/client/tool_card_bridge/tool_name.rs
index 9549329513..db51570d8f 100644
--- a/src/crates/interfaces/acp/src/client/tool_card_bridge/tool_name.rs
+++ b/src/crates/interfaces/acp/src/client/tool_card_bridge/tool_name.rs
@@ -6,12 +6,58 @@ pub(super) fn acp_tool_name(
     kind: Option<&ToolKind>,
 ) -> String {
     if let Some(name) = raw_input.and_then(tool_name_from_raw_input) {
+        if let Some(mapped) = editor_family_tool_name(&name, raw_input) {
+            return mapped;
+        }
         return normalize_tool_name(&name, title, raw_input, kind);
     }
 
+    if let Some(mapped) = editor_family_tool_name(title, raw_input) {
+        return mapped;
+    }
+
+    // Agents that carry the tool identity in the title alone get the same alias
+    // table a rawInput candidate gets. DeepSeek Harness over ACP is one: its
+    // rawInput is the tool arguments (`{todos}`, `{command}`, …) with no name
+    // key at all, so `todo_write` would otherwise reach the heuristics below and
+    // match their "write" substring as a Write card. The match is whole-string,
+    // so a descriptive title like "Run Bash" still falls through.
+    let trimmed_title = title.trim();
+    let from_title = normalize_known_tool_alias(trimmed_title);
+    if from_title != trimmed_title || is_native_tool_name(&from_title) {
+        return from_title;
+    }
+
     normalize_tool_name("", title, raw_input, kind)
 }
 
+/// Map the `str_replace_editor` family, whose single tool name multiplexes
+/// several file operations behind a `command` argument.
+///
+/// The name alone cannot answer which card to draw: every view would open an
+/// Edit card. Worse, the generic path never gets that far — the `command` key
+/// reads as a shell call and the whole family lands on Bash. DeepSeek Harness's
+/// minimal preset ships exactly this tool as one of its two.
+fn editor_family_tool_name(name: &str, raw_input: Option<&serde_json::Value>) -> Option<String> {
+    if !matches!(
+        name.trim().to_ascii_lowercase().as_str(),
+        "str_replace_editor" | "str_replace_based_edit_tool" | "text_editor"
+    ) {
+        return None;
+    }
+    let command = raw_input
+        .and_then(|value| value.get("command"))
+        .and_then(|value| value.as_str())
+        .unwrap_or_default();
+    Some(match command {
+        "view" => "Read".to_string(),
+        "create" => "Write".to_string(),
+        // `str_replace`, `insert`, `undo_edit`, and anything an agent adds
+        // later: all of them modify a file that already exists.
+        _ => "Edit".to_string(),
+    })
+}
+
 fn tool_name_from_raw_input(raw_input: &serde_json::Value) -> Option<String> {
     let object = raw_input.as_object()?;
     for key in [
@@ -50,6 +96,17 @@ fn normalize_tool_name(
     let haystack = format!("{} {}", candidate_lower, title_lower);
     let input = raw_input.and_then(|value| value.as_object());
     if let Some(input) = input {
+        // A tool that executes and whose whole argument is a `code` blob runs a
+        // program, not a shell line. DeepSeek Harness's Code Mode (PTC) preset
+        // is one: it replaces every per-action tool with a single `run_code`.
+        // Left to the `Execute` fallback below it would draw a terminal card
+        // whose command is empty, because there is no command.
+        if matches!(kind, Some(ToolKind::Execute))
+            && has_any_key(input, &["code"])
+            && !has_any_key(input, &["command", "cmd"])
+        {
+            return "RunCode".to_string();
+        }
         if has_any_key(input, &["command", "cmd"]) {
             return "Bash".to_string();
         }
@@ -191,6 +248,7 @@ fn normalize_known_tool_alias(name: &str) -> String {
         "write" | "write_file" | "create" => "Write".to_string(),
         "edit" | "patch" | "replace" | "update" => "Edit".to_string(),
         "delete" | "remove" | "rm" => "Delete".to_string(),
+        "run_code" | "runcode" | "execute_code" | "code_execute" => "RunCode".to_string(),
         "todowrite" | "todo_write" | "todo" => "TodoWrite".to_string(),
         "websearch" | "web_search" | "search_web" => "WebSearch".to_string(),
         _ => name.to_string(),
@@ -208,6 +266,7 @@ fn is_native_tool_name(name: &str) -> bool {
             | "Grep"
             | "Glob"
             | "Bash"
+            | "RunCode"
             | "TodoWrite"
             | "WebSearch"
     )
diff --git a/src/crates/interfaces/acp/src/client/tool_card_bridge/tool_params.rs b/src/crates/interfaces/acp/src/client/tool_card_bridge/tool_params.rs
index 0dcc106e32..02eff11552 100644
--- a/src/crates/interfaces/acp/src/client/tool_card_bridge/tool_params.rs
+++ b/src/crates/interfaces/acp/src/client/tool_card_bridge/tool_params.rs
@@ -21,6 +21,18 @@ pub(super) fn normalize_tool_params(
                 );
             }
         }
+        "RunCode" => {
+            if !normalized.contains_key("code") {
+                if let Some(value) = normalized
+                    .get("source")
+                    .or_else(|| normalized.get("script"))
+                    .or_else(|| normalized.get("program"))
+                    .cloned()
+                {
+                    normalized.insert("code".to_string(), value);
+                }
+            }
+        }
         "Read" | "Write" | "Edit" | "Delete" => {
             if !normalized.contains_key("file_path") {
                 if let Some(value) = normalized
@@ -36,16 +48,35 @@ pub(super) fn normalize_tool_params(
             }
             if tool_name == "Edit" {
                 if !normalized.contains_key("old_string") {
-                    if let Some(value) = normalized.get("oldString").cloned() {
+                    // `old_str`/`new_str` are the `str_replace_editor` family's
+                    // spelling; without them its card shows a path and no diff.
+                    if let Some(value) = normalized
+                        .get("oldString")
+                        .or_else(|| normalized.get("old_str"))
+                        .cloned()
+                    {
                         normalized.insert("old_string".to_string(), value);
                     }
                 }
                 if !normalized.contains_key("new_string") {
-                    if let Some(value) = normalized.get("newString").cloned() {
+                    if let Some(value) = normalized
+                        .get("newString")
+                        .or_else(|| normalized.get("new_str"))
+                        .cloned()
+                    {
                         normalized.insert("new_string".to_string(), value);
                     }
                 }
             }
+            if tool_name == "Write" && !normalized.contains_key("content") {
+                if let Some(value) = normalized
+                    .get("file_text")
+                    .or_else(|| normalized.get("contents"))
+                    .cloned()
+                {
+                    normalized.insert("content".to_string(), value);
+                }
+            }
         }
         "LS" => {
             if !normalized.contains_key("path") {
diff --git a/src/crates/interfaces/acp/src/client/tool_card_bridge/tool_result.rs b/src/crates/interfaces/acp/src/client/tool_card_bridge/tool_result.rs
new file mode 100644
index 0000000000..713dd88e9b
--- /dev/null
+++ b/src/crates/interfaces/acp/src/client/tool_card_bridge/tool_result.rs
@@ -0,0 +1,359 @@
+//! Search results arrive over ACP as the model-facing *text* the harness wrote,
+//! while BitFun's Grep/Glob cards read counts and a file list off a structured
+//! object. Without a translation the cards render every search as "0 matches /
+//! 0 files" even though the search itself succeeded.
+//!
+//! Parsing belongs here rather than in the cards: the wire format is a property
+//! of the agent we speak to, and the cards should keep reading one shape.
+//! Anything that does not parse is returned untouched — an unrecognized result
+//! is still shown raw, which is better than an invented one.
+
+use serde_json::{json, Map, Value};
+
+/// How deep to walk a result value looking for its text blocks. Real payloads
+/// nest three or four levels; the bound only exists so a cyclic-looking shape
+/// cannot spin.
+const MAX_TEXT_DEPTH: usize = 8;
+
+pub(super) fn normalize_tool_result(tool_name: &str, result: Value) -> Value {
+    match tool_name {
+        "Grep" => normalize_grep_result(result),
+        "Glob" => normalize_glob_result(result),
+        "Bash" | "RunCode" => normalize_output_result(result),
+        _ => result,
+    }
+}
+
+/// The terminal and run-code cards show `output` (or `stdout`), while an ACP
+/// result carries its text in content blocks. Without this the card renders the
+/// command it ran and nothing underneath it.
+fn normalize_output_result(result: Value) -> Value {
+    if result.get("output").is_some() || result.get("stdout").is_some() {
+        return result;
+    }
+    let Some(text) = result_text(&result) else {
+        return result;
+    };
+
+    let mut object = match result {
+        Value::Object(object) => object,
+        _ => Map::new(),
+    };
+    object.insert("output".to_string(), Value::String(text));
+    Value::Object(object)
+}
+
+/// The grep card reads `total_matches` / `file_count`, and shows `result` as the
+/// expanded body; `matches` is the same rows in structured form.
+fn normalize_grep_result(result: Value) -> Value {
+    if grep_already_structured(&result) {
+        return result;
+    }
+    let Some(text) = result_text(&result) else {
+        return result;
+    };
+    let Some(summary) = parse_grep_text(&text) else {
+        return result;
+    };
+
+    let mut object = object_base(result, &text);
+    object.insert("total_matches".to_string(), json!(summary.total));
+    object.insert("file_count".to_string(), json!(summary.file_count));
+    object.insert("matches".to_string(), Value::Array(summary.matches));
+    Value::Object(object)
+}
+
+/// The glob card reads `files`; the text stays as `result` for the raw view.
+fn normalize_glob_result(result: Value) -> Value {
+    if glob_already_structured(&result) {
+        return result;
+    }
+    let Some(text) = result_text(&result) else {
+        return result;
+    };
+    let Some(paths) = parse_glob_text(&text) else {
+        return result;
+    };
+
+    let mut object = object_base(result, &text);
+    object.insert(
+        "files".to_string(),
+        Value::Array(paths.into_iter().map(Value::String).collect()),
+    );
+    Value::Object(object)
+}
+
+fn grep_already_structured(result: &Value) -> bool {
+    result.get("total_matches").is_some() || result.get("matches").is_some_and(Value::is_array)
+}
+
+fn glob_already_structured(result: &Value) -> bool {
+    result.is_array()
+        || result.get("files").is_some_and(Value::is_array)
+        || result.get("matches").is_some_and(Value::is_array)
+}
+
+/// Keep whatever the agent sent and add the card's fields to it, so the raw view
+/// still shows the original payload. A non-object result becomes the `result`
+/// text the cards already know how to display.
+fn object_base(result: Value, text: &str) -> Map<String, Value> {
+    let mut object = match result {
+        Value::Object(object) => object,
+        _ => Map::new(),
+    };
+    object.insert("result".to_string(), Value::String(text.to_string()));
+    object
+}
+
+/// Collect the text blocks out of a tool result, whichever envelope it came in:
+/// a bare string, the ACP `{content: [...]}` fallback, or a harness result
+/// message whose `content` nests one more level.
+fn result_text(value: &Value) -> Option<String> {
+    let mut chunks = Vec::new();
+    collect_text(value, 0, &mut chunks);
+    if chunks.is_empty() {
+        return None;
+    }
+    Some(chunks.join("\n"))
+}
+
+fn collect_text(value: &Value, depth: usize, out: &mut Vec<String>) {
+    if depth > MAX_TEXT_DEPTH {
+        return;
+    }
+    match value {
+        Value::String(text) => out.push(text.clone()),
+        Value::Array(items) => {
+            for item in items {
+                collect_text(item, depth + 1, out);
+            }
+        }
+        Value::Object(object) => {
+            if let Some(Value::String(text)) = object.get("text") {
+                out.push(text.clone());
+            } else if let Some(content) = object.get("content") {
+                collect_text(content, depth + 1, out);
+            }
+        }
+        _ => {}
+    }
+}
+
+struct GrepSummary {
+    /// Matches the search found — the header's count, which stays the truth even
+    /// when the body below it was capped.
+    total: u64,
+    /// Distinct files among the rows actually listed.
+    file_count: usize,
+    matches: Vec<Value>,
+}
+
+/// Parse the harness grep body: a `Found N matches` header, then per file its
+/// path followed by one `Line N: <text>` row per match, with a parenthesized
+/// footer when the list was capped.
+fn parse_grep_text(text: &str) -> Option<GrepSummary> {
+    let trimmed = text.trim();
+    if trimmed == "No matches found" {
+        return Some(GrepSummary {
+            total: 0,
+            file_count: 0,
+            matches: Vec::new(),
+        });
+    }
+
+    let mut lines = trimmed.lines();
+    let total = parse_grep_header(lines.next()?)?;
+
+    let mut current_file: Option<&str> = None;
+    let mut files: Vec<&str> = Vec::new();
+    let mut matches = Vec::new();
+    for line in lines {
+        let line = line.trim_end();
+        if line.is_empty() {
+            continue;
+        }
+        if let Some((number, matched)) = parse_grep_match_line(line) {
+            if let Some(file) = current_file {
+                matches.push(json!({ "file": file, "line": number, "text": matched }));
+            }
+        } else if line.starts_with('(') && line.ends_with(')') {
+            // The truncation / spill footer, not a path.
+            break;
+        } else {
+            current_file = Some(line);
+            if !files.contains(&line) {
+                files.push(line);
+            }
+        }
+    }
+
+    Some(GrepSummary {
+        total,
+        file_count: files.len(),
+        matches,
+    })
+}
+
+/// `Found 12 matches`, `Found 1 match`, or `Found 30 of 159 matches` — the count
+/// reported is always the number the search saw.
+fn parse_grep_header(header: &str) -> Option<u64> {
+    let rest = header.trim().strip_prefix("Found ")?;
+    let counts = rest
+        .strip_suffix(" matches")
+        .or_else(|| rest.strip_suffix(" match"))?;
+    counts.rsplit(" of ").next()?.trim().parse().ok()
+}
+
+fn parse_grep_match_line(line: &str) -> Option<(u64, &str)> {
+    let (number, matched) = line.strip_prefix("Line ")?.split_once(": ")?;
+    Some((number.parse().ok()?, matched))
+}
+
+/// Parse the harness glob body: one path per line, with a parenthesized paging
+/// footer when the list was capped. Prose is rejected rather than turned into
+/// paths — a path list has no blank or indented lines.
+fn parse_glob_text(text: &str) -> Option<Vec<String>> {
+    let trimmed = text.trim();
+    if trimmed == "No files found" {
+        return Some(Vec::new());
+    }
+
+    let body = match trimmed.rsplit_once("\n\n") {
+        Some((head, footer)) if footer.starts_with('(') && footer.ends_with(')') => head,
+        _ => trimmed,
+    };
+
+    let mut paths = Vec::new();
+    for line in body.lines() {
+        let line = line.trim_end();
+        if line.is_empty() || line.starts_with(char::is_whitespace) || line.contains('\t') {
+            return None;
+        }
+        paths.push(line.to_string());
+    }
+    if paths.is_empty() {
+        return None;
+    }
+    Some(paths)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::normalize_tool_result;
+    use serde_json::json;
+
+    /// The envelope DeepSeek Harness sends: a result message whose content
+    /// nests the text one level deeper than the ACP fallback shape.
+    fn harness_result(text: &str) -> serde_json::Value {
+        json!({
+            "source": { "kind": "tool", "callId": "call_00" },
+            "role": "user",
+            "content": [{
+                "type": "tool-result",
+                "toolCallId": "call_00",
+                "isError": false,
+                "content": [{ "type": "text", "text": text }],
+            }],
+        })
+    }
+
+    #[test]
+    fn counts_grep_matches_and_files_from_the_harness_text() {
+        let result = normalize_tool_result(
+            "Grep",
+            harness_result(
+                "Found 3 matches\n\ndocs/a.md\nLine 12: alpha\nLine 40: beta\n\nsrc/b.rs\nLine 7: gamma",
+            ),
+        );
+
+        assert_eq!(result["total_matches"], 3);
+        assert_eq!(result["file_count"], 2);
+        assert_eq!(result["matches"][0]["file"], "docs/a.md");
+        assert_eq!(result["matches"][0]["line"], 12);
+        assert_eq!(result["matches"][0]["text"], "alpha");
+        assert_eq!(result["matches"][2]["file"], "src/b.rs");
+        // The original text stays available to the expanded view.
+        assert!(result["result"]
+            .as_str()
+            .unwrap()
+            .starts_with("Found 3 matches"));
+        assert_eq!(result["source"]["callId"], "call_00");
+    }
+
+    #[test]
+    fn reports_the_searched_total_when_the_listing_was_capped() {
+        // The body is capped but the search saw 159; showing the capped number
+        // would understate the result the user asked about.
+        let result = normalize_tool_result(
+            "Grep",
+            json!("Found 2 of 159 matches\n\ndocs/a.md\nLine 1: x\nLine 2: y\n\n(Full grep result stored at: /tmp/grep.txt. Read it.)"),
+        );
+
+        assert_eq!(result["total_matches"], 159);
+        assert_eq!(result["file_count"], 1);
+        assert_eq!(result["matches"].as_array().unwrap().len(), 2);
+    }
+
+    #[test]
+    fn keeps_an_empty_search_empty() {
+        let grep = normalize_tool_result("Grep", harness_result("No matches found"));
+        assert_eq!(grep["total_matches"], 0);
+        assert_eq!(grep["file_count"], 0);
+
+        let glob = normalize_tool_result("Glob", harness_result("No files found"));
+        assert_eq!(glob["files"].as_array().unwrap().len(), 0);
+    }
+
+    #[test]
+    fn lists_glob_paths_and_drops_the_paging_footer() {
+        let result = normalize_tool_result(
+            "Glob",
+            harness_result(
+                "docs/a.md\ndocs/b.md\n\n(Showing 2 of 40 paths. Narrow path to see more.)",
+            ),
+        );
+
+        assert_eq!(result["files"], json!(["docs/a.md", "docs/b.md"]));
+    }
+
+    #[test]
+    fn leaves_a_result_it_cannot_parse_untouched() {
+        // Prose from some other agent must not become a fake file list.
+        let prose = harness_result("I looked around the repository.\n\n  Nothing matched.");
+        assert_eq!(normalize_tool_result("Glob", prose.clone()), prose);
+        assert_eq!(normalize_tool_result("Grep", prose.clone()), prose);
+        // A tool whose card reads the result as-is is passed straight through.
+        assert_eq!(normalize_tool_result("Read", prose.clone()), prose);
+    }
+
+    #[test]
+    fn lifts_command_and_program_output_to_the_field_those_cards_read() {
+        let bash = normalize_tool_result("Bash", harness_result("total 0\ndrwxr-xr-x  4 user"));
+        assert_eq!(bash["output"], "total 0\ndrwxr-xr-x  4 user");
+        // The envelope stays intact for the raw view.
+        assert_eq!(bash["role"], "user");
+
+        let code = normalize_tool_result("RunCode", harness_result("42"));
+        assert_eq!(code["output"], "42");
+
+        // An agent that already speaks the card's shape is left alone.
+        let native = json!({ "output": "done", "exit_code": 0 });
+        assert_eq!(normalize_tool_result("Bash", native.clone()), native);
+        let piped = json!({ "stdout": "done", "stderr": "" });
+        assert_eq!(normalize_tool_result("Bash", piped.clone()), piped);
+
+        // Nothing to lift: a result with no text is untouched rather than
+        // given an empty output that reads as "the command printed nothing".
+        let empty = json!({ "locations": [] });
+        assert_eq!(normalize_tool_result("RunCode", empty.clone()), empty);
+    }
+
+    #[test]
+    fn leaves_an_already_structured_result_alone() {
+        let grep = json!({ "total_matches": 4, "file_count": 2, "result": "Found 4 matches" });
+        assert_eq!(normalize_tool_result("Grep", grep.clone()), grep);
+
+        let glob = json!({ "files": ["a.rs"] });
+        assert_eq!(normalize_tool_result("Glob", glob.clone()), glob);
+    }
+}
diff --git a/src/crates/interfaces/acp/src/lib.rs b/src/crates/interfaces/acp/src/lib.rs
index 5930b0a52b..e00dd75678 100644
--- a/src/crates/interfaces/acp/src/lib.rs
+++ b/src/crates/interfaces/acp/src/lib.rs
@@ -1,13 +1,20 @@
 //! BitFun Agent Client Protocol integration.
 //!
-//! This crate owns the external ACP server surface and maps it onto BitFun's
-//! core agentic runtime. CLI and other hosts should only start this crate.
+//! This crate owns the ACP client and server surfaces over BitFun's assembled
+//! runtime. Product hosts select the additive `client` and `server` features
+//! explicitly; the compatibility default enables both roles.
 
+#[cfg(feature = "client")]
 pub mod client;
+#[cfg(feature = "server")]
 mod runtime;
+#[cfg(feature = "server")]
 mod server;
 
 pub use agent_client_protocol as protocol;
+#[cfg(feature = "client")]
 pub use client::AcpClientService;
+#[cfg(feature = "server")]
 pub use runtime::BitfunAcpRuntime;
+#[cfg(feature = "server")]
 pub use server::AcpServer;
diff --git a/src/crates/interfaces/app-server-client/src/lib.rs b/src/crates/interfaces/app-server-client/src/lib.rs
index 155e327fe7..6d558c008b 100644
--- a/src/crates/interfaces/app-server-client/src/lib.rs
+++ b/src/crates/interfaces/app-server-client/src/lib.rs
@@ -174,6 +174,13 @@ impl AppServerClient {
             .await
     }
 
+    pub async fn project_reasoning_catalog(
+        &self,
+        request: ProjectReasoningCatalogRequest,
+    ) -> agent_client_protocol::Result<ProjectReasoningCatalogResponse> {
+        self.rpc(|cx| Ok(cx.send_request(request))).await
+    }
+
     pub async fn worktree_repository_status(
         &self,
         request: WorktreeRepositoryStatusRequest,
@@ -376,14 +383,6 @@ impl AppServerClient {
             .await
     }
 
-    pub async fn record_local_command_turn(
-        &self,
-        request: RecordLocalCommandTurnRequest,
-    ) -> Result<RecordLocalCommandTurnResponse, ClientError> {
-        self.request_with_timeout(|cx| Ok(cx.send_request(request)), SIDE_EFFECT_TIMEOUT)
-            .await
-    }
-
     pub async fn respond_permission(
         &self,
         request: RespondPermissionRequest,
diff --git a/src/crates/interfaces/app-server-protocol/Cargo.toml b/src/crates/interfaces/app-server-protocol/Cargo.toml
index b1f5112438..2503e45d93 100644
--- a/src/crates/interfaces/app-server-protocol/Cargo.toml
+++ b/src/crates/interfaces/app-server-protocol/Cargo.toml
@@ -12,15 +12,20 @@ name = "bitfun_app_server_protocol"
 agent-client-protocol = { workspace = true }
 bitfun-events = { path = "../../contracts/events" }
 bitfun-core-types = { path = "../../contracts/core-types" }
-bitfun-product-domains = { path = "../../contracts/product-domains", default-features = false, features = ["external-sources"] }
-bitfun-runtime-ports = { path = "../../contracts/runtime-ports" }
+bitfun-product-domains = { path = "../../contracts/product-domains", features = ["external-sources"] }
+bitfun-runtime-ports = { path = "../../contracts/runtime-ports", features = ["agent-api", "git-port"] }
 serde = { workspace = true }
 serde_json = { workspace = true }
 ts-rs = { workspace = true, optional = true }
 
 [features]
 default = []
-ts = ["dep:ts-rs"]
+ts = [
+    "dep:ts-rs",
+    "bitfun-core-types/ts",
+    "bitfun-product-domains/ts",
+    "bitfun-runtime-ports/ts",
+]
 
 [lints]
 workspace = true
diff --git a/src/crates/interfaces/app-server-protocol/src/config.rs b/src/crates/interfaces/app-server-protocol/src/config.rs
index c30fc57dba..741cd73c0c 100644
--- a/src/crates/interfaces/app-server-protocol/src/config.rs
+++ b/src/crates/interfaces/app-server-protocol/src/config.rs
@@ -5,6 +5,116 @@
 
 use agent_client_protocol::{JsonRpcRequest, JsonRpcResponse};
 use serde::{Deserialize, Serialize};
+use std::collections::{BTreeMap, HashMap};
+
+/// API view of a mode configuration.
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(default)]
+pub struct AgentProfileView {
+    pub profile_id: String,
+    pub enabled_tools: Vec<String>,
+    pub default_tools: Vec<String>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub disabled_user_skills: Vec<String>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub enabled_user_skills: Vec<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
+#[request(method = "config/getAgentProfileConfigs", response = GetAgentProfileConfigsResponse)]
+pub struct GetAgentProfileConfigsMessage {}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
+pub struct GetAgentProfileConfigsResponse {
+    pub profiles: HashMap<String, AgentProfileView>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[request(method = "config/getAgentProfileConfig", response = GetAgentProfileConfigResponse)]
+pub struct GetAgentProfileConfigMessage {
+    pub agent_id: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
+pub struct GetAgentProfileConfigResponse(pub AgentProfileView);
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
+#[request(method = "config/getModelConfigs", response = GetModelConfigsResponse)]
+pub struct GetModelConfigsMessage {}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
+pub struct GetModelConfigsResponse {
+    pub models: Vec<serde_json::Value>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
+#[serde(rename_all = "camelCase")]
+#[request(method = "config/getConfig", response = GetConfigResponse)]
+pub struct GetConfigMessage {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub path: Option<String>,
+    #[serde(default, skip_serializing_if = "skip_if_false")]
+    pub skip_retry_on_not_found: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
+pub struct GetConfigResponse(pub serde_json::Value);
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
+#[serde(rename_all = "camelCase")]
+#[request(method = "config/getConfigs", response = GetConfigsResponse)]
+pub struct GetConfigsMessage {
+    pub paths: Vec<String>,
+    #[serde(default, skip_serializing_if = "skip_if_false")]
+    pub skip_retry_on_not_found: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
+pub struct GetConfigsResponse {
+    pub configs: BTreeMap<String, serde_json::Value>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
+#[serde(rename_all = "camelCase")]
+#[request(method = "config/setConfig", response = SetConfigResponse)]
+pub struct SetConfigMessage {
+    pub path: String,
+    pub value: serde_json::Value,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
+pub struct SetConfigResponse {}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "camelCase")]
+#[request(method = "config/setAgentProfileConfig", response = SetAgentProfileConfigResponse)]
+pub struct SetAgentProfileConfigMessage {
+    pub agent_id: String,
+    pub config: serde_json::Value,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+pub struct SetAgentProfileConfigResponse(pub AgentProfileView);
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "camelCase")]
+#[request(method = "config/resetAgentProfileConfig", response = ResetAgentProfileConfigResponse)]
+pub struct ResetAgentProfileConfigMessage {
+    pub agent_id: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+pub struct ResetAgentProfileConfigResponse(pub AgentProfileView);
+
+fn skip_if_false(value: &bool) -> bool {
+    !*value
+}
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
diff --git a/src/crates/interfaces/app-server-protocol/src/lib.rs b/src/crates/interfaces/app-server-protocol/src/lib.rs
index 7f96360609..dc16279890 100644
--- a/src/crates/interfaces/app-server-protocol/src/lib.rs
+++ b/src/crates/interfaces/app-server-protocol/src/lib.rs
@@ -16,8 +16,8 @@ pub use role::{AppClient, AppServer};
 // Keep the established public domain paths while the schema sources live in a
 // single physical directory.
 pub use schemas::{
-    account, agent, app, error, event, external_source, hook, mcp, method, model, session, skill,
-    subagent, workspace, worktree,
+    account, agent, app, error, event, external_source, git, hook, i18n, mcp, method, model,
+    permission, session, skill, subagent, workspace, worktree,
 };
 
 /// Current App Server protocol version.
diff --git a/src/crates/interfaces/app-server-protocol/src/schemas/agent.rs b/src/crates/interfaces/app-server-protocol/src/schemas/agent.rs
index 3bc4b8cd52..44cb3eae53 100644
--- a/src/crates/interfaces/app-server-protocol/src/schemas/agent.rs
+++ b/src/crates/interfaces/app-server-protocol/src/schemas/agent.rs
@@ -3,10 +3,12 @@
 use agent_client_protocol::{JsonRpcRequest, JsonRpcResponse};
 use bitfun_product_domains::tool_permissions::{PermissionReply, PermissionRequest};
 use bitfun_runtime_ports::{
-    AgentDialogSteerRequest, AgentDialogTurnRequest, AgentSessionCreateRequest,
-    AgentSessionCreateResult, AgentSessionDeleteRequest, AgentSessionListRequest,
-    AgentSessionSummary, AgentTurnCancellationRequest, AgentTurnCancellationResult,
-    AgentUserShellCommandRequest, AgentUserShellCommandResult, DialogSubmitOutcome,
+    AgentDialogSteerRequest, AgentDialogTurnExecution, AgentDialogTurnRequest,
+    AgentInputAttachment, AgentSessionCreateRequest, AgentSessionCreateResult,
+    AgentSessionDeleteRequest, AgentSessionListRequest, AgentSessionSummary,
+    AgentSubmissionRequest, AgentSubmissionResult, AgentSubmissionSource,
+    AgentTurnCancellationRequest, AgentTurnCancellationResult, AgentUserShellCommandRequest,
+    AgentUserShellCommandResult, DialogSubmissionPolicy,
 };
 use serde::{Deserialize, Serialize};
 
@@ -48,6 +50,8 @@ pub struct AgentModeSummary {
 pub struct ListSessionsRequest(pub AgentSessionListRequest);
 
 #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+/// `agent/listSessions` response body.
 pub struct ListSessionsResponse {
     pub sessions: Vec<AgentSessionSummary>,
 }
@@ -92,37 +96,94 @@ unit_response!(DeleteSessionResponse);
 
 #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
 #[request(method = "agent/submitDialogTurn", response = SubmitDialogTurnResponse)]
-pub struct SubmitDialogTurnRequest(pub AgentDialogTurnRequest);
+pub struct SubmitDialogTurnRequest(pub SubmitDialogTurnBody);
+
+pub use SubmitDialogTurnRequest as SubmitDialogTurnMessage;
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "camelCase")]
+/// Wire form of [`AgentDialogTurnRequest`] with an optional `policy`.
+pub struct SubmitDialogTurnBody {
+    pub session_id: String,
+    pub message: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub original_message: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub turn_id: Option<String>,
+    #[serde(default, skip_serializing_if = "AgentDialogTurnExecution::is_standard")]
+    pub execution: AgentDialogTurnExecution,
+    pub agent_type: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub workspace_path: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_connection_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_ssh_host: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub policy: Option<DialogSubmissionPolicy>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub attachments: Vec<AgentInputAttachment>,
+    #[serde(default, skip_serializing_if = "serde_json::Map::is_empty")]
+    pub metadata: serde_json::Map<String, serde_json::Value>,
+}
+
+impl SubmitDialogTurnBody {
+    /// Project this wire body into the runtime contract using the adapter's
+    /// explicit fallback policy when the legacy payload omits one.
+    pub fn to_request(self, default_policy: DialogSubmissionPolicy) -> AgentDialogTurnRequest {
+        AgentDialogTurnRequest {
+            session_id: self.session_id,
+            message: self.message,
+            original_message: self.original_message,
+            turn_id: self.turn_id,
+            execution: self.execution,
+            agent_type: self.agent_type,
+            workspace_path: self.workspace_path,
+            remote_connection_id: self.remote_connection_id,
+            remote_ssh_host: self.remote_ssh_host,
+            policy: self.policy.unwrap_or(default_policy),
+            reply_route: None,
+            prepended_reminders: Vec::new(),
+            attachments: self.attachments,
+            metadata: self.metadata,
+        }
+    }
+}
+
+impl From<AgentDialogTurnRequest> for SubmitDialogTurnRequest {
+    fn from(request: AgentDialogTurnRequest) -> Self {
+        // The App Server wire contract predates reply routing and prepended
+        // reminders. Keep the currently effective behavior: those runtime-only
+        // fields are not sent over this compatibility method.
+        Self(SubmitDialogTurnBody {
+            session_id: request.session_id,
+            message: request.message,
+            original_message: request.original_message,
+            turn_id: request.turn_id,
+            execution: request.execution,
+            agent_type: request.agent_type,
+            workspace_path: request.workspace_path,
+            remote_connection_id: request.remote_connection_id,
+            remote_ssh_host: request.remote_ssh_host,
+            policy: Some(request.policy),
+            attachments: request.attachments,
+            metadata: request.metadata,
+        })
+    }
+}
 
 #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[serde(rename_all = "camelCase", tag = "status")]
+/// `agent/submitDialogTurn` response body.
 pub enum SubmitDialogTurnResponse {
     Started { session_id: String, turn_id: String },
     Queued { session_id: String, turn_id: String },
 }
 
-impl From<DialogSubmitOutcome> for SubmitDialogTurnResponse {
-    fn from(outcome: DialogSubmitOutcome) -> Self {
-        match outcome {
-            DialogSubmitOutcome::Started {
-                session_id,
-                turn_id,
-            } => Self::Started {
-                session_id,
-                turn_id,
-            },
-            DialogSubmitOutcome::Queued {
-                session_id,
-                turn_id,
-            } => Self::Queued {
-                session_id,
-                turn_id,
-            },
-        }
-    }
-}
-
 #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[request(method = "agent/respondPermission", response = RespondPermissionResponse)]
 pub struct RespondPermissionRequest {
     pub request_id: String,
@@ -146,3 +207,56 @@ pub struct CancelTurnRequest(pub AgentTurnCancellationRequest);
 
 #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
 pub struct CancelTurnResponse(pub AgentTurnCancellationResult);
+
+pub use CancelTurnRequest as CancelTurnMessage;
+pub use CreateSessionRequest as CreateSessionMessage;
+pub use DeleteSessionRequest as DeleteSessionMessage;
+pub use ListSessionsRequest as ListSessionsMessage;
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
+#[request(method = "agent/submitTurn", response = SubmitTurnResponse)]
+pub struct SubmitTurnMessage(pub AgentSubmissionRequest);
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
+pub struct SubmitTurnResponse(pub AgentSubmissionResult);
+
+/// `agent/run` response body.
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "camelCase")]
+pub struct RunResponse {
+    pub session_id: String,
+    pub turn_id: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub agent_type: Option<String>,
+    #[serde(default)]
+    pub accepted: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "camelCase", tag = "kind")]
+pub enum RunSessionSpec {
+    Existing {
+        session_id: String,
+    },
+    Create {
+        session_name: String,
+        agent_type: String,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        workspace_path: Option<String>,
+    },
+}
+
+/// Compatibility request for `agent/run`.
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
+#[request(method = "agent/run", response = RunResponse)]
+#[serde(rename_all = "camelCase")]
+pub struct RunMessage {
+    pub session: RunSessionSpec,
+    pub message: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub turn_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub source: Option<AgentSubmissionSource>,
+}
diff --git a/src/crates/interfaces/app-server-protocol/src/schemas/event.rs b/src/crates/interfaces/app-server-protocol/src/schemas/event.rs
index 425674a832..38c9bf0312 100644
--- a/src/crates/interfaces/app-server-protocol/src/schemas/event.rs
+++ b/src/crates/interfaces/app-server-protocol/src/schemas/event.rs
@@ -5,6 +5,15 @@ use bitfun_events::AgenticEventEnvelope;
 use bitfun_product_domains::tool_permissions::{PermissionRequest, PermissionRequestEvent};
 use serde::{Deserialize, Serialize};
 
+/// Browser-facing projected runtime or permission event.
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcNotification)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[notification(method = "agent/frontendEvent")]
+pub struct FrontendEventNotification {
+    pub event: String,
+    pub payload: serde_json::Value,
+}
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub enum EventStream {
@@ -132,7 +141,7 @@ pub enum ConfigUpdate {
     ModelsReconciled {
         invalidated_model_ids: Vec<String>,
         default_models_changed: bool,
-        func_agent_models_changed: bool,
+        task_models_changed: bool,
         agent_model_defaults_changed: bool,
     },
 }
diff --git a/src/crates/interfaces/app-server-protocol/src/schemas/git.rs b/src/crates/interfaces/app-server-protocol/src/schemas/git.rs
new file mode 100644
index 0000000000..0a4b4f71ca
--- /dev/null
+++ b/src/crates/interfaces/app-server-protocol/src/schemas/git.rs
@@ -0,0 +1,107 @@
+//! Git-domain App Server wire schemas.
+
+use agent_client_protocol::{JsonRpcRequest, JsonRpcResponse};
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
+#[request(method = "git/isRepository", response = GitIsRepositoryResponse)]
+pub struct GitIsRepositoryMessage(pub GitRepositoryPathRequest);
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
+pub struct GitIsRepositoryResponse(pub bool);
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
+#[request(method = "git/getStatus", response = GitGetStatusResponse)]
+pub struct GitGetStatusMessage(pub GitRepositoryPathRequest);
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
+pub struct GitGetStatusResponse(pub GitStatus);
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
+#[request(method = "git/getBranches", response = GitGetBranchesResponse)]
+pub struct GitGetBranchesMessage(pub GitBranchesRequest);
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
+pub struct GitGetBranchesResponse {
+    pub branches: Vec<GitBranch>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "camelCase")]
+pub struct GitRepositoryPathRequest {
+    pub repository_path: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "camelCase")]
+pub struct GitBranchesRequest {
+    pub repository_path: String,
+    #[serde(default)]
+    pub include_remote: Option<bool>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct GitStatus {
+    pub staged: Vec<GitFileStatus>,
+    pub unstaged: Vec<GitFileStatus>,
+    pub untracked: Vec<String>,
+    #[serde(default)]
+    pub conflicts: Vec<String>,
+    pub current_branch: String,
+    pub ahead: i32,
+    pub behind: i32,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct GitFileStatus {
+    pub path: String,
+    pub status: String,
+    pub index_status: Option<String>,
+    pub workdir_status: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+pub struct GitBranch {
+    pub name: String,
+    pub current: bool,
+    pub remote: bool,
+    pub upstream: Option<String>,
+    pub ahead: i32,
+    pub behind: i32,
+    pub last_commit: Option<String>,
+    pub last_commit_date: Option<String>,
+    pub base_branch: Option<String>,
+    pub child_branches: Option<Vec<String>>,
+    pub merged_branches: Option<Vec<String>>,
+    pub branch_type: Option<String>,
+    pub has_conflicts: Option<bool>,
+    pub can_merge: Option<bool>,
+    pub is_stale: Option<bool>,
+    pub merge_status: Option<String>,
+    pub stats: Option<GitBranchStats>,
+    pub created_at: Option<String>,
+    pub last_activity_at: Option<String>,
+    pub tags: Option<Vec<String>>,
+    pub description: Option<String>,
+    pub linked_issues: Option<Vec<String>>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+pub struct GitBranchStats {
+    pub commit_count: i32,
+    pub contributor_count: i32,
+    pub file_changes: i32,
+    pub lines_changed: GitLinesChanged,
+    pub activity_score: i32,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+pub struct GitLinesChanged {
+    pub additions: i32,
+    pub deletions: i32,
+}
diff --git a/src/crates/interfaces/app-server/src/schema/i18n.rs b/src/crates/interfaces/app-server-protocol/src/schemas/i18n.rs
similarity index 78%
rename from src/crates/interfaces/app-server/src/schema/i18n.rs
rename to src/crates/interfaces/app-server-protocol/src/schemas/i18n.rs
index c84a04de7a..7948742167 100644
--- a/src/crates/interfaces/app-server/src/schema/i18n.rs
+++ b/src/crates/interfaces/app-server-protocol/src/schemas/i18n.rs
@@ -1,19 +1,18 @@
+//! Internationalization App Server wire schemas.
+
 use agent_client_protocol::{JsonRpcRequest, JsonRpcResponse};
 use serde::{Deserialize, Serialize};
 
 #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[request(method = "i18n/getCurrentLanguage", response = I18nGetCurrentLanguageResponse)]
 pub struct I18nGetCurrentLanguageMessage {}
 
 #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 pub struct I18nGetCurrentLanguageResponse {
     pub language: String,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[request(method = "i18n/setLanguage", response = I18nSetLanguageResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct I18nSetLanguageMessage {
@@ -21,18 +20,15 @@ pub struct I18nSetLanguageMessage {
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 pub struct I18nSetLanguageResponse {
     pub language: String,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[request(method = "i18n/getConfig", response = I18nGetConfigResponse)]
 pub struct I18nGetConfigMessage {}
 
 #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 pub struct I18nGetConfigResponse {
     pub current_language: String,
     pub fallback_language: String,
@@ -40,7 +36,6 @@ pub struct I18nGetConfigResponse {
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[request(method = "i18n/setConfig", response = I18nSetConfigResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct I18nSetConfigMessage {
@@ -53,16 +48,13 @@ pub struct I18nSetConfigMessage {
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 pub struct I18nSetConfigResponse {}
 
 #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[request(method = "i18n/getSupportedLanguages", response = I18nGetSupportedLanguagesResponse)]
 pub struct I18nGetSupportedLanguagesMessage {}
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[serde(rename_all = "camelCase")]
 pub struct I18nLocaleMetadata {
     pub id: String,
@@ -73,7 +65,6 @@ pub struct I18nLocaleMetadata {
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 pub struct I18nGetSupportedLanguagesResponse {
     pub locales: Vec<I18nLocaleMetadata>,
 }
diff --git a/src/crates/interfaces/app-server-protocol/src/schemas/mod.rs b/src/crates/interfaces/app-server-protocol/src/schemas/mod.rs
index 973b949187..4a6580fcc2 100644
--- a/src/crates/interfaces/app-server-protocol/src/schemas/mod.rs
+++ b/src/crates/interfaces/app-server-protocol/src/schemas/mod.rs
@@ -6,10 +6,13 @@ pub mod app;
 pub mod error;
 pub mod event;
 pub mod external_source;
+pub mod git;
 pub mod hook;
+pub mod i18n;
 pub mod mcp;
 pub mod method;
 pub mod model;
+pub mod permission;
 pub mod session;
 pub mod skill;
 pub mod subagent;
diff --git a/src/crates/interfaces/app-server-protocol/src/schemas/model.rs b/src/crates/interfaces/app-server-protocol/src/schemas/model.rs
index 9cf851b373..1164c12974 100644
--- a/src/crates/interfaces/app-server-protocol/src/schemas/model.rs
+++ b/src/crates/interfaces/app-server-protocol/src/schemas/model.rs
@@ -5,7 +5,9 @@
 //! are never returned by the server.
 
 use agent_client_protocol::{JsonRpcRequest, JsonRpcResponse};
-use bitfun_core_types::{ProviderCatalog, ReasoningConfig};
+use bitfun_core_types::{
+    ProviderCatalog, ReasoningCatalogProjection, ReasoningCatalogProjectionRequest, ReasoningConfig,
+};
 use serde::{Deserialize, Serialize};
 
 macro_rules! unit_response {
@@ -54,6 +56,16 @@ pub struct TuiModelCatalogResponse {
     pub reasoning_presets_by_model: std::collections::BTreeMap<String, Vec<String>>,
 }
 
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
+#[request(method = "model/projectReasoningCatalog", response = ProjectReasoningCatalogResponse)]
+#[serde(transparent)]
+pub struct ProjectReasoningCatalogRequest(pub ReasoningCatalogProjectionRequest);
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
+pub struct ProjectReasoningCatalogResponse {
+    pub projection: ReasoningCatalogProjection,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct ModelSummary {
diff --git a/src/crates/interfaces/app-server/src/schema/permission.rs b/src/crates/interfaces/app-server-protocol/src/schemas/permission.rs
similarity index 58%
rename from src/crates/interfaces/app-server/src/schema/permission.rs
rename to src/crates/interfaces/app-server-protocol/src/schemas/permission.rs
index b3178c7a3a..07855997b4 100644
--- a/src/crates/interfaces/app-server/src/schema/permission.rs
+++ b/src/crates/interfaces/app-server-protocol/src/schemas/permission.rs
@@ -1,24 +1,14 @@
+//! Permission-domain App Server wire schemas.
+
 use agent_client_protocol::{JsonRpcRequest, JsonRpcResponse};
-use bitfun_agent_runtime::sdk::{
-    PermissionAuditRecord, PermissionGrant, PermissionGrantKey, PermissionReply, PermissionRequest,
+use bitfun_product_domains::tool_permissions::{
+    PermissionAuditRecord, PermissionGrant, PermissionGrantKey, PermissionReply,
 };
 use serde::{Deserialize, Serialize};
 
-/// `agent/respondPermission` request body.
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[request(method = "agent/respondPermission", response = RespondPermissionResponse)]
-pub struct RespondPermissionMessage {
-    pub request_id: String,
-    pub reply: PermissionReply,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-pub struct RespondPermissionResponse {}
+pub type RespondPermissionMessage = super::agent::RespondPermissionRequest;
 
 #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[request(method = "agent/respondPermissionBatch", response = RespondPermissionBatchResponse)]
 pub struct RespondPermissionBatchMessage {
     pub request_id: String,
@@ -26,24 +16,14 @@ pub struct RespondPermissionBatchMessage {
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 pub struct RespondPermissionBatchResponse {
     pub request_ids: Vec<String>,
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[request(method = "agent/listPendingPermissionRequests", response = ListPendingPermissionRequestsResponse)]
-pub struct ListPendingPermissionRequestsMessage {}
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-pub struct ListPendingPermissionRequestsResponse {
-    pub requests: Vec<PermissionRequest>,
-}
+pub type ListPendingPermissionRequestsMessage = super::agent::PendingPermissionsRequest;
+pub type ListPendingPermissionRequestsResponse = super::agent::PendingPermissionsResponse;
 
 #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[request(method = "agent/listProjectPermissionGrants", response = ListProjectPermissionGrantsResponse)]
 pub struct ListProjectPermissionGrantsMessage {
     pub project_id: String,
@@ -56,7 +36,6 @@ pub struct ListProjectPermissionGrantsResponse {
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
 #[request(method = "agent/removeProjectPermissionGrant", response = RemoveProjectPermissionGrantResponse)]
 pub struct RemoveProjectPermissionGrantMessage(pub PermissionGrantKey);
 
@@ -67,29 +46,23 @@ pub struct RemoveProjectPermissionGrantResponse {
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[request(method = "agent/clearProjectPermissionGrants", response = ClearProjectPermissionGrantsResponse)]
 pub struct ClearProjectPermissionGrantsMessage {
     pub project_id: String,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 pub struct ClearProjectPermissionGrantsResponse {
     pub cleared: usize,
 }
 
-pub use bitfun_app_server_protocol::event::PermissionEventNotification;
-
 #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[request(method = "agent/listProjectPermissionAudit", response = ListProjectPermissionAuditResponse)]
 pub struct ListProjectPermissionAuditMessage {
     pub project_id: String,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 pub struct ListProjectPermissionAuditResponse {
     pub records: Vec<PermissionAuditRecord>,
 }
diff --git a/src/crates/interfaces/app-server-protocol/src/schemas/session.rs b/src/crates/interfaces/app-server-protocol/src/schemas/session.rs
index f6eb86d78f..5c0d51180a 100644
--- a/src/crates/interfaces/app-server-protocol/src/schemas/session.rs
+++ b/src/crates/interfaces/app-server-protocol/src/schemas/session.rs
@@ -4,16 +4,15 @@ use agent_client_protocol::{JsonRpcRequest, JsonRpcResponse};
 use bitfun_core_types::SessionUsageReport;
 use bitfun_product_domains::tool_permissions::PermissionRequest;
 use bitfun_runtime_ports::{
-    AgentContextReloadRequest, AgentLocalCommandTurnRecordRequest,
-    AgentLocalCommandTurnRecordResult, AgentSessionCompactionRequest, AgentSessionCompactionResult,
-    AgentSessionForkBeforeTurnRequest, AgentSessionForkRequest, AgentSessionForkResult,
-    AgentSessionLineageCancellationRequest, AgentSessionLineageInspection,
-    AgentSessionLineageRequest, AgentSessionLineageSnapshot, AgentSessionLineageTranscriptRequest,
-    AgentSessionModeUpdateRequest, AgentSessionModelUpdateRequest, AgentSessionRenameRequest,
-    AgentSessionRevertRequest, AgentSessionRevertResult, AgentSessionSummary,
-    AgentSessionUsageRequest, AgentSessionWorkspaceBinding, AgentSessionWorkspaceRequest,
-    AgentTurnCancellationResult, AgentTurnSettlementRequest, SessionTranscript,
-    SessionTranscriptRequest,
+    AgentContextReloadRequest, AgentSessionArchiveStateRequest, AgentSessionCompactionRequest,
+    AgentSessionCompactionResult, AgentSessionForkAtTurnRequest, AgentSessionForkBeforeTurnRequest,
+    AgentSessionForkRequest, AgentSessionForkResult, AgentSessionLineageCancellationRequest,
+    AgentSessionLineageInspection, AgentSessionLineageRequest, AgentSessionLineageSnapshot,
+    AgentSessionLineageTranscriptRequest, AgentSessionModeUpdateRequest,
+    AgentSessionModelUpdateRequest, AgentSessionRenameRequest, AgentSessionRevertRequest,
+    AgentSessionRevertResult, AgentSessionSummary, AgentSessionUsageRequest,
+    AgentSessionWorkspaceBinding, AgentSessionWorkspaceRequest, AgentTurnCancellationResult,
+    AgentTurnSettlementRequest, SessionTranscript, SessionTranscriptRequest,
 };
 use serde::{Deserialize, Serialize};
 
@@ -50,6 +49,7 @@ pub struct SyncSessionResponse {
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[serde(
     tag = "kind",
     rename_all = "camelCase",
@@ -68,6 +68,7 @@ pub enum SessionRuntimeState {
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[serde(rename_all = "camelCase")]
 pub enum SessionProcessingPhase {
     Starting,
@@ -78,6 +79,30 @@ pub enum SessionProcessingPhase {
     ToolConfirming,
 }
 
+/// Compatibility request for `session/restore`.
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[request(method = "session/restore", response = RestoreSessionResponse)]
+#[serde(rename_all = "camelCase")]
+pub struct RestoreSessionMessage {
+    pub workspace_path: String,
+    pub session_id: String,
+    #[serde(default)]
+    pub include_internal: bool,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_connection_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remote_ssh_host: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "camelCase")]
+pub struct RestoreSessionResponse {
+    pub session: AgentSessionSummary,
+    pub state: SessionRuntimeState,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
 #[request(method = "session/readTranscript", response = ReadTranscriptResponse)]
 pub struct ReadTranscriptRequest(pub SessionTranscriptRequest);
@@ -92,13 +117,6 @@ pub struct ResolveWorkspaceRequest(pub AgentSessionWorkspaceRequest);
 #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
 pub struct ResolveWorkspaceResponse(pub Option<AgentSessionWorkspaceBinding>);
 
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[request(method = "session/recordLocalCommandTurn", response = RecordLocalCommandTurnResponse)]
-pub struct RecordLocalCommandTurnRequest(pub AgentLocalCommandTurnRecordRequest);
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
-pub struct RecordLocalCommandTurnResponse(pub AgentLocalCommandTurnRecordResult);
-
 #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
 #[request(method = "session/rename", response = RenameSessionResponse)]
 pub struct RenameSessionRequest(pub AgentSessionRenameRequest);
@@ -172,6 +190,7 @@ pub struct ForkSessionRequest(pub AgentSessionForkRequest);
 pub struct ForkSessionBeforeTurnRequest(pub AgentSessionForkBeforeTurnRequest);
 
 #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 pub struct ForkSessionResponse(pub AgentSessionForkResult);
 
 #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
@@ -185,3 +204,21 @@ unit_response!(UpdateSessionModelResponse);
 pub struct UpdateSessionModeRequest(pub AgentSessionModeUpdateRequest);
 
 unit_response!(UpdateSessionModeResponse);
+
+pub use ForkSessionBeforeTurnRequest as ForkSessionBeforeTurnMessage;
+pub use ForkSessionRequest as ForkSessionMessage;
+pub use RenameSessionRequest as RenameSessionMessage;
+pub use UpdateSessionModeRequest as UpdateSessionModeMessage;
+pub use UpdateSessionModelRequest as UpdateSessionModelMessage;
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[request(method = "session/setArchived", response = SetSessionArchivedResponse)]
+pub struct SetSessionArchivedMessage(pub AgentSessionArchiveStateRequest);
+
+unit_response!(SetSessionArchivedResponse);
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[request(method = "session/forkAtTurn", response = ForkSessionResponse)]
+pub struct ForkSessionAtTurnMessage(pub AgentSessionForkAtTurnRequest);
diff --git a/src/crates/interfaces/app-server-protocol/tests/legacy_wire_contracts.rs b/src/crates/interfaces/app-server-protocol/tests/legacy_wire_contracts.rs
new file mode 100644
index 0000000000..bcbbe5bf10
--- /dev/null
+++ b/src/crates/interfaces/app-server-protocol/tests/legacy_wire_contracts.rs
@@ -0,0 +1,84 @@
+use agent_client_protocol::JsonRpcMessage;
+use bitfun_app_server_protocol::{
+    agent::{RunResponse, SubmitDialogTurnMessage, SubmitDialogTurnRequest},
+    config::GetAgentProfileConfigMessage,
+    permission::RespondPermissionMessage,
+    session::{RestoreSessionMessage, SessionProcessingPhase, SessionRuntimeState},
+};
+use serde_json::json;
+
+#[test]
+fn legacy_submit_dialog_contract_keeps_optional_policy_and_method() {
+    let request: SubmitDialogTurnRequest = serde_json::from_value(json!({
+        "sessionId": "session-1",
+        "message": "hello",
+        "agentType": "general"
+    }))
+    .expect("legacy dialog payload should accept a missing policy");
+    let body = request.0;
+
+    assert!(body.policy.is_none());
+    assert!(body.attachments.is_empty());
+    assert!(body.metadata.is_empty());
+    assert!(SubmitDialogTurnMessage::matches_method(
+        "agent/submitDialogTurn"
+    ));
+    assert_eq!(
+        std::any::TypeId::of::<SubmitDialogTurnMessage>(),
+        std::any::TypeId::of::<SubmitDialogTurnRequest>()
+    );
+}
+
+#[test]
+fn legacy_restore_and_session_state_keep_their_wire_shape() {
+    let request: RestoreSessionMessage = serde_json::from_value(json!({
+        "workspacePath": "/workspace",
+        "sessionId": "session-1"
+    }))
+    .expect("restore request should accept omitted includeInternal");
+    assert!(!request.include_internal);
+
+    let state = SessionRuntimeState::Processing {
+        current_turn_id: "turn-1".to_string(),
+        phase: SessionProcessingPhase::ToolCalling,
+    };
+    assert_eq!(
+        serde_json::to_value(state).expect("state should serialize"),
+        json!({
+            "kind": "processing",
+            "currentTurnId": "turn-1",
+            "phase": "toolCalling"
+        })
+    );
+}
+
+#[test]
+fn legacy_mixed_case_fields_and_response_defaults_remain_compatible() {
+    let profile: GetAgentProfileConfigMessage = serde_json::from_value(json!({
+        "agent_id": "general"
+    }))
+    .expect("legacy get-profile request should keep snake_case");
+    assert_eq!(profile.agent_id, "general");
+
+    let permission: RespondPermissionMessage = serde_json::from_value(json!({
+        "request_id": "permission-1",
+        "reply": { "reply": "once" }
+    }))
+    .expect("legacy permission request should keep snake_case");
+    assert_eq!(permission.request_id, "permission-1");
+
+    let response: RunResponse = serde_json::from_value(json!({
+        "sessionId": "session-1",
+        "turnId": "turn-1"
+    }))
+    .expect("accepted should default to false");
+    assert!(!response.accepted);
+    assert_eq!(
+        serde_json::to_value(response).expect("response should serialize"),
+        json!({
+            "sessionId": "session-1",
+            "turnId": "turn-1",
+            "accepted": false
+        })
+    );
+}
diff --git a/src/crates/interfaces/app-server/AGENTS-CN.md b/src/crates/interfaces/app-server/AGENTS-CN.md
index 5f3b412e41..c8ab0b4cae 100644
--- a/src/crates/interfaces/app-server/AGENTS-CN.md
+++ b/src/crates/interfaces/app-server/AGENTS-CN.md
@@ -1,8 +1,9 @@
 **中文** | [English](AGENTS.md)
 
-# App Server 服务端与接线指南
+# App Server 接口族指南
 
-适用范围：本指南只适用于 `src/crates/interfaces/app-server` 及其服务端生产接线。
+适用范围：本指南适用于相邻的 `app-server-protocol`、`app-server-client`、`app-server`
+三个 crate 及 App Server 生产接线。除非另有说明，服务端专属规则只约束 `app-server`。
 
 App Server 接口由四个 owner 分工：
 
@@ -13,10 +14,13 @@ App Server 接口由四个 owner 分工：
 | `app-server` | server 生命周期、生产 handler 注册、事件转发、Runtime/domain 到 wire 的转换和错误映射 |
 | `src/apps/*` 下的产品 Host | 具体 transport、认证、连接作用域、capability/limit 构造、平台能力、进程监督和关闭流程 |
 
-不要在本 crate 新增 protocol 或 client 所有权。消费者迁移期间可以保留 compatibility
+不要在 `bitfun-app-server` 中新增 protocol 或 client 所有权。消费者迁移期间可以保留 compatibility
 module 和 re-export，但新 method、DTO、wire error 和类型化 client 行为必须放入相邻的
 protocol/client crate。
 
+`bitfun-app-server/ts` 只保留为兼容转发 feature。protocol crate 是唯一的 TypeScript
+schema 导出 owner；不要把 `ts-rs`、Runtime 实现类型或第二条导出命令重新加入本 crate。
+
 ## 护栏
 
 - compatibility role 和 transport helper 必须保持 schema-free。不要在 `AppServer` /
@@ -55,7 +59,8 @@ kind 和结构化 data，不泄露 Runtime 内部细节。Host transport/auth/sc
 ## 验证
 
 ```bash
-cargo check -p bitfun-app-server --offline
-cargo test -p bitfun-app-server --offline
+cargo check --locked -p bitfun-app-server --offline
+cargo test --locked -p bitfun-app-server --offline --lib server::wire::tests
+cargo test --locked -p bitfun-app-server-protocol --offline --test legacy_wire_contracts
 pnpm run check:core-boundaries
 ```
diff --git a/src/crates/interfaces/app-server/AGENTS.md b/src/crates/interfaces/app-server/AGENTS.md
index ef859abc20..6078559e7b 100644
--- a/src/crates/interfaces/app-server/AGENTS.md
+++ b/src/crates/interfaces/app-server/AGENTS.md
@@ -1,9 +1,10 @@
 [中文](AGENTS-CN.md) | **English**
 
-# App Server Server and Wiring Guide
+# App Server Interface Family Guide
 
-Scope: this guide applies only to `src/crates/interfaces/app-server` and its
-server-side production wiring.
+Scope: this guide applies to the adjacent `app-server-protocol`,
+`app-server-client`, and `app-server` crates, plus App Server production wiring.
+Server-specific rules apply to `app-server` unless stated otherwise.
 
 The App Server surface is split across four owners:
 
@@ -14,11 +15,15 @@ The App Server surface is split across four owners:
 | `app-server` | Server lifecycle, production handler registration, event forwarding, Runtime/domain-to-wire conversion, and error mapping |
 | Product Host under `src/apps/*` | Concrete transport, authentication, connection scope, capability/limit construction, platform capabilities, process supervision, and shutdown |
 
-Do not add new protocol or client ownership to this crate. Compatibility
+Do not add new protocol or client ownership to `bitfun-app-server`. Compatibility
 modules and re-exports may remain while consumers migrate, but new methods,
 DTOs, wire errors, and typed client behavior belong in the adjacent protocol
 and client crates.
 
+The `bitfun-app-server/ts` feature is a compatibility forwarder only. The
+protocol crate is the sole TypeScript schema exporter; do not add `ts-rs`,
+runtime implementation types, or a second export command back to this crate.
+
 ## Guardrails
 
 - Keep compatibility role and transport helpers schema-free. Do not hard-code
@@ -71,7 +76,8 @@ failures use helpers such as `BitfunAppRuntime::runtime_error` and
 ## Verification
 
 ```bash
-cargo check -p bitfun-app-server --offline
-cargo test -p bitfun-app-server --offline
+cargo check --locked -p bitfun-app-server --offline
+cargo test --locked -p bitfun-app-server --offline --lib server::wire::tests
+cargo test --locked -p bitfun-app-server-protocol --offline --test legacy_wire_contracts
 pnpm run check:core-boundaries
 ```
diff --git a/src/crates/interfaces/app-server/Cargo.toml b/src/crates/interfaces/app-server/Cargo.toml
index 8db5fcdcc5..b2a81f826c 100644
--- a/src/crates/interfaces/app-server/Cargo.toml
+++ b/src/crates/interfaces/app-server/Cargo.toml
@@ -14,35 +14,23 @@ bitfun-app-server-protocol = { path = "../app-server-protocol" }
 # Host-service handlers use the reviewed Agent Runtime owner closure. Add a
 # narrower Core owner feature when a newly registered domain needs it; the
 # protocol surface must not inherit the broad bitfun-core/product-full union.
-bitfun-core = { path = "../../assembly/core", default-features = false, features = ["external-sources", "git", "remote-connect"] }
-bitfun-agent-runtime = { path = "../../execution/agent-runtime" }
-bitfun-events = { path = "../../contracts/events" }
-bitfun-product-domains = { path = "../../contracts/product-domains", default-features = false, features = ["external-sources"] }
-bitfun-runtime-ports = { path = "../../contracts/runtime-ports" }
+bitfun-core = { path = "../../assembly/core", features = ["external-sources", "git", "i18n-runtime", "remote-connect"] }
+bitfun-agent-runtime = { path = "../../execution/agent-runtime", features = ["agent-runtime"] }
+bitfun-product-domains = { path = "../../contracts/product-domains", features = ["external-sources"] }
+bitfun-runtime-ports = { path = "../../contracts/runtime-ports", features = ["agent-api"] }
 tokio = { workspace = true, features = ["macros", "rt", "sync", "time"] }
-tokio-util = { workspace = true, features = ["compat"] }
-futures = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
 anyhow = { workspace = true }
 log = { workspace = true }
 tracing = { workspace = true }
 url = { workspace = true }
-ts-rs = { workspace = true, optional = true }
 
 [features]
 default = []
-# Schema-first TypeScript binding export. Derives `ts_rs::TS` (via
-# `cfg_attr`) on the wire types under `src/schema/` and propagates the `ts` feature
-# to the upstream contract/service crates so every type the schema references
-# also implements `TS`. Run `cargo test --features ts export_types` (or the
-# frontend `gen:types` script) to emit `.ts` into `TS_RS_EXPORT_DIR`.
-ts = [
-    "dep:ts-rs",
-    "bitfun-app-server-protocol/ts",
-    "bitfun-core/ts",
-    "bitfun-runtime-ports/ts",
-]
+# Compatibility feature for existing callers. TypeScript schemas are owned and
+# exported by `bitfun-app-server-protocol`.
+ts = ["bitfun-app-server-protocol/ts"]
 
 [lints]
 workspace = true
diff --git a/src/crates/interfaces/app-server/src/client.rs b/src/crates/interfaces/app-server/src/client.rs
deleted file mode 100644
index d4a64c724e..0000000000
--- a/src/crates/interfaces/app-server/src/client.rs
+++ /dev/null
@@ -1,781 +0,0 @@
-//! Generic app-server client: drives an [`AppClient`] connection over a
-//! host-supplied transport and exposes the agent kernel RPC surface.
-//!
-//! This module is the client counterpart of [`crate::server::BitfunAppServer`].
-//! It is **transport-agnostic**: the host picks the transport (in-memory pair,
-//! stdio, websocket, ...) and passes the client half to [`connect`]. The
-//! server half is driven by the host through [`BitfunAppServer::serve`], so
-//! this client never decides how the server is started -- it only owns the
-//! client end of one connection.
-//!
-//! [`connect`] builds an [`AppClient`] on the given transport, parks the
-//! [`ConnectionTo<AppServer>`] for the lifetime of the returned handle, and
-//! registers `on_receive_notification` for `agent/event`. Each forwarded
-//! [`AgenticEventEnvelope`] is projected to the frontend shape (via
-//! [`bitfun_events::project_agentic_frontend_event`]) and fanned out through a
-//! [`tokio::sync::broadcast`] channel; consumers receive them via
-//! [`AppServerClient::subscribe_events`]. The client never subscribes to the
-//! runtime event queue directly, so all agent interfaces uniformly go through
-//! the app-server protocol surface.
-//!
-//! The connection-driving pattern mirrors the ACP client manager
-//! (`acp/src/client/manager.rs`): the `connect_with` main function parks the
-//! [`ConnectionTo<AppServer>`] through a oneshot and then awaits a shutdown
-//! signal so the connection task stays alive for the lifetime of the host.
-//!
-//! # In-process pairing
-//!
-//! A host that runs the server and client in the same process pairs them with
-//! [`crate::transport::in_memory_channel_pair`]:
-//!
-//! ```no_run
-//! # use bitfun_app_server::{AppClient, AppServer, transport};
-//! # use bitfun_app_server::client::connect;
-//! # async fn example() -> anyhow::Result<()> {
-//! // let (server_transport, client_transport) = transport::in_memory_channel_pair();
-//! // let _server = tokio::spawn(async { /* serve BitfunAppServer on server_transport */ });
-//! // let client = connect(client_transport).await?;
-//! # Ok(())
-//! # }
-//! ```
-
-use std::sync::Arc;
-use std::time::Duration;
-
-use agent_client_protocol::ConnectTo;
-use agent_client_protocol::{ConnectionTo, JsonRpcResponse, Result, SentRequest};
-use bitfun_events::project_agentic_frontend_event;
-use tokio::sync::{broadcast, oneshot};
-
-use crate::schema::{
-    CancelTurnMessage, CancelTurnResponse, ClearProjectPermissionGrantsMessage,
-    ClearProjectPermissionGrantsResponse, ConfigEventNotification, ConfigUpdate,
-    CreateSessionMessage, CreateSessionResponse, DeleteSessionMessage, DeleteSessionResponse,
-    ForkSessionAtTurnMessage, ForkSessionBeforeTurnMessage, ForkSessionMessage,
-    ForkSessionResponse, GetAgentProfileConfigMessage, GetAgentProfileConfigResponse,
-    GetAgentProfileConfigsMessage, GetAgentProfileConfigsResponse, GetConfigMessage,
-    GetConfigResponse, GetConfigsMessage, GetConfigsResponse, GetModelConfigsMessage,
-    GetModelConfigsResponse, GitBranchesRequest, GitGetBranchesMessage, GitGetBranchesResponse,
-    GitGetStatusMessage, GitGetStatusResponse, GitIsRepositoryMessage, GitIsRepositoryResponse,
-    GitRepositoryPathRequest, I18nGetConfigMessage, I18nGetCurrentLanguageMessage,
-    I18nGetCurrentLanguageResponse, I18nGetSupportedLanguagesMessage,
-    I18nGetSupportedLanguagesResponse, I18nSetConfigMessage, I18nSetConfigResponse,
-    I18nSetLanguageMessage, I18nSetLanguageResponse, ListPendingPermissionRequestsMessage,
-    ListPendingPermissionRequestsResponse, ListProjectPermissionAuditMessage,
-    ListProjectPermissionAuditResponse, ListProjectPermissionGrantsMessage,
-    ListProjectPermissionGrantsResponse, ListSessionsMessage, ListSessionsResponse,
-    PermissionEventNotification, RemoveProjectPermissionGrantMessage,
-    RemoveProjectPermissionGrantResponse, RenameSessionMessage, RenameSessionResponse,
-    ResetAgentProfileConfigMessage, ResetAgentProfileConfigResponse, RespondPermissionBatchMessage,
-    RespondPermissionBatchResponse, RespondPermissionMessage, RespondPermissionResponse,
-    RestoreSessionMessage, RunMessage, RunResponse, SessionEventNotification,
-    SetAgentProfileConfigMessage, SetAgentProfileConfigResponse, SetConfigMessage,
-    SetConfigResponse, SetSessionArchivedMessage, SetSessionArchivedResponse,
-    SubmitDialogTurnMessage, SubmitTurnMessage, SubmitTurnResponse, UpdateSessionModeMessage,
-    UpdateSessionModeResponse, UpdateSessionModelMessage, UpdateSessionModelResponse,
-};
-use crate::{AppClient, AppServer};
-
-/// Projected frontend event forwarded to consumers (websocket connections,
-/// Tauri event bridge, ...).
-#[derive(Debug, Clone)]
-pub struct FrontendEvent {
-    /// Frontend event name (`agent/event` projection).
-    pub event: String,
-    /// Projected payload, ready to serialize for the consumer's wire shape.
-    pub payload: serde_json::Value,
-}
-
-/// Startup grace for the in-process app-server client connection.
-const CLIENT_STARTUP_TIMEOUT: Duration = Duration::from_secs(5);
-
-/// Client handle for an app-server connection.
-///
-/// Cheaply cloneable: each clone shares the connection handle, the event
-/// broadcast sender, and the shutdown signal. Use [`AppServerClient::rpc`]
-/// (or the typed helpers) to route an agent kernel RPC through the app-server
-/// surface, and [`AppServerClient::subscribe_events`] to receive projected
-/// runtime events.
-///
-/// The connection is parked for the lifetime of this handle: the in-process
-/// `connect_task` that drives the `AppClient` connection parks on the shutdown
-/// receiver, and the `shutdown_tx` lives in the shared handle so the parked
-/// main loop only resumes when [`AppServerClient::shutdown`] is called or the
-/// last clone is dropped. Hosts that want the connection to live as long as
-/// the process (the Server Host pattern) simply hold a clone and never call
-/// `shutdown`.
-#[derive(Clone)]
-pub struct AppServerClient {
-    connection: Arc<ConnectionTo<AppServer>>,
-    event_tx: broadcast::Sender<FrontendEvent>,
-    config_event_tx: broadcast::Sender<ConfigUpdate>,
-    shutdown_tx: Arc<std::sync::Mutex<Option<oneshot::Sender<()>>>>,
-}
-
-impl AppServerClient {
-    /// Subscribe to projected frontend events. One receiver per consumer
-    /// (websocket connection, Tauri bridge, ...); dropping the last receiver
-    /// does not close the server.
-    pub fn subscribe_events(&self) -> broadcast::Receiver<FrontendEvent> {
-        self.event_tx.subscribe()
-    }
-
-    /// Subscribe to canonical configuration updates from `config/event`.
-    pub fn subscribe_config_updates(&self) -> broadcast::Receiver<ConfigUpdate> {
-        self.config_event_tx.subscribe()
-    }
-
-    /// Shut down the in-process app-server client connection. Signals the
-    /// parked `connect_task` to resume, which lets the connection's background
-    /// actors (task/outgoing/incoming/responder) unwind and close the
-    /// transport. Safe to call more than once; subsequent calls are no-ops.
-    /// Hosts that want the connection to live for the process lifetime simply
-    /// never call this.
-    pub async fn shutdown(&self) {
-        if let Some(tx) = self
-            .shutdown_tx
-            .lock()
-            .ok()
-            .and_then(|mut guard| guard.take())
-        {
-            let _ = tx.send(());
-        }
-    }
-
-    /// Create an agent session via `agent/createSession`.
-    pub async fn create_session(
-        &self,
-        request: bitfun_agent_runtime::sdk::AgentSessionCreateRequest,
-    ) -> Result<bitfun_agent_runtime::sdk::AgentSessionCreateResult> {
-        let CreateSessionResponse(inner) = self
-            .rpc(|cx| cx.send_request(CreateSessionMessage(request)))
-            .await?;
-        Ok(inner)
-    }
-
-    /// List agent sessions via `agent/listSessions`.
-    pub async fn list_sessions(
-        &self,
-        request: bitfun_agent_runtime::sdk::AgentSessionListRequest,
-    ) -> Result<Vec<bitfun_agent_runtime::sdk::AgentSessionSummary>> {
-        let ListSessionsResponse { sessions } = self
-            .rpc(|cx| cx.send_request(ListSessionsMessage(request)))
-            .await?;
-        Ok(sessions)
-    }
-
-    /// Delete an agent session via `agent/deleteSession`.
-    pub async fn delete_session(
-        &self,
-        request: bitfun_agent_runtime::sdk::AgentSessionDeleteRequest,
-    ) -> Result<()> {
-        let DeleteSessionResponse {} = self
-            .rpc(|cx| cx.send_request(DeleteSessionMessage(request)))
-            .await?;
-        Ok(())
-    }
-
-    /// Rename a persisted Session through the Runtime Session owner.
-    pub async fn rename_session(
-        &self,
-        request: bitfun_agent_runtime::sdk::AgentSessionRenameRequest,
-    ) -> Result<()> {
-        let RenameSessionResponse {} = self
-            .rpc(|cx| cx.send_request(RenameSessionMessage(request)))
-            .await?;
-        Ok(())
-    }
-
-    /// Set the persisted archive state through the Runtime Session owner.
-    pub async fn set_session_archived(
-        &self,
-        request: bitfun_agent_runtime::sdk::AgentSessionArchiveStateRequest,
-    ) -> Result<()> {
-        let SetSessionArchivedResponse {} = self
-            .rpc(|cx| cx.send_request(SetSessionArchivedMessage(request)))
-            .await?;
-        Ok(())
-    }
-
-    /// Update the selected model for an already loaded Session.
-    pub async fn update_session_model(
-        &self,
-        request: bitfun_agent_runtime::sdk::AgentSessionModelUpdateRequest,
-    ) -> Result<()> {
-        let UpdateSessionModelResponse {} = self
-            .rpc(|cx| cx.send_request(UpdateSessionModelMessage(request)))
-            .await?;
-        Ok(())
-    }
-
-    /// Update the selected mode for an already loaded Session.
-    pub async fn update_session_mode(
-        &self,
-        request: bitfun_agent_runtime::sdk::AgentSessionModeUpdateRequest,
-    ) -> Result<()> {
-        let UpdateSessionModeResponse {} = self
-            .rpc(|cx| cx.send_request(UpdateSessionModeMessage(request)))
-            .await?;
-        Ok(())
-    }
-
-    /// Fork a Session at its latest persisted turn.
-    pub async fn fork_session(
-        &self,
-        request: bitfun_agent_runtime::sdk::AgentSessionForkRequest,
-    ) -> Result<bitfun_agent_runtime::sdk::AgentSessionForkResult> {
-        let ForkSessionResponse(result) = self
-            .rpc(|cx| cx.send_request(ForkSessionMessage(request)))
-            .await?;
-        Ok(result)
-    }
-
-    /// Fork a Session including the selected persisted turn.
-    pub async fn fork_session_at_turn(
-        &self,
-        request: bitfun_agent_runtime::sdk::AgentSessionForkAtTurnRequest,
-    ) -> Result<bitfun_agent_runtime::sdk::AgentSessionForkResult> {
-        let ForkSessionResponse(result) = self
-            .rpc(|cx| cx.send_request(ForkSessionAtTurnMessage(request)))
-            .await?;
-        Ok(result)
-    }
-
-    /// Fork a Session immediately before the selected persisted turn.
-    pub async fn fork_session_before_turn(
-        &self,
-        request: bitfun_agent_runtime::sdk::AgentSessionForkBeforeTurnRequest,
-    ) -> Result<bitfun_agent_runtime::sdk::AgentSessionForkResult> {
-        let ForkSessionResponse(result) = self
-            .rpc(|cx| cx.send_request(ForkSessionBeforeTurnMessage(request)))
-            .await?;
-        Ok(result)
-    }
-
-    /// Restore a persisted Session into the Runtime owner.
-    pub async fn restore_session(
-        &self,
-        request: bitfun_agent_runtime::sdk::AgentSessionRestoreRequest,
-    ) -> Result<bitfun_agent_runtime::sdk::AgentSessionRestoreResult> {
-        let response = self
-            .rpc(|cx| {
-                cx.send_request(RestoreSessionMessage {
-                    workspace_path: request.workspace_path,
-                    session_id: request.session_id,
-                    include_internal: request.include_internal,
-                    remote_connection_id: request.remote_connection_id,
-                    remote_ssh_host: request.remote_ssh_host,
-                })
-            })
-            .await?;
-        Ok(response.into())
-    }
-
-    /// Submit a turn via `agent/submitTurn`.
-    pub async fn submit_turn(
-        &self,
-        request: bitfun_agent_runtime::sdk::AgentSubmissionRequest,
-    ) -> Result<bitfun_agent_runtime::sdk::AgentSubmissionResult> {
-        let SubmitTurnResponse(inner) = self
-            .rpc(|cx| cx.send_request(SubmitTurnMessage(request)))
-            .await?;
-        Ok(inner)
-    }
-
-    /// Submit a dialog turn via `agent/submitDialogTurn`.
-    ///
-    /// This is the operation the desktop `start_dialog_turn` command drives and
-    /// the one web/CLI hosts should map `startDialogTurn`-style calls to: it
-    /// carries `agentType`/`workspacePath`/`policy`, unlike `submit_turn` which
-    /// is a bare message into an existing session. The response reports whether
-    /// the turn started immediately or was queued.
-    pub async fn submit_dialog_turn(
-        &self,
-        body: crate::schema::SubmitDialogTurnBody,
-    ) -> Result<crate::schema::SubmitDialogTurnResponse> {
-        self.rpc(|cx| cx.send_request(SubmitDialogTurnMessage(body)))
-            .await
-    }
-
-    /// Cancel a turn via `agent/cancelTurn`.
-    pub async fn cancel_turn(
-        &self,
-        request: bitfun_agent_runtime::sdk::AgentTurnCancellationRequest,
-    ) -> Result<bitfun_agent_runtime::sdk::AgentTurnCancellationResult> {
-        let CancelTurnResponse(inner) = self
-            .rpc(|cx| cx.send_request(CancelTurnMessage(request)))
-            .await?;
-        Ok(inner)
-    }
-
-    /// Respond to a permission request via `agent/respondPermission`.
-    pub async fn respond_permission(
-        &self,
-        request_id: &str,
-        reply: bitfun_agent_runtime::sdk::PermissionReply,
-    ) -> Result<()> {
-        let RespondPermissionResponse {} = self
-            .rpc(|cx| {
-                cx.send_request(RespondPermissionMessage {
-                    request_id: request_id.to_string(),
-                    reply,
-                })
-            })
-            .await?;
-        Ok(())
-    }
-
-    /// Respond to a permission request and all requests sharing its reply via
-    /// `agent/respondPermissionBatch`. Returns the request ids that shared the
-    /// resolved reply.
-    pub async fn respond_permission_batch(
-        &self,
-        request_id: &str,
-        reply: bitfun_agent_runtime::sdk::PermissionReply,
-    ) -> Result<Vec<String>> {
-        let RespondPermissionBatchResponse { request_ids } = self
-            .rpc(|cx| {
-                cx.send_request(RespondPermissionBatchMessage {
-                    request_id: request_id.to_string(),
-                    reply,
-                })
-            })
-            .await?;
-        Ok(request_ids)
-    }
-
-    /// List pending permission requests via `agent/listPendingPermissionRequests`.
-    pub async fn list_pending_permission_requests(
-        &self,
-    ) -> Result<Vec<bitfun_agent_runtime::sdk::PermissionRequest>> {
-        let ListPendingPermissionRequestsResponse { requests } = self
-            .rpc(|cx| cx.send_request(ListPendingPermissionRequestsMessage {}))
-            .await?;
-        Ok(requests)
-    }
-
-    /// List project permission grants via `agent/listProjectPermissionGrants`.
-    pub async fn list_project_permission_grants(
-        &self,
-        project_id: &str,
-    ) -> Result<Vec<bitfun_agent_runtime::sdk::PermissionGrant>> {
-        let ListProjectPermissionGrantsResponse { grants } = self
-            .rpc(|cx| {
-                cx.send_request(ListProjectPermissionGrantsMessage {
-                    project_id: project_id.to_string(),
-                })
-            })
-            .await?;
-        Ok(grants)
-    }
-
-    /// Remove a project permission grant via `agent/removeProjectPermissionGrant`.
-    pub async fn remove_project_permission_grant(
-        &self,
-        key: bitfun_agent_runtime::sdk::PermissionGrantKey,
-    ) -> Result<bool> {
-        let RemoveProjectPermissionGrantResponse { removed } = self
-            .rpc(|cx| cx.send_request(RemoveProjectPermissionGrantMessage(key)))
-            .await?;
-        Ok(removed)
-    }
-
-    /// Clear all permission grants for a project via
-    /// `agent/clearProjectPermissionGrants`. Returns the count cleared.
-    pub async fn clear_project_permission_grants(&self, project_id: &str) -> Result<usize> {
-        let ClearProjectPermissionGrantsResponse { cleared } = self
-            .rpc(|cx| {
-                cx.send_request(ClearProjectPermissionGrantsMessage {
-                    project_id: project_id.to_string(),
-                })
-            })
-            .await?;
-        Ok(cleared)
-    }
-
-    /// List the permission audit log for a project via
-    /// `agent/listProjectPermissionAudit`.
-    pub async fn list_project_permission_audit(
-        &self,
-        project_id: &str,
-    ) -> Result<Vec<bitfun_agent_runtime::sdk::PermissionAuditRecord>> {
-        let ListProjectPermissionAuditResponse { records } = self
-            .rpc(|cx| {
-                cx.send_request(ListProjectPermissionAuditMessage {
-                    project_id: project_id.to_string(),
-                })
-            })
-            .await?;
-        Ok(records)
-    }
-
-    /// Run an agent turn (create-or-existing) via `agent/run`.
-    pub async fn run(&self, request: RunMessage) -> Result<RunResponse> {
-        self.rpc(|cx| cx.send_request(request)).await
-    }
-
-    /// Check whether a path is a Git repository via `git/isRepository`.
-    pub async fn git_is_repository(&self, repository_path: &str) -> Result<bool> {
-        let GitIsRepositoryResponse(value) = self
-            .rpc(|cx| {
-                cx.send_request(GitIsRepositoryMessage(GitRepositoryPathRequest {
-                    repository_path: repository_path.to_string(),
-                }))
-            })
-            .await?;
-        Ok(value)
-    }
-
-    /// Get the working-tree status of a Git repository via `git/getStatus`.
-    pub async fn git_get_status(
-        &self,
-        repository_path: &str,
-    ) -> Result<bitfun_core::service::git::GitStatus> {
-        let GitGetStatusResponse(status) = self
-            .rpc(|cx| {
-                cx.send_request(GitGetStatusMessage(GitRepositoryPathRequest {
-                    repository_path: repository_path.to_string(),
-                }))
-            })
-            .await?;
-        Ok(status)
-    }
-
-    /// List the branches of a Git repository via `git/getBranches`.
-    pub async fn git_get_branches(
-        &self,
-        repository_path: &str,
-        include_remote: bool,
-    ) -> Result<Vec<bitfun_core::service::git::GitBranch>> {
-        let GitGetBranchesResponse { branches } = self
-            .rpc(|cx| {
-                cx.send_request(GitGetBranchesMessage(GitBranchesRequest {
-                    repository_path: repository_path.to_string(),
-                    include_remote: Some(include_remote),
-                }))
-            })
-            .await?;
-        Ok(branches)
-    }
-
-    /// List all agent profile configs via `config/getAgentProfileConfigs`.
-    pub async fn get_agent_profile_configs(
-        &self,
-    ) -> Result<std::collections::HashMap<String, bitfun_core::service::config::AgentProfileView>>
-    {
-        let GetAgentProfileConfigsResponse { profiles } = self
-            .rpc(|cx| cx.send_request(GetAgentProfileConfigsMessage {}))
-            .await?;
-        Ok(profiles)
-    }
-
-    /// Get a single agent profile config via `config/getAgentProfileConfig`.
-    pub async fn get_agent_profile_config(
-        &self,
-        agent_id: &str,
-    ) -> Result<bitfun_core::service::config::AgentProfileView> {
-        let GetAgentProfileConfigResponse(view) = self
-            .rpc(|cx| {
-                cx.send_request(GetAgentProfileConfigMessage {
-                    agent_id: agent_id.to_string(),
-                })
-            })
-            .await?;
-        Ok(view)
-    }
-
-    /// List all AI model configs via `config/getModelConfigs`.
-    pub async fn get_model_configs(
-        &self,
-    ) -> Result<Vec<bitfun_core::service::config::AIModelConfig>> {
-        let GetModelConfigsResponse { models } = self
-            .rpc(|cx| cx.send_request(GetModelConfigsMessage {}))
-            .await?;
-        Ok(models)
-    }
-
-    /// Read a single config path via `config/getConfig`. Returns the raw JSON
-    /// value at that path (`None` path reads the whole config tree). A missing
-    /// path surfaces as an error whose `message` matches the desktop contract
-    /// (`Failed to get config: Not found: Config path '<path>' not found`) so
-    /// the frontend `ConfigAPI.getConfig` can swallow it into `undefined`.
-    pub async fn get_config(&self, path: Option<&str>) -> Result<serde_json::Value> {
-        let GetConfigResponse(value) = self
-            .rpc(|cx| {
-                cx.send_request(GetConfigMessage {
-                    path: path.map(str::to_string),
-                    skip_retry_on_not_found: false,
-                })
-            })
-            .await?;
-        Ok(value)
-    }
-
-    /// Read multiple config paths in one batch via `config/getConfigs`.
-    /// Returns a path -> value map; paths are deduped server-side the way the
-    /// desktop host does. The first not-found path aborts the batch and
-    /// surfaces the same not-found message shape as [`get_config`].
-    pub async fn get_configs(
-        &self,
-        paths: &[String],
-    ) -> Result<std::collections::BTreeMap<String, serde_json::Value>> {
-        let GetConfigsResponse { configs } = self
-            .rpc(|cx| {
-                cx.send_request(GetConfigsMessage {
-                    paths: paths.to_vec(),
-                    skip_retry_on_not_found: false,
-                })
-            })
-            .await?;
-        Ok(configs)
-    }
-
-    /// Write a value at a config path via `config/setConfig` (Track B). The
-    /// handler reaches the global config singleton the Desktop host uses.
-    pub async fn set_config(&self, path: &str, value: serde_json::Value) -> Result<()> {
-        let SetConfigResponse {} = self
-            .rpc(|cx| {
-                cx.send_request(SetConfigMessage {
-                    path: path.to_string(),
-                    value,
-                })
-            })
-            .await?;
-        Ok(())
-    }
-
-    /// Canonicalize and persist one agent profile, returning the effective view.
-    pub async fn set_agent_profile_config(
-        &self,
-        agent_id: &str,
-        config: serde_json::Value,
-    ) -> Result<bitfun_core::service::config::AgentProfileView> {
-        let SetAgentProfileConfigResponse(view) = self
-            .rpc(|cx| {
-                cx.send_request(SetAgentProfileConfigMessage {
-                    agent_id: agent_id.to_string(),
-                    config,
-                })
-            })
-            .await?;
-        Ok(view)
-    }
-
-    /// Reset one agent profile and return the effective default view.
-    pub async fn reset_agent_profile_config(
-        &self,
-        agent_id: &str,
-    ) -> Result<bitfun_core::service::config::AgentProfileView> {
-        let ResetAgentProfileConfigResponse(view) = self
-            .rpc(|cx| {
-                cx.send_request(ResetAgentProfileConfigMessage {
-                    agent_id: agent_id.to_string(),
-                })
-            })
-            .await?;
-        Ok(view)
-    }
-
-    /// Read the current runtime locale id via `i18n/getCurrentLanguage`.
-    pub async fn i18n_get_current_language(&self) -> Result<String> {
-        let I18nGetCurrentLanguageResponse { language } = self
-            .rpc(|cx| cx.send_request(I18nGetCurrentLanguageMessage {}))
-            .await?;
-        Ok(language)
-    }
-
-    /// Set the runtime locale via `i18n/setLanguage` and sync the global
-    /// I18nService. Returns the validated locale id that was applied.
-    pub async fn i18n_set_language(&self, language: &str) -> Result<String> {
-        let I18nSetLanguageResponse { language } = self
-            .rpc(|cx| {
-                cx.send_request(I18nSetLanguageMessage {
-                    language: language.to_string(),
-                })
-            })
-            .await?;
-        Ok(language)
-    }
-
-    /// Read the i18n config (current/fallback language, autoDetect) via
-    /// `i18n/getConfig`.
-    pub async fn i18n_get_config(&self) -> Result<crate::schema::I18nGetConfigResponse> {
-        let response = self
-            .rpc(|cx| cx.send_request(I18nGetConfigMessage {}))
-            .await?;
-        Ok(response)
-    }
-
-    /// Write the i18n config (writes `currentLanguage` and syncs the I18nService)
-    /// via `i18n/setConfig`.
-    pub async fn i18n_set_config(
-        &self,
-        current_language: Option<&str>,
-        fallback_language: Option<&str>,
-        auto_detect: bool,
-    ) -> Result<()> {
-        let I18nSetConfigResponse {} = self
-            .rpc(|cx| {
-                cx.send_request(I18nSetConfigMessage {
-                    current_language: current_language.map(str::to_string),
-                    fallback_language: fallback_language.map(str::to_string),
-                    auto_detect,
-                })
-            })
-            .await?;
-        Ok(())
-    }
-
-    /// List all supported locales via `i18n/getSupportedLanguages`.
-    pub async fn i18n_get_supported_languages(
-        &self,
-    ) -> Result<Vec<crate::schema::I18nLocaleMetadata>> {
-        let I18nGetSupportedLanguagesResponse { locales } = self
-            .rpc(|cx| cx.send_request(I18nGetSupportedLanguagesMessage {}))
-            .await?;
-        Ok(locales)
-    }
-
-    /// Send a JSON-RPC request through the app-server connection and await its
-    /// response. Uses the canonical `on_receiving_result` + oneshot pattern
-    /// (mirrors the app-server round-trip tests) so the calling task is not
-    /// blocked on the connection driver.
-    async fn rpc<F, R>(&self, send: F) -> Result<R>
-    where
-        F: FnOnce(&ConnectionTo<AppServer>) -> SentRequest<R>,
-        R: JsonRpcResponse + Send,
-    {
-        let sent = send(&self.connection);
-        let (tx, rx) = oneshot::channel();
-        sent.on_receiving_result(async move |result| {
-            tx.send(result)
-                .map_err(|_| agent_client_protocol::Error::internal_error())
-        })?;
-        rx.await
-            .map_err(|_| agent_client_protocol::Error::internal_error())?
-    }
-}
-
-/// Connect an app-server client over a host-supplied transport.
-///
-/// Drives an [`AppClient`] on `transport`, parks the [`ConnectionTo<AppServer>`]
-/// for the lifetime of the returned handle, and fans projected `agent/event`
-/// notifications out through the returned [`AppServerClient`]. The host owns the
-/// transport and the server half of the connection (for example it spawns
-/// [`crate::BitfunAppServer::serve`] on the server half of an
-/// [`crate::transport::in_memory_channel_pair`] before calling this).
-///
-/// The connection is parked for the lifetime of the host: the shutdown signal
-/// is intentionally never sent, so the spawned connection task (which owns the
-/// transport) stays alive while the [`AppServerClient`] is in use.
-///
-/// # Errors
-///
-/// Returns an error if the connection closes or the startup handshake does not
-/// complete within the startup grace window.
-pub async fn connect(
-    transport: impl ConnectTo<AppClient> + 'static,
-) -> std::result::Result<AppServerClient, anyhow::Error> {
-    // Event fan-out: the client receives `agent/event` notifications forwarded
-    // by the app-server, projects each envelope to the frontend shape, and
-    // broadcasts it to consumers.
-    let (event_tx, _) = broadcast::channel::<FrontendEvent>(1024);
-    let event_tx_for_task = event_tx.clone();
-    let (config_event_tx, _) = broadcast::channel::<ConfigUpdate>(256);
-    let config_event_tx_for_task = config_event_tx.clone();
-
-    // Park the connection handle through a oneshot, then await a never-sent
-    // shutdown signal so `connect_with`'s main_fn keeps the connection alive.
-    let (cx_tx, cx_rx) = oneshot::channel::<ConnectionTo<AppServer>>();
-    let (shutdown_tx, shutdown_rx) = oneshot::channel::<()>();
-    let connect_task = tokio::spawn(async move {
-        let result = AppClient
-            .builder()
-            .name("bitfun-app-client")
-            .on_receive_notification(
-                {
-                    let event_tx = event_tx_for_task.clone();
-                    async move |notification: SessionEventNotification,
-                                _cx: ConnectionTo<AppServer>| {
-                        let SessionEventNotification {
-                            event: envelope, ..
-                        } = notification;
-                        if let Some(projected) = project_agentic_frontend_event(envelope.event) {
-                            let _ = event_tx.send(FrontendEvent {
-                                event: projected.event_name,
-                                payload: projected.payload,
-                            });
-                        }
-                        Ok(())
-                    }
-                },
-                agent_client_protocol::on_receive_notification!(),
-            )
-            .on_receive_notification(
-                async move |notification: ConfigEventNotification, _cx: ConnectionTo<AppServer>| {
-                    let ConfigEventNotification { event, .. } = notification;
-                    let _ = config_event_tx_for_task.send(event);
-                    Ok(())
-                },
-                agent_client_protocol::on_receive_notification!(),
-            )
-            .on_receive_notification(
-                {
-                    let event_tx = event_tx_for_task;
-                    async move |notification: PermissionEventNotification,
-                                _cx: ConnectionTo<AppServer>| {
-                        let PermissionEventNotification { event, .. } = notification;
-                        // Project the permission lifecycle event to the frontend
-                        // `permission://event` channel the desktop host uses, so
-                        // consumers can listen on the same name in web and desktop.
-                        if let Ok(payload) = serde_json::to_value(&event) {
-                            let _ = event_tx.send(FrontendEvent {
-                                event: "permission://event".to_string(),
-                                payload,
-                            });
-                        }
-                        Ok(())
-                    }
-                },
-                agent_client_protocol::on_receive_notification!(),
-            )
-            .connect_with(transport, async |cx: ConnectionTo<AppServer>| {
-                let _ = cx_tx.send(cx);
-                let _ = shutdown_rx.await;
-                Ok(())
-            })
-            .await;
-        if let Err(error) = &result {
-            log::warn!("App-server client connection ended with error: {:?}", error);
-        }
-    });
-
-    let connection = match tokio::time::timeout(CLIENT_STARTUP_TIMEOUT, cx_rx).await {
-        Ok(Ok(cx)) => cx,
-        Ok(Err(_)) => {
-            connect_task.abort();
-            anyhow::bail!("App-server client connection closed before startup completed");
-        }
-        Err(_) => {
-            connect_task.abort();
-            anyhow::bail!("App-server client connection startup timed out");
-        }
-    };
-
-    // The connection is parked for the lifetime of the host: the `shutdown_tx`
-    // lives in the returned handle so the parked `connect_task` main loop only
-    // resumes when the host calls `shutdown` (or drops the last clone). The
-    // Server Host holds the handle for the process lifetime and never calls
-    // `shutdown`, so the connection -- and therefore the in-process app-server
-    // `BitfunAppServer` it is paired with -- stays alive as long as the server
-    // does. (Previously this was `let _ = shutdown_tx;`, which dropped the
-    // sender immediately and let the parked main loop resume right after
-    // `connect` returned, killing the connection -- every subsequent RPC then
-    // surfaced as `send failed because receiver is gone`.)
-    Ok(AppServerClient {
-        connection: Arc::new(connection),
-        event_tx,
-        config_event_tx,
-        shutdown_tx: Arc::new(std::sync::Mutex::new(Some(shutdown_tx))),
-    })
-}
diff --git a/src/crates/interfaces/app-server/src/lib.rs b/src/crates/interfaces/app-server/src/lib.rs
index 19ff651f57..929a4da7cb 100644
--- a/src/crates/interfaces/app-server/src/lib.rs
+++ b/src/crates/interfaces/app-server/src/lib.rs
@@ -1,4 +1,4 @@
-//! BitFun generic JSON-RPC app-server surface.
+//! BitFun generic JSON-RPC App Server host surface.
 //!
 //! This crate owns a protocol-agnostic JSON-RPC server/client scaffold built on
 //! [`agent_client_protocol`] using custom roles ([`AppServer`]/[`AppClient`]),
@@ -6,12 +6,11 @@
 //! own `JsonRpcRequest` / `JsonRpcNotification` types; the crate binds no
 //! schema method set, unlike [`bitfun_acp`].
 //!
-//! The optional `agent` module is the Phase 2 wiring: [`BitfunAppServer`]
-//! exposes a ready set of agent kernel operations (create / list / delete /
-//! submit / run / cancel) over a host-injected [`AgentRuntime`], using the
-//! generic `AppServer` role and the schema in [`schema`]. Hosts that want a
-//! purely schema-free scaffold can ignore `agent` / `schema` / `server` and
-//! register their own message types directly on `AppServer::builder()`.
+//! [`BitfunAppServer`] exposes the selected Agent Kernel and management
+//! operations over a host-injected runtime. Behavior-light wire contracts are
+//! owned by `bitfun-app-server-protocol`; [`schema`] remains a compatibility
+//! re-export for existing server-side imports. Typed clients are owned by the
+//! separate `bitfun-app-server-client` crate.
 //!
 //! # Example
 //!
@@ -35,15 +34,12 @@
 //!
 //! [`bitfun_acp`]: bitfun_acp
 //!
-//! # Crate boundary (preview)
+//! # Crate boundary
 //!
 //! This crate is an **internal interface crate**, not a versioned public API.
 //! The server-side surface ([`BitfunAppServer`], [`schema`], [`agent`]) is the
-//! production path consumed by the Server Host. The client-side exports
-//! ([`AppServerClient`], [`FrontendEvent`], [`connect`]) are test-only
-//! utilities -- they have no production consumer and are `#[doc(hidden)]` to
-//! avoid implying a stable public SDK. They will be replaced by a proper
-//! versioned event envelope and connection protocol in a follow-up.
+//! production path consumed by the Server Host. This crate does not own a
+//! second client implementation.
 
 // Lifted from the default 128: the `AppServer` builder chains one
 // `ChainedHandler` layer per registered request handler, and with the
@@ -55,7 +51,6 @@
 #![recursion_limit = "256"]
 
 pub mod agent;
-pub mod client;
 pub mod management;
 pub mod role;
 pub mod schema;
@@ -64,12 +59,6 @@ pub mod transport;
 
 pub use agent::BitfunAppRuntime;
 pub use agent_client_protocol as protocol;
-// `connect`, `AppServerClient`, and `FrontendEvent` are test-only utilities
-// with no production consumer. They are `#[doc(hidden)]` to avoid implying a
-// versioned public client SDK; they will be replaced by a proper versioned
-// event envelope in a follow-up.
-#[doc(hidden)]
-pub use client::{connect, AppServerClient, FrontendEvent};
 pub use management::{
     AppManagementCapabilities, AppManagementError, AppManagementErrorKind, AppManagementResult,
     AppManagementService, EXTERNAL_HOOKS_CAPABILITY, EXTERNAL_SOURCES_CAPABILITY,
@@ -81,8 +70,7 @@ pub use server::BitfunAppServer;
 /// Convenience prelude for consumers building an app-server connection.
 pub mod prelude {
     pub use crate::{
-        agent, client, schema, server, transport, AppClient, AppServer, BitfunAppRuntime,
-        BitfunAppServer,
+        agent, schema, server, transport, AppClient, AppServer, BitfunAppRuntime, BitfunAppServer,
     };
     pub use agent_client_protocol::{
         Builder, ConnectionTo, Dispatch, Handled, JsonRpcNotification, JsonRpcRequest,
diff --git a/src/crates/interfaces/app-server/src/management.rs b/src/crates/interfaces/app-server/src/management.rs
index 79534bc75f..b1b4ac8e26 100644
--- a/src/crates/interfaces/app-server/src/management.rs
+++ b/src/crates/interfaces/app-server/src/management.rs
@@ -93,6 +93,7 @@ impl AppManagementCapabilities {
                 self.models.clone(),
                 &[
                     "config/getTuiModelCatalog",
+                    "model/projectReasoningCatalog",
                     "model/list",
                     "model/get",
                     "model/add",
diff --git a/src/crates/interfaces/app-server/src/management/service.rs b/src/crates/interfaces/app-server/src/management/service.rs
index 3a87bd2f52..1513d809a4 100644
--- a/src/crates/interfaces/app-server/src/management/service.rs
+++ b/src/crates/interfaces/app-server/src/management/service.rs
@@ -1352,6 +1352,15 @@ impl AppManagementService {
         })
     }
 
+    pub async fn project_reasoning_catalog(
+        &self,
+        request: ProjectReasoningCatalogRequest,
+    ) -> AppManagementResult<ProjectReasoningCatalogResponse> {
+        Ok(ProjectReasoningCatalogResponse {
+            projection: bitfun_core::project_ai_model_reasoning_catalog(request.0).await,
+        })
+    }
+
     pub async fn add_model(
         &self,
         request: AddModelRequest,
diff --git a/src/crates/interfaces/app-server/src/schema/agent.rs b/src/crates/interfaces/app-server/src/schema/agent.rs
deleted file mode 100644
index cb9fcfc937..0000000000
--- a/src/crates/interfaces/app-server/src/schema/agent.rs
+++ /dev/null
@@ -1,234 +0,0 @@
-use agent_client_protocol::{JsonRpcRequest, JsonRpcResponse};
-use bitfun_agent_runtime::sdk::{
-    AgentDialogTurnExecution, AgentDialogTurnRequest, AgentInputAttachment, AgentRunHandle,
-    AgentRunRequest, AgentSessionCreateRequest, AgentSessionCreateResult,
-    AgentSessionDeleteRequest, AgentSessionListRequest, AgentSessionSummary,
-    AgentSubmissionRequest, AgentSubmissionResult, AgentSubmissionSource,
-    AgentTurnCancellationRequest, AgentTurnCancellationResult, DialogSubmissionPolicy,
-    DialogSubmitOutcome, SessionSelector,
-};
-use serde::{Deserialize, Serialize};
-
-/// `agent/createSession` request body (wraps the port request type).
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
-#[request(method = "agent/createSession", response = CreateSessionResponse)]
-pub struct CreateSessionMessage(pub AgentSessionCreateRequest);
-
-/// `agent/createSession` response body (wraps the port result type).
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
-pub struct CreateSessionResponse(pub AgentSessionCreateResult);
-
-/// `agent/listSessions` request body.
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
-#[request(method = "agent/listSessions", response = ListSessionsResponse)]
-pub struct ListSessionsMessage(pub AgentSessionListRequest);
-
-/// `agent/listSessions` response body.
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-pub struct ListSessionsResponse {
-    pub sessions: Vec<AgentSessionSummary>,
-}
-
-/// `agent/deleteSession` request body.
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
-#[request(method = "agent/deleteSession", response = DeleteSessionResponse)]
-pub struct DeleteSessionMessage(pub AgentSessionDeleteRequest);
-
-/// `agent/deleteSession` response body.
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-pub struct DeleteSessionResponse {}
-
-/// `agent/submitTurn` request body.
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
-#[request(method = "agent/submitTurn", response = SubmitTurnResponse)]
-pub struct SubmitTurnMessage(pub AgentSubmissionRequest);
-
-/// `agent/submitTurn` response body.
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
-pub struct SubmitTurnResponse(pub AgentSubmissionResult);
-
-/// `agent/submitDialogTurn` request body.
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
-#[request(method = "agent/submitDialogTurn", response = SubmitDialogTurnResponse)]
-pub struct SubmitDialogTurnMessage(pub SubmitDialogTurnBody);
-
-/// Wire form of [`AgentDialogTurnRequest`] with an optional `policy`.
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[serde(rename_all = "camelCase")]
-pub struct SubmitDialogTurnBody {
-    pub session_id: String,
-    pub message: String,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub original_message: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub turn_id: Option<String>,
-    #[serde(default, skip_serializing_if = "AgentDialogTurnExecution::is_standard")]
-    pub execution: AgentDialogTurnExecution,
-    pub agent_type: String,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub workspace_path: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_connection_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_ssh_host: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub policy: Option<DialogSubmissionPolicy>,
-    #[serde(default, skip_serializing_if = "Vec::is_empty")]
-    pub attachments: Vec<AgentInputAttachment>,
-    #[serde(default, skip_serializing_if = "serde_json::Map::is_empty")]
-    pub metadata: serde_json::Map<String, serde_json::Value>,
-}
-
-impl SubmitDialogTurnBody {
-    /// Build the runtime request, defaulting `policy` to the desktop UI source.
-    pub fn to_request(self) -> AgentDialogTurnRequest {
-        AgentDialogTurnRequest {
-            session_id: self.session_id,
-            message: self.message,
-            original_message: self.original_message,
-            turn_id: self.turn_id,
-            execution: self.execution,
-            agent_type: self.agent_type,
-            workspace_path: self.workspace_path,
-            remote_connection_id: self.remote_connection_id,
-            remote_ssh_host: self.remote_ssh_host,
-            policy: self.policy.unwrap_or_else(|| {
-                DialogSubmissionPolicy::for_source(AgentSubmissionSource::DesktopUi)
-            }),
-            reply_route: None,
-            prepended_reminders: Vec::new(),
-            attachments: self.attachments,
-            metadata: self.metadata,
-        }
-    }
-}
-
-/// `agent/submitDialogTurn` response body.
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[serde(rename_all = "camelCase", tag = "status")]
-pub enum SubmitDialogTurnResponse {
-    Started { session_id: String, turn_id: String },
-    Queued { session_id: String, turn_id: String },
-}
-
-impl SubmitDialogTurnResponse {
-    pub fn from_outcome(outcome: DialogSubmitOutcome) -> Self {
-        match outcome {
-            DialogSubmitOutcome::Started {
-                session_id,
-                turn_id,
-            } => Self::Started {
-                session_id,
-                turn_id,
-            },
-            DialogSubmitOutcome::Queued {
-                session_id,
-                turn_id,
-            } => Self::Queued {
-                session_id,
-                turn_id,
-            },
-        }
-    }
-}
-
-/// `agent/cancelTurn` request body.
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
-#[request(method = "agent/cancelTurn", response = CancelTurnResponse)]
-pub struct CancelTurnMessage(pub AgentTurnCancellationRequest);
-
-/// `agent/cancelTurn` response body.
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
-pub struct CancelTurnResponse(pub AgentTurnCancellationResult);
-
-/// `agent/run` request body.
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[request(method = "agent/run", response = RunResponse)]
-pub struct RunMessage {
-    pub session: RunSessionSpec,
-    pub message: String,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub turn_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub source: Option<AgentSubmissionSource>,
-}
-
-/// Wire form of [`SessionSelector`].
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[serde(rename_all = "camelCase", tag = "kind")]
-pub enum RunSessionSpec {
-    Existing {
-        session_id: String,
-    },
-    Create {
-        session_name: String,
-        agent_type: String,
-        #[serde(default, skip_serializing_if = "Option::is_none")]
-        workspace_path: Option<String>,
-    },
-}
-
-impl RunSessionSpec {
-    pub fn to_selector(&self) -> SessionSelector {
-        match self {
-            RunSessionSpec::Existing { session_id } => SessionSelector::existing(session_id),
-            RunSessionSpec::Create {
-                session_name,
-                agent_type,
-                workspace_path,
-            } => SessionSelector::create(session_name, agent_type, workspace_path.clone()),
-        }
-    }
-}
-
-/// `agent/run` response body.
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[serde(rename_all = "camelCase")]
-pub struct RunResponse {
-    pub session_id: String,
-    pub turn_id: String,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub agent_type: Option<String>,
-    #[serde(default)]
-    pub accepted: bool,
-}
-
-impl RunResponse {
-    pub fn from_handle(handle: AgentRunHandle) -> Self {
-        Self {
-            session_id: handle.session_id,
-            turn_id: handle.turn_id,
-            agent_type: handle.agent_type,
-            accepted: handle.accepted,
-        }
-    }
-}
-
-impl RunMessage {
-    pub fn to_run_request(&self) -> AgentRunRequest {
-        let mut request = AgentRunRequest::new(self.session.to_selector(), &self.message);
-        if let Some(turn_id) = &self.turn_id {
-            request = request.with_turn_id(turn_id);
-        }
-        if let Some(source) = self.source {
-            request = request.with_source(source);
-        }
-        request
-    }
-}
diff --git a/src/crates/interfaces/app-server/src/schema/app.rs b/src/crates/interfaces/app-server/src/schema/app.rs
deleted file mode 100644
index 80e9b2d6af..0000000000
--- a/src/crates/interfaces/app-server/src/schema/app.rs
+++ /dev/null
@@ -1,3 +0,0 @@
-//! Behavior-light application lifecycle contracts.
-
-pub use bitfun_app_server_protocol::app::*;
diff --git a/src/crates/interfaces/app-server/src/schema/config.rs b/src/crates/interfaces/app-server/src/schema/config.rs
deleted file mode 100644
index 20b3ac4c84..0000000000
--- a/src/crates/interfaces/app-server/src/schema/config.rs
+++ /dev/null
@@ -1,111 +0,0 @@
-use agent_client_protocol::{JsonRpcRequest, JsonRpcResponse};
-use serde::{Deserialize, Serialize};
-
-pub use bitfun_app_server_protocol::config::{
-    SaveCloudSpeechConfigMessage, SaveCloudSpeechConfigRequest, SaveCloudSpeechConfigResponse,
-    SaveCloudSpeechConfigResult, ValidateConfigMessage, ValidateConfigResponse,
-};
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[request(method = "config/getAgentProfileConfigs", response = GetAgentProfileConfigsResponse)]
-pub struct GetAgentProfileConfigsMessage {}
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-pub struct GetAgentProfileConfigsResponse {
-    pub profiles: std::collections::HashMap<String, bitfun_core::service::config::AgentProfileView>,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[request(method = "config/getAgentProfileConfig", response = GetAgentProfileConfigResponse)]
-pub struct GetAgentProfileConfigMessage {
-    pub agent_id: String,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
-pub struct GetAgentProfileConfigResponse(pub bitfun_core::service::config::AgentProfileView);
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[request(method = "config/getModelConfigs", response = GetModelConfigsResponse)]
-pub struct GetModelConfigsMessage {}
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
-pub struct GetModelConfigsResponse {
-    pub models: Vec<bitfun_core::service::config::AIModelConfig>,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[request(method = "config/getConfig", response = GetConfigResponse)]
-#[serde(rename_all = "camelCase")]
-pub struct GetConfigMessage {
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub path: Option<String>,
-    #[serde(default, skip_serializing_if = "skip_if_false")]
-    pub skip_retry_on_not_found: bool,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
-pub struct GetConfigResponse(pub serde_json::Value);
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[request(method = "config/getConfigs", response = GetConfigsResponse)]
-#[serde(rename_all = "camelCase")]
-pub struct GetConfigsMessage {
-    pub paths: Vec<String>,
-    #[serde(default, skip_serializing_if = "skip_if_false")]
-    pub skip_retry_on_not_found: bool,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-pub struct GetConfigsResponse {
-    pub configs: std::collections::BTreeMap<String, serde_json::Value>,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[request(method = "config/setConfig", response = SetConfigResponse)]
-#[serde(rename_all = "camelCase")]
-pub struct SetConfigMessage {
-    pub path: String,
-    pub value: serde_json::Value,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-pub struct SetConfigResponse {}
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[request(method = "config/setAgentProfileConfig", response = SetAgentProfileConfigResponse)]
-#[serde(rename_all = "camelCase")]
-pub struct SetAgentProfileConfigMessage {
-    pub agent_id: String,
-    pub config: serde_json::Value,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-pub struct SetAgentProfileConfigResponse(pub bitfun_core::service::config::AgentProfileView);
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[request(method = "config/resetAgentProfileConfig", response = ResetAgentProfileConfigResponse)]
-#[serde(rename_all = "camelCase")]
-pub struct ResetAgentProfileConfigMessage {
-    pub agent_id: String,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-pub struct ResetAgentProfileConfigResponse(pub bitfun_core::service::config::AgentProfileView);
-
-fn skip_if_false(value: &bool) -> bool {
-    !*value
-}
diff --git a/src/crates/interfaces/app-server/src/schema/events.rs b/src/crates/interfaces/app-server/src/schema/events.rs
deleted file mode 100644
index 581399d09e..0000000000
--- a/src/crates/interfaces/app-server/src/schema/events.rs
+++ /dev/null
@@ -1,127 +0,0 @@
-use agent_client_protocol::JsonRpcNotification;
-use serde::{Deserialize, Serialize};
-
-pub use bitfun_app_server_protocol::event::{
-    AgentEventNotification as SessionEventNotification, ConfigEventNotification, ConfigUpdate,
-    EventCursor, EventStream, EventStreamState, EventStreamStateNotification, ResyncDirective,
-    SyncEventsRequest, SyncEventsResponse,
-};
-
-/// Browser-facing projected runtime or permission event.
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcNotification)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[notification(method = "agent/frontendEvent")]
-pub struct FrontendEventNotification {
-    /// Frontend event name, such as `agentic://session-created`.
-    pub event: String,
-    /// Projected payload in the frontend's expected shape.
-    pub payload: serde_json::Value,
-}
-
-pub(crate) fn config_update_from_owner(
-    value: bitfun_core::service::config::ConfigUpdateEvent,
-) -> ConfigUpdate {
-    use bitfun_core::service::config::ConfigUpdateEvent;
-
-    match value {
-        ConfigUpdateEvent::ModelConfigurationUpdated => ConfigUpdate::ModelConfigurationUpdated,
-        ConfigUpdateEvent::AIModelUpdated {
-            model_id,
-            model_name,
-        } => ConfigUpdate::AiModelUpdated {
-            model_id,
-            model_name,
-        },
-        ConfigUpdateEvent::DefaultAIModelUpdated {
-            model_id,
-            model_name,
-        } => ConfigUpdate::DefaultAiModelUpdated {
-            model_id,
-            model_name,
-        },
-        ConfigUpdateEvent::AppearanceUpdated { appearance_id } => {
-            ConfigUpdate::AppearanceUpdated { appearance_id }
-        }
-        ConfigUpdateEvent::EditorUpdated => ConfigUpdate::EditorUpdated,
-        ConfigUpdateEvent::TerminalUpdated => ConfigUpdate::TerminalUpdated,
-        ConfigUpdateEvent::WorkspaceUpdated => ConfigUpdate::WorkspaceUpdated,
-        ConfigUpdateEvent::AppUpdated => ConfigUpdate::AppUpdated,
-        ConfigUpdateEvent::ConfigReloaded => ConfigUpdate::ConfigReloaded,
-        ConfigUpdateEvent::ReasoningCatalogUpdated => ConfigUpdate::ReasoningCatalogUpdated,
-        ConfigUpdateEvent::DebugModeConfigUpdated {
-            new_port,
-            new_log_path,
-        } => ConfigUpdate::DebugModeConfigUpdated {
-            new_port,
-            new_log_path,
-        },
-        ConfigUpdateEvent::LogLevelUpdated { new_level } => {
-            ConfigUpdate::LogLevelUpdated { new_level }
-        }
-        ConfigUpdateEvent::LoggingSensitiveDiagnosticsUpdated {
-            include_sensitive_diagnostics,
-        } => ConfigUpdate::LoggingSensitiveDiagnosticsUpdated {
-            include_sensitive_diagnostics,
-        },
-        ConfigUpdateEvent::ModelsReconciled {
-            invalidated_model_ids,
-            default_models_changed,
-            func_agent_models_changed,
-            agent_model_defaults_changed,
-        } => ConfigUpdate::ModelsReconciled {
-            invalidated_model_ids,
-            default_models_changed,
-            func_agent_models_changed,
-            agent_model_defaults_changed,
-        },
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use bitfun_core::service::config::ConfigUpdateEvent;
-    use serde_json::json;
-
-    #[test]
-    fn models_reconciled_preserves_all_owner_facts() {
-        let update = super::config_update_from_owner(ConfigUpdateEvent::ModelsReconciled {
-            invalidated_model_ids: vec!["model-1".to_string()],
-            default_models_changed: true,
-            func_agent_models_changed: false,
-            agent_model_defaults_changed: true,
-        });
-
-        assert_eq!(
-            serde_json::to_value(update).expect("config update should serialize"),
-            json!({
-                "kind": "modelsReconciled",
-                "invalidatedModelIds": ["model-1"],
-                "defaultModelsChanged": true,
-                "funcAgentModelsChanged": false,
-                "agentModelDefaultsChanged": true
-            })
-        );
-    }
-
-    #[test]
-    fn reasoning_catalog_update_is_projected() {
-        let update = super::config_update_from_owner(ConfigUpdateEvent::ReasoningCatalogUpdated);
-
-        assert_eq!(
-            serde_json::to_value(update).expect("config update should serialize"),
-            json!({ "kind": "reasoningCatalogUpdated" })
-        );
-    }
-}
-
-#[cfg(all(test, feature = "ts"))]
-mod ts_exports {
-    use super::ConfigUpdate;
-    use ts_rs::{Config, TS};
-
-    #[test]
-    fn export_upstream_config_update() {
-        ConfigUpdate::export(&Config::from_env())
-            .expect("ConfigUpdate TypeScript export should succeed");
-    }
-}
diff --git a/src/crates/interfaces/app-server/src/schema/git.rs b/src/crates/interfaces/app-server/src/schema/git.rs
deleted file mode 100644
index 7a960acc1e..0000000000
--- a/src/crates/interfaces/app-server/src/schema/git.rs
+++ /dev/null
@@ -1,47 +0,0 @@
-use agent_client_protocol::{JsonRpcRequest, JsonRpcResponse};
-use serde::{Deserialize, Serialize};
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
-#[request(method = "git/isRepository", response = GitIsRepositoryResponse)]
-pub struct GitIsRepositoryMessage(pub GitRepositoryPathRequest);
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
-pub struct GitIsRepositoryResponse(pub bool);
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
-#[request(method = "git/getStatus", response = GitGetStatusResponse)]
-pub struct GitGetStatusMessage(pub GitRepositoryPathRequest);
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
-pub struct GitGetStatusResponse(pub bitfun_core::service::git::GitStatus);
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
-#[request(method = "git/getBranches", response = GitGetBranchesResponse)]
-pub struct GitGetBranchesMessage(pub GitBranchesRequest);
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-pub struct GitGetBranchesResponse {
-    pub branches: Vec<bitfun_core::service::git::GitBranch>,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[serde(rename_all = "camelCase")]
-pub struct GitRepositoryPathRequest {
-    pub repository_path: String,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[serde(rename_all = "camelCase")]
-pub struct GitBranchesRequest {
-    pub repository_path: String,
-    #[serde(default)]
-    pub include_remote: Option<bool>,
-}
diff --git a/src/crates/interfaces/app-server/src/schema/mod.rs b/src/crates/interfaces/app-server/src/schema/mod.rs
index 166034b205..8390a263bc 100644
--- a/src/crates/interfaces/app-server/src/schema/mod.rs
+++ b/src/crates/interfaces/app-server/src/schema/mod.rs
@@ -4,20 +4,16 @@
 //! complete contract. Existing consumers can continue importing types from
 //! `bitfun_app_server::schema` without depending on the internal layout.
 
-mod agent;
-mod app;
-mod config;
-mod events;
-mod git;
-mod i18n;
-mod permission;
-mod session;
-
-pub use agent::*;
-pub use app::*;
-pub use config::*;
-pub use events::*;
-pub use git::*;
-pub use i18n::*;
-pub use permission::*;
-pub use session::*;
+pub use bitfun_app_server_protocol::agent::*;
+pub use bitfun_app_server_protocol::app::*;
+pub use bitfun_app_server_protocol::config::*;
+pub use bitfun_app_server_protocol::event::{
+    AgentEventNotification as SessionEventNotification, ConfigEventNotification, ConfigUpdate,
+    EventCursor, EventStream, EventStreamState, EventStreamStateNotification,
+    FrontendEventNotification, PermissionEventNotification, ResyncDirective, SyncEventsRequest,
+    SyncEventsResponse,
+};
+pub use bitfun_app_server_protocol::git::*;
+pub use bitfun_app_server_protocol::i18n::*;
+pub use bitfun_app_server_protocol::permission::*;
+pub use bitfun_app_server_protocol::session::*;
diff --git a/src/crates/interfaces/app-server/src/schema/session.rs b/src/crates/interfaces/app-server/src/schema/session.rs
deleted file mode 100644
index 9b89b1f716..0000000000
--- a/src/crates/interfaces/app-server/src/schema/session.rs
+++ /dev/null
@@ -1,209 +0,0 @@
-use agent_client_protocol::{JsonRpcRequest, JsonRpcResponse};
-use bitfun_agent_runtime::sdk::{
-    AgentSessionArchiveStateRequest, AgentSessionForkAtTurnRequest,
-    AgentSessionForkBeforeTurnRequest, AgentSessionForkRequest, AgentSessionForkResult,
-    AgentSessionModeUpdateRequest, AgentSessionModelUpdateRequest, AgentSessionRenameRequest,
-};
-use serde::{Deserialize, Serialize};
-
-macro_rules! empty_response {
-    ($name:ident) => {
-        #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
-        #[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-        pub struct $name {}
-    };
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[request(method = "session/rename", response = RenameSessionResponse)]
-pub struct RenameSessionMessage(pub AgentSessionRenameRequest);
-
-empty_response!(RenameSessionResponse);
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[request(method = "session/setArchived", response = SetSessionArchivedResponse)]
-pub struct SetSessionArchivedMessage(pub AgentSessionArchiveStateRequest);
-
-empty_response!(SetSessionArchivedResponse);
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[request(method = "session/updateModel", response = UpdateSessionModelResponse)]
-pub struct UpdateSessionModelMessage(pub AgentSessionModelUpdateRequest);
-
-empty_response!(UpdateSessionModelResponse);
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[request(method = "session/updateMode", response = UpdateSessionModeResponse)]
-pub struct UpdateSessionModeMessage(pub AgentSessionModeUpdateRequest);
-
-empty_response!(UpdateSessionModeResponse);
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[request(method = "session/fork", response = ForkSessionResponse)]
-pub struct ForkSessionMessage(pub AgentSessionForkRequest);
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[request(method = "session/forkAtTurn", response = ForkSessionResponse)]
-pub struct ForkSessionAtTurnMessage(pub AgentSessionForkAtTurnRequest);
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[request(method = "session/forkBeforeTurn", response = ForkSessionResponse)]
-pub struct ForkSessionBeforeTurnMessage(pub AgentSessionForkBeforeTurnRequest);
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-pub struct ForkSessionResponse(pub AgentSessionForkResult);
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[request(method = "session/restore", response = RestoreSessionResponse)]
-#[serde(rename_all = "camelCase")]
-pub struct RestoreSessionMessage {
-    pub workspace_path: String,
-    pub session_id: String,
-    #[serde(default)]
-    pub include_internal: bool,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_connection_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub remote_ssh_host: Option<String>,
-}
-
-impl From<RestoreSessionMessage> for bitfun_agent_runtime::sdk::AgentSessionRestoreRequest {
-    fn from(value: RestoreSessionMessage) -> Self {
-        Self {
-            workspace_path: value.workspace_path,
-            session_id: value.session_id,
-            include_internal: value.include_internal,
-            remote_connection_id: value.remote_connection_id,
-            remote_ssh_host: value.remote_ssh_host,
-        }
-    }
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[serde(rename_all = "camelCase")]
-pub struct RestoreSessionResponse {
-    pub session: bitfun_agent_runtime::sdk::AgentSessionSummary,
-    pub state: SessionRuntimeState,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[serde(
-    tag = "kind",
-    rename_all = "camelCase",
-    rename_all_fields = "camelCase"
-)]
-#[cfg_attr(feature = "ts", ts(rename_all = "camelCase"))]
-pub enum SessionRuntimeState {
-    Idle,
-    Processing {
-        current_turn_id: String,
-        phase: SessionProcessingPhase,
-    },
-    Error {
-        error: String,
-        recoverable: bool,
-    },
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
-#[serde(rename_all = "camelCase")]
-pub enum SessionProcessingPhase {
-    Starting,
-    Compacting,
-    Thinking,
-    Streaming,
-    ToolCalling,
-    ToolConfirming,
-}
-
-impl From<bitfun_agent_runtime::sdk::AgentSessionRestoreResult> for RestoreSessionResponse {
-    fn from(value: bitfun_agent_runtime::sdk::AgentSessionRestoreResult) -> Self {
-        Self {
-            session: value.session,
-            state: value.state.into(),
-        }
-    }
-}
-
-impl From<bitfun_agent_runtime::session_state::SessionState> for SessionRuntimeState {
-    fn from(value: bitfun_agent_runtime::session_state::SessionState) -> Self {
-        use bitfun_agent_runtime::session_state::SessionState;
-
-        match value {
-            SessionState::Idle => Self::Idle,
-            SessionState::Processing {
-                current_turn_id,
-                phase,
-            } => Self::Processing {
-                current_turn_id,
-                phase: phase.into(),
-            },
-            SessionState::Error { error, recoverable } => Self::Error { error, recoverable },
-        }
-    }
-}
-
-impl From<bitfun_agent_runtime::session_state::ProcessingPhase> for SessionProcessingPhase {
-    fn from(value: bitfun_agent_runtime::session_state::ProcessingPhase) -> Self {
-        use bitfun_agent_runtime::session_state::ProcessingPhase;
-
-        match value {
-            ProcessingPhase::Starting => Self::Starting,
-            ProcessingPhase::Compacting => Self::Compacting,
-            ProcessingPhase::Thinking => Self::Thinking,
-            ProcessingPhase::Streaming => Self::Streaming,
-            ProcessingPhase::ToolCalling => Self::ToolCalling,
-            ProcessingPhase::ToolConfirming => Self::ToolConfirming,
-        }
-    }
-}
-
-impl From<RestoreSessionResponse> for bitfun_agent_runtime::sdk::AgentSessionRestoreResult {
-    fn from(value: RestoreSessionResponse) -> Self {
-        Self {
-            session: value.session,
-            state: value.state.into(),
-        }
-    }
-}
-
-impl From<SessionRuntimeState> for bitfun_agent_runtime::session_state::SessionState {
-    fn from(value: SessionRuntimeState) -> Self {
-        match value {
-            SessionRuntimeState::Idle => Self::Idle,
-            SessionRuntimeState::Processing {
-                current_turn_id,
-                phase,
-            } => Self::Processing {
-                current_turn_id,
-                phase: phase.into(),
-            },
-            SessionRuntimeState::Error { error, recoverable } => Self::Error { error, recoverable },
-        }
-    }
-}
-
-impl From<SessionProcessingPhase> for bitfun_agent_runtime::session_state::ProcessingPhase {
-    fn from(value: SessionProcessingPhase) -> Self {
-        match value {
-            SessionProcessingPhase::Starting => Self::Starting,
-            SessionProcessingPhase::Compacting => Self::Compacting,
-            SessionProcessingPhase::Thinking => Self::Thinking,
-            SessionProcessingPhase::Streaming => Self::Streaming,
-            SessionProcessingPhase::ToolCalling => Self::ToolCalling,
-            SessionProcessingPhase::ToolConfirming => Self::ToolConfirming,
-        }
-    }
-}
diff --git a/src/crates/interfaces/app-server/src/server.rs b/src/crates/interfaces/app-server/src/server.rs
index 4dfeac8806..e83c400110 100644
--- a/src/crates/interfaces/app-server/src/server.rs
+++ b/src/crates/interfaces/app-server/src/server.rs
@@ -7,6 +7,7 @@
 mod event_forwarder;
 mod fallback;
 mod handlers;
+mod wire;
 
 use std::sync::atomic::{AtomicU64, Ordering};
 use std::sync::Arc;
diff --git a/src/crates/interfaces/app-server/src/server/event_forwarder.rs b/src/crates/interfaces/app-server/src/server/event_forwarder.rs
index 1afbbe5f22..42c3c5bc59 100644
--- a/src/crates/interfaces/app-server/src/server/event_forwarder.rs
+++ b/src/crates/interfaces/app-server/src/server/event_forwarder.rs
@@ -2,9 +2,8 @@ use crate::agent::BitfunAppRuntime;
 use crate::management::AppManagementService;
 use crate::role::AppClient;
 use crate::schema::{
-    config_update_from_owner, ConfigEventNotification, EventStream, EventStreamState,
-    EventStreamStateNotification, PermissionEventNotification, ResyncDirective,
-    SessionEventNotification,
+    ConfigEventNotification, EventStream, EventStreamState, EventStreamStateNotification,
+    PermissionEventNotification, ResyncDirective, SessionEventNotification,
 };
 use agent_client_protocol::{ConnectionTo, Result};
 use bitfun_agent_runtime::sdk::PermissionRequestEvent;
@@ -111,7 +110,7 @@ pub(super) async fn run(
                 Some(Ok(event)) => {
                     if let Err(error) = cx.send_notification(ConfigEventNotification {
                         cursor: event_state.next_cursor(EventStream::Config),
-                        event: config_update_from_owner(event),
+                        event: crate::server::wire::config_update(event),
                     }) {
                         log::warn!("App-server config event forwarder failed to send a notification: {:?} -- skipping this event", error);
                     }
diff --git a/src/crates/interfaces/app-server/src/server/handlers/agent.rs b/src/crates/interfaces/app-server/src/server/handlers/agent.rs
index 5abffa5a5d..fc3d29668e 100644
--- a/src/crates/interfaces/app-server/src/server/handlers/agent.rs
+++ b/src/crates/interfaces/app-server/src/server/handlers/agent.rs
@@ -12,6 +12,7 @@ use crate::agent::{runtime_call, BitfunAppRuntime};
 use crate::management::{AppManagementService, MODES_CAPABILITY};
 use crate::role::{AppClient, AppServer};
 use crate::schema::*;
+use crate::server::wire;
 
 pub(in crate::server) fn builder(
     runtime: Arc<BitfunAppRuntime>,
@@ -91,9 +92,9 @@ pub(in crate::server) fn builder(
                     responder.respond_with_result(
                         runtime
                             .runtime()
-                            .submit_dialog_turn(request.0.to_request())
+                            .submit_dialog_turn(wire::submit_dialog_turn_request(request.0))
                             .await
-                            .map(SubmitDialogTurnResponse::from_outcome)
+                            .map(wire::submit_dialog_turn_response)
                             .map_err(|err| {
                                 BitfunAppRuntime::session_runtime_error(&session_id, err)
                             }),
@@ -107,8 +108,8 @@ pub(in crate::server) fn builder(
                 let runtime = runtime.clone();
                 async move |request: RunMessage, responder, _cx| {
                     let handle =
-                        runtime_call(runtime.runtime().run(request.to_run_request()).await)?;
-                    responder.respond(RunResponse::from_handle(handle))
+                        runtime_call(runtime.runtime().run(wire::run_request(&request)).await)?;
+                    responder.respond(wire::run_response(handle))
                 }
             },
             agent_client_protocol::on_receive_request!(),
diff --git a/src/crates/interfaces/app-server/src/server/handlers/app.rs b/src/crates/interfaces/app-server/src/server/handlers/app.rs
index 4d59cc6bdf..21a6abf1fe 100644
--- a/src/crates/interfaces/app-server/src/server/handlers/app.rs
+++ b/src/crates/interfaces/app-server/src/server/handlers/app.rs
@@ -113,7 +113,6 @@ fn registered_capabilities(
                 "session/sync",
                 "session/readTranscript",
                 "session/resolveWorkspace",
-                "session/recordLocalCommandTurn",
                 "session/rename",
                 "session/setArchived",
                 "session/updateModel",
@@ -166,6 +165,7 @@ fn registered_capabilities(
                 "config/getAgentProfileConfig",
                 "config/getModelConfigs",
                 "config/getTuiModelCatalog",
+                "model/projectReasoningCatalog",
                 "config/getConfig",
                 "config/getConfigs",
                 "config/setConfig",
diff --git a/src/crates/interfaces/app-server/src/server/handlers/config.rs b/src/crates/interfaces/app-server/src/server/handlers/config.rs
index bbd13d5500..13deb921e4 100644
--- a/src/crates/interfaces/app-server/src/server/handlers/config.rs
+++ b/src/crates/interfaces/app-server/src/server/handlers/config.rs
@@ -1,6 +1,7 @@
 use crate::agent::{bitfun_error, config_get_error};
 use crate::role::{AppClient, AppServer};
 use crate::schema::*;
+use crate::server::wire;
 use agent_client_protocol::{Builder, HandleDispatchFrom};
 
 pub(in crate::server) fn builder() -> Builder<AppServer, impl HandleDispatchFrom<AppClient>> {
@@ -11,7 +12,12 @@ pub(in crate::server) fn builder() -> Builder<AppServer, impl HandleDispatchFrom
             async move |_: GetAgentProfileConfigsMessage, responder, _cx| {
                 let result = bitfun_core::service::config::mode_config_canonicalizer::get_agent_profile_views()
                     .await
-                    .map(|profiles| GetAgentProfileConfigsResponse { profiles })
+                    .map(|profiles| GetAgentProfileConfigsResponse {
+                        profiles: profiles
+                            .into_iter()
+                            .map(|(id, profile)| (id, wire::agent_profile_view(profile)))
+                            .collect(),
+                    })
                     .map_err(bitfun_error);
                 responder.respond_with_result(result)
             },
@@ -21,7 +27,7 @@ pub(in crate::server) fn builder() -> Builder<AppServer, impl HandleDispatchFrom
             async move |request: GetAgentProfileConfigMessage, responder, _cx| {
                 let result = bitfun_core::service::config::mode_config_canonicalizer::get_agent_profile_view(&request.agent_id)
                     .await
-                    .map(GetAgentProfileConfigResponse)
+                    .map(|profile| GetAgentProfileConfigResponse(wire::agent_profile_view(profile)))
                     .map_err(bitfun_error);
                 responder.respond_with_result(result)
             },
@@ -31,7 +37,12 @@ pub(in crate::server) fn builder() -> Builder<AppServer, impl HandleDispatchFrom
             async move |_: GetModelConfigsMessage, responder, _cx| {
                 let result = async {
                     let service = bitfun_core::service::config::get_global_config_service().await?;
-                    service.get_ai_models().await
+                    let models = service.get_ai_models().await?;
+                    models
+                        .into_iter()
+                        .map(wire::model_config)
+                        .collect::<Result<Vec<_>, _>>()
+                        .map_err(bitfun_core::BitFunError::from)
                 }
                 .await
                 .map(|models| GetModelConfigsResponse { models })
@@ -152,7 +163,7 @@ pub(in crate::server) fn builder() -> Builder<AppServer, impl HandleDispatchFrom
                     .await
                 }
                 .await
-                .map(SetAgentProfileConfigResponse)
+                .map(|profile| SetAgentProfileConfigResponse(wire::agent_profile_view(profile)))
                 .map_err(bitfun_error);
                 responder.respond_with_result(result)
             },
@@ -171,7 +182,7 @@ pub(in crate::server) fn builder() -> Builder<AppServer, impl HandleDispatchFrom
                     .await
                 }
                 .await
-                .map(ResetAgentProfileConfigResponse)
+                .map(|profile| ResetAgentProfileConfigResponse(wire::agent_profile_view(profile)))
                 .map_err(bitfun_error);
                 responder.respond_with_result(result)
             },
diff --git a/src/crates/interfaces/app-server/src/server/handlers/git.rs b/src/crates/interfaces/app-server/src/server/handlers/git.rs
index 769fd437a5..ca78f4868b 100644
--- a/src/crates/interfaces/app-server/src/server/handlers/git.rs
+++ b/src/crates/interfaces/app-server/src/server/handlers/git.rs
@@ -8,6 +8,7 @@ use crate::schema::{
     GitGetStatusResponse, GitIsRepositoryMessage, GitIsRepositoryResponse,
     GitRepositoryPathRequest,
 };
+use crate::server::wire;
 
 pub(in crate::server) fn builder() -> Builder<AppServer, impl HandleDispatchFrom<AppClient>> {
     AppServer
@@ -31,7 +32,7 @@ pub(in crate::server) fn builder() -> Builder<AppServer, impl HandleDispatchFrom
                 responder.respond_with_result(
                     GitService::get_status(&repository_path)
                         .await
-                        .map(GitGetStatusResponse)
+                        .map(|status| GitGetStatusResponse(wire::git_status(status)))
                         .map_err(git_service_error),
                 )
             },
@@ -46,7 +47,9 @@ pub(in crate::server) fn builder() -> Builder<AppServer, impl HandleDispatchFrom
                 let result =
                     GitService::get_branches(&repository_path, include_remote.unwrap_or(false))
                         .await
-                        .map(|branches| GitGetBranchesResponse { branches })
+                        .map(|branches| GitGetBranchesResponse {
+                            branches: branches.into_iter().map(wire::git_branch).collect(),
+                        })
                         .map_err(git_service_error);
                 responder.respond_with_result(result)
             },
diff --git a/src/crates/interfaces/app-server/src/server/handlers/model.rs b/src/crates/interfaces/app-server/src/server/handlers/model.rs
index d485dc3e92..4229041b34 100644
--- a/src/crates/interfaces/app-server/src/server/handlers/model.rs
+++ b/src/crates/interfaces/app-server/src/server/handlers/model.rs
@@ -13,6 +13,15 @@ pub(in crate::server) fn builder(
     AppServer
         .builder()
         .name("model handlers")
+        .on_receive_request(
+            management_handler!(
+                management,
+                MODELS_CAPABILITY,
+                ProjectReasoningCatalogRequest,
+                project_reasoning_catalog
+            ),
+            agent_client_protocol::on_receive_request!(),
+        )
         .on_receive_request(
             management_handler!(
                 management,
diff --git a/src/crates/interfaces/app-server/src/server/handlers/session.rs b/src/crates/interfaces/app-server/src/server/handlers/session.rs
index 59ce5cb9b4..7c45345776 100644
--- a/src/crates/interfaces/app-server/src/server/handlers/session.rs
+++ b/src/crates/interfaces/app-server/src/server/handlers/session.rs
@@ -1,21 +1,21 @@
 use std::sync::Arc;
 
 use agent_client_protocol::{Builder, Error, HandleDispatchFrom};
-use bitfun_agent_runtime::sdk::{AgentSessionRestoreRequest, ProcessingPhase, SessionState};
+use bitfun_agent_runtime::sdk::AgentSessionRestoreRequest;
 use bitfun_app_server_protocol::session::{
     CancelLineageRequest, CancelLineageResponse, CompactSessionRequest, CompactSessionResponse,
     InspectLineageRequest, InspectLineageResponse, ReadTranscriptRequest, ReadTranscriptResponse,
-    RecordLocalCommandTurnRequest, RecordLocalCommandTurnResponse, RedoSessionRequest,
-    ReloadContextRequest, ReloadContextResponse, ResolveWorkspaceRequest, ResolveWorkspaceResponse,
-    RevertSessionResponse, SessionLineageRequest, SessionLineageResponse, SessionProcessingPhase,
-    SessionRuntimeState, SessionUsageRequest, SessionUsageResponse, SyncSessionRequest,
-    SyncSessionResponse, UndoSessionRequest, WaitForSettlementRequest, WaitForSettlementResponse,
+    RedoSessionRequest, ReloadContextRequest, ReloadContextResponse, ResolveWorkspaceRequest,
+    ResolveWorkspaceResponse, RevertSessionResponse, SessionLineageRequest, SessionLineageResponse,
+    SessionUsageRequest, SessionUsageResponse, SyncSessionRequest, SyncSessionResponse,
+    UndoSessionRequest, WaitForSettlementRequest, WaitForSettlementResponse,
 };
 use bitfun_runtime_ports::{AgentSessionWorkspaceBinding, SessionExecutionTarget};
 
 use crate::agent::{runtime_call, BitfunAppRuntime};
 use crate::role::{AppClient, AppServer};
 use crate::schema::*;
+use crate::server::wire;
 
 pub(in crate::server) fn builder(
     runtime: Arc<BitfunAppRuntime>,
@@ -152,9 +152,9 @@ pub(in crate::server) fn builder(
                     responder.respond_with_result(
                         runtime
                             .runtime()
-                            .restore_session(request.into())
+                            .restore_session(wire::restore_session_request(request))
                             .await
-                            .map(RestoreSessionResponse::from)
+                            .map(wire::restore_session_response)
                             .map_err(|error| {
                                 BitfunAppRuntime::session_runtime_error(&session_id, error)
                             }),
@@ -214,7 +214,7 @@ pub(in crate::server) fn builder(
 
                     responder.respond(SyncSessionResponse {
                         session: restored.session,
-                        state: session_state(restored.state),
+                        state: wire::session_state(restored.state),
                         transcript,
                         workspace_binding,
                         pending_permissions,
@@ -223,25 +223,6 @@ pub(in crate::server) fn builder(
             },
             agent_client_protocol::on_receive_request!(),
         )
-        .on_receive_request(
-            {
-                let runtime = runtime.clone();
-                async move |request: RecordLocalCommandTurnRequest, responder, _cx| {
-                    let session_id = request.0.session_id.clone();
-                    responder.respond_with_result(
-                        runtime
-                            .runtime()
-                            .record_completed_local_command_turn(request.0)
-                            .await
-                            .map(RecordLocalCommandTurnResponse)
-                            .map_err(|error| {
-                                BitfunAppRuntime::session_runtime_error(&session_id, error)
-                            }),
-                    )
-                }
-            },
-            agent_client_protocol::on_receive_request!(),
-        )
         .on_receive_request(
             {
                 let runtime = runtime.clone();
@@ -436,30 +417,3 @@ fn fallback_workspace_binding(workspace_path: String) -> AgentSessionWorkspaceBi
         remote_ssh_host: None,
     }
 }
-
-fn session_state(state: SessionState) -> SessionRuntimeState {
-    match state {
-        SessionState::Idle => SessionRuntimeState::Idle,
-        SessionState::Processing {
-            current_turn_id,
-            phase,
-        } => SessionRuntimeState::Processing {
-            current_turn_id,
-            phase: processing_phase(phase),
-        },
-        SessionState::Error { error, recoverable } => {
-            SessionRuntimeState::Error { error, recoverable }
-        }
-    }
-}
-
-fn processing_phase(phase: ProcessingPhase) -> SessionProcessingPhase {
-    match phase {
-        ProcessingPhase::Starting => SessionProcessingPhase::Starting,
-        ProcessingPhase::Compacting => SessionProcessingPhase::Compacting,
-        ProcessingPhase::Thinking => SessionProcessingPhase::Thinking,
-        ProcessingPhase::Streaming => SessionProcessingPhase::Streaming,
-        ProcessingPhase::ToolCalling => SessionProcessingPhase::ToolCalling,
-        ProcessingPhase::ToolConfirming => SessionProcessingPhase::ToolConfirming,
-    }
-}
diff --git a/src/crates/interfaces/app-server/src/server/wire.rs b/src/crates/interfaces/app-server/src/server/wire.rs
new file mode 100644
index 0000000000..34cbe9c248
--- /dev/null
+++ b/src/crates/interfaces/app-server/src/server/wire.rs
@@ -0,0 +1,381 @@
+//! Server-owned translations between behavior-light wire DTOs and runtime or
+//! service-owner types.
+
+use bitfun_agent_runtime::sdk::{
+    AgentRunHandle, AgentRunRequest, AgentSessionRestoreRequest, AgentSessionRestoreResult,
+    DialogSubmitOutcome, SessionSelector,
+};
+use bitfun_agent_runtime::session_state::{ProcessingPhase, SessionState};
+use bitfun_app_server_protocol::agent::{
+    RunMessage, RunResponse, RunSessionSpec, SubmitDialogTurnBody, SubmitDialogTurnResponse,
+};
+use bitfun_app_server_protocol::config::AgentProfileView;
+use bitfun_app_server_protocol::event::ConfigUpdate;
+use bitfun_app_server_protocol::git::{
+    GitBranch, GitBranchStats, GitFileStatus, GitLinesChanged, GitStatus,
+};
+use bitfun_app_server_protocol::session::{
+    RestoreSessionMessage, RestoreSessionResponse, SessionProcessingPhase, SessionRuntimeState,
+};
+use bitfun_runtime_ports::{AgentDialogTurnRequest, AgentSubmissionSource, DialogSubmissionPolicy};
+
+pub(super) fn submit_dialog_turn_request(body: SubmitDialogTurnBody) -> AgentDialogTurnRequest {
+    body.to_request(DialogSubmissionPolicy::for_source(
+        AgentSubmissionSource::DesktopUi,
+    ))
+}
+
+pub(super) fn submit_dialog_turn_response(
+    outcome: DialogSubmitOutcome,
+) -> SubmitDialogTurnResponse {
+    match outcome {
+        DialogSubmitOutcome::Started {
+            session_id,
+            turn_id,
+        } => SubmitDialogTurnResponse::Started {
+            session_id,
+            turn_id,
+        },
+        DialogSubmitOutcome::Queued {
+            session_id,
+            turn_id,
+        } => SubmitDialogTurnResponse::Queued {
+            session_id,
+            turn_id,
+        },
+    }
+}
+
+pub(super) fn run_request(request: &RunMessage) -> AgentRunRequest {
+    let session = match &request.session {
+        RunSessionSpec::Existing { session_id } => SessionSelector::existing(session_id),
+        RunSessionSpec::Create {
+            session_name,
+            agent_type,
+            workspace_path,
+        } => SessionSelector::create(session_name, agent_type, workspace_path.clone()),
+    };
+    let mut runtime_request = AgentRunRequest::new(session, &request.message);
+    if let Some(turn_id) = &request.turn_id {
+        runtime_request = runtime_request.with_turn_id(turn_id);
+    }
+    if let Some(source) = request.source {
+        runtime_request = runtime_request.with_source(source);
+    }
+    runtime_request
+}
+
+pub(super) fn run_response(handle: AgentRunHandle) -> RunResponse {
+    RunResponse {
+        session_id: handle.session_id,
+        turn_id: handle.turn_id,
+        agent_type: handle.agent_type,
+        accepted: handle.accepted,
+    }
+}
+
+pub(super) fn restore_session_request(
+    request: RestoreSessionMessage,
+) -> AgentSessionRestoreRequest {
+    AgentSessionRestoreRequest {
+        workspace_path: request.workspace_path,
+        session_id: request.session_id,
+        include_internal: request.include_internal,
+        remote_connection_id: request.remote_connection_id,
+        remote_ssh_host: request.remote_ssh_host,
+    }
+}
+
+pub(super) fn restore_session_response(
+    result: AgentSessionRestoreResult,
+) -> RestoreSessionResponse {
+    RestoreSessionResponse {
+        session: result.session,
+        state: session_state(result.state),
+    }
+}
+
+pub(super) fn session_state(value: SessionState) -> SessionRuntimeState {
+    match value {
+        SessionState::Idle => SessionRuntimeState::Idle,
+        SessionState::Processing {
+            current_turn_id,
+            phase,
+        } => SessionRuntimeState::Processing {
+            current_turn_id,
+            phase: session_processing_phase(phase),
+        },
+        SessionState::Error { error, recoverable } => {
+            SessionRuntimeState::Error { error, recoverable }
+        }
+    }
+}
+
+fn session_processing_phase(value: ProcessingPhase) -> SessionProcessingPhase {
+    match value {
+        ProcessingPhase::Starting => SessionProcessingPhase::Starting,
+        ProcessingPhase::Compacting => SessionProcessingPhase::Compacting,
+        ProcessingPhase::Thinking => SessionProcessingPhase::Thinking,
+        ProcessingPhase::Streaming => SessionProcessingPhase::Streaming,
+        ProcessingPhase::ToolCalling => SessionProcessingPhase::ToolCalling,
+        ProcessingPhase::ToolConfirming => SessionProcessingPhase::ToolConfirming,
+    }
+}
+
+pub(super) fn agent_profile_view(
+    value: bitfun_core::service::config::AgentProfileView,
+) -> AgentProfileView {
+    AgentProfileView {
+        profile_id: value.profile_id,
+        enabled_tools: value.enabled_tools,
+        default_tools: value.default_tools,
+        disabled_user_skills: value.disabled_user_skills,
+        enabled_user_skills: value.enabled_user_skills,
+    }
+}
+
+pub(super) fn model_config(
+    value: bitfun_core::service::config::AIModelConfig,
+) -> Result<serde_json::Value, serde_json::Error> {
+    serde_json::to_value(value)
+}
+
+pub(super) fn git_status(value: bitfun_core::service::git::GitStatus) -> GitStatus {
+    GitStatus {
+        staged: value.staged.into_iter().map(git_file_status).collect(),
+        unstaged: value.unstaged.into_iter().map(git_file_status).collect(),
+        untracked: value.untracked,
+        conflicts: value.conflicts,
+        current_branch: value.current_branch,
+        ahead: value.ahead,
+        behind: value.behind,
+    }
+}
+
+fn git_file_status(value: bitfun_core::service::git::GitFileStatus) -> GitFileStatus {
+    GitFileStatus {
+        path: value.path,
+        status: value.status,
+        index_status: value.index_status,
+        workdir_status: value.workdir_status,
+    }
+}
+
+pub(super) fn git_branch(value: bitfun_core::service::git::GitBranch) -> GitBranch {
+    GitBranch {
+        name: value.name,
+        current: value.current,
+        remote: value.remote,
+        upstream: value.upstream,
+        ahead: value.ahead,
+        behind: value.behind,
+        last_commit: value.last_commit,
+        last_commit_date: value.last_commit_date,
+        base_branch: value.base_branch,
+        child_branches: value.child_branches,
+        merged_branches: value.merged_branches,
+        branch_type: value.branch_type,
+        has_conflicts: value.has_conflicts,
+        can_merge: value.can_merge,
+        is_stale: value.is_stale,
+        merge_status: value.merge_status,
+        stats: value.stats.map(|stats| GitBranchStats {
+            commit_count: stats.commit_count,
+            contributor_count: stats.contributor_count,
+            file_changes: stats.file_changes,
+            lines_changed: GitLinesChanged {
+                additions: stats.lines_changed.additions,
+                deletions: stats.lines_changed.deletions,
+            },
+            activity_score: stats.activity_score,
+        }),
+        created_at: value.created_at,
+        last_activity_at: value.last_activity_at,
+        tags: value.tags,
+        description: value.description,
+        linked_issues: value.linked_issues,
+    }
+}
+
+pub(super) fn config_update(
+    value: bitfun_core::service::config::ConfigUpdateEvent,
+) -> ConfigUpdate {
+    use bitfun_core::service::config::ConfigUpdateEvent;
+
+    match value {
+        ConfigUpdateEvent::ModelConfigurationUpdated => ConfigUpdate::ModelConfigurationUpdated,
+        ConfigUpdateEvent::AIModelUpdated {
+            model_id,
+            model_name,
+        } => ConfigUpdate::AiModelUpdated {
+            model_id,
+            model_name,
+        },
+        ConfigUpdateEvent::DefaultAIModelUpdated {
+            model_id,
+            model_name,
+        } => ConfigUpdate::DefaultAiModelUpdated {
+            model_id,
+            model_name,
+        },
+        ConfigUpdateEvent::AppearanceUpdated { appearance_id } => {
+            ConfigUpdate::AppearanceUpdated { appearance_id }
+        }
+        ConfigUpdateEvent::EditorUpdated => ConfigUpdate::EditorUpdated,
+        ConfigUpdateEvent::TerminalUpdated => ConfigUpdate::TerminalUpdated,
+        ConfigUpdateEvent::WorkspaceUpdated => ConfigUpdate::WorkspaceUpdated,
+        ConfigUpdateEvent::AppUpdated => ConfigUpdate::AppUpdated,
+        ConfigUpdateEvent::ConfigReloaded => ConfigUpdate::ConfigReloaded,
+        ConfigUpdateEvent::ReasoningCatalogUpdated => ConfigUpdate::ReasoningCatalogUpdated,
+        ConfigUpdateEvent::DebugModeConfigUpdated {
+            new_port,
+            new_log_path,
+        } => ConfigUpdate::DebugModeConfigUpdated {
+            new_port,
+            new_log_path,
+        },
+        ConfigUpdateEvent::LogLevelUpdated { new_level } => {
+            ConfigUpdate::LogLevelUpdated { new_level }
+        }
+        ConfigUpdateEvent::LoggingSensitiveDiagnosticsUpdated {
+            include_sensitive_diagnostics,
+        } => ConfigUpdate::LoggingSensitiveDiagnosticsUpdated {
+            include_sensitive_diagnostics,
+        },
+        ConfigUpdateEvent::ModelsReconciled {
+            invalidated_model_ids,
+            default_models_changed,
+            task_models_changed,
+            agent_model_defaults_changed,
+        } => ConfigUpdate::ModelsReconciled {
+            invalidated_model_ids,
+            default_models_changed,
+            task_models_changed,
+            agent_model_defaults_changed,
+        },
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use bitfun_app_server_protocol::agent::SubmitDialogTurnBody;
+    use bitfun_app_server_protocol::session::{SessionProcessingPhase, SessionRuntimeState};
+    use bitfun_runtime_ports::{AgentDialogTurnExecution, AgentSubmissionSource};
+
+    #[test]
+    fn missing_dialog_policy_defaults_only_at_the_server_boundary() {
+        let request = super::submit_dialog_turn_request(SubmitDialogTurnBody {
+            session_id: "session-1".to_string(),
+            message: "hello".to_string(),
+            original_message: None,
+            turn_id: None,
+            execution: AgentDialogTurnExecution::Standard,
+            agent_type: "general".to_string(),
+            workspace_path: None,
+            remote_connection_id: None,
+            remote_ssh_host: None,
+            policy: None,
+            attachments: Vec::new(),
+            metadata: serde_json::Map::new(),
+        });
+
+        assert_eq!(
+            request.policy.trigger_source,
+            AgentSubmissionSource::DesktopUi
+        );
+        assert!(request.reply_route.is_none());
+        assert!(request.prepended_reminders.is_empty());
+    }
+
+    #[test]
+    fn runtime_session_state_maps_without_changing_wire_phase_names() {
+        let state = super::session_state(
+            bitfun_agent_runtime::session_state::SessionState::Processing {
+                current_turn_id: "turn-1".to_string(),
+                phase: bitfun_agent_runtime::session_state::ProcessingPhase::ToolCalling,
+            },
+        );
+
+        assert!(matches!(
+            state,
+            SessionRuntimeState::Processing {
+                phase: SessionProcessingPhase::ToolCalling,
+                ..
+            }
+        ));
+    }
+
+    #[test]
+    fn legacy_model_config_wire_document_is_the_owner_serialization() {
+        let owner = bitfun_core::service::config::AIModelConfig::default();
+        let expected = serde_json::to_value(&owner).expect("owner config should serialize");
+
+        assert_eq!(
+            super::model_config(owner).expect("wire projection should serialize"),
+            expected
+        );
+    }
+
+    #[test]
+    fn legacy_git_wire_projections_preserve_owner_json() {
+        let status_json = serde_json::json!({
+            "staged": [{
+                "path": "src/main.rs",
+                "status": "modified",
+                "index_status": "M",
+                "workdir_status": null
+            }],
+            "unstaged": [],
+            "untracked": ["notes.txt"],
+            "conflicts": ["Cargo.toml"],
+            "current_branch": "main",
+            "ahead": 2,
+            "behind": 1
+        });
+        let status = serde_json::from_value(status_json.clone())
+            .expect("owner Git status fixture should deserialize");
+        assert_eq!(
+            serde_json::to_value(super::git_status(status))
+                .expect("wire Git status should serialize"),
+            status_json
+        );
+
+        let branch_json = serde_json::json!({
+            "name": "feature/schema-owner",
+            "current": true,
+            "remote": false,
+            "upstream": "origin/feature/schema-owner",
+            "ahead": 3,
+            "behind": 0,
+            "last_commit": "abc123",
+            "last_commit_date": "2026-08-14T00:00:00Z",
+            "base_branch": "main",
+            "child_branches": ["feature/child"],
+            "merged_branches": [],
+            "branch_type": "feature",
+            "has_conflicts": false,
+            "can_merge": true,
+            "is_stale": false,
+            "merge_status": "clean",
+            "stats": {
+                "commit_count": 3,
+                "contributor_count": 1,
+                "file_changes": 4,
+                "lines_changed": { "additions": 20, "deletions": 5 },
+                "activity_score": 8
+            },
+            "created_at": "2026-08-13T00:00:00Z",
+            "last_activity_at": "2026-08-14T00:00:00Z",
+            "tags": ["schema"],
+            "description": "schema owner migration",
+            "linked_issues": ["#123"]
+        });
+        let branch = serde_json::from_value(branch_json.clone())
+            .expect("owner Git branch fixture should deserialize");
+        assert_eq!(
+            serde_json::to_value(super::git_branch(branch))
+                .expect("wire Git branch should serialize"),
+            branch_json
+        );
+    }
+}
diff --git a/src/crates/interfaces/app-server/tests/agent_kernel.rs b/src/crates/interfaces/app-server/tests/agent_kernel.rs
index 9e63e0b6f0..5745022542 100644
--- a/src/crates/interfaces/app-server/tests/agent_kernel.rs
+++ b/src/crates/interfaces/app-server/tests/agent_kernel.rs
@@ -301,7 +301,6 @@ struct Phase2Provider {
     steers: Mutex<Vec<ports::AgentDialogSteerRequest>>,
     shell_commands: Mutex<Vec<ports::AgentUserShellCommandRequest>>,
     answers: Mutex<Vec<ports::AgentUserAnswersRequest>>,
-    local_commands: Mutex<Vec<ports::AgentLocalCommandTurnRecordRequest>>,
     compactions: Mutex<Vec<ports::AgentSessionCompactionRequest>>,
     settlements: Mutex<Vec<ports::AgentTurnSettlementRequest>>,
     reloads: Mutex<Vec<ports::AgentContextReloadRequest>>,
@@ -468,7 +467,6 @@ impl ports::AgentLocalCommandTurnPort for Phase2Provider {
         &self,
         request: ports::AgentLocalCommandTurnRecordRequest,
     ) -> PortResult<ports::AgentLocalCommandTurnRecordResult> {
-        self.local_commands.lock().unwrap().push(request.clone());
         Ok(ports::AgentLocalCommandTurnRecordResult {
             turn_id: request
                 .turn_id
@@ -650,6 +648,11 @@ fn revert_result(session_id: String, text: &str) -> ports::AgentSessionRevertRes
         retired_turn_ids: vec!["turn-active".to_string()],
         changed: true,
         hidden_turn_count: 1,
+        boundary_storage_turn_index: None,
+        target_turn_id: None,
+        restored_files: Vec::new(),
+        reload_required: false,
+        reload_reason: None,
     }
 }
 
@@ -833,6 +836,8 @@ async fn phase2_mutations_route_through_runtime_owner_ports() {
                         turn_id: "turn-active".to_string(),
                         content: "keep going".to_string(),
                         display_content: None,
+                        attachments: Vec::new(),
+                        metadata: serde_json::Map::new(),
                     },
                 ))
                 .await
@@ -858,20 +863,6 @@ async fn phase2_mutations_route_through_runtime_owner_ports() {
                 })
                 .await
                 .expect("submit user answers");
-            let local_turn = client
-                .record_local_command_turn(protocol_session::RecordLocalCommandTurnRequest(
-                    ports::AgentLocalCommandTurnRecordRequest {
-                        session_id: "session-1".to_string(),
-                        content: "usage: 12 tokens".to_string(),
-                        turn_id: Some("local-turn".to_string()),
-                        timestamp_ms: Some(100),
-                        metadata: serde_json::Map::new(),
-                    },
-                ))
-                .await
-                .expect("record local command turn");
-            assert_eq!(local_turn.0.turn_id, "local-turn");
-
             client
                 .compact_session(protocol_session::CompactSessionRequest(
                     ports::AgentSessionCompactionRequest {
@@ -920,7 +911,6 @@ async fn phase2_mutations_route_through_runtime_owner_ports() {
                 "cargo test"
             );
             assert_eq!(provider.answers.lock().unwrap().len(), 1);
-            assert_eq!(provider.local_commands.lock().unwrap().len(), 1);
             assert_eq!(provider.compactions.lock().unwrap().len(), 1);
             assert_eq!(provider.reloads.lock().unwrap().len(), 1);
             client.shutdown().await;
@@ -1655,55 +1645,3 @@ struct UnknownAgentResponse;
 
 #[allow(dead_code)]
 fn _document_run_response_shape_in_tests(_r: RunResponse) {}
-
-/// The Server Host drives the app-server through the real `client::connect`
-/// handle (not an inline `AppClient::builder().connect_with` main_fn like the
-/// round-trip tests above). `connect` parks its main loop on a shutdown
-/// receiver and returns an `AppServerClient` the host holds for the process
-/// lifetime. This regression test pins that contract: after `connect`
-/// returns, an RPC sent through the returned handle must still reach the
-/// server and get a response. A previous version dropped `shutdown_tx` right
-/// before returning (`let _ = shutdown_tx;`), which let the parked main loop
-/// resume immediately, cancelling the connection's background actors -- every
-/// subsequent RPC then surfaced as `send failed because receiver is gone`
-/// (from `Task::spawn`'s `unbounded_send` failure). This test fails loud if
-/// that regression returns, because `create_session` would error instead of
-/// returning the mock session id.
-#[tokio::test(flavor = "current_thread")]
-async fn client_connect_keeps_connection_alive_after_return() {
-    let local = LocalSet::new();
-    local
-        .run_until(async {
-            let (server_transport, client_transport) = transport::in_memory_channel_pair();
-            let runtime = build_app_runtime();
-            spawn_server(runtime, server_transport);
-
-            let client = bitfun_app_server::connect(client_transport)
-                .await
-                .expect("app-server client should connect");
-
-            // The connect task must still be parked on the shutdown receiver
-            // here -- otherwise the connection's background actors are gone and
-            // this RPC surfaces `send failed because receiver is gone`.
-            let response = client
-                .create_session(AgentSessionCreateRequest {
-                    session_name: "post-connect session".to_string(),
-                    agent_type: "agentic".to_string(),
-                    workspace_path: None,
-                    project_workspace_path: None,
-                    execution_target: None,
-                    workspace_id: None,
-                    remote_connection_id: None,
-                    remote_ssh_host: None,
-                    model_id: None,
-                    metadata: Default::default(),
-                })
-                .await
-                .expect("RPC after connect() must succeed -- connection should still be alive");
-            assert_eq!(response.session_id, "example-session");
-            assert_eq!(response.agent_type, "agentic");
-
-            client.shutdown().await;
-        })
-        .await;
-}
diff --git a/src/crates/interfaces/sdk-host/Cargo.toml b/src/crates/interfaces/sdk-host/Cargo.toml
index 355f9b03f9..3cd0904510 100644
--- a/src/crates/interfaces/sdk-host/Cargo.toml
+++ b/src/crates/interfaces/sdk-host/Cargo.toml
@@ -10,17 +10,25 @@ name = "bitfun_sdk_host"
 
 [dependencies]
 async-trait = { workspace = true }
-bitfun-agent-runtime = { path = "../../execution/agent-runtime" }
+bitfun-agent-runtime = { path = "../../execution/agent-runtime", features = ["agent-runtime"] }
 bitfun-core-types = { path = "../../contracts/core-types" }
 bitfun-events = { path = "../../contracts/events" }
-bitfun-runtime-ports = { path = "../../contracts/runtime-ports" }
+bitfun-runtime-ports = { path = "../../contracts/runtime-ports", features = ["agent-api"] }
 futures-util = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
 tokio = { workspace = true, features = ["macros", "rt", "sync", "time"] }
 tokio-util = { workspace = true, features = ["codec"] }
 tracing = { workspace = true }
+ts-rs = { workspace = true, optional = true }
 uuid = { workspace = true }
 
+[features]
+default = []
+ts = ["dep:ts-rs", "bitfun-core-types/ts"]
+
+[dev-dependencies]
+bitfun-runtime-ports = { path = "../../contracts/runtime-ports", features = ["permission"] }
+
 [lints]
 workspace = true
diff --git a/src/crates/interfaces/sdk-host/src/host.rs b/src/crates/interfaces/sdk-host/src/host.rs
index dbe8b24d28..6914146034 100644
--- a/src/crates/interfaces/sdk-host/src/host.rs
+++ b/src/crates/interfaces/sdk-host/src/host.rs
@@ -2,7 +2,7 @@
 
 use std::collections::{HashMap, HashSet};
 use std::sync::atomic::{AtomicBool, Ordering};
-use std::sync::Arc;
+use std::sync::{Arc, Mutex as StdMutex};
 use std::time::Duration;
 
 use bitfun_agent_runtime::sdk::{
@@ -23,13 +23,14 @@ use tokio_util::sync::CancellationToken;
 
 use crate::protocol::{
     ErrorCode, ErrorData, ErrorStage, InitializeParams, InitializeResult, JsonRpcErrorResponse,
-    JsonRpcNotification, JsonRpcRequest, JsonRpcSuccessResponse, QueryCancelParams,
-    QueryCancelResult, QueryEvent, QueryEventParams, QueryResultError, QueryResultParams,
-    QueryStartParams, QueryStartResult, QueryTerminalStatus, RecoveryAction, RequestId,
-    SessionCloseParams, SessionCloseResult, SessionCreateParams, SessionCreateResult,
-    SessionLifetime, ShutdownParams, ShutdownResult, JSON_RPC_VERSION, METHOD_INITIALIZE,
-    METHOD_QUERY_CANCEL, METHOD_QUERY_START, METHOD_SESSION_CLOSE, METHOD_SESSION_CREATE,
-    METHOD_SHUTDOWN, NOTIFICATION_QUERY_EVENT, NOTIFICATION_QUERY_RESULT, PROTOCOL_VERSION,
+    JsonRpcNotification, JsonRpcRequest, JsonRpcSuccessResponse, OutcomeCertainty,
+    QueryCancelParams, QueryCancelResult, QueryEvent, QueryEventParams, QueryOutput,
+    QueryResultError, QueryResultParams, QueryStartParams, QueryStartResult, QueryTerminalStatus,
+    RecoveryAction, RequestId, SessionCloseParams, SessionCloseResult, SessionCreateParams,
+    SessionCreateResult, SessionLifetime, ShutdownParams, ShutdownResult, JSON_RPC_VERSION,
+    METHOD_INITIALIZE, METHOD_QUERY_CANCEL, METHOD_QUERY_START, METHOD_SESSION_CLOSE,
+    METHOD_SESSION_CREATE, METHOD_SHUTDOWN, NOTIFICATION_QUERY_EVENT, NOTIFICATION_QUERY_RESULT,
+    PROTOCOL_VERSION,
 };
 
 const DEFAULT_SESSION_NAME: &str = "BitFun SDK query";
@@ -37,6 +38,14 @@ const DEFAULT_AGENT: &str = "agentic";
 const DEFAULT_TURN_SETTLEMENT_TIMEOUT_MS: u64 = 5_000;
 const PERMISSION_REJECTION_TIMEOUT_MS: u64 = 2_000;
 const MAX_SESSION_CLOSE_TIMEOUT_MS: u64 = 30_000;
+const MAX_QUERY_OUTPUT_WIRE_BYTES: usize = 768 * 1024;
+
+fn json_string_content_bytes(value: &str) -> usize {
+    serde_json::to_vec(value)
+        .expect("serializing a Rust string as JSON cannot fail")
+        .len()
+        .saturating_sub(2)
+}
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ConnectionControl {
@@ -93,6 +102,7 @@ struct ConnectionInner {
     query_budget: Arc<Semaphore>,
     session_budget: Arc<Semaphore>,
     shutdown_started: CancellationToken,
+    connection_failed: CancellationToken,
 }
 
 #[derive(Default)]
@@ -140,12 +150,20 @@ struct QueryLease {
     query_id: String,
     session_id: String,
     turn_id: String,
+    operation_id: String,
+    output: StdMutex<QueryOutputBuffer>,
     terminal: AtomicBool,
     stop_forwarding: CancellationToken,
     emit_output: bool,
     _budget: OwnedSemaphorePermit,
 }
 
+#[derive(Default)]
+struct QueryOutputBuffer {
+    text: String,
+    wire_bytes: usize,
+}
+
 impl QueryLease {
     fn finish_once(&self) -> bool {
         !self.terminal.swap(true, Ordering::AcqRel)
@@ -187,10 +205,15 @@ impl SdkHostConnection {
                 query_budget: Arc::new(Semaphore::new(config.max_active_queries.max(1))),
                 session_budget: Arc::new(Semaphore::new(config.max_leased_sessions.max(1))),
                 shutdown_started: CancellationToken::new(),
+                connection_failed: CancellationToken::new(),
             }),
         }
     }
 
+    pub fn connection_failed_token(&self) -> CancellationToken {
+        self.inner.connection_failed.clone()
+    }
+
     pub async fn handle_request(&self, request: JsonRpcRequest) -> ConnectionControl {
         let request_id = request.id.clone();
         if request.jsonrpc != JSON_RPC_VERSION {
@@ -201,6 +224,8 @@ impl SdkHostConnection {
                 ErrorStage::Protocol,
                 false,
                 None,
+                OutcomeCertainty::NotStarted,
+                None,
                 "jsonrpc must be 2.0",
             )
             .await;
@@ -324,6 +349,8 @@ impl SdkHostConnection {
                     ErrorStage::Protocol,
                     false,
                     None,
+                    OutcomeCertainty::NotStarted,
+                    None,
                     "method is not supported by this SDK Host",
                 )
                 .await;
@@ -1022,10 +1049,13 @@ impl SdkHostConnection {
             } => (session_id, turn_id),
         };
         let query_id = format!("query_{}", uuid::Uuid::new_v4());
+        let operation_id = format!("operation_{}", uuid::Uuid::new_v4());
         let lease = Arc::new(QueryLease {
             query_id: query_id.clone(),
             session_id: submitted_session_id.clone(),
             turn_id: turn_id.clone(),
+            operation_id: operation_id.clone(),
+            output: StdMutex::new(QueryOutputBuffer::default()),
             terminal: AtomicBool::new(false),
             stop_forwarding: CancellationToken::new(),
             emit_output,
@@ -1045,6 +1075,7 @@ impl SdkHostConnection {
                     query_id: query_id.clone(),
                     session_id: submitted_session_id.clone(),
                     turn_id: turn_id.clone(),
+                    operation_id,
                     accepted: true,
                     created_session,
                     session_lifetime,
@@ -1176,6 +1207,39 @@ impl SdkHostConnection {
                 let terminal = terminal_fact(&envelope.event, &lease.turn_id, &lease.query_id);
                 if lease.emit_output {
                     if let Some(projected) = project_query_event(&envelope.event) {
+                        let QueryEvent::AssistantTextDelta { text } = &projected;
+                        let output_exceeded = {
+                            let encoded_bytes = json_string_content_bytes(text);
+                            let mut output = lease
+                                .output
+                                .lock()
+                                .expect("SDK Host Query output lock poisoned");
+                            if encoded_bytes
+                                > MAX_QUERY_OUTPUT_WIRE_BYTES.saturating_sub(output.wire_bytes)
+                            {
+                                true
+                            } else {
+                                output.text.push_str(text);
+                                output.wire_bytes += encoded_bytes;
+                                false
+                            }
+                        };
+                        if output_exceeded {
+                            connection
+                                .cancel_and_finish(
+                                    &lease,
+                                    QueryResultError::new(
+                                        ErrorCode::Overloaded,
+                                        false,
+                                        None,
+                                        &lease.query_id,
+                                        "SDK Host Query output exceeded the protocol size limit",
+                                    ),
+                                    true,
+                                )
+                                .await;
+                            return;
+                        }
                         sequence += 1;
                         if !connection
                             .send_notification(
@@ -1184,6 +1248,7 @@ impl SdkHostConnection {
                                     query_id: lease.query_id.clone(),
                                     session_id: lease.session_id.clone(),
                                     turn_id: lease.turn_id.clone(),
+                                    operation_id: lease.operation_id.clone(),
                                     sequence,
                                     event: projected,
                                 },
@@ -1231,17 +1296,31 @@ impl SdkHostConnection {
             .get(&params.query_id)
             .cloned();
         let Some(lease) = lease else {
-            self.send_error(
+            self.send_success(
                 request.id.clone(),
-                ErrorCode::NotFound,
-                ErrorStage::Query,
-                false,
-                None,
-                "Query was not found",
+                QueryCancelResult {
+                    query_id: params.query_id,
+                    session_id: params.session_id,
+                    turn_id: params.turn_id,
+                    operation_id: params.operation_id,
+                    requested: false,
+                },
             )
             .await;
             return;
         };
+        if lease.session_id != params.session_id
+            || lease.turn_id != params.turn_id
+            || lease.operation_id != params.operation_id
+        {
+            self.send_invalid_params(
+                request.id.clone(),
+                ErrorStage::Query,
+                "Query cancellation identity does not match the accepted Query",
+            )
+            .await;
+            return;
+        }
         match timeout(
             Duration::from_millis(2_500),
             self.inner
@@ -1265,21 +1344,28 @@ impl SdkHostConnection {
                         query_id: lease.query_id.clone(),
                         session_id: lease.session_id.clone(),
                         turn_id: lease.turn_id.clone(),
+                        operation_id: lease.operation_id.clone(),
                         requested: result.requested,
                     },
                 )
                 .await;
             }
             Ok(Err(error)) => {
-                self.send_runtime_error(request.id.clone(), ErrorStage::Query, error)
-                    .await
+                self.send_runtime_uncertain_error(
+                    request.id.clone(),
+                    ErrorStage::Query,
+                    Some(lease.operation_id.clone()),
+                    error,
+                )
+                .await
             }
             Err(_) => {
-                self.send_error(
+                self.send_uncertain_error(
                     request.id.clone(),
                     ErrorCode::Timeout,
                     ErrorStage::Query,
                     true,
+                    Some(lease.operation_id.clone()),
                     Some(RecoveryAction::Retry),
                     "SDK Host Query cancellation timed out",
                 )
@@ -1408,11 +1494,12 @@ impl SdkHostConnection {
                     "SDK Host Session close ended with uncertain cleanup"
                 );
                 self.mark_session_cleanup_failed(&params.session_id).await;
-                self.send_error(
+                self.send_uncertain_error(
                     request.id.clone(),
                     ErrorCode::CleanupRequired,
                     ErrorStage::Session,
                     false,
+                    None,
                     Some(RecoveryAction::RestartHost),
                     "SDK Host Session cleanup is incomplete; restart the Host before retrying",
                 )
@@ -1424,11 +1511,12 @@ impl SdkHostConnection {
                     "SDK Host Session close timed out with uncertain cleanup"
                 );
                 self.mark_session_cleanup_failed(&params.session_id).await;
-                self.send_error(
+                self.send_uncertain_error(
                     request.id.clone(),
                     ErrorCode::CleanupRequired,
                     ErrorStage::Session,
                     false,
+                    None,
                     Some(RecoveryAction::RestartHost),
                     "SDK Host Session cleanup timed out; restart the Host before retrying",
                 )
@@ -1717,8 +1805,8 @@ impl SdkHostConnection {
     async fn finish_query(
         &self,
         lease: &Arc<QueryLease>,
-        mut status: QueryTerminalStatus,
-        mut error: Option<QueryResultError>,
+        status: QueryTerminalStatus,
+        error: Option<QueryResultError>,
         emit_result: bool,
     ) {
         if !lease.finish_once() {
@@ -1735,41 +1823,23 @@ impl SdkHostConnection {
                 }),
         )
         .await;
-        let mut poison_session = false;
-        match settlement {
-            Ok(Ok(())) => {}
-            Ok(Err(_settlement_error)) => {
-                poison_session = true;
-                status = QueryTerminalStatus::Failed;
-                error = Some(QueryResultError::new(
-                    ErrorCode::CleanupRequired,
-                    false,
-                    Some(RecoveryAction::RestartHost),
-                    &lease.query_id,
-                    "SDK Host could not confirm Turn settlement; restart the Host before retrying",
-                ));
-            }
-            Err(_) => {
-                poison_session = true;
-                status = QueryTerminalStatus::Failed;
-                error = Some(QueryResultError::new(
-                    ErrorCode::CleanupRequired,
-                    false,
-                    Some(RecoveryAction::RestartHost),
-                    &lease.query_id,
-                    "SDK Host Turn settlement timed out; restart the Host before retrying",
-                ));
-            }
-        }
+        let settlement_confirmed = matches!(settlement, Ok(Ok(())));
         {
             let mut state = self.inner.state.lock().await;
             state.queries.remove(&lease.query_id);
             state.starting_query_sessions.remove(&lease.session_id);
             state.active_query_sessions.remove(&lease.session_id);
-            if poison_session {
+            if !settlement_confirmed {
                 state.poisoned_sessions.insert(lease.session_id.clone());
+                state.cleanup_failed = true;
+                state.shutting_down = true;
             }
         }
+        if !settlement_confirmed {
+            lease.stop_forwarding.cancel();
+            self.inner.connection_failed.cancel();
+            return;
+        }
         if emit_result {
             self.send_query_result(lease, status, error).await;
         }
@@ -1779,18 +1849,29 @@ impl SdkHostConnection {
         &self,
         lease: &QueryLease,
         status: QueryTerminalStatus,
-        error: Option<QueryResultError>,
+        mut error: Option<QueryResultError>,
     ) -> bool {
         if !lease.emit_output {
             return true;
         }
+        if let Some(error) = error.as_mut() {
+            error.data.operation_id = Some(lease.operation_id.clone());
+        }
+        let output_text = lease
+            .output
+            .lock()
+            .expect("SDK Host Query output lock poisoned")
+            .text
+            .clone();
         self.send_notification(
             NOTIFICATION_QUERY_RESULT,
             QueryResultParams {
                 query_id: lease.query_id.clone(),
                 session_id: lease.session_id.clone(),
                 turn_id: lease.turn_id.clone(),
+                operation_id: lease.operation_id.clone(),
                 status,
+                output: QueryOutput { text: output_text },
                 error,
             },
         )
@@ -1933,6 +2014,8 @@ impl SdkHostConnection {
             stage,
             false,
             None,
+            OutcomeCertainty::NotStarted,
+            None,
             message,
         )
         .await;
@@ -1949,6 +2032,28 @@ impl SdkHostConnection {
             .await;
     }
 
+    async fn send_runtime_uncertain_error(
+        &self,
+        id: Option<RequestId>,
+        stage: ErrorStage,
+        operation_id: Option<String>,
+        error: RuntimeError,
+    ) {
+        let (code, retryable, recovery) = runtime_error_facts(&error);
+        self.send_rpc_error(
+            id,
+            -32000,
+            code,
+            stage,
+            retryable,
+            operation_id,
+            OutcomeCertainty::Unknown,
+            recovery,
+            &error.into_message(),
+        )
+        .await;
+    }
+
     async fn send_error(
         &self,
         id: Option<RequestId>,
@@ -1958,8 +2063,42 @@ impl SdkHostConnection {
         recovery: Option<RecoveryAction>,
         message: &str,
     ) {
-        self.send_rpc_error(id, -32000, code, stage, retryable, recovery, message)
-            .await;
+        self.send_rpc_error(
+            id,
+            -32000,
+            code,
+            stage,
+            retryable,
+            None,
+            OutcomeCertainty::NotStarted,
+            recovery,
+            message,
+        )
+        .await;
+    }
+
+    async fn send_uncertain_error(
+        &self,
+        id: Option<RequestId>,
+        code: ErrorCode,
+        stage: ErrorStage,
+        retryable: bool,
+        operation_id: Option<String>,
+        recovery: Option<RecoveryAction>,
+        message: &str,
+    ) {
+        self.send_rpc_error(
+            id,
+            -32000,
+            code,
+            stage,
+            retryable,
+            operation_id,
+            OutcomeCertainty::Unknown,
+            recovery,
+            message,
+        )
+        .await;
     }
 
     #[allow(clippy::too_many_arguments)]
@@ -1970,6 +2109,8 @@ impl SdkHostConnection {
         code: ErrorCode,
         stage: ErrorStage,
         retryable: bool,
+        operation_id: Option<String>,
+        outcome_certainty: OutcomeCertainty,
         recovery: Option<RecoveryAction>,
         message: &str,
     ) {
@@ -1986,6 +2127,9 @@ impl SdkHostConnection {
                 stage,
                 retryable,
                 correlation_id,
+                operation_id,
+                causation_id: None,
+                outcome_certainty,
                 recovery,
             },
         ))
diff --git a/src/crates/interfaces/sdk-host/src/protocol.rs b/src/crates/interfaces/sdk-host/src/protocol.rs
index 5cb055f0ea..8c72312203 100644
--- a/src/crates/interfaces/sdk-host/src/protocol.rs
+++ b/src/crates/interfaces/sdk-host/src/protocol.rs
@@ -105,6 +105,9 @@ impl JsonRpcErrorResponse {
                     stage: ErrorStage::Protocol,
                     retryable: false,
                     correlation_id: correlation_id.into(),
+                    operation_id: None,
+                    causation_id: None,
+                    outcome_certainty: OutcomeCertainty::NotStarted,
                     recovery: None,
                 },
             },
@@ -127,6 +130,9 @@ impl JsonRpcErrorResponse {
                     stage: ErrorStage::Protocol,
                     retryable: false,
                     correlation_id: correlation_id.into(),
+                    operation_id: None,
+                    causation_id: None,
+                    outcome_certainty: OutcomeCertainty::NotStarted,
                     recovery: None,
                 },
             },
@@ -159,6 +165,7 @@ impl<T> JsonRpcNotification<T> {
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[serde(deny_unknown_fields, rename_all = "camelCase")]
 pub struct InitializeParams {
     pub protocol_version: u32,
@@ -167,6 +174,7 @@ pub struct InitializeParams {
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[serde(deny_unknown_fields)]
 pub struct ClientInfo {
     pub name: String,
@@ -174,12 +182,14 @@ pub struct ClientInfo {
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[serde(deny_unknown_fields, rename_all = "camelCase")]
 pub struct ClientCapabilities {
     pub server_notifications: bool,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[serde(rename_all = "camelCase")]
 pub struct InitializeResult {
     pub protocol_version: u32,
@@ -200,6 +210,7 @@ impl InitializeResult {
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[serde(rename_all = "snake_case")]
 pub enum Stability {
     /// Internal implementation candidate. It is not a supported SDK surface.
@@ -207,6 +218,7 @@ pub enum Stability {
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[serde(rename_all = "camelCase")]
 pub struct HostCapabilities {
     pub session_create: bool,
@@ -246,6 +258,7 @@ impl HostCapabilities {
 
 /// Persistence boundary of a Session visible through the internal Host candidate.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[serde(rename_all = "snake_case")]
 pub enum SessionLifetime {
     /// Created and deleted by this Host connection.
@@ -260,6 +273,7 @@ where
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[serde(rename_all = "snake_case")]
 pub enum ErrorCode {
     InvalidRequest,
@@ -286,6 +300,7 @@ pub enum ErrorCode {
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[serde(rename_all = "snake_case")]
 pub enum ErrorStage {
     Protocol,
@@ -296,6 +311,7 @@ pub enum ErrorStage {
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[serde(rename_all = "snake_case")]
 pub enum RecoveryAction {
     Initialize,
@@ -305,42 +321,70 @@ pub enum RecoveryAction {
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[serde(rename_all = "camelCase")]
 pub struct ErrorData {
     pub code: ErrorCode,
     pub stage: ErrorStage,
     pub retryable: bool,
     pub correlation_id: String,
+    #[cfg_attr(feature = "ts", ts(optional))]
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub operation_id: Option<String>,
+    #[cfg_attr(feature = "ts", ts(optional))]
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub causation_id: Option<String>,
+    pub outcome_certainty: OutcomeCertainty,
+    #[cfg_attr(feature = "ts", ts(optional))]
     #[serde(skip_serializing_if = "Option::is_none")]
     pub recovery: Option<RecoveryAction>,
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(rename_all = "snake_case")]
+pub enum OutcomeCertainty {
+    NotStarted,
+    Committed,
+    Unknown,
+}
+
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[serde(deny_unknown_fields, rename_all = "camelCase")]
 pub struct SessionCreateParams {
+    #[cfg_attr(feature = "ts", ts(optional = nullable))]
     #[serde(default)]
     pub session_name: Option<String>,
+    #[cfg_attr(feature = "ts", ts(optional = nullable))]
     #[serde(default)]
     pub agent: Option<String>,
+    #[cfg_attr(feature = "ts", ts(optional = nullable))]
     #[serde(default)]
     pub cwd: Option<String>,
+    #[cfg_attr(feature = "ts", ts(optional = nullable))]
     #[serde(default)]
     pub model: Option<String>,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[serde(rename_all = "camelCase")]
 pub struct SessionCreateResult {
     pub session_id: String,
     pub session_name: String,
     pub agent: String,
     pub lifetime: SessionLifetime,
+    #[cfg_attr(feature = "ts", ts(optional))]
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub workspace_path: Option<String>,
+    #[cfg_attr(feature = "ts", ts(optional))]
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub workspace_id: Option<String>,
+    #[cfg_attr(feature = "ts", ts(optional))]
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub project_workspace_path: Option<String>,
+    #[cfg_attr(feature = "ts", ts(optional))]
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub execution_target: Option<SessionExecutionTarget>,
 }
@@ -361,56 +405,73 @@ impl SessionCreateResult {
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[serde(deny_unknown_fields, rename_all = "camelCase")]
 pub struct QueryStartParams {
     pub prompt: String,
+    #[cfg_attr(feature = "ts", ts(optional = nullable))]
     #[serde(default)]
     pub session_id: Option<String>,
+    #[cfg_attr(feature = "ts", ts(optional = nullable))]
     #[serde(default)]
     pub session_name: Option<String>,
+    #[cfg_attr(feature = "ts", ts(optional = nullable))]
     #[serde(default)]
     pub agent: Option<String>,
+    #[cfg_attr(feature = "ts", ts(optional = nullable))]
     #[serde(default)]
     pub cwd: Option<String>,
+    #[cfg_attr(feature = "ts", ts(optional = nullable))]
     #[serde(default)]
     pub model: Option<String>,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[serde(rename_all = "camelCase")]
 pub struct QueryStartResult {
     pub query_id: String,
     pub session_id: String,
     pub turn_id: String,
+    pub operation_id: String,
     pub accepted: bool,
     pub created_session: bool,
     pub session_lifetime: SessionLifetime,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[serde(deny_unknown_fields, rename_all = "camelCase")]
 pub struct QueryCancelParams {
     pub query_id: String,
+    pub session_id: String,
+    pub turn_id: String,
+    pub operation_id: String,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[serde(rename_all = "camelCase")]
 pub struct QueryCancelResult {
     pub query_id: String,
     pub session_id: String,
     pub turn_id: String,
+    pub operation_id: String,
     pub requested: bool,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[serde(deny_unknown_fields, rename_all = "camelCase")]
 pub struct SessionCloseParams {
     pub session_id: String,
+    #[cfg_attr(feature = "ts", ts(optional = nullable))]
     #[serde(default)]
     pub wait_timeout_ms: Option<u64>,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[serde(rename_all = "camelCase")]
 pub struct SessionCloseResult {
     pub session_id: String,
@@ -418,32 +479,38 @@ pub struct SessionCloseResult {
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[serde(deny_unknown_fields)]
 pub struct ShutdownParams {}
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[serde(rename_all = "camelCase")]
 pub struct ShutdownResult {
     pub accepted: bool,
 }
 
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[serde(rename_all = "camelCase")]
 pub struct QueryEventParams {
     pub query_id: String,
     pub session_id: String,
     pub turn_id: String,
+    pub operation_id: String,
     pub sequence: u64,
     pub event: QueryEvent,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[serde(tag = "type", rename_all = "snake_case")]
 pub enum QueryEvent {
     AssistantTextDelta { text: String },
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[serde(rename_all = "snake_case")]
 pub enum QueryTerminalStatus {
     Completed,
@@ -452,17 +519,28 @@ pub enum QueryTerminalStatus {
 }
 
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 #[serde(rename_all = "camelCase")]
 pub struct QueryResultParams {
     pub query_id: String,
     pub session_id: String,
     pub turn_id: String,
+    pub operation_id: String,
     pub status: QueryTerminalStatus,
+    pub output: QueryOutput,
+    #[cfg_attr(feature = "ts", ts(optional))]
     #[serde(skip_serializing_if = "Option::is_none")]
     pub error: Option<QueryResultError>,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+pub struct QueryOutput {
+    pub text: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
 pub struct QueryResultError {
     pub message: String,
     pub data: ErrorData,
@@ -483,6 +561,14 @@ impl QueryResultError {
                 stage: ErrorStage::Query,
                 retryable,
                 correlation_id: format!("query:{query_id}"),
+                operation_id: None,
+                causation_id: None,
+                outcome_certainty: match code {
+                    ErrorCode::CleanupRequired | ErrorCode::ProcessLost => {
+                        OutcomeCertainty::Unknown
+                    }
+                    _ => OutcomeCertainty::Committed,
+                },
                 recovery,
             },
         }
diff --git a/src/crates/interfaces/sdk-host/tests/host_lifecycle.rs b/src/crates/interfaces/sdk-host/tests/host_lifecycle.rs
index 747a0106c4..d66dd608da 100644
--- a/src/crates/interfaces/sdk-host/tests/host_lifecycle.rs
+++ b/src/crates/interfaces/sdk-host/tests/host_lifecycle.rs
@@ -23,6 +23,7 @@ use bitfun_runtime_ports::{
 use bitfun_sdk_host::host::{ConnectionControl, HostOutput, SdkHostConfig, SdkHostConnection};
 use bitfun_sdk_host::protocol::{JsonRpcRequest, PROTOCOL_VERSION};
 use tokio::sync::{mpsc, Notify};
+use tokio::time::timeout;
 
 #[derive(Default)]
 struct FakeOwner {
@@ -38,6 +39,7 @@ struct FakeOwner {
     fail_settlement: bool,
     queue_dialog: bool,
     dialog_session_override: Option<String>,
+    output_text: Option<String>,
     block_dialog_submit: bool,
     block_agent_resolution: bool,
     block_first_cancel: bool,
@@ -93,6 +95,15 @@ impl FakeOwner {
         }
     }
 
+    fn with_output(queue: Arc<EventQueue>, output_text: String) -> Self {
+        Self {
+            queue: Mutex::new(Some(queue)),
+            emit_terminal: true,
+            output_text: Some(output_text),
+            ..Self::default()
+        }
+    }
+
     fn failing_dialog(queue: Arc<EventQueue>) -> Self {
         Self {
             queue: Mutex::new(Some(queue)),
@@ -309,7 +320,10 @@ impl AgentDialogTurnPort for FakeOwner {
                     round_id: "round-fixture".to_string(),
                     attempt_id: Some("attempt-fixture".to_string()),
                     attempt_index: Some(0),
-                    text: "fixture result".to_string(),
+                    text: self
+                        .output_text
+                        .clone()
+                        .unwrap_or_else(|| "fixture result".to_string()),
                 },
                 None,
             )
@@ -773,16 +787,187 @@ async fn query_streams_existing_events_and_one_terminal_result() {
     let event = output.recv().await.unwrap();
     assert_eq!(event["method"], "query/event");
     assert_eq!(event["params"]["queryId"], query_id);
+    let operation_id = accepted["result"]["operationId"]
+        .as_str()
+        .expect("accepted Query operation id")
+        .to_string();
+    assert_ne!(operation_id, query_id);
+    assert_eq!(event["params"]["operationId"], operation_id);
     assert_eq!(event["params"]["event"]["type"], "assistant_text_delta");
     assert_eq!(event["params"]["event"]["text"], "fixture result");
 
     let result = output.recv().await.unwrap();
     assert_eq!(result["method"], "query/result");
     assert_eq!(result["params"]["queryId"], query_id);
+    assert_eq!(result["params"]["operationId"], operation_id);
     assert_eq!(result["params"]["status"], "completed");
+    assert_eq!(result["params"]["output"]["text"], "fixture result");
     assert!(output.try_recv().is_err(), "terminal result must be unique");
 }
 
+#[tokio::test]
+async fn escaped_query_output_fails_before_exceeding_the_wire_budget() {
+    let queue = Arc::new(EventQueue::new(EventQueueConfig::default()));
+    let owner = Arc::new(FakeOwner::with_output(
+        queue.clone(),
+        "\\".repeat(384 * 1024 + 1),
+    ));
+    let runtime = AgentRuntimeBuilder::new()
+        .with_submission_port(owner.clone())
+        .with_dialog_turn_port(owner.clone())
+        .with_cancellation_port(owner.clone())
+        .with_turn_settlement_port(owner.clone())
+        .with_session_management_port(owner.clone())
+        .with_session_close_port(owner.clone())
+        .with_permission_request_manager(permission_manager())
+        .with_event_source(AgentEventSource::new(queue))
+        .build()
+        .unwrap();
+    let (sender, mut output) = mpsc::channel(16);
+    let host = SdkHostConnection::new(
+        runtime,
+        "D:/workspace/project",
+        sender,
+        SdkHostConfig::default(),
+    );
+    initialize(&host, &mut output).await;
+
+    host.handle_request(request(serde_json::json!({
+        "jsonrpc": "2.0",
+        "id": "query-output-limit",
+        "method": "query/start",
+        "params": { "prompt": "produce excessive output" }
+    })))
+    .await;
+
+    assert_eq!(output.recv().await.unwrap()["id"], "query-output-limit");
+    let result = output.recv().await.unwrap();
+    assert_eq!(result["method"], "query/result");
+    assert_eq!(result["params"]["status"], "failed");
+    assert_eq!(result["params"]["error"]["data"]["code"], "overloaded");
+    assert_eq!(result["params"]["output"]["text"], "");
+}
+
+#[tokio::test]
+async fn cancellation_after_terminal_result_is_idempotent_with_full_query_identity() {
+    let (host, _, mut output) = host().await;
+    initialize(&host, &mut output).await;
+    host.handle_request(request(serde_json::json!({
+        "jsonrpc": "2.0",
+        "id": "query-before-late-cancel",
+        "method": "query/start",
+        "params": { "prompt": "hello" }
+    })))
+    .await;
+    let accepted = output.recv().await.unwrap();
+    let query_id = accepted["result"]["queryId"].as_str().unwrap().to_string();
+    let session_id = accepted["result"]["sessionId"]
+        .as_str()
+        .unwrap()
+        .to_string();
+    let turn_id = accepted["result"]["turnId"].as_str().unwrap().to_string();
+    let operation_id = accepted["result"]["operationId"]
+        .as_str()
+        .unwrap()
+        .to_string();
+    while output.recv().await.unwrap()["method"] != "query/result" {}
+
+    host.handle_request(request(serde_json::json!({
+        "jsonrpc": "2.0",
+        "id": "late-cancel",
+        "method": "query/cancel",
+        "params": {
+            "queryId": query_id,
+            "sessionId": session_id,
+            "turnId": turn_id,
+            "operationId": operation_id
+        }
+    })))
+    .await;
+    let cancelled = output.recv().await.unwrap();
+    assert_eq!(cancelled["id"], "late-cancel");
+    assert_eq!(cancelled["result"]["queryId"], query_id);
+    assert_eq!(cancelled["result"]["operationId"], operation_id);
+    assert_eq!(cancelled["result"]["requested"], false);
+}
+
+#[tokio::test]
+async fn cancellation_timeout_reports_unknown_outcome_for_the_exact_operation() {
+    let queue = Arc::new(EventQueue::new(EventQueueConfig::default()));
+    let owner = Arc::new(FakeOwner::blocking_first_cancel(queue.clone()));
+    let runtime = AgentRuntimeBuilder::new()
+        .with_submission_port(owner.clone())
+        .with_dialog_turn_port(owner.clone())
+        .with_cancellation_port(owner.clone())
+        .with_turn_settlement_port(owner.clone())
+        .with_session_management_port(owner.clone())
+        .with_session_close_port(owner.clone())
+        .with_permission_request_manager(permission_manager())
+        .with_event_source(AgentEventSource::new(queue))
+        .build()
+        .unwrap();
+    let (sender, mut output) = mpsc::channel(16);
+    let host = SdkHostConnection::new(
+        runtime,
+        "D:/workspace/project",
+        sender,
+        SdkHostConfig::default(),
+    );
+    initialize(&host, &mut output).await;
+
+    host.handle_request(request(serde_json::json!({
+        "jsonrpc": "2.0",
+        "id": "query-before-cancel-timeout",
+        "method": "query/start",
+        "params": { "prompt": "hello" }
+    })))
+    .await;
+    let accepted = output.recv().await.unwrap();
+    let query_id = accepted["result"]["queryId"].as_str().unwrap().to_string();
+    let session_id = accepted["result"]["sessionId"]
+        .as_str()
+        .unwrap()
+        .to_string();
+    let turn_id = accepted["result"]["turnId"].as_str().unwrap().to_string();
+    let operation_id = accepted["result"]["operationId"]
+        .as_str()
+        .unwrap()
+        .to_string();
+    let expected_operation_id = operation_id.clone();
+
+    let cancel_host = host.clone();
+    let cancel = tokio::spawn(async move {
+        cancel_host
+            .handle_request(request(serde_json::json!({
+                "jsonrpc": "2.0",
+                "id": "cancel-timeout",
+                "method": "query/cancel",
+                "params": {
+                    "queryId": query_id,
+                    "sessionId": session_id,
+                    "turnId": turn_id,
+                    "operationId": operation_id
+                }
+            })))
+            .await
+    });
+    owner.first_cancel_started.notified().await;
+    let cancellation = loop {
+        let message = output.recv().await.unwrap();
+        if message["id"] == "cancel-timeout" {
+            break message;
+        }
+    };
+    assert_eq!(cancellation["error"]["data"]["code"], "timeout");
+    assert_eq!(cancellation["error"]["data"]["outcomeCertainty"], "unknown");
+    assert_eq!(
+        cancellation["error"]["data"]["operationId"],
+        expected_operation_id
+    );
+    assert_eq!(cancel.await.unwrap(), ConnectionControl::Continue);
+    host.shutdown_connection().await;
+}
+
 #[tokio::test]
 async fn query_on_created_transient_session_preserves_connection_lifetime() {
     let (host, _, mut output) = host().await;
@@ -892,12 +1077,19 @@ async fn cancel_close_and_shutdown_use_existing_runtime_owners() {
         .as_str()
         .unwrap()
         .to_string();
+    let turn_id = accepted["result"]["turnId"].as_str().unwrap();
+    let operation_id = accepted["result"]["operationId"].as_str().unwrap();
 
     host.handle_request(request(serde_json::json!({
         "jsonrpc": "2.0",
         "id": "cancel-1",
         "method": "query/cancel",
-        "params": { "queryId": query_id }
+        "params": {
+            "queryId": query_id,
+            "sessionId": session_id,
+            "turnId": turn_id,
+            "operationId": operation_id
+        }
     })))
     .await;
     while output.recv().await.unwrap()["id"] != "cancel-1" {}
@@ -973,6 +1165,7 @@ async fn uncertain_session_close_cleanup_requires_host_restart() {
     let close_error = output.recv().await.unwrap();
     assert_eq!(close_error["error"]["data"]["code"], "cleanup_required");
     assert_eq!(close_error["error"]["data"]["retryable"], false);
+    assert_eq!(close_error["error"]["data"]["outcomeCertainty"], "unknown");
     assert_eq!(close_error["error"]["data"]["recovery"], "restart_host");
 
     host.handle_request(request(serde_json::json!({
@@ -1064,12 +1257,18 @@ async fn cancellation_remains_available_when_data_request_capacity_is_exhausted(
         "jsonrpc": "2.0",
         "id": "cancel-while-data-busy",
         "method": "query/cancel",
-        "params": { "queryId": "missing-query" }
+        "params": {
+            "queryId": "missing-query",
+            "sessionId": "missing-session",
+            "turnId": "missing-turn",
+            "operationId": "missing-operation"
+        }
     })))
     .await;
     let cancellation = output.recv().await.unwrap();
     assert_eq!(cancellation["id"], "cancel-while-data-busy");
-    assert_eq!(cancellation["error"]["data"]["code"], "not_found");
+    assert_eq!(cancellation["result"]["requested"], false);
+    assert_eq!(cancellation["result"]["operationId"], "missing-operation");
 
     owner.release_session_create.notify_one();
     assert_eq!(create.await.unwrap(), ConnectionControl::Continue);
@@ -1681,7 +1880,7 @@ async fn terminal_failure_is_typed_and_emitted_after_settlement() {
 }
 
 #[tokio::test]
-async fn uncertain_turn_settlement_poisons_the_session_against_retry() {
+async fn uncertain_turn_settlement_fails_the_connection_without_a_result() {
     let queue = Arc::new(EventQueue::new(EventQueueConfig::default()));
     let owner = Arc::new(FakeOwner::failing_settlement(queue.clone()));
     let runtime = AgentRuntimeBuilder::new()
@@ -1702,6 +1901,7 @@ async fn uncertain_turn_settlement_poisons_the_session_against_retry() {
         sender,
         SdkHostConfig::default(),
     );
+    let connection_failed = host.connection_failed_token();
     initialize(&host, &mut output).await;
     host.handle_request(request(serde_json::json!({
         "jsonrpc": "2.0",
@@ -1711,25 +1911,13 @@ async fn uncertain_turn_settlement_poisons_the_session_against_retry() {
     })))
     .await;
     let accepted = output.recv().await.unwrap();
-    let session_id = accepted["result"]["sessionId"]
-        .as_str()
-        .unwrap()
-        .to_string();
-    let result = loop {
-        let value = output.recv().await.unwrap();
-        if value["method"] == "query/result" {
-            break value;
-        }
-    };
-    assert_eq!(
-        result["params"]["error"]["data"]["code"],
-        "cleanup_required"
-    );
-    assert_eq!(result["params"]["error"]["data"]["retryable"], false);
-    assert_eq!(
-        result["params"]["error"]["data"]["recovery"],
-        "restart_host"
-    );
+    let session_id = accepted["result"]["sessionId"].as_str().unwrap();
+    timeout(Duration::from_secs(1), connection_failed.cancelled())
+        .await
+        .expect("uncertain Turn settlement must fail the connection");
+    while let Ok(Some(value)) = timeout(Duration::from_millis(50), output.recv()).await {
+        assert_ne!(value["method"], "query/result");
+    }
 
     host.handle_request(request(serde_json::json!({
         "jsonrpc": "2.0",
diff --git a/src/crates/interfaces/sdk-host/tests/protocol_contracts.rs b/src/crates/interfaces/sdk-host/tests/protocol_contracts.rs
index d06eaa5db6..93eb25860e 100644
--- a/src/crates/interfaces/sdk-host/tests/protocol_contracts.rs
+++ b/src/crates/interfaces/sdk-host/tests/protocol_contracts.rs
@@ -1,8 +1,8 @@
 use bitfun_sdk_host::protocol::{
     ErrorCode, ErrorData, ErrorStage, HostCapabilities, InitializeParams, InitializeResult,
-    JsonRpcErrorResponse, JsonRpcRequest, JsonRpcSuccessResponse, QueryEvent, QueryResultError,
-    QueryResultParams, QueryTerminalStatus, RecoveryAction, RequestId, SessionLifetime, Stability,
-    PROTOCOL_VERSION,
+    JsonRpcErrorResponse, JsonRpcRequest, JsonRpcSuccessResponse, OutcomeCertainty, QueryEvent,
+    QueryOutput, QueryResultError, QueryResultParams, QueryTerminalStatus, RecoveryAction,
+    RequestId, SessionLifetime, Stability, PROTOCOL_VERSION,
 };
 
 #[test]
@@ -85,7 +85,11 @@ fn query_events_and_terminal_errors_are_closed_protocol_values() {
         query_id: "query-1".to_string(),
         session_id: "session-1".to_string(),
         turn_id: "turn-1".to_string(),
+        operation_id: "operation-1".to_string(),
         status: QueryTerminalStatus::Failed,
+        output: QueryOutput {
+            text: "partial response".to_string(),
+        },
         error: Some(QueryResultError {
             message: "Permission approval is required".to_string(),
             data: ErrorData {
@@ -93,6 +97,9 @@ fn query_events_and_terminal_errors_are_closed_protocol_values() {
                 stage: ErrorStage::Query,
                 retryable: false,
                 correlation_id: "query:query-1".to_string(),
+                operation_id: Some("operation-1".to_string()),
+                causation_id: None,
+                outcome_certainty: OutcomeCertainty::Committed,
                 recovery: None,
             },
         }),
@@ -100,6 +107,9 @@ fn query_events_and_terminal_errors_are_closed_protocol_values() {
     .unwrap();
     assert_eq!(result["error"]["data"]["code"], "action_required");
     assert_eq!(result["error"]["data"]["stage"], "query");
+    assert_eq!(result["operationId"], "operation-1");
+    assert_eq!(result["output"]["text"], "partial response");
+    assert_eq!(result["error"]["data"]["outcomeCertainty"], "committed");
     assert_eq!(
         result["error"]["message"],
         "Permission approval is required"
@@ -142,6 +152,9 @@ fn success_and_error_envelopes_are_strict_json_rpc() {
             stage: ErrorStage::Query,
             retryable: true,
             correlation_id: "request:2".to_string(),
+            operation_id: Some("operation-2".to_string()),
+            causation_id: None,
+            outcome_certainty: OutcomeCertainty::NotStarted,
             recovery: Some(RecoveryAction::Retry),
         },
     );
@@ -150,6 +163,7 @@ fn success_and_error_envelopes_are_strict_json_rpc() {
     assert_eq!(value["error"]["data"]["stage"], "query");
     assert_eq!(value["error"]["data"]["recovery"], "retry");
     assert_eq!(value["error"]["data"]["retryable"], true);
+    assert_eq!(value["error"]["data"]["outcomeCertainty"], "not_started");
 }
 
 #[test]
diff --git a/src/crates/services/miniapp-market-service/Cargo.toml b/src/crates/services/miniapp-market-service/Cargo.toml
index 4ea25d7d0a..c221641e79 100644
--- a/src/crates/services/miniapp-market-service/Cargo.toml
+++ b/src/crates/services/miniapp-market-service/Cargo.toml
@@ -17,19 +17,18 @@ chrono = { workspace = true }
 hex = { workspace = true }
 image = { workspace = true }
 rand = { workspace = true }
-reqwest = { workspace = true, features = ["rustls"] }
+reqwest = { workspace = true, features = ["form", "http2", "json", "rustls"] }
 serde = { workspace = true }
 serde_json = { workspace = true }
 semver = { workspace = true }
 sha2 = { workspace = true }
 similar = { workspace = true }
-sqlx = { version = "0.8", default-features = false, features = ["runtime-tokio", "sqlite"] }
+sqlx = { workspace = true, features = ["runtime-tokio", "sqlite"] }
 thiserror = { workspace = true }
 tokio = { workspace = true, features = ["fs", "rt", "sync", "time"] }
 tower-http = { version = "0.6.11", features = ["fs", "set-header", "trace"] }
 tracing = { workspace = true }
 url = { workspace = true }
-urlencoding = { workspace = true }
 uuid = { workspace = true }
 zip = { workspace = true }
 
diff --git a/src/crates/services/page-function-runtime/Cargo.toml b/src/crates/services/page-function-runtime/Cargo.toml
index 581a26dbc8..b7f9083f0b 100644
--- a/src/crates/services/page-function-runtime/Cargo.toml
+++ b/src/crates/services/page-function-runtime/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "bitfun-page-function-runtime"
-version = "0.2.17"
+version = "0.2.18"
 authors = ["BitFun Team"]
 edition = "2021"
 description = "Embedded JS Page Function runtime for BitFun Pages (rquickjs)"
diff --git a/src/crates/services/relay-service/Cargo.toml b/src/crates/services/relay-service/Cargo.toml
index b1777efb5f..5a0d96a8cd 100644
--- a/src/crates/services/relay-service/Cargo.toml
+++ b/src/crates/services/relay-service/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "bitfun-relay-service"
-version = "0.2.17"
+version = "0.2.18"
 authors = ["BitFun Team"]
 edition = "2021"
 description = "Reusable relay runtime for BitFun Remote Connect"
diff --git a/src/crates/services/relay-service/src/db.rs b/src/crates/services/relay-service/src/db.rs
index cb9f53dd0c..ab518700bf 100644
--- a/src/crates/services/relay-service/src/db.rs
+++ b/src/crates/services/relay-service/src/db.rs
@@ -38,6 +38,7 @@ CREATE TABLE IF NOT EXISTS devices (
   device_id    TEXT NOT NULL,
   user_id      TEXT NOT NULL REFERENCES users(user_id) ON DELETE CASCADE,
   device_name  TEXT,
+  device_kind  TEXT,
   public_key   TEXT,
   last_seen_at INTEGER,
   online       INTEGER NOT NULL DEFAULT 0,
@@ -141,6 +142,10 @@ const MIGRATE_AUTH_TOKEN_REQUEST_ID: &str = r#"
 ALTER TABLE auth_tokens ADD COLUMN request_id TEXT;
 "#;
 
+const MIGRATE_DEVICE_KIND: &str = r#"
+ALTER TABLE devices ADD COLUMN device_kind TEXT;
+"#;
+
 /// Open (or create) the SQLite database and ensure the schema exists.
 pub async fn connect(db_path: &str) -> Result<DbPool> {
     connect_with_presence_reset(db_path, true).await
@@ -216,6 +221,15 @@ async fn connect_with_presence_reset(db_path: &str, reset_presence: bool) -> Res
         }
     }
     migrate_account_scoped_devices(&pool).await?;
+    // Runs after the account-scoping migration because that path rebuilds
+    // `devices` from the legacy schema; adding the column last covers both the
+    // rebuilt table and databases that never needed rebuilding. A NULL kind
+    // means "registered before clients reported one" and is read as a desktop.
+    if let Err(error) = sqlx::query(MIGRATE_DEVICE_KIND).execute(&pool).await {
+        if !error.to_string().contains("duplicate column name") {
+            return Err(anyhow!("migrate device kinds: {error}"));
+        }
+    }
     sqlx::query(
         "CREATE UNIQUE INDEX IF NOT EXISTS idx_auth_tokens_request_id \
          ON auth_tokens(request_id) WHERE request_id IS NOT NULL",
@@ -615,11 +629,36 @@ fn lockout_until(attempts: i64, now: i64) -> i64 {
 
 // ── Devices ─────────────────────────────────────────────────────────────
 
+/// Only desktops can host a remote-control session, so the device list is
+/// filtered on this. Phones and watches still register — they need a device
+/// row to hold their auth token — they just aren't offered as control targets.
+pub const DEVICE_KIND_DESKTOP: &str = "desktop";
+pub const DEVICE_KIND_MOBILE: &str = "mobile";
+pub const DEVICE_KIND_WATCH: &str = "watch";
+
+pub const DEVICE_KINDS: [&str; 3] = [
+    DEVICE_KIND_DESKTOP,
+    DEVICE_KIND_MOBILE,
+    DEVICE_KIND_WATCH,
+];
+
+pub fn is_valid_device_kind(kind: &str) -> bool {
+    DEVICE_KINDS.contains(&kind)
+}
+
+/// A missing kind predates client-side reporting, and is read as a desktop:
+/// hiding a real desktop would break remote control outright, while a stale
+/// phone row corrects itself the next time that phone logs in.
+pub fn device_kind_is_desktop(kind: Option<&str>) -> bool {
+    matches!(kind, None | Some(DEVICE_KIND_DESKTOP))
+}
+
 #[derive(Debug, Clone, sqlx::FromRow)]
 pub struct DeviceRow {
     pub device_id: String,
     pub user_id: String,
     pub device_name: Option<String>,
+    pub device_kind: Option<String>,
     pub public_key: Option<String>,
     pub last_seen_at: Option<i64>,
     pub online: i64,
@@ -631,20 +670,27 @@ impl DeviceRow {
         device_id: &str,
         user_id: &str,
         device_name: &str,
+        device_kind: Option<&str>,
         public_key: Option<&str>,
     ) -> Result<()> {
         let now = Utc::now().timestamp();
+        // `device_kind` is only overwritten when the caller actually reported
+        // one. A client build that predates the field would otherwise erase a
+        // known kind on every login and put the device back in the list.
         sqlx::query(
-            "INSERT INTO devices (device_id, user_id, device_name, public_key, last_seen_at, online) \
-             VALUES (?, ?, ?, ?, ?, 0) \
+            "INSERT INTO devices \
+               (device_id, user_id, device_name, device_kind, public_key, last_seen_at, online) \
+             VALUES (?, ?, ?, ?, ?, ?, 0) \
              ON CONFLICT(user_id, device_id) DO UPDATE SET \
                device_name = excluded.device_name, \
+               device_kind = COALESCE(excluded.device_kind, devices.device_kind), \
                public_key = excluded.public_key, \
                last_seen_at = excluded.last_seen_at",
         )
         .bind(device_id)
         .bind(user_id)
         .bind(device_name)
+        .bind(device_kind)
         .bind(public_key)
         .bind(now)
         .execute(pool)
@@ -675,7 +721,7 @@ impl DeviceRow {
 
     pub async fn list_by_user(pool: &DbPool, user_id: &str) -> Result<Vec<DeviceRow>> {
         let rows = sqlx::query_as::<_, DeviceRow>(
-            "SELECT device_id, user_id, device_name, public_key, last_seen_at, online \
+            "SELECT device_id, user_id, device_name, device_kind, public_key, last_seen_at, online \
              FROM devices WHERE user_id = ?",
         )
         .bind(user_id)
@@ -756,6 +802,7 @@ impl AuthToken {
         user_id: &str,
         device_id: &str,
         device_name: &str,
+        device_kind: Option<&str>,
         request_id: &str,
     ) -> Result<Option<AuthToken>> {
         let mut tx = pool
@@ -801,12 +848,13 @@ impl AuthToken {
 
         let inserted = sqlx::query(
             "INSERT OR IGNORE INTO devices \
-             (device_id, user_id, device_name, public_key, last_seen_at, online) \
-             VALUES (?, ?, ?, NULL, ?, 0)",
+             (device_id, user_id, device_name, device_kind, public_key, last_seen_at, online) \
+             VALUES (?, ?, ?, ?, NULL, ?, 0)",
         )
         .bind(device_id)
         .bind(user_id)
         .bind(device_name)
+        .bind(device_kind)
         .bind(now)
         .execute(&mut *tx)
         .await
@@ -2361,7 +2409,7 @@ mod tests {
         UserRow::create(&runtime_pool, "u1", "alice", "s", "ks", "{}", "hash", "wmk")
             .await
             .unwrap();
-        DeviceRow::upsert(&runtime_pool, "d1", "u1", "Laptop", None)
+        DeviceRow::upsert(&runtime_pool, "d1", "u1", "Laptop", None, None)
             .await
             .unwrap();
         DeviceRow::set_online(&runtime_pool, "u1", "d1", true)
@@ -2418,7 +2466,7 @@ mod tests {
         UserRow::create(&pool, "u1", "alice", "s", "ks", "{}", "hash", "wmk")
             .await
             .unwrap();
-        DeviceRow::upsert(&pool, "d1", "u1", "Laptop", None)
+        DeviceRow::upsert(&pool, "d1", "u1", "Laptop", None, None)
             .await
             .unwrap();
         let tok = AuthToken::create(&pool, "u1", "d1").await.unwrap();
@@ -2452,10 +2500,10 @@ mod tests {
             .await
             .unwrap();
 
-        DeviceRow::upsert(&pool, "shared-install", "u1", "Alice laptop", None)
+        DeviceRow::upsert(&pool, "shared-install", "u1", "Alice laptop", None, None)
             .await
             .unwrap();
-        DeviceRow::upsert(&pool, "shared-install", "u2", "Bob laptop", None)
+        DeviceRow::upsert(&pool, "shared-install", "u2", "Bob laptop", None, None)
             .await
             .unwrap();
         let token_u1 = AuthToken::create(&pool, "u1", "shared-install")
@@ -2652,7 +2700,7 @@ mod tests {
             .await
             .unwrap()
             .is_none());
-        DeviceRow::upsert(&migrated, "shared-install", "u1", "Alice laptop", None)
+        DeviceRow::upsert(&migrated, "shared-install", "u1", "Alice laptop", None, None)
             .await
             .unwrap();
         assert_eq!(
@@ -2673,6 +2721,34 @@ mod tests {
         let _ = std::fs::remove_file(db_path);
     }
 
+    #[tokio::test]
+    async fn reopening_a_database_keeps_the_device_kind_column_and_its_values() {
+        let db_path = std::env::temp_dir().join(format!(
+            "bitfun-relay-device-kind-migration-{}-{}.db",
+            std::process::id(),
+            rand::random::<u64>()
+        ));
+        let db_path_text = db_path.to_string_lossy().to_string();
+
+        let first = connect(&db_path_text).await.unwrap();
+        UserRow::create(&first, "u1", "alice", "s", "ks", "{}", "hash", "wmk")
+            .await
+            .unwrap();
+        DeviceRow::upsert(&first, "phone", "u1", "Phone", Some(DEVICE_KIND_MOBILE), None)
+            .await
+            .unwrap();
+        first.close().await;
+
+        // The ALTER runs on every startup and must tolerate the column already
+        // being there, rather than failing the whole boot.
+        let second = connect(&db_path_text).await.unwrap();
+        let rows = DeviceRow::list_by_user(&second, "u1").await.unwrap();
+        assert_eq!(rows.len(), 1);
+        assert_eq!(rows[0].device_kind.as_deref(), Some(DEVICE_KIND_MOBILE));
+        second.close().await;
+        let _ = std::fs::remove_file(db_path);
+    }
+
     #[tokio::test]
     async fn legacy_pages_receive_nonempty_authorization_generations() {
         let db_path = std::env::temp_dir().join(format!(
diff --git a/src/crates/services/relay-service/src/routes/auth.rs b/src/crates/services/relay-service/src/routes/auth.rs
index ae47a51d0d..c7551b3a03 100644
--- a/src/crates/services/relay-service/src/routes/auth.rs
+++ b/src/crates/services/relay-service/src/routes/auth.rs
@@ -61,6 +61,12 @@ fn valid_login_request_id(value: &str) -> bool {
     uuid::Uuid::parse_str(value).is_ok()
 }
 
+/// Absent is legal — clients that predate the field still log in, and their
+/// stored kind is left untouched rather than overwritten with a guess.
+fn valid_optional_device_kind(value: Option<&str>) -> bool {
+    value.is_none_or(crate::db::is_valid_device_kind)
+}
+
 fn decoy_login_challenge(username: &str) -> LoginChallengeResponse {
     static SECRET: OnceLock<[u8; 32]> = OnceLock::new();
     let secret = SECRET.get_or_init(rand::random);
@@ -217,6 +223,10 @@ pub struct LoginRequest {
     pub password_hash: String,
     pub device_id: String,
     pub device_name: String,
+    /// `desktop` | `mobile` | `watch`. Absent from clients that predate the
+    /// field; see `device_kind_is_desktop` for how those rows are read.
+    #[serde(default)]
+    pub device_kind: Option<String>,
     #[serde(default)]
     pub request_id: Option<String>,
 }
@@ -225,6 +235,8 @@ pub struct LoginRequest {
 pub struct ProvisionDeviceRequest {
     pub device_id: String,
     pub device_name: String,
+    #[serde(default)]
+    pub device_kind: Option<String>,
     pub request_id: String,
 }
 
@@ -410,6 +422,7 @@ pub async fn login(
 ) -> Result<Json<AuthResponse>, (StatusCode, Json<ErrorResponse>)> {
     if !valid_device_id(&body.device_id)
         || !valid_bounded_text(&body.device_name, MAX_DEVICE_NAME_BYTES)
+        || !valid_optional_device_kind(body.device_kind.as_deref())
         || body
             .request_id
             .as_deref()
@@ -445,12 +458,19 @@ pub async fn login(
     )
     .await?;
 
-    DeviceRow::upsert(db, &body.device_id, &user.user_id, &body.device_name, None)
-        .await
-        .map_err(|e| {
-            tracing::error!("login: failed to upsert device: {e}");
-            err("internal error", StatusCode::INTERNAL_SERVER_ERROR)
-        })?;
+    DeviceRow::upsert(
+        db,
+        &body.device_id,
+        &user.user_id,
+        &body.device_name,
+        body.device_kind.as_deref(),
+        None,
+    )
+    .await
+    .map_err(|e| {
+        tracing::error!("login: failed to upsert device: {e}");
+        err("internal error", StatusCode::INTERNAL_SERVER_ERROR)
+    })?;
 
     let token = match body.request_id.as_deref() {
         Some(request_id) => {
@@ -624,6 +644,7 @@ pub async fn provision_device(
             .bytes()
             .all(|byte| byte.is_ascii_digit() || matches!(byte, b'a'..=b'f'))
         || !valid_bounded_text(&body.device_name, MAX_DEVICE_NAME_BYTES)
+        || !valid_optional_device_kind(body.device_kind.as_deref())
         || !valid_login_request_id(&body.request_id)
     {
         return Err(err(
@@ -654,11 +675,18 @@ pub async fn provision_device(
         return Err(err("forbidden", StatusCode::FORBIDDEN));
     }
 
+    // This route only ever bootstraps a machine over SSH, so an unreported
+    // kind is a desktop rather than an unknown.
     let provisioned = AuthToken::provision_new_device(
         db,
         &auth.user_id,
         &body.device_id,
         body.device_name.trim(),
+        Some(
+            body.device_kind
+                .as_deref()
+                .unwrap_or(crate::db::DEVICE_KIND_DESKTOP),
+        ),
         &body.request_id,
     )
     .await
@@ -716,7 +744,7 @@ mod tests {
         UserRow::create(&db, "owner", "alice", "s", "ks", "{}", "hash", "wmk")
             .await
             .unwrap();
-        DeviceRow::upsert(&db, "owner-device", "owner", "Owner", None)
+        DeviceRow::upsert(&db, "owner-device", "owner", "Owner", None, None)
             .await
             .unwrap();
         let token = AuthToken::create(&db, "owner", "owner-device")
diff --git a/src/crates/services/relay-service/src/routes/devices.rs b/src/crates/services/relay-service/src/routes/devices.rs
index c92e427a4d..4d3e751155 100644
--- a/src/crates/services/relay-service/src/routes/devices.rs
+++ b/src/crates/services/relay-service/src/routes/devices.rs
@@ -8,7 +8,7 @@
 //! workspaces/sessions and dispatch tasks, without requiring a direct WS
 //! connection or proxying through another desktop.
 
-use axum::extract::{Path, State};
+use axum::extract::{DefaultBodyLimit, Path, State};
 use axum::http::{header, HeaderMap, StatusCode};
 use axum::routing::{delete, get, post};
 use axum::{Json, Router};
@@ -28,6 +28,15 @@ const MAX_DEVICE_ID_BYTES: usize = 128;
 const MAX_ENCRYPTED_PAYLOAD_BYTES: usize = 48 * 1024 * 1024;
 const MAX_NONCE_BYTES: usize = 256;
 
+/// Body ceiling for `/api/devices/:id/rpc`.
+///
+/// Without this the route inherits Axum's 2 MB default, which rejects the body
+/// before `is_valid_encrypted_payload` ever runs — so a mobile client sending a
+/// photo got a bare 413 while the payload validator above claimed to allow
+/// 48 MB. Derived from that constant so the two cannot drift apart again; the
+/// slack covers the JSON envelope and the base64 nonce.
+const RPC_BODY_LIMIT_BYTES: usize = MAX_ENCRYPTED_PAYLOAD_BYTES + 64 * 1024;
+
 fn is_valid_device_id(value: &str) -> bool {
     !value.is_empty()
         && value.len() <= MAX_DEVICE_ID_BYTES
@@ -67,7 +76,10 @@ async fn validate_user(state: &AppState, headers: &HeaderMap) -> Result<AuthToke
 pub fn device_router() -> Router<AppState> {
     Router::new()
         .route("/api/devices", get(list_devices))
-        .route("/api/devices/{target_device_id}/rpc", post(device_rpc))
+        .route(
+            "/api/devices/{target_device_id}/rpc",
+            post(device_rpc).layer(DefaultBodyLimit::max(RPC_BODY_LIMIT_BYTES)),
+        )
         .route("/api/devices/{target_device_id}", delete(delete_device))
 }
 
@@ -77,11 +89,15 @@ pub fn device_router() -> Router<AppState> {
 pub struct DeviceListEntry {
     pub device_id: String,
     pub device_name: String,
+    pub device_kind: Option<String>,
     pub online: bool,
     pub last_seen_at: Option<i64>,
 }
 
-/// `GET /api/devices` — list all devices for the account (online + offline).
+/// `GET /api/devices` — list the account's remote-control targets.
+///
+/// Phones and watches register device rows too (they need one to hold an auth
+/// token), but they cannot host a session, so they are never listed here.
 async fn list_devices(
     State(state): State<AppState>,
     headers: HeaderMap,
@@ -96,13 +112,19 @@ async fn list_devices(
 
     // Get all registered devices from the DB (online + offline)
     let mut devices = Vec::new();
+    let mut hidden_ids: std::collections::HashSet<String> = std::collections::HashSet::new();
     if let Some(db) = &state.db {
         if let Ok(db_devices) = crate::db::DeviceRow::list_by_user(db, &user_id).await {
             for row in db_devices {
+                if !crate::db::device_kind_is_desktop(row.device_kind.as_deref()) {
+                    hidden_ids.insert(row.device_id);
+                    continue;
+                }
                 let is_online = online_ids.contains(&row.device_id);
                 devices.push(DeviceListEntry {
                     device_id: row.device_id,
                     device_name: row.device_name.unwrap_or_default(),
+                    device_kind: row.device_kind,
                     online: is_online,
                     last_seen_at: row.last_seen_at,
                 });
@@ -110,12 +132,18 @@ async fn list_devices(
         }
     }
 
-    // Also include any online-only devices not yet in the DB
+    // Also include any online-only devices not yet in the DB. The in-memory
+    // registry does not carry a kind, so these are treated like a NULL row —
+    // except for ids the DB just told us to hide, which must stay hidden.
     for (id, name) in &online {
+        if hidden_ids.contains(id) {
+            continue;
+        }
         if !devices.iter().any(|d| &d.device_id == id) {
             devices.push(DeviceListEntry {
                 device_id: id.clone(),
                 device_name: name.clone(),
+                device_kind: None,
                 online: true,
                 last_seen_at: None,
             });
@@ -315,13 +343,13 @@ mod tests {
         UserRow::create(&db, "other", "bob", "s", "ks", "{}", "hash", "wmk")
             .await
             .unwrap();
-        DeviceRow::upsert(&db, "owner-device", "owner", "Owner", None)
+        DeviceRow::upsert(&db, "owner-device", "owner", "Owner", None, None)
             .await
             .unwrap();
-        DeviceRow::upsert(&db, "target-device", "owner", "Target", None)
+        DeviceRow::upsert(&db, "target-device", "owner", "Target", None, None)
             .await
             .unwrap();
-        DeviceRow::upsert(&db, "other-device", "other", "Other", None)
+        DeviceRow::upsert(&db, "other-device", "other", "Other", None, None)
             .await
             .unwrap();
 
@@ -389,6 +417,119 @@ mod tests {
             .status()
     }
 
+    async fn listed_device_ids(app: &axum::Router, token: &str) -> Vec<String> {
+        let response = app
+            .clone()
+            .oneshot(
+                Request::builder()
+                    .method("GET")
+                    .uri("/api/devices")
+                    .header(header::AUTHORIZATION, format!("Bearer {token}"))
+                    .body(Body::empty())
+                    .unwrap(),
+            )
+            .await
+            .unwrap();
+        assert_eq!(response.status(), StatusCode::OK);
+        let body = axum::body::to_bytes(response.into_body(), usize::MAX)
+            .await
+            .unwrap();
+        let entries: Vec<serde_json::Value> = serde_json::from_slice(&body).unwrap();
+        entries
+            .into_iter()
+            .map(|entry| entry["device_id"].as_str().unwrap().to_string())
+            .collect()
+    }
+
+    async fn rpc(
+        app: &axum::Router,
+        token: &str,
+        device_id: &str,
+        payload_bytes: usize,
+    ) -> StatusCode {
+        let body = serde_json::json!({
+            "encrypted_data": "A".repeat(payload_bytes),
+            "nonce": "AAAA",
+        })
+        .to_string();
+        app.clone()
+            .oneshot(
+                Request::builder()
+                    .method("POST")
+                    .uri(format!("/api/devices/{device_id}/rpc"))
+                    .header(header::AUTHORIZATION, format!("Bearer {token}"))
+                    .header(header::CONTENT_TYPE, "application/json")
+                    .body(Body::from(body))
+                    .unwrap(),
+            )
+            .await
+            .unwrap()
+            .status()
+    }
+
+    #[tokio::test]
+    async fn device_list_hides_mobile_devices_and_keeps_unlabeled_rows() {
+        let ctx = setup_app().await;
+        DeviceRow::upsert(&ctx.db, "phone", "owner", "HarmonyOS Phone", Some("mobile"), None)
+            .await
+            .unwrap();
+        DeviceRow::upsert(&ctx.db, "mac", "owner", "MacBook", Some("desktop"), None)
+            .await
+            .unwrap();
+
+        let ids = listed_device_ids(&ctx.app, &ctx.owner_token).await;
+
+        assert!(!ids.contains(&"phone".to_string()));
+        assert!(ids.contains(&"mac".to_string()));
+        // owner-device and target-device were registered before the kind
+        // existed; a NULL kind must still be offered as a control target.
+        assert!(ids.contains(&"owner-device".to_string()));
+        assert!(ids.contains(&"target-device".to_string()));
+    }
+
+    #[tokio::test]
+    async fn a_login_without_a_kind_does_not_erase_a_known_one() {
+        let ctx = setup_app().await;
+        DeviceRow::upsert(&ctx.db, "phone", "owner", "HarmonyOS Phone", Some("mobile"), None)
+            .await
+            .unwrap();
+
+        // An older client build logs in again and reports no kind.
+        DeviceRow::upsert(&ctx.db, "phone", "owner", "HarmonyOS Phone", None, None)
+            .await
+            .unwrap();
+
+        let ids = listed_device_ids(&ctx.app, &ctx.owner_token).await;
+        assert!(!ids.contains(&"phone".to_string()));
+    }
+
+    #[tokio::test]
+    async fn device_rpc_accepts_payloads_above_the_default_body_limit() {
+        let ctx = setup_app().await;
+
+        // A phone sending a photo lands here: base64 of the image, encrypted and
+        // base64ed again, clears Axum's 2 MB default by itself. NOT_FOUND means
+        // the body was read and the offline target was the only complaint.
+        let status = rpc(&ctx.app, &ctx.owner_token, "target-device", 3 * 1024 * 1024).await;
+
+        assert_eq!(status, StatusCode::NOT_FOUND);
+    }
+
+    #[tokio::test]
+    async fn device_rpc_still_rejects_payloads_past_the_route_limit() {
+        let ctx = setup_app().await;
+
+        let status = rpc(
+            &ctx.app,
+            &ctx.owner_token,
+            "target-device",
+            RPC_BODY_LIMIT_BYTES + 1,
+        )
+        .await;
+
+        assert_eq!(status, StatusCode::PAYLOAD_TOO_LARGE);
+    }
+
     #[tokio::test]
     async fn deleting_owned_device_revokes_token_before_device_row() {
         let ctx = setup_app().await;
diff --git a/src/crates/services/relay-service/src/routes/pages.rs b/src/crates/services/relay-service/src/routes/pages.rs
index 7f3f35121a..60d1214f90 100644
--- a/src/crates/services/relay-service/src/routes/pages.rs
+++ b/src/crates/services/relay-service/src/routes/pages.rs
@@ -3093,10 +3093,10 @@ mod tests {
         UserRow::create(&pool, "u2", "bob", "s", "ks", "{}", "hash", "wmk")
             .await
             .unwrap();
-        DeviceRow::upsert(&pool, "d1", "u1", "Laptop", None)
+        DeviceRow::upsert(&pool, "d1", "u1", "Laptop", None, None)
             .await
             .unwrap();
-        DeviceRow::upsert(&pool, "d2", "u2", "Phone", None)
+        DeviceRow::upsert(&pool, "d2", "u2", "Phone", None, None)
             .await
             .unwrap();
         let tok_alice = AuthToken::create(&pool, "u1", "d1").await.unwrap();
diff --git a/src/crates/services/relay-service/src/routes/websocket.rs b/src/crates/services/relay-service/src/routes/websocket.rs
index a1a5fa1181..3a848c0d0d 100644
--- a/src/crates/services/relay-service/src/routes/websocket.rs
+++ b/src/crates/services/relay-service/src/routes/websocket.rs
@@ -88,6 +88,10 @@ pub enum InboundMessage {
     AuthConnect {
         token: String,
         device_name: String,
+        /// `desktop` | `mobile` | `watch`. Absent from clients that predate
+        /// the field, which leaves the stored kind untouched.
+        #[serde(default)]
+        device_kind: Option<String>,
     },
     /// Route an encrypted payload to another device in the same account.
     DeviceMessage {
@@ -540,7 +544,11 @@ async fn handle_text_message(
             }
         }
 
-        InboundMessage::AuthConnect { token, device_name } => {
+        InboundMessage::AuthConnect {
+            token,
+            device_name,
+            device_kind,
+        } => {
             if state.room_manager.has_connection(conn_id)
                 || state.device_manager.has_connection(conn_id)
             {
@@ -548,6 +556,9 @@ async fn handle_text_message(
             }
             if !crate::db::is_valid_auth_token(&token)
                 || !is_valid_display_text(&device_name, MAX_DEVICE_NAME_BYTES)
+                || device_kind
+                    .as_deref()
+                    .is_some_and(|kind| !crate::db::is_valid_device_kind(kind))
             {
                 return reject_protocol(out_tx, "invalid authentication parameters");
             }
@@ -598,6 +609,7 @@ async fn handle_text_message(
                 &auth.user_id,
                 &auth.device_id,
                 &device_name,
+                device_kind.as_deref(),
                 conn_id,
             )
             .await
@@ -853,6 +865,7 @@ async fn activate_pending_device_if_authorized(
     expected_user_id: &str,
     expected_device_id: &str,
     device_name: &str,
+    device_kind: Option<&str>,
     conn_id: ConnId,
 ) -> anyhow::Result<bool> {
     // Serialize the final token lookup, durable device update, activation, and
@@ -872,9 +885,15 @@ async fn activate_pending_device_if_authorized(
         return Ok(false);
     }
 
-    if let Err(error) =
-        crate::db::DeviceRow::upsert(db, expected_device_id, expected_user_id, device_name, None)
-            .await
+    if let Err(error) = crate::db::DeviceRow::upsert(
+        db,
+        expected_device_id,
+        expected_user_id,
+        device_name,
+        device_kind,
+        None,
+    )
+    .await
     {
         device_manager.disconnect_pending(conn_id);
         return Err(error);
@@ -1006,7 +1025,7 @@ mod tests {
         UserRow::create(&db, "owner", "alice", "s", "ks", "{}", "hash", "wmk")
             .await
             .unwrap();
-        DeviceRow::upsert(&db, "device-a", "owner", "Device A", None)
+        DeviceRow::upsert(&db, "device-a", "owner", "Device A", None, None)
             .await
             .unwrap();
         let token = AuthToken::create(&db, "owner", "device-a")
@@ -1037,7 +1056,7 @@ mod tests {
                 .unwrap()
         );
         assert!(!activate_pending_device_if_authorized(
-            &db, &manager, &token, "owner", "device-a", "Device A", 1,
+            &db, &manager, &token, "owner", "device-a", "Device A", None, 1,
         )
         .await
         .unwrap());
@@ -1052,7 +1071,7 @@ mod tests {
         UserRow::create(&db, "owner", "alice", "s", "ks", "{}", "hash", "wmk")
             .await
             .unwrap();
-        DeviceRow::upsert(&db, "device-a", "owner", "Device A", None)
+        DeviceRow::upsert(&db, "device-a", "owner", "Device A", None, None)
             .await
             .unwrap();
         DeviceRow::set_online(&db, "owner", "device-a", true)
@@ -1105,7 +1124,7 @@ mod tests {
             .await
             .unwrap();
         assert!(!activate_pending_device_if_authorized(
-            &db, &manager, &token, "owner", "device-a", "Device A", 2,
+            &db, &manager, &token, "owner", "device-a", "Device A", None, 2,
         )
         .await
         .unwrap());
@@ -1137,10 +1156,10 @@ mod tests {
         UserRow::create(&db, "owner", "alice", "s", "ks", "{}", "hash", "wmk")
             .await
             .unwrap();
-        DeviceRow::upsert(&db, "device-a", "owner", "Device A", None)
+        DeviceRow::upsert(&db, "device-a", "owner", "Device A", None, None)
             .await
             .unwrap();
-        DeviceRow::upsert(&db, "device-c", "owner", "Device C", None)
+        DeviceRow::upsert(&db, "device-c", "owner", "Device C", None, None)
             .await
             .unwrap();
         DeviceRow::set_online(&db, "owner", "device-a", true)
@@ -1230,7 +1249,7 @@ mod tests {
         UserRow::create(&db, "owner", "alice", "s", "ks", "{}", "hash", "wmk")
             .await
             .unwrap();
-        DeviceRow::upsert(&db, "device-a", "owner", "Device A", None)
+        DeviceRow::upsert(&db, "device-a", "owner", "Device A", None, None)
             .await
             .unwrap();
         let token = AuthToken::create(&db, "owner", "device-a")
@@ -1248,7 +1267,7 @@ mod tests {
                 .await
                 .unwrap()
         );
-        DeviceRow::upsert(&db, "device-a", "owner", "Device A", None)
+        DeviceRow::upsert(&db, "device-a", "owner", "Device A", None, None)
             .await
             .unwrap();
         DeviceRow::set_online(&db, "owner", "device-a", true)
@@ -1281,7 +1300,7 @@ mod tests {
         UserRow::create(&db, "owner", "alice", "s", "ks", "{}", "hash", "wmk")
             .await
             .unwrap();
-        DeviceRow::upsert(&db, "device-a", "owner", "Device A", None)
+        DeviceRow::upsert(&db, "device-a", "owner", "Device A", None, None)
             .await
             .unwrap();
         let token = AuthToken::create(&db, "owner", "device-a")
@@ -1299,7 +1318,7 @@ mod tests {
         manager.register_pending("owner", "device-a", &token, "Device A", 1, tx, close_tx);
 
         assert!(!activate_pending_device_if_authorized(
-            &db, &manager, &token, "owner", "device-a", "Device A", 1,
+            &db, &manager, &token, "owner", "device-a", "Device A", None, 1,
         )
         .await
         .unwrap());
@@ -1317,7 +1336,7 @@ mod tests {
         UserRow::create(&db, "owner", "alice", "s", "ks", "{}", "hash", "wmk")
             .await
             .unwrap();
-        DeviceRow::upsert(&db, "device-a", "owner", "Device A", None)
+        DeviceRow::upsert(&db, "device-a", "owner", "Device A", None, None)
             .await
             .unwrap();
         let token = AuthToken::create(&db, "owner", "device-a")
@@ -1332,7 +1351,7 @@ mod tests {
         assert!(manager.online_devices("owner").is_empty());
         assert!(!manager.route_message("owner", "device-a", "opaque"));
         assert!(activate_pending_device_if_authorized(
-            &db, &manager, &token, "owner", "device-a", "Device A", 1,
+            &db, &manager, &token, "owner", "device-a", "Device A", None, 1,
         )
         .await
         .unwrap());
diff --git a/src/crates/services/services-core/AGENTS.md b/src/crates/services/services-core/AGENTS.md
index ae34edff61..84fa3107a6 100644
--- a/src/crates/services/services-core/AGENTS.md
+++ b/src/crates/services/services-core/AGENTS.md
@@ -18,17 +18,19 @@ crate.
 - Prefer `bitfun-core-types` for shared DTOs and `bitfun-runtime-ports` for
   cross-layer traits.
 - Keep dependency features explicit and keep `default = []`. The coarse service
-  capability owners are `filesystem` (local file operations/search),
+  capability owners are `diagnostics` (diagnostic-log redaction), `diff`
+  (local text diff calculation), `filesystem` (local file operations/search),
   `json-io` (generic locked and atomic JSON file IO), `local-storage`
   (JSON/session/usage persistence), `process-runtime` (command
   lookup and supervised child lifecycle), and `workspace-instructions`
   (declarative instruction discovery). Consumers enable those or the narrower
   `lsp`, `workspace-runtime`, `workspace-identity`, `runtime-ownership`,
-  `permission`, `dispatch-workspace`, `markdown`, and `session-git` extensions
+  `permission`, `dispatch-workspace`, `markdown`, `session-git`, and
+  `workspace-text-runtime` extensions
   only for behavior they use. In particular, session metadata consumers must
   not compile libgit2 unless they use the memory-workspace baseline/diff API.
   Keep Tokio and platform API capabilities owner-scoped too: the empty profile
-  carries only Tokio runtime/time support, `lsp` and `workspace-runtime`
+  carries no Tokio dependency, `lsp` and `workspace-runtime`
   explicitly compose `process-runtime`, and Windows storage/process bindings
   must not be enabled from one shared dependency feature union.
 - LSP manifest and protocol DTOs belong in `bitfun-core-types`; reusable LSP
@@ -69,6 +71,9 @@ target. Representative stable entry points are:
 ```bash
 cargo check -p bitfun-services-core --no-default-features
 cargo check -p bitfun-services-core --no-default-features --features filesystem
+cargo test -p bitfun-services-core --no-default-features --features diagnostics --lib diagnostics::contract_tests::
+cargo test -p bitfun-services-core --no-default-features --features diff --lib diff::contract_tests::
+cargo test -p bitfun-services-core --no-default-features --features workspace-text-runtime --lib workspace_text::tests::
 cargo test -p bitfun-services-core --no-default-features --features local-storage --test session_contracts session_metadata_contracts::
 cargo test -p bitfun-services-core --no-default-features --features local-storage --test session_write_lock_contracts
 cargo test -p bitfun-services-core --no-default-features --features process-runtime --test process_runtime_contracts
diff --git a/src/crates/services/services-core/Cargo.toml b/src/crates/services/services-core/Cargo.toml
index 253487755a..657c87eaa1 100644
--- a/src/crates/services/services-core/Cargo.toml
+++ b/src/crates/services/services-core/Cargo.toml
@@ -16,7 +16,7 @@ async-trait = { workspace = true, optional = true }
 bitfun-core-types = { path = "../../contracts/core-types", optional = true }
 bitfun-events = { path = "../../contracts/events", optional = true }
 bitfun-runtime-ports = { path = "../../contracts/runtime-ports", optional = true }
-tokio = { workspace = true, features = ["rt", "time"] }
+tokio = { workspace = true, optional = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
 serde_yaml = { workspace = true, optional = true }
@@ -33,8 +33,8 @@ ignore = { workspace = true, optional = true }
 globset = { workspace = true, optional = true }
 sha2 = { workspace = true, optional = true }
 which = { workspace = true, optional = true }
-similar = { workspace = true }
-regex = { workspace = true }
+similar = { workspace = true, optional = true }
+regex = { workspace = true, optional = true }
 rusqlite = { version = "0.32", features = ["bundled"], optional = true }
 
 [target.'cfg(windows)'.dependencies]
@@ -50,12 +50,26 @@ libc = { workspace = true, optional = true }
 
 [features]
 default = []
-filesystem = ["dep:base64", "dep:chrono", "dep:ignore", "dep:sha2", "tokio/fs"]
+diagnostics = ["dep:regex"]
+diff = ["dep:similar", "dep:tokio", "tokio/rt", "tokio/time"]
+filesystem = [
+    "dep:base64",
+    "dep:chrono",
+    "dep:ignore",
+    "dep:regex",
+    "dep:sha2",
+    "dep:tokio",
+    "tokio/fs",
+    "tokio/rt",
+]
 json-io = [
     "dep:fs2",
+    "dep:tokio",
     "dep:windows",
     "tokio/fs",
+    "tokio/rt",
     "tokio/sync",
+    "tokio/time",
     "windows/Win32_Foundation",
     "windows/Win32_Storage_FileSystem",
 ]
@@ -65,25 +79,41 @@ local-storage = [
     "dep:chrono",
     "dep:fs2",
     "dep:libc",
+    "dep:regex",
     "dep:sha2",
+    "dep:similar",
+    "dep:tokio",
     "dep:windows",
     "tokio/fs",
+    "tokio/rt",
     "tokio/sync",
+    "tokio/time",
     "windows/Win32_Foundation",
     "windows/Win32_Storage_FileSystem",
 ]
 process-runtime = [
     "dep:libc",
+    "dep:tokio",
     "dep:which",
     "dep:win32job",
     "dep:windows",
     "tokio/io-util",
     "tokio/process",
+    "tokio/rt",
+    "tokio/time",
     "windows/Win32_Foundation",
     "windows/Win32_System_Diagnostics_ToolHelp",
     "windows/Win32_System_Threading",
 ]
-workspace-instructions = ["dep:globset", "dep:serde_yaml", "tokio/fs", "tokio/io-util"]
+workspace-instructions = [
+    "dep:globset",
+    "dep:regex",
+    "dep:serde_yaml",
+    "dep:tokio",
+    "tokio/fs",
+    "tokio/io-util",
+    "tokio/rt",
+]
 lsp = [
     "dep:anyhow",
     "dep:bitfun-core-types",
@@ -94,11 +124,13 @@ lsp = [
     "tokio/io-util",
     "tokio/sync",
 ]
-markdown = ["dep:serde_yaml"]
+markdown = ["dep:regex", "dep:serde_yaml"]
 workspace-runtime = [
     "dep:anyhow",
     "dep:async-trait",
     "dep:bitfun-runtime-ports",
+    "bitfun-runtime-ports/runtime-event-port",
+    "bitfun-runtime-ports/workspace-ports",
     "dep:dunce",
     "process-runtime",
     "tokio/fs",
@@ -107,14 +139,22 @@ workspace-runtime = [
 ]
 workspace-identity = ["dep:dunce", "dep:sha2"]
 runtime-ownership = ["dep:dunce", "dep:fs2", "dep:sha2"]
-permission = ["dep:async-trait", "dep:bitfun-runtime-ports", "dep:rusqlite", "bitfun-runtime-ports/permission"]
+permission = [
+    "dep:async-trait",
+    "dep:bitfun-runtime-ports",
+    "dep:rusqlite",
+    "dep:tokio",
+    "bitfun-runtime-ports/permission",
+    "tokio/rt",
+]
 dispatch-workspace = ["dep:anyhow", "dep:sha2"]
 session-git = ["local-storage", "dep:git2"]
+workspace-text-runtime = ["dep:tokio", "tokio/rt"]
 
 [dev-dependencies]
 filetime = { workspace = true }
 tempfile = { workspace = true }
-tokio = { workspace = true, features = ["macros"] }
+tokio = { workspace = true, features = ["macros", "time"] }
 
 [[test]]
 name = "markdown_owner_contracts"
diff --git a/src/crates/services/services-core/src/diagnostics/mod.rs b/src/crates/services/services-core/src/diagnostics/mod.rs
index 38479bbde4..9bf14f6965 100644
--- a/src/crates/services/services-core/src/diagnostics/mod.rs
+++ b/src/crates/services/services-core/src/diagnostics/mod.rs
@@ -3,3 +3,73 @@ pub mod redaction;
 pub use redaction::{
     redact_diagnostic_log_text, redact_diagnostic_log_text_with_report, RedactedDiagnosticLog,
 };
+
+#[cfg(test)]
+mod contract_tests {
+    use super::{redact_diagnostic_log_text, redact_diagnostic_log_text_with_report};
+
+    #[test]
+    fn redacts_model_payloads_without_removing_routing_metadata() {
+        let input = r#"[2026-05-13T10:38:21.837][DEBUG][ai::openai] Request body:
+{
+  "model": "kimi-k2.6",
+  "api_key": "sk-secret-token",
+  "messages": [
+    {"role": "user", "content": "please review C:\\Users\\limit\\private\\file.rs"}
+  ],
+  "tools": [{"name": "Read"}],
+  "tool_call": {"name": "Read", "arguments": "{\"path\":\"C:\\Users\\limit\\private\\file.rs\"}"}
+}
+Authorization: Bearer live-provider-token
+"#;
+
+        let report = redact_diagnostic_log_text_with_report(input);
+
+        assert!(report.redaction_count >= 4);
+        assert!(report.text.contains("[ai::openai]"));
+        assert!(report.text.contains("\"model\": \"kimi-k2.6\""));
+        assert!(report.text.contains("\"role\": \"user\""));
+        assert!(report.text.contains("\"name\": \"Read\""));
+        assert!(!report.text.contains("sk-secret-token"));
+        assert!(!report.text.contains("live-provider-token"));
+        assert!(!report.text.contains("please review"));
+        assert!(!report.text.contains("C:\\Users\\limit"));
+        assert!(report.text.contains("<redacted"));
+    }
+
+    #[test]
+    fn redacts_anthropic_stream_payloads_but_keeps_event_shape() {
+        let input = r#"[TRACE][ai::anthropic_stream_response] Anthropic SSE: Event { event: "content_block_delta", data: "{\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"input_json_delta\",\"partial_json\":\"-US secret argument\"}}", id: "", retry: None }
+[TRACE][ai::anthropic_stream_response] Anthropic unified response: UnifiedResponse { text: Some("private answer"), reasoning_content: Some("hidden reasoning"), thinking_signature: "<omitted>", tool_call: Some(UnifiedToolCall { tool_call_index: Some(0), id: Some("toolu_1"), name: Some("Read"), arguments: Some("{\"path\":\"D:\\workspace\\secret\\main.rs\"}"), arguments_is_snapshot: false }), usage: None, finish_reason: None, provider_metadata: "<omitted>" }
+"#;
+
+        let redacted = redact_diagnostic_log_text(input);
+
+        assert!(redacted.contains("Anthropic SSE"));
+        assert!(redacted.contains("event: \"content_block_delta\""));
+        assert!(redacted.contains("tool_call_index: Some(0)"));
+        assert!(redacted.contains("name: Some(\"Read\")"));
+        assert!(!redacted.contains("-US secret argument"));
+        assert!(!redacted.contains("private answer"));
+        assert!(!redacted.contains("hidden reasoning"));
+        assert!(!redacted.contains("D:\\workspace\\secret"));
+    }
+
+    #[test]
+    fn handles_large_log_text_without_dropping_lines() {
+        let mut input = String::new();
+        for index in 0..2_000 {
+            input.push_str(&format!(
+                "[TRACE][webview] event={index} payload={{\"prompt\":\"secret prompt {index}\",\"path\":\"C:\\\\Users\\\\limit\\\\secret-{index}.txt\"}}\n"
+            ));
+        }
+
+        let report = redact_diagnostic_log_text_with_report(&input);
+
+        assert_eq!(report.text.lines().count(), 2_000);
+        assert!(report.redaction_count >= 4_000);
+        assert!(report.text.contains("[TRACE][webview] event=1999"));
+        assert!(!report.text.contains("secret prompt"));
+        assert!(!report.text.contains("C:\\\\Users\\\\limit"));
+    }
+}
diff --git a/src/crates/services/services-core/src/diff/mod.rs b/src/crates/services/services-core/src/diff/mod.rs
index bcd7109fa2..d3f50f1ed6 100644
--- a/src/crates/services/services-core/src/diff/mod.rs
+++ b/src/crates/services/services-core/src/diff/mod.rs
@@ -7,3 +7,24 @@ pub mod types;
 
 pub use service::DiffService;
 pub use types::*;
+
+#[cfg(test)]
+mod contract_tests {
+    use super::{DiffConfig, DiffLineType, DiffService};
+
+    #[test]
+    fn diff_service_preserves_line_count_contract() {
+        let service = DiffService::new(DiffConfig::new());
+        let result = service.compute_diff("one\ntwo\n", "one\nthree\n");
+
+        assert_eq!(result.additions, 1);
+        assert_eq!(result.deletions, 1);
+        assert_eq!(result.changes, 2);
+        assert_eq!(result.hunks.len(), 1);
+        assert!(result
+            .hunks
+            .iter()
+            .flat_map(|hunk| hunk.lines.iter())
+            .any(|line| line.line_type == DiffLineType::Add && line.content == "three"));
+    }
+}
diff --git a/src/crates/services/services-core/src/lib.rs b/src/crates/services/services-core/src/lib.rs
index 953824f7e8..e744185412 100644
--- a/src/crates/services/services-core/src/lib.rs
+++ b/src/crates/services/services-core/src/lib.rs
@@ -4,7 +4,9 @@
 //! tested without compiling the full BitFun product runtime.
 
 pub mod bounded_fs;
+#[cfg(feature = "diagnostics")]
 pub mod diagnostics;
+#[cfg(feature = "diff")]
 pub mod diff;
 pub mod dispatch_contract;
 #[cfg(feature = "dispatch-workspace")]
diff --git a/src/crates/services/services-core/src/session/mod.rs b/src/crates/services/services-core/src/session/mod.rs
index 31b0445036..7c6fbbf95f 100644
--- a/src/crates/services/services-core/src/session/mod.rs
+++ b/src/crates/services/services-core/src/session/mod.rs
@@ -9,7 +9,7 @@ pub mod page;
 pub mod types;
 mod write_lock;
 
-pub use bitfun_core_types::SessionKind;
+pub use bitfun_core_types::{SessionKind, SESSION_PROVIDER_ACP, SESSION_PROVIDER_METADATA_KEY};
 pub use layout::SessionStorageLayout;
 pub use lineage::{
     apply_session_lineage, build_branched_session_metadata, build_session_lineage_snapshot,
diff --git a/src/crates/services/services-core/src/session/types.rs b/src/crates/services/services-core/src/session/types.rs
index 7da2e98399..a910cef439 100644
--- a/src/crates/services/services-core/src/session/types.rs
+++ b/src/crates/services/services-core/src/session/types.rs
@@ -532,6 +532,20 @@ pub struct DialogTurnData {
     )]
     pub error_detail: Option<AiErrorDetail>,
 
+    /// Additive recovery lifecycle for an intentionally interrupted user turn.
+    ///
+    /// `TurnStatus` remains backward-compatible (`cancelled` while interrupted)
+    /// so older builds can still load the turn and simply treat it as terminal.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub recovery: Option<DialogTurnRecoveryData>,
+
+    /// Monotonic tombstone proving that the Runtime has owned persistence for
+    /// this turn. It remains after recovery settles so a delayed whole-turn UI
+    /// projection from an older execution generation cannot overwrite the
+    /// authoritative terminal payload.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub recovery_epoch: Option<u32>,
+
     /// Turn status
     pub status: TurnStatus,
 }
@@ -999,6 +1013,29 @@ fn default_transcript_line_range() -> TranscriptLineRange {
     }
 }
 
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum DialogTurnRecoveryStatus {
+    Interrupted,
+    Recovering,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct DialogTurnRecoveryData {
+    pub status: DialogTurnRecoveryStatus,
+    /// Generation zero is the original execution; each recovery increments it.
+    pub execution_generation: u32,
+    #[serde(default)]
+    pub resume_count: u32,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub interrupted_at: Option<u64>,
+    /// Model binding captured at interruption. Recovery rejects a model switch
+    /// instead of silently continuing one turn under a different model.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub model_id: Option<String>,
+}
+
 /// Turn status
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
 #[serde(rename_all = "lowercase")]
@@ -1162,6 +1199,8 @@ impl DialogTurnData {
             has_final_response: None,
             error: None,
             error_detail: None,
+            recovery: None,
+            recovery_epoch: None,
             status: TurnStatus::InProgress,
         }
     }
@@ -1190,9 +1229,10 @@ impl DialogTurnData {
 #[cfg(test)]
 mod tests {
     use super::{
-        DialogTurnData, DialogTurnKind, ModelRoundData, SessionMemoryMode, SessionMetadata,
-        SessionRelationship, SessionRelationshipKind, SessionTurnWindowResponse, TextItemData,
-        ThinkingItemData, ToolItemData, UserMessageData,
+        DialogTurnData, DialogTurnKind, DialogTurnRecoveryData, DialogTurnRecoveryStatus,
+        ModelRoundData, SessionMemoryMode, SessionMetadata, SessionRelationship,
+        SessionRelationshipKind, SessionTurnWindowResponse, TextItemData, ThinkingItemData,
+        ToolItemData, UserMessageData,
     };
     use bitfun_core_types::{SessionContinuationPolicy, SessionKind};
 
@@ -1217,6 +1257,41 @@ mod tests {
             serde_json::from_value(payload).expect("legacy payload should deserialize");
 
         assert_eq!(turn.kind, DialogTurnKind::UserDialog);
+        assert!(turn.recovery.is_none());
+    }
+
+    #[test]
+    fn interrupted_turn_recovery_metadata_is_additive_and_generation_scoped() {
+        let mut turn = DialogTurnData::new(
+            "turn-1".to_string(),
+            0,
+            "session-1".to_string(),
+            UserMessageData {
+                id: "user-1".to_string(),
+                content: "hello".to_string(),
+                timestamp: 1,
+                metadata: None,
+            },
+        );
+        turn.recovery = Some(DialogTurnRecoveryData {
+            status: DialogTurnRecoveryStatus::Interrupted,
+            execution_generation: 2,
+            resume_count: 2,
+            interrupted_at: Some(42),
+            model_id: Some("model-a".to_string()),
+        });
+
+        let serialized = serde_json::to_value(&turn).expect("serialize interrupted turn");
+        assert_eq!(serialized["status"], "inprogress");
+        assert_eq!(serialized["recovery"]["status"], "interrupted");
+        assert_eq!(serialized["recovery"]["executionGeneration"], 2);
+        assert_eq!(serialized["recovery"]["resumeCount"], 2);
+        assert_eq!(serialized["recovery"]["interruptedAt"], 42);
+        assert_eq!(serialized["recovery"]["modelId"], "model-a");
+
+        let restored: DialogTurnData =
+            serde_json::from_value(serialized).expect("restore interrupted turn");
+        assert_eq!(restored.recovery, turn.recovery);
     }
 
     #[test]
diff --git a/src/crates/services/services-core/src/workspace_text.rs b/src/crates/services/services-core/src/workspace_text.rs
index fcb8bf4660..b7637ddb3d 100644
--- a/src/crates/services/services-core/src/workspace_text.rs
+++ b/src/crates/services/services-core/src/workspace_text.rs
@@ -1,6 +1,8 @@
 //! Safe bounded reads for explicitly referenced local workspace text files.
 
+#[cfg(feature = "workspace-text-runtime")]
 use crate::bounded_fs::{is_symlink_or_reparse, read_bounded_text, BoundedTextRead};
+#[cfg(feature = "workspace-text-runtime")]
 use std::path::{Path, PathBuf};
 use thiserror::Error;
 
@@ -45,6 +47,7 @@ pub enum WorkspaceTextReadError {
     Io(String),
 }
 
+#[cfg(feature = "workspace-text-runtime")]
 pub async fn read_workspace_relative_text_bounded(
     workspace_root: &Path,
     relative_path: &str,
@@ -83,6 +86,7 @@ pub async fn read_workspace_relative_text_bounded(
 /// Every path component is checked with `symlink_metadata`, so callers cannot
 /// turn a structured workspace reference into a symlink or reparse-point
 /// escape after it was selected by the UI.
+#[cfg(feature = "workspace-text-runtime")]
 pub async fn resolve_workspace_relative_entry(
     workspace_root: &Path,
     relative_path: &str,
@@ -134,6 +138,7 @@ pub fn normalize_workspace_relative_path(value: &str) -> Result<String, Workspac
     Ok(components.join("/"))
 }
 
+#[cfg(feature = "workspace-text-runtime")]
 fn resolve_workspace_file(
     workspace_root: &Path,
     components: &[String],
@@ -145,6 +150,7 @@ fn resolve_workspace_file(
     Ok(path)
 }
 
+#[cfg(feature = "workspace-text-runtime")]
 fn resolve_workspace_entry(
     workspace_root: &Path,
     components: &[String],
@@ -207,6 +213,7 @@ fn resolve_workspace_entry(
     Ok((canonical_entry, kind))
 }
 
+#[cfg(feature = "workspace-text-runtime")]
 fn map_read_error(error: std::io::Error) -> WorkspaceTextReadError {
     if error.kind() == std::io::ErrorKind::NotFound {
         WorkspaceTextReadError::NotFound
@@ -215,7 +222,7 @@ fn map_read_error(error: std::io::Error) -> WorkspaceTextReadError {
     }
 }
 
-#[cfg(test)]
+#[cfg(all(test, feature = "workspace-text-runtime"))]
 mod tests {
     use super::{
         read_workspace_relative_text_bounded, resolve_workspace_relative_entry, WorkspaceEntryKind,
@@ -378,3 +385,43 @@ mod tests {
         std::os::windows::fs::symlink_file(target, link).is_ok()
     }
 }
+
+#[cfg(test)]
+mod path_contract_tests {
+    use super::{
+        normalize_workspace_relative_path, WorkspaceEntry, WorkspaceEntryKind, WorkspaceTextFile,
+        WorkspaceTextReadError,
+    };
+
+    #[test]
+    fn normalizes_only_safe_workspace_relative_paths_without_async_runtime() {
+        assert_eq!(
+            normalize_workspace_relative_path(r"src\.\lib.rs").unwrap(),
+            "src/lib.rs"
+        );
+        assert_eq!(
+            WorkspaceEntry {
+                relative_path: "src".to_string(),
+                kind: WorkspaceEntryKind::Directory,
+            }
+            .kind,
+            WorkspaceEntryKind::Directory
+        );
+        assert_eq!(
+            WorkspaceTextFile {
+                relative_path: "src/lib.rs".to_string(),
+                content: "fn main() {}".to_string(),
+                byte_len: 12,
+            }
+            .byte_len,
+            12
+        );
+        for invalid in ["", ".", "../secret.md", "/etc/passwd", r"C:\secret.md"] {
+            assert_eq!(
+                normalize_workspace_relative_path(invalid),
+                Err(WorkspaceTextReadError::InvalidRelativePath),
+                "{invalid:?}"
+            );
+        }
+    }
+}
diff --git a/src/crates/services/services-core/tests/service_contracts.rs b/src/crates/services/services-core/tests/service_contracts.rs
index a105a86652..002f9a9c2d 100644
--- a/src/crates/services/services-core/tests/service_contracts.rs
+++ b/src/crates/services/services-core/tests/service_contracts.rs
@@ -1,6 +1,2 @@
-#[path = "service_contracts/diagnostic_log_redaction.rs"]
-mod diagnostic_log_redaction;
 #[path = "service_contracts/jsonc_contracts.rs"]
 mod jsonc_contracts;
-#[path = "service_contracts/service_contracts.rs"]
-mod service_contracts;
diff --git a/src/crates/services/services-core/tests/service_contracts/diagnostic_log_redaction.rs b/src/crates/services/services-core/tests/service_contracts/diagnostic_log_redaction.rs
deleted file mode 100644
index e911e917f6..0000000000
--- a/src/crates/services/services-core/tests/service_contracts/diagnostic_log_redaction.rs
+++ /dev/null
@@ -1,68 +0,0 @@
-use bitfun_services_core::diagnostics::{
-    redact_diagnostic_log_text, redact_diagnostic_log_text_with_report,
-};
-
-#[test]
-fn redacts_model_payloads_without_removing_routing_metadata() {
-    let input = r#"[2026-05-13T10:38:21.837][DEBUG][ai::openai] Request body:
-{
-  "model": "kimi-k2.6",
-  "api_key": "sk-secret-token",
-  "messages": [
-    {"role": "user", "content": "please review C:\\Users\\limit\\private\\file.rs"}
-  ],
-  "tools": [{"name": "Read"}],
-  "tool_call": {"name": "Read", "arguments": "{\"path\":\"C:\\Users\\limit\\private\\file.rs\"}"}
-}
-Authorization: Bearer live-provider-token
-"#;
-
-    let report = redact_diagnostic_log_text_with_report(input);
-
-    assert!(report.redaction_count >= 4);
-    assert!(report.text.contains("[ai::openai]"));
-    assert!(report.text.contains("\"model\": \"kimi-k2.6\""));
-    assert!(report.text.contains("\"role\": \"user\""));
-    assert!(report.text.contains("\"name\": \"Read\""));
-    assert!(!report.text.contains("sk-secret-token"));
-    assert!(!report.text.contains("live-provider-token"));
-    assert!(!report.text.contains("please review"));
-    assert!(!report.text.contains("C:\\Users\\limit"));
-    assert!(report.text.contains("<redacted"));
-}
-
-#[test]
-fn redacts_anthropic_stream_payloads_but_keeps_event_shape() {
-    let input = r#"[TRACE][ai::anthropic_stream_response] Anthropic SSE: Event { event: "content_block_delta", data: "{\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"input_json_delta\",\"partial_json\":\"-US secret argument\"}}", id: "", retry: None }
-[TRACE][ai::anthropic_stream_response] Anthropic unified response: UnifiedResponse { text: Some("private answer"), reasoning_content: Some("hidden reasoning"), thinking_signature: "<omitted>", tool_call: Some(UnifiedToolCall { tool_call_index: Some(0), id: Some("toolu_1"), name: Some("Read"), arguments: Some("{\"path\":\"D:\\workspace\\secret\\main.rs\"}"), arguments_is_snapshot: false }), usage: None, finish_reason: None, provider_metadata: "<omitted>" }
-"#;
-
-    let redacted = redact_diagnostic_log_text(input);
-
-    assert!(redacted.contains("Anthropic SSE"));
-    assert!(redacted.contains("event: \"content_block_delta\""));
-    assert!(redacted.contains("tool_call_index: Some(0)"));
-    assert!(redacted.contains("name: Some(\"Read\")"));
-    assert!(!redacted.contains("-US secret argument"));
-    assert!(!redacted.contains("private answer"));
-    assert!(!redacted.contains("hidden reasoning"));
-    assert!(!redacted.contains("D:\\workspace\\secret"));
-}
-
-#[test]
-fn handles_large_log_text_without_dropping_lines() {
-    let mut input = String::new();
-    for index in 0..2_000 {
-        input.push_str(&format!(
-            "[TRACE][webview] event={index} payload={{\"prompt\":\"secret prompt {index}\",\"path\":\"C:\\\\Users\\\\limit\\\\secret-{index}.txt\"}}\n"
-        ));
-    }
-
-    let report = redact_diagnostic_log_text_with_report(&input);
-
-    assert_eq!(report.text.lines().count(), 2_000);
-    assert!(report.redaction_count >= 4_000);
-    assert!(report.text.contains("[TRACE][webview] event=1999"));
-    assert!(!report.text.contains("secret prompt"));
-    assert!(!report.text.contains("C:\\\\Users\\\\limit"));
-}
diff --git a/src/crates/services/services-core/tests/service_contracts/service_contracts.rs b/src/crates/services/services-core/tests/service_contracts/service_contracts.rs
deleted file mode 100644
index 26d293f8b6..0000000000
--- a/src/crates/services/services-core/tests/service_contracts/service_contracts.rs
+++ /dev/null
@@ -1,17 +0,0 @@
-use bitfun_services_core::diff::{DiffConfig, DiffLineType, DiffService};
-
-#[test]
-fn diff_service_preserves_line_count_contract() {
-    let service = DiffService::new(DiffConfig::new());
-    let result = service.compute_diff("one\ntwo\n", "one\nthree\n");
-
-    assert_eq!(result.additions, 1);
-    assert_eq!(result.deletions, 1);
-    assert_eq!(result.changes, 2);
-    assert_eq!(result.hunks.len(), 1);
-    assert!(result
-        .hunks
-        .iter()
-        .flat_map(|hunk| hunk.lines.iter())
-        .any(|line| line.line_type == DiffLineType::Add && line.content == "three"));
-}
diff --git a/src/crates/services/services-integrations/AGENTS.md b/src/crates/services/services-integrations/AGENTS.md
index 3e68955033..666ae721f2 100644
--- a/src/crates/services/services-integrations/AGENTS.md
+++ b/src/crates/services/services-integrations/AGENTS.md
@@ -91,8 +91,11 @@ slices that are outside pure product logic but still platform-neutral.
   new session/process group are outside the managed boundary.
 - Announcement remote fetch/cache lives here; product assembly supplies config
   values such as endpoint, locale, version, platform, and cache path.
-- DeepResearch report IO here may own report/citation sidecar filesystem work;
-  provider-neutral citation numbering stays in `bitfun-agent-runtime`.
+- DeepResearch report IO here owns report/citation sidecar filesystem work;
+  provider-neutral citation numbering stays in `bitfun-agent-runtime`. The IO
+  path must use the injected `WorkspaceFileSystem` for both local and remote
+  workspaces; never probe or fall back to the host filesystem for a remote
+  workspace path.
 
 ## Verification
 
@@ -107,6 +110,7 @@ cargo check -p bitfun-services-integrations --no-default-features
 cargo test -p bitfun-services-integrations --no-default-features --features mcp --test mcp_contracts
 cargo test -p bitfun-services-integrations --no-default-features --features remote-ssh --test remote_ssh_contracts remote_ssh_disabled_contracts::
 cargo test -p bitfun-services-integrations --no-default-features --features file-watch --test file_watch_contracts
+cargo test --locked -p bitfun-services-integrations --no-default-features --features deep-research --lib deep_research::tests::
 pnpm run check:core-boundaries
 ```
 
diff --git a/src/crates/services/services-integrations/Cargo.toml b/src/crates/services/services-integrations/Cargo.toml
index f4f50c233e..57a4b7f463 100644
--- a/src/crates/services/services-integrations/Cargo.toml
+++ b/src/crates/services/services-integrations/Cargo.toml
@@ -20,7 +20,7 @@ bitfun-agent-runtime = { path = "../../execution/agent-runtime", optional = true
 bitfun-agent-tools = { path = "../../execution/tool-contracts", optional = true }
 bitfun-events = { path = "../../contracts/events" }
 bitfun-core-types = { path = "../../contracts/core-types", optional = true }
-bitfun-product-domains = { path = "../../contracts/product-domains", default-features = false, optional = true }
+bitfun-product-domains = { path = "../../contracts/product-domains", optional = true }
 bitfun-runtime-ports = { path = "../../contracts/runtime-ports", optional = true }
 aes-gcm = { workspace = true, optional = true }
 aes = { workspace = true, optional = true }
@@ -28,7 +28,7 @@ anyhow = { workspace = true, optional = true }
 argon2 = { workspace = true, optional = true }
 async-trait = { workspace = true, optional = true }
 base64 = { workspace = true, optional = true }
-bitfun-services-core = { path = "../services-core", default-features = false, optional = true }
+bitfun-services-core = { path = "../services-core", optional = true }
 bzip2 = { workspace = true, optional = true }
 chrono = { workspace = true, optional = true }
 dunce = { workspace = true, optional = true }
@@ -47,9 +47,10 @@ mac_address = { workspace = true, optional = true }
 md5 = { workspace = true, optional = true }
 notify = { workspace = true, optional = true }
 oxc = { workspace = true, optional = true }
-qrcode = { workspace = true, optional = true }
+qrcode = { workspace = true, features = ["image", "svg"], optional = true }
 rand = { workspace = true, optional = true }
-reqwest = { workspace = true, optional = true }
+regex = { workspace = true, optional = true }
+reqwest = { workspace = true, features = ["http2"], optional = true }
 semver = { workspace = true, optional = true }
 rmcp = { workspace = true, optional = true }
 rustls = { workspace = true, optional = true }
@@ -105,7 +106,7 @@ tauri-support = ["dep:tauri"]
 # feature group (e.g. `git`) only derive `TS` when that group is also enabled;
 # app-server's `ts` feature enables `product-full` which pulls `git`.
 ts = ["dep:ts-rs"]
-announcement = ["reqwest", "reqwest/rustls", "tokio/fs", "tokio/sync"]
+announcement = ["reqwest", "reqwest/json", "reqwest/rustls", "tokio/fs", "tokio/sync"]
 models-dev = [
     "reqwest",
     "reqwest/rustls",
@@ -116,7 +117,7 @@ models-dev = [
     "tokio/time",
     "windows",
 ]
-browser-control = ["anyhow", "bitfun-services-core/process-runtime", "dirs", "reqwest", "reqwest/rustls", "thiserror", "tokio/time"]
+browser-control = ["anyhow", "bitfun-services-core/process-runtime", "dirs", "reqwest", "reqwest/json", "reqwest/rustls", "thiserror", "tokio/time"]
 canvas-runtime = [
     "dep:bitfun-product-domains",
     "oxc",
@@ -142,11 +143,17 @@ feedback = [
     "sha2",
     "uuid",
 ]
-debug-log = ["anyhow", "chrono", "reqwest", "reqwest/rustls", "tokio/rt", "uuid"]
-deep-research = ["bitfun-agent-runtime", "tokio/fs"]
+debug-log = ["anyhow", "chrono", "reqwest", "reqwest/json", "reqwest/rustls", "tokio/rt", "uuid"]
+deep-research = [
+    "anyhow",
+    "async-trait",
+    "dep:bitfun-agent-runtime",
+    "bitfun-agent-runtime/deep-research",
+    "bitfun-runtime-ports/workspace-ports",
+]
 git = [
     "async-trait",
-    "bitfun-runtime-ports",
+    "bitfun-runtime-ports/git-port",
     "bitfun-services-core/process-runtime",
     "chrono",
     "git2",
@@ -168,13 +175,15 @@ mcp = [
     "anyhow",
     "async-trait",
     "base64",
-    "bitfun-agent-tools",
+    "bitfun-agent-tools/mcp-bridge",
     "bitfun-services-core/process-runtime",
     "futures",
     "hex",
     "rand",
     "reqwest",
+    "reqwest/json",
     "reqwest/rustls",
+    "reqwest/stream",
     "rmcp",
     "rmcp/transport-streamable-http-client-reqwest",
     "sha2",
@@ -197,6 +206,7 @@ miniapp-runtime = [
     "dirs",
     "reqwest",
     "reqwest/rustls",
+    "reqwest/stream",
     "tokio/fs",
     "tokio/io-util",
     "tokio/net",
@@ -219,7 +229,10 @@ miniapp-market = [
     "image",
     "miniapp-runtime",
     "reqwest",
+    "reqwest/json",
+    "reqwest/query",
     "reqwest/rustls",
+    "reqwest/stream",
     "semver",
     "sha2",
     "thiserror",
@@ -243,7 +256,8 @@ plugin-source = [
     "windows",
 ]
 hook-import = [
-    "bitfun-agent-runtime",
+    "dep:bitfun-agent-runtime",
+    "bitfun-agent-runtime/native-hook-settings",
     "bitfun-product-domains/external-sources",
     "bitfun-services-core/local-storage",
     "dep:bitfun-product-domains",
@@ -261,11 +275,12 @@ remote-connect = [
     "argon2",
     "async-trait",
     "base64",
-    "bitfun-agent-tools",
+    "dep:bitfun-agent-tools",
     "dep:bitfun-core-types",
     "bitfun-services-core/local-storage",
     "bitfun-services-core/process-runtime",
-    "bitfun-runtime-ports",
+    "bitfun-runtime-ports/agent-api",
+    "bitfun-runtime-ports/remote-workspace-ports",
     "chrono",
     "dirs",
     "futures",
@@ -278,6 +293,9 @@ remote-connect = [
     "qrcode",
     "rand",
     "reqwest",
+    "reqwest/json",
+    "reqwest/multipart",
+    "reqwest/query",
     "reqwest/rustls",
     "rustls",
     "rustls-native-certs",
@@ -302,7 +320,10 @@ remote-ssh = [
     "bitfun-services-core/filesystem",
     "bitfun-services-core/process-runtime",
     "bitfun-services-core/workspace-identity",
-    "bitfun-runtime-ports",
+    "bitfun-runtime-ports/remote-exec-port",
+    "bitfun-runtime-ports/remote-workspace-ports",
+    "bitfun-runtime-ports/workspace-ports",
+    "regex",
     "sha2",
     "terminal-core",
     "thiserror",
@@ -322,13 +343,14 @@ remote-ssh-concrete = [
     "anyhow",
     "async-trait",
     "base64",
-    "bitfun-runtime-ports",
+    "dep:bitfun-runtime-ports",
     "chrono",
     "dirs",
     "minisign-verify",
     "rand",
     "reqwest",
     "reqwest/rustls",
+    "reqwest/stream",
     "russh",
     "russh-sftp",
     "russh-keys",
@@ -345,7 +367,10 @@ review-platform = [
     "chrono",
     "futures",
     "reqwest",
+    "reqwest/json",
+    "reqwest/query",
     "reqwest/rustls",
+    "reqwest/stream",
     "sha2",
     "thiserror",
     "tokio/fs",
@@ -363,6 +388,7 @@ speech = [
     "futures-util",
     "reqwest",
     "reqwest/rustls",
+    "reqwest/stream",
     "sha2",
     "sherpa-onnx",
     "tar",
@@ -390,7 +416,7 @@ workspace-search = [
 process-tree = ["bitfun-services-core/process-runtime"]
 script-tool-runtime = [
     "async-trait",
-    "bitfun-runtime-ports",
+    "bitfun-runtime-ports/script-tool-runtime",
     "process-tree",
     "tokio/io-util",
     "tokio/process",
@@ -399,7 +425,7 @@ script-tool-runtime = [
     "tokio/time",
     "which",
 ]
-web-tools = ["reqwest", "reqwest/rustls", "thiserror"]
+web-tools = ["reqwest", "reqwest/json", "reqwest/rustls", "thiserror"]
 product-full = [
     "announcement",
     "models-dev",
diff --git a/src/crates/services/services-integrations/src/browser_control/launcher.rs b/src/crates/services/services-integrations/src/browser_control/launcher.rs
index b639a76305..554865db1c 100644
--- a/src/crates/services/services-integrations/src/browser_control/launcher.rs
+++ b/src/crates/services/services-integrations/src/browser_control/launcher.rs
@@ -53,6 +53,16 @@ pub struct BrowserInfo {
     pub cdp_available: bool,
 }
 
+/// Browser-level CDP endpoint published by a Chromium browser's user-approved
+/// remote debugging flow. Unlike the legacy fixed-port endpoint, this points
+/// at the user's real browser profile and the WebSocket handshake requires an
+/// explicit approval in the browser.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct BrowserDebugEndpoint {
+    pub port: u16,
+    pub web_socket_url: String,
+}
+
 /// Cache for browser installation status to avoid repeated filesystem checks.
 /// The cache is valid for the lifetime of the process since browser installations
 /// don't change during a session.
@@ -64,6 +74,11 @@ pub struct BrowserLauncher;
 pub struct BrowserLaunchOptions {
     pub user_data_dir: Option<PathBuf>,
     pub managed_profile_root: Option<PathBuf>,
+    /// Wait for the user to enable guarded remote debugging in the browser's
+    /// settings page. Product surfaces should opt into this only for an
+    /// explicit setup action; ordinary agent connects should return guidance
+    /// quickly instead of holding a tool call open.
+    pub wait_for_user_profile_setup: bool,
 }
 
 impl BrowserLauncher {
@@ -325,6 +340,265 @@ impl BrowserLauncher {
             .join(Self::browser_profile_slug(kind))
     }
 
+    /// Return the browser's normal user-data directory. Browsers that expose
+    /// approval-based remote debugging write `DevToolsActivePort` here.
+    pub fn user_profile_data_dir(kind: &BrowserKind) -> Option<PathBuf> {
+        #[cfg(target_os = "macos")]
+        {
+            let home = dirs::home_dir()?;
+            let application_support = home.join("Library").join("Application Support");
+            let relative = match kind {
+                BrowserKind::Chrome => Path::new("Google/Chrome"),
+                BrowserKind::Edge => Path::new("Microsoft Edge"),
+                BrowserKind::Chromium => Path::new("Chromium"),
+                BrowserKind::Brave => Path::new("BraveSoftware/Brave-Browser"),
+                BrowserKind::Arc => Path::new("Arc/User Data"),
+                BrowserKind::Unknown(_) => return None,
+            };
+            return Some(application_support.join(relative));
+        }
+
+        #[cfg(target_os = "windows")]
+        {
+            let local_app_data = std::env::var_os("LOCALAPPDATA").map(PathBuf::from)?;
+            let relative = match kind {
+                BrowserKind::Chrome => Path::new("Google/Chrome/User Data"),
+                BrowserKind::Edge => Path::new("Microsoft/Edge/User Data"),
+                BrowserKind::Chromium => Path::new("Chromium/User Data"),
+                BrowserKind::Brave => Path::new("BraveSoftware/Brave-Browser/User Data"),
+                BrowserKind::Arc => Path::new("Arc/User Data"),
+                BrowserKind::Unknown(_) => return None,
+            };
+            return Some(local_app_data.join(relative));
+        }
+
+        #[cfg(target_os = "linux")]
+        {
+            let config_root = std::env::var_os("CHROME_CONFIG_HOME")
+                .or_else(|| std::env::var_os("XDG_CONFIG_HOME"))
+                .map(PathBuf::from)
+                .or_else(|| dirs::home_dir().map(|home| home.join(".config")))?;
+            let relative = match kind {
+                BrowserKind::Chrome => Path::new("google-chrome"),
+                BrowserKind::Edge => Path::new("microsoft-edge"),
+                BrowserKind::Chromium => Path::new("chromium"),
+                BrowserKind::Brave => Path::new("BraveSoftware/Brave-Browser"),
+                BrowserKind::Arc => Path::new("arc"),
+                BrowserKind::Unknown(_) => return None,
+            };
+            return Some(config_root.join(relative));
+        }
+    }
+
+    fn parse_devtools_active_port(contents: &str) -> Result<BrowserDebugEndpoint> {
+        let mut lines = contents
+            .lines()
+            .map(str::trim)
+            .filter(|line| !line.is_empty());
+        let raw_port = lines
+            .next()
+            .ok_or_else(|| anyhow!("DevToolsActivePort is missing its port"))?;
+        let web_socket_path = lines
+            .next()
+            .ok_or_else(|| anyhow!("DevToolsActivePort is missing its WebSocket path"))?;
+        let port = raw_port
+            .parse::<u16>()
+            .map_err(|_| anyhow!("DevToolsActivePort contains an invalid port"))?;
+        if port == 0 {
+            return Err(anyhow!("DevToolsActivePort contains port zero"));
+        }
+        if !web_socket_path.starts_with("/devtools/browser/")
+            || web_socket_path.chars().any(char::is_whitespace)
+        {
+            return Err(anyhow!(
+                "DevToolsActivePort contains an invalid browser WebSocket path"
+            ));
+        }
+
+        Ok(BrowserDebugEndpoint {
+            port,
+            web_socket_url: format!("ws://127.0.0.1:{port}{web_socket_path}"),
+        })
+    }
+
+    /// Discover a browser-level endpoint for the real user profile. This works
+    /// for every supported Chromium browser that publishes `DevToolsActivePort`
+    /// in its normal user-data directory. Malformed or stale files are treated
+    /// as unavailable; the subsequent WebSocket connection is the source of truth.
+    pub fn user_profile_debug_endpoint(kind: &BrowserKind) -> Option<BrowserDebugEndpoint> {
+        let path = Self::user_profile_data_dir(kind)?.join("DevToolsActivePort");
+        let contents = std::fs::read_to_string(&path).ok()?;
+        match Self::parse_devtools_active_port(&contents) {
+            Ok(endpoint) => {
+                let address = std::net::SocketAddr::from(([127, 0, 0, 1], endpoint.port));
+                if std::net::TcpStream::connect_timeout(&address, Duration::from_millis(150))
+                    .is_ok()
+                {
+                    Some(endpoint)
+                } else {
+                    debug!(
+                        "Ignoring stale browser DevToolsActivePort file at {}",
+                        path.display()
+                    );
+                    None
+                }
+            }
+            Err(error) => {
+                debug!(
+                    "Ignoring invalid browser DevToolsActivePort file at {}: {}",
+                    path.display(),
+                    error
+                );
+                None
+            }
+        }
+    }
+
+    fn user_profile_debugging_setup_url(kind: &BrowserKind) -> Option<&'static str> {
+        match kind {
+            BrowserKind::Chrome => Some("chrome://inspect/#remote-debugging"),
+            BrowserKind::Edge => Some("edge://inspect/#remote-debugging"),
+            _ => None,
+        }
+    }
+
+    pub fn supports_default_cdp(kind: &BrowserKind) -> bool {
+        // Chrome 144+ and current Edge document an inspect-page toggle that
+        // starts approval-based remote debugging for the normal user profile.
+        matches!(kind, BrowserKind::Chrome | BrowserKind::Edge)
+    }
+
+    fn default_cdp_preference_enabled(contents: &str) -> bool {
+        serde_json::from_str::<serde_json::Value>(contents)
+            .ok()
+            .and_then(|value| {
+                value
+                    .pointer("/devtools/remote_debugging/user-enabled")
+                    .and_then(serde_json::Value::as_bool)
+            })
+            .unwrap_or(false)
+    }
+
+    /// Whether the browser's persistent, approval-based CDP preference is on.
+    /// The endpoint is also accepted as proof because the browser may create it
+    /// before its Local State update has been flushed to disk.
+    pub fn is_default_cdp_enabled(kind: &BrowserKind) -> bool {
+        if !Self::supports_default_cdp(kind) {
+            return false;
+        }
+        if Self::user_profile_debug_endpoint(kind).is_some() {
+            return true;
+        }
+        let Some(path) =
+            Self::user_profile_data_dir(kind).map(|directory| directory.join("Local State"))
+        else {
+            return false;
+        };
+        std::fs::read_to_string(path)
+            .ok()
+            .is_some_and(|contents| Self::default_cdp_preference_enabled(&contents))
+    }
+
+    /// Open the browser's Remote debugging settings page.
+    ///
+    /// Chromium drops `chrome://` URLs handed to it on the command line and
+    /// silently substitutes the New Tab Page, so spawning the executable with
+    /// the settings URL looks to the user like "the browser opened and nothing
+    /// happened". macOS can route the URL through the browser's own AppleScript
+    /// `open location` handler, which is not subject to that filter; other
+    /// platforms have no equivalent, so the caller must hand the URL to the
+    /// user instead. Returns whether the page was actually opened.
+    fn open_user_profile_debugging_setup(kind: &BrowserKind, setup_url: &str) -> bool {
+        #[cfg(target_os = "macos")]
+        {
+            let Some(app_name) = Self::launch_app_name(kind) else {
+                return false;
+            };
+            let script = format!(
+                "tell application \"{}\" to open location \"{}\"",
+                app_name.replace('"', "\\\""),
+                setup_url
+            );
+            match silent_command("osascript").args(["-e", &script]).output() {
+                Ok(output) if output.status.success() => true,
+                Ok(output) => {
+                    debug!(
+                        "Failed to open {} remote debugging settings: {}",
+                        kind,
+                        String::from_utf8_lossy(&output.stderr).trim()
+                    );
+                    false
+                }
+                Err(error) => {
+                    debug!(
+                        "Failed to run osascript for {} remote debugging settings: {}",
+                        kind, error
+                    );
+                    false
+                }
+            }
+        }
+
+        #[cfg(not(target_os = "macos"))]
+        {
+            let _ = setup_url;
+            // Start the browser when it is not up yet so the user has somewhere
+            // to paste the URL. Passing the URL itself would only reach the New
+            // Tab Page, which is what made this flow look broken.
+            if !Self::is_browser_running(kind) {
+                let exe = Self::browser_executable(kind);
+                if let Err(error) = silent_command(&exe).spawn() {
+                    debug!(
+                        "Failed to start {} for remote debugging setup: {}",
+                        kind, error
+                    );
+                }
+            }
+            false
+        }
+    }
+
+    async fn prepare_user_profile_connection(
+        kind: &BrowserKind,
+        wait_for_user_setup: bool,
+    ) -> Result<LaunchResult> {
+        if let Some(endpoint) = Self::user_profile_debug_endpoint(kind) {
+            return Ok(LaunchResult::UserProfileReady { endpoint });
+        }
+
+        let setup_url = Self::user_profile_debugging_setup_url(kind)
+            .ok_or_else(|| anyhow!("{} does not support guarded user-profile CDP", kind))?;
+        let opened = Self::open_user_profile_debugging_setup(kind, setup_url);
+
+        // An explicit Settings action waits up to one minute so the user can
+        // tick the browser-owned consent checkbox; an ordinary agent connect
+        // only waits for the normal-start fast path before returning guidance.
+        let attempts = if wait_for_user_setup { 240 } else { 8 };
+        for _ in 0..attempts {
+            tokio::time::sleep(Duration::from_millis(250)).await;
+            if let Some(endpoint) = Self::user_profile_debug_endpoint(kind) {
+                return Ok(LaunchResult::UserProfileReady { endpoint });
+            }
+        }
+
+        let instructions = if opened {
+            format!(
+                "{kind} opened its Remote debugging settings. Turn on \"Allow remote debugging for this browser instance\" there; the browser remembers this preference for normal future starts. Then connect again and approve BitFun's connection request. This guarded flow uses your current browser profile, including its existing tabs and login state."
+            )
+        } else {
+            format!(
+                "Open {setup_url} in {kind} and turn on \"Allow remote debugging for this browser instance\"; the browser remembers this preference for normal future starts. Then connect again and approve BitFun's connection request. This guarded flow uses your current browser profile, including its existing tabs and login state."
+            )
+        };
+
+        Ok(LaunchResult::UserProfileSetupRequired {
+            browser: kind.to_string(),
+            setup_url: setup_url.to_string(),
+            opened,
+            instructions,
+        })
+    }
+
     fn default_managed_profile_root() -> PathBuf {
         dirs::data_local_dir()
             .or_else(dirs::data_dir)
@@ -522,6 +796,22 @@ impl BrowserLauncher {
         port: u16,
         options: BrowserLaunchOptions,
     ) -> Result<LaunchResult> {
+        if options.user_data_dir.is_none() {
+            // Opportunistically reuse the real profile for any Chromium browser
+            // that already publishes a browser-level endpoint. Chrome and Edge
+            // additionally get a first-class setup flow when it is not enabled.
+            if let Some(endpoint) = Self::user_profile_debug_endpoint(kind) {
+                return Ok(LaunchResult::UserProfileReady { endpoint });
+            }
+            if Self::supports_default_cdp(kind) {
+                return Self::prepare_user_profile_connection(
+                    kind,
+                    options.wait_for_user_profile_setup,
+                )
+                .await;
+            }
+        }
+
         if Self::is_cdp_available(port).await {
             info!("CDP already available on port {} for {}", port, kind);
             return Ok(LaunchResult::AlreadyConnected);
@@ -739,55 +1029,6 @@ impl BrowserLauncher {
             false
         }
     }
-
-    /// Create a macOS `.app` wrapper that launches the browser with CDP enabled.
-    #[cfg(target_os = "macos")]
-    pub fn create_cdp_launcher_app(kind: &BrowserKind, port: u16) -> Result<String> {
-        let app_name = format!("{} Debug", kind);
-        let app_dir = format!("/Applications/{}.app", app_name);
-        let macos_dir = format!("{}/Contents/MacOS", app_dir);
-        let script_path = format!("{}/launch", macos_dir);
-        let exe = Self::browser_executable(kind);
-
-        std::fs::create_dir_all(&macos_dir)
-            .map_err(|e| anyhow!("Failed to create app bundle: {}", e))?;
-
-        let script = format!(
-            "#!/bin/bash\nexec \"{}\" --remote-debugging-port={} \"$@\"\n",
-            exe, port
-        );
-        std::fs::write(&script_path, &script)
-            .map_err(|e| anyhow!("Failed to write launcher script: {}", e))?;
-
-        #[cfg(unix)]
-        {
-            use std::os::unix::fs::PermissionsExt;
-            std::fs::set_permissions(&script_path, std::fs::Permissions::from_mode(0o755))
-                .map_err(|e| anyhow!("Failed to set executable permission: {}", e))?;
-        }
-
-        let plist = format!(
-            r#"<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-    <key>CFBundleName</key>
-    <string>{}</string>
-    <key>CFBundleExecutable</key>
-    <string>launch</string>
-    <key>CFBundleIdentifier</key>
-    <string>com.bitfun.browser-debug-launcher</string>
-</dict>
-</plist>"#,
-            app_name
-        );
-
-        std::fs::write(format!("{}/Contents/Info.plist", app_dir), &plist)
-            .map_err(|e| anyhow!("Failed to write Info.plist: {}", e))?;
-
-        info!("Created CDP launcher app at {}", app_dir);
-        Ok(app_dir)
-    }
 }
 
 /// Result of a browser launch attempt.
@@ -795,6 +1036,17 @@ impl BrowserLauncher {
 pub enum LaunchResult {
     AlreadyConnected,
     Launched,
+    UserProfileReady {
+        endpoint: BrowserDebugEndpoint,
+    },
+    UserProfileSetupRequired {
+        browser: String,
+        setup_url: String,
+        /// Whether the settings page could be opened for the user. Platforms
+        /// without a browser automation entry point can only show the URL.
+        opened: bool,
+        instructions: String,
+    },
     LaunchedButCdpNotReady {
         port: u16,
         message: String,
@@ -843,4 +1095,54 @@ mod tests {
         );
         assert_eq!(dir, root.join("browser-control").join("custom-browser"));
     }
+
+    #[test]
+    fn devtools_active_port_parser_accepts_guarded_browser_endpoint() {
+        let endpoint = BrowserLauncher::parse_devtools_active_port(
+            "62314\n/devtools/browser/598cf21d-ec63-45f3-abba-698f26a88807\n",
+        )
+        .expect("valid endpoint");
+
+        assert_eq!(endpoint.port, 62314);
+        assert_eq!(
+            endpoint.web_socket_url,
+            "ws://127.0.0.1:62314/devtools/browser/598cf21d-ec63-45f3-abba-698f26a88807"
+        );
+    }
+
+    #[test]
+    fn devtools_active_port_parser_rejects_non_browser_paths() {
+        let error = BrowserLauncher::parse_devtools_active_port(
+            "9222\nhttp://attacker.example/devtools/browser/token\n",
+        )
+        .expect_err("non-local path must be rejected");
+
+        assert!(error.to_string().contains("invalid browser WebSocket path"));
+    }
+
+    #[test]
+    fn guarded_real_profile_setup_is_available_for_chrome_and_edge() {
+        assert!(BrowserLauncher::supports_default_cdp(&BrowserKind::Chrome));
+        assert!(BrowserLauncher::supports_default_cdp(&BrowserKind::Edge));
+        assert_eq!(
+            BrowserLauncher::user_profile_debugging_setup_url(&BrowserKind::Chrome),
+            Some("chrome://inspect/#remote-debugging")
+        );
+        assert_eq!(
+            BrowserLauncher::user_profile_debugging_setup_url(&BrowserKind::Edge),
+            Some("edge://inspect/#remote-debugging")
+        );
+        assert!(!BrowserLauncher::supports_default_cdp(&BrowserKind::Brave));
+    }
+
+    #[test]
+    fn default_cdp_preference_reads_chromium_local_state_shape() {
+        assert!(BrowserLauncher::default_cdp_preference_enabled(
+            r#"{"devtools":{"remote_debugging":{"user-enabled":true}}}"#
+        ));
+        assert!(!BrowserLauncher::default_cdp_preference_enabled(
+            r#"{"devtools":{"remote_debugging":{"user-enabled":false}}}"#
+        ));
+        assert!(!BrowserLauncher::default_cdp_preference_enabled("{}"));
+    }
 }
diff --git a/src/crates/services/services-integrations/src/browser_control/mod.rs b/src/crates/services/services-integrations/src/browser_control/mod.rs
index 930adab1ad..e9df814b57 100644
--- a/src/crates/services/services-integrations/src/browser_control/mod.rs
+++ b/src/crates/services/services-integrations/src/browser_control/mod.rs
@@ -10,5 +10,6 @@ pub mod launcher;
 
 pub use cdp::{CdpEndpointProvider, CdpPageInfo, CdpVersionInfo};
 pub use launcher::{
-    BrowserKind, BrowserLaunchOptions, BrowserLauncher, LaunchResult, DEFAULT_CDP_PORT,
+    BrowserDebugEndpoint, BrowserKind, BrowserLaunchOptions, BrowserLauncher, LaunchResult,
+    DEFAULT_CDP_PORT,
 };
diff --git a/src/crates/services/services-integrations/src/deep_research.rs b/src/crates/services/services-integrations/src/deep_research.rs
index 85c5908e54..6a9fbb59a4 100644
--- a/src/crates/services/services-integrations/src/deep_research.rs
+++ b/src/crates/services/services-integrations/src/deep_research.rs
@@ -6,11 +6,11 @@
 use bitfun_agent_runtime::deep_research::{
     renumber_research_report, ResearchCitationDisplayMapEntry,
 };
+use bitfun_runtime_ports::WorkspaceFileSystem;
 use log::{debug, info, warn};
 use serde_json::json;
 use std::fmt;
-use std::path::{Path, PathBuf};
-use tokio::fs;
+use std::path::PathBuf;
 
 #[derive(Debug)]
 pub enum DeepResearchReportIoError {
@@ -63,42 +63,52 @@ pub struct RenumberStats {
 /// Operates on the per-session WORK_DIR at
 /// `<workspace>/.bitfun/sessions/<session_id>/research/`, where both the
 /// report and the audit files live.
-pub async fn run_for_session_workspace(workspace_root: &Path, session_id: &str) {
-    let work_dir = workspace_root
-        .join(".bitfun")
-        .join("sessions")
-        .join(session_id)
-        .join("research");
-    let report_path = work_dir.join("report.md");
-
-    if !report_path.exists() {
-        debug!(
-            "citation_renumber: {} not found, nothing to renumber",
-            report_path.display()
-        );
-        return;
+pub async fn run_for_session_workspace(
+    fs: &dyn WorkspaceFileSystem,
+    workspace_root: &str,
+    session_id: &str,
+) {
+    let work_dir = fs.join_path(
+        workspace_root,
+        &[".bitfun", "sessions", session_id, "research"],
+    );
+    let report_path = fs.join_path(&work_dir, &["report.md"]);
+
+    match fs.exists(&report_path).await {
+        Ok(false) => {
+            debug!(
+                "citation_renumber: {} not found, nothing to renumber",
+                report_path
+            );
+            return;
+        }
+        Err(error) => {
+            warn!(
+                "citation_renumber: skipped (best-effort failure): path={}, err=check report existence failed: {}",
+                report_path, error
+            );
+            return;
+        }
+        Ok(true) => {}
     }
 
-    match try_renumber_research_report(&report_path, &work_dir).await {
+    match try_renumber_research_report(fs, &report_path, &work_dir).await {
         Ok(stats) if stats.citations_renumbered == 0 => {
             debug!(
                 "citation_renumber: no cit_XXX references found in {}; skipping",
-                report_path.display()
+                report_path
             );
         }
         Ok(stats) => {
             info!(
                 "citation_renumber: renumbered {} citations in {} ({} rejected refs in body)",
-                stats.citations_renumbered,
-                report_path.display(),
-                stats.rejected_refs_in_body
+                stats.citations_renumbered, report_path, stats.rejected_refs_in_body
             );
         }
         Err(err) => {
             warn!(
                 "citation_renumber: skipped (best-effort failure): path={}, err={}",
-                report_path.display(),
-                err
+                report_path, err
             );
         }
     }
@@ -110,32 +120,43 @@ pub async fn run_for_session_workspace(workspace_root: &Path, session_id: &str)
 /// citation registry's `status=ACCEPTED|REJECTED` flags so REJECTED rows can
 /// be skipped during numbering.
 pub async fn try_renumber_research_report(
-    report_path: &Path,
-    work_dir: &Path,
+    fs: &dyn WorkspaceFileSystem,
+    report_path: &str,
+    work_dir: &str,
 ) -> DeepResearchReportIoResult<RenumberStats> {
-    if !report_path.exists() {
+    if !fs
+        .exists(report_path)
+        .await
+        .map_err(|error| DeepResearchReportIoError::ReadReport(workspace_io_error(error)))?
+    {
         return Ok(RenumberStats::default());
     }
 
-    let report = fs::read_to_string(report_path)
+    let report = fs
+        .read_file_text(report_path)
         .await
-        .map_err(DeepResearchReportIoError::ReadReport)?;
+        .map_err(|error| DeepResearchReportIoError::ReadReport(workspace_io_error(error)))?;
 
-    let registry_path = work_dir.join("citations.md");
-    let registry_content = if registry_path.exists() {
-        match fs::read_to_string(&registry_path).await {
+    let registry_path = fs.join_path(work_dir, &["citations.md"]);
+    let registry_content = match fs.exists(&registry_path).await {
+        Ok(true) => match fs.read_file_text(&registry_path).await {
             Ok(content) => Some(content),
-            Err(e) => {
+            Err(error) => {
                 warn!(
                     "citation_renumber: failed to read citations.md ({}): {}",
-                    registry_path.display(),
-                    e
+                    registry_path, error
                 );
                 None
             }
+        },
+        Ok(false) => None,
+        Err(error) => {
+            warn!(
+                "citation_renumber: failed to inspect citations.md ({}): {}",
+                registry_path, error
+            );
+            None
         }
-    } else {
-        None
     };
 
     let output = renumber_research_report(&report, registry_content.as_deref());
@@ -143,7 +164,7 @@ pub async fn try_renumber_research_report(
     if output.display_map.is_empty() {
         debug!(
             "citation_renumber: no eligible cit_XXX references in {}",
-            report_path.display()
+            report_path
         );
         return Ok(RenumberStats {
             citations_renumbered: output.stats.citations_renumbered,
@@ -151,9 +172,9 @@ pub async fn try_renumber_research_report(
         });
     }
 
-    fs::write(report_path, &output.report)
+    fs.write_file(report_path, output.report.as_bytes())
         .await
-        .map_err(DeepResearchReportIoError::WriteReport)?;
+        .map_err(|error| DeepResearchReportIoError::WriteReport(workspace_io_error(error)))?;
 
     if output.stats.rejected_index_rows_dropped > 0 {
         warn!(
@@ -162,7 +183,11 @@ pub async fn try_renumber_research_report(
         );
     }
 
-    let _ = write_display_map_sidecar(work_dir, report_path, &output.display_map).await;
+    if let Err(error) =
+        write_display_map_sidecar(fs, work_dir, report_path, &output.display_map).await
+    {
+        warn!("citation_renumber: {error}");
+    }
 
     Ok(RenumberStats {
         citations_renumbered: output.stats.citations_renumbered,
@@ -171,11 +196,12 @@ pub async fn try_renumber_research_report(
 }
 
 async fn write_display_map_sidecar(
-    parent: &Path,
-    report_path: &Path,
+    fs: &dyn WorkspaceFileSystem,
+    parent: &str,
+    report_path: &str,
     display_map: &[ResearchCitationDisplayMapEntry],
-) -> DeepResearchReportIoResult<PathBuf> {
-    let map_path = parent.join("display_map.json");
+) -> DeepResearchReportIoResult<String> {
+    let map_path = fs.join_path(parent, &["display_map.json"]);
     let entries = display_map
         .iter()
         .map(|entry| {
@@ -187,25 +213,197 @@ async fn write_display_map_sidecar(
         .collect::<Vec<_>>();
     let body = json!({
         "version": 1,
-        "report_path": report_path.to_string_lossy(),
+        "report_path": report_path,
         "citation_count": display_map.len(),
         "entries": entries,
     });
     let serialized = serde_json::to_string_pretty(&body)
         .map_err(DeepResearchReportIoError::SerializeDisplayMap)?;
-    fs::write(&map_path, serialized).await.map_err(|source| {
-        DeepResearchReportIoError::WriteDisplayMap {
-            path: map_path.clone(),
-            source,
-        }
-    })?;
+    fs.write_file(&map_path, serialized.as_bytes())
+        .await
+        .map_err(|source| DeepResearchReportIoError::WriteDisplayMap {
+            path: PathBuf::from(&map_path),
+            source: workspace_io_error(source),
+        })?;
     Ok(map_path)
 }
 
+fn workspace_io_error(error: anyhow::Error) -> std::io::Error {
+    match error.downcast::<std::io::Error>() {
+        Ok(error) => error,
+        Err(error) => std::io::Error::other(error),
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
+    use bitfun_runtime_ports::{WorkspaceDirEntry, WorkspaceFileSystem, WorkspacePathKind};
+    use std::collections::HashMap;
     use std::env;
+    use std::path::Path;
+    use std::path::PathBuf;
+    use std::sync::{Arc, Mutex};
+
+    struct HostWorkspaceFs;
+
+    #[async_trait::async_trait]
+    impl WorkspaceFileSystem for HostWorkspaceFs {
+        async fn read_file(&self, path: &str) -> anyhow::Result<Vec<u8>> {
+            Ok(std::fs::read(path)?)
+        }
+
+        async fn read_file_text(&self, path: &str) -> anyhow::Result<String> {
+            Ok(std::fs::read_to_string(path)?)
+        }
+
+        async fn write_file(&self, path: &str, contents: &[u8]) -> anyhow::Result<()> {
+            if let Some(parent) = Path::new(path).parent() {
+                std::fs::create_dir_all(parent)?;
+            }
+            Ok(std::fs::write(path, contents)?)
+        }
+
+        async fn exists(&self, path: &str) -> anyhow::Result<bool> {
+            Ok(Path::new(path).try_exists()?)
+        }
+
+        async fn is_file(&self, path: &str) -> anyhow::Result<bool> {
+            Ok(std::fs::metadata(path)
+                .map(|metadata| metadata.is_file())
+                .unwrap_or(false))
+        }
+
+        async fn is_dir(&self, path: &str) -> anyhow::Result<bool> {
+            Ok(std::fs::metadata(path)
+                .map(|metadata| metadata.is_dir())
+                .unwrap_or(false))
+        }
+
+        async fn read_dir(&self, path: &str) -> anyhow::Result<Vec<WorkspaceDirEntry>> {
+            let mut entries = Vec::new();
+            let read_dir = std::fs::read_dir(path)?;
+            for entry in read_dir {
+                let entry = entry?;
+                let metadata = entry.metadata()?;
+                entries.push(WorkspaceDirEntry {
+                    name: entry.file_name().to_string_lossy().to_string(),
+                    path: entry.path().to_string_lossy().to_string(),
+                    is_dir: metadata.is_dir(),
+                    is_symlink: metadata.file_type().is_symlink(),
+                });
+            }
+            Ok(entries)
+        }
+    }
+
+    #[derive(Clone, Default)]
+    struct RecordingWorkspaceFs {
+        files: Arc<Mutex<HashMap<String, Vec<u8>>>>,
+        operations: Arc<Mutex<Vec<String>>>,
+    }
+
+    impl RecordingWorkspaceFs {
+        fn insert(&self, path: &str, contents: impl Into<Vec<u8>>) {
+            self.files
+                .lock()
+                .unwrap()
+                .insert(path.to_string(), contents.into());
+        }
+
+        fn text(&self, path: &str) -> Option<String> {
+            self.files
+                .lock()
+                .unwrap()
+                .get(path)
+                .map(|contents| String::from_utf8(contents.clone()).unwrap())
+        }
+
+        fn observed_operations(&self) -> Vec<String> {
+            self.operations.lock().unwrap().clone()
+        }
+
+        fn record(&self, operation: &str, path: &str) {
+            self.operations
+                .lock()
+                .unwrap()
+                .push(format!("{operation}:{path}"));
+        }
+    }
+
+    #[async_trait::async_trait]
+    impl WorkspaceFileSystem for RecordingWorkspaceFs {
+        fn join_path(&self, root: &str, components: &[&str]) -> String {
+            let mut path = root.trim_end_matches('/').to_string();
+            if path.is_empty() && root.starts_with('/') {
+                path.push('/');
+            }
+            for component in components {
+                if !path.is_empty() && !path.ends_with('/') {
+                    path.push('/');
+                }
+                path.push_str(component.trim_matches('/'));
+            }
+            path
+        }
+
+        async fn read_file(&self, path: &str) -> anyhow::Result<Vec<u8>> {
+            self.record("read", path);
+            self.files
+                .lock()
+                .unwrap()
+                .get(path)
+                .cloned()
+                .ok_or_else(|| anyhow::anyhow!("missing test file: {path}"))
+        }
+
+        async fn read_file_text(&self, path: &str) -> anyhow::Result<String> {
+            Ok(String::from_utf8(self.read_file(path).await?)?)
+        }
+
+        async fn write_file(&self, path: &str, contents: &[u8]) -> anyhow::Result<()> {
+            self.record("write", path);
+            self.files
+                .lock()
+                .unwrap()
+                .insert(path.to_string(), contents.to_vec());
+            Ok(())
+        }
+
+        async fn exists(&self, path: &str) -> anyhow::Result<bool> {
+            self.record("exists", path);
+            Ok(self.files.lock().unwrap().contains_key(path))
+        }
+
+        async fn is_file(&self, path: &str) -> anyhow::Result<bool> {
+            self.exists(path).await
+        }
+
+        async fn is_dir(&self, _path: &str) -> anyhow::Result<bool> {
+            Ok(false)
+        }
+
+        async fn path_kind_no_follow(
+            &self,
+            path: &str,
+        ) -> anyhow::Result<Option<WorkspacePathKind>> {
+            Ok(self.exists(path).await?.then_some(WorkspacePathKind::File))
+        }
+
+        async fn read_dir(&self, _path: &str) -> anyhow::Result<Vec<WorkspaceDirEntry>> {
+            Ok(Vec::new())
+        }
+    }
+
+    #[test]
+    fn workspace_io_error_preserves_standard_io_kind() {
+        let error = workspace_io_error(anyhow::Error::new(std::io::Error::new(
+            std::io::ErrorKind::PermissionDenied,
+            "denied",
+        )));
+
+        assert_eq!(error.kind(), std::io::ErrorKind::PermissionDenied);
+    }
 
     /// Minimal tempdir helper to avoid pulling in the `tempfile` crate just
     /// for one test. Removes the dir on drop.
@@ -236,17 +434,15 @@ mod tests {
         let dir = ScratchDir::new("e2e");
         let work_dir = dir.path().join("research");
         let report_dir = dir.path().join("report-out");
-        fs::create_dir_all(&work_dir).await.unwrap();
-        fs::create_dir_all(&report_dir).await.unwrap();
+        std::fs::create_dir_all(&work_dir).unwrap();
+        std::fs::create_dir_all(&report_dir).unwrap();
 
         let citations = "\
 cit_001 | claim a | url=u1 | authority=high | status=ACCEPTED
 cit_002 | claim b | url=u2 | authority=low | status=REJECTED | reason=contradicted
 cit_005 | claim c | url=u3 | authority=medium
 ";
-        fs::write(work_dir.join("citations.md"), citations)
-            .await
-            .unwrap();
+        std::fs::write(work_dir.join("citations.md"), citations).unwrap();
 
         let report = "\
 # Deep Research Report
@@ -268,15 +464,19 @@ cit_005 | claim c | url=u3 | authority=medium
 | cit_005 | claim c | u3 |
 ";
         let report_path = report_dir.join("test-subject-2026-05-13.md");
-        fs::write(&report_path, report).await.unwrap();
+        std::fs::write(&report_path, report).unwrap();
 
-        let stats = try_renumber_research_report(&report_path, &work_dir)
-            .await
-            .unwrap();
+        let stats = try_renumber_research_report(
+            &HostWorkspaceFs,
+            &report_path.to_string_lossy(),
+            &work_dir.to_string_lossy(),
+        )
+        .await
+        .unwrap();
         assert_eq!(stats.citations_renumbered, 2);
         assert_eq!(stats.rejected_refs_in_body, 1);
 
-        let after = fs::read_to_string(&report_path).await.unwrap();
+        let after = std::fs::read_to_string(&report_path).unwrap();
         assert!(after.contains("mentioning [1] first"));
         assert!(after.contains("claim with [2] here"));
         assert!(after.contains("A pair: [1, 2]"));
@@ -300,14 +500,15 @@ cit_005 | claim c | url=u3 | authority=medium
             "display_map.json must NOT be written next to the report"
         );
         let map: serde_json::Value =
-            serde_json::from_str(&fs::read_to_string(sidecar).await.unwrap()).unwrap();
+            serde_json::from_str(&std::fs::read_to_string(sidecar).unwrap()).unwrap();
         assert_eq!(map["citation_count"], 2);
     }
 
     #[tokio::test]
     async fn run_for_session_is_no_op_when_session_has_no_report() {
         let dir = ScratchDir::new("no-session-report");
-        run_for_session_workspace(dir.path(), "missing-session").await;
+        let workspace_root = dir.path().to_string_lossy().to_string();
+        run_for_session_workspace(&HostWorkspaceFs, &workspace_root, "missing-session").await;
 
         let work_dir = dir
             .path()
@@ -315,8 +516,8 @@ cit_005 | claim c | url=u3 | authority=medium
             .join("sessions")
             .join("incomplete-session")
             .join("research");
-        fs::create_dir_all(&work_dir).await.unwrap();
-        run_for_session_workspace(dir.path(), "incomplete-session").await;
+        std::fs::create_dir_all(&work_dir).unwrap();
+        run_for_session_workspace(&HostWorkspaceFs, &workspace_root, "incomplete-session").await;
         assert!(!work_dir.join("display_map.json").exists());
     }
 
@@ -331,7 +532,7 @@ cit_005 | claim c | url=u3 | authority=medium
             .join("sessions")
             .join(session_id)
             .join("research");
-        fs::create_dir_all(&work_dir).await.unwrap();
+        std::fs::create_dir_all(&work_dir).unwrap();
 
         let report_path = work_dir.join("report.md");
         let report = "\
@@ -346,23 +547,99 @@ Para 1 references cit_005 first. Para 2 references cit_001.
 | cit_001 | claim a | u1 |
 | cit_005 | claim c | u3 |
 ";
-        fs::write(&report_path, report).await.unwrap();
+        std::fs::write(&report_path, report).unwrap();
 
-        fs::write(
+        std::fs::write(
             work_dir.join("citations.md"),
             "cit_001 | claim a | url=u1 | authority=high | status=ACCEPTED\n\
              cit_005 | claim c | url=u3 | authority=medium\n",
         )
-        .await
         .unwrap();
 
-        run_for_session_workspace(dir.path(), session_id).await;
+        let workspace_root = dir.path().to_string_lossy().to_string();
+        run_for_session_workspace(&HostWorkspaceFs, &workspace_root, session_id).await;
 
-        let after = fs::read_to_string(&report_path).await.unwrap();
+        let after = std::fs::read_to_string(&report_path).unwrap();
         assert!(after.contains("references [1] first"));
         assert!(after.contains("references [2]."));
         assert!(after.contains("[2] cit_001"));
         assert!(after.contains("[1] cit_005"));
         assert!(work_dir.join("display_map.json").exists());
     }
+
+    #[tokio::test]
+    async fn remote_workspace_paths_are_processed_only_through_the_workspace_fs_port() {
+        let fs = RecordingWorkspaceFs::default();
+        let workspace_root = "/root/project";
+        let session_id = "remote-session";
+        let work_dir = format!("{workspace_root}/.bitfun/sessions/{session_id}/research");
+        let report_path = format!("{work_dir}/report.md");
+        let citations_path = format!("{work_dir}/citations.md");
+        let display_map_path = format!("{work_dir}/display_map.json");
+        fs.insert(
+            &report_path,
+            b"Finding cit_005 then cit_001.\n\n## Citation Index\n\n| ID | Claim |\n|---|---|\n| cit_001 | a |\n| cit_005 | b |\n".to_vec(),
+        );
+        fs.insert(
+            &citations_path,
+            b"cit_001 | claim a | status=ACCEPTED\ncit_005 | claim b | status=ACCEPTED\n".to_vec(),
+        );
+
+        run_for_session_workspace(&fs, workspace_root, session_id).await;
+
+        let report = fs.text(&report_path).expect("rewritten remote report");
+        assert!(report.contains("Finding [1] then [2]."));
+        let display_map = fs
+            .text(&display_map_path)
+            .expect("remote display map sidecar");
+        assert!(display_map.contains("\"citation_count\": 2"));
+        assert_eq!(
+            fs.observed_operations(),
+            vec![
+                format!("exists:{report_path}"),
+                format!("exists:{report_path}"),
+                format!("read:{report_path}"),
+                format!("exists:{citations_path}"),
+                format!("read:{citations_path}"),
+                format!("write:{report_path}"),
+                format!("write:{display_map_path}"),
+            ]
+        );
+    }
+
+    #[tokio::test]
+    async fn missing_workspace_file_never_falls_back_to_the_host_filesystem() {
+        let host_workspace = ScratchDir::new("no-host-fallback");
+        let session_id = "remote-session";
+        let host_work_dir = host_workspace
+            .path()
+            .join(".bitfun")
+            .join("sessions")
+            .join(session_id)
+            .join("research");
+        std::fs::create_dir_all(&host_work_dir).unwrap();
+        let host_report = host_work_dir.join("report.md");
+        let original_report = "Finding cit_001.\n";
+        std::fs::write(&host_report, original_report).unwrap();
+
+        let remote_fs = RecordingWorkspaceFs::default();
+        let workspace_root = host_workspace.path().to_string_lossy().to_string();
+        run_for_session_workspace(&remote_fs, &workspace_root, session_id).await;
+
+        assert_eq!(
+            std::fs::read_to_string(&host_report).unwrap(),
+            original_report
+        );
+        assert!(!host_work_dir.join("display_map.json").exists());
+        assert_eq!(
+            remote_fs.observed_operations(),
+            vec![format!(
+                "exists:{}",
+                remote_fs.join_path(
+                    &workspace_root,
+                    &[".bitfun", "sessions", session_id, "research", "report.md"]
+                )
+            )]
+        );
+    }
 }
diff --git a/src/crates/services/services-integrations/src/function_agents.rs b/src/crates/services/services-integrations/src/function_agents.rs
index c50a73ede6..5425b417b1 100644
--- a/src/crates/services/services-integrations/src/function_agents.rs
+++ b/src/crates/services/services-integrations/src/function_agents.rs
@@ -4,15 +4,11 @@
 //! owns concrete Git snapshots for function agents without depending on
 //! `bitfun-core`.
 
-use std::path::{Path, PathBuf};
+use std::path::PathBuf;
 
 use bitfun_product_domains::function_agents::common::{AgentError, AgentResult};
 use bitfun_product_domains::function_agents::git_func_agent::ContextAnalyzer;
-use bitfun_product_domains::function_agents::ports::{
-    GitCommitSnapshot, StartchatGitSnapshot, StartchatTimeSnapshot,
-};
-use bitfun_product_domains::function_agents::startchat_func_agent::AheadBehind;
-use bitfun_services_core::process_manager;
+use bitfun_product_domains::function_agents::ports::GitCommitSnapshot;
 
 use crate::git::{GitDiffParams, GitService};
 
@@ -47,104 +43,4 @@ impl FunctionAgentGitService {
             project_context,
         })
     }
-
-    pub async fn startchat_git_snapshot(repo_path: PathBuf) -> AgentResult<StartchatGitSnapshot> {
-        let current_branch = git_stdout_lenient(&repo_path, &["branch", "--show-current"])?
-            .trim()
-            .to_string();
-        let status_porcelain = git_stdout_lenient(&repo_path, &["status", "--porcelain"])?;
-        let unstaged_diff = git_stdout_lenient(&repo_path, &["diff", "HEAD"])?;
-        let staged_diff = git_stdout_lenient(&repo_path, &["diff", "--cached"])?;
-        let unpushed_commits = git_unpushed_commits(&repo_path);
-        let ahead_behind = git_ahead_behind(&repo_path);
-        let last_commit_timestamp = git_last_commit_timestamp(&repo_path);
-
-        Ok(StartchatGitSnapshot {
-            current_branch,
-            status_porcelain,
-            unstaged_diff,
-            staged_diff,
-            unpushed_commits,
-            ahead_behind,
-            last_commit_timestamp,
-        })
-    }
-
-    pub fn startchat_time_snapshot(repo_path: &Path) -> StartchatTimeSnapshot {
-        StartchatTimeSnapshot {
-            last_commit_timestamp: git_last_commit_timestamp(repo_path),
-        }
-    }
-}
-
-fn git_stdout_lenient(repo_path: &Path, args: &[&str]) -> AgentResult<String> {
-    let output = process_manager::create_command("git")
-        .args(args)
-        .current_dir(repo_path)
-        .output()
-        .map_err(|e| AgentError::git_error(format!("Failed to run git {:?}: {}", args, e)))?;
-
-    Ok(String::from_utf8_lossy(&output.stdout).to_string())
-}
-
-fn git_unpushed_commits(repo_path: &Path) -> u32 {
-    let output = process_manager::create_command("git")
-        .arg("log")
-        .arg("@{u}..")
-        .arg("--oneline")
-        .current_dir(repo_path)
-        .output();
-
-    if let Ok(output) = output {
-        if output.status.success() {
-            return String::from_utf8_lossy(&output.stdout).lines().count() as u32;
-        }
-    }
-
-    0
-}
-
-fn git_ahead_behind(repo_path: &Path) -> Option<AheadBehind> {
-    let output = process_manager::create_command("git")
-        .arg("rev-list")
-        .arg("--left-right")
-        .arg("--count")
-        .arg("HEAD...@{u}")
-        .current_dir(repo_path)
-        .output()
-        .ok()?;
-
-    if !output.status.success() {
-        return None;
-    }
-
-    let result = String::from_utf8_lossy(&output.stdout);
-    let parts: Vec<&str> = result.split_whitespace().collect();
-    if parts.len() < 2 {
-        return None;
-    }
-
-    Some(AheadBehind {
-        ahead: parts[0].parse().unwrap_or(0),
-        behind: parts[1].parse().unwrap_or(0),
-    })
-}
-
-fn git_last_commit_timestamp(repo_path: &Path) -> Option<i64> {
-    let output = process_manager::create_command("git")
-        .arg("log")
-        .arg("-1")
-        .arg("--format=%ct")
-        .current_dir(repo_path)
-        .output()
-        .ok()?;
-
-    if !output.status.success() {
-        return None;
-    }
-
-    String::from_utf8_lossy(&output.stdout)
-        .trim()
-        .parse::<i64>()
-        .ok()
 }
diff --git a/src/crates/services/services-integrations/src/mcp/server/mod.rs b/src/crates/services/services-integrations/src/mcp/server/mod.rs
index d09c028f63..e677483bec 100644
--- a/src/crates/services/services-integrations/src/mcp/server/mod.rs
+++ b/src/crates/services/services-integrations/src/mcp/server/mod.rs
@@ -30,7 +30,9 @@ pub use runtime_policy::{
     mcp_server_is_running, mcp_server_is_starting_or_running, mcp_should_start_after_config_update,
     MCPListChangedKind, MCPReconnectRuntimeDecision,
 };
-pub use runtime_state::{MCPProcessStartContext, MCPProcessStartOutcome, MCPServerRuntimeState};
+pub use runtime_state::{
+    MCPProcessStartContext, MCPProcessStartOutcome, MCPServerRuntimeState, MCPServerStartFailure,
+};
 
 /// MCP server type.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
diff --git a/src/crates/services/services-integrations/src/mcp/server/runtime_state.rs b/src/crates/services/services-integrations/src/mcp/server/runtime_state.rs
index 14f943278f..819150654f 100644
--- a/src/crates/services/services-integrations/src/mcp/server/runtime_state.rs
+++ b/src/crates/services/services-integrations/src/mcp/server/runtime_state.rs
@@ -11,6 +11,7 @@ use super::{
 };
 use crate::mcp::protocol::{MCPPrompt, MCPResource};
 use log::info;
+use std::collections::HashMap;
 use std::fmt;
 use std::path::{Path, PathBuf};
 use std::sync::Arc;
@@ -37,6 +38,84 @@ pub enum MCPProcessStartContext {
     Remote { data_dir: PathBuf },
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MCPServerStartFailure {
+    Authentication,
+    Timeout,
+    CommandUnavailable,
+    WorkingDirectoryUnavailable,
+    ConnectionFailed,
+    ProtocolFailed,
+    Other,
+}
+
+impl MCPServerStartFailure {
+    pub fn classify(error: &str) -> Self {
+        let error = error.to_ascii_lowercase();
+        if [
+            "unauthorized",
+            "forbidden",
+            "authentication",
+            "oauth",
+            "status 401",
+            "status 403",
+            "http 401",
+            "http 403",
+        ]
+        .iter()
+        .any(|pattern| error.contains(pattern))
+        {
+            Self::Authentication
+        } else if ["timed out", "timeout", "deadline elapsed"]
+            .iter()
+            .any(|pattern| error.contains(pattern))
+        {
+            Self::Timeout
+        } else if [
+            "working directory",
+            "current directory",
+            "directory name is invalid",
+        ]
+        .iter()
+        .any(|pattern| error.contains(pattern))
+        {
+            Self::WorkingDirectoryUnavailable
+        } else if [
+            "connection refused",
+            "could not connect",
+            "failed to connect",
+            "dns",
+            "name resolution",
+        ]
+        .iter()
+        .any(|pattern| error.contains(pattern))
+        {
+            Self::ConnectionFailed
+        } else if ["handshake", "initialize", "protocol", "json-rpc"]
+            .iter()
+            .any(|pattern| error.contains(pattern))
+        {
+            Self::ProtocolFailed
+        } else if [
+            "program not found",
+            "executable not found",
+            "command not found",
+            "failed to start mcp server",
+            "os error 2",
+            "process error",
+            "failed to spawn",
+            "create process",
+        ]
+        .iter()
+        .any(|pattern| error.contains(pattern))
+        {
+            Self::CommandUnavailable
+        } else {
+            Self::Other
+        }
+    }
+}
+
 impl MCPProcessStartContext {
     fn server_type(&self) -> MCPServerType {
         match self {
@@ -60,6 +139,7 @@ pub struct MCPServerRuntimeState {
     connection_pool: MCPConnectionPool,
     reconnect_tracker: MCPReconnectTracker,
     catalog_cache: MCPCatalogCache,
+    start_failures: RwLock<HashMap<String, MCPServerStartFailure>>,
 }
 
 impl MCPServerRuntimeState {
@@ -69,6 +149,7 @@ impl MCPServerRuntimeState {
             connection_pool: MCPConnectionPool::new(),
             reconnect_tracker: MCPReconnectTracker::default(),
             catalog_cache: MCPCatalogCache::new(),
+            start_failures: RwLock::new(HashMap::new()),
         }
     }
 
@@ -80,6 +161,18 @@ impl MCPServerRuntimeState {
         self.registry.contains(server_id).await
     }
 
+    pub async fn set_start_failure(&self, server_id: String, failure: MCPServerStartFailure) {
+        self.start_failures.write().await.insert(server_id, failure);
+    }
+
+    pub async fn clear_start_failure(&self, server_id: &str) {
+        self.start_failures.write().await.remove(server_id);
+    }
+
+    pub async fn start_failure(&self, server_id: &str) -> Option<MCPServerStartFailure> {
+        self.start_failures.read().await.get(server_id).copied()
+    }
+
     pub async fn register(&self, config: &MCPServerConfig) -> MCPRuntimeResult<()> {
         self.registry.register(config).await
     }
@@ -93,7 +186,9 @@ impl MCPServerRuntimeState {
     }
 
     pub async fn clear_registry(&self) -> MCPRuntimeResult<()> {
-        self.registry.clear().await
+        self.registry.clear().await?;
+        self.start_failures.write().await.clear();
+        Ok(())
     }
 
     async fn get_process(&self, server_id: &str) -> Option<Arc<RwLock<MCPServerProcess>>> {
@@ -142,6 +237,15 @@ impl MCPServerRuntimeState {
                     MCPRuntimeError::configuration("Missing command for local MCP server")
                 })?;
                 let resolved = resolve_mcp_local_command(command, managed_runtimes_dir)?;
+                if config
+                    .working_directory
+                    .as_deref()
+                    .is_some_and(|directory| !Path::new(directory).is_dir())
+                {
+                    return Err(MCPRuntimeError::configuration(
+                        "MCP working directory is unavailable",
+                    ));
+                }
                 info!(
                     "Starting local MCP server: command={} source={} id={}",
                     resolved.command, resolved.source_label, config.id
@@ -339,3 +443,58 @@ impl Default for MCPServerRuntimeState {
         Self::new()
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::{MCPServerRuntimeState, MCPServerStartFailure};
+
+    #[test]
+    fn start_failures_are_actionable_without_exposing_runtime_details() {
+        assert_eq!(
+            MCPServerStartFailure::classify(
+                "Failed to start MCP server 'secret-command': program not found"
+            ),
+            MCPServerStartFailure::CommandUnavailable,
+        );
+        assert_eq!(
+            MCPServerStartFailure::classify("401 Unauthorized: token=secret"),
+            MCPServerStartFailure::Authentication,
+        );
+        assert_eq!(
+            MCPServerStartFailure::classify("initialize request timed out"),
+            MCPServerStartFailure::Timeout,
+        );
+        assert_eq!(
+            MCPServerStartFailure::classify(
+                "Failed to start MCP server: working directory is unavailable"
+            ),
+            MCPServerStartFailure::WorkingDirectoryUnavailable,
+        );
+
+        for failure in [
+            MCPServerStartFailure::CommandUnavailable,
+            MCPServerStartFailure::Authentication,
+            MCPServerStartFailure::Timeout,
+            MCPServerStartFailure::Other,
+        ] {
+            let debug = format!("{failure:?}");
+            assert!(!debug.contains("secret"));
+            assert!(!debug.contains("token="));
+        }
+    }
+
+    #[tokio::test]
+    async fn clearing_registry_also_clears_start_failures() {
+        let state = MCPServerRuntimeState::new();
+        state
+            .set_start_failure(
+                "external:mcp".to_string(),
+                MCPServerStartFailure::CommandUnavailable,
+            )
+            .await;
+
+        state.clear_registry().await.expect("clear registry");
+
+        assert_eq!(state.start_failure("external:mcp").await, None);
+    }
+}
diff --git a/src/crates/services/services-integrations/src/remote_connect.rs b/src/crates/services/services-integrations/src/remote_connect.rs
index 514e390b4f..e470b36bfd 100644
--- a/src/crates/services/services-integrations/src/remote_connect.rs
+++ b/src/crates/services/services-integrations/src/remote_connect.rs
@@ -2250,6 +2250,27 @@ pub enum RemoteCommand {
     /// relay device APIs directly. Answered by the host runtime; other hosts
     /// return an error response.
     GetDelegatedIdentity,
+    /// Ask the paired desktop to mint a *full* account device credential for a
+    /// separate device that cannot type a password (a watch). The desktop calls
+    /// the relay's `/api/auth/provision-device` with its own device token, then
+    /// returns the minted credential together with the account master key over
+    /// this already-encrypted room channel. The relay never sees the master key.
+    ///
+    /// Unlike `GetDelegatedIdentity` this yields a 30-day full credential rather
+    /// than a 24-hour delegated one, because the provisioned device is a primary
+    /// surface and cannot re-authenticate on its own when the token lapses.
+    ///
+    /// `request_id` is minted by the device being provisioned, not by the
+    /// desktop, so that a retry anywhere along the watch → phone → desktop chain
+    /// replays one idempotent relay request instead of registering a second
+    /// device. Answered by the host runtime; other hosts return an error
+    /// response.
+    ProvisionPeerDevice {
+        /// 32 lowercase hex characters; the relay rejects any other shape.
+        device_id: String,
+        device_name: String,
+        request_id: String,
+    },
     Ping,
 
     // ── Device-to-device distributed control ──────────────────────────────
@@ -2474,6 +2495,16 @@ pub enum RemoteResponse {
         master_key: String,
         device_id: String,
     },
+    /// A full account device credential minted for a paired client's peer
+    /// device. `master_key` is base64-encoded; `device_id` echoes the *newly
+    /// provisioned* device, not the delegating host — the opposite of
+    /// `DelegateIdentity`, whose `device_id` names the desktop.
+    PeerDeviceProvisioned {
+        token: String,
+        user_id: String,
+        master_key: String,
+        device_id: String,
+    },
     Error {
         message: String,
     },
@@ -2604,6 +2635,12 @@ where
             message: "Delegated identity is not available on this host".to_string(),
         },
 
+        // Same contract as GetDelegatedIdentity above: the host runtime owns the
+        // account credentials and answers before dispatch reaches this router.
+        RemoteCommand::ProvisionPeerDevice { .. } => RemoteResponse::Error {
+            message: "Device provisioning is not available on this host".to_string(),
+        },
+
         RemoteCommand::SendSessionToDevice { .. }
         | RemoteCommand::ExecuteOnDevice { .. }
         | RemoteCommand::DeviceQueryInfo
diff --git a/src/crates/services/services-integrations/src/remote_connect/account.rs b/src/crates/services/services-integrations/src/remote_connect/account.rs
index 9f5ff0693e..e6b6313d8e 100644
--- a/src/crates/services/services-integrations/src/remote_connect/account.rs
+++ b/src/crates/services/services-integrations/src/remote_connect/account.rs
@@ -478,6 +478,7 @@ impl AccountClient {
             "password_hash": password_hash,
             "device_id": device.device_id,
             "device_name": device.device_name,
+            "device_kind": "desktop",
             "request_id": uuid::Uuid::new_v4().to_string(),
         });
         let request = self
@@ -865,6 +866,11 @@ impl AccountClient {
     }
 
     /// Register a new account device and mint its full routing token.
+    ///
+    /// `device_kind` is what keeps the minted row out of the wrong lists: this
+    /// route serves both an SSH host being bootstrapped (`"desktop"`) and a
+    /// keyboard-less peer that cannot type a password (`"watch"`), and only the
+    /// caller knows which one it is holding.
     /// `request_id` makes an ambiguous HTTP response safe to replay.
     pub async fn provision_device_token(
         &self,
@@ -872,11 +878,13 @@ impl AccountClient {
         session: &AccountSession,
         device_id: &str,
         device_name: &str,
+        device_kind: &str,
         request_id: uuid::Uuid,
     ) -> Result<ProvisionedDeviceToken> {
         let body = serde_json::json!({
             "device_id": device_id,
             "device_name": device_name,
+            "device_kind": device_kind,
             "request_id": request_id.to_string(),
         });
         let resp = send_with_retry(
diff --git a/src/crates/services/services-integrations/src/remote_connect/relay_client.rs b/src/crates/services/services-integrations/src/remote_connect/relay_client.rs
index e7fad23361..4dd59c9030 100644
--- a/src/crates/services/services-integrations/src/remote_connect/relay_client.rs
+++ b/src/crates/services/services-integrations/src/remote_connect/relay_client.rs
@@ -64,6 +64,7 @@ pub enum RelayMessage {
     AuthConnect {
         token: String,
         device_name: String,
+        device_kind: String,
     },
     /// Route an encrypted payload to another device in the same account.
     DeviceMessage {
@@ -354,6 +355,7 @@ impl RelayClient {
                                 let reauth = RelayMessage::AuthConnect {
                                     token: ctx.token.clone(),
                                     device_name: ctx.device_name.clone(),
+                                    device_kind: "desktop".to_string(),
                                 };
                                 let _ = new_cmd_tx.send(reauth);
                                 info!("Re-sent AuthConnect after reconnect");
@@ -534,9 +536,12 @@ impl RelayClient {
         }
         drop(guard);
 
+        // Only desktops hold a relay WebSocket — phones and watches talk HTTP —
+        // so the kind is a constant here rather than a parameter.
         self.send(RelayMessage::AuthConnect {
             token: token.to_string(),
             device_name: device_name.to_string(),
+            device_kind: "desktop".to_string(),
         })
         .await
     }
diff --git a/src/crates/services/services-integrations/src/remote_ssh/dispatch_ssh.rs b/src/crates/services/services-integrations/src/remote_ssh/dispatch_ssh.rs
index 40ddc703c9..14caf5d576 100644
--- a/src/crates/services/services-integrations/src/remote_ssh/dispatch_ssh.rs
+++ b/src/crates/services/services-integrations/src/remote_ssh/dispatch_ssh.rs
@@ -1181,12 +1181,7 @@ async fn account_daemon_cli_path(
 /// Keys of the `ai` config section that make up "model configuration": the
 /// model catalog (credentials included) plus every default-selection table the
 /// target consults when resolving a ready model.
-const MODEL_CONFIG_KEYS: [&str; 4] = [
-    "models",
-    "default_models",
-    "agent_model_defaults",
-    "func_agent_models",
-];
+const MODEL_CONFIG_KEYS: [&str; 3] = ["models", "default_models", "agent_model_defaults"];
 
 /// Write the controller's model configuration into the target's global config
 /// so `bitfun dispatch probe` can report a ready model.
@@ -4158,6 +4153,11 @@ mod tests {
             "tool_permissions": {}
         }))
         .is_err());
+        assert!(validate_model_config_payload(&serde_json::json!({
+            "models": [{"id": "m1"}],
+            "task_models": {"session_title": {"kind": "inherit"}}
+        }))
+        .is_err());
         assert!(validate_model_config_payload(&serde_json::json!({ "models": [] })).is_err());
         assert!(validate_model_config_payload(&serde_json::json!("models")).is_err());
     }
diff --git a/src/crates/services/services-integrations/src/remote_ssh/file_name_search.rs b/src/crates/services/services-integrations/src/remote_ssh/file_name_search.rs
new file mode 100644
index 0000000000..d61e4c2206
--- /dev/null
+++ b/src/crates/services/services-integrations/src/remote_ssh/file_name_search.rs
@@ -0,0 +1,249 @@
+use super::{RemoteDirEntry, RemoteFileService, RemoteWorkspaceEntry};
+use bitfun_services_core::filesystem::{
+    FileSearchOutcome, FileSearchProgressSink, FileSearchResult, FileSearchResultGroup,
+    SearchMatchType,
+};
+use regex::Regex;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+
+/// One remote filename search routed to an already-resolved workspace.
+///
+/// Target resolution remains with the caller because a POSIX path alone does
+/// not identify a remote workspace when multiple SSH connections expose the
+/// same root. This service owns only the reusable remote filesystem traversal.
+pub struct RemoteFileNameSearch {
+    pub remote_fs: RemoteFileService,
+    pub workspace: RemoteWorkspaceEntry,
+    pub root_path: String,
+    pub pattern: String,
+    pub case_sensitive: bool,
+    pub use_regex: bool,
+    pub whole_word: bool,
+    pub include_directories: bool,
+    pub limit: usize,
+    pub cancel_flag: Option<Arc<AtomicBool>>,
+    pub progress_sink: Option<Arc<dyn FileSearchProgressSink>>,
+}
+
+fn compile_file_name_search_regex(
+    pattern: &str,
+    case_sensitive: bool,
+    use_regex: bool,
+    whole_word: bool,
+) -> Result<Regex, String> {
+    let mut pattern = if use_regex {
+        pattern.to_string()
+    } else {
+        regex::escape(pattern)
+    };
+
+    if whole_word {
+        pattern = format!(r"\b(?:{})\b", pattern);
+    }
+
+    if !case_sensitive {
+        pattern = format!("(?i){}", pattern);
+    }
+
+    Regex::new(&pattern).map_err(|error| format!("Invalid search pattern: {}", error))
+}
+
+fn should_skip_directory(name: &str) -> bool {
+    matches!(
+        name,
+        ".git"
+            | ".svn"
+            | ".hg"
+            | "node_modules"
+            | "target"
+            | "dist"
+            | "build"
+            | ".next"
+            | ".nuxt"
+            | ".cache"
+            | ".turbo"
+    )
+}
+
+fn should_skip_file(name: &str) -> bool {
+    let lower = name.to_ascii_lowercase();
+    matches!(
+        lower.rsplit_once('.').map(|(_, ext)| ext),
+        Some(
+            "png"
+                | "jpg"
+                | "jpeg"
+                | "gif"
+                | "webp"
+                | "ico"
+                | "pdf"
+                | "zip"
+                | "tar"
+                | "gz"
+                | "rar"
+                | "7z"
+                | "exe"
+                | "dll"
+                | "so"
+                | "dylib"
+        )
+    )
+}
+
+fn search_result(entry: &RemoteDirEntry) -> FileSearchResult {
+    FileSearchResult {
+        path: entry.path.clone(),
+        name: entry.name.clone(),
+        is_directory: entry.is_dir,
+        match_type: SearchMatchType::FileName,
+        line_number: None,
+        matched_content: None,
+        preview_before: None,
+        preview_inside: None,
+        preview_after: None,
+    }
+}
+
+/// Searches a remote workspace through its file provider and reports matches
+/// as soon as they are discovered. The progress contract is important for
+/// high-latency workspaces: callers must not wait for the entire recursive walk
+/// before showing an early match.
+pub async fn search_remote_file_names(
+    search: RemoteFileNameSearch,
+) -> Result<FileSearchOutcome, String> {
+    let RemoteFileNameSearch {
+        remote_fs,
+        workspace,
+        root_path,
+        pattern,
+        case_sensitive,
+        use_regex,
+        whole_word,
+        include_directories,
+        limit,
+        cancel_flag,
+        progress_sink,
+    } = search;
+    let matcher = compile_file_name_search_regex(&pattern, case_sensitive, use_regex, whole_word)?;
+    let mut stack = vec![root_path];
+    let mut results = Vec::new();
+    let mut truncated = false;
+
+    while let Some(directory) = stack.pop() {
+        if cancel_flag
+            .as_ref()
+            .is_some_and(|flag| flag.load(Ordering::Relaxed))
+        {
+            break;
+        }
+
+        let mut entries = match remote_fs
+            .read_dir(&workspace.connection_id, &directory)
+            .await
+        {
+            Ok(entries) => entries,
+            Err(error) => {
+                if let Some(sink) = progress_sink.as_ref() {
+                    sink.flush();
+                }
+                return Err(format!("Failed to read remote directory: {}", error));
+            }
+        };
+        entries.sort_by(|a, b| match (a.is_dir, b.is_dir) {
+            (true, false) => std::cmp::Ordering::Less,
+            (false, true) => std::cmp::Ordering::Greater,
+            _ => a.name.cmp(&b.name),
+        });
+
+        for child in entries {
+            if cancel_flag
+                .as_ref()
+                .is_some_and(|flag| flag.load(Ordering::Relaxed))
+            {
+                break;
+            }
+
+            if child.is_dir {
+                if should_skip_directory(&child.name) {
+                    continue;
+                }
+
+                if include_directories && matcher.is_match(&child.name) {
+                    let result = search_result(&child);
+                    if let Some(sink) = progress_sink.as_ref() {
+                        sink.report(FileSearchResultGroup {
+                            path: result.path.clone(),
+                            name: result.name.clone(),
+                            is_directory: result.is_directory,
+                            file_name_match: Some(result.clone()),
+                            content_matches: Vec::new(),
+                        });
+                    }
+                    results.push(result);
+                    if results.len() >= limit {
+                        truncated = true;
+                        break;
+                    }
+                }
+
+                stack.push(child.path);
+                continue;
+            }
+
+            if !child.is_file || should_skip_file(&child.name) {
+                continue;
+            }
+
+            if matcher.is_match(&child.name) {
+                let result = search_result(&child);
+                if let Some(sink) = progress_sink.as_ref() {
+                    sink.report(FileSearchResultGroup {
+                        path: result.path.clone(),
+                        name: result.name.clone(),
+                        is_directory: result.is_directory,
+                        file_name_match: Some(result.clone()),
+                        content_matches: Vec::new(),
+                    });
+                }
+                results.push(result);
+                if results.len() >= limit {
+                    truncated = true;
+                    break;
+                }
+            }
+        }
+
+        if truncated {
+            break;
+        }
+    }
+
+    if let Some(sink) = progress_sink.as_ref() {
+        sink.flush();
+    }
+
+    Ok(FileSearchOutcome { results, truncated })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{compile_file_name_search_regex, should_skip_directory, should_skip_file};
+
+    #[test]
+    fn literal_search_matches_unicode_directory_names() {
+        let matcher = compile_file_name_search_regex("手写", false, false, false)
+            .expect("compile literal matcher");
+        assert!(matcher.is_match("手写笔画标注项目"));
+        assert!(!matcher.is_match("框球项目"));
+    }
+
+    #[test]
+    fn traversal_filters_keep_existing_search_contract() {
+        assert!(should_skip_directory("node_modules"));
+        assert!(should_skip_directory(".git"));
+        assert!(!should_skip_directory("src"));
+        assert!(should_skip_file("archive.zip"));
+        assert!(!should_skip_file("README.md"));
+    }
+}
diff --git a/src/crates/services/services-integrations/src/remote_ssh/mod.rs b/src/crates/services/services-integrations/src/remote_ssh/mod.rs
index cb3f2bbbed..abe62202b4 100644
--- a/src/crates/services/services-integrations/src/remote_ssh/mod.rs
+++ b/src/crates/services/services-integrations/src/remote_ssh/mod.rs
@@ -3,6 +3,7 @@
 //! `bitfun-core::service::remote_ssh` remains as the compatibility facade for
 //! the legacy public path.
 
+mod file_name_search;
 pub mod paths;
 pub mod remote_git;
 mod shell;
@@ -35,6 +36,7 @@ pub mod remote_fs;
 #[cfg(feature = "remote-ssh-concrete")]
 pub mod remote_terminal;
 
+pub use file_name_search::{search_remote_file_names, RemoteFileNameSearch};
 pub use paths::*;
 pub use remote_git::{build_remote_git_command, shell_quote_posix};
 #[cfg(feature = "remote-ssh-concrete")]
diff --git a/src/crates/services/services-integrations/src/remote_ssh/release_verify.rs b/src/crates/services/services-integrations/src/remote_ssh/release_verify.rs
index 0aa1be4c19..f909bb1fde 100644
--- a/src/crates/services/services-integrations/src/remote_ssh/release_verify.rs
+++ b/src/crates/services/services-integrations/src/remote_ssh/release_verify.rs
@@ -67,28 +67,39 @@ pub(crate) fn verify_sha256(data: &[u8], expected: &str, filename: &str) -> Resu
     Ok(())
 }
 
-/// Verify a Tauri-format `.sig` (base64 of a complete minisign signature file)
-/// using the likewise base64-wrapped public key.
-pub(crate) fn verify_minisign(data: &[u8], signature_b64: &str, pubkey_b64: &str) -> Result<()> {
+/// Verify a Tauri-format `.sig` (base64 of a complete minisign signature file).
+/// The public key may be the raw minisign file accepted by current Tauri CLIs
+/// or the legacy base64 wrapper stored by older release configurations.
+pub(crate) fn verify_minisign(data: &[u8], signature_b64: &str, pubkey: &str) -> Result<()> {
     use base64::Engine as _;
 
-    let decode = |value: &str, what: &str| -> Result<String> {
-        let bytes = base64::engine::general_purpose::STANDARD
-            .decode(value.trim().as_bytes())
-            .with_context(|| format!("decode {what}"))?;
-        String::from_utf8(bytes).with_context(|| format!("decode {what} as UTF-8"))
-    };
-
-    let public_key = minisign_verify::PublicKey::decode(&decode(pubkey_b64, "release public key")?)
+    let public_key = minisign_verify::PublicKey::decode(&decode_public_key(pubkey)?)
         .map_err(|error| anyhow!("invalid release public key: {error}"))?;
-    let signature =
-        minisign_verify::Signature::decode(&decode(signature_b64, "release signature")?)
-            .map_err(|error| anyhow!("invalid release signature: {error}"))?;
+    let signature_bytes = base64::engine::general_purpose::STANDARD
+        .decode(signature_b64.trim().as_bytes())
+        .context("decode release signature")?;
+    let signature_text =
+        String::from_utf8(signature_bytes).context("decode release signature as UTF-8")?;
+    let signature = minisign_verify::Signature::decode(&signature_text)
+        .map_err(|error| anyhow!("invalid release signature: {error}"))?;
     public_key
         .verify(data, &signature, false)
         .map_err(|error| anyhow!("release signature does not match the signed data: {error}"))
 }
 
+fn decode_public_key(value: &str) -> Result<String> {
+    use base64::Engine as _;
+
+    let value = value.trim();
+    if value.starts_with("untrusted comment:") {
+        return Ok(value.to_owned());
+    }
+    let bytes = base64::engine::general_purpose::STANDARD
+        .decode(value.as_bytes())
+        .context("decode release public key")?;
+    String::from_utf8(bytes).context("decode release public key as UTF-8")
+}
+
 /// Verify the minisign signature over a checksum sidecar, then return its
 /// normalized digest. This is useful when the eventual target host has only a
 /// SHA256 implementation and no copy of the BitFun trust root.
@@ -114,13 +125,8 @@ mod tests {
 
     #[test]
     fn embedded_trust_root_is_always_available_and_well_formed() {
-        use base64::Engine as _;
-
         let pubkey = require_release_pubkey().expect("every build carries a trust root");
-        let decoded = base64::engine::general_purpose::STANDARD
-            .decode(pubkey.trim().as_bytes())
-            .expect("trust root is base64");
-        let text = String::from_utf8(decoded).expect("trust root decodes as UTF-8");
+        let text = decode_public_key(pubkey).expect("trust root has a supported key format");
         minisign_verify::PublicKey::decode(&text).expect("trust root is a minisign public key");
     }
 
@@ -128,6 +134,9 @@ mod tests {
     fn minisign_wire_format_accepts_authentic_data_and_rejects_tampering() {
         verify_minisign(FIXTURE_DATA, FIXTURE_SIGNATURE, FIXTURE_PUBKEY)
             .expect("fixture signature must verify");
+        let raw_pubkey = decode_public_key(FIXTURE_PUBKEY).expect("decode fixture public key");
+        verify_minisign(FIXTURE_DATA, FIXTURE_SIGNATURE, &raw_pubkey)
+            .expect("raw minisign public key must verify");
         assert!(verify_minisign(b"tampered\n", FIXTURE_SIGNATURE, FIXTURE_PUBKEY).is_err());
         assert!(verify_minisign(FIXTURE_DATA, "bm90LWEtc2ln", FIXTURE_PUBKEY).is_err());
     }
diff --git a/src/crates/services/services-integrations/src/remote_ssh/transport.rs b/src/crates/services/services-integrations/src/remote_ssh/transport.rs
index c0729994dd..a3f9d01e07 100644
--- a/src/crates/services/services-integrations/src/remote_ssh/transport.rs
+++ b/src/crates/services/services-integrations/src/remote_ssh/transport.rs
@@ -394,6 +394,23 @@ impl WorkspacePipes {
     }
 }
 
+/// Resolve on the next real signal, and never on the channel closing.
+///
+/// A caller that keeps no `WorkspaceProcessControl` — because it drives the
+/// process purely over its IO streams — closes this channel the moment the
+/// handle it was given falls out of scope. That is not a request to kill
+/// anything: what leases the process is the three IO streams, as
+/// [`WorkspaceStdio`] documents. Reading the close as a `Kill` killed such a
+/// process microseconds after it started, before it could say a word.
+async fn next_control_signal(
+    control_rx: &mut mpsc::Receiver<WorkspaceProcessSignal>,
+) -> WorkspaceProcessSignal {
+    match control_rx.recv().await {
+        Some(signal) => signal,
+        None => std::future::pending().await,
+    }
+}
+
 #[cfg(feature = "remote-ssh-concrete")]
 async fn run_ssh_channel(mut channel: Channel<Msg>, mut pipes: WorkspacePipeOwner) {
     let mut stdin_buffer = vec![0u8; 16 * 1024];
@@ -413,12 +430,12 @@ async fn run_ssh_channel(mut channel: Channel<Msg>, mut pipes: WorkspacePipeOwne
         tokio::select! {
             biased;
 
-            signal = pipes.control_rx.recv() => {
+            signal = next_control_signal(&mut pipes.control_rx) => {
                 match signal {
-                    Some(WorkspaceProcessSignal::Interrupt) => {
+                    WorkspaceProcessSignal::Interrupt => {
                         let _ = channel.signal(Sig::INT).await;
                     }
-                    Some(WorkspaceProcessSignal::Kill) | None => {
+                    WorkspaceProcessSignal::Kill => {
                         let _ = channel.signal(Sig::KILL).await;
                         let _ = channel.close().await;
                         exit_code.get_or_insert(137);
@@ -543,10 +560,10 @@ async fn run_local_process(
         // We are the ones ending the process here, so a signal death says
         // nothing the caller does not already know. Prefer a status the
         // child chose for itself and otherwise report the requested intent.
-        signal = pipes.control_rx.recv() => {
+        signal = next_control_signal(&mut pipes.control_rx) => {
             let fallback = match signal {
-                Some(WorkspaceProcessSignal::Interrupt) => 130,
-                Some(WorkspaceProcessSignal::Kill) | None => 137,
+                WorkspaceProcessSignal::Interrupt => 130,
+                WorkspaceProcessSignal::Kill => 137,
             };
             let _ = child.start_kill();
             child.wait().await.ok().and_then(|status| status.code()).or(Some(fallback))
@@ -687,6 +704,18 @@ mod ssh_channel_tests {
     }
 
     async fn workspace_exit_for(report: ExitReport) -> WorkspaceProcessExit {
+        let transport = workspace_stdio_for(report).await;
+        let (_stdin, mut stdout, _stderr, _control, completion) = transport.into_parts();
+        let mut stdout_bytes = Vec::new();
+        let _ = stdout.read_to_end(&mut stdout_bytes).await;
+        assert_eq!(stdout_bytes, b"workspace output\n");
+
+        tokio::time::timeout(Duration::from_secs(20), completion.wait())
+            .await
+            .expect("channel owner should report completion")
+    }
+
+    async fn workspace_stdio_for(report: ExitReport) -> WorkspaceStdio {
         let listener = TcpListener::bind("127.0.0.1:0")
             .await
             .expect("test SSH listener should bind");
@@ -724,15 +753,7 @@ mod ssh_channel_tests {
             .await
             .expect("test exec should start");
 
-        let transport = WorkspaceStdio::from_ssh_channel(channel);
-        let (_stdin, mut stdout, _stderr, _control, completion) = transport.into_parts();
-        let mut stdout_bytes = Vec::new();
-        let _ = stdout.read_to_end(&mut stdout_bytes).await;
-        assert_eq!(stdout_bytes, b"workspace output\n");
-
-        tokio::time::timeout(Duration::from_secs(20), completion.wait())
-            .await
-            .expect("channel owner should report completion")
+        WorkspaceStdio::from_ssh_channel(channel)
     }
 
     #[tokio::test]
@@ -760,6 +781,32 @@ mod ssh_channel_tests {
         assert_eq!(exit.exit_code, Some(143));
     }
 
+    #[tokio::test]
+    async fn dropping_the_control_handle_does_not_end_the_channel() {
+        let transport = workspace_stdio_for(ExitReport::EofBeforeExitStatus).await;
+        let (_stdin, mut stdout, _stderr, control, completion) = transport.into_parts();
+        // A caller that drives the process over its IO streams alone has no use
+        // for this handle, and every ACP client is such a caller. Letting it go
+        // says nothing about whether the process should keep running.
+        drop(control);
+
+        let mut stdout_bytes = Vec::new();
+        let _ = stdout.read_to_end(&mut stdout_bytes).await;
+        let exit = tokio::time::timeout(Duration::from_secs(20), completion.wait())
+            .await
+            .expect("channel owner should report completion");
+
+        assert_eq!(
+            stdout_bytes, b"workspace output\n",
+            "the remote process must still get to say what it had to say"
+        );
+        assert_eq!(
+            exit.exit_code,
+            Some(7),
+            "a dropped control handle is not a kill request"
+        );
+    }
+
     #[tokio::test]
     async fn missing_exit_status_stays_unknown() {
         let exit = workspace_exit_for(ExitReport::NoStatus).await;
@@ -883,6 +930,29 @@ mod tests {
         );
     }
 
+    #[tokio::test]
+    #[cfg(unix)]
+    async fn dropping_the_control_handle_does_not_end_the_local_process() {
+        let transport = WorkspaceStdio::spawn_local_process(
+            "sh",
+            &["-lc".to_string(), "sleep 0.3; exit 5".to_string()],
+        )
+        .unwrap();
+        let (_stdin, _stdout, _stderr, control, completion) = transport.into_parts();
+        // The IO streams are the lease; this handle is not.
+        drop(control);
+
+        let exit = tokio::time::timeout(std::time::Duration::from_secs(5), completion.wait())
+            .await
+            .expect("the process should run to its own end");
+
+        assert_eq!(
+            exit.exit_code,
+            Some(5),
+            "a dropped control handle must not be read as a kill request"
+        );
+    }
+
     #[tokio::test]
     #[cfg(unix)]
     async fn dropping_all_io_streams_cancels_local_process() {
diff --git a/src/crates/services/services-integrations/src/remote_ssh/workspace_registry.rs b/src/crates/services/services-integrations/src/remote_ssh/workspace_registry.rs
index b2c9426bef..14d4114cfc 100644
--- a/src/crates/services/services-integrations/src/remote_ssh/workspace_registry.rs
+++ b/src/crates/services/services-integrations/src/remote_ssh/workspace_registry.rs
@@ -128,12 +128,11 @@ impl RemoteWorkspaceRegistry {
             .filter(|r| registration_matches_path(r, &path_norm))
             .collect();
 
-        // Only use preferred_connection_id to disambiguate when multiple
-        // path-matching candidates exist. When there is exactly one match,
-        // the path is unambiguous and the preferred hint must not override it.
+        // Keep the legacy hint semantics for existing callers: only use the
+        // preferred id to disambiguate multiple path-matching registrations.
         if candidates.len() > 1 {
-            if let Some(pref) = preferred_connection_id {
-                candidates.retain(|r| r.connection_id == pref);
+            if let Some(preferred) = preferred_connection_id {
+                candidates.retain(|registration| registration.connection_id == preferred);
             }
         }
 
@@ -156,6 +155,32 @@ impl RemoteWorkspaceRegistry {
         None
     }
 
+    /// Looks up one exact `(connection_id, path)` scope.
+    ///
+    /// Unlike [`Self::lookup_connection`], this never treats the connection id
+    /// as a best-effort hint and never selects another registered host.
+    pub async fn lookup_scoped_connection(
+        &self,
+        path: &str,
+        connection_id: &str,
+    ) -> Option<RemoteWorkspaceEntry> {
+        let connection_id = connection_id.trim();
+        if connection_id.is_empty() {
+            return None;
+        }
+
+        let path_norm = normalize_remote_workspace_path(path);
+        let guard = self.registrations.read().await;
+        guard
+            .iter()
+            .filter(|registration| {
+                registration.connection_id == connection_id
+                    && registration_matches_path(registration, &path_norm)
+            })
+            .max_by_key(|registration| registration.remote_root.len())
+            .map(entry_from_registration)
+    }
+
     /// True if `path` could belong to any registered remote root before disambiguation.
     pub async fn is_remote_path(&self, path: &str) -> bool {
         let path_norm = normalize_remote_workspace_path(path);
diff --git a/src/crates/services/services-integrations/src/remote_ssh/workspace_services.rs b/src/crates/services/services-integrations/src/remote_ssh/workspace_services.rs
index 11d0fb49d4..6aa2696fd6 100644
--- a/src/crates/services/services-integrations/src/remote_ssh/workspace_services.rs
+++ b/src/crates/services/services-integrations/src/remote_ssh/workspace_services.rs
@@ -82,8 +82,26 @@ impl RemoteWorkspaceFs {
     }
 }
 
+fn join_posix_path(root: &str, components: &[&str]) -> String {
+    let mut path = root.trim_end_matches('/').to_string();
+    if path.is_empty() && root.starts_with('/') {
+        path.push('/');
+    }
+    for component in components {
+        if !path.is_empty() && !path.ends_with('/') {
+            path.push('/');
+        }
+        path.push_str(component.trim_matches('/'));
+    }
+    path
+}
+
 #[async_trait]
 impl WorkspaceFileSystem for RemoteWorkspaceFs {
+    fn join_path(&self, root: &str, components: &[&str]) -> String {
+        join_posix_path(root, components)
+    }
+
     async fn read_file(&self, path: &str) -> anyhow::Result<Vec<u8>> {
         self.file_service.read_file(&self.connection_id, path).await
     }
@@ -226,6 +244,19 @@ mod bounded_read_tests {
         }
     }
 
+    #[test]
+    fn remote_workspace_paths_keep_posix_syntax_for_absolute_home_and_relative_roots() {
+        for (root, expected) in [
+            ("/", "/.bitfun/report.md"),
+            ("~", "~/.bitfun/report.md"),
+            ("~/repo", "~/repo/.bitfun/report.md"),
+            ("repo", "repo/.bitfun/report.md"),
+            (".", "./.bitfun/report.md"),
+        ] {
+            assert_eq!(join_posix_path(root, &[".bitfun", "report.md"]), expected);
+        }
+    }
+
     #[test]
     fn bounded_binary_preflight_preserves_errors_and_follows_document_symlinks() {
         assert_eq!(
diff --git a/src/crates/services/services-integrations/tests/function_agent_contracts.rs b/src/crates/services/services-integrations/tests/function_agent_contracts.rs
index e035225607..b90c07ed5a 100644
--- a/src/crates/services/services-integrations/tests/function_agent_contracts.rs
+++ b/src/crates/services/services-integrations/tests/function_agent_contracts.rs
@@ -63,59 +63,6 @@ async fn git_service_builds_commit_snapshot_from_staged_diff_without_unstaged_co
     assert!(!snapshot.diff_content.contains("unstaged only"));
 }
 
-#[tokio::test]
-async fn git_service_startchat_snapshot_preserves_no_head_and_non_git_fallback() {
-    let no_head_repo = TestTempDir::new("startchat-no-head");
-    init_git_repo(no_head_repo.path());
-    fs::write(no_head_repo.path().join("new.txt"), "new\n").unwrap();
-
-    let no_head =
-        FunctionAgentGitService::startchat_git_snapshot(no_head_repo.path().to_path_buf())
-            .await
-            .unwrap();
-
-    assert_eq!(no_head.current_branch, "main");
-    assert!(no_head.status_porcelain.contains("?? new.txt"));
-    assert!(no_head.unstaged_diff.is_empty());
-    assert!(no_head.staged_diff.is_empty());
-    assert_eq!(no_head.unpushed_commits, 0);
-    assert!(no_head.ahead_behind.is_none());
-    assert!(no_head.last_commit_timestamp.is_none());
-
-    let plain_dir = TestTempDir::new("not-git");
-    let non_git = FunctionAgentGitService::startchat_git_snapshot(plain_dir.path().to_path_buf())
-        .await
-        .unwrap();
-
-    assert!(non_git.current_branch.is_empty());
-    assert!(non_git.status_porcelain.is_empty());
-    assert!(non_git.unstaged_diff.is_empty());
-    assert!(non_git.staged_diff.is_empty());
-    assert_eq!(non_git.unpushed_commits, 0);
-    assert!(non_git.ahead_behind.is_none());
-    assert!(non_git.last_commit_timestamp.is_none());
-}
-
-#[tokio::test]
-async fn git_service_time_snapshot_uses_last_commit_timestamp() {
-    let repo = TestTempDir::new("time-snapshot");
-    init_git_repo(repo.path());
-    fs::write(repo.path().join("tracked.txt"), "base\n").unwrap();
-    git(repo.path(), &["add", "tracked.txt"]);
-    git_with_env(
-        repo.path(),
-        &["commit", "-m", "initial"],
-        &[
-            ("GIT_AUTHOR_DATE", "1700000000 +0000"),
-            ("GIT_COMMITTER_DATE", "1700000000 +0000"),
-        ],
-    );
-
-    let snapshot = FunctionAgentGitService::startchat_time_snapshot(repo.path());
-
-    assert_eq!(snapshot.last_commit_timestamp, Some(1_700_000_000));
-}
-
 fn init_git_repo(repo: &Path) {
     git(repo, &["init", "-b", "main"]);
     git(repo, &["config", "user.email", "test@example.com"]);
diff --git a/src/crates/services/services-integrations/tests/remote_connect_contracts.rs b/src/crates/services/services-integrations/tests/remote_connect_contracts.rs
index 597361e224..63095104b9 100644
--- a/src/crates/services/services-integrations/tests/remote_connect_contracts.rs
+++ b/src/crates/services/services-integrations/tests/remote_connect_contracts.rs
@@ -2216,6 +2216,7 @@ fn remote_connect_model_catalog_builder_preserves_config_shape() {
                     execution_provider: None,
                     execution_model: None,
                 }],
+                unavailable_presets: Vec::new(),
             }),
         }],
         provider_catalog: Default::default(),
diff --git a/src/crates/services/services-integrations/tests/remote_ssh_contracts/remote_ssh_contracts.rs b/src/crates/services/services-integrations/tests/remote_ssh_contracts/remote_ssh_contracts.rs
index b251b8376c..4906fc3e69 100644
--- a/src/crates/services/services-integrations/tests/remote_ssh_contracts/remote_ssh_contracts.rs
+++ b/src/crates/services/services-integrations/tests/remote_ssh_contracts/remote_ssh_contracts.rs
@@ -317,6 +317,33 @@ async fn remote_workspace_registry_preserves_ambiguous_root_resolution_contract(
     assert_eq!(preferred.ssh_host, "host-b");
 }
 
+#[tokio::test]
+async fn remote_workspace_registry_treats_explicit_connection_as_exact_identity() {
+    let registry = RemoteWorkspaceRegistry::new();
+    registry
+        .register_remote_workspace(
+            "/workspace".to_string(),
+            "conn-a".to_string(),
+            "Server A".to_string(),
+            "host-a".to_string(),
+        )
+        .await;
+
+    assert!(
+        registry
+            .lookup_scoped_connection("/workspace/project", "conn-b")
+            .await
+            .is_none(),
+        "an explicit connection must never route to a different registered host"
+    );
+
+    let legacy_hint = registry
+        .lookup_connection("/workspace/project", Some("conn-b"))
+        .await
+        .expect("the compatibility lookup keeps its unique-path hint behavior");
+    assert_eq!(legacy_hint.connection_id, "conn-a");
+}
+
 #[tokio::test]
 async fn remote_workspace_registry_preserves_legacy_state_and_clear_contract() {
     let registry = RemoteWorkspaceRegistry::new();
diff --git a/src/crates/services/skin-market-service/Cargo.toml b/src/crates/services/skin-market-service/Cargo.toml
index 7b35abb31b..f5ed1471f8 100644
--- a/src/crates/services/skin-market-service/Cargo.toml
+++ b/src/crates/services/skin-market-service/Cargo.toml
@@ -17,12 +17,12 @@ chrono = { workspace = true }
 hex = { workspace = true }
 image = { workspace = true }
 hmac = { workspace = true }
-reqwest = { workspace = true, features = ["rustls"] }
+reqwest = { workspace = true, features = ["http2", "json", "rustls"] }
 semver = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
 sha2 = { workspace = true }
-sqlx = { version = "0.8", default-features = false, features = ["runtime-tokio", "sqlite"] }
+sqlx = { workspace = true, features = ["runtime-tokio", "sqlite"] }
 tokio = { workspace = true, features = ["fs", "rt", "sync", "time"] }
 tokio-util = { workspace = true, features = ["io"] }
 tower-http = { version = "0.6.11", features = ["fs"] }
diff --git a/src/crates/services/terminal/Cargo.toml b/src/crates/services/terminal/Cargo.toml
index 3d2ea05120..bf63756457 100644
--- a/src/crates/services/terminal/Cargo.toml
+++ b/src/crates/services/terminal/Cargo.toml
@@ -10,7 +10,7 @@ name = "terminal_core"
 path = "src/lib.rs"
 
 [dependencies]
-bitfun-runtime-ports = { path = "../../contracts/runtime-ports" }
+bitfun-runtime-ports = { path = "../../contracts/runtime-ports", features = ["terminal-port"] }
 
 # Async runtime
 tokio = { workspace = true, features = ["io-util", "macros", "process", "rt", "sync", "time"] }
diff --git a/src/miniapp-market-web/package.json b/src/miniapp-market-web/package.json
index d22c2609ef..89b9423221 100644
--- a/src/miniapp-market-web/package.json
+++ b/src/miniapp-market-web/package.json
@@ -1,6 +1,6 @@
 {
   "name": "bitfun-miniapp-market-web",
-  "version": "0.2.17",
+  "version": "0.2.18",
   "private": true,
   "type": "module",
   "scripts": {
diff --git a/src/mobile-web/package-lock.json b/src/mobile-web/package-lock.json
index 356c15e940..f33deb7d78 100644
--- a/src/mobile-web/package-lock.json
+++ b/src/mobile-web/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "bitfun-mobile-web",
-  "version": "0.2.17",
+  "version": "0.2.18",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "bitfun-mobile-web",
-      "version": "0.2.17",
+      "version": "0.2.18",
       "dependencies": {
         "@noble/ciphers": "^2.1.1",
         "@noble/curves": "^2.0.1",
diff --git a/src/mobile-web/package.json b/src/mobile-web/package.json
index 5e65ede73c..b92e4e182e 100644
--- a/src/mobile-web/package.json
+++ b/src/mobile-web/package.json
@@ -1,6 +1,6 @@
 {
   "name": "bitfun-mobile-web",
-  "version": "0.2.17",
+  "version": "0.2.18",
   "private": true,
   "type": "module",
   "scripts": {
diff --git a/src/skin-market-web/package.json b/src/skin-market-web/package.json
index 7ccbbeb8f0..d57cc693ca 100644
--- a/src/skin-market-web/package.json
+++ b/src/skin-market-web/package.json
@@ -1,6 +1,6 @@
 {
   "name": "bitfun-skin-market-web",
-  "version": "0.2.17",
+  "version": "0.2.18",
   "private": true,
   "type": "module",
   "scripts": {
diff --git a/src/web-ui/AGENTS.md b/src/web-ui/AGENTS.md
index 29521f1f98..408e9182a2 100644
--- a/src/web-ui/AGENTS.md
+++ b/src/web-ui/AGENTS.md
@@ -75,10 +75,14 @@ Choose the smallest matching check:
 pnpm run i18n:audit
 pnpm run i18n:generate && pnpm run i18n:contract:test && pnpm run i18n:audit
 pnpm run type-check:web && pnpm --dir src/web-ui run test:run src/infrastructure/i18n/core/I18nService.test.ts
+pnpm run motion:audit
 pnpm run type-check:web
 ```
 
 Use the first line for resource-only locale changes, the second for
 contract/shared-term changes, the third for i18n runtime/namespace-loading
-changes, and the fourth for ordinary Web UI code. Rely on CI for full lint,
-build, and broad test coverage unless the local change specifically needs it.
+changes, the fourth for presentation or interaction-motion changes, and the
+fifth for ordinary Web UI code. The motion audit is an intent-review inventory,
+not a pass/fail gate; do not mechanically replace deliberate layout transitions
+or animate virtualized content. Rely on CI for full lint, build, and broad test
+coverage unless the local change specifically needs it.
diff --git a/src/web-ui/MOTION_AUDIT.md b/src/web-ui/MOTION_AUDIT.md
new file mode 100644
index 0000000000..a0ee6cb3e5
--- /dev/null
+++ b/src/web-ui/MOTION_AUDIT.md
@@ -0,0 +1,72 @@
+# BitFun Web UI 动效排查与优化清单
+
+本清单覆盖 `src/web-ui` 的桌面端与 Server/Web 共用 React 前端。排查对象包括按钮、输入控件、菜单、Tooltip、Select、弹窗、抽屉、页面/面板切换、列表增删与排序、拖拽、滚动导航、进度与异步状态，以及 Flow Chat 和工具面板中的交互反馈。
+
+## 三遍排查
+
+1. **全量静态扫描**：逐目录检查 `app`、`component-library`、`features`、`flow_chat`、`infrastructure`、`shared`、`tools` 中的交互处理器、CSS transition/keyframe、无限动画、滚动行为与 reduced-motion。
+2. **生命周期复查**：专查条件挂载、Portal、弹层 placement、快速重开、退出期数据快照、焦点与 `aria-hidden`/`inert`，以及列表删除、折叠、拖拽后的空间连续性。
+3. **独立反向审查**：用高标准动效 review 再查一遍 transform 所有权、键盘路径、焦点交接、异步竞态、虚拟列表滚动稳定性和无障碍降级；发现的阻断项修复后重新验证。
+
+可重复运行：
+
+```bash
+pnpm run motion:audit
+```
+
+该命令是意图清单，不机械替代人工判断。目前目标项均为 0：`transition: all`、`scale(0)`、未经审查的 JS smooth scroll、缺少局部 reduced-motion 的无限动画、重复全局 keyframe。
+
+首轮修改前的静态基线约为 590 个 TSX、348 个样式文件、1464 个交互处理器属性、190 处 `transition: all`、382 个 keyframe 定义和 13 组重名 keyframe。最终审计覆盖 2080 个生产源文件和 1593 个交互处理器属性；新增交互来自退出生命周期、焦点与键盘支持，不是装饰动画。
+
+## 优化清单
+
+| 区域 | 排查到的不丝滑点 | 已完成优化 |
+| --- | --- | --- |
+| 动效基础与组件原语 | 时长/曲线不统一；Button、Input、Card、Select 等大量 `transition: all`；hover 放大未限制精确指针；Tooltip 双重入场 | 统一更短的 motion token 与 decelerate 曲线；显式列出属性；hover 仅限 fine pointer；按下反馈约 `.97`；Tooltip 单一动效所有权 |
+| Modal、Popover、Select、菜单 | 上层条件卸载使 Modal 退出失效；自定义 overlay 只进不退；placement 翻转后方向错误；快速关闭/重开被 keyframe 抢占 | 新增共享 `PresenceBoundary`；Modal 调用方、自定义 overlay、Select、模型/推理/会话树弹层均保留退出态与最后快照；按实际 placement 设置 origin；改为可中断 transition；退出期 `inert`/`aria-hidden`；键盘打开即时 |
+| 通知与公告 | 通知删除和堆栈重排跳变；进度条动画 width；Feature modal 翻页 `display:none`；toast/弹窗退出计时不一致、动效过弹 | 通知退出 retention 与堆栈收拢；进度改 `scaleX`；公告弹窗/Toast 缩短并对齐计时；Feature modal 方向感知的 8px crossfade；退出禁交互并清理 timer |
+| Flow Chat | 选择器/文件弹层无退出；权限、运行状态、BTW 操作条瞬移；滚到底部控件闪现；TokenUsage 改高度/宽度；Pixel Pet 在 reduced-motion 下仍强行动画 | 补齐退出与焦点交接；权限快照绑定 session；BTW 退出期保留布局；运行状态固定槽 crossfade；高频滚动控件仅短 opacity；TokenUsage 固定 hitbox + `scaleX`；无限动效均有静止降级 |
+| 列表、折叠与配置 | Context/Todo/权限规则删除后空间跳变；配置 disclosure 只有入口；Nav 主 section 被覆盖为无动画；Todo 编辑器关闭时内容/高度突变 | Context 行稳定退出；Todo 编辑器/日期详情冻结完整数据并同步收起布局；权限规则增删与排序用可取消 FLIP；配置 disclosure 使用 grid presence；Nav section 恢复 150ms 收拢 |
+| 拖拽与排序 | Tab 与 Workspace 拖拽时邻项不让位、drop 后瞬移；Workspace drop line 作为 flex child 改变布局 | 拖动本体保持 1:1；邻项 120ms transform 让位；drop 后 160ms FLIP；drop line 改绝对定位，不再挤动列表 |
+| 工具与功能面板 | File Explorer 2s 高亮与全局 smooth scroll；Git Graph pulse/scale；编辑器光标/匹配项高频 pulse；生成 Widget 每个 DOM 节点入场；SSH/Relay/Peer picker 等退出缺失 | 高亮缩至 240ms；自动/键盘滚动即时、仅显式定位保留 RM-aware smooth；移除高频 pulse/scale；Widget 根级一次淡入；SSH/Relay/Peer、自定义 diff/branch overlay 补齐退出和竞态保护 |
+
+## 逐项落地索引
+
+| 状态 | 交互面 | 落地点 |
+| --- | --- | --- |
+| 完成 | 全局时长、曲线与 popup fallback | `app/styles/motion.scss`、Appearance motion tokens；组件自有 motion 可显式排除全局 fallback |
+| 完成 | Button、IconButton、Input、Textarea、NumberInput、Card、FilterPill | 移除 `transition: all`；限定变化属性；hover 只在 fine pointer 生效；按下反馈方向正确 |
+| 完成 | Tooltip、Select、Search、NavSearch | 去除 Tooltip 双重入场；Select placement-aware presence；键盘选项/搜索输入保持即时；warm tooltip 不排队 |
+| 完成 | 共享 Modal 调用方 | 首次打开后由 `PresenceBoundary` 保留 owner，让 Modal 自身 180ms 退出真正执行；快速重开取消卸载 |
+| 完成 | BranchSelect、Diff fullscreen、Peer directory picker | 自定义 overlay/surface 具备进出场、退出快照、焦点与异步竞态保护 |
+| 完成 | ContextMenu | placement origin、100ms 退出、退出期 inert；补齐 roving focus、方向键、Home/End、Enter/Space、Escape 与子菜单焦点返回 |
+| 完成 | Notification | Toast 退出 retention、焦点先移出再 inert、堆栈收拢；进度条由 width 改为 `scaleX` |
+| 完成 | Announcement Toast、Feature Modal | 取消过度 bounce/ghost 位移；hover 降幅并 gating；翻页方向感知；JS/CSS 退出计时对齐 |
+| 完成 | ModelSelector、ReasoningPreset、SessionTree、输入区弹层 | 根据实际 placement 决定位移和 origin；退出保留、快速重开、兄弟菜单清理与焦点返回 |
+| 完成 | Permission、BTW、RuntimeStatus | 会话切换不残留旧权限卡；操作条退出时不塌布局；运行状态使用固定槽 crossfade |
+| 完成 | ScrollToBottom、ScrollToLatest、TokenUsage | 高频控件只做短 opacity；退出前焦点回到消息滚动区；进度固定 hitbox + `scaleX` |
+| 完成 | ContextList | 连续删除保持稳定顺序；160ms 收拢后提交；unmount 不丢删除意图；reduced-motion 即时完成 |
+| 完成 | Todos editor、日期详情 | 保留完整 committed snapshot（含新建态）；内容与占位同步 160ms 收起；快速开关不闪旧数据 |
+| 完成 | Global permission rules | 新增 150ms；删除 retention 120ms；上下移动使用可取消 WAAPI FLIP 160ms；退出禁交互并安全移焦 |
+| 完成 | Config disclosure、Nav section | Grid presence 补齐收起；chevron 与内容同节奏；桌面 Nav 被覆盖的无动画规则恢复为 150ms |
+| 完成 | Tab 与 Workspace 拖拽 | 拖动物体 1:1；邻项 transform 让位；drop FLIP；drop indicator 绝对定位避免挤布局 |
+| 完成 | Update 与通知进度 | determinate 全部 `scaleX`；indeterminate 保留状态表达，reduced-motion 下静止可见 |
+| 完成 | File Explorer、Git Graph、Generative Widget | 去除 2s paint、自动 smooth、pulse/scale 和逐 DOM 节点入场；只保留一次根级反馈 |
+| 完成 | SSH、Relay、Dispatch、Canvas、Terminal、Git/Editor 工具 | 弹层退出补齐；generic keyframe 命名空间化；无限 spinner/pulse 均有局部 reduced-motion 静止态 |
+| 完成 | Markdown、FlowChat tool cards、CodeEditor | 删除挂载 fade 与高频光标/匹配 pulse；虚拟/流式内容不因重挂载重复播放 |
+
+## 明确不增加的动效
+
+- 虚拟化消息行、流式 Markdown、工具卡挂载不做 fade/slide，避免滚动锚点与高度估算抖动。
+- 键盘重复导航、搜索输入、Select option highlight、warm tooltip 保持即时。
+- drag/resize 本体严格跟手，不加 easing；只让受影响的邻项和 drop settle 动。
+- 场景快捷键切换不等待长退出；高频滚动按钮不做位移/弹簧入场。
+- indeterminate loading 可继续表达“进行中”，但 reduced-motion 下必须静止且保持可见。
+
+## 默认参数
+
+- 直接反馈：80–120ms。
+- 弹层/列表空间连续性：120–180ms。
+- 大型 Modal：进入约 180–220ms，退出约 120–180ms。
+- 位移通常 2–8px，scale 通常不低于 `.985`；不用 `scale(0)`。
+- reduced-motion：取消位移、旋转、pulse 与滚动动画；必要时只保留不超过约 100ms 的 opacity。
diff --git a/src/web-ui/README.md b/src/web-ui/README.md
index d34663fd20..0c5c51d0a3 100644
--- a/src/web-ui/README.md
+++ b/src/web-ui/README.md
@@ -94,6 +94,7 @@ VITE_BUILD_TARGET=web pnpm --dir src/web-ui run build
 ## Related docs (within this package)
 
 - [Logging guide](LOGGING.md)
+- [Motion audit and optimization checklist](MOTION_AUDIT.md)
 - [Component library README](src/component-library/README.md)
 - [i18n README](src/infrastructure/i18n/README.md)
 
diff --git a/src/web-ui/package.json b/src/web-ui/package.json
index cf4d323ced..6f5ee86ad8 100644
--- a/src/web-ui/package.json
+++ b/src/web-ui/package.json
@@ -1,13 +1,13 @@
 {
   "name": "@bitfun/web-ui",
-  "version": "0.2.17",
+  "version": "0.2.18",
   "private": true,
   "description": "BitFun Web UI - 支持 Desktop 和 Server 两种部署方式",
   "type": "module",
   "scripts": {
     "dev": "vite",
     "dev:force": "vite --force",
-    "gen:types": "cargo test --package bitfun-app-server-protocol --features ts export -- --nocapture && cargo test --package bitfun-app-server --features ts --no-default-features export -- --nocapture && node scripts/gen-api-barrel.mjs",
+    "gen:types": "node scripts/gen-api-barrel.mjs --clean && cargo test --locked --package bitfun-app-server-protocol --no-default-features --features ts --lib export -- --nocapture && node scripts/gen-api-barrel.mjs",
     "build": "vite build",
     "build:desktop": "vite build --mode desktop",
     "build:web": "vite build --mode web",
@@ -61,7 +61,7 @@
     "react-i18next": "^16.5.3",
     "react-markdown": "^10.1.0",
     "react-syntax-highlighter": "^15.6.6",
-    "react-virtuoso": "^4.14.1",
+    "react-virtuoso": "^4.18.11",
     "rehype-katex": "^7.0.1",
     "rehype-raw": "^7.0.0",
     "rehype-sanitize": "^6.0.0",
diff --git a/src/web-ui/scripts/gen-api-barrel.mjs b/src/web-ui/scripts/gen-api-barrel.mjs
index 7f32f0423d..00de698f4f 100644
--- a/src/web-ui/scripts/gen-api-barrel.mjs
+++ b/src/web-ui/scripts/gen-api-barrel.mjs
@@ -1,17 +1,23 @@
 // Generates src/generated/api/index.ts — a barrel re-exporting every
 // ts-rs-generated type. Run after `cargo test ... export` (gen:types).
 // Generated files are gitignored; this barrel is regenerated alongside them.
-import { readdir, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, rm, writeFile } from 'node:fs/promises';
 import { join, basename, extname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const here = fileURLToPath(new URL('.', import.meta.url));
 const dir = join(here, '..', 'src', 'generated', 'api');
 
+if (process.argv.includes('--clean')) {
+  await rm(dir, { recursive: true, force: true });
+  await mkdir(dir, { recursive: true });
+  process.exit(0);
+}
+
 const header = `// GENERATED CODE! DO NOT MODIFY BY HAND!
 //
-// Source: src/crates/interfaces/app-server/src/schema/ (+ upstream contract
-// crates), exported via ts-rs (#[ts(export)], run by \`npm run gen:types\`).
+// Source: bitfun-app-server-protocol (+ stable contract crates), exported via
+// ts-rs (#[ts(export)], run by \`npm run gen:types\`).
 // This barrel re-exports every generated type so consumers can import from a
 // single path: \`import type { SubmitDialogTurnBody } from '@/generated/api'\`.
 //
@@ -24,9 +30,25 @@ const files = (await readdir(dir, { withFileTypes: true }))
   .sort();
 
 const requiredTypes = [
+  'AgentSessionArchiveStateRequest',
+  'AgentSessionForkAtTurnRequest',
   'ConfigUpdate',
+  'ForkSessionResponse',
+  'GitBranch',
+  'GitRepositoryPathRequest',
+  'ListSessionsResponse',
+  'PermissionGrant',
+  'PermissionReply',
+  'RemoveProjectPermissionGrantResponse',
+  'ResetAgentProfileConfigMessage',
+  'ResetAgentProfileConfigResponse',
+  'RunResponse',
   'SaveCloudSpeechConfigRequest',
   'SaveCloudSpeechConfigResult',
+  'SetAgentProfileConfigMessage',
+  'SetAgentProfileConfigResponse',
+  'SubmitDialogTurnBody',
+  'SubmitDialogTurnResponse',
 ];
 const missingTypes = requiredTypes.filter((typeName) => !files.includes(typeName));
 if (missingTypes.length > 0) {
diff --git a/src/web-ui/src/app/App.tsx b/src/web-ui/src/app/App.tsx
index 4a5b190778..889bd4b6ff 100644
--- a/src/web-ui/src/app/App.tsx
+++ b/src/web-ui/src/app/App.tsx
@@ -10,6 +10,7 @@ import { NotificationContainer, notificationService } from '../shared/notificati
 import { NotificationCenter } from '../shared/notification-system/components/NotificationCenter';
 import { AnnouncementProvider } from '../shared/announcement-system';
 import { ConfirmDialogRenderer } from '../component-library';
+import { SessionUsageModal } from '../flow_chat/components/usage/SessionUsageModal';
 import { createLogger } from '@/shared/utils/logger';
 import { startupTrace } from '@/shared/utils/startupTrace';
 import { isTauriRuntime } from '@/infrastructure/runtime';
@@ -898,6 +899,11 @@ function App() {
             {/* Confirm dialog */}
             <ConfirmDialogRenderer />
 
+            {/* Session usage report. Mounted here rather than in a chat view:
+                the request runs below any component, and the report outlives
+                whichever session view is on screen. */}
+            <SessionUsageModal />
+
             {/* Announcement / feature-demo / tips system */}
             <AnnouncementProvider />
 
diff --git a/src/web-ui/src/app/components/AboutDialog/AboutDialog.scss b/src/web-ui/src/app/components/AboutDialog/AboutDialog.scss
index 8d047f39e4..d916f727b4 100644
--- a/src/web-ui/src/app/components/AboutDialog/AboutDialog.scss
+++ b/src/web-ui/src/app/components/AboutDialog/AboutDialog.scss
@@ -440,7 +440,7 @@
 
   svg {
     color: var(--bf-appearance-token-color-text-muted);
-    transition: all 0.2s ease;
+    transition: color 0.2s ease;
   }
 }
 
@@ -688,3 +688,10 @@
     padding: 12px 24px 14px;
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .bitfun-about-dialog__download-fill--indeterminate {
+    animation: none;
+    transform: none;
+  }
+}
diff --git a/src/web-ui/src/app/components/AgentCompanionDesktopPet/AgentCompanionDesktopPet.scss b/src/web-ui/src/app/components/AgentCompanionDesktopPet/AgentCompanionDesktopPet.scss
index d324d146c9..da08e38196 100644
--- a/src/web-ui/src/app/components/AgentCompanionDesktopPet/AgentCompanionDesktopPet.scss
+++ b/src/web-ui/src/app/components/AgentCompanionDesktopPet/AgentCompanionDesktopPet.scss
@@ -549,3 +549,13 @@
     transform: scale(1.08);
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .bitfun-agent-companion__pet--needs-attention::before,
+  .bitfun-agent-companion__bubble--typing::after,
+  .bitfun-agent-companion__bubble--attention,
+  .bitfun-agent-companion__bubble--attention::after {
+    animation: none !important;
+    transform: none;
+  }
+}
diff --git a/src/web-ui/src/app/components/NavPanel/MainNav.tsx b/src/web-ui/src/app/components/NavPanel/MainNav.tsx
index 1b93c15498..9297855288 100644
--- a/src/web-ui/src/app/components/NavPanel/MainNav.tsx
+++ b/src/web-ui/src/app/components/NavPanel/MainNav.tsx
@@ -14,7 +14,7 @@
 import React, { useCallback, useState, useMemo, useEffect, useRef } from 'react';
 import { createPortal } from 'react-dom';
 import { getAppearanceOverlayHost } from '@/infrastructure/appearance/runtime/AppearanceOverlayHost';
-import { Plus, FolderOpen, FolderPlus, History, Check, User, Users, Puzzle, Blocks, ChevronDown, Search } from 'lucide-react';
+import { Plus, FolderOpen, FolderPlus, History, Check, User, Users, Puzzle, Blocks, CalendarClock, ChevronDown, Search } from 'lucide-react';
 // import { PanelsTopLeft } from 'lucide-react'; // temporarily hidden: Pages nav entry
 import { Tooltip } from '@/component-library';
 import { useApp } from '../../hooks/useApp';
@@ -395,6 +395,10 @@ const MainNav: React.FC<MainNavProps> = ({
     switchLeftPanelTab,
   ]);
 
+  const handleOpenTodos = useCallback(() => {
+    openScene('todos');
+  }, [openScene]);
+
   const handleOpenAgents = useCallback(() => {
     openScene('agents');
   }, [openScene]);
@@ -506,8 +510,10 @@ const MainNav: React.FC<MainNavProps> = ({
   const createCodeTooltip = t('nav.sessions.newCodeSession');
   const createCoworkTooltip = t('nav.sessions.newCoworkSession');
   const assistantTooltip = t('nav.items.persona');
+  const todosTooltip = t('nav.tooltips.todos');
   const addWorkspaceTooltip = t('nav.tooltips.addWorkspace');
   const isAssistantActive = activeTabId === 'assistant';
+  const isTodosActive = activeTabId === 'todos';
   const agentsTooltip = t('nav.tooltips.agents');
   const skillsTooltip = t('nav.tooltips.skills');
   const extensionsLabel = t('nav.sections.extensions');
@@ -597,6 +603,25 @@ const MainNav: React.FC<MainNavProps> = ({
           </button>
         </Tooltip>
 
+        <Tooltip content={todosTooltip} placement="right" followCursor>
+          <button
+            type="button"
+            className={`bitfun-nav-panel__top-action-btn${isTodosActive ? ' is-active' : ''}`}
+            data-bf-component="nav-panel"
+            data-bf-part="topAction"
+            data-bf-action="todos"
+            data-bf-state={isTodosActive ? 'active' : ''}
+            onClick={handleOpenTodos}
+            aria-label={todosTooltip}
+            data-testid="nav-todos-btn"
+          >
+            <span className="bitfun-nav-panel__top-action-icon-slot" aria-hidden="true">
+              <CalendarClock size={15} />
+            </span>
+            <span>{t('nav.items.todos')}</span>
+          </button>
+        </Tooltip>
+
         <div className="bitfun-nav-panel__top-action-expand" data-bf-component="nav-panel" data-bf-part="extensionGroup" data-bf-state={isExtensionsOpen ? 'open' : ''} data-testid="agent-skill-panel">
           <Tooltip content={extensionsLabel} placement="right" followCursor>
             <button
diff --git a/src/web-ui/src/app/components/NavPanel/NavPanel.scss b/src/web-ui/src/app/components/NavPanel/NavPanel.scss
index 14dd94dc19..1540c4c2da 100644
--- a/src/web-ui/src/app/components/NavPanel/NavPanel.scss
+++ b/src/web-ui/src/app/components/NavPanel/NavPanel.scss
@@ -62,40 +62,40 @@ $_section-header-height: 24px;
       flex: 1 1 auto;
       min-width: 0;
       max-width: 100%;
-      transition: opacity 0.2s $easing-standard;
+      opacity: 1;
+      transform: translate3d(0, 0, 0);
+      transition: none;
 
-      // Non-split scenes: hide MainNav instantly when scene nav opens
+      // Non-split scenes move as a coordinated pair when pointer motion is on.
       .is-scene:not(.is-split-open) & {
         opacity: 0;
+        transform: translate3d(-4px, 0, 0);
         pointer-events: none;
       }
     }
 
     // 鈹€鈹€ SceneNav overlay 鈹€鈹€
     &--scene {
-      clip-path: inset(var(--clip-origin-top) 0 var(--clip-origin-bottom) 0);
-      transition: clip-path $motion-base $easing-decelerate,
-                  opacity $motion-fast $easing-decelerate;
+      clip-path: inset(0 0 0 0);
       position: absolute;
       inset: 0;
       z-index: 1;
       pointer-events: none;
-        clip-path: inset(0 0 0 0);
       opacity: 0;
+      transform: translate3d(6px, 0, 0);
       background: var(--bf-appearance-token-color-bg-primary);
-
-      // Default transition for non-split scenes: simple fade
-      transition: opacity 0.25s $easing-decelerate;
+      transition: none;
 
       &.is-active {
         pointer-events: auto;
         opacity: 1;
+        transform: translate3d(0, 0, 0);
       }
 
       // Split-open scenes (file-viewer): clip-path reveal from anchor.
       // The opaque background ensures revealed portions fully cover MainNav
       // so departing items never bleed through.
-      .is-split-open & {
+      .is-split-open.has-pointer-motion & {
         clip-path: inset(var(--clip-origin-top) 0 var(--clip-origin-bottom) 0);
         transition: clip-path 0.26s cubic-bezier(0.22, 1, 0.36, 1),
                     opacity 0.06s linear;
@@ -107,6 +107,39 @@ $_section-header-height: 24px;
     }
   }
 
+  &__content.has-pointer-motion &__layer--main {
+    transition:
+      opacity 140ms cubic-bezier(0.23, 1, 0.32, 1),
+      transform 180ms cubic-bezier(0.23, 1, 0.32, 1);
+  }
+
+  &__content.has-pointer-motion:not(.is-split-open) &__layer--scene {
+    transition:
+      opacity 160ms cubic-bezier(0.23, 1, 0.32, 1),
+      transform 180ms cubic-bezier(0.23, 1, 0.32, 1);
+
+    &.is-active {
+      @starting-style {
+        opacity: 0;
+        transform: translate3d(6px, 0, 0);
+      }
+    }
+  }
+
+  &__scene-transition {
+    display: flex;
+    flex: 1 1 auto;
+    min-width: 0;
+    min-height: 0;
+
+    > .bitfun-view-transition-boundary__view {
+      display: flex;
+      flex: 1 1 auto;
+      min-width: 0;
+      min-height: 0;
+    }
+  }
+
   &__scene-inner {
     flex: 1 1 auto;
     min-height: 0;
@@ -2091,7 +2124,12 @@ $_section-header-height: 24px;
   padding: 7px 16px;
   font-size: var(--bf-appearance-token-font-size-xs);
   cursor: pointer;
-  transition: all $motion-fast $easing-standard;
+  transition:
+    background-color $motion-fast $easing-standard,
+    border-color $motion-fast $easing-standard,
+    color $motion-fast $easing-standard,
+    opacity $motion-fast $easing-standard,
+    transform $motion-fast $easing-standard;
 }
 
 .bitfun-nav-panel__remote-disclaimer-btn--secondary {
@@ -2126,7 +2164,6 @@ $_section-header-height: 24px;
     &__item-icon,
     &__section,
     &__section-label,
-    &__layer--scene,
     &__collapsible,
     &__mode-pill,
     &__mode-pill-liquid,
@@ -2138,6 +2175,24 @@ $_section-header-height: 24px;
       clip-path: none;
       filter: none;
     }
+
+    &__layer--main,
+    &__layer--scene {
+      transform: none;
+    }
+
+    &__content.has-pointer-motion &__layer--main,
+    &__content.has-pointer-motion:not(.is-split-open) &__layer--scene {
+      transform: none;
+      transition: opacity 100ms cubic-bezier(0.23, 1, 0.32, 1);
+    }
+
+    &__content.has-pointer-motion:not(.is-split-open) &__layer--scene.is-active {
+      @starting-style {
+        opacity: 0;
+        transform: none;
+      }
+    }
   }
 
   .bitfun-nav-panel__top-action-icon-circle {
@@ -2494,7 +2549,10 @@ $_section-header-height: 24px;
     }
   }
 
-  &__collapsible,
+  &__collapsible {
+    transition: grid-template-rows 150ms cubic-bezier(0.23, 1, 0.32, 1);
+  }
+
   &__item-slot {
     transition: none;
 
diff --git a/src/web-ui/src/app/components/NavPanel/NavPanel.tsx b/src/web-ui/src/app/components/NavPanel/NavPanel.tsx
index 1e12206e14..0a3bc03722 100644
--- a/src/web-ui/src/app/components/NavPanel/NavPanel.tsx
+++ b/src/web-ui/src/app/components/NavPanel/NavPanel.tsx
@@ -8,8 +8,9 @@
  *     item while SceneNav is revealed via clip-path expanding from the
  *     anchor's Y position. Both layers coexist in the DOM (overlay).
  *
- *   All other scenes (settings, …):
- *     Simple crossfade — MainNav hidden instantly, SceneNav fades in.
+ *   All other pointer-opened scenes (settings, …):
+ *     MainNav and SceneNav use a short paired crossfade/translation. Keyboard
+ *     and programmatic navigation stay immediate.
  *
  * MainNav is always mounted so its state is preserved across transitions.
  */
@@ -26,9 +27,11 @@ import { useI18n } from '@/infrastructure/i18n';
 import { useNavSceneStore } from '../../stores/navSceneStore';
 import { getSceneNav, preloadSceneNav } from '../../scenes/nav-registry';
 import type { SceneTabId } from '../SceneBar/types';
+import { ViewTransitionBoundary } from '@/component-library';
+import type { InteractionMotion } from '@/shared/utils/motionPreference';
 import MainNav from './MainNav';
 import PersistentFooterActions from './components/PersistentFooterActions';
-import { PeerRemoteBadge } from '@/infrastructure/peer-device/PeerRemoteBadge';
+import { DeviceSurfaceSwitcher } from '@/infrastructure/peer-device/DeviceSurfaceSwitcher';
 import './NavPanel.scss';
 
 /** Scenes that use the split-open accordion transition. */
@@ -45,8 +48,10 @@ const NavPanel: React.FC<NavPanelProps> = ({ className = '' }) => {
   const { t } = useI18n('common');
   const showSceneNav = useNavSceneStore(s => s.showSceneNav);
   const navSceneId = useNavSceneStore(s => s.navSceneId);
+  const navigationMotion = useNavSceneStore(s => s.navigationMotion);
 
   const [mountedSceneId, setMountedSceneId] = useState<SceneTabId | null>(navSceneId);
+  const [mountedSceneMotion, setMountedSceneMotion] = useState<InteractionMotion>(navigationMotion);
   const sceneRequestRef = useRef(0);
   useEffect(() => {
     const requestId = ++sceneRequestRef.current;
@@ -56,10 +61,13 @@ const NavPanel: React.FC<NavPanelProps> = ({ className = '' }) => {
       if (sceneRequestRef.current !== requestId) return;
       // React keeps the currently painted navigation visible if the cached
       // lazy component still suspends for a final promise microtask.
-      startTransition(() => setMountedSceneId(navSceneId));
+      startTransition(() => {
+        setMountedSceneId(navSceneId);
+        setMountedSceneMotion(navigationMotion);
+      });
     };
     void preloadSceneNav(navSceneId).then(commit, commit);
-  }, [navSceneId]);
+  }, [navSceneId, navigationMotion]);
 
   const SceneNavComponent = mountedSceneId ? getSceneNav(mountedSceneId) : null;
 
@@ -96,6 +104,7 @@ const NavPanel: React.FC<NavPanelProps> = ({ className = '' }) => {
     'bitfun-nav-panel__content',
     hasMountedSceneNav && 'is-scene',
     useSplitOpen && 'is-split-open',
+    (showSceneNav ? mountedSceneMotion : navigationMotion) === 'pointer' && 'has-pointer-motion',
   ].filter(Boolean).join(' ');
 
   const sceneCls = [
@@ -128,15 +137,22 @@ const NavPanel: React.FC<NavPanelProps> = ({ className = '' }) => {
         {SceneNavComponent && (
           <div className={sceneCls} data-bf-component="nav-panel" data-bf-part="sceneLayer" data-bf-layer="scene" data-bf-state={showSceneNav ? 'active' : ''}>
             <Suspense fallback={null}>
-              <div key={mountedSceneId} className="bitfun-nav-panel__scene-inner" data-bf-component="nav-panel" data-bf-part="sceneContent">
+              <ViewTransitionBoundary
+                viewKey={mountedSceneId ?? 'main'}
+                animate={showSceneNav && mountedSceneMotion === 'pointer'}
+                className="bitfun-nav-panel__scene-transition"
+                viewClassName="bitfun-nav-panel__scene-inner"
+                data-bf-component="nav-panel"
+                data-bf-part="sceneContent"
+              >
                 <SceneNavComponent />
-              </div>
+              </ViewTransitionBoundary>
             </Suspense>
           </div>
         )}
 
       </div>
-      <PeerRemoteBadge />
+      <DeviceSurfaceSwitcher />
       <PersistentFooterActions />
     </nav>
   );
diff --git a/src/web-ui/src/app/components/NavPanel/NavSearchDialog.scss b/src/web-ui/src/app/components/NavPanel/NavSearchDialog.scss
index cf38e183b4..6ee67abef1 100644
--- a/src/web-ui/src/app/components/NavPanel/NavSearchDialog.scss
+++ b/src/web-ui/src/app/components/NavPanel/NavSearchDialog.scss
@@ -34,7 +34,6 @@
   display: flex;
   flex-direction: column;
   max-height: calc(100vh - 120px);
-  animation: bitfun-nav-search-card-in 0.28s cubic-bezier(0.22, 1, 0.36, 1) both;
 }
 
 :root[data-bf-appearance-mode='light'] .bitfun-nav-search-dialog__card {
@@ -122,7 +121,6 @@
   text-align: center;
   color: var(--bf-appearance-token-color-text-muted);
   font-size: var(--bf-appearance-token-font-size-sm);
-  animation: bitfun-nav-search-fade-rise 0.32s cubic-bezier(0.22, 1, 0.36, 1) 0.06s both;
 }
 
 .bitfun-nav-search-dialog__group {
diff --git a/src/web-ui/src/app/components/NavPanel/appearance.ts b/src/web-ui/src/app/components/NavPanel/appearance.ts
index cf8ed757e3..1f147067c9 100644
--- a/src/web-ui/src/app/components/NavPanel/appearance.ts
+++ b/src/web-ui/src/app/components/NavPanel/appearance.ts
@@ -34,7 +34,7 @@ export const navPanelAppearanceDescriptor: AppearanceSurfaceDescriptor = {
   ],
   facets: [
     { id: 'layer', attribute: 'data-bf-layer', values: ['main', 'scene'] },
-    { id: 'action', attribute: 'data-bf-action', values: ['code', 'cowork', 'assistant', 'extensions', 'agents', 'skills'] },
+    { id: 'action', attribute: 'data-bf-action', values: ['code', 'cowork', 'assistant', 'todos', 'extensions', 'agents', 'skills'] },
     { id: 'section', attribute: 'data-bf-section', values: ['assistant-sessions', 'workspace'] },
   ],
   states: [
diff --git a/src/web-ui/src/app/components/NavPanel/components/PersistentFooterActions.tsx b/src/web-ui/src/app/components/NavPanel/components/PersistentFooterActions.tsx
index 188f55b206..0243e1f314 100644
--- a/src/web-ui/src/app/components/NavPanel/components/PersistentFooterActions.tsx
+++ b/src/web-ui/src/app/components/NavPanel/components/PersistentFooterActions.tsx
@@ -14,8 +14,8 @@ import {
   ChevronUp,
   MessageSquare,
 } from 'lucide-react';
+import { Tooltip, Modal, PresenceBoundary } from '@/component-library';
 import { systemAPI } from '@/infrastructure/api';
-import { Tooltip, Modal } from '@/component-library';
 import { useI18n } from '@/infrastructure/i18n/hooks/useI18n';
 import { useSceneManager } from '../../../hooks/useSceneManager';
 import { useNavSceneStore } from '../../../stores/navSceneStore';
@@ -427,18 +427,18 @@ const PersistentFooterActions: React.FC = () => {
           <NotificationButton className="bitfun-nav-panel__footer-btn" navFooterHoverIconSwap />
         </div>
       </div>
-      {showAbout && (
+      <PresenceBoundary active={showAbout}>
         <Suspense fallback={null}>
           <AboutDialog isOpen={showAbout} onClose={() => setShowAbout(false)} />
         </Suspense>
-      )}
-      {showFeedback && (
+      </PresenceBoundary>
+      <PresenceBoundary active={showFeedback}>
         <Suspense fallback={null}>
           <FeedbackDialog isOpen={showFeedback} onClose={() => setShowFeedback(false)} />
         </Suspense>
-      )}
+      </PresenceBoundary>
       {/* BitFun account login dialog is intentionally disabled. */}
-      {showRemoteConnect && (
+      <PresenceBoundary active={showRemoteConnect}>
         <Suspense fallback={null}>
           <RemoteConnectDialog
             isOpen={showRemoteConnect}
@@ -446,7 +446,7 @@ const PersistentFooterActions: React.FC = () => {
             initialGroup={remoteInitialGroup}
           />
         </Suspense>
-      )}
+      </PresenceBoundary>
       <Modal
         isOpen={showRemoteDisclaimer}
         onClose={() => setShowRemoteDisclaimer(false)}
diff --git a/src/web-ui/src/app/components/NavPanel/sections/sessions/SessionsSection.tsx b/src/web-ui/src/app/components/NavPanel/sections/sessions/SessionsSection.tsx
index 0b94d08d35..2bba591eee 100644
--- a/src/web-ui/src/app/components/NavPanel/sections/sessions/SessionsSection.tsx
+++ b/src/web-ui/src/app/components/NavPanel/sections/sessions/SessionsSection.tsx
@@ -8,7 +8,7 @@
 import React, { lazy, Suspense, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { createPortal } from 'react-dom';
 import { Pencil, Trash2, Check, X, Bot, Code2, ClipboardList, Panda, MoreHorizontal, Loader2, Archive, Clock3, Copy, CircleHelp, FileDown, ChevronLeft } from 'lucide-react';
-import { IconButton, Input, Tooltip } from '@/component-library';
+import { IconButton, Input, PresenceBoundary, Tooltip } from '@/component-library';
 import { useI18n } from '@/infrastructure/i18n';
 import { flowChatStore } from '../../../../../flow_chat/store/FlowChatStore';
 import { flowChatManager } from '../../../../../flow_chat/services/FlowChatManager';
@@ -793,6 +793,11 @@ const SessionsSection: React.FC<SessionsSectionProps> = ({
   const scheduledJobsSession = scheduledJobsSessionId
     ? flowChatState.sessions.get(scheduledJobsSessionId) ?? null
     : null;
+  const lastScheduledJobsSessionRef = useRef<Session | null>(null);
+  if (scheduledJobsSession) {
+    lastScheduledJobsSessionRef.current = scheduledJobsSession;
+  }
+  const retainedScheduledJobsSession = scheduledJobsSession ?? lastScheduledJobsSessionRef.current;
   const lastHistoryOpenIntentRef = useRef<{ sessionId: string; atMs: number } | null>(null);
 
   const dispatchHistoryOpenIntentForSession = useCallback(
@@ -1726,24 +1731,26 @@ const SessionsSection: React.FC<SessionsSectionProps> = ({
         </button>
       )}
 
-      {scheduledJobsSession && (
-        <Suspense fallback={null}>
-          <ScheduledJobsModal
-            isOpen={scheduledJobsSession != null}
-            onClose={() => setScheduledJobsSessionId(null)}
-            workspacePath={scheduledJobsSession.workspacePath || workspacePath}
-            workspaceId={scheduledJobsSession.workspaceId || workspaceId}
-            remoteConnectionId={scheduledJobsSession.remoteConnectionId || remoteConnectionId}
-            remoteSshHost={scheduledJobsSession.remoteSshHost || remoteSshHost}
-            sessionId={scheduledJobsSession.sessionId}
-            targetKind="session"
-            lockSessionId
-            title={t('nav.scheduledJobs.title')}
-            targetLabel={resolveSessionTitle(scheduledJobsSession)}
-            targetDescription={scheduledJobsSession.workspacePath || workspacePath}
-          />
-        </Suspense>
-      )}
+      <PresenceBoundary active={scheduledJobsSession != null}>
+        {retainedScheduledJobsSession && (
+          <Suspense fallback={null}>
+            <ScheduledJobsModal
+              isOpen={scheduledJobsSession != null}
+              onClose={() => setScheduledJobsSessionId(null)}
+              workspacePath={retainedScheduledJobsSession.workspacePath || workspacePath}
+              workspaceId={retainedScheduledJobsSession.workspaceId || workspaceId}
+              remoteConnectionId={retainedScheduledJobsSession.remoteConnectionId || remoteConnectionId}
+              remoteSshHost={retainedScheduledJobsSession.remoteSshHost || remoteSshHost}
+              sessionId={retainedScheduledJobsSession.sessionId}
+              targetKind="session"
+              lockSessionId
+              title={t('nav.scheduledJobs.title')}
+              targetLabel={resolveSessionTitle(retainedScheduledJobsSession)}
+              targetDescription={retainedScheduledJobsSession.workspacePath || workspacePath}
+            />
+          </Suspense>
+        )}
+      </PresenceBoundary>
     </div>
   );
 };
diff --git a/src/web-ui/src/app/components/NavPanel/sections/workspaces/WorkspaceItem.tsx b/src/web-ui/src/app/components/NavPanel/sections/workspaces/WorkspaceItem.tsx
index 14810e123c..9075060c6b 100644
--- a/src/web-ui/src/app/components/NavPanel/sections/workspaces/WorkspaceItem.tsx
+++ b/src/web-ui/src/app/components/NavPanel/sections/workspaces/WorkspaceItem.tsx
@@ -3,7 +3,7 @@ import { createPortal } from 'react-dom';
 import { Folder, FolderOpen, MoreHorizontal, FolderSearch, Plus, ChevronDown, Trash2, RotateCcw, Copy, FileText, Bot, Link2, ListChecks, Loader2, Clock3, ShieldCheck, Pencil, Server } from 'lucide-react';
 import { useTranslation } from 'react-i18next';
 import { DotMatrixArrowRightIcon } from './DotMatrixArrowRightIcon';
-import { Button, ConfirmDialog, InputDialog, Modal, Tooltip } from '@/component-library';
+import { Button, ConfirmDialog, InputDialog, Modal, PresenceBoundary, Tooltip } from '@/component-library';
 import { useI18n } from '@/infrastructure/i18n';
 import { getAppearanceOverlayHost } from '@/infrastructure/appearance/runtime/AppearanceOverlayHost';
 import { aiExperienceConfigService } from '@/infrastructure/config/services/AIExperienceConfigService';
@@ -1069,7 +1069,7 @@ const WorkspaceItem: React.FC<WorkspaceItemProps> = ({
           confirmDanger
           preview={`${t('nav.workspaces.resetWorkspaceDialog.pathLabel')}\n${workspace.rootPath}`}
         />
-        {scheduledJobsModalOpen && (
+        <PresenceBoundary active={scheduledJobsModalOpen}>
           <Suspense fallback={null}>
             <ScheduledJobsModal
               isOpen={scheduledJobsModalOpen}
@@ -1085,8 +1085,8 @@ const WorkspaceItem: React.FC<WorkspaceItemProps> = ({
               targetDescription={workspace.rootPath}
             />
           </Suspense>
-        )}
-        {projectPermissionsDialogOpen && (
+        </PresenceBoundary>
+        <PresenceBoundary active={projectPermissionsDialogOpen}>
           <Suspense fallback={null}>
             <WorkspaceProjectPermissionsDialog
               workspace={workspace}
@@ -1094,7 +1094,7 @@ const WorkspaceItem: React.FC<WorkspaceItemProps> = ({
               onClose={() => setProjectPermissionsDialogOpen(false)}
             />
           </Suspense>
-        )}
+        </PresenceBoundary>
       </div>
     );
   }
@@ -1590,16 +1590,16 @@ const WorkspaceItem: React.FC<WorkspaceItemProps> = ({
         required={false}
       />
       <ConfirmDialog
-        isOpen={deleteWorkspaceDialogOpen}
-        onClose={() => setDeleteWorkspaceDialogOpen(false)}
-        onConfirm={() => { void handleConfirmDeleteWorkspace(); }}
-        title={t('nav.workspaces.deleteWorkspaceDialog.title', { name: workspaceDisplayName })}
-        message={t('nav.workspaces.deleteWorkspaceDialog.message')}
-        confirmText={t('nav.workspaces.actions.deleteWorkspace')}
-        cancelText={t('actions.cancel')}
-        confirmDanger
+          isOpen={deleteWorkspaceDialogOpen}
+          onClose={() => setDeleteWorkspaceDialogOpen(false)}
+          onConfirm={() => { void handleConfirmDeleteWorkspace(); }}
+          title={t('nav.workspaces.deleteWorkspaceDialog.title', { name: workspaceDisplayName })}
+          message={t('nav.workspaces.deleteWorkspaceDialog.message')}
+          confirmText={t('nav.workspaces.actions.deleteWorkspace')}
+          cancelText={t('actions.cancel')}
+          confirmDanger
       />
-      {relatedPathsDialogOpen && (
+      <PresenceBoundary active={relatedPathsDialogOpen}>
         <Suspense fallback={null}>
           <WorkspaceRelatedPathsDialog
             workspace={workspace}
@@ -1607,8 +1607,8 @@ const WorkspaceItem: React.FC<WorkspaceItemProps> = ({
             onClose={() => setRelatedPathsDialogOpen(false)}
           />
         </Suspense>
-      )}
-      {projectPermissionsDialogOpen && (
+      </PresenceBoundary>
+      <PresenceBoundary active={projectPermissionsDialogOpen}>
         <Suspense fallback={null}>
           <WorkspaceProjectPermissionsDialog
             workspace={workspace}
@@ -1616,8 +1616,8 @@ const WorkspaceItem: React.FC<WorkspaceItemProps> = ({
             onClose={() => setProjectPermissionsDialogOpen(false)}
           />
         </Suspense>
-      )}
-      {sessionBatchModalOpen && (
+      </PresenceBoundary>
+      <PresenceBoundary active={sessionBatchModalOpen}>
         <Suspense fallback={null}>
           <WorkspaceSessionBatchModal
             isOpen={sessionBatchModalOpen}
@@ -1628,8 +1628,8 @@ const WorkspaceItem: React.FC<WorkspaceItemProps> = ({
             remoteSshHost={isRemoteWorkspace(workspace) ? workspace.sshHost : null}
           />
         </Suspense>
-      )}
-      {scheduledJobsModalOpen && (
+      </PresenceBoundary>
+      <PresenceBoundary active={scheduledJobsModalOpen}>
         <Suspense fallback={null}>
           <ScheduledJobsModal
             isOpen={scheduledJobsModalOpen}
@@ -1645,7 +1645,7 @@ const WorkspaceItem: React.FC<WorkspaceItemProps> = ({
             targetDescription={workspace.rootPath}
           />
         </Suspense>
-      )}
+      </PresenceBoundary>
     </div>
   );
 };
diff --git a/src/web-ui/src/app/components/NavPanel/sections/workspaces/WorkspaceListSection.scss b/src/web-ui/src/app/components/NavPanel/sections/workspaces/WorkspaceListSection.scss
index 7e4760cdbc..fec867bb25 100644
--- a/src/web-ui/src/app/components/NavPanel/sections/workspaces/WorkspaceListSection.scss
+++ b/src/web-ui/src/app/components/NavPanel/sections/workspaces/WorkspaceListSection.scss
@@ -1084,6 +1084,7 @@
   }
 
   &__workspace-drop-target {
+    position: relative;
     border-radius: $size-radius-base;
     display: flex;
     flex-direction: column;
@@ -1106,11 +1107,23 @@
   }
 
   &__workspace-drop-line {
+    position: absolute;
+    left: 12px;
+    right: 12px;
+    z-index: 2;
     height: 2px;
-    margin: 3px 12px;
+    margin: 0;
     background: var(--bf-appearance-token-color-accent-500);
     border-radius: 999px;
     pointer-events: none;
+
+    .is-before & {
+      top: -1px;
+    }
+
+    .is-after & {
+      bottom: -1px;
+    }
   }
 }
 
diff --git a/src/web-ui/src/app/components/NavPanel/sections/workspaces/WorkspaceListSection.tsx b/src/web-ui/src/app/components/NavPanel/sections/workspaces/WorkspaceListSection.tsx
index 73cd317e9e..b8b0ca257f 100644
--- a/src/web-ui/src/app/components/NavPanel/sections/workspaces/WorkspaceListSection.tsx
+++ b/src/web-ui/src/app/components/NavPanel/sections/workspaces/WorkspaceListSection.tsx
@@ -1,4 +1,4 @@
-import React, { useCallback, useEffect, useRef, useState } from 'react';
+import React, { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
 import { useI18n } from '@/infrastructure/i18n';
 import { useWorkspaceContext } from '@/infrastructure/contexts/WorkspaceContext';
 import { notificationService } from '@/shared/notification-system';
@@ -20,6 +20,8 @@ interface WorkspaceDragPayload {
 }
 
 const WORKSPACE_DRAG_MIME_TYPE = 'application/x-bitfun-workspace';
+const WORKSPACE_DROP_SETTLE_MS = 160;
+const WORKSPACE_DROP_EASING = 'cubic-bezier(0.22, 1, 0.36, 1)';
 
 
 const WorkspaceListSection: React.FC<WorkspaceListSectionProps> = ({ variant }) => {
@@ -40,6 +42,10 @@ const WorkspaceListSection: React.FC<WorkspaceListSectionProps> = ({ variant })
   // Refs for values that must be read inside event handlers without stale closures
   const draggedWorkspaceIdRef = useRef<string | null>(null);
   const dropTargetRef = useRef<{ workspaceId: string; position: WorkspaceDragPosition } | null>(null);
+  const workspaceRowRefs = useRef<Map<string, HTMLDivElement>>(new Map());
+  const pendingDropRectsRef = useRef<Map<string, DOMRect> | null>(null);
+  const dropAnimationsRef = useRef<Map<string, Animation>>(new Map());
+
   // Drag-state safety nets (window dragend/mousedown + reset timeout) to clear
   // stuck is-drag-active state when dragend doesn't fire normally.
   const dragSafetyTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
@@ -70,6 +76,42 @@ const WorkspaceListSection: React.FC<WorkspaceListSectionProps> = ({ variant })
   const emptyLabel = variant === 'assistants'
     ? t('nav.workspaces.emptyAssistants')
     : t('nav.workspaces.emptyProjects');
+  const workspaceSignature = workspaces.map(workspace => workspace.id).join(':');
+
+  useEffect(() => () => {
+    dropAnimationsRef.current.forEach(animation => animation.cancel());
+    dropAnimationsRef.current.clear();
+  }, []);
+
+  useLayoutEffect(() => {
+    const previousRects = pendingDropRectsRef.current;
+    if (!previousRects) return;
+    pendingDropRectsRef.current = null;
+    if (window.matchMedia?.('(prefers-reduced-motion: reduce)').matches) return;
+
+    for (const [workspaceId, element] of workspaceRowRefs.current) {
+      const previousRect = previousRects.get(workspaceId);
+      if (!previousRect) continue;
+      const currentRect = element.getBoundingClientRect();
+      const deltaY = previousRect.top - currentRect.top;
+      if (Math.abs(deltaY) < 0.5) continue;
+
+      dropAnimationsRef.current.get(workspaceId)?.cancel();
+      const animation = element.animate(
+        [
+          { transform: `translateY(${deltaY}px)` },
+          { transform: 'translateY(0)' },
+        ],
+        { duration: WORKSPACE_DROP_SETTLE_MS, easing: WORKSPACE_DROP_EASING },
+      );
+      dropAnimationsRef.current.set(workspaceId, animation);
+      animation.addEventListener('finish', () => {
+        if (dropAnimationsRef.current.get(workspaceId) === animation) {
+          dropAnimationsRef.current.delete(workspaceId);
+        }
+      }, { once: true });
+    }
+  }, [workspaceSignature]);
 
   const removeDragArtifacts = useCallback(() => {
     if (dragSafetyTimeoutRef.current !== null) {
@@ -258,10 +300,16 @@ const WorkspaceListSection: React.FC<WorkspaceListSectionProps> = ({ variant })
     draggedWorkspaceIdRef.current = null;
     dropTargetRef.current = null;
     setDropTarget(null);
+    pendingDropRectsRef.current = new Map(
+      Array.from(workspaceRowRefs.current, ([id, element]) => (
+        [id, element.getBoundingClientRect()] as const
+      )),
+    );
 
     try {
       await reorderOpenedWorkspacesInSection(variant, payload.workspaceId, workspaceId, position);
     } catch (error) {
+      pendingDropRectsRef.current = null;
       notificationService.error(
         error instanceof Error ? error.message : t('nav.workspaces.reorderFailed'),
         { duration: 4000 }
@@ -294,6 +342,10 @@ const WorkspaceListSection: React.FC<WorkspaceListSectionProps> = ({ variant })
             data-bf-part="item"
             data-bf-state={workspace.id === activeWorkspaceId ? 'selected' : undefined}
             key={workspace.id}
+            ref={(element) => {
+              if (element) workspaceRowRefs.current.set(workspace.id, element);
+              else workspaceRowRefs.current.delete(workspace.id);
+            }}
             className={[
               'bitfun-nav-panel__workspace-drop-target',
               draggedWorkspaceId && draggedWorkspaceId !== workspace.id && 'is-drag-active',
@@ -308,9 +360,6 @@ const WorkspaceListSection: React.FC<WorkspaceListSectionProps> = ({ variant })
             onDragLeave={handleDragLeave(workspace.id)}
             onDrop={(event) => { void handleDrop(workspace.id)(event); }}
           >
-            {dropTarget?.workspaceId === workspace.id && dropTarget.position === 'before' ? (
-              <div data-bf-component="workspace-list-section" data-bf-part="dropLine" className="bitfun-nav-panel__workspace-drop-line" aria-hidden="true" />
-            ) : null}
             <WorkspaceItem
               workspace={workspace}
               isActive={
@@ -324,7 +373,7 @@ const WorkspaceListSection: React.FC<WorkspaceListSectionProps> = ({ variant })
               onDrag={handleDrag}
               onDragEnd={handleDragEnd}
             />
-            {dropTarget?.workspaceId === workspace.id && dropTarget.position === 'after' ? (
+            {dropTarget?.workspaceId === workspace.id ? (
               <div data-bf-component="workspace-list-section" data-bf-part="dropLine" className="bitfun-nav-panel__workspace-drop-line" aria-hidden="true" />
             ) : null}
           </div>
diff --git a/src/web-ui/src/app/components/NavPanel/sections/workspaces/WorkspaceSessionBatchModal.scss b/src/web-ui/src/app/components/NavPanel/sections/workspaces/WorkspaceSessionBatchModal.scss
index 979f9c3177..18b2e24dc4 100644
--- a/src/web-ui/src/app/components/NavPanel/sections/workspaces/WorkspaceSessionBatchModal.scss
+++ b/src/web-ui/src/app/components/NavPanel/sections/workspaces/WorkspaceSessionBatchModal.scss
@@ -367,3 +367,10 @@
     }
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .workspace-session-batch-modal__spinner {
+    animation: none;
+    transform: none;
+  }
+}
diff --git a/src/web-ui/src/app/components/NewProjectDialog/NewProjectDialog.scss b/src/web-ui/src/app/components/NewProjectDialog/NewProjectDialog.scss
index 552e2d120f..7aed0e21c7 100644
--- a/src/web-ui/src/app/components/NewProjectDialog/NewProjectDialog.scss
+++ b/src/web-ui/src/app/components/NewProjectDialog/NewProjectDialog.scss
@@ -230,7 +230,12 @@
     input {
       font-size: 12px;
       color: var(--bf-appearance-token-color-text-primary);
-
+      transition:
+        background-color 0.2s ease,
+        border-color 0.2s ease,
+        box-shadow 0.2s ease,
+        color 0.2s ease;
+      
       &::placeholder {
         color: var(--bf-appearance-token-color-text-muted);
         font-size: 12px;
@@ -458,3 +463,10 @@
     }
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .new-project-dialog__btn-spinner {
+    animation: none;
+    transform: none;
+  }
+}
diff --git a/src/web-ui/src/app/components/RemoteConnectDialog/AccountPanel.scss b/src/web-ui/src/app/components/RemoteConnectDialog/AccountPanel.scss
index 7f3b94cae8..0a22a15ad6 100644
--- a/src/web-ui/src/app/components/RemoteConnectDialog/AccountPanel.scss
+++ b/src/web-ui/src/app/components/RemoteConnectDialog/AccountPanel.scss
@@ -243,7 +243,7 @@
   }
 
   .spinning {
-    animation: spin 1s linear infinite;
+    animation: bitfun-account-panel-spin 1s linear infinite;
   }
 
   &__sync-indicator {
@@ -564,7 +564,14 @@
   }
 }
 
-@keyframes spin {
+@keyframes bitfun-account-panel-spin {
   from { transform: rotate(0deg); }
   to { transform: rotate(360deg); }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .account-panel .spinning {
+    animation: none;
+    transform: none;
+  }
+}
diff --git a/src/web-ui/src/app/components/RemoteConnectDialog/AccountPanel.tsx b/src/web-ui/src/app/components/RemoteConnectDialog/AccountPanel.tsx
index 7ab2ecfae2..7d850d92c3 100644
--- a/src/web-ui/src/app/components/RemoteConnectDialog/AccountPanel.tsx
+++ b/src/web-ui/src/app/components/RemoteConnectDialog/AccountPanel.tsx
@@ -217,7 +217,7 @@ export const AccountPanel: React.FC<AccountPanelProps> = ({
   const { t, formatRelativeTime } = useI18n('common');
   const { success, info, warning } = useNotification();
   const { workspacePath } = useCurrentWorkspace();
-  const { enterPeerMode } = usePeerDeviceMode();
+  const { peerMode, switchToDevice, switchToLocal } = usePeerDeviceMode();
   const openScene = useSceneStore((s) => s.openScene);
   const syncStatus = useAccountSyncStore((s) => s.status);
   const syncProgress = useAccountSyncStore((s) => s.progress);
@@ -1020,26 +1020,52 @@ export const AccountPanel: React.FC<AccountPanelProps> = ({
 
   const selectDevice = useCallback(async (device: AccountDeviceInfo) => {
     if (!device.online) return;
-    if (localDeviceId && device.device_id === localDeviceId) return;
-    if (syncStatus === 'syncing') {
-      info(t('accountLogin.syncInProgressHint'));
-      return;
-    }
-    if (syncStatus === 'failed') {
-      warning(t('accountLogin.syncFailedPeerHint'));
+    // Picking this machine is a normal surface switch back, not a no-op: the
+    // window may currently be rendering a peer.
+    const isLocalDevice = Boolean(localDeviceId) && device.device_id === localDeviceId;
+    if (!isLocalDevice) {
+      if (syncStatus === 'syncing') {
+        info(t('accountLogin.syncInProgressHint'));
+        return;
+      }
+      if (syncStatus === 'failed') {
+        warning(t('accountLogin.syncFailedPeerHint'));
+      }
     }
     setLoading(true);
     setError(null);
     try {
-      await enterPeerMode(device.device_id, device.device_name);
-      success(t('accountLogin.enteredPeerMode', { name: device.device_name }));
-      onCloseDialog();
+      let outcome: 'activated' | 'superseded';
+      if (isLocalDevice) {
+        outcome = await switchToLocal();
+        if (outcome === 'activated') {
+          success(t('accountLogin.deviceSwitcher.switchedLocal'));
+        }
+      } else {
+        outcome = await switchToDevice(device.device_id, device.device_name);
+        if (outcome === 'activated') {
+          success(t('accountLogin.enteredPeerMode', { name: device.device_name }));
+        }
+      }
+      if (outcome === 'activated') {
+        onCloseDialog();
+      }
     } catch (e: unknown) {
       setError(e instanceof Error ? e.message : String(e));
     } finally {
       setLoading(false);
     }
-  }, [enterPeerMode, info, localDeviceId, onCloseDialog, success, syncStatus, t, warning]);
+  }, [
+    info,
+    localDeviceId,
+    onCloseDialog,
+    success,
+    switchToDevice,
+    switchToLocal,
+    syncStatus,
+    t,
+    warning,
+  ]);
 
   return (
     <>
@@ -1247,7 +1273,11 @@ export const AccountPanel: React.FC<AccountPanelProps> = ({
               )}
               {!relayError && sortedDevices.map((d) => {
                 const isLocal = localDeviceId === d.device_id;
-                const isSelectable = !isLocal && d.online && syncStatus !== 'syncing';
+                // This machine is selectable while the window renders a peer,
+                // so the dialog can bring the UI back without disconnecting.
+                const isSelectable = isLocal
+                  ? peerMode.active
+                  : d.online && syncStatus !== 'syncing';
                 const removeLabel = isLocal
                   ? t('accountLogin.removeCurrentDevice')
                   : t('accountLogin.removeDevice');
diff --git a/src/web-ui/src/app/components/SceneBar/types.ts b/src/web-ui/src/app/components/SceneBar/types.ts
index b26d0ab0b5..bc7d97df50 100644
--- a/src/web-ui/src/app/components/SceneBar/types.ts
+++ b/src/web-ui/src/app/components/SceneBar/types.ts
@@ -19,6 +19,7 @@ export type SceneTabId =
   | 'pages'
   | 'browser'
   | 'assistant'
+  | 'todos'
   | 'insights'
   | 'shell'
   | 'panel-view'
diff --git a/src/web-ui/src/app/components/panels/BranchSelectModal.scss b/src/web-ui/src/app/components/panels/BranchSelectModal.scss
index d18ab2a0a8..87a1299526 100644
--- a/src/web-ui/src/app/components/panels/BranchSelectModal.scss
+++ b/src/web-ui/src/app/components/panels/BranchSelectModal.scss
@@ -19,12 +19,14 @@
   align-items: center;
   justify-content: center;
   padding: 24px;
-  animation: branch-overlay-fade 0.2s ease;
-}
+  opacity: 1;
+  transition: opacity 160ms cubic-bezier(0.23, 1, 0.32, 1);
 
-@keyframes branch-overlay-fade {
-  from { opacity: 0; }
-  to { opacity: 1; }
+  &[data-state='closed'] {
+    opacity: 0;
+    pointer-events: none;
+    transition-duration: 120ms;
+  }
 }
 
 // ==================== Dialog Body ====================
@@ -41,17 +43,27 @@
   max-width: calc(100vw - 48px);
   max-height: min(520px, calc(100vh - 48px));
   overflow: hidden;
-  animation: branch-dialog-enter 0.25s cubic-bezier(0.16, 1, 0.3, 1);
+  opacity: 1;
+  transform: translateY(0) scale(1);
+  transition:
+    opacity 160ms cubic-bezier(0.23, 1, 0.32, 1),
+    transform 160ms cubic-bezier(0.23, 1, 0.32, 1);
 }
 
-@keyframes branch-dialog-enter {
-  from {
+.branch-select-overlay[data-state='closed'] .branch-select-dialog {
+  opacity: 0;
+  transform: translateY(4px) scale(0.985);
+  transition-duration: 120ms;
+}
+
+@starting-style {
+  .branch-select-overlay {
     opacity: 0;
-    transform: translateY(16px) scale(0.98);
   }
-  to {
-    opacity: 1;
-    transform: translateY(0) scale(1);
+
+  .branch-select-dialog {
+    opacity: 0;
+    transform: translateY(4px) scale(0.985);
   }
 }
 
@@ -331,3 +343,22 @@
     }
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .branch-select-dialog {
+    animation: none;
+    transform: none;
+    transition: opacity 160ms cubic-bezier(0.23, 1, 0.32, 1);
+  }
+
+  .branch-select-overlay[data-state='closed'] .branch-select-dialog {
+    transform: none;
+    transition-duration: 120ms;
+  }
+
+  .branch-select-dialog__loading-dots span {
+    animation: none;
+    opacity: 0.65;
+    transform: none;
+  }
+}
diff --git a/src/web-ui/src/app/components/panels/BranchSelectModal.test.tsx b/src/web-ui/src/app/components/panels/BranchSelectModal.test.tsx
new file mode 100644
index 0000000000..2da8e61d76
--- /dev/null
+++ b/src/web-ui/src/app/components/panels/BranchSelectModal.test.tsx
@@ -0,0 +1,76 @@
+// @vitest-environment jsdom
+
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { PRESENCE_BOUNDARY_MIN_EXIT_MS } from '@/component-library';
+import { BranchSelectModal } from './BranchSelectModal';
+
+const mocks = vi.hoisted(() => ({
+  getBranches: vi.fn(),
+}));
+
+vi.mock('@/infrastructure/appearance/runtime/AppearanceOverlayHost', () => ({
+  getAppearanceOverlayHost: () => document.body,
+}));
+
+vi.mock('@/infrastructure/i18n', () => ({
+  useI18n: () => ({ t: (key: string) => key }),
+  i18nService: { t: (key: string) => key },
+}));
+
+vi.mock('../../../infrastructure/api/service-api/GitAPI', () => ({
+  gitAPI: { getBranches: mocks.getBranches },
+}));
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+describe('BranchSelectModal presence', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    mocks.getBranches.mockResolvedValue([]);
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    document.querySelectorAll('.branch-select-overlay').forEach((node) => node.remove());
+    vi.useRealTimers();
+    vi.clearAllMocks();
+  });
+
+  const renderModal = (isOpen: boolean, title: string) => {
+    act(() => {
+      root.render(
+        <BranchSelectModal
+          isOpen={isOpen}
+          onClose={vi.fn()}
+          onSelect={vi.fn()}
+          repositoryPath=""
+          title={title}
+        />,
+      );
+    });
+  };
+
+  it('retains the closed surface and last title until the exit window completes', () => {
+    renderModal(true, 'Choose release branch');
+    expect(document.querySelector('.branch-select-overlay')?.getAttribute('data-state')).toBe('open');
+
+    renderModal(false, 'Changed after close');
+    expect(document.querySelector('.branch-select-overlay')?.getAttribute('data-state')).toBe('closed');
+    expect(document.querySelector('.branch-select-dialog__title')?.textContent).toBe('Choose release branch');
+
+    act(() => vi.advanceTimersByTime(PRESENCE_BOUNDARY_MIN_EXIT_MS - 1));
+    expect(document.querySelector('.branch-select-overlay')).not.toBeNull();
+
+    act(() => vi.advanceTimersByTime(1));
+    expect(document.querySelector('.branch-select-overlay')).toBeNull();
+  });
+});
diff --git a/src/web-ui/src/app/components/panels/BranchSelectModal.tsx b/src/web-ui/src/app/components/panels/BranchSelectModal.tsx
index 3c090c456f..32e4632b54 100644
--- a/src/web-ui/src/app/components/panels/BranchSelectModal.tsx
+++ b/src/web-ui/src/app/components/panels/BranchSelectModal.tsx
@@ -8,7 +8,14 @@ import { createPortal } from 'react-dom';
 import { getAppearanceOverlayHost } from '@/infrastructure/appearance/runtime/AppearanceOverlayHost';
 import { GitBranch, Plus, X } from 'lucide-react';
 import { createLogger } from '@/shared/utils/logger';
-import { IconButton, Button, Input, Checkbox } from '@/component-library';
+import {
+  IconButton,
+  Button,
+  Input,
+  Checkbox,
+  PresenceBoundary,
+  PRESENCE_BOUNDARY_MIN_EXIT_MS,
+} from '@/component-library';
 import { useI18n } from '@/infrastructure/i18n';
 import { gitAPI, type GitBranch as GitBranchType } from '../../../infrastructure/api/service-api/GitAPI';
 import './BranchSelectModal.scss';
@@ -60,20 +67,40 @@ export const BranchSelectModal: React.FC<BranchSelectModalProps> = ({
   const [error, setError] = useState<string | null>(null);
   const inputRef = useRef<HTMLInputElement>(null);
   const resolvedTitle = title ?? t('branchSelect.title');
+  const retainedDisplayRef = useRef({
+    title: resolvedTitle,
+    currentBranch,
+    existingWorktreeBranches,
+    showOpenAfterCreate,
+  });
+
+  if (isOpen) {
+    retainedDisplayRef.current = {
+      title: resolvedTitle,
+      currentBranch,
+      existingWorktreeBranches,
+      showOpenAfterCreate,
+    };
+  }
 
+  const retainedDisplay = retainedDisplayRef.current;
 
   useEffect(() => {
     if (!isOpen) {
-      setSearchTerm('');
-      setSelectedBranch(null);
-      setIsNewBranch(false);
-      setOpenAfterCreate(defaultOpenAfterCreate);
-      setError(null);
-    } else {
-      setTimeout(() => {
-        inputRef.current?.focus();
-      }, 100);
+      const resetTimer = window.setTimeout(() => {
+        setSearchTerm('');
+        setSelectedBranch(null);
+        setIsNewBranch(false);
+        setOpenAfterCreate(defaultOpenAfterCreate);
+        setError(null);
+      }, PRESENCE_BOUNDARY_MIN_EXIT_MS);
+      return () => window.clearTimeout(resetTimer);
     }
+
+    const focusTimer = window.setTimeout(() => {
+      inputRef.current?.focus();
+    }, 100);
+    return () => window.clearTimeout(focusTimer);
   }, [defaultOpenAfterCreate, isOpen]);
 
   useEffect(() => {
@@ -118,10 +145,10 @@ export const BranchSelectModal: React.FC<BranchSelectModalProps> = ({
 
     const availableBranches: SelectableBranch[] = [];
     const unavailableBranches: SelectableBranch[] = [];
-    const existingWorktreeSet = new Set(existingWorktreeBranches);
+    const existingWorktreeSet = new Set(retainedDisplay.existingWorktreeBranches);
 
     result.forEach(branch => {
-      const isCurrent = branch.name === currentBranch;
+      const isCurrent = branch.name === retainedDisplay.currentBranch;
       const hasWorktree = existingWorktreeSet.has(branch.name);
 
       if (isCurrent || hasWorktree) {
@@ -132,7 +159,7 @@ export const BranchSelectModal: React.FC<BranchSelectModalProps> = ({
     });
 
     return [...availableBranches, ...unavailableBranches];
-  }, [branches, searchTerm, currentBranch, existingWorktreeBranches]);
+  }, [branches, retainedDisplay.currentBranch, retainedDisplay.existingWorktreeBranches, searchTerm]);
 
   const canCreateNewBranch = useMemo(() => {
     if (!searchTerm.trim()) return false;
@@ -167,10 +194,16 @@ export const BranchSelectModal: React.FC<BranchSelectModalProps> = ({
     onClose();
   }, [onClose, onSelect, openAfterCreate]);
 
-  if (!isOpen) return null;
-
   const modalContent = (
-    <div data-bf-component="branch-select-modal" data-bf-part="overlay" className="branch-select-overlay" onClick={onClose}>
+    <div
+      data-bf-component="branch-select-modal"
+      data-bf-part="overlay"
+      data-state={isOpen ? 'open' : 'closed'}
+      aria-hidden={!isOpen}
+      {...(!isOpen ? { inert: '' } : {})}
+      className="branch-select-overlay"
+      onClick={onClose}
+    >
       <div data-bf-component="branch-select-modal" data-bf-part="root" className="branch-select-dialog" onClick={(e) => e.stopPropagation()}>
         <IconButton 
           className="branch-select-dialog__close"
@@ -185,7 +218,7 @@ export const BranchSelectModal: React.FC<BranchSelectModalProps> = ({
         </IconButton>
 
         <div data-bf-component="branch-select-modal" data-bf-part="header" className="branch-select-dialog__header">
-          <h2 className="branch-select-dialog__title">{resolvedTitle}</h2>
+          <h2 className="branch-select-dialog__title">{retainedDisplay.title}</h2>
         </div>
 
         <div data-bf-component="branch-select-modal" data-bf-part="content" className="branch-select-dialog__content">
@@ -282,7 +315,7 @@ export const BranchSelectModal: React.FC<BranchSelectModalProps> = ({
         </div>
 
         <div data-bf-component="branch-select-modal" data-bf-part="footer" className="branch-select-dialog__footer">
-          {showOpenAfterCreate ? (
+          {retainedDisplay.showOpenAfterCreate ? (
             <div data-bf-component="branch-select-modal" data-bf-part="options" className="branch-select-dialog__options">
               <Checkbox
                 checked={openAfterCreate}
@@ -312,11 +345,17 @@ export const BranchSelectModal: React.FC<BranchSelectModalProps> = ({
     </div>
   );
 
+  const retainedModal = (
+    <PresenceBoundary active={isOpen}>
+      {modalContent}
+    </PresenceBoundary>
+  );
+
   if (typeof document === 'undefined') {
-    return modalContent;
+    return retainedModal;
   }
 
-  return createPortal(modalContent, getAppearanceOverlayHost());
+  return createPortal(retainedModal, getAppearanceOverlayHost());
 };
 
 export default BranchSelectModal;
diff --git a/src/web-ui/src/app/components/panels/DiffFullscreenViewer.css b/src/web-ui/src/app/components/panels/DiffFullscreenViewer.css
index 4260c2e9c2..766ca11451 100644
--- a/src/web-ui/src/app/components/panels/DiffFullscreenViewer.css
+++ b/src/web-ui/src/app/components/panels/DiffFullscreenViewer.css
@@ -13,17 +13,15 @@
   display: flex;
   align-items: center;
   justify-content: center;
-  animation: fadeIn 0.2s ease-out;
+  opacity: 1;
+  transition: opacity 160ms cubic-bezier(0.23, 1, 0.32, 1);
   pointer-events: auto;
 }
 
-@keyframes fadeIn {
-  from {
-    opacity: 0;
-  }
-  to {
-    opacity: 1;
-  }
+.diff-fullscreen-overlay[data-state='closed'] {
+  opacity: 0;
+  pointer-events: none;
+  transition-duration: 120ms;
 }
 
 .diff-fullscreen-container {
@@ -33,19 +31,30 @@
   display: flex;
   flex-direction: column;
   position: relative;
-  animation: slideInUp 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+  opacity: 1;
+  transform: translateY(0) scale(1);
+  transform-origin: center;
+  transition:
+    opacity 160ms cubic-bezier(0.23, 1, 0.32, 1),
+    transform 160ms cubic-bezier(0.23, 1, 0.32, 1);
   pointer-events: auto;
   z-index: 1;
 }
 
-@keyframes slideInUp {
-  from {
+.diff-fullscreen-overlay[data-state='closed'] .diff-fullscreen-container {
+  opacity: 0;
+  transform: translateY(4px) scale(0.985);
+  transition-duration: 120ms;
+}
+
+@starting-style {
+  .diff-fullscreen-overlay {
     opacity: 0;
-    transform: translateY(20px);
   }
-  to {
-    opacity: 1;
-    transform: translateY(0);
+
+  .diff-fullscreen-container {
+    opacity: 0;
+    transform: translateY(4px) scale(0.985);
   }
 }
 
@@ -115,7 +124,13 @@
   font-size: 13px;
   font-weight: 500;
   cursor: pointer;
-  transition: all 0.2s ease;
+  transition:
+    background-color 0.2s ease,
+    border-color 0.2s ease,
+    box-shadow 0.2s ease,
+    color 0.2s ease,
+    opacity 0.2s ease,
+    transform 0.2s ease;
   background: var(--bf-appearance-token-color-overlay-white-08);
   color: var(--bf-appearance-token-color-overlay-white-80);
   border: 1px solid var(--bf-appearance-token-color-overlay-white-12);
@@ -239,14 +254,30 @@
   border: 2px solid color-mix(in srgb, var(--bf-appearance-token-color-static-white) 30%, transparent);
   border-top: 2px solid var(--bf-appearance-token-color-overlay-white-90);
   border-radius: 50%;
-  animation: spin 1s linear infinite;
+  animation: bitfun-diff-fullscreen-spin 1s linear infinite;
 }
 
-@keyframes spin {
+@keyframes bitfun-diff-fullscreen-spin {
   0% { transform: rotate(0deg); }
   100% { transform: rotate(360deg); }
 }
 
+@media (prefers-reduced-motion: reduce) {
+  .fullscreen-loading-overlay .loading-spinner {
+    animation: none;
+  }
+
+  .diff-fullscreen-container {
+    transform: none;
+    transition: opacity 160ms cubic-bezier(0.23, 1, 0.32, 1);
+  }
+
+  .diff-fullscreen-overlay[data-state='closed'] .diff-fullscreen-container {
+    transform: none;
+    transition-duration: 120ms;
+  }
+}
+
 /* Responsive layout */
 @media (max-width: 768px) {
   .diff-fullscreen-header {
diff --git a/src/web-ui/src/app/components/panels/DiffFullscreenViewer.test.tsx b/src/web-ui/src/app/components/panels/DiffFullscreenViewer.test.tsx
new file mode 100644
index 0000000000..1286db19a1
--- /dev/null
+++ b/src/web-ui/src/app/components/panels/DiffFullscreenViewer.test.tsx
@@ -0,0 +1,74 @@
+// @vitest-environment jsdom
+
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { PRESENCE_BOUNDARY_MIN_EXIT_MS } from '@/component-library';
+import { DiffFullscreenViewer } from './DiffFullscreenViewer';
+
+vi.mock('@/infrastructure/appearance/runtime/AppearanceOverlayHost', () => ({
+  getAppearanceOverlayHost: () => document.body,
+}));
+
+vi.mock('@/infrastructure/i18n', () => ({
+  useI18n: () => ({ t: (key: string) => key }),
+  i18nService: { t: (key: string) => key },
+}));
+
+vi.mock('../../../tools/editor', () => ({
+  DiffEditor: ({ filePath }: { filePath: string }) => (
+    <div data-testid="retained-diff-path">{filePath}</div>
+  ),
+}));
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+describe('DiffFullscreenViewer presence', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    document.querySelectorAll('.diff-fullscreen-overlay').forEach((node) => node.remove());
+    document.body.style.overflow = '';
+    vi.useRealTimers();
+  });
+
+  const renderViewer = (isOpen: boolean, filePath: string) => {
+    act(() => {
+      root.render(
+        <DiffFullscreenViewer
+          isOpen={isOpen}
+          onClose={vi.fn()}
+          filePath={filePath}
+          originalContent="before"
+          modifiedContent="after"
+          onAcceptFile={vi.fn()}
+          onRejectFile={vi.fn()}
+          onAcceptBlock={vi.fn()}
+          onRejectBlock={vi.fn()}
+        />,
+      );
+    });
+  };
+
+  it('keeps the last diff stable during exit before unmounting it', () => {
+    renderViewer(true, '/repo/old.ts');
+    expect(document.querySelector('.diff-fullscreen-overlay')?.getAttribute('data-state')).toBe('open');
+
+    renderViewer(false, '/repo/new.ts');
+    expect(document.querySelector('.diff-fullscreen-overlay')?.getAttribute('data-state')).toBe('closed');
+    expect(document.querySelector('[data-testid="retained-diff-path"]')?.textContent).toBe('/repo/old.ts');
+
+    act(() => vi.advanceTimersByTime(PRESENCE_BOUNDARY_MIN_EXIT_MS));
+    expect(document.querySelector('.diff-fullscreen-overlay')).toBeNull();
+  });
+});
diff --git a/src/web-ui/src/app/components/panels/DiffFullscreenViewer.tsx b/src/web-ui/src/app/components/panels/DiffFullscreenViewer.tsx
index d2069f7b55..7a2aab8d5e 100644
--- a/src/web-ui/src/app/components/panels/DiffFullscreenViewer.tsx
+++ b/src/web-ui/src/app/components/panels/DiffFullscreenViewer.tsx
@@ -1,8 +1,8 @@
-import React, { useEffect, useCallback } from 'react';
+import React, { useEffect, useCallback, useRef } from 'react';
 import { createPortal } from 'react-dom';
 import { getAppearanceOverlayHost } from '@/infrastructure/appearance/runtime/AppearanceOverlayHost';
 import { X, CheckCircle, XCircle } from 'lucide-react';
-import { Tooltip } from '@/component-library';
+import { PresenceBoundary, Tooltip } from '@/component-library';
 import { useI18n } from '@/infrastructure/i18n';
 import { DiffEditor } from '../../../tools/editor';
 import './DiffFullscreenViewer.css';
@@ -33,6 +33,23 @@ export const DiffFullscreenViewer: React.FC<DiffFullscreenViewerProps> = ({
   loading = false
 }) => {
   const { t } = useI18n('components');
+  const retainedContentRef = useRef({
+    filePath,
+    originalContent,
+    modifiedContent,
+    loading,
+  });
+
+  if (isOpen) {
+    retainedContentRef.current = {
+      filePath,
+      originalContent,
+      modifiedContent,
+      loading,
+    };
+  }
+
+  const retainedContent = retainedContentRef.current;
   // Close on Escape
   useEffect(() => {
     const handleEscape = (e: KeyboardEvent) => {
@@ -59,13 +76,14 @@ export const DiffFullscreenViewer: React.FC<DiffFullscreenViewerProps> = ({
     }
   }, [onClose]);
 
-  if (!isOpen) return null;
-
-  const fileName = filePath.split(/[/\\]/).pop() || filePath;
+  const fileName = retainedContent.filePath.split(/[/\\]/).pop() || retainedContent.filePath;
 
   const fullscreenContent = (
     <div
       className="diff-fullscreen-overlay"
+      data-state={isOpen ? 'open' : 'closed'}
+      aria-hidden={!isOpen}
+      {...(!isOpen ? { inert: '' } : {})}
       onClick={handleBackdropClick}
       data-bf-component="diff-fullscreen-viewer"
       data-bf-part="overlay"
@@ -82,7 +100,7 @@ export const DiffFullscreenViewer: React.FC<DiffFullscreenViewerProps> = ({
             </div>
             <div className="file-details">
               <div className="file-name">{fileName}</div>
-              <div className="file-path-full">{filePath}</div>
+              <div className="file-path-full">{retainedContent.filePath}</div>
             </div>
           </div>
 
@@ -91,7 +109,7 @@ export const DiffFullscreenViewer: React.FC<DiffFullscreenViewerProps> = ({
               <button
                 className="header-btn accept-btn"
                 onClick={onAcceptFile}
-                disabled={loading}
+                disabled={retainedContent.loading}
               >
                 <CheckCircle size={16} />
                 <span>{t('diffFullscreen.acceptFile')}</span>
@@ -102,7 +120,7 @@ export const DiffFullscreenViewer: React.FC<DiffFullscreenViewerProps> = ({
               <button
                 className="header-btn reject-btn"
                 onClick={onRejectFile}
-                disabled={loading}
+                disabled={retainedContent.loading}
               >
                 <XCircle size={16} />
                 <span>{t('diffFullscreen.rejectFile')}</span>
@@ -125,9 +143,9 @@ export const DiffFullscreenViewer: React.FC<DiffFullscreenViewerProps> = ({
         {/* Diff content */}
         <div className="diff-fullscreen-content" data-bf-component="diff-fullscreen-viewer" data-bf-part="content">
           <DiffEditor
-            originalContent={originalContent}
-            modifiedContent={modifiedContent}
-            filePath={filePath}
+            originalContent={retainedContent.originalContent}
+            modifiedContent={retainedContent.modifiedContent}
+            filePath={retainedContent.filePath}
             readOnly={false}
             renderSideBySide={true}
             showMinimap={false}
@@ -135,7 +153,7 @@ export const DiffFullscreenViewer: React.FC<DiffFullscreenViewerProps> = ({
         </div>
 
         {/* Loading overlay */}
-        {loading && (
+        {retainedContent.loading && (
           <div className="fullscreen-loading-overlay" data-bf-component="diff-fullscreen-viewer" data-bf-part="loading">
             <div className="loading-spinner" />
             <span>{t('diffFullscreen.processing')}</span>
@@ -145,5 +163,10 @@ export const DiffFullscreenViewer: React.FC<DiffFullscreenViewerProps> = ({
     </div>
   );
 
-  return createPortal(fullscreenContent, getAppearanceOverlayHost());
+  return createPortal(
+    <PresenceBoundary active={isOpen}>
+      {fullscreenContent}
+    </PresenceBoundary>,
+    getAppearanceOverlayHost(),
+  );
 };
diff --git a/src/web-ui/src/app/components/panels/FilesPanel.scss b/src/web-ui/src/app/components/panels/FilesPanel.scss
index 619b65165c..09045fa25e 100644
--- a/src/web-ui/src/app/components/panels/FilesPanel.scss
+++ b/src/web-ui/src/app/components/panels/FilesPanel.scss
@@ -498,7 +498,12 @@
     background: transparent;
     color: var(--bf-appearance-token-color-text-muted);
     cursor: pointer;
-    transition: all $motion-base $easing-standard;
+    transition:
+      background-color $motion-base $easing-standard,
+      border-color $motion-base $easing-standard,
+      color $motion-base $easing-standard,
+      opacity $motion-base $easing-standard,
+      transform $motion-base $easing-standard;
     font-size: var(--bf-appearance-token-font-size-xs);
 
     &:hover {
@@ -676,3 +681,13 @@
     }
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .bitfun-files-panel__sync-indicator,
+  .bitfun-files-panel__search-spinner,
+  .bitfun-files-panel__transfer-track--indeterminate .bitfun-files-panel__transfer-fill,
+  .bitfun-files-panel__loading-spinner {
+    animation: none;
+    transform: none;
+  }
+}
diff --git a/src/web-ui/src/app/components/panels/FilesPanel.tsx b/src/web-ui/src/app/components/panels/FilesPanel.tsx
index 6c1ac5a91a..b32503533d 100644
--- a/src/web-ui/src/app/components/panels/FilesPanel.tsx
+++ b/src/web-ui/src/app/components/panels/FilesPanel.tsx
@@ -21,6 +21,7 @@ import { globalEventBus } from '@/infrastructure/event-bus';
 import { useNotification } from '@/shared/notification-system';
 import { InputDialog, CubeLoading } from '@/component-library';
 import { openFileInBestTarget } from '@/shared/utils/tabUtils';
+import { getMotionAwareScrollBehavior } from '@/shared/utils/motionPreference';
 import { PanelHeader } from './base';
 import { createLogger } from '@/shared/utils/logger';
 import { isPeerDeviceModeActive } from '@/infrastructure/peer-device/peerModeFlag';
@@ -671,7 +672,10 @@ const FilesPanel: React.FC<FilesPanelProps> = ({
       const escapedPath = finalExpandPath.replace(/\\/g, '\\\\');
       const targetElement = document.querySelector(`[data-file-path="${escapedPath}"]`);
       if (targetElement) {
-        targetElement.scrollIntoView({ behavior: 'smooth', block: 'center' });
+        targetElement.scrollIntoView({
+          behavior: getMotionAwareScrollBehavior('smooth'),
+          block: 'center',
+        });
         targetElement.classList.add('bitfun-file-explorer__node-content--highlighted');
         setTimeout(() => {
           targetElement.classList.remove('bitfun-file-explorer__node-content--highlighted');
diff --git a/src/web-ui/src/app/components/panels/base/FlexiblePanel.scss b/src/web-ui/src/app/components/panels/base/FlexiblePanel.scss
index f594f3905a..aced5e648b 100644
--- a/src/web-ui/src/app/components/panels/base/FlexiblePanel.scss
+++ b/src/web-ui/src/app/components/panels/base/FlexiblePanel.scss
@@ -610,3 +610,11 @@
     height: 100%;
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .bitfun-flexible-panel__loading::before,
+  .bitfun-flexible-panel .needs-fix {
+    animation: none;
+    transform: none;
+  }
+}
diff --git a/src/web-ui/src/app/components/panels/content-canvas/editor-area/EditorGroup.scss b/src/web-ui/src/app/components/panels/content-canvas/editor-area/EditorGroup.scss
index 29984d9059..e5946c44b4 100644
--- a/src/web-ui/src/app/components/panels/content-canvas/editor-area/EditorGroup.scss
+++ b/src/web-ui/src/app/components/panels/content-canvas/editor-area/EditorGroup.scss
@@ -29,7 +29,8 @@
     flex-direction: column;
   }
 
-  // Tab content - instant switch, no transition
+  // Cached panes switch immediately; pointer selections receive a short WAAPI
+  // transform/opacity bridge from EditorGroup without delaying keyboard paths.
   &__tab-content {
     width: 100%;
     flex: 1;
diff --git a/src/web-ui/src/app/components/panels/content-canvas/editor-area/EditorGroup.tsx b/src/web-ui/src/app/components/panels/content-canvas/editor-area/EditorGroup.tsx
index c938514927..08f637b2ac 100644
--- a/src/web-ui/src/app/components/panels/content-canvas/editor-area/EditorGroup.tsx
+++ b/src/web-ui/src/app/components/panels/content-canvas/editor-area/EditorGroup.tsx
@@ -3,14 +3,19 @@
  * A single editor group with tab bar and content area.
  */
 
-import React, { useCallback, useMemo, useRef, useEffect } from 'react';
+import React, { useCallback, useMemo, useRef, useEffect, useLayoutEffect } from 'react';
 import { useTranslation } from 'react-i18next';
 import { TabBar } from '../tab-bar';
 import { DropZone } from './DropZone';
 import FlexiblePanel from '../../base/FlexiblePanel';
 import { usePanelViewCanvasStore } from '../stores';
 import { useSceneStore } from '../../../../stores/sceneStore';
-import type { 
+import {
+  getInteractionMotion,
+  isReducedMotionPreferred,
+  type InteractionMotion,
+} from '@/shared/utils/motionPreference';
+import type {
   EditorGroupId, 
   EditorGroupState, 
   TabDragPayload,
@@ -77,6 +82,13 @@ export const EditorGroup: React.FC<EditorGroupProps> = ({
 }) => {
   const { t } = useTranslation('components');
   const visibleTabs = useMemo(() => group.tabs.filter(t => !t.isHidden), [group.tabs]);
+  const activeTabContentRef = useRef<HTMLDivElement | null>(null);
+  const activeTabAnimationRef = useRef<Animation | null>(null);
+  const previousActiveTabIdRef = useRef(group.activeTabId);
+  const tabTransitionIntentRef = useRef<{
+    motion: InteractionMotion;
+    tabId: string;
+  } | null>(null);
   const isKeepAliveTab = useCallback((tab: EditorGroupState['tabs'][number]) =>
     tab.content.type === 'terminal' || tab.content.type === 'image-viewer',
   []);
@@ -142,6 +154,49 @@ export const EditorGroup: React.FC<EditorGroupProps> = ({
     useSceneStore.getState().openScene('panel-view');
   }, [group.tabs]);
 
+  const handleVisibleTabClick = useCallback((tabId: string) => {
+    tabTransitionIntentRef.current = {
+      motion: getInteractionMotion(),
+      tabId,
+    };
+    onTabClick(tabId);
+  }, [onTabClick]);
+
+  useLayoutEffect(() => {
+    const previousTabId = previousActiveTabIdRef.current;
+    previousActiveTabIdRef.current = group.activeTabId;
+    if (!previousTabId || !group.activeTabId || previousTabId === group.activeTabId) {
+      return;
+    }
+
+    const intent = tabTransitionIntentRef.current;
+    const motion = intent?.tabId === group.activeTabId
+      ? intent.motion
+      : getInteractionMotion();
+    tabTransitionIntentRef.current = null;
+    if (motion !== 'pointer' || !activeTabContentRef.current) return;
+
+    activeTabAnimationRef.current?.cancel();
+    const reducedMotion = isReducedMotionPreferred();
+    activeTabAnimationRef.current = activeTabContentRef.current.animate(
+      reducedMotion
+        ? [{ opacity: 0.82 }, { opacity: 1 }]
+        : [
+            { opacity: 0.72, transform: 'translate3d(0, 4px, 0) scale(0.997)' },
+            { opacity: 1, transform: 'translate3d(0, 0, 0) scale(1)' },
+          ],
+      {
+        duration: reducedMotion ? 100 : 150,
+        easing: 'cubic-bezier(0.23, 1, 0.32, 1)',
+      },
+    );
+
+    return () => {
+      activeTabAnimationRef.current?.cancel();
+      activeTabAnimationRef.current = null;
+    };
+  }, [group.activeTabId]);
+
   const isDragging = draggingTabId !== null;
 
   return (
@@ -155,7 +210,7 @@ export const EditorGroup: React.FC<EditorGroupProps> = ({
         groupId={groupId}
         activeTabId={group.activeTabId}
         isActiveGroup={isActive}
-        onTabClick={onTabClick}
+        onTabClick={handleVisibleTabClick}
         onTabDoubleClick={onTabDoubleClick}
         onTabClose={onTabClose}
         onTabPin={onTabPin}
@@ -181,6 +236,7 @@ export const EditorGroup: React.FC<EditorGroupProps> = ({
             tabsToRender.map((tab) => (
               <div
                 key={tab.id}
+                ref={group.activeTabId === tab.id ? activeTabContentRef : undefined}
                 data-bf-component="canvas-editor-group"
                 data-bf-part="tabContent"
                 className="canvas-editor-group__tab-content"
diff --git a/src/web-ui/src/app/components/panels/content-canvas/tab-bar/TabBar.scss b/src/web-ui/src/app/components/panels/content-canvas/tab-bar/TabBar.scss
index 9b9d56f273..722e657726 100644
--- a/src/web-ui/src/app/components/panels/content-canvas/tab-bar/TabBar.scss
+++ b/src/web-ui/src/app/components/panels/content-canvas/tab-bar/TabBar.scss
@@ -29,6 +29,7 @@
     position: relative;
     display: flex;
     align-items: center;
+    transition: transform 120ms cubic-bezier(0.22, 1, 0.36, 1);
   }
 
   // Actions area
@@ -67,6 +68,12 @@
   }
 }
 
+@media (prefers-reduced-motion: reduce) {
+  .canvas-tab-bar__tab-wrapper {
+    transition: none;
+  }
+}
+
 // Drop indicator
 .canvas-tab-drop-indicator {
   position: absolute;
diff --git a/src/web-ui/src/app/components/panels/content-canvas/tab-bar/TabBar.tsx b/src/web-ui/src/app/components/panels/content-canvas/tab-bar/TabBar.tsx
index 61c8eae3e4..359cb5ad89 100644
--- a/src/web-ui/src/app/components/panels/content-canvas/tab-bar/TabBar.tsx
+++ b/src/web-ui/src/app/components/panels/content-canvas/tab-bar/TabBar.tsx
@@ -14,6 +14,8 @@ import { createLogger } from '@/shared/utils/logger';
 import './TabBar.scss';
 
 const log = createLogger('TabBar');
+const TAB_REORDER_DURATION_MS = 160;
+const TAB_REORDER_EASING = 'cubic-bezier(0.22, 1, 0.36, 1)';
 
 export interface TabBarProps {
   /** Tab list */
@@ -107,6 +109,9 @@ export const TabBar: React.FC<TabBarProps> = ({
   const containerRef = useRef<HTMLDivElement>(null);
   const tabsListRef = useRef<HTMLDivElement>(null);
   const actionsRef = useRef<HTMLDivElement>(null);
+  const tabWrapperRefs = useRef<Map<string, HTMLDivElement>>(new Map());
+  const pendingReorderRectsRef = useRef<Map<string, DOMRect> | null>(null);
+  const reorderAnimationsRef = useRef<Map<string, Animation>>(new Map());
   // Cache actual tab widths (keyed by tab.id + title since title affects width)
   const tabWidthCacheRef = useRef<Map<string, number>>(new Map());
 
@@ -234,6 +239,46 @@ export const TabBar: React.FC<TabBarProps> = ({
   // Split visible and overflow tabs
   const displayedTabs = visibleTabs.slice(0, visibleTabsCount);
   const overflowTabs = visibleTabs.slice(visibleTabsCount);
+  const displayedTabSignature = displayedTabs.map(tab => tab.id).join(':');
+
+  useEffect(() => () => {
+    reorderAnimationsRef.current.forEach(animation => animation.cancel());
+    reorderAnimationsRef.current.clear();
+  }, []);
+
+  useLayoutEffect(() => {
+    const previousRects = pendingReorderRectsRef.current;
+    if (!previousRects) return;
+    pendingReorderRectsRef.current = null;
+
+    const reduceMotion = window.matchMedia?.('(prefers-reduced-motion: reduce)').matches ?? false;
+    if (reduceMotion) return;
+
+    for (const [tabId, element] of tabWrapperRefs.current) {
+      const previousRect = previousRects.get(tabId);
+      if (!previousRect) continue;
+      const deltaX = previousRect.left - element.getBoundingClientRect().left;
+      if (Math.abs(deltaX) < 0.5) continue;
+
+      reorderAnimationsRef.current.get(tabId)?.cancel();
+      const animation = element.animate(
+        [
+          { transform: `translateX(${deltaX}px)` },
+          { transform: 'translateX(0)' },
+        ],
+        {
+          duration: TAB_REORDER_DURATION_MS,
+          easing: TAB_REORDER_EASING,
+        },
+      );
+      reorderAnimationsRef.current.set(tabId, animation);
+      animation.addEventListener('finish', () => {
+        if (reorderAnimationsRef.current.get(tabId) === animation) {
+          reorderAnimationsRef.current.delete(tabId);
+        }
+      }, { once: true });
+    }
+  }, [displayedTabSignature]);
 
   // Handle tab drag start
   const handleTabDragStart = useCallback((tab: CanvasTab) => (_e: React.DragEvent) => {
@@ -274,6 +319,11 @@ export const TabBar: React.FC<TabBarProps> = ({
       if (data.sourceGroupId === groupId) {
         const currentIndex = visibleTabs.findIndex(t => t.id === data.tabId);
         if (currentIndex !== -1 && currentIndex !== targetIndex) {
+          pendingReorderRectsRef.current = new Map(
+            Array.from(tabWrapperRefs.current, ([tabId, element]) => (
+              [tabId, element.getBoundingClientRect()] as const
+            )),
+          );
           onReorderTab(data.tabId, targetIndex);
         }
       }
@@ -282,6 +332,26 @@ export const TabBar: React.FC<TabBarProps> = ({
     }
   }, [draggingTabId, groupId, visibleTabs, onReorderTab]);
 
+  const draggingDisplayedIndex = draggingTabId
+    ? displayedTabs.findIndex(tab => tab.id === draggingTabId)
+    : -1;
+  const draggedTabWidth = draggingDisplayedIndex >= 0
+    ? getTabWidth(displayedTabs[draggingDisplayedIndex])
+    : 0;
+
+  const getDragShift = (index: number): number => {
+    if (dragOverIndex === null || draggingDisplayedIndex < 0 || index === draggingDisplayedIndex) {
+      return 0;
+    }
+    if (draggingDisplayedIndex < dragOverIndex && index > draggingDisplayedIndex && index <= dragOverIndex) {
+      return -draggedTabWidth;
+    }
+    if (draggingDisplayedIndex > dragOverIndex && index >= dragOverIndex && index < draggingDisplayedIndex) {
+      return draggedTabWidth;
+    }
+    return 0;
+  };
+
   // Clear indicator when drag ends
   useEffect(() => {
     if (!draggingTabId) {
@@ -308,8 +378,18 @@ export const TabBar: React.FC<TabBarProps> = ({
           <div
             data-bf-component="canvas-tab-bar"
             data-bf-part="tabWrapper"
+            data-tab-id={tab.id}
             key={tab.id}
             className="canvas-tab-bar__tab-wrapper"
+            ref={(element) => {
+              if (element) tabWrapperRefs.current.set(tab.id, element);
+              else tabWrapperRefs.current.delete(tab.id);
+            }}
+            style={{
+              transform: getDragShift(index) === 0
+                ? undefined
+                : `translateX(${getDragShift(index)}px)`,
+            }}
             onDragOver={(e) => handleDragOver(e, index)}
             onDragLeave={handleDragLeave}
             onDrop={(e) => handleDrop(e, index)}
diff --git a/src/web-ui/src/app/components/panels/review-platform/ReviewPlatformPanel.scss b/src/web-ui/src/app/components/panels/review-platform/ReviewPlatformPanel.scss
index cadea53465..43d451fbdd 100644
--- a/src/web-ui/src/app/components/panels/review-platform/ReviewPlatformPanel.scss
+++ b/src/web-ui/src/app/components/panels/review-platform/ReviewPlatformPanel.scss
@@ -1699,3 +1699,11 @@
     }
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .review-platform__loading-inline--icon,
+  .review-platform__thread-loading svg {
+    animation: none;
+    transform: none;
+  }
+}
diff --git a/src/web-ui/src/app/components/scheduled-jobs/DateTimePickerPopover.appearance.ts b/src/web-ui/src/app/components/scheduled-jobs/DateTimePickerPopover.appearance.ts
new file mode 100644
index 0000000000..cc74975b31
--- /dev/null
+++ b/src/web-ui/src/app/components/scheduled-jobs/DateTimePickerPopover.appearance.ts
@@ -0,0 +1,16 @@
+import type { AppearanceSurfaceDescriptor } from '@/infrastructure/appearance';
+
+export const dateTimePickerAppearanceDescriptor: AppearanceSurfaceDescriptor = {
+  id: 'datetime-picker',
+  parts: [
+    { id: 'root' },
+    { id: 'head' },
+    { id: 'grid' },
+    { id: 'day' },
+    { id: 'foot' },
+  ],
+  states: [
+    { id: 'selected', selector: { kind: 'self', suffix: '[data-bf-state~="selected"]' } },
+    { id: 'today', selector: { kind: 'self', suffix: '[data-bf-state~="today"]' } },
+  ],
+};
diff --git a/src/web-ui/src/app/components/scheduled-jobs/DateTimePickerPopover.tsx b/src/web-ui/src/app/components/scheduled-jobs/DateTimePickerPopover.tsx
new file mode 100644
index 0000000000..0ffac464dd
--- /dev/null
+++ b/src/web-ui/src/app/components/scheduled-jobs/DateTimePickerPopover.tsx
@@ -0,0 +1,215 @@
+/**
+ * Day picker for `LocalizedDateTimeField`.
+ *
+ * Replaces the browser's own picker, which was driven through `showPicker()` on
+ * a hidden anchor input and would not dismiss after a selection — its
+ * open/close lifecycle assumes a real, hit-testable anchor. Rendering the grid
+ * in-app puts that lifecycle under our control, and keeps the calendar in the
+ * app's own locale and theme.
+ *
+ * Scope is deliberately the date only: the time is easier to type than to click,
+ * and the text field already accepts it.
+ */
+
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { ChevronLeft, ChevronRight } from 'lucide-react';
+import { IconButton, Button } from '@/component-library';
+import { getAppearanceOverlayHost } from '@/infrastructure/appearance/runtime/AppearanceOverlayHost';
+import { useI18n } from '@/infrastructure/i18n';
+import { computeFixedPopoverPosition } from '@/shared/utils/fixedPopoverViewport';
+
+const POPOVER_WIDTH = 268;
+const POPOVER_HEIGHT = 300;
+
+/** Six-week grid (42 local days) covering the month `monthAnchorMs` falls in. */
+function buildMonthGrid(monthAnchorMs: number): Date[] {
+  const anchor = new Date(monthAnchorMs);
+  const firstOfMonth = new Date(anchor.getFullYear(), anchor.getMonth(), 1);
+  const gridStart = new Date(firstOfMonth);
+  gridStart.setDate(firstOfMonth.getDate() - firstOfMonth.getDay());
+
+  return Array.from({ length: 42 }, (_, index) => {
+    const day = new Date(gridStart);
+    day.setDate(gridStart.getDate() + index);
+    return day;
+  });
+}
+
+function isSameDay(left: Date, right: Date): boolean {
+  return left.getFullYear() === right.getFullYear()
+    && left.getMonth() === right.getMonth()
+    && left.getDate() === right.getDate();
+}
+
+export interface DateTimePickerPopoverProps {
+  /** Element the popover is positioned against. */
+  anchorRef: React.RefObject<HTMLElement | null>;
+  /** Currently selected day, or null when the field is empty. */
+  selected: Date | null;
+  onSelect: (day: Date) => void;
+  onClose: () => void;
+}
+
+const DateTimePickerPopover: React.FC<DateTimePickerPopoverProps> = ({
+  anchorRef,
+  selected,
+  onSelect,
+  onClose,
+}) => {
+  const { t, formatDate } = useI18n('common');
+  const popoverRef = useRef<HTMLDivElement | null>(null);
+
+  const [monthAnchorMs, setMonthAnchorMs] = useState(() => {
+    const base = selected ?? new Date();
+    return new Date(base.getFullYear(), base.getMonth(), 1).getTime();
+  });
+  const [position, setPosition] = useState(() => {
+    const rect = anchorRef.current?.getBoundingClientRect();
+    return rect
+      ? computeFixedPopoverPosition(rect, POPOVER_WIDTH, POPOVER_HEIGHT)
+      : { top: 0, left: 0 };
+  });
+
+  // Reposition against the live popover size once it has painted, and keep it
+  // anchored while the surrounding form scrolls.
+  useEffect(() => {
+    const reposition = () => {
+      const rect = anchorRef.current?.getBoundingClientRect();
+      if (!rect) return;
+      const element = popoverRef.current;
+      setPosition(computeFixedPopoverPosition(
+        rect,
+        element?.offsetWidth ?? POPOVER_WIDTH,
+        element?.offsetHeight ?? POPOVER_HEIGHT,
+      ));
+    };
+
+    reposition();
+    window.addEventListener('resize', reposition);
+    window.addEventListener('scroll', reposition, true);
+    return () => {
+      window.removeEventListener('resize', reposition);
+      window.removeEventListener('scroll', reposition, true);
+    };
+  }, [anchorRef]);
+
+  useEffect(() => {
+    const handlePointerDown = (event: MouseEvent) => {
+      const target = event.target as Node | null;
+      if (!target) return;
+      if (popoverRef.current?.contains(target)) return;
+      if (anchorRef.current?.contains(target)) return;
+      onClose();
+    };
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') onClose();
+    };
+
+    document.addEventListener('mousedown', handlePointerDown);
+    document.addEventListener('keydown', handleKeyDown);
+    return () => {
+      document.removeEventListener('mousedown', handlePointerDown);
+      document.removeEventListener('keydown', handleKeyDown);
+    };
+  }, [anchorRef, onClose]);
+
+  const grid = useMemo(() => buildMonthGrid(monthAnchorMs), [monthAnchorMs]);
+  const anchorDate = useMemo(() => new Date(monthAnchorMs), [monthAnchorMs]);
+  const today = useMemo(() => new Date(), []);
+
+  const weekdayLabels = useMemo(
+    () => grid.slice(0, 7).map(day => formatDate(day, { weekday: 'narrow' })),
+    [formatDate, grid],
+  );
+
+  const shiftMonth = useCallback((delta: number) => {
+    setMonthAnchorMs(current => {
+      const date = new Date(current);
+      return new Date(date.getFullYear(), date.getMonth() + delta, 1).getTime();
+    });
+  }, []);
+
+  return createPortal(
+    <div
+      ref={popoverRef}
+      className="bf-datetime-picker"
+      data-bf-component="datetime-picker"
+      data-bf-part="root"
+      data-testid="datetime-picker"
+      role="dialog"
+      aria-label={t('dateTimeField.pickerLabel')}
+      style={{ top: position.top, left: position.left }}
+    >
+      <header className="bf-datetime-picker__head" data-bf-component="datetime-picker" data-bf-part="head">
+        <IconButton
+          type="button"
+          size="xs"
+          aria-label={t('dateTimeField.previousMonth')}
+          onClick={() => shiftMonth(-1)}
+        >
+          <ChevronLeft size={14} />
+        </IconButton>
+        <span className="bf-datetime-picker__month">
+          {formatDate(anchorDate, { year: 'numeric', month: 'long' })}
+        </span>
+        <IconButton
+          type="button"
+          size="xs"
+          aria-label={t('dateTimeField.nextMonth')}
+          onClick={() => shiftMonth(1)}
+        >
+          <ChevronRight size={14} />
+        </IconButton>
+      </header>
+
+      <div className="bf-datetime-picker__weekdays" aria-hidden="true">
+        {weekdayLabels.map((label, index) => (
+          <span key={index} className="bf-datetime-picker__weekday">{label}</span>
+        ))}
+      </div>
+
+      <div className="bf-datetime-picker__grid" role="grid" data-bf-component="datetime-picker" data-bf-part="grid">
+        {grid.map(day => {
+          const isCurrentMonth = day.getMonth() === anchorDate.getMonth();
+          const isSelected = selected != null && isSameDay(day, selected);
+          const isToday = isSameDay(day, today);
+
+          return (
+            <button
+              key={day.getTime()}
+              type="button"
+              role="gridcell"
+              className={[
+                'bf-datetime-picker__day',
+                isCurrentMonth ? '' : 'bf-datetime-picker__day--outside',
+                isToday ? 'bf-datetime-picker__day--today' : '',
+                isSelected ? 'bf-datetime-picker__day--selected' : '',
+              ].filter(Boolean).join(' ')}
+              data-bf-component="datetime-picker"
+              data-bf-part="day"
+              data-bf-state={isSelected ? 'selected' : isToday ? 'today' : undefined}
+              aria-pressed={isSelected}
+              aria-label={formatDate(day, { year: 'numeric', month: 'long', day: 'numeric' })}
+              onClick={() => onSelect(day)}
+            >
+              {day.getDate()}
+            </button>
+          );
+        })}
+      </div>
+
+      <footer className="bf-datetime-picker__foot" data-bf-component="datetime-picker" data-bf-part="foot">
+        <Button size="small" variant="ghost" onClick={() => onSelect(new Date())}>
+          {t('dateTimeField.now')}
+        </Button>
+        <Button size="small" variant="ghost" onClick={onClose}>
+          {t('dateTimeField.close')}
+        </Button>
+      </footer>
+    </div>,
+    getAppearanceOverlayHost(),
+  );
+};
+
+export default DateTimePickerPopover;
diff --git a/src/web-ui/src/app/components/scheduled-jobs/LocalizedDateTimeField.appearance.ts b/src/web-ui/src/app/components/scheduled-jobs/LocalizedDateTimeField.appearance.ts
new file mode 100644
index 0000000000..62cf0deb06
--- /dev/null
+++ b/src/web-ui/src/app/components/scheduled-jobs/LocalizedDateTimeField.appearance.ts
@@ -0,0 +1,11 @@
+import type { AppearanceSurfaceDescriptor } from '@/infrastructure/appearance';
+
+export const localizedDateTimeFieldAppearanceDescriptor: AppearanceSurfaceDescriptor = {
+  id: 'localized-datetime-field',
+  parts: [
+    { id: 'root' },
+  ],
+  states: [
+    { id: 'error', selector: { kind: 'self', suffix: '[data-bf-state~="error"]' } },
+  ],
+};
diff --git a/src/web-ui/src/app/components/scheduled-jobs/LocalizedDateTimeField.scss b/src/web-ui/src/app/components/scheduled-jobs/LocalizedDateTimeField.scss
new file mode 100644
index 0000000000..f07bfc1632
--- /dev/null
+++ b/src/web-ui/src/app/components/scheduled-jobs/LocalizedDateTimeField.scss
@@ -0,0 +1,109 @@
+@use '../../../component-library/styles/tokens.scss' as *;
+
+.bf-datetime-field {
+  position: relative;
+  display: flex;
+  align-items: center;
+  gap: $size-gap-1;
+  min-width: 0;
+
+  &__input {
+    flex: 1 1 auto;
+    min-width: 0;
+  }
+}
+
+.bf-datetime-picker {
+  position: fixed;
+  z-index: 9999;
+  width: 268px;
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  gap: $size-gap-2;
+  padding: $size-gap-3;
+  border: 1px solid var(--bf-appearance-token-border-subtle);
+  border-radius: $size-radius-lg;
+  // Opaque elevated surface, matching the nav workspace menu. A translucent
+  // element background let the form behind it read through the grid.
+  background: var(--bf-appearance-token-color-bg-elevated);
+  box-shadow: 0 4px 12px var(--bf-appearance-token-color-overlay-black-30);
+
+  &__head {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: $size-gap-2;
+  }
+
+  &__month {
+    flex: 1 1 auto;
+    text-align: center;
+    font-size: var(--bf-appearance-token-font-size-sm);
+    font-weight: $font-weight-semibold;
+    color: var(--bf-appearance-token-color-text-primary);
+  }
+
+  &__weekdays,
+  &__grid {
+    display: grid;
+    grid-template-columns: repeat(7, minmax(0, 1fr));
+    gap: 2px;
+  }
+
+  &__weekday {
+    padding: 2px 0;
+    text-align: center;
+    font-size: var(--bf-appearance-token-font-size-2xs);
+    font-weight: $font-weight-semibold;
+    color: var(--bf-appearance-token-color-text-muted);
+  }
+
+  &__day {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    height: 28px;
+    padding: 0;
+    border: 1px solid transparent;
+    border-radius: $size-radius-base;
+    background: transparent;
+    color: var(--bf-appearance-token-color-text-primary);
+    font-size: var(--bf-appearance-token-font-size-xs);
+    font-variant-numeric: tabular-nums;
+    cursor: pointer;
+    transition: background $motion-fast $easing-standard;
+
+    &:hover {
+      background: var(--bf-appearance-token-element-bg-soft);
+    }
+
+    &:focus-visible {
+      outline: 2px solid var(--bf-appearance-token-color-accent-500);
+      outline-offset: 1px;
+    }
+
+    &--outside {
+      color: var(--bf-appearance-token-color-text-muted);
+      opacity: 0.55;
+    }
+
+    &--today {
+      border-color: color-mix(in srgb, var(--bf-appearance-token-color-accent-500) 55%, transparent);
+    }
+
+    &--selected {
+      background: var(--bf-appearance-token-color-accent-500);
+      color: var(--bf-appearance-token-color-static-white);
+    }
+  }
+
+  &__foot {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: $size-gap-2;
+    padding-top: $size-gap-2;
+    border-top: 1px solid color-mix(in srgb, var(--bf-appearance-token-border-subtle) 70%, transparent);
+  }
+}
diff --git a/src/web-ui/src/app/components/scheduled-jobs/LocalizedDateTimeField.tsx b/src/web-ui/src/app/components/scheduled-jobs/LocalizedDateTimeField.tsx
new file mode 100644
index 0000000000..cc31e9ca7c
--- /dev/null
+++ b/src/web-ui/src/app/components/scheduled-jobs/LocalizedDateTimeField.tsx
@@ -0,0 +1,164 @@
+/**
+ * Date-time entry whose field order follows the app locale.
+ *
+ * A native `<input type="datetime-local">` renders in the *browser's* locale,
+ * which Chromium takes from the OS and does not read from the `lang`
+ * attribute. Running the UI in Chinese on an English system therefore shows
+ * `08/12/2026, 04:48 AM` inside an otherwise Chinese form.
+ *
+ * This is an ordinary text input so it looks and behaves like every other field
+ * in the form, showing `2026/08/12 04:48` in Chinese and `08/12/2026 04:48` in
+ * English, with an in-app day picker on the calendar button. Callers keep the
+ * native `YYYY-MM-DDTHH:mm` value contract.
+ */
+
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { CalendarDays } from 'lucide-react';
+import { IconButton, Input } from '@/component-library';
+import { useI18n } from '@/infrastructure/i18n';
+import DateTimePickerPopover from './DateTimePickerPopover';
+import {
+  dateTimeFormatHint,
+  formatDateTimeText,
+  parseDateTimeText,
+  resolveDateFieldOrder,
+} from './localizedDateTime';
+
+/** Time a picked day falls back to when the field has no time yet. */
+const DEFAULT_TIME = { hour: 9, minute: 0 };
+
+function pad(value: number): string {
+  return String(value).padStart(2, '0');
+}
+
+export interface LocalizedDateTimeFieldProps {
+  /** `YYYY-MM-DDTHH:mm`, matching the native datetime-local value. */
+  value: string;
+  onChange: (value: string) => void;
+  error?: boolean;
+  disabled?: boolean;
+  className?: string;
+  'aria-label'?: string;
+}
+
+const LocalizedDateTimeField: React.FC<LocalizedDateTimeFieldProps> = ({
+  value,
+  onChange,
+  error = false,
+  disabled = false,
+  className,
+  'aria-label': ariaLabel,
+}) => {
+  const { t, currentLanguage } = useI18n('common');
+  const anchorRef = useRef<HTMLDivElement | null>(null);
+  const editingRef = useRef(false);
+  const [pickerOpen, setPickerOpen] = useState(false);
+
+  const order = useMemo(() => resolveDateFieldOrder(currentLanguage), [currentLanguage]);
+
+  // Local text so partial input survives; a fully controlled field would reject
+  // every keystroke until the whole date parsed, which makes it untypable.
+  const [text, setText] = useState(() => formatDateTimeText(value, order));
+
+  // Adopt external changes (loading a job, switching locale) unless the user is
+  // mid-edit, where overwriting their keystrokes would fight them.
+  useEffect(() => {
+    if (editingRef.current) return;
+    setText(formatDateTimeText(value, order));
+  }, [order, value]);
+
+  const commitText = useCallback((nextText: string) => {
+    setText(nextText);
+
+    if (!nextText.trim()) {
+      onChange('');
+      return;
+    }
+
+    const parsed = parseDateTimeText(nextText, order);
+    if (parsed) onChange(parsed);
+  }, [onChange, order]);
+
+  const handleBlur = useCallback(() => {
+    editingRef.current = false;
+
+    // Normalize whatever parsed into the canonical rendering, so `2026/8/2 4:8`
+    // settles as `2026/08/02 04:08` instead of staying half-typed.
+    const parsed = text.trim() ? parseDateTimeText(text, order) : null;
+    setText(parsed ? formatDateTimeText(parsed, order) : text);
+  }, [order, text]);
+
+  /** Day currently represented by the field, for highlighting in the picker. */
+  const selectedDay = useMemo(() => {
+    const parsed = parseDateTimeText(text, order) ?? (value.trim() || null);
+    if (!parsed) return null;
+    const timestamp = new Date(parsed).getTime();
+    return Number.isFinite(timestamp) ? new Date(timestamp) : null;
+  }, [order, text, value]);
+
+  const handlePickDay = useCallback((day: Date) => {
+    // Keep whatever time is already set; picking a day should not silently
+    // rewind the clock to midnight.
+    const existing = selectedDay;
+    const hour = existing ? existing.getHours() : DEFAULT_TIME.hour;
+    const minute = existing ? existing.getMinutes() : DEFAULT_TIME.minute;
+
+    const next = [
+      String(day.getFullYear()).padStart(4, '0'),
+      pad(day.getMonth() + 1),
+      pad(day.getDate()),
+    ].join('-') + `T${pad(hour)}:${pad(minute)}`;
+
+    editingRef.current = false;
+    setText(formatDateTimeText(next, order));
+    onChange(next);
+    setPickerOpen(false);
+  }, [onChange, order, selectedDay]);
+
+  return (
+    <div
+      ref={anchorRef}
+      className={['bf-datetime-field', className ?? ''].filter(Boolean).join(' ')}
+      data-bf-component="localized-datetime-field"
+      data-bf-part="root"
+      data-bf-state={error ? 'error' : undefined}
+    >
+      <Input
+        size="small"
+        value={text}
+        error={error}
+        disabled={disabled}
+        inputMode="numeric"
+        placeholder={dateTimeFormatHint(order)}
+        aria-label={ariaLabel ?? t('dateTimeField.label')}
+        className="bf-datetime-field__input"
+        onFocus={() => { editingRef.current = true; }}
+        onChange={event => commitText(event.currentTarget.value)}
+        onBlur={handleBlur}
+      />
+
+      <IconButton
+        type="button"
+        size="xs"
+        disabled={disabled}
+        aria-label={t('dateTimeField.openPicker')}
+        tooltip={t('dateTimeField.openPicker')}
+        aria-expanded={pickerOpen}
+        onClick={() => setPickerOpen(open => !open)}
+      >
+        <CalendarDays size={14} />
+      </IconButton>
+
+      {pickerOpen && !disabled ? (
+        <DateTimePickerPopover
+          anchorRef={anchorRef}
+          selected={selectedDay}
+          onSelect={handlePickDay}
+          onClose={() => setPickerOpen(false)}
+        />
+      ) : null}
+    </div>
+  );
+};
+
+export default LocalizedDateTimeField;
diff --git a/src/web-ui/src/app/components/scheduled-jobs/ScheduledJobsView.scss b/src/web-ui/src/app/components/scheduled-jobs/ScheduledJobsView.scss
index 3383de22cd..886813e0b9 100644
--- a/src/web-ui/src/app/components/scheduled-jobs/ScheduledJobsView.scss
+++ b/src/web-ui/src/app/components/scheduled-jobs/ScheduledJobsView.scss
@@ -338,6 +338,11 @@
       grid-template-columns: minmax(0, 1fr) auto;
       align-items: start;
     }
+
+    &--interval {
+      grid-template-columns: minmax(0, 1fr) minmax(84px, auto);
+      align-items: center;
+    }
   }
 
   &__toggle-card {
diff --git a/src/web-ui/src/app/components/scheduled-jobs/ScheduledJobsView.tsx b/src/web-ui/src/app/components/scheduled-jobs/ScheduledJobsView.tsx
index 23b1abc13f..838df20560 100644
--- a/src/web-ui/src/app/components/scheduled-jobs/ScheduledJobsView.tsx
+++ b/src/web-ui/src/app/components/scheduled-jobs/ScheduledJobsView.tsx
@@ -20,10 +20,8 @@ import {
   cronAPI,
   type CreateCronJobRequest,
   type CronJob,
-  type CronJobTarget,
   type CronJobTargetKind,
   type CronSchedule,
-  type CronWorkspaceRef,
   type UpdateCronJobRequest,
 } from '@/infrastructure/api';
 import { agentAPI, type ModeInfo } from '@/infrastructure/api/service-api/AgentAPI';
@@ -39,41 +37,36 @@ import { createLogger } from '@/shared/utils/logger';
 import { i18nService } from '@/infrastructure/i18n';
 import { resolveSessionTitle } from '@/flow_chat/utils/sessionTitle';
 import { WorkspaceKind } from '@/shared/types';
-import { normalizePath } from '@/shared/utils/pathUtils';
+import {
+  ASSISTANT_WORKSPACE_AGENT_TYPE,
+  DEFAULT_AGENT_TYPE,
+  EMPTY_VALIDATION_ERRORS,
+  INTERVAL_UNIT_OPTIONS,
+  SCHEDULED_JOBS_CHANGED_EVENT,
+  buildScheduleFromDraft,
+  buildTargetFromDraft,
+  buildWorkspaceRef,
+  createEmptyDraft,
+  formatIntervalValue,
+  splitInterval,
+  getCurrentLocalDateTimeInput,
+  getNextExecutionAtMs,
+  hasValidationErrors,
+  isFutureLocalDateTimeInput,
+  jobToDraft,
+  notifyScheduledJobsChanged as emitScheduledJobsChanged,
+  validateDraft,
+  type IntervalUnit,
+  type JobDraft,
+  type JobDraftValidationErrors,
+  type ScheduleKind,
+} from './scheduledJobDraft';
+import LocalizedDateTimeField from './LocalizedDateTimeField';
+import './LocalizedDateTimeField.scss';
 import './ScheduledJobsView.scss';
 
 const log = createLogger('ScheduledJobsView');
-const MINUTE_IN_MS = 60_000;
 const NEW_JOB_ID = '__new__';
-const DEFAULT_AGENT_TYPE = 'agentic';
-const ASSISTANT_WORKSPACE_AGENT_TYPE = 'Claw';
-const SCHEDULED_JOBS_CHANGED_EVENT = 'bitfun:scheduled-jobs-changed';
-
-type ScheduleKind = CronSchedule['kind'];
-
-interface JobDraft {
-  name: string;
-  text: string;
-  enabled: boolean;
-  sessionId: string;
-  agentType: string;
-  scheduleKind: ScheduleKind;
-  at: string;
-  everyMinutes: string;
-  anchorMs: string;
-  expr: string;
-  tz: string;
-}
-
-interface JobDraftValidationErrors {
-  name: boolean;
-  sessionId: boolean;
-  agentType: boolean;
-  text: boolean;
-  at: boolean;
-  everyMinutes: boolean;
-  cronExpr: boolean;
-}
 
 export interface ScheduledJobsViewProps {
   workspacePath?: string;
@@ -91,32 +84,6 @@ export interface ScheduledJobsViewProps {
   assistantWorkspaceMode?: boolean;
 }
 
-function getCurrentLocalDateTimeInput(): string {
-  return toLocalDateTimeInput(new Date().toISOString());
-}
-
-function toLocalDateTimeInput(isoTimestamp: string): string {
-  const date = new Date(isoTimestamp);
-  const timezoneOffset = date.getTimezoneOffset();
-  const localDate = new Date(date.getTime() - timezoneOffset * 60_000);
-  return localDate.toISOString().slice(0, 16);
-}
-
-function timestampMsToLocalDateTimeInput(timestampMs: number): string {
-  return toLocalDateTimeInput(new Date(timestampMs).toISOString());
-}
-
-function isFutureLocalDateTimeInput(value: string, nowMs = Date.now()): boolean {
-  const timestampMs = new Date(value).getTime();
-  return Number.isFinite(timestampMs) && timestampMs > nowMs;
-}
-
-function formatEveryMinutes(everyMs: number): string {
-  const everyMinutes = everyMs / MINUTE_IN_MS;
-  if (Number.isInteger(everyMinutes)) return String(everyMinutes);
-  return everyMinutes.toFixed(2).replace(/\.?0+$/, '');
-}
-
 function getDefaultAgentType(
   targetKind: CronJobTargetKind,
   workspaceKind?: WorkspaceKind,
@@ -127,139 +94,6 @@ function getDefaultAgentType(
   return DEFAULT_AGENT_TYPE;
 }
 
-function createEmptyDraft(defaultSessionId = '', defaultAgentType = DEFAULT_AGENT_TYPE): JobDraft {
-  return {
-    name: '',
-    text: '',
-    enabled: true,
-    sessionId: defaultSessionId,
-    agentType: defaultAgentType,
-    scheduleKind: 'at',
-    at: getCurrentLocalDateTimeInput(),
-    everyMinutes: '60',
-    anchorMs: '',
-    expr: '0 8 * * *',
-    tz: '',
-  };
-}
-
-function buildWorkspaceRef(
-  workspacePath?: string,
-  workspaceId?: string,
-  remoteConnectionId?: string | null,
-  remoteSshHost?: string | null,
-): CronWorkspaceRef | null {
-  const normalizedWorkspacePath = normalizePath(workspacePath?.trim() ?? '');
-  if (!normalizedWorkspacePath) {
-    return null;
-  }
-
-  return {
-    workspacePath: normalizedWorkspacePath,
-    workspaceId: workspaceId?.trim() || undefined,
-    remoteConnectionId: remoteConnectionId?.trim() || undefined,
-    remoteSshHost: remoteSshHost?.trim() || undefined,
-  };
-}
-
-function buildTargetFromDraft(
-  targetKind: CronJobTargetKind,
-  draft: JobDraft,
-  workspace: CronWorkspaceRef,
-): CronJobTarget {
-  if (targetKind === 'session') {
-    return {
-      kind: 'session',
-      sessionId: draft.sessionId.trim(),
-      workspace,
-    };
-  }
-
-  return {
-    kind: 'workspace',
-    workspace,
-    launch: {
-      agentType: draft.agentType.trim() || DEFAULT_AGENT_TYPE,
-    },
-  };
-}
-
-function jobToDraft(job: CronJob, defaultAgentType: string): JobDraft {
-  const base = createEmptyDraft('', defaultAgentType);
-  const draft: JobDraft = {
-    ...base,
-    name: job.name,
-    text: job.payload.text,
-    enabled: job.enabled,
-  };
-  if (job.target.kind === 'session') {
-    draft.sessionId = job.target.sessionId;
-  } else {
-    draft.agentType = job.target.launch.agentType || defaultAgentType;
-  }
-  if (job.schedule.kind === 'at') {
-    draft.scheduleKind = 'at';
-    draft.at = toLocalDateTimeInput(job.schedule.at);
-  } else if (job.schedule.kind === 'every') {
-    draft.scheduleKind = 'every';
-    draft.everyMinutes = formatEveryMinutes(job.schedule.everyMs);
-    draft.anchorMs = job.schedule.anchorMs != null
-      ? timestampMsToLocalDateTimeInput(job.schedule.anchorMs)
-      : '';
-  } else {
-    draft.scheduleKind = 'cron';
-    draft.expr = job.schedule.expr;
-    draft.tz = job.schedule.tz ?? '';
-  }
-  return draft;
-}
-
-function buildScheduleFromDraft(draft: JobDraft): CronSchedule {
-  if (draft.scheduleKind === 'at') {
-    return { kind: 'at', at: new Date(draft.at).toISOString() };
-  }
-  if (draft.scheduleKind === 'every') {
-    const everyMinutes = Number(draft.everyMinutes);
-    const anchorMs = draft.anchorMs.trim() ? new Date(draft.anchorMs).getTime() : undefined;
-    return { kind: 'every', everyMs: Math.round(everyMinutes * MINUTE_IN_MS), anchorMs };
-  }
-  return { kind: 'cron', expr: draft.expr.trim(), tz: draft.tz.trim() || undefined };
-}
-
-function validateDraft(
-  targetKind: CronJobTargetKind,
-  draft: JobDraft,
-): JobDraftValidationErrors {
-  const everyMinutes = Number(draft.everyMinutes);
-  return {
-    name: !draft.name.trim(),
-    sessionId: targetKind === 'session' && !draft.sessionId.trim(),
-    agentType: targetKind === 'workspace' && !draft.agentType.trim(),
-    text: !draft.text.trim(),
-    at: draft.scheduleKind === 'at' && !draft.at.trim(),
-    everyMinutes:
-      draft.scheduleKind === 'every'
-      && (!draft.everyMinutes.trim() || !Number.isFinite(everyMinutes) || everyMinutes <= 0),
-    cronExpr: draft.scheduleKind === 'cron' && !draft.expr.trim(),
-  };
-}
-
-function hasValidationErrors(errors: JobDraftValidationErrors): boolean {
-  return (
-    errors.name
-    || errors.sessionId
-    || errors.agentType
-    || errors.text
-    || errors.at
-    || errors.everyMinutes
-    || errors.cronExpr
-  );
-}
-
-function getNextExecutionAtMs(job: CronJob): number | null {
-  return job.state.pendingTriggerAtMs ?? job.state.retryAtMs ?? job.state.nextRunAtMs ?? null;
-}
-
 function formatScheduleSummary(
   schedule: CronSchedule,
   formatDate: (date: Date | number, options?: Intl.DateTimeFormatOptions) => string,
@@ -268,8 +102,12 @@ function formatScheduleSummary(
   switch (schedule.kind) {
     case 'at':
       return `${t('nav.scheduledJobs.scheduleKinds.at')}: ${formatTimestamp(new Date(schedule.at).getTime(), formatDate, t)}`;
-    case 'every':
-      return t('nav.scheduledJobs.scheduleSummary.every', { everyMinutes: formatEveryMinutes(schedule.everyMs) });
+    case 'every': {
+      const interval = splitInterval(schedule.everyMs);
+      return t(`nav.scheduledJobs.scheduleSummary.everyUnit.${interval.unit}`, {
+        value: formatIntervalValue(interval.value),
+      });
+    }
     case 'cron':
       return schedule.tz
         ? t('nav.scheduledJobs.scheduleSummary.cronWithTz', { expr: schedule.expr, tz: schedule.tz })
@@ -381,15 +219,9 @@ const ScheduledJobsView: React.FC<ScheduledJobsViewProps> = ({
   const [saving, setSaving] = useState(false);
   const [selectedJobId, setSelectedJobId] = useState<string | null>(null);
   const [expandedJobId, setExpandedJobId] = useState<string | null>(null);
-  const [validationErrors, setValidationErrors] = useState<JobDraftValidationErrors>({
-    name: false,
-    sessionId: false,
-    agentType: false,
-    text: false,
-    at: false,
-    everyMinutes: false,
-    cronExpr: false,
-  });
+  const [validationErrors, setValidationErrors] = useState<JobDraftValidationErrors>(
+    EMPTY_VALIDATION_ERRORS,
+  );
 
   const defaultAgentType = useMemo(
     () => assistantWorkspaceMode
@@ -410,9 +242,7 @@ const ScheduledJobsView: React.FC<ScheduledJobsViewProps> = ({
     : targetKind;
 
   const notifyScheduledJobsChanged = useCallback(() => {
-    window.dispatchEvent(new CustomEvent(SCHEDULED_JOBS_CHANGED_EVENT, {
-      detail: { sourceId: instanceIdRef.current },
-    }));
+    emitScheduledJobsChanged(instanceIdRef.current);
   }, []);
 
   useEffect(() => {
@@ -551,15 +381,7 @@ const ScheduledJobsView: React.FC<ScheduledJobsViewProps> = ({
   ]);
 
   const resetValidationErrors = useCallback(() => {
-    setValidationErrors({
-      name: false,
-      sessionId: false,
-      agentType: false,
-      text: false,
-      at: false,
-      everyMinutes: false,
-      cronExpr: false,
-    });
+    setValidationErrors(EMPTY_VALIDATION_ERRORS);
   }, []);
 
   const handleCreateNew = useCallback(() => {
@@ -947,7 +769,7 @@ const ScheduledJobsView: React.FC<ScheduledJobsViewProps> = ({
                   setValidationErrors(current => ({
                     ...current,
                     at: false,
-                    everyMinutes: false,
+                    everyValue: false,
                     cronExpr: false,
                   }));
                   setDraft(c => ({
@@ -980,13 +802,10 @@ const ScheduledJobsView: React.FC<ScheduledJobsViewProps> = ({
               <span className="asv__field-label">{t('nav.scheduledJobs.fields.at')}</span>
             </div>
             <div className="asv__field-control" data-bf-component="scheduled-jobs-view" data-bf-part="fieldControl">
-              <Input
-                size="small"
-                type="datetime-local"
+              <LocalizedDateTimeField
                 value={draft.at}
                 error={validationErrors.at}
-                onChange={e => {
-                  const at = e.currentTarget.value;
+                onChange={at => {
                   setValidationErrors(current => ({ ...current, at: false }));
                   setDraft(c => ({
                     ...c,
@@ -1006,18 +825,31 @@ const ScheduledJobsView: React.FC<ScheduledJobsViewProps> = ({
                 <span className="asv__field-label">{t('nav.scheduledJobs.fields.everyMs')}</span>
               </div>
               <div className="asv__field-control" data-bf-component="scheduled-jobs-view" data-bf-part="fieldControl">
-                <Input
-                  size="small"
-                  type="number"
-                  value={draft.everyMinutes}
-                  error={validationErrors.everyMinutes}
-                  onChange={e => {
-                    const everyMinutes = e.currentTarget.value;
-                    setValidationErrors(current => ({ ...current, everyMinutes: false }));
-                    setDraft(c => ({ ...c, everyMinutes }));
-                  }}
-                  placeholder="60"
-                />
+                <div className="asv__control-grid asv__control-grid--interval">
+                  <Input
+                    size="small"
+                    type="number"
+                    value={draft.everyValue}
+                    error={validationErrors.everyValue}
+                    onChange={e => {
+                      const everyValue = e.currentTarget.value;
+                      setValidationErrors(current => ({ ...current, everyValue: false }));
+                      setDraft(c => ({ ...c, everyValue }));
+                    }}
+                    placeholder="1"
+                  />
+                  <Select
+                    size="small"
+                    value={draft.everyUnit}
+                    options={INTERVAL_UNIT_OPTIONS.map(unit => ({
+                      value: unit,
+                      label: t(`nav.scheduledJobs.intervalUnits.${unit}`),
+                    }))}
+                    onChange={value => {
+                      setDraft(c => ({ ...c, everyUnit: value as IntervalUnit }));
+                    }}
+                  />
+                </div>
               </div>
             </div>
             <div className="asv__form-row asv__form-row--inline" data-bf-component="scheduled-jobs-view" data-bf-part="field">
@@ -1025,15 +857,10 @@ const ScheduledJobsView: React.FC<ScheduledJobsViewProps> = ({
                 <span className="asv__field-label">{t('nav.scheduledJobs.fields.anchorMs')}</span>
               </div>
               <div className="asv__field-control" data-bf-component="scheduled-jobs-view" data-bf-part="fieldControl">
-                <Input
-                  size="small"
-                  type="datetime-local"
+                <LocalizedDateTimeField
                   value={draft.anchorMs}
-                  onChange={e => {
-                    const anchorMs = e.currentTarget.value;
-                    setDraft(c => ({ ...c, anchorMs }));
-                  }}
-                  placeholder={t('nav.scheduledJobs.placeholders.anchorMs')}
+                  onChange={anchorMs => setDraft(c => ({ ...c, anchorMs }))}
+                  aria-label={t('nav.scheduledJobs.fields.anchorMs')}
                 />
               </div>
             </div>
diff --git a/src/web-ui/src/app/components/scheduled-jobs/localizedDateTime.test.ts b/src/web-ui/src/app/components/scheduled-jobs/localizedDateTime.test.ts
new file mode 100644
index 0000000000..5c71a16b1e
--- /dev/null
+++ b/src/web-ui/src/app/components/scheduled-jobs/localizedDateTime.test.ts
@@ -0,0 +1,90 @@
+/**
+ * This control exists because a native datetime-local renders in the browser's
+ * locale, not the app's. These cases pin the ordering it replaces that with,
+ * and the text <-> value contract callers still rely on.
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  dateTimeFormatHint,
+  formatDateTimeText,
+  parseDateTimeText,
+  resolveDateFieldOrder,
+} from './localizedDateTime';
+
+describe('resolveDateFieldOrder', () => {
+  it('reads year-first for CJK locales, regardless of the browser locale', () => {
+    expect(resolveDateFieldOrder('zh-CN')).toBe('year-first');
+    expect(resolveDateFieldOrder('zh-TW')).toBe('year-first');
+    expect(resolveDateFieldOrder('ja-JP')).toBe('year-first');
+  });
+
+  it('reads month-first for English and unknown locales', () => {
+    expect(resolveDateFieldOrder('en-US')).toBe('month-first');
+    expect(resolveDateFieldOrder(undefined)).toBe('month-first');
+    expect(resolveDateFieldOrder('')).toBe('month-first');
+  });
+});
+
+describe('formatDateTimeText', () => {
+  it('renders in the locale order', () => {
+    expect(formatDateTimeText('2026-08-12T04:48', 'year-first')).toBe('2026/08/12 04:48');
+    expect(formatDateTimeText('2026-08-12T04:48', 'month-first')).toBe('08/12/2026 04:48');
+  });
+
+  it('renders empty for a missing or unparseable value', () => {
+    expect(formatDateTimeText('', 'year-first')).toBe('');
+    expect(formatDateTimeText('nonsense', 'year-first')).toBe('');
+  });
+});
+
+describe('parseDateTimeText', () => {
+  it('round-trips its own rendering in both orders', () => {
+    for (const order of ['year-first', 'month-first'] as const) {
+      const text = formatDateTimeText('2026-08-12T04:48', order);
+      expect(parseDateTimeText(text, order)).toBe('2026-08-12T04:48');
+    }
+  });
+
+  it('accepts loose separators and unpadded numbers', () => {
+    expect(parseDateTimeText('2026-8-12 4:8', 'year-first')).toBe('2026-08-12T04:08');
+    expect(parseDateTimeText('2026.08.12 04:48', 'year-first')).toBe('2026-08-12T04:48');
+    expect(parseDateTimeText('2026/08/12 04:48:30', 'year-first')).toBe('2026-08-12T04:48');
+  });
+
+  it('locates the year by its four digits, whichever order it was typed in', () => {
+    // Someone pasting the other locale's order still lands on the right date.
+    expect(parseDateTimeText('08/12/2026 04:48', 'year-first')).toBe('2026-08-12T04:48');
+    expect(parseDateTimeText('2026/08/12 04:48', 'month-first')).toBe('2026-08-12T04:48');
+  });
+
+  it('falls back to the locale order when no group is four digits', () => {
+    expect(parseDateTimeText('26/8/12 04:48', 'year-first')).toBeNull();
+    expect(parseDateTimeText('8/12/26 04:48', 'month-first')).toBeNull();
+  });
+
+  it('returns null while the text is still incomplete', () => {
+    expect(parseDateTimeText('', 'year-first')).toBeNull();
+    expect(parseDateTimeText('2026', 'year-first')).toBeNull();
+    expect(parseDateTimeText('2026/08/12', 'year-first')).toBeNull();
+  });
+
+  it('rejects out-of-range components', () => {
+    expect(parseDateTimeText('2026/13/12 04:48', 'year-first')).toBeNull();
+    expect(parseDateTimeText('2026/08/12 24:48', 'year-first')).toBeNull();
+    expect(parseDateTimeText('2026/08/12 04:60', 'year-first')).toBeNull();
+  });
+
+  it('clamps a day past the end of its month instead of rolling over', () => {
+    expect(parseDateTimeText('2026/02/31 09:00', 'year-first')).toBe('2026-02-28T09:00');
+    expect(parseDateTimeText('2028/02/31 09:00', 'year-first')).toBe('2028-02-29T09:00');
+    expect(parseDateTimeText('2026/04/31 09:00', 'year-first')).toBe('2026-04-30T09:00');
+  });
+});
+
+describe('dateTimeFormatHint', () => {
+  it('shows the placeholder in the same order the field reads', () => {
+    expect(dateTimeFormatHint('year-first')).toBe('YYYY/MM/DD HH:mm');
+    expect(dateTimeFormatHint('month-first')).toBe('MM/DD/YYYY HH:mm');
+  });
+});
diff --git a/src/web-ui/src/app/components/scheduled-jobs/localizedDateTime.ts b/src/web-ui/src/app/components/scheduled-jobs/localizedDateTime.ts
new file mode 100644
index 0000000000..312b5f615e
--- /dev/null
+++ b/src/web-ui/src/app/components/scheduled-jobs/localizedDateTime.ts
@@ -0,0 +1,99 @@
+/**
+ * Text <-> timestamp helpers for `LocalizedDateTimeField`.
+ *
+ * The field shows and accepts a plain localized string (`2026/08/12 04:48` in
+ * Chinese, `08/12/2026 04:48` in English) while callers keep the native
+ * `YYYY-MM-DDTHH:mm` value contract.
+ *
+ * Kept apart from the component so the parsing rules can be tested directly.
+ */
+
+/** Locales that read year-first. Everything else falls back to month-first. */
+const YEAR_FIRST_LOCALE_PREFIXES = ['zh', 'ja', 'ko'];
+
+export type DateFieldOrder = 'year-first' | 'month-first';
+
+/**
+ * Field order for a locale, driven by the app's language rather than the
+ * browser's — which is the whole reason this control exists.
+ */
+export function resolveDateFieldOrder(locale: string | null | undefined): DateFieldOrder {
+  const language = String(locale ?? '').toLowerCase();
+  return YEAR_FIRST_LOCALE_PREFIXES.some(prefix => language.startsWith(prefix))
+    ? 'year-first'
+    : 'month-first';
+}
+
+/** Days in the given month, so 31 February clamps instead of rolling over. */
+function daysInMonth(year: number, month: number): number {
+  return new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+
+function pad(value: number, length = 2): string {
+  return String(value).padStart(length, '0');
+}
+
+/** Renders a native datetime-local value as localized display text. */
+export function formatDateTimeText(value: string, order: DateFieldOrder): string {
+  const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})/.exec(value.trim());
+  if (!match) return '';
+
+  const [, year, month, day, hour, minute] = match;
+  const date = order === 'year-first'
+    ? `${year}/${month}/${day}`
+    : `${month}/${day}/${year}`;
+  return `${date} ${hour}:${minute}`;
+}
+
+/**
+ * Reads localized display text back into a native datetime-local value.
+ *
+ * Deliberately forgiving about separators, so `2026-08-12 04:48`,
+ * `2026/8/12 4:8` and `2026.08.12 04:48` all work. The four-digit group
+ * identifies the year wherever it sits, which keeps a value pasted in the other
+ * locale's order readable instead of silently landing on the wrong date.
+ * Returns null when the text cannot be read as a complete date and time.
+ */
+export function parseDateTimeText(text: string, order: DateFieldOrder): string | null {
+  const groups = text.match(/\d+/g);
+  if (!groups || groups.length < 5) return null;
+
+  const [a, b, c, hourText, minuteText] = groups;
+
+  let yearText: string;
+  let monthText: string;
+  let dayText: string;
+
+  if (a.length === 4) {
+    [yearText, monthText, dayText] = [a, b, c];
+  } else if (c.length === 4) {
+    [monthText, dayText, yearText] = [a, b, c];
+  } else if (order === 'year-first') {
+    [yearText, monthText, dayText] = [a, b, c];
+  } else {
+    [monthText, dayText, yearText] = [a, b, c];
+  }
+
+  const year = Number(yearText);
+  const month = Number(monthText);
+  const day = Number(dayText);
+  const hour = Number(hourText);
+  const minute = Number(minuteText);
+
+  if (![year, month, day, hour, minute].every(Number.isFinite)) return null;
+  if (year < 1970 || year > 9999) return null;
+  if (month < 1 || month > 12) return null;
+  if (day < 1) return null;
+  if (hour > 23 || minute > 59) return null;
+
+  // Clamp rather than reject: someone typing 31 in a 30-day month means the end
+  // of that month, and rolling into the next one would be a silent wrong date.
+  const clampedDay = Math.min(day, daysInMonth(year, month));
+
+  return `${pad(year, 4)}-${pad(month)}-${pad(clampedDay)}T${pad(hour)}:${pad(minute)}`;
+}
+
+/** Example string used as the field placeholder, in the locale's own order. */
+export function dateTimeFormatHint(order: DateFieldOrder): string {
+  return order === 'year-first' ? 'YYYY/MM/DD HH:mm' : 'MM/DD/YYYY HH:mm';
+}
diff --git a/src/web-ui/src/app/components/scheduled-jobs/scheduledJobDraft.test.ts b/src/web-ui/src/app/components/scheduled-jobs/scheduledJobDraft.test.ts
new file mode 100644
index 0000000000..4b06ce2dd2
--- /dev/null
+++ b/src/web-ui/src/app/components/scheduled-jobs/scheduledJobDraft.test.ts
@@ -0,0 +1,90 @@
+/**
+ * Interval units are entered in one scale and stored in another, so the
+ * round trip is the part worth pinning: what the editor shows must rebuild the
+ * exact millisecond value the scheduler already had.
+ */
+
+import { describe, expect, it } from 'vitest';
+import type { CronJob } from '@/infrastructure/api';
+import {
+  DAY_IN_MS,
+  HOUR_IN_MS,
+  MINUTE_IN_MS,
+  buildScheduleFromDraft,
+  createEmptyDraft,
+  formatIntervalValue,
+  jobToDraft,
+  splitInterval,
+} from './scheduledJobDraft';
+
+function jobWithInterval(everyMs: number): CronJob {
+  return {
+    id: 'cron_test',
+    name: 'test',
+    schedule: { kind: 'every', everyMs },
+    payload: { text: 'hello' },
+    enabled: true,
+    target: {
+      kind: 'workspace',
+      workspace: { workspacePath: '/tmp/workspace' },
+      launch: { agentType: 'agentic' },
+    },
+    createdAtMs: 0,
+    configUpdatedAtMs: 0,
+    updatedAtMs: 0,
+    state: { consecutiveFailures: 0, coalescedRunCount: 0 },
+  };
+}
+
+describe('splitInterval', () => {
+  it('reads a daily interval as days rather than 1440 minutes', () => {
+    expect(splitInterval(DAY_IN_MS)).toEqual({ value: 1, unit: 'day' });
+    expect(splitInterval(3 * DAY_IN_MS)).toEqual({ value: 3, unit: 'day' });
+  });
+
+  it('prefers hours when days do not divide evenly', () => {
+    expect(splitInterval(6 * HOUR_IN_MS)).toEqual({ value: 6, unit: 'hour' });
+    expect(splitInterval(36 * HOUR_IN_MS)).toEqual({ value: 36, unit: 'hour' });
+  });
+
+  it('falls back to minutes for anything finer', () => {
+    expect(splitInterval(30 * MINUTE_IN_MS)).toEqual({ value: 30, unit: 'minute' });
+    expect(splitInterval(90 * MINUTE_IN_MS)).toEqual({ value: 90, unit: 'minute' });
+  });
+
+  it('does not claim a unit for a non-positive interval', () => {
+    expect(splitInterval(0).unit).toBe('minute');
+  });
+});
+
+describe('interval round trip', () => {
+  it.each([
+    ['daily', DAY_IN_MS],
+    ['six hourly', 6 * HOUR_IN_MS],
+    ['half hourly', 30 * MINUTE_IN_MS],
+    ['awkward', 90 * MINUTE_IN_MS],
+  ])('rebuilds the exact interval for a %s job', (_label, everyMs) => {
+    const draft = jobToDraft(jobWithInterval(everyMs), 'agentic');
+    const schedule = buildScheduleFromDraft(draft);
+
+    expect(schedule).toMatchObject({ kind: 'every', everyMs });
+  });
+});
+
+describe('formatIntervalValue', () => {
+  it('keeps whole numbers whole and trims trailing zeros', () => {
+    expect(formatIntervalValue(3)).toBe('3');
+    expect(formatIntervalValue(1.5)).toBe('1.5');
+    expect(formatIntervalValue(2.0)).toBe('2');
+  });
+});
+
+describe('createEmptyDraft', () => {
+  it('defaults to a readable hourly interval', () => {
+    const draft = createEmptyDraft();
+    expect(draft.everyValue).toBe('1');
+    expect(draft.everyUnit).toBe('hour');
+    expect(buildScheduleFromDraft({ ...draft, scheduleKind: 'every' }))
+      .toMatchObject({ kind: 'every', everyMs: HOUR_IN_MS });
+  });
+});
diff --git a/src/web-ui/src/app/components/scheduled-jobs/scheduledJobDraft.ts b/src/web-ui/src/app/components/scheduled-jobs/scheduledJobDraft.ts
new file mode 100644
index 0000000000..13e0435c75
--- /dev/null
+++ b/src/web-ui/src/app/components/scheduled-jobs/scheduledJobDraft.ts
@@ -0,0 +1,267 @@
+/**
+ * Pure draft <-> CronJob conversion helpers shared by every scheduled-job editor.
+ *
+ * These are deliberately free of React and i18n so both the per-workspace
+ * `ScheduledJobsView` and the global Todos scene can build the same request
+ * shapes from the same form state.
+ */
+
+import type {
+  CronJob,
+  CronJobTarget,
+  CronJobTargetKind,
+  CronSchedule,
+  CronWorkspaceRef,
+} from '@/infrastructure/api';
+import { normalizePath } from '@/shared/utils/pathUtils';
+
+export const MINUTE_IN_MS = 60_000;
+export const HOUR_IN_MS = 60 * MINUTE_IN_MS;
+export const DAY_IN_MS = 24 * HOUR_IN_MS;
+export const DEFAULT_AGENT_TYPE = 'agentic';
+export const ASSISTANT_WORKSPACE_AGENT_TYPE = 'Claw';
+
+/**
+ * Interval units offered by the editors.
+ *
+ * The wire format stays milliseconds; the unit only decides how a value is
+ * entered and read back, so a daily job reads "every 1 day" rather than
+ * "every 1440 minutes".
+ */
+export type IntervalUnit = 'minute' | 'hour' | 'day';
+
+/** Selector order, coarsest-last so the common "every N minutes" stays first. */
+export const INTERVAL_UNIT_OPTIONS: readonly IntervalUnit[] = ['minute', 'hour', 'day'];
+
+export const INTERVAL_UNIT_MS: Record<IntervalUnit, number> = {
+  minute: MINUTE_IN_MS,
+  hour: HOUR_IN_MS,
+  day: DAY_IN_MS,
+};
+
+/** Largest unit that divides the interval evenly, so the value stays whole. */
+export function splitInterval(everyMs: number): { value: number; unit: IntervalUnit } {
+  if (Number.isFinite(everyMs) && everyMs > 0) {
+    if (everyMs % DAY_IN_MS === 0) return { value: everyMs / DAY_IN_MS, unit: 'day' };
+    if (everyMs % HOUR_IN_MS === 0) return { value: everyMs / HOUR_IN_MS, unit: 'hour' };
+  }
+  return { value: everyMs / MINUTE_IN_MS, unit: 'minute' };
+}
+
+/** Emitted after any create/update/delete so other mounted views reload. */
+export const SCHEDULED_JOBS_CHANGED_EVENT = 'bitfun:scheduled-jobs-changed';
+
+export type ScheduleKind = CronSchedule['kind'];
+
+export interface JobDraft {
+  name: string;
+  text: string;
+  enabled: boolean;
+  sessionId: string;
+  agentType: string;
+  scheduleKind: ScheduleKind;
+  at: string;
+  /** Interval value in `everyUnit`; kept as a string so the input stays free-form. */
+  everyValue: string;
+  everyUnit: IntervalUnit;
+  anchorMs: string;
+  expr: string;
+  tz: string;
+}
+
+export interface JobDraftValidationErrors {
+  name: boolean;
+  sessionId: boolean;
+  agentType: boolean;
+  text: boolean;
+  at: boolean;
+  everyValue: boolean;
+  cronExpr: boolean;
+}
+
+/** Shared reset value. Frozen because callers hold the same reference. */
+export const EMPTY_VALIDATION_ERRORS: JobDraftValidationErrors = Object.freeze({
+  name: false,
+  sessionId: false,
+  agentType: false,
+  text: false,
+  at: false,
+  everyValue: false,
+  cronExpr: false,
+});
+
+export function toLocalDateTimeInput(isoTimestamp: string): string {
+  const date = new Date(isoTimestamp);
+  const timezoneOffset = date.getTimezoneOffset();
+  const localDate = new Date(date.getTime() - timezoneOffset * MINUTE_IN_MS);
+  return localDate.toISOString().slice(0, 16);
+}
+
+export function getCurrentLocalDateTimeInput(): string {
+  return toLocalDateTimeInput(new Date().toISOString());
+}
+
+export function timestampMsToLocalDateTimeInput(timestampMs: number): string {
+  return toLocalDateTimeInput(new Date(timestampMs).toISOString());
+}
+
+export function isFutureLocalDateTimeInput(value: string, nowMs = Date.now()): boolean {
+  const timestampMs = new Date(value).getTime();
+  return Number.isFinite(timestampMs) && timestampMs > nowMs;
+}
+
+/** Trims a possibly fractional interval value to a short display string. */
+export function formatIntervalValue(value: number): string {
+  if (Number.isInteger(value)) return String(value);
+  return value.toFixed(2).replace(/\.?0+$/, '');
+}
+
+export function createEmptyDraft(
+  defaultSessionId = '',
+  defaultAgentType = DEFAULT_AGENT_TYPE,
+): JobDraft {
+  return {
+    name: '',
+    text: '',
+    enabled: true,
+    sessionId: defaultSessionId,
+    agentType: defaultAgentType,
+    scheduleKind: 'at',
+    at: getCurrentLocalDateTimeInput(),
+    everyValue: '1',
+    everyUnit: 'hour',
+    anchorMs: '',
+    expr: '0 8 * * *',
+    tz: '',
+  };
+}
+
+export function jobToDraft(job: CronJob, defaultAgentType: string): JobDraft {
+  const base = createEmptyDraft('', defaultAgentType);
+  const draft: JobDraft = {
+    ...base,
+    name: job.name,
+    text: job.payload.text,
+    enabled: job.enabled,
+  };
+  if (job.target.kind === 'session') {
+    draft.sessionId = job.target.sessionId;
+  } else {
+    draft.agentType = job.target.launch.agentType || defaultAgentType;
+  }
+  if (job.schedule.kind === 'at') {
+    draft.scheduleKind = 'at';
+    draft.at = toLocalDateTimeInput(job.schedule.at);
+  } else if (job.schedule.kind === 'every') {
+    draft.scheduleKind = 'every';
+    const interval = splitInterval(job.schedule.everyMs);
+    draft.everyValue = formatIntervalValue(interval.value);
+    draft.everyUnit = interval.unit;
+    draft.anchorMs = job.schedule.anchorMs != null
+      ? timestampMsToLocalDateTimeInput(job.schedule.anchorMs)
+      : '';
+  } else {
+    draft.scheduleKind = 'cron';
+    draft.expr = job.schedule.expr;
+    draft.tz = job.schedule.tz ?? '';
+  }
+  return draft;
+}
+
+export function buildScheduleFromDraft(draft: JobDraft): CronSchedule {
+  if (draft.scheduleKind === 'at') {
+    return { kind: 'at', at: new Date(draft.at).toISOString() };
+  }
+  if (draft.scheduleKind === 'every') {
+    const everyValue = Number(draft.everyValue);
+    const anchorMs = draft.anchorMs.trim() ? new Date(draft.anchorMs).getTime() : undefined;
+    return {
+      kind: 'every',
+      everyMs: Math.round(everyValue * INTERVAL_UNIT_MS[draft.everyUnit]),
+      anchorMs,
+    };
+  }
+  return { kind: 'cron', expr: draft.expr.trim(), tz: draft.tz.trim() || undefined };
+}
+
+export function buildWorkspaceRef(
+  workspacePath?: string,
+  workspaceId?: string,
+  remoteConnectionId?: string | null,
+  remoteSshHost?: string | null,
+): CronWorkspaceRef | null {
+  const normalizedWorkspacePath = normalizePath(workspacePath?.trim() ?? '');
+  if (!normalizedWorkspacePath) {
+    return null;
+  }
+
+  return {
+    workspacePath: normalizedWorkspacePath,
+    workspaceId: workspaceId?.trim() || undefined,
+    remoteConnectionId: remoteConnectionId?.trim() || undefined,
+    remoteSshHost: remoteSshHost?.trim() || undefined,
+  };
+}
+
+export function buildTargetFromDraft(
+  targetKind: CronJobTargetKind,
+  draft: JobDraft,
+  workspace: CronWorkspaceRef,
+): CronJobTarget {
+  if (targetKind === 'session') {
+    return {
+      kind: 'session',
+      sessionId: draft.sessionId.trim(),
+      workspace,
+    };
+  }
+
+  return {
+    kind: 'workspace',
+    workspace,
+    launch: {
+      agentType: draft.agentType.trim() || DEFAULT_AGENT_TYPE,
+    },
+  };
+}
+
+export function validateDraft(
+  targetKind: CronJobTargetKind,
+  draft: JobDraft,
+): JobDraftValidationErrors {
+  const everyValue = Number(draft.everyValue);
+  return {
+    name: !draft.name.trim(),
+    sessionId: targetKind === 'session' && !draft.sessionId.trim(),
+    agentType: targetKind === 'workspace' && !draft.agentType.trim(),
+    text: !draft.text.trim(),
+    at: draft.scheduleKind === 'at' && !draft.at.trim(),
+    everyValue:
+      draft.scheduleKind === 'every'
+      && (!draft.everyValue.trim() || !Number.isFinite(everyValue) || everyValue <= 0),
+    cronExpr: draft.scheduleKind === 'cron' && !draft.expr.trim(),
+  };
+}
+
+export function hasValidationErrors(errors: JobDraftValidationErrors): boolean {
+  return (
+    errors.name
+    || errors.sessionId
+    || errors.agentType
+    || errors.text
+    || errors.at
+    || errors.everyValue
+    || errors.cronExpr
+  );
+}
+
+/** Timestamp the scheduler will actually act on next, or null when nothing is pending. */
+export function getNextExecutionAtMs(job: CronJob): number | null {
+  return job.state.pendingTriggerAtMs ?? job.state.retryAtMs ?? job.state.nextRunAtMs ?? null;
+}
+
+export function notifyScheduledJobsChanged(sourceId: string): void {
+  window.dispatchEvent(new CustomEvent(SCHEDULED_JOBS_CHANGED_EVENT, {
+    detail: { sourceId },
+  }));
+}
diff --git a/src/web-ui/src/app/hooks/useSceneManager.ts b/src/web-ui/src/app/hooks/useSceneManager.ts
index d3a26e0155..e0e50d03de 100644
--- a/src/web-ui/src/app/hooks/useSceneManager.ts
+++ b/src/web-ui/src/app/hooks/useSceneManager.ts
@@ -15,6 +15,8 @@ import { useI18n } from '@/infrastructure/i18n';
 export interface UseSceneManagerReturn {
   openTabs: ReturnType<typeof useSceneStore.getState>['openTabs'];
   activeTabId: ReturnType<typeof useSceneStore.getState>['activeTabId'];
+  navigationMotion: ReturnType<typeof useSceneStore.getState>['navigationMotion'];
+  navigationSequence: ReturnType<typeof useSceneStore.getState>['navigationSequence'];
   tabDefs: SceneTabDef[];
   activateScene: (id: SceneTabId) => void;
   openScene: (id: SceneTabId) => void;
@@ -22,7 +24,15 @@ export interface UseSceneManagerReturn {
 }
 
 export function useSceneManager(): UseSceneManagerReturn {
-  const { openTabs, activeTabId, activateScene, openScene, closeScene } = useSceneStore();
+  const {
+    openTabs,
+    activeTabId,
+    navigationMotion,
+    navigationSequence,
+    activateScene,
+    openScene,
+    closeScene,
+  } = useSceneStore();
   const apps = useMiniAppStore((s) => s.apps);
   const { currentLanguage } = useI18n();
 
@@ -38,6 +48,8 @@ export function useSceneManager(): UseSceneManagerReturn {
   return {
     openTabs,
     activeTabId,
+    navigationMotion,
+    navigationSequence,
     tabDefs: [...SCENE_TAB_REGISTRY, ...miniAppDefs],
     activateScene,
     openScene,
diff --git a/src/web-ui/src/app/layout/AppLayout.tsx b/src/web-ui/src/app/layout/AppLayout.tsx
index e0698c1bc1..29cec626d5 100644
--- a/src/web-ui/src/app/layout/AppLayout.tsx
+++ b/src/web-ui/src/app/layout/AppLayout.tsx
@@ -26,7 +26,7 @@ import { MCPInteractionDialog } from '../components/MCPInteractionDialog/MCPInte
 import { workspaceAPI } from '@/infrastructure/api';
 import { systemAPI } from '@/infrastructure/api/service-api/SystemAPI';
 import type { CloseBehavior } from '@/infrastructure/api/service-api/SystemAPI';
-import { confirmDialog } from '@/component-library';
+import { confirmDialog, PresenceBoundary } from '@/component-library';
 import { createLogger } from '@/shared/utils/logger';
 import { DailyAppUpdateGate } from '@/infrastructure/update';
 import { useI18n } from '@/infrastructure/i18n';
@@ -777,7 +777,7 @@ const AppLayout: React.FC<AppLayoutProps> = ({ className = '' }) => {
       </div>
 
       {/* Dialogs (previously owned by TitleBar) */}
-      {showNewProjectDialog && (
+      <PresenceBoundary active={showNewProjectDialog}>
         <Suspense fallback={null}>
           <NewProjectDialog
             isOpen={showNewProjectDialog}
@@ -790,16 +790,16 @@ const AppLayout: React.FC<AppLayoutProps> = ({ className = '' }) => {
             }
           />
         </Suspense>
-      )}
-      {showAboutDialog && (
+      </PresenceBoundary>
+      <PresenceBoundary active={showAboutDialog}>
         <Suspense fallback={null}>
           <AboutDialog
             isOpen={showAboutDialog}
             onClose={() => setShowAboutDialog(false)}
           />
         </Suspense>
-      )}
-      {showWorkspaceStatus && (
+      </PresenceBoundary>
+      <PresenceBoundary active={showWorkspaceStatus}>
         <Suspense fallback={null}>
           <WorkspaceManager
             isVisible={showWorkspaceStatus}
@@ -807,7 +807,7 @@ const AppLayout: React.FC<AppLayoutProps> = ({ className = '' }) => {
             onWorkspaceSelect={() => {}}
           />
         </Suspense>
-      )}
+      </PresenceBoundary>
       <MCPInteractionDialog />
     </>
   );
diff --git a/src/web-ui/src/app/layout/FloatingMiniChat.tsx b/src/web-ui/src/app/layout/FloatingMiniChat.tsx
index 045b923e87..03d762c466 100644
--- a/src/web-ui/src/app/layout/FloatingMiniChat.tsx
+++ b/src/web-ui/src/app/layout/FloatingMiniChat.tsx
@@ -211,6 +211,9 @@ export const FloatingMiniChat: React.FC = () => {
       // Registration presence makes this an isolated workspace even when the
       // hidden session has no path, so the normal project never leaks in.
       workspacePath: displayedSession?.workspacePath || '',
+      remoteConnectionId:
+        displayedSession?.remoteConnectionId
+        || displayedSession?.config?.remoteConnectionId,
       draft: composerPrefill
         ? { id: composerPrefill.id, text: composerPrefill.text }
         : undefined,
@@ -222,6 +225,8 @@ export const FloatingMiniChat: React.FC = () => {
     activeMiniAppName,
     bubbleCustomization?.composer?.placeholder,
     composerPrefill,
+    displayedSession?.config?.remoteConnectionId,
+    displayedSession?.remoteConnectionId,
     displayedSession?.workspacePath,
     handleMiniAppDraftConsumed,
     handleMiniAppSubmit,
diff --git a/src/web-ui/src/app/scenes/SceneViewport.scss b/src/web-ui/src/app/scenes/SceneViewport.scss
index a700d0ad04..2a1976c215 100644
--- a/src/web-ui/src/app/scenes/SceneViewport.scss
+++ b/src/web-ui/src/app/scenes/SceneViewport.scss
@@ -79,6 +79,12 @@
     margin: 0;
   }
 
+  &__empty {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+
   // ── Lazy chunk loading ────────────────────────────────
 
   &__lazy-fallback {
@@ -99,8 +105,7 @@
     display: none;
     overflow: hidden;
 
-    &--active,
-    &--outgoing {
+    &--visible {
       display: flex;
       flex-direction: row;
       min-width: 0;
@@ -119,11 +124,28 @@
       z-index: 1;
     }
 
+    &--empty {
+      align-items: center;
+      justify-content: center;
+    }
+
+    &--incoming {
+      opacity: 1;
+      transition: opacity 480ms cubic-bezier(0.23, 1, 0.32, 1);
+    }
+
     &--outgoing {
       z-index: 2;
       pointer-events: none;
     }
   }
+
+  &__clip[data-scene-motion-phase='preparing'] {
+    .bitfun-scene-viewport__scene--incoming {
+      opacity: 0.5;
+      transition: none;
+    }
+  }
 }
 
 @media (prefers-reduced-motion: reduce) {
@@ -131,9 +153,13 @@
     transition: none;
   }
 
-  // Do not keep the previous scene painted during the exit grace period when
-  // the user has asked for motion to be reduced.
-  .bitfun-scene-viewport__scene--exiting {
-    display: none;
+  .bitfun-scene-viewport__scene--incoming {
+    transition: none;
+  }
+
+  .bitfun-scene-viewport__clip[data-scene-motion-phase='preparing'] {
+    .bitfun-scene-viewport__scene--incoming {
+      opacity: 1;
+    }
   }
 }
diff --git a/src/web-ui/src/app/scenes/SceneViewport.test.tsx b/src/web-ui/src/app/scenes/SceneViewport.test.tsx
new file mode 100644
index 0000000000..b2879ddad3
--- /dev/null
+++ b/src/web-ui/src/app/scenes/SceneViewport.test.tsx
@@ -0,0 +1,153 @@
+// @vitest-environment jsdom
+
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const sceneHarness = vi.hoisted(() => {
+  let resolveAgents: (() => void) | null = null;
+  let agentsAreReady = false;
+  const agentsReady = new Promise<void>((resolve) => {
+    resolveAgents = () => {
+      agentsAreReady = true;
+      resolve();
+    };
+  });
+
+  return {
+    state: {
+      openTabs: [{ id: 'session', openedAt: 0, lastUsed: 0 }],
+      activeTabId: 'session',
+      navigationMotion: 'instant',
+      navigationSequence: 0,
+    },
+    agentsReady,
+    agentsAreReady: () => agentsAreReady,
+    resolveAgents: () => resolveAgents?.(),
+  };
+});
+
+vi.mock('../hooks/useSceneManager', () => ({
+  useSceneManager: () => sceneHarness.state,
+}));
+
+vi.mock('../hooks/useDialogCompletionNotify', () => ({
+  useDialogCompletionNotify: () => undefined,
+}));
+
+vi.mock('@/infrastructure/i18n/hooks/useI18n', () => ({
+  useI18n: () => ({ t: (key: string) => key }),
+}));
+
+vi.mock('@/component-library', () => ({
+  DotMatrixLoader: () => <div data-testid="scene-loader" />,
+}));
+
+vi.mock('./session/SessionScene', () => ({
+  default: () => <div data-testid="session-scene-content" />,
+}));
+
+vi.mock('./settings/SettingsScene', () => ({
+  default: () => <div data-testid="settings-scene-content" />,
+}));
+
+vi.mock('./assistant/AssistantScene', () => ({
+  default: () => <div data-testid="assistant-scene-content" />,
+}));
+
+vi.mock('./agents/AgentsScene', () => ({
+  default: () => {
+    if (!sceneHarness.agentsAreReady()) {
+      throw sceneHarness.agentsReady;
+    }
+    return <div data-testid="agents-scene-content" />;
+  },
+}));
+
+import SceneViewport from './SceneViewport';
+
+describe('SceneViewport transitions', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => (
+      window.setTimeout(() => callback(performance.now()), 16)
+    ));
+    vi.stubGlobal('cancelAnimationFrame', (handle: number) => window.clearTimeout(handle));
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+  });
+
+  function visibleScenes(): Element[] {
+    return Array.from(container.querySelectorAll('[data-testid="scene-viewport-scene"]'))
+      .filter(scene => !scene.hasAttribute('hidden'));
+  }
+
+  it('keeps one scene visible while a lazy pointer target becomes ready', async () => {
+    act(() => root.render(<SceneViewport />));
+    expect(visibleScenes().map(scene => scene.getAttribute('data-scene-id'))).toEqual(['session']);
+
+    sceneHarness.state = {
+      openTabs: [
+        { id: 'session', openedAt: 0, lastUsed: 0 },
+        { id: 'agents', openedAt: 1, lastUsed: 1 },
+      ],
+      activeTabId: 'agents',
+      navigationMotion: 'pointer',
+      navigationSequence: 1,
+    };
+    await act(async () => {
+      root.render(<SceneViewport />);
+      await Promise.resolve();
+    });
+
+    expect(visibleScenes().map(scene => scene.getAttribute('data-scene-id'))).toEqual(['session']);
+
+    await act(async () => {
+      sceneHarness.resolveAgents();
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    expect(visibleScenes().map(scene => scene.getAttribute('data-scene-id'))).toEqual(['agents']);
+    expect(container.querySelector('[data-scene-id="session"]')?.hasAttribute('hidden')).toBe(true);
+    expect(container.querySelector('[data-scene-id="agents"]')?.classList.contains(
+      'bitfun-scene-viewport__scene--incoming',
+    )).toBe(true);
+
+    act(() => vi.advanceTimersByTime(32));
+    expect(container.querySelector('[data-scene-id="agents"]')?.classList.contains(
+      'bitfun-scene-viewport__scene--incoming',
+    )).toBe(true);
+
+    act(() => vi.advanceTimersByTime(479));
+    expect(container.querySelector('[data-scene-id="agents"]')?.classList.contains(
+      'bitfun-scene-viewport__scene--incoming',
+    )).toBe(true);
+
+    act(() => vi.advanceTimersByTime(1));
+    expect(container.querySelector('[data-scene-id="agents"]')?.classList.contains(
+      'bitfun-scene-viewport__scene--incoming',
+    )).toBe(false);
+
+    sceneHarness.state = {
+      ...sceneHarness.state,
+      activeTabId: 'session',
+      navigationSequence: 2,
+    };
+    act(() => root.render(<SceneViewport />));
+
+    expect(visibleScenes().map(scene => scene.getAttribute('data-scene-id'))).toEqual(['session']);
+    expect(container.querySelector('[data-scene-id="agents"]')?.hasAttribute('hidden')).toBe(true);
+  });
+});
diff --git a/src/web-ui/src/app/scenes/SceneViewport.tsx b/src/web-ui/src/app/scenes/SceneViewport.tsx
index 584f75727f..071029dee4 100644
--- a/src/web-ui/src/app/scenes/SceneViewport.tsx
+++ b/src/web-ui/src/app/scenes/SceneViewport.tsx
@@ -38,19 +38,21 @@ const SkillsScene     = lazy(() => import('./skills/SkillsScene'));
 const MiniAppGalleryScene = lazy(() => import('./miniapps/MiniAppGalleryScene'));
 const PagesScene      = lazy(() => import('./pages/PagesScene'));
 const BrowserScene    = lazy(() => import('./browser/BrowserScene'));
+const TodosScene      = lazy(() => import('./todos/TodosScene'));
 const InsightsScene   = lazy(() => import('./my-agent/InsightsScene'));
 const ShellScene      = lazy(() => import('./shell/ShellScene'));
 const WelcomeScene    = lazy(() => import('./welcome/WelcomeScene'));
 const MiniAppScene    = lazy(() => import('./miniapps/MiniAppScene'));
 const PanelViewScene  = lazy(() => import('./panel-view/PanelViewScene'));
 
-// Keep in sync with bitfun-motion-view-exit in app/styles/motion.scss.
-const SCENE_EXIT_DURATION_MS = 140;
+const SCENE_ENTRY_DURATION_MS = 480;
+const EMPTY_SCENE_ID = '__empty-scene__' as const;
+type RenderedSceneId = SceneTabId | typeof EMPTY_SCENE_ID;
 
 interface SceneTransition {
-  outgoingTabId: SceneTabId;
-  incomingTabId: SceneTabId;
-  phase: 'holding' | 'exiting';
+  outgoingTabId: RenderedSceneId;
+  incomingTabId: RenderedSceneId;
+  phase: 'holding' | 'preparing' | 'running';
 }
 
 interface SceneReadyBoundaryProps {
@@ -82,12 +84,20 @@ interface SceneViewportProps {
 }
 
 const SceneViewport: React.FC<SceneViewportProps> = ({ workspacePath, isEntering = false }) => {
-  const { openTabs, activeTabId } = useSceneManager();
+  const {
+    openTabs,
+    activeTabId,
+    navigationMotion,
+    navigationSequence,
+  } = useSceneManager();
   const { t } = useI18n('common');
+  const activeRenderedSceneId: RenderedSceneId = openTabs.length === 0
+    ? EMPTY_SCENE_ID
+    : activeTabId;
   const [transition, setTransition] = useState<SceneTransition | null>(null);
   const [readyVersion, setReadyVersion] = useState(0);
-  const readySceneIdsRef = useRef<Set<SceneTabId>>(new Set());
-  const previousActiveTabIdRef = useRef<SceneTabId>(activeTabId);
+  const readySceneIdsRef = useRef<Set<RenderedSceneId>>(new Set([EMPTY_SCENE_ID]));
+  const previousActiveTabIdRef = useRef<RenderedSceneId>(activeRenderedSceneId);
   useDialogCompletionNotify();
 
   const markSceneReady = useCallback((sceneId: SceneTabId) => {
@@ -96,31 +106,47 @@ const SceneViewport: React.FC<SceneViewportProps> = ({ workspacePath, isEntering
     setReadyVersion(version => version + 1);
   }, []);
 
-  // Derive the outgoing id during render as well as from state. This keeps a
-  // just-closed active tab (notably the welcome tab) in the keyed React tree
-  // for its exit frame instead of unmounting and remounting it after layout.
-  const outgoingTabId = previousActiveTabIdRef.current !== activeTabId
-    ? previousActiveTabIdRef.current
-    : transition?.outgoingTabId ?? null;
-  const renderedTabIds = openTabs.map(tab => tab.id);
+  // Derive the outgoing id during render as well as from state. Pointer
+  // navigation keeps that scene as the only visible surface until the target
+  // has resolved through Suspense, then swaps atomically to the incoming scene.
+  const activeSceneChanged = previousActiveTabIdRef.current !== activeRenderedSceneId;
+  const pendingTransition: SceneTransition | null = activeSceneChanged
+    && navigationMotion === 'pointer'
+    ? {
+        outgoingTabId: previousActiveTabIdRef.current,
+        incomingTabId: activeRenderedSceneId,
+        phase: 'holding',
+      }
+    : activeSceneChanged
+      ? null
+      : transition;
+  const outgoingTabId = pendingTransition?.outgoingTabId ?? null;
+  const renderedTabIds: RenderedSceneId[] = openTabs.length === 0
+    ? [EMPTY_SCENE_ID]
+    : openTabs.map(tab => tab.id);
   if (outgoingTabId && !renderedTabIds.includes(outgoingTabId)) {
     renderedTabIds.push(outgoingTabId);
   }
 
   useLayoutEffect(() => {
     const previousActiveTabId = previousActiveTabIdRef.current;
-    previousActiveTabIdRef.current = activeTabId;
+    previousActiveTabIdRef.current = activeRenderedSceneId;
+
+    if (previousActiveTabId === activeRenderedSceneId) {
+      return;
+    }
 
-    if (!previousActiveTabId || previousActiveTabId === activeTabId) {
+    if (navigationMotion !== 'pointer') {
+      setTransition(null);
       return;
     }
 
     setTransition({
       outgoingTabId: previousActiveTabId,
-      incomingTabId: activeTabId,
-      phase: readySceneIdsRef.current.has(activeTabId) ? 'exiting' : 'holding',
+      incomingTabId: activeRenderedSceneId,
+      phase: readySceneIdsRef.current.has(activeRenderedSceneId) ? 'preparing' : 'holding',
     });
-  }, [activeTabId]);
+  }, [activeRenderedSceneId, navigationMotion, navigationSequence]);
 
   useLayoutEffect(() => {
     if (
@@ -132,87 +158,127 @@ const SceneViewport: React.FC<SceneViewportProps> = ({ workspacePath, isEntering
 
     setTransition(current => (
       current?.incomingTabId === transition.incomingTabId
-        ? { ...current, phase: 'exiting' }
+        ? { ...current, phase: 'preparing' }
         : current
     ));
   }, [readyVersion, transition]);
 
   useEffect(() => {
-    if (transition?.phase !== 'exiting') return;
+    if (transition?.phase !== 'preparing') return;
+
+    const preparedTransition = transition;
+    let runningFrame: number | null = null;
+    const preparationFrame = window.requestAnimationFrame(() => {
+      runningFrame = window.requestAnimationFrame(() => {
+        setTransition(current => (
+          current === preparedTransition
+            ? { ...current, phase: 'running' }
+            : current
+        ));
+      });
+    });
+
+    return () => {
+      window.cancelAnimationFrame(preparationFrame);
+      if (runningFrame !== null) {
+        window.cancelAnimationFrame(runningFrame);
+      }
+    };
+  }, [transition]);
+
+  useEffect(() => {
+    if (transition?.phase !== 'running') return;
 
     const completedTransition = transition;
-    const exitTimer = window.setTimeout(() => {
+    const entryTimer = window.setTimeout(() => {
       setTransition(current => (
         current === completedTransition ? null : current
       ));
-    }, SCENE_EXIT_DURATION_MS);
+    }, SCENE_ENTRY_DURATION_MS);
 
-    return () => window.clearTimeout(exitTimer);
+    return () => window.clearTimeout(entryTimer);
   }, [transition]);
 
-  // All tabs closed — show empty state
-  if (openTabs.length === 0) {
-    return (
-      <div className="bitfun-scene-viewport" data-testid="scene-viewport" data-bf-scene="workbench" data-bf-part="viewport" data-bf-state="empty">
-        <div
-          className="bitfun-scene-viewport__clip bitfun-scene-viewport__clip--empty"
-          data-testid="scene-viewport-empty"
-          data-bf-scene="workbench"
-          data-bf-part="empty"
-          data-bf-state="empty"
-        >
-          <p className="bitfun-scene-viewport__empty-hint">{t('welcomeScene.emptyHint')}</p>
-        </div>
-      </div>
-    );
-  }
-
   return (
-    <div className="bitfun-scene-viewport" data-testid="scene-viewport" data-bf-scene="workbench" data-bf-part="viewport">
-      <div className="bitfun-scene-viewport__clip" data-testid="scene-viewport-clip" data-bf-scene="workbench" data-bf-part="viewportClip">
+    <div
+      className="bitfun-scene-viewport"
+      data-testid="scene-viewport"
+      data-bf-scene="workbench"
+      data-bf-part="viewport"
+      data-bf-state={activeRenderedSceneId === EMPTY_SCENE_ID ? 'empty' : undefined}
+    >
+      <div
+        className="bitfun-scene-viewport__clip"
+        data-testid="scene-viewport-clip"
+        data-scene-motion-phase={pendingTransition?.phase}
+        data-bf-scene="workbench"
+        data-bf-part="viewportClip"
+      >
         {renderedTabIds.map(tabId => {
-          const isActive = tabId === activeTabId;
+          const isEmpty = tabId === EMPTY_SCENE_ID;
+          const isActive = tabId === activeRenderedSceneId;
           const isOutgoing = !isActive && tabId === outgoingTabId;
-          const isExiting = isOutgoing && transition?.phase === 'exiting';
+          const isIncoming = isActive && pendingTransition?.incomingTabId === tabId;
+          const isVisible = pendingTransition?.phase === 'holding'
+            ? isOutgoing
+            : isActive;
           return (
             <div
               key={tabId}
               className={[
                 'bitfun-scene-viewport__scene',
+                isEmpty && 'bitfun-scene-viewport__scene--empty',
                 isActive && 'bitfun-scene-viewport__scene--active',
+                isVisible && 'bitfun-scene-viewport__scene--visible',
+                isIncoming && 'bitfun-scene-viewport__scene--incoming',
                 isOutgoing && 'bitfun-scene-viewport__scene--outgoing',
-                isExiting && 'bitfun-scene-viewport__scene--exiting',
               ].filter(Boolean).join(' ')}
+              hidden={!isVisible}
               aria-hidden={!isActive}
+              {...(!isActive ? { inert: '' } : {})}
               data-testid="scene-viewport-scene"
               data-scene-id={tabId}
               data-scene-active={isActive ? 'true' : 'false'}
-              data-scene-transition={isExiting ? 'exit' : undefined}
               data-bf-scene="workbench"
               data-bf-part="scene"
-              data-bf-scene-id={tabId}
-              data-bf-state={isActive ? 'active' : undefined}
+              data-bf-scene-id={isEmpty ? undefined : tabId}
+              data-bf-state={[
+                isActive && 'active',
+                isEmpty && 'empty',
+              ].filter(Boolean).join(' ') || undefined}
             >
-              <Suspense
-                fallback={
-                  isActive ? (
-                    <div
-                      className="bitfun-scene-viewport__lazy-fallback"
-                      role="status"
-                      aria-busy="true"
-                      aria-label={t('loading.scenes')}
-                      data-bf-scene="workbench"
-                      data-bf-part="loading"
-                    >
-                      <DotMatrixLoader size="medium" />
-                    </div>
-                  ) : null
-                }
-              >
-                <SceneReadyBoundary sceneId={tabId} onReady={markSceneReady}>
-                  {renderScene(tabId, workspacePath, isEntering, isActive)}
-                </SceneReadyBoundary>
-              </Suspense>
+              {isEmpty ? (
+                <div
+                  className="bitfun-scene-viewport__empty"
+                  data-testid="scene-viewport-empty"
+                  data-bf-scene="workbench"
+                  data-bf-part="empty"
+                  data-bf-state="empty"
+                >
+                  <p className="bitfun-scene-viewport__empty-hint">{t('welcomeScene.emptyHint')}</p>
+                </div>
+              ) : (
+                <Suspense
+                  fallback={
+                    isActive ? (
+                      <div
+                        className="bitfun-scene-viewport__lazy-fallback"
+                        role="status"
+                        aria-busy="true"
+                        aria-label={t('loading.scenes')}
+                        data-bf-scene="workbench"
+                        data-bf-part="loading"
+                      >
+                        <DotMatrixLoader size="medium" />
+                      </div>
+                    ) : null
+                  }
+                >
+                  <SceneReadyBoundary sceneId={tabId} onReady={markSceneReady}>
+                    {renderScene(tabId, workspacePath, isEntering, isActive)}
+                  </SceneReadyBoundary>
+                </Suspense>
+              )}
             </div>
           );
         })}
@@ -254,6 +320,8 @@ function renderScene(
       return <BrowserScene />;
     case 'assistant':
       return <AssistantScene workspacePath={workspacePath} />;
+    case 'todos':
+      return <TodosScene />;
     case 'insights':
       return <InsightsScene />;
     case 'shell':
diff --git a/src/web-ui/src/app/scenes/agents/AgentsScene.test.tsx b/src/web-ui/src/app/scenes/agents/AgentsScene.test.tsx
index 1ef041353c..030c780218 100644
--- a/src/web-ui/src/app/scenes/agents/AgentsScene.test.tsx
+++ b/src/web-ui/src/app/scenes/agents/AgentsScene.test.tsx
@@ -25,12 +25,20 @@ vi.mock('./components/CreateAgentPage', () => ({
 vi.mock('./components/AgentCard', () => ({
   default: ({
     agent,
+    toolCount,
     onOpenDetails,
   }: {
     agent: { name: string };
+    toolCount?: number;
     onOpenDetails: (agent: unknown) => void;
   }) => (
-    <button type="button" onClick={() => onOpenDetails(agent)}>{agent.name}</button>
+    <button
+      type="button"
+      data-tool-count={toolCount}
+      onClick={() => onOpenDetails(agent)}
+    >
+      {agent.name}
+    </button>
   ),
 }));
 
@@ -59,6 +67,19 @@ vi.mock('./components/SkillGroupPicker', () => ({
   SkillGroupSummary: () => <div data-testid="agent-detail-skill-summary">skill summary</div>,
 }));
 
+vi.mock('./components/ToolGroupPicker', () => ({
+  ToolGroupPicker: ({ tools }: { tools: Array<{ name: string }> }) => (
+    <div data-testid="agent-detail-tool-groups">
+      {tools.map((tool) => tool.name).join(',')}
+    </div>
+  ),
+  ToolGroupSummary: ({ tools }: { tools: Array<{ name: string }> }) => (
+    <div data-testid="agent-detail-tool-summary">
+      {tools.map((tool) => tool.name).join(',')}
+    </div>
+  ),
+}));
+
 vi.mock('@/component-library', () => ({
   Badge: ({ children }: { children: React.ReactNode }) => <span>{children}</span>,
   Button: ({ children, onClick }: { children: React.ReactNode; onClick?: () => void }) => (
@@ -304,4 +325,56 @@ describeWithJsdom('AgentsScene', () => {
     });
     expect(container.querySelector('[data-testid="agent-detail-skill-groups"]')).toBeTruthy();
   });
+
+  it('keeps MCP tools out of mode cards and tool details', async () => {
+    const mode = {
+      key: 'mode::custom-mode',
+      id: 'custom-mode',
+      name: 'Custom mode',
+      description: 'General coding mode.',
+      isReadonly: false,
+      isReview: false,
+      toolCount: 2,
+      defaultTools: ['Read'],
+      defaultEnabled: true,
+      effectiveEnabled: true,
+      source: 'user',
+      agentKind: 'mode' as const,
+      capabilities: [],
+    };
+    mockAgentsList({
+      allAgents: [mode],
+      filteredAgents: [mode],
+      availableTools: [
+        { name: 'Read', description: 'Read files.', is_readonly: true },
+        {
+          name: 'mcp__github__list_issues',
+          description: 'List issues.',
+          is_readonly: true,
+        },
+      ],
+      getModeConfig: () => ({
+        profile_id: 'coding_shared',
+        enabled_tools: ['Read', 'mcp__github__list_issues'],
+        default_tools: ['Read'],
+      }),
+    });
+    const { default: AgentsScene } = await import('./AgentsScene');
+
+    await act(async () => {
+      root.render(<AgentsScene />);
+    });
+
+    const card = Array.from(container.querySelectorAll<HTMLButtonElement>('button'))
+      .find((button) => button.textContent === mode.name);
+    expect(card?.dataset.toolCount).toBe('1');
+
+    await act(async () => {
+      card?.click();
+    });
+
+    const summary = container.querySelector('[data-testid="agent-detail-tool-summary"]');
+    expect(summary?.textContent).toBe('Read');
+    expect(summary?.textContent).not.toContain('mcp__github__list_issues');
+  });
 });
diff --git a/src/web-ui/src/app/scenes/agents/AgentsScene.tsx b/src/web-ui/src/app/scenes/agents/AgentsScene.tsx
index afd2808fdb..954ee5ef95 100644
--- a/src/web-ui/src/app/scenes/agents/AgentsScene.tsx
+++ b/src/web-ui/src/app/scenes/agents/AgentsScene.tsx
@@ -42,7 +42,8 @@ import { useAgentsList } from './hooks/useAgentsList';
 import { AGENT_ICON_MAP } from './agentsIcons';
 import { CAPABILITY_ACCENT, CORE_AGENT_ACCENTS, DEFAULT_CORE_AGENT_ACCENT } from './agentAppearance';
 import { getCardGradient } from '@/shared/utils/cardGradients';
-import { isUserSelectableToolName } from '@/shared/utils/toolVisibility';
+import { getMotionAwareScrollBehavior } from '@/shared/utils/motionPreference';
+import { isAgentProfileConfigurableToolName } from './agentToolVisibility';
 import { getAgentBadge, getAgentDescription, getCapabilityLabel } from './utils';
 import './AgentsView.scss';
 import './AgentsScene.scss';
@@ -265,7 +266,10 @@ const AgentsHomeView: React.FC = () => {
   );
 
   const scrollToZone = useCallback((targetId: string) => {
-    document.getElementById(targetId)?.scrollIntoView({ behavior: 'smooth', block: 'start' });
+    document.getElementById(targetId)?.scrollIntoView({
+      behavior: getMotionAwareScrollBehavior('smooth'),
+      block: 'start',
+    });
   }, []);
 
   const levelFilters = [
@@ -317,11 +321,11 @@ const AgentsHomeView: React.FC = () => {
       : (selectedAgent?.defaultTools ?? [])
   ), [selectedAgent, selectedAgentModeConfig]);
   const selectedAgentTools = useMemo(
-    () => selectedAgentConfiguredTools.filter(isUserSelectableToolName),
+    () => selectedAgentConfiguredTools.filter(isAgentProfileConfigurableToolName),
     [selectedAgentConfiguredTools],
   );
-  const userSelectableAvailableTools = useMemo(
-    () => availableTools.filter((tool) => isUserSelectableToolName(tool.name)),
+  const agentProfileAvailableTools = useMemo(
+    () => availableTools.filter((tool) => isAgentProfileConfigurableToolName(tool.name)),
     [availableTools],
   );
   const selectedAgentHasSkillTool = hasSkillTool(selectedAgentConfiguredTools);
@@ -379,7 +383,7 @@ const AgentsHomeView: React.FC = () => {
       ? (getModeConfig(agent.id)?.enabled_tools ?? agent.defaultTools)
       : agent.defaultTools;
     if (configuredTools) {
-      return configuredTools.filter(isUserSelectableToolName).length;
+      return configuredTools.filter(isAgentProfileConfigurableToolName).length;
     }
     return agent.toolCount ?? 0;
   }, [getModeConfig]);
@@ -446,11 +450,11 @@ const AgentsHomeView: React.FC = () => {
     if (selectedAgentTools.length > 0) {
       const currentToolCount = selectedAgent?.agentKind === 'mode'
         ? (toolsEditing
-          ? (pendingTools ?? selectedAgentConfiguredTools).filter(isUserSelectableToolName).length
+          ? (pendingTools ?? selectedAgentTools).length
           : selectedAgentTools.length)
         : selectedAgentTools.length;
       const totalToolCount = selectedAgent?.agentKind === 'mode'
-        ? userSelectableAvailableTools.length
+        ? agentProfileAvailableTools.length
         : selectedAgentTools.length;
 
       tabs.push({
@@ -491,13 +495,12 @@ const AgentsHomeView: React.FC = () => {
 
     return tabs;
   }, [
-    userSelectableAvailableTools.length,
+    agentProfileAvailableTools.length,
     pendingSkills,
     pendingSubagentIds,
     pendingTools,
     selectedAgent,
     selectedAgentIsExternal,
-    selectedAgentConfiguredTools,
     selectedAgentEnabledSubagentIds,
     selectedAgentHasSkillTool,
     selectedAgentHasTaskTool,
@@ -1089,7 +1092,7 @@ const AgentsHomeView: React.FC = () => {
                           size="small"
                           onClick={() => {
                             if (currentCapabilityTab === 'tools') {
-                              setPendingTools([...selectedAgentConfiguredTools]);
+                              setPendingTools([...selectedAgentTools]);
                               setToolsEditing(true);
                               return;
                             }
@@ -1131,8 +1134,8 @@ const AgentsHomeView: React.FC = () => {
                 {currentCapabilityTab === 'tools' ? (
                   selectedAgent.agentKind === 'mode' && toolsEditing ? (
                     <ToolGroupPicker
-                      tools={userSelectableAvailableTools}
-                      selectedToolNames={pendingTools ?? selectedAgentConfiguredTools}
+                      tools={agentProfileAvailableTools}
+                      selectedToolNames={pendingTools ?? selectedAgentTools}
                       userGroups={userToolGroups}
                       onSelectionChange={setPendingTools}
                       onSaveUserGroups={saveUserToolGroups}
@@ -1141,7 +1144,7 @@ const AgentsHomeView: React.FC = () => {
                     />
                   ) : (
                     <ToolGroupSummary
-                      tools={userSelectableAvailableTools}
+                      tools={agentProfileAvailableTools}
                       selectedToolNames={selectedAgentTools}
                       userGroups={userToolGroups}
                     />
diff --git a/src/web-ui/src/app/scenes/agents/agentToolVisibility.test.ts b/src/web-ui/src/app/scenes/agents/agentToolVisibility.test.ts
new file mode 100644
index 0000000000..2a6de653d6
--- /dev/null
+++ b/src/web-ui/src/app/scenes/agents/agentToolVisibility.test.ts
@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+import { isAgentProfileConfigurableToolName } from './agentToolVisibility';
+
+describe('isAgentProfileConfigurableToolName', () => {
+  it('hides MCP tools from per-agent profile configuration', () => {
+    expect(isAgentProfileConfigurableToolName('mcp__github__list_issues')).toBe(false);
+  });
+
+  it('keeps regular product tools configurable', () => {
+    expect(isAgentProfileConfigurableToolName('Read')).toBe(true);
+  });
+
+  it('continues to hide internal gateway tools', () => {
+    expect(isAgentProfileConfigurableToolName('GetToolSpec')).toBe(false);
+  });
+});
diff --git a/src/web-ui/src/app/scenes/agents/agentToolVisibility.ts b/src/web-ui/src/app/scenes/agents/agentToolVisibility.ts
new file mode 100644
index 0000000000..acae1fabbc
--- /dev/null
+++ b/src/web-ui/src/app/scenes/agents/agentToolVisibility.ts
@@ -0,0 +1,6 @@
+import { isMcpToolName } from '@/infrastructure/mcp/toolName';
+import { isUserSelectableToolName } from '@/shared/utils/toolVisibility';
+
+export function isAgentProfileConfigurableToolName(toolName: string): boolean {
+  return isUserSelectableToolName(toolName) && !isMcpToolName(toolName);
+}
diff --git a/src/web-ui/src/app/scenes/browser/BrowserPanel.scss b/src/web-ui/src/app/scenes/browser/BrowserPanel.scss
index e60a60f7e9..759d06adc0 100644
--- a/src/web-ui/src/app/scenes/browser/BrowserPanel.scss
+++ b/src/web-ui/src/app/scenes/browser/BrowserPanel.scss
@@ -135,3 +135,10 @@
   from { transform: rotate(0deg); }
   to { transform: rotate(360deg); }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .browser-panel__spinning {
+    animation: none;
+    transform: none;
+  }
+}
diff --git a/src/web-ui/src/app/scenes/browser/BrowserScene.scss b/src/web-ui/src/app/scenes/browser/BrowserScene.scss
index 745705e470..5f84d28b81 100644
--- a/src/web-ui/src/app/scenes/browser/BrowserScene.scss
+++ b/src/web-ui/src/app/scenes/browser/BrowserScene.scss
@@ -126,3 +126,10 @@
   from { transform: rotate(0deg); }
   to { transform: rotate(360deg); }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .browser-scene__spinning {
+    animation: none;
+    transform: none;
+  }
+}
diff --git a/src/web-ui/src/app/scenes/miniapps/MiniAppScene.scss b/src/web-ui/src/app/scenes/miniapps/MiniAppScene.scss
index 819eaf6a5c..5bb6d90381 100644
--- a/src/web-ui/src/app/scenes/miniapps/MiniAppScene.scss
+++ b/src/web-ui/src/app/scenes/miniapps/MiniAppScene.scss
@@ -535,3 +535,10 @@
   from { transform: rotate(0deg); }
   to { transform: rotate(360deg); }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .miniapp-scene__spinning {
+    animation: none;
+    transform: none;
+  }
+}
diff --git a/src/web-ui/src/app/scenes/miniapps/components/MiniAppCard.scss b/src/web-ui/src/app/scenes/miniapps/components/MiniAppCard.scss
index 038cdca426..d75b5e94c9 100644
--- a/src/web-ui/src/app/scenes/miniapps/components/MiniAppCard.scss
+++ b/src/web-ui/src/app/scenes/miniapps/components/MiniAppCard.scss
@@ -120,7 +120,7 @@
   &__run-dot {
     background: var(--bf-appearance-token-color-success);
     box-shadow: 0 0 6px color-mix(in srgb, var(--bf-appearance-token-color-success) 65%, transparent);
-    animation: pulse 2s ease-in-out infinite;
+    animation: miniapp-card-status-pulse 2s ease-in-out infinite;
   }
 
   &__customize-dot {
@@ -293,7 +293,7 @@
   100% { transform: scale(1) rotate(0deg); }
 }
 
-@keyframes pulse {
+@keyframes miniapp-card-status-pulse {
   0%, 100% { opacity: 1; }
   50% { opacity: 0.5; }
 }
diff --git a/src/web-ui/src/app/scenes/my-agent/InsightsScene.tsx b/src/web-ui/src/app/scenes/my-agent/InsightsScene.tsx
index af0f53ec11..43bc331615 100644
--- a/src/web-ui/src/app/scenes/my-agent/InsightsScene.tsx
+++ b/src/web-ui/src/app/scenes/my-agent/InsightsScene.tsx
@@ -14,6 +14,7 @@ import { getProviderDisplayName } from '@/infrastructure/config/services/modelCo
 import type { AIModelConfig } from '@/infrastructure/config/types';
 import { useInsightsStore } from './insightsStore';
 import { createLogger } from '@/shared/utils/logger';
+import { getMotionAwareScrollBehavior } from '@/shared/utils/motionPreference';
 import { notificationService } from '@/shared/notification-system';
 import { APPEARANCE_DOMAIN_TOKENS } from '@/infrastructure/appearance/appearanceDomainTokens';
 import '@/app/components/GalleryLayout/GalleryLayout.scss';
@@ -517,7 +518,10 @@ const ReportNav: React.FC<{ report: InsightsReport; scrollContainerRef: React.Re
     if (!element) return;
     const containerTop = container.getBoundingClientRect().top;
     const elTop = element.getBoundingClientRect().top - containerTop;
-    container.scrollBy({ top: elTop - 16, behavior: 'smooth' });
+    container.scrollBy({
+      top: elTop - 16,
+      behavior: getMotionAwareScrollBehavior('smooth'),
+    });
   };
 
   return (
diff --git a/src/web-ui/src/app/scenes/pages/PagesScene.test.tsx b/src/web-ui/src/app/scenes/pages/PagesScene.test.tsx
index aab6310378..80efcdac6f 100644
--- a/src/web-ui/src/app/scenes/pages/PagesScene.test.tsx
+++ b/src/web-ui/src/app/scenes/pages/PagesScene.test.tsx
@@ -78,6 +78,9 @@ vi.mock('@/component-library', () => ({
     <button {...props}>{children}</button>
   ),
   Input: (props: React.InputHTMLAttributes<HTMLInputElement>) => <input {...props} />,
+  PresenceBoundary: ({ active, children }: { active: boolean; children: React.ReactNode }) => (
+    active ? <>{children}</> : null
+  ),
   Select: () => <div />,
   confirmDanger: mocks.confirmDanger,
   confirmWarning: vi.fn(),
diff --git a/src/web-ui/src/app/scenes/pages/PagesScene.tsx b/src/web-ui/src/app/scenes/pages/PagesScene.tsx
index 363d0b9f11..9a60f01fa0 100644
--- a/src/web-ui/src/app/scenes/pages/PagesScene.tsx
+++ b/src/web-ui/src/app/scenes/pages/PagesScene.tsx
@@ -23,6 +23,7 @@ import {
 import {
   Button,
   Input,
+  PresenceBoundary,
   Select,
   confirmDanger,
   confirmWarning,
@@ -1098,7 +1099,7 @@ const PagesScene: React.FC<PagesSceneProps> = ({ isActive = true }) => {
           </div>
         )}
       </div>
-      {showAccountDialog && (
+      <PresenceBoundary active={showAccountDialog}>
         <Suspense fallback={null}>
           <RemoteConnectDialog
             isOpen={showAccountDialog}
@@ -1109,7 +1110,7 @@ const PagesScene: React.FC<PagesSceneProps> = ({ isActive = true }) => {
             }}
           />
         </Suspense>
-      )}
+      </PresenceBoundary>
     </GalleryLayout>
   );
 };
diff --git a/src/web-ui/src/app/scenes/registry.ts b/src/web-ui/src/app/scenes/registry.ts
index 4f8d85a5c7..b9bb402df3 100644
--- a/src/web-ui/src/app/scenes/registry.ts
+++ b/src/web-ui/src/app/scenes/registry.ts
@@ -21,6 +21,7 @@ import {
   Globe,
   User,
   BarChart3,
+  CalendarClock,
   ExternalLink,
 } from 'lucide-react';
 import type { SceneTabDef, SceneTabId } from '../components/SceneBar/types';
@@ -144,6 +145,15 @@ export const SCENE_TAB_REGISTRY: SceneTabDef[] = [
     singleton: true,
     defaultOpen: false,
   },
+  {
+    id: 'todos' as SceneTabId,
+    label: 'Todos',
+    labelKey: 'scenes.todos',
+    Icon: CalendarClock,
+    pinned: false,
+    singleton: true,
+    defaultOpen: false,
+  },
   {
     id: 'insights' as SceneTabId,
     label: 'Insights',
diff --git a/src/web-ui/src/app/scenes/session/SessionScene.scss b/src/web-ui/src/app/scenes/session/SessionScene.scss
index 69a08a7214..3a6a700bc9 100644
--- a/src/web-ui/src/app/scenes/session/SessionScene.scss
+++ b/src/web-ui/src/app/scenes/session/SessionScene.scss
@@ -325,9 +325,10 @@
   user-select: none;
   z-index: $z-sticky;
   background: var(--bf-appearance-token-border-subtle);
-  transition: all $motion-base $easing-standard,
-              height $motion-base $easing-standard,
-              opacity $motion-base $easing-standard;
+  transition:
+    background-color $motion-base $easing-standard,
+    height $motion-base $easing-standard,
+    opacity $motion-base $easing-standard;
 
   &::before {
     content: '';
diff --git a/src/web-ui/src/app/scenes/settings/SettingsNav.tsx b/src/web-ui/src/app/scenes/settings/SettingsNav.tsx
index e9ce3935ad..e6f6e78205 100644
--- a/src/web-ui/src/app/scenes/settings/SettingsNav.tsx
+++ b/src/web-ui/src/app/scenes/settings/SettingsNav.tsx
@@ -22,6 +22,7 @@ import React, {
 import type { i18n as I18nApi } from 'i18next';
 import { useTranslation } from 'react-i18next';
 import { Search, Badge } from '@/component-library';
+import { getInteractionMotion } from '@/shared/utils/motionPreference';
 import { useSettingsStore } from './settingsStore';
 import { SETTINGS_CATEGORIES } from './settingsConfig';
 import type { ConfigTab } from './settingsConfig';
@@ -183,7 +184,7 @@ function useSettingsNav() {
   }, [setSearchQuery]);
 
   const activateTab = useCallback(
-    (tab: ConfigTab) => {
+    (tab: ConfigTab, motion = getInteractionMotion()) => {
       const requestId = ++activationRequestRef.current;
       const commit = () => {
         if (activationRequestRef.current !== requestId) return;
@@ -191,7 +192,7 @@ function useSettingsNav() {
         // first mount; inside a transition React keeps the painted panel until
         // the new one is ready instead of committing the skeleton fallback.
         startTransition(() => {
-          setActiveTab(tab);
+          setActiveTab(tab, motion);
           clearSearch();
         });
       };
@@ -202,11 +203,12 @@ function useSettingsNav() {
 
   const handleTabClick = useCallback(
     (tab: ConfigTab) => {
+      const motion = getInteractionMotion();
       const requestId = ++activationRequestRef.current;
       const commit = () => {
         if (activationRequestRef.current !== requestId) return;
         startTransition(() => {
-          setActiveTab(tab);
+          setActiveTab(tab, motion);
         });
       };
       void preloadSettingsTabContent(tab).then(commit, commit);
@@ -233,7 +235,7 @@ function useSettingsNav() {
       }
       if (e.key === 'Enter' && results.length === 1) {
         e.preventDefault();
-        activateTab(results[0].tabId);
+        activateTab(results[0].tabId, 'instant');
       }
     },
     [clearSearch, results, activateTab, resultsRef]
@@ -266,7 +268,7 @@ function useSettingsNav() {
       }
       if (e.key === 'Enter' && highlightedIndex >= 0 && highlightedIndex < results.length) {
         e.preventDefault();
-        activateTab(results[highlightedIndex].tabId);
+        activateTab(results[highlightedIndex].tabId, 'instant');
       }
     },
     [isSearchMode, results, highlightedIndex, activateTab, clearSearch]
diff --git a/src/web-ui/src/app/scenes/settings/SettingsScene.scss b/src/web-ui/src/app/scenes/settings/SettingsScene.scss
index 8760d32e77..0453d17e09 100644
--- a/src/web-ui/src/app/scenes/settings/SettingsScene.scss
+++ b/src/web-ui/src/app/scenes/settings/SettingsScene.scss
@@ -46,6 +46,20 @@
     overflow: hidden;
   }
 
+  &__content-transition {
+    flex: 1 1 auto;
+    width: 100%;
+    height: 100%;
+    min-width: 0;
+    min-height: 0;
+    overflow: hidden;
+
+    > .bitfun-view-transition-boundary__view {
+      width: 100%;
+      height: 100%;
+    }
+  }
+
   &__content-wrapper {
     display: flex;
     flex-direction: column;
@@ -54,5 +68,15 @@
     min-width: 0;
     min-height: 0;
     overflow: hidden;
+
+    > [data-testid='settings-scene-content'] {
+      display: flex;
+      flex: 1 1 auto;
+      flex-direction: column;
+      width: 100%;
+      height: 100%;
+      min-width: 0;
+      min-height: 0;
+    }
   }
 }
diff --git a/src/web-ui/src/app/scenes/settings/SettingsScene.test.tsx b/src/web-ui/src/app/scenes/settings/SettingsScene.test.tsx
index e1eae5fe7e..3443a17617 100644
--- a/src/web-ui/src/app/scenes/settings/SettingsScene.test.tsx
+++ b/src/web-ui/src/app/scenes/settings/SettingsScene.test.tsx
@@ -83,6 +83,9 @@ describe('SettingsScene lazy tab routing', () => {
       activeTab: 'basics',
       contentFocus: null,
       contentFocusRequestId: 0,
+      tabTransitionTarget: null,
+      tabTransitionMotion: 'instant',
+      tabTransitionSequence: 0,
       searchQuery: '',
     });
   });
@@ -92,6 +95,7 @@ describe('SettingsScene lazy tab routing', () => {
       root.unmount();
     });
     container.remove();
+    vi.unstubAllGlobals();
     vi.useRealTimers();
   });
 
@@ -178,4 +182,31 @@ describe('SettingsScene lazy tab routing', () => {
     expect(container.querySelector('[data-testid="basics-config"]')).toBeNull();
     expect(container.querySelectorAll('[data-testid="settings-scene-content"]')).toHaveLength(1);
   });
+
+  it('bridges a pointer tab switch while making the outgoing panel inert', async () => {
+    await act(async () => {
+      root.render(<SettingsScene />);
+    });
+    await waitForPanelContent('basics-config');
+
+    vi.useFakeTimers();
+    vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => (
+      window.setTimeout(() => callback(performance.now()), 16)
+    ));
+    vi.stubGlobal('cancelAnimationFrame', (handle: number) => window.clearTimeout(handle));
+
+    await act(async () => {
+      useSettingsStore.getState().setActiveTab('appearance', 'pointer');
+      await Promise.resolve();
+    });
+
+    const outgoing = container.querySelector('.bitfun-view-transition-boundary__view--outgoing');
+    expect(outgoing?.hasAttribute('inert')).toBe(true);
+    expect(container.querySelector('[data-testid="basics-config"]')).not.toBeNull();
+    expect(container.querySelector('[data-testid="appearance-config"]')).not.toBeNull();
+
+    act(() => vi.advanceTimersByTime(232));
+    expect(container.querySelector('[data-testid="basics-config"]')).toBeNull();
+    expect(container.querySelectorAll('[data-testid="settings-scene-content"]')).toHaveLength(1);
+  });
 });
diff --git a/src/web-ui/src/app/scenes/settings/SettingsScene.tsx b/src/web-ui/src/app/scenes/settings/SettingsScene.tsx
index ebdbc8b67a..712e6931df 100644
--- a/src/web-ui/src/app/scenes/settings/SettingsScene.tsx
+++ b/src/web-ui/src/app/scenes/settings/SettingsScene.tsx
@@ -9,8 +9,11 @@
 import React, {
   Suspense,
   useEffect,
+  useLayoutEffect,
+  useRef,
   useState,
 } from 'react';
+import { ViewTransitionBoundary } from '@/component-library';
 import { useSettingsStore } from './settingsStore';
 import { useExternalAppAwareness } from '@/infrastructure/config/components/external-sources';
 import type { ConfigTab } from './settingsConfig';
@@ -82,7 +85,11 @@ const SettingsScene: React.FC = () => {
   const activeTab = useSettingsStore(s => s.activeTab);
   const contentFocus = useSettingsStore(s => s.contentFocus);
   const contentFocusRequestId = useSettingsStore(s => s.contentFocusRequestId);
+  const tabTransitionTarget = useSettingsStore(s => s.tabTransitionTarget);
+  const tabTransitionMotion = useSettingsStore(s => s.tabTransitionMotion);
+  const tabTransitionSequence = useSettingsStore(s => s.tabTransitionSequence);
   const setActiveTab = useSettingsStore(s => s.setActiveTab);
+  const appliedTransitionSequenceRef = useRef(tabTransitionSequence);
 
   const resolvedTab: ConfigTab =
     (activeTab as string) === 'session-config' ? 'session-permissions' : activeTab;
@@ -94,6 +101,16 @@ const SettingsScene: React.FC = () => {
     }
   }, [activeTab, setActiveTab]);
 
+  const shouldAnimateTabTransition = (
+    appliedTransitionSequenceRef.current !== tabTransitionSequence
+    && tabTransitionTarget === resolvedTab
+    && tabTransitionMotion === 'pointer'
+  );
+
+  useLayoutEffect(() => {
+    appliedTransitionSequenceRef.current = tabTransitionSequence;
+  }, [tabTransitionSequence]);
+
   /**
    * Cold entries into the scene (first open after launch, deep links) mount a
    * panel whose chunk and i18n namespaces are still in flight, which paints the
@@ -132,25 +149,30 @@ const SettingsScene: React.FC = () => {
       data-bf-tab={resolvedTab}
     >
       {Content && (
-        <div
-          key={resolvedTab}
-          className="bitfun-settings-scene__content-wrapper"
-          data-testid="settings-scene-content"
-          data-bf-scene="settings"
-          data-bf-part="content"
-          data-bf-tab={resolvedTab}
+        <ViewTransitionBoundary
+          viewKey={resolvedTab}
+          animate={shouldAnimateTabTransition}
+          className="bitfun-settings-scene__content-transition"
+          viewClassName="bitfun-settings-scene__content-wrapper"
         >
-          <Suspense fallback={<SettingsSceneLoading />}>
-            {resolvedTab === 'external-sources' || resolvedTab === 'hooks' ? (
-              <ExternalSourcesConfig
-                initialFocus={contentFocus === 'hooks' ? 'hooks' : undefined}
-                focusRequestId={contentFocus === 'hooks' ? contentFocusRequestId : undefined}
-              />
-            ) : (
-              <Content />
-            )}
-          </Suspense>
-        </div>
+          <div
+            data-testid="settings-scene-content"
+            data-bf-scene="settings"
+            data-bf-part="content"
+            data-bf-tab={resolvedTab}
+          >
+            <Suspense fallback={<SettingsSceneLoading />}>
+              {resolvedTab === 'external-sources' || resolvedTab === 'hooks' ? (
+                <ExternalSourcesConfig
+                  initialFocus={contentFocus === 'hooks' ? 'hooks' : undefined}
+                  focusRequestId={contentFocus === 'hooks' ? contentFocusRequestId : undefined}
+                />
+              ) : (
+                <Content />
+              )}
+            </Suspense>
+          </div>
+        </ViewTransitionBoundary>
       )}
     </div>
   );
diff --git a/src/web-ui/src/app/scenes/settings/components/KeyboardShortcutsTab.scss b/src/web-ui/src/app/scenes/settings/components/KeyboardShortcutsTab.scss
index cba8ad3d90..c972114f39 100644
--- a/src/web-ui/src/app/scenes/settings/components/KeyboardShortcutsTab.scss
+++ b/src/web-ui/src/app/scenes/settings/components/KeyboardShortcutsTab.scss
@@ -20,7 +20,6 @@
       /* Match Search defaults; the canonical border token must stay defined to avoid a dropped border. */
       border: 1px solid var(--bf-appearance-token-border-base);
       background: var(--bf-appearance-token-element-bg-base);
-      transition: border-color 0.15s ease, box-shadow 0.15s ease;
     }
 
     &.search--hovered:not(.search--disabled) .search__wrapper {
@@ -70,7 +69,6 @@
     justify-content: space-between;
     padding: 8px 12px;
     border-radius: 6px;
-    transition: background 0.1s;
 
     &:hover {
       background: var(--bf-appearance-token-element-bg-hover);
@@ -153,7 +151,6 @@
     font-size: 12px;
     cursor: pointer;
     white-space: nowrap;
-    transition: border-color 0.1s, background 0.1s;
     min-width: 60px;
     justify-content: center;
 
@@ -166,7 +163,6 @@
       border-color: var(--bf-appearance-token-color-accent-500);
       background: var(--bf-appearance-token-color-accent-100);
       color: var(--bf-appearance-token-color-accent-500);
-      animation: kb-pulse 1s ease-in-out infinite;
     }
 
     &--conflict {
@@ -203,10 +199,6 @@
   }
 }
 
-@keyframes kb-pulse {
-  0%, 100% { opacity: 1; }
-  50% { opacity: 0.6; }
-}
 
 /* Page subtitle: keep primary title dominant */
 .kb-shortcuts-page-header.bitfun-config-page-header {
diff --git a/src/web-ui/src/app/scenes/settings/settingsStore.ts b/src/web-ui/src/app/scenes/settings/settingsStore.ts
index 4a8b451cfb..c008b56f08 100644
--- a/src/web-ui/src/app/scenes/settings/settingsStore.ts
+++ b/src/web-ui/src/app/scenes/settings/settingsStore.ts
@@ -6,6 +6,7 @@
  */
 
 import { create } from 'zustand';
+import type { InteractionMotion } from '@/shared/utils/motionPreference';
 import type { ConfigTab, SettingsContentFocus } from './settingsConfig';
 import { DEFAULT_SETTINGS_TAB, SETTINGS_CATEGORIES } from './settingsConfig';
 
@@ -13,8 +14,15 @@ interface SettingsState {
   activeTab: ConfigTab;
   contentFocus: SettingsContentFocus | null;
   contentFocusRequestId: number;
-  openTab: (tab: ConfigTab, focus?: SettingsContentFocus | null) => void;
-  setActiveTab: (tab: ConfigTab) => void;
+  tabTransitionTarget: ConfigTab | null;
+  tabTransitionMotion: InteractionMotion;
+  tabTransitionSequence: number;
+  openTab: (
+    tab: ConfigTab,
+    focus?: SettingsContentFocus | null,
+    motion?: InteractionMotion,
+  ) => void;
+  setActiveTab: (tab: ConfigTab, motion?: InteractionMotion) => void;
   /** Debounced from SettingsNav search input; used for filtering index. */
   searchQuery: string;
   setSearchQuery: (query: string) => void;
@@ -33,17 +41,29 @@ export const useSettingsStore = create<SettingsState>((set) => ({
   activeTab: DEFAULT_SETTINGS_TAB,
   contentFocus: null,
   contentFocusRequestId: 0,
+  tabTransitionTarget: null,
+  tabTransitionMotion: 'instant',
+  tabTransitionSequence: 0,
   searchQuery: '',
   unseenTabs: [],
 
-  openTab: (tab, focus = null) => set((state) => ({
+  openTab: (tab, focus = null, motion = 'instant') => set((state) => ({
     activeTab: tab,
     contentFocus: focus,
     contentFocusRequestId: focus
       ? state.contentFocusRequestId + 1
       : state.contentFocusRequestId,
+    tabTransitionTarget: tab,
+    tabTransitionMotion: motion,
+    tabTransitionSequence: state.tabTransitionSequence + 1,
+  })),
+  setActiveTab: (tab, motion = 'instant') => set((state) => ({
+    activeTab: tab,
+    contentFocus: null,
+    tabTransitionTarget: tab,
+    tabTransitionMotion: motion,
+    tabTransitionSequence: state.tabTransitionSequence + 1,
   })),
-  setActiveTab: (tab) => set({ activeTab: tab, contentFocus: null }),
   setSearchQuery: (query) => set({ searchQuery: query }),
   markTabUnseen: (tab, unseen) => set((state) => {
     const has = state.unseenTabs.includes(tab);
diff --git a/src/web-ui/src/app/scenes/todos/TodosScene.scss b/src/web-ui/src/app/scenes/todos/TodosScene.scss
new file mode 100644
index 0000000000..1128880f0d
--- /dev/null
+++ b/src/web-ui/src/app/scenes/todos/TodosScene.scss
@@ -0,0 +1,673 @@
+@use '../../../component-library/styles/tokens.scss' as *;
+
+// Below this width the two tiers stack instead of sitting side by side.
+$todos-stack-breakpoint: 1080px;
+
+.bf-todos {
+  display: flex;
+  flex-direction: column;
+  gap: $size-gap-3;
+  width: 100%;
+  height: 100%;
+  min-height: 0;
+  padding: $size-gap-4;
+  box-sizing: border-box;
+  overflow: hidden;
+
+  // ── Header ────────────────────────────────────────────────────────────────
+
+  &__head {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: $size-gap-3;
+    flex: 0 0 auto;
+    min-width: 0;
+  }
+
+  &__head-main {
+    display: flex;
+    align-items: center;
+    gap: $size-gap-3;
+    min-width: 0;
+  }
+
+  &__head-icon {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 30px;
+    height: 30px;
+    flex: 0 0 auto;
+    border-radius: $size-radius-lg;
+    background: var(--bf-appearance-token-element-bg-soft);
+    color: var(--bf-appearance-token-color-text-secondary);
+  }
+
+  &__head-text {
+    display: flex;
+    flex-direction: column;
+    gap: 1px;
+    min-width: 0;
+  }
+
+  &__title {
+    margin: 0;
+    font-size: var(--bf-appearance-token-font-size-base);
+    font-weight: $font-weight-semibold;
+    color: var(--bf-appearance-token-color-text-primary);
+  }
+
+  &__subtitle {
+    margin: 0;
+    font-size: var(--bf-appearance-token-font-size-xs);
+    color: var(--bf-appearance-token-color-text-muted);
+  }
+
+  &__head-actions {
+    display: flex;
+    align-items: center;
+    gap: $size-gap-2;
+    flex: 0 0 auto;
+  }
+
+  &__spin {
+    animation: bf-todos-spin 0.8s linear infinite;
+  }
+
+  // ── Two tiers ─────────────────────────────────────────────────────────────
+
+  &__panes {
+    display: grid;
+    grid-template-columns: minmax(320px, 4fr) minmax(420px, 6fr);
+    gap: $size-gap-4;
+    flex: 1 1 auto;
+    min-height: 0;
+  }
+
+  &__pane {
+    display: flex;
+    flex-direction: column;
+    gap: $size-gap-3;
+    min-width: 0;
+    min-height: 0;
+    overflow-y: auto;
+    padding-right: 2px;
+  }
+
+  &__pane-head {
+    display: flex;
+    flex-direction: column;
+    gap: 1px;
+    flex: 0 0 auto;
+  }
+
+  &__pane-title {
+    margin: 0;
+    font-size: var(--bf-appearance-token-font-size-2xs);
+    font-weight: $font-weight-semibold;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    color: var(--bf-appearance-token-color-text-muted);
+  }
+
+  &__pane-hint {
+    margin: 0;
+    font-size: var(--bf-appearance-token-font-size-xs);
+    color: var(--bf-appearance-token-color-text-muted);
+  }
+
+  &__empty {
+    margin: 0;
+    padding: $size-gap-6 $size-gap-4;
+    text-align: center;
+    font-size: var(--bf-appearance-token-font-size-sm);
+    color: var(--bf-appearance-token-color-text-muted);
+    border: 1px dashed var(--bf-appearance-token-border-subtle);
+    border-radius: $size-radius-lg;
+  }
+
+  // ── Rows ──────────────────────────────────────────────────────────────────
+
+  &__rows {
+    display: flex;
+    flex-direction: column;
+    gap: $size-gap-2;
+  }
+
+  &__row {
+    display: flex;
+    align-items: flex-start;
+    gap: $size-gap-3;
+    padding: $size-gap-2 $size-gap-3;
+    border-radius: $size-radius-lg;
+    background: var(--bf-appearance-token-element-bg-base);
+    cursor: pointer;
+    transition:
+      background $motion-fast $easing-standard,
+      box-shadow $motion-fast $easing-standard;
+
+    &:hover {
+      background: var(--bf-appearance-token-element-bg-soft);
+      box-shadow: var(--bf-appearance-token-shadow-xs);
+    }
+
+    &:focus-visible {
+      outline: 2px solid var(--bf-appearance-token-color-accent-500);
+      outline-offset: 2px;
+    }
+
+    &--selected {
+      background: var(--bf-appearance-token-element-bg-soft);
+      box-shadow: inset 2px 0 0 var(--bf-appearance-token-color-accent-500);
+    }
+
+    &--overdue {
+      box-shadow: inset 2px 0 0 var(--bf-appearance-token-color-warning);
+    }
+
+    &--running {
+      box-shadow: inset 2px 0 0 var(--bf-appearance-token-color-accent-500);
+    }
+
+    &--disabled {
+      opacity: 0.62;
+    }
+  }
+
+  &__row-time {
+    display: flex;
+    flex-direction: column;
+    align-items: flex-start;
+    gap: 1px;
+    flex: 0 0 auto;
+    min-width: 62px;
+  }
+
+  &__row-clock {
+    font-size: var(--bf-appearance-token-font-size-sm);
+    font-weight: $font-weight-semibold;
+    font-variant-numeric: tabular-nums;
+    color: var(--bf-appearance-token-color-text-primary);
+  }
+
+  &__row-relative {
+    font-size: var(--bf-appearance-token-font-size-2xs);
+    color: var(--bf-appearance-token-color-text-muted);
+    white-space: nowrap;
+  }
+
+  &__row-body {
+    flex: 1 1 auto;
+    min-width: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+  }
+
+  &__row-title-line {
+    display: flex;
+    align-items: center;
+    gap: $size-gap-2;
+    min-width: 0;
+  }
+
+  &__row-name {
+    min-width: 0;
+    font-size: var(--bf-appearance-token-font-size-sm);
+    font-weight: $font-weight-medium;
+    color: var(--bf-appearance-token-color-text-primary);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  &__row-badge {
+    flex: 0 0 auto;
+    padding: 1px 6px;
+    border-radius: $size-radius-sm;
+    background: color-mix(in srgb, var(--bf-appearance-token-color-accent-500) 16%, transparent);
+    color: var(--bf-appearance-token-color-accent-500);
+    font-size: var(--bf-appearance-token-font-size-2xs);
+    font-weight: $font-weight-medium;
+    line-height: 1.5;
+    white-space: nowrap;
+
+    &--warn {
+      background: color-mix(in srgb, var(--bf-appearance-token-color-warning) 16%, transparent);
+      color: var(--bf-appearance-token-color-warning);
+    }
+
+    &--running {
+      background: color-mix(in srgb, var(--bf-appearance-token-color-success) 16%, transparent);
+      color: var(--bf-appearance-token-color-success);
+    }
+  }
+
+  &__row-meta {
+    display: flex;
+    align-items: center;
+    gap: $size-gap-1;
+    min-width: 0;
+    font-size: var(--bf-appearance-token-font-size-xs);
+    color: var(--bf-appearance-token-color-text-muted);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  &__row-meta-sep {
+    opacity: 0.6;
+  }
+
+  &__row-error {
+    margin: 0;
+    font-size: var(--bf-appearance-token-font-size-xs);
+    color: var(--bf-appearance-token-color-error);
+    word-break: break-word;
+  }
+
+  &__row-actions {
+    display: flex;
+    align-items: center;
+    gap: $size-gap-2;
+    flex: 0 0 auto;
+  }
+
+  // ── Inactive group ────────────────────────────────────────────────────────
+
+  &__inactive {
+    display: flex;
+    flex-direction: column;
+    gap: $size-gap-2;
+    padding-top: $size-gap-3;
+    border-top: 1px solid color-mix(in srgb, var(--bf-appearance-token-border-subtle) 70%, transparent);
+  }
+
+  &__inactive-title {
+    margin: 0;
+    font-size: var(--bf-appearance-token-font-size-2xs);
+    font-weight: $font-weight-semibold;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    color: var(--bf-appearance-token-color-text-muted);
+  }
+
+  // ── Calendar ──────────────────────────────────────────────────────────────
+
+  &__calendar {
+    display: flex;
+    flex-direction: column;
+    gap: $size-gap-2;
+    min-width: 0;
+  }
+
+  &__calendar-head {
+    display: flex;
+    align-items: flex-start;
+    justify-content: space-between;
+    gap: $size-gap-3;
+    flex-wrap: wrap;
+  }
+
+  &__calendar-heading {
+    display: flex;
+    flex-direction: column;
+    gap: 1px;
+    min-width: 0;
+  }
+
+  &__calendar-nav {
+    display: flex;
+    align-items: center;
+    gap: $size-gap-1;
+    flex: 0 0 auto;
+  }
+
+  &__calendar-month {
+    min-width: 108px;
+    text-align: center;
+    font-size: var(--bf-appearance-token-font-size-sm);
+    font-weight: $font-weight-semibold;
+    color: var(--bf-appearance-token-color-text-primary);
+  }
+
+  &__calendar-weekdays {
+    display: grid;
+    grid-template-columns: repeat(7, minmax(0, 1fr));
+    gap: $size-gap-1;
+  }
+
+  &__calendar-weekday {
+    padding: 2px 0;
+    text-align: center;
+    font-size: var(--bf-appearance-token-font-size-2xs);
+    font-weight: $font-weight-semibold;
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    color: var(--bf-appearance-token-color-text-muted);
+  }
+
+  &__calendar-grid {
+    display: grid;
+    grid-template-columns: repeat(7, minmax(0, 1fr));
+    grid-auto-rows: minmax(74px, auto);
+    gap: $size-gap-1;
+  }
+
+  &__calendar-cell {
+    display: flex;
+    flex-direction: column;
+    align-items: stretch;
+    gap: 3px;
+    padding: 4px;
+    border: 1px solid transparent;
+    border-radius: $size-radius-base;
+    background: var(--bf-appearance-token-element-bg-base);
+    text-align: left;
+    cursor: pointer;
+    overflow: hidden;
+    transition:
+      background $motion-fast $easing-standard,
+      border-color $motion-fast $easing-standard;
+
+    &:hover {
+      background: var(--bf-appearance-token-element-bg-soft);
+    }
+
+    &:focus-visible {
+      outline: 2px solid var(--bf-appearance-token-color-accent-500);
+      outline-offset: 1px;
+    }
+
+    &--outside {
+      opacity: 0.45;
+    }
+
+    &--today {
+      border-color: color-mix(in srgb, var(--bf-appearance-token-color-accent-500) 55%, transparent);
+    }
+
+    &--selected {
+      border-color: var(--bf-appearance-token-color-accent-500);
+      background: var(--bf-appearance-token-element-bg-soft);
+    }
+  }
+
+  &__calendar-daynum {
+    font-size: var(--bf-appearance-token-font-size-xs);
+    font-weight: $font-weight-medium;
+    font-variant-numeric: tabular-nums;
+    color: var(--bf-appearance-token-color-text-secondary);
+  }
+
+  &__calendar-chips {
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+    min-width: 0;
+  }
+
+  &__calendar-chip {
+    display: flex;
+    align-items: baseline;
+    gap: 4px;
+    min-width: 0;
+    padding: 1px 4px;
+    border-radius: $size-radius-sm;
+    background: color-mix(in srgb, var(--bf-appearance-token-color-accent-500) 14%, transparent);
+    font-size: var(--bf-appearance-token-font-size-2xs);
+    line-height: 1.45;
+  }
+
+  &__calendar-chip-time {
+    flex: 0 0 auto;
+    font-variant-numeric: tabular-nums;
+    color: var(--bf-appearance-token-color-accent-500);
+  }
+
+  &__calendar-chip-name {
+    min-width: 0;
+    color: var(--bf-appearance-token-color-text-secondary);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  &__calendar-more {
+    padding-left: 4px;
+    font-size: var(--bf-appearance-token-font-size-2xs);
+    color: var(--bf-appearance-token-color-text-muted);
+  }
+
+  // ── Selected day detail ───────────────────────────────────────────────────
+
+  &__day-detail-presence {
+    display: grid;
+    grid-template-rows: 1fr;
+    min-height: 0;
+    overflow: hidden;
+    transform-origin: top center;
+    transition:
+      grid-template-rows 160ms cubic-bezier(0.23, 1, 0.32, 1),
+      opacity 120ms ease,
+      transform 150ms cubic-bezier(0.23, 1, 0.32, 1);
+
+    &[data-open='true'] {
+      @starting-style {
+        opacity: 0;
+        transform: translateY(-4px);
+      }
+    }
+
+    &[data-open='false'] {
+      grid-template-rows: 0fr;
+      opacity: 0;
+      transform: translateY(-4px);
+      pointer-events: none;
+    }
+  }
+
+  &__day-detail {
+    display: flex;
+    flex-direction: column;
+    gap: $size-gap-2;
+    min-height: 0;
+    overflow: hidden;
+    padding-top: $size-gap-3;
+    border-top: 1px solid color-mix(in srgb, var(--bf-appearance-token-border-subtle) 70%, transparent);
+  }
+
+  &__day-detail-head {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: $size-gap-2;
+  }
+
+  &__day-detail-title {
+    margin: 0;
+    font-size: var(--bf-appearance-token-font-size-sm);
+    font-weight: $font-weight-semibold;
+    color: var(--bf-appearance-token-color-text-primary);
+  }
+
+  // ── Editor ────────────────────────────────────────────────────────────────
+
+  &__editor {
+    display: flex;
+    flex-direction: column;
+    gap: $size-gap-3;
+    flex: 0 0 auto;
+    padding: $size-gap-3;
+    border: 1px solid var(--bf-appearance-token-border-subtle);
+    border-radius: $size-radius-xl;
+    background: var(--bf-appearance-token-element-bg-subtle);
+    max-height: 46vh;
+    overflow-y: auto;
+  }
+
+  &__editor-presence {
+    display: grid;
+    grid-template-rows: 1fr;
+    min-height: 0;
+    overflow: hidden;
+    transform-origin: top center;
+    transition:
+      grid-template-rows 160ms cubic-bezier(0.23, 1, 0.32, 1),
+      opacity 120ms ease,
+      transform 150ms cubic-bezier(0.23, 1, 0.32, 1);
+
+    &[data-open='true'] {
+      @starting-style {
+        opacity: 0;
+        transform: translateY(-4px);
+      }
+    }
+
+    &[data-open='false'] {
+      grid-template-rows: 0fr;
+      opacity: 0;
+      transform: translateY(-4px);
+      pointer-events: none;
+    }
+  }
+
+  &__editor-head {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: $size-gap-2;
+  }
+
+  &__editor-title {
+    margin: 0;
+    font-size: var(--bf-appearance-token-font-size-sm);
+    font-weight: $font-weight-semibold;
+    color: var(--bf-appearance-token-color-text-primary);
+  }
+
+  &__editor-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+    gap: $size-gap-3;
+  }
+
+  &__field {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+    min-width: 0;
+
+    &--toggle {
+      justify-content: flex-start;
+    }
+
+    &--prompt {
+      grid-column: 1 / -1;
+    }
+  }
+
+  &__field-label {
+    font-size: 11px;
+    font-weight: $font-weight-semibold;
+    letter-spacing: 0.03em;
+    text-transform: uppercase;
+    color: var(--bf-appearance-token-color-text-secondary);
+  }
+
+  &__field-note {
+    font-size: var(--bf-appearance-token-font-size-2xs);
+    color: var(--bf-appearance-token-color-text-muted);
+    line-height: 1.4;
+  }
+
+  &__field-static {
+    padding: 5px 0;
+    font-size: var(--bf-appearance-token-font-size-sm);
+    color: var(--bf-appearance-token-color-text-primary);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  &__interval {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) minmax(84px, auto);
+    gap: $size-gap-2;
+    align-items: center;
+  }
+
+  &__workspace-option {
+    display: flex;
+    flex-direction: column;
+    gap: 1px;
+    min-width: 0;
+  }
+
+  &__workspace-option-label {
+    font-weight: $font-weight-medium;
+    color: var(--bf-appearance-token-color-text-secondary);
+  }
+
+  &__workspace-option-path {
+    font-size: var(--bf-appearance-token-font-size-2xs);
+    color: var(--bf-appearance-token-color-text-muted);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  &__warning {
+    margin: 0;
+    padding: $size-gap-2 $size-gap-3;
+    border: 1px solid color-mix(in srgb, var(--bf-appearance-token-color-error) 20%, transparent);
+    border-radius: $size-radius-base;
+    background: color-mix(in srgb, var(--bf-appearance-token-color-error) 6%, transparent);
+    font-size: var(--bf-appearance-token-font-size-xs);
+    color: var(--bf-appearance-token-color-error);
+  }
+
+  &__editor-actions {
+    display: flex;
+    justify-content: flex-end;
+    gap: $size-gap-2;
+  }
+}
+
+@media (max-width: $todos-stack-breakpoint) {
+  .bf-todos {
+    overflow-y: auto;
+
+    &__panes {
+      grid-template-columns: minmax(0, 1fr);
+    }
+
+    &__pane {
+      overflow-y: visible;
+    }
+
+    &__calendar-grid {
+      grid-auto-rows: minmax(60px, auto);
+    }
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .bf-todos__row,
+  .bf-todos__calendar-cell,
+  .bf-todos__day-detail-presence,
+  .bf-todos__editor-presence {
+    transition: none;
+    animation: none;
+  }
+
+  .bf-todos__spin {
+    animation: none;
+  }
+}
+
+@keyframes bf-todos-spin {
+  from { transform: rotate(0deg); }
+  to   { transform: rotate(360deg); }
+}
diff --git a/src/web-ui/src/app/scenes/todos/TodosScene.tsx b/src/web-ui/src/app/scenes/todos/TodosScene.tsx
new file mode 100644
index 0000000000..4487acc88e
--- /dev/null
+++ b/src/web-ui/src/app/scenes/todos/TodosScene.tsx
@@ -0,0 +1,566 @@
+/**
+ * TodosScene — one place for every scheduled task across all workspaces.
+ *
+ * Two tiers, as the panel's contract:
+ *   - anything due within 24 hours is listed, soonest first;
+ *   - the month calendar carries the whole remaining agenda, near-term runs
+ *     included, so a day cell is never mysteriously empty.
+ *
+ * Todos are scheduled jobs, so this reads and writes the same cron service the
+ * agent's own scheduling tool and the per-workspace editors use. Changes here
+ * broadcast on the shared change event so those views stay in step.
+ */
+
+import React, {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { CalendarClock, Plus, RefreshCw } from 'lucide-react';
+import { Button, IconButton, PresenceBoundary, confirmDanger } from '@/component-library';
+import { cronAPI, type CronJob, type CreateCronJobRequest, type UpdateCronJobRequest } from '@/infrastructure/api';
+import { useI18n } from '@/infrastructure/i18n';
+import { useWorkspaceContext } from '@/infrastructure/contexts/WorkspaceContext';
+import { notificationService } from '@/shared/notification-system';
+import { createLogger } from '@/shared/utils/logger';
+import { normalizePath } from '@/shared/utils/pathUtils';
+import { WorkspaceKind } from '@/shared/types';
+import {
+  ASSISTANT_WORKSPACE_AGENT_TYPE,
+  DEFAULT_AGENT_TYPE,
+  EMPTY_VALIDATION_ERRORS,
+  SCHEDULED_JOBS_CHANGED_EVENT,
+  buildScheduleFromDraft,
+  buildTargetFromDraft,
+  buildWorkspaceRef,
+  createEmptyDraft,
+  hasValidationErrors,
+  jobToDraft,
+  notifyScheduledJobsChanged,
+  validateDraft,
+  type JobDraft,
+  type JobDraftValidationErrors,
+} from '@/app/components/scheduled-jobs/scheduledJobDraft';
+import TodoCalendar from './components/TodoCalendar';
+import TodoEditor from './components/TodoEditor';
+import TodoItemRow from './components/TodoItemRow';
+import {
+  buildTodoBuckets,
+  groupOccurrencesByDay,
+  monthRangeMs,
+  type InactiveReason,
+} from './todoOccurrences';
+import { buildWorkspaceOptions, formatDateTime } from './todoPresentation';
+import './TodosScene.scss';
+
+const log = createLogger('TodosScene');
+
+/** Keeps countdowns honest without re-rendering more than once a minute. */
+const CLOCK_TICK_MS = 30_000;
+
+function startOfCurrentMonthMs(nowMs: number): number {
+  const now = new Date(nowMs);
+  return new Date(now.getFullYear(), now.getMonth(), 1).getTime();
+}
+
+const TodosScene: React.FC = () => {
+  const { t, formatDate } = useI18n(['scenes/todos', 'common', 'shared']);
+  const instanceIdRef = useRef(`todos-scene-${Math.random().toString(36).slice(2)}`);
+
+  const { openedWorkspacesList, currentWorkspace, primaryAssistantWorkspaceId } = useWorkspaceContext();
+
+  const [jobs, setJobs] = useState<CronJob[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [saving, setSaving] = useState(false);
+  const [nowMs, setNowMs] = useState(() => Date.now());
+  const [monthAnchorMs, setMonthAnchorMs] = useState(() => startOfCurrentMonthMs(Date.now()));
+  const [selectedDayKey, setSelectedDayKey] = useState<string | null>(null);
+
+  const [editorOpen, setEditorOpen] = useState(false);
+  // The whole job, not just its id: saving has to preserve the target kind a
+  // job was created with, so editing a session-bound job here never silently
+  // turns it into one that launches a fresh session.
+  const [editingJob, setEditingJob] = useState<CronJob | null>(null);
+  const [draft, setDraft] = useState<JobDraft>(() => createEmptyDraft());
+  const [selectedWorkspaceId, setSelectedWorkspaceId] = useState('');
+  const [validationErrors, setValidationErrors] = useState<JobDraftValidationErrors>(
+    EMPTY_VALIDATION_ERRORS,
+  );
+
+  const workspaceOptions = useMemo(
+    () => buildWorkspaceOptions(openedWorkspacesList),
+    [openedWorkspacesList],
+  );
+  const liveEditorSnapshot = {
+    editingJob,
+    draft,
+    validationErrors,
+    workspaceOptions,
+    selectedWorkspaceId,
+    saving,
+  };
+  const retainedEditorSnapshotRef = useRef(liveEditorSnapshot);
+  useLayoutEffect(() => {
+    if (editorOpen) {
+      retainedEditorSnapshotRef.current = {
+        editingJob,
+        draft,
+        validationErrors,
+        workspaceOptions,
+        selectedWorkspaceId,
+        saving,
+      };
+    }
+  }, [
+    draft,
+    editingJob,
+    editorOpen,
+    saving,
+    selectedWorkspaceId,
+    validationErrors,
+    workspaceOptions,
+  ]);
+  const renderedEditor = editorOpen ? liveEditorSnapshot : retainedEditorSnapshotRef.current;
+
+  /** Where a new Todo lands by default: current workspace, else the assistant. */
+  const defaultWorkspaceId = useMemo(() => {
+    if (currentWorkspace && workspaceOptions.some((o) => o.value === currentWorkspace.id)) {
+      return currentWorkspace.id;
+    }
+    if (
+      primaryAssistantWorkspaceId
+      && workspaceOptions.some((o) => o.value === primaryAssistantWorkspaceId)
+    ) {
+      return primaryAssistantWorkspaceId;
+    }
+    return workspaceOptions[0]?.value ?? '';
+  }, [currentWorkspace, primaryAssistantWorkspaceId, workspaceOptions]);
+
+  useEffect(() => {
+    const timer = window.setInterval(() => setNowMs(Date.now()), CLOCK_TICK_MS);
+    return () => window.clearInterval(timer);
+  }, []);
+
+  const loadJobs = useCallback(async () => {
+    setLoading(true);
+    try {
+      // No filters: the Todos panel is the cross-workspace view.
+      const result = await cronAPI.listJobs({});
+      setJobs(result);
+    } catch (error) {
+      log.error('Failed to load scheduled jobs for the Todos scene', { error });
+      notificationService.error(
+        t('messages.loadFailed', {
+          error: error instanceof Error ? error.message : String(error),
+        }),
+      );
+    } finally {
+      setLoading(false);
+    }
+  }, [t]);
+
+  useEffect(() => { void loadJobs(); }, [loadJobs]);
+
+  // Another view (a workspace editor, or the agent's own scheduling tool)
+  // changed a job — reload so the panel is never stale.
+  useEffect(() => {
+    const handleChanged = (event: Event) => {
+      const sourceId = (event as CustomEvent<{ sourceId?: string }>).detail?.sourceId;
+      if (sourceId === instanceIdRef.current) return;
+      void loadJobs();
+    };
+    window.addEventListener(SCHEDULED_JOBS_CHANGED_EVENT, handleChanged);
+    return () => window.removeEventListener(SCHEDULED_JOBS_CHANGED_EVENT, handleChanged);
+  }, [loadJobs]);
+
+  const calendarRange = useMemo(() => monthRangeMs(monthAnchorMs), [monthAnchorMs]);
+
+  const buckets = useMemo(
+    () => buildTodoBuckets(jobs, { nowMs, rangeEndMs: calendarRange.endMs }),
+    [calendarRange.endMs, jobs, nowMs],
+  );
+
+  const selectedDayOccurrences = useMemo(() => {
+    if (!selectedDayKey) return [];
+    return groupOccurrencesByDay(buckets.calendar).get(selectedDayKey) ?? [];
+  }, [buckets.calendar, selectedDayKey]);
+  const retainedSelectedDayOccurrencesRef = useRef(selectedDayOccurrences);
+  useLayoutEffect(() => {
+    if (selectedDayKey) retainedSelectedDayOccurrencesRef.current = selectedDayOccurrences;
+  }, [selectedDayKey, selectedDayOccurrences]);
+  const renderedSelectedDayOccurrences = selectedDayKey
+    ? selectedDayOccurrences
+    : retainedSelectedDayOccurrencesRef.current;
+
+  const resetEditor = useCallback(() => {
+    setEditorOpen(false);
+    setEditingJob(null);
+    setValidationErrors(EMPTY_VALIDATION_ERRORS);
+    setDraft(createEmptyDraft());
+  }, []);
+
+  const handleCreateNew = useCallback(() => {
+    const workspace = workspaceOptions.find((option) => option.value === defaultWorkspaceId);
+    const agentType = workspace?.workspace.workspaceKind === WorkspaceKind.Assistant
+      ? ASSISTANT_WORKSPACE_AGENT_TYPE
+      : DEFAULT_AGENT_TYPE;
+
+    setEditingJob(null);
+    setValidationErrors(EMPTY_VALIDATION_ERRORS);
+    setDraft(createEmptyDraft('', agentType));
+    setSelectedWorkspaceId(defaultWorkspaceId);
+    setEditorOpen(true);
+  }, [defaultWorkspaceId, workspaceOptions]);
+
+  const handleEdit = useCallback((job: CronJob) => {
+    // Toggle the editor shut when the same Todo is clicked twice.
+    if (editorOpen && editingJob?.id === job.id) {
+      resetEditor();
+      return;
+    }
+
+    // Stored refs are normalized, so normalize both sides before comparing.
+    const ref = job.target.workspace;
+    const normalizedJobPath = normalizePath(ref.workspacePath);
+    const matchedOption = workspaceOptions.find((option) => (
+      (ref.workspaceId && option.workspace.id === ref.workspaceId)
+      || normalizePath(option.workspace.rootPath) === normalizedJobPath
+    ));
+
+    setEditingJob(job);
+    setValidationErrors(EMPTY_VALIDATION_ERRORS);
+    setDraft(jobToDraft(job, DEFAULT_AGENT_TYPE));
+    setSelectedWorkspaceId(matchedOption?.value ?? defaultWorkspaceId);
+    setEditorOpen(true);
+  }, [defaultWorkspaceId, editingJob, editorOpen, resetEditor, workspaceOptions]);
+
+  const handleToggleEnabled = useCallback(async (job: CronJob, enabled: boolean) => {
+    try {
+      await cronAPI.updateJob(job.id, { enabled });
+      await loadJobs();
+      notifyScheduledJobsChanged(instanceIdRef.current);
+    } catch (error) {
+      log.error('Failed to toggle Todo', { jobId: job.id, error });
+      notificationService.error(
+        t('messages.updateFailed', {
+          error: error instanceof Error ? error.message : String(error),
+        }),
+      );
+    }
+  }, [loadJobs, t]);
+
+  const handleDelete = useCallback(async (job: CronJob) => {
+    const confirmed = await confirmDanger(t('deleteDialog.title', { name: job.name }), null);
+    if (!confirmed) return;
+
+    try {
+      await cronAPI.deleteJob(job.id);
+      if (editingJob?.id === job.id) resetEditor();
+      await loadJobs();
+      notifyScheduledJobsChanged(instanceIdRef.current);
+    } catch (error) {
+      log.error('Failed to delete Todo', { jobId: job.id, error });
+      notificationService.error(
+        t('messages.deleteFailed', {
+          error: error instanceof Error ? error.message : String(error),
+        }),
+      );
+    }
+  }, [editingJob, loadJobs, resetEditor, t]);
+
+  const handleSave = useCallback(async () => {
+    // New Todos always launch their own session; an existing job keeps whatever
+    // target it was created with, including a binding to a specific session.
+    const targetKind = editingJob?.target.kind ?? 'workspace';
+
+    const nextErrors = validateDraft(targetKind, draft);
+    setValidationErrors(nextErrors);
+    if (hasValidationErrors(nextErrors)) return;
+
+    const option = workspaceOptions.find((entry) => entry.value === selectedWorkspaceId);
+    if (!option) {
+      notificationService.warning(t('messages.workspaceRequired'));
+      return;
+    }
+
+    const workspaceRef = buildWorkspaceRef(
+      option.workspace.rootPath,
+      option.workspace.id,
+      option.remoteConnectionId,
+      option.remoteSshHost,
+    );
+    if (!workspaceRef) {
+      notificationService.warning(t('messages.workspaceRequired'));
+      return;
+    }
+
+    const schedule = buildScheduleFromDraft(draft);
+    const target = buildTargetFromDraft(targetKind, draft, workspaceRef);
+
+    setSaving(true);
+    try {
+      if (editingJob) {
+        const request: UpdateCronJobRequest = {
+          name: draft.name.trim(),
+          payload: { text: draft.text.trim() },
+          enabled: draft.enabled,
+          schedule,
+          target,
+        };
+        await cronAPI.updateJob(editingJob.id, request);
+      } else {
+        const request: CreateCronJobRequest = {
+          name: draft.name.trim(),
+          payload: { text: draft.text.trim() },
+          enabled: draft.enabled,
+          schedule,
+          target,
+        };
+        await cronAPI.createJob(request);
+      }
+      resetEditor();
+      await loadJobs();
+      notifyScheduledJobsChanged(instanceIdRef.current);
+    } catch (error) {
+      log.error('Failed to save Todo', { error });
+      notificationService.error(
+        t('messages.saveFailed', {
+          error: error instanceof Error ? error.message : String(error),
+        }),
+      );
+    } finally {
+      setSaving(false);
+    }
+  }, [draft, editingJob, loadJobs, resetEditor, selectedWorkspaceId, t, workspaceOptions]);
+
+  const inactiveStatusLabel = useCallback((reason: InactiveReason) => {
+    switch (reason) {
+      case 'disabled':
+        return t('inactive.disabled');
+      case 'completed':
+        return t('shared:statuses.done');
+      default:
+        return t('inactive.invalid');
+    }
+  }, [t]);
+
+  const summaryLabel = t('header.summary', {
+    total: jobs.length,
+    dueSoon: buckets.upcoming.length,
+  });
+
+  return (
+    <div
+      className="bf-todos"
+      data-bf-scene="todos"
+      data-bf-part="root"
+      data-testid="todos-scene"
+    >
+      <header className="bf-todos__head" data-bf-scene="todos" data-bf-part="header">
+        <div className="bf-todos__head-main">
+          <span className="bf-todos__head-icon" aria-hidden="true"><CalendarClock size={16} /></span>
+          <div className="bf-todos__head-text">
+            <h2 className="bf-todos__title">{t('title')}</h2>
+            <p className="bf-todos__subtitle">{summaryLabel}</p>
+          </div>
+        </div>
+        <div className="bf-todos__head-actions" data-bf-scene="todos" data-bf-part="headerActions">
+          <IconButton
+            type="button"
+            size="xs"
+            aria-label={t('actions.refresh')}
+            tooltip={t('actions.refresh')}
+            onClick={() => { void loadJobs(); }}
+            data-testid="todos-refresh"
+          >
+            <RefreshCw size={14} className={loading ? 'bf-todos__spin' : undefined} />
+          </IconButton>
+          <Button
+            size="small"
+            variant="primary"
+            onClick={handleCreateNew}
+            disabled={workspaceOptions.length === 0}
+            data-testid="todos-new"
+          >
+            <Plus size={13} />
+            <span>{t('actions.newTodo')}</span>
+          </Button>
+        </div>
+      </header>
+
+      <PresenceBoundary
+        active={editorOpen}
+        exitDurationMs={160}
+        minimumExitDurationMs={160}
+      >
+        <div
+          className="bf-todos__editor-presence"
+          data-open={editorOpen ? 'true' : 'false'}
+          aria-hidden={!editorOpen}
+          {...(!editorOpen ? { inert: '' } : {})}
+        >
+          <TodoEditor
+            draft={renderedEditor.draft}
+            onDraftChange={setDraft}
+            validationErrors={renderedEditor.validationErrors}
+            onValidationErrorsChange={setValidationErrors}
+            workspaceOptions={renderedEditor.workspaceOptions}
+            selectedWorkspaceId={renderedEditor.selectedWorkspaceId}
+            onSelectedWorkspaceIdChange={setSelectedWorkspaceId}
+            isEditing={Boolean(renderedEditor.editingJob)}
+            boundSessionId={
+              renderedEditor.editingJob?.target.kind === 'session'
+                ? renderedEditor.editingJob.target.sessionId
+                : null
+            }
+            saving={renderedEditor.saving}
+            onSave={() => { void handleSave(); }}
+            onCancel={resetEditor}
+          />
+        </div>
+      </PresenceBoundary>
+
+      <div className="bf-todos__panes" data-bf-scene="todos" data-bf-part="panes">
+        {/* ── Tier 1: due within 24 hours ───────────────────── */}
+        <section
+          className="bf-todos__pane bf-todos__pane--list"
+          aria-label={t('list.title')}
+          data-bf-scene="todos"
+          data-bf-part="listPane"
+          data-testid="todos-list-pane"
+        >
+          <header className="bf-todos__pane-head">
+            <h3 className="bf-todos__pane-title">{t('list.title')}</h3>
+            <p className="bf-todos__pane-hint">{t('list.hint')}</p>
+          </header>
+
+          {buckets.upcoming.length === 0 ? (
+            <p className="bf-todos__empty" data-bf-scene="todos" data-bf-part="empty">
+              {t('list.empty')}
+            </p>
+          ) : (
+            <div className="bf-todos__rows" data-bf-scene="todos" data-bf-part="rows">
+              {buckets.upcoming.map((occurrence) => (
+                <TodoItemRow
+                  key={`${occurrence.job.id}-${occurrence.atMs}`}
+                  job={occurrence.job}
+                  atMs={occurrence.atMs}
+                  isOverdue={occurrence.isOverdue}
+                  isNextRun={occurrence.isNextRun}
+                  isRunning={occurrence.isRunning}
+                  nowMs={nowMs}
+                  workspaces={openedWorkspacesList}
+                  isSelected={editingJob?.id === occurrence.job.id}
+                  onEdit={handleEdit}
+                  onDelete={(job) => { void handleDelete(job); }}
+                  onToggleEnabled={(job, enabled) => { void handleToggleEnabled(job, enabled); }}
+                />
+              ))}
+            </div>
+          )}
+
+          {buckets.inactive.length > 0 ? (
+            <div className="bf-todos__inactive" data-bf-scene="todos" data-bf-part="inactive">
+              <h4 className="bf-todos__inactive-title">
+                {t('inactive.title', { total: buckets.inactive.length })}
+              </h4>
+              <div className="bf-todos__rows">
+                {buckets.inactive.map((entry) => (
+                  <TodoItemRow
+                    key={entry.job.id}
+                    job={entry.job}
+                    atMs={null}
+                    nowMs={nowMs}
+                    workspaces={openedWorkspacesList}
+                    statusLabel={inactiveStatusLabel(entry.reason)}
+                    isSelected={editingJob?.id === entry.job.id}
+                    onEdit={handleEdit}
+                    onDelete={(job) => { void handleDelete(job); }}
+                    onToggleEnabled={(job, enabled) => { void handleToggleEnabled(job, enabled); }}
+                  />
+                ))}
+              </div>
+            </div>
+          ) : null}
+        </section>
+
+        {/* ── Tier 2: more than 24 hours out ────────────────── */}
+        <div
+          className="bf-todos__pane bf-todos__pane--calendar"
+          data-bf-scene="todos"
+          data-bf-part="calendarPane"
+        >
+          <TodoCalendar
+            occurrences={buckets.calendar}
+            monthAnchorMs={monthAnchorMs}
+            selectedDayKey={selectedDayKey}
+            nowMs={nowMs}
+            onMonthChange={(nextMonthMs) => {
+              setMonthAnchorMs(nextMonthMs);
+              setSelectedDayKey(null);
+            }}
+            onSelectDay={setSelectedDayKey}
+          />
+
+          <PresenceBoundary
+            active={selectedDayKey != null}
+            exitDurationMs={160}
+            minimumExitDurationMs={160}
+          >
+            <div
+              className="bf-todos__day-detail-presence"
+              data-open={selectedDayKey ? 'true' : 'false'}
+              aria-hidden={!selectedDayKey}
+              {...(!selectedDayKey ? { inert: '' } : {})}
+            >
+              <section
+                className="bf-todos__day-detail"
+                aria-label={t('calendar.dayDetailTitle')}
+                data-bf-scene="todos"
+                data-bf-part="dayDetail"
+                data-testid="todos-day-detail"
+              >
+                <header className="bf-todos__day-detail-head">
+                  <h4 className="bf-todos__day-detail-title">
+                    {renderedSelectedDayOccurrences[0]
+                      ? formatDateTime(renderedSelectedDayOccurrences[0].atMs, formatDate)
+                      : t('calendar.dayDetailTitle')}
+                  </h4>
+                  <Button size="small" variant="ghost" onClick={() => setSelectedDayKey(null)}>
+                    {t('calendar.clearDay')}
+                  </Button>
+                </header>
+                {renderedSelectedDayOccurrences.length === 0 ? (
+                  <p className="bf-todos__empty">{t('calendar.dayEmpty')}</p>
+                ) : (
+                  <div className="bf-todos__rows">
+                    {renderedSelectedDayOccurrences.map((occurrence) => (
+                      <TodoItemRow
+                        key={`${occurrence.job.id}-${occurrence.atMs}`}
+                        job={occurrence.job}
+                        atMs={occurrence.atMs}
+                        isNextRun={occurrence.isNextRun}
+                        isRunning={occurrence.isRunning}
+                        nowMs={nowMs}
+                        workspaces={openedWorkspacesList}
+                        isSelected={editingJob?.id === occurrence.job.id}
+                        onEdit={handleEdit}
+                        onDelete={(job) => { void handleDelete(job); }}
+                        onToggleEnabled={(job, enabled) => { void handleToggleEnabled(job, enabled); }}
+                      />
+                    ))}
+                  </div>
+                )}
+              </section>
+            </div>
+          </PresenceBoundary>
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export default TodosScene;
diff --git a/src/web-ui/src/app/scenes/todos/appearance.ts b/src/web-ui/src/app/scenes/todos/appearance.ts
new file mode 100644
index 0000000000..7f8c3a2ec1
--- /dev/null
+++ b/src/web-ui/src/app/scenes/todos/appearance.ts
@@ -0,0 +1,41 @@
+import type { AppearanceSurfaceDescriptor } from '@/infrastructure/appearance/types';
+
+export const todosSceneAppearanceDescriptor: AppearanceSurfaceDescriptor = {
+  id: 'todos',
+  parts: [
+    { id: 'root' },
+    { id: 'header' },
+    { id: 'headerActions' },
+    { id: 'panes' },
+    { id: 'listPane' },
+    { id: 'rows' },
+    { id: 'row' },
+    { id: 'rowTime' },
+    { id: 'rowBody' },
+    { id: 'rowBadge' },
+    { id: 'rowError' },
+    { id: 'rowActions' },
+    { id: 'inactive' },
+    { id: 'empty' },
+    { id: 'calendarPane' },
+    { id: 'calendar' },
+    { id: 'calendarHead' },
+    { id: 'calendarNav' },
+    { id: 'calendarGrid' },
+    { id: 'calendarCell' },
+    { id: 'dayDetail' },
+    { id: 'editor' },
+    { id: 'editorHead' },
+    { id: 'editorGrid' },
+    { id: 'editorActions' },
+    { id: 'field' },
+    { id: 'warning' },
+  ],
+  states: [
+    { id: 'selected', selector: { kind: 'self', suffix: '[data-bf-state~="selected"]' } },
+    { id: 'today', selector: { kind: 'self', suffix: '[data-bf-state~="today"]' } },
+    { id: 'outside', selector: { kind: 'self', suffix: '[data-bf-state~="outside"]' } },
+    { id: 'overdue', selector: { kind: 'self', suffix: '[data-bf-state~="overdue"]' } },
+    { id: 'disabled', selector: { kind: 'self', suffix: '[data-bf-state~="disabled"]' } },
+  ],
+};
diff --git a/src/web-ui/src/app/scenes/todos/components/TodoCalendar.tsx b/src/web-ui/src/app/scenes/todos/components/TodoCalendar.tsx
new file mode 100644
index 0000000000..16fa6622e9
--- /dev/null
+++ b/src/web-ui/src/app/scenes/todos/components/TodoCalendar.tsx
@@ -0,0 +1,183 @@
+/**
+ * Month calendar covering the whole remaining agenda.
+ *
+ * Near-term runs appear here as well as in the 24-hour list: the list answers
+ * "what is about to happen", the calendar answers "when is everything
+ * happening", and hiding today's runs from it only made day cells look wrong.
+ * Jobs with nothing left to run are the only ones left out.
+ */
+
+import React, { useMemo } from 'react';
+import { ChevronLeft, ChevronRight } from 'lucide-react';
+import { IconButton, Button } from '@/component-library';
+import { useI18n } from '@/infrastructure/i18n';
+import {
+  buildMonthGrid,
+  groupOccurrencesByDay,
+  localDayKey,
+  type TodoOccurrence,
+} from '../todoOccurrences';
+import { formatTimeOfDay } from '../todoPresentation';
+
+/** Chips rendered inside a day cell before collapsing into a "+N" counter. */
+const MAX_CHIPS_PER_DAY = 3;
+
+export interface TodoCalendarProps {
+  occurrences: TodoOccurrence[];
+  monthAnchorMs: number;
+  selectedDayKey: string | null;
+  nowMs: number;
+  onMonthChange: (monthAnchorMs: number) => void;
+  onSelectDay: (dayKey: string | null) => void;
+}
+
+const TodoCalendar: React.FC<TodoCalendarProps> = ({
+  occurrences,
+  monthAnchorMs,
+  selectedDayKey,
+  nowMs,
+  onMonthChange,
+  onSelectDay,
+}) => {
+  const { t, formatDate } = useI18n('scenes/todos');
+
+  const grid = useMemo(() => buildMonthGrid(monthAnchorMs), [monthAnchorMs]);
+  const byDay = useMemo(() => groupOccurrencesByDay(occurrences), [occurrences]);
+
+  const anchorDate = useMemo(() => new Date(monthAnchorMs), [monthAnchorMs]);
+  const anchorMonth = anchorDate.getMonth();
+  const todayKey = localDayKey(nowMs);
+
+  const monthLabel = formatDate(anchorDate, { year: 'numeric', month: 'long' });
+
+  // Weekday headers are derived from the grid so they follow the active locale
+  // instead of a hard-coded English list.
+  const weekdayLabels = useMemo(
+    () => grid.slice(0, 7).map((day) => formatDate(day, { weekday: 'short' })),
+    [formatDate, grid],
+  );
+
+  const shiftMonth = (delta: number) => {
+    const shifted = new Date(anchorDate.getFullYear(), anchorMonth + delta, 1);
+    onMonthChange(shifted.getTime());
+  };
+
+  return (
+    <section
+      className="bf-todos__calendar"
+      aria-label={t('calendar.title')}
+      data-bf-scene="todos"
+      data-bf-part="calendar"
+      data-testid="todos-calendar"
+    >
+      <header className="bf-todos__calendar-head" data-bf-scene="todos" data-bf-part="calendarHead">
+        <div className="bf-todos__calendar-heading">
+          <h3 className="bf-todos__pane-title">{t('calendar.title')}</h3>
+          <p className="bf-todos__pane-hint">{t('calendar.hint')}</p>
+        </div>
+        <div className="bf-todos__calendar-nav" data-bf-scene="todos" data-bf-part="calendarNav">
+          <IconButton
+            type="button"
+            size="xs"
+            aria-label={t('calendar.previousMonth')}
+            tooltip={t('calendar.previousMonth')}
+            onClick={() => shiftMonth(-1)}
+            data-testid="todos-calendar-prev"
+          >
+            <ChevronLeft size={14} />
+          </IconButton>
+          <span className="bf-todos__calendar-month" data-testid="todos-calendar-month">{monthLabel}</span>
+          <IconButton
+            type="button"
+            size="xs"
+            aria-label={t('calendar.nextMonth')}
+            tooltip={t('calendar.nextMonth')}
+            onClick={() => shiftMonth(1)}
+            data-testid="todos-calendar-next"
+          >
+            <ChevronRight size={14} />
+          </IconButton>
+          <Button
+            size="small"
+            variant="ghost"
+            onClick={() => {
+              const today = new Date(nowMs);
+              onMonthChange(new Date(today.getFullYear(), today.getMonth(), 1).getTime());
+            }}
+          >
+            {t('calendar.today')}
+          </Button>
+        </div>
+      </header>
+
+      <div className="bf-todos__calendar-weekdays" aria-hidden="true">
+        {weekdayLabels.map((label, index) => (
+          <span key={index} className="bf-todos__calendar-weekday">{label}</span>
+        ))}
+      </div>
+
+      <div className="bf-todos__calendar-grid" role="grid" data-bf-scene="todos" data-bf-part="calendarGrid">
+        {grid.map((day) => {
+          const dayKey = localDayKey(day.getTime());
+          const dayOccurrences = byDay.get(dayKey) ?? [];
+          const isCurrentMonth = day.getMonth() === anchorMonth;
+          const isToday = dayKey === todayKey;
+          const isSelected = dayKey === selectedDayKey;
+          const cellState = [
+            isSelected ? 'selected' : null,
+            isToday ? 'today' : null,
+            isCurrentMonth ? null : 'outside',
+          ].filter(Boolean).join(' ');
+
+          return (
+            <button
+              key={dayKey}
+              type="button"
+              role="gridcell"
+              className={[
+                'bf-todos__calendar-cell',
+                isCurrentMonth ? '' : 'bf-todos__calendar-cell--outside',
+                isToday ? 'bf-todos__calendar-cell--today' : '',
+                isSelected ? 'bf-todos__calendar-cell--selected' : '',
+                dayOccurrences.length > 0 ? 'bf-todos__calendar-cell--has-items' : '',
+              ].filter(Boolean).join(' ')}
+              data-bf-scene="todos"
+              data-bf-part="calendarCell"
+              data-bf-state={cellState || undefined}
+              data-testid="todos-calendar-cell"
+              data-day-key={dayKey}
+              aria-pressed={isSelected}
+              aria-label={`${formatDate(day, { year: 'numeric', month: 'long', day: 'numeric' })}, ${
+                t('calendar.dayCount', { total: dayOccurrences.length })
+              }`}
+              onClick={() => onSelectDay(isSelected ? null : dayKey)}
+            >
+              <span className="bf-todos__calendar-daynum">{day.getDate()}</span>
+              <span className="bf-todos__calendar-chips">
+                {dayOccurrences.slice(0, MAX_CHIPS_PER_DAY).map((occurrence, index) => (
+                  <span
+                    key={`${occurrence.job.id}-${occurrence.atMs}-${index}`}
+                    className="bf-todos__calendar-chip"
+                    title={`${formatTimeOfDay(occurrence.atMs, formatDate)} ${occurrence.job.name}`}
+                  >
+                    <span className="bf-todos__calendar-chip-time">
+                      {formatTimeOfDay(occurrence.atMs, formatDate)}
+                    </span>
+                    <span className="bf-todos__calendar-chip-name">{occurrence.job.name}</span>
+                  </span>
+                ))}
+                {dayOccurrences.length > MAX_CHIPS_PER_DAY ? (
+                  <span className="bf-todos__calendar-more">
+                    {t('calendar.moreCount', { total: dayOccurrences.length - MAX_CHIPS_PER_DAY })}
+                  </span>
+                ) : null}
+              </span>
+            </button>
+          );
+        })}
+      </div>
+    </section>
+  );
+};
+
+export default TodoCalendar;
diff --git a/src/web-ui/src/app/scenes/todos/components/TodoEditor.tsx b/src/web-ui/src/app/scenes/todos/components/TodoEditor.tsx
new file mode 100644
index 0000000000..bc59e7e744
--- /dev/null
+++ b/src/web-ui/src/app/scenes/todos/components/TodoEditor.tsx
@@ -0,0 +1,403 @@
+/**
+ * Create / edit form for a Todo.
+ *
+ * Unlike the per-workspace scheduled-jobs editor, the Todos scene is global, so
+ * this form owns a workspace picker: a job cannot be scheduled without knowing
+ * which workspace it runs in.
+ */
+
+import React, { useCallback, useEffect, useMemo, useState } from 'react';
+import { Button, Input, Select, Switch, Textarea } from '@/component-library';
+import { agentAPI, type ModeInfo } from '@/infrastructure/api/service-api/AgentAPI';
+import { useI18n } from '@/infrastructure/i18n';
+import { WorkspaceKind } from '@/shared/types';
+import { createLogger } from '@/shared/utils/logger';
+import {
+  ASSISTANT_WORKSPACE_AGENT_TYPE,
+  DEFAULT_AGENT_TYPE,
+  getCurrentLocalDateTimeInput,
+  isFutureLocalDateTimeInput,
+  type JobDraft,
+  type JobDraftValidationErrors,
+  type ScheduleKind,
+} from '@/app/components/scheduled-jobs/scheduledJobDraft';
+import {
+  INTERVAL_UNIT_OPTIONS,
+  type IntervalUnit,
+} from '@/app/components/scheduled-jobs/scheduledJobDraft';
+import LocalizedDateTimeField from '@/app/components/scheduled-jobs/LocalizedDateTimeField';
+import '@/app/components/scheduled-jobs/LocalizedDateTimeField.scss';
+import type { TodoWorkspaceOption } from '../todoPresentation';
+
+const log = createLogger('TodoEditor');
+
+export interface TodoEditorProps {
+  draft: JobDraft;
+  onDraftChange: (updater: (draft: JobDraft) => JobDraft) => void;
+  validationErrors: JobDraftValidationErrors;
+  onValidationErrorsChange: (
+    updater: (errors: JobDraftValidationErrors) => JobDraftValidationErrors,
+  ) => void;
+  workspaceOptions: TodoWorkspaceOption[];
+  selectedWorkspaceId: string;
+  onSelectedWorkspaceIdChange: (workspaceId: string) => void;
+  /** True when editing an existing Todo rather than creating one. */
+  isEditing: boolean;
+  /**
+   * Set when the Todo runs inside a specific existing session instead of
+   * launching a new one. That binding is preserved on save, so the agent-type
+   * picker is replaced by a note rather than implying a fresh session.
+   */
+  boundSessionId?: string | null;
+  saving: boolean;
+  onSave: () => void;
+  onCancel: () => void;
+}
+
+const TodoEditor: React.FC<TodoEditorProps> = ({
+  draft,
+  onDraftChange,
+  validationErrors,
+  onValidationErrorsChange,
+  workspaceOptions,
+  selectedWorkspaceId,
+  onSelectedWorkspaceIdChange,
+  isEditing,
+  boundSessionId = null,
+  saving,
+  onSave,
+  onCancel,
+}) => {
+  const { t } = useI18n(['scenes/todos', 'common', 'shared']);
+  const [availableModes, setAvailableModes] = useState<ModeInfo[]>([]);
+
+  const selectedWorkspace = useMemo(
+    () => workspaceOptions.find((option) => option.value === selectedWorkspaceId)?.workspace ?? null,
+    [selectedWorkspaceId, workspaceOptions],
+  );
+  const isAssistantWorkspace = selectedWorkspace?.workspaceKind === WorkspaceKind.Assistant;
+
+  useEffect(() => {
+    let cancelled = false;
+
+    const loadAvailableModes = async () => {
+      try {
+        const modes = await agentAPI.getAvailableModes();
+        if (!cancelled) setAvailableModes(modes);
+      } catch (error) {
+        log.error('Failed to load available modes for the Todo editor', { error });
+      }
+    };
+
+    void loadAvailableModes();
+    return () => { cancelled = true; };
+  }, []);
+
+  // An assistant workspace only ever runs its own agent type; keep the draft in
+  // step with the picked workspace so a saved Todo cannot carry a stale one.
+  useEffect(() => {
+    if (!selectedWorkspace) return;
+    onDraftChange((current) => {
+      const nextAgentType = isAssistantWorkspace
+        ? ASSISTANT_WORKSPACE_AGENT_TYPE
+        : current.agentType === ASSISTANT_WORKSPACE_AGENT_TYPE || !current.agentType
+          ? DEFAULT_AGENT_TYPE
+          : current.agentType;
+      return current.agentType === nextAgentType
+        ? current
+        : { ...current, agentType: nextAgentType };
+    });
+  }, [isAssistantWorkspace, onDraftChange, selectedWorkspace]);
+
+  const agentTypeOptions = useMemo(() => {
+    if (isAssistantWorkspace) {
+      return [{ value: ASSISTANT_WORKSPACE_AGENT_TYPE, label: ASSISTANT_WORKSPACE_AGENT_TYPE }];
+    }
+
+    const options = availableModes
+      .filter((mode) => mode.id !== ASSISTANT_WORKSPACE_AGENT_TYPE)
+      .map((mode) => ({ value: mode.id, label: mode.name?.trim() || mode.id }));
+
+    if (draft.agentType && !options.some((option) => option.value === draft.agentType)) {
+      options.push({ value: draft.agentType, label: draft.agentType });
+    }
+    return options;
+  }, [availableModes, draft.agentType, isAssistantWorkspace]);
+
+  const workspaceSelectOptions = useMemo(
+    () => workspaceOptions.map((option) => ({
+      value: option.value,
+      label: option.label,
+      description: option.description,
+    })),
+    [workspaceOptions],
+  );
+
+  const updateDraft = useCallback(
+    (patch: Partial<JobDraft>) => onDraftChange((current) => ({ ...current, ...patch })),
+    [onDraftChange],
+  );
+
+  const clearError = useCallback(
+    (field: keyof JobDraftValidationErrors) =>
+      onValidationErrorsChange((current) => ({ ...current, [field]: false })),
+    [onValidationErrorsChange],
+  );
+
+  return (
+    <section
+      className="bf-todos__editor"
+      aria-label={isEditing ? t('editor.editTitle') : t('editor.createTitle')}
+      data-bf-scene="todos"
+      data-bf-part="editor"
+      data-testid="todos-editor"
+    >
+      <header className="bf-todos__editor-head" data-bf-scene="todos" data-bf-part="editorHead">
+        <h3 className="bf-todos__editor-title">
+          {isEditing ? t('editor.editTitle') : t('editor.createTitle')}
+        </h3>
+      </header>
+
+      <div className="bf-todos__editor-grid" data-bf-scene="todos" data-bf-part="editorGrid">
+        <label className="bf-todos__field" data-bf-scene="todos" data-bf-part="field">
+          <span className="bf-todos__field-label">{t('editor.fields.name')}</span>
+          <Input
+            size="small"
+            value={draft.name}
+            error={validationErrors.name}
+            placeholder={t('editor.placeholders.name')}
+            onChange={(event) => {
+              const name = event.currentTarget.value;
+              clearError('name');
+              updateDraft({ name });
+            }}
+            data-testid="todos-editor-name"
+          />
+        </label>
+
+        <label className="bf-todos__field" data-bf-scene="todos" data-bf-part="field">
+          <span className="bf-todos__field-label">{t('shared:features.workspace')}</span>
+          <Select
+            size="small"
+            options={workspaceSelectOptions}
+            value={selectedWorkspaceId}
+            searchable
+            placeholder={t('editor.placeholders.workspace')}
+            onChange={(value) => onSelectedWorkspaceIdChange(String(value))}
+            renderOption={(option) => (
+              <div className="bf-todos__workspace-option">
+                <span className="bf-todos__workspace-option-label">{option.label}</span>
+                {option.description ? (
+                  <span className="bf-todos__workspace-option-path">{option.description}</span>
+                ) : null}
+              </div>
+            )}
+          />
+        </label>
+
+        {boundSessionId ? (
+          <div className="bf-todos__field" data-bf-scene="todos" data-bf-part="field">
+            <span className="bf-todos__field-label">{t('editor.fields.runsIn')}</span>
+            <span className="bf-todos__field-static" title={boundSessionId}>
+              {t('target.existingSession')}
+            </span>
+            <span className="bf-todos__field-note">{t('editor.hints.boundSession')}</span>
+          </div>
+        ) : (
+          <label className="bf-todos__field" data-bf-scene="todos" data-bf-part="field">
+            <span className="bf-todos__field-label">{t('editor.fields.agentType')}</span>
+            <Select
+              size="small"
+              options={agentTypeOptions}
+              value={draft.agentType}
+              error={validationErrors.agentType}
+              disabled={isAssistantWorkspace}
+              placeholder={t('editor.placeholders.agentType')}
+              onChange={(value) => {
+                clearError('agentType');
+                updateDraft({ agentType: String(value) });
+              }}
+            />
+          </label>
+        )}
+
+        <label className="bf-todos__field" data-bf-scene="todos" data-bf-part="field">
+          <span className="bf-todos__field-label">{t('editor.fields.scheduleKind')}</span>
+          <Select
+            size="small"
+            value={draft.scheduleKind}
+            options={[
+              { value: 'at', label: t('schedule.kinds.at') },
+              { value: 'every', label: t('schedule.kinds.every') },
+              { value: 'cron', label: t('schedule.kinds.cron') },
+            ]}
+            onChange={(value) => {
+              const scheduleKind = value as ScheduleKind;
+              onValidationErrorsChange((current) => ({
+                ...current,
+                at: false,
+                everyValue: false,
+                cronExpr: false,
+              }));
+              onDraftChange((current) => ({
+                ...current,
+                scheduleKind,
+                at: scheduleKind === 'at' && !current.at.trim()
+                  ? getCurrentLocalDateTimeInput()
+                  : current.at,
+              }));
+            }}
+            data-testid="todos-editor-schedule-kind"
+          />
+        </label>
+
+        {draft.scheduleKind === 'at' ? (
+          <label className="bf-todos__field" data-bf-scene="todos" data-bf-part="field">
+            <span className="bf-todos__field-label">{t('editor.fields.at')}</span>
+            <LocalizedDateTimeField
+              value={draft.at}
+              error={validationErrors.at}
+              onChange={(at) => {
+                clearError('at');
+                // Re-enable a Todo that was left off after its time passed.
+                onDraftChange((current) => ({
+                  ...current,
+                  at,
+                  enabled: !current.enabled && isFutureLocalDateTimeInput(at) ? true : current.enabled,
+                }));
+              }}
+            />
+          </label>
+        ) : null}
+
+        {draft.scheduleKind === 'every' ? (
+          <>
+            <label className="bf-todos__field" data-bf-scene="todos" data-bf-part="field">
+              <span className="bf-todos__field-label">{t('editor.fields.every')}</span>
+              <div className="bf-todos__interval">
+                <Input
+                  size="small"
+                  type="number"
+                  value={draft.everyValue}
+                  error={validationErrors.everyValue}
+                  placeholder="1"
+                  onChange={(event) => {
+                    const everyValue = event.currentTarget.value;
+                    clearError('everyValue');
+                    updateDraft({ everyValue });
+                  }}
+                />
+                <Select
+                  size="small"
+                  value={draft.everyUnit}
+                  options={INTERVAL_UNIT_OPTIONS.map((unit) => ({
+                    value: unit,
+                    label: t(`schedule.intervalUnits.${unit}`),
+                  }))}
+                  onChange={(value) => updateDraft({ everyUnit: value as IntervalUnit })}
+                />
+              </div>
+            </label>
+            <label className="bf-todos__field" data-bf-scene="todos" data-bf-part="field">
+              <span className="bf-todos__field-label">{t('editor.fields.anchor')}</span>
+              <LocalizedDateTimeField
+                value={draft.anchorMs}
+                aria-label={t('editor.fields.anchor')}
+                onChange={(anchorMs) => updateDraft({ anchorMs })}
+              />
+            </label>
+          </>
+        ) : null}
+
+        {draft.scheduleKind === 'cron' ? (
+          <>
+            <label className="bf-todos__field" data-bf-scene="todos" data-bf-part="field">
+              <span className="bf-todos__field-label">{t('editor.fields.cronExpr')}</span>
+              <Input
+                size="small"
+                value={draft.expr}
+                error={validationErrors.cronExpr}
+                placeholder="0 8 * * *"
+                onChange={(event) => {
+                  const expr = event.currentTarget.value;
+                  clearError('cronExpr');
+                  updateDraft({ expr });
+                }}
+              />
+              <span className="bf-todos__field-note">{t('editor.hints.cronExpr')}</span>
+            </label>
+            <label className="bf-todos__field" data-bf-scene="todos" data-bf-part="field">
+              <span className="bf-todos__field-label">{t('editor.fields.timezone')}</span>
+              <Input
+                size="small"
+                value={draft.tz}
+                placeholder={t('editor.placeholders.timezone')}
+                onChange={(event) => updateDraft({ tz: event.currentTarget.value })}
+              />
+            </label>
+          </>
+        ) : null}
+
+        <div
+          className="bf-todos__field bf-todos__field--toggle"
+          data-bf-scene="todos"
+          data-bf-part="field"
+        >
+          <span className="bf-todos__field-label">{t('editor.fields.enabled')}</span>
+          <Switch
+            size="small"
+            checked={draft.enabled}
+            aria-label={t('editor.fields.enabled')}
+            onChange={(event) => updateDraft({ enabled: event.currentTarget.checked })}
+          />
+        </div>
+      </div>
+
+      <label
+        className="bf-todos__field bf-todos__field--prompt"
+        data-bf-scene="todos"
+        data-bf-part="field"
+      >
+        <span className="bf-todos__field-label">{t('editor.fields.prompt')}</span>
+        <Textarea
+          value={draft.text}
+          error={validationErrors.text}
+          autoResize
+          showCount
+          maxLength={4000}
+          placeholder={t('editor.placeholders.prompt')}
+          onChange={(event) => {
+            const text = event.currentTarget.value;
+            clearError('text');
+            updateDraft({ text });
+          }}
+          data-testid="todos-editor-prompt"
+        />
+      </label>
+
+      {workspaceOptions.length === 0 ? (
+        <p className="bf-todos__warning" data-bf-scene="todos" data-bf-part="warning">
+          {t('editor.noWorkspace')}
+        </p>
+      ) : null}
+
+      <div className="bf-todos__editor-actions" data-bf-scene="todos" data-bf-part="editorActions">
+        <Button size="small" variant="ghost" onClick={onCancel}>
+          {t('common:nav.scheduledJobs.actions.cancel')}
+        </Button>
+        <Button
+          size="small"
+          variant="primary"
+          onClick={onSave}
+          isLoading={saving}
+          disabled={workspaceOptions.length === 0 || !selectedWorkspaceId}
+          data-testid="todos-editor-save"
+        >
+          {isEditing ? t('editor.actions.save') : t('editor.actions.create')}
+        </Button>
+      </div>
+    </section>
+  );
+};
+
+export default TodoEditor;
diff --git a/src/web-ui/src/app/scenes/todos/components/TodoItemRow.tsx b/src/web-ui/src/app/scenes/todos/components/TodoItemRow.tsx
new file mode 100644
index 0000000000..737d72a1d3
--- /dev/null
+++ b/src/web-ui/src/app/scenes/todos/components/TodoItemRow.tsx
@@ -0,0 +1,176 @@
+/**
+ * One Todo row, shared by the 24-hour list and the calendar day detail.
+ *
+ * A row represents a single occurrence, so the same recurring job can appear on
+ * several rows with different times.
+ */
+
+import React from 'react';
+import { Pencil, Trash2 } from 'lucide-react';
+import { IconButton, Switch } from '@/component-library';
+import { useI18n } from '@/infrastructure/i18n';
+import type { CronJob } from '@/infrastructure/api';
+import type { WorkspaceInfo } from '@/shared/types';
+import {
+  formatCountdown,
+  formatJobTargetLabel,
+  formatScheduleSummary,
+  formatTimeOfDay,
+  resolveJobWorkspaceLabel,
+} from '../todoPresentation';
+
+export interface TodoItemRowProps {
+  job: CronJob;
+  /** Occurrence time, or null for a row in the inactive group. */
+  atMs: number | null;
+  isOverdue?: boolean;
+  isNextRun?: boolean;
+  /** The scheduler is executing this run right now. */
+  isRunning?: boolean;
+  nowMs: number;
+  workspaces: WorkspaceInfo[];
+  /** Replaces the countdown, used for inactive rows ("Paused", "Done"). */
+  statusLabel?: string;
+  isSelected?: boolean;
+  onEdit: (job: CronJob) => void;
+  onDelete: (job: CronJob) => void;
+  onToggleEnabled: (job: CronJob, enabled: boolean) => void;
+}
+
+const TodoItemRow: React.FC<TodoItemRowProps> = ({
+  job,
+  atMs,
+  isOverdue = false,
+  isNextRun = false,
+  isRunning = false,
+  nowMs,
+  workspaces,
+  statusLabel,
+  isSelected = false,
+  onEdit,
+  onDelete,
+  onToggleEnabled,
+}) => {
+  const { t, formatDate } = useI18n(['scenes/todos', 'shared']);
+
+  const timeLabel = atMs != null ? formatTimeOfDay(atMs, formatDate) : null;
+  const relativeLabel = statusLabel
+    ?? (isRunning ? t('shared:statuses.running') : null)
+    ?? (atMs != null ? formatCountdown(atMs, nowMs, t) : null);
+
+  const rowState = [
+    isSelected ? 'selected' : null,
+    isRunning ? 'running' : null,
+    isOverdue ? 'overdue' : null,
+    job.enabled ? null : 'disabled',
+  ].filter(Boolean).join(' ');
+
+  return (
+    <div
+      className={[
+        'bf-todos__row',
+        isRunning ? 'bf-todos__row--running' : '',
+        isOverdue ? 'bf-todos__row--overdue' : '',
+        job.enabled ? '' : 'bf-todos__row--disabled',
+        isSelected ? 'bf-todos__row--selected' : '',
+      ].filter(Boolean).join(' ')}
+      data-bf-scene="todos"
+      data-bf-part="row"
+      data-bf-state={rowState || undefined}
+      data-testid="todos-row"
+      role="group"
+      tabIndex={0}
+      aria-label={`${job.name}${timeLabel ? `, ${timeLabel}` : ''}`}
+      onClick={() => onEdit(job)}
+      onKeyDown={(event) => {
+        if (event.key === 'Enter' || event.key === ' ') {
+          event.preventDefault();
+          onEdit(job);
+        }
+      }}
+    >
+      <div className="bf-todos__row-time" data-bf-scene="todos" data-bf-part="rowTime">
+        <span className="bf-todos__row-clock">{timeLabel ?? '—'}</span>
+        {relativeLabel ? (
+          <span className="bf-todos__row-relative">{relativeLabel}</span>
+        ) : null}
+      </div>
+
+      <div className="bf-todos__row-body" data-bf-scene="todos" data-bf-part="rowBody">
+        <div className="bf-todos__row-title-line">
+          <span className="bf-todos__row-name">{job.name}</span>
+          {isRunning ? (
+            <span
+              className="bf-todos__row-badge bf-todos__row-badge--running"
+              data-bf-scene="todos"
+              data-bf-part="rowBadge"
+            >
+              {t('shared:statuses.running')}
+            </span>
+          ) : isNextRun ? (
+            <span className="bf-todos__row-badge" data-bf-scene="todos" data-bf-part="rowBadge">
+              {t('badges.nextRun')}
+            </span>
+          ) : null}
+          {isOverdue ? (
+            <span
+              className="bf-todos__row-badge bf-todos__row-badge--warn"
+              data-bf-scene="todos"
+              data-bf-part="rowBadge"
+            >
+              {t('badges.overdue')}
+            </span>
+          ) : null}
+        </div>
+        <div className="bf-todos__row-meta">
+          <span>{resolveJobWorkspaceLabel(job, workspaces)}</span>
+          <span className="bf-todos__row-meta-sep" aria-hidden="true">·</span>
+          <span>{formatScheduleSummary(job.schedule, t, formatDate)}</span>
+          <span className="bf-todos__row-meta-sep" aria-hidden="true">·</span>
+          <span>{formatJobTargetLabel(job, t)}</span>
+        </div>
+        {job.state.lastError ? (
+          <p className="bf-todos__row-error" data-bf-scene="todos" data-bf-part="rowError">
+            {job.state.lastError}
+          </p>
+        ) : null}
+      </div>
+
+      <div
+        className="bf-todos__row-actions"
+        data-bf-scene="todos"
+        data-bf-part="rowActions"
+        onClick={(event) => event.stopPropagation()}
+        role="presentation"
+      >
+        <Switch
+          size="small"
+          checked={job.enabled}
+          aria-label={t('actions.toggleEnabled')}
+          onChange={(event) => onToggleEnabled(job, event.currentTarget.checked)}
+        />
+        <IconButton
+          type="button"
+          size="xs"
+          aria-label={t('actions.edit')}
+          tooltip={t('actions.edit')}
+          onClick={() => onEdit(job)}
+        >
+          <Pencil size={13} />
+        </IconButton>
+        <IconButton
+          type="button"
+          size="xs"
+          variant="danger"
+          aria-label={t('actions.delete')}
+          tooltip={t('actions.delete')}
+          onClick={() => onDelete(job)}
+        >
+          <Trash2 size={13} />
+        </IconButton>
+      </div>
+    </div>
+  );
+};
+
+export default TodoItemRow;
diff --git a/src/web-ui/src/app/scenes/todos/cronExpression.ts b/src/web-ui/src/app/scenes/todos/cronExpression.ts
new file mode 100644
index 0000000000..5117c9c605
--- /dev/null
+++ b/src/web-ui/src/app/scenes/todos/cronExpression.ts
@@ -0,0 +1,326 @@
+/**
+ * Cron expression evaluation that mirrors the scheduler's backend semantics.
+ *
+ * The backend evaluates `CronSchedule::Cron` with the Rust `cron` crate, so the
+ * calendar has to agree with it field for field or it would advertise runs that
+ * never happen. The behaviors reproduced here, all of which differ from classic
+ * crontab, are:
+ *
+ *  - Fields are `sec min hour day-of-month month day-of-week year`. A 5-field
+ *    expression is prefixed with a `0` seconds field; 6 and 7 fields are used
+ *    as written.
+ *  - Day-of-week ordinals are 1-7 with Sunday = 1 (Quartz style), so `0` is out
+ *    of range rather than meaning Sunday.
+ *  - Day-of-month and day-of-week are ANDed. Classic crontab ORs them when both
+ *    are restricted; the crate does not.
+ *  - Without an explicit timezone the expression is evaluated in local time.
+ */
+
+/** Inclusive ordinal bounds per field, in canonical 7-field order. */
+const FIELD_BOUNDS = {
+  second: [0, 59],
+  minute: [0, 59],
+  hour: [0, 23],
+  dayOfMonth: [1, 31],
+  month: [1, 12],
+  dayOfWeek: [1, 7],
+  year: [1970, 2100],
+} as const;
+
+type FieldName = keyof typeof FIELD_BOUNDS;
+
+const MONTH_NAMES: Record<string, number> = {
+  jan: 1, january: 1,
+  feb: 2, february: 2,
+  mar: 3, march: 3,
+  apr: 4, april: 4,
+  may: 5,
+  jun: 6, june: 6,
+  jul: 7, july: 7,
+  aug: 8, august: 8,
+  sep: 9, sept: 9, september: 9,
+  oct: 10, october: 10,
+  nov: 11, november: 11,
+  dec: 12, december: 12,
+};
+
+/** Sunday = 1, matching `DaysOfWeek::ordinal_from_name` in the `cron` crate. */
+const DAY_OF_WEEK_NAMES: Record<string, number> = {
+  sun: 1, sunday: 1,
+  mon: 2, monday: 2,
+  tue: 3, tues: 3, tuesday: 3,
+  wed: 4, wednesday: 4,
+  thu: 5, thurs: 5, thursday: 5,
+  fri: 6, friday: 6,
+  sat: 7, saturday: 7,
+};
+
+export interface ParsedCronExpression {
+  seconds: number[];
+  minutes: number[];
+  hours: number[];
+  daysOfMonth: number[];
+  months: number[];
+  daysOfWeek: number[];
+  years: number[] | null;
+}
+
+function namesFor(field: FieldName): Record<string, number> | null {
+  if (field === 'month') return MONTH_NAMES;
+  if (field === 'dayOfWeek') return DAY_OF_WEEK_NAMES;
+  return null;
+}
+
+function parseOrdinal(token: string, field: FieldName): number {
+  const names = namesFor(field);
+  const named = names?.[token.toLowerCase()];
+  if (named !== undefined) return named;
+
+  if (!/^\d+$/.test(token)) {
+    throw new Error(`Invalid ${field} value '${token}'`);
+  }
+  return Number(token);
+}
+
+/** Expands one comma-separated field into the sorted set of ordinals it matches. */
+function parseField(rawField: string, field: FieldName): number[] {
+  const [min, max] = FIELD_BOUNDS[field];
+  const matched = new Set<number>();
+
+  for (const part of rawField.split(',')) {
+    const token = part.trim();
+    if (!token) throw new Error(`Empty ${field} field`);
+
+    const [baseToken, stepToken, ...extra] = token.split('/');
+    if (extra.length > 0) throw new Error(`Invalid ${field} step in '${token}'`);
+
+    let step = 1;
+    if (stepToken !== undefined) {
+      if (!/^\d+$/.test(stepToken) || Number(stepToken) === 0) {
+        throw new Error(`Invalid ${field} step in '${token}'`);
+      }
+      step = Number(stepToken);
+    }
+
+    let rangeStart: number;
+    let rangeEnd: number;
+
+    // `?` is accepted as a synonym for `*` in day fields, as Quartz-style
+    // expressions commonly use it.
+    if (baseToken === '*' || baseToken === '?') {
+      rangeStart = min;
+      rangeEnd = max;
+    } else if (baseToken.includes('-')) {
+      const [startToken, endToken, ...rest] = baseToken.split('-');
+      if (rest.length > 0) throw new Error(`Invalid ${field} range in '${token}'`);
+      rangeStart = parseOrdinal(startToken, field);
+      rangeEnd = parseOrdinal(endToken, field);
+    } else {
+      rangeStart = parseOrdinal(baseToken, field);
+      // A bare point with a step runs from that point to the field maximum.
+      rangeEnd = stepToken !== undefined ? max : rangeStart;
+    }
+
+    if (rangeStart < min || rangeEnd > max || rangeStart > rangeEnd) {
+      throw new Error(`${field} value out of range in '${token}'`);
+    }
+
+    for (let value = rangeStart; value <= rangeEnd; value += step) {
+      matched.add(value);
+    }
+  }
+
+  return [...matched].sort((a, b) => a - b);
+}
+
+/**
+ * Parses a 5, 6, or 7 field expression. Throws on anything the backend would
+ * also reject, so callers can treat a throw as "this job will not run".
+ */
+export function parseCronExpression(expr: string): ParsedCronExpression {
+  const fields = expr.trim().split(/\s+/).filter(Boolean);
+
+  let normalized: string[];
+  if (fields.length === 5) {
+    normalized = ['0', ...fields];
+  } else if (fields.length === 6 || fields.length === 7) {
+    normalized = fields;
+  } else {
+    throw new Error(
+      `Cron expression '${expr}' must contain 5, 6, or 7 fields, found ${fields.length}`,
+    );
+  }
+
+  return {
+    seconds: parseField(normalized[0], 'second'),
+    minutes: parseField(normalized[1], 'minute'),
+    hours: parseField(normalized[2], 'hour'),
+    daysOfMonth: parseField(normalized[3], 'dayOfMonth'),
+    months: parseField(normalized[4], 'month'),
+    daysOfWeek: parseField(normalized[5], 'dayOfWeek'),
+    years: normalized[6] !== undefined ? parseField(normalized[6], 'year') : null,
+  };
+}
+
+/** Wall-clock fields of an instant in the viewer's local zone. */
+interface WallClock {
+  year: number;
+  month: number;
+  day: number;
+  hour: number;
+  minute: number;
+  second: number;
+}
+
+/**
+ * Whether this expression can be expanded in the browser.
+ *
+ * Evaluating a named timezone needs a timezone database, and the only one a
+ * browser exposes is `Intl`, which the i18n contract reserves for the shared
+ * formatting APIs. Rather than approximate — and print run times that never
+ * happen — schedules pinned to an explicit timezone are not expanded here; the
+ * caller falls back to the next run the scheduler itself reports.
+ */
+export function canExpandLocally(tz: string | null | undefined): boolean {
+  return !tz?.trim();
+}
+
+function toWallClock(utcMs: number): WallClock {
+  const local = new Date(utcMs);
+  return {
+    year: local.getFullYear(),
+    month: local.getMonth() + 1,
+    day: local.getDate(),
+    hour: local.getHours(),
+    minute: local.getMinutes(),
+    second: local.getSeconds(),
+  };
+}
+
+/**
+ * Converts local wall-clock fields back to a timestamp.
+ *
+ * Returns null when the wall clock does not exist — a spring-forward gap —
+ * mirroring the backend's `LocalResult::None` skip.
+ */
+function fromWallClock(wall: WallClock): number | null {
+  const local = new Date(
+    wall.year, wall.month - 1, wall.day, wall.hour, wall.minute, wall.second, 0,
+  );
+  // Rolled-over components mean the wall clock does not exist on this date.
+  if (
+    local.getFullYear() !== wall.year
+    || local.getMonth() !== wall.month - 1
+    || local.getDate() !== wall.day
+    || local.getHours() !== wall.hour
+  ) {
+    return null;
+  }
+  return local.getTime();
+}
+
+/** Day of week for a civil date, as a 1-7 ordinal with Sunday = 1. */
+function dayOfWeekOrdinal(year: number, month: number, day: number): number {
+  return new Date(Date.UTC(year, month - 1, day)).getUTCDay() + 1;
+}
+
+function daysInMonth(year: number, month: number): number {
+  return new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+
+export interface CronOccurrenceOptions {
+  /** Exclusive lower bound; only occurrences strictly after this are produced. */
+  afterMs: number;
+  /** Inclusive upper bound. */
+  untilMs: number;
+  /** Safety cap so a per-second expression cannot allocate without bound. */
+  limit: number;
+}
+
+/**
+ * Lists occurrences of a cron expression in `(afterMs, untilMs]`.
+ *
+ * Iterates candidate days rather than stepping second by second, so a month
+ * long window costs at most ~31 day checks plus the matching times on each.
+ *
+ * Returns an empty list for a schedule pinned to an explicit timezone — see
+ * `canExpandLocally`. The expression is still parsed first, so an invalid one
+ * is reported as invalid rather than silently treated as un-expandable.
+ */
+export function cronOccurrencesInRange(
+  expr: string,
+  tz: string | null | undefined,
+  { afterMs, untilMs, limit }: CronOccurrenceOptions,
+): number[] {
+  const parsed = parseCronExpression(expr);
+  if (untilMs <= afterMs || limit <= 0 || !canExpandLocally(tz)) return [];
+
+  const monthSet = new Set(parsed.months);
+  const dayOfMonthSet = new Set(parsed.daysOfMonth);
+  const dayOfWeekSet = new Set(parsed.daysOfWeek);
+  const yearSet = parsed.years ? new Set(parsed.years) : null;
+
+  const occurrences: number[] = [];
+  const startWall = toWallClock(afterMs);
+  const endWall = toWallClock(untilMs);
+
+  let { year, month, day } = startWall;
+
+  // Walk local civil days until past the window's last day.
+  while (
+    year < endWall.year
+    || (year === endWall.year && month < endWall.month)
+    || (year === endWall.year && month === endWall.month && day <= endWall.day)
+  ) {
+    const dayMatches =
+      (yearSet === null || yearSet.has(year))
+      && monthSet.has(month)
+      && dayOfMonthSet.has(day)
+      && dayOfWeekSet.has(dayOfWeekOrdinal(year, month, day));
+
+    if (dayMatches) {
+      for (const hour of parsed.hours) {
+        for (const minute of parsed.minutes) {
+          for (const second of parsed.seconds) {
+            const atMs = fromWallClock({ year, month, day, hour, minute, second });
+            if (atMs === null || atMs <= afterMs) continue;
+            if (atMs > untilMs) continue;
+
+            occurrences.push(atMs);
+            if (occurrences.length >= limit) {
+              return occurrences.sort((a, b) => a - b);
+            }
+          }
+        }
+      }
+    }
+
+    day += 1;
+    if (day > daysInMonth(year, month)) {
+      day = 1;
+      month += 1;
+      if (month > 12) {
+        month = 1;
+        year += 1;
+        if (yearSet && year > Math.max(...yearSet)) break;
+      }
+    }
+  }
+
+  return occurrences.sort((a, b) => a - b);
+}
+
+/** First occurrence strictly after `afterMs`, or null if none within `withinMs`. */
+export function nextCronOccurrence(
+  expr: string,
+  tz: string | null | undefined,
+  afterMs: number,
+  withinMs: number,
+): number | null {
+  const [first] = cronOccurrencesInRange(expr, tz, {
+    afterMs,
+    untilMs: afterMs + withinMs,
+    limit: 1,
+  });
+  return first ?? null;
+}
diff --git a/src/web-ui/src/app/scenes/todos/todoOccurrences.test.ts b/src/web-ui/src/app/scenes/todos/todoOccurrences.test.ts
new file mode 100644
index 0000000000..1b560a65d1
--- /dev/null
+++ b/src/web-ui/src/app/scenes/todos/todoOccurrences.test.ts
@@ -0,0 +1,478 @@
+/**
+ * The Todos calendar is only trustworthy if its occurrence math agrees with the
+ * scheduler. These cases pin the behaviors that differ from classic crontab,
+ * plus the backend cases ported from `service/cron/schedule.rs`.
+ */
+
+import { describe, expect, it } from 'vitest';
+import type { CronJob, CronJobState, CronSchedule } from '@/infrastructure/api';
+import { canExpandLocally, cronOccurrencesInRange, parseCronExpression } from './cronExpression';
+import {
+  DAY_IN_MS,
+  MAX_CALENDAR_OCCURRENCES_PER_JOB_PER_DAY,
+  MAX_LIST_OCCURRENCES_PER_JOB,
+  buildMonthGrid,
+  buildTodoBuckets,
+  groupOccurrencesByDay,
+  localDayKey,
+  scheduleOccurrencesInRange,
+} from './todoOccurrences';
+
+const HOUR_IN_MS = 60 * 60 * 1000;
+const MINUTE_IN_MS = 60 * 1000;
+
+function makeJob(overrides: Partial<CronJob> & { schedule: CronSchedule }): CronJob {
+  const state: CronJobState = {
+    consecutiveFailures: 0,
+    coalescedRunCount: 0,
+    ...overrides.state,
+  };
+  return {
+    id: 'cron_test',
+    name: 'test job',
+    payload: { text: 'hello' },
+    enabled: true,
+    target: {
+      kind: 'workspace',
+      workspace: { workspacePath: '/tmp/workspace' },
+      launch: { agentType: 'agentic' },
+    },
+    createdAtMs: 0,
+    configUpdatedAtMs: 0,
+    updatedAtMs: 0,
+    ...overrides,
+    state,
+  };
+}
+
+/** Local-time timestamp, matching how the backend evaluates a tz-less cron. */
+function localMs(
+  year: number, month: number, day: number,
+  hour = 0, minute = 0, second = 0,
+): number {
+  return new Date(year, month - 1, day, hour, minute, second, 0).getTime();
+}
+
+describe('parseCronExpression', () => {
+  it('prefixes a seconds field onto a 5-field expression', () => {
+    const parsed = parseCronExpression('0 8 * * *');
+    expect(parsed.seconds).toEqual([0]);
+    expect(parsed.minutes).toEqual([0]);
+    expect(parsed.hours).toEqual([8]);
+  });
+
+  it('reads a 6-field expression as starting with seconds', () => {
+    const parsed = parseCronExpression('30 0 8 * * *');
+    expect(parsed.seconds).toEqual([30]);
+    expect(parsed.minutes).toEqual([0]);
+    expect(parsed.hours).toEqual([8]);
+  });
+
+  it('maps day-of-week names onto Sunday=1 ordinals', () => {
+    expect(parseCronExpression('0 8 * * sun').daysOfWeek).toEqual([1]);
+    expect(parseCronExpression('0 8 * * mon').daysOfWeek).toEqual([2]);
+    expect(parseCronExpression('0 8 * * sat').daysOfWeek).toEqual([7]);
+  });
+
+  it('rejects day-of-week 0, which is out of range for the backend', () => {
+    expect(() => parseCronExpression('0 8 * * 0')).toThrow();
+  });
+
+  it('expands steps, ranges and lists', () => {
+    expect(parseCronExpression('*/15 * * * *').minutes).toEqual([0, 15, 30, 45]);
+    expect(parseCronExpression('0 9-17 * * *').hours)
+      .toEqual([9, 10, 11, 12, 13, 14, 15, 16, 17]);
+    expect(parseCronExpression('0 8,12,18 * * *').hours).toEqual([8, 12, 18]);
+    expect(parseCronExpression('0 8 * * mon-fri').daysOfWeek).toEqual([2, 3, 4, 5, 6]);
+  });
+
+  it('rejects an expression with the wrong field count', () => {
+    expect(() => parseCronExpression('8 * *')).toThrow();
+  });
+});
+
+describe('cronOccurrencesInRange', () => {
+  it('lists a daily run once per day', () => {
+    const occurrences = cronOccurrencesInRange('0 8 * * *', null, {
+      afterMs: localMs(2026, 8, 12, 9, 0),
+      untilMs: localMs(2026, 8, 15, 23, 59, 59),
+      limit: 50,
+    });
+
+    expect(occurrences).toEqual([
+      localMs(2026, 8, 13, 8, 0),
+      localMs(2026, 8, 14, 8, 0),
+      localMs(2026, 8, 15, 8, 0),
+    ]);
+  });
+
+  it('ANDs day-of-month and day-of-week instead of ORing them', () => {
+    // 2026-08-14 is a Friday and the only 14th in range; a Monday constraint
+    // must therefore exclude it. Classic crontab would include it.
+    const occurrences = cronOccurrencesInRange('0 8 14 * mon', null, {
+      afterMs: localMs(2026, 8, 1),
+      untilMs: localMs(2026, 8, 31, 23, 59, 59),
+      limit: 50,
+    });
+
+    expect(occurrences).toEqual([]);
+  });
+
+  it('does not expand a schedule pinned to an explicit timezone', () => {
+    // Evaluating a named zone needs a timezone database the i18n contract keeps
+    // behind the shared formatters, so these fall back to the scheduler's own
+    // next run instead of being approximated here.
+    expect(canExpandLocally(null)).toBe(true);
+    expect(canExpandLocally('  ')).toBe(true);
+    expect(canExpandLocally('Asia/Shanghai')).toBe(false);
+
+    expect(
+      cronOccurrencesInRange('0 8 * * *', 'Asia/Shanghai', {
+        afterMs: localMs(2026, 8, 12),
+        untilMs: localMs(2026, 8, 20),
+        limit: 10,
+      }),
+    ).toEqual([]);
+  });
+
+  it('still reports an invalid expression when a timezone is set', () => {
+    expect(() =>
+      cronOccurrencesInRange('nope', 'Asia/Shanghai', {
+        afterMs: localMs(2026, 8, 12),
+        untilMs: localMs(2026, 8, 20),
+        limit: 10,
+      }),
+    ).toThrow();
+  });
+
+  it('excludes the lower bound and includes the upper bound', () => {
+    const at8am = localMs(2026, 8, 13, 8, 0);
+    expect(
+      cronOccurrencesInRange('0 8 * * *', null, {
+        afterMs: at8am,
+        untilMs: at8am,
+        limit: 5,
+      }),
+    ).toEqual([]);
+
+    expect(
+      cronOccurrencesInRange('0 8 * * *', null, {
+        afterMs: at8am - 1,
+        untilMs: at8am,
+        limit: 5,
+      }),
+    ).toEqual([at8am]);
+  });
+
+  it('stops at the limit for a high-frequency expression', () => {
+    const occurrences = cronOccurrencesInRange('* * * * *', null, {
+      afterMs: localMs(2026, 8, 12),
+      untilMs: localMs(2026, 9, 12),
+      limit: 10,
+    });
+
+    expect(occurrences).toHaveLength(10);
+  });
+});
+
+describe('scheduleOccurrencesInRange', () => {
+  it('keeps an interval series aligned to its anchor', () => {
+    // Ported from `every_schedule_keeps_anchor_alignment` in schedule.rs.
+    const occurrences = scheduleOccurrencesInRange(
+      { kind: 'every', everyMs: 60_000, anchorMs: 1_000 },
+      1_000,
+      181_000,
+      301_000,
+    );
+
+    expect(occurrences[0]).toBe(241_000);
+  });
+
+  it('falls back to the creation time when an interval has no anchor', () => {
+    const createdAtMs = localMs(2026, 8, 12, 8, 3);
+    const occurrences = scheduleOccurrencesInRange(
+      { kind: 'every', everyMs: HOUR_IN_MS },
+      createdAtMs,
+      localMs(2026, 8, 12, 10, 0),
+      localMs(2026, 8, 12, 12, 0),
+    );
+
+    expect(occurrences).toEqual([
+      localMs(2026, 8, 12, 10, 3),
+      localMs(2026, 8, 12, 11, 3),
+    ]);
+  });
+
+  it('returns a one-shot run only when it falls inside the range', () => {
+    const schedule: CronSchedule = {
+      kind: 'at',
+      at: new Date(localMs(2026, 8, 13, 9, 0)).toISOString(),
+    };
+
+    expect(
+      scheduleOccurrencesInRange(schedule, 0, localMs(2026, 8, 12), localMs(2026, 8, 14)),
+    ).toEqual([localMs(2026, 8, 13, 9, 0)]);
+
+    expect(
+      scheduleOccurrencesInRange(schedule, 0, localMs(2026, 8, 14), localMs(2026, 8, 15)),
+    ).toEqual([]);
+  });
+
+  it('throws for a zero interval, as the backend rejects it', () => {
+    expect(() =>
+      scheduleOccurrencesInRange({ kind: 'every', everyMs: 0 }, 0, 0, DAY_IN_MS),
+    ).toThrow();
+  });
+});
+
+describe('buildTodoBuckets', () => {
+  const nowMs = localMs(2026, 8, 12, 10, 0);
+  const rangeEndMs = localMs(2026, 8, 31, 23, 59, 59);
+
+  it('splits occurrences at the 24 hour boundary', () => {
+    const job = makeJob({
+      schedule: { kind: 'cron', expr: '0 9 * * *' },
+      state: { consecutiveFailures: 0, coalescedRunCount: 0, nextRunAtMs: localMs(2026, 8, 13, 9, 0) },
+    });
+
+    const { upcoming, later } = buildTodoBuckets([job], { nowMs, rangeEndMs });
+
+    // 09:00 tomorrow is 23h out and lists; every later day goes to the calendar.
+    expect(upcoming.map((o) => o.atMs)).toEqual([localMs(2026, 8, 13, 9, 0)]);
+    expect(later[0].atMs).toBe(localMs(2026, 8, 14, 9, 0));
+    expect(later.every((o) => o.atMs > nowMs + DAY_IN_MS)).toBe(true);
+  });
+
+  it('marks the scheduler-reported run as the next run', () => {
+    const nextRunAtMs = localMs(2026, 8, 12, 14, 0);
+    const job = makeJob({
+      schedule: { kind: 'every', everyMs: 4 * HOUR_IN_MS, anchorMs: localMs(2026, 8, 12, 2, 0) },
+      state: { consecutiveFailures: 0, coalescedRunCount: 0, nextRunAtMs },
+    });
+
+    const { upcoming } = buildTodoBuckets([job], { nowMs, rangeEndMs });
+
+    expect(upcoming[0].atMs).toBe(nextRunAtMs);
+    expect(upcoming[0].isNextRun).toBe(true);
+    expect(upcoming.filter((o) => o.isNextRun)).toHaveLength(1);
+  });
+
+  it('surfaces an overdue pending trigger instead of hiding it', () => {
+    const pendingTriggerAtMs = nowMs - 30 * MINUTE_IN_MS;
+    const job = makeJob({
+      schedule: { kind: 'at', at: new Date(pendingTriggerAtMs).toISOString() },
+      state: { consecutiveFailures: 0, coalescedRunCount: 0, pendingTriggerAtMs },
+    });
+
+    const { upcoming, inactive } = buildTodoBuckets([job], { nowMs, rangeEndMs });
+
+    expect(inactive).toHaveLength(0);
+    expect(upcoming).toHaveLength(1);
+    expect(upcoming[0].isOverdue).toBe(true);
+  });
+
+  it('includes a retry time that sits off the nominal series', () => {
+    const retryAtMs = nowMs + 5 * MINUTE_IN_MS;
+    const job = makeJob({
+      schedule: { kind: 'cron', expr: '0 9 * * *' },
+      state: { consecutiveFailures: 1, coalescedRunCount: 0, retryAtMs },
+    });
+
+    const { upcoming } = buildTodoBuckets([job], { nowMs, rangeEndMs });
+
+    expect(upcoming[0].atMs).toBe(retryAtMs);
+    expect(upcoming[0].isNextRun).toBe(true);
+  });
+
+  it('groups a disabled job as inactive rather than dropping it', () => {
+    const job = makeJob({
+      enabled: false,
+      schedule: { kind: 'cron', expr: '0 9 * * *' },
+    });
+
+    const { upcoming, later, inactive } = buildTodoBuckets([job], { nowMs, rangeEndMs });
+
+    expect(upcoming).toHaveLength(0);
+    expect(later).toHaveLength(0);
+    expect(inactive).toEqual([{ job, reason: 'disabled' }]);
+  });
+
+  it('reports a fired one-shot as completed', () => {
+    const firedAtMs = nowMs - 2 * HOUR_IN_MS;
+    const job = makeJob({
+      schedule: { kind: 'at', at: new Date(firedAtMs).toISOString() },
+      state: {
+        consecutiveFailures: 0,
+        coalescedRunCount: 0,
+        lastEnqueuedAtMs: firedAtMs,
+        lastRunFinishedAtMs: firedAtMs + 1_000,
+        lastRunStatus: 'ok',
+      },
+    });
+
+    const { inactive } = buildTodoBuckets([job], { nowMs, rangeEndMs });
+
+    expect(inactive).toEqual([{ job, reason: 'completed' }]);
+  });
+
+  it('falls back to the scheduler next run for a timezone-pinned schedule', () => {
+    const nextRunAtMs = localMs(2026, 8, 20, 8, 0);
+    const job = makeJob({
+      schedule: { kind: 'cron', expr: '0 8 * * *', tz: 'Asia/Shanghai' },
+      state: { consecutiveFailures: 0, coalescedRunCount: 0, nextRunAtMs },
+    });
+
+    const { later, inactive } = buildTodoBuckets([job], { nowMs, rangeEndMs });
+
+    // Exactly the run the backend reports — no locally invented occurrences.
+    expect(inactive).toHaveLength(0);
+    expect(later.map((o) => o.atMs)).toEqual([nextRunAtMs]);
+    expect(later[0].isNextRun).toBe(true);
+  });
+
+  it('puts near-term runs on the calendar as well as in the list', () => {
+    const job = makeJob({
+      schedule: { kind: 'cron', expr: '0 9 * * *' },
+      state: { consecutiveFailures: 0, coalescedRunCount: 0, nextRunAtMs: localMs(2026, 8, 13, 9, 0) },
+    });
+
+    const { upcoming, later, calendar } = buildTodoBuckets([job], { nowMs, rangeEndMs });
+
+    // The list keeps its 24-hour scope, but the calendar carries the whole
+    // agenda so today's and tomorrow's cells are not mysteriously empty.
+    expect(upcoming).toHaveLength(1);
+    expect(calendar).toHaveLength(upcoming.length + later.length);
+    expect(calendar.map((o) => o.atMs)).toContain(localMs(2026, 8, 13, 9, 0));
+    expect(calendar).toEqual([...calendar].sort((a, b) => a.atMs - b.atMs));
+  });
+
+  it('keeps a finished job off the calendar', () => {
+    const firedAtMs = nowMs - 2 * HOUR_IN_MS;
+    const job = makeJob({
+      schedule: { kind: 'at', at: new Date(firedAtMs).toISOString() },
+      state: {
+        consecutiveFailures: 0,
+        coalescedRunCount: 0,
+        lastEnqueuedAtMs: firedAtMs,
+        lastRunStatus: 'ok',
+      },
+    });
+
+    const { calendar, inactive } = buildTodoBuckets([job], { nowMs, rangeEndMs });
+
+    expect(calendar).toHaveLength(0);
+    expect(inactive[0].reason).toBe('completed');
+  });
+
+  it('marks an in-flight run as running rather than overdue', () => {
+    const pendingTriggerAtMs = nowMs - 10 * MINUTE_IN_MS;
+    const job = makeJob({
+      schedule: { kind: 'every', everyMs: DAY_IN_MS, anchorMs: pendingTriggerAtMs },
+      state: {
+        consecutiveFailures: 0,
+        coalescedRunCount: 0,
+        pendingTriggerAtMs,
+        activeTurnId: 'cronjob_test_1',
+        lastRunStatus: 'running',
+      },
+    });
+
+    const { upcoming } = buildTodoBuckets([job], { nowMs, rangeEndMs });
+    const current = upcoming.find((o) => o.atMs === pendingTriggerAtMs);
+
+    expect(current?.isRunning).toBe(true);
+    expect(current?.isOverdue).toBe(false);
+    // A job past its time but not executing is still genuinely overdue.
+    expect(
+      buildTodoBuckets(
+        [makeJob({
+          schedule: { kind: 'at', at: new Date(pendingTriggerAtMs).toISOString() },
+          state: { consecutiveFailures: 0, coalescedRunCount: 0, pendingTriggerAtMs },
+        })],
+        { nowMs, rangeEndMs },
+      ).upcoming[0].isOverdue,
+    ).toBe(true);
+  });
+
+  it('reports an unparseable expression as invalid with its error', () => {
+    const job = makeJob({ schedule: { kind: 'cron', expr: 'not a cron' } });
+
+    const { inactive } = buildTodoBuckets([job], { nowMs, rangeEndMs });
+
+    expect(inactive).toHaveLength(1);
+    expect(inactive[0].reason).toBe('invalid');
+    expect(inactive[0].error).toBeTruthy();
+  });
+
+  it('caps a high-frequency job in the list instead of flooding it', () => {
+    const job = makeJob({
+      schedule: { kind: 'every', everyMs: 5 * MINUTE_IN_MS, anchorMs: nowMs },
+    });
+
+    const { upcoming } = buildTodoBuckets([job], { nowMs, rangeEndMs });
+
+    // 5 minutes over 24 hours is 288 runs; the row's schedule summary carries
+    // the recurrence, so only the leading few are listed.
+    expect(upcoming).toHaveLength(MAX_LIST_OCCURRENCES_PER_JOB);
+    expect(upcoming.map((o) => o.atMs)).toEqual([
+      nowMs + 5 * MINUTE_IN_MS,
+      nowMs + 10 * MINUTE_IN_MS,
+      nowMs + 15 * MINUTE_IN_MS,
+    ]);
+  });
+
+  it('keeps a high-frequency job visible on every calendar day it runs', () => {
+    const job = makeJob({
+      schedule: { kind: 'every', everyMs: 5 * MINUTE_IN_MS, anchorMs: nowMs },
+    });
+
+    const { later } = buildTodoBuckets([job], { nowMs, rangeEndMs });
+    const days = new Set(later.map((o) => localDayKey(o.atMs)));
+
+    // A single windowed budget would have been spent on the first day alone.
+    expect(days.size).toBeGreaterThan(10);
+    for (const [, dayOccurrences] of groupOccurrencesByDay(later)) {
+      expect(dayOccurrences.length).toBeLessThanOrEqual(
+        MAX_CALENDAR_OCCURRENCES_PER_JOB_PER_DAY,
+      );
+    }
+  });
+
+  it('keeps the 24 hour list complete while the calendar shows a later month', () => {
+    const job = makeJob({
+      schedule: { kind: 'cron', expr: '0 9 * * *' },
+    });
+
+    // Calendar moved back to a past month: rangeEndMs is behind "now".
+    const { upcoming } = buildTodoBuckets([job], {
+      nowMs,
+      rangeEndMs: localMs(2026, 7, 31, 23, 59, 59),
+    });
+
+    expect(upcoming.map((o) => o.atMs)).toEqual([localMs(2026, 8, 13, 9, 0)]);
+  });
+});
+
+describe('calendar helpers', () => {
+  it('builds a six week grid starting on the Sunday before the month', () => {
+    const grid = buildMonthGrid(localMs(2026, 8, 12));
+
+    expect(grid).toHaveLength(42);
+    expect(grid[0].getDay()).toBe(0);
+    expect(localDayKey(grid[0].getTime())).toBe('2026-07-26');
+    expect(grid.some((day) => localDayKey(day.getTime()) === '2026-08-01')).toBe(true);
+    expect(grid.some((day) => localDayKey(day.getTime()) === '2026-08-31')).toBe(true);
+  });
+
+  it('buckets occurrences by local day', () => {
+    const job = makeJob({ schedule: { kind: 'cron', expr: '0 9 * * *' } });
+    const byDay = groupOccurrencesByDay([
+      { job, atMs: localMs(2026, 8, 13, 9, 0), isNextRun: false, isOverdue: false },
+      { job, atMs: localMs(2026, 8, 13, 18, 0), isNextRun: false, isOverdue: false },
+      { job, atMs: localMs(2026, 8, 14, 9, 0), isNextRun: false, isOverdue: false },
+    ]);
+
+    expect(byDay.get('2026-08-13')).toHaveLength(2);
+    expect(byDay.get('2026-08-14')).toHaveLength(1);
+  });
+});
diff --git a/src/web-ui/src/app/scenes/todos/todoOccurrences.ts b/src/web-ui/src/app/scenes/todos/todoOccurrences.ts
new file mode 100644
index 0000000000..b77f9bcb65
--- /dev/null
+++ b/src/web-ui/src/app/scenes/todos/todoOccurrences.ts
@@ -0,0 +1,366 @@
+/**
+ * Turns scheduled jobs into dated occurrences and splits them into the two
+ * tiers the Todos scene renders: a list for everything due within 24 hours and
+ * a calendar for everything further out.
+ *
+ * Occurrence times are derived the same way the backend derives them, so the
+ * panel never advertises a run the scheduler will not perform. Cron semantics
+ * live in `cronExpression.ts`; `at` and `every` are handled here.
+ */
+
+import type { CronJob, CronSchedule } from '@/infrastructure/api';
+import { getNextExecutionAtMs } from '@/app/components/scheduled-jobs/scheduledJobDraft';
+import { cronOccurrencesInRange } from './cronExpression';
+
+export const DAY_IN_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Per-job caps that keep a high-frequency schedule from swamping either tier.
+ *
+ * A five-minute Todo fires 288 times a day, which is neither readable as a list
+ * nor useful as calendar chips. Each tier takes only the leading runs it can
+ * show; the row's schedule summary ("Every 5 minutes") is what tells the reader
+ * it keeps going. The calendar budget is per day rather than per month so a
+ * frequent job still marks every day it runs instead of exhausting its budget
+ * in the first few hours.
+ */
+export const MAX_LIST_OCCURRENCES_PER_JOB = 3;
+export const MAX_CALENDAR_OCCURRENCES_PER_JOB_PER_DAY = 4;
+
+/** Default cap for a single `scheduleOccurrencesInRange` call. */
+export const MAX_OCCURRENCES_PER_JOB = 200;
+
+export interface TodoOccurrence {
+  job: CronJob;
+  /** When this run fires. */
+  atMs: number;
+  /** True when the scheduler has this exact run queued as its next action. */
+  isNextRun: boolean;
+  /** True when the run time has passed and the job is not currently running. */
+  isOverdue: boolean;
+  /** True while the scheduler is executing this run. */
+  isRunning: boolean;
+}
+
+/**
+ * Why a job has nothing upcoming — drives the "no upcoming run" group so a
+ * paused or finished job stays reachable instead of vanishing from the panel.
+ */
+export type InactiveReason = 'disabled' | 'completed' | 'invalid';
+
+export interface InactiveTodo {
+  job: CronJob;
+  reason: InactiveReason;
+  /** Parse/validation failure text, when `reason` is `invalid`. */
+  error?: string;
+}
+
+export interface TodoBuckets {
+  /** Due within 24 hours (including overdue and running), ascending. */
+  upcoming: TodoOccurrence[];
+  /** More than 24 hours out, ascending. */
+  later: TodoOccurrence[];
+  /**
+   * Everything still scheduled, near-term included, for the calendar tier.
+   *
+   * The calendar shows the whole agenda rather than only the far half: a run
+   * happening today is exactly what someone opening a calendar expects to see.
+   * Only jobs with nothing left to run stay out of it.
+   */
+  calendar: TodoOccurrence[];
+  /** Jobs with no upcoming run at all. */
+  inactive: InactiveTodo[];
+}
+
+/**
+ * Whether the scheduler is executing this job right now.
+ *
+ * A running job keeps its pending trigger timestamp in the past until the turn
+ * finishes, so without this check an in-flight run reads as overdue.
+ */
+export function isJobRunning(job: CronJob): boolean {
+  return job.state.activeTurnId != null
+    || job.state.lastRunStatus === 'running'
+    || job.state.lastRunStatus === 'queued';
+}
+
+export interface BuildTodoBucketsOptions {
+  nowMs: number;
+  /** End of the calendar window, normally the last day of the visible month. */
+  rangeEndMs: number;
+  /** Boundary between the list tier and the calendar tier. */
+  listWindowMs?: number;
+}
+
+function everyOccurrencesInRange(
+  everyMs: number,
+  anchorMs: number,
+  afterMs: number,
+  untilMs: number,
+  limit: number,
+): number[] {
+  if (!Number.isFinite(everyMs) || everyMs <= 0) return [];
+
+  // Mirrors compute_every_next_run_ms: the series is anchored, not relative to
+  // "now", so a job created at 08:03 with a 1h interval fires at :03.
+  let first: number;
+  if (anchorMs > afterMs) {
+    first = anchorMs;
+  } else {
+    const steps = Math.floor((afterMs - anchorMs) / everyMs) + 1;
+    first = anchorMs + steps * everyMs;
+  }
+
+  const occurrences: number[] = [];
+  for (let atMs = first; atMs <= untilMs && occurrences.length < limit; atMs += everyMs) {
+    occurrences.push(atMs);
+  }
+  return occurrences;
+}
+
+/**
+ * Lists the runs a schedule produces in `(afterMs, untilMs]`.
+ *
+ * Throws only for schedules the backend would also reject; callers surface that
+ * as an inactive job rather than dropping it silently.
+ */
+export function scheduleOccurrencesInRange(
+  schedule: CronSchedule,
+  createdAtMs: number,
+  afterMs: number,
+  untilMs: number,
+  limit = MAX_OCCURRENCES_PER_JOB,
+): number[] {
+  if (schedule.kind === 'at') {
+    const atMs = new Date(schedule.at).getTime();
+    if (!Number.isFinite(atMs)) {
+      throw new Error(`Invalid ISO-8601 timestamp '${schedule.at}'`);
+    }
+    return atMs > afterMs && atMs <= untilMs ? [atMs] : [];
+  }
+
+  if (schedule.kind === 'every') {
+    if (!Number.isFinite(schedule.everyMs) || schedule.everyMs <= 0) {
+      throw new Error('Recurring schedule everyMs must be greater than 0');
+    }
+    return everyOccurrencesInRange(
+      schedule.everyMs,
+      schedule.anchorMs ?? createdAtMs,
+      afterMs,
+      untilMs,
+      limit,
+    );
+  }
+
+  return cronOccurrencesInRange(schedule.expr, schedule.tz, {
+    afterMs,
+    untilMs,
+    limit,
+  });
+}
+
+/**
+ * Expands the calendar tier one local day at a time.
+ *
+ * Budgeting per day rather than across the whole window keeps a frequent job
+ * visible on every day it runs; a single windowed call would spend the entire
+ * budget on the first day and leave the rest of the month looking empty.
+ */
+function expandCalendarOccurrences(
+  job: CronJob,
+  fromMs: number,
+  untilMs: number,
+): number[] {
+  if (untilMs <= fromMs) return [];
+
+  const occurrences: number[] = [];
+  const cursor = new Date(fromMs);
+  const lastDay = new Date(untilMs);
+
+  // Start at the day containing `fromMs`; its earlier hours are excluded by the
+  // exclusive lower bound below.
+  cursor.setHours(0, 0, 0, 0);
+  lastDay.setHours(0, 0, 0, 0);
+
+  while (cursor.getTime() <= lastDay.getTime()) {
+    const dayStart = cursor.getTime();
+    const dayEnd = new Date(
+      cursor.getFullYear(), cursor.getMonth(), cursor.getDate(), 23, 59, 59, 999,
+    ).getTime();
+
+    occurrences.push(...scheduleOccurrencesInRange(
+      job.schedule,
+      job.createdAtMs,
+      Math.max(dayStart - 1, fromMs),
+      Math.min(dayEnd, untilMs),
+      MAX_CALENDAR_OCCURRENCES_PER_JOB_PER_DAY,
+    ));
+
+    cursor.setDate(cursor.getDate() + 1);
+  }
+
+  return occurrences;
+}
+
+/**
+ * A one-shot job whose run already happened is finished, not broken.
+ *
+ * The backend clears `nextRunAtMs` once it enqueues a one-shot run, so the
+ * absence of a next run plus a recorded run is what marks it complete.
+ */
+function hasCompletedOneShot(job: CronJob): boolean {
+  if (job.schedule.kind !== 'at') return false;
+  return (
+    job.state.lastEnqueuedAtMs != null
+    || job.state.lastRunFinishedAtMs != null
+    || job.state.lastRunStartedAtMs != null
+  );
+}
+
+/**
+ * Groups every job into the list tier, the calendar tier, or the inactive
+ * group. `rangeEndMs` bounds calendar expansion; the list tier always covers
+ * the full 24-hour window even when the calendar is showing a later month.
+ */
+export function buildTodoBuckets(
+  jobs: CronJob[],
+  { nowMs, rangeEndMs, listWindowMs = DAY_IN_MS }: BuildTodoBucketsOptions,
+): TodoBuckets {
+  const upcoming: TodoOccurrence[] = [];
+  const later: TodoOccurrence[] = [];
+  const inactive: InactiveTodo[] = [];
+
+  const listBoundaryMs = nowMs + listWindowMs;
+  const expansionEndMs = Math.max(rangeEndMs, listBoundaryMs);
+
+  for (const job of jobs) {
+    if (!job.enabled) {
+      inactive.push({ job, reason: 'disabled' });
+      continue;
+    }
+
+    const scheduledAtMs = getNextExecutionAtMs(job);
+
+    let occurrenceTimes: number[];
+    try {
+      // Expand from just before the scheduler's own next run when that is in
+      // the past, so an overdue or retrying run still shows up.
+      const expandAfterMs = scheduledAtMs != null
+        ? Math.min(scheduledAtMs - 1, nowMs)
+        : nowMs;
+
+      occurrenceTimes = [
+        ...scheduleOccurrencesInRange(
+          job.schedule,
+          job.createdAtMs,
+          expandAfterMs,
+          listBoundaryMs,
+          MAX_LIST_OCCURRENCES_PER_JOB,
+        ),
+        ...expandCalendarOccurrences(job, listBoundaryMs, expansionEndMs),
+      ];
+    } catch (error) {
+      inactive.push({
+        job,
+        reason: 'invalid',
+        error: error instanceof Error ? error.message : String(error),
+      });
+      continue;
+    }
+
+    // A one-shot that already ran expands to nothing; report it as finished
+    // rather than as a job with an unexplained empty schedule.
+    if (occurrenceTimes.length === 0 && scheduledAtMs == null) {
+      inactive.push({
+        job,
+        reason: hasCompletedOneShot(job) ? 'completed' : 'invalid',
+      });
+      continue;
+    }
+
+    // The scheduler's pending trigger wins over a recomputed time: a retry sits
+    // off the nominal series and is still the run that will actually happen.
+    if (scheduledAtMs != null && !occurrenceTimes.includes(scheduledAtMs)) {
+      occurrenceTimes.unshift(scheduledAtMs);
+      occurrenceTimes.sort((a, b) => a - b);
+    }
+
+    const running = isJobRunning(job);
+
+    for (const atMs of occurrenceTimes) {
+      const occurrence: TodoOccurrence = {
+        job,
+        atMs,
+        isNextRun: atMs === scheduledAtMs,
+        // A run that is executing is late only in the clock sense; surfacing it
+        // as overdue misreports healthy work as a problem.
+        isOverdue: atMs < nowMs && !running,
+        isRunning: running && atMs === scheduledAtMs,
+      };
+      if (atMs <= listBoundaryMs) {
+        upcoming.push(occurrence);
+      } else {
+        later.push(occurrence);
+      }
+    }
+  }
+
+  const byTime = (a: TodoOccurrence, b: TodoOccurrence) =>
+    a.atMs - b.atMs || a.job.name.localeCompare(b.job.name);
+
+  upcoming.sort(byTime);
+  later.sort(byTime);
+  inactive.sort((a, b) => b.job.configUpdatedAtMs - a.job.configUpdatedAtMs);
+
+  const calendar = [...upcoming, ...later].sort(byTime);
+
+  return { upcoming, later, calendar, inactive };
+}
+
+/** Local calendar-day key (`YYYY-MM-DD`) used to bucket occurrences into cells. */
+export function localDayKey(timestampMs: number): string {
+  const date = new Date(timestampMs);
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  return `${date.getFullYear()}-${month}-${day}`;
+}
+
+export function groupOccurrencesByDay(
+  occurrences: TodoOccurrence[],
+): Map<string, TodoOccurrence[]> {
+  const byDay = new Map<string, TodoOccurrence[]>();
+  for (const occurrence of occurrences) {
+    const key = localDayKey(occurrence.atMs);
+    const bucket = byDay.get(key);
+    if (bucket) {
+      bucket.push(occurrence);
+    } else {
+      byDay.set(key, [occurrence]);
+    }
+  }
+  return byDay;
+}
+
+/** Six-week grid (42 local days) covering the month `monthAnchorMs` falls in. */
+export function buildMonthGrid(monthAnchorMs: number): Date[] {
+  const anchor = new Date(monthAnchorMs);
+  const firstOfMonth = new Date(anchor.getFullYear(), anchor.getMonth(), 1);
+  const gridStart = new Date(firstOfMonth);
+  gridStart.setDate(firstOfMonth.getDate() - firstOfMonth.getDay());
+
+  return Array.from({ length: 42 }, (_, index) => {
+    const day = new Date(gridStart);
+    day.setDate(gridStart.getDate() + index);
+    return day;
+  });
+}
+
+export function monthRangeMs(monthAnchorMs: number): { startMs: number; endMs: number } {
+  const grid = buildMonthGrid(monthAnchorMs);
+  const first = grid[0];
+  const last = grid[grid.length - 1];
+  return {
+    startMs: new Date(first.getFullYear(), first.getMonth(), first.getDate()).getTime(),
+    endMs: new Date(last.getFullYear(), last.getMonth(), last.getDate(), 23, 59, 59, 999).getTime(),
+  };
+}
diff --git a/src/web-ui/src/app/scenes/todos/todoPresentation.ts b/src/web-ui/src/app/scenes/todos/todoPresentation.ts
new file mode 100644
index 0000000000..fdc41470a2
--- /dev/null
+++ b/src/web-ui/src/app/scenes/todos/todoPresentation.ts
@@ -0,0 +1,144 @@
+/**
+ * Label helpers shared by the Todos list, calendar and editor.
+ *
+ * All user-visible strings come from i18n; these functions only assemble them.
+ */
+
+import type { CronJob, CronSchedule } from '@/infrastructure/api';
+import { formatIntervalValue, splitInterval } from '@/app/components/scheduled-jobs/scheduledJobDraft';
+import { WorkspaceKind, type WorkspaceInfo, isRemoteWorkspace } from '@/shared/types';
+import { normalizePath } from '@/shared/utils/pathUtils';
+
+type Translate = (key: string, params?: Record<string, unknown>) => string;
+type FormatDate = (date: Date | number, options?: Intl.DateTimeFormatOptions) => string;
+
+export function formatTimeOfDay(timestampMs: number, formatDate: FormatDate): string {
+  return formatDate(timestampMs, { hour: '2-digit', minute: '2-digit' });
+}
+
+export function formatDateTime(timestampMs: number, formatDate: FormatDate): string {
+  return formatDate(timestampMs, {
+    month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit',
+  });
+}
+
+/**
+ * "Every 30 minutes" / "Every 1 day", using the largest unit that divides the
+ * interval evenly so a daily job does not read as 1440 minutes.
+ */
+export function formatIntervalSummary(everyMs: number, t: Translate): string {
+  const { value, unit } = splitInterval(everyMs);
+  return t(`schedule.everyUnit.${unit}`, { value: formatIntervalValue(value) });
+}
+
+/** Human summary of the recurrence rule, independent of any single run. */
+export function formatScheduleSummary(
+  schedule: CronSchedule,
+  t: Translate,
+  formatDate: FormatDate,
+): string {
+  switch (schedule.kind) {
+    case 'at':
+      return t('schedule.once', { at: formatDateTime(new Date(schedule.at).getTime(), formatDate) });
+    case 'every':
+      return formatIntervalSummary(schedule.everyMs, t);
+    case 'cron':
+      return schedule.tz
+        ? t('schedule.cronWithTz', { expr: schedule.expr, tz: schedule.tz })
+        : t('schedule.cron', { expr: schedule.expr });
+    default:
+      return '';
+  }
+}
+
+/**
+ * Coarse "in 2 hr" / "in 3 days" text for the list tier.
+ *
+ * Uses explicit keys rather than `Intl.RelativeTimeFormat` so the wording stays
+ * under translator control alongside the rest of the panel.
+ */
+export function formatCountdown(
+  targetMs: number,
+  nowMs: number,
+  t: Translate,
+): string {
+  const deltaMs = targetMs - nowMs;
+  if (deltaMs < 0) return t('relative.overdue');
+
+  const minutes = Math.floor(deltaMs / 60_000);
+  if (minutes < 1) return t('relative.now');
+  if (minutes < 60) return t('relative.inMinutes', { value: minutes });
+
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return t('relative.inHours', { value: hours });
+
+  const days = Math.floor(hours / 24);
+  return days === 1 ? t('relative.inOneDay') : t('relative.inDays', { value: days });
+}
+
+export function resolveWorkspaceDisplayName(workspace: WorkspaceInfo): string {
+  if (workspace.workspaceKind === WorkspaceKind.Assistant) {
+    return workspace.identity?.name?.trim() || workspace.name;
+  }
+  return workspace.name;
+}
+
+/**
+ * Names the workspace a job runs in.
+ *
+ * Jobs outlive the workspace list — a workspace can be closed while its jobs
+ * keep running — so this falls back to the stored path instead of implying the
+ * job is gone.
+ */
+export function resolveJobWorkspaceLabel(
+  job: CronJob,
+  workspaces: WorkspaceInfo[],
+): string {
+  const ref = job.target.workspace;
+  const normalizedJobPath = normalizePath(ref.workspacePath);
+
+  const matched = workspaces.find((workspace) => {
+    if (ref.workspaceId && workspace.id === ref.workspaceId) return true;
+    return normalizePath(workspace.rootPath) === normalizedJobPath;
+  });
+
+  if (matched) return resolveWorkspaceDisplayName(matched);
+
+  const segments = normalizedJobPath.split('/').filter(Boolean);
+  return segments[segments.length - 1] || ref.workspacePath;
+}
+
+/** What the job launches into: a specific session, or a fresh one. */
+export function formatJobTargetLabel(job: CronJob, t: Translate): string {
+  if (job.target.kind === 'session') {
+    return t('target.existingSession');
+  }
+  return t('target.newSession', { agentType: job.target.launch.agentType });
+}
+
+export interface TodoWorkspaceOption {
+  workspace: WorkspaceInfo;
+  value: string;
+  label: string;
+  description: string;
+  remoteConnectionId: string | null;
+  remoteSshHost: string | null;
+}
+
+/** Workspaces a Todo can be created against, assistants first. */
+export function buildWorkspaceOptions(workspaces: WorkspaceInfo[]): TodoWorkspaceOption[] {
+  const ranked = [...workspaces].sort((a, b) => {
+    const aAssistant = a.workspaceKind === WorkspaceKind.Assistant ? 0 : 1;
+    const bAssistant = b.workspaceKind === WorkspaceKind.Assistant ? 0 : 1;
+    return aAssistant - bAssistant;
+  });
+
+  return ranked.map((workspace) => ({
+    workspace,
+    value: workspace.id,
+    label: resolveWorkspaceDisplayName(workspace),
+    description: workspace.rootPath,
+    remoteConnectionId: isRemoteWorkspace(workspace) ? workspace.connectionId ?? null : null,
+    remoteSshHost: isRemoteWorkspace(workspace) ? workspace.sshHost ?? null : null,
+  }));
+}
diff --git a/src/web-ui/src/app/startup/startupPerformanceContract.test.ts b/src/web-ui/src/app/startup/startupPerformanceContract.test.ts
index 02e4b32cc2..516eebb608 100644
--- a/src/web-ui/src/app/startup/startupPerformanceContract.test.ts
+++ b/src/web-ui/src/app/startup/startupPerformanceContract.test.ts
@@ -688,7 +688,7 @@ describe('startup performance contract', () => {
     expect(appLayoutSource).not.toMatch(/import\s+\{\s*NewProjectDialog\s*\}\s+from/);
     expect(appLayoutSource).toContain('const NewProjectDialog = lazy');
     expect(appLayoutSource).toContain("import('../components/NewProjectDialog')");
-    expect(appLayoutSource).toContain('{showNewProjectDialog && (');
+    expect(appLayoutSource).toContain('<PresenceBoundary active={showNewProjectDialog}>');
 
     expect(workspaceItemSource).not.toMatch(/import\s+WorkspaceRelatedPathsDialog\s+from/);
     expect(workspaceItemSource).not.toMatch(/import\s+WorkspaceSessionBatchModal\s+from/);
@@ -696,17 +696,17 @@ describe('startup performance contract', () => {
     expect(workspaceItemSource).toContain("lazy(() => import('./WorkspaceRelatedPathsDialog'))");
     expect(workspaceItemSource).toContain("lazy(() => import('./WorkspaceSessionBatchModal'))");
     expect(workspaceItemSource).toContain("lazy(() => import('@/app/components/scheduled-jobs/ScheduledJobsModal'))");
-    expect(workspaceItemSource).toContain('{relatedPathsDialogOpen && (');
-    expect(workspaceItemSource).toContain('{sessionBatchModalOpen && (');
-    expect(workspaceItemSource).toContain('{scheduledJobsModalOpen && (');
+    expect(workspaceItemSource).toContain('<PresenceBoundary active={relatedPathsDialogOpen}>');
+    expect(workspaceItemSource).toContain('<PresenceBoundary active={sessionBatchModalOpen}>');
+    expect(workspaceItemSource).toContain('<PresenceBoundary active={scheduledJobsModalOpen}>');
 
     expect(sessionsSectionSource).not.toMatch(/import\s+ScheduledJobsModal\s+from/);
     expect(sessionsSectionSource).toContain("lazy(() => import('@/app/components/scheduled-jobs/ScheduledJobsModal'))");
-    expect(sessionsSectionSource).toContain('{scheduledJobsSession && (');
+    expect(sessionsSectionSource).toContain('<PresenceBoundary active={scheduledJobsSession != null}>');
 
     expect(footerActionsSource).not.toMatch(/import\s+\{\s*RemoteConnectDialog\s*\}\s+from/);
     expect(footerActionsSource).toContain("lazy(() => import('../../RemoteConnectDialog'))");
-    expect(footerActionsSource).toContain('{showRemoteConnect && (');
+    expect(footerActionsSource).toContain('<PresenceBoundary active={showRemoteConnect}>');
 
     expect(newProjectDialogSource).not.toMatch(/from\s+['"]@tauri-apps\/plugin-dialog['"]/);
     expect(newProjectDialogSource).not.toContain("await import('@tauri-apps/plugin-dialog')");
diff --git a/src/web-ui/src/app/stores/navSceneStore.ts b/src/web-ui/src/app/stores/navSceneStore.ts
index 6fa8f48753..4db99920c8 100644
--- a/src/web-ui/src/app/stores/navSceneStore.ts
+++ b/src/web-ui/src/app/stores/navSceneStore.ts
@@ -14,11 +14,17 @@
  */
 
 import { create } from 'zustand';
+import {
+  getInteractionMotion,
+  type InteractionMotion,
+} from '@/shared/utils/motionPreference';
 import type { SceneTabId } from '../components/SceneBar/types';
 
 interface NavSceneState {
   showSceneNav: boolean;
   navSceneId: SceneTabId | null;
+  navigationMotion: InteractionMotion;
+  navigationSequence: number;
   openNavScene: (id: SceneTabId) => void;
   closeNavScene: () => void;
   goBack: () => void;
@@ -28,10 +34,30 @@ interface NavSceneState {
 export const useNavSceneStore = create<NavSceneState>((set) => ({
   showSceneNav: false,
   navSceneId: null,
-  openNavScene: (id) => set({ showSceneNav: true, navSceneId: id }),
-  closeNavScene: () => set({ showSceneNav: false, navSceneId: null }),
-  goBack: () => set({ showSceneNav: false }),
-  goForward: () => set({ showSceneNav: true }),
+  navigationMotion: 'instant',
+  navigationSequence: 0,
+  openNavScene: (id) => set(state => ({
+    showSceneNav: true,
+    navSceneId: id,
+    navigationMotion: getInteractionMotion(),
+    navigationSequence: state.navigationSequence + 1,
+  })),
+  closeNavScene: () => set(state => ({
+    showSceneNav: false,
+    navSceneId: null,
+    navigationMotion: getInteractionMotion(),
+    navigationSequence: state.navigationSequence + 1,
+  })),
+  goBack: () => set(state => ({
+    showSceneNav: false,
+    navigationMotion: getInteractionMotion(),
+    navigationSequence: state.navigationSequence + 1,
+  })),
+  goForward: () => set(state => ({
+    showSceneNav: true,
+    navigationMotion: getInteractionMotion(),
+    navigationSequence: state.navigationSequence + 1,
+  })),
 }));
 
 export function selectNavCanGoBack(state: NavSceneState): boolean {
diff --git a/src/web-ui/src/app/stores/sceneStore.test.ts b/src/web-ui/src/app/stores/sceneStore.test.ts
index d5b4249142..680d5c3e91 100644
--- a/src/web-ui/src/app/stores/sceneStore.test.ts
+++ b/src/web-ui/src/app/stores/sceneStore.test.ts
@@ -1,8 +1,10 @@
 import { beforeEach, describe, expect, it } from 'vitest';
+import { recordInteractionModality } from '@/shared/utils/motionPreference';
 import { useSceneStore } from './sceneStore';
 
 describe('sceneStore transition snapshots', () => {
   beforeEach(() => {
+    recordInteractionModality('programmatic');
     useSceneStore.getState().resetForPeerSwitch();
   });
 
@@ -30,4 +32,14 @@ describe('sceneStore transition snapshots', () => {
     expect(useSceneStore.getState().openTabs.map(tab => tab.id)).toContain('welcome');
     expect(useSceneStore.getState().activeTabId).toBe('welcome');
   });
+
+  it('records pointer scene navigation without animating keyboard activation', () => {
+    recordInteractionModality('pointer');
+    useSceneStore.getState().openScene('settings');
+    expect(useSceneStore.getState().navigationMotion).toBe('pointer');
+
+    recordInteractionModality('keyboard');
+    useSceneStore.getState().openScene('session');
+    expect(useSceneStore.getState().navigationMotion).toBe('instant');
+  });
 });
diff --git a/src/web-ui/src/app/stores/sceneStore.ts b/src/web-ui/src/app/stores/sceneStore.ts
index 6453048126..bb90327f19 100644
--- a/src/web-ui/src/app/stores/sceneStore.ts
+++ b/src/web-ui/src/app/stores/sceneStore.ts
@@ -20,6 +20,10 @@ import { create } from 'zustand';
 import { SCENE_TAB_REGISTRY, MAX_OPEN_SCENES, getSceneDef, getMiniAppSceneDef } from '../scenes/registry';
 import { getSceneNav } from '../scenes/nav-registry';
 import { useNavSceneStore } from './navSceneStore';
+import {
+  getInteractionMotion,
+  type InteractionMotion,
+} from '@/shared/utils/motionPreference';
 import type { SceneTab, SceneTabId } from '../components/SceneBar/types';
 
 const AGENT_SCENE_ID: SceneTabId = 'session';
@@ -71,6 +75,9 @@ interface SceneState {
   navHistory: SceneTabId[];
   /** Index of the current position in navHistory. */
   navCursor: number;
+  /** Input source for the latest active-scene change. */
+  navigationMotion: InteractionMotion;
+  navigationSequence: number;
 
   openScene:    (id: SceneTabId) => void;
   activateScene:(id: SceneTabId) => void;
@@ -129,10 +136,13 @@ export const useSceneStore = create<SceneState>((set, get) => ({
   activeTabId: initialActiveId,
   navHistory:  [initialActiveId],
   navCursor:   0,
+  navigationMotion: 'instant',
+  navigationSequence: 0,
 
   openScene: (id) => {
     const state = get();
     const { activeTabId } = state;
+    const navigationMotion = getInteractionMotion();
 
     // Already active — re-sync left nav in case user navigated back to MainNav
     if (id === activeTabId) {
@@ -177,6 +187,8 @@ export const useSceneStore = create<SceneState>((set, get) => ({
         openTabs: ensureAgentFirst(openTabs.map(tab =>
           tab.id === id ? { ...tab, lastUsed: activatedAt } : tab
         )),
+        navigationMotion,
+        navigationSequence: state.navigationSequence + 1,
         ...histUpdate,
       });
       return;
@@ -200,7 +212,13 @@ export const useSceneStore = create<SceneState>((set, get) => ({
     }
 
     next.push(buildSceneTab(id, Date.now()));
-    set({ openTabs: ensureAgentFirst(next), activeTabId: id, ...histUpdate });
+    set({
+      openTabs: ensureAgentFirst(next),
+      activeTabId: id,
+      navigationMotion,
+      navigationSequence: state.navigationSequence + 1,
+      ...histUpdate,
+    });
   },
 
   activateScene: (id) => {
@@ -208,7 +226,8 @@ export const useSceneStore = create<SceneState>((set, get) => ({
   },
 
   closeScene: (id) => {
-    const { openTabs, activeTabId, navHistory, navCursor } = get();
+    const state = get();
+    const { openTabs, activeTabId, navHistory, navCursor } = state;
     if (!isClosableScene(id)) return;
 
     const nextTabs = openTabs.filter(t => t.id !== id);
@@ -216,24 +235,40 @@ export const useSceneStore = create<SceneState>((set, get) => ({
     let newActiveId = activeTabId;
     if (id === activeTabId) {
       if (nextTabs.length === 0) {
-        set({ openTabs: [], activeTabId: '' as SceneTabId, navHistory: [], navCursor: -1 });
+        set({
+          openTabs: [],
+          activeTabId: '' as SceneTabId,
+          navHistory: [],
+          navCursor: -1,
+          navigationMotion: getInteractionMotion(),
+          navigationSequence: state.navigationSequence + 1,
+        });
         return;
       }
       newActiveId = [...nextTabs].sort((a, b) => b.lastUsed - a.lastUsed)[0].id;
     }
 
     const histUpdate = removeFromHistory(navHistory, navCursor, id, newActiveId);
-    set({ openTabs: ensureAgentFirst(nextTabs), activeTabId: newActiveId, ...histUpdate });
+    set({
+      openTabs: ensureAgentFirst(nextTabs),
+      activeTabId: newActiveId,
+      navigationMotion: getInteractionMotion(),
+      navigationSequence: state.navigationSequence + 1,
+      ...histUpdate,
+    });
   },
 
   goBack: () => {
-    const { navHistory, navCursor, openTabs } = get();
+    const state = get();
+    const { navHistory, navCursor, openTabs } = state;
     for (let i = navCursor - 1; i >= 0; i--) {
       const targetId = navHistory[i];
       if (openTabs.some(t => t.id === targetId)) {
         set(state => ({
           navCursor: i,
           activeTabId: targetId,
+          navigationMotion: getInteractionMotion(),
+          navigationSequence: state.navigationSequence + 1,
           openTabs: state.openTabs.map(t =>
             t.id === targetId ? { ...t, lastUsed: Date.now() } : t
           ),
@@ -244,13 +279,16 @@ export const useSceneStore = create<SceneState>((set, get) => ({
   },
 
   goForward: () => {
-    const { navHistory, navCursor, openTabs } = get();
+    const state = get();
+    const { navHistory, navCursor, openTabs } = state;
     for (let i = navCursor + 1; i < navHistory.length; i++) {
       const targetId = navHistory[i];
       if (openTabs.some(t => t.id === targetId)) {
         set(state => ({
           navCursor: i,
           activeTabId: targetId,
+          navigationMotion: getInteractionMotion(),
+          navigationSequence: state.navigationSequence + 1,
           openTabs: state.openTabs.map(t =>
             t.id === targetId ? { ...t, lastUsed: Date.now() } : t
           ),
@@ -261,6 +299,7 @@ export const useSceneStore = create<SceneState>((set, get) => ({
   },
 
   resetForPeerSwitch: () => {
+    const state = get();
     const tabs = buildDefaultTabs();
     const activeTabId: SceneTabId = tabs[0]?.id ?? WELCOME_SCENE_ID;
     set({
@@ -268,6 +307,8 @@ export const useSceneStore = create<SceneState>((set, get) => ({
       activeTabId,
       navHistory: [activeTabId],
       navCursor: 0,
+      navigationMotion: 'instant',
+      navigationSequence: state.navigationSequence + 1,
     });
   },
 }));
diff --git a/src/web-ui/src/app/styles/components/forms.css b/src/web-ui/src/app/styles/components/forms.css
index 565810d9b0..d69d9b0818 100644
--- a/src/web-ui/src/app/styles/components/forms.css
+++ b/src/web-ui/src/app/styles/components/forms.css
@@ -72,7 +72,13 @@
   -webkit-backdrop-filter: var(--bf-appearance-token-blur-subtle);
   box-shadow: var(--bf-appearance-token-shadow-sm);
   
-  transition: all var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard);
+  transition:
+    background-color var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+    border-color var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+    box-shadow var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+    color var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+    opacity var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+    transform var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard);
   outline: none;
 }
 
@@ -354,7 +360,10 @@
   border-radius: var(--bf-appearance-token-size-radius-base);
   color: var(--bf-appearance-token-color-text-secondary);
   cursor: pointer;
-  transition: all var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard);
+  transition:
+    background-color var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+    border-color var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+    color var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard);
 }
 
 .form-file:hover .form-file-label {
@@ -383,7 +392,9 @@
   border-radius: 50%;
   cursor: pointer;
   box-shadow: 0 2px 8px var(--bf-appearance-token-border-accent-soft);
-  transition: all var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
+  transition:
+    box-shadow var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+    transform var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
 }
 
 .form-range::-webkit-slider-thumb:hover {
diff --git a/src/web-ui/src/app/styles/global.scss b/src/web-ui/src/app/styles/global.scss
index 64fc642645..54c2dc02ea 100644
--- a/src/web-ui/src/app/styles/global.scss
+++ b/src/web-ui/src/app/styles/global.scss
@@ -225,12 +225,17 @@ li {
 
 /* Reduced motion mode */
 @media (prefers-reduced-motion: reduce) {
+  :root {
+    scroll-behavior: auto;
+  }
+
   *,
   *::before,
   *::after {
     animation-duration: 0.01ms !important;
     animation-iteration-count: 1 !important;
-    transition-duration: 0.01ms !important;
+    transition-delay: 0ms !important;
+    scroll-behavior: auto !important;
   }
 }
 
diff --git a/src/web-ui/src/app/styles/motion.scss b/src/web-ui/src/app/styles/motion.scss
index 961dbf039c..0d2c4c75cb 100644
--- a/src/web-ui/src/app/styles/motion.scss
+++ b/src/web-ui/src/app/styles/motion.scss
@@ -7,6 +7,7 @@
  *   data-motion="interactive"  press / hover feedback
  *   data-motion="view"         page or panel entrance
  *   data-motion="popup"        menu, popover, or floating surface entrance
+ *   data-motion="presence"     component owns its complete enter/exit lifecycle
  *   data-motion="overlay"      backdrop entrance
  *   data-motion="none"         disable motion for this subtree
  *
@@ -38,8 +39,8 @@
 @keyframes bitfun-motion-popup-enter {
   from {
     opacity: 0;
-    translate: 0 -2px;
-    scale: 0.992;
+    translate: 0 -4px;
+    scale: 0.97;
   }
 
   to {
@@ -52,8 +53,8 @@
 @keyframes bitfun-motion-dialog-enter {
   from {
     opacity: 0;
-    translate: 0 6px;
-    scale: 0.992;
+    translate: 0 8px;
+    scale: 0.985;
   }
 
   to {
@@ -114,25 +115,6 @@
       opacity var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
   }
 
-  @media (hover: hover) and (pointer: fine) {
-    :where(
-      button,
-      input[type='button'],
-      input[type='submit'],
-      input[type='reset'],
-      summary,
-      [role='button'],
-      [role='checkbox'],
-      [role='radio'],
-      [role='switch'],
-      [data-motion='interactive']
-    ):where(
-      :not(:disabled):not([aria-disabled='true']):not([data-motion='none'])
-    ):hover {
-      translate: 0 -1px;
-    }
-  }
-
   :where(
     button,
     input[type='button'],
@@ -148,7 +130,7 @@
     :not(:disabled):not([aria-disabled='true']):not([data-motion='none'])
   ):active {
     translate: 0 0;
-    scale: 0.985;
+    scale: 0.97;
   }
 
   /**
@@ -157,14 +139,14 @@
    * the component already owns a transition or a Suspense fallback.
    */
   :where([data-motion='view']):where(:not([data-motion='none'])) {
-    animation: bitfun-motion-view-enter 140ms cubic-bezier(0.22, 1, 0.36, 1) both;
+    animation: bitfun-motion-view-enter 140ms cubic-bezier(0.23, 1, 0.32, 1) both;
   }
 
   :where(
     [data-scene-transition='exit'],
     [data-motion='view-exit']
   ):where(:not([data-motion='none'])) {
-    animation: bitfun-motion-view-exit 140ms cubic-bezier(0.4, 0, 1, 1) both;
+    animation: bitfun-motion-view-exit 120ms cubic-bezier(0.23, 1, 0.32, 1) both;
   }
 
   /**
@@ -188,9 +170,9 @@
     [class*='__context-menu '],
     [class$='-context-menu'],
     [class*='-context-menu ']
-  ):where(:not([data-motion='none'])) {
+  ):where(:not([data-motion='none']):not([data-motion='presence'])) {
     transform-origin: center top;
-    animation: bitfun-motion-popup-enter 160ms cubic-bezier(0.22, 1, 0.36, 1) both;
+    animation: bitfun-motion-popup-enter 160ms cubic-bezier(0.23, 1, 0.32, 1) both;
   }
 
   /**
@@ -210,7 +192,7 @@
     )
   ) {
     transform-origin: center;
-    animation: bitfun-motion-dialog-enter 220ms cubic-bezier(0.22, 1, 0.36, 1) both;
+    animation: bitfun-motion-dialog-enter 220ms cubic-bezier(0.23, 1, 0.32, 1) both;
   }
 
   :where(
diff --git a/src/web-ui/src/app/styles/utilities/animations.css b/src/web-ui/src/app/styles/utilities/animations.css
index 4c690bda2d..58edca1ecc 100644
--- a/src/web-ui/src/app/styles/utilities/animations.css
+++ b/src/web-ui/src/app/styles/utilities/animations.css
@@ -3,12 +3,12 @@
 /* ========== Core keyframe animations ========== */
 
 /* Base animations */
-@keyframes fadeIn {
+@keyframes bitfun-utility-fade-in {
   from { opacity: 0; }
   to { opacity: 1; }
 }
 
-@keyframes fadeInUp {
+@keyframes bitfun-utility-fade-in-up {
   from {
     opacity: 0;
     transform: translateY(20px);
@@ -19,7 +19,7 @@
   }
 }
 
-@keyframes slideInUp {
+@keyframes bitfun-utility-slide-in-up {
   from {
     opacity: 0;
     transform: translateY(20px);
@@ -30,7 +30,7 @@
   }
 }
 
-@keyframes slideInLeft {
+@keyframes bitfun-utility-slide-in-left {
   from {
     opacity: 0;
     transform: translateX(-20px);
@@ -41,7 +41,7 @@
   }
 }
 
-@keyframes slideInRight {
+@keyframes bitfun-utility-slide-in-right {
   from {
     opacity: 0;
     transform: translateX(20px);
@@ -52,7 +52,7 @@
   }
 }
 
-@keyframes scaleIn {
+@keyframes bitfun-utility-scale-in {
   from {
     opacity: 0;
     transform: scale(0.9);
@@ -64,7 +64,7 @@
 }
 
 /* Interaction animations */
-@keyframes pulse {
+@keyframes bitfun-utility-pulse {
   0%, 100% {
     opacity: 1;
     transform: scale(1);
@@ -75,19 +75,19 @@
   }
 }
 
-@keyframes spin {
+@keyframes bitfun-utility-spin {
   from { transform: rotate(0deg); }
   to { transform: rotate(360deg); }
 }
 
-@keyframes bounce {
+@keyframes bitfun-utility-bounce {
   0%, 20%, 53%, 80%, 100% { transform: translateY(0); }
   40%, 43% { transform: translateY(-8px); }
   70% { transform: translateY(-4px); }
   90% { transform: translateY(-2px); }
 }
 
-@keyframes shake {
+@keyframes bitfun-utility-shake {
   0%, 100% { transform: translateX(0); }
   10%, 30%, 50%, 70%, 90% { transform: translateX(-2px); }
   20%, 40%, 60%, 80% { transform: translateX(2px); }
@@ -96,7 +96,7 @@
 /* ========== Glassmorphism effect animations ========== */
 
 /* Glass shine animation */
-@keyframes glassShine {
+@keyframes bitfun-utility-glass-shine {
   0%, 100% {
     opacity: 0.15;
     transform: translateX(-50%) scaleX(0.8);
@@ -108,13 +108,13 @@
 }
 
 /* Light sweep effect */
-@keyframes sweepGlow {
+@keyframes bitfun-utility-sweep-glow {
   0% { left: -100%; }
   100% { left: 100%; }
 }
 
 /* Mirror reflection shimmer */
-@keyframes shimmer {
+@keyframes bitfun-utility-shimmer {
   0%, 100% {
     left: -100%;
     opacity: 0;
@@ -126,7 +126,7 @@
 }
 
 /* Circle pulse effect - from the prompt box */
-@keyframes questionPulse {
+@keyframes bitfun-utility-question-pulse {
   0%, 100% {
     transform: scale(1);
     opacity: 0.6;
@@ -138,7 +138,7 @@
 }
 
 /* Breathing animation system */
-@keyframes breathingRing1 {
+@keyframes bitfun-utility-breathing-ring-1 {
   0%, 100% {
     transform: scale(1);
     opacity: 0.6;
@@ -149,7 +149,7 @@
   }
 }
 
-@keyframes breathingRing2 {
+@keyframes bitfun-utility-breathing-ring-2 {
   0%, 100% {
     transform: scale(1);
     opacity: 0.4;
@@ -161,7 +161,7 @@
 }
 
 /* Decorative pulse animation */
-@keyframes decorationPulse {
+@keyframes bitfun-utility-decoration-pulse {
   0%, 100% {
     opacity: 0.6;
     transform: scaleY(1);
@@ -175,24 +175,24 @@
 /* ========== Animation utilities ========== */
 
 /* Base animation classes */
-.anim-fade-in { animation: fadeIn var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard); }
-.anim-fade-in-slow { animation: fadeIn var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard); }
-.anim-fade-in-up { animation: fadeInUp var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard); }
-.anim-slide-in-up { animation: slideInUp var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard); }
-.anim-slide-in-left { animation: slideInLeft var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard); }
-.anim-slide-in-right { animation: slideInRight var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard); }
-.anim-scale-in { animation: scaleIn var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard); }
+.anim-fade-in { animation: bitfun-utility-fade-in var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard); }
+.anim-fade-in-slow { animation: bitfun-utility-fade-in var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard); }
+.anim-fade-in-up { animation: bitfun-utility-fade-in-up var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard); }
+.anim-slide-in-up { animation: bitfun-utility-slide-in-up var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard); }
+.anim-slide-in-left { animation: bitfun-utility-slide-in-left var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard); }
+.anim-slide-in-right { animation: bitfun-utility-slide-in-right var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard); }
+.anim-scale-in { animation: bitfun-utility-scale-in var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard); }
 
 /* Interaction animation classes */
-.anim-pulse { animation: pulse 2s ease-in-out infinite; }
-.anim-spin { animation: spin 1s linear infinite; }
-.anim-bounce { animation: bounce 1s ease-in-out infinite; }
-.anim-shake { animation: shake 0.5s ease-in-out infinite; }
+.anim-pulse { animation: bitfun-utility-pulse 2s ease-in-out infinite; }
+.anim-spin { animation: bitfun-utility-spin 1s linear infinite; }
+.anim-bounce { animation: bitfun-utility-bounce 1s ease-in-out infinite; }
+.anim-shake { animation: bitfun-utility-shake 0.5s ease-in-out infinite; }
 
 /* Glass effect animation classes */
-.anim-glass-shine { animation: glassShine 4s ease-in-out infinite; }
-.anim-question-pulse { animation: questionPulse 2s ease-in-out infinite; }
-.anim-decoration-pulse { animation: decorationPulse 3s ease-in-out infinite; }
+.anim-glass-shine { animation: bitfun-utility-glass-shine 4s ease-in-out infinite; }
+.anim-question-pulse { animation: bitfun-utility-question-pulse 2s ease-in-out infinite; }
+.anim-decoration-pulse { animation: bitfun-utility-decoration-pulse 3s ease-in-out infinite; }
 
 /* ========== Hover effect classes ========== */
 
@@ -238,7 +238,7 @@
   z-index: 1;
 }
 .sweep-glow:hover::before {
-  animation: sweepGlow 0.5s ease;
+  animation: bitfun-utility-sweep-glow 0.5s ease;
 }
 
 /* ========== Glassmorphism composite classes ========== */
@@ -255,7 +255,11 @@
 
 /* Enhanced glass effect on hover */
 .glass-hover {
-  transition: all var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard);
+  transition:
+    background-color var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+    border-color var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+    box-shadow var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+    transform var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard);
 }
 .glass-hover:hover {
   background: var(--bf-appearance-token-glass-bg-hover);
@@ -290,7 +294,7 @@
     transparent 100%);
   border-radius: 2px;
   opacity: 0.4;
-  animation: glassShine 4s ease-in-out infinite;
+  animation: bitfun-utility-glass-shine 4s ease-in-out infinite;
   pointer-events: none;
   z-index: 1;
 }
diff --git a/src/web-ui/src/app/styles/utilities/floating-input.css b/src/web-ui/src/app/styles/utilities/floating-input.css
index d2b4c5f2b1..26b41c7562 100644
--- a/src/web-ui/src/app/styles/utilities/floating-input.css
+++ b/src/web-ui/src/app/styles/utilities/floating-input.css
@@ -19,7 +19,15 @@
     inset 0 1px 0 var(--bf-appearance-token-color-overlay-white-08);
   padding: var(--bf-appearance-token-size-gap-3) var(--bf-appearance-token-size-gap-4);
   z-index: 100;
-  transition: all var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard);
+  transition:
+    background-color var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+    border-color var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+    border-radius var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+    box-shadow var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+    opacity var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+    padding var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+    transform var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+    width var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard);
   opacity: 0.6; /* Overall opacity when inactive */
   display: flex;
   align-items: center;
@@ -80,7 +88,11 @@
   cursor: pointer;
   padding: var(--bf-appearance-token-size-gap-2);
   border-radius: var(--bf-appearance-token-size-radius-sm);
-  transition: all var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
+  transition:
+    background-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+    color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+    opacity var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+    transform var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
   display: flex;
   align-items: center;
   justify-content: center;
diff --git a/src/web-ui/src/app/styles/utilities/index.css b/src/web-ui/src/app/styles/utilities/index.css
index e3782cafd8..539d24bbb8 100644
--- a/src/web-ui/src/app/styles/utilities/index.css
+++ b/src/web-ui/src/app/styles/utilities/index.css
@@ -286,7 +286,13 @@
   backdrop-filter: blur(8px) saturate(1.1);
   -webkit-backdrop-filter: blur(8px) saturate(1.1);
   box-shadow: var(--bf-appearance-token-shadow-base);
-  transition: all var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard);
+  transition:
+    background-color var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+    border-color var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+    box-shadow var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+    color var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+    opacity var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+    transform var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard);
 }
 
 .glass-input {
@@ -296,7 +302,13 @@
   backdrop-filter: var(--bf-appearance-token-blur-subtle);
   -webkit-backdrop-filter: var(--bf-appearance-token-blur-subtle);
   box-shadow: var(--bf-appearance-token-shadow-sm);
-  transition: all var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard);
+  transition:
+    background-color var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+    border-color var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+    box-shadow var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+    color var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+    opacity var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+    transform var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard);
 }
 
 /* ========== Responsive utilities ========== */
diff --git a/src/web-ui/src/app/styles/utilities/resizer.css b/src/web-ui/src/app/styles/utilities/resizer.css
index 10312da20a..541ae7a2af 100644
--- a/src/web-ui/src/app/styles/utilities/resizer.css
+++ b/src/web-ui/src/app/styles/utilities/resizer.css
@@ -10,17 +10,17 @@
 
 .u-panel-resizer {
   width: 2px;
-  background: linear-gradient(180deg,
-    color-mix(in srgb, var(--bf-appearance-token-color-static-white) 1%, transparent) 0%,
-    var(--bf-appearance-token-color-overlay-white-04) 50%,
-    color-mix(in srgb, var(--bf-appearance-token-color-static-white) 1%, transparent) 100%);
+  background-color: var(--bf-appearance-token-color-overlay-white-04);
   cursor: col-resize;
   position: relative;
   z-index: 0;
   display: flex;
   align-items: center;
   justify-content: center;
-  transition: all var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard);
+  transition:
+    background-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+    opacity var(--bf-appearance-token-motion-fast) ease,
+    transform var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
   border: none;
   flex-shrink: 0;
   opacity: 0.2;
@@ -28,30 +28,14 @@
   overflow: hidden;
 }
 
-.u-panel-resizer:hover {
-  background: linear-gradient(180deg,
-    var(--bf-appearance-token-color-accent-100) 0%,
-    color-mix(in srgb, var(--bf-appearance-token-color-purple-500) 12%, transparent) 50%,
-    var(--bf-appearance-token-color-accent-100) 100%);
-  opacity: 0.4;
-  box-shadow:
-    0 0 6px color-mix(in srgb, var(--bf-appearance-token-color-accent-500) 5%, transparent),
-    0 0 12px color-mix(in srgb, var(--bf-appearance-token-color-purple-500) 8%, transparent),
-    inset 0 0 3px var(--bf-appearance-token-color-overlay-white-04);
-  transform: scaleY(1.02);
-}
-
 .u-panel-resizer.dragging {
-  background: linear-gradient(180deg,
-    color-mix(in srgb, var(--bf-appearance-token-color-accent-500) 30%, transparent) 0%,
-    color-mix(in srgb, var(--bf-appearance-token-color-purple-500) 50%, transparent) 50%,
-    color-mix(in srgb, var(--bf-appearance-token-color-accent-500) 30%, transparent) 100%);
+  background-color: color-mix(in srgb, var(--bf-appearance-token-color-purple-500) 50%, transparent);
   opacity: 0.8;
   box-shadow:
     0 0 12px color-mix(in srgb, var(--bf-appearance-token-color-accent-500) 20%, transparent),
     0 0 24px var(--bf-appearance-token-color-purple-200),
     inset 0 0 6px var(--bf-appearance-token-color-overlay-white-08);
-  transform: scaleY(1.15);
+  transform: scaleX(2);
 }
 
 .u-resizer-line {
@@ -59,24 +43,35 @@
   height: 20px;
   background: var(--bf-appearance-token-color-overlay-white-12);
   border-radius: var(--bf-appearance-token-size-radius-sm);
-  transition: all var(--bf-appearance-token-motion-base);
+  transition:
+    background-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+    opacity var(--bf-appearance-token-motion-fast) ease,
+    transform var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
   opacity: 0.2;
 }
 
-.u-panel-resizer:hover .u-resizer-line {
-  width: 1px;
-  height: 25px;
-  background: var(--bf-appearance-token-color-overlay-white-20);
-  opacity: 0.4;
-  transform: scaleY(1.3);
-}
-
 .u-panel-resizer.dragging .u-resizer-line {
-  width: 1px;
-  height: 30px;
-  background: color-mix(in srgb, var(--bf-appearance-token-color-static-white) 30%, transparent);
+  background-color: color-mix(in srgb, var(--bf-appearance-token-color-static-white) 30%, transparent);
   opacity: 0.6;
-  transform: scaleY(1.65);
+  transform: scaleY(1.5);
+}
+
+@media (hover: hover) and (pointer: fine) {
+  .u-panel-resizer:not(.dragging):hover {
+    background-color: color-mix(in srgb, var(--bf-appearance-token-color-accent-500) 16%, transparent);
+    opacity: 0.4;
+    box-shadow:
+      0 0 6px color-mix(in srgb, var(--bf-appearance-token-color-accent-500) 5%, transparent),
+      0 0 12px color-mix(in srgb, var(--bf-appearance-token-color-purple-500) 8%, transparent),
+      inset 0 0 3px var(--bf-appearance-token-color-overlay-white-04);
+    transform: scaleX(1.5);
+  }
+
+  .u-panel-resizer:not(.dragging):hover .u-resizer-line {
+    background-color: var(--bf-appearance-token-color-overlay-white-20);
+    opacity: 0.4;
+    transform: scaleY(1.25);
+  }
 }
 
 /* Mobile adjustments */
@@ -85,7 +80,17 @@
     width: 3px;
   }
 
-  .u-panel-resizer:hover {
-    transform: scaleX(1.67) scaleY(1.02);
+  .u-panel-resizer.dragging {
+    transform: scaleX(1.67);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .u-panel-resizer,
+  .u-resizer-line {
+    transition:
+      background-color var(--bf-appearance-token-motion-instant) ease,
+      opacity var(--bf-appearance-token-motion-instant) ease;
+    transform: none;
   }
 }
diff --git a/src/web-ui/src/component-library/components/Avatar/Avatar.scss b/src/web-ui/src/component-library/components/Avatar/Avatar.scss
index 57c146d564..41f5c4fb85 100644
--- a/src/web-ui/src/component-library/components/Avatar/Avatar.scss
+++ b/src/web-ui/src/component-library/components/Avatar/Avatar.scss
@@ -73,7 +73,9 @@
   .bitfun-avatar {
     margin-left: -8px;
     border: 2px solid rgba(var(--bf-appearance-token-color-overlay-slate-rgb), 0.8);
-    transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
+    transition:
+      transform 160ms cubic-bezier(0.23, 1, 0.32, 1),
+      box-shadow 0.2s ease;
 
     &:first-child {
       margin-left: 0;
@@ -93,3 +95,13 @@
     font-size: 12px;
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .bitfun-avatar-group .bitfun-avatar {
+    transition: none;
+
+    &:hover {
+      transform: none;
+    }
+  }
+}
diff --git a/src/web-ui/src/component-library/components/Button/Button.scss b/src/web-ui/src/component-library/components/Button/Button.scss
index e478d81f09..2c9e0dd5c5 100644
--- a/src/web-ui/src/component-library/components/Button/Button.scss
+++ b/src/web-ui/src/component-library/components/Button/Button.scss
@@ -19,7 +19,12 @@
   color: var(--bf-appearance-token-color-text-secondary);
   border: none;
   border-radius: var(--bf-appearance-token-size-radius-sm);
-  transition: all var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
+  transition:
+    background-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+    border-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+    box-shadow var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+    color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+    scale var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
 
   &:focus-visible {
     outline: 2px solid color-mix(in srgb, var(--bf-appearance-token-color-accent-500) 50%, transparent);
@@ -44,13 +49,9 @@
     font-size: var(--bf-appearance-token-font-size-lg);
   }
 
-  &:hover:not(:disabled) {
-    background: var(--bf-appearance-token-element-bg-medium);
-    color: var(--bf-appearance-token-color-text-primary);
-  }
-
   &:active:not(:disabled) {
     background: var(--bf-appearance-token-element-bg-soft);
+    scale: 0.97;
   }
 
   &:disabled,
@@ -80,11 +81,6 @@
     background: var(--bf-appearance-token-element-bg-base);
     color: var(--bf-appearance-token-color-text-secondary);
 
-    &:hover:not(:disabled) {
-      background: var(--bf-appearance-token-element-bg-medium);
-      color: var(--bf-appearance-token-color-text-primary);
-    }
-
     &:active:not(:disabled) {
       background: var(--bf-appearance-token-element-bg-soft);
     }
@@ -94,11 +90,6 @@
     background: transparent;
     color: var(--bf-appearance-token-color-text-secondary);
 
-    &:hover:not(:disabled) {
-      background: var(--bf-appearance-token-element-bg-soft);
-      color: var(--bf-appearance-token-color-text-primary);
-    }
-
     &:active:not(:disabled) {
       background: var(--bf-appearance-token-element-bg-base);
     }
@@ -109,13 +100,6 @@
     color: var(--bf-appearance-token-color-text-secondary);
     border: 1px dashed var(--bf-appearance-token-border-base);
 
-    &:hover:not(:disabled) {
-      background: var(--bf-appearance-token-element-bg-subtle);
-      color: var(--bf-appearance-token-color-text-primary);
-      border-style: solid;
-      border-color: var(--bf-appearance-token-border-medium);
-    }
-
     &:active:not(:disabled) {
       background: var(--bf-appearance-token-element-bg-base);
       border-color: var(--bf-appearance-token-border-strong);
@@ -169,29 +153,20 @@
   outline: none;
   border: none;
   border-radius: var(--bf-appearance-token-size-radius-sm);
-  transition: all var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
+  transition:
+    background-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+    border-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+    box-shadow var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+    color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+    scale var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
 
   background: var(--bf-appearance-token-element-bg-base);
   color: var(--bf-appearance-token-color-text-secondary);
 
-  &:hover {
-    background: var(--bf-appearance-token-element-bg-medium);
-    color: var(--bf-appearance-token-color-text-primary);
-  }
-
   &-ai {
     background: color-mix(in srgb, var(--bf-appearance-token-color-purple-500) 18%, transparent);
     color: var(--bf-appearance-token-color-purple-500);
 
-    &:hover {
-      background: color-mix(in srgb, var(--bf-appearance-token-color-purple-500) 28%, transparent);
-      color: var(--bf-appearance-token-color-static-white);
-
-      svg {
-        color: var(--bf-appearance-token-color-purple-500);
-      }
-    }
-
     &:active {
       background: color-mix(in srgb, var(--bf-appearance-token-color-purple-500) 22%, transparent);
     }
@@ -201,11 +176,6 @@
     background: color-mix(in srgb, var(--bf-appearance-token-color-error) 18%, transparent);
     color: var(--bf-appearance-token-color-error);
 
-    &:hover {
-      background: color-mix(in srgb, var(--bf-appearance-token-color-error) 28%, transparent);
-      color: var(--bf-appearance-token-color-static-white);
-    }
-
     &:active {
       background: color-mix(in srgb, var(--bf-appearance-token-color-error) 22%, transparent);
     }
@@ -215,11 +185,6 @@
     background: color-mix(in srgb, var(--bf-appearance-token-color-success) 18%, transparent);
     color: var(--bf-appearance-token-color-success);
 
-    &:hover {
-      background: color-mix(in srgb, var(--bf-appearance-token-color-success) 28%, transparent);
-      color: var(--bf-appearance-token-color-static-white);
-    }
-
     &:active {
       background: color-mix(in srgb, var(--bf-appearance-token-color-success) 22%, transparent);
     }
@@ -232,7 +197,7 @@
   }
 
   &:active:not(:disabled) {
-    transform: scale(0.98);
+    scale: 0.97;
   }
 }
 
@@ -249,12 +214,14 @@
 
     &-ghost:hover:not(:disabled) {
       background: var(--bf-appearance-token-element-bg-soft);
+      color: var(--bf-appearance-token-color-text-primary);
     }
 
     &-dashed:hover:not(:disabled) {
       background: var(--bf-appearance-token-element-bg-subtle);
       border-style: solid;
       border-color: var(--bf-appearance-token-border-medium);
+      color: var(--bf-appearance-token-color-text-primary);
     }
   }
 
@@ -266,14 +233,21 @@
 
     &-ai:hover:not(:disabled) {
       background: color-mix(in srgb, var(--bf-appearance-token-color-purple-500) 28%, transparent);
+      color: var(--bf-appearance-token-color-static-white);
+
+      svg {
+        color: var(--bf-appearance-token-color-purple-500);
+      }
     }
 
     &-danger:hover:not(:disabled) {
       background: color-mix(in srgb, var(--bf-appearance-token-color-error) 28%, transparent);
+      color: var(--bf-appearance-token-color-static-white);
     }
 
     &-success:hover:not(:disabled) {
       background: color-mix(in srgb, var(--bf-appearance-token-color-success) 28%, transparent);
+      color: var(--bf-appearance-token-color-static-white);
     }
   }
 }
@@ -282,14 +256,19 @@
   .btn,
   .btn-action {
     transition:
-      background-color var(--bf-appearance-token-motion-fast) ease,
-      color var(--bf-appearance-token-motion-fast) ease,
-      border-color var(--bf-appearance-token-motion-fast) ease;
+      background-color var(--bf-appearance-token-motion-instant) ease,
+      color var(--bf-appearance-token-motion-instant) ease,
+      border-color var(--bf-appearance-token-motion-instant) ease,
+      box-shadow var(--bf-appearance-token-motion-instant) ease;
 
     &:active:not(:disabled) {
-      transform: none;
+      scale: none;
     }
   }
+
+  .btn-loading-icon {
+    animation: none;
+  }
 }
 
 @keyframes spin {
diff --git a/src/web-ui/src/component-library/components/Card/Card.scss b/src/web-ui/src/component-library/components/Card/Card.scss
index 44c56f74af..817171e9ce 100644
--- a/src/web-ui/src/component-library/components/Card/Card.scss
+++ b/src/web-ui/src/component-library/components/Card/Card.scss
@@ -16,9 +16,6 @@
   border-radius: var(--bf-appearance-token-size-radius-base);
   color: var(--bf-appearance-token-color-text-secondary);
 
-  transition: all var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard);
-
-
   &--default {
     background: var(--v-card-bg-default);
   }
@@ -51,10 +48,15 @@
 
   &--interactive {
     cursor: pointer;
+    transition:
+      background-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+      border-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+      box-shadow var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+      scale var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
 
     &:active {
       background: var(--v-card-bg-active);
-      transform: scale(0.985);
+      scale: 0.985;
     }
   }
 
@@ -94,6 +96,19 @@
   }
 }
 
+@media (prefers-reduced-motion: reduce) {
+  .v-card--interactive {
+    transition:
+      background-color var(--bf-appearance-token-motion-instant) ease,
+      border-color var(--bf-appearance-token-motion-instant) ease,
+      box-shadow var(--bf-appearance-token-motion-instant) ease;
+
+    &:active {
+      scale: none;
+    }
+  }
+}
+
 :root[data-bf-appearance-mode="light"] .v-card,
 [data-bf-appearance-mode="light"] .v-card {
   --v-card-bg-default: var(--bf-appearance-token-color-overlay-black-08);
diff --git a/src/web-ui/src/component-library/components/CodeEditor/CodeEditor.scss b/src/web-ui/src/component-library/components/CodeEditor/CodeEditor.scss
index a1447ad6b8..3f9c6b4ee6 100644
--- a/src/web-ui/src/component-library/components/CodeEditor/CodeEditor.scss
+++ b/src/web-ui/src/component-library/components/CodeEditor/CodeEditor.scss
@@ -31,7 +31,9 @@
       0 8px 32px rgba(var(--bf-appearance-token-color-static-black-rgb), 0.5),
       0 0 0 1px var(--code-editor-teal-08) inset,
       0 2px 16px rgba(var(--code-editor-blue-rgb), 0.12);
-    transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+    transition:
+      border-color 0.18s ease,
+      box-shadow 0.18s ease;
 
     &:hover {
       border-color: var(--code-editor-blue-40);
@@ -70,14 +72,12 @@
           color: rgba(var(--bf-appearance-token-color-static-white-rgb), 0.35);
           font-weight: 400;
           font-variant-numeric: tabular-nums;
-          transition: color 0.2s ease;
         }
 
         .margin-view-overlays .current-line ~ .line-numbers {
           color: var(--code-editor-blue-100);
           font-weight: 700;
           text-shadow: 0 0 10px rgba(var(--code-editor-blue-rgb), 0.6);
-          transform: scale(1.05);
         }
 
         .margin-view-overlays .line-numbers:hover {
@@ -92,16 +92,6 @@
           );
           border-left: 3px solid rgba(var(--code-editor-blue-rgb), 0.5);
           border-right: none;
-          animation: pulse-highlight 2s ease-in-out infinite;
-        }
-
-        @keyframes pulse-highlight {
-          0%, 100% {
-            opacity: 1;
-          }
-          50% {
-            opacity: 0.85;
-          }
         }
 
         .selected-text {
@@ -118,7 +108,7 @@
               rgba(var(--code-editor-purple-rgb), 0.35)
             ) !important;
             border-radius: 6px;
-            transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+            transition: box-shadow 0.18s ease;
 
             &:hover {
               background: linear-gradient(135deg,
@@ -147,20 +137,6 @@
           box-shadow:
             0 0 16px rgba(var(--code-editor-blue-rgb), 0.9),
             0 0 32px rgba(var(--code-editor-teal-rgb), 0.5);
-          animation: cursor-glow 1.5s ease-in-out infinite;
-        }
-
-        @keyframes cursor-glow {
-          0%, 100% {
-            box-shadow:
-              0 0 16px rgba(var(--code-editor-blue-rgb), 0.9),
-              0 0 32px rgba(var(--code-editor-teal-rgb), 0.5);
-          }
-          50% {
-            box-shadow:
-              0 0 20px rgba(var(--code-editor-blue-rgb), 1),
-              0 0 40px rgba(var(--code-editor-teal-rgb), 0.7);
-          }
         }
 
         .bracket-match {
@@ -168,19 +144,6 @@
           border: 1px solid rgba(var(--code-editor-teal-rgb), 0.7);
           border-radius: 2px;
           box-shadow: 0 0 10px rgba(var(--code-editor-teal-rgb), 0.4);
-          animation: bracket-pulse 0.3s ease-out;
-        }
-
-        @keyframes bracket-pulse {
-          0% {
-            transform: scale(1);
-          }
-          50% {
-            transform: scale(1.05);
-          }
-          100% {
-            transform: scale(1);
-          }
         }
 
         .findMatch {
@@ -188,7 +151,6 @@
           border: 1px solid rgba(var(--code-editor-find-rgb), 0.7);
           border-radius: 2px;
           box-shadow: 0 0 6px rgba(var(--code-editor-find-rgb), 0.3);
-          animation: find-pulse 0.5s ease-out;
         }
 
         .currentFindMatch {
@@ -196,37 +158,15 @@
           border: 1px solid rgba(var(--code-editor-current-find-rgb), 1);
           border-radius: 2px;
           box-shadow: 0 0 10px var(--code-editor-current-find-50);
-          animation: current-find-pulse 1s ease-in-out infinite;
-        }
-
-        @keyframes find-pulse {
-          0% {
-            transform: scale(1);
-            opacity: 0.7;
-          }
-          50% {
-            transform: scale(1.03);
-            opacity: 1;
-          }
-          100% {
-            transform: scale(1);
-            opacity: 1;
-          }
-        }
-
-        @keyframes current-find-pulse {
-          0%, 100% {
-            box-shadow: 0 0 10px var(--code-editor-current-find-50);
-          }
-          50% {
-            box-shadow: 0 0 16px rgba(var(--code-editor-current-find-rgb), 0.8);
-          }
         }
 
         .cldr {
           &.codicon {
             color: rgba(var(--bf-appearance-token-color-static-white-rgb), 0.4);
-            transition: all 0.2s ease;
+            transition:
+              transform 120ms cubic-bezier(0.23, 1, 0.32, 1),
+              color 0.2s ease,
+              text-shadow 0.2s ease;
 
             &:hover {
               color: var(--code-editor-blue-100);
@@ -268,7 +208,6 @@
           }
 
           .monaco-list-row {
-            transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
             border-radius: 4px;
             margin: 2px 4px;
 
@@ -278,7 +217,6 @@
                 var(--code-editor-teal-15) 100%
               );
               box-shadow: 0 0 12px var(--code-editor-blue-30);
-              transform: translateX(4px);
             }
 
             &:hover {
@@ -300,10 +238,10 @@
             0 2px 12px var(--code-editor-blue-25);
           backdrop-filter: blur(20px);
           -webkit-backdrop-filter: blur(20px);
-          animation: hover-fade-in 0.2s ease-out;
+          animation: bitfun-code-editor-hover-in 160ms cubic-bezier(0.23, 1, 0.32, 1);
         }
 
-        @keyframes hover-fade-in {
+        @keyframes bitfun-code-editor-hover-in {
           0% {
             opacity: 0;
             transform: translateY(-4px);
@@ -329,8 +267,6 @@
           -webkit-backdrop-filter: blur(20px);
 
           .signature {
-            transition: all 0.2s ease;
-
             &.focused {
               background: rgba(var(--code-editor-blue-rgb), 0.1);
             }
@@ -409,7 +345,12 @@
     display: flex;
     align-items: center;
     justify-content: center;
-    transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+    transition:
+      transform 160ms cubic-bezier(0.23, 1, 0.32, 1),
+      background-color 0.18s ease,
+      border-color 0.18s ease,
+      color 0.18s ease,
+      box-shadow 0.18s ease;
     backdrop-filter: blur(10px);
     -webkit-backdrop-filter: blur(10px);
 
@@ -445,7 +386,7 @@
     height: 100vh !important;
     z-index: tokens.$z-fullscreen;
     background: var(--bf-appearance-token-color-bg-primary);
-    animation: fullscreen-fade-in 0.3s ease-out;
+    animation: bitfun-code-editor-fullscreen-in 180ms cubic-bezier(0.23, 1, 0.32, 1);
 
     .code-editor__wrapper {
       width: 100%;
@@ -466,7 +407,7 @@
     }
   }
 
-  @keyframes fullscreen-fade-in {
+  @keyframes bitfun-code-editor-fullscreen-in {
     0% {
       opacity: 0;
     }
@@ -475,6 +416,41 @@
     }
   }
 
+  @media (prefers-reduced-motion: reduce) {
+    &--fullscreen {
+      animation: none;
+    }
+
+    &__wrapper {
+      :global {
+        .monaco-hover {
+          animation: none;
+        }
+
+        .cldr.codicon {
+          transition: none;
+
+          &:hover {
+            transform: none;
+          }
+        }
+      }
+    }
+
+    &__fullscreen-btn {
+      transition:
+        background-color 0.18s ease,
+        border-color 0.18s ease,
+        color 0.18s ease,
+        box-shadow 0.18s ease;
+
+      &:hover,
+      &:active {
+        transform: none;
+      }
+    }
+  }
+
   @media (max-width: 768px) {
     .code-editor__wrapper {
       :global {
diff --git a/src/web-ui/src/component-library/components/CubeLogo/CubeLogo.scss b/src/web-ui/src/component-library/components/CubeLogo/CubeLogo.scss
index fd7e00d2d2..1591356154 100644
--- a/src/web-ui/src/component-library/components/CubeLogo/CubeLogo.scss
+++ b/src/web-ui/src/component-library/components/CubeLogo/CubeLogo.scss
@@ -226,3 +226,11 @@
     opacity: 0.5;
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .cube-logo__particle {
+    animation: none;
+    opacity: 0.4;
+    transform: none;
+  }
+}
diff --git a/src/web-ui/src/component-library/components/DotMatrixLoader/DotMatrixLoader.scss b/src/web-ui/src/component-library/components/DotMatrixLoader/DotMatrixLoader.scss
index eba7d6c85e..4250e840b3 100644
--- a/src/web-ui/src/component-library/components/DotMatrixLoader/DotMatrixLoader.scss
+++ b/src/web-ui/src/component-library/components/DotMatrixLoader/DotMatrixLoader.scss
@@ -100,3 +100,10 @@ $matrix-epsilon: 0.0001%;
     animation-name: dot-matrix-choreo-#{$cell};
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .dot-matrix-loader__dot {
+    animation: none;
+    opacity: $matrix-lit;
+  }
+}
diff --git a/src/web-ui/src/component-library/components/FilterPill/FilterPill.scss b/src/web-ui/src/component-library/components/FilterPill/FilterPill.scss
index 7c8cae8906..d40aa23088 100644
--- a/src/web-ui/src/component-library/components/FilterPill/FilterPill.scss
+++ b/src/web-ui/src/component-library/components/FilterPill/FilterPill.scss
@@ -22,7 +22,11 @@
   font-weight: $font-weight-medium;
   font-family: $font-family-sans;
   cursor: pointer;
-  transition: all $motion-base $easing-standard;
+  transition:
+    background-color $motion-fast $easing-standard,
+    border-color $motion-fast $easing-standard,
+    color $motion-fast $easing-standard,
+    scale $motion-fast $easing-standard;
   white-space: nowrap;
 
   &:hover:not(:disabled) {
@@ -67,3 +71,13 @@
     color: var(--bf-appearance-token-color-text-muted);
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .v-filter-pill {
+    transition:
+      background-color $motion-instant ease,
+      border-color $motion-instant ease,
+      color $motion-instant ease;
+    scale: none;
+  }
+}
diff --git a/src/web-ui/src/component-library/components/FlowChatCards/BaseToolCard/BaseToolCard.scss b/src/web-ui/src/component-library/components/FlowChatCards/BaseToolCard/BaseToolCard.scss
index ffe4e388d3..3c8e52dcd8 100644
--- a/src/web-ui/src/component-library/components/FlowChatCards/BaseToolCard/BaseToolCard.scss
+++ b/src/web-ui/src/component-library/components/FlowChatCards/BaseToolCard/BaseToolCard.scss
@@ -141,7 +141,7 @@
   }
 
   &__status-spinner {
-    animation: spin 1s linear infinite;
+    animation: bitfun-base-tool-card-spin 1s linear infinite;
     color: var(--bf-appearance-token-color-accent-500);
   }
 
@@ -296,7 +296,7 @@
 }
 
 
-@keyframes spin {
+@keyframes bitfun-base-tool-card-spin {
   from {
     transform: rotate(0deg);
   }
@@ -305,11 +305,8 @@
   }
 }
 
-@keyframes pulse {
-  0%, 100% {
-    opacity: 1;
-  }
-  50% {
-    opacity: 0.6;
+@media (prefers-reduced-motion: reduce) {
+  .base-tool-card__status-spinner {
+    animation: none;
   }
 }
diff --git a/src/web-ui/src/component-library/components/FlowChatCards/ContextCompressionCard/ContextCompressionCard.scss b/src/web-ui/src/component-library/components/FlowChatCards/ContextCompressionCard/ContextCompressionCard.scss
index 2062328122..33909f8740 100644
--- a/src/web-ui/src/component-library/components/FlowChatCards/ContextCompressionCard/ContextCompressionCard.scss
+++ b/src/web-ui/src/component-library/components/FlowChatCards/ContextCompressionCard/ContextCompressionCard.scss
@@ -25,7 +25,9 @@
   margin: 6px 0;
   padding: 0;
   overflow: hidden;
-  transition: all 0.3s ease;
+  transition:
+    border-color 0.2s ease,
+    box-shadow 0.2s ease;
   box-sizing: border-box;
   position: relative;
   font-family: tokens.$font-family-mono;
@@ -35,7 +37,7 @@
     content: '';
     position: absolute;
     top: 0;
-    left: -100%;
+    left: 0;
     width: 100%;
     height: 100%;
     background: linear-gradient(
@@ -44,13 +46,14 @@
       var(--bf-appearance-token-color-overlay-white-12) 50%,
       transparent 100%
     );
-    transition: left 0.5s ease;
+    transform: translateX(-100%);
+    transition: transform 180ms cubic-bezier(0.23, 1, 0.32, 1);
     pointer-events: none;
     z-index: 1;
   }
 
   &:hover::before {
-    left: 100%;
+    transform: translateX(100%);
   }
 
   &:hover {
@@ -115,7 +118,7 @@
 }
 
 .context-compression-card__status-spinner {
-  animation: spin 1s linear infinite;
+  animation: bitfun-context-compression-card-spin 1s linear infinite;
   color: var(--context-compression-accent);
 }
 
@@ -131,7 +134,7 @@
   color: var(--context-compression-accent);
 }
 
-@keyframes spin {
+@keyframes bitfun-context-compression-card-spin {
   from { transform: rotate(0deg); }
   to { transform: rotate(360deg); }
 }
@@ -207,6 +210,17 @@
 
 .context-compression-card__processing-icon {
   color: var(--context-compression-accent);
-  animation: spin 1s linear infinite;
+  animation: bitfun-context-compression-card-spin 1s linear infinite;
   flex-shrink: 0;
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .context-compression-card::before {
+    transition: none;
+  }
+
+  .context-compression-card__status-spinner,
+  .context-compression-card__processing-icon {
+    animation: none;
+  }
+}
diff --git a/src/web-ui/src/component-library/components/FlowChatCards/SearchCard/SearchCard.scss b/src/web-ui/src/component-library/components/FlowChatCards/SearchCard/SearchCard.scss
index 785947ce4c..cd982d6268 100644
--- a/src/web-ui/src/component-library/components/FlowChatCards/SearchCard/SearchCard.scss
+++ b/src/web-ui/src/component-library/components/FlowChatCards/SearchCard/SearchCard.scss
@@ -10,7 +10,12 @@
 .search-card {
   @include shared.liquid-card-base;
   font-family: tokens.$font-family-mono;
-  transition: all tokens.$motion-base tokens.$easing-standard;
+  transition:
+    background-color tokens.$motion-base tokens.$easing-standard,
+    border-color tokens.$motion-base tokens.$easing-standard,
+    box-shadow tokens.$motion-base tokens.$easing-standard,
+    opacity tokens.$motion-base tokens.$easing-standard,
+    transform tokens.$motion-base tokens.$easing-standard;
 }
 
 
@@ -38,7 +43,7 @@
 
 .search-card__icon {
   flex-shrink: 0;
-  transition: all tokens.$motion-base;
+  transition: color tokens.$motion-base tokens.$easing-standard;
 }
 
 .search-card__action {
@@ -77,7 +82,7 @@
 }
 
 .search-card__status-spinner {
-  animation: spin 1s linear infinite;
+  animation: bitfun-search-card-spin 1s linear infinite;
   color: var(--bf-appearance-token-color-info);
 }
 
@@ -93,7 +98,7 @@
   color: var(--bf-appearance-token-color-warning);
 }
 
-@keyframes spin {
+@keyframes bitfun-search-card-spin {
   from { transform: rotate(0deg); }
   to { transform: rotate(360deg); }
 }
@@ -180,7 +185,10 @@
   font-size: var(--bf-appearance-token-font-size-sm);
   font-weight: tokens.$font-weight-medium;
   cursor: pointer;
-  transition: all tokens.$motion-base tokens.$easing-standard;
+  transition:
+    background-color tokens.$motion-base tokens.$easing-standard,
+    border-color tokens.$motion-base tokens.$easing-standard,
+    color tokens.$motion-base tokens.$easing-standard;
 
   &:hover {
     background: var(--bf-appearance-token-element-bg-soft);
@@ -217,7 +225,7 @@
   gap: tokens.$size-gap-2;
   padding: tokens.$size-gap-2;
   border-radius: tokens.$size-radius-sm;
-  transition: all tokens.$motion-base;
+  transition: background-color tokens.$motion-base tokens.$easing-standard;
 
   &:hover {
     background: var(--bf-appearance-token-element-bg-soft);
@@ -229,6 +237,12 @@
   }
 }
 
+@media (prefers-reduced-motion: reduce) {
+  .search-card__status-spinner {
+    animation: none;
+  }
+}
+
 .search-card__file-name {
   flex: 1;
   font-size: var(--bf-appearance-token-font-size-sm);
diff --git a/src/web-ui/src/component-library/components/FlowChatCards/SnapshotCard/SnapshotCard.scss b/src/web-ui/src/component-library/components/FlowChatCards/SnapshotCard/SnapshotCard.scss
index f601c2de11..ce1e62a162 100644
--- a/src/web-ui/src/component-library/components/FlowChatCards/SnapshotCard/SnapshotCard.scss
+++ b/src/web-ui/src/component-library/components/FlowChatCards/SnapshotCard/SnapshotCard.scss
@@ -11,7 +11,12 @@
 
   @include shared.liquid-card-base;
   font-family: tokens.$font-family-mono;
-  transition: all tokens.$motion-base tokens.$easing-standard;
+  transition:
+    background-color tokens.$motion-base tokens.$easing-standard,
+    border-color tokens.$motion-base tokens.$easing-standard,
+    box-shadow tokens.$motion-base tokens.$easing-standard,
+    opacity tokens.$motion-base tokens.$easing-standard,
+    transform tokens.$motion-base tokens.$easing-standard;
 }
 
 
@@ -65,27 +70,17 @@
 .snapshot-card--compact.snapshot-card--conflict {
   border-color: color-mix(in srgb, var(--bf-appearance-token-git-color-deleted) 60%, transparent);
   background: linear-gradient(135deg, color-mix(in srgb, var(--bf-appearance-token-git-color-deleted) 2%, transparent), color-mix(in srgb, var(--bf-appearance-token-git-color-deleted) 1%, transparent));
-  animation: pulse-warning 2s infinite;
+  box-shadow: 0 0 0 2px color-mix(in srgb, var(--bf-appearance-token-git-color-deleted) 22%, transparent);
 
   &:hover {
     border-color: color-mix(in srgb, var(--bf-appearance-token-git-color-deleted) 80%, transparent);
   }
 }
 
-@keyframes pulse-warning {
-  0%, 100% {
-    box-shadow: 0 0 0 0 color-mix(in srgb, var(--bf-appearance-token-git-color-deleted) 40%, transparent);
-  }
-  50% {
-    box-shadow: 0 0 0 8px color-mix(in srgb, var(--bf-appearance-token-git-color-deleted) 0%, transparent);
-  }
-}
-
-
 .snapshot-card__icon {
   flex-shrink: 0;
   color: var(--snapshot-card-operation-color);
-  transition: all tokens.$motion-base;
+  transition: color tokens.$motion-base tokens.$easing-standard;
 }
 
 .snapshot-card__action {
@@ -141,7 +136,7 @@
 }
 
 .snapshot-card__status-spinner {
-  animation: spin 1s linear infinite;
+  animation: bitfun-snapshot-card-spin 1s linear infinite;
   color: var(--bf-appearance-token-color-info);
 }
 
@@ -157,7 +152,7 @@
   color: var(--bf-appearance-token-color-warning);
 }
 
-@keyframes spin {
+@keyframes bitfun-snapshot-card-spin {
   from { transform: rotate(0deg); }
   to { transform: rotate(360deg); }
 }
@@ -180,7 +175,11 @@
   border-radius: tokens.$size-radius-sm;
   background: transparent;
   cursor: pointer;
-  transition: all tokens.$motion-base tokens.$easing-standard;
+  transition:
+    background-color tokens.$motion-base tokens.$easing-standard,
+    border-color tokens.$motion-base tokens.$easing-standard,
+    color tokens.$motion-base tokens.$easing-standard,
+    opacity tokens.$motion-base tokens.$easing-standard;
   padding: 0;
 
   svg {
@@ -345,7 +344,18 @@
 }
 
 .snapshot-card__processing-icon {
-  animation: spin 1s linear infinite;
+  animation: bitfun-snapshot-card-spin 1s linear infinite;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .snapshot-card__status-spinner,
+  .snapshot-card__processing-icon {
+    animation: none;
+  }
+
+  .snapshot-card--compact:hover {
+    transform: none;
+  }
 }
 
 .snapshot-card__error {
diff --git a/src/web-ui/src/component-library/components/FlowChatCards/TaskCard/TaskCard.scss b/src/web-ui/src/component-library/components/FlowChatCards/TaskCard/TaskCard.scss
index 742ba2c03e..67a54f6553 100644
--- a/src/web-ui/src/component-library/components/FlowChatCards/TaskCard/TaskCard.scss
+++ b/src/web-ui/src/component-library/components/FlowChatCards/TaskCard/TaskCard.scss
@@ -107,7 +107,10 @@
     font-size: 13px;
     font-weight: 500;
     cursor: pointer;
-    transition: all 0.2s ease;
+    transition:
+      background-color 0.2s ease,
+      border-color 0.2s ease,
+      color 0.2s ease;
 
     &:hover {
       background: var(--bf-appearance-token-color-bg-primary);
@@ -164,11 +167,11 @@
   }
 
   &__executing-icon {
-    animation: pulse 2s ease-in-out infinite;
+    animation: bitfun-task-card-pulse 2s ease-in-out infinite;
   }
 }
 
-@keyframes pulse {
+@keyframes bitfun-task-card-pulse {
   0%, 100% {
     opacity: 1;
   }
@@ -176,3 +179,10 @@
     opacity: 0.5;
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .task-card__executing-icon {
+    animation: none;
+    opacity: 1;
+  }
+}
diff --git a/src/web-ui/src/component-library/components/FlowChatCards/TodoCard/TodoCard.scss b/src/web-ui/src/component-library/components/FlowChatCards/TodoCard/TodoCard.scss
index 60216c925e..e11f3cf3c3 100644
--- a/src/web-ui/src/component-library/components/FlowChatCards/TodoCard/TodoCard.scss
+++ b/src/web-ui/src/component-library/components/FlowChatCards/TodoCard/TodoCard.scss
@@ -17,7 +17,9 @@
     border: 1px solid var(--bf-appearance-token-border-base);
     border-radius: 6px;
     font-size: 13px;
-    transition: all 0.2s ease;
+    transition:
+      background-color 0.2s ease,
+      border-color 0.2s ease;
 
     &:hover {
       background: var(--bf-appearance-token-element-bg-hover);
@@ -132,7 +134,7 @@
 
     &--in-progress {
       color: var(--bf-appearance-token-color-warning);
-      animation: pulse 2s ease-in-out infinite;
+      animation: bitfun-todo-card-status-pulse 2s ease-in-out infinite;
     }
 
     &--completed {
@@ -165,7 +167,7 @@
   }
 }
 
-@keyframes pulse {
+@keyframes bitfun-todo-card-status-pulse {
   0%, 100% {
     opacity: 1;
   }
@@ -173,3 +175,10 @@
     opacity: 0.5;
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .todo-card__status-icon--in-progress {
+    animation: none;
+    opacity: 1;
+  }
+}
diff --git a/src/web-ui/src/component-library/components/FlowChatCards/ToolProcessingDots/ToolProcessingDots.scss b/src/web-ui/src/component-library/components/FlowChatCards/ToolProcessingDots/ToolProcessingDots.scss
index bf9bb2eb15..2032ec3d7a 100644
--- a/src/web-ui/src/component-library/components/FlowChatCards/ToolProcessingDots/ToolProcessingDots.scss
+++ b/src/web-ui/src/component-library/components/FlowChatCards/ToolProcessingDots/ToolProcessingDots.scss
@@ -73,3 +73,11 @@
     opacity: 1;
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .bitfun-tool-processing-dots__dot {
+    animation: none;
+    opacity: 0.75;
+    transform: none;
+  }
+}
diff --git a/src/web-ui/src/component-library/components/FlowChatCards/WebSearchCard/WebSearchCard.scss b/src/web-ui/src/component-library/components/FlowChatCards/WebSearchCard/WebSearchCard.scss
index 9f082e0958..6b2dc4ffaf 100644
--- a/src/web-ui/src/component-library/components/FlowChatCards/WebSearchCard/WebSearchCard.scss
+++ b/src/web-ui/src/component-library/components/FlowChatCards/WebSearchCard/WebSearchCard.scss
@@ -17,7 +17,9 @@
     border: 1px solid var(--bf-appearance-token-border-subtle);
     border-radius: 6px;
     font-size: 13px;
-    transition: all 0.2s ease;
+    transition:
+      background-color 0.2s ease,
+      border-color 0.2s ease;
 
     &:hover {
       background: var(--bf-appearance-token-color-bg-secondary);
@@ -105,7 +107,10 @@
     font-size: 13px;
     font-weight: 500;
     cursor: pointer;
-    transition: all 0.2s ease;
+    transition:
+      background-color 0.2s ease,
+      border-color 0.2s ease,
+      color 0.2s ease;
 
     &:hover {
       background: var(--bf-appearance-token-color-bg-primary);
@@ -173,7 +178,9 @@
     padding: 4px;
     border-radius: 3px;
     color: var(--private-web-search-card-identity-color);
-    transition: all 0.2s ease;
+    transition:
+      background-color 0.2s ease,
+      color 0.2s ease;
 
     &:hover {
       background: color-mix(in srgb, var(--private-web-search-card-identity-color) 10%, transparent);
@@ -223,11 +230,11 @@
   }
 
   &__searching-icon {
-    animation: pulse 2s ease-in-out infinite;
+    animation: bitfun-web-search-card-pulse 2s ease-in-out infinite;
   }
 }
 
-@keyframes pulse {
+@keyframes bitfun-web-search-card-pulse {
   0%, 100% {
     opacity: 1;
   }
@@ -235,3 +242,10 @@
     opacity: 0.5;
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .web-search-card__searching-icon {
+    animation: none;
+    opacity: 1;
+  }
+}
diff --git a/src/web-ui/src/component-library/components/FlowChatCards/_shared-styles.scss b/src/web-ui/src/component-library/components/FlowChatCards/_shared-styles.scss
index 8563577144..7312d33cbc 100644
--- a/src/web-ui/src/component-library/components/FlowChatCards/_shared-styles.scss
+++ b/src/web-ui/src/component-library/components/FlowChatCards/_shared-styles.scss
@@ -8,7 +8,12 @@
   background: transparent;
   border: 1px solid var(--bf-appearance-token-color-overlay-white-20);
   border-radius: tokens.$size-radius-lg;
-  transition: all tokens.$motion-base tokens.$easing-standard;
+  transition:
+    background-color tokens.$motion-base tokens.$easing-standard,
+    border-color tokens.$motion-base tokens.$easing-standard,
+    box-shadow tokens.$motion-base tokens.$easing-standard,
+    opacity tokens.$motion-base tokens.$easing-standard,
+    transform tokens.$motion-base tokens.$easing-standard;
   position: relative;
 }
 
@@ -48,11 +53,13 @@
   border: 1px solid var(--bf-appearance-token-color-overlay-white-20);
   border-radius: tokens.$size-radius-base;
   padding: tokens.$size-gap-2;
-  transition: all tokens.$motion-base tokens.$easing-standard;
+  transition:
+    background-color tokens.$motion-base tokens.$easing-standard,
+    border-color tokens.$motion-base tokens.$easing-standard;
 
   svg {
     color: color-mix(in srgb, var(--bf-appearance-token-color-static-white) 75%, transparent);
-    transition: all tokens.$motion-base;
+    transition: color tokens.$motion-base tokens.$easing-standard;
   }
 
   &:hover {
@@ -73,7 +80,11 @@
   font-size: var(--bf-appearance-token-font-size-sm);
   font-weight: tokens.$font-weight-medium;
   cursor: pointer;
-  transition: all tokens.$motion-base tokens.$easing-standard;
+  transition:
+    background-color tokens.$motion-base tokens.$easing-standard,
+    border-color tokens.$motion-base tokens.$easing-standard,
+    color tokens.$motion-base tokens.$easing-standard,
+    opacity tokens.$motion-base tokens.$easing-standard;
 
   @if $variant == 'success' {
     background: var(--bf-appearance-token-color-success-bg);
diff --git a/src/web-ui/src/component-library/components/IconButton/IconButton.scss b/src/web-ui/src/component-library/components/IconButton/IconButton.scss
index 36f7947da9..03727a2fff 100644
--- a/src/web-ui/src/component-library/components/IconButton/IconButton.scss
+++ b/src/web-ui/src/component-library/components/IconButton/IconButton.scss
@@ -12,24 +12,18 @@
   outline: none;
   user-select: none;
   flex-shrink: 0;
-  transform: scale(1);
+  scale: 1;
   transform-origin: center;
   transition:
-    transform var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
-    background var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+    scale var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+    background-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
     color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
 
   background: transparent;
   color: var(--bf-appearance-token-color-text-secondary);
 
-  &:hover:not(:disabled) {
-    transform: scale(1.06);
-    background: var(--bf-appearance-token-color-overlay-white-08);
-    color: var(--bf-appearance-token-color-accent-500);
-  }
-
   &:active:not(:disabled) {
-    transform: scale(1.02);
+    scale: 0.97;
     background: var(--bf-appearance-token-color-overlay-white-08);
   }
 
@@ -88,10 +82,6 @@
     background: color-mix(in srgb, var(--bf-appearance-token-color-accent-500) 20%, transparent);
     color: var(--bf-appearance-token-color-static-white);
 
-    &:hover:not(:disabled) {
-      background: color-mix(in srgb, var(--bf-appearance-token-color-accent-500) 30%, transparent);
-    }
-
     &:active:not(:disabled) {
       background: color-mix(in srgb, var(--bf-appearance-token-color-accent-500) 24%, transparent);
     }
@@ -101,11 +91,6 @@
     background: transparent;
     color: var(--bf-appearance-token-color-text-secondary);
 
-    &:hover:not(:disabled) {
-      background: color-mix(in srgb, var(--bf-appearance-token-color-error) 28%, transparent);
-      color: var(--bf-appearance-token-color-error);
-    }
-
     &:active:not(:disabled) {
       background: color-mix(in srgb, var(--bf-appearance-token-color-error) 22%, transparent);
       color: var(--bf-appearance-token-color-error);
@@ -116,11 +101,6 @@
     background: color-mix(in srgb, var(--bf-appearance-token-color-success) 18%, transparent);
     color: var(--bf-appearance-token-color-success);
 
-    &:hover:not(:disabled) {
-      background: color-mix(in srgb, var(--bf-appearance-token-color-success) 28%, transparent);
-      color: var(--bf-appearance-token-color-static-white);
-    }
-
     &:active:not(:disabled) {
       background: color-mix(in srgb, var(--bf-appearance-token-color-success) 22%, transparent);
     }
@@ -130,11 +110,6 @@
     background: color-mix(in srgb, var(--bf-appearance-token-color-warning) 18%, transparent);
     color: var(--bf-appearance-token-color-warning);
 
-    &:hover:not(:disabled) {
-      background: color-mix(in srgb, var(--bf-appearance-token-color-warning) 28%, transparent);
-      color: var(--bf-appearance-token-color-static-white);
-    }
-
     &:active:not(:disabled) {
       background: color-mix(in srgb, var(--bf-appearance-token-color-warning) 22%, transparent);
     }
@@ -144,11 +119,6 @@
     background: color-mix(in srgb, var(--bf-appearance-token-color-purple-500) 18%, transparent);
     color: var(--bf-appearance-token-color-purple-500);
 
-    &:hover:not(:disabled) {
-      background: color-mix(in srgb, var(--bf-appearance-token-color-purple-500) 28%, transparent);
-      color: var(--bf-appearance-token-color-static-white);
-    }
-
     &:active:not(:disabled) {
       background: color-mix(in srgb, var(--bf-appearance-token-color-purple-500) 22%, transparent);
     }
@@ -210,13 +180,17 @@
 @media (prefers-reduced-motion: reduce) {
   .icon-btn {
     transition:
-      background-color var(--bf-appearance-token-motion-fast) ease,
-      color var(--bf-appearance-token-motion-fast) ease;
+      background-color var(--bf-appearance-token-motion-instant) ease,
+      color var(--bf-appearance-token-motion-instant) ease;
 
     &:active:not(:disabled) {
-      transform: none;
+      scale: none;
     }
   }
+
+  .icon-btn--loading svg {
+    animation: none;
+  }
 }
 
 @keyframes icon-btn-spin {
diff --git a/src/web-ui/src/component-library/components/Input/Input.scss b/src/web-ui/src/component-library/components/Input/Input.scss
index 39be71aa3b..14e5e3f7c2 100644
--- a/src/web-ui/src/component-library/components/Input/Input.scss
+++ b/src/web-ui/src/component-library/components/Input/Input.scss
@@ -107,7 +107,10 @@
   gap: var(--bf-appearance-token-size-gap-2);
   padding: 0 var(--bf-appearance-token-size-gap-3);
   border-radius: 4px;
-  transition: all var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard);
+  transition:
+    background-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+    border-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+    box-shadow var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
   position: relative;
   min-width: 0;
   overflow: hidden;
@@ -188,7 +191,7 @@
   border-radius: 4px;
   transition:
     color var(--bf-appearance-token-motion-fast) ease,
-    transform var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
+    scale var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
 
   &:hover {
     color: var(--bf-appearance-token-color-text-secondary);
@@ -231,7 +234,15 @@
 }
 
 @media (prefers-reduced-motion: reduce) {
+  .bitfun-input-container {
+    transition-duration: var(--bf-appearance-token-motion-instant);
+  }
+
+  .bitfun-input-toggle {
+    transition: color var(--bf-appearance-token-motion-instant) ease;
+  }
+
   .bitfun-input-toggle:active {
-    transform: none;
+    scale: none;
   }
 }
diff --git a/src/web-ui/src/component-library/components/Markdown/Markdown.scss b/src/web-ui/src/component-library/components/Markdown/Markdown.scss
index 10d92534c3..effb433e81 100644
--- a/src/web-ui/src/component-library/components/Markdown/Markdown.scss
+++ b/src/web-ui/src/component-library/components/Markdown/Markdown.scss
@@ -62,7 +62,6 @@
   word-wrap: break-word;
   cursor: text;
   user-select: text;
-  animation: fadeIn var(--bf-appearance-token-motion-base) ease-out;
 }
 
 .markdown-renderer > * {
@@ -666,14 +665,3 @@
   --markdown-code-bg-elevated: color-mix(in srgb, var(--bf-appearance-token-color-bg-primary) 94%, var(--bf-appearance-token-color-static-white) 6%);
   --markdown-pre-border: rgba(var(--bf-appearance-token-color-static-white-rgb), 0.09);
 }
-
-@keyframes fadeIn {
-  from {
-    opacity: 0;
-    transform: translateY(4px);
-  }
-  to {
-    opacity: 1;
-    transform: translateY(0);
-  }
-}
diff --git a/src/web-ui/src/component-library/components/Markdown/MermaidBlock.scss b/src/web-ui/src/component-library/components/Markdown/MermaidBlock.scss
index 412e4ee498..9c7f84ba91 100644
--- a/src/web-ui/src/component-library/components/Markdown/MermaidBlock.scss
+++ b/src/web-ui/src/component-library/components/Markdown/MermaidBlock.scss
@@ -12,7 +12,9 @@
   overflow: hidden;
   background: var(--bf-appearance-token-color-bg-primary);
   border: 1px solid var(--bf-appearance-token-element-bg-base);
-  transition: all 0.3s ease;
+  transition:
+    border-color 0.2s ease,
+    box-shadow 0.2s ease;
 
   &:hover {
     box-shadow:
@@ -30,11 +32,11 @@
     .streaming-cursor {
       display: inline-block;
       color: var(--bf-appearance-token-color-accent-500);
-      animation: blink 1s infinite;
+      animation: bitfun-mermaid-streaming-cursor-blink 1s step-end infinite;
       margin-left: 2px;
     }
 
-    @keyframes blink {
+    @keyframes bitfun-mermaid-streaming-cursor-blink {
       0%, 49% { opacity: 1; }
       50%, 100% { opacity: 0; }
     }
@@ -74,10 +76,10 @@
       margin-bottom: var(--bf-appearance-token-flowchat-card-gap);
 
       .spinning {
-        animation: spin 1s linear infinite;
+        animation: bitfun-mermaid-loading-spin 1s linear infinite;
       }
 
-      @keyframes spin {
+      @keyframes bitfun-mermaid-loading-spin {
         from { transform: rotate(0deg); }
         to { transform: rotate(360deg); }
       }
@@ -91,7 +93,7 @@
       padding: var(--bf-appearance-token-flowchat-card-pad-y) var(--bf-appearance-token-flowchat-card-pad-x);
       background: transparent;
       overflow-x: auto;
-      animation: fadeIn 0.4s ease;
+      animation: bitfun-mermaid-diagram-in 160ms cubic-bezier(0.23, 1, 0.32, 1);
 
       svg {
         display: block;
@@ -100,10 +102,10 @@
         height: auto;
       }
 
-      @keyframes fadeIn {
+      @keyframes bitfun-mermaid-diagram-in {
         from {
           opacity: 0;
-          transform: translateY(10px);
+          transform: translateY(4px);
         }
         to {
           opacity: 1;
@@ -217,7 +219,10 @@
     border-radius: 4px;
     color: var(--bf-appearance-token-color-text-muted);
     cursor: pointer;
-    transition: all 0.15s ease;
+    transition:
+      transform 150ms cubic-bezier(0.23, 1, 0.32, 1),
+      background-color 0.15s ease,
+      color 0.15s ease;
 
     &:hover {
       background: var(--bf-appearance-token-element-bg-medium);
@@ -248,7 +253,11 @@
     color: var(--bf-appearance-token-color-text-secondary);
     font-size: 0.8125rem;
     cursor: pointer;
-    transition: all 0.2s ease;
+    transition:
+      transform 160ms cubic-bezier(0.23, 1, 0.32, 1),
+      background-color 0.2s ease,
+      border-color 0.2s ease,
+      color 0.2s ease;
 
     &:hover {
       background: var(--bf-appearance-token-element-bg-subtle);
@@ -275,6 +284,30 @@
   }
 }
 
+@media (prefers-reduced-motion: reduce) {
+  .mermaid-block {
+    .streaming-cursor,
+    .spinning,
+    .mermaid-block__diagram {
+      animation: none;
+    }
+
+    .streaming-cursor {
+      opacity: 1;
+    }
+
+    .mermaid-icon-btn,
+    .mermaid-action-btn {
+      transition: none;
+    }
+
+    .mermaid-icon-btn:active,
+    .mermaid-action-btn:active {
+      transform: none;
+    }
+  }
+}
+
 .mermaid-block__diagram {
   svg {
     font-family: var(--bf-appearance-token-font-family-sans);
diff --git a/src/web-ui/src/component-library/components/Markdown/ReproductionStepsBlock.scss b/src/web-ui/src/component-library/components/Markdown/ReproductionStepsBlock.scss
index 68c80e16b9..397ac85cd8 100644
--- a/src/web-ui/src/component-library/components/Markdown/ReproductionStepsBlock.scss
+++ b/src/web-ui/src/component-library/components/Markdown/ReproductionStepsBlock.scss
@@ -12,12 +12,14 @@
   border: 1px solid var(--bf-appearance-token-color-warning);
   background: var(--bf-appearance-token-color-bg-scene);
   backdrop-filter: blur(10px);
-  transition: all 0.2s ease;
+  transition:
+    border-color 0.2s ease,
+    box-shadow 0.2s ease;
   overflow: hidden;
   position: relative;
 
 
-  animation: waitingPulse 2s ease-in-out infinite;
+  animation: bitfun-reproduction-steps-waiting-pulse 2s ease-in-out infinite;
 
 
   &:hover:not(.proceeded) {
@@ -134,7 +136,9 @@
   font-weight: 500;
   color: var(--bf-appearance-token-color-text-primary);
   line-height: var(--bf-appearance-token-flowchat-support-line-height);
-  transition: all 0.15s ease;
+  transition:
+    background-color 0.15s ease,
+    border-color 0.15s ease;
 
   &:hover {
     background: var(--bf-appearance-token-element-bg-subtle);
@@ -206,7 +210,12 @@
   font-size: var(--bf-appearance-token-flowchat-font-size-sm);
   font-weight: 600;
   cursor: pointer;
-  transition: all 0.15s ease;
+  transition:
+    transform 150ms cubic-bezier(0.23, 1, 0.32, 1),
+    background-color 0.15s ease,
+    border-color 0.15s ease,
+    box-shadow 0.15s ease,
+    opacity 0.15s ease;
   width: 100%;
 
   &:hover:not(:disabled) {
@@ -233,7 +242,7 @@
   }
 
   .spin {
-    animation: spin 1s linear infinite;
+    animation: bitfun-reproduction-steps-spin 1s linear infinite;
   }
 }
 
@@ -256,7 +265,7 @@
 }
 
 
-@keyframes spin {
+@keyframes bitfun-reproduction-steps-spin {
   from {
     transform: rotate(0deg);
   }
@@ -265,7 +274,7 @@
   }
 }
 
-@keyframes fadeIn {
+@keyframes bitfun-reproduction-steps-content-in {
   from {
     opacity: 0;
     transform: translateY(-4px);
@@ -277,7 +286,7 @@
 }
 
 
-@keyframes waitingPulse {
+@keyframes bitfun-reproduction-steps-waiting-pulse {
   0%, 100% {
     box-shadow: 0 0 0 0 transparent;
   }
@@ -287,5 +296,26 @@
 }
 
 .reproduction-steps-content {
-  animation: fadeIn 0.2s ease-out;
+  animation: bitfun-reproduction-steps-content-in 0.2s cubic-bezier(0.23, 1, 0.32, 1);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .reproduction-steps-block:not(.proceeded) {
+    animation: none;
+    box-shadow: 0 0 0 1px var(--bf-appearance-token-color-warning-border);
+  }
+
+  .reproduction-steps-content,
+  .reproduction-proceed-btn .spin {
+    animation: none;
+  }
+
+  .reproduction-proceed-btn {
+    transition: none;
+  }
+
+  .reproduction-proceed-btn:hover:not(:disabled),
+  .reproduction-proceed-btn:active:not(:disabled) {
+    transform: none;
+  }
 }
diff --git a/src/web-ui/src/component-library/components/NumberInput/NumberInput.scss b/src/web-ui/src/component-library/components/NumberInput/NumberInput.scss
index 6a990738a7..91a0644ad6 100644
--- a/src/web-ui/src/component-library/components/NumberInput/NumberInput.scss
+++ b/src/web-ui/src/component-library/components/NumberInput/NumberInput.scss
@@ -22,7 +22,9 @@
     background: transparent;
     border: 1px solid var(--bf-appearance-token-border-base);
     border-radius: var(--bf-appearance-token-size-radius-sm);
-    transition: all var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard);
+    transition:
+      background-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+      border-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
     overflow: hidden;
 
     &:hover:not(.bitfun-number-input--disabled &) {
@@ -110,7 +112,10 @@
     border: none;
     color: var(--bf-appearance-token-color-text-muted);
     cursor: pointer;
-    transition: all var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
+    transition:
+      background-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+      color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+      scale var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
     position: relative;
     overflow: hidden;
 
@@ -120,7 +125,7 @@
     }
 
     &:active:not(:disabled) {
-      transform: scale(0.9);
+      scale: 0.97;
     }
 
     &:disabled {
@@ -300,3 +305,21 @@
   &--editing {
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .bitfun-number-input__container,
+  .bitfun-number-input__progress,
+  .bitfun-number-input__progress-bar {
+    transition-duration: var(--bf-appearance-token-motion-instant);
+  }
+
+  .bitfun-number-input__btn {
+    transition:
+      background-color var(--bf-appearance-token-motion-instant) ease,
+      color var(--bf-appearance-token-motion-instant) ease;
+
+    &:active:not(:disabled) {
+      scale: none;
+    }
+  }
+}
diff --git a/src/web-ui/src/component-library/components/PresenceBoundary/PresenceBoundary.test.tsx b/src/web-ui/src/component-library/components/PresenceBoundary/PresenceBoundary.test.tsx
new file mode 100644
index 0000000000..6b24bd4080
--- /dev/null
+++ b/src/web-ui/src/component-library/components/PresenceBoundary/PresenceBoundary.test.tsx
@@ -0,0 +1,93 @@
+// @vitest-environment jsdom
+
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  PRESENCE_BOUNDARY_MIN_EXIT_MS,
+  PresenceBoundary,
+} from './PresenceBoundary';
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+describe('PresenceBoundary', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    vi.useRealTimers();
+  });
+
+  const renderBoundary = (
+    active: boolean,
+    exitDurationMs?: number,
+    minimumExitDurationMs?: number,
+  ) => {
+    root.render(
+      <PresenceBoundary
+        active={active}
+        exitDurationMs={exitDurationMs}
+        minimumExitDurationMs={minimumExitDurationMs}
+      >
+        <div data-testid="retained-child">Dialog owner</div>
+      </PresenceBoundary>,
+    );
+  };
+
+  it('does not render before its first activation', () => {
+    act(() => renderBoundary(false));
+
+    expect(container.querySelector('[data-testid="retained-child"]')).toBeNull();
+  });
+
+  it('retains children for at least 200 ms after deactivation', () => {
+    act(() => renderBoundary(true, 50));
+    expect(container.querySelector('[data-testid="retained-child"]')).not.toBeNull();
+
+    act(() => renderBoundary(false, 50));
+    act(() => vi.advanceTimersByTime(PRESENCE_BOUNDARY_MIN_EXIT_MS - 1));
+    expect(container.querySelector('[data-testid="retained-child"]')).not.toBeNull();
+
+    act(() => vi.advanceTimersByTime(1));
+    expect(container.querySelector('[data-testid="retained-child"]')).toBeNull();
+  });
+
+  it('honors a longer owner-specific exit duration', () => {
+    act(() => renderBoundary(true, 320));
+    act(() => renderBoundary(false, 320));
+    act(() => vi.advanceTimersByTime(319));
+    expect(container.querySelector('[data-testid="retained-child"]')).not.toBeNull();
+
+    act(() => vi.advanceTimersByTime(1));
+    expect(container.querySelector('[data-testid="retained-child"]')).toBeNull();
+  });
+
+  it('supports an explicit shorter floor for compact primitives', () => {
+    act(() => renderBoundary(true, 120, 120));
+    act(() => renderBoundary(false, 120, 120));
+    act(() => vi.advanceTimersByTime(119));
+    expect(container.querySelector('[data-testid="retained-child"]')).not.toBeNull();
+
+    act(() => vi.advanceTimersByTime(1));
+    expect(container.querySelector('[data-testid="retained-child"]')).toBeNull();
+  });
+
+  it('cancels a pending unmount when reactivated', () => {
+    act(() => renderBoundary(true));
+    act(() => renderBoundary(false));
+    act(() => vi.advanceTimersByTime(120));
+    act(() => renderBoundary(true));
+    act(() => vi.advanceTimersByTime(PRESENCE_BOUNDARY_MIN_EXIT_MS));
+
+    expect(container.querySelector('[data-testid="retained-child"]')).not.toBeNull();
+  });
+});
diff --git a/src/web-ui/src/component-library/components/PresenceBoundary/PresenceBoundary.tsx b/src/web-ui/src/component-library/components/PresenceBoundary/PresenceBoundary.tsx
new file mode 100644
index 0000000000..137e692ef4
--- /dev/null
+++ b/src/web-ui/src/component-library/components/PresenceBoundary/PresenceBoundary.tsx
@@ -0,0 +1,61 @@
+import React, { useEffect, useState } from 'react';
+
+/**
+ * The shared Modal exit animation lasts 180 ms. Keep its owner mounted a little
+ * longer so the Modal can finish its own exit lifecycle before React removes it.
+ */
+export const PRESENCE_BOUNDARY_MIN_EXIT_MS = 200;
+
+export interface PresenceBoundaryProps {
+  active: boolean;
+  children: React.ReactNode;
+  /** Owner-specific exit window, clamped to `minimumExitDurationMs`. */
+  exitDurationMs?: number;
+  /**
+   * Component-specific retention floor. Keep the 200 ms default for Modal;
+   * shorter primitives may opt into their own measured CSS exit window.
+   */
+  minimumExitDurationMs?: number;
+}
+
+/**
+ * Delays owner-level unmounting without eagerly rendering lazy children.
+ * Reopening during the retention window cancels the pending unmount.
+ */
+export const PresenceBoundary: React.FC<PresenceBoundaryProps> = ({
+  active,
+  children,
+  exitDurationMs,
+  minimumExitDurationMs = PRESENCE_BOUNDARY_MIN_EXIT_MS,
+}) => {
+  const [isRetained, setIsRetained] = useState(active);
+
+  useEffect(() => {
+    if (active) {
+      setIsRetained(true);
+      return;
+    }
+
+    if (!isRetained) {
+      return;
+    }
+
+    const timer = window.setTimeout(
+      () => setIsRetained(false),
+      Math.max(
+        0,
+        minimumExitDurationMs,
+        exitDurationMs ?? minimumExitDurationMs,
+      ),
+    );
+    return () => window.clearTimeout(timer);
+  }, [active, exitDurationMs, isRetained, minimumExitDurationMs]);
+
+  if (!active && !isRetained) {
+    return null;
+  }
+
+  return <>{children}</>;
+};
+
+export default PresenceBoundary;
diff --git a/src/web-ui/src/component-library/components/PresenceBoundary/appearance.ts b/src/web-ui/src/component-library/components/PresenceBoundary/appearance.ts
new file mode 100644
index 0000000000..e6654e7de4
--- /dev/null
+++ b/src/web-ui/src/component-library/components/PresenceBoundary/appearance.ts
@@ -0,0 +1,6 @@
+/**
+ * PresenceBoundary is intentionally DOM-transparent: its child owns the
+ * Appearance surface and the boundary only controls how long that child stays
+ * mounted for its exit lifecycle.
+ */
+export {};
diff --git a/src/web-ui/src/component-library/components/PresenceBoundary/index.ts b/src/web-ui/src/component-library/components/PresenceBoundary/index.ts
new file mode 100644
index 0000000000..6ec4659298
--- /dev/null
+++ b/src/web-ui/src/component-library/components/PresenceBoundary/index.ts
@@ -0,0 +1,2 @@
+export { PresenceBoundary, PRESENCE_BOUNDARY_MIN_EXIT_MS } from './PresenceBoundary';
+export type { PresenceBoundaryProps } from './PresenceBoundary';
diff --git a/src/web-ui/src/component-library/components/Search/Search.scss b/src/web-ui/src/component-library/components/Search/Search.scss
index c4c522e4e3..7876309b36 100644
--- a/src/web-ui/src/component-library/components/Search/Search.scss
+++ b/src/web-ui/src/component-library/components/Search/Search.scss
@@ -39,7 +39,6 @@
 
   &--expandable:not(.search--focused) &__wrapper {
     width: 200px;
-    transition: width var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
   }
 
   &--expandable.search--focused &__wrapper {
@@ -133,12 +132,8 @@
     background: transparent;
     color: var(--bf-appearance-token-color-text-muted);
     cursor: pointer;
-    transition: color $motion-base $easing-standard;
-    animation: search-fade-in 0.2s ease forwards;
-
-    &:hover {
-      color: var(--bf-appearance-token-color-text-secondary);
-    }
+    scale: none;
+    transition: none;
 
     &:active {
       color: var(--bf-appearance-token-color-text-primary);
@@ -167,21 +162,16 @@
     font-weight: $font-weight-medium;
     font-family: $font-family-sans;
     cursor: pointer;
-    transform: scale(1);
+    scale: 1;
     transition:
       background-color var(--bf-appearance-token-motion-fast) ease,
       border-color var(--bf-appearance-token-motion-fast) ease,
       color var(--bf-appearance-token-motion-fast) ease,
-      transform var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
+      scale var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
     white-space: nowrap;
 
-    &:hover:not(:disabled) {
-      background: var(--bf-appearance-token-color-accent-100);
-      color: var(--bf-appearance-token-color-accent-400);
-    }
-
     &:active:not(:disabled) {
-      transform: scale(0.98);
+      scale: 0.97;
     }
 
     &:disabled {
@@ -297,17 +287,6 @@
   }
 }
 
-@keyframes search-fade-in {
-  from {
-    opacity: 0;
-    transform: scale(0.96);
-  }
-  to {
-    opacity: 1;
-    transform: scale(1);
-  }
-}
-
 @keyframes search-slide-down {
   from {
     opacity: 0;
@@ -333,12 +312,11 @@
 
 @media (prefers-reduced-motion: reduce) {
   .search__wrapper,
-  .search__clear,
   .search__button {
     transition:
-      background-color var(--bf-appearance-token-motion-fast) ease,
-      border-color var(--bf-appearance-token-motion-fast) ease,
-      color var(--bf-appearance-token-motion-fast) ease;
+      background-color var(--bf-appearance-token-motion-instant) ease,
+      border-color var(--bf-appearance-token-motion-instant) ease,
+      color var(--bf-appearance-token-motion-instant) ease;
   }
 
   .search__clear,
@@ -346,8 +324,17 @@
     animation: none;
   }
 
+  .search__clear {
+    transition: none;
+    scale: none;
+  }
+
+  .search__loading-icon {
+    animation: none;
+  }
+
   .search__clear:active,
   .search__button:active:not(:disabled) {
-    transform: none;
+    scale: none;
   }
 }
diff --git a/src/web-ui/src/component-library/components/Select/Select.scss b/src/web-ui/src/component-library/components/Select/Select.scss
index 1a11ccab35..fc3972c405 100644
--- a/src/web-ui/src/component-library/components/Select/Select.scss
+++ b/src/web-ui/src/component-library/components/Select/Select.scss
@@ -26,7 +26,9 @@
     border: 1px solid var(--bf-appearance-token-border-base);
     border-radius: var(--bf-appearance-token-size-radius-sm);
     cursor: pointer;
-    transition: all var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard);
+    transition:
+      background-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+      border-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
     min-height: 36px;
     position: relative;
     min-width: 0;
@@ -125,7 +127,10 @@
     font-size: var(--bf-appearance-token-font-size-xs);
     color: var(--bf-appearance-token-color-accent-500);
     max-width: 150px;
-    transition: all var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
+    transition:
+      background-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+      border-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+      color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
 
     &:hover {
       background: var(--bf-appearance-token-color-accent-100);
@@ -164,7 +169,9 @@
     font-size: 14px;
     line-height: 1;
     color: var(--bf-appearance-token-color-text-muted);
-    transition: all var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
+    transition:
+      background-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+      color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
     margin-left: 2px;
 
     &:hover {
@@ -189,7 +196,9 @@
     border-radius: 50%;
     color: var(--bf-appearance-token-color-text-muted);
     cursor: pointer;
-    transition: all var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
+    transition:
+      background-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+      color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
     font-size: 16px;
     line-height: 1;
     padding: 0;
@@ -221,7 +230,9 @@
     align-items: center;
     justify-content: center;
     color: var(--bf-appearance-token-color-text-muted);
-    transition: all var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard);
+    transition:
+      color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+      transform var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
 
     &--open {
       transform: rotate(180deg);
@@ -230,7 +241,7 @@
   }
 
   &__dropdown {
-    --select-entry-y: -2px;
+    --select-motion-y: -2px;
     position: fixed;
     box-sizing: border-box;
     max-width: calc(100vw - 16px);
@@ -243,11 +254,34 @@
     border-radius: 0 0 var(--bf-appearance-token-size-radius-sm) var(--bf-appearance-token-size-radius-sm);
     box-shadow: 0 4px 12px var(--bf-appearance-token-color-overlay-black-40);
     z-index: tokens.$z-popover;
-    animation: select-dropdown-appear var(--bf-appearance-token-motion-fast) tokens.$easing-decelerate;
+    opacity: 1;
+    transform: translateY(0) scale(1);
+    transform-origin: center top;
+    transition:
+      opacity 100ms tokens.$easing-decelerate,
+      transform 120ms tokens.$easing-decelerate;
     overflow: hidden;
     display: flex;
     flex-direction: column;
 
+    &[data-open='true']:not([data-keyboard-open='true']) {
+      @starting-style {
+        opacity: 0;
+        transform: translateY(var(--select-motion-y)) scale(0.985);
+      }
+    }
+
+    &[data-open='false'] {
+      opacity: 0;
+      transform: translateY(var(--select-motion-y)) scale(0.985);
+      transition-duration: 100ms;
+      pointer-events: none;
+    }
+
+    &[data-keyboard-open='true'] {
+      transition: none;
+    }
+
     &::before {
       content: '';
       position: absolute;
@@ -259,7 +293,8 @@
     }
 
     &--top {
-      --select-entry-y: 2px;
+      --select-motion-y: 2px;
+      transform-origin: center bottom;
       border-top: 1px solid var(--bf-appearance-token-border-medium);
       border-bottom: none;
       border-radius: var(--bf-appearance-token-size-radius-sm) var(--bf-appearance-token-size-radius-sm) 0 0;
@@ -300,7 +335,9 @@
     cursor: pointer;
     font-size: 14px;
     line-height: 1;
-    transition: all var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
+    transition:
+      background-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+      color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
     flex-shrink: 0;
     padding: 0;
     border: 0;
@@ -324,7 +361,7 @@
     box-shadow: none !important;
     appearance: none;
     -webkit-appearance: none;
-    transition: all var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
+    transition: background-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
 
     &::placeholder {
       color: var(--bf-appearance-token-color-text-muted);
@@ -354,7 +391,9 @@
     font-weight: var(--bf-appearance-token-font-weight-medium);
     border-bottom: 1px solid var(--bf-appearance-token-border-subtle);
     background: transparent;
-    transition: all var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
+    transition:
+      background-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+      color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
     border-radius: 3px;
     margin-bottom: 0;
     padding-bottom: 8px;
@@ -376,7 +415,6 @@
     gap: 8px;
     padding: 6px 10px;
     cursor: pointer;
-    transition: all var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
     font-size: var(--bf-appearance-token-font-size-sm);
     color: var(--bf-appearance-token-color-text-secondary);
     border-radius: 3px;
@@ -453,7 +491,10 @@
     justify-content: center;
     flex-shrink: 0;
     font-size: 11px;
-    transition: all var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
+    transition:
+      background-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+      border-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+      color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
     background: transparent;
     color: transparent;
 
@@ -503,7 +544,10 @@
     gap: 8px;
     padding: 8px 12px;
     cursor: pointer;
-    transition: all var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
+    transition:
+      background-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+      border-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+      color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
     font-size: var(--bf-appearance-token-font-size-sm);
     color: var(--bf-appearance-token-color-accent-500);
     border-radius: 3px;
@@ -626,17 +670,6 @@
   }
 }
 
-@keyframes select-dropdown-appear {
-  from {
-    opacity: 0;
-    transform: translateY(var(--select-entry-y)) scale(0.985);
-  }
-  to {
-    opacity: 1;
-    transform: translateY(0);
-  }
-}
-
 @media (hover: hover) and (pointer: fine) {
   .select:not(.select--disabled) .select__trigger:hover {
     background: var(--bf-appearance-token-element-bg-subtle);
@@ -685,21 +718,52 @@
 }
 
 @media (prefers-reduced-motion: reduce) {
+  .select__trigger,
+  .select__tag,
+  .select__tag-remove,
+  .select__clear,
+  .select__arrow,
+  .select__search-clear,
+  .select__search-input,
+  .select__select-all,
+  .select__checkbox,
+  .select__custom-value-hint {
+    transition-duration: var(--bf-appearance-token-motion-instant);
+  }
+
   .select__trigger,
   .select__tag-remove,
   .select__clear,
+  .select__arrow,
   .select__search-clear {
     transform: none;
   }
 
   .select__dropdown {
-    animation: select-dropdown-fade var(--bf-appearance-token-motion-fast) ease;
+    transform: none;
+    transition: opacity var(--bf-appearance-token-motion-instant) ease;
+  }
+
+  .select__dropdown[data-open='true']:not([data-keyboard-open='true']) {
+    @starting-style {
+      opacity: 0;
+      transform: none;
+    }
+  }
+
+  .select__dropdown[data-open='false'] {
+    opacity: 0;
+    transform: none;
+    transition-duration: var(--bf-appearance-token-motion-instant);
+  }
+
+  .select__dropdown[data-keyboard-open='true'] {
+    transition: none;
   }
-}
 
-@keyframes select-dropdown-fade {
-  from { opacity: 0; }
-  to { opacity: 1; }
+  .select__loading-spinner {
+    animation: none;
+  }
 }
 
 @keyframes select-spin {
diff --git a/src/web-ui/src/component-library/components/Select/Select.test.tsx b/src/web-ui/src/component-library/components/Select/Select.test.tsx
index 5318b6d0c6..b4700d147d 100644
--- a/src/web-ui/src/component-library/components/Select/Select.test.tsx
+++ b/src/web-ui/src/component-library/components/Select/Select.test.tsx
@@ -18,7 +18,7 @@ describe('Select', () => {
   let root: Root;
   let getBoundingClientRectSpy: ReturnType<typeof vi.spyOn>;
   let offsetHeightSpy: ReturnType<typeof vi.spyOn>;
-  let innerHeight = 800;
+  const innerHeight = 800;
 
   beforeEach(() => {
     (globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
@@ -79,6 +79,7 @@ describe('Select', () => {
     document.querySelector('[data-bf-overlay-host="true"]')?.remove();
     getBoundingClientRectSpy.mockRestore();
     offsetHeightSpy.mockRestore();
+    vi.useRealTimers();
     vi.restoreAllMocks();
   });
 
@@ -295,7 +296,7 @@ describe('Select', () => {
     );
   });
 
-  it('keeps portalled interactions inside the Select and closes on a true outside press', async () => {
+  it('keeps portalled interactions inside the Select and safely retains an outside-closed dropdown', async () => {
     await act(async () => {
       root.render(<Select options={[{ value: 'one', label: 'One' }]} />);
     });
@@ -308,12 +309,119 @@ describe('Select', () => {
     });
     expect(document.querySelector('.select__dropdown')).not.toBeNull();
 
+    vi.useFakeTimers();
     await act(async () => {
       document.body.dispatchEvent(new MouseEvent('mousedown', { bubbles: true }));
     });
+    const closingDropdown = document.querySelector<HTMLElement>('.select__dropdown');
+    expect(closingDropdown).not.toBeNull();
+    expect(closingDropdown?.getAttribute('data-open')).toBe('false');
+    expect(closingDropdown?.getAttribute('aria-hidden')).toBe('true');
+    expect(closingDropdown?.hasAttribute('inert')).toBe(true);
+    expect(closingDropdown?.getAttribute('tabindex')).toBe('-1');
+
+    act(() => vi.advanceTimersByTime(119));
+    expect(document.querySelector('.select__dropdown')).not.toBeNull();
+    act(() => vi.advanceTimersByTime(1));
+    expect(document.querySelector('.select__dropdown')).toBeNull();
+  });
+
+  it('keeps the last options and resolved placement stable during exit', async () => {
+    await act(async () => {
+      root.render(
+        <Select
+          options={[{ value: 'old', label: 'Original option' }]}
+          placement="top"
+        />,
+      );
+    });
+    const trigger = container.querySelector<HTMLElement>('.select__trigger');
+    await act(async () => trigger?.click());
+
+    expect(document.querySelector('.select__dropdown--top')).not.toBeNull();
+    expect(document.querySelector('.select__option')?.textContent).toContain('Original option');
+
+    vi.useFakeTimers();
+    await act(async () => trigger?.click());
+    await act(async () => {
+      root.render(
+        <Select
+          options={[{ value: 'new', label: 'Replacement option' }]}
+          placement="bottom"
+        />,
+      );
+    });
+
+    const closingDropdown = document.querySelector<HTMLElement>('.select__dropdown');
+    expect(closingDropdown?.className).toContain('select__dropdown--top');
+    expect(closingDropdown?.textContent).toContain('Original option');
+    expect(closingDropdown?.textContent).not.toContain('Replacement option');
+
+    act(() => vi.advanceTimersByTime(120));
     expect(document.querySelector('.select__dropdown')).toBeNull();
   });
 
+  it('cancels pending dropdown removal when reopened quickly', async () => {
+    await act(async () => {
+      root.render(<Select options={[{ value: 'one', label: 'One' }]} />);
+    });
+    const trigger = container.querySelector<HTMLElement>('.select__trigger');
+    await act(async () => trigger?.click());
+
+    vi.useFakeTimers();
+    await act(async () => trigger?.click());
+    act(() => vi.advanceTimersByTime(60));
+    await act(async () => trigger?.click());
+    act(() => vi.advanceTimersByTime(120));
+
+    const reopenedDropdown = document.querySelector<HTMLElement>('.select__dropdown');
+    expect(reopenedDropdown).not.toBeNull();
+    expect(reopenedDropdown?.getAttribute('data-open')).toBe('true');
+    expect(reopenedDropdown?.getAttribute('aria-hidden')).toBe('false');
+    expect(reopenedDropdown?.hasAttribute('inert')).toBe(false);
+  });
+
+  it('opens from the keyboard without motion and returns focus when closed', async () => {
+    Object.defineProperty(HTMLElement.prototype, 'scrollIntoView', {
+      configurable: true,
+      value: vi.fn(),
+    });
+    await act(async () => {
+      root.render(
+        <Select
+          searchable
+          options={[{ value: 'one', label: 'One' }]}
+        />,
+      );
+    });
+    const trigger = container.querySelector<HTMLElement>('.select__trigger');
+    await act(async () => {
+      trigger?.dispatchEvent(new KeyboardEvent('keydown', {
+        key: 'ArrowDown',
+        bubbles: true,
+      }));
+    });
+
+    const openDropdown = document.querySelector<HTMLElement>('.select__dropdown');
+    const searchInput = document.querySelector<HTMLInputElement>('.select__search-input');
+    expect(openDropdown?.getAttribute('data-keyboard-open')).toBe('true');
+    expect(document.activeElement).toBe(searchInput);
+
+    vi.useFakeTimers();
+    await act(async () => {
+      searchInput?.dispatchEvent(new KeyboardEvent('keydown', {
+        key: 'Escape',
+        bubbles: true,
+      }));
+    });
+
+    const closingDropdown = document.querySelector<HTMLElement>('.select__dropdown');
+    expect(document.activeElement).toBe(trigger);
+    expect(closingDropdown?.getAttribute('data-open')).toBe('false');
+    expect(closingDropdown?.getAttribute('data-keyboard-open')).toBe('true');
+    expect(searchInput?.tabIndex).toBe(-1);
+  });
+
   it('retains the explicit inline mode for layout-expanding selectors', async () => {
     await act(async () => {
       root.render(
diff --git a/src/web-ui/src/component-library/components/Select/Select.tsx b/src/web-ui/src/component-library/components/Select/Select.tsx
index 12e152fca5..7f74b90efd 100644
--- a/src/web-ui/src/component-library/components/Select/Select.tsx
+++ b/src/web-ui/src/component-library/components/Select/Select.tsx
@@ -6,15 +6,22 @@ import React, {
   useState,
   useRef,
   useEffect,
+  useLayoutEffect,
   useMemo,
   useCallback,
 } from 'react';
 import { createPortal } from 'react-dom';
 import { getAppearanceOverlayHost } from '@/infrastructure/appearance/runtime/AppearanceOverlayHost';
 import { useI18n } from '@/infrastructure/i18n';
-import { useAnchoredPopoverPosition } from '@/shared/utils/useAnchoredPopoverPosition';
+import {
+  useAnchoredPopoverPosition,
+  type AnchoredPopoverLayout,
+} from '@/shared/utils/useAnchoredPopoverPosition';
+import { PresenceBoundary } from '../PresenceBoundary/PresenceBoundary';
 import './Select.scss';
 
+const SELECT_DROPDOWN_EXIT_RETENTION_MS = 120;
+
 export interface SelectOption {
   label: string;
   value: string | number;
@@ -66,6 +73,17 @@ export interface SelectProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
   dropdownMatchTriggerWidth?: boolean;
 }
 
+interface SelectDropdownMountProps {
+  mode: NonNullable<SelectProps['dropdownMode']>;
+  children: React.ReactNode;
+}
+
+const SelectDropdownMount: React.FC<SelectDropdownMountProps> = ({ mode, children }) => (
+  mode === 'overlay'
+    ? createPortal(children, getAppearanceOverlayHost())
+    : <>{children}</>
+);
+
 export const Select: React.FC<SelectProps> = ({
   options = [],
   value,
@@ -120,6 +138,7 @@ export const Select: React.FC<SelectProps> = ({
   );
   const [searchQuery, setSearchQuery] = useState('');
   const [highlightedIndex, setHighlightedIndex] = useState(-1);
+  const [keyboardOpen, setKeyboardOpen] = useState(false);
   const hasMountedRef = useRef(false);
   
   const selectRef = useRef<HTMLDivElement>(null);
@@ -180,6 +199,50 @@ export const Select: React.FC<SelectProps> = ({
     ...Object.values(groupedOptions.groups).flat(),
   ], [groupedOptions]);
 
+  const liveDropdownSnapshot = useMemo<{
+    filteredOptions: SelectOption[];
+    groupedOptions: typeof groupedOptions;
+    highlightedIndex: number;
+    searchQuery: string;
+    loading: boolean;
+    placement: 'bottom' | 'top';
+    layout: AnchoredPopoverLayout | null;
+  }>(() => ({
+    filteredOptions,
+    groupedOptions,
+    highlightedIndex,
+    searchQuery,
+    loading,
+    placement: resolvedPlacement,
+    layout: dropdownLayout,
+  }), [
+    dropdownLayout,
+    filteredOptions,
+    groupedOptions,
+    highlightedIndex,
+    loading,
+    resolvedPlacement,
+    searchQuery,
+  ]);
+  const lastOpenDropdownSnapshotRef = useRef(liveDropdownSnapshot);
+  useLayoutEffect(() => {
+    if (isOpen) {
+      lastOpenDropdownSnapshotRef.current = liveDropdownSnapshot;
+    }
+  }, [isOpen, liveDropdownSnapshot]);
+  const renderedDropdownSnapshot = isOpen
+    ? liveDropdownSnapshot
+    : lastOpenDropdownSnapshotRef.current;
+  const {
+    filteredOptions: renderedFilteredOptions,
+    groupedOptions: renderedGroupedOptions,
+    highlightedIndex: renderedHighlightedIndex,
+    searchQuery: renderedSearchQuery,
+    loading: renderedLoading,
+    placement: renderedPlacement,
+    layout: renderedDropdownLayout,
+  } = renderedDropdownSnapshot;
+
   const isSelected = useCallback((optionValue: string | number) => {
     if (multiple) {
       return (selectedValue as (string | number)[]).includes(optionValue);
@@ -297,6 +360,10 @@ export const Select: React.FC<SelectProps> = ({
   const handleKeyDown = useCallback((e: React.KeyboardEvent) => {
     if (disabled) return;
 
+    if (['Enter', 'Escape', 'ArrowDown', 'ArrowUp', 'Tab'].includes(e.key)) {
+      setKeyboardOpen(true);
+    }
+
     switch (e.key) {
       case 'Enter':
         e.preventDefault();
@@ -357,6 +424,7 @@ export const Select: React.FC<SelectProps> = ({
         && !selectRef.current.contains(target)
         && !dropdownRef.current?.contains(target)
       ) {
+        setKeyboardOpen(false);
         if (allowCustomValue && !multiple && searchQuery.trim()) {
           const trimmedValue = searchQuery.trim();
           const existingOption = options.find(opt => 
@@ -393,6 +461,15 @@ export const Select: React.FC<SelectProps> = ({
     }
   }, [isOpen, searchable]);
 
+  useLayoutEffect(() => {
+    if (
+      !isOpen
+      && dropdownRef.current?.contains(document.activeElement)
+    ) {
+      triggerRef.current?.focus({ preventScroll: true });
+    }
+  }, [isOpen]);
+
   useEffect(() => {
     if (highlightedIndex >= 0 && dropdownRef.current && isKeyboardNavigation.current) {
       const highlightedElement = document.getElementById(`${listboxId}-option-${highlightedIndex}`);
@@ -478,7 +555,7 @@ export const Select: React.FC<SelectProps> = ({
 
   const renderOptionItem = (option: SelectOption, index: number) => {
     const selected = isSelected(option.value);
-    const highlighted = index === highlightedIndex;
+    const highlighted = index === renderedHighlightedIndex;
     
     return (
       <div
@@ -487,7 +564,10 @@ export const Select: React.FC<SelectProps> = ({
         className={`select__option ${selected ? 'select__option--selected' : ''} ${
           option.disabled ? 'select__option--disabled' : ''
         } ${highlighted ? 'select__option--highlighted' : ''}`}
-        onClick={() => handleSelect(option)}
+        onClick={() => {
+          setKeyboardOpen(false);
+          handleSelect(option);
+        }}
         onMouseEnter={() => {
           if (!option.disabled) setHighlightedIndex(index);
         }}
@@ -527,7 +607,7 @@ export const Select: React.FC<SelectProps> = ({
       id={listboxId}
       className={[
         'select__dropdown',
-        `select__dropdown--${resolvedPlacement}`,
+        `select__dropdown--${renderedPlacement}`,
         `select__dropdown--${size}`,
         `select__dropdown--${dropdownMode}`,
         dropdownClassName,
@@ -535,18 +615,25 @@ export const Select: React.FC<SelectProps> = ({
       ref={dropdownRef}
       style={dropdownMode === 'overlay' ? {
         position: 'fixed',
-        top: `${dropdownLayout?.top ?? 0}px`,
-        left: `${dropdownLayout?.left ?? 0}px`,
-        width: dropdownLayout?.width === undefined ? undefined : `${dropdownLayout.width}px`,
-        visibility: dropdownLayout ? 'visible' : 'hidden',
+        top: `${renderedDropdownLayout?.top ?? 0}px`,
+        left: `${renderedDropdownLayout?.left ?? 0}px`,
+        width: renderedDropdownLayout?.width === undefined
+          ? undefined
+          : `${renderedDropdownLayout.width}px`,
+        visibility: renderedDropdownLayout ? 'visible' : 'hidden',
       } : undefined}
       role="listbox"
+      tabIndex={isOpen ? undefined : -1}
+      aria-hidden={!isOpen}
+      {...(!isOpen ? { inert: '' } : {})}
       aria-multiselectable={multiple || undefined}
-      aria-busy={loading || undefined}
+      aria-busy={renderedLoading || undefined}
       data-testid={dropdownTestId}
       data-bf-component="select"
       data-bf-part="dropdown"
-      data-bf-placement={resolvedPlacement}
+      data-bf-placement={renderedPlacement}
+      data-open={isOpen ? 'true' : 'false'}
+      data-keyboard-open={keyboardOpen ? 'true' : 'false'}
     >
       {searchable && (
         <div className="select__search" data-bf-component="select" data-bf-part="search">
@@ -559,14 +646,18 @@ export const Select: React.FC<SelectProps> = ({
             aria-autocomplete="list"
             aria-expanded={isOpen}
             aria-controls={listboxId}
-            aria-activedescendant={highlightedIndex >= 0
-              ? `${listboxId}-option-${highlightedIndex}`
+            aria-activedescendant={isOpen && renderedHighlightedIndex >= 0
+              ? `${listboxId}-option-${renderedHighlightedIndex}`
               : undefined}
             placeholder={resolvedSearchPlaceholder}
-            value={searchQuery}
+            value={renderedSearchQuery}
+            tabIndex={isOpen ? 0 : -1}
             onChange={(e) => setSearchQuery(e.target.value)}
             onClick={(e) => e.stopPropagation()}
             onKeyDown={(e) => {
+              if (['Enter', 'Escape', 'ArrowDown', 'ArrowUp'].includes(e.key)) {
+                setKeyboardOpen(true);
+              }
               if (e.key === 'Enter') {
                 e.preventDefault();
                 if (highlightedIndex >= 0 && highlightedIndex < displayOptions.length) {
@@ -594,10 +685,11 @@ export const Select: React.FC<SelectProps> = ({
             data-bf-component="select"
             data-bf-part="searchInput"
           />
-          {searchQuery && (
+          {renderedSearchQuery && (
             <button
               type="button"
               className="select__search-clear"
+              tabIndex={isOpen ? 0 : -1}
               onClick={(e) => {
                 e.stopPropagation();
                 setSearchQuery('');
@@ -612,45 +704,58 @@ export const Select: React.FC<SelectProps> = ({
         </div>
       )}
 
-      {multiple && showSelectAll && filteredOptions.length > 0 && (
+      {multiple && showSelectAll && renderedFilteredOptions.length > 0 && (
         <div
           className="select__select-all"
-          onClick={handleSelectAll}
+          onClick={() => {
+            setKeyboardOpen(false);
+            handleSelectAll();
+          }}
           role="option"
-          aria-selected={filteredOptions.filter(opt => !opt.disabled).every(opt => isSelected(opt.value))}
+          aria-selected={renderedFilteredOptions
+            .filter(opt => !opt.disabled)
+            .every(opt => isSelected(opt.value))}
         >
           <span className={`select__checkbox ${
-            filteredOptions.filter(opt => !opt.disabled).every(opt => isSelected(opt.value))
+            renderedFilteredOptions.filter(opt => !opt.disabled).every(opt => isSelected(opt.value))
               ? 'select__checkbox--checked' : ''
           }`}>
-            {filteredOptions.filter(opt => !opt.disabled).every(opt => isSelected(opt.value)) && '✓'}
+            {renderedFilteredOptions
+              .filter(opt => !opt.disabled)
+              .every(opt => isSelected(opt.value)) && '✓'}
           </span>
           <span>{t('select.selectAll')}</span>
         </div>
       )}
 
       <div className="select__options" data-bf-component="select" data-bf-part="options">
-        {filteredOptions.length === 0 ? (
-          loading ? (
+        {renderedFilteredOptions.length === 0 ? (
+          renderedLoading ? (
             <div className="select__empty select__empty--loading" data-bf-component="select" data-bf-part="empty">
               <span className="select__loading-spinner" aria-hidden="true" />
               <span>{t('select.loading')}</span>
             </div>
-          ) : allowCustomValue && searchQuery.trim() ? (
-            <div className="select__custom-value-hint" onClick={() => handleCustomValueSubmit()}>
-              <span className="select__custom-value-text">"{searchQuery.trim()}"</span>
+          ) : allowCustomValue && renderedSearchQuery.trim() ? (
+            <div
+              className="select__custom-value-hint"
+              onClick={() => {
+                setKeyboardOpen(false);
+                handleCustomValueSubmit();
+              }}
+            >
+              <span className="select__custom-value-text">"{renderedSearchQuery.trim()}"</span>
               <span className="select__custom-value-action">{resolvedCustomValueHint}</span>
             </div>
           ) : (
             <div className="select__empty" data-bf-component="select" data-bf-part="empty">{resolvedEmptyText}</div>
           )
-        ) : groupedOptions.hasGroups ? (
+        ) : renderedGroupedOptions.hasGroups ? (
           (() => {
             let globalIndex = 0;
             return (
               <>
-                {groupedOptions.ungrouped.map((option) => renderOptionItem(option, globalIndex++))}
-                {Object.entries(groupedOptions.groups).map(([groupName, groupOptions]) => (
+                {renderedGroupedOptions.ungrouped.map((option) => renderOptionItem(option, globalIndex++))}
+                {Object.entries(renderedGroupedOptions.groups).map(([groupName, groupOptions]) => (
                   <div
                     key={groupName}
                     className="select__group"
@@ -668,14 +773,20 @@ export const Select: React.FC<SelectProps> = ({
           })()
         ) : (
           <>
-            {filteredOptions.map((option, index) => renderOptionItem(option, index))}
-            {allowCustomValue && searchQuery.trim()
-              && !filteredOptions.some(opt => (
-                opt.label.toLowerCase() === searchQuery.trim().toLowerCase()
-                || String(opt.value).toLowerCase() === searchQuery.trim().toLowerCase()
+            {renderedFilteredOptions.map((option, index) => renderOptionItem(option, index))}
+            {allowCustomValue && renderedSearchQuery.trim()
+              && !renderedFilteredOptions.some(opt => (
+                opt.label.toLowerCase() === renderedSearchQuery.trim().toLowerCase()
+                || String(opt.value).toLowerCase() === renderedSearchQuery.trim().toLowerCase()
               )) && (
-              <div className="select__custom-value-hint" onClick={() => handleCustomValueSubmit()}>
-                <span className="select__custom-value-text">"{searchQuery.trim()}"</span>
+              <div
+                className="select__custom-value-hint"
+                onClick={() => {
+                  setKeyboardOpen(false);
+                  handleCustomValueSubmit();
+                }}
+              >
+                <span className="select__custom-value-text">"{renderedSearchQuery.trim()}"</span>
                 <span className="select__custom-value-action">{resolvedCustomValueHint}</span>
               </div>
             )}
@@ -692,13 +803,17 @@ export const Select: React.FC<SelectProps> = ({
       <div
         ref={triggerRef}
         className="select__trigger"
-        onClick={() => !disabled && setIsOpen(!isOpen)}
+        onClick={(event) => {
+          if (disabled) return;
+          setKeyboardOpen(event.detail === 0);
+          setIsOpen(!isOpen);
+        }}
         onKeyDown={handleKeyDown}
         tabIndex={disabled ? -1 : 0}
         role="combobox"
         aria-expanded={isOpen}
         aria-haspopup="listbox"
-        aria-controls={listboxId}
+        aria-controls={isOpen ? listboxId : undefined}
         aria-activedescendant={isOpen && highlightedIndex >= 0
           ? `${listboxId}-option-${highlightedIndex}`
           : undefined}
@@ -731,9 +846,15 @@ export const Select: React.FC<SelectProps> = ({
         </div>
       </div>
 
-      {isOpen && (dropdownMode === 'overlay'
-        ? createPortal(dropdownNode, getAppearanceOverlayHost())
-        : dropdownNode)}
+      <PresenceBoundary
+        active={isOpen}
+        exitDurationMs={SELECT_DROPDOWN_EXIT_RETENTION_MS}
+        minimumExitDurationMs={SELECT_DROPDOWN_EXIT_RETENTION_MS}
+      >
+        <SelectDropdownMount mode={dropdownMode}>
+          {dropdownNode}
+        </SelectDropdownMount>
+      </PresenceBoundary>
 
       {error && errorMessage && (
         <div className="select__error-message" data-bf-component="select" data-bf-part="message">{errorMessage}</div>
diff --git a/src/web-ui/src/component-library/components/Tabs/Tabs.scss b/src/web-ui/src/component-library/components/Tabs/Tabs.scss
index 5127cd3c97..7507b4d05a 100644
--- a/src/web-ui/src/component-library/components/Tabs/Tabs.scss
+++ b/src/web-ui/src/component-library/components/Tabs/Tabs.scss
@@ -41,11 +41,6 @@
     border: none;
     white-space: nowrap;
 
-    &:hover:not(&--disabled):not(&--active) {
-      color: var(--bf-appearance-token-color-text-primary);
-      background: var(--bf-appearance-token-element-bg-subtle);
-    }
-
     &--active {
       color: var(--bf-appearance-token-color-accent-500);
     }
@@ -115,10 +110,6 @@
         transform var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
       opacity: 1;
 
-      &:hover {
-        background: color-mix(in srgb, var(--bf-appearance-token-color-error) 20%, transparent);
-        color: var(--bf-appearance-token-color-error);
-      }
     }
   }
 
@@ -126,6 +117,10 @@
     width: 100%;
   }
 
+  &__content-view {
+    width: 100%;
+  }
+
   &--stretch {
     .bitfun-tabs__tab {
       flex: 1;
@@ -191,9 +186,6 @@
         overflow: hidden;
       }
 
-      &:hover:not(&--disabled):not(&--active) {
-        background: var(--bf-appearance-token-element-bg-medium);
-      }
     }
   }
 
diff --git a/src/web-ui/src/component-library/components/Tabs/Tabs.test.tsx b/src/web-ui/src/component-library/components/Tabs/Tabs.test.tsx
new file mode 100644
index 0000000000..4b5bdd1835
--- /dev/null
+++ b/src/web-ui/src/component-library/components/Tabs/Tabs.test.tsx
@@ -0,0 +1,72 @@
+// @vitest-environment jsdom
+
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { recordInteractionModality } from '@/shared/utils/motionPreference';
+import { Tabs, TabPane } from './Tabs';
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+describe('Tabs view transitions', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => (
+      window.setTimeout(() => callback(performance.now()), 16)
+    ));
+    vi.stubGlobal('cancelAnimationFrame', (handle: number) => window.clearTimeout(handle));
+    recordInteractionModality('programmatic');
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    recordInteractionModality('programmatic');
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+  });
+
+  const renderTabs = () => {
+    root.render(
+      <Tabs defaultActiveKey="first">
+        <TabPane tabKey="first" label="First"><div data-testid="first-pane" /></TabPane>
+        <TabPane tabKey="second" label="Second"><div data-testid="second-pane" /></TabPane>
+      </Tabs>,
+    );
+  };
+
+  it('retains the outgoing panel for a pointer-selected tab', () => {
+    act(renderTabs);
+    const secondTab = container.querySelectorAll<HTMLButtonElement>('[role="tab"]')[1];
+    recordInteractionModality('pointer');
+    act(() => secondTab.click());
+
+    expect(container.querySelector('[data-testid="first-pane"]')).not.toBeNull();
+    expect(container.querySelector('[data-testid="second-pane"]')).not.toBeNull();
+    expect(
+      container.querySelector('.bitfun-view-transition-boundary__view--outgoing')?.hasAttribute('inert'),
+    ).toBe(true);
+  });
+
+  it('switches a keyboard-selected tab without retaining the outgoing panel', () => {
+    act(renderTabs);
+    const firstTab = container.querySelectorAll<HTMLButtonElement>('[role="tab"]')[0];
+    recordInteractionModality('keyboard');
+    act(() => {
+      firstTab.dispatchEvent(new KeyboardEvent('keydown', {
+        bubbles: true,
+        key: 'ArrowRight',
+      }));
+    });
+
+    expect(container.querySelector('[data-testid="first-pane"]')).toBeNull();
+    expect(container.querySelector('[data-testid="second-pane"]')).not.toBeNull();
+    expect(container.querySelectorAll('.bitfun-view-transition-boundary__view')).toHaveLength(1);
+  });
+});
diff --git a/src/web-ui/src/component-library/components/Tabs/Tabs.tsx b/src/web-ui/src/component-library/components/Tabs/Tabs.tsx
index daea0bcda9..f00aeede6a 100644
--- a/src/web-ui/src/component-library/components/Tabs/Tabs.tsx
+++ b/src/web-ui/src/component-library/components/Tabs/Tabs.tsx
@@ -1,4 +1,14 @@
-import React, { useState, createContext, useContext, useMemo, useId } from 'react';
+import React, {
+  useState,
+  createContext,
+  useContext,
+  useMemo,
+  useId,
+  useRef,
+  useLayoutEffect,
+} from 'react';
+import { getInteractionMotion, type InteractionMotion } from '@/shared/utils/motionPreference';
+import { ViewTransitionBoundary } from '../ViewTransitionBoundary';
 import './Tabs.scss';
 
 export interface TabItem {
@@ -63,6 +73,11 @@ export const Tabs: React.FC<TabsProps> = ({
   style,
 }) => {
   const generatedId = useId();
+  const transitionIntentRef = useRef<{
+    key: string;
+    motion: InteractionMotion;
+    sourceKey: string;
+  } | null>(null);
   const [internalActiveKey, setInternalActiveKey] = useState<string>(
     defaultActiveKey || ''
   );
@@ -93,8 +108,15 @@ export const Tabs: React.FC<TabsProps> = ({
     }
   }, [activeKey, controlledActiveKey, tabs]);
 
-  const handleTabClick = (key: string, disabled?: boolean) => {
+  const handleTabClick = (
+    key: string,
+    disabled?: boolean,
+    motion: InteractionMotion = getInteractionMotion(),
+  ) => {
     if (disabled) return;
+    transitionIntentRef.current = key === activeKey
+      ? null
+      : { key, motion, sourceKey: activeKey };
     
     if (controlledActiveKey === undefined) {
       setInternalActiveKey(key);
@@ -127,7 +149,7 @@ export const Tabs: React.FC<TabsProps> = ({
       target = enabledTabs[enabledTabs.length - 1];
     } else if (event.key === 'Enter' || event.key === ' ') {
       event.preventDefault();
-      handleTabClick(tabs[currentIndex].key, tabs[currentIndex].disabled);
+      handleTabClick(tabs[currentIndex].key, tabs[currentIndex].disabled, 'instant');
       return;
     } else {
       return;
@@ -135,7 +157,7 @@ export const Tabs: React.FC<TabsProps> = ({
 
     if (!target) return;
     event.preventDefault();
-    handleTabClick(target.tab.key);
+    handleTabClick(target.tab.key, target.tab.disabled, 'instant');
     document.getElementById(getTabId(target.tab.key))?.focus();
   };
 
@@ -152,6 +174,18 @@ export const Tabs: React.FC<TabsProps> = ({
     onChange: handleTabClick,
   };
 
+  const transitionIntent = transitionIntentRef.current;
+  const shouldAnimatePanel = transitionIntent?.key === activeKey
+    && transitionIntent.sourceKey !== activeKey
+    && transitionIntent.motion === 'pointer';
+
+  useLayoutEffect(() => {
+    const pendingIntent = transitionIntentRef.current;
+    if (pendingIntent && pendingIntent.sourceKey !== activeKey) {
+      transitionIntentRef.current = null;
+    }
+  }, [activeKey]);
+
   return (
     <TabsContext.Provider value={contextValue}>
       <div className={containerClass} style={style} data-bf-component="tabs" data-bf-part="root" data-bf-variant={type} data-bf-size={size} data-bf-state={stretch ? 'stretch' : undefined}>
@@ -199,15 +233,20 @@ export const Tabs: React.FC<TabsProps> = ({
           </div>
           {type === 'line' && <div className="bitfun-tabs__ink-bar" data-bf-component="tabs" data-bf-part="inkBar" />}
         </div>
-        <div
+        <ViewTransitionBoundary
+          viewKey={activeKey || '__empty-tab__'}
+          animate={shouldAnimatePanel}
           id={getPanelId(activeKey)}
           className="bitfun-tabs__content"
+          viewClassName="bitfun-tabs__content-view"
           role="tabpanel"
           aria-labelledby={getTabId(activeKey)}
           tabIndex={0}
-         data-bf-component="tabs" data-bf-part="content">
+          data-bf-component="tabs"
+          data-bf-part="content"
+        >
           {panes[activeKey]}
-        </div>
+        </ViewTransitionBoundary>
       </div>
     </TabsContext.Provider>
   );
diff --git a/src/web-ui/src/component-library/components/TextStrokeEffect/TextStrokeEffect.scss b/src/web-ui/src/component-library/components/TextStrokeEffect/TextStrokeEffect.scss
index 0fce1d7ab9..6605d8d1e1 100644
--- a/src/web-ui/src/component-library/components/TextStrokeEffect/TextStrokeEffect.scss
+++ b/src/web-ui/src/component-library/components/TextStrokeEffect/TextStrokeEffect.scss
@@ -55,3 +55,11 @@
     stroke-dashoffset: -46;
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .text-stroke-effect__animated,
+  .text-stroke-effect__gradient {
+    animation: none;
+    stroke-dashoffset: 0;
+  }
+}
diff --git a/src/web-ui/src/component-library/components/Textarea/Textarea.scss b/src/web-ui/src/component-library/components/Textarea/Textarea.scss
index 349e834e9c..9dee550048 100644
--- a/src/web-ui/src/component-library/components/Textarea/Textarea.scss
+++ b/src/web-ui/src/component-library/components/Textarea/Textarea.scss
@@ -39,7 +39,9 @@
     background: var(--bf-appearance-token-element-bg-subtle);
     border: 1.5px solid var(--bf-appearance-token-border-base);
     border-radius: 4px;
-    transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
+    transition:
+      background-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+      border-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
     resize: vertical;
     font-family: inherit;
 
@@ -164,3 +166,9 @@
     background: var(--bf-appearance-token-element-bg-base);
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .bitfun-textarea__field {
+    transition-duration: var(--bf-appearance-token-motion-instant);
+  }
+}
diff --git a/src/web-ui/src/component-library/components/Tooltip/Tooltip.scss b/src/web-ui/src/component-library/components/Tooltip/Tooltip.scss
index 9c2098ba90..788777a667 100644
--- a/src/web-ui/src/component-library/components/Tooltip/Tooltip.scss
+++ b/src/web-ui/src/component-library/components/Tooltip/Tooltip.scss
@@ -115,8 +115,9 @@
     border-right: 0;
   }
 
-  &--top.bitfun-tooltip--visible {
-    animation: bitfun-tooltip-fade-in-top 0.12s ease-out;
+  &--top {
+    --tooltip-enter-y: 3px;
+    transform-origin: center bottom;
   }
 
   &--bottom {
@@ -158,5 +159,9 @@
     &--visible {
       transform: none;
     }
+
+    &[data-instant='true'] {
+      transition-duration: 0ms;
+    }
   }
 }
diff --git a/src/web-ui/src/component-library/components/Tooltip/Tooltip.tsx b/src/web-ui/src/component-library/components/Tooltip/Tooltip.tsx
index 145831ceb6..f12cbd6ed2 100644
--- a/src/web-ui/src/component-library/components/Tooltip/Tooltip.tsx
+++ b/src/web-ui/src/component-library/components/Tooltip/Tooltip.tsx
@@ -423,6 +423,7 @@ export const Tooltip: React.FC<TooltipProps> = ({
           id={tooltipId}
           role="tooltip"
           className={tooltipClass}
+          data-motion="presence"
           data-instant={instantRef.current || undefined}
           onMouseEnter={interactive ? () => {
             if (hideTimeoutRef.current) {
diff --git a/src/web-ui/src/component-library/components/ViewTransitionBoundary/ViewTransitionBoundary.scss b/src/web-ui/src/component-library/components/ViewTransitionBoundary/ViewTransitionBoundary.scss
new file mode 100644
index 0000000000..21ed67265a
--- /dev/null
+++ b/src/web-ui/src/component-library/components/ViewTransitionBoundary/ViewTransitionBoundary.scss
@@ -0,0 +1,68 @@
+.bitfun-view-transition-boundary {
+  position: relative;
+  min-width: 0;
+  min-height: 0;
+
+  &__view {
+    min-width: 0;
+    min-height: 0;
+    opacity: 1;
+    transform: translate3d(0, 0, 0) scale(1);
+  }
+
+  &__view--incoming {
+    position: relative;
+    z-index: 1;
+    transition:
+      opacity 180ms cubic-bezier(0.23, 1, 0.32, 1),
+      transform 180ms cubic-bezier(0.23, 1, 0.32, 1);
+  }
+
+  &__view--outgoing {
+    position: absolute;
+    inset: 0;
+    z-index: 2;
+    pointer-events: none;
+    transition:
+      opacity 140ms cubic-bezier(0.23, 1, 0.32, 1),
+      transform 140ms cubic-bezier(0.23, 1, 0.32, 1);
+  }
+
+  &[data-view-transition-phase='preparing'] {
+    > .bitfun-view-transition-boundary__view--incoming {
+      opacity: 0.72;
+      transform: translate3d(0, 6px, 0) scale(0.995);
+      transition: none;
+    }
+  }
+
+  &[data-view-transition-phase='running'] {
+    > .bitfun-view-transition-boundary__view--outgoing {
+      opacity: 0;
+      transform: translate3d(0, -4px, 0) scale(0.997);
+    }
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .bitfun-view-transition-boundary {
+    &__view--incoming,
+    &__view--outgoing {
+      transform: none;
+      transition: opacity 100ms cubic-bezier(0.23, 1, 0.32, 1);
+    }
+
+    &[data-view-transition-phase='preparing'] {
+      > .bitfun-view-transition-boundary__view--incoming {
+        opacity: 0.82;
+        transform: none;
+      }
+    }
+
+    &[data-view-transition-phase='running'] {
+      > .bitfun-view-transition-boundary__view--outgoing {
+        transform: none;
+      }
+    }
+  }
+}
diff --git a/src/web-ui/src/component-library/components/ViewTransitionBoundary/ViewTransitionBoundary.test.tsx b/src/web-ui/src/component-library/components/ViewTransitionBoundary/ViewTransitionBoundary.test.tsx
new file mode 100644
index 0000000000..d60c45275c
--- /dev/null
+++ b/src/web-ui/src/component-library/components/ViewTransitionBoundary/ViewTransitionBoundary.test.tsx
@@ -0,0 +1,79 @@
+// @vitest-environment jsdom
+
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  VIEW_TRANSITION_EXIT_MS,
+  ViewTransitionBoundary,
+} from './ViewTransitionBoundary';
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+describe('ViewTransitionBoundary', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => (
+      window.setTimeout(() => callback(performance.now()), 16)
+    ));
+    vi.stubGlobal('cancelAnimationFrame', (handle: number) => window.clearTimeout(handle));
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+  });
+
+  const renderView = (viewKey: string, animate: boolean) => {
+    root.render(
+      <ViewTransitionBoundary viewKey={viewKey} animate={animate}>
+        <button type="button" data-testid={`view-${viewKey}`}>{viewKey}</button>
+      </ViewTransitionBoundary>,
+    );
+  };
+
+  it('switches keyboard and programmatic views immediately', () => {
+    act(() => renderView('first', false));
+    act(() => renderView('second', false));
+
+    expect(container.querySelector('[data-testid="view-first"]')).toBeNull();
+    expect(container.querySelector('[data-testid="view-second"]')).not.toBeNull();
+  });
+
+  it('retains an inert outgoing view for a pointer transition', () => {
+    act(() => renderView('first', false));
+    act(() => renderView('second', true));
+
+    const outgoing = container.querySelector('.bitfun-view-transition-boundary__view--outgoing');
+    expect(outgoing?.hasAttribute('inert')).toBe(true);
+    expect(outgoing?.getAttribute('aria-hidden')).toBe('true');
+    expect(container.querySelectorAll('.bitfun-view-transition-boundary__view')).toHaveLength(2);
+
+    act(() => vi.advanceTimersByTime(32));
+    expect(container.querySelector('[data-view-transition-phase="running"]')).not.toBeNull();
+
+    act(() => vi.advanceTimersByTime(VIEW_TRANSITION_EXIT_MS));
+    expect(container.querySelector('[data-testid="view-first"]')).toBeNull();
+    expect(container.querySelectorAll('.bitfun-view-transition-boundary__view')).toHaveLength(1);
+  });
+
+  it('retargets a rapid pointer switch to the latest view', () => {
+    act(() => renderView('first', false));
+    act(() => renderView('second', true));
+    act(() => vi.advanceTimersByTime(32));
+    act(() => renderView('third', true));
+    act(() => vi.advanceTimersByTime(32 + VIEW_TRANSITION_EXIT_MS));
+
+    expect(container.querySelector('[data-testid="view-first"]')).toBeNull();
+    expect(container.querySelector('[data-testid="view-second"]')).toBeNull();
+    expect(container.querySelector('[data-testid="view-third"]')).not.toBeNull();
+  });
+});
diff --git a/src/web-ui/src/component-library/components/ViewTransitionBoundary/ViewTransitionBoundary.tsx b/src/web-ui/src/component-library/components/ViewTransitionBoundary/ViewTransitionBoundary.tsx
new file mode 100644
index 0000000000..f9b7efe622
--- /dev/null
+++ b/src/web-ui/src/component-library/components/ViewTransitionBoundary/ViewTransitionBoundary.tsx
@@ -0,0 +1,188 @@
+import React, { useLayoutEffect, useRef, useState } from 'react';
+import './ViewTransitionBoundary.scss';
+
+export const VIEW_TRANSITION_EXIT_MS = 200;
+
+interface RetainedView {
+  children: React.ReactNode;
+  incomingKey: React.Key;
+  outgoingKey: React.Key;
+  phase: 'preparing' | 'running';
+  sequence: number;
+}
+
+export interface ViewTransitionBoundaryProps
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
+  /** Identity of the visible view. A new key starts a pointer transition. */
+  viewKey: React.Key;
+  children: React.ReactNode;
+  /** Keep false for keyboard, shortcut, and programmatic navigation. */
+  animate?: boolean;
+  /** Class applied to both the current and retained outgoing view wrappers. */
+  viewClassName?: string;
+}
+
+function scheduleAnimationFrame(callback: FrameRequestCallback): number {
+  if (typeof globalThis.requestAnimationFrame === 'function') {
+    return globalThis.requestAnimationFrame(callback);
+  }
+  return window.setTimeout(() => (
+    callback(globalThis.performance?.now() ?? Date.now())
+  ), 16);
+}
+
+function cancelScheduledAnimationFrame(handle: number): void {
+  if (typeof globalThis.cancelAnimationFrame === 'function') {
+    globalThis.cancelAnimationFrame(handle);
+    return;
+  }
+  window.clearTimeout(handle);
+}
+
+/**
+ * Retains the outgoing React tree just long enough to bridge an occasional
+ * pointer-driven content replacement. The outgoing tree is immediately inert;
+ * keyboard and programmatic changes remain synchronous and single-mounted.
+ */
+export const ViewTransitionBoundary: React.FC<ViewTransitionBoundaryProps> = ({
+  viewKey,
+  children,
+  animate = false,
+  className = '',
+  viewClassName = '',
+  ...rootProps
+}) => {
+  const currentKeyRef = useRef<React.Key>(viewKey);
+  const currentChildrenRef = useRef<React.ReactNode>(children);
+  const sequenceRef = useRef(0);
+  const frameRef = useRef<number | null>(null);
+  const exitTimerRef = useRef<number | null>(null);
+  const [transition, setTransition] = useState<RetainedView | null>(null);
+
+  const keyChanged = currentKeyRef.current !== viewKey;
+  if (!keyChanged) {
+    currentChildrenRef.current = children;
+  }
+
+  const pendingTransition: RetainedView | null = keyChanged && animate
+    ? {
+        children: currentChildrenRef.current,
+        incomingKey: viewKey,
+        outgoingKey: currentKeyRef.current,
+        phase: 'preparing',
+        sequence: sequenceRef.current + 1,
+      }
+    : transition?.incomingKey === viewKey
+      ? transition
+      : null;
+
+  useLayoutEffect(() => {
+    if (currentKeyRef.current === viewKey) return;
+
+    const outgoingKey = currentKeyRef.current;
+    const outgoingChildren = currentChildrenRef.current;
+    currentKeyRef.current = viewKey;
+    currentChildrenRef.current = children;
+
+    if (frameRef.current !== null) {
+      cancelScheduledAnimationFrame(frameRef.current);
+      frameRef.current = null;
+    }
+    if (exitTimerRef.current !== null) {
+      window.clearTimeout(exitTimerRef.current);
+      exitTimerRef.current = null;
+    }
+
+    if (!animate) {
+      setTransition(null);
+      return;
+    }
+
+    const sequence = ++sequenceRef.current;
+    setTransition({
+      children: outgoingChildren,
+      incomingKey: viewKey,
+      outgoingKey,
+      phase: 'preparing',
+      sequence,
+    });
+
+    frameRef.current = scheduleAnimationFrame(() => {
+      // A second frame guarantees the preparing styles have reached a paint.
+      // React may otherwise flush an interaction effect before the browser
+      // paints, collapsing the starting and running states into one frame.
+      frameRef.current = scheduleAnimationFrame(() => {
+        frameRef.current = null;
+        setTransition(current => (
+          current?.sequence === sequence
+            ? { ...current, phase: 'running' }
+            : current
+        ));
+        exitTimerRef.current = window.setTimeout(() => {
+          exitTimerRef.current = null;
+          setTransition(current => (
+            current?.sequence === sequence ? null : current
+          ));
+        }, VIEW_TRANSITION_EXIT_MS);
+      });
+    });
+  }, [animate, children, viewKey]);
+
+  useLayoutEffect(() => () => {
+    if (frameRef.current !== null) {
+      cancelScheduledAnimationFrame(frameRef.current);
+    }
+    if (exitTimerRef.current !== null) {
+      window.clearTimeout(exitTimerRef.current);
+    }
+  }, []);
+
+  const rootClassName = [
+    'bitfun-view-transition-boundary',
+    className,
+  ].filter(Boolean).join(' ');
+  const currentClassName = [
+    'bitfun-view-transition-boundary__view',
+    pendingTransition && 'bitfun-view-transition-boundary__view--incoming',
+    viewClassName,
+  ].filter(Boolean).join(' ');
+  const outgoingClassName = [
+    'bitfun-view-transition-boundary__view',
+    'bitfun-view-transition-boundary__view--outgoing',
+    viewClassName,
+  ].filter(Boolean).join(' ');
+
+  return (
+    <div
+      className={rootClassName}
+      data-bf-component="view-transition-boundary"
+      data-bf-part="root"
+      {...rootProps}
+      data-motion="presence"
+      data-view-transition-phase={pendingTransition?.phase}
+    >
+      {pendingTransition ? (
+        <div
+          key={pendingTransition.outgoingKey}
+          className={outgoingClassName}
+          aria-hidden="true"
+          data-bf-component="view-transition-boundary"
+          data-bf-part="view"
+          {...{ inert: '' }}
+        >
+          {pendingTransition.children}
+        </div>
+      ) : null}
+      <div
+        key={viewKey}
+        className={currentClassName}
+        data-bf-component="view-transition-boundary"
+        data-bf-part="view"
+      >
+        {children}
+      </div>
+    </div>
+  );
+};
+
+export default ViewTransitionBoundary;
diff --git a/src/web-ui/src/component-library/components/ViewTransitionBoundary/appearance.ts b/src/web-ui/src/component-library/components/ViewTransitionBoundary/appearance.ts
new file mode 100644
index 0000000000..80d3f779f0
--- /dev/null
+++ b/src/web-ui/src/component-library/components/ViewTransitionBoundary/appearance.ts
@@ -0,0 +1,13 @@
+import type { AppearanceSurfaceDescriptor } from '@/infrastructure/appearance/types';
+
+/**
+ * Lifecycle-only surface. It deliberately exposes no paint properties; the
+ * current and outgoing child trees continue to own their visual Appearance.
+ */
+export const viewTransitionBoundaryAppearanceDescriptor: AppearanceSurfaceDescriptor = {
+  id: 'view-transition-boundary',
+  parts: [
+    { id: 'root', propertyProfile: 'layout', visualRole: 'continuous-surface' },
+    { id: 'view', visualRole: 'content' },
+  ],
+};
diff --git a/src/web-ui/src/component-library/components/ViewTransitionBoundary/index.ts b/src/web-ui/src/component-library/components/ViewTransitionBoundary/index.ts
new file mode 100644
index 0000000000..6ee8cad957
--- /dev/null
+++ b/src/web-ui/src/component-library/components/ViewTransitionBoundary/index.ts
@@ -0,0 +1,5 @@
+export {
+  VIEW_TRANSITION_EXIT_MS,
+  ViewTransitionBoundary,
+} from './ViewTransitionBoundary';
+export type { ViewTransitionBoundaryProps } from './ViewTransitionBoundary';
diff --git a/src/web-ui/src/component-library/components/index.ts b/src/web-ui/src/component-library/components/index.ts
index 260a63faba..c713e93649 100644
--- a/src/web-ui/src/component-library/components/index.ts
+++ b/src/web-ui/src/component-library/components/index.ts
@@ -8,6 +8,8 @@ export * from './IconButton';
 export * from './WindowControls';
 
 export * from './Modal';
+export * from './PresenceBoundary';
+export * from './ViewTransitionBoundary';
 export * from './InputDialog';
 export * from './ConfirmDialog';
 
diff --git a/src/web-ui/src/component-library/styles/_extended-mixins.scss b/src/web-ui/src/component-library/styles/_extended-mixins.scss
index a3f202d1ea..c8f2f20677 100644
--- a/src/web-ui/src/component-library/styles/_extended-mixins.scss
+++ b/src/web-ui/src/component-library/styles/_extended-mixins.scss
@@ -126,15 +126,25 @@
 
 // ==================== Interaction mixins ====================
 
-@mixin transition($properties: all, $duration: $motion-base, $easing: $easing-standard) {
+@mixin transition($properties: transform, $duration: $motion-base, $easing: $easing-standard) {
   transition: $properties $duration $easing;
 }
 
 @mixin hover-lift($offset: -2px, $scale: 1.02) {
-  transition: all $motion-base $easing-standard;
-  
-  &:hover {
-    transform: translateY($offset) scale($scale);
+  transition: transform $motion-base $easing-standard;
+
+  @media (hover: hover) and (pointer: fine) {
+    &:hover {
+      transform: translateY($offset) scale($scale);
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    transition: none;
+
+    &:hover {
+      transform: none;
+    }
   }
 }
 
@@ -179,7 +189,7 @@
     stroke: currentColor;
     fill: none;
     stroke-width: $stroke-width-default;
-    transition: all 0.3s $easing-smooth;
+    transition: stroke-width 0.3s $easing-smooth;
   }
 
   &:hover:not(:disabled) {
@@ -195,6 +205,12 @@
       stroke-width: $stroke-width-active;
     }
   }
+
+  @media (prefers-reduced-motion: reduce) {
+    svg {
+      transition: none;
+    }
+  }
 }
 
 // ==================== Visual effects mixins ====================
diff --git a/src/web-ui/src/features/dispatch/DispatchInstallDialog.scss b/src/web-ui/src/features/dispatch/DispatchInstallDialog.scss
index 523378e1fa..faa73ec696 100644
--- a/src/web-ui/src/features/dispatch/DispatchInstallDialog.scss
+++ b/src/web-ui/src/features/dispatch/DispatchInstallDialog.scss
@@ -291,3 +291,9 @@
     transform: rotate(360deg);
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .dispatch-install-dialog__spin {
+    animation: none;
+  }
+}
diff --git a/src/web-ui/src/features/dispatch/DispatchResultDialog.scss b/src/web-ui/src/features/dispatch/DispatchResultDialog.scss
index 2660d3f4df..185303e3ff 100644
--- a/src/web-ui/src/features/dispatch/DispatchResultDialog.scss
+++ b/src/web-ui/src/features/dispatch/DispatchResultDialog.scss
@@ -201,3 +201,9 @@
     transform: rotate(360deg);
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .dispatch-result-dialog__spin {
+    animation: none;
+  }
+}
diff --git a/src/web-ui/src/features/dispatch/dispatchApi.ts b/src/web-ui/src/features/dispatch/dispatchApi.ts
index 709ab66d60..c152561c7e 100644
--- a/src/web-ui/src/features/dispatch/dispatchApi.ts
+++ b/src/web-ui/src/features/dispatch/dispatchApi.ts
@@ -194,6 +194,7 @@ export const dispatchApi = {
     displayContent?: string,
     messageId: string = globalThis.crypto?.randomUUID?.()
       ?? `dispatch-message-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    attachments?: DispatchInlineAttachment[],
   ): Promise<{ accepted: boolean; messageId: string }> {
     return api.invoke<{ accepted: boolean; messageId: string }>('dispatch_append', {
       request: {
@@ -201,6 +202,7 @@ export const dispatchApi = {
         messageId,
         content,
         ...(displayContent?.trim() ? { displayContent } : {}),
+        ...(attachments?.length ? { attachments } : {}),
       },
     });
   },
diff --git a/src/web-ui/src/features/relay-deploy/README.md b/src/web-ui/src/features/relay-deploy/README.md
index c961dbf783..fd3cbaffe7 100644
--- a/src/web-ui/src/features/relay-deploy/README.md
+++ b/src/web-ui/src/features/relay-deploy/README.md
@@ -108,7 +108,7 @@ Desktop Tauri surface: `src/apps/desktop/src/api/relay_deploy_api.rs`
     current release builders assert a GLIBC 2.35 ceiling.
 
 20. **Release metadata has a byte mirror, not a second authority.**
-    `openbitfun-release-sync.sh` mirrors the signed descriptor into both its
+    `scripts/openbitfun-release-sync.sh` mirrors the signed descriptor into both its
     version directory and `/release/relay-image.json`. Desktop may fetch those
     bytes when GitHub is unreachable, but the same built-in minisign key must
     verify them.
diff --git a/src/web-ui/src/features/relay-deploy/RelayDeployWizard.scss b/src/web-ui/src/features/relay-deploy/RelayDeployWizard.scss
index 76a692a1d9..1d7c90ab75 100644
--- a/src/web-ui/src/features/relay-deploy/RelayDeployWizard.scss
+++ b/src/web-ui/src/features/relay-deploy/RelayDeployWizard.scss
@@ -631,3 +631,12 @@
     background: transparent;
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .relay-deploy-wizard {
+    .spinning,
+    &__form--highlighted {
+      animation: none;
+    }
+  }
+}
diff --git a/src/web-ui/src/features/relay-deploy/RelayDeployWizard.tsx b/src/web-ui/src/features/relay-deploy/RelayDeployWizard.tsx
index e6e1585e9b..8067190aab 100644
--- a/src/web-ui/src/features/relay-deploy/RelayDeployWizard.tsx
+++ b/src/web-ui/src/features/relay-deploy/RelayDeployWizard.tsx
@@ -39,6 +39,7 @@ import {
 import { buildRelayServerSearchState, getRelayConnectionHost } from './serverSearch';
 import { ConnectedTerminal, getTerminalService } from '@/tools/terminal';
 import { createLogger } from '@/shared/utils/logger';
+import { getMotionAwareScrollBehavior } from '@/shared/utils/motionPreference';
 import './RelayDeployWizard.scss';
 
 const log = createLogger('RelayDeployWizard');
@@ -116,7 +117,10 @@ export const RelayDeployWizard: React.FC<RelayDeployWizardProps> = ({
   const revealConnectForm = useCallback(() => {
     const el = connectFormRef.current;
     if (!el) return;
-    el.scrollIntoView({ behavior: 'smooth', block: 'start' });
+    el.scrollIntoView({
+      behavior: getMotionAwareScrollBehavior('smooth'),
+      block: 'start',
+    });
     setConnectFormHighlighted(true);
     if (connectFormHighlightTimerRef.current != null) {
       window.clearTimeout(connectFormHighlightTimerRef.current);
diff --git a/src/web-ui/src/features/ssh-remote/RemoteFileBrowser.scss b/src/web-ui/src/features/ssh-remote/RemoteFileBrowser.scss
index 2817d94c4b..62bf1c96cd 100644
--- a/src/web-ui/src/features/ssh-remote/RemoteFileBrowser.scss
+++ b/src/web-ui/src/features/ssh-remote/RemoteFileBrowser.scss
@@ -11,7 +11,7 @@
   background: rgba(var(--bf-appearance-token-color-static-black-rgb), 0.6);
   backdrop-filter: blur(4px);
   z-index: 260;
-  animation: fadeIn 0.2s ease;
+  animation: remote-file-browser-fade-in 0.2s ease;
 
   // Beat `.bitfun-app-layout *:focus-visible` (same specificity as a single-class :focus-visible; load order can win).
   .remote-file-browser__path-input:focus,
@@ -22,7 +22,7 @@
   }
 }
 
-@keyframes fadeIn {
+@keyframes remote-file-browser-fade-in {
   from { opacity: 0; }
   to { opacity: 1; }
 }
@@ -38,7 +38,7 @@
   border-radius: 12px;
   box-shadow: 0 24px 48px var(--bf-appearance-token-color-overlay-black-50), 0 0 0 1px var(--bf-appearance-token-color-overlay-white-04);
   overflow: hidden;
-  animation: slideIn 0.3s cubic-bezier(0.16, 1, 0.3, 1);
+  animation: remote-file-browser-slide-in 0.3s cubic-bezier(0.16, 1, 0.3, 1);
 
   &__header {
     display: flex;
@@ -68,7 +68,9 @@
     border-radius: 6px;
     color: var(--bf-appearance-token-color-text-muted);
     cursor: pointer;
-    transition: all var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
+    transition:
+      background-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+      color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
 
     &:hover {
       background: var(--bf-appearance-token-element-bg-subtle);
@@ -149,7 +151,9 @@
     color: var(--bf-appearance-token-color-text-secondary);
     cursor: pointer;
     white-space: nowrap;
-    transition: all var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
+    transition:
+      background-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+      color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
 
     &:hover {
       background: var(--bf-appearance-token-element-bg-subtle);
@@ -196,7 +200,10 @@
     border-radius: 6px;
     color: var(--bf-appearance-token-color-text-muted);
     cursor: pointer;
-    transition: all var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
+    transition:
+      background-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+      color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+      opacity var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
 
     &:hover:not(:disabled) {
       background: var(--bf-appearance-token-element-bg-subtle);
@@ -220,7 +227,7 @@
     flex-shrink: 0;
 
     .remote-file-browser__spinner-inline {
-      animation: spin 0.8s linear infinite;
+      animation: remote-file-browser-spin 0.8s linear infinite;
     }
   }
 
@@ -265,7 +272,7 @@
   }
 
   &__spinner {
-    animation: spin 1s linear infinite;
+    animation: remote-file-browser-spin 1s linear infinite;
     color: var(--bf-appearance-token-color-accent-500);
   }
 
@@ -435,7 +442,9 @@
     color: var(--bf-appearance-token-color-text-secondary);
     cursor: pointer;
     text-align: left;
-    transition: all var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
+    transition:
+      background-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+      color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
 
     svg {
       color: var(--bf-appearance-token-color-text-muted);
@@ -586,12 +595,12 @@
   }
 }
 
-@keyframes spin {
+@keyframes remote-file-browser-spin {
   from { transform: rotate(0deg); }
   to { transform: rotate(360deg); }
 }
 
-@keyframes slideIn {
+@keyframes remote-file-browser-slide-in {
   from {
     opacity: 0;
     transform: translateY(20px) scale(0.97);
@@ -601,3 +610,19 @@
     transform: translateY(0) scale(1);
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .remote-file-browser-overlay,
+  .remote-file-browser,
+  .remote-file-browser__spinner,
+  .remote-file-browser__spinner-inline {
+    animation: none;
+  }
+
+  .remote-file-browser__close-btn,
+  .remote-file-browser__breadcrumb-btn,
+  .remote-file-browser__toolbar-btn,
+  .remote-file-browser__context-menu-item {
+    transition: none;
+  }
+}
diff --git a/src/web-ui/src/features/ssh-remote/SSHAuthPromptDialog.scss b/src/web-ui/src/features/ssh-remote/SSHAuthPromptDialog.scss
index 39373007f3..f8719184b8 100644
--- a/src/web-ui/src/features/ssh-remote/SSHAuthPromptDialog.scss
+++ b/src/web-ui/src/features/ssh-remote/SSHAuthPromptDialog.scss
@@ -92,3 +92,9 @@
     transform: rotate(360deg);
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .ssh-auth-prompt-dialog__spinner {
+    animation: none;
+  }
+}
diff --git a/src/web-ui/src/features/ssh-remote/SSHConnectionDialog.scss b/src/web-ui/src/features/ssh-remote/SSHConnectionDialog.scss
index 898e1d59b4..a12030935f 100644
--- a/src/web-ui/src/features/ssh-remote/SSHConnectionDialog.scss
+++ b/src/web-ui/src/features/ssh-remote/SSHConnectionDialog.scss
@@ -81,7 +81,9 @@
     padding: 5px 10px;
     border-radius: 6px;
     background: var(--bf-appearance-token-element-bg-subtle);
-    transition: all var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
+    transition:
+      transform var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+      background-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
     cursor: pointer;
     position: relative;
 
@@ -433,7 +435,7 @@
   }
 
   &__spinner {
-    animation: spin 1s linear infinite;
+    animation: ssh-connection-spin 1s linear infinite;
     margin-right: 6px;
   }
 }
@@ -490,7 +492,7 @@
   }
 }
 
-@keyframes spin {
+@keyframes ssh-connection-spin {
   from {
     transform: rotate(0deg);
   }
@@ -499,6 +501,17 @@
   }
 }
 
+@media (prefers-reduced-motion: reduce) {
+  .ssh-connection-dialog__saved-item {
+    transition: none;
+  }
+
+  .ssh-connection-dialog__form--highlighted,
+  .ssh-connection-dialog__spinner {
+    animation: none;
+  }
+}
+
 /** SSH remote workspace dialog only: above nav fixed popovers (~10k) so the dimmed backdrop captures clicks. */
 .ssh-connection-dialog__modal-overlay {
   z-index: 20000;
diff --git a/src/web-ui/src/features/ssh-remote/SSHConnectionDialog.tsx b/src/web-ui/src/features/ssh-remote/SSHConnectionDialog.tsx
index 9499f35c98..af47452fcf 100644
--- a/src/web-ui/src/features/ssh-remote/SSHConnectionDialog.tsx
+++ b/src/web-ui/src/features/ssh-remote/SSHConnectionDialog.tsx
@@ -47,6 +47,7 @@ import {
   pickSshCertificatePath,
   pickSshPrivateKeyPath,
 } from './pickSshPrivateKeyPath';
+import { getMotionAwareScrollBehavior } from '@/shared/utils/motionPreference';
 import './SSHConnectionDialog.scss';
 
 interface SSHConnectionDialogProps {
@@ -111,7 +112,10 @@ export const SSHConnectionDialog: React.FC<SSHConnectionDialogProps> = ({
   const revealConnectionForm = useCallback(() => {
     const el = formRef.current;
     if (!el) return;
-    el.scrollIntoView({ behavior: 'smooth', block: 'start' });
+    el.scrollIntoView({
+      behavior: getMotionAwareScrollBehavior('smooth'),
+      block: 'start',
+    });
     setFormHighlighted(true);
     if (formHighlightTimerRef.current != null) {
       window.clearTimeout(formHighlightTimerRef.current);
@@ -710,8 +714,6 @@ export const SSHConnectionDialog: React.FC<SSHConnectionDialogProps> = ({
     clearError();
   };
 
-  if (!open) return null;
-
   return (
     <>
       <Modal
@@ -1376,7 +1378,7 @@ export const SSHConnectionDialog: React.FC<SSHConnectionDialogProps> = ({
         </div>
       </Modal>
 
-      {credentialsPrompt && (
+      {open && credentialsPrompt && (
         <SSHAuthPromptDialog
           open
           targetDescription={`${credentialsPrompt.username}@${credentialsPrompt.host}:${credentialsPrompt.port}`}
diff --git a/src/web-ui/src/flow_chat/components/AcpPlanPanel.scss b/src/web-ui/src/flow_chat/components/AcpPlanPanel.scss
index 619b145075..6676c85ab2 100644
--- a/src/web-ui/src/flow_chat/components/AcpPlanPanel.scss
+++ b/src/web-ui/src/flow_chat/components/AcpPlanPanel.scss
@@ -90,3 +90,9 @@
     transform: rotate(360deg);
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .bitfun-acp-plan__icon--active {
+    animation: none;
+  }
+}
diff --git a/src/web-ui/src/flow_chat/components/ChatEmptyState.scss b/src/web-ui/src/flow_chat/components/ChatEmptyState.scss
index 5731e39ce1..a405b5798e 100644
--- a/src/web-ui/src/flow_chat/components/ChatEmptyState.scss
+++ b/src/web-ui/src/flow_chat/components/ChatEmptyState.scss
@@ -85,7 +85,9 @@
     border: 1px solid var(--bf-appearance-token-border-medium);
     border-radius: $size-radius-sm;
     line-height: var(--bf-appearance-token-flowchat-support-line-height);
-    transition: all $motion-base $easing-standard;
+    transition:
+      background-color $motion-base $easing-standard,
+      border-color $motion-base $easing-standard;
     
     &:hover {
       background: var(--bf-appearance-token-element-bg-hover);
@@ -105,7 +107,9 @@
     border: 1px solid var(--bf-appearance-token-border-medium);
     border-radius: $size-radius-sm;
     line-height: var(--bf-appearance-token-flowchat-support-line-height);
-    transition: all $motion-base $easing-standard;
+    transition:
+      background-color $motion-base $easing-standard,
+      border-color $motion-base $easing-standard;
     
     &:hover {
       background: var(--bf-appearance-token-element-bg-hover);
@@ -175,7 +179,9 @@
       background: var(--bf-appearance-token-element-bg-subtle);
       border-left: 2px solid var(--bf-appearance-token-border-strong);
       border-radius: 0 $size-radius-sm $size-radius-sm 0;
-      transition: all $motion-base $easing-standard;
+      transition:
+        background-color $motion-base $easing-standard,
+        border-left-color $motion-base $easing-standard;
       
       &:hover {
         background: var(--bf-appearance-token-element-bg-soft);
@@ -224,4 +230,3 @@
   }
 }
 
-
diff --git a/src/web-ui/src/flow_chat/components/ChatInput.appearance.ts b/src/web-ui/src/flow_chat/components/ChatInput.appearance.ts
index 205c6ff71a..cd75818ca2 100644
--- a/src/web-ui/src/flow_chat/components/ChatInput.appearance.ts
+++ b/src/web-ui/src/flow_chat/components/ChatInput.appearance.ts
@@ -55,7 +55,7 @@ export const chatInputAppearanceDescriptor: AppearanceSurfaceDescriptor = {
     { id: 'target', attribute: 'data-bf-target', values: ['main', 'btw'] },
     { id: 'command', attribute: 'data-bf-command', values: ['actions', 'all', 'skills', 'modes'] },
     { id: 'commandItemKind', attribute: 'data-bf-command-item-kind', values: ['action', 'mode', 'skill', 'mcp'] },
-    { id: 'action', attribute: 'data-bf-action', values: ['cancel', 'retry', 'send', 'split'] },
+    { id: 'action', attribute: 'data-bf-action', values: ['cancel', 'continue-interrupted', 'retry', 'send', 'split'] },
     { id: 'boostItemKind', attribute: 'data-bf-boost-item-kind', values: ['mode', 'context', 'skill', 'manage'] },
   ],
   states: [
diff --git a/src/web-ui/src/flow_chat/components/ChatInput.scss b/src/web-ui/src/flow_chat/components/ChatInput.scss
index 0283dffe10..da988190c2 100644
--- a/src/web-ui/src/flow_chat/components/ChatInput.scss
+++ b/src/web-ui/src/flow_chat/components/ChatInput.scss
@@ -1163,7 +1163,7 @@
     -webkit-backdrop-filter: blur(20px) saturate(1.2);
     overflow: hidden;
     transform-origin: left top;
-    animation: mentionPickerSlideUp 180ms cubic-bezier(0.23, 1, 0.32, 1);
+    animation: bitfun-chat-input-boost-menu-enter 180ms cubic-bezier(0.23, 1, 0.32, 1);
   }
 
   &__boost-submenu-shell--left &__boost-submenu-panel {
@@ -1191,7 +1191,7 @@
   }
 
   &__boost-submenu-spinner {
-    animation: spin 0.8s linear infinite;
+    animation: bitfun-chat-input-spin 0.8s linear infinite;
     color: var(--bf-appearance-token-color-accent-500);
   }
 
@@ -1280,7 +1280,7 @@
     }
   }
 
-  @keyframes mentionPickerSlideUp {
+  @keyframes bitfun-chat-input-boost-menu-enter {
     from {
       opacity: 0;
       transform: translateY(4px) scale(0.98);
@@ -1988,7 +1988,7 @@
     border-radius: 50%;
     border: 1px solid transparent;
     border-top-color: var(--bf-appearance-token-color-static-white);
-    animation: spin 0.8s linear infinite;
+    animation: bitfun-chat-input-spin 0.8s linear infinite;
   }
 
   /* Stop: theme-inverted pause glyph — luminous disk + deep square on dark UI;
@@ -2143,41 +2143,12 @@
   }
 }
 
-@keyframes spin {
+@keyframes bitfun-chat-input-spin {
   to {
     transform: rotate(360deg);
   }
 }
 
-@keyframes bitfun-breathing-pulse {
-  0%, 100% {
-    transform: scale(1);
-    box-shadow: 0 0 12px color-mix(in srgb, var(--bf-appearance-token-color-warning) 50%, transparent);
-    opacity: 1;
-  }
-  50% {
-    transform: scale(1.15);
-    box-shadow:
-      0 0 20px color-mix(in srgb, var(--bf-appearance-token-color-warning) 80%, transparent),
-      0 0 30px color-mix(in srgb, var(--bf-appearance-token-color-warning) 40%, transparent);
-    opacity: 0.9;
-  }
-}
-
-@keyframes bitfun-breathing-pulse-fast {
-  0%, 100% {
-    transform: scale(1);
-    box-shadow: 0 0 12px color-mix(in srgb, var(--bf-appearance-token-color-warning) 60%, transparent);
-  }
-  50% {
-    transform: scale(1.2);
-    box-shadow:
-      0 0 24px color-mix(in srgb, var(--bf-appearance-token-color-warning) 90%, transparent),
-      0 0 40px color-mix(in srgb, var(--bf-appearance-token-color-warning) 50%, transparent);
-  }
-}
-
-
 @keyframes bitfun-chat-input-fade-in {
   from {
     opacity: 0;
@@ -2189,39 +2160,6 @@
   }
 }
 
-@keyframes bitfun-space-hint-pop {
-  0% {
-    opacity: 0;
-    transform: translateY(3px);
-  }
-  100% {
-    opacity: 0.62;
-    transform: translateY(0);
-  }
-}
-
-@keyframes bitfun-box-fade-in {
-  0% {
-    opacity: 0;
-    transform: translateY(6px) scale(0.98);
-  }
-  100% {
-    opacity: 1;
-    transform: translateY(0) scale(1);
-  }
-}
-
-@keyframes bitfun-active-content-appear {
-  from {
-    opacity: 0;
-    transform: translateY(4px);
-  }
-  to {
-    opacity: 1;
-    transform: translateY(0);
-  }
-}
-
 @media (hover: none), (pointer: coarse) {
   .bitfun-chat-input__send-button:hover:not(:disabled),
   .bitfun-chat-input__send-button--breathing:hover .bitfun-chat-input__breathing-circle,
diff --git a/src/web-ui/src/flow_chat/components/ChatInput.tsx b/src/web-ui/src/flow_chat/components/ChatInput.tsx
index 7a39ce2cca..990b1bf375 100644
--- a/src/web-ui/src/flow_chat/components/ChatInput.tsx
+++ b/src/web-ui/src/flow_chat/components/ChatInput.tsx
@@ -7,7 +7,7 @@ import React, { useRef, useCallback, useEffect, useReducer, useState, useMemo, u
 import { createPortal } from 'react-dom';
 import path from 'path-browserify';
 import { useTranslation } from 'react-i18next';
-import { ArrowUp, BotMessageSquare, Image, RotateCcw, Plus, X, Sparkles, Loader2, ChevronRight, Files, MessageSquarePlus, Star } from 'lucide-react';
+import { ArrowUp, BotMessageSquare, Image, RotateCcw, Plus, X, Sparkles, Loader2, ChevronRight, Files, MessageSquarePlus, Star, Play } from 'lucide-react';
 import { ContextDropZone, useContextStore } from '../../shared/context-system';
 import { useActiveSessionState } from '@/flow_chat/hooks';
 import { i18nService } from '@/infrastructure/i18n';
@@ -25,7 +25,7 @@ import {
   useSessionStateMachine,
   useSessionStateMachineActions,
 } from '../hooks/useSessionStateMachine';
-import { SessionExecutionEvent } from '../state-machine/types';
+import { SessionExecutionEvent, SessionExecutionState } from '../state-machine/types';
 import { ModelSelector } from './ModelSelector';
 import { FlowChatStore } from '../store/FlowChatStore';
 import { useAcpPlan } from '../hooks/useAcpPlan';
@@ -69,6 +69,7 @@ import {
   sessionComposerStore,
   type PendingLargePasteMap,
 } from '../store/sessionComposerStore';
+import { getActiveSurfaceScope } from '@/infrastructure/peer-device/deviceSurface';
 import {
   failedSubmissionRecoveryTarget,
   shouldRecordContextMutation,
@@ -89,6 +90,7 @@ import { ThreadGoalDialogs } from './thread-goal/ThreadGoalDialogs';
 import { getAppearanceOverlayHost } from '@/infrastructure/appearance/runtime/AppearanceOverlayHost';
 import { useAnchoredPopoverPosition } from '@/shared/utils/useAnchoredPopoverPosition';
 import { FlowChatManager } from '@/flow_chat/services/FlowChatManager';
+import { interruptedTurnRecoveryGate } from '@/flow_chat/services/interruptedTurnRecoveryGate';
 import {
   getDeepReviewLaunchErrorMessage,
 } from '../services/DeepReviewService';
@@ -105,6 +107,7 @@ import {
   sessionWorktreeBindingSubscriptionKey,
 } from '../utils/sessionWorktree';
 import { isRemoteWorkspaceSession, sessionProjectWorkspacePath } from '../utils/sessionWorkspace';
+import { findWorkspaceForSession } from '../utils/workspaceScope';
 import { isTauriRuntime } from '@/infrastructure/runtime';
 import { Tooltip, IconButton, confirmDanger, confirmWarning } from '@/component-library';
 import { PendingQueuePanel } from './PendingQueuePanel';
@@ -183,6 +186,8 @@ import {
 } from '../utils/tokenUsageDisplay';
 import { agentAPI } from '@/infrastructure/api/service-api/AgentAPI';
 import type { SessionPermissionMode } from '@/infrastructure/api/service-api/AgentAPI';
+import { isPeerDeviceModeActive } from '@/infrastructure/peer-device/peerModeFlag';
+import { selectInterruptedTurnRecovery } from '../utils/interruptedTurnRecovery';
 import {
   chatInputPermissionMode,
   permissionModeFromConfig,
@@ -424,6 +429,7 @@ export const ChatInput: React.FC<ChatInputProps> = ({
   isSceneActive = true,
   registration,
 }) => {
+  const deviceSurfaceScope = getActiveSurfaceScope();
   const { t } = useTranslation('flow-chat');
   const { t: tWorktrees } = useI18n('worktrees');
   const canLaunchReview = isTauriRuntime();
@@ -473,10 +479,17 @@ export const ChatInput: React.FC<ChatInputProps> = ({
   // other open session.
   const [sessionPermissionMode, setSessionPermissionMode] =
     useState<SessionPermissionMode | null>(null);
-  // Armed for the next submission only, never persisted. Cleared once a
-  // submission has carried it, or when the target session changes.
-  const [turnPermissionMode, setTurnPermissionMode] =
+  // One-off state has two owners: the idle composer arms a future submission,
+  // while an executing turn keeps a mutable override until it ends.
+  const [armedTurnPermissionMode, setArmedTurnPermissionMode] =
     useState<SessionPermissionMode | null>(null);
+  const [activeTurnPermissionMode, setActiveTurnPermissionMode] =
+    useState<SessionPermissionMode | null>(null);
+  const permissionModeRequestGenerationRef = useRef(0);
+  const permissionModeLifecycleRef = useRef<{
+    sessionId: string | null;
+    activeTurnId: string | null;
+  }>({ sessionId: null, activeTurnId: null });
   const { addMessage: addToHistory, getSessionHistory } = useInputHistoryStore();
   
   const contexts = useContextStore(state => state.contexts);
@@ -586,6 +599,7 @@ export const ChatInput: React.FC<ChatInputProps> = ({
   const threadGoalController = useThreadGoalController(effectiveTargetSession, {
     isBtwSession,
     disabled: !caps.threadGoal,
+    sceneActive: isSceneActive,
   });
   // Resolve via the i18n key (re-localizes on locale switch) instead of the
   // persisted localized session.title string, so this tab stays in sync with
@@ -630,7 +644,17 @@ export const ChatInput: React.FC<ChatInputProps> = ({
     inputState.value.trim()
   );
   const currentReviewActivity = useSessionReviewActivity(currentSessionId);
-  useSessionStateMachine(effectiveTargetSessionId);
+  const sessionMachine = useSessionStateMachine(effectiveTargetSessionId);
+  const activePermissionTurnId =
+    sessionMachine?.currentState === SessionExecutionState.PROCESSING
+      ? sessionMachine.context.currentDialogTurnId
+      : null;
+  const activePermissionTurnIdRef = useRef<string | null>(activePermissionTurnId);
+  activePermissionTurnIdRef.current = activePermissionTurnId;
+  const armedTurnPermissionModeRef = useRef<SessionPermissionMode | null>(
+    armedTurnPermissionMode,
+  );
+  armedTurnPermissionModeRef.current = armedTurnPermissionMode;
   const { confirmDeepReviewLaunch, deepReviewConsentDialog } = useDeepReviewConsent();
   // isMultiLine: true when content overflows a single line (scrollHeight > threshold or has newlines)
   const [isMultiLine, setIsMultiLine] = useState(false);
@@ -936,6 +960,20 @@ export const ChatInput: React.FC<ChatInputProps> = ({
   const workspacePathRef = useRef(sessionBoundWorkspacePath);
   workspacePathRef.current = sessionBoundWorkspacePath;
   const { openedWorkspaces } = useWorkspaceContext();
+  const mentionWorkspace = useMemo(() => (
+    effectiveTargetSession
+      ? findWorkspaceForSession(effectiveTargetSession, openedWorkspaces.values())
+      : workspace ?? undefined
+  ), [effectiveTargetSession, openedWorkspaces, workspace]);
+  const sessionBoundRemoteConnectionId = (
+    hasRegisteredWorkspace
+      ? registration?.remoteConnectionId
+      : (
+          effectiveTargetSession?.remoteConnectionId
+          || effectiveTargetSession?.config?.remoteConnectionId
+          || mentionWorkspace?.connectionId
+        )
+  )?.trim() || undefined;
 
   const chatStripRepositoryPath = useMemo(() => {
     const fromSession = hasRegisteredWorkspace
@@ -1013,8 +1051,11 @@ export const ChatInput: React.FC<ChatInputProps> = ({
   const permissionMode: ChatInputPermissionMode = isAcpTargetSession
     ? 'acp'
     : chatInputPermissionMode(sessionPermissionMode ?? globalPermissionMode);
+  const temporaryPermissionMode = activePermissionTurnId
+    ? activeTurnPermissionMode
+    : armedTurnPermissionMode;
   const permissionModeOverridden =
-    !isAcpTargetSession && (turnPermissionMode !== null || sessionPermissionMode !== null);
+    !isAcpTargetSession && (temporaryPermissionMode !== null || sessionPermissionMode !== null);
   const activeSessionMode = effectiveTargetSessionId
     ? acpTargetAgentType || flowChatState.sessions.get(effectiveTargetSessionId)?.mode
     : undefined;
@@ -1614,16 +1655,20 @@ export const ChatInput: React.FC<ChatInputProps> = ({
   }, [canUseSkillsForTarget, inlineTriggerState, isAcpInputSession]);
 
   const previousComposerSessionIdRef = useRef<string | null>(null);
+  const previousComposerSurfaceEpochRef = useRef(deviceSurfaceScope.epoch);
 
   React.useLayoutEffect(() => {
     const previousSessionId = previousComposerSessionIdRef.current;
+    const surfaceChanged = previousComposerSurfaceEpochRef.current !== deviceSurfaceScope.epoch;
     const draft = sessionComposerStore.getState().activateDraft(
       previousSessionId,
       effectiveTargetSessionId,
       useContextStore.getState().contexts,
       richTextInputRef.current?.getComposerPresentation?.() ?? null,
+      !surfaceChanged,
     );
     previousComposerSessionIdRef.current = effectiveTargetSessionId;
+    previousComposerSurfaceEpochRef.current = deviceSurfaceScope.epoch;
 
     const nextValue = draft.value;
     const nextContexts = draft.contexts;
@@ -1657,7 +1702,7 @@ export const ChatInput: React.FC<ChatInputProps> = ({
       query: '',
       selectedIndex: 0,
     });
-  }, [effectiveTargetSessionId, replaceContexts]);
+  }, [deviceSurfaceScope.epoch, effectiveTargetSessionId, replaceContexts]);
 
   useEffect(() => {
     let previousContexts = useContextStore.getState().contexts;
@@ -1715,8 +1760,10 @@ export const ChatInput: React.FC<ChatInputProps> = ({
     contexts,
     onClearContexts: clearContexts,
     onSuccess: onSendMessage,
-    turnPermissionMode,
-    onTurnPermissionModeConsumed: () => setTurnPermissionMode(null),
+    // A busy session queues new input. Its active override must not leak into
+    // that future turn's submission metadata.
+    turnPermissionMode: activePermissionTurnId ? null : armedTurnPermissionMode,
+    onTurnPermissionModeConsumed: () => setArmedTurnPermissionMode(null),
     onSessionConflictRetryStart: ({ sessionId }) => {
       sessionConflictRetryBaselinesRef.current.set(
         sessionId,
@@ -2023,37 +2070,63 @@ export const ChatInput: React.FC<ChatInputProps> = ({
     };
   }, []);
 
-  // Reads the session's own selection whenever the target session changes, so
-  // switching conversations shows that conversation's mode rather than the last
-  // one the user touched.
+  // Reconcile persistent session state and the exact active-turn override.
+  // A request generation prevents a late response from a previous session or
+  // completed turn from repainting the current control.
   React.useEffect(() => {
-    let cancelled = false;
+    const generation = ++permissionModeRequestGenerationRef.current;
+    const previous = permissionModeLifecycleRef.current;
+    const sessionChanged = previous.sessionId !== effectiveTargetSessionId;
+    const activeTurnChanged = previous.activeTurnId !== activePermissionTurnId;
+    permissionModeLifecycleRef.current = {
+      sessionId: effectiveTargetSessionId,
+      activeTurnId: activePermissionTurnId,
+    };
+
+    if (sessionChanged) {
+      setArmedTurnPermissionMode(null);
+      setActiveTurnPermissionMode(null);
+    } else if (activeTurnChanged) {
+      // A locally submitted one-off becomes the active turn's initial mode.
+      // Keep it armed until start_dialog_turn acknowledges so a failed send
+      // can still be retried with the user's selection.
+      setActiveTurnPermissionMode(
+        activePermissionTurnId ? armedTurnPermissionModeRef.current : null,
+      );
+    }
+
     if (!effectiveTargetSessionId || isAcpTargetSession) {
       setSessionPermissionMode(null);
-      setTurnPermissionMode(null);
+      setArmedTurnPermissionMode(null);
+      setActiveTurnPermissionMode(null);
       return undefined;
     }
-    setTurnPermissionMode(null);
     void (async () => {
       try {
         const response = await agentAPI.getSessionPermissionMode({
           sessionId: effectiveTargetSessionId,
+          turnId: activePermissionTurnId ?? undefined,
           workspacePath: effectiveTargetSession?.workspacePath,
           remoteConnectionId: effectiveTargetSession?.remoteConnectionId,
           remoteSshHost: effectiveTargetSession?.remoteSshHost,
         });
-        if (!cancelled) setSessionPermissionMode(response.mode ?? null);
+        if (permissionModeRequestGenerationRef.current !== generation) return;
+        setSessionPermissionMode(response.mode ?? null);
+        if (activePermissionTurnId && response.activeTurnId === activePermissionTurnId) {
+          setActiveTurnPermissionMode(response.turnMode ?? null);
+        }
       } catch (error) {
         log.warn('Failed to read session permission mode', error);
         // Falling back to the global default is the safe read: it never shows a
         // wider mode than the session actually runs with.
-        if (!cancelled) setSessionPermissionMode(null);
+        if (permissionModeRequestGenerationRef.current === generation) {
+          setSessionPermissionMode(null);
+        }
       }
     })();
-    return () => {
-      cancelled = true;
-    };
+    return undefined;
   }, [
+    activePermissionTurnId,
     effectiveTargetSessionId,
     effectiveTargetSession?.workspacePath,
     effectiveTargetSession?.remoteConnectionId,
@@ -2068,22 +2141,43 @@ export const ChatInput: React.FC<ChatInputProps> = ({
       notificationService.error(t('chatInput.permissionMode.noSession'));
       return;
     }
+    const targetSessionId = effectiveTargetSessionId;
+    const targetTurnId = activePermissionTurnIdRef.current;
+    const generation = ++permissionModeRequestGenerationRef.current;
     const previousMode = sessionPermissionMode;
+    const previousActiveTurnMode = activeTurnPermissionMode;
     setSessionPermissionMode(nextMode);
+    setArmedTurnPermissionMode(null);
+    setActiveTurnPermissionMode(null);
     setPermissionModeSaving(true);
     try {
       const response = await agentAPI.updateSessionPermissionMode({
-        sessionId: effectiveTargetSessionId,
+        sessionId: targetSessionId,
         mode: nextMode,
+        turnId: targetTurnId ?? undefined,
         workspacePath: effectiveTargetSession?.workspacePath,
         remoteConnectionId: effectiveTargetSession?.remoteConnectionId,
         remoteSshHost: effectiveTargetSession?.remoteSshHost,
       });
-      setSessionPermissionMode(response.mode ?? null);
+      if (
+        permissionModeRequestGenerationRef.current === generation
+        && effectiveTargetSessionIdRef.current === targetSessionId
+      ) {
+        setSessionPermissionMode(response.mode ?? null);
+        setActiveTurnPermissionMode(null);
+      }
     } catch (error) {
       log.error('Failed to change session permission mode', error);
-      setSessionPermissionMode(previousMode);
-      notificationService.error(t('chatInput.permissionMode.changeFailed'));
+      if (
+        permissionModeRequestGenerationRef.current === generation
+        && effectiveTargetSessionIdRef.current === targetSessionId
+      ) {
+        setSessionPermissionMode(previousMode);
+        if (activePermissionTurnIdRef.current === targetTurnId) {
+          setActiveTurnPermissionMode(previousActiveTurnMode);
+        }
+        notificationService.error(t('chatInput.permissionMode.changeFailed'));
+      }
     } finally {
       setPermissionModeSaving(false);
     }
@@ -2092,6 +2186,7 @@ export const ChatInput: React.FC<ChatInputProps> = ({
     effectiveTargetSession?.workspacePath,
     effectiveTargetSession?.remoteConnectionId,
     effectiveTargetSession?.remoteSshHost,
+    activeTurnPermissionMode,
     sessionPermissionMode,
     t,
   ]);
@@ -2100,14 +2195,16 @@ export const ChatInput: React.FC<ChatInputProps> = ({
   // one-off turn still runs every tool without asking.
   const confirmFullAccessIfNeeded = useCallback(async (
     nextMode: Exclude<ChatInputPermissionMode, 'acp'>,
-    scope: 'session' | 'turn',
+    scope: 'session' | 'next-turn' | 'active-turn',
   ) => {
     if (nextMode !== 'full_access') return true;
     return confirmDanger(
       t('chatInput.permissionMode.fullAccessWarningTitle'),
-      t(scope === 'turn'
-        ? 'chatInput.permissionMode.fullAccessWarningMessageNextTurn'
-        : 'chatInput.permissionMode.fullAccessWarningMessage'),
+      t(scope === 'active-turn'
+        ? 'chatInput.permissionMode.fullAccessWarningMessageActiveTurn'
+        : scope === 'next-turn'
+          ? 'chatInput.permissionMode.fullAccessWarningMessageNextTurn'
+          : 'chatInput.permissionMode.fullAccessWarningMessage'),
       {
         confirmText: t('chatInput.permissionMode.fullAccessConfirm'),
         cancelText: t('chatInput.permissionMode.cancel'),
@@ -2124,9 +2221,6 @@ export const ChatInput: React.FC<ChatInputProps> = ({
     const backendMode = toBackendPermissionMode(
       nextMode as Exclude<ChatInputPermissionMode, 'acp' | 'reject'>,
     );
-    // An armed one-off would otherwise keep masking the session mode the user
-    // just chose, making the write look like it did nothing.
-    setTurnPermissionMode(null);
     await applySessionPermissionMode(backendMode);
   }, [
     applySessionPermissionMode,
@@ -2135,11 +2229,7 @@ export const ChatInput: React.FC<ChatInputProps> = ({
     permissionModeSaving,
   ]);
 
-  /**
-   * Arms a mode for the next submission without touching the session. Picking
-   * the already-armed mode disarms it, so an accidental arm is undoable
-   * without disturbing the session's own selection.
-   */
+  /** Updates the active turn when one exists; otherwise arms the next send. */
   const handlePermissionModeForNextTurn = useCallback(async (
     nextMode: Exclude<ChatInputPermissionMode, 'acp'>,
   ) => {
@@ -2147,13 +2237,76 @@ export const ChatInput: React.FC<ChatInputProps> = ({
     const backendMode = toBackendPermissionMode(
       nextMode as Exclude<ChatInputPermissionMode, 'acp' | 'reject'>,
     );
-    if (turnPermissionMode === backendMode) {
-      setTurnPermissionMode(null);
+    const targetTurnId = activePermissionTurnIdRef.current;
+    const currentMode = targetTurnId
+      ? activeTurnPermissionMode
+      : armedTurnPermissionMode;
+    const nextTemporaryMode = currentMode === backendMode ? null : backendMode;
+    if (
+      nextTemporaryMode === 'full_access'
+      && !(await confirmFullAccessIfNeeded(
+        nextMode,
+        targetTurnId ? 'active-turn' : 'next-turn',
+      ))
+    ) return;
+    if (
+      activePermissionTurnIdRef.current !== targetTurnId
+      || effectiveTargetSessionIdRef.current !== effectiveTargetSessionId
+    ) return;
+
+    if (!targetTurnId) {
+      setArmedTurnPermissionMode(nextTemporaryMode);
       return;
     }
-    if (!(await confirmFullAccessIfNeeded(nextMode, 'turn'))) return;
-    setTurnPermissionMode(backendMode);
-  }, [confirmFullAccessIfNeeded, isAcpTargetSession, permissionModeSaving, turnPermissionMode]);
+    if (!effectiveTargetSessionId) return;
+
+    const targetSessionId = effectiveTargetSessionId;
+    const generation = ++permissionModeRequestGenerationRef.current;
+    const previousMode = activeTurnPermissionMode;
+    setActiveTurnPermissionMode(nextTemporaryMode);
+    setPermissionModeSaving(true);
+    try {
+      const response = await agentAPI.updateActiveTurnPermissionMode({
+        sessionId: targetSessionId,
+        turnId: targetTurnId,
+        mode: nextTemporaryMode,
+        workspacePath: effectiveTargetSession?.workspacePath,
+        remoteConnectionId: effectiveTargetSession?.remoteConnectionId,
+        remoteSshHost: effectiveTargetSession?.remoteSshHost,
+      });
+      if (
+        permissionModeRequestGenerationRef.current === generation
+        && effectiveTargetSessionIdRef.current === targetSessionId
+        && activePermissionTurnIdRef.current === targetTurnId
+      ) {
+        setSessionPermissionMode(response.mode ?? null);
+        setActiveTurnPermissionMode(response.turnMode ?? null);
+      }
+    } catch (error) {
+      log.error('Failed to change active turn permission mode', error);
+      if (
+        permissionModeRequestGenerationRef.current === generation
+        && effectiveTargetSessionIdRef.current === targetSessionId
+        && activePermissionTurnIdRef.current === targetTurnId
+      ) {
+        setActiveTurnPermissionMode(previousMode);
+        notificationService.error(t('chatInput.permissionMode.changeFailed'));
+      }
+    } finally {
+      setPermissionModeSaving(false);
+    }
+  }, [
+    activeTurnPermissionMode,
+    armedTurnPermissionMode,
+    confirmFullAccessIfNeeded,
+    effectiveTargetSession?.remoteConnectionId,
+    effectiveTargetSession?.remoteSshHost,
+    effectiveTargetSession?.workspacePath,
+    effectiveTargetSessionId,
+    isAcpTargetSession,
+    permissionModeSaving,
+    t,
+  ]);
 
   // The reset row follows the user-level default, so give it a way to reach the
   // page that owns that default instead of making the user hunt for it.
@@ -2164,12 +2317,15 @@ export const ChatInput: React.FC<ChatInputProps> = ({
 
   const handleResetPermissionModeToDefault = useCallback(async () => {
     if (permissionModeSaving || isAcpTargetSession) return;
-    // Drop the armed one-off first; otherwise it would keep masking the
-    // session mode the user just asked to restore.
-    setTurnPermissionMode(null);
-    if (sessionPermissionMode === null) return;
+    if (sessionPermissionMode === null && temporaryPermissionMode === null) return;
     await applySessionPermissionMode(null);
-  }, [applySessionPermissionMode, isAcpTargetSession, permissionModeSaving, sessionPermissionMode]);
+  }, [
+    applySessionPermissionMode,
+    isAcpTargetSession,
+    permissionModeSaving,
+    sessionPermissionMode,
+    temporaryPermissionMode,
+  ]);
 
   const dispatchPermissionMode: ChatInputPermissionMode =
     permissionModeFromDispatchApprovalPolicy(
@@ -3307,11 +3463,10 @@ export const ChatInput: React.FC<ChatInputProps> = ({
           noWorkspaceMessage: t('chatInput.usageNoWorkspace'),
           failedTitle: t('chatInput.usageFailed'),
           unknownErrorMessage: t('error.unknown'),
-          loadingMarkdown: t('usage.loading.markdown'),
         },
       );
 
-      if (result.inserted) {
+      if (result.shown) {
         dispatchInput({ type: 'DEACTIVATE' });
       }
     } catch (error) {
@@ -4118,9 +4273,72 @@ export const ChatInput: React.FC<ChatInputProps> = ({
     reportModeSelectionFailure,
   );
 
+  const interruptedTurnRecovery = useMemo(
+    () => selectInterruptedTurnRecovery(effectiveTargetSession, {
+      draft: inputState.value,
+      hasComposerAttachments: contexts.length > 0,
+      executionIdle:
+        derivedState?.sendButtonMode === 'send'
+        && !caps.transferInFlight,
+      desktopRuntime: isTauriRuntime(),
+      peerMode: isPeerDeviceModeActive(),
+      acpSession: Boolean(acpSessionForInput || isAcpTargetSession),
+      modeChangePending: isModeChangePending,
+      modelChangePending: isModelSwitching,
+    }),
+    [
+      acpSessionForInput,
+      caps.transferInFlight,
+      contexts.length,
+      derivedState?.sendButtonMode,
+      effectiveTargetSession,
+      inputState.value,
+      isAcpTargetSession,
+      isModeChangePending,
+      isModelSwitching,
+    ],
+  );
+  useSyncExternalStore(
+    interruptedTurnRecoveryGate.subscribe,
+    interruptedTurnRecoveryGate.getSnapshot,
+    interruptedTurnRecoveryGate.getSnapshot,
+  );
+  const isInterruptedTurnRecoveryInFlight =
+    interruptedTurnRecoveryGate.isSessionInFlight(effectiveTargetSessionId);
+
+  const handleRecoverInterruptedTurn = useCallback(async () => {
+    const candidate = interruptedTurnRecovery;
+    if (!candidate || !interruptedTurnRecoveryGate.tryBegin(candidate)) return;
+    try {
+      await agentAPI.recoverInterruptedDialogTurn({
+        sessionId: candidate.sessionId,
+        dialogTurnId: candidate.turnId,
+        executionGeneration: candidate.executionGeneration,
+        workspacePath:
+          effectiveTargetSession?.projectWorkspacePath
+          || effectiveTargetSession?.workspacePath
+          || effectiveTargetSession?.config.projectWorkspacePath
+          || effectiveTargetSession?.config.workspacePath,
+      });
+    } catch (error) {
+      log.error('Failed to recover interrupted dialog turn', {
+        sessionId: candidate.sessionId,
+        turnId: candidate.turnId,
+        error,
+      });
+      notificationService.error(t('input.continueInterruptedFailed'));
+      interruptedTurnRecoveryGate.clearExact(candidate);
+    }
+  }, [
+    effectiveTargetSession,
+    interruptedTurnRecovery,
+    t,
+  ]);
+
   const handleSendOrCancel = useCallback(async (messageOverride?: string) => {
     if (!derivedState) return;
     if (caps.transferInFlight) return;
+    if (isInterruptedTurnRecoveryInFlight) return;
 
     const { sendButtonMode } = derivedState;
     const draftTrimmed = (messageOverride ?? inputState.value).trim();
@@ -4332,6 +4550,7 @@ export const ChatInput: React.FC<ChatInputProps> = ({
     isModelSwitching,
     isModeChangePending,
     caps.transferInFlight,
+    isInterruptedTurnRecoveryInFlight,
     inputState.value,
     derivedState,
     dispatchInput,
@@ -4379,10 +4598,11 @@ export const ChatInput: React.FC<ChatInputProps> = ({
     );
   }, [canSwitchModes, selectableCodeModes, slashCommandState.query]);
 
-  publishModeSelectionRef.current = publishModeSelection;
-  requestModeChangeRef.current = requestSessionModeChange;
-
   const requestModeChange = useCallback((modeId: string) => {
+    if (isInterruptedTurnRecoveryInFlight) {
+      dispatchMode({ type: 'CLOSE_DROPDOWN' });
+      return;
+    }
     if (!canSwitchModes) {
       dispatchMode({ type: 'CLOSE_DROPDOWN' });
       return;
@@ -4400,7 +4620,17 @@ export const ChatInput: React.FC<ChatInputProps> = ({
 
     requestSessionModeChange(modeId);
     dispatchMode({ type: 'CLOSE_DROPDOWN' });
-  }, [canSwitchModes, currentMode, effectiveTargetSessionId, requestSessionModeChange, switchableModes]);
+  }, [
+    canSwitchModes,
+    currentMode,
+    effectiveTargetSessionId,
+    isInterruptedTurnRecoveryInFlight,
+    requestSessionModeChange,
+    switchableModes,
+  ]);
+
+  publishModeSelectionRef.current = publishModeSelection;
+  requestModeChangeRef.current = requestModeChange;
 
   const toggleDefaultMode = useCallback(async (modeId: string, modeName: string) => {
     const previousDefaultModeId = userDefaultModeId;
@@ -5167,7 +5397,32 @@ export const ChatInput: React.FC<ChatInputProps> = ({
     if (!derivedState) return <span className="bitfun-chat-input__send-action" data-bf-component="chat-input" data-bf-part="sendButton" data-bf-action="send" data-bf-state="disabled"><IconButton className="bitfun-chat-input__send-button" disabled size="small"><ArrowUp size={11} /></IconButton></span>;
 
     const { sendButtonMode, hasQueuedInput } = derivedState;
-    
+
+    if (interruptedTurnRecovery) {
+      return (
+        <span
+          className="bitfun-chat-input__send-action"
+          data-bf-component="chat-input"
+          data-bf-part="sendButton"
+          data-bf-action="continue-interrupted"
+          data-bf-state={isInterruptedTurnRecoveryInFlight ? 'disabled' : undefined}
+        >
+          <IconButton
+            className="bitfun-chat-input__send-button"
+            onClick={() => void handleRecoverInterruptedTurn()}
+            disabled={isInterruptedTurnRecoveryInFlight}
+            data-testid="chat-input-continue-interrupted-btn"
+            tooltip={t('input.continueInterrupted')}
+            size="small"
+          >
+            {isInterruptedTurnRecoveryInFlight
+              ? <Loader2 size={11} className="bitfun-spin" />
+              : <Play size={11} fill="currentColor" />}
+          </IconButton>
+        </span>
+      );
+    }
+
     if (sendButtonMode === 'cancel') {
       return (
         <span className="bitfun-chat-input__send-action" data-bf-component="chat-input" data-bf-part="sendButton" data-bf-action="cancel">
@@ -5255,6 +5510,7 @@ export const ChatInput: React.FC<ChatInputProps> = ({
       <ContextDropZone
         acceptedTypes={['file', 'directory', 'image', 'code-snippet', 'mermaid-diagram']}
         className="bitfun-chat-input-drop-zone"
+        disabled={isInterruptedTurnRecoveryInFlight}
         onContextAdded={(context) => {
           if (context.type === 'image' && currentImageCount >= CHAT_INPUT_CONFIG.image.maxCount) {
             notificationService.warning(t('input.maxImagesWarning', { count: CHAT_INPUT_CONFIG.image.maxCount }), { duration: 3000 });
@@ -5394,7 +5650,7 @@ export const ChatInput: React.FC<ChatInputProps> = ({
                 onCompositionStart={handleImeCompositionStart}
                 onCompositionEnd={handleImeCompositionEnd}
                 placeholder=""
-                disabled={caps.transferInFlight}
+                disabled={caps.transferInFlight || isInterruptedTurnRecoveryInFlight}
                 contexts={contexts}
                 onRemoveContext={removeContext}
                 onMentionStateChange={setMentionState}
@@ -5407,9 +5663,10 @@ export const ChatInput: React.FC<ChatInputProps> = ({
                 isOpen={mentionState.isActive}
                 searchQuery={mentionState.query}
                 workspacePath={sessionBoundWorkspacePath}
+                remoteConnectionId={sessionBoundRemoteConnectionId}
                 workspaceId={hasRegisteredWorkspace
                   ? undefined
-                  : effectiveTargetSession?.workspaceId || workspace?.id}
+                  : effectiveTargetSession?.workspaceId || mentionWorkspace?.id}
                 excludeSessionId={effectiveTargetSessionId || undefined}
                 anchorRef={mentionAnchorRef}
                 onSelect={(context: FileContext | DirectoryContext | SessionReferenceContext) => {
@@ -5794,8 +6051,7 @@ export const ChatInput: React.FC<ChatInputProps> = ({
                           aria-label={t('chatInput.resetToAgentic')}
                           onClick={e => {
                             e.stopPropagation();
-                            requestSessionModeChange('agentic');
-                            dispatchMode({ type: 'CLOSE_DROPDOWN' });
+                            requestModeChange('agentic');
                           }}
                         >
                           <X size={12} strokeWidth={2.5} />
@@ -6107,11 +6363,12 @@ export const ChatInput: React.FC<ChatInputProps> = ({
                     externalSelection={dispatchModelSelection}
                     modeDefaultModelId={targetModeInfo?.model}
                     persistSharedModeDefault={Boolean(targetModeInfo && targetModeInfo.source !== 'external')}
+                    disabled={isInterruptedTurnRecoveryInFlight}
                   />
                   </div>
                 ) : null}
 
-                {!caps.transferInFlight ? (
+                {!caps.transferInFlight && !isInterruptedTurnRecoveryInFlight ? (
                   <ComposerVoiceInputButton controller={voiceInput} />
                 ) : null}
                 {voiceInput.phase === 'idle' ? renderActionButton() : null}
@@ -6140,13 +6397,16 @@ export const ChatInput: React.FC<ChatInputProps> = ({
             : {
                 mode: permissionMode,
                 saving: permissionModeSaving,
-                scopeLabel: turnPermissionMode
-                  ? t('chatInput.permissionMode.turnScope')
+                scopeLabel: activePermissionTurnId
+                  ? t('chatInput.permissionMode.activeTurnScope')
+                  : temporaryPermissionMode
+                    ? t('chatInput.permissionMode.turnScope')
                   : t('chatInput.permissionMode.sessionScope'),
                 overridden: permissionModeOverridden,
-                nextTurnMode: turnPermissionMode
-                  ? chatInputPermissionMode(turnPermissionMode)
+                nextTurnMode: temporaryPermissionMode
+                  ? chatInputPermissionMode(temporaryPermissionMode)
                   : null,
+                activeTurn: activePermissionTurnId !== null,
                 onChangeForNextTurn: isAcpTargetSession
                   ? undefined
                   : handlePermissionModeForNextTurn,
diff --git a/src/web-ui/src/flow_chat/components/ChatInputPixelPet.scss b/src/web-ui/src/flow_chat/components/ChatInputPixelPet.scss
index 5d323126e7..ab0ced95dd 100644
--- a/src/web-ui/src/flow_chat/components/ChatInputPixelPet.scss
+++ b/src/web-ui/src/flow_chat/components/ChatInputPixelPet.scss
@@ -765,129 +765,25 @@
   }
 }
 
-/* ---------- Reduced motion: pet always animates ----------
-   The companion pet is a functional notification surface, not decoration.
-   It must always animate so users never miss attention-required states
-   (e.g. AskUserQuestion waiting for input). These !important longhand
-   overrides counteract the global prefers-reduced-motion * rule (which
-   clamps animation-duration to 0.01ms and iteration-count to 1).
-   Longhand properties are used instead of the animation shorthand to
-   preserve animation-delay set by nth-child rules. */
+/* ---------- Reduced motion: preserve state, remove movement ----------
+   Mood-specific faces and PetDex rows continue to communicate state without
+   restoring infinite motion over the user's accessibility preference. */
 
 @media (prefers-reduced-motion: reduce) {
-  .bitfun-chat-input-pixel-pet__petdex,
-  .bitfun-chat-input-pixel-pet__petdex--rest,
-  .bitfun-chat-input-pixel-pet__petdex--working,
-  .bitfun-chat-input-pixel-pet__petdex--hover,
-  .bitfun-chat-input-pixel-pet__petdex--dragging,
-  .bitfun-panda-head,
-  .bitfun-panda-head--analyzing,
-  .bitfun-panda-head--waiting,
-  .bitfun-panda-head--working,
-  .bitfun-panda-head--hover,
-  .bitfun-panda-head--dragging,
-  .bitfun-panda-head__zzz-glyph--a,
-  .bitfun-panda-head__zzz-glyph--b,
-  .bitfun-panda-head__zzz-glyph--c,
-  .bitfun-panda-head--analyzing .bitfun-panda-head__ear--left,
-  .bitfun-panda-head--analyzing .bitfun-panda-head__ear--right,
-  .bitfun-panda-head__think-pip,
-  .bitfun-panda-head--waiting .bitfun-panda-head__paw--front,
-  .bitfun-panda-head__wait-pip,
-  .bitfun-panda-head__sweat-drop,
-  .bitfun-panda-head--working .bitfun-panda-head__ear--right,
-  .bitfun-panda-head--hover .bitfun-panda-head__ear--left,
-  .bitfun-panda-head--hover .bitfun-panda-head__ear--right,
-  .bitfun-panda-head__sparkle,
-  .bitfun-panda-head--dragging .bitfun-panda-head__paw--front,
-  .bitfun-panda-head--dragging .bitfun-panda-head__paw--rear,
-  .bitfun-panda-head__drag-line {
-    animation-iteration-count: infinite !important;
-  }
-
-  /* Single-animation elements grouped by duration */
-  .bitfun-panda-head,
-  .bitfun-panda-head__zzz-glyph--a,
-  .bitfun-panda-head__zzz-glyph--b,
-  .bitfun-panda-head__zzz-glyph--c {
-    animation-duration: 6.8s !important;
-  }
-
-  .bitfun-panda-head__think-pip,
-  .bitfun-panda-head__sweat-drop,
-  .bitfun-panda-head--working .bitfun-panda-head__ear--right {
-    animation-duration: 3.2s !important;
+  .bitfun-chat-input-pixel-pet,
+  .bitfun-chat-input-pixel-pet * {
+    animation: none !important;
   }
 
-  .bitfun-panda-head--analyzing .bitfun-panda-head__ear--left,
-  .bitfun-panda-head--analyzing .bitfun-panda-head__ear--right {
-    animation-duration: 2.8s !important;
-  }
-
-  .bitfun-panda-head__sparkle {
-    animation-duration: 2.4s !important;
-  }
-
-  .bitfun-panda-head__wait-pip {
-    animation-duration: 2.2s !important;
-  }
-
-  .bitfun-panda-head--hover .bitfun-panda-head__ear--left,
-  .bitfun-panda-head--hover .bitfun-panda-head__ear--right {
-    animation-duration: 1.9s !important;
-  }
-
-  .bitfun-panda-head--waiting .bitfun-panda-head__paw--front {
-    animation-duration: 1.8s !important;
-  }
-
-  .bitfun-panda-head__drag-line {
-    animation-duration: 1.44s !important;
-  }
-
-  .bitfun-panda-head--dragging .bitfun-panda-head__paw--front,
-  .bitfun-panda-head--dragging .bitfun-panda-head__paw--rear {
-    animation-duration: 0.96s !important;
+  .bitfun-chat-input-pixel-pet__stage,
+  .bitfun-chat-input-pixel-pet__petdex,
+  .bitfun-panda-head,
+  .bitfun-panda-head__ear,
+  .bitfun-panda-head__paw {
+    transform: none !important;
   }
 
-  /* Two-animation elements (comma-separated durations) */
   .bitfun-chat-input-pixel-pet__petdex {
-    animation-duration: 1.8s, 6s !important;
-  }
-
-  .bitfun-chat-input-pixel-pet__petdex--rest {
-    animation-duration: 2.4s, 6.4s !important;
-  }
-
-  .bitfun-chat-input-pixel-pet__petdex--working {
-    animation-duration: 1.16s, 0.56s !important;
-  }
-
-  .bitfun-chat-input-pixel-pet__petdex--hover {
-    animation-duration: 1.44s, 1.9s !important;
-  }
-
-  .bitfun-chat-input-pixel-pet__petdex--dragging {
-    animation-duration: 0.96s, 0.48s !important;
-  }
-
-  .bitfun-panda-head--analyzing {
-    animation-duration: 5.2s, 4.8s !important;
-  }
-
-  .bitfun-panda-head--waiting {
-    animation-duration: 5.2s, 6s !important;
-  }
-
-  .bitfun-panda-head--working {
-    animation-duration: 5.2s, 0.36s !important;
-  }
-
-  .bitfun-panda-head--hover {
-    animation-duration: 4.2s, 1.9s !important;
-  }
-
-  .bitfun-panda-head--dragging {
-    animation-duration: 4.8s, 0.48s !important;
+    background-position-x: 0;
   }
 }
diff --git a/src/web-ui/src/flow_chat/components/ChatInputWorkspaceStrip.scss b/src/web-ui/src/flow_chat/components/ChatInputWorkspaceStrip.scss
index 197ff30678..fe902b70a7 100644
--- a/src/web-ui/src/flow_chat/components/ChatInputWorkspaceStrip.scss
+++ b/src/web-ui/src/flow_chat/components/ChatInputWorkspaceStrip.scss
@@ -728,3 +728,9 @@
     transform: rotate(360deg);
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .bitfun-chat-input-workspace-strip__worktree-icon.is-spinning {
+    animation: none;
+  }
+}
diff --git a/src/web-ui/src/flow_chat/components/ChatInputWorkspaceStrip.test.tsx b/src/web-ui/src/flow_chat/components/ChatInputWorkspaceStrip.test.tsx
index 9a0920f504..e9be5f99e3 100644
--- a/src/web-ui/src/flow_chat/components/ChatInputWorkspaceStrip.test.tsx
+++ b/src/web-ui/src/flow_chat/components/ChatInputWorkspaceStrip.test.tsx
@@ -204,6 +204,47 @@ describe('ChatInputWorkspaceStrip git refresh behavior', () => {
     expect(onChange).toHaveBeenCalledTimes(1);
   });
 
+  it('labels one-off choices as current-turn updates while a turn is active', async () => {
+    const onChangeForNextTurn = vi.fn();
+    await act(async () => {
+      root.render(
+        <ChatInputWorkspaceStrip
+          repositoryPath=""
+          workspaceLabel=""
+          permissionControl={{
+            mode: 'ask',
+            activeTurn: true,
+            nextTurnMode: null,
+            scopeLabel: 'chatInput.permissionMode.activeTurnScope',
+            onChange: vi.fn(),
+            onChangeForNextTurn,
+          }}
+        />
+      );
+    });
+
+    const trigger = container.querySelector<HTMLButtonElement>(
+      '[data-testid="chat-input-permission-trigger"]',
+    );
+    expect(trigger?.dataset.permissionActiveTurn).toBe('true');
+    await act(async () => {
+      trigger?.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    });
+
+    const oneOff = document.querySelector<HTMLButtonElement>(
+      '[data-testid="chat-input-permission-next-turn-auto"]',
+    );
+    expect(oneOff?.textContent).toBe('chatInput.permissionMode.activeTurnOnlyShort');
+    expect(oneOff?.getAttribute('aria-label')).toBe(
+      'chatInput.permissionMode.activeTurnOnly',
+    );
+
+    await act(async () => {
+      oneOff?.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    });
+    expect(onChangeForNextTurn).toHaveBeenCalledWith('auto');
+  });
+
   it('keeps the mode descriptions out of the row and in the accessible name', async () => {
     await act(async () => {
       root.render(
diff --git a/src/web-ui/src/flow_chat/components/ChatInputWorkspaceStrip.tsx b/src/web-ui/src/flow_chat/components/ChatInputWorkspaceStrip.tsx
index d0ab7f52e7..fc3424b882 100644
--- a/src/web-ui/src/flow_chat/components/ChatInputWorkspaceStrip.tsx
+++ b/src/web-ui/src/flow_chat/components/ChatInputWorkspaceStrip.tsx
@@ -70,14 +70,14 @@ export interface ChatInputWorkspaceStripProps {
     /** Opens the settings page that owns the default this row follows. */
     onOpenDefaultSettings?: () => void;
     /**
-     * Mode armed for the next submission only, or `null` when none is.
-     * Scope is chosen per click rather than by a separate toggle, so a mode
-     * can never be written to the session by one click and then be "corrected"
-     * to one-off by a later one.
+     * Temporary one-off mode. While idle it is armed for the next submission;
+     * while a turn is active it is that turn's mutable override.
      */
     nextTurnMode?: ChatInputPermissionMode | null;
+    /** Whether `nextTurnMode` currently belongs to the active turn. */
+    activeTurn?: boolean;
     onChange?: (mode: Exclude<ChatInputPermissionMode, 'acp'>) => void | Promise<void>;
-    /** Arms the mode for the next submission; re-picking the armed one disarms it. */
+    /** Updates the one-off mode; re-picking the selected one clears it. */
     onChangeForNextTurn?: (
       mode: Exclude<ChatInputPermissionMode, 'acp'>,
     ) => void | Promise<void>;
@@ -303,14 +303,20 @@ export const ChatInputWorkspaceStrip: React.FC<ChatInputWorkspaceStripProps> = (
     ? null
     : permissionControl?.nextTurnMode ?? null;
   const permissionNextTurnArmed = permissionNextTurnMode !== null;
-  // The trigger reports what the next submission will actually run with, so an
-  // armed one-off outranks the session mode there.
+  const permissionActiveTurn = permissionMode !== 'acp' && !!permissionControl?.activeTurn;
+  // The trigger reports what the active turn (or the next submission while
+  // idle) runs with, so a one-off outranks the session mode there.
   const permissionDisplayMode = permissionNextTurnMode ?? permissionMode;
   const permissionModeLabel = permissionCopy[permissionDisplayMode].label;
   const permissionTooltip = permissionMode === 'acp'
     ? t('chatInput.permissionMode.acp.tooltip')
     : permissionNextTurnArmed
-      ? t('chatInput.permissionMode.currentTurnOverride', { mode: permissionModeLabel })
+      ? t(
+          permissionActiveTurn
+            ? 'chatInput.permissionMode.currentActiveTurnOverride'
+            : 'chatInput.permissionMode.currentTurnOverride',
+          { mode: permissionModeLabel },
+        )
       : permissionOverridden
         ? t('chatInput.permissionMode.currentSessionOverride', { mode: permissionModeLabel })
         : t('chatInput.permissionMode.current', { mode: permissionModeLabel });
@@ -472,6 +478,7 @@ export const ChatInputWorkspaceStrip: React.FC<ChatInputWorkspaceStripProps> = (
                   data-permission-mode={permissionDisplayMode}
                   data-permission-overridden={permissionOverridden ? 'true' : undefined}
                   data-permission-next-turn={permissionNextTurnArmed ? 'true' : undefined}
+                  data-permission-active-turn={permissionActiveTurn ? 'true' : undefined}
                   onClick={event => {
                     event.stopPropagation();
                     if (!permissionDisabled) {
@@ -592,7 +599,9 @@ export const ChatInputWorkspaceStrip: React.FC<ChatInputWorkspaceStripProps> = (
                             ) : null}
                             {permissionControl.onChangeForNextTurn ? (
                               <Tooltip
-                                content={t('chatInput.permissionMode.nextTurnOnly', {
+                                content={t(permissionActiveTurn
+                                  ? 'chatInput.permissionMode.activeTurnOnly'
+                                  : 'chatInput.permissionMode.nextTurnOnly', {
                                   mode: copy.label,
                                 })}
                                 placement="top"
@@ -601,7 +610,9 @@ export const ChatInputWorkspaceStrip: React.FC<ChatInputWorkspaceStripProps> = (
                                   type="button"
                                   role="menuitemcheckbox"
                                   aria-checked={armed}
-                                  aria-label={t('chatInput.permissionMode.nextTurnOnly', {
+                                  aria-label={t(permissionActiveTurn
+                                    ? 'chatInput.permissionMode.activeTurnOnly'
+                                    : 'chatInput.permissionMode.nextTurnOnly', {
                                     mode: copy.label,
                                   })}
                                   data-bf-component="chat-input-workspace-strip"
@@ -621,7 +632,9 @@ export const ChatInputWorkspaceStrip: React.FC<ChatInputWorkspaceStripProps> = (
                                     void permissionControl.onChangeForNextTurn?.(mode);
                                   }}
                                 >
-                                  {t('chatInput.permissionMode.nextTurnOnlyShort')}
+                                  {t(permissionActiveTurn
+                                    ? 'chatInput.permissionMode.activeTurnOnlyShort'
+                                    : 'chatInput.permissionMode.nextTurnOnlyShort')}
                                 </button>
                               </Tooltip>
                             ) : null}
diff --git a/src/web-ui/src/flow_chat/components/CodePreview.scss b/src/web-ui/src/flow_chat/components/CodePreview.scss
index b039343aaa..5ca8123b39 100644
--- a/src/web-ui/src/flow_chat/components/CodePreview.scss
+++ b/src/web-ui/src/flow_chat/components/CodePreview.scss
@@ -191,3 +191,9 @@
     background-color: var(--bf-appearance-token-color-overlay-black-08);
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .code-preview__cursor {
+    animation: none;
+  }
+}
diff --git a/src/web-ui/src/flow_chat/components/CopyOutputButton.css b/src/web-ui/src/flow_chat/components/CopyOutputButton.css
index 5d2f8e8cf3..31087f1914 100644
--- a/src/web-ui/src/flow_chat/components/CopyOutputButton.css
+++ b/src/web-ui/src/flow_chat/components/CopyOutputButton.css
@@ -21,7 +21,13 @@
   font-size: var(--bf-appearance-token-flowchat-font-size-xs);
   font-weight: 500;
   cursor: pointer;
-  transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
+  transition:
+    transform 120ms cubic-bezier(0.23, 1, 0.32, 1),
+    opacity 140ms ease,
+    background-color 160ms ease,
+    border-color 160ms ease,
+    color 160ms ease,
+    box-shadow 180ms ease;
   backdrop-filter: blur(8px);
   -webkit-backdrop-filter: blur(8px);
   min-width: 60px;
@@ -83,7 +89,6 @@
   font-weight: 600;
   letter-spacing: 0.3px;
   white-space: nowrap;
-  transition: all 0.2s ease;
 }
 
 @media (max-width: 768px) {
diff --git a/src/web-ui/src/flow_chat/components/CurrentSessionTitle.scss b/src/web-ui/src/flow_chat/components/CurrentSessionTitle.scss
index 1e1dab80ec..9887639a84 100644
--- a/src/web-ui/src/flow_chat/components/CurrentSessionTitle.scss
+++ b/src/web-ui/src/flow_chat/components/CurrentSessionTitle.scss
@@ -42,7 +42,11 @@
     color: var(--bf-appearance-token-color-text-muted);
     cursor: pointer;
     opacity: 1;
-    transition: all $motion-fast $easing-standard;
+    transition:
+      transform $motion-fast $easing-standard,
+      background-color $motion-fast $easing-standard,
+      color $motion-fast $easing-standard,
+      opacity $motion-fast $easing-standard;
     flex-shrink: 0;
 
     &:hover {
diff --git a/src/web-ui/src/flow_chat/components/FileMentionPicker.appearance.ts b/src/web-ui/src/flow_chat/components/FileMentionPicker.appearance.ts
index 9690ed4ec5..4061f4812d 100644
--- a/src/web-ui/src/flow_chat/components/FileMentionPicker.appearance.ts
+++ b/src/web-ui/src/flow_chat/components/FileMentionPicker.appearance.ts
@@ -10,5 +10,6 @@ export const fileMentionPickerAppearanceDescriptor: AppearanceSurfaceDescriptor
   states: [
     { id: 'selected', selector: { kind: 'self', suffix: '[data-bf-state~="selected"]' } },
     { id: 'loading', selector: { kind: 'self', suffix: '[data-bf-state~="loading"]' } },
+    { id: 'error', selector: { kind: 'self', suffix: '[data-bf-state~="error"]' } },
   ],
 };
diff --git a/src/web-ui/src/flow_chat/components/FileMentionPicker.scss b/src/web-ui/src/flow_chat/components/FileMentionPicker.scss
index e68f002e83..ed81018163 100644
--- a/src/web-ui/src/flow_chat/components/FileMentionPicker.scss
+++ b/src/web-ui/src/flow_chat/components/FileMentionPicker.scss
@@ -46,20 +46,6 @@
     font-family: var(--bf-appearance-token-font-family-sans);
   }
   
-  // Entry animation
-  animation: mentionPickerSlideUp 0.18s cubic-bezier(0.34, 1.56, 0.64, 1);
-  
-  @keyframes mentionPickerSlideUp {
-    from {
-      opacity: 0;
-      transform: translateY(12px) scale(0.96);
-    }
-    to {
-      opacity: 1;
-      transform: translateY(0) scale(1);
-    }
-  }
-  
   &__header {
     display: flex;
     align-items: center;
@@ -87,7 +73,11 @@
     border: 1px solid var(--bf-appearance-token-color-overlay-white-12);
     border-radius: 4px;
     cursor: pointer;
-    transition: all 0.15s ease;
+    transition:
+      background-color 150ms ease,
+      border-color 150ms ease,
+      color 150ms ease,
+      scale 120ms cubic-bezier(0.23, 1, 0.32, 1);
     color: var(--bf-appearance-token-color-text-muted);
     
     &:hover {
@@ -129,10 +119,10 @@
   }
   
   &__spinner {
-    animation: spin 1s linear infinite;
+    animation: file-mention-picker-spin 1s linear infinite;
     color: var(--bf-appearance-token-color-accent-500);
     
-    @keyframes spin {
+    @keyframes file-mention-picker-spin {
       from { transform: rotate(0deg); }
       to { transform: rotate(360deg); }
     }
@@ -149,7 +139,9 @@
     padding: 0.25rem var(--bf-appearance-token-flowchat-card-expanded-pad-y);
     border-radius: 4px;
     cursor: pointer;
-    transition: all 0.12s ease;
+    transition:
+      background-color 120ms ease,
+      color 120ms ease;
     
     &:hover {
       background: var(--bf-appearance-token-color-overlay-white-08);
@@ -190,6 +182,7 @@
   
   &__item-name {
     flex: 1;
+    min-width: 0;
     font-size: var(--bf-appearance-token-flowchat-font-size-sm);
     font-weight: 400;
     color: var(--bf-appearance-token-color-text-primary);
@@ -197,6 +190,11 @@
     overflow: hidden;
     text-overflow: ellipsis;
     line-height: var(--bf-appearance-token-flowchat-support-line-height);
+
+    &--with-path {
+      flex: 0 1 auto;
+      max-width: 50%;
+    }
   }
 
   &__item-detail {
@@ -208,6 +206,12 @@
     text-overflow: ellipsis;
     white-space: nowrap;
   }
+
+  &__item-path {
+    flex: 1 1 0;
+    min-width: 0;
+    max-width: none;
+  }
   
   &__expand-icon {
     flex-shrink: 0;
@@ -309,3 +313,9 @@
     }
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .file-mention-picker__spinner {
+    animation: none;
+  }
+}
diff --git a/src/web-ui/src/flow_chat/components/FileMentionPicker.tsx b/src/web-ui/src/flow_chat/components/FileMentionPicker.tsx
index 4b612fc8c9..3e7152bbf3 100644
--- a/src/web-ui/src/flow_chat/components/FileMentionPicker.tsx
+++ b/src/web-ui/src/flow_chat/components/FileMentionPicker.tsx
@@ -22,7 +22,7 @@ import {
 } from '@/infrastructure/api/service-api/ExternalSourcesAPI';
 import type {
   ExplorerNodeDto,
-  FileSearchResult,
+  FileSearchResultGroup,
 } from '@/infrastructure/api/service-api/tauri-commands';
 import type { SessionReferenceCandidate } from '@/infrastructure/api/service-api/SessionAPI';
 import type {
@@ -49,6 +49,8 @@ export interface FileMentionPickerProps {
   searchQuery: string;
   workspacePath?: string;
   workspaceId?: string;
+  /** Disambiguates identical POSIX workspace paths on different remote hosts. */
+  remoteConnectionId?: string;
   /** The composing session itself must not appear as a reference candidate. */
   excludeSessionId?: string;
   onSelect: (context: FileContext | DirectoryContext | SessionReferenceContext) => void;
@@ -63,11 +65,37 @@ type MentionItem =
   | { kind: 'file'; item: FileItem }
   | { kind: 'session'; item: SessionReferenceCandidate };
 
+function mergeFileSearchResults(
+  previous: FileItem[],
+  groups: FileSearchResultGroup[],
+  getRelativePath: (path: string) => string,
+): FileItem[] {
+  const byPath = new Map(previous.map(item => [item.path, item]));
+  for (const group of groups) {
+    const result = group.fileNameMatch;
+    if (!result) continue;
+    byPath.set(result.path, {
+      path: result.path,
+      name: result.name,
+      isDirectory: result.isDirectory || false,
+      relativePath: getRelativePath(result.path),
+    });
+  }
+
+  return Array.from(byPath.values())
+    .sort((a, b) => {
+      if (a.isDirectory !== b.isDirectory) return a.isDirectory ? -1 : 1;
+      return a.name.localeCompare(b.name);
+    })
+    .slice(0, FILE_MENTION_MAX_RESULTS);
+}
+
 export const FileMentionPicker: React.FC<FileMentionPickerProps> = ({
   isOpen,
   searchQuery,
   workspacePath,
   workspaceId,
+  remoteConnectionId,
   excludeSessionId,
   onSelect,
   onClose,
@@ -79,8 +107,11 @@ export const FileMentionPicker: React.FC<FileMentionPickerProps> = ({
   const [sessionResults, setSessionResults] = useState<SessionReferenceCandidate[]>([]);
   const [workspaceReferences, setWorkspaceReferences] = useState<WorkspaceReferenceEntry[]>([]);
   const [currentFiles, setCurrentFiles] = useState<FileItem[]>([]);
-  const [isFileLoading, setIsFileLoading] = useState(false);
+  const [isDirectoryLoading, setIsDirectoryLoading] = useState(false);
+  const [isFileSearchLoading, setIsFileSearchLoading] = useState(false);
   const [isSessionLoading, setIsSessionLoading] = useState(false);
+  const [directoryLoadError, setDirectoryLoadError] = useState(false);
+  const [fileSearchError, setFileSearchError] = useState(false);
   const [selectedIndex, setSelectedIndex] = useState(0);
   const [currentPath, setCurrentPath] = useState<string>('');
   const [pathHistory, setPathHistory] = useState<string[]>([]);
@@ -110,13 +141,19 @@ export const FileMentionPicker: React.FC<FileMentionPickerProps> = ({
   const loadDirectory = useCallback(async (dirPath: string, targetSelectedPath?: string | null) => {
     if (!workspacePath) {
       setCurrentFiles([]);
+      setIsDirectoryLoading(false);
+      setDirectoryLoadError(false);
       return;
     }
 
     const requestId = ++directoryLoadRequestIdRef.current;
-    setIsFileLoading(true);
+    setIsDirectoryLoading(true);
+    setDirectoryLoadError(false);
     try {
-      const children = await workspaceAPI.getDirectoryChildren(dirPath || workspacePath);
+      const children = await workspaceAPI.getDirectoryChildren(
+        dirPath || workspacePath,
+        remoteConnectionId,
+      );
       const items: FileItem[] = children
         .filter((entry: ExplorerNodeDto) => {
           const name = entry.name || '';
@@ -141,11 +178,14 @@ export const FileMentionPicker: React.FC<FileMentionPickerProps> = ({
       setSelectedIndex(targetIndex >= 0 ? targetIndex : 0);
     } catch (error) {
       log.error('Failed to load directory', error);
-      if (requestId === directoryLoadRequestIdRef.current) setCurrentFiles([]);
+      if (requestId === directoryLoadRequestIdRef.current) {
+        setCurrentFiles([]);
+        setDirectoryLoadError(true);
+      }
     } finally {
-      if (requestId === directoryLoadRequestIdRef.current) setIsFileLoading(false);
+      if (requestId === directoryLoadRequestIdRef.current) setIsDirectoryLoading(false);
     }
-  }, [workspacePath, getRelativePath]);
+  }, [workspacePath, remoteConnectionId, getRelativePath]);
 
   const enterDirectory = useCallback((item: FileItem) => {
     if (!item.isDirectory) return;
@@ -173,11 +213,13 @@ export const FileMentionPicker: React.FC<FileMentionPickerProps> = ({
     setCurrentFiles([]);
     setResults([]);
     setSessionResults([]);
+    setDirectoryLoadError(false);
+    setFileSearchError(false);
     setSelectedIndex(0);
     selectedItemHistoryRef.current = [];
     targetSelectedPathRef.current = null;
     loadDirectory('', null);
-  }, [isOpen, workspacePath, loadDirectory]);
+  }, [isOpen, workspacePath, remoteConnectionId, loadDirectory]);
 
   useEffect(() => {
     if (!isOpen || !workspacePath) {
@@ -218,37 +260,44 @@ export const FileMentionPicker: React.FC<FileMentionPickerProps> = ({
   ) => {
     if (!workspacePath) {
       setResults([]);
+      setIsFileSearchLoading(false);
       return;
     }
     try {
-      const searchResults = await workspaceAPI.searchFilenamesOnly(
-        workspacePath, query, false, false, false, controller.signal,
+      await workspaceAPI.searchFilenamesOnlyStreamDetailed(
+        workspacePath,
+        query,
+        false,
+        false,
+        false,
+        undefined,
+        FILE_MENTION_MAX_RESULTS,
+        true,
+        {
+          onProgress: (event) => {
+            if (
+              requestId !== fileSearchRequestIdRef.current
+              || controller.signal.aborted
+            ) return;
+
+            setResults(previous => mergeFileSearchResults(previous, event.results, getRelativePath));
+          },
+        },
+        controller.signal,
+        remoteConnectionId,
       );
-      if (requestId !== fileSearchRequestIdRef.current || controller.signal.aborted) return;
-      const items = searchResults.map((result: FileSearchResult) => ({
-        path: result.path,
-        name: result.name,
-        isDirectory: result.isDirectory || false,
-        relativePath: getRelativePath(result.path),
-      }));
-      items.sort((a, b) => {
-        if (a.isDirectory !== b.isDirectory) return a.isDirectory ? -1 : 1;
-        return a.name.localeCompare(b.name);
-      });
-      setResults(items.slice(0, FILE_MENTION_MAX_RESULTS));
-      setSelectedIndex(0);
     } catch (error) {
       if (!(error instanceof DOMException && error.name === 'AbortError')) {
         log.error('File mention search failed', error);
+        if (requestId === fileSearchRequestIdRef.current) setFileSearchError(true);
       }
-      if (requestId === fileSearchRequestIdRef.current) setResults([]);
     } finally {
       if (requestId === fileSearchRequestIdRef.current && fileAbortControllerRef.current === controller) {
         fileAbortControllerRef.current = null;
-        setIsFileLoading(false);
+        setIsFileSearchLoading(false);
       }
     }
-  }, [workspacePath, getRelativePath]);
+  }, [workspacePath, remoteConnectionId, getRelativePath]);
 
   useEffect(() => {
     if (!isOpen) return;
@@ -264,14 +313,18 @@ export const FileMentionPicker: React.FC<FileMentionPickerProps> = ({
       fileSearchRequestIdRef.current += 1;
       setResults([]);
       setSelectedIndex(0);
-      setIsFileLoading(false);
+      setIsFileSearchLoading(false);
+      setFileSearchError(false);
       return;
     }
 
     const requestId = ++fileSearchRequestIdRef.current;
     const controller = new AbortController();
     fileAbortControllerRef.current = controller;
-    setIsFileLoading(true);
+    setResults([]);
+    setSelectedIndex(0);
+    setIsFileSearchLoading(true);
+    setFileSearchError(false);
     fileSearchDebounceTimerRef.current = window.setTimeout(() => {
       fileSearchDebounceTimerRef.current = null;
       void searchFiles(query, controller, requestId);
@@ -325,6 +378,10 @@ export const FileMentionPicker: React.FC<FileMentionPickerProps> = ({
   }, [excludeSessionId, isOpen, searchQuery]);
 
   const isSearchMode = searchQuery.trim().length > 0;
+  const isFileLoading = isSearchMode ? isFileSearchLoading : isDirectoryLoading;
+  const fileLoadError = isSearchMode
+    ? (fileSearchError ? 'search' : null)
+    : (directoryLoadError ? 'directory' : null);
   const referenceItems = useMemo(
     () => workspaceReferenceItems(workspaceReferences, isSearchMode ? searchQuery : ''),
     [isSearchMode, searchQuery, workspaceReferences],
@@ -472,7 +529,7 @@ export const FileMentionPicker: React.FC<FileMentionPickerProps> = ({
   useEffect(() => {
     if (!containerRef.current || displayItems.length === 0) return;
     containerRef.current.querySelector(`[data-index="${selectedIndex}"]`)
-      ?.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
+      ?.scrollIntoView({ block: 'nearest', behavior: 'auto' });
   }, [displayItems.length, selectedIndex]);
 
   if (!isOpen) return null;
@@ -509,7 +566,13 @@ export const FileMentionPicker: React.FC<FileMentionPickerProps> = ({
         )}
       </div>
       <div data-bf-component="file-mention-picker" data-bf-part="content" className="file-mention-picker__content">
-        {displayItems.length === 0 && isLoading ? (
+        {displayItems.length === 0 && fileLoadError ? (
+          <div data-bf-component="file-mention-picker" data-bf-part="empty" data-bf-state="error" className="file-mention-picker__empty">
+            <span>{t(fileLoadError === 'search'
+              ? 'fileMention.searchUnavailable'
+              : 'fileMention.browseUnavailable')}</span>
+          </div>
+        ) : displayItems.length === 0 && isLoading ? (
           <div data-bf-component="file-mention-picker" data-bf-part="loading" className="file-mention-picker__loading"><Loader2 size={14} className="file-mention-picker__spinner" /><span>{t('fileMention.loading')}</span></div>
         ) : displayItems.length === 0 ? (
           <div data-bf-component="file-mention-picker" data-bf-part="empty" className="file-mention-picker__empty"><span>{isSearchMode ? t('fileMention.noMatchingFiles') : t('fileMention.emptyDirectory')}</span></div>
@@ -536,8 +599,24 @@ export const FileMentionPicker: React.FC<FileMentionPickerProps> = ({
                   onMouseEnter={() => setSelectedIndex(index)}
                 >
                   {isSession ? <MessageCircle size={13} className="file-mention-picker__icon file-mention-picker__icon--session" /> : file?.isDirectory ? <Folder size={13} className="file-mention-picker__icon file-mention-picker__icon--folder" /> : <File size={13} className="file-mention-picker__icon file-mention-picker__icon--file" />}
-                  <span data-bf-component="file-mention-picker" data-bf-part="itemName" className="file-mention-picker__item-name">{session?.sessionName ?? file?.name}</span>
+                  <span
+                    data-bf-component="file-mention-picker"
+                    data-bf-part="itemName"
+                    className={`file-mention-picker__item-name${file && !file.referenceStableKey ? ' file-mention-picker__item-name--with-path' : ''}`}
+                  >
+                    {session?.sessionName ?? file?.name}
+                  </span>
                   {session && <span data-bf-component="file-mention-picker" data-bf-part="itemDetail" className="file-mention-picker__item-detail">{session.workspaceLabel}</span>}
+                  {file && !file.referenceStableKey && (
+                    <span
+                      data-bf-component="file-mention-picker"
+                      data-bf-part="itemDetail"
+                      className="file-mention-picker__item-detail file-mention-picker__item-path"
+                      title={file.relativePath}
+                    >
+                      {file.relativePath}
+                    </span>
+                  )}
                   {file?.referenceStableKey && (
                     <span data-bf-component="file-mention-picker" data-bf-part="itemDetail" className="file-mention-picker__item-detail">
                       {file.referenceDescription || file.path}
@@ -547,6 +626,19 @@ export const FileMentionPicker: React.FC<FileMentionPickerProps> = ({
                 </div>
               );
             })}
+            {isLoading && (
+              <div data-bf-component="file-mention-picker" data-bf-part="loading" className="file-mention-picker__loading">
+                <Loader2 size={14} className="file-mention-picker__spinner" />
+                <span>{t('fileMention.loading')}</span>
+              </div>
+            )}
+            {fileLoadError && (
+              <div data-bf-component="file-mention-picker" data-bf-part="empty" data-bf-state="error" className="file-mention-picker__empty">
+                <span>{t(fileLoadError === 'search'
+                  ? 'fileMention.searchUnavailable'
+                  : 'fileMention.browseUnavailable')}</span>
+              </div>
+            )}
           </div>
         )}
       </div>
diff --git a/src/web-ui/src/flow_chat/components/FileMentionPickerOverlay.test.tsx b/src/web-ui/src/flow_chat/components/FileMentionPickerOverlay.test.tsx
index 9458b138f5..61488d7728 100644
--- a/src/web-ui/src/flow_chat/components/FileMentionPickerOverlay.test.tsx
+++ b/src/web-ui/src/flow_chat/components/FileMentionPickerOverlay.test.tsx
@@ -3,6 +3,7 @@
 import React, { act, useRef } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { workspaceAPI } from '@/infrastructure/api';
 import { FileMentionPicker } from './FileMentionPicker';
 
 globalThis.IS_REACT_ACT_ENVIRONMENT = true;
@@ -21,7 +22,13 @@ vi.mock('@/infrastructure/api', () => ({
   },
   workspaceAPI: {
     getDirectoryChildren: vi.fn().mockResolvedValue([]),
-    searchFilenamesOnly: vi.fn().mockResolvedValue([]),
+    searchFilenamesOnlyStreamDetailed: vi.fn().mockResolvedValue({
+      searchId: 'search-1',
+      searchKind: 'filenames',
+      limit: 30,
+      truncated: false,
+      totalResults: 0,
+    }),
   },
 }));
 
@@ -31,15 +38,19 @@ vi.mock('@/infrastructure/api/service-api/ExternalSourcesAPI', () => ({
   },
 }));
 
-const Harness: React.FC = () => {
+const Harness: React.FC<{
+  searchQuery?: string;
+  remoteConnectionId?: string;
+}> = ({ searchQuery = '', remoteConnectionId = 'remote-connection-1' }) => {
   const anchorRef = useRef<HTMLButtonElement>(null);
   return (
     <div>
       <button ref={anchorRef} type="button">anchor</button>
       <FileMentionPicker
         isOpen
-        searchQuery=""
+        searchQuery={searchQuery}
         workspacePath="/workspace"
+        remoteConnectionId={remoteConnectionId}
         anchorRef={anchorRef}
         onSelect={vi.fn()}
         onClose={vi.fn()}
@@ -53,12 +64,14 @@ describe('FileMentionPicker overlay', () => {
   let root: Root;
 
   beforeEach(() => {
+    Element.prototype.scrollIntoView = vi.fn();
     container = document.createElement('div');
     document.body.appendChild(container);
     root = createRoot(container);
   });
 
   afterEach(() => {
+    vi.useRealTimers();
     act(() => root.unmount());
     document.querySelector('[data-bf-overlay-host="true"]')?.remove();
     container.remove();
@@ -74,5 +87,135 @@ describe('FileMentionPicker overlay', () => {
     const picker = document.querySelector<HTMLElement>('.file-mention-picker--overlay');
     expect(picker?.parentElement?.getAttribute('data-bf-overlay-host')).toBe('true');
     expect(picker?.style.visibility).toBe('visible');
+    expect(workspaceAPI.getDirectoryChildren).toHaveBeenCalledWith(
+      '/workspace',
+      'remote-connection-1',
+    );
+  });
+
+  it('shows the workspace-relative path after the file name', async () => {
+    vi.mocked(workspaceAPI.getDirectoryChildren).mockResolvedValueOnce([
+      {
+        path: '/workspace/src/App.tsx',
+        name: 'App.tsx',
+        isDirectory: false,
+      },
+    ]);
+
+    await act(async () => {
+      root.render(<Harness />);
+      await Promise.resolve();
+    });
+
+    const item = document.querySelector('[data-bf-part="item"]');
+    const itemName = item?.querySelector('[data-bf-part="itemName"]');
+    const itemPath = item?.querySelector('[data-bf-part="itemDetail"]');
+    expect(itemName?.textContent).toBe('App.tsx');
+    expect(itemName?.classList.contains('file-mention-picker__item-name--with-path')).toBe(true);
+    expect(itemPath?.textContent).toBe('src/App.tsx');
+    expect(itemPath?.classList.contains('file-mention-picker__item-path')).toBe(true);
+  });
+
+  it('does not present a remote browse failure as an empty directory', async () => {
+    vi.mocked(workspaceAPI.getDirectoryChildren).mockRejectedValueOnce(
+      new Error('remote connection unavailable'),
+    );
+
+    await act(async () => {
+      root.render(<Harness />);
+      await Promise.resolve();
+    });
+
+    expect(document.querySelector('[data-bf-part="empty"][data-bf-state~="error"]')?.textContent)
+      .toBe('fileMention.browseUnavailable');
+    expect(document.querySelector('[data-bf-part="empty"]:not([data-bf-state~="error"])')).toBeNull();
+  });
+
+  it('shows streamed remote matches before the recursive search completes', async () => {
+    vi.useFakeTimers();
+    let reportProgress: ((event: {
+      searchId: string;
+      searchKind: 'filenames';
+      results: Array<{
+        path: string;
+        name: string;
+        isDirectory: boolean;
+        fileNameMatch: {
+          path: string;
+          name: string;
+          isDirectory: boolean;
+          matchType: 'fileName';
+        };
+        contentMatches: [];
+      }>;
+    }) => void) | undefined;
+    let finishSearch: (() => void) | undefined;
+
+    vi.mocked(workspaceAPI.searchFilenamesOnlyStreamDetailed).mockImplementationOnce((
+      _rootPath,
+      _pattern,
+      _caseSensitive,
+      _useRegex,
+      _wholeWord,
+      _searchIdOrSignal,
+      _maxResults,
+      _includeDirectories,
+      callbacks,
+    ) => {
+      reportProgress = callbacks.onProgress;
+      return new Promise(resolve => {
+        finishSearch = () => resolve({
+          searchId: 'search-remote-1',
+          searchKind: 'filenames',
+          limit: 30,
+          truncated: false,
+          totalResults: 1,
+        });
+      });
+    });
+
+    await act(async () => {
+      root.render(<Harness searchQuery="手写" />);
+      await Promise.resolve();
+    });
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(300);
+    });
+
+    expect(workspaceAPI.searchFilenamesOnlyStreamDetailed).toHaveBeenCalled();
+    expect(
+      vi.mocked(workspaceAPI.searchFilenamesOnlyStreamDetailed).mock.calls[0]?.[10],
+    ).toBe('remote-connection-1');
+
+    await act(async () => {
+      reportProgress?.({
+        searchId: 'search-remote-1',
+        searchKind: 'filenames',
+        results: [{
+          path: '/workspace/手写笔画标注项目',
+          name: '手写笔画标注项目',
+          isDirectory: true,
+          fileNameMatch: {
+            path: '/workspace/手写笔画标注项目',
+            name: '手写笔画标注项目',
+            isDirectory: true,
+            matchType: 'fileName',
+          },
+          contentMatches: [],
+        }],
+      });
+      await Promise.resolve();
+    });
+
+    expect(document.querySelector('[data-bf-part="itemName"]')?.textContent)
+      .toBe('手写笔画标注项目');
+    expect(document.querySelector('[data-bf-part="root"]')?.getAttribute('data-bf-state'))
+      .toBe('loading');
+
+    await act(async () => {
+      finishSearch?.();
+      await Promise.resolve();
+    });
+    vi.useRealTimers();
   });
 });
diff --git a/src/web-ui/src/flow_chat/components/FlowItemRenderer.tsx b/src/web-ui/src/flow_chat/components/FlowItemRenderer.tsx
deleted file mode 100644
index 3a41a47c8e..0000000000
--- a/src/web-ui/src/flow_chat/components/FlowItemRenderer.tsx
+++ /dev/null
@@ -1,97 +0,0 @@
-/**
- * Streaming item renderer
- * Dispatches to the right component by item type
- * Uses React.memo to avoid unnecessary re-renders
- */
-
-import React from 'react';
-import { FlowItem, FlowTextItem, FlowToolItem, FlowThinkingItem, FlowUserSteeringItem, type ToolRejectOptions } from '../types/flow-chat';
-import { FlowTextBlock } from './FlowTextBlock';
-import { FlowToolCard } from './FlowToolCard';
-import { ModelThinkingDisplay } from '../tool-cards/ModelThinkingDisplay';
-import { UserSteeringBubble } from './UserSteeringBubble';
-
-interface FlowItemRendererProps {
-  item: FlowItem;
-  onFileViewRequest?: (filePath: string) => void;
-  onTabOpen?: (tabInfo: any) => void;
-  onConfirm?: (toolId: string, permissionOptionId?: string, approve?: boolean) => void;
-  onReject?: (toolId: string, options?: ToolRejectOptions) => void;
-  sessionId?: string;
-}
-
-const FlowItemRendererComponent: React.FC<FlowItemRendererProps> = ({
-  item,
-  onFileViewRequest,
-  onTabOpen,
-  onConfirm,
-  onReject,
-  sessionId
-}) => {
-  if (item.type === 'text') {
-    const textItem = item as FlowTextItem;
-    return <FlowTextBlock textItem={textItem} />;
-  }
-  
-  if (item.type === 'thinking') {
-    return <ModelThinkingDisplay thinkingItem={item as FlowThinkingItem} />;
-  }
-  
-  if (item.type === 'user-steering') {
-    return <UserSteeringBubble item={item as FlowUserSteeringItem} />;
-  }
-
-  if (item.type === 'tool') {
-    const toolItem = item as FlowToolItem;
-    return (
-      <div className="flowchat-tool-wrapper">
-        <FlowToolCard
-          toolItem={toolItem}
-          onConfirm={onConfirm}
-          onReject={onReject}
-          onOpenInEditor={onFileViewRequest}
-          onOpenInPanel={onTabOpen}
-          sessionId={sessionId}
-        />
-      </div>
-    );
-  }
-  
-  return null;
-};
-
-// Key optimization: React.memo
-export const FlowItemRenderer = React.memo(
-  FlowItemRendererComponent,
-  (prev, next) => {
-    // Re-render if ID changes
-    if (prev.item.id !== next.item.id) return false;
-    
-    // Re-render if status changes
-    if (prev.item.status !== next.item.status) return false;
-    
-    // Compare text content for text items
-    if (prev.item.type === 'text' && next.item.type === 'text') {
-      const prevText = prev.item as FlowTextItem;
-      const nextText = next.item as FlowTextItem;
-      return prevText.content === nextText.content &&
-             prevText.isStreaming === nextText.isStreaming;
-    }
-    
-    // Compare tool results and streaming params for tool items
-    if (prev.item.type === 'tool' && next.item.type === 'tool') {
-      const prevTool = prev.item as FlowToolItem;
-      const nextTool = next.item as FlowToolItem;
-      // Compare streaming params to re-render when they update
-      return prevTool.toolResult === nextTool.toolResult &&
-             prevTool.interruptionReason === nextTool.interruptionReason &&
-             prevTool.acpPermission === nextTool.acpPermission &&
-             prevTool.isParamsStreaming === nextTool.isParamsStreaming &&
-             JSON.stringify(prevTool.partialParams) === JSON.stringify(nextTool.partialParams);
-    }
-    
-    return true;
-  }
-);
-
-FlowItemRenderer.displayName = 'FlowItemRenderer';
diff --git a/src/web-ui/src/flow_chat/components/ImageAnalysisCard.scss b/src/web-ui/src/flow_chat/components/ImageAnalysisCard.scss
index a947559cc8..726f4af178 100644
--- a/src/web-ui/src/flow_chat/components/ImageAnalysisCard.scss
+++ b/src/web-ui/src/flow_chat/components/ImageAnalysisCard.scss
@@ -19,7 +19,9 @@
   border-radius: 8px;
   padding: 12px;
   margin: 8px 0;
-  transition: all 0.2s ease;
+  transition:
+    background-color 180ms ease,
+    border-color 180ms ease;
   
   &[data-status="analyzing"] {
     border-color: var(--image-analysis-primary);
@@ -30,7 +32,7 @@
       var(--image-analysis-surface) 100%
     );
     background-size: 200% 100%;
-    animation: shimmer 2s infinite;
+    animation: image-analysis-shimmer 2s linear infinite;
   }
   
   &[data-status="completed"] {
@@ -42,7 +44,7 @@
   }
 }
 
-@keyframes shimmer {
+@keyframes image-analysis-shimmer {
   0% {
     background-position: -200% 0;
   }
@@ -106,7 +108,7 @@
     color: var(--image-analysis-primary);
     
     .spinner {
-      animation: spin 1s linear infinite;
+      animation: image-analysis-spin 1s linear infinite;
     }
   }
   
@@ -140,7 +142,7 @@
   }
 }
 
-@keyframes spin {
+@keyframes image-analysis-spin {
   from {
     transform: rotate(0deg);
   }
@@ -149,6 +151,13 @@
   }
 }
 
+@media (prefers-reduced-motion: reduce) {
+  .image-analysis-card[data-status="analyzing"],
+  .image-analysis-card__status.analyzing .spinner {
+    animation: none;
+  }
+}
+
 .image-analysis-card__content {
   margin-top: 12px;
   padding-top: 12px;
@@ -272,4 +281,3 @@
   --image-analysis-success: var(--bf-appearance-token-color-success);
   --image-analysis-error: var(--bf-appearance-token-color-error);
 }
-
diff --git a/src/web-ui/src/flow_chat/components/ModelSelector.scss b/src/web-ui/src/flow_chat/components/ModelSelector.scss
index add70a7342..f45201e70d 100644
--- a/src/web-ui/src/flow_chat/components/ModelSelector.scss
+++ b/src/web-ui/src/flow_chat/components/ModelSelector.scss
@@ -135,6 +135,8 @@
   // ==================== Dropdown menu ====================
   
   &__dropdown {
+    --bitfun-model-dropdown-offset: -4px;
+
     position: fixed;
     min-width: clamp(0px, 220px, calc(100vw - 16px));
     max-width: clamp(0px, 280px, calc(100vw - 16px));
@@ -152,7 +154,32 @@
       0 0 1px var(--bf-appearance-token-color-overlay-white-12),
       inset 0 1px 0 var(--bf-appearance-token-color-overlay-white-08);
     z-index: $z-popover;
-    animation: bitfun-model-dropdown-fade-in 0.15s ease-out;
+    transform-origin: center top;
+    transition:
+      opacity 100ms ease,
+      transform 120ms cubic-bezier(0.23, 1, 0.32, 1);
+
+    &[data-open='true']:not([data-keyboard-open='true']) {
+      @starting-style {
+        opacity: 0;
+        transform: translateY(var(--bitfun-model-dropdown-offset)) scale(0.98);
+      }
+    }
+
+    &[data-placement='top'] {
+      --bitfun-model-dropdown-offset: 4px;
+      transform-origin: center bottom;
+    }
+
+    &[data-open='false'] {
+      opacity: 0;
+      transform: translateY(var(--bitfun-model-dropdown-offset)) scale(0.98);
+      pointer-events: none;
+    }
+
+    &[data-keyboard-open='true'] {
+      transition: none;
+    }
   }
   
   &__dropdown-header {
@@ -362,18 +389,6 @@
   }
 }
 
-// Dropdown fade-in animation
-@keyframes bitfun-model-dropdown-fade-in {
-  from {
-    opacity: 0;
-    transform: translateY(4px) scale(0.98);
-  }
-  to {
-    opacity: 1;
-    transform: translateY(0);
-  }
-}
-
 @keyframes bitfun-ctx-critical-pulse {
   0%, 100% { opacity: 0.8; }
   50%       { opacity: 1; }
diff --git a/src/web-ui/src/flow_chat/components/ModelSelector.tsx b/src/web-ui/src/flow_chat/components/ModelSelector.tsx
index f4562b5737..678e6239aa 100644
--- a/src/web-ui/src/flow_chat/components/ModelSelector.tsx
+++ b/src/web-ui/src/flow_chat/components/ModelSelector.tsx
@@ -28,6 +28,7 @@ import {
 import { globalEventBus } from '@/infrastructure/event-bus';
 import type { AIModelConfig, AgentModelDefaultsConfig, DefaultModelsConfig } from '@/infrastructure/config/types';
 import { Switch, Tooltip } from '@/component-library';
+import { PresenceBoundary } from '@/component-library/components/PresenceBoundary';
 import { notificationService } from '@/shared/notification-system';
 import { FlowChatStore } from '../store/FlowChatStore';
 import { getModelMaxTokens } from '../services/flow-chat-manager/SessionModule';
@@ -36,6 +37,7 @@ import {
   buildAcpFastModeValue,
   getAcpModelProviderName,
   resolveAcpFastModeState,
+  resolveAcpModeState,
   resolveAcpReasoningState,
 } from '../utils/acpSessionConfig';
 import { sessionProjectWorkspacePath } from '../utils/sessionWorkspace';
@@ -44,7 +46,7 @@ import {
   type ContextUsageSource,
 } from '../utils/tokenUsageDisplay';
 import { createLogger } from '@/shared/utils/logger';
-import { getModelSelectorDropdownStyle } from './modelSelectorDropdownPosition';
+import { getModelSelectorDropdownLayout } from './modelSelectorDropdownPosition';
 import { ReasoningPresetSelector } from './ReasoningPresetSelector';
 import {
   getRecentReasoningPreset,
@@ -106,6 +108,8 @@ interface ModelSelectorProps {
   modeDefaultModelId?: string;
   /** Whether a selection also changes BitFun's shared built-in mode default. */
   persistSharedModeDefault?: boolean;
+  /** Whether lifecycle ownership currently prevents Session setting changes. */
+  disabled?: boolean;
 }
 
 interface ModelInfo {
@@ -245,6 +249,7 @@ export const ModelSelector: React.FC<ModelSelectorProps> = ({
   externalSelection,
   modeDefaultModelId,
   persistSharedModeDefault = true,
+  disabled = false,
 }) => {
   const { t } = useTranslation('flow-chat');
   const [allModels, setAllModels] = useState<AIModelConfig[]>([]);
@@ -272,6 +277,7 @@ export const ModelSelector: React.FC<ModelSelectorProps> = ({
     position: 'fixed',
     visibility: 'hidden',
   });
+  const [resolvedDropdownPlacement, setResolvedDropdownPlacement] = useState(dropdownPlacement);
   const activeSession = sessionId ? FlowChatStore.getInstance().getState().sessions.get(sessionId) : undefined;
   const sessionReasoningPreset = useSyncExternalStore(
     useCallback(
@@ -440,6 +446,7 @@ export const ModelSelector: React.FC<ModelSelectorProps> = ({
       if (dropdownRef.current && !dropdownRef.current.contains(target)
           && portalDropdownRef.current && !portalDropdownRef.current.contains(target)) {
         setDropdownOpen(false);
+        setKeyboardNavigationOpen(false);
       }
     };
 
@@ -460,12 +467,14 @@ export const ModelSelector: React.FC<ModelSelectorProps> = ({
       if (!dropdownRef.current || !portalDropdownRef.current) return;
       const anchorRect = dropdownRef.current.getBoundingClientRect();
       const dropdownRect = portalDropdownRef.current.getBoundingClientRect();
-      setDropdownStyle(getModelSelectorDropdownStyle(
+      const layout = getModelSelectorDropdownLayout(
         anchorRect,
         dropdownRect,
         dropdownPlacement,
         { width: window.innerWidth, height: window.innerHeight },
-      ));
+      );
+      setDropdownStyle(layout.style);
+      setResolvedDropdownPlacement(layout.placement);
     };
 
     updatePosition();
@@ -599,6 +608,10 @@ export const ModelSelector: React.FC<ModelSelectorProps> = ({
     () => resolveAcpReasoningState(acpOptions?.configOptions ?? []),
     [acpOptions?.configOptions],
   );
+  const acpMode = useMemo(
+    () => resolveAcpModeState(acpOptions?.configOptions ?? []),
+    [acpOptions?.configOptions],
+  );
 
   const getCurrentModelId = useCallback((): string => {
     // Session-owned model takes priority so that each session remembers
@@ -727,8 +740,11 @@ export const ModelSelector: React.FC<ModelSelectorProps> = ({
   }, [defaultModels, modelCatalog]);
 
   const handleSelectModel = useCallback(async (modelId: string) => {
-    if (loading || reasoningLoading) return;
+    if (disabled || loading || reasoningLoading) return;
 
+    if (portalDropdownRef.current?.contains(document.activeElement)) {
+      triggerRef.current?.focus();
+    }
     setLoading(true);
     setDropdownOpen(false);
 
@@ -830,6 +846,7 @@ export const ModelSelector: React.FC<ModelSelectorProps> = ({
     acpClientId,
     currentMode,
     defaultModels,
+    disabled,
     externalSelection,
     isAcpSession,
     loading,
@@ -843,7 +860,8 @@ export const ModelSelector: React.FC<ModelSelectorProps> = ({
 
   const handleSelectReasoningPreset = useCallback(async (presetId: string | null) => {
     if (
-      loading
+      disabled
+      || loading
       || reasoningLoading
       || !sessionId
       || !concreteModelId
@@ -898,6 +916,7 @@ export const ModelSelector: React.FC<ModelSelectorProps> = ({
     concreteModelId,
     currentNativeModelId,
     currentReasoningProjection,
+    disabled,
     loading,
     reasoningLoading,
     sessionId,
@@ -906,7 +925,7 @@ export const ModelSelector: React.FC<ModelSelectorProps> = ({
   ]);
 
   const handleSetAcpFastMode = useCallback(async (enabled: boolean) => {
-    if (loading || !acpFastMode || !acpClientId || !sessionId) return;
+    if (disabled || loading || !acpFastMode || !acpClientId || !sessionId) return;
     const value = buildAcpFastModeValue(acpFastMode.option, enabled);
     if (!value) return;
 
@@ -936,12 +955,13 @@ export const ModelSelector: React.FC<ModelSelectorProps> = ({
     activeSession?.workspacePath,
     acpClientId,
     acpFastMode,
+    disabled,
     loading,
     sessionId,
   ]);
 
   const handleSelectAcpReasoning = useCallback(async (presetId: string | null) => {
-    if (loading || !presetId || !acpReasoning || !acpClientId || !sessionId) return;
+    if (disabled || loading || !presetId || !acpReasoning || !acpClientId || !sessionId) return;
     setReasoningLoading(true);
     try {
       const options = await ACPClientAPI.setSessionConfigOption({
@@ -969,6 +989,45 @@ export const ModelSelector: React.FC<ModelSelectorProps> = ({
     activeSession?.workspacePath,
     acpClientId,
     acpReasoning,
+    disabled,
+    loading,
+    sessionId,
+    t,
+  ]);
+
+  const handleSelectAcpMode = useCallback(async (value: string) => {
+    if (loading || !acpMode || !acpClientId || !sessionId) return;
+    // A locked picker is disabled in the UI; refusing here too keeps a stray
+    // keyboard activation from asking the agent for something it will refuse.
+    if (acpMode.locked || acpMode.currentValue === value) return;
+
+    setLoading(true);
+    try {
+      const options = await ACPClientAPI.setSessionConfigOption({
+        sessionId,
+        clientId: acpClientId,
+        workspacePath: activeSession?.workspacePath || activeSession?.config.workspacePath,
+        remoteConnectionId: activeSession?.remoteConnectionId,
+        remoteSshHost: activeSession?.remoteSshHost,
+        configId: acpMode.option.id,
+        value: { type: 'select', value },
+      });
+      setAcpOptions(options);
+      syncAcpContextUsageToStore(sessionId, options);
+      log.info('ACP session mode updated', { sessionId, acpClientId, value });
+    } catch (error) {
+      log.error('Failed to update ACP session mode', error);
+      notificationService.error(t('modelSelector.acpModeFailed'));
+    } finally {
+      setLoading(false);
+    }
+  }, [
+    activeSession?.config.workspacePath,
+    activeSession?.remoteConnectionId,
+    activeSession?.remoteSshHost,
+    activeSession?.workspacePath,
+    acpClientId,
+    acpMode,
     loading,
     sessionId,
     t,
@@ -988,16 +1047,14 @@ export const ModelSelector: React.FC<ModelSelectorProps> = ({
     if (event.key === 'Escape' && dropdownOpen) {
       event.preventDefault();
       setDropdownOpen(false);
-      setKeyboardNavigationOpen(false);
     }
   }, [dropdownOpen, isAcpSession, loadAcpOptions]);
 
   const handleDropdownKeyDown = useCallback((event: React.KeyboardEvent<HTMLDivElement>) => {
     if (event.key === 'Escape') {
       event.preventDefault();
-      setDropdownOpen(false);
-      setKeyboardNavigationOpen(false);
       triggerRef.current?.focus();
+      setDropdownOpen(false);
       return;
     }
 
@@ -1039,6 +1096,12 @@ export const ModelSelector: React.FC<ModelSelectorProps> = ({
     return () => window.cancelAnimationFrame(frameId);
   }, [dropdownOpen, keyboardNavigationOpen]);
 
+  useEffect(() => {
+    if (!dropdownOpen && keyboardNavigationOpen) {
+      triggerRef.current?.focus();
+    }
+  }, [dropdownOpen, keyboardNavigationOpen]);
+
   const tokenPercentage = useMemo(() => {
     if (!maxTokens || maxTokens <= 0 || !currentTokens) return 0;
     return Math.min(Math.round((currentTokens / maxTokens) * 100), 100);
@@ -1063,7 +1126,7 @@ export const ModelSelector: React.FC<ModelSelectorProps> = ({
         ref={dropdownRef}
         className={`bitfun-model-selector ${className}`}
       >
-        <Tooltip content={getModelTooltipText(
+        <Tooltip disabled={dropdownOpen} content={getModelTooltipText(
           externalCurrentModel,
           externalSelection.providerLabel,
         )}>
@@ -1078,10 +1141,14 @@ export const ModelSelector: React.FC<ModelSelectorProps> = ({
             onKeyDown={handleTriggerKeyDown}
             onClick={(event) => {
               const nextOpen = !dropdownOpen;
-              setKeyboardNavigationOpen(nextOpen && event.detail === 0);
+              if (nextOpen) {
+                setKeyboardNavigationOpen(event.detail === 0);
+              } else if (event.detail !== 0) {
+                setKeyboardNavigationOpen(false);
+              }
               setDropdownOpen(nextOpen);
             }}
-            disabled={loading || externalSelection.disabled}
+            disabled={disabled || loading || externalSelection.disabled}
           >
             <span className="bitfun-model-selector__name">
               {getModelDisplayLabel(externalCurrentModel, externalCurrentModelId)}
@@ -1096,22 +1163,26 @@ export const ModelSelector: React.FC<ModelSelectorProps> = ({
             selectedPreset={externalSelection.selectedReasoningPreset === 'auto'
               ? undefined
               : externalSelection.selectedReasoningPreset}
-            disabled={externalSelection.disabled}
+            disabled={disabled || externalSelection.disabled}
             loading={false}
             dropdownPlacement={dropdownPlacement}
             onSelect={externalSelection.onSelectReasoningPreset}
           />
         )}
 
-        {dropdownOpen && createPortal(
-          <div
+        <PresenceBoundary active={dropdownOpen}>
+          {createPortal(
+            <div
             id={menuId}
             className="bitfun-model-selector__dropdown"
             ref={portalDropdownRef}
             style={dropdownStyle}
             data-testid="chat-model-selector-menu"
             data-keyboard-open={keyboardNavigationOpen ? 'true' : 'false'}
-            data-placement={dropdownPlacement}
+            data-placement={resolvedDropdownPlacement}
+            data-open={dropdownOpen ? 'true' : 'false'}
+            aria-hidden={!dropdownOpen}
+            {...(!dropdownOpen ? { inert: '' } : {})}
             role="menu"
             aria-label={t('modelSelector.modelSelection')}
             onKeyDown={handleDropdownKeyDown}
@@ -1151,20 +1222,30 @@ export const ModelSelector: React.FC<ModelSelectorProps> = ({
                 );
               })}
             </div>
-          </div>,
-          document.body,
-        )}
+            </div>,
+            document.body,
+          )}
+        </PresenceBoundary>
       </div>
     );
   }
 
   if (isAcpSession) {
-    if (acpAvailableModels.length === 0) {
+    // An agent may offer models, a mode, or both. dsh-acp offers only a mode,
+    // so returning early on an empty model list would hide its picker entirely.
+    if (acpAvailableModels.length === 0 && !acpMode) {
       return null;
     }
 
     const currentAcpModelId = acpOptions?.currentModelId || acpAvailableModels[0]?.id || '';
-    const acpBaseTooltip = getModelTooltipText(acpCurrentModel, acpClientId ? `${acpClientId} ACP` : 'ACP');
+    const acpModeLabel = acpMode
+      ? (acpMode.option.options.find(candidate => candidate.value === acpMode.currentValue)?.name
+        ?? acpMode.currentValue)
+      : '';
+    const acpModeOnly = acpAvailableModels.length === 0 && acpMode !== null;
+    const acpBaseTooltip = acpModeOnly
+      ? (acpMode?.option.description ?? `${acpMode?.option.name ?? ''}: ${acpModeLabel}`)
+      : getModelTooltipText(acpCurrentModel, acpClientId ? `${acpClientId} ACP` : 'ACP');
     const acpTooltip = buildContextUsageTooltip({
       baseTooltip: acpBaseTooltip,
       usage: {
@@ -1180,7 +1261,7 @@ export const ModelSelector: React.FC<ModelSelectorProps> = ({
         ref={dropdownRef}
         className={`bitfun-model-selector ${className}`}
       >
-        <Tooltip content={acpTooltip}>
+        <Tooltip content={acpTooltip} disabled={dropdownOpen}>
           <button
             ref={triggerRef}
             data-testid="chat-model-selector-btn"
@@ -1192,16 +1273,20 @@ export const ModelSelector: React.FC<ModelSelectorProps> = ({
             onKeyDown={handleTriggerKeyDown}
             onClick={(event) => {
               const nextOpen = !dropdownOpen;
-              setKeyboardNavigationOpen(nextOpen && event.detail === 0);
+              if (nextOpen) {
+                setKeyboardNavigationOpen(event.detail === 0);
+              } else if (event.detail !== 0) {
+                setKeyboardNavigationOpen(false);
+              }
               setDropdownOpen(nextOpen);
               if (nextOpen) {
                 void loadAcpOptions();
               }
             }}
-            disabled={loading}
+            disabled={disabled || loading}
            data-bf-component="model-selector" data-bf-part="trigger" data-bf-state={dropdownOpen ? 'open' : undefined}>
             <span className="bitfun-model-selector__name" data-bf-component="model-selector" data-bf-part="name">
-              {getModelDisplayLabel(acpCurrentModel, currentAcpModelId)}
+              {acpModeOnly ? acpModeLabel : getModelDisplayLabel(acpCurrentModel, currentAcpModelId)}
             </span>
             {acpFastMode?.enabled && (
               <Zap size={9} className="bitfun-model-selector__fast-icon" />
@@ -1219,15 +1304,16 @@ export const ModelSelector: React.FC<ModelSelectorProps> = ({
           <ReasoningPresetSelector
             projection={acpReasoning.projection}
             selectedPreset={acpReasoning.selectedPreset}
-            disabled={loading}
+            disabled={disabled || loading}
             loading={reasoningLoading}
             dropdownPlacement={dropdownPlacement}
             onSelect={handleSelectAcpReasoning}
           />
         )}
 
-        {dropdownOpen && createPortal(
-          <div
+        <PresenceBoundary active={dropdownOpen}>
+          {createPortal(
+            <div
             id={menuId}
             className="bitfun-model-selector__dropdown"
             data-bf-component="model-selector"
@@ -1236,18 +1322,22 @@ export const ModelSelector: React.FC<ModelSelectorProps> = ({
             style={dropdownStyle}
             data-testid="chat-model-selector-menu"
             data-keyboard-open={keyboardNavigationOpen ? 'true' : 'false'}
-            data-placement={dropdownPlacement}
+            data-placement={resolvedDropdownPlacement}
+            data-open={dropdownOpen ? 'true' : 'false'}
+            aria-hidden={!dropdownOpen}
+            {...(!dropdownOpen ? { inert: '' } : {})}
             role="menu"
-            aria-label="ACP model"
+            aria-label={acpModeOnly ? t('modelSelector.acpMode') : 'ACP model'}
             onKeyDown={handleDropdownKeyDown}
           >
             <div className="bitfun-model-selector__dropdown-header" data-bf-component="model-selector" data-bf-part="dropdownHeader">
-              <span>ACP model</span>
+              <span>{acpModeOnly ? t('modelSelector.acpMode') : 'ACP model'}</span>
               <span className="bitfun-model-selector__dropdown-hint">
                 {acpClientId}
               </span>
             </div>
 
+            {acpAvailableModels.length > 0 && (
             <div className="bitfun-model-selector__list" data-bf-component="model-selector" data-bf-part="list">
               {acpAvailableModels.map(model => {
                 const isSelected = currentAcpModelId === model.id;
@@ -1287,6 +1377,63 @@ export const ModelSelector: React.FC<ModelSelectorProps> = ({
                 );
               })}
             </div>
+            )}
+
+            {acpMode && (
+              <>
+                {acpAvailableModels.length > 0 && (
+                  <>
+                    <div className="bitfun-model-selector__divider" />
+                    <div className="bitfun-model-selector__dropdown-header" data-bf-component="model-selector" data-bf-part="dropdownHeader">
+                      <span>{t('modelSelector.acpMode')}</span>
+                    </div>
+                  </>
+                )}
+                <div className="bitfun-model-selector__list" data-bf-component="model-selector" data-bf-part="list">
+                  {acpMode.option.options.map(candidate => {
+                    const isSelected = acpMode.currentValue === candidate.value;
+                    // The row stays one line; what a mode does — or why it can no
+                    // longer change — is hover-only.
+                    const hint = acpMode.locked
+                      ? (acpMode.option.description ?? t('modelSelector.acpModeLocked'))
+                      : (candidate.description ?? candidate.name);
+
+                    return (
+                      <Tooltip
+                        key={candidate.value}
+                        content={hint}
+                        placement="right"
+                      >
+                        <button
+                          type="button"
+                          role="menuitemradio"
+                          aria-checked={isSelected}
+                          data-testid="chat-acp-mode-option"
+                          data-mode-value={candidate.value}
+                          data-selected={isSelected ? 'true' : 'false'}
+                          disabled={acpMode.locked || loading}
+                          className={`bitfun-model-selector__option ${isSelected ? 'bitfun-model-selector__option--selected' : ''}`}
+                          data-bf-component="model-selector"
+                          data-bf-part="option"
+                          data-bf-state={isSelected ? 'selected' : undefined}
+                          onClick={() => { void handleSelectAcpMode(candidate.value); }}
+                        >
+                          <div className="bitfun-model-selector__option-main" data-bf-component="model-selector" data-bf-part="optionMain">
+                            <span className="bitfun-model-selector__option-name">
+                              {candidate.name}
+                            </span>
+                          </div>
+                          {isSelected && (
+                            <Check size={14} className="bitfun-model-selector__option-check" />
+                          )}
+                        </button>
+                      </Tooltip>
+                    );
+                  })}
+                </div>
+              </>
+            )}
+
             {acpFastMode && (
               <>
                 <div className="bitfun-model-selector__divider" />
@@ -1309,9 +1456,10 @@ export const ModelSelector: React.FC<ModelSelectorProps> = ({
                 </div>
               </>
             )}
-          </div>,
-          getAppearanceOverlayHost()
-        )}
+            </div>,
+            getAppearanceOverlayHost()
+          )}
+        </PresenceBoundary>
       </div>
     );
   }
@@ -1339,7 +1487,7 @@ export const ModelSelector: React.FC<ModelSelectorProps> = ({
       ref={dropdownRef}
       className={`bitfun-model-selector ${className}`}
     >
-      <Tooltip content={tooltipContent}>
+      <Tooltip content={tooltipContent} disabled={dropdownOpen}>
         <button
           ref={triggerRef}
           data-testid="chat-model-selector-btn"
@@ -1351,10 +1499,14 @@ export const ModelSelector: React.FC<ModelSelectorProps> = ({
           onKeyDown={handleTriggerKeyDown}
           onClick={(event) => {
             const nextOpen = !dropdownOpen;
-            setKeyboardNavigationOpen(nextOpen && event.detail === 0);
+            if (nextOpen) {
+              setKeyboardNavigationOpen(event.detail === 0);
+            } else if (event.detail !== 0) {
+              setKeyboardNavigationOpen(false);
+            }
             setDropdownOpen(nextOpen);
           }}
-          disabled={loading || reasoningLoading}
+          disabled={disabled || loading || reasoningLoading}
          data-bf-component="model-selector" data-bf-part="trigger" data-bf-state={dropdownOpen ? 'open' : undefined}>
           <span className="bitfun-model-selector__name" data-bf-component="model-selector" data-bf-part="name">
             {getModelDisplayLabel(currentModel, t('modelSelector.autoModel'))}
@@ -1367,7 +1519,7 @@ export const ModelSelector: React.FC<ModelSelectorProps> = ({
         <ReasoningPresetSelector
           projection={currentReasoningProjection}
           selectedPreset={selectedReasoningPreset}
-          disabled={loading}
+          disabled={disabled || loading}
           loading={reasoningLoading}
           dropdownPlacement={dropdownPlacement}
           onSelect={handleSelectReasoningPreset}
@@ -1382,8 +1534,9 @@ export const ModelSelector: React.FC<ModelSelectorProps> = ({
         </Tooltip>
       )}
 
-      {dropdownOpen && createPortal(
-        <div
+      <PresenceBoundary active={dropdownOpen}>
+        {createPortal(
+          <div
           id={menuId}
           className="bitfun-model-selector__dropdown"
           data-bf-component="model-selector"
@@ -1392,7 +1545,10 @@ export const ModelSelector: React.FC<ModelSelectorProps> = ({
           style={dropdownStyle}
           data-testid="chat-model-selector-menu"
           data-keyboard-open={keyboardNavigationOpen ? 'true' : 'false'}
-          data-placement={dropdownPlacement}
+          data-placement={resolvedDropdownPlacement}
+          data-open={dropdownOpen ? 'true' : 'false'}
+          aria-hidden={!dropdownOpen}
+          {...(!dropdownOpen ? { inert: '' } : {})}
           role="menu"
           aria-label={t('modelSelector.modelSelection')}
           onKeyDown={handleDropdownKeyDown}
@@ -1548,9 +1704,10 @@ export const ModelSelector: React.FC<ModelSelectorProps> = ({
               );
             })}
           </div>
-        </div>,
-        getAppearanceOverlayHost()
-      )}
+          </div>,
+          getAppearanceOverlayHost()
+        )}
+      </PresenceBoundary>
     </div>
   );
 };
diff --git a/src/web-ui/src/flow_chat/components/ModelSelectorAcpMode.test.tsx b/src/web-ui/src/flow_chat/components/ModelSelectorAcpMode.test.tsx
new file mode 100644
index 0000000000..32c43ef664
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/ModelSelectorAcpMode.test.tsx
@@ -0,0 +1,222 @@
+/**
+ * @vitest-environment jsdom
+ *
+ * The composer's mode picker for ACP sessions. An agent publishes its modes as
+ * a `mode`-category config option, and dsh-acp publishes ONLY that — no models —
+ * so this covers the case where the mode is the whole picker, and the case where
+ * the agent has fixed it and left exactly one choice.
+ */
+
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { ModelSelector } from './ModelSelector';
+import { ACPClientAPI } from '@/infrastructure/api/service-api/ACPClientAPI';
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+const aiApiMocks = vi.hoisted(() => ({
+  getModelCatalog: vi.fn(),
+  onModelCatalogUpdated: vi.fn(),
+}));
+
+const flowChatStoreMocks = vi.hoisted(() => {
+  type TestSession = {
+    workspacePath?: string;
+    config: { agentType?: string; modelName?: string; workspacePath?: string };
+  };
+  const sessions = new Map<string, TestSession>();
+  const store = {
+    getState: () => ({ sessions }),
+    subscribe: vi.fn(() => () => undefined),
+    updateSessionModelName: vi.fn(),
+    updateSessionReasoningPreset: vi.fn(),
+    updateSessionMaxContextTokens: vi.fn(),
+    updateAcpContextUsage: vi.fn(),
+  };
+  return { sessions, store };
+});
+
+vi.mock('@/infrastructure/api/service-api/AIApi', () => ({ aiApi: aiApiMocks }));
+
+vi.mock('react-i18next', () => ({
+  initReactI18next: { type: '3rdParty', init: vi.fn() },
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+vi.mock('@/component-library', () => ({
+  // Keep the hover copy inspectable: descriptions live only in the tooltip now.
+  Tooltip: ({ children, content }: { children: React.ReactNode; content?: React.ReactNode }) => (
+    <span data-tooltip={typeof content === 'string' ? content : undefined}>{children}</span>
+  ),
+  Switch: () => null,
+}));
+
+vi.mock('@/infrastructure/config/services/ConfigManager', () => ({
+  configManager: {
+    getConfigs: vi.fn(async () => ({ 'ai.models': [] })),
+    onConfigChange: vi.fn(() => () => undefined),
+    setConfig: vi.fn(async () => undefined),
+  },
+}));
+
+vi.mock('@/infrastructure/api/service-api/AgentAPI', () => ({
+  agentAPI: { updateSessionModel: vi.fn(async () => undefined) },
+}));
+
+vi.mock('@/infrastructure/api/service-api/ACPClientAPI', () => ({
+  ACPClientAPI: {
+    getSessionOptions: vi.fn(),
+    setSessionConfigOption: vi.fn(),
+    onSessionOptionsChanged: vi.fn(() => () => undefined),
+  },
+}));
+
+vi.mock('../services/flow-chat-manager/SessionModule', () => ({
+  getModelMaxTokens: vi.fn(async () => 128_000),
+}));
+
+vi.mock('@/infrastructure/event-bus', () => ({
+  globalEventBus: { emit: vi.fn(), on: vi.fn(), off: vi.fn() },
+}));
+
+vi.mock('../store/FlowChatStore', () => ({
+  FlowChatStore: { getInstance: () => flowChatStoreMocks.store },
+}));
+
+/** The mode option as an unlocked agent publishes it. */
+const MODE_OPTION = {
+  id: 'agent-preset',
+  name: 'Mode',
+  category: 'mode',
+  type: 'select' as const,
+  currentValue: 'standard',
+  options: [
+    { value: 'standard', name: 'Standard', description: 'the default toolset' },
+    { value: 'minimal', name: 'Minimal', description: 'bash and an editor' },
+  ],
+};
+
+describe('ModelSelector ACP mode picker', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    flowChatStoreMocks.sessions.clear();
+    flowChatStoreMocks.sessions.set('acp-session', {
+      workspacePath: '/tmp/project',
+      config: { agentType: 'acp:dsh' },
+    });
+    const storage = new Map<string, string>();
+    vi.stubGlobal('localStorage', {
+      getItem: (key: string) => storage.get(key) ?? null,
+      setItem: (key: string, value: string) => storage.set(key, String(value)),
+      removeItem: (key: string) => storage.delete(key),
+      clear: () => storage.clear(),
+      key: (index: number) => [...storage.keys()][index] ?? null,
+      get length() { return storage.size; },
+    });
+    aiApiMocks.getModelCatalog.mockResolvedValue({ version: 1, default_models: {}, models: [] });
+    aiApiMocks.onModelCatalogUpdated.mockImplementation(() => () => undefined);
+    class TestResizeObserver {
+      observe() {}
+      disconnect() {}
+    }
+    vi.stubGlobal('ResizeObserver', TestResizeObserver);
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    vi.unstubAllGlobals();
+    vi.clearAllMocks();
+  });
+
+  /** Render the selector against one set of ACP session options. */
+  const renderWithOptions = async (configOptions: unknown[]) => {
+    vi.mocked(ACPClientAPI.getSessionOptions).mockResolvedValue({
+      availableModels: [],
+      configOptions,
+    } as never);
+    await act(async () => {
+      root.render(<ModelSelector currentMode="acp:dsh" sessionId="acp-session" />);
+      await Promise.resolve();
+    });
+    await act(async () => { await Promise.resolve(); });
+  };
+
+  it('renders the mode as the whole picker when the agent offers no models', async () => {
+    await renderWithOptions([MODE_OPTION]);
+
+    const trigger = container.querySelector<HTMLButtonElement>('[data-testid="chat-model-selector-btn"]');
+    // Without this the ACP branch used to return null on an empty model list,
+    // leaving a dsh session with no picker at all.
+    expect(trigger, 'the mode picker must render without models').not.toBeNull();
+    expect(trigger?.textContent).toContain('Standard');
+
+    await act(async () => { trigger?.click(); });
+    const options = document.body.querySelectorAll('[data-testid="chat-acp-mode-option"]');
+    expect([...options].map(option => option.getAttribute('data-mode-value')))
+      .toEqual(['standard', 'minimal']);
+  });
+
+  it('sends the chosen mode to the agent', async () => {
+    await renderWithOptions([MODE_OPTION]);
+    vi.mocked(ACPClientAPI.setSessionConfigOption).mockResolvedValue({
+      availableModels: [],
+      configOptions: [{ ...MODE_OPTION, currentValue: 'minimal' }],
+    } as never);
+
+    await act(async () => {
+      container.querySelector<HTMLButtonElement>('[data-testid="chat-model-selector-btn"]')?.click();
+    });
+    await act(async () => {
+      document.body.querySelector<HTMLButtonElement>(
+        '[data-testid="chat-acp-mode-option"][data-mode-value="minimal"]',
+      )?.click();
+      await Promise.resolve();
+    });
+
+    expect(ACPClientAPI.setSessionConfigOption).toHaveBeenCalledWith(expect.objectContaining({
+      sessionId: 'acp-session',
+      clientId: 'dsh',
+      configId: 'agent-preset',
+      value: { type: 'select', value: 'minimal' },
+    }));
+    expect(
+      container.querySelector('[data-testid="chat-model-selector-btn"]')?.textContent,
+    ).toContain('Minimal');
+  });
+
+  it('disables the picker once the agent leaves one mode', async () => {
+    // How an agent says "fixed" without a flag ACP does not have: it publishes
+    // only the mode in force, and explains itself in the option description.
+    await renderWithOptions([{
+      ...MODE_OPTION,
+      description: 'This conversation has already started, so its mode is fixed.',
+      options: [MODE_OPTION.options[0]],
+    }]);
+
+    await act(async () => {
+      container.querySelector<HTMLButtonElement>('[data-testid="chat-model-selector-btn"]')?.click();
+    });
+    const options = document.body.querySelectorAll<HTMLButtonElement>(
+      '[data-testid="chat-acp-mode-option"]',
+    );
+    expect(options).toHaveLength(1);
+    expect(options[0]?.disabled).toBe(true);
+    // The row itself stays a bare mode name; the reason is hover-only.
+    expect(options[0]?.textContent).toBe('Standard');
+    expect(options[0]?.closest('[data-tooltip]')?.getAttribute('data-tooltip'))
+      .toContain('already started');
+
+    await act(async () => {
+      options[0]?.click();
+      await Promise.resolve();
+    });
+    expect(ACPClientAPI.setSessionConfigOption).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/web-ui/src/flow_chat/components/PendingQueuePanel.tsx b/src/web-ui/src/flow_chat/components/PendingQueuePanel.tsx
index 66305e677f..c030ad61fa 100644
--- a/src/web-ui/src/flow_chat/components/PendingQueuePanel.tsx
+++ b/src/web-ui/src/flow_chat/components/PendingQueuePanel.tsx
@@ -7,12 +7,12 @@
  * UX notes:
  * - Click anywhere on the preview text to start editing.
  * - Cmd/Ctrl+Enter saves the edit; Esc cancels.
- * - Clicking "send now" eagerly inserts a UserSteeringBubble into the live
- *   round so the user sees feedback instantly; the backend confirmation event
- *   is deduped via `steeringId`.
+ * - Clicking "send now" eagerly inserts a steering message into the live round
+ *   so the user sees feedback instantly; the backend confirmation event is
+ *   deduped via `steeringId`.
  */
 
-import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useCallback, useEffect, useMemo, useState, useSyncExternalStore } from 'react';
 import { useTranslation } from 'react-i18next';
 import {
   Pencil,
@@ -27,15 +27,13 @@ import { Tooltip, IconButton } from '@/component-library';
 import { agentAPI } from '@/infrastructure/api/service-api/AgentAPI';
 import { stateMachineManager } from '../state-machine';
 import { FlowChatStore } from '../store/FlowChatStore';
-import {
-  pendingQueueManager,
-  queuedMessageHasUnsupportedSteeringPayload,
-} from '../services/flow-chat-manager/PendingQueueModule';
+import { pendingQueueManager } from '../services/flow-chat-manager/PendingQueueModule';
 import { FlowChatManager } from '../services/FlowChatManager';
+import { interruptedTurnRecoveryGate } from '../services/interruptedTurnRecoveryGate';
 import { insertSteeringItemIfAbsent } from '../services/flow-chat-manager/EventHandlerModule';
 import { notificationService } from '../../shared/notification-system';
 import { createLogger } from '@/shared/utils/logger';
-import type { QueuedMessage } from '../types/flow-chat';
+import type { QueuedMessage, SteeringImage } from '../types/flow-chat';
 import { isAcpFlowSession } from '../utils/acpSession';
 import './PendingQueuePanel.scss';
 
@@ -48,6 +46,12 @@ interface PendingQueuePanelProps {
 
 export function PendingQueuePanel({ sessionId, className }: PendingQueuePanelProps): JSX.Element | null {
   const { t } = useTranslation('flow-chat');
+  useSyncExternalStore(
+    interruptedTurnRecoveryGate.subscribe,
+    interruptedTurnRecoveryGate.getSnapshot,
+    interruptedTurnRecoveryGate.getSnapshot,
+  );
+  const recoveryInFlight = interruptedTurnRecoveryGate.isSessionInFlight(sessionId);
   const [items, setItems] = useState<QueuedMessage[]>(() =>
     sessionId ? pendingQueueManager.list(sessionId) : [],
   );
@@ -124,81 +128,74 @@ export function PendingQueuePanel({ sessionId, className }: PendingQueuePanelPro
 
   const handleSendNow = useCallback(
     async (item: QueuedMessage) => {
-      if (!sessionId) return;
-      if (isAcpSession) {
-        log.warn('Steering is disabled for ACP sessions', { sessionId, itemId: item.id });
-        return;
-      }
+      if (!sessionId || recoveryInFlight) return;
       const machine = stateMachineManager.get(sessionId);
-      const ctx = machine?.getContext();
-      const dialogTurnId = ctx?.currentDialogTurnId ?? null;
+      const dialogTurnId = machine?.getContext().currentDialogTurnId ?? null;
 
-      if (!dialogTurnId) {
-        // Turn already finished — fall back to the regular drain path so the
-        // item starts a new turn instead.
-        log.info('Send now fallback: no active dialog turn, using drain path', {
-          sessionId,
-          itemId: item.id,
-        });
+      // A running turn takes the message through the steering channel, which
+      // carries the whole payload — text, attachments and metadata alike.
+      // ACP agents own their execution loop and expose no mid-turn injection
+      // point, so they take the drain path below instead.
+      if (dialogTurnId && !isAcpSession) {
+        pendingQueueManager.setStatus(sessionId, item.id, 'sending_now');
         try {
-          if (!pendingQueueManager.promoteForExplicitDrain(sessionId, item.id)) {
-            log.warn('Send now fallback item is no longer queued', {
-              sessionId,
-              itemId: item.id,
-            });
-            return;
+          const resp = await agentAPI.steerDialogTurn({
+            sessionId,
+            dialogTurnId,
+            content: item.content,
+            displayContent: item.displayMessage ?? item.content,
+            imageContexts: item.imageContexts,
+            userMessageMetadata: item.userMessageMetadata,
+          });
+          // Optimistically render the steering bubble in the running round so
+          // the user sees their message land immediately. The backend
+          // `UserSteeringInjected` event dedupes by the same `steeringId`.
+          if (resp?.steeringId) {
+            try {
+              insertSteeringItemIfAbsent({
+                sessionId,
+                turnId: dialogTurnId,
+                steeringId: resp.steeringId,
+                content: item.displayMessage ?? item.content,
+                images: item.imageDisplayData as SteeringImage[] | undefined,
+                status: 'pending',
+              });
+            } catch (renderErr) {
+              log.warn('Optimistic steering render failed', { renderErr });
+            }
           }
-          await FlowChatManager.getInstance().drainPendingQueueForSession(sessionId);
+          pendingQueueManager.remove(sessionId, item.id);
+          return;
         } catch (err) {
-          log.error('Send now fallback failed', { sessionId, itemId: item.id, err });
-          notificationService.error(t('pendingQueue.errors.sendNowFailed'), { duration: 4000 });
+          // Most often the turn finished between the click and the request.
+          // Fall through to the drain path rather than reporting a failure the
+          // user cannot act on.
+          log.warn('Steering rejected, falling back to the drain path', {
+            sessionId,
+            itemId: item.id,
+            err,
+          });
+          pendingQueueManager.setStatus(sessionId, item.id, 'queued');
         }
-        return;
-      }
-
-      if (queuedMessageHasUnsupportedSteeringPayload(item)) {
-        log.info('Send now kept queued because steering is text-only', {
-          sessionId,
-          itemId: item.id,
-        });
-        notificationService.warning(t('pendingQueue.errors.richContentUnsupported'), {
-          duration: 4000,
-        });
-        return;
       }
 
-      pendingQueueManager.setStatus(sessionId, item.id, 'sending_now');
+      // No turn to inject into. Move the item to the head and send it at the
+      // first opportunity: right now if the session is idle, otherwise the
+      // IDLE drain listener picks it up the moment the current turn ends.
       try {
-        const resp = await agentAPI.steerDialogTurn({
-          sessionId,
-          dialogTurnId,
-          content: item.content,
-          displayContent: item.displayMessage ?? item.content,
-        });
-        // Optimistically render the steering bubble in the running round so the
-        // user sees their message land immediately. The backend
-        // `UserSteeringInjected` event will dedupe by the same `steeringId`.
-        if (resp?.steeringId) {
-          try {
-            insertSteeringItemIfAbsent({
-              sessionId,
-              turnId: dialogTurnId,
-              steeringId: resp.steeringId,
-              content: item.displayMessage ?? item.content,
-              status: 'pending',
-            });
-          } catch (renderErr) {
-            log.warn('Optimistic steering render failed', { renderErr });
-          }
+        if (!pendingQueueManager.promoteForExplicitDrain(sessionId, item.id)) {
+          log.warn('Send now item is no longer queued', { sessionId, itemId: item.id });
+          return;
         }
-        pendingQueueManager.remove(sessionId, item.id);
+        await FlowChatManager.getInstance().drainPendingQueueForSession(sessionId, {
+          allowInterruptedRecoveryAbandon: true,
+        });
       } catch (err) {
-        log.error('Send now (steering) failed', { sessionId, itemId: item.id, err });
-        pendingQueueManager.setStatus(sessionId, item.id, 'queued');
+        log.error('Send now fallback failed', { sessionId, itemId: item.id, err });
         notificationService.error(t('pendingQueue.errors.sendNowFailed'), { duration: 4000 });
       }
     },
-    [isAcpSession, sessionId, t],
+    [isAcpSession, recoveryInFlight, sessionId, t],
   );
 
   const visibleItems = useMemo(() => items, [items]);
@@ -364,27 +361,25 @@ export function PendingQueuePanel({ sessionId, className }: PendingQueuePanelPro
                         <Pencil size={12} strokeWidth={2.25} />
                       </IconButton>
                     </Tooltip>
-                    {!isAcpSession && (
-                      <Tooltip content={t('pendingQueue.tooltip.sendNow')}>
-                        <IconButton
-                          data-bf-component="pending-queue-panel"
-                          data-bf-part="action"
-                          size="small"
-                          className="bitfun-pending-queue-panel__btn bitfun-pending-queue-panel__btn--primary"
-                          disabled={isSending}
-                          onClick={() => {
-                            void handleSendNow(item);
-                          }}
-                          aria-label={t('pendingQueue.actions.sendNow')}
-                        >
-                          {isSendingNow ? (
-                            <Loader2 size={12} strokeWidth={2.5} className="bitfun-pending-queue-panel__spin" />
-                          ) : (
-                            <ArrowUp size={12} strokeWidth={2.5} />
-                          )}
-                        </IconButton>
-                      </Tooltip>
-                    )}
+                    <Tooltip content={t('pendingQueue.tooltip.sendNow')}>
+                      <IconButton
+                        data-bf-component="pending-queue-panel"
+                        data-bf-part="action"
+                        size="small"
+                        className="bitfun-pending-queue-panel__btn bitfun-pending-queue-panel__btn--primary"
+                        disabled={isSending || recoveryInFlight}
+                        onClick={() => {
+                          void handleSendNow(item);
+                        }}
+                        aria-label={t('pendingQueue.actions.sendNow')}
+                      >
+                        {isSendingNow ? (
+                          <Loader2 size={12} strokeWidth={2.5} className="bitfun-pending-queue-panel__spin" />
+                        ) : (
+                          <ArrowUp size={12} strokeWidth={2.5} />
+                        )}
+                      </IconButton>
+                    </Tooltip>
                     <Tooltip content={t('pendingQueue.actions.delete')}>
                       <IconButton
                         data-bf-component="pending-queue-panel"
diff --git a/src/web-ui/src/flow_chat/components/PlannerButton.scss b/src/web-ui/src/flow_chat/components/PlannerButton.scss
index cc36d4d6fb..54a5ccf796 100644
--- a/src/web-ui/src/flow_chat/components/PlannerButton.scss
+++ b/src/web-ui/src/flow_chat/components/PlannerButton.scss
@@ -30,7 +30,11 @@
   backdrop-filter: none;
   -webkit-backdrop-filter: none;
   
-  transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+  transition:
+    transform 120ms cubic-bezier(0.23, 1, 0.32, 1),
+    color 160ms ease,
+    border-color 160ms ease,
+    box-shadow 180ms ease;
   position: relative;
   overflow: hidden;
   
@@ -39,7 +43,7 @@
     content: '';
     position: absolute;
     top: 0;
-    left: -100%;
+    left: 0;
     width: 100%;
     height: 100%;
     background: linear-gradient(90deg,
@@ -49,38 +53,41 @@
       var(--bf-appearance-token-color-overlay-white-08),
       transparent
     );
-    transition: left 0.6s cubic-bezier(0.4, 0, 0.2, 1);
+    transform: translateX(-100%);
+    transition: transform 180ms cubic-bezier(0.23, 1, 0.32, 1);
     z-index: 1;
     pointer-events: none;
   }
   
-  // Hover: enable glass effect
-  &:hover {
-    background: linear-gradient(135deg,
-      color-mix(in srgb, var(--bf-appearance-token-color-warning) 20%, transparent) 0%,
-      color-mix(in srgb, var(--bf-appearance-token-color-warning) 17%, transparent) 30%,
-      color-mix(in srgb, var(--bf-appearance-token-color-warning) 13%, transparent) 60%,
-      color-mix(in srgb, var(--bf-appearance-token-color-warning) 23%, transparent) 100%
-    );
-    border-color: color-mix(in srgb, var(--bf-appearance-token-color-warning) 50%, transparent);
-    color: var(--bf-appearance-token-color-text-primary);
-    box-shadow: 
-      0 10px 20px color-mix(in srgb, var(--bf-appearance-token-color-warning) 20%, transparent),
-      0 6px 12px color-mix(in srgb, var(--bf-appearance-token-color-warning) 15%, transparent),
-      $inner-glow-top-hover,
-      inset 0 -1px 0 color-mix(in srgb, var(--bf-appearance-token-color-warning) 15%, transparent);
-    backdrop-filter: blur(12px) saturate(1.2) brightness(1.05);
-    -webkit-backdrop-filter: blur(12px) saturate(1.2) brightness(1.05);
-    transform: translateY(-1px);
-    
-    &::before {
-      left: 100%;
+  // Hover: enable glass effect only for devices with a persistent pointer.
+  @media (hover: hover) and (pointer: fine) {
+    &:hover {
+      background: linear-gradient(135deg,
+        color-mix(in srgb, var(--bf-appearance-token-color-warning) 20%, transparent) 0%,
+        color-mix(in srgb, var(--bf-appearance-token-color-warning) 17%, transparent) 30%,
+        color-mix(in srgb, var(--bf-appearance-token-color-warning) 13%, transparent) 60%,
+        color-mix(in srgb, var(--bf-appearance-token-color-warning) 23%, transparent) 100%
+      );
+      border-color: color-mix(in srgb, var(--bf-appearance-token-color-warning) 50%, transparent);
+      color: var(--bf-appearance-token-color-text-primary);
+      box-shadow:
+        0 10px 20px color-mix(in srgb, var(--bf-appearance-token-color-warning) 20%, transparent),
+        0 6px 12px color-mix(in srgb, var(--bf-appearance-token-color-warning) 15%, transparent),
+        $inner-glow-top-hover,
+        inset 0 -1px 0 color-mix(in srgb, var(--bf-appearance-token-color-warning) 15%, transparent);
+      backdrop-filter: blur(12px) saturate(1.2) brightness(1.05);
+      -webkit-backdrop-filter: blur(12px) saturate(1.2) brightness(1.05);
+      transform: translateY(-1px);
+
+      &::before {
+        transform: translateX(100%);
+      }
     }
   }
   
   // Active state
   &:active {
-    transform: translateY(-1px) scale(1.005);
+    transform: scale(0.97);
   }
   
   &__dot {
@@ -124,3 +131,17 @@
   }
 }
 
+@media (prefers-reduced-motion: reduce) {
+  .bitfun-planner-button {
+    &::before {
+      transition: none;
+      transform: translateX(-100%);
+    }
+
+    &__dot {
+      animation: none;
+      opacity: 1;
+      transform: none;
+    }
+  }
+}
diff --git a/src/web-ui/src/flow_chat/components/ReasoningPresetSelector.scss b/src/web-ui/src/flow_chat/components/ReasoningPresetSelector.scss
index 554d15f29b..d7e3ddb652 100644
--- a/src/web-ui/src/flow_chat/components/ReasoningPresetSelector.scss
+++ b/src/web-ui/src/flow_chat/components/ReasoningPresetSelector.scss
@@ -51,6 +51,8 @@
   }
 
   &__menu {
+    --reasoning-preset-menu-offset: -4px;
+
     min-width: clamp(0px, 190px, calc(100vw - 16px));
     max-width: clamp(0px, 240px, calc(100vw - 16px));
     padding: 4px;
@@ -60,6 +62,32 @@
     border-radius: 6px;
     box-shadow: 0 8px 32px var(--bf-appearance-token-color-overlay-black-50);
     z-index: $z-popover;
+    transform-origin: center top;
+    transition:
+      opacity 100ms ease,
+      transform 120ms cubic-bezier(0.23, 1, 0.32, 1);
+
+    &[data-open='true']:not([data-keyboard-open='true']) {
+      @starting-style {
+        opacity: 0;
+        transform: translateY(var(--reasoning-preset-menu-offset)) scale(0.985);
+      }
+    }
+
+    &[data-placement='top'] {
+      --reasoning-preset-menu-offset: 4px;
+      transform-origin: center bottom;
+    }
+
+    &[data-open='false'] {
+      opacity: 0;
+      transform: translateY(var(--reasoning-preset-menu-offset)) scale(0.985);
+      pointer-events: none;
+    }
+
+    &[data-keyboard-open='true'] {
+      transition: none;
+    }
   }
 
   &__header {
@@ -126,6 +154,12 @@
   }
 }
 
+@media (prefers-reduced-motion: reduce) {
+  .bitfun-reasoning-preset-selector__menu {
+    transition: opacity 100ms linear;
+  }
+}
+
 @media (max-width: 520px) {
   .bitfun-reasoning-preset-selector__trigger {
     max-width: 84px;
diff --git a/src/web-ui/src/flow_chat/components/ReasoningPresetSelector.test.tsx b/src/web-ui/src/flow_chat/components/ReasoningPresetSelector.test.tsx
index 72e1e34a25..7c24d384e8 100644
--- a/src/web-ui/src/flow_chat/components/ReasoningPresetSelector.test.tsx
+++ b/src/web-ui/src/flow_chat/components/ReasoningPresetSelector.test.tsx
@@ -119,4 +119,78 @@ describe('ReasoningPresetSelector', () => {
       .toBe('reasoningSelector.source.model_config');
     expect(document.body.querySelector('[data-preset-id="high"] small')).toBeNull();
   });
+
+  it('returns focus to the trigger and keeps keyboard motion suppressed while exiting', async () => {
+    const onSelect = vi.fn();
+    await act(async () => {
+      root.render(
+        <ReasoningPresetSelector
+          projection={{
+            status: 'known',
+            presets: [
+              { id: 'high', label: 'High', order: 10, source: 'models_dev', actions: [{ type: 'effort', value: 'high' }] },
+            ],
+          }}
+          onSelect={onSelect}
+        />,
+      );
+    });
+
+    const trigger = container.querySelector<HTMLButtonElement>(
+      '[data-testid="chat-reasoning-preset-selector-btn"]',
+    );
+    trigger?.focus();
+    await act(async () => {
+      trigger?.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true }));
+      await Promise.resolve();
+    });
+
+    const option = document.body.querySelector<HTMLButtonElement>('[data-preset-id="high"]');
+    option?.focus();
+    await act(async () => {
+      option?.click();
+    });
+
+    const exitingMenu = document.body.querySelector<HTMLElement>(
+      '[data-testid="chat-reasoning-preset-selector-menu"]',
+    );
+    expect(onSelect).toHaveBeenCalledWith('high');
+    expect(document.activeElement).toBe(trigger);
+    expect(exitingMenu?.getAttribute('aria-hidden')).toBe('true');
+    expect(exitingMenu?.dataset.keyboardOpen).toBe('true');
+  });
+
+  it('restores trigger focus when Escape closes a focused menu', async () => {
+    await act(async () => {
+      root.render(
+        <ReasoningPresetSelector
+          projection={{
+            status: 'known',
+            presets: [
+              { id: 'medium', label: 'Medium', order: 10, source: 'models_dev', actions: [{ type: 'effort', value: 'medium' }] },
+            ],
+          }}
+          onSelect={vi.fn()}
+        />,
+      );
+    });
+
+    const trigger = container.querySelector<HTMLButtonElement>(
+      '[data-testid="chat-reasoning-preset-selector-btn"]',
+    );
+    await act(async () => {
+      trigger?.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true }));
+      await Promise.resolve();
+    });
+    const option = document.body.querySelector<HTMLButtonElement>('[data-preset-id="medium"]');
+    option?.focus();
+
+    await act(async () => {
+      option?.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+    });
+
+    expect(document.activeElement).toBe(trigger);
+    expect(document.body.querySelector('[data-testid="chat-reasoning-preset-selector-menu"]')
+      ?.getAttribute('aria-hidden')).toBe('true');
+  });
 });
diff --git a/src/web-ui/src/flow_chat/components/ReasoningPresetSelector.tsx b/src/web-ui/src/flow_chat/components/ReasoningPresetSelector.tsx
index 48fc273022..1b0ba4a50a 100644
--- a/src/web-ui/src/flow_chat/components/ReasoningPresetSelector.tsx
+++ b/src/web-ui/src/flow_chat/components/ReasoningPresetSelector.tsx
@@ -3,12 +3,13 @@ import { createPortal } from 'react-dom';
 import { Brain, Check, ChevronDown } from 'lucide-react';
 import { useTranslation } from 'react-i18next';
 import { Tooltip } from '@/component-library';
+import { PresenceBoundary } from '@/component-library/components/PresenceBoundary';
 import { getAppearanceOverlayHost } from '@/infrastructure/appearance/runtime/AppearanceOverlayHost';
 import type {
   ReasoningCatalogProjection,
   ReasoningPresetDescriptor,
 } from '@/infrastructure/config/types';
-import { getModelSelectorDropdownStyle } from './modelSelectorDropdownPosition';
+import { getModelSelectorDropdownLayout } from './modelSelectorDropdownPosition';
 import './ReasoningPresetSelector.scss';
 
 interface ReasoningPresetSelectorProps {
@@ -74,6 +75,7 @@ export const ReasoningPresetSelector: React.FC<ReasoningPresetSelectorProps> = (
     position: 'fixed',
     visibility: 'hidden',
   });
+  const [resolvedPlacement, setResolvedPlacement] = useState(dropdownPlacement);
 
   const presets = useMemo(
     () => (projection?.status === 'known' ? projection.presets ?? [] : []),
@@ -103,12 +105,14 @@ export const ReasoningPresetSelector: React.FC<ReasoningPresetSelectorProps> = (
     if (!open || !rootRef.current) return;
     const updatePosition = () => {
       if (!rootRef.current || !menuRef.current) return;
-      setMenuStyle(getModelSelectorDropdownStyle(
+      const layout = getModelSelectorDropdownLayout(
         rootRef.current.getBoundingClientRect(),
         menuRef.current.getBoundingClientRect(),
         dropdownPlacement,
         { width: window.innerWidth, height: window.innerHeight },
-      ));
+      );
+      setMenuStyle(layout.style);
+      setResolvedPlacement(layout.placement);
     };
     updatePosition();
     const observer = new ResizeObserver(updatePosition);
@@ -137,17 +141,18 @@ export const ReasoningPresetSelector: React.FC<ReasoningPresetSelectorProps> = (
   }, [keyboardOpen, open]);
 
   const select = useCallback((presetId: string | null) => {
+    if (menuRef.current?.contains(document.activeElement)) {
+      triggerRef.current?.focus();
+    }
     setOpen(false);
-    setKeyboardOpen(false);
     void onSelect(presetId);
   }, [onSelect]);
 
   const handleMenuKeyDown = useCallback((event: React.KeyboardEvent<HTMLDivElement>) => {
     if (event.key === 'Escape') {
       event.preventDefault();
-      setOpen(false);
-      setKeyboardOpen(false);
       triggerRef.current?.focus();
+      setOpen(false);
       return;
     }
     if (!['ArrowDown', 'ArrowUp', 'Home', 'End'].includes(event.key)) return;
@@ -191,7 +196,7 @@ export const ReasoningPresetSelector: React.FC<ReasoningPresetSelectorProps> = (
       data-bf-part="root"
       data-bf-state={open ? 'open' : undefined}
     >
-      <Tooltip content={tooltip}>
+      <Tooltip content={tooltip} disabled={open}>
         <button
           ref={triggerRef}
           type="button"
@@ -206,7 +211,11 @@ export const ReasoningPresetSelector: React.FC<ReasoningPresetSelectorProps> = (
           disabled={disabled || loading}
           onClick={(event) => {
             const nextOpen = !open;
-            setKeyboardOpen(nextOpen && event.detail === 0);
+            if (nextOpen) {
+              setKeyboardOpen(event.detail === 0);
+            } else if (event.detail !== 0) {
+              setKeyboardOpen(false);
+            }
             setOpen(nextOpen);
           }}
           onKeyDown={(event) => {
@@ -217,7 +226,6 @@ export const ReasoningPresetSelector: React.FC<ReasoningPresetSelectorProps> = (
             } else if (event.key === 'Escape' && open) {
               event.preventDefault();
               setOpen(false);
-              setKeyboardOpen(false);
             }
           }}
         >
@@ -233,15 +241,21 @@ export const ReasoningPresetSelector: React.FC<ReasoningPresetSelectorProps> = (
         </button>
       </Tooltip>
 
-      {open && createPortal(
-        <div
+      <PresenceBoundary active={open}>
+        {createPortal(
+          <div
           id={menuId}
           ref={menuRef}
           className="bitfun-reasoning-preset-selector__menu"
           data-bf-component="reasoning-preset-selector"
           data-bf-part="menu"
+          data-placement={resolvedPlacement}
+          data-open={open ? 'true' : 'false'}
+          data-keyboard-open={keyboardOpen ? 'true' : 'false'}
           style={menuStyle}
           role="menu"
+          aria-hidden={!open}
+          {...(!open ? { inert: '' } : {})}
           aria-label={t('reasoningSelector.title')}
           data-testid="chat-reasoning-preset-selector-menu"
           onKeyDown={handleMenuKeyDown}
@@ -301,9 +315,10 @@ export const ReasoningPresetSelector: React.FC<ReasoningPresetSelectorProps> = (
               </Tooltip>
             );
           })}
-        </div>,
-        getAppearanceOverlayHost(),
-      )}
+          </div>,
+          getAppearanceOverlayHost(),
+        )}
+      </PresenceBoundary>
     </div>
   );
 };
diff --git a/src/web-ui/src/flow_chat/components/RichTextInput.scss b/src/web-ui/src/flow_chat/components/RichTextInput.scss
index acfaa208a3..8637d49e11 100644
--- a/src/web-ui/src/flow_chat/components/RichTextInput.scss
+++ b/src/web-ui/src/flow_chat/components/RichTextInput.scss
@@ -86,7 +86,10 @@
   user-select: text;
   vertical-align: middle;
   line-height: var(--bf-appearance-token-flowchat-support-line-height);
-  transition: all 0.2s ease;
+  transition:
+    background-color 160ms ease,
+    border-color 160ms ease,
+    color 160ms ease;
   white-space: nowrap;
   
   &:hover {
@@ -143,7 +146,9 @@
   user-select: none;
   vertical-align: middle;
   line-height: var(--bf-appearance-token-flowchat-support-line-height);
-  transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
+  transition:
+    background-color 160ms ease,
+    color 160ms ease;
   
   &:hover {
     background: color-mix(in srgb, var(--bf-appearance-token-color-accent-500) 18%, transparent);
diff --git a/src/web-ui/src/flow_chat/components/ScrollPresenceFocus.test.tsx b/src/web-ui/src/flow_chat/components/ScrollPresenceFocus.test.tsx
new file mode 100644
index 0000000000..2b6f9ef4a5
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/ScrollPresenceFocus.test.tsx
@@ -0,0 +1,139 @@
+/** @vitest-environment jsdom */
+
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { ScrollToBottomButton } from './ScrollToBottomButton';
+import { ScrollToLatestBar } from './ScrollToLatestBar';
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+vi.mock('@/component-library', async () => {
+  const { PresenceBoundary } = await import(
+    '@/component-library/components/PresenceBoundary/PresenceBoundary'
+  );
+  return {
+    PresenceBoundary,
+    Tooltip: ({ children }: { children: React.ReactNode }) => children,
+  };
+});
+
+describe('retained scroll controls', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    vi.useRealTimers();
+  });
+
+  it('returns focus from the scroll-to-bottom button before its retained exit', () => {
+    const focusTarget = document.createElement('div');
+    focusTarget.tabIndex = -1;
+    document.body.appendChild(focusTarget);
+    const focusReturnRef = { current: focusTarget };
+    act(() => {
+      root.render(
+        <ScrollToBottomButton
+          visible
+          onClick={vi.fn()}
+          focusReturnRef={focusReturnRef}
+        />,
+      );
+    });
+    const button = container.querySelector<HTMLButtonElement>('button');
+    button?.focus();
+    expect(document.activeElement).toBe(button);
+
+    act(() => {
+      root.render(
+        <ScrollToBottomButton
+          visible={false}
+          onClick={vi.fn()}
+          focusReturnRef={focusReturnRef}
+        />,
+      );
+    });
+
+    expect(document.activeElement).toBe(focusTarget);
+    expect(button?.getAttribute('aria-hidden')).toBe('true');
+    expect(button?.hasAttribute('inert')).toBe(true);
+    expect(button?.tabIndex).toBe(-1);
+    act(() => vi.advanceTimersByTime(199));
+    expect(container.querySelector('button')).not.toBeNull();
+    act(() => vi.advanceTimersByTime(1));
+    expect(container.querySelector('button')).toBeNull();
+    focusTarget.remove();
+  });
+
+  it('returns focus from the scroll-to-latest bar before its retained exit', () => {
+    const focusTarget = document.createElement('div');
+    focusTarget.tabIndex = -1;
+    document.body.appendChild(focusTarget);
+    const focusReturnRef = { current: focusTarget };
+    act(() => {
+      root.render(
+        <ScrollToLatestBar
+          visible
+          onClick={vi.fn()}
+          focusReturnRef={focusReturnRef}
+        />,
+      );
+    });
+    const bar = container.querySelector<HTMLElement>('[role="button"]');
+    bar?.focus();
+    expect(document.activeElement).toBe(bar);
+
+    act(() => {
+      root.render(
+        <ScrollToLatestBar
+          visible={false}
+          onClick={vi.fn()}
+          focusReturnRef={focusReturnRef}
+        />,
+      );
+    });
+
+    expect(document.activeElement).toBe(focusTarget);
+    expect(bar?.getAttribute('aria-hidden')).toBe('true');
+    expect(bar?.hasAttribute('inert')).toBe(true);
+    expect(bar?.tabIndex).toBe(-1);
+    act(() => vi.advanceTimersByTime(199));
+    expect(container.querySelector('[role="button"]')).not.toBeNull();
+    act(() => vi.advanceTimersByTime(1));
+    expect(container.querySelector('[role="button"]')).toBeNull();
+    focusTarget.remove();
+  });
+
+  it('cancels removal when a scroll affordance reappears quickly', () => {
+    act(() => {
+      root.render(<ScrollToBottomButton visible onClick={vi.fn()} unreadCount={2} />);
+    });
+    act(() => {
+      root.render(<ScrollToBottomButton visible={false} onClick={vi.fn()} unreadCount={2} />);
+    });
+    act(() => vi.advanceTimersByTime(100));
+    act(() => {
+      root.render(<ScrollToBottomButton visible onClick={vi.fn()} unreadCount={3} />);
+    });
+    act(() => vi.advanceTimersByTime(200));
+
+    const button = container.querySelector<HTMLButtonElement>('button');
+    expect(button).not.toBeNull();
+    expect(button?.getAttribute('aria-hidden')).toBe('false');
+    expect(button?.hasAttribute('inert')).toBe(false);
+    expect(button?.textContent).toContain('3');
+  });
+});
diff --git a/src/web-ui/src/flow_chat/components/ScrollToBottomButton.scss b/src/web-ui/src/flow_chat/components/ScrollToBottomButton.scss
index 11f14d7b61..49fc248ac5 100644
--- a/src/web-ui/src/flow_chat/components/ScrollToBottomButton.scss
+++ b/src/web-ui/src/flow_chat/components/ScrollToBottomButton.scss
@@ -32,21 +32,21 @@
   
   cursor: pointer;
   transition:
-    transform 140ms cubic-bezier(0.23, 1, 0.32, 1),
-    opacity 140ms ease;
+    transform 100ms cubic-bezier(0.23, 1, 0.32, 1),
+    opacity 100ms ease;
+
+  &[data-visible='true'] {
+    @starting-style {
+      opacity: 0;
+    }
+  }
   
   z-index: 10;
 
-  &:hover {
-    background: color-mix(in srgb, var(--bf-appearance-token-color-bg-elevated) 98%, transparent);
-    color: var(--bf-appearance-token-color-text-primary);
-    border-color: var(--bf-appearance-token-color-text-primary);
-    transform: translateY(-2px);
-
-    box-shadow:
-      0 8px 22px rgba(var(--bf-appearance-token-color-static-black-rgb), 0.42),
-      0 0 0 1px color-mix(in srgb, var(--bf-appearance-token-color-text-primary) 40%, transparent),
-      inset 0 1px 0 color-mix(in srgb, var(--bf-appearance-token-color-text-primary) 16%, transparent);
+  &[data-visible='false'] {
+    opacity: 0;
+    transform: translateY(4px) scale(0.97);
+    pointer-events: none;
   }
 
   &:active {
@@ -95,6 +95,20 @@
   }
 }
 
+@media (hover: hover) and (pointer: fine) {
+  .scroll-to-bottom-button[data-visible='true']:hover {
+    background: color-mix(in srgb, var(--bf-appearance-token-color-bg-elevated) 98%, transparent);
+    color: var(--bf-appearance-token-color-text-primary);
+    border-color: var(--bf-appearance-token-color-text-primary);
+    transform: translateY(-2px);
+
+    box-shadow:
+      0 8px 22px rgba(var(--bf-appearance-token-color-static-black-rgb), 0.42),
+      0 0 0 1px color-mix(in srgb, var(--bf-appearance-token-color-text-primary) 40%, transparent),
+      inset 0 1px 0 color-mix(in srgb, var(--bf-appearance-token-color-text-primary) 16%, transparent);
+  }
+}
+
 // Responsive tweaks
 @media (max-width: 768px) {
   .scroll-to-bottom-button {
diff --git a/src/web-ui/src/flow_chat/components/ScrollToBottomButton.tsx b/src/web-ui/src/flow_chat/components/ScrollToBottomButton.tsx
index 1dc816eb64..ba7bb25af1 100644
--- a/src/web-ui/src/flow_chat/components/ScrollToBottomButton.tsx
+++ b/src/web-ui/src/flow_chat/components/ScrollToBottomButton.tsx
@@ -3,9 +3,9 @@
  * Shows when the user scrolls up; click to return to latest messages.
  */
 
-import React from 'react';
+import React, { useLayoutEffect, useRef } from 'react';
 import { useTranslation } from 'react-i18next';
-import { Tooltip } from '@/component-library';
+import { PresenceBoundary, Tooltip } from '@/component-library';
 import './ScrollToBottomButton.scss';
 
 interface ScrollToBottomButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'onClick'> {
@@ -13,6 +13,7 @@ interface ScrollToBottomButtonProps extends Omit<React.ButtonHTMLAttributes<HTML
   onClick: () => void;
   unreadCount?: number; // Optional: show unread message count.
   className?: string;
+  focusReturnRef?: React.RefObject<HTMLElement | null>;
 }
 
 export const ScrollToBottomButton: React.FC<ScrollToBottomButtonProps> = ({
@@ -20,39 +21,57 @@ export const ScrollToBottomButton: React.FC<ScrollToBottomButtonProps> = ({
   onClick,
   unreadCount,
   className = '',
+  focusReturnRef,
   ...buttonProps
 }) => {
   const { t } = useTranslation('flow-chat');
-  
-  if (!visible) return null;
+  const buttonRef = useRef<HTMLButtonElement>(null);
+
+  useLayoutEffect(() => {
+    if (!visible && buttonRef.current?.contains(document.activeElement)) {
+      const focusTarget = focusReturnRef?.current;
+      if (focusTarget) {
+        focusTarget.focus({ preventScroll: true });
+      } else {
+        buttonRef.current.blur();
+      }
+    }
+  }, [focusReturnRef, visible]);
 
   return (
-    <Tooltip content={t('scroll.toBottom')}>
-      <button data-bf-component="scroll-to-bottom-button" data-bf-part="root"
-        className={`scroll-to-bottom-button ${className}`}
-        onClick={onClick}
-        aria-label={unreadCount ? t('scroll.toBottomWithCount', { count: unreadCount }) : t('scroll.toBottom')}
-        {...buttonProps}
-      >
-        <svg
-          data-bf-component="scroll-to-bottom-button"
-          data-bf-part="icon"
-          className="scroll-icon"
-          width="20"
-          height="20"
-          viewBox="0 0 24 24"
-          fill="none"
-          stroke="currentColor"
-          strokeWidth="3"
-          strokeLinecap="round"
-          strokeLinejoin="round"
+    <PresenceBoundary active={visible}>
+      <Tooltip content={t('scroll.toBottom')} disabled={!visible}>
+        <button data-bf-component="scroll-to-bottom-button" data-bf-part="root"
+          ref={buttonRef}
+          {...buttonProps}
+          data-visible={visible ? 'true' : 'false'}
+          className={`scroll-to-bottom-button ${className}`}
+          onClick={visible ? onClick : undefined}
+          aria-hidden={!visible}
+          aria-label={unreadCount ? t('scroll.toBottomWithCount', { count: unreadCount }) : t('scroll.toBottom')}
+          tabIndex={visible ? buttonProps.tabIndex : -1}
+          {...(!visible ? { inert: '' } : {})}
         >
-          <polyline points="6 9 12 15 18 9" />
-        </svg>
-        {unreadCount !== undefined && unreadCount > 0 && (
-          <span data-bf-component="scroll-to-bottom-button" data-bf-part="badge" className="unread-badge">{unreadCount > 99 ? '99+' : unreadCount}</span>
-        )}
-      </button>
-    </Tooltip>
+          <svg
+            data-bf-component="scroll-to-bottom-button"
+            data-bf-part="icon"
+            className="scroll-icon"
+            width="20"
+            height="20"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="3"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+          >
+            <polyline points="6 9 12 15 18 9" />
+          </svg>
+          {unreadCount !== undefined && unreadCount > 0 && (
+            <span data-bf-component="scroll-to-bottom-button" data-bf-part="badge" className="unread-badge">{unreadCount > 99 ? '99+' : unreadCount}</span>
+          )}
+        </button>
+      </Tooltip>
+    </PresenceBoundary>
   );
 };
diff --git a/src/web-ui/src/flow_chat/components/ScrollToLatestBar.scss b/src/web-ui/src/flow_chat/components/ScrollToLatestBar.scss
index 70bf442ec1..4429cc632e 100644
--- a/src/web-ui/src/flow_chat/components/ScrollToLatestBar.scss
+++ b/src/web-ui/src/flow_chat/components/ScrollToLatestBar.scss
@@ -18,6 +18,20 @@
   
   // Height follows live composer measurements; do not animate layout.
   transition: none;
+
+  &[data-visible='false'] {
+    pointer-events: none;
+
+    .scroll-to-latest-bar__gradient,
+    .scroll-to-latest-bar__content {
+      opacity: 0;
+    }
+
+    .scroll-to-latest-bar__content {
+      transform: translateY(4px);
+      pointer-events: none;
+    }
+  }
   
   // ========== ChatInput collapsed ==========
   &--input-collapsed {
@@ -48,6 +62,7 @@
       var(--bf-appearance-token-color-overlay-black-80) 60%,
       black 85%
     );
+    transition: opacity 140ms ease;
   }
   
   // ========== Divider content layer ==========
@@ -63,7 +78,15 @@
     align-items: center;
     justify-content: center;
     
-    transition: opacity 140ms ease;
+    transition:
+      opacity 100ms ease,
+      transform 100ms cubic-bezier(0.23, 1, 0.32, 1);
+
+    .scroll-to-latest-bar[data-visible='true'] & {
+      @starting-style {
+        opacity: 0;
+      }
+    }
   }
   
   // ========== Circle arrow button ==========
@@ -86,15 +109,6 @@
       opacity 120ms ease;
   }
   
-  // ========== Hover state ==========
-  &:hover {
-    .scroll-to-latest-bar__btn {
-      border-color: var(--bf-appearance-token-border-medium);
-      color: var(--bf-appearance-token-color-text-primary);
-      transform: translateY(1px);
-    }
-  }
-  
   // ========== Active state ==========
   &:active {
     .scroll-to-latest-bar__btn {
@@ -113,11 +127,21 @@
   }
 }
 
+@media (hover: hover) and (pointer: fine) {
+  .scroll-to-latest-bar[data-visible='true']:hover .scroll-to-latest-bar__btn {
+    border-color: var(--bf-appearance-token-border-medium);
+    color: var(--bf-appearance-token-color-text-primary);
+    transform: translateY(1px);
+  }
+}
+
 @media (prefers-reduced-motion: reduce) {
   .scroll-to-latest-bar__content,
-  .scroll-to-latest-bar__btn {
+  .scroll-to-latest-bar__btn,
+  .scroll-to-latest-bar__gradient {
     transition-duration: 0ms;
   }
+
 }
 
 // ========== Responsive tweaks ==========
diff --git a/src/web-ui/src/flow_chat/components/ScrollToLatestBar.tsx b/src/web-ui/src/flow_chat/components/ScrollToLatestBar.tsx
index 194f5bc373..f94c0dd9a1 100644
--- a/src/web-ui/src/flow_chat/components/ScrollToLatestBar.tsx
+++ b/src/web-ui/src/flow_chat/components/ScrollToLatestBar.tsx
@@ -3,8 +3,9 @@
  * Minimal divider style with a soft fade.
  */
 
-import React from 'react';
+import React, { useLayoutEffect, useRef } from 'react';
 import { useTranslation } from 'react-i18next';
+import { PresenceBoundary } from '@/component-library';
 import {
   CHAT_INPUT_DROP_ZONE_BOTTOM_PX,
   SCROLL_TO_LATEST_INPUT_CLEARANCE_PX,
@@ -21,6 +22,7 @@ interface ScrollToLatestBarProps {
   /** Measured height of the ChatInput container in pixels (0 if unknown). */
   inputHeight?: number;
   className?: string;
+  focusReturnRef?: React.RefObject<HTMLElement | null>;
 }
 
 export const ScrollToLatestBar: React.FC<ScrollToLatestBarProps> = ({
@@ -29,11 +31,22 @@ export const ScrollToLatestBar: React.FC<ScrollToLatestBarProps> = ({
   isInputExpanded = false,
   isInputActive = true,
   inputHeight = 0,
-  className = ''
+  className = '',
+  focusReturnRef,
 }) => {
   const { t } = useTranslation('flow-chat');
-  
-  if (!visible) return null;
+  const barRef = useRef<HTMLDivElement>(null);
+
+  useLayoutEffect(() => {
+    if (!visible && barRef.current?.contains(document.activeElement)) {
+      const focusTarget = focusReturnRef?.current;
+      if (focusTarget) {
+        focusTarget.focus({ preventScroll: true });
+      } else {
+        (document.activeElement as HTMLElement).blur();
+      }
+    }
+  }, [focusReturnRef, visible]);
 
   // Derive the modifier class from ChatInput state.
   const inputStateClass = !isInputActive 
@@ -64,33 +77,39 @@ export const ScrollToLatestBar: React.FC<ScrollToLatestBarProps> = ({
   }
 
   return (
-    <div
-      data-bf-component="scroll-to-latest-bar"
-      data-bf-part="root"
-      data-bf-input={!isInputActive ? 'collapsed' : isInputExpanded ? 'expanded' : 'active'}
-      className={`scroll-to-latest-bar ${inputStateClass} ${className}`}
-      style={dynamicStyle}
-      onClick={onClick}
-      role="button"
-      tabIndex={0}
-      onKeyDown={(e) => {
-        if (e.key === 'Enter' || e.key === ' ') {
-          e.preventDefault();
-          onClick();
-        }
-      }}
-      aria-label={t('scroll.toLatest')}
-    >
-      <div data-bf-component="scroll-to-latest-bar" data-bf-part="gradient" className="scroll-to-latest-bar__gradient" />
-      
-      <div data-bf-component="scroll-to-latest-bar" data-bf-part="content" className="scroll-to-latest-bar__content" style={contentStyle}>
-        <button data-bf-component="scroll-to-latest-bar" data-bf-part="button" className="scroll-to-latest-bar__btn" aria-hidden="true" tabIndex={-1}>
-          <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
-            <path d="M8 3.5V12.5M8 12.5L4 8.5M8 12.5L12 8.5" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round"/>
-          </svg>
-        </button>
+    <PresenceBoundary active={visible}>
+      <div
+        ref={barRef}
+        data-bf-component="scroll-to-latest-bar"
+        data-bf-part="root"
+        data-bf-input={!isInputActive ? 'collapsed' : isInputExpanded ? 'expanded' : 'active'}
+        data-visible={visible ? 'true' : 'false'}
+        className={`scroll-to-latest-bar ${inputStateClass} ${className}`}
+        style={dynamicStyle}
+        onClick={visible ? onClick : undefined}
+        role="button"
+        tabIndex={visible ? 0 : -1}
+        onKeyDown={(e) => {
+          if (visible && (e.key === 'Enter' || e.key === ' ')) {
+            e.preventDefault();
+            onClick();
+          }
+        }}
+        aria-hidden={!visible}
+        {...(!visible ? { inert: '' } : {})}
+        aria-label={t('scroll.toLatest')}
+      >
+        <div data-bf-component="scroll-to-latest-bar" data-bf-part="gradient" className="scroll-to-latest-bar__gradient" />
+
+        <div data-bf-component="scroll-to-latest-bar" data-bf-part="content" className="scroll-to-latest-bar__content" style={contentStyle}>
+          <button data-bf-component="scroll-to-latest-bar" data-bf-part="button" className="scroll-to-latest-bar__btn" aria-hidden="true" tabIndex={-1}>
+            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+              <path d="M8 3.5V12.5M8 12.5L4 8.5M8 12.5L12 8.5" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round"/>
+            </svg>
+          </button>
+        </div>
       </div>
-    </div>
+    </PresenceBoundary>
   );
 };
 
diff --git a/src/web-ui/src/flow_chat/components/ScrollToTurnHeaderButton.scss b/src/web-ui/src/flow_chat/components/ScrollToTurnHeaderButton.scss
index 11fa36380e..52b95bb3b6 100644
--- a/src/web-ui/src/flow_chat/components/ScrollToTurnHeaderButton.scss
+++ b/src/web-ui/src/flow_chat/components/ScrollToTurnHeaderButton.scss
@@ -7,7 +7,7 @@
   position: absolute;
   left: 0;
   right: 0;
-  top: 57px; // Keep in sync with `.message-list-header` height.
+  top: 0; // FlowChatHeader is stacked above the list, so start at the viewport top.
   z-index: 10;
   pointer-events: none;
 
@@ -98,7 +98,7 @@
 // ========== Responsive tweaks ==========
 @media (max-width: 768px) {
   .scroll-to-turn-header-trigger {
-    top: 57px;
+    top: 0;
     height: 64px;
 
     &__btn {
diff --git a/src/web-ui/src/flow_chat/components/SnapshotRollbackButton.appearance.ts b/src/web-ui/src/flow_chat/components/SnapshotRollbackButton.appearance.ts
deleted file mode 100644
index 3ba11d201d..0000000000
--- a/src/web-ui/src/flow_chat/components/SnapshotRollbackButton.appearance.ts
+++ /dev/null
@@ -1,8 +0,0 @@
-import type { AppearanceSurfaceDescriptor } from '@/infrastructure/appearance';
-
-export const snapshotRollbackButtonAppearanceDescriptor: AppearanceSurfaceDescriptor = {
-  id: 'snapshot-rollback-button',
-  parts: [{ id: 'root' }, { id: 'label' }],
-  facets: [{ id: 'outcome', attribute: 'data-bf-outcome', values: ['idle', 'current', 'success', 'error'] }],
-  states: [{ id: 'loading', selector: { kind: 'self', suffix: '[data-bf-state~="loading"]' } }],
-};
diff --git a/src/web-ui/src/flow_chat/components/SnapshotRollbackButton.scss b/src/web-ui/src/flow_chat/components/SnapshotRollbackButton.scss
deleted file mode 100644
index 3f0d9fae4d..0000000000
--- a/src/web-ui/src/flow_chat/components/SnapshotRollbackButton.scss
+++ /dev/null
@@ -1,107 +0,0 @@
-/**
- * Turn snapshot rollback button styles.
- */
-
-.snapshot-rollback-button {
-  --snapshot-rollback-error-color: var(--bf-appearance-token-color-error);
-  --snapshot-rollback-error-bg: var(--bf-appearance-token-color-error-bg);
-
-  display: inline-flex;
-  align-items: center;
-  gap: 6px;
-  padding: 4px 12px;
-  font-size: var(--bf-appearance-token-tool-card-action-font-size);
-  font-weight: 500;
-  line-height: var(--bf-appearance-token-flowchat-support-line-height);
-  border-radius: 6px;
-  border: 1px solid var(--bf-appearance-token-border-base);
-  background: var(--bf-appearance-token-color-bg-elevated);
-  color: var(--bf-appearance-token-color-text-secondary);
-  cursor: pointer;
-  transition: all 0.2s ease;
-  white-space: nowrap;
-  
-  svg {
-    flex-shrink: 0;
-  }
-  
-  &:hover:not(:disabled) {
-    border-color: var(--bf-appearance-token-color-accent-500);
-    background: var(--bf-appearance-token-color-accent-100);
-    color: var(--bf-appearance-token-color-accent-500);
-    transform: translateY(-1px);
-    box-shadow: 0 2px 4px var(--bf-appearance-token-color-overlay-black-12);
-  }
-  
-  &:active:not(:disabled) {
-    transform: translateY(0);
-    box-shadow: 0 1px 2px var(--bf-appearance-token-color-overlay-black-12);
-  }
-  
-  &:disabled {
-    opacity: 0.5;
-    cursor: default;
-  }
-  
-  // Loading state
-  &--loading {
-    border-color: var(--bf-appearance-token-color-accent-500);
-    background: var(--bf-appearance-token-color-accent-100);
-    color: var(--bf-appearance-token-color-accent-500);
-    cursor: wait;
-  }
-  
-  // Success state
-  &--success {
-    border-color: var(--bf-appearance-token-color-success);
-    background: var(--bf-appearance-token-color-success-bg);
-    color: var(--bf-appearance-token-color-success);
-    cursor: default;
-    
-    &:hover {
-      transform: none;
-      box-shadow: none;
-    }
-  }
-  
-  // Error state
-  &--error {
-    border-color: var(--snapshot-rollback-error-color);
-    background: var(--snapshot-rollback-error-bg);
-    color: var(--snapshot-rollback-error-color);
-    cursor: default;
-    
-    &:hover {
-      transform: none;
-      box-shadow: none;
-    }
-  }
-  
-  // Current turn marker
-  &--current {
-    border-color: var(--bf-appearance-token-color-success);
-    background: var(--bf-appearance-token-color-success-bg);
-    color: var(--bf-appearance-token-color-success);
-    cursor: default;
-    font-weight: 600;
-    
-    &:hover {
-      transform: none;
-      box-shadow: none;
-    }
-  }
-  
-  // Spinner animation
-  &__spinner {
-    animation: spin 1s linear infinite;
-  }
-}
-
-@keyframes spin {
-  from {
-    transform: rotate(0deg);
-  }
-  to {
-    transform: rotate(360deg);
-  }
-}
diff --git a/src/web-ui/src/flow_chat/components/SnapshotRollbackButton.tsx b/src/web-ui/src/flow_chat/components/SnapshotRollbackButton.tsx
deleted file mode 100644
index 65d5d03a9f..0000000000
--- a/src/web-ui/src/flow_chat/components/SnapshotRollbackButton.tsx
+++ /dev/null
@@ -1,124 +0,0 @@
-/**
- * Turn snapshot rollback button.
- * Allows rolling back to a specific dialog turn's code state.
- */
-
-import React, { useState } from 'react';
-import { RotateCcw, Check, AlertCircle, Loader2 } from 'lucide-react';
-import { invoke } from '@tauri-apps/api/core';
-import { createLogger } from '@/shared/utils/logger';
-import './SnapshotRollbackButton.scss';
-
-const log = createLogger('SnapshotRollbackButton');
-
-export interface SnapshotRollbackButtonProps {
-  sessionId: string;
-  turnIndex: number;
-  turnId: string;
-  isCurrentTurn?: boolean;
-  onRollbackSuccess?: () => void;
-  onRollbackError?: (error: string) => void;
-}
-
-export const SnapshotRollbackButton: React.FC<SnapshotRollbackButtonProps> = ({
-  sessionId,
-  turnIndex,
-  turnId,
-  isCurrentTurn = false,
-  onRollbackSuccess,
-  onRollbackError
-}) => {
-  const [isRollingBack, setIsRollingBack] = useState(false);
-  const [rollbackStatus, setRollbackStatus] = useState<'idle' | 'success' | 'error'>('idle');
-  const [errorMessage, setErrorMessage] = useState<string>('');
-
-  const handleRollback = async () => {
-    if (isRollingBack || isCurrentTurn) return;
-
-    try {
-      setIsRollingBack(true);
-      setRollbackStatus('idle');
-      setErrorMessage('');
-
-      log.debug('Starting rollback', { sessionId, turnIndex, turnId });
-
-      // Call backend API to roll back.
-      await invoke('rollback_to_turn', {
-        sessionId,
-        turnIndex
-      });
-
-      setRollbackStatus('success');
-      onRollbackSuccess?.();
-
-      // Reset status after 3 seconds.
-      setTimeout(() => {
-        setRollbackStatus('idle');
-      }, 3000);
-
-    } catch (error) {
-      log.error('Rollback failed', { sessionId, turnIndex, turnId, error });
-      const errorMsg = error instanceof Error ? error.message : String(error);
-      setErrorMessage(errorMsg);
-      setRollbackStatus('error');
-      onRollbackError?.(errorMsg);
-
-      // Reset error state after 5 seconds.
-      setTimeout(() => {
-        setRollbackStatus('idle');
-        setErrorMessage('');
-      }, 5000);
-    } finally {
-      setIsRollingBack(false);
-    }
-  };
-
-  if (isCurrentTurn) {
-    return (
-      <div data-bf-component="snapshot-rollback-button" data-bf-part="root" data-bf-outcome="current" className="snapshot-rollback-button snapshot-rollback-button--current">
-        <Check size={14} />
-        <span data-bf-component="snapshot-rollback-button" data-bf-part="label">Current code state</span>
-      </div>
-    );
-  }
-
-  if (rollbackStatus === 'success') {
-    return (
-      <div data-bf-component="snapshot-rollback-button" data-bf-part="root" data-bf-outcome="success" className="snapshot-rollback-button snapshot-rollback-button--success">
-        <Check size={14} />
-        <span data-bf-component="snapshot-rollback-button" data-bf-part="label">Rolled back to this turn</span>
-      </div>
-    );
-  }
-
-  if (rollbackStatus === 'error') {
-    return (
-      <div data-bf-component="snapshot-rollback-button" data-bf-part="root" data-bf-outcome="error" className="snapshot-rollback-button snapshot-rollback-button--error" title={errorMessage}>
-        <AlertCircle size={14} />
-        <span data-bf-component="snapshot-rollback-button" data-bf-part="label">Rollback failed</span>
-      </div>
-    );
-  }
-
-  return (
-    <button data-bf-component="snapshot-rollback-button" data-bf-part="root" data-bf-outcome="idle" data-bf-state={isRollingBack ? 'loading' : ''}
-      className={`snapshot-rollback-button ${isRollingBack ? 'snapshot-rollback-button--loading' : ''}`}
-      onClick={handleRollback}
-      disabled={isRollingBack}
-      title={`Rollback to code state at turn ${turnIndex + 1}`}
-    >
-      {isRollingBack ? (
-        <>
-          <Loader2 size={14} className="snapshot-rollback-button__spinner" />
-          <span data-bf-component="snapshot-rollback-button" data-bf-part="label">Rolling back...</span>
-        </>
-      ) : (
-        <>
-          <RotateCcw size={14} />
-          <span data-bf-component="snapshot-rollback-button" data-bf-part="label">Rollback to this turn</span>
-        </>
-      )}
-    </button>
-  );
-};
-
diff --git a/src/web-ui/src/flow_chat/components/StickyTaskIndicator.appearance.ts b/src/web-ui/src/flow_chat/components/StickyTaskIndicator.appearance.ts
deleted file mode 100644
index 3f4bc2d016..0000000000
--- a/src/web-ui/src/flow_chat/components/StickyTaskIndicator.appearance.ts
+++ /dev/null
@@ -1,10 +0,0 @@
-import type { AppearanceSurfaceDescriptor } from '@/infrastructure/appearance';
-
-export const stickyTaskIndicatorAppearanceDescriptor: AppearanceSurfaceDescriptor = {
-  id: 'sticky-task-indicator',
-  parts: [
-    { id: 'root' }, { id: 'gradient' }, { id: 'content' }, { id: 'button' },
-    { id: 'icon' }, { id: 'label' }, { id: 'arrow' },
-  ],
-  states: [{ id: 'visible', selector: { kind: 'self', suffix: '[data-bf-state~="visible"]' } }],
-};
diff --git a/src/web-ui/src/flow_chat/components/StickyTaskIndicator.scss b/src/web-ui/src/flow_chat/components/StickyTaskIndicator.scss
deleted file mode 100644
index bd0ee94bbc..0000000000
--- a/src/web-ui/src/flow_chat/components/StickyTaskIndicator.scss
+++ /dev/null
@@ -1,132 +0,0 @@
-/**
- * Sticky task indicator styles.
- * Fixed at the top of the flowchat message list with a gradient fade.
- */
-
-.sticky-task-indicator {
-  position: absolute;
-  left: 0;
-  right: 0;
-  top: 93px; // Below FlowChatHeader (36px) + ScrollToTurnHeaderButton hover zone (57px).
-  z-index: 10;
-  pointer-events: none;
-
-  // Trigger area height: 40px hover zone + 20px gradient.
-  height: 60px;
-
-  opacity: 0;
-  transition: opacity 140ms ease;
-
-  // ========== Visible state ==========
-  &--visible {
-    opacity: 1;
-    pointer-events: auto;
-  }
-
-  // ========== Gradient background layer ==========
-  &__gradient {
-    position: absolute;
-    inset: 0;
-    pointer-events: none;
-
-    background: linear-gradient(
-      to bottom,
-      var(--bf-appearance-token-color-bg-scene) 0%,
-      color-mix(in srgb, var(--bf-appearance-token-color-bg-scene) 80%, transparent) 40%,
-      color-mix(in srgb, var(--bf-appearance-token-color-bg-scene) 40%, transparent) 70%,
-      transparent 100%
-    );
-  }
-
-  // ========== Content layer ==========
-  &__content {
-    position: absolute;
-    top: 8px;
-    left: 0;
-    right: 0;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-
-    transition: transform 140ms cubic-bezier(0.23, 1, 0.32, 1);
-  }
-
-  // ========== Task label button ==========
-  &__btn {
-    display: inline-flex;
-    align-items: center;
-    gap: 6px;
-    max-width: min(480px, 70vw);
-    height: 28px;
-    padding: 0 10px;
-    border-radius: 999px;
-    border: 1px solid var(--bf-appearance-token-border-base);
-    background: var(--bf-appearance-token-color-bg-scene);
-    color: var(--bf-appearance-token-color-text-muted);
-    cursor: pointer;
-    font-size: var(--bf-appearance-token-flowchat-font-size-xs);
-    line-height: 1;
-    white-space: nowrap;
-
-    box-shadow: 0 6px 16px var(--bf-appearance-token-color-overlay-black-15);
-    transition:
-      transform 120ms cubic-bezier(0.23, 1, 0.32, 1),
-      opacity 120ms ease;
-
-    &:hover {
-      border-color: var(--bf-appearance-token-border-medium);
-      color: var(--bf-appearance-token-color-text-primary);
-      transform: translateY(-1px);
-    }
-
-    &:active {
-      transform: scale(0.97);
-    }
-
-    &:focus-visible {
-      outline: none;
-      border-color: var(--bf-appearance-token-border-strong);
-      color: var(--bf-appearance-token-color-text-primary);
-      box-shadow: 0 0 0 1.5px var(--bf-appearance-token-border-strong);
-    }
-  }
-
-  &__icon {
-    flex-shrink: 0;
-    opacity: 0.75;
-  }
-
-  &__label {
-    min-width: 0;
-    overflow: hidden;
-    text-overflow: ellipsis;
-    white-space: nowrap;
-  }
-
-  &__arrow {
-    flex-shrink: 0;
-    opacity: 0.6;
-  }
-}
-
-@media (prefers-reduced-motion: reduce) {
-  .sticky-task-indicator,
-  .sticky-task-indicator__content,
-  .sticky-task-indicator__btn {
-    transition-duration: 0ms;
-  }
-}
-
-// ========== Responsive tweaks ==========
-@media (max-width: 768px) {
-  .sticky-task-indicator {
-    top: 93px;
-    height: 52px;
-
-    &__btn {
-      height: 26px;
-      padding: 0 8px;
-      max-width: min(320px, 80vw);
-    }
-  }
-}
diff --git a/src/web-ui/src/flow_chat/components/StickyTaskIndicator.tsx b/src/web-ui/src/flow_chat/components/StickyTaskIndicator.tsx
deleted file mode 100644
index e6dec703a9..0000000000
--- a/src/web-ui/src/flow_chat/components/StickyTaskIndicator.tsx
+++ /dev/null
@@ -1,59 +0,0 @@
-/**
- * Sticky task indicator.
- * Shows at the top of the message list when the user has scrolled past a Task
- * tool card, indicating which Task they are currently reading.
- * Clicking the indicator scrolls the Task to the viewport top.
- */
-
-import React from 'react';
-import { useTranslation } from 'react-i18next';
-import { Split, ChevronUp } from 'lucide-react';
-import { Tooltip } from '@/component-library';
-import type { VisibleTaskInfo } from '../hooks/useVisibleTaskInfo';
-import './StickyTaskIndicator.scss';
-
-interface StickyTaskIndicatorProps {
-  visible: boolean;
-  taskInfo: VisibleTaskInfo | null;
-  onClick: () => void;
-}
-
-export const StickyTaskIndicator: React.FC<StickyTaskIndicatorProps> = ({
-  visible,
-  taskInfo,
-  onClick,
-}) => {
-  const { t } = useTranslation('flow-chat');
-
-  const label = taskInfo?.label || t('toolCards.taskTool.defaultAgentKind');
-  const tooltip = t('stickyTaskIndicator.tooltip');
-
-  return (
-    <div data-bf-component="sticky-task-indicator" data-bf-part="root" data-bf-state={visible ? 'visible' : ''}
-      className={`sticky-task-indicator ${visible ? 'sticky-task-indicator--visible' : ''}`}
-      aria-hidden={!visible}
-    >
-      <div data-bf-component="sticky-task-indicator" data-bf-part="gradient" className="sticky-task-indicator__gradient" />
-      <div data-bf-component="sticky-task-indicator" data-bf-part="content" className="sticky-task-indicator__content">
-        <Tooltip content={tooltip} placement="bottom">
-          <button
-            data-bf-component="sticky-task-indicator"
-            data-bf-part="button"
-            className="sticky-task-indicator__btn"
-            onClick={onClick}
-            aria-label={tooltip}
-            tabIndex={visible ? 0 : -1}
-          >
-            <Split size={12} data-bf-component="sticky-task-indicator" data-bf-part="icon" className="sticky-task-indicator__icon" />
-            <span data-bf-component="sticky-task-indicator" data-bf-part="label" className="sticky-task-indicator__label" title={label}>
-              {label}
-            </span>
-            <ChevronUp size={12} data-bf-component="sticky-task-indicator" data-bf-part="arrow" className="sticky-task-indicator__arrow" />
-          </button>
-        </Tooltip>
-      </div>
-    </div>
-  );
-};
-
-StickyTaskIndicator.displayName = 'StickyTaskIndicator';
diff --git a/src/web-ui/src/flow_chat/components/TaskDetailPanel/TaskDetailPanel.scss b/src/web-ui/src/flow_chat/components/TaskDetailPanel/TaskDetailPanel.scss
index 54ca42a255..23a9296672 100644
--- a/src/web-ui/src/flow_chat/components/TaskDetailPanel/TaskDetailPanel.scss
+++ b/src/web-ui/src/flow_chat/components/TaskDetailPanel/TaskDetailPanel.scss
@@ -135,7 +135,9 @@
       color: var(--bf-appearance-token-color-text-secondary);
       cursor: pointer;
       user-select: none;
-      transition: all 0.15s ease;
+      transition:
+        color 150ms ease,
+        border-color 150ms ease;
       border: 1px dashed var(--bf-appearance-token-border-base);
       border-radius: 6px;
 
@@ -200,7 +202,9 @@
       color: var(--bf-appearance-token-color-text-secondary);
       cursor: pointer;
       user-select: none;
-      transition: all 0.15s ease;
+      transition:
+        color 150ms ease,
+        border-color 150ms ease;
       border: 1px dashed var(--bf-appearance-token-border-base);
       border-radius: 6px;
 
@@ -325,4 +329,3 @@
     }
   }
 }
-
diff --git a/src/web-ui/src/flow_chat/components/TokenUsageIndicator.scss b/src/web-ui/src/flow_chat/components/TokenUsageIndicator.scss
index bdcd8c06af..a5f5a01e35 100644
--- a/src/web-ui/src/flow_chat/components/TokenUsageIndicator.scss
+++ b/src/web-ui/src/flow_chat/components/TokenUsageIndicator.scss
@@ -13,12 +13,12 @@
   border-radius: 8px;
   font-size: var(--bf-appearance-token-flowchat-font-size-xxs);
   font-weight: 600;
-  transition: all 0.25s ease;
+  transition: opacity 140ms ease;
   cursor: default;
   white-space: nowrap;
   overflow: hidden;
   min-width: 48px;
-  height: 6px;
+  height: 18px;
   opacity: 0;
   pointer-events: none;
   
@@ -31,28 +31,32 @@
   // Progress track (background)
   &__progress-track {
     position: absolute;
-    top: 0;
+    top: 50%;
     left: 0;
     right: 0;
-    bottom: 0;
+    height: 6px;
+    transform: translateY(-50%);
     background: var(--bf-appearance-token-color-overlay-white-08);
     border-radius: 8px;
     overflow: hidden;
+    transition:
+      background-color 140ms ease,
+      border-color 140ms ease;
   }
   
   // Progress fill
   &__progress-fill {
+    --token-usage-progress: 0;
+
     position: absolute;
     top: 0;
     left: 0;
     bottom: 0;
-    transition: width 0.3s ease, background 0.2s ease;
-    border-radius: 8px 0 0 8px;
-    
-    // When nearly full, round the right edge
-    &[style*="100%"] {
-      border-radius: 8px;
-    }
+    width: 100%;
+    transform: scaleX(var(--token-usage-progress));
+    transform-origin: left center;
+    transition: transform 140ms linear;
+    border-radius: inherit;
   }
   
   // Hover content
@@ -64,7 +68,7 @@
     z-index: 2;
     opacity: 0;
     pointer-events: none;
-    transition: opacity 0.2s ease;
+    transition: opacity 100ms ease;
     white-space: nowrap;
   }
   
@@ -74,20 +78,14 @@
     font-size: var(--bf-appearance-token-flowchat-font-size-xxs);
   }
   
-  // Hover behavior
-  &:hover {
-    height: 18px;
-    
-    .bitfun-token-usage__hover-content {
-      opacity: 1;
-    }
-  }
-  
   // Normal state (0-69%)
   &--normal {
-    background: var(--bf-appearance-token-glass-blue-subtle);
     color: var(--bf-appearance-token-color-accent-500);
-    border: 1px solid color-mix(in srgb, var(--bf-appearance-token-color-accent-600) 25%, transparent);
+
+    .bitfun-token-usage__progress-track {
+      background: var(--bf-appearance-token-glass-blue-subtle);
+      border: 1px solid color-mix(in srgb, var(--bf-appearance-token-color-accent-600) 25%, transparent);
+    }
     
     .bitfun-token-usage__progress-fill {
       background: linear-gradient(
@@ -97,26 +95,16 @@
       );
     }
     
-    &:hover {
-      background: color-mix(in srgb, var(--bf-appearance-token-color-accent-600) 12%, transparent);
-      border-color: var(--bf-appearance-token-color-accent-400);
-      
-      .bitfun-token-usage__progress-fill {
-        background: linear-gradient(
-          90deg,
-          var(--bf-appearance-token-border-accent),
-          color-mix(in srgb, var(--bf-appearance-token-color-accent-500) 60%, transparent)
-        );
-      }
-    }
   }
   
-  // Warning state (80%+)
+  // Warning state (70-89%)
   &--warning {
-    background: color-mix(in srgb, var(--bf-appearance-token-color-warning) 8%, transparent);
     color: var(--bf-appearance-token-color-warning);
-    border: 1px solid color-mix(in srgb, var(--bf-appearance-token-color-warning) 25%, transparent);
-    animation: pulse-warning 2s ease-in-out infinite;
+
+    .bitfun-token-usage__progress-track {
+      background: color-mix(in srgb, var(--bf-appearance-token-color-warning) 8%, transparent);
+      border: 1px solid color-mix(in srgb, var(--bf-appearance-token-color-warning) 25%, transparent);
+    }
     
     .bitfun-token-usage__progress-fill {
       background: linear-gradient(
@@ -124,40 +112,38 @@
         color-mix(in srgb, var(--bf-appearance-token-color-warning) 30%, transparent),
         color-mix(in srgb, var(--bf-appearance-token-color-warning) 50%, transparent)
       );
-      animation: progress-pulse 2s ease-in-out infinite;
     }
-    
-    &:hover {
-      background: color-mix(in srgb, var(--bf-appearance-token-color-warning) 12%, transparent);
-      border-color: color-mix(in srgb, var(--bf-appearance-token-color-warning) 40%, transparent);
-      
-      .bitfun-token-usage__progress-fill {
-        background: linear-gradient(
-          90deg,
-          color-mix(in srgb, var(--bf-appearance-token-color-warning) 40%, transparent),
-          color-mix(in srgb, var(--bf-appearance-token-color-warning) 60%, transparent)
-        );
-      }
+  }
+
+  &--critical {
+    color: var(--bf-appearance-token-color-error);
+
+    .bitfun-token-usage__progress-track {
+      background: color-mix(in srgb, var(--bf-appearance-token-color-error) 8%, transparent);
+      border: 1px solid color-mix(in srgb, var(--bf-appearance-token-color-error) 30%, transparent);
+    }
+
+    .bitfun-token-usage__progress-fill {
+      background: linear-gradient(
+        90deg,
+        color-mix(in srgb, var(--bf-appearance-token-color-error) 45%, transparent),
+        color-mix(in srgb, var(--bf-appearance-token-color-error) 75%, transparent)
+      );
     }
   }
 }
 
-// Warning pulse animation
-@keyframes pulse-warning {
-  0%, 100% {
-    box-shadow: 0 0 0 color-mix(in srgb, var(--bf-appearance-token-color-warning) 0%, transparent);
-  }
-  50% {
-    box-shadow: 0 0 8px color-mix(in srgb, var(--bf-appearance-token-color-warning) 40%, transparent);
+@media (hover: hover) and (pointer: fine) {
+  .bitfun-token-usage:hover .bitfun-token-usage__hover-content {
+    opacity: 1;
   }
 }
 
-// Progress pulse animation (warning state)
-@keyframes progress-pulse {
-  0%, 100% {
-    opacity: 0.8;
-  }
-  50% {
-    opacity: 1;
+@media (prefers-reduced-motion: reduce) {
+  .bitfun-token-usage,
+  .bitfun-token-usage__progress-track,
+  .bitfun-token-usage__progress-fill,
+  .bitfun-token-usage__hover-content {
+    transition: none;
   }
 }
diff --git a/src/web-ui/src/flow_chat/components/TokenUsageIndicator.tsx b/src/web-ui/src/flow_chat/components/TokenUsageIndicator.tsx
index 304d89928c..2af358f1df 100644
--- a/src/web-ui/src/flow_chat/components/TokenUsageIndicator.tsx
+++ b/src/web-ui/src/flow_chat/components/TokenUsageIndicator.tsx
@@ -39,13 +39,17 @@ export const TokenUsageIndicator: React.FC<TokenUsageIndicatorProps> = ({
       data-bf-level={statusClass}
       className={`bitfun-token-usage ${className} bitfun-token-usage--${statusClass}`}
       title={`Token usage: ${formatNumber(currentTokens)} / ${formatNumber(maxTokens)}`}
+      role="progressbar"
+      aria-valuemin={0}
+      aria-valuemax={100}
+      aria-valuenow={percentage}
     >
       <div data-bf-component="token-usage-indicator" data-bf-part="track" className="bitfun-token-usage__progress-track">
         <div 
           data-bf-component="token-usage-indicator"
           data-bf-part="fill"
           className="bitfun-token-usage__progress-fill"
-          style={{ width: `${percentage}%` }}
+          style={{ '--token-usage-progress': percentage / 100 } as React.CSSProperties}
         />
       </div>
       
@@ -57,4 +61,3 @@ export const TokenUsageIndicator: React.FC<TokenUsageIndicatorProps> = ({
 };
 
 export default TokenUsageIndicator;
-
diff --git a/src/web-ui/src/flow_chat/components/TurnHistoryPanel.appearance.ts b/src/web-ui/src/flow_chat/components/TurnHistoryPanel.appearance.ts
deleted file mode 100644
index bf4ceb90ae..0000000000
--- a/src/web-ui/src/flow_chat/components/TurnHistoryPanel.appearance.ts
+++ /dev/null
@@ -1,11 +0,0 @@
-import type { AppearanceSurfaceDescriptor } from '@/infrastructure/appearance';
-
-export const turnHistoryPanelAppearanceDescriptor: AppearanceSurfaceDescriptor = {
-  id: 'turn-history-panel',
-  parts: [
-    { id: 'root' }, { id: 'loading' }, { id: 'empty' }, { id: 'header' },
-    { id: 'count' }, { id: 'list' }, { id: 'item' }, { id: 'itemHeader' },
-    { id: 'files' }, { id: 'filesList' }, { id: 'time' },
-  ],
-  states: [{ id: 'current', selector: { kind: 'self', suffix: '[data-bf-state~="current"]' } }],
-};
diff --git a/src/web-ui/src/flow_chat/components/TurnHistoryPanel.scss b/src/web-ui/src/flow_chat/components/TurnHistoryPanel.scss
deleted file mode 100644
index 8ab8cf6332..0000000000
--- a/src/web-ui/src/flow_chat/components/TurnHistoryPanel.scss
+++ /dev/null
@@ -1,135 +0,0 @@
-@use '../../component-library/styles/_extended-mixins' as mixins;
-
-.turn-history-panel {
-  padding: 16px;
-  background: var(--bf-appearance-token-color-bg-primary);
-  border-radius: 8px;
-  box-shadow: var(--bf-appearance-token-shadow-sm);
-
-  .turn-history-header {
-    display: flex;
-    justify-content: space-between;
-    align-items: center;
-    margin-bottom: 16px;
-    padding-bottom: 12px;
-    border-bottom: 1px solid var(--bf-appearance-token-border-base);
-
-    h3 {
-      margin: 0;
-      font-size: 16px;
-      font-weight: 600;
-      color: var(--bf-appearance-token-color-text-primary);
-    }
-
-    .turn-count {
-      font-size: var(--bf-appearance-token-tool-card-action-font-size);
-      color: var(--bf-appearance-token-color-text-secondary);
-      background: var(--bf-appearance-token-element-bg-soft);
-      padding: 4px 8px;
-      border-radius: 4px;
-    }
-  }
-
-  .turn-history-list {
-    display: flex;
-    flex-direction: column;
-    gap: 12px;
-    max-height: 500px;
-    overflow-y: auto;
-
-  }
-
-  .turn-history-item {
-    padding: 12px;
-    border: 1px solid var(--bf-appearance-token-border-base);
-    border-radius: 6px;
-    transition: all 0.2s ease;
-
-    &:hover {
-      border-color: var(--bf-appearance-token-color-accent-600);
-      box-shadow: 0 2px 4px color-mix(in srgb, var(--bf-appearance-token-color-accent-600) 10%, transparent);
-    }
-
-    &.current {
-      background: var(--bf-appearance-token-color-accent-100);
-      border-color: var(--bf-appearance-token-color-accent-600);
-    }
-
-    .turn-item-header {
-      display: flex;
-      justify-content: space-between;
-      align-items: center;
-      margin-bottom: 8px;
-
-      .turn-index {
-        font-size: 14px;
-        font-weight: 600;
-        color: var(--bf-appearance-token-color-text-primary);
-      }
-    }
-
-    .turn-item-files {
-      margin: 8px 0;
-      padding: 8px;
-      background: var(--bf-appearance-token-element-bg-subtle);
-      border-radius: 4px;
-
-      .files-label {
-        font-size: var(--bf-appearance-token-tool-card-action-font-size);
-        color: var(--bf-appearance-token-color-text-secondary);
-        font-weight: 500;
-        display: block;
-        margin-bottom: 4px;
-      }
-
-      .files-list {
-        margin: 0;
-        padding-left: 16px;
-
-        .file-item {
-          font-size: var(--bf-appearance-token-tool-card-action-font-size);
-          color: var(--bf-appearance-token-color-text-secondary);
-          margin: 2px 0;
-          font-family: var(--bf-appearance-token-font-family-mono);
-        }
-
-        .file-item-more {
-          font-size: var(--bf-appearance-token-tool-card-action-font-size);
-          color: var(--bf-appearance-token-color-text-muted);
-          font-style: italic;
-          list-style: none;
-          margin-left: -16px;
-        }
-      }
-    }
-
-    .turn-item-time {
-      font-size: var(--bf-appearance-token-flowchat-font-size-xs);
-      color: var(--bf-appearance-token-color-text-muted);
-      margin-top: 8px;
-    }
-  }
-}
-
-.turn-history-panel-loading {
-  padding: 40px;
-  text-align: center;
-  color: var(--bf-appearance-token-color-text-secondary);
-  font-size: 14px;
-}
-
-.turn-history-panel-empty {
-  padding: 40px;
-  text-align: center;
-
-  p {
-    margin: 8px 0;
-    color: var(--bf-appearance-token-color-text-secondary);
-    font-size: 14px;
-
-    &.hint {
-      font-size: var(--bf-appearance-token-tool-card-action-font-size);
-      color: var(--bf-appearance-token-color-text-muted);
-    }
-  }
-}
diff --git a/src/web-ui/src/flow_chat/components/TurnHistoryPanel.tsx b/src/web-ui/src/flow_chat/components/TurnHistoryPanel.tsx
deleted file mode 100644
index 0ccc75ad1e..0000000000
--- a/src/web-ui/src/flow_chat/components/TurnHistoryPanel.tsx
+++ /dev/null
@@ -1,114 +0,0 @@
-import React, { useState, useEffect, useCallback } from 'react';
-import { snapshotAPI } from '@/infrastructure/api';
-import { useI18n } from '@/infrastructure/i18n';
-import type { TurnSnapshot } from '@/infrastructure/api/service-api/SnapshotAPI';
-import { TurnRollbackButton } from './TurnRollbackButton';
-import { createLogger } from '@/shared/utils/logger';
-import './TurnHistoryPanel.scss';
-
-const log = createLogger('TurnHistoryPanel');
-
-interface TurnHistoryPanelProps {
-  sessionId: string;
-}
-
-/**
- * Turn history panel.
- * Shows all turns in the current session and allows rollback.
- */
-export const TurnHistoryPanel: React.FC<TurnHistoryPanelProps> = ({ sessionId }) => {
-  const { formatDate } = useI18n('flow-chat');
-  const [turns, setTurns] = useState<TurnSnapshot[]>([]);
-  const [loading, setLoading] = useState(false);
-  const [currentTurnIndex, setCurrentTurnIndex] = useState<number>(-1);
-
-  const loadTurns = useCallback(async () => {
-    if (!sessionId) return;
-    
-    setLoading(true);
-    try {
-      const turnList = await snapshotAPI.getSessionTurnSnapshots(sessionId);
-      setTurns(turnList);
-      setCurrentTurnIndex(turnList.length > 0 ? turnList.length - 1 : -1);
-    } catch (error) {
-      log.error('Failed to load turn snapshots', { sessionId, error });
-    } finally {
-      setLoading(false);
-    }
-  }, [sessionId]);
-
-  useEffect(() => {
-    void loadTurns();
-  }, [loadTurns]);
-
-  const handleRollbackComplete = () => {
-    void loadTurns();
-  };
-
-  if (loading) {
-    return <div data-bf-component="turn-history-panel" data-bf-part="loading" className="turn-history-panel-loading">Loading...</div>;
-  }
-
-  if (turns.length === 0) {
-    return (
-      <div data-bf-component="turn-history-panel" data-bf-part="empty" className="turn-history-panel-empty">
-        <p>No turn history available.</p>
-        <p className="hint">A snapshot is created after each AI response.</p>
-      </div>
-    );
-  }
-
-  return (
-    <div data-bf-component="turn-history-panel" data-bf-part="root" className="turn-history-panel">
-      <div data-bf-component="turn-history-panel" data-bf-part="header" className="turn-history-header">
-        <h3>Session history</h3>
-        <span data-bf-component="turn-history-panel" data-bf-part="count" className="turn-count">{turns.length} turns</span>
-      </div>
-
-      <div data-bf-component="turn-history-panel" data-bf-part="list" className="turn-history-list">
-        {turns.map((turn, index) => (
-          <div 
-            key={`${turn.sessionId}-${turn.turnIndex}`} 
-            data-bf-component="turn-history-panel"
-            data-bf-part="item"
-            data-bf-state={index === currentTurnIndex ? 'current' : ''}
-            className={`turn-history-item ${index === currentTurnIndex ? 'current' : ''}`}
-          >
-            <div data-bf-component="turn-history-panel" data-bf-part="itemHeader" className="turn-item-header">
-              <span className="turn-index">Turn {index + 1}</span>
-              <TurnRollbackButton
-                sessionId={turn.sessionId}
-                turnIndex={turn.turnIndex}
-                isCurrent={index === currentTurnIndex}
-                onRollbackComplete={handleRollbackComplete}
-              />
-            </div>
-            
-            {turn.modifiedFiles.length > 0 && (
-              <div data-bf-component="turn-history-panel" data-bf-part="files" className="turn-item-files">
-                <span className="files-label">Modified files:</span>
-                <ul data-bf-component="turn-history-panel" data-bf-part="filesList" className="files-list">
-                  {turn.modifiedFiles.slice(0, 3).map((file: string, fileIndex: number) => (
-                    <li key={fileIndex} className="file-item">{file}</li>
-                  ))}
-                  {turn.modifiedFiles.length > 3 && (
-                    <li className="file-item-more">
-                      {turn.modifiedFiles.length - 3} more files...
-                    </li>
-                  )}
-                </ul>
-              </div>
-            )}
-
-            <div data-bf-component="turn-history-panel" data-bf-part="time" className="turn-item-time">
-              {formatDate(new Date(turn.timestamp * 1000), {
-                dateStyle: 'medium',
-                timeStyle: 'short',
-              })}
-            </div>
-          </div>
-        ))}
-      </div>
-    </div>
-  );
-};
diff --git a/src/web-ui/src/flow_chat/components/TurnRollbackButton.appearance.ts b/src/web-ui/src/flow_chat/components/TurnRollbackButton.appearance.ts
deleted file mode 100644
index 24c889ab06..0000000000
--- a/src/web-ui/src/flow_chat/components/TurnRollbackButton.appearance.ts
+++ /dev/null
@@ -1,8 +0,0 @@
-import type { AppearanceSurfaceDescriptor } from '@/infrastructure/appearance';
-
-export const turnRollbackButtonAppearanceDescriptor: AppearanceSurfaceDescriptor = {
-  id: 'turn-rollback-button',
-  parts: [{ id: 'root' }],
-  facets: [{ id: 'mode', attribute: 'data-bf-mode', values: ['current', 'action'] }],
-  states: [{ id: 'loading', selector: { kind: 'self', suffix: '[data-bf-state~="loading"]' } }],
-};
diff --git a/src/web-ui/src/flow_chat/components/TurnRollbackButton.scss b/src/web-ui/src/flow_chat/components/TurnRollbackButton.scss
deleted file mode 100644
index 0e68fba3f6..0000000000
--- a/src/web-ui/src/flow_chat/components/TurnRollbackButton.scss
+++ /dev/null
@@ -1,40 +0,0 @@
-.turn-rollback-button {
-  padding: 4px 12px;
-  font-size: var(--bf-appearance-token-tool-card-action-font-size);
-  font-weight: 500;
-  background: var(--bf-appearance-token-color-accent-600);
-  color: var(--bf-appearance-token-color-static-white);
-  border: none;
-  border-radius: 4px;
-  cursor: pointer;
-  transition: all 0.2s ease;
-  white-space: nowrap;
-
-  &:hover {
-    background: var(--bf-appearance-token-color-accent-700);
-    transform: translateY(-1px);
-    box-shadow: 0 2px 4px color-mix(in srgb, var(--bf-appearance-token-color-accent-600) 30%, transparent);
-  }
-
-  &:active {
-    transform: translateY(0);
-  }
-
-  &:disabled {
-    opacity: var(--bf-appearance-token-opacity-disabled);
-    cursor: default;
-    transform: none;
-    box-shadow: none;
-  }
-}
-
-.turn-rollback-button-current {
-  padding: 4px 12px;
-  font-size: var(--bf-appearance-token-tool-card-action-font-size);
-  font-weight: 500;
-  background: var(--bf-appearance-token-color-success);
-  color: var(--bf-appearance-token-color-static-white);
-  border-radius: 4px;
-  display: inline-block;
-  white-space: nowrap;
-}
diff --git a/src/web-ui/src/flow_chat/components/TurnRollbackButton.tsx b/src/web-ui/src/flow_chat/components/TurnRollbackButton.tsx
deleted file mode 100644
index 2d34d814ce..0000000000
--- a/src/web-ui/src/flow_chat/components/TurnRollbackButton.tsx
+++ /dev/null
@@ -1,102 +0,0 @@
-import React, { useState } from 'react';
-import { useTranslation } from 'react-i18next';
-import { snapshotAPI } from '@/infrastructure/api';
-import { notificationService } from '@/shared/notification-system';
-import { confirmDanger } from '@/component-library';
-import { createLogger } from '@/shared/utils/logger';
-import './TurnRollbackButton.scss';
-
-const log = createLogger('TurnRollbackButton');
-
-interface TurnRollbackButtonProps {
-  sessionId: string;
-  turnIndex: number;
-  isCurrent: boolean;
-  onRollbackComplete?: () => void;
-}
-
-export const TurnRollbackButton: React.FC<TurnRollbackButtonProps> = ({
-  sessionId,
-  turnIndex,
-  isCurrent,
-  onRollbackComplete,
-}) => {
-  const { t } = useTranslation('flow-chat');
-  const [loading, setLoading] = useState(false);
-  
-  const handleRollback = async () => {
-    if (isCurrent || loading) return;
-
-    const index = turnIndex + 1;
-    const confirmed = await confirmDanger(
-      t('message.rollbackPanelDialogTitle', { index }),
-      (
-        <>
-          <p className="confirm-dialog__message-intro">{t('message.rollbackPanelDialogIntro')}</p>
-          <ul className="confirm-dialog__bullet-list">
-            <li>{t('message.rollbackPanelBulletRestore', { index })}</li>
-            <li>{t('message.rollbackPanelBulletUndo', { index })}</li>
-            <li>{t('message.rollbackPanelBulletHistory')}</li>
-          </ul>
-        </>
-      )
-    );
-
-    if (!confirmed) return;
-    
-    setLoading(true);
-    try {
-      const restoredFiles = await snapshotAPI.rollbackToTurn(sessionId, turnIndex);
-      
-      log.debug('Rollback completed', { sessionId, turnIndex, restoredFilesCount: restoredFiles.length });
-      
-      // Notify related components to refresh.
-      const { globalEventBus } = await import('@/infrastructure/event-bus');
-      
-      // Refresh file tree.
-      globalEventBus.emit('file-tree:refresh');
-      
-      // Refresh open files in the editor.
-      restoredFiles.forEach(filePath => {
-        globalEventBus.emit('editor:file-changed', { filePath });
-      });
-      
-      // Refresh snapshot state.
-      globalEventBus.emit('snapshot:rollback-completed', { 
-        sessionId,
-        turnIndex,
-        restoredFiles
-      });
-      
-      // Notify parent.
-      if (onRollbackComplete) {
-        onRollbackComplete();
-      }
-      
-    } catch (error) {
-      log.error('Rollback failed', { sessionId, turnIndex, error });
-      notificationService.error(
-        `${t('message.rollbackFailed')}: ${error instanceof Error ? error.message : String(error)}`
-      );
-    } finally {
-      setLoading(false);
-    }
-  };
-  
-  if (isCurrent) {
-    return <span data-bf-component="turn-rollback-button" data-bf-part="root" data-bf-mode="current" className="turn-rollback-button-current">Current</span>;
-  }
-  
-  return (
-    <button data-bf-component="turn-rollback-button" data-bf-part="root" data-bf-mode="action" data-bf-state={loading ? 'loading' : ''}
-      className="turn-rollback-button"
-      onClick={handleRollback}
-      disabled={loading}
-      title={`Rollback to turn ${turnIndex + 1}`}
-    >
-      {loading ? 'Rolling back...' : 'Rollback'}
-    </button>
-  );
-};
-
-
diff --git a/src/web-ui/src/flow_chat/components/UserMessage.appearance.ts b/src/web-ui/src/flow_chat/components/UserMessage.appearance.ts
deleted file mode 100644
index 62cec8eba6..0000000000
--- a/src/web-ui/src/flow_chat/components/UserMessage.appearance.ts
+++ /dev/null
@@ -1,13 +0,0 @@
-import type { AppearanceSurfaceDescriptor } from '@/infrastructure/appearance';
-
-export const userMessageAppearanceDescriptor: AppearanceSurfaceDescriptor = {
-  id: 'user-message',
-  parts: [
-    { id: 'root' }, { id: 'content' }, { id: 'inlineContent' },
-    { id: 'footer' }, { id: 'timestamp' }, { id: 'snapshotAction' },
-  ],
-  states: [
-    { id: 'expanded', selector: { kind: 'self', suffix: '[data-bf-state~="expanded"]' } },
-    { id: 'collapsed', selector: { kind: 'self', suffix: '[data-bf-state~="collapsed"]' } },
-  ],
-};
diff --git a/src/web-ui/src/flow_chat/components/UserMessage.scss b/src/web-ui/src/flow_chat/components/UserMessage.scss
deleted file mode 100644
index c05f5efa36..0000000000
--- a/src/web-ui/src/flow_chat/components/UserMessage.scss
+++ /dev/null
@@ -1,116 +0,0 @@
-/* User message component styles. */
-
-@use '../../component-library/styles/tokens' as *;
-
-.user-message {
-  margin-bottom: 1rem;
-  padding: 1rem 1.25rem;
-  background: var(--bf-appearance-token-element-bg-medium);
-  border: 1px solid var(--bf-appearance-token-border-medium);
-  border-radius: 12px;
-  max-width: 100%;
-  width: 100%;
-  min-width: 200px;
-  max-height: 60vh;
-  display: block;
-  visibility: visible;
-  box-sizing: border-box;
-  position: relative;
-  animation: user-message-slide-in 0.4s cubic-bezier(0.25, 0.8, 0.25, 1);
-  overflow-y: auto;
-  
-  &:focus-within {
-    border-color: var(--bf-appearance-token-border-prominent);
-  }
-
-  // Collapsed state
-  &--collapsed {
-    .message-inline-content {
-      display: -webkit-box !important;
-      -webkit-line-clamp: 3;
-      line-clamp: 3;
-      -webkit-box-orient: vertical;
-      overflow: hidden;
-      text-overflow: ellipsis;
-      white-space: pre-wrap;
-    }
-  }
-
-  // Expanded state
-  &--expanded {
-    .message-inline-content {
-      display: inline;
-    }
-  }
-}
-
-.message-content {
-  font-weight: 500;
-  line-height: var(--bf-appearance-token-flowchat-text-line-height);
-  color: var(--bf-appearance-token-color-text-primary);
-  position: relative;
-  z-index: 1;
-  font-size: 1em;
-  user-select: text;
-}
-
-.message-inline-content {
-  line-height: var(--bf-appearance-token-flowchat-text-line-height);
-  word-break: break-word;
-  white-space: pre-wrap;
-}
-
-.message-footer {
-  display: flex;
-  justify-content: space-between;
-  align-items: center;
-  margin-top: 0.75rem;
-}
-
-.message-timestamp {
-  font-size: 0.75em;
-  color: var(--bf-appearance-token-color-text-muted);
-  font-weight: 400;
-}
-
-.message-snapshot-action {
-  display: flex;
-  align-items: center;
-}
-
-// ==================== Inline context tags ====================
-
-.inline-context-tag {
-  display: inline-flex;
-  align-items: center;
-  gap: 0.25rem;
-  padding: 0.125rem 0.5rem;
-  margin: 0 0.25rem;
-  border-radius: 0.375rem;
-  border: 1px solid;
-  font-size: 0.875em;
-  font-weight: 500;
-  vertical-align: middle;
-  white-space: nowrap;
-  transition: all 0.2s ease;
-  cursor: default;
-
-  &:hover {
-    transform: translateY(-1px);
-    box-shadow: 0 2px 4px var(--bf-appearance-token-color-overlay-black-12);
-  }
-}
-
-// ==================== Animations ====================
-
-@keyframes user-message-slide-in {
-  from {
-    opacity: 0;
-    transform: translateX(-20px) scale(0.95);
-  }
-  to {
-    opacity: 1;
-    transform: translateX(0) scale(1);
-  }
-}
-
diff --git a/src/web-ui/src/flow_chat/components/UserMessage.tsx b/src/web-ui/src/flow_chat/components/UserMessage.tsx
deleted file mode 100644
index 54e2fd3f82..0000000000
--- a/src/web-ui/src/flow_chat/components/UserMessage.tsx
+++ /dev/null
@@ -1,263 +0,0 @@
-/**
- * User message component.
- * Parses and renders inline context tags inside user text.
- */
-
-import React, { useMemo, useState, useRef, useEffect } from 'react';
-import { File, Folder, Code, Image, Terminal, GitBranch, Link, FileText, GitPullRequest } from 'lucide-react';
-import { Tag } from '@/component-library';
-import { useI18n } from '@/infrastructure/i18n';
-import { shouldIgnoreCardToggleClick } from '@/shared/utils/textSelection';
-import { observeElementResize } from '@/shared/utils/sharedResizeObserver';
-import { SnapshotRollbackButton } from './SnapshotRollbackButton';
-import './UserMessage.scss';
-
-export interface UserMessageProps {
-  message?: string; // New API
-  content?: string; // Legacy API
-  timestamp?: number;
-  showTimestamp?: boolean;
-  className?: string;
-  // Turn snapshot support
-  sessionId?: string;
-  turnIndex?: number;
-  turnId?: string;
-  showSnapshotButton?: boolean;
-  isCurrentTurn?: boolean;
-}
-
-// Content segment type: text or tag.
-type ContentPart = 
-  | { type: 'text'; content: string }
-  | { type: 'tag'; tagType: string; label: string };
-
-type InlineTagColor = 'blue' | 'green' | 'red' | 'yellow' | 'purple' | 'gray';
-
-// Tag metadata
-const TAG_CONFIG = {
-  file: { icon: File, tagColor: 'blue' as InlineTagColor, label: 'File' },
-  dir: { icon: Folder, tagColor: 'purple' as InlineTagColor, label: 'Directory' },
-  code: { icon: Code, tagColor: 'green' as InlineTagColor, label: 'Code' },
-  img: { icon: Image, tagColor: 'yellow' as InlineTagColor, label: 'Image' },
-  cmd: { icon: Terminal, tagColor: 'gray' as InlineTagColor, label: 'Command' },
-  chart: { icon: FileText, tagColor: 'gray' as InlineTagColor, label: 'Chart' },
-  git: { icon: GitBranch, tagColor: 'red' as InlineTagColor, label: 'Git' },
-  link: { icon: Link, tagColor: 'blue' as InlineTagColor, label: 'Link' },
-  pr: { icon: GitPullRequest, tagColor: 'purple' as InlineTagColor, label: 'Pull Request' }
-};
-
-/**
- * Parse message content into inline segments.
- * Supported format: #type:value
- *
- * Tag formats:
- * - #file:filename - File reference
- * - #dir:dirname - Directory reference
- * - #code:file:10-20 - Code snippet
- * - #img:image - Image reference
- * - #cmd:command - Command reference
- * - #chart:chart - Chart reference
- * - #git:branch - Git reference
- * - #link:URL - Link reference
- */
-function parseMessageContent(content: string): ContentPart[] {
-  const parts: ContentPart[] = [];
-  
-  // Match #type:value until whitespace or line break.
-  const tagPattern = /#(file|dir|code|img|cmd|chart|git|link|pr):([^\s\n]+)/g;
-  
-  let lastIndex = 0;
-  let match;
-  
-  while ((match = tagPattern.exec(content)) !== null) {
-    if (match.index > lastIndex) {
-      const textBefore = content.slice(lastIndex, match.index);
-      if (textBefore) {
-        parts.push({ type: 'text', content: textBefore });
-      }
-    }
-    
-    const tagType = match[1];
-    const label = match[2];
-    
-    parts.push({
-      type: 'tag',
-      tagType,
-      label
-    });
-    
-    lastIndex = match.index + match[0].length;
-  }
-  
-  if (lastIndex < content.length) {
-    const textAfter = content.slice(lastIndex);
-    if (textAfter) {
-      parts.push({ type: 'text', content: textAfter });
-    }
-  }
-  
-  if (parts.length === 0) {
-    parts.push({ type: 'text', content });
-  }
-  
-  return parts;
-}
-
-/**
- * Inline context tag component.
- */
-const InlineContextTag: React.FC<{ tagType: string; label: string }> = ({ tagType, label }) => {
-  const config = TAG_CONFIG[tagType as keyof typeof TAG_CONFIG] || TAG_CONFIG.file;
-  const IconComponent = config.icon;
-  
-  return (
-    <Tag 
-      color={config.tagColor}
-      size="small"
-      className="inline-context-tag"
-      title={`${config.label}: ${label}`}
-    >
-      <IconComponent size={12} style={{ marginRight: '4px', display: 'inline-flex', verticalAlign: 'middle' }} />
-      <span>{label}</span>
-    </Tag>
-  );
-};
-
-export const UserMessage: React.FC<UserMessageProps> = React.memo(({
-  message,
-  content,
-  timestamp,
-  showTimestamp = false,
-  className = '',
-  sessionId,
-  turnIndex,
-  turnId,
-  showSnapshotButton = false,
-  isCurrentTurn = false
-}) => {
-  const { formatDate } = useI18n('flow-chat');
-  const messageContent = message || content || '';
-  const parts = useMemo(() => parseMessageContent(messageContent), [messageContent]);
-  const [isExpanded, setIsExpanded] = useState(false);
-  const [hasOverflow, setHasOverflow] = useState(false);
-  const messageRef = useRef<HTMLDivElement>(null);
-  const contentRef = useRef<HTMLDivElement>(null);
-  
-  // Shared ResizeObserver instead of a per-message window resize listener:
-  // observer callbacks run after layout, avoiding forced reflow per message.
-  useEffect(() => {
-    const element = contentRef.current;
-    if (!element || isExpanded) {
-      setHasOverflow(false);
-      return;
-    }
-
-    const checkOverflow = () => {
-      const isOverflowing = element.scrollHeight > element.clientHeight ||
-                            element.scrollWidth > element.clientWidth;
-      setHasOverflow(isOverflowing);
-    };
-
-    checkOverflow();
-
-    return observeElementResize(element, checkOverflow);
-  }, [messageContent, isExpanded]);
-  
-  const toggleExpand = (e: React.MouseEvent) => {
-    if (shouldIgnoreCardToggleClick(e, contentRef.current)) {
-      return;
-    }
-
-    if (!hasOverflow && !isExpanded) {
-      return;
-    }
-    e.stopPropagation();
-    setIsExpanded(prev => !prev);
-  };
-  
-  useEffect(() => {
-    if (!isExpanded) {
-      return;
-    }
-    
-    const handleClickOutside = (event: MouseEvent) => {
-      if (messageRef.current && !messageRef.current.contains(event.target as Node)) {
-        setIsExpanded(false);
-      }
-    };
-    
-    const timeoutId = setTimeout(() => {
-      document.addEventListener('click', handleClickOutside, true);
-    }, 100);
-    
-    return () => {
-      clearTimeout(timeoutId);
-      document.removeEventListener('click', handleClickOutside, true);
-    };
-  }, [isExpanded]);
-  
-  const currentClassName = `user-message ${className} ${isExpanded ? 'user-message--expanded' : 'user-message--collapsed'}`;
-  
-  return (
-    <div
-      data-bf-component="user-message"
-      data-bf-part="root"
-      data-bf-state={isExpanded ? 'expanded' : 'collapsed'}
-      ref={messageRef}
-      className={currentClassName}
-    >
-      <div 
-        data-bf-component="user-message"
-        data-bf-part="content"
-        className="message-content" 
-        onClick={toggleExpand}
-        style={{ cursor: (hasOverflow || isExpanded) ? 'pointer' : 'text' }}
-      >
-        <div data-bf-component="user-message" data-bf-part="inlineContent" className="message-inline-content" ref={contentRef}>
-          {parts.map((part, index) => {
-            if (part.type === 'text') {
-              return part.content.split('\n').map((line, lineIndex) => (
-                <React.Fragment key={`text-${index}-${lineIndex}`}>
-                  {lineIndex > 0 && <br />}
-                  {line}
-                </React.Fragment>
-              ));
-            } else {
-              return (
-                <InlineContextTag
-                  key={`tag-${index}`}
-                  tagType={part.tagType}
-                  label={part.label}
-                />
-              );
-            }
-          })}
-        </div>
-      </div>
-      
-      <div data-bf-component="user-message" data-bf-part="footer" className="message-footer">
-        {showTimestamp && timestamp && (
-          <div data-bf-component="user-message" data-bf-part="timestamp" className="message-timestamp">
-            {formatDate(new Date(timestamp), {
-              hour: '2-digit',
-              minute: '2-digit',
-            })}
-          </div>
-        )}
-        
-        {showSnapshotButton && sessionId && turnId !== undefined && turnIndex !== undefined && (
-          <div data-bf-component="user-message" data-bf-part="snapshotAction" className="message-snapshot-action">
-            <SnapshotRollbackButton
-              sessionId={sessionId}
-              turnIndex={turnIndex}
-              turnId={turnId}
-              isCurrentTurn={isCurrentTurn}
-            />
-          </div>
-        )}
-      </div>
-    </div>
-  );
-});
-
-UserMessage.displayName = 'UserMessage';
diff --git a/src/web-ui/src/flow_chat/components/UserSteeringBubble.tsx b/src/web-ui/src/flow_chat/components/UserSteeringBubble.tsx
deleted file mode 100644
index a50f9c215b..0000000000
--- a/src/web-ui/src/flow_chat/components/UserSteeringBubble.tsx
+++ /dev/null
@@ -1,30 +0,0 @@
-/**
- * Renders a `user-steering` flow item as a normal user message in the
- * conversation flow. The backend confirmation still updates this item by
- * `steeringId`, but the user-facing surface is intentionally identical to a
- * message sent from the composer.
- *
- * The item is appended to the *current* model round's items, so it visually
- * sits after whatever thinking / text / tool-call content has already
- * streamed. When the backend finishes the current atomic step and starts a
- * new model round, that next round renders below it — matching the user's
- * mental model of "the agent reads my steering and responds in a new turn".
- */
-
-import { UserMessage } from './UserMessage';
-import type { FlowUserSteeringItem } from '../types/flow-chat';
-
-interface UserSteeringBubbleProps {
-  item: FlowUserSteeringItem;
-}
-
-export function UserSteeringBubble({ item }: UserSteeringBubbleProps): JSX.Element {
-  return (
-    <UserMessage
-      message={item.content}
-      timestamp={item.timestamp}
-    />
-  );
-}
-
-export default UserSteeringBubble;
diff --git a/src/web-ui/src/flow_chat/components/WelcomePanel.tsx b/src/web-ui/src/flow_chat/components/WelcomePanel.tsx
index d0b7867a2e..aa39c04938 100644
--- a/src/web-ui/src/flow_chat/components/WelcomePanel.tsx
+++ b/src/web-ui/src/flow_chat/components/WelcomePanel.tsx
@@ -6,9 +6,8 @@
 import React, { useEffect, useState, useCallback, useRef, useMemo } from 'react';
 import { createPortal } from 'react-dom';
 import { useTranslation } from 'react-i18next';
-import {FolderOpen, ChevronDown, Check, GitBranch, FolderPlus} from 'lucide-react';
-import { gitAPI ,workspaceAPI} from '../../infrastructure/api';
-import type { GitWorkState } from '../../infrastructure/api/service-api/StartchatAgentAPI';
+import { FolderOpen, FolderPlus, ChevronDown, Check, GitBranch } from 'lucide-react';
+import { gitAPI, workspaceAPI } from '../../infrastructure/api';
 import { useApp } from '../../app/hooks/useApp';
 import { createLogger } from '@/shared/utils/logger';
 import { useWorkspaceContext } from '@/infrastructure/contexts/WorkspaceContext';
@@ -21,6 +20,13 @@ import './WelcomePanel.css';
 
 const log = createLogger('WelcomePanel');
 
+interface GitWorkState {
+  currentBranch: string;
+  unstagedFiles: number;
+  stagedFiles: number;
+  unpushedCommits: number;
+}
+
 interface WelcomePanelProps {
   onQuickAction?: (command: string) => void;
   className?: string;
@@ -143,8 +149,6 @@ export const WelcomePanel: React.FC<WelcomePanelProps> = ({
         unstagedFiles: s.unstaged.length + s.untracked.length,
         stagedFiles: s.staged.length,
         unpushedCommits: s.ahead,
-        aheadBehind: { ahead: s.ahead, behind: s.behind },
-        modifiedFiles: [],
       });
     } catch (err) {
       log.warn('Failed to load git state', err);
diff --git a/src/web-ui/src/flow_chat/components/background-command/BackgroundCommandOutputPanel.scss b/src/web-ui/src/flow_chat/components/background-command/BackgroundCommandOutputPanel.scss
index fd3027f03b..e828638516 100644
--- a/src/web-ui/src/flow_chat/components/background-command/BackgroundCommandOutputPanel.scss
+++ b/src/web-ui/src/flow_chat/components/background-command/BackgroundCommandOutputPanel.scss
@@ -288,3 +288,9 @@
     transform: rotate(360deg);
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .background-command-output-panel__loading svg {
+    animation: none;
+  }
+}
diff --git a/src/web-ui/src/flow_chat/components/btw/BtwSessionPanel.appearance.ts b/src/web-ui/src/flow_chat/components/btw/BtwSessionPanel.appearance.ts
index 1ec955c3e8..54c520e0ff 100644
--- a/src/web-ui/src/flow_chat/components/btw/BtwSessionPanel.appearance.ts
+++ b/src/web-ui/src/flow_chat/components/btw/BtwSessionPanel.appearance.ts
@@ -22,5 +22,6 @@ export const btwSessionPanelAppearanceDescriptor: AppearanceSurfaceDescriptor =
   states: [
     { id: 'hasActionBar', selector: { kind: 'self', suffix: '[data-bf-state~="hasActionBar"]' } },
     { id: 'minimized', selector: { kind: 'self', suffix: '[data-bf-state~="minimized"]' } },
+    { id: 'hidden', selector: { kind: 'self', suffix: '[data-bf-state~="hidden"]' } },
   ],
 };
diff --git a/src/web-ui/src/flow_chat/components/btw/BtwSessionPanel.review-action.test.tsx b/src/web-ui/src/flow_chat/components/btw/BtwSessionPanel.review-action.test.tsx
index ac97adb767..2fb023527b 100644
--- a/src/web-ui/src/flow_chat/components/btw/BtwSessionPanel.review-action.test.tsx
+++ b/src/web-ui/src/flow_chat/components/btw/BtwSessionPanel.review-action.test.tsx
@@ -484,6 +484,7 @@ describe('BtwSessionPanel review action bar integration', () => {
     });
     container.remove();
     useReviewActionBarStore.getState().reset();
+    vi.useRealTimers();
   });
 
   it('shows a Review-check loading state instead of an empty thread', async () => {
@@ -1183,6 +1184,76 @@ describe('BtwSessionPanel review action bar integration', () => {
     expect(body?.style.paddingBottom).toBe('96px');
   });
 
+  it('retains action-bar layout through exit and cancels release when reopened', async () => {
+    vi.useFakeTimers();
+    vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockReturnValue({
+      bottom: 80,
+      height: 80,
+      left: 0,
+      right: 0,
+      top: 0,
+      width: 0,
+      x: 0,
+      y: 0,
+      toJSON: () => ({}),
+    });
+
+    await act(async () => {
+      root.render(
+        <BtwSessionPanel
+          childSessionId="deep-review-child"
+          parentSessionId="parent-session"
+          workspacePath="D:/workspace/project"
+        />,
+      );
+    });
+    await act(async () => {
+      useReviewActionBarStore.getState().showCapacityQueueBar({
+        childSessionId: 'deep-review-child',
+        parentSessionId: 'parent-session',
+        capacityQueueState: {
+          toolId: 'task-security',
+          subagentType: 'ReviewSecurity',
+          status: 'queued_for_capacity',
+          queuedReviewerCount: 1,
+          waitingReviewers: [{
+            toolId: 'task-security',
+            subagentType: 'ReviewSecurity',
+            status: 'queued_for_capacity',
+          }],
+        },
+      });
+    });
+
+    const panel = container.querySelector<HTMLElement>('.btw-session-panel');
+    const body = container.querySelector<HTMLElement>('.btw-session-panel__body');
+    expect(panel?.classList.contains('btw-session-panel--has-action-bar')).toBe(true);
+    expect(body?.style.paddingBottom).toBe('176px');
+
+    act(() => useReviewActionBarStore.getState().minimize('deep-review-child'));
+    expect(panel?.classList.contains('btw-session-panel--has-action-bar')).toBe(true);
+    expect(body?.style.paddingBottom).toBe('176px');
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(199);
+    });
+    expect(panel?.classList.contains('btw-session-panel--has-action-bar')).toBe(true);
+
+    act(() => useReviewActionBarStore.getState().restore('deep-review-child'));
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(1);
+    });
+    expect(panel?.classList.contains('btw-session-panel--has-action-bar')).toBe(true);
+    expect(body?.style.paddingBottom).toBe('176px');
+
+    act(() => useReviewActionBarStore.getState().minimize('deep-review-child'));
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(200);
+    });
+    expect(panel?.classList.contains('btw-session-panel--has-action-bar')).toBe(false);
+    expect(body?.style.paddingBottom).toBe('96px');
+  });
+
   it('restores the minimized running action when capacity waiting ends before the review finishes', async () => {
     flowChatState = {
       ...flowChatState,
diff --git a/src/web-ui/src/flow_chat/components/btw/BtwSessionPanel.scss b/src/web-ui/src/flow_chat/components/btw/BtwSessionPanel.scss
index 31404dce1a..de59e368a1 100644
--- a/src/web-ui/src/flow_chat/components/btw/BtwSessionPanel.scss
+++ b/src/web-ui/src/flow_chat/components/btw/BtwSessionPanel.scss
@@ -162,6 +162,15 @@
     box-sizing: border-box;
     overflow: hidden;
     pointer-events: none;
+    transition: opacity 140ms ease;
+
+    &[data-visible='false'] {
+      opacity: 0;
+      visibility: hidden;
+      transition:
+        opacity 140ms ease,
+        visibility 0s linear 140ms;
+    }
   }
 
   &__action-bar-wrapper > .deep-review-action-bar {
@@ -228,6 +237,18 @@
     left: 14px;
     z-index: 11;
     pointer-events: auto;
+    transition:
+      opacity 120ms ease,
+      transform 150ms cubic-bezier(0.23, 1, 0.32, 1),
+      visibility 0s linear 0s;
+
+    &[data-bf-state='hidden'] {
+      opacity: 0;
+      visibility: hidden;
+      transform: translateY(4px) scale(0.96);
+      pointer-events: none;
+      transition-delay: 0s, 0s, 150ms;
+    }
   }
 
   &__minimized-button {
@@ -277,6 +298,13 @@
   }
 }
 
+@media (prefers-reduced-motion: reduce) {
+  .btw-session-panel__action-bar-wrapper,
+  .btw-session-panel__minimized-indicator {
+    transition: none;
+  }
+}
+
 @keyframes btw-session-panel-stop-spin {
   to {
     transform: rotate(360deg);
diff --git a/src/web-ui/src/flow_chat/components/btw/BtwSessionPanel.tsx b/src/web-ui/src/flow_chat/components/btw/BtwSessionPanel.tsx
index 4b1451f969..a635f54847 100644
--- a/src/web-ui/src/flow_chat/components/btw/BtwSessionPanel.tsx
+++ b/src/web-ui/src/flow_chat/components/btw/BtwSessionPanel.tsx
@@ -15,6 +15,10 @@ import {FLOWCHAT_FOCUS_ITEM_EVENT, type FlowChatFocusItemRequest} from '../../ev
 import {fileTabManager} from '@/shared/services/FileTabManager';
 import {createTab} from '@/shared/utils/tabUtils';
 import {IconButton, type LineRange} from '@/component-library';
+import {
+  PRESENCE_BOUNDARY_MIN_EXIT_MS,
+  PresenceBoundary,
+} from '@/component-library/components/PresenceBoundary';
 import {resolveSessionRelationship} from '../../utils/sessionMetadata';
 import {agentAPI} from '@/infrastructure/api';
 import {globalEventBus} from '@/infrastructure/event-bus';
@@ -54,6 +58,7 @@ import {
   collectModifiedFilePathsFromTurns,
   hasOpaqueWorkspaceMutationRisk,
 } from '../../utils/modifiedFilePaths';
+import { getMotionAwareScrollBehavior } from '../../utils/motionPreference';
 
 function findReviewChildByRequestId(
   parentSessionId: string | null | undefined,
@@ -304,7 +309,10 @@ export const BtwSessionPanel: React.FC<BtwSessionPanelProps> = ({
     const container = scrollContainerRef.current;
     if (!container) return;
     shouldAutoScrollRef.current = true;
-    container.scrollTo({ top: container.scrollHeight, behavior: 'smooth' });
+    container.scrollTo({
+      top: container.scrollHeight,
+      behavior: getMotionAwareScrollBehavior('smooth'),
+    });
     setShowScrollToBottom(false);
   }, []);
 
@@ -401,12 +409,40 @@ export const BtwSessionPanel: React.FC<BtwSessionPanelProps> = ({
     actionBarPhase !== 'idle' &&
     !actionBarMinimized;
 
+  const [retainedReviewActionBarOwnerId, setRetainedReviewActionBarOwnerId] = useState<string | null>(
+    showReviewActionBar ? childSessionId ?? null : null,
+  );
+  useEffect(() => {
+    const ownerId = childSessionId ?? null;
+    if (showReviewActionBar && ownerId) {
+      setRetainedReviewActionBarOwnerId(ownerId);
+      return undefined;
+    }
+    if (!ownerId || retainedReviewActionBarOwnerId !== ownerId) {
+      if (retainedReviewActionBarOwnerId !== null) {
+        setRetainedReviewActionBarOwnerId(null);
+      }
+      return undefined;
+    }
+
+    const timer = window.setTimeout(() => {
+      setRetainedReviewActionBarOwnerId((currentOwnerId) =>
+        currentOwnerId === ownerId ? null : currentOwnerId,
+      );
+    }, PRESENCE_BOUNDARY_MIN_EXIT_MS);
+    return () => window.clearTimeout(timer);
+  }, [childSessionId, retainedReviewActionBarOwnerId, showReviewActionBar]);
+  const retainsReviewActionBarLayout = Boolean(
+    showReviewActionBar ||
+    (childSessionId && retainedReviewActionBarOwnerId === childSessionId),
+  );
+
   const showMinimizedIndicator =
     isReviewSession &&
     actionBarChildSessionId === childSessionId &&
     actionBarPhase !== 'idle' &&
     actionBarMinimized;
-  const reviewActionBottomPadding = showReviewActionBar
+  const reviewActionBottomPadding = retainsReviewActionBarLayout
     ? actionBarHeight + REVIEW_ACTION_BOTTOM_BLANK_SPACE_PX
     : showMinimizedIndicator
       ? REVIEW_ACTION_BOTTOM_BLANK_SPACE_PX
@@ -857,7 +893,7 @@ export const BtwSessionPanel: React.FC<BtwSessionPanelProps> = ({
 
   // Observe action bar height to adjust body padding dynamically
   useEffect(() => {
-    if (!showReviewActionBar) {
+    if (!retainsReviewActionBarLayout) {
       setActionBarHeight(0);
       return;
     }
@@ -881,7 +917,7 @@ export const BtwSessionPanel: React.FC<BtwSessionPanelProps> = ({
     return () => {
       observer.disconnect();
     };
-  }, [showReviewActionBar]);
+  }, [retainsReviewActionBarLayout]);
 
   const handleStopReviewSession = useCallback(async () => {
     if (!childSessionId || stoppingReview || !isTurnProcessing) {
@@ -962,11 +998,11 @@ export const BtwSessionPanel: React.FC<BtwSessionPanelProps> = ({
     <FlowChatContext.Provider value={contextValue}>
       <FlowChatVolatileContext.Provider value={volatileContextValue}>
       <div
-        className={`btw-session-panel${showReviewActionBar ? ' btw-session-panel--has-action-bar' : ''}`}
+        className={`btw-session-panel${retainsReviewActionBarLayout ? ' btw-session-panel--has-action-bar' : ''}`}
         data-bf-component="btw-session-panel"
         data-bf-part="root"
         data-bf-view="session"
-        data-bf-state={showReviewActionBar ? 'hasActionBar' : undefined}
+        data-bf-state={retainsReviewActionBarLayout ? 'hasActionBar' : undefined}
       >
         <div className="btw-session-panel__header" data-bf-component="btw-session-panel" data-bf-part="header">
           <div className="btw-session-panel__header-left" data-bf-component="btw-session-panel" data-bf-part="headerMain">
@@ -1031,6 +1067,7 @@ export const BtwSessionPanel: React.FC<BtwSessionPanelProps> = ({
 
         <div
           ref={scrollContainerRef}
+          tabIndex={-1}
           className="btw-session-panel__body"
           data-bf-component="btw-session-panel"
           data-bf-part="body"
@@ -1082,12 +1119,19 @@ export const BtwSessionPanel: React.FC<BtwSessionPanelProps> = ({
         <ScrollToBottomButton
           visible={showScrollToBottom}
           onClick={handleScrollToBottom}
+          focusReturnRef={scrollContainerRef}
           className="btw-session-panel__scroll-to-bottom"
           data-bf-component="btw-session-panel"
           data-bf-part="scrollToBottom"
         />
-        {showMinimizedIndicator && (
-          <div className="btw-session-panel__minimized-indicator" data-bf-component="btw-session-panel" data-bf-part="minimized" data-bf-state="minimized">
+        <div
+          className="btw-session-panel__minimized-indicator"
+          data-bf-component="btw-session-panel"
+          data-bf-part="minimized"
+          data-bf-state={showMinimizedIndicator ? 'minimized' : 'hidden'}
+          aria-hidden={!showMinimizedIndicator}
+          {...(!showMinimizedIndicator ? { inert: '' } : {})}
+        >
             <button
               type="button"
               onClick={() => useReviewActionBarStore.getState().restore(childSessionId)}
@@ -1106,14 +1150,21 @@ export const BtwSessionPanel: React.FC<BtwSessionPanelProps> = ({
                 </span>
               )}
             </button>
-          </div>
-        )}
+        </div>
 
-        {showReviewActionBar && (
-          <div ref={actionBarRef} className="btw-session-panel__action-bar-wrapper" data-bf-component="btw-session-panel" data-bf-part="actionBar">
+        <PresenceBoundary active={showReviewActionBar}>
+          <div
+            ref={actionBarRef}
+            className="btw-session-panel__action-bar-wrapper"
+            data-bf-component="btw-session-panel"
+            data-bf-part="actionBar"
+            data-visible={showReviewActionBar ? 'true' : 'false'}
+            aria-hidden={!showReviewActionBar}
+            {...(!showReviewActionBar ? { inert: '' } : {})}
+          >
             <ReviewActionBar childSessionId={childSessionId} />
           </div>
-        )}
+        </PresenceBoundary>
       </div>
       </FlowChatVolatileContext.Provider>
     </FlowChatContext.Provider>
diff --git a/src/web-ui/src/flow_chat/components/btw/DeepReviewActionBar.scss b/src/web-ui/src/flow_chat/components/btw/DeepReviewActionBar.scss
index 791f78fa52..260158d204 100644
--- a/src/web-ui/src/flow_chat/components/btw/DeepReviewActionBar.scss
+++ b/src/web-ui/src/flow_chat/components/btw/DeepReviewActionBar.scss
@@ -1145,3 +1145,10 @@
     }
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .deep-review-action-bar__icon--loading,
+  .deep-review-action-bar__fixing-icon {
+    animation: none;
+  }
+}
diff --git a/src/web-ui/src/flow_chat/components/chatInputRegistration.ts b/src/web-ui/src/flow_chat/components/chatInputRegistration.ts
index b872a6c33b..b44c651679 100644
--- a/src/web-ui/src/flow_chat/components/chatInputRegistration.ts
+++ b/src/web-ui/src/flow_chat/components/chatInputRegistration.ts
@@ -40,6 +40,8 @@ export interface ChatInputRegistration {
    * explicit isolated workspace and must not fall back to the active project.
    */
   workspacePath?: string;
+  /** Remote connection that owns `workspacePath`; paths alone are ambiguous across hosts. */
+  remoteConnectionId?: string;
   draft?: ChatInputDraftRegistration;
   onDraftConsumed?: (id: number) => void;
   onSubmit?: (submission: ChatInputSubmission) => void | Promise<void>;
diff --git a/src/web-ui/src/flow_chat/components/modelSelectorDropdownPosition.test.ts b/src/web-ui/src/flow_chat/components/modelSelectorDropdownPosition.test.ts
index 08929f60b5..272990e762 100644
--- a/src/web-ui/src/flow_chat/components/modelSelectorDropdownPosition.test.ts
+++ b/src/web-ui/src/flow_chat/components/modelSelectorDropdownPosition.test.ts
@@ -1,5 +1,8 @@
 import { describe, expect, it } from 'vitest';
-import { getModelSelectorDropdownStyle } from './modelSelectorDropdownPosition';
+import {
+  getModelSelectorDropdownLayout,
+  getModelSelectorDropdownStyle,
+} from './modelSelectorDropdownPosition';
 
 describe('getModelSelectorDropdownStyle', () => {
   it('preserves the measured intrinsic width in a wide viewport', () => {
@@ -28,13 +31,14 @@ describe('getModelSelectorDropdownStyle', () => {
   });
 
   it('flips below the trigger when the preferred top placement does not fit', () => {
-    const style = getModelSelectorDropdownStyle(
+    const layout = getModelSelectorDropdownLayout(
       { left: 24, top: 20, bottom: 44 },
       { width: 240, height: 200 },
       'top',
       { width: 800, height: 600 },
     );
 
-    expect(style.top).toBe('50px');
+    expect(layout.style.top).toBe('50px');
+    expect(layout.placement).toBe('bottom');
   });
 });
diff --git a/src/web-ui/src/flow_chat/components/modelSelectorDropdownPosition.ts b/src/web-ui/src/flow_chat/components/modelSelectorDropdownPosition.ts
index 6695eea0d4..7c582b82ad 100644
--- a/src/web-ui/src/flow_chat/components/modelSelectorDropdownPosition.ts
+++ b/src/web-ui/src/flow_chat/components/modelSelectorDropdownPosition.ts
@@ -23,12 +23,17 @@ interface ModelSelectorDropdownStyle {
   bottom: 'auto';
 }
 
-export function getModelSelectorDropdownStyle(
+export interface ModelSelectorDropdownLayout {
+  style: ModelSelectorDropdownStyle;
+  placement: FixedPopoverPlacement;
+}
+
+export function getModelSelectorDropdownLayout(
   anchorRect: ModelSelectorDropdownAnchorRect,
   dropdownSize: ModelSelectorDropdownSize,
   preferredPlacement: FixedPopoverPlacement,
   viewport: FixedPopoverViewport,
-): ModelSelectorDropdownStyle {
+): ModelSelectorDropdownLayout {
   const position = computeFixedPopoverPositionInViewport(
     anchorRect,
     dropdownSize.width,
@@ -36,12 +41,34 @@ export function getModelSelectorDropdownStyle(
     viewport,
     { preferredPlacement },
   );
+  const placement = position.top + dropdownSize.height <= anchorRect.top
+    ? 'top'
+    : position.top >= anchorRect.bottom
+      ? 'bottom'
+      : preferredPlacement;
 
   return {
-    position: 'fixed',
-    visibility: 'visible',
-    left: `${position.left}px`,
-    top: `${position.top}px`,
-    bottom: 'auto',
+    placement,
+    style: {
+      position: 'fixed',
+      visibility: 'visible',
+      left: `${position.left}px`,
+      top: `${position.top}px`,
+      bottom: 'auto',
+    },
   };
 }
+
+export function getModelSelectorDropdownStyle(
+  anchorRect: ModelSelectorDropdownAnchorRect,
+  dropdownSize: ModelSelectorDropdownSize,
+  preferredPlacement: FixedPopoverPlacement,
+  viewport: FixedPopoverViewport,
+): ModelSelectorDropdownStyle {
+  return getModelSelectorDropdownLayout(
+    anchorRect,
+    dropdownSize,
+    preferredPlacement,
+    viewport,
+  ).style;
+}
diff --git a/src/web-ui/src/flow_chat/components/modern/AGENTS.md b/src/web-ui/src/flow_chat/components/modern/AGENTS.md
index d96a429bbe..34f1588bb9 100644
--- a/src/web-ui/src/flow_chat/components/modern/AGENTS.md
+++ b/src/web-ui/src/flow_chat/components/modern/AGENTS.md
@@ -1,127 +1,217 @@
-# FlowChat Scroll Stability Instructions
+# FlowChat Scroll Instructions
 
 This file applies to the modern FlowChat viewport implementation under this
-directory.
+directory. It is the rules. The reasoning, the measurements, and the failures
+each rule was written against live in the documents below — read the one that
+covers what you are about to change.
+
+Also follow the repository and Web UI instructions in the parent guides.
 
 ## Required Reading
 
-Before changing FlowChat rendering, projection, virtualization, scrolling,
-tool-card collapse behavior, footer reservations, runtime-status slots, or
-typewriter/reveal behavior, read:
-
-- `FLOWCHAT_SCROLL_STABILITY.md`
-
-Also follow the repository and Web UI instructions in the parent `AGENTS.md`
-files.
-
-The stability document describes the current contracts and the failure modes
-that have caused visible flashes, header drops, stale tail whitespace, and
-scroll ownership races. Treat it as part of the implementation contract, not
-as background documentation.
-
-## Stability Model
-
-The central invariant is single ownership of viewport motion:
-
-- `FlowChatViewportCoordinator` owns semantic viewport modes and anchors:
-  `pinned-item`, `following-tail`, and `preserving-element`.
-- `useFlowChatFollowOutput` owns the continuous streaming tail-follow RAF loop.
-  It is the only continuous writer that advances the viewport toward the
-  streaming tail and it must yield while an element anchor or collapse
-  transaction owns the viewport.
-- `VirtualMessageList` keeps Virtuoso's `followOutput={false}`. Do not enable
-  Virtuoso's autonomous follow behavior or introduce another effect that writes
-  the outer FlowChat viewport tail position. Independent writers are what
-  produce the drop-then-restore flash. Local scroll surfaces inside a thinking,
-  explore, terminal, or subagent card have their own narrowly scoped behavior.
-- Tool cards must not calculate `scrollTop`, `scrollBy`, compensation pixels,
-  or anchor offsets. They dispatch
-  `flowchat:tool-card-collapse-intent` before a known height reduction and use
-  `useToolCardHeightContract` for the state transition.
-- Direct `scrollTop` / `scrollTo` writes are not categorically forbidden, but
-  outer-viewport writes are restricted to the coordinator, the follow
-  controller, and the narrowly scoped `VirtualMessageList` navigation,
-  physical-bottom recovery, and reservation transactions. Every new write
-  needs an explicit owner, a user-intent guard, and a reason why the existing
-  coordinator or follow controller cannot perform it.
-- Footer `collapse` and `pin` reservations provide physical range while the
-  DOM or Virtuoso measurements settle. Apply footer compensation synchronously
-  before restoring an anchor; do not replace this with React-state-only footer
-  rendering.
-
-Stable virtual-item keys and projection identity are equally important. Do not
-split one `ModelRound` into multiple `model-round` virtual items, add
-mount-triggered animations, or use a timer to reclassify projection/grouping.
-Card-local completion preview timers are allowed only when they leave the
-virtual projection unchanged and use the existing height contract when they
-eventually collapse a card.
-
-## Required Verification
-
-Choose focused tests for the code you changed, then run the normal Web UI
-checks:
-
-```text
-pnpm run type-check:web
-pnpm --dir src/web-ui run lint
-pnpm --dir src/web-ui run test:run <focused-test-files>
-```
-
-Relevant stability tests include:
-
-- `src/flow_chat/components/modern/FlowChatViewportCoordinator.test.ts`
-- `src/flow_chat/components/modern/useFlowChatFollowOutput.test.tsx`
-- `src/flow_chat/components/modern/VirtualMessageList.layout.test.ts`
-- `src/flow_chat/components/modern/VirtualMessageList.session-boundary.test.tsx`
-- `src/flow_chat/components/modern/flowChatCollapseMotion.test.ts`
-
-For tool-card or collapse-contract changes, also run the nearest focused card
-tests, for example the `FileOperationToolCard`, `ExecProcessToolCardView`,
-`TaskToolDisplay`, `useToolCardHeightContract`, or `SmoothHeightCollapse` tests.
-Do not claim the stability behavior is verified from type-check/lint alone.
-
-## Manual Verification
-
-For changes that affect viewport ownership, tail follow, pinning, collapse
-height, session handoff, or scroll event handling, **require the user to perform
-the following manual verification before considering the change complete**.
-These interactions are too stateful and timing-sensitive for an Agent to verify
-reliably; an Agent may run static checks and automated tests, but must not claim
-these manual results without explicit user confirmation. Use a real streaming
-conversation and check all of the following:
-
-1. Start a new round and confirm the new user message is pinned to the intended
-   top position without a visible jump.
-2. Do not touch the viewport while output streams. When the output reaches the
-   bottom, confirm it transitions naturally into follow-output mode instead of
-   stopping short or waiting for the round to finish.
-3. While output is streaming and following, scroll upward and downward by hand.
-   Confirm the user's scroll intent immediately wins: auto-follow must not pull
-   the viewport back or re-pin it unexpectedly.
-4. Switch to another conversation during an active round, then return to the
-   original conversation. Confirm the viewport resumes the correct follow mode
-   when appropriate, without a black/empty tail, excessive synthetic footer
-   space, or a delayed recovery that depends on another user scroll.
-5. Exercise completed `Write`, `Edit`, `ExecCommand`, and terminal/tool-card
-   collapses both at the tail and in the middle of the transcript. Confirm the
-   header stays at the same viewport position while the body contracts.
-6. Repeat the flow around thinking, explore groups, runtime-status/footer
-   visibility, and at least one multi-tool round. Confirm there is no visible
-   flash, drop-then-snap-back, permanent fall, accumulating tail whitespace, or
-   one-frame loss of the pinned header.
-
-When a manual check fails, enable the FlowChat diagnostics setting and inspect
-the session `flowchat.log` before changing ownership rules. Keep diagnostic
-payloads bounded and free of message content, tool arguments, and file data.
-
-## Change Discipline
-
-- Do not add a competing scroll writer, persistent scroll lock, or ad hoc
-  `scrollBy`/`scrollTo` call from a card or renderer.
-- Do not bypass `flowchat:tool-card-collapse-intent` for a known shrink.
-- Do not clear footer reservations or semantic anchors merely to make a test
-  pass; determine which viewport owner still needs them.
-- Preserve user scroll intent, session/generation cancellation, and cleanup of
-  pending RAF/timer work.
-- Update `FLOWCHAT_SCROLL_STABILITY.md` whenever the ownership model,
-  reservation contract, collapse lifecycle, or required verification changes.
+| Changing | Read |
+|---|---|
+| the tail spacer, the follow target, pinning, holding, resizing, the footer, the reveal | `FLOWCHAT_SCROLL_STABILITY.md` |
+| history paging, the prepend, the viewport anchor, history presentation | `FLOWCHAT_HISTORY_PAGING.md` |
+| anything that writes `scrollTop`, one-shot navigation, the diagnostic trail | `FLOWCHAT_VIEWPORT_REGISTER.md` |
+| the virtualizer, item measurement, item keys, anything a row renders | `FLOWCHAT_VIRTUALIZATION.md` |
+
+`FLOWCHAT_SCROLL_STABILITY.md` also carries *Known Gaps* for all four — check it
+before reporting a defect as new.
+
+## Reservation and Follow
+
+- FlowChat reserves a resident tail spacer of about one viewport, sized from
+  `scroller.clientHeight` and nothing else.
+- Static reservation is allowed; reactive compensation is not. Do not derive any
+  reserved height from a measured content height, a collapse delta, an animation
+  duration, or a streaming rate.
+- Do not add sticky Turn modes, pre-collapse compensation, or persistent
+  element-anchor guards.
+- The follow target lives in `flowChatTailFollow.ts` as pure functions over
+  geometry. Keep it free of timers and mutation observers.
+- `scheduleFollowToLatest` must not force the content end — the hold rule is
+  what keeps a collapse from moving the viewport.
+- `useFlowChatFollowOutput` is the only continuous outer viewport writer.
+- The follow's **write** may be eased; its **target** may not. Everything that
+  reads the follow — the settle budget and the at-tail band — reads
+  the offset the rule owns, never how far behind the ease is riding. The ease
+  stands down while the transcript is opening, where the target is
+  authoritative.
+- A follow the frame loop is still correcting counts as being at the tail.
+  Ownership cannot stand in for that: it outlives the loop, which is exactly the
+  state a viewport stranded in the reserved blank is in.
+- The loop's stand-down for its own animated scroll is timed in milliseconds at
+  both ends — how long it waits for the animation to move, and how long it
+  waits for the animation at all. Neither may be a frame count: a frame count
+  is not a duration, and a smooth scroll eases in slowly enough that its first
+  frames do not move at all on a high-refresh display.
+- A jump to latest animates only within `FLOWCHAT_ANIMATED_JUMP_MAX_VIEWPORTS`
+  and lands outright past it. Measured in viewports, never in pixels: the
+  question is whether the reader can follow the movement, and what they can
+  follow is a share of what they can see.
+- Scrolling up loses the follow only once the reader is past the end of real
+  content. Until then they are in the reserved blank, having missed nothing, and
+  output growing to fill it hands the viewport back — unless their own gesture
+  claim is still live, in which case the crossing is deferred, not spent. Judged
+  by which side moved further between two samples, never by geometry alone.
+- That watch runs for as long as the reader holds the viewport, not for one
+  crossing. A reader may climb out of the blank and scroll back down into it any
+  number of times, and each time is another chance for output to reach them.
+- Footer height represents only the current input-stack layout and real footer
+  content such as history state and `RuntimeStatusSlot`. The tail spacer is a
+  separate sibling and must not be folded into it.
+- "At bottom" is measured against the end of real content, which sits above the
+  tail spacer, so no alignment to the last item can express it.
+
+## The Viewport Register
+
+- Every deliberate viewport write goes through `useFlowChatViewportOwner`, named
+  with the owner it belongs to, and holds that ownership for as long as it is
+  moving — an animation included. Never assign `scrollTop` or call `scrollTo`
+  on the FlowChat scroller directly.
+- Adding an owner means adding it to `FLOWCHAT_VIEWPORT_OWNERS` in priority
+  order and to its test, not adding a condition to anyone else's predicate.
+- The virtualizer's own writes are registered through its `scrollToFn` option
+  and attributed to whoever asked for the aim. Do not bypass it.
+- A writer that declines to move the viewport says so through
+  `flowChatViewportDiagnostics.ts`. The register records the writes; a write
+  that never happened is invisible everywhere else, and "nothing happened" is
+  the more common report. Anything reachable every frame goes through
+  `traceViewportRepeating`, keyed by what distinguishes one run from another —
+  **including the magnitude a reader would feel and the subject it is about**. A
+  run collapses to its first sample and turns the rest into a sum, so a key too
+  coarse to separate a rounding correction from a 400px one hides exactly the
+  events worth having: two rounds of diagnosis in a row read `0.7px` against
+  458.7px of suppressed travel spanning three different anchors.
+- There are no viewport writes outside the register. Adding one means wrapping
+  it in `traceViewportPlacement` and having a reason it cannot be a register
+  write; both writers that used to be outside are gone.
+- One user action gets one painted placement. A focus request that first
+  navigates to a Turn and then aims at an item inside it does both in the same
+  task — two placements a few frames apart are two movements the reader sees,
+  and the sampled drift lands on the first one, not the second.
+- Centring a flow item is `VirtualMessageListRef.focusFlowItem`, not
+  `element.scrollIntoView`. The virtualizer aligns *items*, so it cannot express
+  "this tool call inside this Turn"; the computed offset is the contract's
+  carve-out for a target that is not an item, and it still goes through the
+  register.
+- One-shot Turn/search/history navigation remains inside `VirtualMessageList`.
+- A gesture ends an aim, it does not merely outrank it. The library's re-aim
+  runs for 5s and cannot see a refusal, while a gesture's hold lasts 200ms, so
+  `notifyUserScrollIntent` calls `cancelAim`. Anything else that hands the
+  viewport to a new owner mid-aim owes the same call.
+
+## History Paging and the Anchor
+
+- Deciding *that* a history boundary is worth asking about belongs to
+  `flowChatHistoryBoundary.ts` and reads only a visible item range and the
+  scroll distance to each end. Deciding whether the ask is honoured stays in the
+  container, which declines while follow-output owns the viewport and until the
+  visible range has left that boundary since the last page.
+- A page asks for what lies past the *rendered* transcript, never past the
+  window the store cut. The continuous projection makes those differ, and the
+  window's end is then an ordinal already on screen.
+- Every path out of a boundary intent records an outcome and leaves the boundary
+  status in a state it can be seen in. A silent return is a status the reader
+  keeps looking at, and `loading` is not a resting state.
+- A boundary status is labelled by what it is. An `error` rendered with the
+  `loading` label is a permanent failure shown as permanent progress.
+- The ask goes out a screenful before the boundary, so the junction lands off
+  screen. Do not express that lead in items: one item here is anything from a
+  38px user message to a 5012px model round.
+- The arming latch re-arms from `historyBoundariesReached`, never from the ask.
+  Sharing one predicate makes a boundary the reader can never be off, and the
+  direction stays disarmed for the rest of the session.
+- A *visible* item range is `getVisibleItemRange`, never the rendered rows. The
+  rendered window carries overscan and reports both ends present for any
+  transcript short enough to render whole.
+- Boundaries are evaluated on scroll **intent**, not only on `scroll` events. A
+  reader already at the top produces no scroll event, so the one signal that
+  they want more history is the gesture itself. Evaluate after ownership has
+  been released, so the ask is theirs rather than our placement's.
+- Ownership is read through `isFollowingOutputNow()`, never a render-time mirror
+  of `isFollowingOutput`. A gesture releases it synchronously and asks in the
+  same handler; the mirror still reports the ownership that gesture just ended.
+- `exhausted` is latched per *window*, not per session. It answers "nothing
+  before this start ordinal", so the latch clears whenever the window's ordinals
+  change — not only when a page is `applied`.
+- A history prepend must be compensated for in `VirtualMessageList`, by the
+  height of the items that arrived above. Keying measurements on item identity
+  covers the measurements; it does not move the scroll offset. The compensation
+  cannot finish the job on its own — most of the movement is the arrived items
+  measuring over the frames after it, and only the anchor's relationship
+  survives that.
+- That compensation and the viewport anchor are displacements, not positions:
+  `viewportOwner.shift`, never a write with an owner. A gesture must not be able
+  to refuse either — paging up happens only while the reader is scrolling up, so
+  anything a gesture can refuse here is refused every time.
+- A scroll re-anchors the reader, except while the anchored Turn is missing from
+  the rendered window. A correction is owed there and cannot be measured yet, so
+  the anchor is carried through the scroll — credited with the reader's own
+  travel — never replaced by whatever else happens to be rendered.
+- The anchor's settle window is refreshed by what a frame *observed*, never by a
+  counter left over from an earlier one. A frame that stood down for another
+  owner looked at nothing, so it refreshes nothing — otherwise the loop runs at
+  frame rate for as long as that owner rests on the viewport, which at the tail
+  is indefinitely.
+- The viewport anchor lives in `flowChatViewportAnchor.ts` and
+  `useFlowChatViewportAnchor.ts` and must stay independent of the virtualizer:
+  it may read the scroller and the Turns rendered inside it, and nothing else.
+  Virtualizer-specific compensation stays in `VirtualMessageList`.
+- "A new Turn" is `activeSession.dialogTurns.at(-1)`, never the end of the
+  projection. Do not qualify that identity by whether the Turn is on screen —
+  that belongs to the response, which defers until the Turn can be aligned.
+- Detecting one means the ledger **grew**, not that the identity changed. A
+  rollback truncates `dialogTurns` and moves that identity backwards onto a Turn
+  that was always there; read as an arrival it pins the survivor to the top.
+- An action that rewrites `dialogTurns` and wants the viewport moved announces
+  it — `FLOWCHAT_MESSAGE_SUBMITTED_EVENT` for giving up a navigated history
+  window, `FLOWCHAT_TURNS_ROLLED_BACK_EVENT` for settling on a new tail. The
+  ledger cannot tell a Turn the reader sent from one that arrived from
+  elsewhere, nor a rollback from a window re-cut, and there are two dozen
+  writers of that array. Do not infer either from a count.
+
+## Virtualization and Rendering
+
+- `useFlowChatVirtualizer.ts` is the only module that may import a virtualization
+  library. It speaks in scroller offsets and item positions; anything that would
+  make a caller aware of which library is underneath belongs inside it.
+- Prefer `scrollItemIntoView` over computing an offset. The virtualizer re-aims
+  while items below the target measure, and an offset computed once cannot.
+  Compute one only when the target is not an item.
+- Anything reading an item position in the commit that changed the items calls
+  `measureRenderedItems()` first. The library skips its inline measurement while
+  the reader is scrolling, which is exactly when history arrives, so the cache
+  holds reserved estimates until the ResizeObserver delivers a frame later.
+- The virtualizer must not adjust the scroll for its own re-measurements. It
+  replays a delta against a scroll position it learns about a frame late, and
+  every continuous writer here assigns `scrollTop` directly.
+- The virtualizer never follows output.
+- No mount or enter animation inside `.virtual-item-wrapper`, no mount-triggered
+  motion that changes transcript geometry, and nothing keyed on a state change a
+  scroll can replay. A row mounts when it enters the rendered window, not when
+  its content arrives, so the animation runs again on every page up and every
+  scroll back. Cancel it at the wrapper rather than in the component — this has
+  been patched locally four times and recurred each time.
+- Tool cards reflow naturally and dispatch only `tool-card-toggle` after an
+  expanded-state change so the virtualizer can remeasure.
+- Stable virtual-item keys and projection identity must be preserved. Do not
+  split one `ModelRound` into multiple virtual items or reclassify projection
+  from a timer.
+
+## Verification
+
+`FLOWCHAT_VERIFICATION.md` is the single list — the automated checks, mapped to
+the contract each one holds, and the manual ones grouped by scenario. Do not
+keep a second copy here.
+
+Do not perform UI interaction verification. Report the manual checks as pending
+unless the user confirms them.
+
+## Keeping These Documents True
+
+Update the document that owns the area you changed, and this file only if a rule
+changed. A rule belongs here when a reviewer could catch its violation by
+reading a diff; everything else — the reasoning, the numbers, the failure it was
+written against — belongs in the document.
diff --git a/src/web-ui/src/flow_chat/components/modern/ExploreGroupRenderer.tsx b/src/web-ui/src/flow_chat/components/modern/ExploreGroupRenderer.tsx
index c75ea5e40d..cb1b094182 100644
--- a/src/web-ui/src/flow_chat/components/modern/ExploreGroupRenderer.tsx
+++ b/src/web-ui/src/flow_chat/components/modern/ExploreGroupRenderer.tsx
@@ -129,14 +129,10 @@ export const ExploreGroupRenderer: React.FC<ExploreGroupRendererProps> = React.m
   // One-shot auto-collapse: fires exactly once when the group transitions from
   // tail (wasCutByCritical=false) to cut (wasCutByCritical=true).
   //
-  // IMPORTANT: do NOT use `isExpanded` to guard this effect. When wasCutByCritical
-  // flips to true, the same render also recomputes isExpanded = false (because
-  // defaultExpanded = !wasCutByCritical). So `justGotCut && isExpanded` would
-  // always be false and the collapse-intent would never fire.
-  //
-  // No explicit state means the group was expanded by the live-tail default,
-  // so dispatch the height-contract event before compacting it. An explicit
-  // state is user intent and must not be overwritten by a later auto event.
+  // Do not use `isExpanded` to guard this effect. The render that flips
+  // `wasCutByCritical` also recomputes the default expanded state. No explicit
+  // state means the live-tail default may collapse naturally; an explicit
+  // state is user intent and must not be overwritten.
   useLayoutEffect(() => {
     const justGotCut = wasCutByCritical && !prevWasCutRef.current;
     prevWasCutRef.current = wasCutByCritical;
@@ -147,8 +143,6 @@ export const ExploreGroupRenderer: React.FC<ExploreGroupRendererProps> = React.m
 
     applyExpandedState(true, false, () => {
       onCollapseGroup?.(groupId);
-    }, {
-      reason: 'auto',
     });
   }, [
     applyExpandedState,
diff --git a/src/web-ui/src/flow_chat/components/modern/FLOWCHAT_HISTORY_PAGING.md b/src/web-ui/src/flow_chat/components/modern/FLOWCHAT_HISTORY_PAGING.md
new file mode 100644
index 0000000000..cf808fb2f8
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/modern/FLOWCHAT_HISTORY_PAGING.md
@@ -0,0 +1,663 @@
+# FlowChat History Paging
+
+Older Turns are fetched when the reader approaches the head of the loaded
+window, prepended above them, and paid for by moving the viewport down by
+exactly what arrived. This document covers the whole of that: when the ask goes
+out, what may refuse it, how the displacement is repaid, and how the reading
+position survives the measurement that follows.
+
+Read alongside `FLOWCHAT_VIEWPORT_REGISTER.md` — the two repairs described here
+are the only writers that do not take their turn in the priority order — and
+`FLOWCHAT_VIRTUALIZATION.md`, which owns the measurement behaviour they depend
+on.
+
+## A Page Is Asked For a Screenful Early
+
+A history page is not a quiet event, and no amount of care makes it one. The
+items arrive above the reader and everything below them moves; the virtualizer
+picks its window from a scroll offset it only learns from scroll events, so for
+one commit it renders from a position the reader has already been moved off and
+the transcript below the junction goes blank; the rows then measure and the
+whole thing settles a second time. Watched frame by frame, at 1/8 speed: the
+loading notice disappears, the tail of the previous Turn leaks out, everything
+past the junction goes white, the viewport shifts up and clips the top of a user
+message, and then it is fine. Four frames, twice, at the two junctions the
+reader crossed.
+
+Every one of those steps is correct. The reader still called it a flicker and a
+jolt, because they were looking at it.
+
+So the ask goes out while the boundary is still a screenful away —
+`HISTORY_BOUNDARY_LEAD_SCREENS`, measured against live geometry rather than an
+item count, since one item here is anything from a 38px user message to a
+5012px model round. The page then lands above the viewport: the mis-aimed
+window, the blank and the re-measurement all happen where nobody is looking, and
+the reader scrolls up into content that is already there and already measured.
+It costs one page of history fetched sooner than strictly needed, and nothing on
+session open, where the boundary is a whole transcript away.
+
+The pixel rule is a union with the item rule, not a replacement. A window short
+enough that its head is on screen has no screenful of lead to offer, and that
+case is the one the item slack was written for.
+
+**The lead widens the ask and nothing else.** `historyBoundariesReached` is a
+separate function for that reason: the arming latch below disarms a direction on
+dispatch and re-arms it when the reader is no longer at the boundary, so serving
+the latch from the wider answer leaves a boundary the reader can never be off.
+Measured, with the two sharing one predicate: a 43-Turn session loaded one
+window of five Turns, and every ask afterwards was refused as `not-rearmed` —
+39 refusals over six minutes, the reader scrolling into a wall two Turns from
+the top of what was loaded. The two questions look alike and are not: *has the
+reader arrived* is about them, *is it worth asking* is about the fetch.
+
+A pass can therefore re-arm and ask in the same breath, which is the point
+rather than an oversight — "off the boundary, and a screen from it" is exactly
+the state the lead exists to serve.
+
+The lead is one screen rather than several because it only has to outlast the
+fetch. At a brisk wheel scroll the reader covers a few hundred pixels in the
+time a page takes to arrive from local storage; a longer lead just loads history
+nobody reaches.
+
+## Two Refusals Stand Between an Ask and a Page
+
+`flowChatHistoryBoundary.ts` decides that a boundary is worth asking about.
+Whether the ask is honoured is the container's, and it declines twice:
+
+**While follow-output owns the viewport.** The position the ask was derived from
+is then our own placement, not the reader's — as true of a history window being
+opened as of the live tail, so the test is ownership and not presentation mode.
+Ownership ends the moment the reader scrolls, which is exactly when the ask
+starts meaning something.
+
+**Until the visible range has left that boundary.** Prepend compensation puts
+the viewport back on the reader's content, but the virtualizer places its rows
+from a scroll offset it refreshes a frame later, so for one commit the visible
+range is still read against the head. A direction is disarmed on dispatch and
+armed again by the range leaving it — by `historyBoundariesReached`, never by
+the wider ask; an ask that resolves to anything other than `applied` re-arms
+immediately, because nothing was prepended and the range sitting at the boundary
+is still the reader's own position.
+
+Both were free under react-virtuoso: `firstItemIndex` moved the reported range
+with the prepend, so the local start index jumped by the number of items added
+and the rule stopped applying by itself.
+
+**A gesture that moves nothing still asks.** The evaluation used to hang off
+the `scroll` event, which is the one signal a reader at the top cannot produce:
+the wheel changes no offset, so no event fires, so nothing asks. Combined with
+the ownership refusal that is a closed loop, and it was measured as one. A tail
+window of three Turns fitted inside the viewport, which put the entire scroll
+range inside the reserved blank:
+
+- at the bottom of that range no row intersects the viewport at all, so
+  `getVisibleItemRange` returns nothing and there is no position to judge;
+- at offset 0, an evaluation may still be refused while follow-output owns the
+  opening placement;
+- and at offset 0 the reader's own gestures produced twenty `user-gesture`
+  claims over seven seconds with no scroll event, no anchor capture, and not
+  one evaluation.
+
+Scrolling up did nothing, permanently. So `notifyUserScrollIntent` evaluates
+too, after it has cleared follow-output's ownership — which makes the ask the
+reader's rather than our placement's, and gives the top of the range a signal
+it can actually emit.
+
+The empty visible range is traced (`historyPaging.noVisibleRange`) rather than
+returned from in silence. Reading that session, the absence of an anchor
+capture was the only way to tell "nobody asked" from "the ask was refused".
+
+**The ask reads ownership as of now, not as of the last render.** A gesture
+releases follow-output synchronously and then asks, so a render-time mirror of
+`isFollowingOutput` reports the ownership the gesture has just ended.
+`isFollowingOutputNow` is the hook's own ref, and the refusal reads it — in the
+log, `followOutput.exit` and `historyPaging.refused:
+follow-output-owns-the-viewport` sat at the same millisecond, three entries
+apart, and the ask was refused for an ownership one line older than itself.
+
+**`exhausted` describes the window that asked, not the session.** "There is
+nothing before this" is a fact about a start ordinal. Navigating to the first
+Turn asks `before`, the store answers `reached-start` for `targetOrdinal: -1`,
+and that is correct — but only until the window moves. Only `applied` used to
+clear the latch, which is the single case where the window moves *because* of
+the page; every other way it moves left the old answer standing. Measured: 3
+Turns of 43 loaded, `before` latched from a visit to Turn 1, and after jumping
+back to the tail the reader could not page at all.
+`warnHistoryPagingRefusedWithPendingTurns` fired
+(`latched-exhausted-while-partial`) and nothing acted on it. The latch is now
+cleared whenever the window's ordinals change.
+
+## Keeping the Viewport on the Reader's Content
+
+When history is prepended, the items arriving above the reader push their content
+down by their own height while `scrollTop` stays the number it was.
+`VirtualMessageList` adds that height back, in a layout effect, before anything
+else observes the new transcript. The amount is read from the virtualizer's
+placement of the item that *used to be first* — the height of exactly what
+arrived, a delta and not a total.
+
+This is the half of `firstItemIndex` that keying measurements on item identity
+does not supply, and it was left out of the TanStack migration. Everything
+downstream assumes it holds, and three separate failures were that one
+assumption breaking:
+
+- The virtualizer re-windows from its own scroll offset, which lags a frame, so
+  it renders the head. The paging rule reads that as the reader having arrived
+  at the head, and pages again — **five pages in 890ms on session open, and a
+  single junction paging a transcript back to its first Turn**.
+- The anchored Turn falls outside that window, so the anchor cannot find its
+  element, drops the anchor, and corrects nothing. Measured: **655px of history
+  arrived and `scrollTop` held at 23**, leaving the reader at the top of a block
+  they never asked to see.
+- With the reader left at the head, the paging boundary never re-arms and
+  history becomes unreachable.
+
+The arriving items are estimates until they measure, so this lands close rather
+than exactly; the anchor — which can now find its Turn — takes it the rest of the
+way. It writes as `layout-correction`, so the register refuses it while anything
+above is moving the viewport on purpose: a navigation reaching a Turn, or the
+follow loop re-asserting its target, both of which already say where the reader
+belongs.
+
+## A Displacement Is Not a Movement
+
+Two things repair displacement rather than choose a position, and neither goes
+through the priority order in `FLOWCHAT_VIEWPORT_REGISTER.md`: the prepend
+compensation, and the viewport anchor. Both are `viewportOwner.shift`, which
+asks a different question — content moving under the reader changes what their
+offset *means*, and restoring that meaning is not competing with anyone over
+where the viewport should be. So they are refused only by an owner that holds a
+target and will re-assert it: follow-output or a navigation still reaching its
+Turn.
+
+The two are not redundant. The compensation is a pixel delta applied in the
+commit that prepends, and it is the only thing that can act when the reader's
+Turn is not rendered. The anchor restores a relationship, so it is the only
+thing that can act on a re-measurement landing *after* that commit — which is
+the majority of the movement, since the arrived items measure over the frames
+that follow. Measured: a compensation of exactly the DOM's own growth (949px)
+still left the reader at the end of the transcript, because the transcript then
+shrank 200px in the next 21ms.
+
+**The anchor cannot act in the prepend commit itself.** The virtualizer chooses
+its rendered window from a scroll offset it only learns from scroll events
+(`calculateRange` is memoised on `getScrollOffset()`, and `scrollOffset` is
+assigned in the `observeElementOffset` callback and nowhere else), so the commit
+that prepends is still windowing the position the reader has just been moved
+off. Their Turn is in the DOM a frame later. This is why the anchor keeps an
+anchor whose Turn is missing rather than dropping it on the first miss: dropping
+threw the reading position away one frame before it could be used, at four
+junctions in a row and not one correction between them.
+
+**A gesture is not one of them, and must not be.** The reader chose a position
+in the transcript, not a number of pixels. Ranking these under `user-gesture`
+was a total failure rather than an intermittent one, because history pages in
+*only* while the reader scrolls up into the boundary — so the gesture was
+holding the viewport every single time either of them had work to do. Measured:
+2494px of history arrived and the compensation was refused, `scrollTop` held at
+40, and the transcript jumped back thirteen Turns; in the same session the
+anchor stood down 23 times and corrected nothing at all.
+
+Correcting during a gesture is safe for the reason the anchor already re-anchors
+on every scroll of the reader's: within that window the anchor is tracking them,
+so a correction is zero unless something else really moved. Outside it, nothing
+changed — the claim had already lapsed.
+
+**The amount is the smallest of three bounds**, because each of them
+over-states and they do so for different reasons:
+
+| Bound | Over-states when |
+|---|---|
+| `prependedPx` — height the arrived items measure, read back from the cache | the arrived items are not all rendered, so some of them are still estimates |
+| `scrollRangeGrowthPx` — what the scroll range actually gained | the transcript also grew *below* the reader in the same commit |
+| `contentEndPx - scrollTop` — what the range can absorb | never; content arriving above the reader cannot push them past the end |
+
+Overshooting is the expensive direction. It puts the reader below the content
+end inside the reserved blank. Undershooting leaves them looking at slightly
+earlier content, which the anchor removes.
+
+**The cache is measured before it is read.** Left alone it is not close:
+measured twice in one session, 2174px reserved against 670px of real growth,
+then 2494px against 949px — and the whole nineteen-item transcript came to
+1236px once measured. That gap is not a virtualizer being approximate, it is a
+guard in the library. `measureElement` resizes an item inline only when the
+reader is holding still:
+
+```js
+if ((!this.isScrolling || this.scrollState) && ...) this.resizeItem(...)
+```
+
+History pages in precisely when they are not. So at a junction the rows are in
+the DOM at their real heights, the cache holds the estimates it reserved for
+them, and the ResizeObserver that would have reconciled the two does not deliver
+until after the layout effects of the commit that added them — one frame later
+than the compensation, which has to move the reader in the same paint as the
+rows that displaced them. `virtualizer.measureRenderedItems()` does that
+reconciliation itself, first thing: the same work, a frame earlier, and free for
+any row whose height was already right (`resizeItem` returns on a zero delta).
+
+`prependCompensated` still records all three numbers, so the remaining gap
+between `prependedPx` and `scrollRangeGrowthPx` is a reading rather than an
+inference — and now it is a reading of how much of the arrived block was never
+rendered, not of how far behind the cache is.
+
+## The Viewport Anchor Owns Scroll Compensation
+
+A virtualizer places items in the scroll range before it knows how tall they
+are, so every late measurement rewrites the offset of everything below it.
+Correcting for that is unavoidable. Doing it with `scrollTop` is not possible:
+the same number means a different place after every measurement. The reading
+position is therefore recorded as a **Turn and its offset from the viewport
+top**, and restored as a relationship rather than replayed as a delta. That
+makes the correction idempotent — when nothing moved it is zero.
+
+**The anchor is the only compensator.** The virtualizer's own adjustment is
+turned off (see `FLOWCHAT_VIRTUALIZATION.md`) because it replays a delta against
+a scroll position it learns about a frame late. Restoring a relationship has no
+base to go stale, which is the whole reason this is the one that stays.
+
+This was not always true, and what happened when it was not is why the rule is
+written down. react-virtuoso corrected by the change in *total* list height,
+which assumes the change happened above the viewport — scrolling up into a
+freshly paged block guarantees it did not, and one item measuring 38px -> 1003px
+moved the viewport 965px, across a whole Turn. Worse, the correction was gated
+on scroll direction, and its own prepend compensation set that direction to
+`down`, disabling it for exactly the measurements that followed: `scrollHeight`
+went 8393 -> 10073 with `scrollTop` held at 1133 and no correction at all,
+sliding the transcript down by the full 1680px. Those corrections had to be
+intercepted at `scrollBy` and answered by re-anchoring. **Do not reintroduce a
+compensator whose amount is a total rather than a delta.**
+
+**Capture is qualified by intent, not by geometry.** A scroll event cannot say
+whether the user moved or the transcript moved under them, so a *new* Turn is
+taken as the reading position only within `USER_DRIVEN_SCROLL_WINDOW_MS` of a
+wheel, touch, key, or scrollbar press — the same distinction follow-output
+draws. Two rules were tried and measured first, and both failed in ways worth
+recording:
+
+- Capturing at the intent event itself records the position *before* the scroll
+  it causes, which drags a scrolling viewport backwards.
+- Gating on "the content height did not change" blocks almost every capture,
+  because lazy measurement changes it on nearly every frame: 1075 blocked
+  captures against 8 accepted ones, and a 1037px correction issued against the
+  user's own gesture.
+
+**A scroll may not replace an anchor that is owed a repair.** While the anchored
+Turn is missing from the rendered window the displacement exists and cannot yet
+be measured, and re-reading the anchor from the DOM takes whatever *is* rendered
+at its already-displaced position — which files the displacement away as the
+reader's own choice. Measured across five history junctions: the anchor was owed
+104px, then 140px, then an amount never established, and at three of the five a
+scroll 77ms later replaced it before the Turn came back. Two of the three were
+never corrected at all.
+
+Refusing the scroll outright is not the answer either — paging up is something
+the reader does *while scrolling*, so the anchor would fight them for the whole
+settle. So the anchor is **carried** instead: their travel is a change to
+`scrollTop`, and it is subtracted from where the Turn is expected to be, leaving
+only the part the transcript moved outstanding. When the Turn renders, the
+correction is that part and none of their scrolling — however far they got.
+
+**Falling outside the intent window is not grounds for ignoring a scroll.** The
+window runs from the *input* event while the scrolling it authorises outlives
+it: a wheel notch smooth-scrolls for longer than 200ms, and a main thread busy
+with streaming delivers one coalesced event carrying the whole travel after the
+window has closed. Ignoring it leaves the reader's own movement credited to
+nobody, and the next settle undoes it in full. Measured over 181 seconds of
+reading: fourteen gestures, **one** capture, and seven corrections between 308px
+and 618px that each returned the viewport to exactly where its gesture had
+started — the reader could not get anywhere.
+
+So a scroll has three answers, not two, and the third is the same **carry**:
+
+| | |
+|---|---|
+| **Captured** | A recent intent event. The Turn they arrived at is the new reading position. |
+| **Carried** | Not provably theirs, and no registered writer owns the viewport. Nothing else changes `scrollTop`, so it is theirs. |
+| **Left alone** | A registered writer owns the viewport. It chose that position; the stored relationship is not rewritten on its account. |
+
+Carrying is safe here for the same reason it is safe anywhere: a displacement
+moves the transcript *under* a viewport whose `scrollTop` does not change, so
+carrying is a no-op for exactly the case the anchor exists to repair.
+
+The third row changes nothing the reader can see — a restore carries the anchor
+through whatever moved the viewport anyway, by the rule below — and it is kept
+because the stored offset then goes on meaning "where the Turn was when the
+reader last agreed to it", which is what the trail is read as.
+
+**A displacement moves the transcript under a `scrollTop` that stays put.** That
+is what makes it a displacement, and it is the rule the correction is computed
+from: whatever `scrollTop` has changed by since the anchor's offset was agreed
+belongs to whoever changed it, and only what is left over is drift to repair.
+
+The alternative was in place for a long time and is what "scrolling down pulls
+me back" turned out to be. The settle loop reads `scrollTop` from the DOM; a
+commit opens a window on almost every frame; the scroll event carrying the
+reader's travel is delivered after all of that. So a correction routinely runs
+against a reading position agreed hundreds of pixels ago, with no capture in
+between, and reads their own scrolling as drift. Measured over one reproduction,
+ten corrections: **every one of them was the reader's travel**, the largest
+putting a 508px scroll back where it started while the transcript had really
+moved 7.8px.
+
+Note what this does *not* weaken. A displacement contributes nothing to
+`scrollTop`, so taking the movement out never takes any of the repair with it —
+when the reader has not moved, the correction is what it always was.
+
+**The offset and the viewport position it was agreed at are two halves of one
+fact, and every writer moves both.** That is the invariant, and it is the whole
+of why the movement is taken *into* the anchor at the top of a restore rather
+than subtracted inside the correction. Subtracting it leaves the two halves free
+to drift apart: a frame with nothing to correct advanced only the position, and
+the reader's travel became a debt the next frame collected. Measured, with the
+subtraction in place: a 32px scroll and an 81px scroll each reported back a
+frame later as a correction of exactly itself, the anchored Turn provably not
+having moved. Worse, the subtraction made that frame the *ordinary* outcome —
+with the movement taken out, a frame in which only the reader moved corrects by
+exactly zero.
+
+There is one movement of `scrollTop` that must not be taken into the offset, and
+it is the repair itself: the shift puts the Turn back at the stored offset, so
+the position advances by the correction and the offset stays.
+
+The baseline is therefore carried, not re-taken. It used to be re-set to the
+current position every time a settle window opened, on the grounds that the
+prepend compensation had written from the layout effect just before and that
+write is not the reader — which was true of the compensation and false of
+everything else the reset swallowed, the reader's own travel first among them.
+The compensation now says so itself, through `absorbViewportShift`: it is the
+one movement made on the anchor's behalf, so it is the one that must not count
+as somebody moving the viewport.
+
+**The anchor must be a Turn the reader can see, at both edges.** A Turn's marker
+is its user message, which is short, so a reader inside an answer taller than
+the viewport has no marker on screen — and "the first marker below the top
+edge" then answers with the *next* Turn, however far down it is. Measured: an
+anchor held at an offset of 1695.5px in a scroller at most 1325.7px tall, at
+least 370px past the bottom edge.
+
+The two directions are not symmetrical, which is why the bottom edge is a bound
+and not a preference. Content above the viewport re-measuring moves everything
+below it, the on-screen transcript included, so a marker above the fold is a
+faithful proxy for what the reader sees. Content *below* the viewport
+re-measuring moves nothing they can see — so a marker down there reports
+movement that never reached the screen, and correcting to it **creates** a
+displacement instead of repairing one. No anchor is the honest answer, and it is
+what this already gave once every marker had gone off the top.
+
+**A navigation replaces the reading position; it does not displace it.** Standing
+down for the register is not enough — that postpones the correction for the
+length of the hold and no longer. A Turn navigation therefore drops the anchor
+outright before it aims, and the settle window opened by the commit that renders
+the placement takes the new one. Measured over four clicks on one Turn: the aim
+placed the viewport at 287px each time, and each time the anchor put it back
+1653px away on the first frame after `ONE_SHOT_NAVIGATION_HOLD_MS` lapsed, still
+anchored to the Turn the reader had jumped away from. The re-capture cannot
+happen in the aim's own task: the target is commonly outside the rendered window
+when the aim is issued, so reading the DOM there anchors to whatever the reader
+was moved off.
+
+**Restoring needs a window, not a callback.** A prepend settles over several
+frames — a margin holds the position, the real heights land in padding, then the
+margin is released — and *a margin change fires no ResizeObserver at all*, so no
+single callback covers it. Every signal that the transcript moved therefore
+opens `ANCHOR_SETTLE_FRAMES`, and a frame that had to correct refreshes it — as
+does one still waiting for the anchored Turn to be rendered, since "not there
+yet" is neither a repair nor a failure. Without that, the settle outlasts the
+wait only for as long as `ANCHOR_SETTLE_FRAMES` and
+`ANCHOR_MISSING_TURN_ATTEMPTS` happen to be the same number, which is a
+coincidence and not a design. Measured before the window existed: four
+consecutive painted frames displaced by 896px.
+
+The observer feeding this had to be repointed. `scrollerRef.firstElementChild`
+is a viewport-sized box that stays at the scroller's height no matter how much
+transcript there is — it never reported a content change at all, despite a
+comment claiming it watched content. The item list is the element that grows,
+and `border-box` is required because the virtualizer parks item space in
+padding.
+
+**The keeper does not know there is a virtualizer.** It lives in
+`flowChatViewportAnchor.ts` (geometry and the DOM contract for the anchor
+element) and `useFlowChatViewportAnchor.ts` (capture, restore, and the settle
+window), and it talks to a scroller element and the Turns rendered inside it and
+to nothing else. That is what let the virtualizer underneath it be replaced
+without the keeper changing at all.
+
+One consequence of the refresh rule is worth stating plainly: a frame that finds
+the anchor already in place consumes the remaining settle budget rather than
+refreshing it. The cost is a `querySelectorAll` and two rect reads per frame for
+the bounded settle window. A correction or a Turn still waiting to render
+refreshes the window, while a stable anchor winds it down and another owner
+holding the viewport still stands it down.
+
+The anchor is skipped entirely while follow-output owns the viewport. Restoring
+a pre-prepend position is only meaningful when the user owns it — and a frame
+spent standing down is *not* evidence the settle is still running. It looked at
+nothing. The loop used to refresh on the missing-Turn count instead, which is a
+fact about the last frame that did look, and that count can only advance on a
+frame that does not stand down: the same condition jammed the loop and put its
+only exit out of reach. Measured at the tail after a jump-to-latest, where
+follow-output does not release because resting there is what it is for: 27
+seconds of `anchor.stoodDown`, one per frame, zero travel, ending only when the
+reader scrolled. The wait it reported for that — `waitedFrames: 6609`,
+`waitedForMs: 28116`, against 20 attempts — was of a reading position that had
+been correct the whole time.
+
+So the outcome of a restore is five-valued inside the loop, not a boolean.
+`false` covers a stand-down, a Turn not rendered yet, and no anchor at all, and
+the loop has to treat those differently; the public `restoreAnchor` still
+answers the only question its other callers ask.
+
+**What the anchor cannot fix on its own** is a scroll range that was wrong to
+begin with. Holding the reading position across a burst of measurement is worth
+nothing if the burst blocks the main thread for 295ms. That is a property of how
+unmeasured items are reserved, not of the anchor, and it is why the virtualizer
+underneath it takes a per-item estimate.
+
+## The Ask Is Derived From the Transcript, Not From the Window
+
+**A page asks for what lies past the transcript on screen.** Those are the same
+range only until the continuous projection splices a window starting at ordinal
+0 with the live tail: the rendered transcript then runs to the newest Turn while
+the store's window still ends where it was paged in. `resolveHistoryBoundaryTarget`
+therefore takes the *rendered* range, and the store's window stays what the
+extension below operates on.
+
+Deriving the ask from the store's window instead asks to load a Turn that is
+already on screen. Measured, in a live session: a window paged in from the tail
+ended at ordinal 6 while the session had grown to 10, so the reader was sitting
+on the newest output with a `history-window` presentation behind it. Reaching
+the bottom asked for ordinal 6 — which the *turn catalog* could not resolve
+either, because it still held the six entries it was built with. 266 asks, every
+one answered `not-found`, none of them recorded, and a boundary status the
+reader was shown as history being prepared for a transcript that was already
+complete.
+
+Three things had to be true for that to reach a reader, and each is fixed where
+it belongs:
+
+- The ask used the wrong range. That is the bug; the rest is how it stayed
+  visible.
+- **`reached-latest` is not `beyond-known-total`.** Asking past the newest Turn
+  is what the bottom edge of a live transcript answers every time the reader
+  arrives at it, and it must not raise the missing-history alarm. Asking past
+  the known total going *backwards* still does.
+- **A load that fails records an outcome.** `not-ready` and the superseded
+  cancel both returned silently, which is why the trail held 266 asks and no
+  answers at all. The cancel also left the boundary status reading `loading`
+  forever; the status is ours to clear even when the load was not ours to
+  finish.
+
+The status the reader sees is separate again, and is in
+`FLOWCHAT_SCROLL_STABILITY.md`'s footer contract only insofar as the sentinel
+lives there: **a boundary in `error` must not be labelled as one in
+`loading`.** Both ends now pick their label by state. One label for both is why
+a permanent failure read as permanent progress, and why cancelling the Turn did
+not clear it — nothing about the Turn was ever involved.
+
+## Reading History Is About the Transcript, Not the Intent
+
+`viewportMode: 'history-reading'` does two things — it suppresses streaming
+follow, and it pins the jump-to-latest bar open and routes it through a
+presentation reset. Both are asking one question: **does the transcript on
+screen still reach the newest Turn?**
+
+A turn-navigation viewport intent used to answer that faithfully, because turn
+navigation was the only thing that activated a history window. It is not any
+more. A session whose loaded tail is shorter than the viewport pages older Turns
+in the moment it opens, with nobody navigating, and the first paging step has to
+set a turn intent — `isShowingHistoryPresentation` requires one, so without it
+the paged-in Turns would not render at all. The viewport sitting on the newest
+output was therefore reported as reading history: the bar was visible from the
+moment the session opened, clicking it dropped the window and paged it straight
+back in, and streaming output was not followed at all.
+
+`flowChatLiveTailWindow.ts` answers it from the window's own ordinals instead.
+These are ledger numbers, not measurements — the rule against inferring intent
+from geometry is about ambiguous quantities like `scrollTop`, and does not
+apply. The answer also keeps up on its own: a Turn arriving past the end of the
+window flips it back with no help, where a flag recorded at activation time
+would go stale and leave no way to the live tail.
+
+`isReadingTurnViewport` keeps its old meaning for the auto-tail placement, which
+asks a third question again — who owns the viewport. Merging those two is the
+mistake this separates.
+
+**A tail-anchored window must grow with the session.** It stops at the newest
+Turn that existed when it was cut, and nothing moves its end afterwards, so an
+appended Turn is simply not rendered. That is worse than it sounds: `latestTurnId`
+is read off the rendered items, so follow-output never learns the Turn exists —
+no pin, no follow, and nothing to scroll to. `resolveTailWindowGrowth` is
+level-triggered for that reason. An edge — "it reached the tail last render and
+does not now" — is consumed whether or not the extension succeeded, stranding
+the window permanently on one failure; the current state stays `'extend'` until
+the window is actually repaired. A window the user navigated to has a different
+end, so the session growing says nothing about it and it is left alone. When the
+store cannot extend far enough, the fallback drops back to the canonical tail:
+that costs a visible re-page of the history above, which is why it is the
+fallback, but it is the only branch that always shows the message just sent.
+
+## A New Turn Is a Fact About the Session
+
+`latestTurnId` comes from `activeSession.dialogTurns`, never from
+`virtualItems.at(-1)`. The projection answers where the presentation currently
+*ends*, and a history window re-cut moves that to a Turn which has existed for
+hours: measured, navigating to Turn 2 landed correctly and was then overwritten
+twice, because each window loaded on the way ended somewhere new and each of
+those read as a submission, pinning the window's last Turn to the top.
+
+**Whether the Turn can be acted on is a second question, and it does not belong
+in the identity.** Qualifying `latestTurnId` by "and it is on screen" makes a
+Turn that merely came into view look new — the same bug with the opposite sign,
+and it is how navigating to Turn 29 ended on Turn 38.
+
+**An arrival is not a change.** Getting the identity right does not settle how
+to *detect* one, and the detector asked whether `latestTurnId` differed from
+last render. A rollback truncates `dialogTurns`, which moves that identity
+backwards onto a Turn that has been there all along — so undoing a message
+pinned the Turn *before* it to the viewport top. `dialogTurnCount` separates the
+two: an arrival grows the ledger, and nothing else that rewrites `dialogTurns`
+— a history page merging in above, a window re-cut, a hydration — moves the
+last Turn at all, so requiring growth costs nothing and excludes every
+truncation.
+
+**A rollback then says where to land, because the ledger cannot.** A shorter
+`dialogTurns` is also what a window re-cut and a hydration merge look like, and
+two dozen call sites write that array; inferring an action from its size is the
+same mistake as inferring intent from `scrollTop`. So the rollback announces
+itself through `FLOWCHAT_TURNS_ROLLED_BACK_EVENT`, exactly as a submission does,
+and the transcript settles on the new tail — the Turn it was pinning is one of
+the ones that stopped existing.
+
+It takes the viewport whether or not follow owned it. A rollback at Turn N
+removes N *and everything after
+it*, and the reader had N on screen — they clicked its own button. So the new
+tail is always within a Turn of where they already are, and there is no history
+below them to be pulled out of. Gating it on ownership instead — the first
+attempt — made it dead code in the case it was written for: reaching a Turn far
+enough up to want it gone means scrolling, and scrolling is what hands the
+viewport back to the reader. The viewport anchor then answered instead, and
+answered a different question: it holds the reader's Turn at its offset from the
+viewport top, so an 8-Turn session rolled back at Turn 7 came to rest showing
+Turns 2..6, with the new last Turn's answer below the fold. Nothing was wrong
+with the anchor. It was the only thing still running.
+
+The event fires a frame after the truncation, because the answer is a scroll to
+the end of *real content* and that has to be read from a DOM the truncation has
+already been committed to. Edit-and-rerun does not announce: its truncation is
+followed by a rerun whose Turn really is new, and announcing would spend a
+visible movement on the way to it.
+
+So the response carries it instead. A new Turn is answered by pinning it to the
+viewport top; until it is in the transcript on screen there is nothing to align,
+and the fallback — the end of real content — is not a stand-in, because it
+would leave the Turn unpinned or pull a reader out of a history window. The
+answer is therefore **deferred, not dropped**: held in `pendingNewTurnIdRef` and
+retried when the transcript next changes, which is exactly when the presentation
+is restored to the live tail.
+
+**Submitting is what gives up a navigated window.** `resolveTailWindowGrowth`
+leaves such a window alone as the session grows, and that is right — a Turn
+arriving from anywhere else must not take a reader out of the history they are
+in. Nothing in the ledger separates that from a Turn the reader sent themselves,
+so the composer says so directly: `useMessageSender` announces
+`FLOWCHAT_MESSAGE_SUBMITTED_EVENT`, and the container gives up the window only
+when the transcript does not already reach the latest Turn. Measured before it
+existed: a message sent while parked on the first Turn left the transcript on a
+24-item window it was never in, with follow-output holding an answer it had
+nothing to align.
+
+## Diagnosing History Paging
+
+Older Turns are paged in when the viewport reaches the head of the loaded
+window. Every way that handshake can fail is **silent and identical in the UI**:
+the boundary status returns to `idle` and no indicator is shown, so "declined to
+load" is indistinguishable from "there is no more history". The failure is also
+intermittent, so it is traced permanently rather than reproduced on demand.
+
+`historySessionDiagnostics` keeps a per-session ring buffer shared with the
+hydration timeline, and the two log channels carry different things:
+
+| | `flowchat.log` | `webview.log` |
+|---|---|---|
+| carries | the full paging step stream | the refusal alarm + its trail |
+| enabled by | `app.logging.flow_chat_diagnostics` | always on |
+| written via | `flowChatDiagnostics.trace` | `log.warn` |
+
+The in-memory trail is kept regardless of the flag, so
+`warnHistoryPagingRefusedWithPendingTurns` is **self-sufficient** — the recent
+events travel with the warning and no one has to reproduce the fault with
+diagnostics turned on first. It warns once per session, so scrolling against a
+dead boundary cannot flood the log. Turn the flag on only when the trail's
+30-event cap is not enough.
+
+Two detectors raise it:
+
+- `exhausted` returned for `beyond-known-total`. That result **latches the
+  direction off for the rest of the session** and only `applied` clears it, so
+  reaching it on an unknown or contradictory total is how history goes
+  permanently missing rather than merely late.
+- A `before` request blocked by that latch while the session is still
+  `isPartial`. This fires at the moment the user scrolls up and nothing happens.
+
+When the report is "scrolling up shows no history, but the Turn Rail can still
+load those Turns", search the log for `declined to page older Turns`. Turn Rail
+navigation goes through `loadSessionTurnWindow` directly and bypasses the
+boundary latch entirely, which is why it keeps working. The accompanying
+`FlowChat history paging trail` warning carries the preceding events, including
+`anchor_capture_failed` — `captureHistoryPrependAnchor` returning `false`
+cancels a window that was already fetched.
+
+The viewport side of the same junction is traced separately; see *Diagnosing the
+Viewport* in `FLOWCHAT_VIEWPORT_REGISTER.md`, and in particular the pair of
+numbers that separates "the compensation overshot" from "the transcript
+re-measured".
+
+## Related Files
+
+- `flowChatHistoryBoundary.ts`
+- `flowChatViewportAnchor.ts`
+- `useFlowChatViewportAnchor.ts`
+- `flowChatLiveTailWindow.ts`
+- `VirtualMessageList.tsx`
+- `ModernFlowChatContainer.tsx`
diff --git a/src/web-ui/src/flow_chat/components/modern/FLOWCHAT_SCROLL_STABILITY.md b/src/web-ui/src/flow_chat/components/modern/FLOWCHAT_SCROLL_STABILITY.md
index 4aefe19c57..02df97a4f9 100644
--- a/src/web-ui/src/flow_chat/components/modern/FLOWCHAT_SCROLL_STABILITY.md
+++ b/src/web-ui/src/flow_chat/components/modern/FLOWCHAT_SCROLL_STABILITY.md
@@ -1,788 +1,577 @@
 # FlowChat Scroll Stability
 
-This document explains the scroll-stability mechanism used by `VirtualMessageList.tsx`.
-
-## Rule Zero: Do Not Create Motion For This Mechanism To Chase
-
-Every rule below is compensation for content that changes size on its own. The
-cheapest way to keep the pane stable is to not generate the movement in the
-first place. Five invariants hold across the message list, and breaking any of
-them reintroduces the "the chat keeps refreshing itself" report:
-
-1. **Keep a live action's top-level projection identity stable.** A rendered
-   `ModelRound` remains one `model-round` virtual item, and an explore-only
-   round remains one `explore-group` virtual item with a stable key. Within a
-   `ModelRound`, an active collapsible tool is intentionally kept as a critical
-   item; after it settles it may join the surrounding explore grouping. That
-   inner grouping transition must not split the round into multiple virtual
-   items or replace the item/round keys, which would unmount the card and look
-   like a flash. Likewise, never hide the old location with `display: none` as
-   a handoff mechanism.
-2. **No mount-triggered animation on anything the list renders.** The list is
-   virtualized: an item that scrolls out of view unmounts and remounts, so a
-   `fadeIn` / `slideInUp` keyed off mount replays on every pass. Same for an
-   animation keyed off `--streaming` → `--complete`: it replays when the
-   typewriter drains. `getModelRoundItemClassName` deliberately has no `--enter`
-   modifier, and `.user-message-item` deliberately has no enter animation.
-3. **Keep wall-clock state out of projection and grouping.**
-   `sessionToVirtualItems` and `buildModelRoundItemGroups` remain pure
-   functions of session data. A timer must not reclassify a round, change a
-   `VirtualItem` key, or create a recently-completed projection. The card layer
-   does have a bounded completion-preview timer (documented below), but it only
-   changes local expanded state after the card is already rendered; it does not
-   restructure the virtual list.
-4. **Do not compact a live tail in the same completion commit.** The execution
-   and file-operation cards use a short completion-preview grace period while
-   they remain the expanded tail. A newer item still collapses them immediately;
-   if no newer item arrives, they compact after the grace period. Task,
-   question, thinking, and explore-group components retain their own
-   status/last-item policies and are not implicitly covered by this timer. When
-   an automatic collapse starts, it **may animate** for
-   `FLOWCHAT_COLLAPSE_DURATION_MS` (300ms) as long as
-   `flowchat:tool-card-collapse-intent` stays active for that full window plus
-   settle frames. Instant collapse is reserved for `prefers-reduced-motion` or
-   an explicit `disableAnimation` opt-out. Height, opacity, and transform must
-   share one duration (see `flowChatCollapseMotion.ts` /
-   `SmoothHeightCollapse`). Do not hard-swap `BaseToolCard` ↔ `CompactToolCard`
-   for expand/collapse — that remounts the body with no height transition.
-5. **Keep the leading edge stable across collapse states.** A revealed body
-   must not add `margin-inline-start`, `padding-inline-start`, or an equivalent
-   left offset relative to its collapsed header. Expanded thinking, explore
-   rows, tool details, image previews, and subagent projections all begin on
-   their owning message/card edge. Vertical and trailing-edge spacing may
-   remain, but a leading inset reads as a horizontal jump during collapse.
-
-A sixth, related rule lives in `useTypewriter`: `replayOnMount` defaults to
-false, so a still-streaming block that remounts continues from its current text
-instead of resetting to an empty string and re-growing.
-
-Read this before changing any of the following:
-
-- footer height / footer rendering in `VirtualMessageList.tsx`
-- scroll compensation state or refs
-- semantic anchor lifetime and one-shot fallback restoration
-- `ResizeObserver` / `MutationObserver` / transition listeners
-- `flowchat:tool-card-collapse-intent`
-- `tool-card-toggle`
-- `overflow-anchor` styles in `VirtualMessageList.scss`
-
-## Problem
-
-FlowChat uses `react-virtuoso` for virtualization. When the user is already at or near the bottom, collapsing content near the end of the list can shrink total content height.
-
-Without compensation, the browser clamps `scrollTop` downward immediately because the previous bottom position no longer exists. That causes the visible header/content above to drop.
-
-If we compensate too late, the user sees a flash:
-
-1. browser clamps `scrollTop`
-2. code restores `scrollTop`
-3. header appears to drop and jump back
-
-If we restore without enough compensation, the final position is still wrong.
-
-The goal of this mechanism is:
-
-- keep the visible header/content vertically stable
-- allow temporary invisible blank space at the bottom
-- avoid the collapse flash
-
-## High-Level Strategy
-
-The fix is a two-stage approach:
-
-1. Pre-compensate before a known collapse starts.
-2. Reconcile with the real measured height delta after layout updates.
-
-This prevents the "drop first, restore later" behavior while still using the actual measured shrink amount to settle on the correct final compensation.
-
-## Core Building Blocks
-
-## 1. Bottom Reservations
-
-The footer uses a unified bottom-reservation model. Each reservation contributes
-temporary tail space, but keeps its own semantics:
-
-- `collapse`: shrink protection for height loss near the bottom
-- `pin`: viewport positioning space for "pin turn to top" navigation
-
-The rendered footer height is the sum of all active reservations.
-
-A non-zero `collapse` reservation must have an explicit semantic owner: an
-active or retained tool collapse, input-stack shrink, preserved-element range,
-late-shrink clamp, or protected-range transfer from a pin. Ordinary Virtuoso
-measurement convergence has no such owner. An idle measurement with no owner
-must only rebase the measured height and must never create Footer space from a
-negative `scrollHeight` delta alone.
-
-Reservation state is ref-owned first and mirrored into React state. A Virtuoso
-Footer remount must synchronously read the ref-owned value; otherwise one stale
-React commit can remove exactly the reserved scroll range for a frame.
-
-The Virtuoso Footer does not receive reservation pixels through React context.
-Its stable DOM node is updated imperatively, and its ref callback restores the
-current ref-owned height on mount. This keeps reservation updates from causing
-an additional measurement-sensitive Virtuoso render.
-
-Important details:
-
-- the real footer height is `MESSAGE_LIST_FOOTER_HEIGHT + totalBottomReservationPx`
-- reservation space is not real content height
-- reservations may define a `floorPx`
-- a floor prevents unrelated shrink reconciliation from dropping live scroll range
-- collapse floors still drain from measured content growth or deliberate downward
-  user navigation; pin floors drain only through the sticky-pin settlement path
-- all measurements that compare old vs new content height must use:
-
-```ts
-effectiveScrollHeight = scroller.scrollHeight - getTotalBottomCompensationPx()
+FlowChat reserves a resident tail spacer below the transcript, and pairs it with
+a follow target that does not move backwards for free. Together these give a
+newly submitted Turn a top-aligned position and keep a tool-card collapse from
+dragging earlier content down.
+
+That is this document. Four siblings carry the rest.
+
+## Which Document
+
+| Changing | Read |
+|---|---|
+| the tail spacer, the follow target, pinning, holding, resizing, the footer | this file |
+| history paging, the prepend, the viewport anchor, history presentation | `FLOWCHAT_HISTORY_PAGING.md` |
+| anything that writes `scrollTop`, one-shot navigation, the diagnostic trail | `FLOWCHAT_VIEWPORT_REGISTER.md` |
+| the virtualizer, item measurement, item keys, anything a row renders | `FLOWCHAT_VIRTUALIZATION.md` |
+| what to run before claiming it works | `FLOWCHAT_VERIFICATION.md` |
+
+*Known Gaps* below is the whole list for all five — accepted defects are easier
+to keep in one place than to hunt for.
+
+## The Rule That Matters
+
+**Static reservation is allowed. Reactive compensation is not.**
+
+The tail spacer's height is a function of the viewport and the input-stack
+inset. It must never be derived from a measured content height, a collapse
+delta, an animation duration, or a streaming rate. The moment its height reacts
+to content, it stops being a reservation and becomes the compensation engine
+that was removed in "remove synthetic tail-space scrolling" — do not rebuild
+that under a new name.
+
+## How Much To Reserve
+
+The spacer keeps two offsets inside the scroll range, and is the larger of what
+they need. Both are bounds, not estimates: reserving more than the larger one is
+pure blank at the end of the scroll range, and reserving less than either is a
+clamp.
+
+- **A pinned Turn.** Worst case its user message is the newest item with nothing
+  answering it yet, so the message, the input inset and the spacer are all that
+  lie below the message top. `clientHeight - bottomInsetPx -
+  PINNED_TURN_MIN_ITEM_HEIGHT_PX` is exactly enough to put it on the top edge.
+- **A held collapse gap.** `hold-tail` parks up to `tailHoldMaxGapPx` past the
+  content end, and an offset the browser clamps is one the hold rule does not
+  actually get to hold.
+
+`PINNED_TURN_MIN_ITEM_HEIGHT_PX` must stay an **under**estimate of a
+user-message item. Too low costs a few spare pixels of blank; too high puts the
+pinned offset past the end of the scroll range, and the Turn is clamped back
+down from the viewport top while the follow loop rewrites the clamped offset
+every frame.
+
+While the pin reserve is the binding bound, the spacer and the footer sum to a
+constant: growing the composer moves the content end without moving the end of
+the scroll range. Under the hold-gap floor the spacer stops tracking the inset
+and the range grows with the composer, exactly as it did when the spacer was a
+flat viewport.
+
+## Why Both Halves Are Required
+
+The spacer alone fixes nothing. It only removes the browser's forced `scrollTop`
+clamp when content shrinks, which is *permission* to hold position. A follow
+target that re-aligns the content end to the viewport bottom every frame will
+still drag earlier content down by the collapse delta, spacer or not.
+
+`flowChatTailFollow.ts` supplies the second half:
+
+- `pin-turn-top` holds a freshly submitted Turn's user message at the viewport
+  top while its answer is shorter than one viewport, then hands off at the
+  crossover. The blank below a pinned Turn is the mode, not a defect.
+- `hold-tail` keeps its previous offset when content shrinks, and gives ground
+  only once the blank below the live output exceeds `tailHoldMaxGapPx`
+  (a share of the viewport, not a measured delta).
+
+Both are pure functions over geometry. They hold no timers and observe no
+mutation.
+
+`useFlowChatFollowOutput` is the only continuous outer viewport writer. Three
+things about how it runs are load-bearing:
+
+- **`scheduleFollowToLatest` re-asserts ownership after a layout change but does
+  not force the content end.** A collapse resizes content too, and the hold rule
+  is what keeps that from moving the viewport.
+- **The pinned Turn's offset is re-resolved from live layout every frame.**
+  Items above it are estimates until they are measured, so a cached absolute
+  offset would drift.
+- **When streaming stops, `hold-tail` settles any remaining blank with one
+  smooth scroll.** A pinned Turn does not settle.
+
+`tailHoldMaxGapPx` is a **streaming allowance**. Blank below the live output is
+tolerable only because more output is about to fill it. Do not reuse it to
+absorb anything else — applied to a foreign forward move it parks the content
+end mid-viewport permanently, since nothing pulls the target back down.
+
+## Opening a Session
+
+A session mounts against an unsettled transcript: item heights are still
+estimates, and an `isPartial` session pages older Turns in for hundreds of
+milliseconds. The end of content can travel thousands of pixels after the first
+alignment, so opening is its own phase with its own rules.
+
+**While opening, the transcript is hidden and the follow target is
+authoritative.** It tracks the content end exactly — no remembered offset, no
+gap tolerance, and no accommodation of a foreign `scrollTop` write. The
+virtualizer writes during this window too, as items measure and it corrects for
+the ones above the viewport; fighting it is invisible because nothing is
+painted, and accommodating it would be permanent once paging stops.
+
+Nothing places the opening viewport by aligning to an item. The end of *real
+content* is above the resident tail spacer, and no item knows where that is, so
+the follow target writes the offset and the reveal waits for it.
+
+Session open enters follow-output as `session-open`, even with nothing
+streaming. The frame loop then runs on a `SETTLE_FRAMES` budget that refreshes
+whenever the target actually moves, so it tracks measurement and paging and then
+goes quiet. Without it nothing owns the viewport after the one-shot alignment,
+and the transcript strands wherever that early shot landed. `scrollToTurnEnd`
+deliberately does **not** exit follow-output for the same reason: it is the
+session-open placement and wants the same position the settle is converging on,
+and releasing ownership there hands the viewport back to nobody.
+
+**After the reveal, the follow target is cooperative.** The gap tolerance
+applies again, because from then on a shrinking content end means a card
+collapsed, not that measurement is still catching up.
+
+The reveal waits for a *semantic* signal — the last virtual item rendered with
+its end inside the viewport, plus the viewport in position — not for geometry to
+stop changing. Before the virtualizer renders anything, `scrollHeight` and the
+end sit unchanged at their unmeasured values, which is indistinguishable from
+having finished; a stability test reveals on frame 3 and shows the whole settle.
+
+## User-Controlled Reserved Blank
+
+The spacer is a full viewport the user can scroll into. Once a reader exits
+follow-output, their own scroll position is preserved even when it lands in the
+blank. There is no `scrollend` correction or quiet-period fallback that takes
+the viewport back. Explicit actions such as opening a session, submitting a new
+Turn, navigating a Turn, rolling back, or choosing jump-to-latest remain the
+ways to re-enter follow-output.
+
+The remaining follow rules carry the live-tail design:
+
+**The target is the follow target, never the content end.** A short new Turn is
+pinned above the content end, so aiming at the content end would scroll *up*
+and shove the message the user just sent into the middle of the viewport. A
+held collapse gap is likewise a legitimate offset up to `tailHoldMaxGapPx` past
+the content end; judged against the content end it would read as an overshoot
+and fight the hold rule on every collapse. `memorylessFollowState` computes the
+target from live geometry with no remembered offset, because the offset the hold
+rule was protecting stopped being meaningful the moment the user took over.
+
+The pin's *identity* therefore outlives a user takeover; only its *activity*
+stops. Three things retire a pin: the crossover to `hold-tail`, a newer Turn,
+and a session change. The crossover has to be one-way — a collapse can pull
+content back under one viewport, and re-pinning there would jump the viewport
+backwards. Since nothing re-pins a Turn whose identity was dropped, that is
+automatic.
+
+**Where a jump to latest lands.** Every entry into follow-output resumes at the
+end of real content, with one exception: a jump to latest while the **newest**
+Turn is still pinned returns to the pin. That mode only holds while the Turn's
+answer is shorter than one viewport, so everything it has produced is already on
+screen, and aiming at the content end would scroll *up* and shove the message
+the user just sent into the middle. The exemption therefore outlives the Turn:
+a short Turn stays pinned until a newer one replaces it.
+
+## Output Catching Up With a Reader in the Blank
+
+This watch covers the reader who scrolled up out of the tail but is still
+looking at reserved blank, and whom output then overtakes.
+
+Scrolling up gives the follow away permanently, and that is right only for a
+reader who left the live region. A small scroll up may not have. The blank is up
+to `tailHoldMaxGapPx` under `hold-tail` and the whole gap under a pinned Turn,
+so the reader can be a few hundred pixels off the tail with nothing hidden from
+them at all — until output grows past the bottom edge, and they silently stop
+seeing it with no affordance saying so.
+
+So a watch runs for as long as the reader holds the viewport — from the scroll
+that took it to whatever hands it back. `scrollTop > contentEnd` is the
+predicate for "the blank is on screen". The watch keeps one bit between
+samples: whether the blank was on screen at the previous one. A crossing is that
+bit going from set to clear, and which side moved decides who keeps the viewport
+(`resolveTailDepartureCrossing`):
+
+- **`content-caught-up`** — the content end rose further than the reader moved.
+  Output filled the space under someone who was standing still, so follow takes
+  the viewport back.
+- **`reader-left-blank`** — the reader moved further than the content end rose.
+  They went to read history, and are left alone. The latch clears, so nothing
+  asks again until they put the blank back on screen themselves.
+
+A crossing does **not** end the watch. Scoping it to one was tried and is wrong:
+a reader who climbs out of the blank, reads for a while and scrolls back down to
+sit in it again is in exactly the position the rule exists for, and had already
+spent the single crossing they were given. The watch also opens on any exit that
+finds none open, not only the one that took the follow — every wheel notch
+exits, and only the first of them finds anything to give up.
+
+Streaming does not stop because the reader scrolled, so both sides usually move
+between samples and the tie-break above is doing real work. Two guards keep it
+honest:
+
+**A live gesture vetoes the resume.** Measured over one session's twenty
+departures: nine left blank on screen, and two of those ended `content-caught-up`
+— one a reader who had been still for 1.6s and was overtaken, one 320ms into a
+live gesture with the reader climbing 200px while content grew 237. The
+tie-break called the second for the content, correctly, and acting on it would
+have taken the viewport back mid-scroll. `user-gesture` on the register
+separates them, because a wheel claim lapses `USER_DRIVEN_SCROLL_WINDOW_MS`
+after the last notch and notches arrive faster than that. A veto *defers* the
+crossing rather than settling it — the latch stays set, so the next sample
+judges the same transition again: a reader who carries on climbing out-moves the
+content and is let go by a verdict that never needed the veto, and one who has
+stopped is followed as soon as the claim lapses.
+
+**Geometry read from two moments is not geometry.** `scrollTop` is clamped to
+`scrollHeight - clientHeight`, so no settled viewport is more than the spacer
+past the content end (`isTailBlankMeasurable`). A larger reading means the
+transcript is mid-restructure: a history prepend shifts the viewport by the
+height it inserted before that height is in the scroll range, and the blank
+between the two reads as thousands of pixels. Measured on a session that paged
+its whole history on the first scroll up — 14252px of shift against a content
+end still reading 989, a blank of 6239px. Read at face value that is a reader
+deep in the blank, which is the one state this acts on, so the next sample would
+have pulled them out of the history they had just asked for. Such a sample takes
+no verdict and does not touch the latch: a restructure says nothing about where
+the reader was standing before it.
+
+Resuming does not scroll. The blank closing *is* the two offsets meeting, so
+what remains is one sample of growth, and the follow loop's ease covers it; a
+one-shot scroll here would be a snap the reader can see for a correction they
+cannot. It also retires the pin, even when the departure happened under one: the
+pin's reservation is the blank the reader just scrolled out of, and restoring it
+would pull them back down to the offset they left.
+
+The whole watch is a ref. `followOutput.tailWatch` and
+`followOutput.tailWatchEnded` bracket it — the second carrying `crossings`, so a
+watch that never resolved anything can be told from one that resolved against
+the reader — and `followOutput.tailCrossing` records each transition with its
+verdict, both raw deltas, and whether a gesture was live.
+
+## The Follow Eases Its Write, Never Its Target
+
+The follow target moves when the transcript reflows, and Markdown reflows a
+line at a time. A loop that assigns the target outright therefore spends 24px
+on one frame out of seven and nothing on the other six, which is what a reader
+reports as the output jumping rather than scrolling. `flowChatTailEase.ts`
+spends the same distance over all seven.
+
+It buys latency, not speed. Under steady growth the eased offset settles where
+its per-frame catch-up equals the growth, so the visible step converges on *the
+content's growth per frame* whatever the fraction is; smoothing spreads a lumpy
+motion evenly across frames it already had. What `TAIL_EASE_ALPHA` actually
+sets is how far behind the tail the offset rides, and that lag is what has to be
+given back when the stream stops.
+
+**Only the write is eased.** `followStateRef` still holds the offset the rule
+owns, so the settle budget and the at-tail band both keep reading
+a target rather than a position in transit. An ease that leaked into the target
+would make every one of them chase the lag.
+
+Four boundaries, and none of them is a matter of taste:
+
+- **Past `TAIL_EASE_SNAP_ABOVE_PX` it jumps.** The first frame of an ease covers
+  a quarter of the distance, so beyond four lines the ease's *opening step* is
+  already bigger than the jump it set out to replace.
+- **A target above the current offset is never eased.** That is content getting
+  shorter — a card collapsing, a table reflowing — and easing down through it
+  reads as the transcript being clawed backwards.
+- **Not while the transcript is opening.** There the target is authoritative and
+  nothing is painted, so an ease is travel nobody can see, holding open the one
+  phase whose whole point is to end. The reveal is watching for the viewport to
+  reach the content end.
+- **An ease in flight keeps the loop alive.** The settle budget is refreshed by
+  the *target* travelling, so without this a correction arriving on the last
+  budgeted frame would be abandoned partway. It terminates on its own: the ease
+  halves what is left every frame, and a write the register refuses moves
+  nothing and so books no further frame.
+
+A step of the list's own scroll offset changes no layout, and the worry that it
+would still be charged for — the virtualizer re-windows from the scroll events
+it produces, and each one is also an anchor carry and a visible-Turn pass — did
+not show up in the measurement. Over 1580 steps and 8435px of following, list
+commits held between 15/s and 28/s while the step rate varied from 29/s to
+119/s, so the cost per step *falls* as the follow gets busier. The two highest
+commit rates in the session, 46/s and 51/s, were windows where the list follow
+took no step at all and a thinking card was growing instead. Commits track
+content changing height, which is also what moves the follow target, and the
++0.80 correlation between the two is that shared cause rather than a price.
+
+What the ease actually did, over the same run: no step over a line that was not
+a deliberate snap, 99% of steps under 12px, 67% under 4px, and every window's
+largest step exactly `TAIL_EASE_ALPHA` of its largest lag — 0.242 to 0.261
+against a nominal 0.25, which is also the evidence that nothing else was
+writing the viewport in between.
+
+"At bottom" is a band, not a point: from the end of real content down to
+whatever the follow rule owns. A pinned Turn and a held collapse gap are both
+inside it, so neither raises the jump-to-latest affordance; the reserved blank
+is outside it, so parking there does. No virtualizer-reported "at bottom" can
+express this: the end of the scroll range is the bottom of the reserved blank,
+not the end of content.
+
+The band is recomputed on scroll, on resize, **and when follow ownership
+changes** — its lower edge is the follow target, which can move while the
+viewport is perfectly still. A jump to latest that lands on a pin the viewport
+already sits on writes
+nothing at all. Driving the band from scroll events alone left the affordance
+visible over a viewport that was at the tail, and clicking it then had nothing
+to do — an inert button is worse than a missing one.
+
+**A follow the frame loop is still correcting is inside the band by
+definition.** The eased write rides behind the offset it owns, so a burst of
+two or three lines would otherwise drop the viewport out of the band for a few
+frames and flash the affordance over a transcript that is following the newest
+output. Ownership cannot express this: it outlives the loop deliberately, and a
+viewport resting in the reserved blank is an intentional reader-controlled
+state. A gesture stops the loop before it can hide anything, and no later settle
+step reclaims the viewport.
+
+## Resizing Anchors the Viewport Bottom
+
+A plain scroller preserves `scrollTop` across a resize, which anchors the **top**
+edge — the bottom is where content gets revealed or swallowed. For a transcript
+that is backwards, because the interesting end is the bottom.
+`handleViewportResize` anchors there instead. Follow output already behaves this
+way for a viewport it owns; this is the same rule for one it does not, so the
+same drag stops producing two different results depending on whether the user
+had scrolled.
+
+The two halves are not equally capable, and the difference is the useful part:
+
+- **A height change moves no content.** Preserving `scrollTop + clientHeight` is
+  exact and needs no judgement about what the user was doing, so it is applied
+  unconditionally. It also preserves the distance to the content end, which
+  makes "was at the end, stays at the end" fall out for free rather than being a
+  case. Growing the viewport is additionally a *restoration*: the browser used
+  to clamp a bottom-anchored viewport at `scrollHeight - clientHeight`, and the
+  resident spacer removed that clamp.
+- **A width change reflows the transcript.** Where the line that was on the
+  bottom edge went is a DOM question, and by the time the resize is observed the
+  reflow has already happened, so it cannot be answered after the fact.
+  Answering it would mean sampling an element anchor on the scroll path, which
+  is a `getBoundingClientRect` per scroll event. Instead only the one position
+  that can be recomputed from geometry is restored — the end of the transcript —
+  which needs `wasAtTail`, the band check from *before* the resize.
+  `VirtualMessageList` mirrors `isAtBottom` into a ref for that, and calls the
+  handler ahead of recomputing it.
+
+**One correction is not enough.** A width change reflows every item and a height
+change makes the virtualizer render a different number of them; either way it
+re-measures over the following passes, so the content end keeps moving after the
+first callback. The correction therefore repeats over
+`TAIL_REALIGN_RESIZE_CALLBACKS`, a window opened only by a change to the
+scroller's own box. Streaming content growth arrives through the same observer
+and must never inherit that window — it moves the content end away from a
+resting viewport and can never strand it, so reacting to it would be all risk
+and no benefit.
+
+Two properties are shared with the gesture path, and one is not:
+
+- **Instant, never animated.** A height change moves the viewport by exactly the
+  height that was added or removed, so nothing appears to move at all; the rest
+  is a correction the user is already watching happen under the cursor. An
+  animation would add a scroll nobody asked for.
+- **No transfer of ownership** — unlike the gesture path. A gesture ending in
+  the blank says "take me to the end"; a layout change says nothing. The
+  browser's clamp never changed who owned the viewport either.
+
+Native scroll anchoring cannot help here: `overflow-anchor: none` is set
+throughout the transcript, because it fights the virtualizer.
+
+## An Animation Only as Far as the Reader Can Follow
+
+A jump to latest animates within `FLOWCHAT_ANIMATED_JUMP_MAX_VIEWPORTS` of where
+the viewport already is, and lands outright past that. The distance is counted
+in viewports, not pixels: what a reader can follow is a share of what they can
+see, and the same 2000px is two and a half screens on a laptop and most of one
+on a tall display.
+
+**The animation is the affordance, not the movement.** Its job is spatial
+continuity — showing which way and how far the viewport went — and three screens
+on, the transcript in between goes past faster than anyone can read it. What is
+left is a wait where the answer was, which is why every other navigation in the
+transcript is instant already.
+
+Distance also costs more than it looks. Animating across N screens of a
+virtualized transcript renders and measures every item passed while the
+animation runs, and heights are estimates until they are measured — so the
+content end moves under an animation aimed at where it used to be, and the
+follow loop corrects that afterwards as a second, visible movement.
+
+And past a few screens the animation does not finish. The stand-down below is
+bounded, and what it does not cover is delivered as a jump: measured, a jump
+issued for 8717px animated 5480 of them and was finished by the loop in a single
+3290px write. Two thirds of a scroll and then a jump is worse than either half
+alone, and no yield budget fixes it — a longer one only makes the reader wait
+through more of an animation they cannot read.
+
+The other `'smooth'` request in `useFlowChatFollowOutput`, the post-streaming
+settle, needs no such test: the gap it closes is bounded by `tailHoldMaxGapPx`,
+which is 60% of one viewport.
+
+`followOutput.jumpBehavior` records the decision and the distance in viewports.
+It is also how the constant is checked: if `followOutput.animatedScrollEnded`
+still reports a `backstop` reason, an animation ran out its yield without
+arriving and the number is too high.
+
+## The Frame Loop Yields to Its Own Animated Scrolls
+
+`applyFollowTarget` assigns `scrollTop` outright, which cancels an in-flight
+smooth scroll on the very next frame. Both `'smooth'` requests in
+`useFlowChatFollowOutput` — the near jump to latest and the post-streaming
+settle — were therefore jumps in practice, so the loop stands down while one
+travels.
+
+**What ends the stand-down is the viewport having sat still for
+`SMOOTH_SCROLL_STALL_MS`.** That says the animation is over, or was cancelled,
+or never started; either way there is nothing left to yield to. Arriving on
+target ends it as well, and sooner.
+
+**Neither half of this may be counted in frames, and both were.** A frame count
+is not a duration, and the two failures are the same mistake at opposite ends
+of the animation:
+
+- The budget was 45 frames — 0.75s at 60Hz, 0.52s on a busy 200Hz display — so
+  what a caller bought depended on the machine. The browser scales a smooth
+  scroll's duration with its distance; measured, a jump aimed at 8717px animated
+  5480 of them and was finished by the loop in a single 3290px write, 38% short.
+  A wall-clock budget is what makes that failure the same size everywhere, and
+  the distance cap above is what stops anything asking for a jump that size in
+  the first place.
+- The stall check was then two frames, which is 10ms at 200Hz. A programmatic
+  smooth scroll *eases in* — measured, 2px in its first 50ms against 9734px to
+  travel — and with scroll offsets quantised to 0.8px the early frames
+  genuinely do not move. So the stand-down ended 21ms after it began, having
+  animated nothing, and the jump to latest lost its animation entirely.
+
+`SMOOTH_SCROLL_STALL_MS` is therefore derived from the curve's start rather
+than from the platform's startup latency, which is the shorter of the two:
+visible increments arrive up to ~40ms apart early on, and the constant is that
+doubled. `SMOOTH_SCROLL_YIELD_MS` remains as a backstop for an animation that
+never ends at all — also a wall-clock fact, and now written as one.
+
+`followOutput.animatedScrollEnded` says which of the three ended it and how far
+the animation actually got. Both bugs above were a stand-down ending early, and
+both were invisible in the trail: the loop simply started writing, exactly as
+it does when an animation finishes properly.
+
+The stand-down ends *by falling through to the write*, not by returning. An
+animation aims at the offset it was issued for, and content arrives while it
+travels, so the frame that reclaims the viewport is also the frame that covers
+whatever grew — one catch-up step rather than one wasted frame and then a
+bigger one.
+
+The whole mechanism is *intra-owner* and deliberately outside the register:
+this is follow-output yielding to its own animation, and the register
+arbitrates between writers rather than inside one. See
+`FLOWCHAT_VIEWPORT_REGISTER.md`.
+
+## Footer Contract
+
+The footer below the items holds two independent pieces, and they must stay
+separate:
+
+```text
+message-list-footer      = current input-stack height + bottom inset + clearance
+message-list-tail-spacer = tailSpacerPxForViewport(clientHeight, footer)
 ```
 
-If you forget to subtract reservation space, future shrink/growth calculations become wrong.
-
-`pin` reservations use this extra metadata:
-
-- `targetTurnId`: which user turn the viewport should align to
-- `mode: 'transient' | 'sticky-latest'`
-- `floorPx`: the minimum tail space needed to keep the pinned target stable
-
-`sticky-latest` is used for the "latest turn should stay pinned to top" behavior.
-Its floor grows when live DOM measurements require more range and drains only
-from measured positive content growth.
-The pinned item may hand off to tail-follow only after both the complete pin
-reservation (`px`, not only `floorPx`) and collapse reservation reach zero.
-
-## 2. Synchronous Footer DOM Apply
-
-React state alone is not enough here.
-
-`applyFooterCompensationNow()` writes footer height directly to the DOM and forces layout reads:
-
-- `footer.style.height`
-- `footer.style.minHeight`
-- `footer.offsetHeight`
-- `scroller.scrollHeight`
-
-This is intentional. It ensures the browser uses the new footer height in the same turn, before we restore the anchor.
-
-If you move compensation back to "React render only", the flash can return because the DOM may still be one frame behind when `scrollTop` is restored.
-
-## 3. Semantic Anchor Coordinator
-
-`FlowChatViewportCoordinator` owns the semantic viewport anchor. It tracks one
-primary mode at a time: pinned item, following tail, or preserving an element.
-Tool cards supply an anchor element but never calculate scroll offsets or
-heights. The coordinator records the element's viewport-relative position and
-restores it after the list remeasures. While an element anchor is active, the
-coordinator also owns virtualizer compensation corrections, so independent
-scroll writers cannot fight the pinned header.
-
-The logical `isFollowingOutput` flag follows the same ownership rule: it is
-only true while the coordinator owns `following-tail`. A `sticky-latest` pin
-clears the flag and arms its turn for handoff. Once collapse protection and
-unsettled pin growth have drained, the handoff re-enters tail follow when
-either the pin reservation is empty or the natural content tail (excluding
-Footer reservations) reaches the viewport bottom. The latter condition avoids
-making real content grow through stale synthetic pin space before follow can
-start. This prevents a stale React render from allowing follow effects to
-overwrite a pinned header.
-The armed turn identity is owned only by `useFlowChatFollowOutput`; the list
-must not mirror it in a second ref because session resume and pin preparation
-can otherwise update the two identities in different commits.
-
-Collapse anchors have three phases: active while CSS layout is changing,
-retained-provisional while delayed virtualizer measurements may still arrive,
-and settled-grace after the provisional estimate has been reconciled to current
-DOM geometry. A short negative-layout quiet window ends the provisional phase.
-The Footer is then reduced atomically to the minimum physical range needed by
-the captured `scrollTop`; an anchor at `scrollTop === 0` needs no overflow range.
-The semantic anchor remains retained through one final grace window, so a late
-Virtuoso shrink can extend the range and restart settlement without exposing a
-clamped frame. User navigation, a new pin, session reset, DOM disconnection, or
-a quiet grace with no further correction releases it. Scroll
-events enqueue semantic-element restores into the coordinator's single pending
-animation frame. A transaction-owned non-user clamp may additionally extend its
-physical range and restore the captured raw position synchronously before paint.
-Active preservation blocks automatic tail takeover, while retained preservation
-allows the tail controller to take ownership when its normal distance and intent
-rules say that following should resume.
-
-There is no persistent raw `scrollTop` lock or scroll-listener lock. An
-unsignaled shrink may adjust an already owned protected range, but it may not
-create a collapse reservation from idle geometry alone. Without a semantic
-owner, the list accepts the new Virtuoso measurement and rebases its height and
-scroll baselines. Subsequent layout changes are handled by the semantic anchor
-(when present), the owned reservation transaction, or follow mode.
-
-An element anchor also owns the minimum physical scroll range needed to restore
-its offset. After writing `scrollTop`, the coordinator remeasures the actual DOM
-offset. If a positive correction remains because the browser clamped at the
-bottom, the range host synchronously extends the matching reservation, flushes
-layout, and retries in the same frame. The post-write DOM measurement is the
-source of truth because integer `scrollHeight` can overstate the browser's
-subpixel scroll limit.
-
-Physical-bottom synchronization must yield whenever the coordinator owns an
-element anchor. It also yields while streaming `following-tail` owns the
-viewport, because the single tail loop is the writer for content-growth motion.
-Outside tail follow, physical-bottom synchronization is limited to a real
-viewport `clientHeight` change. A message, round footer, or other content growth
-changes `scrollHeight` only and must remain below the existing viewport instead
-of moving the transcript upward to reach the new physical bottom.
-A sticky pin intentionally sits at the physical bottom created by its
-reservation; treating that geometry as tail-follow causes every content growth
-measurement to push the pinned header upward before the coordinator can restore
-it. Pinned, anchored, and non-streaming paths keep the normal physical-bottom
-synchronization behavior.
-
-Sticky pin floors are not reduced from a transient target rect. Positive
-effective content growth first enters a short settlement ledger (currently
-300 ms) instead of immediately removing physical bottom range. An unsignaled
-negative height correction cancels matching unsettled growth; a known collapse
-does not. Growth that reaches the complete remaining pin floor settles
-immediately because the sticky viewport has reached its tail-follow handoff
-boundary; if a collapse transaction is still active, that settlement resumes
-as soon as the transaction finishes. Sub-threshold growth still waits for the
-quiet window. Stable growth consumes the pin floor in one synchronous Footer
-update. Live pin reconciliation may increase a floor immediately, but cannot
-shrink it while Virtuoso item measurements are still moving. Stream end performs
-one final pin measurement when the target is available, transfers all remaining
-pin range into protected collapse space, and releases `pinned-item` ownership in
-the same transaction. A temporarily virtualized target must not block this
-release: the existing physical range is retained until a later explicit drain.
-Pending pin retries and growth settlement are canceled at that boundary.
-
-When a sticky target is temporarily virtualized, its provisional range must be
-computed from `scrollHeight - currentPinPx`. Reusing physical `scrollHeight`
-directly feeds the synthetic footer back into the next retry and grows the range
-on every frame. Provisional pins remain at `floorPx: 0`; if the request expires
-without capturing an element anchor, that range is removed atomically.
-
-The pin-owned portion of the footer is capped at one viewport. A rendered
-target can never require more than `clientHeight` of extra range to align its
-top inside the viewport, and one viewport is also sufficient to materialize a
-virtualized target. This cap applies to provisional and established pin ranges.
-It does not apply to collapse compensation or the total footer: a large card or
-several cumulative collapses can legitimately require more than one viewport to
-preserve the current semantic anchor.
-
-Pending pin retries carry a synchronous generation plus the owning session and
-turn. Canceling or replacing a request increments the generation before React
-state is updated, so already-queued animation frames cannot restore a canceled
-reservation. User navigation drops a provisional sticky range instead of
-transferring it into protected collapse. Established pins keep the existing
-protected-range handoff.
-
-Arbitrary-turn navigation is a materialize-then-align transaction. Starting a
-new request exits tail follow, but it does not remove the previous established
-pin reservation before the target DOM exists. That reservation remains only as
-physical scroll range; the active request prevents the old sticky target from
-reconciling it. Once the requested user message is rendered, the shared pin
-resolver applies the request's alignment policy. Exact requests replace the old
-reservation, align the message to the 57px viewport offset, and start bounded
-transient stabilization. Turn-rail requests use best-effort alignment: they
-still align exactly when the natural range is sufficient, but when the target
-cannot reach the 57px offset without synthetic tail space, they remove the
-transient pin reservation, clamp to the natural maximum, and release
-`pinned-item` ownership immediately. The natural boundary is an expected
-content limit, not a pending transaction, so it must not retry until TTL expiry.
-`sticky-latest` always uses the exact policy because streaming follow-output
-depends on its protected pin range. An expired request releases semantic
-ownership while preserving the current physical range, so failure cannot
-silently clamp the pane to the bottom.
-
-`rangeChanged` is a target-materialization signal, not a source of turn
-identity. It retries the active generation against real DOM geometry. RAF
-retries remain as a bounded fallback for browsers that coalesce range updates.
-Transient navigation remains pending until the requested turn stays aligned for
-two consecutive geometry samples. During that bounded transaction, Virtuoso's
-materialization range expands to two viewport heights in both directions so
-height-estimate reconciliation cannot immediately evict the target. If the
-pinned DOM element still disconnects, the coordinator drops the stale element
-anchor but retains logical `pinned-item` ownership while the active generation
-rematerializes it. User intent, replacement, expiry, and explicit handoff still
-release that ownership.
-Virtuoso mounts on the first initial-history commit. A target prepared before
-its ref is available becomes `initialTopMostItemIndex`; targets selected after
-mount enter the normal immediate materialize-then-align transaction. The
-left-side
-`FlowChatTurnRail` is mounted outside the scroller and delegates navigation to
-the same container-owned turn-pin request, so it does not need to rebind across
-renderer handoffs or write the FlowChat viewport directly.
-
-Mounting an already-streaming session is not a new-turn event. Session entry
-resumes tail follow directly, while sticky pinning remains reserved for a new
-turn that appears in the currently mounted session.
-
-## 4. Collapse Intent
-
-Some collapses are predictable before layout actually shrinks.
-
-`flowchat:tool-card-collapse-intent` is emitted before a known collapsible UI
-shrinks. `VirtualMessageList` uses that event to:
-
-- capture the card root as the semantic header anchor
-- capture the pre-collapse anchor `scrollTop`
-- capture the bottom distance before collapse
-- estimate required compensation from current card height
-- apply provisional compensation immediately
-
-This pre-compensation is what avoids the flash.
-
-Runtime status is transient session UI state, not a `FlowItem`. The always-mounted
-`RuntimeStatusSlot` occupies the first 24px of the existing Footer spacer and
-switches only `visibility`; showing, hiding, and clearing it never change list
-height or enter collapse reconciliation. Subagent projections use the same
-fixed-height slot inside their local scroll surface.
-
-If the list waits until `ResizeObserver` sees the shrink, the browser may already have clamped `scrollTop`.
-
-### Completion-preview grace period
-
-`useToolCardCompletionGracePeriod.ts` provides the bounded tail-preview window
-used by `ExecProcessToolCardView`, `TerminalToolCard`, and
-`FileOperationToolCard`. Its default is
-`TOOL_CARD_COMPLETION_PREVIEW_GRACE_MS = 800`.
-
-The timer starts only when a card that was expanded during execution is still
-the last rendered item and has not been manually toggled. A newer item, user
-interaction, unmount, or loss of tail ownership cancels the pending preview.
-For ExecProcess/Terminal cards this covers terminal completion, cancellation,
-errors, and rejections. For successful Write/Edit cards, the timer starts after
-the typewriter reveal finishes so the completed content is not truncated. The
-timer does not change `isLastItem`; an empty next round can still leave the
-previous card as the rendered tail, but the grace period bounds that wait. The
-timer expiry calls the existing height-contract collapse path, so footer
-pre-compensation and semantic-anchor handling remain the same as for a
-successor-driven collapse.
-
-This is deliberately separate from the VirtualMessageList collapse-intent TTL
-and settlement timers: the former controls when a card may compact, while the
-latter protects the viewport while its height changes.
-
-## Runtime Flow
-
-## A. Known Tool Card Collapse
-
-When a helper-backed card or region is about to collapse:
-
-1. it dispatches `flowchat:tool-card-collapse-intent` with its anchor element before the collapse state is applied
-2. `VirtualMessageList` estimates the upcoming shrink using `cardHeight`
-3. `VirtualMessageList` adds provisional footer compensation immediately
-4. `VirtualMessageList` applies the provisional footer synchronously and records
-   the semantic anchor's viewport offset
-5. actual layout shrink happens
-6. `ResizeObserver` / `MutationObserver` / transition listeners trigger `measureHeightChange()`
-7. measured shrink reconciles the compensation to the real final value
-8. the coordinator restores the anchor element's exact viewport-relative position
-
-Common examples:
-
-- `FileOperationToolCard`
-- `ModelThinkingDisplay`
-- `TerminalToolCard`
-- `ExploreGroupRenderer`
-
-## B. Unknown or Unsignaled Shrink
-
-If a shrink happens without a collapse intent:
-
-1. `measureHeightChange()` detects the negative height delta
-2. compensation falls back to `shrinkAmount - distanceFromBottom`
-3. `restoreScrollPositionOnce()` makes one clamped fallback restore using the
-   previously known scroll position
-
-This path is safer than doing nothing, but it is more likely to show visible movement than the pre-compensation path.
-
-## C. Initial-History Snapshot Handoff
-
-Virtuoso is the only initial-history scroller and mounts on the first commit.
-For sessions that still need the initial history render budget, a bounded recent
-projection is rendered above it as a non-interactive snapshot. The snapshot:
-
-- has no scroll container, spacers, pagination handlers, or viewport writer
-- uses `pointer-events: none` and cannot consume wheel, touch, keyboard, or
-  scrollbar intent
-- keeps the previous pixels visible while Virtuoso measures its initial range
-- releases immediately when the user starts scrolling so the real Virtuoso
-  motion is never hidden behind a frozen frame
-- retargets its release condition when Turn navigation begins during handoff
-- disappears only after the requested Turn has visible text, the session
-  changes, or the bounded handoff timeout expires
-
-All Turn navigation, search materialization, boundary pagination, bottom state,
-and follow-output transitions run through the mounted Virtuoso instance even
-while the snapshot is visible. A catalog-backed partial session still keeps
-only its restored tail as the default data presentation; this rendering change
-does not imply full-history hydration.
-
-## D. Arbitrary Turn Navigation Through Virtuoso
-
-The left-side turn rail delegates to the container-owned top-aligned pin
-transaction:
-
-1. record generation, session, target turn, behavior, and pin mode
-2. exit tail follow without removing established physical range
-3. if the target is absent, issue an immediate `scrollToIndex(..., align:
-   'start')`
-4. retry from `rangeChanged` and bounded RAF work until the target user message
-   exists
-5. replace the prior pin reservation with the target's measured reservation
-6. align the target to the shared 57px header offset and stabilize delayed
-   Virtuoso measurements
-7. cancel stale work on a newer request, user intent, session switch, jump to
-   latest, or timeout
-
-Every turn-rail marker, including the canonical latest Turn, uses this same
-immediate transient top-pin transaction. Selecting the latest marker means
-"show this Turn header"; it does not restore the tail presentation or resume
-follow-output. Only the explicit jump-to-latest action restores the canonical
-tail presentation and re-enters live-tail following. This separation keeps
-turn navigation consistent and treats every rail selection as user reading
-intent, including while the latest Turn is streaming.
-
-Do not clear the previous pin/footer range in step 2. The target may be outside
-the current Virtuoso range, and removing the footer first lets the browser clamp
-the old position to the physical bottom before materialization succeeds.
-
-The turn rail is an independent overlay surface. Its height is bounded to 60%
-of the FlowChat content area; overflow scrolls only the rail, and keeping the
-current marker visible may update only the rail list's `scrollTop`. Rail wheel,
-keyboard, hover, and tooltip behavior must never become another writer for the
-outer FlowChat viewport.
-
-The existing visible-turn DOM measurement also collects every distinct turn
-whose rendered items intersect the readable viewport. The first intersecting
-turn remains the semantic current turn, while every intersecting turn marker
-uses the same rail emphasis. Publish a new ordered `visibleTurnIds` snapshot
-only when membership or order changes so ordinary scroll frames do not cause
-redundant rail renders.
-
-### Catalog-backed history loading
-
-Catalog, loaded Turn cache, and active presentation are separate layers. Keep
-these ownership rules intact:
-
-- `Session.dialogTurns` remains the live restored tail unless an explicit
-  full-history consumer calls `ensureSessionFullHistory`.
-- Data residency, viewport intent, and follow-output ownership are independent.
-  A cached history presentation may remain resident after the viewport returns
-  to the live tail, but it must not keep the UI in history-reading mode,
-  suppress live-tail anchoring, or imply that follow-output is active.
-- For a small session whose cached presentation is contiguous from ordinal zero
-  through the current total (`[0, totalTurnCount)`) and stays within the
-  continuous projection budgets (24 Turns and 200 virtual items), explicit
-  jump-to-latest changes only the viewport intent and follow-output ownership.
-  The rendered projection and its stable virtual-item keys remain unchanged;
-  `historyWindow` is disabled so boundary loading cannot start while following
-  the tail. Canonical overlapping Turns are still overlaid by stable id, and a
-  newly appended canonical Turn extends the projection at the end.
-- Incomplete, discontinuous, or over-budget presentations retain the fallback
-  behavior: explicit jump-to-latest clears the Store's `activeRange`, restores
-  the canonical tail data source, and keeps the most recent component
-  presentation only as a reactivation hint. The Store LRU remains authoritative:
-  reactivation must find the complete range in `loadedRanges`, touch it as MRU,
-  and otherwise fall back to the ordinary window-load transaction.
-- Turn-rail navigation and sequential boundary loading use
-  `load_session_turn_window`; neither path writes the FlowChat scroller.
-- Upward user intent at the restored-tail boundary loads the adjacent ordinal
-  window without holding viewport ownership. Presentation activation then waits
-  for a bounded 320 ms quiet window after the latest wheel, touch, keyboard, or
-  scrollbar intent. New input resets that wait; session changes and newer
-  presentation-owner generations cancel it. Only after the quiet window is
-  acquired does the list capture the current element anchor and change to one
-  contiguous history-window presentation. This keeps a multi-thousand-pixel
-  prepend commit out of an active wheel gesture while still allowing the data
-  request itself to prefetch in parallel. Never expose a later cached range
-  across an unloaded gap.
-- Derive the restored-tail boundary from the canonical `Session.dialogTurns`
-  ordinal interval, never from the start of a merged `loadedRanges` entry.
-  Cache residency may extend to the first Turn while the canonical tail still
-  renders only recent Turns. Reaching ordinal zero is an exhausted boundary,
-  not a not-ready or failed load.
-- Appending below the current presentation does not require compensation.
-  Prepending or trimming above it must retain the existing element-anchor
-  transaction until the same user message returns to its captured viewport
-  offset.
-- A rejected or failed adjacent-window request must release only the element
-  anchor lease created during its commit preparation, if any. A stale
-  completion must never release a newer navigation or layout-preservation
-  transaction.
-- The non-tail loaded Turn cache uses a 48-Turn soft budget and a 64-Turn hard
-  budget. Crossing the hard budget evicts least-recently-used ordinals back
-  toward the soft budget. The live tail, active presentation, pending target,
-  and in-flight request intervals are protected; merged cached ranges may be
-  sliced, but the active presentation is never trimmed by cache eviction.
-- Passive live-tail updates outside the presented history range remain hidden
-  while the user reads history. When the history range overlaps canonical live
-  Turns, stable Turn ids select the canonical objects instead of cached
-  snapshots so streaming or recently completed content stays current without
-  changing the viewport intent. An explicit `send-message` Turn-pin request
-  first restores the tail presentation, then lets the existing sticky-latest
-  pin materialize the newly submitted Turn.
-- Cross-feature focus requests identify a Turn by stable `turnId` whenever one
-  is available, with `turnIndex` reserved for the absolute one-based visible
-  ordinal. They delegate to the same catalog/window materialization transaction
-  as the Turn rail. Never pass that absolute ordinal to `scrollToTurn` on a
-  partial tail or bounded history presentation; that method only understands
-  the currently rendered local list.
-- Search, edit, rollback, and compatibility fallback are explicit full-history
-  consumers. Their shared ensure operation deduplicates an existing request and
-  applies the completed projection only after the caller asks for it.
-- A Host without `turnCatalog`, or without `load_session_turn_window`, retains
-  the legacy full-restore fallback. This compatibility path must not cause a
-  catalog-capable Host to resume unconditional background hydration.
-
-## Why Transition Tracking Exists
-
-User-initiated expand/collapse still uses animated layout properties such as:
-
-- `grid-template-rows`
-- `height`
-- `max-height`
-
-Automatic and manual collapses both animate through the shared motion contract
-unless animation is explicitly disabled.
-
-During those transitions, the DOM may report intermediate sizes for multiple frames.
-
-The collapse intent carries a hard TTL (`expiresAtMs`, currently 1000 ms), but
-that TTL only bounds collapse measurement and reservation settlement; it does
-not expire the semantic element anchor. Automatic collapses are
-finalized after `FLOWCHAT_COLLAPSE_DURATION_MS` plus a short settle-frame window;
-manual or otherwise unsignaled intents use the TTL timer. The scroll handler keeps only a throttled-background
-timer fallback for browsers that delay timers. While the intent is alive, the
-grow branch of `measureHeightChange` protects the collapse reservation, but it
-may still consume measured content growth from the sticky pin reservation.
-Intent settlement follows the current semantic viewport owner. A sticky pinned
-turn always reconciles provisional collapse space back into a freshly measured
-pin reservation, even when the active transaction established a non-zero
-collapse floor. That floor protects the pin only while layout is moving; it
-must not cause the full-card estimate to survive into the next collapse. If the
-pinned target is temporarily unavailable, settlement retries without dropping
-the current range. A following tail instead enters retained-provisional quiet
-settlement, while a collapsing header that owns `preserving-element` reduces
-the footer atomically to the minimum range needed by its captured `scrollTop`.
-A detached protected viewport uses the same geometric settlement against its
-current `scrollTop`, without retaining provisional pixels above that range.
-These owner-specific transactions prevent both clear-and-reacquire frames and
-cumulative provisional whitespace. Any deferred follow is then replayed.
-
-## E. Follow-Output Mode (continuous tail)
-
-When the viewport is in follow-output mode and the latest turn is still
-streaming, the user's intent is "keep the tail visible". After the viewport
-coordinator has entered `following-tail`, one RAF loop eases `scrollTop` toward
-the effective bottom. Follow events only wake this loop; they do not launch
-additional scroll writers. The target subtracts the current Footer
-reservation, and large gaps snap directly to the target instead of leaving the
-user visibly behind the output.
-
-The loop is dormant while `pinned-item`, `preserving-element`, or a collapse
-transaction owns the viewport. It never clears reservations or calls
-`followTail()` from inside the animation frame. This keeps the semantic
-handoff and Virtuoso compensation paths authoritative while allowing small
-line-height growth to move over several frames. Explicit "jump to latest"
-navigation keeps its native smooth scroll; the RAF loop waits for that motion
-to settle before writing.
-
-Collapses interact with follow mode in three mutually exclusive ways:
-
-1. **Known collapse while follow + streaming is active:** the intent applies
-   synchronous Footer pre-compensation before the card shrinks. The active
-   intent allows shrink reconciliation even though tail follow is running.
-    When the CSS window ends, the transaction becomes a retained-provisional
-   collapse anchor instead of shrinking the Footer from a signed net-height
-   estimate. Virtuoso
-   can publish the matching item measurement after the CSS transition and after
-   stream end; reducing synthetic range before that measurement clamps the
-   viewport by exactly the removed pixels.
-   The retained transaction records the latest safe follow position. After a
-   negative-layout quiet window, it replaces both the provisional `px` and stale
-   `floorPx` with the minimum geometrically required Footer range. The final
-   release uses one timer plus a geometry generation: any effective height
-   change invalidates that timer's snapshot, and the timer performs one more
-   quiet check instead of every token allocating new timer work. If a later
-   measurement clamps below that position, the scroll handler synchronously
-   extends the range and restores it before paint. Real content growth and
-   downward follow movement consume the range one-for-one. User intent, a new
-   pin, session reset, or a final quiet grace releases the retained anchor.
-   Stream end restarts the same settlement path;
-   it does not preserve the provisional full-card estimate indefinitely.
-2. **Unsignaled shrink while follow + streaming is active:** a strict physical
-   clamp signature (the previous and current geometries are both at their
-   physical bottoms, the range shrink matches the negative `scrollTop` delta,
-   viewport height is stable, and there is no user intent) starts a
-   `late-shrink` viewport transaction. The scroll handler extends the Footer and
-   restores the pre-clamp position synchronously, covering virtualizer size
-   commits that arrive after the originating collapse transaction was released.
-   Other unsignaled shrinks remain owned by the tail loop; it follows only
-   downward toward the new effective bottom on the next frame.
-   A negative `scrollBy` issued by Virtuoso after a virtualized height
-   reduction is also suppressed when the previous geometry was already at the
-   physical bottom. That compensation would move the viewport away from the
-   tail; the next follow frame owns the single tail correction instead.
-3. **Not following (user reading older content):** the intent +
-   pre-compensation + semantic-anchor path applies as described above, and
-   `shouldSuspendAutoFollow` keeps event-driven follow scheduling
-   deferred until the intent's TTL lapses.
-
-The loop is cancelled as soon as follow exits (user upward scroll,
-session change, or streaming end). Explicit "jump to latest" navigation pauses
-the writer while its native smooth scroll completes, then resumes the same
-single tail loop.
-
-## Why `overflow-anchor: none` Must Stay
-
-`VirtualMessageList.scss` disables native browser scroll anchoring on:
-
-- `[data-virtuoso-scroller]`
-- `.message-list-footer`
-
-This is required because the browser's built-in anchoring fights the manual compensation logic.
-
-If you remove `overflow-anchor: none`, the browser may apply its own anchor correction on top of our compensation and produce unstable or inconsistent results.
-
-## Required Event Contract
-
-`tool-card-toggle`
-
-- dispatch after a generic expand/collapse action that changes height
-- purpose: schedule a follow-up measurement
-
-`flowchat:tool-card-collapse-intent`
-
-- dispatch before a collapse that can reduce list height near the bottom
-- include the card root as `anchorElement`; its top edge represents the stable header position
-- include `cardHeight` when possible
-- purpose: pre-compensate before the browser clamps scroll position
-
-Current producer:
-
-- `useToolCardHeightContract.ts` (used by most tool cards, including
-  `ExecProcessToolCardView`, `FileOperationToolCard`, and `TerminalToolCard`)
-- `ModelThinkingDisplay.tsx`
-- `ExploreGroupRenderer.tsx`
-
-Most tool cards now emit these events through `useToolCardHeightContract`.
-The helper measures the visible `cardRootRef` and retains recent visible
-measurements so state-driven collapses still report the pre-collapse height.
-Never substitute an inner scroll container's `scrollHeight`; hidden overflow is
-not layout height removed from the FlowChat list.
-
-If a future collapsible component shows the same "header drops" or "flash on collapse" symptom, it should likely emit `flowchat:tool-card-collapse-intent` before collapsing.
-
-## Invariants To Preserve
-
-- Footer compensation must remain additive temporary space, not real content.
-- Effective height comparisons must subtract current compensation.
-- Footer DOM compensation must be applied synchronously before anchor restore.
-- Anchor restore must clamp against current `maxScrollTop`.
-- A stalled positive anchor correction must extend physical bottom range and
-  retry before paint.
-- Resize and height observers must not synchronize to the physical bottom while
-  a semantic element anchor owns the viewport.
-- Sticky pin floors must shrink from measured content growth, not a transient
-  target-element position.
-- A user gesture that exits pinned mode must release the semantic anchor and
-  atomically transfer the pin reservation to a protected collapse range in the
-  same operation; an idle coordinator must never retain a live pin reservation.
-- Stream end or cancellation must perform that same protected-range transfer
-  before releasing `pinned-item`, even when the pinned DOM target is unavailable.
-- Scroll-handler anchor corrections must be coalesced through the coordinator's
-  animation-frame restore queue; they must not write `scrollTop` synchronously.
-- A retained collapse transaction may synchronously restore only a non-user
-  downward clamp. It is transaction-scoped, advances with downward tail follow,
-  and must release on user intent; it is not a general `scrollTop` lock.
-- Following-tail collapse finalization must never reduce Footer range directly
-  from a signed net-height estimate. It may reduce the retained estimate only
-  after the negative-layout quiet window, using current DOM geometry while the
-  anchor remains protected through the final grace.
-- Unsignaled shrink reconciliation must not reduce a protected collapse floor;
-  only measured growth, downward navigation, bottom arrival, or an explicit
-  reservation reset may consume it.
-- Unsignaled shrink reconciliation must not create a collapse reservation when
-  no collapse transaction owns the range. Session-open and history-projection
-  handoffs rebase their measurements instead of treating estimate convergence
-  as content collapse.
-- Pre-collapse intent must capture the anchor before the component shrinks.
-- Compensation must not be consumed too early during active layout transitions.
-- Session changes and empty-list resets must clear compensation and anchor state.
-
-## Common Ways To Break This
-
-- Adding a mount-triggered CSS animation to a virtualized list item, or animating
-  an automatic collapse without keeping collapse-intent protection alive for the
-  full `FLOWCHAT_COLLAPSE_DURATION_MS` window (see Rule Zero).
-- Feeding `Date.now()` back into `sessionToVirtualItems` /
-  `buildModelRoundItemGroups`, or splitting one `ModelRound` into several
-  `model-round` virtual items — both swap stable Virtuoso keys for new ones and
-  remount visible content.
-- Replacing `applyFooterCompensationNow()` with state-only rendering.
-- Measuring raw `scrollHeight` deltas without subtracting existing compensation.
-- Removing `flowchat:tool-card-collapse-intent` from a helper-backed collapsible component.
-- Finalizing an active collapse intent when a new one arrives mid-burst instead of
-  coalescing TTL / provisional shrink (drops footer protection for a frame).
-- Dispatching collapse intent after `setState` instead of before it.
-- Removing `overflow-anchor: none`.
-- Removing the intent TTL, settle-frame finalizer, or the throttled scroll
-  fallback that covers delayed background timers.
-- Reintroducing a persistent scroll-listener lock or allowing multiple competing
-  scroll writers. Semantic anchors and the bounded fallback must remain separate.
-- Passing reservation pixels through Virtuoso context or React-owned Footer
-  styles. The stable Footer DOM and ref-owned reservation are the hot path.
-- Restoring the blanket follow-mode early return in
-  `handleToolCardCollapseIntent` or applying it to an active known intent in
-  `measureHeightChange`. Known streaming collapses require synchronous range
-  reservation; only unsignaled shrinks are delegated entirely to the RAF loop.
-- Removing the `shouldSuspendAutoFollow` gate from event-driven follow
-  scheduling. Outside follow mode it keeps deferred follows from firing while a
-  collapse intent is still protecting the anchor.
-- Removing the continuous RAF follow loop. Event-driven follow alone cannot
-  keep up with dense token streams without visible jitter outside collapse
-  windows.
-
-## If You Need To Change This Logic
-
-### Opt-in viewport diagnostics
-
-Enable `app.logging.flow_chat_diagnostics` from the logging settings only while
-reproducing a viewport stability issue. The frontend records bounded JSONL
-batches to `flowchat.log` in the current session log directory. When disabled,
-probe payloads are not evaluated and no timer, IPC request, or file is created.
-
-The diagnostic schema groups events by hypothesis:
-
-- `A`: user scroll intent, pin release, reservation transfer, and tail handoff
-- `B`: semantic anchor capture, correction, release, or unexpected reacquisition
-- `C`: content measurement, Footer compensation, and physical range changes
-- `D`: Virtuoso scroll compensation and tail-follow ownership
-- `E`: streaming tool-card collapse intent and anchor preservation
-
-Do not add message content, tool arguments, file contents, or other sensitive
-payloads to this channel. Keep all data producers lazy and guard hot-path probes
-with `flowChatDiagnostics.isEnabled()` before allocating probe objects.
-
-Use this checklist:
-
-1. Verify a just-completed ExecCommand/Write tail keeps its preview during the
-   short grace period, then compacts if no follow-on item arrives.
-2. Verify manual collapse of a completed `Write` / `Edit` tool card.
-3. Verify a newer item still causes immediate automatic compaction before the
-   grace period expires.
-4. Verify repeated expand/collapse near the bottom.
-5. Verify thinking / explore / other collapsible sections still schedule measurements correctly.
-6. Verify there is no visible "drop then snap back" flash.
-7. Verify the final header position remains stable after collapse.
+The footer must not retain an earlier input height or include an estimated card
+shrink. The spacer reads the footer to size itself, but the two must not be
+folded into one number: the footer is content the transcript clears, the spacer
+is range past the end of content, and only the footer is inside the content end.
+
+Footer height represents only the current input-stack layout and real footer
+content such as history state and `RuntimeStatusSlot`.
+
+## Known Gaps
+
+- The eased follow raises the scroll-event rate from one a line to one a frame
+  while output streams — 1247 of them in one 120-second session, each an anchor
+  stand-down and a visible-Turn pass. It does not show in list commits, and
+  nothing here counts the DOM reads themselves, so what is actually known is
+  that the rendering cost did not move. Re-measure with the `tailFollow` probe
+  before changing `TAIL_EASE_ALPHA`.
+- Easing is bounded by the frames the display gives it. The step it converges
+  on is the content's growth *per frame*, so the same stream smooths less at
+  60Hz than on the ~200Hz display these numbers come from, and a fast enough
+  stream is a line a frame anywhere — at which point the ease is spending its
+  lag and buying nothing.
+- `SMOOTH_SCROLL_YIELD_MS` is only a backstop now, but it is still a guess: an
+  animation that stalls mid-flight without ever resuming holds the follow off
+  for its whole duration. Nothing observed has done that — the stall check ends
+  every real animation long before it — and the cost if one did is the follow
+  resuming late, not the viewport landing wrong.
+- A scrollbar drag is recognised from the gutter the bar occupies, so it is
+  invisible where the platform draws overlay scrollbars that take no layout
+  width — WebKit-backed builds, where `scrollbar-gutter: stable` reserves
+  nothing either. There the drag can still fight the frame loop while output
+  streams. Closing it means either a signal that does not depend on the bar
+  having a box, or a scrollbar of our own.
+- A collapse larger than `tailHoldMaxGapPx` still moves the viewport, by the
+  excess only.
+- **A reader who scrolls out of the blank and stops at the content end keeps no
+  follow.** Output then accumulates below the bottom edge unseen until an
+  explicit follow entry takes the viewport again.
+- **Paging a long history while still scrolling throws the reading position a
+  long way.** Reproduced four times: a session opened on its three-Turn tail
+  pages the rest on the first scroll up, the prepend is compensated, and the
+  reader keeps wheeling through the settle that follows. Their Turn is out of
+  the rendered window for the whole of it, so `captureAnchorForScroll` cannot
+  re-capture and carries instead — adding each scroll to the Turn's expected
+  offset with no DOM to check the result against. Measured: three attempts,
+  5532.7px, an anchor agreed at 112.6px from the viewport top becoming one
+  agreed at 3356px in a 985px viewport, and a −1349px correction computed
+  against that. Worst case it clamps at `scrollTop: 0` with the session's first
+  Turn at the top. `ANCHOR_MISSING_TURN_ATTEMPTS` does not bound it — that is
+  frames, not distance.
+
+  **Three fixes were tried and reverted; do not re-derive them.** *Refuse a
+  correction whose offset left the viewport* — an anchored offset legitimately
+  leaves it, both when the reader scrolls past their own Turn and when a
+  registered writer's travel is taken out, and each has a test asserting the
+  correction that follows. *Subtract the browser's clamp,*
+  `previousScrollTop - max(0, scrollHeight - clientHeight)` — unsound, because
+  the previous offset was valid at the previous range, so any shrink at all
+  makes it exceed the new maximum whether or not the viewport was ever clamped;
+  measured, it took 2790.7px off a descent the reader had made themselves.
+  *Track the smallest range since the last credit* — the floor came back equal
+  to the current range, so no dip was ever observed. `overflow-anchor` is a dead
+  end too: already `none` on every scrolling box here.
+
+  What the four logs do establish: the reader is wheeling continuously
+  throughout (the `user-gesture` claims are coalesced, so read `suppressedCount`
+  before concluding they stopped), and the descent is largely theirs. The next
+  attempt should probably bound the *result* — an offset several screens outside
+  the viewport is wrong whatever put it there — rather than try to attribute the
+  movement, which is what all three failures had in common.
+- An animated scroll aims at the target it was issued for. Jumping to latest
+  while output is arriving therefore ends with one catch-up step covering
+  whatever content grew during the animation — under the ease's snap threshold
+  at ordinary streaming rates, and a visible jump above them.
+- A width change anchors the viewport bottom only for a viewport that was at the
+  end of the transcript. Everywhere else the reflow moves content out from under
+  the bottom edge and nothing puts it back, because the anchor would have to be
+  captured before the reflow. Closing this means sampling an element anchor on
+  the scroll path.
+- On a very short transcript the scrollbar exposes a viewport of empty range.
+  The range is intentionally draggable and no longer bounces back.
+- The opening reveal has a hard frame cap. A session that pages for longer than
+  the cap is revealed mid-settle; raising the cap trades that against a longer
+  blank on open.
+- **Estimates are still estimates.** A page of history is now reserved per item
+  rather than at one scalar, so the range it takes up is close instead of wrong
+  by an order of magnitude — but `estimateVirtualMessageItemHeight` cannot know
+  how a model round wraps. Corrections shrink; they do not reach zero. And the
+  cost of rendering a heavy item is a separate axis: less measurement is forced
+  at once, but the work each one costs is unchanged. See
+  `FLOWCHAT_VIRTUALIZATION.md`.
+- A junction still costs one frame at the first page of a session, measured at
+  93px: the commit paints before the settle frame that would correct it. Slower
+  frames swallow both and show nothing. Closing it means a tighter estimator,
+  not a further correction — the correction already equals the change in the
+  scroll range every time it runs.
 
 ## Related Files
 
-- `src/web-ui/src/flow_chat/components/modern/VirtualMessageList.tsx`
-- `src/web-ui/src/flow_chat/components/modern/FlowChatViewportCoordinator.ts`
-- `src/web-ui/src/flow_chat/components/modern/VirtualMessageList.scss`
-- `src/web-ui/src/flow_chat/tool-cards/useToolCardHeightContract.ts`
-- `src/web-ui/src/flow_chat/tool-cards/useToolCardCompletionGracePeriod.ts`
-- `src/web-ui/src/flow_chat/tool-cards/ExecProcessToolCardView.tsx`
-- `src/web-ui/src/flow_chat/tool-cards/FileOperationToolCard.tsx`
-- `src/web-ui/src/flow_chat/tool-cards/ModelThinkingDisplay.tsx`
-- `src/web-ui/src/flow_chat/tool-cards/TerminalToolCard.tsx`
-- `src/web-ui/src/flow_chat/components/modern/ExploreGroupRenderer.tsx`
+- `flowChatTailFollow.ts`
+- `useFlowChatFollowOutput.ts`
+- `../../utils/flowChatScrollLayout.ts`
+- `../../tool-cards/useToolCardHeightContract.ts`
+- `VirtualMessageList.tsx`
+- `ModernFlowChatContainer.tsx`
diff --git a/src/web-ui/src/flow_chat/components/modern/FLOWCHAT_VERIFICATION.md b/src/web-ui/src/flow_chat/components/modern/FLOWCHAT_VERIFICATION.md
new file mode 100644
index 0000000000..52e04949ba
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/modern/FLOWCHAT_VERIFICATION.md
@@ -0,0 +1,232 @@
+# FlowChat Viewport Verification
+
+The automated checks, and the manual ones agents may not run.
+
+## Automated
+
+```text
+pnpm run type-check:web
+pnpm --dir src/web-ui run lint
+pnpm --dir src/web-ui run test:run <the files below that your change touches>
+```
+
+Pick by what you changed rather than running the whole column — but this is the
+whole column, and it is the only list. Two divergent copies of it used to exist,
+each missing what the other had.
+
+| Test | Contract it holds |
+|---|---|
+| `flowChatTailFollow.test.ts` | the follow target, `pin-turn-top`, `hold-tail` |
+| `flowChatCollapseMotion.test.ts` | collapse does not move earlier content |
+| `useFlowChatFollowOutput.test.tsx` | the frame loop, user-controlled blank, resize realign |
+| `../../tool-cards/useToolCardHeightContract.test.tsx` | tool cards reflow rather than compensate |
+| `flowChatHistoryBoundary.test.ts` | the screenful lead, and the latch's own predicate |
+| `flowChatLiveTailWindow.test.ts` | "does the transcript still reach the newest Turn" |
+| `flowChatViewportAnchor.test.ts` | anchor geometry and the DOM contract |
+| `useFlowChatViewportAnchor.test.tsx` | capture, restore, carry, the settle window |
+| `VirtualMessageList.session-boundary.test.tsx` | prepend compensation and the ask |
+| `ModernFlowChatContainer.history-state.test.tsx` | history presentation and the submission event |
+| `flowChatViewportOwnership.test.ts` | the priority order, preemption, expiry |
+| `../../../infrastructure/diagnostics/flowChatViewportDiagnostics.test.ts` | coalescing, placement sampling, the switch |
+| `useFlowChatVirtualizer.test.ts` | the offsets-and-positions boundary |
+| `useFlowChatVirtualizer.measurement.test.tsx` | `measureRenderedItems` against a real virtualizer |
+| `useFlowChatVirtualizer.aim.test.tsx` | the re-aim, and giving it up on takeover |
+| `VirtualMessageList.layout.test.ts` | the item-height estimate and the spacer |
+
+## Manual
+
+**Agents must not perform UI interaction verification.** Report these as pending
+unless a human confirms them. They are grouped so that adding a check to one
+group does not renumber the others.
+
+### Opening a session
+
+1. Session open lands at the end of the transcript, not inside the spacer.
+2. Open a long `isPartial` session and leave it alone. Nothing may page in
+   behind the reveal: the transcript opens on its loaded tail and stays there.
+   Five pages arriving over 890ms is what this checks for, and the reveal only
+   hides the first frame of it.
+3. Open a long session and check the scrollbar thumb: its size should be close
+   to right on the first painted frame, and it should not jump as items
+   measure. This is the per-item estimate doing its job, and it is the single
+   most visible symptom if the estimate ever regresses.
+4. Session switching and history paging do not restore stale footer height.
+
+### Submitting and pinning
+
+1. A newly submitted Turn opens at the viewport top with room below it.
+2. Send a one-line message and let it pin. It must come to rest at the top with
+   the same small gap above it as the very first Turn of the session, and the
+   pin must hold steady rather than creeping down — a pinned offset past the
+   end of the scroll range is clamped, and the follow loop will rewrite it
+   every frame.
+3. Scroll down into the blank and let go right after submitting a short Turn:
+   it returns that Turn to the viewport top, not to the content end.
+4. Send a message from the live tail, and again while parked deep in history.
+   Both must end with the new Turn at the viewport top; the second also has to
+   leave the history window to get there.
+5. Send a message, let it pin, then roll it back from its own message actions.
+   The transcript must come to rest with the surviving last Turn at the
+   *bottom* — not with it pinned to the top, which is what reading the
+   truncation as an arrival used to do.
+6. Roll a Turn back from further up a transcript, having scrolled to reach it.
+   The surviving last Turn must end at the bottom here too — scrolling to reach
+   the button hands the viewport to the reader, and the answer has to run
+   anyway. Leaving it to the anchor is what showed Turns 2..6 of an 8-Turn
+   session with the new last Turn's answer below the fold.
+7. Edit a message and rerun it. There must be one movement, not two — the
+   truncation is silent and the rerun's Turn pins as usual.
+
+### Streaming and follow
+
+1. Streaming follows the tail until the user scrolls, and the pinned Turn hands
+   off once its answer overflows the viewport.
+2. With output streaming, scroll up and hold still. Follow must not write while
+   the gesture is recent, and must resume once it goes quiet.
+3. Jump to latest from a screen or two up is animated rather than an instant
+   jump. It must glide the whole way, with at most a small catch-up for content
+   that arrived while it travelled — a stand-down counted in frames rather than
+   milliseconds used to cut this short.
+4. Jump to latest from the top of a long transcript lands outright. Half an
+   animation followed by a jump is the failure to look for, and it is what the
+   distance cap exists to prevent; `followOutput.jumpBehavior` says which of the
+   two was chosen and how many viewports away the target was.
+5. While reading a history window, let output arrive from somewhere else. The
+   viewport must not move — this is the case the submission event exists to
+   stay out of.
+6. Watch a Markdown answer stream past the bottom of the viewport. It must
+   scroll rather than step: no move of a whole line, and none of the ease's
+   lag left behind once the stream stops.
+7. Stream a burst — a code fence or a table arriving at once — and confirm it
+   goes the whole way in one move rather than gliding through content nobody
+   has seen, and that the jump-to-latest bar does not flash while it does.
+8. Turn on `prefers-reduced-motion` and stream again. The follow must step
+   straight to its target, as it did before the ease.
+
+### Collapse
+
+1. An auto-collapsing TodoWrite or ExecCommand card leaves earlier content
+   visually still.
+2. Expand and collapse a tall tool card near the top of the viewport, and one
+   below it, and confirm earlier content stays put in both cases.
+
+### The user-controlled reserved blank
+
+1. Scrolling down into the reserved blank and letting go leaves the viewport at
+   the user's chosen offset; it must not return automatically.
+2. Pressing End scrolls to the bottom of the scroll range and stays there until
+   an explicit follow action occurs.
+3. Scroll to the very bottom and confirm the transcript ends where content
+   ends, with the reserved blank below it reachable but not where the session
+   opens.
+4. Wheel down into the reserved blank and stop. The transcript must remain
+   still and the jump-to-latest affordance must stay available.
+5. With a short Turn pinned, scroll up and jump to latest. The explicit jump
+   must still return to the pin rather than the physical bottom of the spacer.
+
+### Output catching up with a reader in the blank
+
+1. Send a message so a short Turn pins with blank below it, then wheel up a
+   little — far enough to leave the tail, not far enough to push the blank off
+   screen — and take your hand off. As the answer grows past the bottom edge the
+   transcript must resume following, easing rather than snapping, and the
+   jump-to-latest affordance must disappear with it.
+2. The same scroll, but keep wheeling. The transcript must not take the viewport
+   back mid-gesture, and once you are above the end of content it must leave you
+   there however much more arrives — until you go back down yourself.
+3. Scroll up past the end of content, stop, and let output arrive. Nothing may
+   move. This is the case the rule must never claim.
+4. From there — above the end of content, follow long gone — scroll back *down*
+   until the blank shows again and stop. Follow must resume as output reaches
+   the bottom edge. Repeat it a third time. Nothing about this is once-only.
+5. With no blank on screen at all — a transcript that fills the viewport, mid
+   answer — scroll up a little. Follow must not resume until you bring the blank
+   back on screen; nothing was crossed.
+
+### The scrollbar
+
+1. Drag the scrollbar to the very bottom. The screen must not be entirely
+   blank: the last Turn and the input clearance stay visible above the
+   reservation. Repeat with the composer expanded, which is where the reserve
+   falls back to the hold-gap floor.
+2. Drag the scrollbar, without touching the wheel first, down into the reserved
+   blank and let go: it must stay there. Then drag it while output streams: the
+   transcript must follow the thumb without the frame loop fighting it. A press
+   on the thumb that moves nothing must leave the viewport alone.
+
+### Resizing
+
+1. With the viewport resting at the end but *not* following — scroll away and
+   back, and check the jump-to-latest affordance is hidden — resizing the
+   window keeps content against the bottom in every direction: taller reveals
+   more history above, shorter does not cut the last lines off, and narrower
+   does not push them off screen as the text rewraps. Repeat while reading
+   history: nothing should move.
+
+### History paging
+
+1. Open a session long enough to be `isPartial` — the loaded tail is shorter
+   than the viewport, so it pages older Turns in on its own. No jump-to-latest
+   bar should appear, and streaming output should be followed. Then send a
+   message: it must appear immediately and pin to the viewport top, with the
+   history above neither moving nor reloading.
+2. Scroll up to a junction. **One** page loads, the Turn under the cursor stays
+   where it is, and paging stops until the head is reached again. Then keep
+   going: every junction must behave the same way all the way to the first
+   Turn, with no run of pages and no point where scrolling up stops doing
+   anything.
+3. Open a long `isPartial` session and scroll up slowly through several paging
+   junctions. The Turn under the cursor must not move — not backwards, not
+   forwards, and not for a single frame. A stall while a page is measured is a
+   known gap and reads differently from a jump: the picture freezes and
+   resumes in place, rather than showing different content and snapping back.
+   Then scroll up fast through the same junctions, which is where the anchor
+   and the user's gesture are most likely to disagree.
+4. During that scroll, check that a paging junction does not leave the viewport
+   stuck: keep scrolling past it, then wheel back down, and confirm the
+   transcript still tracks the gesture in both directions. Nothing on screen may
+   fade or slide as rows come back — a row entering the rendered window is not
+   its content arriving.
+5. Navigate to the first Turn of a long session, then jump to latest. The tail
+   window it lands on can be short enough to fit inside the viewport, which
+   puts the whole scroll range inside the reserved blank. Scroll up from there:
+   history must load. This is the case where the reader is at the top, so the
+   wheel emits no scroll event and the gesture is the only thing to go on.
+6. In an `isPartial` session that paged on open and is now streaming, scroll
+   down into the reserved blank and use jump-to-latest to return. No history
+   status may appear at either end of the transcript — the transcript already
+   reaches the newest Turn, so there is nothing past its bottom to load. This
+   is the case that showed "preparing the conversation history" under a
+   complete transcript, permanently, and survived cancelling the Turn.
+
+### Turn navigation
+
+1. Turn Rail and Usage Report navigation can top-align the final Turns.
+2. Click the last Turn on the Turn Rail while it is short. It must land in one
+   movement at the end of the transcript — no top-align followed by a slide
+   back down. Do it from near the tail *and* from the top of a long session:
+   those are the rendered and unrendered branches, and they take different
+   paths. Then click a final Turn whose answer is longer than the viewport: it
+   must still top-align.
+3. Navigate to a Turn from the Turn Rail — a near one, a far one, and one close
+   enough to the end that the window loaded for it reaches the newest Turn. All
+   three must come to rest on that Turn at the viewport top and stay there.
+4. Navigate to a far Turn and start scrolling with the wheel before it comes to
+   rest. The gesture wins immediately and nothing pulls the viewport back to
+   the Turn afterwards, including several seconds later.
+5. From the Session Usage report, click a tool call and a slow span. Each must
+   come to rest with that item centred, in **one** movement — no landing on the
+   Turn followed by a slide onto the item a few frames later.
+6. **While a Turn is streaming**, click a Turn well up the history. It must land
+   on that Turn and stay there — not drift back to where you were reading half a
+   second later, which is when the navigation's hold lapses. Then click the same
+   Turn again from where you land: the second and later clicks used to fail
+   where the first appeared to work.
+7. While a Turn is streaming, scroll up with the wheel and let it stop. The
+   viewport stays where the gesture left it. Repeat several times in a row and
+   keep going after streaming ends: the failure was a scroll that came to rest
+   and was then returned, in full, to where that gesture had started.
+8. Scroll **down** through a long answer in several flicks, in a session with
+   enough history to keep re-measuring. Each flick keeps its distance — the
+   failure was arriving and then sliding back part of the way, every time, so
+   that a given point in the transcript could not be passed at all.
diff --git a/src/web-ui/src/flow_chat/components/modern/FLOWCHAT_VIEWPORT_REGISTER.md b/src/web-ui/src/flow_chat/components/modern/FLOWCHAT_VIEWPORT_REGISTER.md
new file mode 100644
index 0000000000..f254bcddcf
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/modern/FLOWCHAT_VIEWPORT_REGISTER.md
@@ -0,0 +1,312 @@
+# FlowChat Viewport Register
+
+Every deliberate write to the FlowChat scroller goes through one register, which
+decides whether the writer may act. This document covers the register, what it
+replaced, the two writers that stand outside it, and the trail it leaves.
+
+## Who May Move the Viewport at All
+
+Continuous movement belongs to `useFlowChatFollowOutput`; one-shot navigation
+belongs to `VirtualMessageList`. The virtualizer never follows output. Card
+renderers and tool cards must not write the outer FlowChat `scrollTop` — local
+scroll surfaces inside a thinking, explore, terminal, or subagent card may
+manage their own scroll position, but they must not dispatch an outer viewport
+compensation request.
+
+## The Register and Its Order
+
+Every deliberate write goes through `useFlowChatViewportOwner`, which asks
+`flowChatViewportOwnership.ts` whether the writer may act. The order is the
+design:
+
+| | Owner | Held while |
+|---|---|---|
+| 1 | `user-gesture` | 200ms from the last wheel, touch, key, or scrollbar press |
+| 2 | `one-shot-navigation` | a Turn, search hit, or focus request is being reached |
+| 3 | `follow-output` | the continuous writer owns the viewport |
+| 4 | `layout-correction` | the scroller's box changed and a resting viewport is re-aligned |
+
+The register decides **whether**, never **where** — targets stay with the writer
+that owns them, and the anchor's correction stays idempotent. Ordering answers
+what idempotency cannot: whether a movement was ours on purpose or something to
+be undone.
+
+**Repairing a displacement is not on this list**, and putting it there was a
+mistake worth keeping recorded. The prepend compensation and the viewport anchor
+both use `viewportOwner.shift` — see *A Displacement Is Not a Movement* in
+`FLOWCHAT_HISTORY_PAGING.md`.
+
+**Taking ownership and writing are one call.** Adding a writer without declaring
+it means not using the helper, which is visible in review — the register keeps
+the deliberate movement owners explicit and leaves user-controlled positions
+alone until another explicit action takes the viewport.
+
+**Only an owner that releases may hold the viewport indefinitely**, and
+follow-output is the only one — a claim with no expiry and no release is a
+viewport nothing below it can ever write again. Every other writer states its
+own window: a gesture goes quiet, an animation may never report completion, a
+re-aim runs while measurements settle. Saying nothing means the write is
+instantaneous and owns only itself, which is what a correction wants; the claim
+still resolves against whoever holds the viewport, because that is the question
+deciding whether the write happens at all.
+
+The first thing this caught was its own: the virtualizer places the scroller
+against its own state on mount, before any aim of ours exists. That 0px write
+was attributed to a navigation and took an unbounded claim, so follow-output was
+refused for the whole opening reveal and a long session opened at the head of
+its loaded window instead of on the newest Turn. A library write nobody asked
+for is now attributed to `layout-correction`, which is what it is.
+
+**The opening reveal is not an owner.** It is a phase, and the thing moving the
+viewport during it is follow-output, so a claim standing in for the reveal would
+outrank follow-output and refuse it. One slot cannot hold a phase and a writer
+at once, so the reveal remains an explicit condition beside the register.
+
+Not everything collapsed into it, and the difference is worth keeping straight.
+`smoothScrollFramesRef` is follow-output yielding to *its own* animation, which
+is intra-owner; `settleFramesRef` is a frame budget; `boundaryArmedRef` is paging policy.
+Only the parts that were really answering "is someone else moving the viewport"
+are gone.
+
+## What Counts as a Gesture
+
+Ordinary `scroll` events do not transfer viewport ownership; only explicit
+wheel, touch, or keyboard navigation exits follow-output. Once a reader takes
+the viewport, resting inside the reserved blank does not hand it back.
+
+A scrollbar drag is the one exception, and the press is what makes it one: a
+pointer held past the content box's trailing edge is on the bar, so the
+scrolling it causes *is* intent. The press only arms it — `scrollbar-gutter:
+stable` keeps the gutter reserved whether or not a bar is drawn there, so a
+press that scrolls nothing changes nothing. Unqualified, a drag never released
+the viewport: measured on WebView2, follow-output rewrote its target against the
+thumb every frame for a 100px oscillation. Recognising the drag transfers
+ownership to the reader, and their resting position is preserved.
+
+## Reaching a Turn Is One Shot
+
+One-shot Turn, search and history navigation lives in `VirtualMessageList`, and
+holds `one-shot-navigation` for as long as it is still arriving.
+
+**Alignment is asked for, not computed, wherever it fits.** A navigation
+correcting its own scroll must re-issue through the virtualizer, never by
+writing the scroller. The virtualizer keeps re-aiming at its last target for as
+long as the measurements under it move, and only another scroll issued through
+it replaces that. Writing the scroller directly is what left the tail Turn
+top-aligning, being pulled to the content end, and being re-aimed at the top
+again.
+
+**The clamp branches on what is knowable, not on where the Turn is.** A rendered
+Turn resolves its own offset, so the decision is made before anything moves and
+the requested `behavior` survives. An unrendered one is known only to the
+virtualizer, so it is placed with `behavior: 'auto'` and the landing read back;
+an animated placement would not have arrived yet, so there would be nothing to
+read. Both writes land in the same task, so the correction costs a second scroll
+but not a second visible movement.
+
+**Turn navigation never scrolls into the reserved blank to top-align a Turn.** A
+Turn whose top lies past the content end is stopped at the content end instead,
+which is where the tail rests. The blank belongs to follow-output — `pin-turn-top`
+holds it for output that is arriving, and nothing arrives under a Turn the user
+navigated to. There is no "is this the last Turn" test and no measurement of
+what lies below it: a Turn with a viewport of content under it has its top above
+the content end already, so the clamp does not bind and the final Turns of a
+long transcript still top-align. Before the resident spacer the browser did this
+for free by clamping at the end of the scroll range.
+
+**Top-aligning a Turn aims at `FLOWCHAT_TURN_TOP_GAP_PX` above its user
+message**, not at the message itself. The first Turn already sits below that gap
+for free, because `.message-list-header` occupies it at the head of the scroll
+content; every other Turn used to land flat on the top edge, and the two read as
+different alignments. The header renders at the same constant so they cannot
+drift. Both the one-shot scroll and the offset the follow loop re-asserts every
+frame carry it — if only one did, they would fight.
+
+**A gesture preempts a navigation still in flight, and ends it.** The library's
+re-aim keeps computing for up to 5s after the aim that started it, recomputing
+the target offset from measurements that are still landing and writing again
+whenever it moves.
+
+Refusing those writes is not enough, and this is the one place the register's
+guarantee stops short on its own. The refusal is invisible to the library — it
+has no return value to read — so it keeps its schedule either way, and the
+gesture's hold is `USER_DRIVEN_SCROLL_WINDOW_MS`, 200ms after the last wheel
+notch. A measurement landing after the reader has stopped, and inside the
+remaining five seconds, is granted. Measured on a rail click into a long
+history window: placed at 5358, the reader took over 6ms later, and 12ms after
+that the re-aim asked for 7784 and was refused — with nothing having ended it.
+
+So `notifyUserScrollIntent` gives the aim up outright, through `cancelAim`. It
+aims at the offset the scroller already holds: an offset aim carries no index,
+the re-aim recomputes its target *from* the index, and writing again is the only
+thing it does when that target changes. The library's `scrollState` is private,
+and a cast into it is the kind of thing a version bump breaks silently.
+
+The cost is accepted, and it is what the reader asked for: a distant navigation
+the wheel brushes stops where it is and is not corrected further. In the
+measured case that is 2460px short of the Turn that was clicked — the placement
+is deliberately approximate, and the re-aim is what would have finished it.
+
+**A hold postpones a corrector; it does not cancel one.** Standing down for the
+register keeps a correction from landing while the hold is live, and hands it
+over intact the moment the hold lapses. Where the movement being held off was a
+*change of intent* rather than a displacement, that is not what was wanted, and
+the register cannot know the difference — it ranks writers, it does not carry
+meaning. Whoever changes the intent has to say so: a Turn navigation drops the
+viewport anchor before it aims, because otherwise the anchor spends the hold
+waiting and then undoes the jump. Measured over four clicks on one Turn: 1653px
+back, four times out of four, each on the first frame after
+`ONE_SHOT_NAVIGATION_HOLD_MS` lapsed.
+
+This is also why a placement's outcome is sampled *after* the hold rather than
+inside it. `turnNavigation.placed.outcome` used to read back at 400ms against a
+600ms hold and reported `driftPx: 0` on a placement that was dragged 1653px away
+11ms later — the probe could not see the one thing the hold was postponing.
+
+## Why There Was No Coordinator Before, and What Changed
+
+There was one — `FlowChatViewportCoordinator.ts`, removed alongside the
+compensation engine, and it was a compensation engine itself: reservations,
+pin and collapse compensation, element-anchor leases, a synthetic bottom range.
+Nothing here does any of that.
+
+The argument recorded against replacing it was that single-writer semantics were
+unreachable, because the virtualizer writes `scrollTop` from inside the library —
+its own re-aim, and its adjustment for a re-measured item — so a coordinator
+could only serialise *our* writes while the conflicts in practice were with that
+third writer. Two things retired that premise:
+
+- The library's adjustment for a re-measured item is **off**
+  (`shouldAdjustScrollPositionOnItemSizeChange`), because it replayed a delta
+  against a scroll offset it learns about a frame late.
+- **`scrollToFn` is a first-class virtualizer option.** Every write the library
+  makes — `scrollToIndex`, `scrollToOffset`, and the re-aim that follows them —
+  goes through a function we supply, so it is registered like any other.
+
+What remains outside the register is the reader and the browser, and browser
+scroll anchoring is off. A library write is attributed to whoever asked for the
+aim, which is also what lets a gesture preempt a navigation still chasing its
+Turn.
+
+## Diagnosing the Viewport
+
+Viewport faults are intermittent, leave nothing in the DOM once they are over,
+and read identically to two or three other causes: a Turn that lands and is
+dragged away and a Turn that never landed are the same complaint. So the trail
+is permanent, in `flowchat.log`, behind `app.logging.flow_chat_diagnostics` —
+the same switch history paging uses — and tagged `viewport`.
+
+`flowChatViewportDiagnostics.ts` records two different kinds of thing:
+
+| | Where | What |
+|---|---|---|
+| **Writes** | the register, `viewportOwner.write` / `.claim` / `.release` | who moved the viewport, from where to where, and **who was refused** |
+| **Decisions** | each writer | why it wanted to move, and why it did not |
+
+The second half is the one that pays. A write that never happened leaves nothing
+at the register to find, and "nothing happened" has been the report more often
+than a wrong move has: a deferred new Turn, an anchor whose Turn left the
+rendered window, a boundary declined because the transcript was opening, or a
+boundary that never re-armed. Each of those is now one line saying
+which.
+
+**A placement is recorded with what became of it.** `traceViewportPlacement`
+samples the offset on the next frame and again once things have settled, and
+reports the drift from the target. Read against the register's writes in the
+same window, the drift says *who* took it away. Every deliberate write now goes
+through the register; the two that did not are both gone, and what the sampling
+found before they went is worth keeping, because in both cases it was not what
+the probe was written to catch.
+
+**The focus request was overriding, not overridden.** A usage-report click
+lands a Turn navigation through the register and then centres the flow item
+that was actually clicked — a tool call inside the Turn. The comment on the
+second write predicted the anchor undoing it, since a focus request carries no
+gesture. It never did: measured over four clicks the anchor stood down 93 times
+and the register refused nothing, and the two item aims drifted 0px. The drift
+was on the *first* write. The Turn navigation settled 178px and 334.7px from
+where it had put itself, because the item aim arrived 41ms — three frames —
+later, and `nextFramePx` equalled the Turn placement both times, so the reader
+watched the transcript land and then move. The aim now goes through
+`focusFlowItem` on the list, which is a register write, and is attempted in the
+same task as the Turn navigation so that only the final position is painted.
+When the item is not rendered yet the retry loop still runs, and the Turn
+placement is what is on screen until it lands — that part is unavoidable.
+
+**The sticky Task indicator had never run at all.** Its selector wanted
+`.flowchat-flow-item[data-flow-item-id][data-tool-name]` on one element, and
+`data-tool-name` has only ever been on the tool card *inside* that wrapper —
+added two months later, by a commit adding e2e locators, for an unrelated
+reason. So its probe could not have fired either, which is why there was no
+evidence rather than no problem. Deleted; if the affordance is wanted again it
+needs registering as well as fixing.
+
+`traceViewportPlacement` stays for the next writer that has to sit outside the
+register, and for what it proved here: read against the register's writes, it
+answers *which of two placements won* as readily as *who undid one*.
+
+Everything here can fire on every frame, so repeated identical events collapse
+into one entry per 500ms carrying the count and travel it stands for. The key
+includes whatever makes one run a different run — the owner, the outcome, the
+direction — so a *transition* always emits immediately. A thousand copies of a
+steady state would only bury the transitions, which are the point.
+
+**A duration is reported once, when it ends.** Coalescing is what makes the
+per-frame traces readable, and it is also why they cannot answer "how long did
+that last": only the first of a run is emitted, and the rest are a count.
+`anchor.turnReturned` and `anchor.waitAbandoned` therefore report the whole of a
+wait for the anchored Turn — milliseconds, settle frames, restore attempts, and
+the reader travel carried through it — at the one moment the whole of it exists.
+That wait is what decides whether a junction is seen, so it is the number to
+read first. These are the only traces here that go through `traceViewport`
+rather than the coalescer, because they fire once per wait and their payload is
+the point rather than a sample of it.
+
+**Read the state out before the state changes.** A `data` callback is evaluated
+by `flowChatDiagnostics.trace`, synchronously, so a thunk over refs is normally
+exactly right. It is not right when the caller resets those refs on the next
+line, and the wait report does: it takes its numbers eagerly and closes over
+them.
+
+**Two numbers say whether a correction was a mistake.** `scrollRangePx` is
+recorded on `prependCompensated` and on every `anchor.correct`, because a
+correction and the reason for one read the same otherwise. Measured over five
+junctions, the correction equalled the change in the scroll range every time
+(−94/−93.4, +76/+76.5, +26/+30.7, +8/+7.6): the compensation had not over-shot,
+the transcript above the reader had re-measured, and the anchor was following
+it. A correction with the range *unchanged* would be the other diagnosis.
+
+Nothing evaluates a payload while the switch is off.
+
+### Reading the log
+
+```text
+pnpm run flowchat:log:analyze -- <path-to-flowchat.log> [--around <sequence>]
+```
+
+`scripts/diagnostics/analyze-flowchat-log.mjs` reports, in this order:
+
+1. **Episodes** of viewport activity, worst *churn* first — travel per pixel of
+   progress. A clean move is 1; a much larger number distinguishes "it moved
+   wrongly" from "two writers fought".
+2. **Placements that did not stick**, ranked by drift. A placement with no
+   outcome sampled is listed separately rather than counted as clean.
+3. **Refusals**, as owner × who outranked them.
+4. **Declines**, as writer × reason.
+
+Two things it is careful about, because both would otherwise flatter the
+result: a coalesced entry is weighed by the run it stands for, not as one event;
+and dropped entries are reported at the top, since every count below one is a
+lower bound.
+
+The paging side of the same fault is traced separately; see *Diagnosing History
+Paging* in `FLOWCHAT_HISTORY_PAGING.md`.
+
+## Related Files
+
+- `flowChatViewportOwnership.ts`
+- `useFlowChatViewportOwner.ts`
+- `@/infrastructure/diagnostics/flowChatViewportDiagnostics.ts`
+- `VirtualMessageList.tsx`
+- `useFlowChatNavigation.ts`
+- `scripts/diagnostics/analyze-flowchat-log.mjs`
diff --git a/src/web-ui/src/flow_chat/components/modern/FLOWCHAT_VIRTUALIZATION.md b/src/web-ui/src/flow_chat/components/modern/FLOWCHAT_VIRTUALIZATION.md
new file mode 100644
index 0000000000..d53e741e2a
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/modern/FLOWCHAT_VIRTUALIZATION.md
@@ -0,0 +1,151 @@
+# FlowChat Virtualization
+
+What the virtualization library is allowed to decide, what stays ours, and the
+one rule about rendering that only makes sense once a row's lifetime is shorter
+than its content's.
+
+## What Belongs to the Virtualizer
+
+FlowChat virtualizes with **TanStack Virtual**, behind `useFlowChatVirtualizer.ts`.
+Nothing else imports it. The rest of FlowChat asks for offsets in scroller
+coordinates and gets them back; there is no index space of the virtualizer's own
+to convert at the edges, because measurements are cached against **item keys**,
+so a history prepend leaves every measured item exactly where it was.
+
+That is only half of what react-virtuoso's `firstItemIndex` did, and the other
+half has to be supplied — see *Keeping the Viewport on the Reader's Content* in
+`FLOWCHAT_HISTORY_PAGING.md`.
+
+The reason it is TanStack and not react-virtuoso is one line of its measurement
+pass: `size = measured ?? estimateSize(i)`. A per-item estimate for everything
+unmeasured. react-virtuoso reserves a single scalar (`lastSize`) for all of
+them, and this transcript alternates 38px user messages with model rounds up to
+5012px, so the scroll range was wrong by an order of magnitude until an item was
+actually measured. `estimateVirtualMessageItemHeightWithContext` now feeds it
+directly. The estimate is owned by the data shape in
+`virtualItemHeightEstimators.ts`: text, thinking, user messages, model rounds,
+Explore groups, and tool families each derive a bounded height from their
+content, status, width, and expansion state. This code is pure and runs before
+a row has a DOM node. Once mounted, DOM measurement remains authoritative and
+replaces the estimate. Width and volatile Explore expansion changes invalidate
+only the derived position pass; TanStack's key-based measured-size cache is
+retained.
+
+**Items stay in normal flow inside a padded window**, not absolutely positioned.
+Everything outside the window stands in as `padding-top` and `padding-bottom`
+(`virtualWindowPaddingPx`). This matters for more than tidiness: when an item
+inside the window changes height, the browser reflows the ones below it in the
+same layout pass, so there is no frame where the scroll has been corrected but
+the items have not moved yet.
+
+**The virtualizer does not use TanStack's own late-measurement adjustment.**
+`shouldAdjustScrollPositionOnItemSizeChange` reads the real scroller position
+and asks the viewport owner to apply the delta only when the whole item is above
+the viewport. A partly visible row is left alone because its changed content is
+inside what the reader is looking at. TanStack's adjustment is always refused:
+it applies its delta to `scrollOffset`, the library's copy refreshed only from
+scroll events. Every continuous writer here assigns `scrollTop` directly and
+the matching scroll event lands a frame later, so that base can be stale. The
+owner's displacement is applied before the new size enters the cache, while
+the anchor remains responsible for restoring relationships across larger layout
+transactions.
+
+The measurement decision is recorded as the switch-gated, coalesced
+`virtualizer.itemResize` probe: item identity, estimated and measured sizes,
+the above-viewport decision, and the real scroll geometry before and after the
+owner's displacement. It deliberately omits flow-item contents, which made the
+temporary investigation probe too large for a lasting diagnostic trail.
+
+**Measurement is forced before any position is read in the commit that changed
+the items.** The library skips its inline resize while the reader is scrolling,
+which is exactly when history arrives, so the cache holds reserved estimates
+until the ResizeObserver delivers a frame later.
+`virtualizer.measureRenderedItems()` does that reconciliation itself — the same
+work, a frame earlier, free for any row whose height was already right. The
+evidence and the numbers are in *A Displacement Is Not a Movement* in
+`FLOWCHAT_HISTORY_PAGING.md`.
+
+**Alignment is asked for, not computed, wherever it fits.** `scrollItemIntoView`
+goes through the virtualizer so that its re-aim keeps chasing the item while the
+measurements under it move; an offset computed once is already stale by then.
+The gap above a top-aligned Turn is the virtualizer's `scrollPaddingStart`, for
+the same reason. Only two places compute an offset by hand, and both do it
+because the target is not an item: the end of *real content*, which is above the
+resident tail spacer, and the end of a Turn.
+
+Two things that look like they belong here do not:
+
+- **Positions in `virtualItems`.** That array is FlowChat's own projection, so
+  an index into it means the same thing under any virtualizer. `scrollToIndex`,
+  `scrollToSearchMatch`, and `data-virtual-index` all carry one and are left
+  alone.
+- **When to page.** `historyBoundariesForVisibleRange` decides that a boundary
+  is worth asking about, from where the reader stands and nothing else. Its
+  thresholds are the ones that decide *where* a junction happens, which is why
+  they are named and tested rather than inline.
+
+**Visible is not rendered.** `getVisibleItemRange` intersects the rows with the
+scroller box; the rendered window carries overscan, and a transcript short
+enough to render whole reports the first *and* last item present wherever the
+viewport stands. Feeding the rendered window to a rule that means "has the
+reader arrived here" asks whether the item exists instead. Measured: a 21-item
+transcript rendered rows 0..20 from index 0 no matter where the reader was, so
+the head boundary read as reached forever. It has to be a callback rather than a
+value, because a scroll moves the viewport across the window without changing
+it.
+
+react-virtuoso remains a dependency: the file tree (`VirtualFileTree.tsx`) still
+uses it. Nothing under `flow_chat/` does.
+
+## The Projection Is the Stable Thing
+
+Stable virtual-item keys and projection identity are required. Do not split one
+`ModelRound` into multiple virtual items, and do not reclassify projection from
+a timer.
+
+`getVirtualItemStableKey` keys on type, Turn and content id — never on an index.
+That is what lets a prepend renumber every row without React unmounting any of
+them, and it is what the measurement cache is keyed on underneath.
+
+Tool cards reflow naturally and dispatch only `tool-card-toggle` after an
+expanded-state change, so the virtualizer can remeasure. There is no
+pre-collapse intent event and no per-card compensation.
+
+## A Row's Mount Is Not an Arrival
+
+**No mount or enter animation may live inside `.virtual-item-wrapper`**, no
+mount-triggered motion may change transcript geometry, and nothing may be keyed
+on a state change a scroll can replay.
+
+Outside a virtualized list an element's insertion means its content arrived, and
+a fade or a slide says so honestly. Here insertion means the row entered the
+rendered window. Paging up mounts the Turns the page brought, the rows the
+junction's own correction scrolls past, and every row the reader scrolls back
+over afterwards — each one replaying whatever its stylesheet attached to mount.
+`--streaming` to `--complete` is the same mistake in a different key: it fires
+when the typewriter finishes, which is not when the reader is looking.
+
+The one that shipped was `.markdown-renderer`, from the shared component
+library: `animation: fadeIn var(--bf-appearance-token-motion-base) ease-out`,
+350ms from `opacity: 0`. Once the junction displacement was down to tens of
+pixels that fade was the entire remaining complaint — most of the screen
+dimming and coming back on every page up. `VirtualItemRenderer.scss` cancels it
+for anything inside a row and leaves the library alone, where a markdown block
+really is mounted once.
+
+The rule is stated here because four correct local fixes could not reach it.
+`ModelRoundItem.scss` and `UserMessageItem.scss` each refuse an enter animation
+of their own, in comments that name this reason. `FlowTextBlock`'s typewriter
+refuses to replay on mount, because a streaming block that scrolled out and
+back would restart from an empty string and re-grow. `FlowTextBlock.scss`
+cancels this very fade — but only under `.streaming`, so the one block still
+being written was exempt and the whole of history was not. Each author saw the
+defect, guarded their own file, and had no way to guard a component in another
+package.
+
+## Related Files
+
+- `useFlowChatVirtualizer.ts`
+- `virtualMessageListLayout.ts`
+- `VirtualItemRenderer.tsx` + `.scss`
+- `VirtualMessageList.tsx`
diff --git a/src/web-ui/src/flow_chat/components/modern/FlowChatCollapseAlignment.test.ts b/src/web-ui/src/flow_chat/components/modern/FlowChatCollapseAlignment.test.ts
index b40a5c4ff1..32cb3ce771 100644
--- a/src/web-ui/src/flow_chat/components/modern/FlowChatCollapseAlignment.test.ts
+++ b/src/web-ui/src/flow_chat/components/modern/FlowChatCollapseAlignment.test.ts
@@ -114,13 +114,3 @@ describe('FlowChat collapse spacing', () => {
     );
   });
 });
-
-describe('FlowChat initial projection alignment', () => {
-  it('reserves the Virtuoso scrollbar gutter in the handoff overlay', () => {
-    const stylesheet = readSource('./VirtualMessageList.scss');
-
-    expect(stylesheet).toMatch(
-      /&__projection-handoff-overlay\s*\{[\s\S]*?scrollbar-gutter:\s*stable;/,
-    );
-  });
-});
diff --git a/src/web-ui/src/flow_chat/components/modern/FlowChatHeader.scss b/src/web-ui/src/flow_chat/components/modern/FlowChatHeader.scss
index 6befe113e7..364b044180 100644
--- a/src/web-ui/src/flow_chat/components/modern/FlowChatHeader.scss
+++ b/src/web-ui/src/flow_chat/components/modern/FlowChatHeader.scss
@@ -8,44 +8,20 @@
   justify-content: space-between;
   gap: $size-gap-1;
   padding: 0 $size-gap-3;
-  border-bottom: 1px dashed var(--bf-appearance-token-border-base);
+  border-bottom: 1px solid var(--bf-appearance-token-border-base);
+
+  // Opaque bar stacked above the message list, so message geometry stays
+  // independent of the header.
+  background: var(--bf-appearance-token-color-bg-scene);
 
-  // Frosted glass effect.
-  background: color-mix(in srgb, var(--bf-appearance-token-color-bg-elevated) 45%, transparent);
-  backdrop-filter: blur(20px) saturate(1.3);
-  -webkit-backdrop-filter: blur(20px) saturate(1.3);
-  
   height: 36px;
   min-height: 36px;
   flex-shrink: 0;
-  transition: all $motion-base $easing-standard;
+  transition:
+    background-color $motion-base $easing-standard,
+    border-color $motion-base $easing-standard;
   position: relative;
   z-index: 10;
-  
-  // ==================== Bottom gradient blur ====================
-  &::after {
-    content: '';
-    position: absolute;
-    left: 0;
-    right: 0;
-    top: 100%;
-    height: 16px;
-    pointer-events: none;
-    
-    background: linear-gradient(
-      to bottom,
-      color-mix(in srgb, var(--bf-appearance-token-color-bg-elevated) 35%, transparent) 0%,
-      color-mix(in srgb, var(--bf-appearance-token-color-bg-elevated) 20%, transparent) 35%,
-      color-mix(in srgb, var(--bf-appearance-token-color-bg-elevated) 8%, transparent) 65%,
-      transparent 100%
-    );
-
-    backdrop-filter: blur(8px);
-    -webkit-backdrop-filter: blur(8px);
-
-    mask-image: linear-gradient(to bottom, black 0%, transparent 100%);
-    -webkit-mask-image: linear-gradient(to bottom, black 0%, transparent 100%);
-  }
 
   &__btw-back {
     flex: 0 0 auto;
diff --git a/src/web-ui/src/flow_chat/components/modern/FlowChatHeader.tsx b/src/web-ui/src/flow_chat/components/modern/FlowChatHeader.tsx
index 6553cf9563..3cd97ede3c 100644
--- a/src/web-ui/src/flow_chat/components/modern/FlowChatHeader.tsx
+++ b/src/web-ui/src/flow_chat/components/modern/FlowChatHeader.tsx
@@ -464,9 +464,13 @@ export const FlowChatHeader: React.FC<FlowChatHeaderProps> = ({
     count: backgroundCommandCount,
   });
 
-  if (!visible || totalTurns === 0) {
+  // The header occupies a row above the message list, so its mount state must
+  // not depend on turn measurement: unmounting on a transient `totalTurns === 0`
+  // would resize the list mid-session. Only the centre message is withheld.
+  if (!visible) {
     return null;
   }
+  const hasTurnInfo = totalTurns > 0;
 
   return (
     <div
@@ -484,37 +488,39 @@ export const FlowChatHeader: React.FC<FlowChatHeaderProps> = ({
         <SessionFilesBadge sessionId={sessionId} />
       </div>
 
-      <Tooltip content={currentUserMessage} placement="bottom">
-        <div
-          className="flowchat-header__message"
-          data-bf-component="flow-chat-header"
-          data-bf-part="message"
-          role="button"
-          tabIndex={0}
-          onClick={onJumpToCurrentTurn}
-          onKeyDown={(e) => {
-            if (e.key === 'Enter' || e.key === ' ') {
-              e.preventDefault();
-              onJumpToCurrentTurn?.();
-            }
-          }}
-          aria-label={t('flowChatHeader.jumpToCurrentTurn', {
-            turn: currentTurn
-          })}
-        >
-          <span
-            className="flowchat-header__turn-badge"
-            aria-label={turnBadgeLabel}
+      {hasTurnInfo ? (
+        <Tooltip content={currentUserMessage} placement="bottom">
+          <div
+            className="flowchat-header__message"
             data-bf-component="flow-chat-header"
-            data-bf-part="turnBadge"
+            data-bf-part="message"
+            role="button"
+            tabIndex={0}
+            onClick={onJumpToCurrentTurn}
+            onKeyDown={(e) => {
+              if (e.key === 'Enter' || e.key === ' ') {
+                e.preventDefault();
+                onJumpToCurrentTurn?.();
+              }
+            }}
+            aria-label={t('flowChatHeader.jumpToCurrentTurn', {
+              turn: currentTurn
+            })}
           >
-            <span>{turnBadgeLabel}</span>
-          </span>
-          <span className="flowchat-header__message-text">
-            {truncatedMessage}
-          </span>
-        </div>
-      </Tooltip>
+            <span
+              className="flowchat-header__turn-badge"
+              aria-label={turnBadgeLabel}
+              data-bf-component="flow-chat-header"
+              data-bf-part="turnBadge"
+            >
+              <span>{turnBadgeLabel}</span>
+            </span>
+            <span className="flowchat-header__message-text">
+              {truncatedMessage}
+            </span>
+          </div>
+        </Tooltip>
+      ) : null}
 
       <div
         className="flowchat-header__actions"
diff --git a/src/web-ui/src/flow_chat/components/modern/FlowChatViewportCoordinator.test.ts b/src/web-ui/src/flow_chat/components/modern/FlowChatViewportCoordinator.test.ts
deleted file mode 100644
index a5a68e37d4..0000000000
--- a/src/web-ui/src/flow_chat/components/modern/FlowChatViewportCoordinator.test.ts
+++ /dev/null
@@ -1,532 +0,0 @@
-// @vitest-environment jsdom
-
-import { afterEach, describe, expect, it, vi } from 'vitest';
-import {
-  canHandoffPinnedItemToTail,
-  FlowChatViewportCoordinator,
-} from './FlowChatViewportCoordinator';
-
-function setRect(element: HTMLElement, top: number): void {
-  Object.defineProperty(element, 'getBoundingClientRect', {
-    configurable: true,
-    value: () => ({
-      bottom: top + 40,
-      height: 40,
-      left: 0,
-      right: 300,
-      top,
-      width: 300,
-      x: 0,
-      y: top,
-      toJSON: () => ({}),
-    }),
-  });
-}
-
-function setScrollerGeometry(scroller: HTMLElement, scrollTop: number): void {
-  Object.defineProperties(scroller, {
-    clientHeight: { configurable: true, value: 500 },
-    scrollHeight: { configurable: true, value: 2000 },
-    scrollTop: { configurable: true, writable: true, value: scrollTop },
-  });
-}
-
-afterEach(() => {
-  document.body.replaceChildren();
-  vi.restoreAllMocks();
-});
-
-describe('FlowChatViewportCoordinator', () => {
-  it('hands off after the pin drains or natural content reaches the viewport tail', () => {
-    expect(canHandoffPinnedItemToTail({
-      pinReservationPx: 1029,
-      collapseReservationPx: 0,
-      pendingStickyPinGrowthPx: 0,
-      hasPendingCollapseIntent: false,
-      viewport: {
-        scrollTop: 900,
-        clientHeight: 1000,
-        naturalContentHeight: 1899,
-      },
-    })).toBe(false);
-    expect(canHandoffPinnedItemToTail({
-      pinReservationPx: 1029,
-      collapseReservationPx: 0,
-      pendingStickyPinGrowthPx: 0,
-      hasPendingCollapseIntent: false,
-      viewport: {
-        scrollTop: 900,
-        clientHeight: 1000,
-        naturalContentHeight: 1900,
-      },
-    })).toBe(true);
-    expect(canHandoffPinnedItemToTail({
-      pinReservationPx: 1029,
-      collapseReservationPx: 200,
-      pendingStickyPinGrowthPx: 0,
-      hasPendingCollapseIntent: false,
-      viewport: {
-        scrollTop: 900,
-        clientHeight: 1000,
-        naturalContentHeight: 2000,
-      },
-    })).toBe(false);
-    expect(canHandoffPinnedItemToTail({
-      pinReservationPx: 1029,
-      collapseReservationPx: 0,
-      pendingStickyPinGrowthPx: 20,
-      hasPendingCollapseIntent: false,
-      viewport: {
-        scrollTop: 900,
-        clientHeight: 1000,
-        naturalContentHeight: 2000,
-      },
-    })).toBe(false);
-    expect(canHandoffPinnedItemToTail({
-      pinReservationPx: 1029,
-      collapseReservationPx: 0,
-      pendingStickyPinGrowthPx: 0,
-      hasPendingCollapseIntent: true,
-      viewport: {
-        scrollTop: 900,
-        clientHeight: 1000,
-        naturalContentHeight: 2000,
-      },
-    })).toBe(false);
-    expect(canHandoffPinnedItemToTail({
-      pinReservationPx: 0,
-      collapseReservationPx: 0,
-      pendingStickyPinGrowthPx: 0,
-      hasPendingCollapseIntent: false,
-      viewport: null,
-    })).toBe(true);
-  });
-
-  it('restores a collapsing card header to its captured viewport offset', () => {
-    const scroller = document.createElement('div');
-    scroller.dataset.virtuosoScroller = 'true';
-    const card = document.createElement('div');
-    scroller.append(card);
-    document.body.append(scroller);
-    setScrollerGeometry(scroller, 900);
-    setRect(scroller, 0);
-    setRect(card, 120);
-
-    const coordinator = new FlowChatViewportCoordinator();
-    expect(coordinator.preserveElement(card)).toBe(true);
-
-    setRect(card, 80);
-    expect(coordinator.restoreElementAnchor(scroller)).toBe(true);
-    expect(scroller.scrollTop).toBe(860);
-  });
-
-  it('does not let automatic tail follow replace a preserved card anchor', () => {
-    const scroller = document.createElement('div');
-    scroller.dataset.virtuosoScroller = 'true';
-    const card = document.createElement('div');
-    scroller.append(card);
-    document.body.append(scroller);
-    setScrollerGeometry(scroller, 900);
-    setRect(scroller, 0);
-    setRect(card, 120);
-
-    const coordinator = new FlowChatViewportCoordinator();
-    coordinator.preserveElement(card);
-
-    expect(coordinator.followTail()).toBe(false);
-    expect(coordinator.getMode()).toBe('preserving-element');
-    expect(coordinator.followTail({ force: true })).toBe(true);
-    expect(coordinator.getMode()).toBe('following-tail');
-  });
-
-  it('retains a settled card anchor without a wall-clock expiry', () => {
-    const scroller = document.createElement('div');
-    scroller.dataset.virtuosoScroller = 'true';
-    const card = document.createElement('div');
-    scroller.append(card);
-    document.body.append(scroller);
-    setScrollerGeometry(scroller, 900);
-    setRect(scroller, 0);
-    setRect(card, 120);
-
-    const now = vi.spyOn(performance, 'now').mockReturnValue(1_000);
-    const coordinator = new FlowChatViewportCoordinator();
-    expect(coordinator.preserveElement(card)).toBe(true);
-    expect(coordinator.settleElementPreservation('test-settled')).toBe(true);
-
-    now.mockReturnValue(60_000);
-    expect(coordinator.ownsElementAnchor()).toBe(true);
-    expect(coordinator.getMode()).toBe('preserving-element');
-
-    setRect(card, 80);
-    expect(coordinator.restoreElementAnchor(scroller, 'test-delayed-layout')).toBe(true);
-    expect(scroller.scrollTop).toBe(860);
-  });
-
-  it('allows automatic tail follow to take ownership from a retained anchor', () => {
-    const scroller = document.createElement('div');
-    scroller.dataset.virtuosoScroller = 'true';
-    const card = document.createElement('div');
-    scroller.append(card);
-    document.body.append(scroller);
-    setScrollerGeometry(scroller, 900);
-    setRect(scroller, 0);
-    setRect(card, 120);
-
-    const coordinator = new FlowChatViewportCoordinator();
-    coordinator.preserveElement(card);
-    coordinator.settleElementPreservation('test-settled');
-
-    expect(coordinator.followTail()).toBe(true);
-    expect(coordinator.getMode()).toBe('following-tail');
-    expect(coordinator.ownsElementAnchor()).toBe(false);
-  });
-
-  it('releases a retained anchor when its DOM element disconnects', () => {
-    const scroller = document.createElement('div');
-    scroller.dataset.virtuosoScroller = 'true';
-    const card = document.createElement('div');
-    scroller.append(card);
-    document.body.append(scroller);
-    setScrollerGeometry(scroller, 900);
-    setRect(scroller, 0);
-    setRect(card, 120);
-
-    const coordinator = new FlowChatViewportCoordinator();
-    coordinator.preserveElement(card);
-    coordinator.settleElementPreservation('test-settled');
-    card.remove();
-
-    expect(coordinator.ownsElementAnchor()).toBe(false);
-    expect(coordinator.getMode()).toBe('idle');
-  });
-
-  it('does not let a stale element-anchor lease release a newer preservation transaction', () => {
-    const scroller = document.createElement('div');
-    scroller.dataset.virtuosoScroller = 'true';
-    const firstCard = document.createElement('div');
-    const secondCard = document.createElement('div');
-    scroller.append(firstCard, secondCard);
-    document.body.append(scroller);
-    setScrollerGeometry(scroller, 900);
-    setRect(scroller, 0);
-    setRect(firstCard, 120);
-    setRect(secondCard, 180);
-
-    const coordinator = new FlowChatViewportCoordinator();
-    const firstLease = coordinator.preserveElementWithLease(firstCard);
-    const secondLease = coordinator.preserveElementWithLease(secondCard);
-
-    expect(firstLease).not.toBeNull();
-    expect(secondLease).not.toBeNull();
-    expect(coordinator.releaseElementPreservationLease(
-      firstLease!,
-      'stale-request-finished',
-    )).toBe(false);
-    expect(coordinator.ownsElementAnchor()).toBe(true);
-    expect(coordinator.releaseElementPreservationLease(
-      secondLease!,
-      'current-request-finished',
-    )).toBe(true);
-    expect(coordinator.getMode()).toBe('idle');
-  });
-
-  it('keeps a pinned item anchored until follow mode takes ownership', () => {
-    const scroller = document.createElement('div');
-    scroller.dataset.virtuosoScroller = 'true';
-    const item = document.createElement('div');
-    scroller.append(item);
-    document.body.append(scroller);
-    setScrollerGeometry(scroller, 700);
-    setRect(scroller, 0);
-    setRect(item, 57);
-
-    const coordinator = new FlowChatViewportCoordinator();
-    expect(coordinator.pinElement(item)).toBe(true);
-
-    setRect(item, 87);
-    expect(coordinator.restoreElementAnchor(scroller)).toBe(true);
-    expect(scroller.scrollTop).toBe(730);
-    expect(coordinator.getMode()).toBe('pinned-item');
-
-    coordinator.followTail({ force: true });
-    setRect(item, 117);
-    expect(coordinator.restoreElementAnchor(scroller)).toBe(false);
-  });
-
-  it('retains logical pin ownership while Virtuoso rematerializes a disconnected item', () => {
-    const scroller = document.createElement('div');
-    scroller.dataset.virtuosoScroller = 'true';
-    const item = document.createElement('div');
-    scroller.append(item);
-    document.body.append(scroller);
-    setScrollerGeometry(scroller, 700);
-    setRect(scroller, 0);
-    setRect(item, 57);
-
-    const coordinator = new FlowChatViewportCoordinator();
-    expect(coordinator.pinElement(item)).toBe(true);
-
-    item.remove();
-    expect(coordinator.ownsElementAnchor()).toBe(false);
-    expect(coordinator.getMode()).toBe('pinned-item');
-
-    coordinator.release('test-cleanup');
-    expect(coordinator.getMode()).toBe('idle');
-  });
-
-  it('does not let a tool-card collapse replace an active pinned-item anchor', () => {
-    const scroller = document.createElement('div');
-    scroller.dataset.virtuosoScroller = 'true';
-    const pinnedItem = document.createElement('div');
-    const toolCard = document.createElement('div');
-    scroller.append(pinnedItem, toolCard);
-    document.body.append(scroller);
-    setScrollerGeometry(scroller, 700);
-    setRect(scroller, 0);
-    setRect(pinnedItem, 57);
-    setRect(toolCard, 300);
-
-    const coordinator = new FlowChatViewportCoordinator();
-    coordinator.pinElement(pinnedItem);
-
-    expect(coordinator.preserveElement(toolCard)).toBe(false);
-    expect(coordinator.getMode()).toBe('pinned-item');
-  });
-
-  it('owns virtualizer scroll compensation while an element anchor is active', () => {
-    const scroller = document.createElement('div');
-    scroller.dataset.virtuosoScroller = 'true';
-    const pinnedItem = document.createElement('div');
-    scroller.append(pinnedItem);
-    document.body.append(scroller);
-    setScrollerGeometry(scroller, 700);
-    setRect(scroller, 0);
-    setRect(pinnedItem, 57);
-
-    const coordinator = new FlowChatViewportCoordinator();
-    expect(coordinator.ownsElementAnchor()).toBe(false);
-    coordinator.pinElement(pinnedItem);
-    expect(coordinator.ownsElementAnchor()).toBe(true);
-    coordinator.followTail({ force: true });
-    expect(coordinator.ownsElementAnchor()).toBe(false);
-  });
-
-  it('restores an idle viewport position once without creating a persistent lock', () => {
-    const scroller = document.createElement('div');
-    scroller.dataset.virtuosoScroller = 'true';
-    document.body.append(scroller);
-    setScrollerGeometry(scroller, 900);
-
-    const coordinator = new FlowChatViewportCoordinator();
-    expect(coordinator.restoreScrollPositionOnce(scroller, 1200, 'test-idle')).toBe(true);
-    expect(scroller.scrollTop).toBe(1200);
-
-    scroller.scrollTop = 900;
-    expect(coordinator.getMode()).toBe('idle');
-    expect(scroller.scrollTop).toBe(900);
-  });
-
-  it('clamps the idle fallback restore to the current physical scroll range', () => {
-    const scroller = document.createElement('div');
-    scroller.dataset.virtuosoScroller = 'true';
-    document.body.append(scroller);
-    setScrollerGeometry(scroller, 900);
-
-    const coordinator = new FlowChatViewportCoordinator();
-    expect(coordinator.restoreScrollPositionOnce(scroller, 5000, 'test-clamp')).toBe(true);
-    expect(scroller.scrollTop).toBe(1500);
-  });
-
-  it('delegates one-shot restoration to the semantic anchor when it owns the viewport', () => {
-    const scroller = document.createElement('div');
-    scroller.dataset.virtuosoScroller = 'true';
-    const pinnedItem = document.createElement('div');
-    scroller.append(pinnedItem);
-    document.body.append(scroller);
-    setScrollerGeometry(scroller, 700);
-    setRect(scroller, 0);
-    setRect(pinnedItem, 57);
-
-    const coordinator = new FlowChatViewportCoordinator();
-    coordinator.pinElement(pinnedItem);
-    setRect(pinnedItem, 87);
-
-    expect(coordinator.restoreScrollPositionOnce(scroller, 0, 'test-semantic')).toBe(true);
-    expect(scroller.scrollTop).toBe(730);
-  });
-
-  it('extends the physical bottom range before retrying a stalled semantic restore', () => {
-    const scroller = document.createElement('div');
-    scroller.dataset.virtuosoScroller = 'true';
-    const pinnedItem = document.createElement('div');
-    scroller.append(pinnedItem);
-    document.body.append(scroller);
-
-    let scrollHeight = 1200;
-    const clientHeight = 500;
-    let scrollTop = 700;
-    let itemTop = 57;
-    Object.defineProperties(scroller, {
-      clientHeight: { configurable: true, get: () => clientHeight },
-      scrollHeight: { configurable: true, get: () => scrollHeight },
-      scrollTop: {
-        configurable: true,
-        get: () => scrollTop,
-        set: (requested: number) => {
-          const maxScrollTop = Math.max(0, scrollHeight - clientHeight);
-          const applied = Math.min(maxScrollTop, Math.max(0, requested));
-          itemTop -= applied - scrollTop;
-          scrollTop = applied;
-        },
-      },
-    });
-    setRect(scroller, 0);
-    vi.spyOn(pinnedItem, 'getBoundingClientRect').mockImplementation(() => ({
-      bottom: itemTop + 40,
-      height: 40,
-      left: 0,
-      right: 300,
-      top: itemTop,
-      width: 300,
-      x: 0,
-      y: itemTop,
-      toJSON: () => ({}),
-    }));
-
-    const ensureBottomRange = vi.fn(({ additionalPx }: { additionalPx: number }) => {
-      scrollHeight += additionalPx;
-      return true;
-    });
-    const coordinator = new FlowChatViewportCoordinator();
-    coordinator.setRangeHost({ ensureBottomRange });
-    coordinator.pinElement(pinnedItem);
-
-    scrollHeight = 1150;
-    scroller.scrollTop = 700;
-    expect(scrollTop).toBe(650);
-    expect(itemTop).toBe(107);
-
-    expect(coordinator.restoreElementAnchor(scroller, 'test-range-recovery')).toBe(true);
-    expect(ensureBottomRange).toHaveBeenCalledWith(expect.objectContaining({
-      additionalPx: 51,
-      mode: 'pinned-item',
-      source: 'test-range-recovery',
-    }));
-    expect(scrollTop).toBe(700);
-    expect(itemTop).toBe(57);
-    coordinator.release('test-cleanup');
-  });
-
-  it('reconciles a pinned anchor from the internal animation-frame guard', () => {
-    let scheduledFrame: FrameRequestCallback | null = null;
-    vi.spyOn(window, 'requestAnimationFrame').mockImplementation((callback) => {
-      scheduledFrame = callback;
-      return 1;
-    });
-    vi.spyOn(window, 'cancelAnimationFrame').mockImplementation(() => {});
-
-    const scroller = document.createElement('div');
-    scroller.dataset.virtuosoScroller = 'true';
-    const pinnedItem = document.createElement('div');
-    scroller.append(pinnedItem);
-    document.body.append(scroller);
-    setScrollerGeometry(scroller, 700);
-    setRect(scroller, 0);
-    setRect(pinnedItem, 57);
-
-    const coordinator = new FlowChatViewportCoordinator();
-    coordinator.pinElement(pinnedItem);
-    setRect(pinnedItem, 157);
-
-    expect(scheduledFrame).not.toBeNull();
-    (scheduledFrame as FrameRequestCallback)(0);
-    expect(scroller.scrollTop).toBe(800);
-    coordinator.release('test-cleanup');
-  });
-
-  it('coalesces scheduled anchor restores into the existing frame using the latest request', () => {
-    let scheduledFrame: FrameRequestCallback | null = null;
-    const requestFrame = vi.spyOn(window, 'requestAnimationFrame').mockImplementation((callback) => {
-      scheduledFrame = callback;
-      return 1;
-    });
-    vi.spyOn(window, 'cancelAnimationFrame').mockImplementation(() => {});
-
-    const scroller = document.createElement('div');
-    scroller.dataset.virtuosoScroller = 'true';
-    const pinnedItem = document.createElement('div');
-    scroller.append(pinnedItem);
-    document.body.append(scroller);
-    setScrollerGeometry(scroller, 700);
-    setRect(scroller, 0);
-    setRect(pinnedItem, 57);
-
-    const coordinator = new FlowChatViewportCoordinator();
-    coordinator.pinElement(pinnedItem);
-    const restoreAnchor = vi.spyOn(coordinator, 'restoreElementAnchor');
-    setRect(pinnedItem, 87);
-
-    expect(coordinator.scheduleElementAnchorRestore(scroller, 'scroll-handler:first')).toBe(true);
-    expect(coordinator.scheduleElementAnchorRestore(scroller, 'scroll-handler:latest')).toBe(true);
-    expect(requestFrame).toHaveBeenCalledTimes(1);
-
-    expect(scheduledFrame).not.toBeNull();
-    (scheduledFrame as FrameRequestCallback)(0);
-    expect(restoreAnchor).toHaveBeenCalledTimes(1);
-    expect(restoreAnchor).toHaveBeenCalledWith(scroller, 'scroll-handler:latest');
-    expect(scroller.scrollTop).toBe(730);
-    coordinator.release('test-cleanup');
-  });
-
-  it('cancels a scheduled anchor restore when semantic ownership is released', () => {
-    let scheduledFrame: FrameRequestCallback | null = null;
-    vi.spyOn(window, 'requestAnimationFrame').mockImplementation((callback) => {
-      scheduledFrame = callback;
-      return 17;
-    });
-    const cancelFrame = vi.spyOn(window, 'cancelAnimationFrame').mockImplementation(() => {});
-
-    const scroller = document.createElement('div');
-    scroller.dataset.virtuosoScroller = 'true';
-    const pinnedItem = document.createElement('div');
-    scroller.append(pinnedItem);
-    document.body.append(scroller);
-    setScrollerGeometry(scroller, 700);
-    setRect(scroller, 0);
-    setRect(pinnedItem, 57);
-
-    const coordinator = new FlowChatViewportCoordinator();
-    coordinator.pinElement(pinnedItem);
-    const restoreAnchor = vi.spyOn(coordinator, 'restoreElementAnchor');
-    coordinator.scheduleElementAnchorRestore(scroller, 'scroll-handler');
-    coordinator.release('stream-end-pinned-item');
-
-    expect(cancelFrame).toHaveBeenCalledWith(17);
-    expect(scheduledFrame).not.toBeNull();
-    (scheduledFrame as FrameRequestCallback)(0);
-    expect(restoreAnchor).not.toHaveBeenCalled();
-    expect(coordinator.getMode()).toBe('idle');
-  });
-
-  it('stops the animation-frame guard after element preservation settles', () => {
-    vi.spyOn(window, 'requestAnimationFrame').mockImplementation(() => 17);
-    const cancelFrame = vi.spyOn(window, 'cancelAnimationFrame').mockImplementation(() => {});
-
-    const scroller = document.createElement('div');
-    scroller.dataset.virtuosoScroller = 'true';
-    const card = document.createElement('div');
-    scroller.append(card);
-    document.body.append(scroller);
-    setScrollerGeometry(scroller, 900);
-    setRect(scroller, 0);
-    setRect(card, 120);
-
-    const coordinator = new FlowChatViewportCoordinator();
-    coordinator.preserveElement(card);
-    coordinator.settleElementPreservation('test-settled');
-
-    expect(cancelFrame).toHaveBeenCalledWith(17);
-    expect(coordinator.ownsElementAnchor()).toBe(true);
-  });
-});
diff --git a/src/web-ui/src/flow_chat/components/modern/FlowChatViewportCoordinator.ts b/src/web-ui/src/flow_chat/components/modern/FlowChatViewportCoordinator.ts
deleted file mode 100644
index 32e4589cd8..0000000000
--- a/src/web-ui/src/flow_chat/components/modern/FlowChatViewportCoordinator.ts
+++ /dev/null
@@ -1,482 +0,0 @@
-import { flowChatDiagnostics } from '@/infrastructure/diagnostics/flowChatDiagnostics';
-
-export type FlowChatViewportAnchorMode =
-  | 'idle'
-  | 'pinned-item'
-  | 'following-tail'
-  | 'preserving-element';
-
-export interface FlowChatViewportRangeHost {
-  ensureBottomRange(options: {
-    additionalPx: number;
-    mode: Extract<FlowChatViewportAnchorMode, 'pinned-item' | 'preserving-element'>;
-    source: string;
-  }): boolean;
-}
-
-export type FlowChatElementAnchorLease = number;
-
-type ElementAnchor = {
-  element: HTMLElement;
-  scroller: HTMLElement;
-  offsetFromScrollerTop: number;
-  preservationPhase: 'active' | 'retained' | null;
-  lease: FlowChatElementAnchorLease;
-};
-
-type PendingElementAnchorRestore = {
-  scroller: HTMLElement;
-  source: string;
-};
-
-const ELEMENT_ANCHOR_EPSILON_PX = 0.5;
-const ELEMENT_ANCHOR_RANGE_GUARD_PX = 1;
-
-export function canHandoffPinnedItemToTail(options: {
-  pinReservationPx: number;
-  collapseReservationPx: number;
-  pendingStickyPinGrowthPx: number;
-  hasPendingCollapseIntent: boolean;
-  viewport: {
-    scrollTop: number;
-    clientHeight: number;
-    naturalContentHeight: number;
-  } | null;
-}): boolean {
-  if (
-    options.collapseReservationPx > ELEMENT_ANCHOR_EPSILON_PX ||
-    options.pendingStickyPinGrowthPx > ELEMENT_ANCHOR_EPSILON_PX ||
-    options.hasPendingCollapseIntent
-  ) {
-    return false;
-  }
-
-  if (options.pinReservationPx <= ELEMENT_ANCHOR_EPSILON_PX) {
-    return true;
-  }
-
-  const viewport = options.viewport;
-  if (
-    !viewport ||
-    !Number.isFinite(viewport.scrollTop) ||
-    !Number.isFinite(viewport.clientHeight) ||
-    !Number.isFinite(viewport.naturalContentHeight) ||
-    viewport.clientHeight <= ELEMENT_ANCHOR_EPSILON_PX
-  ) {
-    return false;
-  }
-
-  return (
-    viewport.naturalContentHeight + ELEMENT_ANCHOR_EPSILON_PX >=
-    viewport.scrollTop + viewport.clientHeight
-  );
-}
-
-/** Owns anchor priority independently from the virtualizer implementation. */
-export class FlowChatViewportCoordinator {
-  private mode: FlowChatViewportAnchorMode = 'idle';
-  private elementAnchor: ElementAnchor | null = null;
-  private anchorGuardFrame: number | null = null;
-  private pendingElementAnchorRestore: PendingElementAnchorRestore | null = null;
-  private rangeHost: FlowChatViewportRangeHost | null = null;
-  private nextElementAnchorLease = 0;
-
-  setRangeHost(host: FlowChatViewportRangeHost | null): void {
-    this.rangeHost = host;
-  }
-
-  getMode(): FlowChatViewportAnchorMode {
-    this.validateElementAnchor('get-mode');
-    return this.mode;
-  }
-
-  ownsElementAnchor(): boolean {
-    this.validateElementAnchor('owns-element-anchor');
-    return Boolean(
-      this.elementAnchor &&
-      (this.mode === 'pinned-item' || this.mode === 'preserving-element'),
-    );
-  }
-
-  pinItem(reason = 'unspecified'): void {
-    const previousMode = this.mode;
-    this.cancelElementAnchorRestoreWork();
-    this.elementAnchor = null;
-    this.mode = 'pinned-item';
-    if (flowChatDiagnostics.isEnabled()) {
-      flowChatDiagnostics.trace({
-        hypothesis: 'B',
-        location: 'FlowChatViewportCoordinator.pinItem',
-        message: 'Viewport coordinator entered pinned item mode',
-        data: () => ({ previousMode, reason }),
-      });
-    }
-  }
-
-  pinElement(element: HTMLElement | null | undefined): boolean {
-    return this.captureElement(element, 'pinned-item') !== null;
-  }
-
-  followTail(options?: { force?: boolean }): boolean {
-    this.validateElementAnchor('follow-tail');
-    const hasActiveElementPreservation = (
-      this.mode === 'preserving-element' &&
-      this.elementAnchor?.preservationPhase === 'active'
-    );
-    if (hasActiveElementPreservation && !options?.force) {
-      if (flowChatDiagnostics.isEnabled()) {
-        flowChatDiagnostics.trace({
-          hypothesis: 'B',
-          location: 'FlowChatViewportCoordinator.followTail',
-          message: 'Tail follow rejected during active element preservation',
-          data: () => ({
-            mode: this.mode,
-            preservationPhase: this.elementAnchor?.preservationPhase ?? null,
-            force: options?.force === true,
-          }),
-        });
-      }
-      return false;
-    }
-
-    const previousMode = this.mode;
-    this.cancelElementAnchorRestoreWork();
-    this.elementAnchor = null;
-    this.mode = 'following-tail';
-    if (flowChatDiagnostics.isEnabled()) {
-      flowChatDiagnostics.trace({
-        hypothesis: 'B',
-        location: 'FlowChatViewportCoordinator.followTail',
-        message: 'Viewport coordinator entered tail follow mode',
-        data: () => ({ previousMode, force: options?.force === true }),
-      });
-    }
-    return true;
-  }
-
-  preserveElement(element: HTMLElement | null | undefined): boolean {
-    return this.preserveElementWithLease(element) !== null;
-  }
-
-  preserveElementWithLease(
-    element: HTMLElement | null | undefined,
-  ): FlowChatElementAnchorLease | null {
-    this.validateElementAnchor('preserve-element');
-    if (!element || this.mode === 'following-tail' || this.mode === 'pinned-item') {
-      if (flowChatDiagnostics.isEnabled()) {
-        flowChatDiagnostics.trace({
-          hypothesis: 'E',
-          location: 'FlowChatViewportCoordinator.preserveElement',
-          message: 'Element preservation request rejected',
-          data: () => ({ hasElement: Boolean(element), mode: this.mode }),
-        });
-      }
-      return null;
-    }
-
-    return this.captureElement(
-      element,
-      'preserving-element',
-    );
-  }
-
-  releaseElementPreservationLease(
-    lease: FlowChatElementAnchorLease,
-    reason = 'unspecified',
-  ): boolean {
-    this.validateElementAnchor(`release-element-preservation-lease:${reason}`);
-    if (
-      this.mode !== 'preserving-element'
-      || this.elementAnchor?.lease !== lease
-    ) {
-      return false;
-    }
-
-    this.release(reason);
-    return true;
-  }
-
-  settleElementPreservation(source = 'unspecified'): boolean {
-    this.validateElementAnchor('settle-element-preservation');
-    const anchor = this.elementAnchor;
-    if (!anchor || this.mode !== 'preserving-element') {
-      return false;
-    }
-
-    const previousPhase = anchor.preservationPhase;
-    anchor.preservationPhase = 'retained';
-    this.stopAnchorGuard();
-    this.startAnchorGuard();
-    if (flowChatDiagnostics.isEnabled()) {
-      flowChatDiagnostics.trace({
-        hypothesis: 'E',
-        location: 'FlowChatViewportCoordinator.settleElementPreservation',
-        message: 'Element preservation retained after layout settlement',
-        data: () => ({ previousPhase, source }),
-      });
-    }
-    return true;
-  }
-
-  private captureElement(
-    element: HTMLElement | null | undefined,
-    mode: 'pinned-item' | 'preserving-element',
-  ): FlowChatElementAnchorLease | null {
-    if (!element) {
-      return null;
-    }
-
-    const scroller = element.closest<HTMLElement>('[data-virtuoso-scroller="true"]');
-    if (!scroller) {
-      if (flowChatDiagnostics.isEnabled()) {
-        flowChatDiagnostics.trace({
-          hypothesis: 'B',
-          location: 'FlowChatViewportCoordinator.captureElement',
-          message: 'Element anchor capture failed without a scroller',
-          data: () => ({ mode }),
-        });
-      }
-      return null;
-    }
-
-    const elementRect = element.getBoundingClientRect();
-    const scrollerRect = scroller.getBoundingClientRect();
-    const lease = ++this.nextElementAnchorLease;
-    this.cancelElementAnchorRestoreWork();
-    this.elementAnchor = {
-      element,
-      scroller,
-      offsetFromScrollerTop: elementRect.top - scrollerRect.top,
-      preservationPhase: mode === 'preserving-element' ? 'active' : null,
-      lease,
-    };
-    this.mode = mode;
-    this.startAnchorGuard();
-    if (flowChatDiagnostics.isEnabled()) {
-      flowChatDiagnostics.trace({
-        hypothesis: mode === 'preserving-element' ? 'E' : 'B',
-        location: 'FlowChatViewportCoordinator.captureElement',
-        message: 'Semantic element anchor captured',
-        data: () => ({
-          mode,
-          preservationPhase: this.elementAnchor?.preservationPhase ?? null,
-          lease,
-          elementConnected: element.isConnected,
-          offsetFromScrollerTop: this.elementAnchor?.offsetFromScrollerTop ?? null,
-          scrollTop: scroller.scrollTop,
-          scrollHeight: scroller.scrollHeight,
-          clientHeight: scroller.clientHeight,
-        }),
-      });
-    }
-    return lease;
-  }
-
-  restoreElementAnchor(scroller: HTMLElement, source = 'external'): boolean {
-    this.validateElementAnchor(`restore:${source}`);
-    const anchor = this.elementAnchor;
-    if (!anchor || (this.mode !== 'preserving-element' && this.mode !== 'pinned-item')) {
-      return false;
-    }
-
-    const readCorrection = () => {
-      const elementRect = anchor.element.getBoundingClientRect();
-      const scrollerRect = scroller.getBoundingClientRect();
-      return elementRect.top - scrollerRect.top - anchor.offsetFromScrollerTop;
-    };
-    const applyCorrection = (correction: number) => {
-      const maxScrollTop = Math.max(0, scroller.scrollHeight - scroller.clientHeight);
-      const desiredScrollTop = scroller.scrollTop + correction;
-      const requestedScrollTop = Math.min(maxScrollTop, Math.max(0, desiredScrollTop));
-      scroller.scrollTop = requestedScrollTop;
-    };
-
-    const initialCorrection = readCorrection();
-    if (Math.abs(initialCorrection) <= ELEMENT_ANCHOR_EPSILON_PX) {
-      return false;
-    }
-
-    const diagnosticsEnabled = flowChatDiagnostics.isEnabled();
-    const scrollTopBefore = diagnosticsEnabled ? scroller.scrollTop : null;
-    applyCorrection(initialCorrection);
-    let remainingCorrection = readCorrection();
-    if (diagnosticsEnabled) {
-      flowChatDiagnostics.trace({
-        hypothesis: 'B',
-        location: 'FlowChatViewportCoordinator.restoreElementAnchor',
-        message: 'Semantic anchor correction applied',
-        data: () => ({
-          mode: this.mode,
-          source,
-          initialCorrection,
-          remainingCorrection,
-          scrollTopBefore,
-          scrollTopAfter: scroller.scrollTop,
-          maxScrollTop: Math.max(0, scroller.scrollHeight - scroller.clientHeight),
-        }),
-      });
-    }
-
-    if (
-      remainingCorrection > ELEMENT_ANCHOR_EPSILON_PX &&
-      this.rangeHost &&
-      (this.mode === 'pinned-item' || this.mode === 'preserving-element')
-    ) {
-      const rangeExtended = this.rangeHost.ensureBottomRange({
-        additionalPx: remainingCorrection + ELEMENT_ANCHOR_RANGE_GUARD_PX,
-        mode: this.mode,
-        source,
-      });
-      if (rangeExtended) {
-        void scroller.scrollHeight;
-        remainingCorrection = readCorrection();
-        if (Math.abs(remainingCorrection) > ELEMENT_ANCHOR_EPSILON_PX) {
-          applyCorrection(remainingCorrection);
-        }
-      }
-      if (flowChatDiagnostics.isEnabled()) {
-        flowChatDiagnostics.trace({
-          hypothesis: 'C',
-          location: 'FlowChatViewportCoordinator.restoreElementAnchor',
-          message: 'Semantic anchor requested additional bottom range',
-          data: () => ({
-            mode: this.mode,
-            source,
-            rangeExtended,
-            remainingCorrection,
-            scrollTop: scroller.scrollTop,
-            scrollHeight: scroller.scrollHeight,
-            clientHeight: scroller.clientHeight,
-          }),
-        });
-      }
-    }
-    return true;
-  }
-
-  scheduleElementAnchorRestore(scroller: HTMLElement, source = 'external'): boolean {
-    this.validateElementAnchor(`schedule-restore:${source}`);
-    if (
-      !this.elementAnchor ||
-      (this.mode !== 'preserving-element' && this.mode !== 'pinned-item')
-    ) {
-      return false;
-    }
-
-    this.pendingElementAnchorRestore = { scroller, source };
-    if (typeof requestAnimationFrame === 'undefined') {
-      this.pendingElementAnchorRestore = null;
-      return this.restoreElementAnchor(scroller, source);
-    }
-
-    this.startAnchorGuard();
-    return true;
-  }
-
-  restoreScrollPositionOnce(
-    scroller: HTMLElement,
-    targetScrollTop: number,
-    source = 'unspecified',
-  ): boolean {
-    if (this.ownsElementAnchor()) {
-      this.restoreElementAnchor(scroller, source);
-      return true;
-    }
-
-    const maxScrollTop = Math.max(0, scroller.scrollHeight - scroller.clientHeight);
-    const previousScrollTop = scroller.scrollTop;
-    const nextScrollTop = Math.min(maxScrollTop, Math.max(0, targetScrollTop));
-    if (Math.abs(nextScrollTop - previousScrollTop) <= ELEMENT_ANCHOR_EPSILON_PX) {
-      return false;
-    }
-
-    scroller.scrollTop = nextScrollTop;
-    return true;
-  }
-
-  release(reason = 'unspecified'): void {
-    const previousMode = this.mode;
-    const hadElementAnchor = Boolean(this.elementAnchor);
-    const previousPreservationPhase = this.elementAnchor?.preservationPhase ?? null;
-    this.cancelElementAnchorRestoreWork();
-    this.elementAnchor = null;
-    this.mode = 'idle';
-    if (flowChatDiagnostics.isEnabled()) {
-      flowChatDiagnostics.trace({
-        hypothesis: 'B',
-        location: 'FlowChatViewportCoordinator.release',
-        message: 'Viewport coordinator released semantic ownership',
-        data: () => ({ previousMode, previousPreservationPhase, hadElementAnchor, reason }),
-      });
-    }
-  }
-
-  private validateElementAnchor(source: string): void {
-    const anchor = this.elementAnchor;
-    if (anchor && (!anchor.element.isConnected || !anchor.scroller.isConnected)) {
-      if (this.mode === 'pinned-item' && anchor.scroller.isConnected) {
-        this.cancelElementAnchorRestoreWork();
-        this.elementAnchor = null;
-        return;
-      }
-      this.release(`element-anchor-disconnected:${source}`);
-    }
-  }
-
-  private startAnchorGuard(): void {
-    const shouldContinuouslyGuard = (
-      this.mode === 'pinned-item' ||
-      (
-        this.mode === 'preserving-element' &&
-        this.elementAnchor?.preservationPhase === 'active'
-      )
-    );
-    if (
-      this.anchorGuardFrame !== null ||
-      typeof requestAnimationFrame === 'undefined' ||
-      (!shouldContinuouslyGuard && !this.pendingElementAnchorRestore)
-    ) {
-      return;
-    }
-    this.anchorGuardFrame = requestAnimationFrame(this.runAnchorGuardFrame);
-  }
-
-  private stopAnchorGuard(): void {
-    if (this.anchorGuardFrame === null || typeof cancelAnimationFrame === 'undefined') {
-      this.anchorGuardFrame = null;
-      return;
-    }
-    cancelAnimationFrame(this.anchorGuardFrame);
-    this.anchorGuardFrame = null;
-  }
-
-  private cancelElementAnchorRestoreWork(): void {
-    this.pendingElementAnchorRestore = null;
-    this.stopAnchorGuard();
-  }
-
-  private runAnchorGuardFrame = (): void => {
-    this.anchorGuardFrame = null;
-    this.validateElementAnchor('anchor-guard');
-    const anchor = this.elementAnchor;
-    if (
-      !anchor ||
-      (this.mode !== 'pinned-item' && this.mode !== 'preserving-element') ||
-      (
-        this.mode === 'preserving-element' &&
-        anchor.preservationPhase === 'retained' &&
-        !this.pendingElementAnchorRestore
-      )
-    ) {
-      return;
-    }
-
-    const pendingRestore = this.pendingElementAnchorRestore;
-    this.pendingElementAnchorRestore = null;
-    this.restoreElementAnchor(
-      pendingRestore?.scroller ?? anchor.scroller,
-      pendingRestore?.source ?? 'anchor-guard',
-    );
-    this.startAnchorGuard();
-  };
-}
diff --git a/src/web-ui/src/flow_chat/components/modern/ModelRoundItem.scss b/src/web-ui/src/flow_chat/components/modern/ModelRoundItem.scss
index e9b26a6e36..918e25ed3b 100644
--- a/src/web-ui/src/flow_chat/components/modern/ModelRoundItem.scss
+++ b/src/web-ui/src/flow_chat/components/modern/ModelRoundItem.scss
@@ -380,14 +380,14 @@
 
 .model-round-item__fork-btn {
   .spinning {
-    animation: spin 1s linear infinite;
+    animation: model-round-item-spin 1s linear infinite;
   }
 }
 
 // Export image button
 .model-round-item__export-btn {
   .spinning {
-    animation: spin 1s linear infinite;
+    animation: model-round-item-spin 1s linear infinite;
   }
 
   &:disabled {
@@ -396,7 +396,7 @@
   }
 }
 
-@keyframes spin {
+@keyframes model-round-item-spin {
   from {
     transform: rotate(0deg);
   }
@@ -405,17 +405,6 @@
   }
 }
 
-@keyframes fadeIn {
-  from {
-    opacity: 0;
-    transform: translateY(10px);
-  }
-  to {
-    opacity: 1;
-    transform: translateY(0);
-  }
-}
-
 @keyframes model-round-copy-menu-in {
   from {
     opacity: 0;
diff --git a/src/web-ui/src/flow_chat/components/modern/ModelRoundItem.tsx b/src/web-ui/src/flow_chat/components/modern/ModelRoundItem.tsx
index 64fe0cd02b..c2ef5cf3ec 100644
--- a/src/web-ui/src/flow_chat/components/modern/ModelRoundItem.tsx
+++ b/src/web-ui/src/flow_chat/components/modern/ModelRoundItem.tsx
@@ -131,6 +131,7 @@ interface ModelRoundItemProps {
   turnEndedAt?: number;
   turnDurationMs?: number;
   turnTokenUsage?: TokenUsage;
+  expandedThinkingItemIds?: string[];
 }
 
 function sortRoundAttempts(attempts: ModelRoundAttempt[]): ModelRoundAttempt[] {
@@ -362,6 +363,7 @@ export const ModelRoundItem = React.memo<ModelRoundItemProps>(
     turnEndedAt,
     turnDurationMs,
     turnTokenUsage,
+    expandedThinkingItemIds = [],
   }) => {
     const { t } = useTranslation('flow-chat');
     const { formatDate, formatNumber } = useI18n('flow-chat');
@@ -488,6 +490,7 @@ export const ModelRoundItem = React.memo<ModelRoundItemProps>(
                 turnId={turnId}
                 roundId={options.roundId}
                 isLastItem={isLast && itemIdx === group.items.length - 1}
+                expandedThinkingItemIds={expandedThinkingItemIds}
               />
             ));
 
@@ -516,6 +519,7 @@ export const ModelRoundItem = React.memo<ModelRoundItemProps>(
                 turnId={turnId}
                 roundId={options.roundId}
                 isLastItem={isLast}
+                expandedThinkingItemIds={expandedThinkingItemIds}
               />
             );
           }
@@ -524,7 +528,7 @@ export const ModelRoundItem = React.memo<ModelRoundItemProps>(
             return null;
         }
       })
-    ), [sessionId, turnId]);
+    ), [expandedThinkingItemIds, sessionId, turnId]);
 
     const handleCopyScope = useCallback(async (scope: TranscriptExportScope) => {
       setIsCopyMenuOpen(false);
@@ -847,6 +851,7 @@ export const ModelRoundItem = React.memo<ModelRoundItemProps>(
       prev.round.historyRounds === next.round.historyRounds &&
       prev.isLastRound === next.isLastRound &&
       prev.isTurnComplete === next.isTurnComplete &&
+      prev.expandedThinkingItemIds === next.expandedThinkingItemIds &&
       prev.turnStartedAt === next.turnStartedAt &&
       prev.turnEndedAt === next.turnEndedAt &&
       prev.turnDurationMs === next.turnDurationMs &&
@@ -865,6 +870,7 @@ interface FlowItemRendererProps {
   turnId: string;
   roundId?: string;
   isLastItem?: boolean;
+  expandedThinkingItemIds?: string[];
 }
 
 // Do not memoize: streaming content updates frequently.
@@ -873,6 +879,7 @@ const FlowItemRenderer: React.FC<FlowItemRendererProps> = ({
   turnId,
   roundId,
   isLastItem,
+  expandedThinkingItemIds = [],
 }) => {
   const {
     onToolConfirm,
@@ -903,7 +910,11 @@ const FlowItemRenderer: React.FC<FlowItemRendererProps> = ({
 
     case 'thinking':
       return (
-        <ModelThinkingDisplay thinkingItem={item as FlowThinkingItem} isLastItem={isLastItem} />
+        <ModelThinkingDisplay
+          thinkingItem={item as FlowThinkingItem}
+          isLastItem={isLastItem}
+          forceExpanded={expandedThinkingItemIds.includes(item.id)}
+        />
       );
 
     case 'tool': {
diff --git a/src/web-ui/src/flow_chat/components/modern/ModernFlowChatContainer.history-state.test.tsx b/src/web-ui/src/flow_chat/components/modern/ModernFlowChatContainer.history-state.test.tsx
index 0f2e7e2613..c2a93cd4a6 100644
--- a/src/web-ui/src/flow_chat/components/modern/ModernFlowChatContainer.history-state.test.tsx
+++ b/src/web-ui/src/flow_chat/components/modern/ModernFlowChatContainer.history-state.test.tsx
@@ -1,2454 +1,21 @@
-// @vitest-environment jsdom
+import fs from 'node:fs';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
 
-import React, { act } from 'react';
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { createRoot, type Root } from 'react-dom/client';
-import { ModernFlowChatContainer } from './ModernFlowChatContainer';
-import type { HistoryWindowBoundaryIntentResult } from './VirtualMessageList';
-import type { Session } from '../../types/flow-chat';
-import { flowChatStore } from '../../store/FlowChatStore';
-import {
-  clearHistorySessionOpenTransition,
-  dispatchHistorySessionOpenIntent,
-  HISTORY_SESSION_OPEN_INTENT_EVENT,
-} from '../../services/sessionOpenIntent';
-import { FLOWCHAT_TURN_RAIL_ROW_HEIGHT_PX } from './flowChatTurnRailWindow';
+const componentSource = fs.readFileSync(
+  path.resolve(__dirname, 'ModernFlowChatContainer.tsx'),
+  'utf8',
+);
 
-globalThis.IS_REACT_ACT_ENVIRONMENT = true;
-
-const stateMocks = vi.hoisted(() => ({
-  activeSession: null as Session | null,
-  virtualItems: [] as unknown[],
-  visibleTurnInfo: null as unknown,
-}));
-
-const switchChatSessionMock = vi.hoisted(() => vi.fn());
-const virtualListMock = vi.hoisted(() => ({
-  scrollToTurn: vi.fn(),
-  scrollToIndex: vi.fn(),
-  scrollToSearchMatch: vi.fn(),
-  clearSearchMatch: vi.fn(),
-  scrollToPhysicalBottomAndClearPin: vi.fn(),
-  scrollToTurnEndAndClearPin: vi.fn(() => true),
-  scrollToLatestEndPosition: vi.fn(),
-  isTurnRenderedInViewport: vi.fn(() => false),
-  isTurnTextRenderedInViewport: vi.fn(() => false),
-  pinTurnToTop: vi.fn(() => true),
-  pinTurnToTopWithStatus: vi.fn(() => 'settled' as const),
-  prepareTurnPinToTop: vi.fn(() => 'pending' as const),
-}));
-const virtualListActionClickMock = vi.hoisted(() => vi.fn());
-const startupTraceMock = vi.hoisted(() => ({
-  markPhase: vi.fn(),
-}));
-const historySessionDiagnosticsMock = vi.hoisted(() => ({
-  beginHistorySessionDiagnostics: vi.fn(() => 'diag-1'),
-  recordHistorySessionDiagnosticEvent: vi.fn(),
-  warnHistorySessionLoadingLayerStalled: vi.fn(),
-}));
-const searchStateMock = vi.hoisted(() => ({
-  searchQuery: '',
-  onSearchChange: vi.fn(),
-  matches: [] as unknown[],
-  matchIndices: [] as number[],
-  currentMatchIndex: -1,
-  currentMatchVirtualIndex: -1,
-  goToNext: vi.fn(),
-  goToPrev: vi.fn(),
-  clearSearch: vi.fn(),
-}));
-const headerPropsMock = vi.hoisted(() => ({
-  latest: null as Record<string, unknown> | null,
-}));
-const virtualListPropsMock = vi.hoisted(() => ({
-  latest: null as Record<string, unknown> | null,
-}));
-const navigationOptionsMock = vi.hoisted(() => ({
-  latest: null as Record<string, unknown> | null,
-}));
-const agentApiMock = vi.hoisted(() => ({
-  listBackgroundCommandActivities: vi.fn(() => Promise.resolve({ activities: [] })),
-  onPermissionRequestEvent: vi.fn(() => vi.fn()),
-  subscribePermissionRequests: vi.fn(() => Promise.resolve()),
-  listPendingPermissionRequests: vi.fn(() => Promise.resolve([])),
-}));
-
-vi.mock('react-i18next', () => ({
-  initReactI18next: {
-    type: '3rdParty',
-    init: () => undefined,
-  },
-  useTranslation: () => ({
-    t: (key: string) => {
-      const labels: Record<string, string> = {
-        'historyState.loadingTitle': 'Loading saved session',
-        'historyState.loadingDescription': 'Preparing the conversation history.',
-        'historyState.failedTitle': 'Session history did not load',
-        'historyState.failedDescription': 'Retry loading the saved conversation.',
-        'historyState.retry': 'Retry',
-      };
-      return labels[key] ?? key;
-    },
-  }),
-}));
-
-vi.mock('@/infrastructure/hooks/useShortcut', () => ({
-  useShortcut: vi.fn(),
-}));
-
-vi.mock('@/flow_chat/services/FlowChatManager', () => ({
-  FlowChatManager: {
-    getInstance: () => ({
-      cancelCurrentTask: vi.fn(),
-      createChatSession: vi.fn(),
-      switchChatSession: switchChatSessionMock,
-    }),
-  },
-}));
-
-vi.mock('@/app/stores/sessionModeStore', () => ({
-  useSessionModeStore: {
-    getState: () => ({
-      setMode: vi.fn(),
-    }),
-  },
-}));
-
-vi.mock('@/infrastructure/contexts/WorkspaceContext', () => ({
-  useWorkspaceContext: () => ({
-    workspacePath: 'D:/workspace/BitFun',
-  }),
-}));
-
-vi.mock('@/infrastructure/api/service-api/AgentAPI', () => ({
-  agentAPI: agentApiMock,
-}));
-
-vi.mock('../../utils/acpSession', () => ({
-  isAcpFlowSession: () => false,
-}));
-
-vi.mock('../../store/modernFlowChatStore', () => ({
-  sessionToVirtualItems: (session: Session | null) => (session?.dialogTurns ?? []).map(turn => ({
-    type: 'user-message',
-    turnId: turn.id,
-    data: turn.userMessage,
-  })),
-  useVirtualItems: () => stateMocks.virtualItems,
-  useActiveSession: () => stateMocks.activeSession,
-  useVisibleTurnInfo: () => stateMocks.visibleTurnInfo,
-}));
-
-vi.mock('./VirtualMessageList', () => ({
-  VirtualMessageList: React.forwardRef((props: Record<string, unknown>, ref) => {
-    virtualListPropsMock.latest = props;
-    React.useImperativeHandle(ref, () => virtualListMock);
-    return (
-      <div data-testid="virtual-list">
-        <button type="button" data-testid="virtual-list-action" onClick={virtualListActionClickMock}>
-          Hidden action
-        </button>
-      </div>
-    );
-  }),
-}));
-
-vi.mock('@/shared/utils/startupTrace', () => ({
-  isRemoteTraceContext: () => false,
-  startupTrace: startupTraceMock,
-}));
-
-vi.mock('../../services/historySessionDiagnostics', () => historySessionDiagnosticsMock);
-
-vi.mock('./FlowChatHeader', () => ({
-  FlowChatHeader: (props: Record<string, unknown>) => {
-    headerPropsMock.latest = props;
-    return <div data-testid="flowchat-header" />;
-  },
-}));
-
-vi.mock('../WelcomePanel', () => ({
-  WelcomePanel: () => <div data-testid="welcome-panel">Welcome panel</div>,
-}));
-
-vi.mock('./useExploreGroupState', () => ({
-  useExploreGroupState: () => ({
-    exploreGroupStates: {},
-    onExploreGroupToggle: vi.fn(),
-    onExpandGroup: vi.fn(),
-    onExpandAllInTurn: vi.fn(),
-    onCollapseGroup: vi.fn(),
-  }),
-}));
-
-vi.mock('./useFlowChatFileActions', () => ({
-  useFlowChatFileActions: () => ({
-    handleFileViewRequest: vi.fn(),
-  }),
-}));
-
-vi.mock('./useFlowChatNavigation', () => ({
-  useFlowChatNavigation: (options: Record<string, unknown>) => {
-    navigationOptionsMock.latest = options;
-  },
-}));
-
-vi.mock('./useFlowChatCopyDialog', () => ({
-  useFlowChatCopyDialog: vi.fn(),
-}));
-
-vi.mock('./useFlowChatSync', () => ({
-  useFlowChatSync: vi.fn(),
-}));
-
-vi.mock('./useFlowChatToolActions', () => ({
-  useFlowChatToolActions: () => ({
-    handleToolConfirm: vi.fn(),
-    handleToolReject: vi.fn(),
-  }),
-}));
-
-vi.mock('./useFlowChatSearch', () => ({
-  useFlowChatSearch: () => searchStateMock,
-}));
-
-function createSession(overrides: Partial<Session> = {}): Session {
-  return {
-    sessionId: 'session-1',
-    title: 'Saved session',
-    dialogTurns: [],
-    status: 'idle',
-    config: { agentType: 'agentic' },
-    createdAt: 1,
-    lastActiveAt: 1,
-    error: null,
-    isHistorical: true,
-    todos: [],
-    mode: 'agentic',
-    workspacePath: 'D:/workspace/BitFun',
-    sessionKind: 'normal',
-    ...overrides,
-  };
-}
-
-function createTurn(id: string, content: string, status: 'completed' | 'processing' = 'completed') {
-  return {
-    id,
-    turnId: id,
-    sessionId: 'session-1',
-    timestamp: 1,
-    userMessage: { id: `user-${id}`, content, timestamp: 1 },
-    modelRounds: [],
-    startTime: 1,
-    status,
-  };
-}
-
-let rafCallbacks: FrameRequestCallback[] = [];
-
-function flushAnimationFrame() {
-  const callbacks = rafCallbacks;
-  rafCallbacks = [];
-  act(() => {
-    callbacks.forEach(callback => callback(performance.now()));
-  });
-}
-
-function clickTurnRailItem(container: HTMLElement, turnId: string) {
-  const item = container.querySelector<HTMLButtonElement>(`[data-turn-id="${turnId}"]`);
-  expect(item).not.toBeNull();
-  act(() => {
-    item?.click();
-  });
-}
-
-function scrollTurnRailToOrdinal(
-  container: HTMLElement,
-  ordinal: number,
-  clientHeight = FLOWCHAT_TURN_RAIL_ROW_HEIGHT_PX * 5,
-) {
-  const list = container.querySelector<HTMLDivElement>('.flowchat-turn-rail__list');
-  expect(list).not.toBeNull();
-  if (!list) return;
-
-  Object.defineProperty(list, 'clientHeight', { configurable: true, value: clientHeight });
-  list.scrollTop = ordinal * FLOWCHAT_TURN_RAIL_ROW_HEIGHT_PX;
-  act(() => {
-    list.dispatchEvent(new Event('scroll', { bubbles: true }));
-  });
-}
-
-describe('ModernFlowChatContainer historical empty state', () => {
-  let container: HTMLDivElement;
-  let root: Root;
-
-  beforeEach(() => {
-    vi.restoreAllMocks();
-    rafCallbacks = [];
-    vi.stubGlobal('requestAnimationFrame', vi.fn((callback: FrameRequestCallback) => {
-      rafCallbacks.push(callback);
-      return rafCallbacks.length;
-    }));
-    vi.stubGlobal('cancelAnimationFrame', vi.fn());
-    // jsdom in vitest 4.x may expose window.localStorage without a callable
-    // getItem; provide a minimal storage so shouldShowMockBackgroundActivities
-    // does not crash during render.
-    vi.stubGlobal('localStorage', {
-      getItem: vi.fn(() => null),
-      setItem: vi.fn(),
-      removeItem: vi.fn(),
-      clear: vi.fn(),
-      key: vi.fn(() => null),
-      length: 0,
-    });
-    container = document.createElement('div');
-    document.body.appendChild(container);
-    root = createRoot(container);
-    stateMocks.virtualItems = [];
-    stateMocks.visibleTurnInfo = null;
-    switchChatSessionMock.mockReset();
-    virtualListMock.scrollToTurn.mockReset();
-    virtualListMock.scrollToIndex.mockReset();
-    virtualListMock.scrollToSearchMatch.mockReset();
-    virtualListMock.clearSearchMatch.mockReset();
-    virtualListMock.scrollToPhysicalBottomAndClearPin.mockReset();
-    virtualListMock.scrollToTurnEndAndClearPin.mockReset();
-    virtualListMock.scrollToTurnEndAndClearPin.mockReturnValue(true);
-    virtualListMock.scrollToLatestEndPosition.mockReset();
-    virtualListMock.isTurnRenderedInViewport.mockReset();
-    virtualListMock.isTurnRenderedInViewport.mockReturnValue(false);
-    virtualListMock.isTurnTextRenderedInViewport.mockReset();
-    virtualListMock.isTurnTextRenderedInViewport.mockReturnValue(false);
-    virtualListMock.pinTurnToTop.mockReset();
-    virtualListMock.pinTurnToTop.mockReturnValue(true);
-    virtualListMock.pinTurnToTopWithStatus.mockReset();
-    virtualListMock.pinTurnToTopWithStatus.mockReturnValue('settled');
-    virtualListMock.prepareTurnPinToTop.mockReset();
-    virtualListMock.prepareTurnPinToTop.mockReturnValue('pending');
-    virtualListActionClickMock.mockReset();
-    startupTraceMock.markPhase.mockReset();
-    historySessionDiagnosticsMock.beginHistorySessionDiagnostics.mockReset();
-    historySessionDiagnosticsMock.beginHistorySessionDiagnostics.mockReturnValue('diag-1');
-    historySessionDiagnosticsMock.recordHistorySessionDiagnosticEvent.mockReset();
-    historySessionDiagnosticsMock.warnHistorySessionLoadingLayerStalled.mockReset();
-    agentApiMock.listBackgroundCommandActivities.mockClear();
-    agentApiMock.listBackgroundCommandActivities.mockResolvedValue({ activities: [] });
-    searchStateMock.searchQuery = '';
-    searchStateMock.onSearchChange.mockReset();
-    searchStateMock.matches = [];
-    searchStateMock.matchIndices = [];
-    searchStateMock.currentMatchIndex = -1;
-    searchStateMock.currentMatchVirtualIndex = -1;
-    searchStateMock.goToNext.mockReset();
-    searchStateMock.goToPrev.mockReset();
-    searchStateMock.clearSearch.mockReset();
-    headerPropsMock.latest = null;
-    virtualListPropsMock.latest = null;
-    navigationOptionsMock.latest = null;
-    clearHistorySessionOpenTransition();
-  });
-
-  afterEach(() => {
-    if (root) {
-      act(() => {
-        root.unmount();
-      });
-    }
-    container?.remove();
-    stateMocks.activeSession = null;
-    clearHistorySessionOpenTransition();
-    vi.useRealTimers();
-    vi.unstubAllGlobals();
-  });
-
-  it('shows a history loading shell for metadata-only sessions instead of the new-session welcome', () => {
-    stateMocks.activeSession = createSession({ historyState: 'metadata-only' } as Partial<Session>);
-
-    act(() => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    expect(container.textContent).toContain('Loading saved session');
-    expect(container.querySelector('[data-testid="welcome-panel"]')).toBeNull();
-  });
-
-  it('defers viewport anchoring while the host scene is inactive', () => {
-    const turn = createTurn('turn-1', 'One');
-    stateMocks.activeSession = createSession({
-      dialogTurns: [turn],
-      historyState: 'ready',
-      contextRestoreState: 'ready',
-    });
-    stateMocks.virtualItems = [{
-      type: 'user-message',
-      turnId: turn.id,
-      data: turn.userMessage,
-    }];
-
-    act(() => {
-      root.render(<ModernFlowChatContainer isViewportActive={false} />);
-    });
-
-    expect(virtualListPropsMock.latest).toMatchObject({ isViewportActive: false });
-    expect(virtualListMock.scrollToTurnEndAndClearPin).not.toHaveBeenCalled();
-
-    act(() => {
-      root.render(<ModernFlowChatContainer isViewportActive />);
-    });
-
-    expect(virtualListPropsMock.latest).toMatchObject({ isViewportActive: true });
-    expect(virtualListMock.scrollToTurnEndAndClearPin).toHaveBeenCalledWith(turn.id);
-  });
-
-  it('keeps the loading shell while historical sessions are hydrating', () => {
-    stateMocks.activeSession = createSession({ historyState: 'hydrating' } as Partial<Session>);
-
-    act(() => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    expect(container.textContent).toContain('Loading saved session');
-    expect(container.querySelector('[data-testid="welcome-panel"]')).toBeNull();
-  });
-
-  it('renders a host-provided empty state instead of the generic welcome panel', () => {
-    stateMocks.activeSession = createSession({
-      isHistorical: false,
-      historyState: 'new',
-      dialogTurns: [],
-    } as Partial<Session>);
-
-    act(() => {
-      root.render(
-        <ModernFlowChatContainer
-          emptyState={<div data-testid="miniapp-welcome">MiniApp welcome</div>}
-        />
-      );
-    });
-
-    expect(container.querySelector('[data-testid="miniapp-welcome"]')).not.toBeNull();
-    expect(container.querySelector('[data-testid="welcome-panel"]')).toBeNull();
-  });
-
-  it('reports a stalled history loading layer after the diagnostic threshold', async () => {
-    vi.useFakeTimers();
-    stateMocks.activeSession = createSession({
-      sessionId: 'history-session',
-      historyState: 'metadata-only',
-      dialogTurns: [],
-    } as Partial<Session>);
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    expect(container.textContent).toContain('Loading saved session');
-    expect(historySessionDiagnosticsMock.warnHistorySessionLoadingLayerStalled).not.toHaveBeenCalled();
-
-    await act(async () => {
-      await vi.advanceTimersByTimeAsync(799);
-    });
-
-    expect(historySessionDiagnosticsMock.warnHistorySessionLoadingLayerStalled).not.toHaveBeenCalled();
-
-    await act(async () => {
-      await vi.advanceTimersByTimeAsync(1);
-    });
-
-    expect(historySessionDiagnosticsMock.warnHistorySessionLoadingLayerStalled).toHaveBeenCalledWith(
-      'history-session',
-      expect.objectContaining({
-        durationMs: 800,
-        historyState: 'metadata-only',
-        isHistorical: true,
-        isRemote: false,
-        activeSessionIdMatches: true,
-        hasRenderableContent: false,
-        dialogTurnCount: 0,
-      }),
-    );
-  });
-
-  it('does not show the new-session welcome while a restored session is waiting for virtual items', () => {
-    stateMocks.activeSession = createSession({
-      isHistorical: false,
-      historyState: 'ready',
-      dialogTurns: [{
-        id: 'turn-1',
-        turnId: 'turn-1',
-        sessionId: 'session-1',
-        timestamp: 1,
-        userMessage: { id: 'user-1', content: 'Saved prompt', timestamp: 1 },
-        modelRounds: [],
-        startTime: 1,
-        status: 'completed',
-      }],
-    } as Partial<Session>);
-
-    act(() => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    expect(container.textContent).toContain('Loading saved session');
-    expect(container.querySelector('[data-testid="welcome-panel"]')).toBeNull();
-  });
-
-  it('covers the current message list after a historical session open intent', async () => {
-    stateMocks.activeSession = createSession({
-      sessionId: 'current-session',
-      isHistorical: false,
-      historyState: 'ready',
-      dialogTurns: [createTurn('turn-1', 'Current visible prompt')],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [
-      { type: 'user-message', turnId: 'turn-1', data: { id: 'user-turn-1', content: 'Current visible prompt' } },
-    ];
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    expect(container.querySelector('[data-testid="virtual-list"]')).not.toBeNull();
-    expect(container.querySelector('.modern-flowchat-container__history-overlay')).toBeNull();
-
-    act(() => {
-      window.dispatchEvent(new CustomEvent(HISTORY_SESSION_OPEN_INTENT_EVENT, {
-        detail: { sessionId: 'history-session', sessionTitle: 'Saved investigation' },
-      }));
-    });
-
-    expect(container.textContent).not.toContain('Loading saved session');
-    expect(container.querySelector('[data-testid="virtual-list"]')).not.toBeNull();
-    expect(container.querySelector('.modern-flowchat-container__history-overlay')).toBeNull();
-    expect(container.querySelector('.modern-flowchat-container__history-open-intent-shield')).not.toBeNull();
-    expect(container.querySelector('.modern-flowchat-container__history-open-intent-spinner')).not.toBeNull();
-    expect(container.textContent).toContain('Hidden action');
-    expect(container.textContent).not.toContain('Saved investigation');
-    expect(container.querySelector('.modern-flowchat-container__messages')?.getAttribute('data-show-history-open-intent-overlay'))
-      .toBe('true');
-    (container.querySelector('[data-testid="virtual-list-action"]') as HTMLButtonElement | null)?.click();
-    expect(virtualListActionClickMock).not.toHaveBeenCalled();
-
-    stateMocks.activeSession = createSession({
-      sessionId: 'history-session',
-      historyState: 'metadata-only',
-    } as Partial<Session>);
-    stateMocks.virtualItems = [];
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    expect(container.textContent).not.toContain('Loading saved session');
-    expect(container.querySelector('.modern-flowchat-container__history-overlay')).toBeNull();
-    expect(container.querySelector('[data-testid="welcome-panel"]')).toBeNull();
-    expect(container.querySelector('.modern-flowchat-container__history-open-intent-shield')).not.toBeNull();
-    expect(container.querySelector('.modern-flowchat-container__messages')?.getAttribute('data-show-history-loading-layer'))
-      .toBe('false');
-    expect(container.querySelector('.modern-flowchat-container__messages')?.getAttribute('data-show-history-open-intent-overlay'))
-      .toBe('true');
-
-    stateMocks.activeSession = createSession({
-      sessionId: 'history-session',
-      isHistorical: false,
-      historyState: 'ready',
-      dialogTurns: [createTurn('turn-2', 'Restored latest prompt')],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [
-      { type: 'user-message', turnId: 'turn-2', data: { id: 'user-turn-2', content: 'Restored latest prompt' } },
-    ];
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    expect(container.querySelector('[data-testid="virtual-list"]')).not.toBeNull();
-    expect(container.querySelector('.modern-flowchat-container__history-open-intent-shield')).toBeNull();
-    expect(container.querySelector('.modern-flowchat-container__messages')?.getAttribute('data-show-history-open-intent-overlay'))
-      .toBe('false');
+describe('ModernFlowChatContainer natural navigation contract', () => {
+  it('restores historical tails through natural end alignment', () => {
+    expect(componentSource).toContain('scrollToTurnEnd(latestTurnId)');
+    expect(componentSource).toContain('prepareTurnNavigation');
   });
 
-  it('removes the loading layer when a hydrating session receives its initial tail turns', async () => {
-    stateMocks.activeSession = createSession({
-      sessionId: 'history-session',
-      historyState: 'hydrating',
-      dialogTurns: [],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [];
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    const initialOverlay = container.querySelector('.modern-flowchat-container__history-overlay');
-    expect(initialOverlay).not.toBeNull();
-    expect(container.querySelector('[data-testid="virtual-list"]')).toBeNull();
-
-    stateMocks.activeSession = createSession({
-      sessionId: 'history-session',
-      isHistorical: false,
-      historyState: 'ready',
-      contextRestoreState: 'pending',
-      dialogTurns: [
-        createTurn('turn-1', 'Older restored prompt'),
-        createTurn('turn-2', 'Latest restored prompt'),
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [
-      { type: 'user-message', turnId: 'turn-1', data: { id: 'user-turn-1', content: 'Older restored prompt' } },
-      { type: 'user-message', turnId: 'turn-2', data: { id: 'user-turn-2', content: 'Latest restored prompt' } },
-    ];
-    virtualListMock.isTurnTextRenderedInViewport.mockReturnValue(false);
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    expect(container.querySelector('[data-testid="virtual-list"]')).not.toBeNull();
-    expect(container.querySelector('.modern-flowchat-container__history-overlay')).not.toBe(initialOverlay);
-    expect(container.querySelector('.modern-flowchat-container__history-overlay')).toBeNull();
-    expect(container.textContent).not.toContain('Loading saved session');
-    expect(container.querySelector('.modern-flowchat-container__messages')?.getAttribute('data-show-history-transition-overlay'))
-      .toBe('true');
-  });
-
-  it('keeps restored content visible while restored latest text is not ready', async () => {
-    stateMocks.activeSession = createSession({
-      isHistorical: false,
-      historyState: 'ready',
-      contextRestoreState: 'pending',
-      dialogTurns: [
-        createTurn('turn-1', 'Older restored prompt'),
-        createTurn('turn-2', 'Latest restored prompt'),
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [
-      { type: 'user-message', turnId: 'turn-1', data: { id: 'user-turn-1', content: 'Older restored prompt' } },
-      { type: 'user-message', turnId: 'turn-2', data: { id: 'user-turn-2', content: 'Latest restored prompt' } },
-    ];
-    virtualListMock.isTurnTextRenderedInViewport.mockReturnValue(false);
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    expect(container.querySelector('[data-testid="virtual-list"]')).not.toBeNull();
-    expect(container.textContent).not.toContain('Loading saved session');
-    expect(container.querySelector('.modern-flowchat-container__history-overlay')).toBeNull();
-    expect(container.querySelector('.modern-flowchat-container__messages')?.getAttribute('data-show-history-transition-overlay'))
-      .toBe('true');
-
-    flushAnimationFrame();
-    expect(container.querySelector('[data-testid="virtual-list"]')).not.toBeNull();
-    expect(container.textContent).not.toContain('Loading saved session');
-    expect(container.querySelector('.modern-flowchat-container__history-overlay')).toBeNull();
-
-    virtualListMock.isTurnTextRenderedInViewport.mockReturnValue(true);
-    flushAnimationFrame();
-
-    expect(container.textContent).not.toContain('Loading saved session');
-    expect(container.querySelector('.modern-flowchat-container__history-overlay')).toBeNull();
-  });
-
-  it('does not show the initial history progress again when full hydration adds older turns', async () => {
-    stateMocks.activeSession = createSession({
-      isHistorical: false,
-      historyState: 'ready',
-      contextRestoreState: 'pending',
-      dialogTurns: [
-        createTurn('turn-1', 'Older restored prompt'),
-        createTurn('turn-2', 'Latest restored prompt'),
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [
-      { type: 'user-message', turnId: 'turn-1', data: { id: 'user-turn-1', content: 'Older restored prompt' } },
-      { type: 'user-message', turnId: 'turn-2', data: { id: 'user-turn-2', content: 'Latest restored prompt' } },
-    ];
-    virtualListMock.isTurnTextRenderedInViewport.mockReturnValue(false);
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    expect(container.querySelector('.modern-flowchat-container__history-overlay')).toBeNull();
-
-    virtualListMock.isTurnTextRenderedInViewport.mockReturnValue(true);
-    flushAnimationFrame();
-
-    expect(container.querySelector('.modern-flowchat-container__history-overlay')).toBeNull();
-
-    stateMocks.activeSession = createSession({
-      isHistorical: false,
-      historyState: 'ready',
-      contextRestoreState: 'pending',
-      dialogTurns: [
-        createTurn('turn-0', 'Restored older prompt'),
-        createTurn('turn-1', 'Older restored prompt'),
-        createTurn('turn-2', 'Latest restored prompt'),
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [
-      { type: 'user-message', turnId: 'turn-0', data: { id: 'user-turn-0', content: 'Restored older prompt' } },
-      { type: 'user-message', turnId: 'turn-1', data: { id: 'user-turn-1', content: 'Older restored prompt' } },
-      { type: 'user-message', turnId: 'turn-2', data: { id: 'user-turn-2', content: 'Latest restored prompt' } },
-    ];
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    expect(container.querySelector('.modern-flowchat-container__history-overlay')).toBeNull();
-  });
-
-  it('blocks pointer activation until restored latest text is visible', async () => {
-    const releaseSpy = vi
-      .spyOn(flowChatStore, 'releaseSessionHistoryCompletionAfterInitialPaint')
-      .mockReturnValue(true);
-
-    stateMocks.activeSession = createSession({
-      isHistorical: false,
-      historyState: 'ready',
-      contextRestoreState: 'pending',
-      dialogTurns: [
-        createTurn('turn-1', 'Older restored prompt'),
-        createTurn('turn-2', 'Latest restored prompt'),
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [
-      { type: 'user-message', turnId: 'turn-1', data: { id: 'user-turn-1', content: 'Older restored prompt' } },
-      { type: 'user-message', turnId: 'turn-2', data: { id: 'user-turn-2', content: 'Latest restored prompt' } },
-    ];
-    virtualListMock.isTurnTextRenderedInViewport.mockReturnValue(false);
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    const hiddenAction = container.querySelector('[data-testid="virtual-list-action"]') as HTMLButtonElement;
-    expect(hiddenAction).not.toBeNull();
-    expect(container.textContent).not.toContain('Loading saved session');
-    expect(container.querySelector('.modern-flowchat-container__history-overlay')).toBeNull();
-
-    act(() => {
-      hiddenAction.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true }));
-    });
-
-    expect(virtualListActionClickMock).not.toHaveBeenCalled();
-
-    virtualListMock.isTurnTextRenderedInViewport.mockReturnValue(true);
-    flushAnimationFrame();
-    flushAnimationFrame();
-    flushAnimationFrame();
-
-    expect(container.querySelector('.modern-flowchat-container__history-overlay')).toBeNull();
-    expect(releaseSpy).toHaveBeenCalledWith('session-1');
-    expect(startupTraceMock.markPhase).toHaveBeenCalledWith(
-      'historical_session_initial_content_painted',
-      expect.objectContaining({
-        sessionId: 'session-1',
-        latestTurnId: 'turn-2',
-        released: true,
-      }),
-    );
-
-    act(() => {
-      hiddenAction.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true }));
-    });
-
-    expect(virtualListActionClickMock).toHaveBeenCalledTimes(1);
-    releaseSpy.mockRestore();
-  });
-
-  it('defers background command snapshot until restored latest text is visible and painted', async () => {
-    const releaseSpy = vi
-      .spyOn(flowChatStore, 'releaseSessionHistoryCompletionAfterInitialPaint')
-      .mockReturnValue(true);
-
-    stateMocks.activeSession = createSession({
-      isHistorical: false,
-      historyState: 'ready',
-      contextRestoreState: 'pending',
-      dialogTurns: [
-        createTurn('turn-1', 'Older restored prompt'),
-        createTurn('turn-2', 'Latest restored prompt'),
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [
-      { type: 'user-message', turnId: 'turn-1', data: { id: 'user-turn-1', content: 'Older restored prompt' } },
-      { type: 'user-message', turnId: 'turn-2', data: { id: 'user-turn-2', content: 'Latest restored prompt' } },
-    ];
-    virtualListMock.isTurnTextRenderedInViewport.mockReturnValue(false);
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    expect(agentApiMock.listBackgroundCommandActivities).not.toHaveBeenCalled();
-
-    virtualListMock.isTurnTextRenderedInViewport.mockReturnValue(true);
-    flushAnimationFrame();
-    expect(releaseSpy).not.toHaveBeenCalled();
-    expect(agentApiMock.listBackgroundCommandActivities).not.toHaveBeenCalled();
-
-    flushAnimationFrame();
-    expect(releaseSpy).not.toHaveBeenCalled();
-    expect(agentApiMock.listBackgroundCommandActivities).not.toHaveBeenCalled();
-
-    flushAnimationFrame();
-    expect(releaseSpy).toHaveBeenCalledWith('session-1');
-    expect(agentApiMock.listBackgroundCommandActivities).not.toHaveBeenCalled();
-
-    flushAnimationFrame();
-    expect(agentApiMock.listBackgroundCommandActivities).not.toHaveBeenCalled();
-
-    flushAnimationFrame();
-    expect(agentApiMock.listBackgroundCommandActivities).toHaveBeenCalledTimes(1);
-    expect(agentApiMock.listBackgroundCommandActivities).toHaveBeenCalledWith({
-      agentSessionId: 'session-1',
-    });
-
-    releaseSpy.mockRestore();
-  });
-
-  it('skips stale background command snapshot when another history session open starts first', async () => {
-    const releaseSpy = vi
-      .spyOn(flowChatStore, 'releaseSessionHistoryCompletionAfterInitialPaint')
-      .mockReturnValue(true);
-
-    stateMocks.activeSession = createSession({
-      isHistorical: false,
-      historyState: 'ready',
-      contextRestoreState: 'pending',
-      dialogTurns: [
-        createTurn('turn-1', 'Older restored prompt'),
-        createTurn('turn-2', 'Latest restored prompt'),
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [
-      { type: 'user-message', turnId: 'turn-1', data: { id: 'user-turn-1', content: 'Older restored prompt' } },
-      { type: 'user-message', turnId: 'turn-2', data: { id: 'user-turn-2', content: 'Latest restored prompt' } },
-    ];
-    virtualListMock.isTurnTextRenderedInViewport.mockReturnValue(false);
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    virtualListMock.isTurnTextRenderedInViewport.mockReturnValue(true);
-    flushAnimationFrame();
-    flushAnimationFrame();
-
-    act(() => {
-      dispatchHistorySessionOpenIntent('session-2', 'Next saved session');
-    });
-    flushAnimationFrame();
-
-    expect(releaseSpy).toHaveBeenCalledWith('session-1');
-    flushAnimationFrame();
-    flushAnimationFrame();
-    expect(agentApiMock.listBackgroundCommandActivities).not.toHaveBeenCalled();
-
-    releaseSpy.mockRestore();
-  });
-
-  it('keeps full history projection deferred when latest text visibility signal is missed', async () => {
-    const releaseSpy = vi
-      .spyOn(flowChatStore, 'releaseSessionHistoryCompletionAfterInitialPaint')
-      .mockReturnValue(true);
-
-    stateMocks.activeSession = createSession({
-      isHistorical: false,
-      historyState: 'ready',
-      contextRestoreState: 'pending',
-      dialogTurns: [
-        createTurn('turn-1', 'Older restored prompt'),
-        createTurn('turn-2', 'Latest restored prompt'),
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [
-      { type: 'user-message', turnId: 'turn-1', data: { id: 'user-turn-1', content: 'Older restored prompt' } },
-      { type: 'user-message', turnId: 'turn-2', data: { id: 'user-turn-2', content: 'Latest restored prompt' } },
-    ];
-    virtualListMock.isTurnTextRenderedInViewport.mockReturnValue(false);
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    for (let index = 0; index < 30; index += 1) {
-      flushAnimationFrame();
-    }
-
-    expect(container.textContent).not.toContain('Loading saved session');
-    expect(releaseSpy).not.toHaveBeenCalled();
-    expect(startupTraceMock.markPhase).toHaveBeenCalledWith(
-      'historical_session_initial_content_paint_signal_missed',
-      expect.objectContaining({ attempts: 30 }),
-    );
-
-    releaseSpy.mockRestore();
-  });
-
-  it('requests full history when search starts from a partial session', async () => {
-    const ensureSpy = vi
-      .spyOn(flowChatStore, 'ensureSessionFullHistory')
-      .mockResolvedValue(true);
-
-    stateMocks.activeSession = createSession({
-      isHistorical: false,
-      historyState: 'ready',
-      contextRestoreState: 'ready',
-      isPartial: true,
-      dialogTurns: [
-        createTurn('turn-2', 'Latest restored prompt'),
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [
-      { type: 'user-message', turnId: 'turn-2', data: { id: 'user-turn-2', content: 'Latest restored prompt' } },
-    ];
-    virtualListMock.isTurnTextRenderedInViewport.mockReturnValue(false);
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    await act(async () => {
-      (headerPropsMock.latest?.onSearchChange as ((query: string) => void) | undefined)?.(
-        'older prompt',
-      );
-      await Promise.resolve();
-    });
-
-    expect(searchStateMock.onSearchChange).toHaveBeenCalledWith('older prompt');
-    expect(ensureSpy).toHaveBeenCalledWith('session-1', 'flowchat-search');
-  });
-
-  it('repositions an unchanged virtual match when the search query changes', async () => {
-    stateMocks.activeSession = createSession({
-      isHistorical: false,
-      historyState: 'ready',
-      dialogTurns: [createTurn('turn-1', 'Searchable prompt')],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [
-      { type: 'user-message', turnId: 'turn-1', data: { id: 'user-turn-1', content: 'Searchable prompt' } },
-    ];
-    searchStateMock.searchQuery = 'search';
-    searchStateMock.matches = [{
-      virtualItemIndex: 0,
-      turnId: 'turn-1',
-      type: 'user-message',
-      occurrenceIndex: 0,
-    }];
-    searchStateMock.currentMatchIndex = 0;
-    searchStateMock.currentMatchVirtualIndex = 0;
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-    flushAnimationFrame();
-
-    expect(virtualListMock.scrollToSearchMatch).toHaveBeenLastCalledWith({
-      virtualItemIndex: 0,
-      query: 'search',
-      flowItemId: undefined,
-      occurrenceIndex: 0,
-      expandableIds: undefined,
-    });
-
-    searchStateMock.searchQuery = 'searchable';
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-    flushAnimationFrame();
-
-    expect(virtualListMock.scrollToSearchMatch).toHaveBeenCalledTimes(2);
-    expect(virtualListMock.scrollToSearchMatch).toHaveBeenLastCalledWith({
-      virtualItemIndex: 0,
-      query: 'searchable',
-      flowItemId: undefined,
-      occurrenceIndex: 0,
-      expandableIds: undefined,
-    });
-  });
-
-  it('keeps the new-session welcome for genuinely new empty sessions', () => {
-    stateMocks.activeSession = createSession({
-      isHistorical: false,
-      historyState: 'new',
-    } as Partial<Session>);
-
-    act(() => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    expect(container.querySelector('[data-testid="welcome-panel"]')).not.toBeNull();
-  });
-
-  it('shows retry for failed history loads', () => {
-    stateMocks.activeSession = createSession({ historyState: 'failed' } as Partial<Session>);
-
-    act(() => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    const retryButton = Array.from(container.querySelectorAll('button'))
-      .find(button => button.textContent?.includes('Retry'));
-    expect(container.textContent).toContain('Session history did not load');
-    expect(retryButton).toBeTruthy();
-
-    act(() => {
-      retryButton?.dispatchEvent(new MouseEvent('click', { bubbles: true }));
-    });
-
-    expect(switchChatSessionMock).toHaveBeenCalledWith('session-1');
-  });
-
-  it('shows global turn numbers for partial tail history while navigation stays within loaded turns', async () => {
-    stateMocks.activeSession = createSession({
-      isHistorical: false,
-      historyState: 'ready',
-      isPartial: true,
-      loadedTurnCount: 2,
-      totalTurnCount: 100,
-      dialogTurns: [
-        createTurn('turn-99', 'Recent restored prompt'),
-        createTurn('turn-100', 'Latest restored prompt'),
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [
-      { type: 'user-message', turnId: 'turn-99', data: { id: 'user-turn-99', content: 'Recent restored prompt' } },
-      { type: 'user-message', turnId: 'turn-100', data: { id: 'user-turn-100', content: 'Latest restored prompt' } },
-    ];
-    stateMocks.visibleTurnInfo = {
-      turnId: 'turn-100',
-      turnIndex: 2,
-      totalTurns: 2,
-      userMessage: 'Latest restored prompt',
-      visibleTurnIds: ['turn-99', 'turn-100'],
-    };
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    expect(headerPropsMock.latest).toMatchObject({
-      currentTurn: 100,
-      totalTurns: 100,
-    });
-    const previousTurnRailItem = container.querySelector<HTMLButtonElement>('[data-turn-id="turn-99"]');
-    const currentTurnRailItem = container.querySelector<HTMLButtonElement>('[data-turn-id="turn-100"]');
-    expect(previousTurnRailItem?.dataset.turnIndex).toBe('99');
-    expect(currentTurnRailItem?.dataset.turnIndex).toBe('100');
-    expect(currentTurnRailItem?.getAttribute('aria-current')).toBe('step');
-    expect(previousTurnRailItem?.className).toContain('flowchat-turn-rail__item--visible');
-    expect(currentTurnRailItem?.className).toContain('flowchat-turn-rail__item--visible');
-
-    clickTurnRailItem(container, 'turn-99');
-
-    expect(virtualListMock.pinTurnToTopWithStatus).toHaveBeenLastCalledWith('turn-99', {
-      behavior: 'auto',
-      pinMode: 'transient',
-      alignmentPolicy: 'best-effort',
-    });
-
-  });
-
-  it('treats the latest streaming Turn marker as transient immediate navigation', async () => {
-    const streamingTurn = {
-      ...createTurn('turn-2', 'Streaming prompt', 'processing'),
-      modelRounds: [{
-        id: 'round-2',
-        index: 0,
-        items: [{
-          id: 'text-2',
-          type: 'text' as const,
-          content: 'Streaming output',
-          isStreaming: true,
-          timestamp: 1,
-          status: 'streaming' as const,
-        }],
-        isStreaming: true,
-        isComplete: false,
-        status: 'streaming' as const,
-        startTime: 1,
-      }],
-    } as Session['dialogTurns'][number];
-    stateMocks.activeSession = createSession({
-      isHistorical: false,
-      historyState: 'ready',
-      dialogTurns: [
-        createTurn('turn-1', 'Older prompt'),
-        streamingTurn,
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [
-      { type: 'user-message', turnId: 'turn-1', data: { id: 'user-turn-1', content: 'Older prompt' } },
-      { type: 'user-message', turnId: 'turn-2', data: { id: 'user-turn-2', content: 'Streaming prompt' } },
-    ];
-    stateMocks.visibleTurnInfo = {
-      turnId: 'turn-1',
-      turnIndex: 1,
-      totalTurns: 2,
-      userMessage: 'Older prompt',
-    };
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    const restoreTailSpy = vi.spyOn(flowChatStore, 'restoreSessionTailPresentation');
-    const latestEndCallCount = virtualListMock.scrollToLatestEndPosition.mock.calls.length;
-    clickTurnRailItem(container, 'turn-2');
-
-    expect(virtualListMock.pinTurnToTopWithStatus).toHaveBeenLastCalledWith('turn-2', {
-      behavior: 'auto',
-      pinMode: 'transient',
-      alignmentPolicy: 'best-effort',
-    });
-    expect(restoreTailSpy).not.toHaveBeenCalled();
-    expect(virtualListMock.scrollToLatestEndPosition.mock.calls.length).toBe(latestEndCallCount);
-
-    restoreTailSpy.mockRestore();
-  });
-
-  it('keeps an active history presentation when its latest Turn marker is selected', async () => {
-    const presentationTurns = Array.from(
-      { length: 8 },
-      (_, index) => createTurn(`turn-${index + 3}`, `Prompt ${index + 3}`),
-    );
-    const catalog = {
-      schemaVersion: 1,
-      sessionId: 'session-1',
-      revision: 'catalog-v1',
-      totalTurnCount: 10,
-      complete: true,
-      entries: Array.from({ length: 10 }, (_, ordinal) => ({
-        ordinal,
-        storageTurnIndex: ordinal,
-        turnId: `turn-${ordinal + 1}`,
-        preview: `Prompt ${ordinal + 1}`,
-        previewTruncated: false,
-      })),
-    };
-    const loadSpy = vi.spyOn(flowChatStore, 'loadSessionTurnWindow').mockResolvedValue({
-      status: 'ready',
-      sessionId: 'session-1',
-      targetOrdinal: 4,
-      targetTurnId: 'turn-5',
-      navigationGeneration: 7,
-      isCurrent: true,
-      cacheHit: true,
-      catalog,
-      range: {
-        startOrdinal: 2,
-        endOrdinalExclusive: 10,
-        turns: presentationTurns,
-        lastAccessedAt: 1,
-        source: 'target',
-      },
-    });
-    const activateSpy = vi.spyOn(flowChatStore, 'activateSessionHistoryWindow').mockReturnValue({
-      range: {
-        startOrdinal: 2,
-        endOrdinalExclusive: 10,
-        targetTurnId: 'turn-5',
-        mode: 'history-window',
-      },
-      turns: presentationTurns,
-    });
-    stateMocks.activeSession = createSession({
-      historyState: 'ready',
-      isPartial: true,
-      totalTurnCount: 10,
-      turnCatalog: catalog,
-      dialogTurns: [
-        createTurn('turn-9', 'Recent prompt'),
-        createTurn('turn-10', 'Latest prompt'),
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = stateMocks.activeSession.dialogTurns.map(turn => ({
-      type: 'user-message',
-      turnId: turn.id,
-      data: turn.userMessage,
-    }));
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-    await act(async () => {
-      container.querySelector<HTMLButtonElement>('[data-turn-id="turn-5"]')?.click();
-      await Promise.resolve();
-    });
-    expect(virtualListPropsMock.latest).toMatchObject({ presentationMode: 'history-window' });
-
-    const restoreTailSpy = vi.spyOn(flowChatStore, 'restoreSessionTailPresentation');
-    const latestEndCallCount = virtualListMock.scrollToLatestEndPosition.mock.calls.length;
-    scrollTurnRailToOrdinal(container, 9);
-    clickTurnRailItem(container, 'turn-10');
-
-    expect(virtualListMock.pinTurnToTopWithStatus).toHaveBeenLastCalledWith('turn-10', {
-      behavior: 'auto',
-      pinMode: 'transient',
-      alignmentPolicy: 'best-effort',
-    });
-    expect(restoreTailSpy).not.toHaveBeenCalled();
-    expect(virtualListPropsMock.latest).toMatchObject({ presentationMode: 'history-window' });
-    expect(virtualListMock.scrollToLatestEndPosition.mock.calls.length).toBe(latestEndCallCount);
-
-    stateMocks.activeSession = {
-      ...stateMocks.activeSession,
-      dialogTurns: [
-        createTurn('turn-9', 'Recent prompt'),
-        createTurn('turn-10', 'Latest live update', 'processing'),
-      ],
-    };
-    stateMocks.virtualItems = stateMocks.activeSession.dialogTurns.map(turn => ({
-      type: 'user-message',
-      turnId: turn.id,
-      data: turn.userMessage,
-    }));
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-    const liveLatestItem = (virtualListPropsMock.latest?.items as Array<{
-      type: string;
-      turnId?: string;
-      data?: { content?: string };
-    }>).find(item => item.type === 'user-message' && item.turnId === 'turn-10');
-    expect(liveLatestItem?.data?.content).toBe('Latest live update');
-    expect(virtualListPropsMock.latest).toMatchObject({ presentationMode: 'history-window' });
-
-    await act(async () => {
-      (virtualListPropsMock.latest?.onRequestJumpToLatest as (() => void) | undefined)?.();
-    });
-    flushAnimationFrame();
-    expect(restoreTailSpy).toHaveBeenCalledOnce();
-    expect(restoreTailSpy).toHaveBeenLastCalledWith('session-1');
-    expect(virtualListPropsMock.latest).toMatchObject({ presentationMode: 'tail' });
-    expect(virtualListMock.scrollToLatestEndPosition.mock.calls.length).toBe(latestEndCallCount + 1);
-
-    const tailAnchorCallCount = virtualListMock.scrollToTurnEndAndClearPin.mock.calls.length;
-    stateMocks.activeSession = {
-      ...stateMocks.activeSession,
-      totalTurnCount: 11,
-      dialogTurns: [
-        ...stateMocks.activeSession.dialogTurns,
-        createTurn('turn-11', 'New completed prompt'),
-      ],
-    };
-    stateMocks.virtualItems = stateMocks.activeSession.dialogTurns.map(turn => ({
-      type: 'user-message',
-      turnId: turn.id,
-      data: turn.userMessage,
-    }));
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-    flushAnimationFrame();
-    expect(virtualListPropsMock.latest).toMatchObject({ presentationMode: 'tail' });
-    expect(virtualListMock.scrollToTurnEndAndClearPin.mock.calls.length).toBe(tailAnchorCallCount + 1);
-    expect(virtualListMock.scrollToTurnEndAndClearPin).toHaveBeenLastCalledWith('turn-11');
-
-    const reactivateSpy = vi.spyOn(flowChatStore, 'reactivateSessionHistoryWindow').mockReturnValue({
-      range: {
-        startOrdinal: 2,
-        endOrdinalExclusive: 10,
-        targetTurnId: 'turn-5',
-        mode: 'history-window',
-      },
-      turns: presentationTurns,
-    });
-    scrollTurnRailToOrdinal(container, 4);
-    clickTurnRailItem(container, 'turn-5');
-    expect(reactivateSpy).toHaveBeenCalledWith('session-1', {
-      startOrdinal: 2,
-      endOrdinalExclusive: 10,
-      targetTurnId: 'turn-5',
-      mode: 'history-window',
-    });
-    expect(loadSpy).toHaveBeenCalledTimes(1);
-    expect(virtualListPropsMock.latest).toMatchObject({ presentationMode: 'history-window' });
-
-    reactivateSpy.mockRestore();
-    restoreTailSpy.mockRestore();
-    loadSpy.mockRestore();
-    activateSpy.mockRestore();
-  });
-
-  it('retains a complete small history projection when jumping to the latest Turn', async () => {
-    const presentationTurns = Array.from(
-      { length: 10 },
-      (_, index) => createTurn(`turn-${index + 1}`, `Prompt ${index + 1}`),
-    );
-    const catalog = {
-      schemaVersion: 1,
-      sessionId: 'session-1',
-      revision: 'catalog-complete-v1',
-      totalTurnCount: 10,
-      complete: true,
-      entries: Array.from({ length: 10 }, (_, ordinal) => ({
-        ordinal,
-        storageTurnIndex: ordinal,
-        turnId: `turn-${ordinal + 1}`,
-        preview: `Prompt ${ordinal + 1}`,
-        previewTruncated: false,
-      })),
-    };
-    const loadSpy = vi.spyOn(flowChatStore, 'loadSessionTurnWindow').mockResolvedValue({
-      status: 'ready',
-      sessionId: 'session-1',
-      targetOrdinal: 4,
-      targetTurnId: 'turn-5',
-      navigationGeneration: 8,
-      isCurrent: true,
-      cacheHit: true,
-      catalog,
-      range: {
-        startOrdinal: 0,
-        endOrdinalExclusive: 10,
-        turns: presentationTurns,
-        lastAccessedAt: 1,
-        source: 'target',
-      },
-    });
-    const activateSpy = vi.spyOn(flowChatStore, 'activateSessionHistoryWindow').mockReturnValue({
-      range: {
-        startOrdinal: 0,
-        endOrdinalExclusive: 10,
-        targetTurnId: 'turn-5',
-        mode: 'history-window',
-      },
-      turns: presentationTurns,
-    });
-    stateMocks.activeSession = createSession({
-      historyState: 'ready',
-      isPartial: true,
-      totalTurnCount: 10,
-      turnCatalog: catalog,
-      dialogTurns: [
-        createTurn('turn-9', 'Recent prompt'),
-        createTurn('turn-10', 'Latest prompt'),
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = stateMocks.activeSession.dialogTurns.map(turn => ({
-      type: 'user-message',
-      turnId: turn.id,
-      data: turn.userMessage,
-    }));
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-    await act(async () => {
-      container.querySelector<HTMLButtonElement>('[data-turn-id="turn-5"]')?.click();
-      await Promise.resolve();
-    });
-
-    expect(loadSpy).toHaveBeenCalledWith('session-1', 4, { source: 'target' });
-    expect(virtualListPropsMock.latest).toMatchObject({
-      presentationMode: 'history-window',
-      viewportMode: 'history-reading',
-    });
-    expect((virtualListPropsMock.latest?.items as Array<{ turnId: string }>).map(item => item.turnId))
-      .toEqual(presentationTurns.map(turn => turn.id));
-
-    const restoreTailSpy = vi.spyOn(flowChatStore, 'restoreSessionTailPresentation');
-    const initialItems = virtualListPropsMock.latest?.items;
-    await act(async () => {
-      (virtualListPropsMock.latest?.onRequestJumpToLatest as (() => void) | undefined)?.();
-    });
-
-    expect(restoreTailSpy).not.toHaveBeenCalled();
-    expect(virtualListPropsMock.latest).toMatchObject({
-      presentationMode: 'history-window',
-      viewportMode: 'live-tail',
-      historyWindow: null,
-    });
-    expect(virtualListPropsMock.latest?.items).toBe(initialItems);
-
-    stateMocks.activeSession = {
-      ...stateMocks.activeSession,
-      totalTurnCount: 11,
-      dialogTurns: [
-        createTurn('turn-10', 'Latest live update', 'processing'),
-        createTurn('turn-11', 'New live prompt', 'processing'),
-      ],
-    };
-    stateMocks.virtualItems = stateMocks.activeSession.dialogTurns.map(turn => ({
-      type: 'user-message',
-      turnId: turn.id,
-      data: turn.userMessage,
-    }));
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    expect(virtualListPropsMock.latest).toMatchObject({
-      presentationMode: 'history-window',
-      viewportMode: 'live-tail',
-    });
-    expect((virtualListPropsMock.latest?.items as Array<{ turnId: string }>).map(item => item.turnId))
-      .toEqual([...presentationTurns.map(turn => turn.id), 'turn-11']);
-    const liveLatestItem = (virtualListPropsMock.latest?.items as Array<{
-      turnId: string;
-      data?: { content?: string };
-    }>).find(item => item.turnId === 'turn-10');
-    expect(liveLatestItem?.data?.content).toBe('Latest live update');
-
-    restoreTailSpy.mockRestore();
-    loadSpy.mockRestore();
-    activateSpy.mockRestore();
-  });
-
-  it('retries turn-rail selection without advancing visible-turn state until the virtual list accepts it', async () => {
-    stateMocks.activeSession = createSession({
-      isHistorical: false,
-      historyState: 'ready',
-      dialogTurns: [
-        createTurn('turn-1', 'Older prompt'),
-        createTurn('turn-2', 'Latest prompt'),
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [
-      { type: 'user-message', turnId: 'turn-1', data: { id: 'user-turn-1', content: 'Older prompt' } },
-      { type: 'user-message', turnId: 'turn-2', data: { id: 'user-turn-2', content: 'Latest prompt' } },
-    ];
-    stateMocks.visibleTurnInfo = {
-      turnId: 'turn-2',
-      turnIndex: 2,
-      totalTurns: 2,
-      userMessage: 'Latest prompt',
-    };
-    virtualListMock.pinTurnToTopWithStatus.mockReturnValue('rejected');
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    expect(headerPropsMock.latest).toMatchObject({
-      currentTurn: 2,
-      totalTurns: 2,
-    });
-
-    clickTurnRailItem(container, 'turn-1');
-    expect(virtualListMock.pinTurnToTopWithStatus).toHaveBeenLastCalledWith('turn-1', {
-      behavior: 'auto',
-      pinMode: 'transient',
-      alignmentPolicy: 'best-effort',
-    });
-    expect(headerPropsMock.latest).toMatchObject({
-      currentTurn: 2,
-      totalTurns: 2,
-    });
-
-    virtualListMock.pinTurnToTopWithStatus.mockReturnValue('settled');
-    stateMocks.virtualItems = [
-      ...stateMocks.virtualItems,
-    ];
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-    flushAnimationFrame();
-
-    expect(virtualListMock.pinTurnToTopWithStatus).toHaveBeenLastCalledWith('turn-1', {
-      behavior: 'auto',
-      pinMode: 'transient',
-      alignmentPolicy: 'best-effort',
-    });
-    expect(headerPropsMock.latest).toMatchObject({
-      currentTurn: 2,
-      totalTurns: 2,
-    });
-
-    stateMocks.visibleTurnInfo = {
-      turnId: 'turn-1',
-      turnIndex: 1,
-      totalTurns: 2,
-      userMessage: 'Older prompt',
-    };
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    expect(headerPropsMock.latest).toMatchObject({
-      currentTurn: 1,
-      totalTurns: 2,
-    });
-  });
-
-  it('delegates accepted turn-rail selections to the list without container-level retry', async () => {
-    stateMocks.activeSession = createSession({
-      isHistorical: false,
-      historyState: 'ready',
-      dialogTurns: [
-        createTurn('turn-1', 'Older prompt'),
-        createTurn('turn-2', 'Latest prompt'),
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [
-      { type: 'user-message', turnId: 'turn-1', data: { id: 'user-turn-1', content: 'Older prompt' } },
-      { type: 'user-message', turnId: 'turn-2', data: { id: 'user-turn-2', content: 'Latest prompt' } },
-    ];
-    stateMocks.visibleTurnInfo = {
-      turnId: 'turn-2',
-      turnIndex: 2,
-      totalTurns: 2,
-      userMessage: 'Latest prompt',
-    };
-    virtualListMock.pinTurnToTopWithStatus.mockReturnValue('settled');
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    clickTurnRailItem(container, 'turn-1');
-    expect(virtualListMock.pinTurnToTopWithStatus).toHaveBeenLastCalledWith('turn-1', {
-      behavior: 'auto',
-      pinMode: 'transient',
-      alignmentPolicy: 'best-effort',
-    });
-    expect(headerPropsMock.latest).toMatchObject({
-      currentTurn: 2,
-      totalTurns: 2,
-    });
-
-    const acceptedCallCount = virtualListMock.pinTurnToTopWithStatus.mock.calls.length;
-    flushAnimationFrame();
-    expect(virtualListMock.pinTurnToTopWithStatus.mock.calls.length).toBe(acceptedCallCount);
-
-    stateMocks.visibleTurnInfo = {
-      turnId: 'turn-1',
-      turnIndex: 1,
-      totalTurns: 2,
-      userMessage: 'Older prompt',
-    };
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-    flushAnimationFrame();
-    expect(headerPropsMock.latest).toMatchObject({
-      currentTurn: 1,
-      totalTurns: 2,
-    });
-    const settledCallCount = virtualListMock.pinTurnToTopWithStatus.mock.calls.length;
-    flushAnimationFrame();
-    expect(virtualListMock.pinTurnToTopWithStatus.mock.calls.length).toBe(settledCallCount);
-  });
-
-  it('accepts list-owned pending turn pins without retrying from the container', async () => {
-    stateMocks.activeSession = createSession({
-      isHistorical: false,
-      historyState: 'ready',
-      dialogTurns: [
-        createTurn('turn-1', 'Older prompt'),
-        createTurn('turn-2', 'Latest prompt'),
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [
-      { type: 'user-message', turnId: 'turn-1', data: { id: 'user-turn-1', content: 'Older prompt' } },
-      { type: 'user-message', turnId: 'turn-2', data: { id: 'user-turn-2', content: 'Latest prompt' } },
-    ];
-    stateMocks.visibleTurnInfo = {
-      turnId: 'turn-2',
-      turnIndex: 2,
-      totalTurns: 2,
-      userMessage: 'Latest prompt',
-    };
-    virtualListMock.pinTurnToTopWithStatus.mockReturnValue('pending');
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    clickTurnRailItem(container, 'turn-1');
-    expect(virtualListMock.pinTurnToTopWithStatus).toHaveBeenLastCalledWith('turn-1', {
-      behavior: 'auto',
-      pinMode: 'transient',
-      alignmentPolicy: 'best-effort',
-    });
-    const pendingCallCount = virtualListMock.pinTurnToTopWithStatus.mock.calls.length;
-    flushAnimationFrame();
-    flushAnimationFrame();
-    expect(virtualListMock.pinTurnToTopWithStatus.mock.calls.length).toBe(pendingCallCount);
-  });
-
-  it('does not render stale turn-rail targets', async () => {
-    stateMocks.activeSession = createSession({
-      isHistorical: false,
-      historyState: 'ready',
-      dialogTurns: [
-        createTurn('turn-1', 'Older prompt'),
-        createTurn('turn-2', 'Latest prompt'),
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [
-      { type: 'user-message', turnId: 'turn-1', data: { id: 'user-turn-1', content: 'Older prompt' } },
-      { type: 'user-message', turnId: 'turn-2', data: { id: 'user-turn-2', content: 'Latest prompt' } },
-    ];
-    stateMocks.visibleTurnInfo = {
-      turnId: 'turn-2',
-      turnIndex: 2,
-      totalTurns: 2,
-      userMessage: 'Latest prompt',
-    };
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    const beforeSelectionCallCount = virtualListMock.pinTurnToTopWithStatus.mock.calls.length;
-    expect(container.querySelector('[data-turn-id="turn-missing"]')).toBeNull();
-    expect(virtualListMock.pinTurnToTopWithStatus.mock.calls.length).toBe(beforeSelectionCallCount);
-  });
-
-  it('keeps long-session turn-rail selections single-shot after the list accepts the pin', async () => {
-    const turns = Array.from({ length: 25 }, (_, index) => {
-      const turnNumber = index + 1;
-      return createTurn(`turn-${turnNumber}`, `Prompt ${turnNumber}`);
-    });
-    stateMocks.activeSession = createSession({
-      isHistorical: false,
-      historyState: 'ready',
-      dialogTurns: turns,
-    } as Partial<Session>);
-    stateMocks.virtualItems = turns.map(turn => ({
-      type: 'user-message',
-      turnId: turn.id,
-      data: { id: `user-${turn.id}`, content: turn.userMessage.content },
-    }));
-    stateMocks.visibleTurnInfo = {
-      turnId: 'turn-25',
-      turnIndex: 25,
-      totalTurns: 25,
-      userMessage: 'Prompt 25',
-    };
-    virtualListMock.pinTurnToTopWithStatus.mockReturnValue('settled');
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    expect(headerPropsMock.latest).toMatchObject({
-      currentTurn: 25,
-      totalTurns: 25,
-    });
-    expect(container.querySelector('[data-testid="flowchat-turn-rail"]')?.getAttribute(
-      'data-total-turn-count',
-    )).toBe('25');
-    expect(container.querySelectorAll('.flowchat-turn-rail__item').length).toBeLessThan(25);
-
-    scrollTurnRailToOrdinal(container, 6);
-
-    const beforeSelectionCallCount = virtualListMock.pinTurnToTopWithStatus.mock.calls.length;
-    clickTurnRailItem(container, 'turn-7');
-    expect(virtualListMock.pinTurnToTopWithStatus.mock.calls.length).toBe(beforeSelectionCallCount + 1);
-    expect(virtualListMock.pinTurnToTopWithStatus).toHaveBeenLastCalledWith('turn-7', {
-      behavior: 'auto',
-      pinMode: 'transient',
-      alignmentPolicy: 'best-effort',
-    });
-
-    flushAnimationFrame();
-    flushAnimationFrame();
-    flushAnimationFrame();
-    expect(virtualListMock.pinTurnToTopWithStatus.mock.calls.length).toBe(beforeSelectionCallCount + 1);
-  });
-
-  it('cancels a not-yet-accepted turn-navigation retry when the user scrolls manually', async () => {
-    stateMocks.activeSession = createSession({
-      isHistorical: false,
-      historyState: 'ready',
-      dialogTurns: [
-        createTurn('turn-1', 'Older prompt'),
-        createTurn('turn-2', 'Latest prompt'),
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [
-      { type: 'user-message', turnId: 'turn-1', data: { id: 'user-turn-1', content: 'Older prompt' } },
-      { type: 'user-message', turnId: 'turn-2', data: { id: 'user-turn-2', content: 'Latest prompt' } },
-    ];
-    stateMocks.visibleTurnInfo = {
-      turnId: 'turn-2',
-      turnIndex: 2,
-      totalTurns: 2,
-      userMessage: 'Latest prompt',
-    };
-    virtualListMock.pinTurnToTopWithStatus.mockReturnValue('rejected');
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    clickTurnRailItem(container, 'turn-1');
-    expect(headerPropsMock.latest).toMatchObject({
-      currentTurn: 2,
-      totalTurns: 2,
-    });
-
-    flushAnimationFrame();
-    const retryCallCount = virtualListMock.pinTurnToTopWithStatus.mock.calls.length;
-    expect(retryCallCount).toBeGreaterThan(1);
-
-    await act(async () => {
-      (virtualListPropsMock.latest?.onUserScrollIntent as (() => void) | undefined)?.();
-    });
-    expect(headerPropsMock.latest).toMatchObject({
-      currentTurn: 2,
-      totalTurns: 2,
-    });
-
-    flushAnimationFrame();
-    expect(virtualListMock.pinTurnToTopWithStatus.mock.calls.length).toBe(retryCallCount);
-  });
-
-  it('renders ordinal navigation placeholders for old hosts without a turn catalog', async () => {
-    stateMocks.activeSession = createSession({
-      isHistorical: false,
-      historyState: 'ready',
-      isPartial: true,
-      loadedTurnCount: 2,
-      totalTurnCount: 100,
-      dialogTurns: [
-        createTurn('turn-99', 'Recent restored prompt'),
-        createTurn('turn-100', 'Latest restored prompt'),
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [
-      { type: 'user-message', turnId: 'turn-99', data: { id: 'user-turn-99', content: 'Recent restored prompt' } },
-      { type: 'user-message', turnId: 'turn-100', data: { id: 'user-turn-100', content: 'Latest restored prompt' } },
-    ];
-    stateMocks.visibleTurnInfo = {
-      turnId: 'turn-99',
-      turnIndex: 1,
-      totalTurns: 2,
-      userMessage: 'Recent restored prompt',
-    };
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    expect(headerPropsMock.latest).toMatchObject({
-      currentTurn: 99,
-      totalTurns: 100,
-    });
-    expect(container.querySelector('[data-testid="flowchat-turn-rail"]')?.getAttribute(
-      'data-total-turn-count',
-    )).toBe('100');
-    expect(container.querySelectorAll('.flowchat-turn-rail__item').length).toBeLessThan(100);
-    expect(container.querySelector('[data-turn-key="storage:0"]')).toBeNull();
-    expect(container.querySelector('[data-turn-id="turn-98"]')).toBeNull();
-    expect(container.querySelector('[data-turn-id="turn-99"]')?.getAttribute('aria-disabled')).toBeNull();
-    expect(container.querySelector('[data-turn-id="turn-100"]')?.getAttribute('aria-disabled')).toBeNull();
-
-    scrollTurnRailToOrdinal(container, 0);
-
-    expect(container.querySelector('[data-turn-key="storage:0"]')?.getAttribute('aria-disabled')).toBeNull();
-    expect(container.querySelector('[data-turn-id="turn-99"]')).toBeNull();
-    expect(virtualListMock.pinTurnToTopWithStatus).not.toHaveBeenCalled();
-  });
-
-  it('windows catalog markers while resolving loaded tail identities', async () => {
-    stateMocks.activeSession = createSession({
-      isHistorical: false,
-      historyState: 'ready',
-      isPartial: true,
-      loadedTurnCount: 2,
-      totalTurnCount: 100,
-      turnCatalog: {
-        schemaVersion: 1,
-        sessionId: 'session-1',
-        revision: 'catalog-1',
-        totalTurnCount: 100,
-        complete: false,
-        entries: Array.from({ length: 100 }, (_, ordinal) => ({
-          ordinal,
-          storageTurnIndex: ordinal,
-          ...(ordinal === 98
-            ? { turnId: 'turn-99', preview: 'Stale catalog preview' }
-            : ordinal === 99
-              ? { turnId: 'turn-100', preview: 'Latest catalog preview' }
-              : {}),
-          previewTruncated: false,
-        })),
-      },
-      dialogTurns: [
-        createTurn('turn-99', 'Recent restored prompt'),
-        createTurn('turn-100', 'Latest restored prompt'),
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [
-      { type: 'user-message', turnId: 'turn-99', data: { id: 'user-turn-99', content: 'Recent restored prompt' } },
-      { type: 'user-message', turnId: 'turn-100', data: { id: 'user-turn-100', content: 'Latest restored prompt' } },
-    ];
-    stateMocks.visibleTurnInfo = {
-      turnId: 'turn-100',
-      turnIndex: 2,
-      totalTurns: 2,
-      userMessage: 'Latest restored prompt',
-      visibleTurnIds: ['turn-99', 'turn-100'],
-    };
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    expect(container.querySelector('[data-testid="flowchat-turn-rail"]')?.getAttribute(
-      'data-total-turn-count',
-    )).toBe('100');
-    expect(container.querySelectorAll('.flowchat-turn-rail__item').length).toBeLessThan(100);
-    expect(container.querySelector('[data-turn-key="storage:0"]')).toBeNull();
-    expect(container.querySelector('[data-turn-id="turn-99"]')?.getAttribute('aria-disabled')).toBeNull();
-    expect(container.querySelector('[data-turn-id="turn-100"]')?.getAttribute('aria-disabled')).toBeNull();
-
-    scrollTurnRailToOrdinal(container, 0);
-
-    expect(container.querySelector('[data-turn-key="storage:0"]')?.getAttribute('aria-disabled')).toBeNull();
-    expect(container.querySelector('[data-turn-id="turn-100"]')).toBeNull();
-  });
-
-  it('requests the unified full-history fallback for an unloaded catalog target', async () => {
-    const ensureSpy = vi
-      .spyOn(flowChatStore, 'ensureSessionFullHistory')
-      .mockResolvedValue(true);
-    stateMocks.activeSession = createSession({
-      isHistorical: false,
-      historyState: 'ready',
-      isPartial: true,
-      loadedTurnCount: 2,
-      totalTurnCount: 100,
-      turnCatalog: {
-        schemaVersion: 1,
-        sessionId: 'session-1',
-        revision: 'complete-catalog',
-        totalTurnCount: 100,
-        complete: true,
-        entries: Array.from({ length: 100 }, (_, ordinal) => ({
-          ordinal,
-          storageTurnIndex: ordinal,
-          turnId: `turn-${ordinal + 1}`,
-          preview: `Prompt ${ordinal + 1}`,
-          previewTruncated: false,
-        })),
-      },
-      dialogTurns: [
-        createTurn('turn-99', 'Recent restored prompt'),
-        createTurn('turn-100', 'Latest restored prompt'),
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [
-      { type: 'user-message', turnId: 'turn-99', data: { id: 'user-turn-99', content: 'Recent restored prompt' } },
-      { type: 'user-message', turnId: 'turn-100', data: { id: 'user-turn-100', content: 'Latest restored prompt' } },
-    ];
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    await act(async () => {
-      container.querySelector<HTMLButtonElement>('[data-turn-id="turn-1"]')?.click();
-      await Promise.resolve();
-    });
-
-    expect(ensureSpy).toHaveBeenCalledWith('session-1', 'turn-rail-navigation');
-    expect(virtualListMock.pinTurnToTopWithStatus).not.toHaveBeenCalledWith(
-      'turn-1',
-      expect.anything(),
-    );
-  });
-
-  it('materializes a loaded Turn window for cross-feature focus before reusing the shared pin transaction', async () => {
-    const targetTurn = createTurn('turn-5', 'Target prompt');
-    const loadSpy = vi.spyOn(flowChatStore, 'loadSessionTurnWindow').mockResolvedValue({
-      status: 'ready',
-      sessionId: 'session-1',
-      targetOrdinal: 4,
-      targetTurnId: 'turn-5',
-      navigationGeneration: 7,
-      isCurrent: true,
-      cacheHit: false,
-      range: {
-        startOrdinal: 2,
-        endOrdinalExclusive: 7,
-        turns: Array.from({ length: 5 }, (_, index) => createTurn(`turn-${index + 3}`, `Prompt ${index + 3}`)),
-        lastAccessedAt: 1,
-        source: 'target',
-      },
-    });
-    const activateSpy = vi.spyOn(flowChatStore, 'activateSessionHistoryWindow').mockReturnValue({
-      range: {
-        startOrdinal: 2,
-        endOrdinalExclusive: 7,
-        targetTurnId: targetTurn.id,
-        mode: 'history-window',
-      },
-      turns: Array.from({ length: 5 }, (_, index) => createTurn(`turn-${index + 3}`, `Prompt ${index + 3}`)),
-    });
-    stateMocks.activeSession = createSession({
-      historyState: 'ready',
-      isPartial: true,
-      totalTurnCount: 10,
-      turnCatalog: {
-        schemaVersion: 1,
-        sessionId: 'session-1',
-        revision: 'catalog-v1',
-        totalTurnCount: 10,
-        complete: true,
-        entries: Array.from({ length: 10 }, (_, ordinal) => ({
-          ordinal,
-          storageTurnIndex: ordinal,
-          turnId: `turn-${ordinal + 1}`,
-          preview: `Prompt ${ordinal + 1}`,
-          previewTruncated: false,
-        })),
-      },
-      dialogTurns: [
-        createTurn('turn-9', 'Recent prompt'),
-        createTurn('turn-10', 'Latest prompt'),
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = stateMocks.activeSession.dialogTurns.map(turn => ({
-      type: 'user-message',
-      turnId: turn.id,
-      data: turn.userMessage,
-    }));
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-    const target = container.querySelector<HTMLButtonElement>('[data-turn-id="turn-5"]');
-    expect(target).not.toBeNull();
-    await act(async () => {
-      const onNavigateToFocusTurn = navigationOptionsMock.latest?.onNavigateToFocusTurn as (
-        request: {
-          sessionId: string;
-          turnIndex: number;
-          source: 'usage-report';
-        },
-      ) => Promise<boolean>;
-      await expect(onNavigateToFocusTurn({
-        sessionId: 'session-1',
-        turnIndex: 5,
-        source: 'usage-report',
-      })).resolves.toBe(true);
-    });
-
-    expect(loadSpy).toHaveBeenCalledWith('session-1', 4, { source: 'target' });
-    expect(virtualListMock.prepareTurnPinToTop).toHaveBeenCalledWith('turn-5', {
-      behavior: 'auto',
-      pinMode: 'transient',
-      alignmentPolicy: 'best-effort',
-    });
-    expect(activateSpy).toHaveBeenCalledWith('session-1', 4, 7);
-    expect(virtualListPropsMock.latest).toMatchObject({
-      presentationMode: 'history-window',
-      presentationRevision: 1,
-    });
-    expect((virtualListPropsMock.latest?.items as Array<{ turnId: string }>).map(item => item.turnId)).toEqual([
-      'turn-3',
-      'turn-4',
-      'turn-5',
-      'turn-6',
-      'turn-7',
-    ]);
-    expect(stateMocks.activeSession.dialogTurns.map(turn => turn.id)).toEqual(['turn-9', 'turn-10']);
-    expect(virtualListMock.prepareTurnPinToTop.mock.invocationCallOrder[0]).toBeLessThan(
-      activateSpy.mock.invocationCallOrder[0],
-    );
-
-    const latestTailPinCallCount = virtualListMock.pinTurnToTop.mock.calls.length;
-    const latestTailEndCallCount = virtualListMock.scrollToTurnEndAndClearPin.mock.calls.length;
-    stateMocks.activeSession = {
-      ...stateMocks.activeSession,
-      totalTurnCount: 11,
-      dialogTurns: [
-        ...stateMocks.activeSession.dialogTurns,
-        createTurn('turn-11', 'Streaming prompt', 'processing'),
-      ],
-    };
-    stateMocks.virtualItems = stateMocks.activeSession.dialogTurns.map(turn => ({
-      type: 'user-message',
-      turnId: turn.id,
-      data: turn.userMessage,
-    }));
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-    flushAnimationFrame();
-    expect(virtualListPropsMock.latest).toMatchObject({ presentationMode: 'history-window' });
-    expect(virtualListMock.pinTurnToTop.mock.calls.length).toBe(latestTailPinCallCount);
-    expect(virtualListMock.scrollToTurnEndAndClearPin.mock.calls.length).toBe(latestTailEndCallCount);
-
-    const restoreTailSpy = vi.spyOn(flowChatStore, 'restoreSessionTailPresentation');
-    const latestEndCallCountBeforeSend = virtualListMock.scrollToLatestEndPosition.mock.calls.length;
-    await act(async () => {
-      const onBeforeTurnPinRequest = navigationOptionsMock.latest?.onBeforeTurnPinRequest as (
-        request: {
-          sessionId: string;
-          turnId: string;
-          source: 'send-message';
-          behavior: 'auto';
-          pinMode: 'sticky-latest';
-        },
-      ) => void;
-      onBeforeTurnPinRequest({
-        sessionId: 'session-1',
-        turnId: 'turn-11',
-        source: 'send-message',
-        behavior: 'auto',
-        pinMode: 'sticky-latest',
-      });
-    });
-    expect(restoreTailSpy).toHaveBeenCalledTimes(1);
-    expect(restoreTailSpy).toHaveBeenLastCalledWith('session-1');
-    expect(virtualListPropsMock.latest).toMatchObject({ presentationMode: 'tail' });
-    expect((virtualListPropsMock.latest?.items as Array<{ turnId: string }>).map(item => item.turnId)).toEqual([
-      'turn-9',
-      'turn-10',
-      'turn-11',
-    ]);
-    expect(virtualListMock.scrollToLatestEndPosition.mock.calls.length).toBe(latestEndCallCountBeforeSend);
-
-    await act(async () => {
-      container.querySelector<HTMLButtonElement>('[data-turn-id="turn-5"]')?.click();
-      await Promise.resolve();
-    });
-    expect(virtualListPropsMock.latest).toMatchObject({ presentationMode: 'history-window' });
-
-    await act(async () => {
-      (virtualListPropsMock.latest?.onRequestJumpToLatest as (() => void) | undefined)?.();
-    });
-    flushAnimationFrame();
-    expect(restoreTailSpy).toHaveBeenCalledTimes(2);
-    expect(restoreTailSpy).toHaveBeenLastCalledWith('session-1');
-    expect(virtualListPropsMock.latest).toMatchObject({ presentationMode: 'tail' });
-    expect(virtualListMock.scrollToLatestEndPosition.mock.calls.length).toBe(latestEndCallCountBeforeSend + 1);
-
-    restoreTailSpy.mockRestore();
-    loadSpy.mockRestore();
-    activateSpy.mockRestore();
-  });
-
-  it('materializes an adjacent catalog window when tail history requests older turns', async () => {
-    const catalog = {
-      schemaVersion: 1,
-      sessionId: 'session-1',
-      revision: 'catalog-1',
-      totalTurnCount: 10,
-      complete: true,
-      entries: Array.from({ length: 10 }, (_, ordinal) => ({
-        ordinal,
-        storageTurnIndex: ordinal,
-        turnId: `turn-${ordinal + 1}`,
-        preview: `Prompt ${ordinal + 1}`,
-        previewTruncated: false,
-      })),
-    };
-    stateMocks.activeSession = createSession({
-      isHistorical: false,
-      historyState: 'ready',
-      isPartial: true,
-      loadedTurnCount: 2,
-      totalTurnCount: 10,
-      turnCatalog: catalog,
-      dialogTurns: [
-        createTurn('turn-9', 'Recent prompt'),
-        createTurn('turn-10', 'Latest prompt'),
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = stateMocks.activeSession.dialogTurns.map(turn => ({
-      type: 'user-message',
-      turnId: turn.id,
-      data: turn.userMessage,
-    }));
-    const presentationTurns = Array.from(
-      { length: 8 },
-      (_, index) => createTurn(`turn-${index + 3}`, `Prompt ${index + 3}`),
-    );
-    const cachedTurns = Array.from(
-      { length: 10 },
-      (_, index) => createTurn(`turn-${index + 1}`, `Prompt ${index + 1}`),
-    );
-    vi.spyOn(flowChatStore, 'getState').mockReturnValue({
-      sessions: new Map([['session-1', stateMocks.activeSession]]),
-      activeSessionId: 'session-1',
-    });
-    vi.spyOn(flowChatStore, 'getSessionHistoryViewState').mockReturnValue({
-      catalog,
-      loadedRanges: [{
-        startOrdinal: 0,
-        endOrdinalExclusive: 10,
-        turns: cachedTurns,
-        lastAccessedAt: 1,
-        source: 'prefetch',
-      }],
-      activeRange: null,
-      pendingTargetOrdinal: null,
-      navigationGeneration: 0,
-    });
-    vi.spyOn(flowChatStore, 'getSessionCanonicalTailRange').mockReturnValue({
-      startOrdinal: 8,
-      endOrdinalExclusive: 10,
-    });
-    const loadSpy = vi.spyOn(flowChatStore, 'loadSessionTurnWindow').mockResolvedValue({
-      status: 'ready',
-      sessionId: 'session-1',
-      targetOrdinal: 7,
-      targetTurnId: 'turn-8',
-      navigationGeneration: 0,
-      isCurrent: true,
-      cacheHit: true,
-      catalog,
-    });
-    const activateSpy = vi.spyOn(
-      flowChatStore,
-      'activateSessionHistoryWindowFromTail',
-    ).mockReturnValue({
-      range: {
-        startOrdinal: 2,
-        endOrdinalExclusive: 10,
-        targetTurnId: null,
-        mode: 'history-window',
-      },
-      turns: presentationTurns,
-    });
-    let resolveViewportPreparation: ((ready: boolean) => void) | undefined;
-    const viewportPreparation = new Promise<boolean>(resolve => {
-      resolveViewportPreparation = resolve;
-    });
-    const prepareViewportForPresentationCommit = vi.fn(() => viewportPreparation);
-    const cancelViewportPresentationCommit = vi.fn();
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-    let boundaryIntent: Promise<HistoryWindowBoundaryIntentResult> | undefined;
-    await act(async () => {
-      boundaryIntent = (
-        virtualListPropsMock.latest?.onHistoryWindowBoundaryIntent as
-          | ((
-            direction: 'before' | 'after',
-            options?: {
-              prepareViewportForPresentationCommit?: () => (
-                boolean | void | Promise<boolean | void>
-              );
-              cancelViewportPresentationCommit?: () => void;
-            },
-          ) => Promise<HistoryWindowBoundaryIntentResult>)
-          | undefined
-      )?.('before', {
-        prepareViewportForPresentationCommit,
-        cancelViewportPresentationCommit,
-      });
-      await Promise.resolve();
-    });
-
-    expect(prepareViewportForPresentationCommit).toHaveBeenCalledOnce();
-    expect(cancelViewportPresentationCommit).not.toHaveBeenCalled();
-    expect(activateSpy).not.toHaveBeenCalled();
-    expect(virtualListPropsMock.latest).toMatchObject({ presentationMode: 'tail' });
-
-    await act(async () => {
-      resolveViewportPreparation?.(true);
-      expect(await boundaryIntent).toBe('applied');
-    });
-
-    expect(loadSpy).toHaveBeenCalledWith('session-1', 7, {
-      source: 'prefetch',
-      before: 12,
-      after: 1,
-    });
-    expect(activateSpy).toHaveBeenCalledWith('session-1', 7);
-    expect(virtualListPropsMock.latest).toMatchObject({
-      presentationMode: 'history-window',
-      presentationRevision: 1,
-    });
-  });
-
-  it('lets streaming restored sessions use follow-output instead of container sticky anchoring', async () => {
-    stateMocks.activeSession = createSession({
-      historyState: 'ready',
-      dialogTurns: [
-        createTurn('turn-1', 'Older restored prompt'),
-        createTurn('turn-2', 'Latest restored prompt', 'processing'),
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [
-      { type: 'user-message', turnId: 'turn-1', data: { id: 'user-turn-1', content: 'Older restored prompt' } },
-      { type: 'user-message', turnId: 'turn-2', data: { id: 'user-turn-2', content: 'Latest restored prompt' } },
-    ];
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    expect(container.querySelector('[data-testid="virtual-list"]')).not.toBeNull();
-    expect(virtualListMock.pinTurnToTop).not.toHaveBeenCalled();
-    expect(startupTraceMock.markPhase).toHaveBeenCalledWith(
-      'historical_session_latest_anchor_skipped',
-      expect.objectContaining({ reason: 'streaming_follow_output', mode: 'follow-output' }),
-    );
-  });
-
-  it('scrolls completed restored history to the tail after hydration clears isHistorical', async () => {
-    stateMocks.activeSession = createSession({
-      isHistorical: false,
-      historyState: 'ready',
-      dialogTurns: [
-        createTurn('turn-1', 'Older restored prompt'),
-        createTurn('turn-2', 'Latest restored prompt'),
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [
-      { type: 'user-message', turnId: 'turn-1', data: { id: 'user-turn-1', content: 'Older restored prompt' } },
-      { type: 'user-message', turnId: 'turn-2', data: { id: 'user-turn-2', content: 'Latest restored prompt' } },
-    ];
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    flushAnimationFrame();
-
-    expect(virtualListMock.scrollToTurnEndAndClearPin).toHaveBeenCalledTimes(1);
-    expect(virtualListMock.scrollToTurnEndAndClearPin).toHaveBeenCalledWith('turn-2');
-    expect(virtualListMock.pinTurnToTop).not.toHaveBeenCalled();
-    expect(startupTraceMock.markPhase).toHaveBeenCalledWith(
-      'historical_session_latest_anchor_attempt',
-      expect.objectContaining({ accepted: true, attempt: 1, mode: 'bottom' }),
-    );
-  });
-
-  it('retries completed history tail anchoring when the virtual list is not ready on the first frame', async () => {
-    stateMocks.activeSession = createSession({
-      isHistorical: false,
-      historyState: 'ready',
-      dialogTurns: [
-        createTurn('turn-1', 'Older restored prompt'),
-        createTurn('turn-2', 'Latest restored prompt'),
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [
-      { type: 'user-message', turnId: 'turn-1', data: { id: 'user-turn-1', content: 'Older restored prompt' } },
-      { type: 'user-message', turnId: 'turn-2', data: { id: 'user-turn-2', content: 'Latest restored prompt' } },
-    ];
-    virtualListMock.scrollToTurnEndAndClearPin
-      .mockReturnValueOnce(false)
-      .mockReturnValueOnce(true);
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    flushAnimationFrame();
-    expect(virtualListMock.scrollToTurnEndAndClearPin).toHaveBeenCalledTimes(1);
-    expect(virtualListMock.scrollToTurnEndAndClearPin).toHaveBeenLastCalledWith('turn-2');
-
-    flushAnimationFrame();
-    expect(virtualListMock.scrollToTurnEndAndClearPin).toHaveBeenCalledTimes(2);
-    expect(virtualListMock.scrollToTurnEndAndClearPin).toHaveBeenLastCalledWith('turn-2');
-    expect(startupTraceMock.markPhase).toHaveBeenCalledWith(
-      'historical_session_latest_anchor_attempt',
-      expect.objectContaining({ accepted: false, attempt: 1, mode: 'bottom' }),
-    );
-    expect(startupTraceMock.markPhase).toHaveBeenCalledWith(
-      'historical_session_latest_anchor_attempt',
-      expect.objectContaining({ accepted: true, attempt: 2, mode: 'bottom' }),
-    );
-  });
-
-  it('does not re-anchor local restored history after full hydration expands the same latest turn', async () => {
-    stateMocks.activeSession = createSession({
-      isHistorical: false,
-      historyState: 'ready',
-      dialogTurns: [
-        createTurn('turn-80', 'Latest restored prompt'),
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [
-      { type: 'user-message', turnId: 'turn-80', data: { id: 'user-turn-80', content: 'Latest restored prompt' } },
-    ];
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    flushAnimationFrame();
-
-    expect(virtualListMock.scrollToTurnEndAndClearPin).toHaveBeenCalledTimes(1);
-    expect(virtualListMock.scrollToTurnEndAndClearPin).toHaveBeenLastCalledWith('turn-80');
-
-    stateMocks.activeSession = createSession({
-      isHistorical: false,
-      historyState: 'ready',
-      dialogTurns: [
-        createTurn('turn-1', 'Older restored prompt'),
-        createTurn('turn-80', 'Latest restored prompt'),
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [
-      { type: 'user-message', turnId: 'turn-1', data: { id: 'user-turn-1', content: 'Older restored prompt' } },
-      { type: 'user-message', turnId: 'turn-80', data: { id: 'user-turn-80', content: 'Latest restored prompt' } },
-    ];
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    flushAnimationFrame();
-
-    expect(virtualListMock.scrollToTurnEndAndClearPin).toHaveBeenCalledTimes(1);
-    expect(virtualListMock.scrollToTurnEndAndClearPin).toHaveBeenLastCalledWith('turn-80');
-    expect(virtualListMock.pinTurnToTop).not.toHaveBeenCalled();
-    expect(startupTraceMock.markPhase).toHaveBeenCalledWith(
-      'historical_session_latest_anchor_skipped',
-      expect.objectContaining({ reason: 'local_full_history_projection' }),
-    );
-  });
-
-  it('does not re-anchor local full hydration when the latest restored turn is already visible', async () => {
-    stateMocks.activeSession = createSession({
-      isHistorical: false,
-      historyState: 'ready',
-      dialogTurns: [
-        createTurn('turn-80', 'Latest restored prompt'),
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [
-      { type: 'user-message', turnId: 'turn-80', data: { id: 'user-turn-80', content: 'Latest restored prompt' } },
-    ];
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    flushAnimationFrame();
-
-    expect(virtualListMock.scrollToTurnEndAndClearPin).toHaveBeenCalledTimes(1);
-    expect(virtualListMock.scrollToTurnEndAndClearPin).toHaveBeenLastCalledWith('turn-80');
-
-    stateMocks.visibleTurnInfo = {
-      turnId: 'turn-80',
-      turnIndex: 1,
-      totalTurns: 1,
-      userMessage: 'Latest restored prompt',
-    };
-    virtualListMock.isTurnRenderedInViewport.mockReturnValue(true);
-    stateMocks.activeSession = createSession({
-      isHistorical: false,
-      historyState: 'ready',
-      dialogTurns: [
-        createTurn('turn-1', 'Older restored prompt'),
-        createTurn('turn-80', 'Latest restored prompt'),
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [
-      { type: 'user-message', turnId: 'turn-1', data: { id: 'user-turn-1', content: 'Older restored prompt' } },
-      { type: 'user-message', turnId: 'turn-80', data: { id: 'user-turn-80', content: 'Latest restored prompt' } },
-    ];
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    expect(virtualListMock.scrollToTurnEndAndClearPin).toHaveBeenCalledTimes(1);
-    expect(virtualListMock.scrollToTurnEndAndClearPin).toHaveBeenLastCalledWith('turn-80');
-
-    flushAnimationFrame();
-
-    expect(virtualListMock.scrollToTurnEndAndClearPin).toHaveBeenCalledTimes(1);
-    expect(virtualListMock.scrollToTurnEndAndClearPin).toHaveBeenLastCalledWith('turn-80');
-    expect(virtualListMock.pinTurnToTop).not.toHaveBeenCalled();
-  });
-
-  it('does not repeat immediate latest anchoring after visible turn info catches up', async () => {
-    stateMocks.activeSession = createSession({
-      isHistorical: true,
-      historyState: 'ready',
-      dialogTurns: [
-        createTurn('turn-80', 'Latest restored prompt'),
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [
-      { type: 'user-message', turnId: 'turn-80', data: { id: 'user-turn-80', content: 'Latest restored prompt' } },
-    ];
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    expect(virtualListMock.scrollToTurnEndAndClearPin).toHaveBeenCalledTimes(1);
-    expect(virtualListMock.scrollToTurnEndAndClearPin).toHaveBeenLastCalledWith('turn-80');
-
-    stateMocks.visibleTurnInfo = {
-      turnId: 'turn-80',
-      turnIndex: 1,
-      totalTurns: 1,
-      userMessage: 'Latest restored prompt',
-    };
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    expect(virtualListMock.scrollToTurnEndAndClearPin).toHaveBeenCalledTimes(1);
-    expect(virtualListMock.pinTurnToTop).not.toHaveBeenCalled();
-  });
-
-  it('does not re-anchor local full hydration when visible turn info is stale after prepending older turns', async () => {
-    stateMocks.activeSession = createSession({
-      isHistorical: false,
-      historyState: 'ready',
-      dialogTurns: [
-        createTurn('turn-80', 'Latest restored prompt'),
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [
-      { type: 'user-message', turnId: 'turn-80', data: { id: 'user-turn-80', content: 'Latest restored prompt' } },
-    ];
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    flushAnimationFrame();
-
-    expect(virtualListMock.scrollToTurnEndAndClearPin).toHaveBeenCalledTimes(1);
-    expect(virtualListMock.scrollToTurnEndAndClearPin).toHaveBeenLastCalledWith('turn-80');
-
-    stateMocks.visibleTurnInfo = {
-      turnId: 'turn-80',
-      turnIndex: 1,
-      totalTurns: 1,
-      userMessage: 'Latest restored prompt',
-    };
-    virtualListMock.isTurnRenderedInViewport.mockReturnValue(false);
-    stateMocks.activeSession = createSession({
-      isHistorical: false,
-      historyState: 'ready',
-      dialogTurns: [
-        createTurn('turn-1', 'Older restored prompt'),
-        createTurn('turn-44', 'Middle restored prompt'),
-        createTurn('turn-80', 'Latest restored prompt'),
-      ],
-    } as Partial<Session>);
-    stateMocks.virtualItems = [
-      { type: 'user-message', turnId: 'turn-1', data: { id: 'user-turn-1', content: 'Older restored prompt' } },
-      { type: 'user-message', turnId: 'turn-44', data: { id: 'user-turn-44', content: 'Middle restored prompt' } },
-      { type: 'user-message', turnId: 'turn-80', data: { id: 'user-turn-80', content: 'Latest restored prompt' } },
-    ];
-
-    await act(async () => {
-      root.render(<ModernFlowChatContainer />);
-    });
-
-    flushAnimationFrame();
-
-    expect(virtualListMock.scrollToTurnEndAndClearPin).toHaveBeenCalledTimes(1);
-    expect(virtualListMock.scrollToTurnEndAndClearPin).toHaveBeenLastCalledWith('turn-80');
-    expect(virtualListMock.pinTurnToTop).not.toHaveBeenCalled();
+  it('does not recreate sticky latest or pin reservation modes', () => {
+    expect(componentSource).not.toContain('sticky-latest');
+    expect(componentSource).not.toContain('pinTurnToTop');
+    expect(componentSource).not.toContain('prepareTurnPinToTop');
   });
 });
diff --git a/src/web-ui/src/flow_chat/components/modern/ModernFlowChatContainer.scss b/src/web-ui/src/flow_chat/components/modern/ModernFlowChatContainer.scss
index 9944df23b3..47c3865c1f 100644
--- a/src/web-ui/src/flow_chat/components/modern/ModernFlowChatContainer.scss
+++ b/src/web-ui/src/flow_chat/components/modern/ModernFlowChatContainer.scss
@@ -16,24 +16,13 @@
   display: flex;
   flex-direction: column;
   background: var(--bf-appearance-token-color-bg-scene);
-  position: relative; // Positioning context for floating header.
-  
-  // Header overlays message list for glass effect.
-  > .flowchat-header {
-    position: absolute;
-    top: 0;
-    left: 0;
-    right: 0;
-    z-index: 20; // Ensure it stays above the message list.
-  }
-  
+  position: relative; // Positioning context for the permission panel and overlays.
+
   &__messages {
-    // Messages fill the container, including header area.
-    position: absolute;
-    top: 0;
-    left: 0;
-    right: 0;
-    bottom: 0;
+    // Header and messages stack vertically; messages take the remaining space.
+    position: relative;
+    flex: 1 1 auto;
+    min-height: 0;
     overflow: hidden;
     background: transparent;
   }
@@ -143,7 +132,7 @@
   display: flex;
   align-items: flex-start;
   justify-content: center;
-  padding-top: 76px;
+  padding-top: 40px;
   pointer-events: auto;
   background: var(--bf-appearance-token-color-bg-scene);
   contain: paint;
@@ -152,10 +141,10 @@
 .modern-flowchat-container__history-open-intent-shield::before {
   content: "";
   position: absolute;
-  top: 116px;
+  top: 80px;
   left: 50%;
   width: min(720px, calc(100% - 48px));
-  height: min(220px, calc(100% - 168px));
+  height: min(220px, calc(100% - 132px));
   min-height: 120px;
   transform: translateX(-50%);
   border-radius: 8px;
@@ -185,3 +174,10 @@
     transform: rotate(360deg);
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .history-session-placeholder__icon svg,
+  .modern-flowchat-container__history-open-intent-spinner {
+    animation: none;
+  }
+}
diff --git a/src/web-ui/src/flow_chat/components/modern/ModernFlowChatContainer.tsx b/src/web-ui/src/flow_chat/components/modern/ModernFlowChatContainer.tsx
index 58df5f33e4..76f343501e 100644
--- a/src/web-ui/src/flow_chat/components/modern/ModernFlowChatContainer.tsx
+++ b/src/web-ui/src/flow_chat/components/modern/ModernFlowChatContainer.tsx
@@ -10,7 +10,7 @@ import { FlowChatManager } from '@/flow_chat/services/FlowChatManager';
 import { useSessionModeStore } from '@/app/stores/sessionModeStore';
 import {
   VirtualMessageList,
-  type FlowChatTurnPinRequestStatus,
+  type FlowChatTurnNavigationStatus,
   type HistoryWindowBoundaryIntentResult,
   type HistoryWindowBoundaryIntentOptions,
   type VirtualMessageListRef,
@@ -51,9 +51,10 @@ import type {
   SessionHistoryPresentation,
 } from '../../types/flow-chat';
 import type { SessionHistoryWindowDirection } from '../../store/FlowChatStore';
-import type {
-  FlowChatFocusItemRequest,
-  FlowChatPinTurnToTopRequest,
+import {
+  FLOWCHAT_MESSAGE_SUBMITTED_EVENT,
+  type FlowChatFocusItemRequest,
+  type FlowChatMessageSubmittedRequest,
 } from '../../events/flowchatNavigation';
 import {
   useBackgroundCommandActivityStore,
@@ -63,7 +64,7 @@ import {
 import {
   useBackgroundSubagentActivityStore,
 } from '../../store/backgroundSubagentActivityStore';
-import type { LineRange } from '@/component-library';
+import { PresenceBoundary, type LineRange } from '@/component-library';
 import { isChatPopupActive, subscribeChatPopupChange } from '../chatPopupState';
 import { useWorkspaceContext } from '@/infrastructure/contexts/WorkspaceContext';
 import { flowChatSessionConfigForCurrentWorkspace } from '@/app/utils/projectSessionWorkspace';
@@ -77,7 +78,6 @@ import { resolveThreadGoalHeaderTitle } from '../../utils/threadGoalDisplay';
 import { hasActiveSessionLineageDescendants } from '../../utils/sessionLineage';
 import {
   findDialogTurn,
-  shouldUseStickyLatestPin,
   shouldUseLatestTurnFollowOutput,
 } from '../../utils/flowChatTurnScrollPolicy';
 import { isRemoteTraceContext, startupTrace } from '@/shared/utils/startupTrace';
@@ -92,9 +92,18 @@ import {
   type HistorySessionOpenIntentDetail,
 } from '../../services/sessionOpenIntent';
 import {
+  recordHistoryPagingEvent,
   recordHistorySessionDiagnosticEvent,
+  warnHistoryPagingRefusedWithPendingTurns,
   warnHistorySessionLoadingLayerStalled,
 } from '../../services/historySessionDiagnostics';
+import {
+  resolveHistoryBoundaryTarget,
+  resolveTailBoundaryPrecondition,
+  resolveTailWindowGrowth,
+  transcriptReachesLatestTurn,
+  type RenderedTranscriptRange,
+} from './flowChatLiveTailWindow';
 import './ModernFlowChatContainer.scss';
 import { PermissionRequestPanel } from './PermissionRequestPanel';
 import { pendingPermissionToolCallIdsForSession } from './permissionRequestRouting';
@@ -111,7 +120,6 @@ import {
 
 const log = createLogger('ModernFlowChatContainer');
 
-
 interface ModernFlowChatContainerProps {
   className?: string;
   config?: Partial<FlowChatConfig>;
@@ -387,6 +395,44 @@ export const ModernFlowChatContainer: React.FC<ModernFlowChatContainerProps> = (
       ? canonicalizedHistoryPresentation
       : null;
   const isRenderingHistoryProjection = Boolean(renderedHistoryPresentation);
+  /**
+   * The range the reader is actually looking at, for the paging ask.
+   *
+   * Deliberately the *rendered* presentation and not `historyPresentationRef`,
+   * which holds the window the store cut. The continuous projection makes those
+   * two differ — see `resolveHistoryBoundaryTarget`.
+   */
+  const renderedHistoryPresentationRef = useRef(renderedHistoryPresentation);
+  renderedHistoryPresentationRef.current = renderedHistoryPresentation;
+  /*
+   * Whether the transcript on screen still reaches the newest Turn.
+   *
+   * Both consumers of `history-reading` — suppressing streaming follow, and the
+   * jump-to-latest affordance — are asking this, not "did the user navigate".
+   * A turn intent used to answer it faithfully because only navigation ever
+   * activated a history window. Automatic tail paging activates one with nobody
+   * navigating: a session whose loaded tail is shorter than the viewport pages
+   * on open, and the viewport sitting on the newest output was then reported as
+   * reading history, which pinned the jump-to-latest bar open and routed it
+   * through a presentation reset that dropped the window and paged it back in.
+   *
+   * The window's own ordinal bookkeeping answers it exactly — these are ledger
+   * numbers, not measurements — and keeps answering it as the session grows: a
+   * Turn arriving past the end of the window flips this back on its own, where
+   * a provenance flag recorded at activation time would stay stale and leave no
+   * way back to the live tail.
+   *
+   * `isReadingTurnViewport` deliberately keeps its old meaning for the auto-tail
+   * placement below, which asks a different question again: who owns the
+   * viewport. Merging those two is the mistake this fixes.
+   */
+  const renderedTranscriptReachesLatestTurn = transcriptReachesLatestTurn({
+    windowEndOrdinalExclusive: renderedHistoryPresentation?.range.endOrdinalExclusive ?? null,
+    knownTurnCount: activeSessionKnownTurnCount,
+  });
+  const isViewportDetachedFromLiveTail = (
+    isReadingTurnViewport && !renderedTranscriptReachesLatestTurn
+  );
   const virtualItems = useMemo(() => {
     if (!activeSession || !renderedHistoryPresentation) {
       return canonicalVirtualItems;
@@ -415,6 +461,29 @@ export const ModernFlowChatContainer: React.FC<ModernFlowChatContainerProps> = (
     respond: respondPermission,
     respondBatch: respondPermissionBatch,
   } = usePermissionRequests(activeSession?.sessionId);
+  const activePermissionPanelSnapshot = activeSession && activePermissionBatch
+    ? {
+        ownerSessionId: activeSession.sessionId,
+        batch: activePermissionBatch,
+        totalPendingCount: permissionRequests.length,
+        aboveChatInput: permissionPanelAboveChatInput,
+        onRespond: respondPermission,
+        onRespondBatch: respondPermissionBatch,
+      }
+    : null;
+  const retainedPermissionPanelSnapshotRef = useRef(activePermissionPanelSnapshot);
+  let renderedPermissionPanelSnapshot = activePermissionPanelSnapshot;
+  if (activePermissionPanelSnapshot) {
+    retainedPermissionPanelSnapshotRef.current = activePermissionPanelSnapshot;
+  } else if (
+    retainedPermissionPanelSnapshotRef.current?.ownerSessionId === activeSession?.sessionId
+  ) {
+    renderedPermissionPanelSnapshot = retainedPermissionPanelSnapshotRef.current;
+  } else {
+    // A retained exit belongs to its originating session. Never let it cross a
+    // session boundary with the new session's callbacks or surrounding props.
+    retainedPermissionPanelSnapshotRef.current = null;
+  }
   const visibleTurnInfo = useVisibleTurnInfo();
   const [queuedTurnNavigation, setQueuedTurnNavigation] = useState<QueuedTurnNavigation | null>(null);
   const [pendingHistoryOpenSession, setPendingHistoryOpenSession] = useState<HistorySessionOpenIntentDetail | null>(null);
@@ -433,12 +502,12 @@ export const ModernFlowChatContainer: React.FC<ModernFlowChatContainerProps> = (
   const [stoppingBackgroundCommandIds, setStoppingBackgroundCommandIds] = useState<Set<string>>(() => new Set());
   const [backgroundCommandInputTarget, setBackgroundCommandInputTarget] = useState<FlowChatHeaderCommandSummary | null>(null);
   const [isSendingBackgroundCommandInput, setIsSendingBackgroundCommandInput] = useState(false);
-  const autoPinnedTurnKeyRef = useRef<string | null>(null);
+  const autoTailTurnKeyRef = useRef<string | null>(null);
   const releasedHistoryCompletionKeyRef = useRef<string | null>(null);
   const visibleTurnInfoRef = useRef<VisibleTurnInfo | null>(visibleTurnInfo);
   const turnSummariesRef = useRef<FlowChatTurnSummary[]>([]);
   const turnRailTurnIdsRef = useRef<Set<string>>(new Set());
-  const requestTurnNavigationPinRef = useRef<((turnId: string) => FlowChatTurnPinRequestStatus) | null>(null);
+  const requestTurnNavigationRef = useRef<((turnId: string) => FlowChatTurnNavigationStatus) | null>(null);
   const searchFullHistorySessionIdRef = useRef<string | null>(null);
   const virtualListRef = useRef<VirtualMessageListRef>(null);
   const chatScopeRef = useRef<HTMLDivElement>(null);
@@ -534,18 +603,6 @@ export const ModernFlowChatContainer: React.FC<ModernFlowChatContainerProps> = (
     setQueuedTurnNavigation(null);
   }, [activeSession?.sessionId, continuousHistoryProjectionEligible, updateViewportIntent]);
 
-  const handleBeforeTurnPinRequest = useCallback((request: FlowChatPinTurnToTopRequest) => {
-    const currentViewportIntent = viewportIntentRef.current;
-    if (
-      request.source === 'send-message'
-      && currentViewportIntent?.sessionId === request.sessionId
-      && currentViewportIntent.kind === 'turn'
-      && currentViewportIntent.source === 'history-range'
-    ) {
-      switchToLiveTailForSession(request.sessionId);
-    }
-  }, [switchToLiveTailForSession]);
-
   useEffect(() => {
     historyPresentationRef.current = historyPresentation;
   }, [historyPresentation]);
@@ -596,6 +653,9 @@ export const ModernFlowChatContainer: React.FC<ModernFlowChatContainerProps> = (
     historyPresentationRef.current = null;
     setHistoryPresentation(null);
     setContinuousProjectionSessionId(null);
+    if (activeSession?.sessionId) {
+      flowChatStore.restoreSessionTailPresentation(activeSession.sessionId);
+    }
     if (
       activeViewportIntent?.kind === 'turn'
       && activeViewportIntent.source === 'history-range'
@@ -1027,7 +1087,6 @@ export const ModernFlowChatContainer: React.FC<ModernFlowChatContainerProps> = (
     [activeSession?.dialogTurns, latestTurnId],
   );
   const latestTurnUsesFollowOutput = shouldUseLatestTurnFollowOutput(latestTurn);
-  const latestTurnUsesStickyPin = shouldUseStickyLatestPin(latestTurn);
 
   const navigationVisibleTurnInfo = useMemo<VisibleTurnInfo | null>(() => {
     if (!visibleTurnInfo) {
@@ -1084,19 +1143,17 @@ export const ModernFlowChatContainer: React.FC<ModernFlowChatContainerProps> = (
     return effectiveVisibleTurnInfo?.userMessage ?? '';
   }, [effectiveVisibleTurnInfo?.turnId, effectiveVisibleTurnInfo?.userMessage, renderedTurns, resolveLocalCommandHeaderTitle]);
 
-  const requestTurnNavigationPin = useCallback((turnId: string): FlowChatTurnPinRequestStatus => {
+  const requestTurnNavigation = useCallback((turnId: string): FlowChatTurnNavigationStatus => {
     if (!isViewportActive) {
       return 'rejected';
     }
-    return virtualListRef.current?.pinTurnToTopWithStatus(turnId, {
+    return virtualListRef.current?.navigateToTurnWithStatus(turnId, {
       behavior: 'auto',
-      pinMode: 'transient',
-      alignmentPolicy: 'best-effort',
     }) ?? 'rejected';
   }, [isViewportActive]);
   useEffect(() => {
-    requestTurnNavigationPinRef.current = requestTurnNavigationPin;
-  }, [requestTurnNavigationPin]);
+    requestTurnNavigationRef.current = requestTurnNavigation;
+  }, [requestTurnNavigation]);
   const handleVirtualListUserScrollIntent = useCallback(() => {
     setQueuedTurnNavigation(null);
   }, []);
@@ -1140,8 +1197,8 @@ export const ModernFlowChatContainer: React.FC<ModernFlowChatContainerProps> = (
         return;
       }
 
-      const pinStatus = requestTurnNavigationPinRef.current?.(queuedTurnId) ?? 'rejected';
-      if (pinStatus === 'settled' || pinStatus === 'pending') {
+      const navigationStatus = requestTurnNavigationRef.current?.(queuedTurnId) ?? 'rejected';
+      if (navigationStatus === 'settled' || navigationStatus === 'pending') {
         setQueuedTurnNavigation(null);
         return;
       }
@@ -1170,7 +1227,7 @@ export const ModernFlowChatContainer: React.FC<ModernFlowChatContainerProps> = (
   ]);
 
   useLayoutEffect(() => {
-    autoPinnedTurnKeyRef.current = null;
+    autoTailTurnKeyRef.current = null;
     releasedHistoryCompletionKeyRef.current = null;
     searchFullHistorySessionIdRef.current = null;
   }, [activeSession?.sessionId]);
@@ -1187,163 +1244,47 @@ export const ModernFlowChatContainer: React.FC<ModernFlowChatContainerProps> = (
       ? `${sessionId}:${latestTurnId}:${turnSummaries.length}`
       : null;
     if (
-      !isViewportActive
-      ||
-      !sessionId
-      || isReadingTurnViewport
-      || !latestTurnId
-      || autoPinnedTurnKeyRef.current === latestTurnKey
+      !isViewportActive ||
+      !sessionId ||
+      isReadingTurnViewport ||
+      !latestTurnId ||
+      !latestTurnKey ||
+      autoTailTurnKeyRef.current === latestTurnKey
     ) {
       return;
     }
 
-    const resolvedLatestTurnId = latestTurnId;
-    const resolvedLatestTurnKey = latestTurnKey;
-    const pinMode = latestTurnUsesStickyPin
-      ? 'sticky-latest'
-      : null;
     if (latestTurnUsesFollowOutput) {
-      autoPinnedTurnKeyRef.current = resolvedLatestTurnKey;
-      startupTrace.markPhase('historical_session_latest_anchor_skipped', {
-        sessionId,
-        latestTurnId,
-        reason: 'streaming_follow_output',
-        mode: pinMode ?? 'follow-output',
-        turnCount: turnSummaries.length,
-      });
-      return;
-    }
-    const previousAnchoredLatestTurnKeyPrefix = `${sessionId}:${latestTurnId}:`;
-    const hasPreviouslyAnchoredSameLatestTurn =
-      autoPinnedTurnKeyRef.current?.startsWith(previousAnchoredLatestTurnKeyPrefix) === true;
-    const latestTurnRenderedInViewport = virtualListRef.current?.isTurnRenderedInViewport(latestTurnId) === true;
-    const sameLatestTurnCountChanged =
-      hasPreviouslyAnchoredSameLatestTurn &&
-      autoPinnedTurnKeyRef.current !== resolvedLatestTurnKey;
-    const shouldSkipLocalFullHistoryReanchor =
-      sameLatestTurnCountChanged &&
-      !isRemoteTraceContext(activeSession.remoteConnectionId, activeSession.remoteSshHost);
-    const shouldForceLatestAnchorAfterTurnCountChange =
-      sameLatestTurnCountChanged &&
-      !shouldSkipLocalFullHistoryReanchor;
-    if (shouldSkipLocalFullHistoryReanchor) {
-      autoPinnedTurnKeyRef.current = resolvedLatestTurnKey;
-      startupTrace.markPhase('historical_session_latest_anchor_skipped', {
-        sessionId,
-        latestTurnId,
-        reason: 'local_full_history_projection',
-        mode: pinMode ?? 'bottom',
-        turnCount: turnSummaries.length,
-      });
+      autoTailTurnKeyRef.current = latestTurnKey;
       return;
     }
-    if (
-      !shouldForceLatestAnchorAfterTurnCountChange &&
-      hasPreviouslyAnchoredSameLatestTurn &&
-      visibleTurnInfo?.turnId === latestTurnId &&
-      latestTurnRenderedInViewport
-    ) {
-      autoPinnedTurnKeyRef.current = resolvedLatestTurnKey;
-      startupTrace.markPhase('historical_session_latest_anchor_skipped', {
-        sessionId,
-        latestTurnId,
-        reason: 'latest_turn_already_visible',
-        mode: pinMode ?? 'bottom',
-      });
-      return;
-    }
-    if (
-      hasPreviouslyAnchoredSameLatestTurn &&
-      visibleTurnInfo?.turnId === latestTurnId &&
-      !latestTurnRenderedInViewport
-    ) {
-      startupTrace.markPhase('historical_session_latest_anchor_stale_visible_info', {
-        sessionId,
-        latestTurnId,
-        mode: pinMode ?? 'bottom',
-      });
-    }
 
-    let frameId: number | null = null;
     let cancelled = false;
+    let frameId: number | null = null;
     let attempts = 0;
-
-    const attemptLatestViewportAnchor = () => {
-      if (cancelled) {
-        return;
-      }
-
+    const scrollLatestTurnToNaturalEnd = () => {
+      if (cancelled) return;
       attempts += 1;
-      let accepted = false;
-      const list = virtualListRef.current;
-
-      if (pinMode) {
-        accepted = list?.pinTurnToTop(resolvedLatestTurnId, {
-          behavior: 'auto',
-          pinMode,
-        }) ?? false;
-      } else if (list) {
-        accepted = list.scrollToTurnEndAndClearPin(resolvedLatestTurnId);
-      }
-
-      startupTrace.markPhase('historical_session_latest_anchor_attempt', {
-        sessionId,
-        latestTurnId: resolvedLatestTurnId,
-        accepted,
-        attempt: attempts,
-        mode: pinMode ?? 'bottom',
-      });
-
-      if (accepted) {
-        autoPinnedTurnKeyRef.current = resolvedLatestTurnKey;
+      if (virtualListRef.current?.scrollToTurnEnd(latestTurnId)) {
+        autoTailTurnKeyRef.current = latestTurnKey;
         return;
       }
-
-      if (attempts >= LATEST_TURN_AUTO_PIN_MAX_ATTEMPTS) {
-        startupTrace.markPhase('historical_session_latest_anchor_failed', {
-          sessionId,
-          latestTurnId: resolvedLatestTurnId,
-          attempts,
-          mode: pinMode ?? 'bottom',
-        });
-        return;
+      if (attempts < LATEST_TURN_AUTO_PIN_MAX_ATTEMPTS) {
+        frameId = requestAnimationFrame(scrollLatestTurnToNaturalEnd);
       }
-
-      frameId = requestAnimationFrame(attemptLatestViewportAnchor);
     };
-
-    const shouldAttemptLatestAnchorImmediately =
-      shouldForceLatestAnchorAfterTurnCountChange ||
-      activeSession?.isHistorical === true ||
-      activeSession?.contextRestoreState === 'pending' ||
-      hasPendingHistoryCompletion;
-
-    if (shouldAttemptLatestAnchorImmediately) {
-      attemptLatestViewportAnchor();
-    } else {
-      frameId = requestAnimationFrame(attemptLatestViewportAnchor);
-    }
-
+    frameId = requestAnimationFrame(scrollLatestTurnToNaturalEnd);
     return () => {
       cancelled = true;
-      if (frameId !== null) {
-        cancelAnimationFrame(frameId);
-      }
+      if (frameId !== null) cancelAnimationFrame(frameId);
     };
   }, [
     activeSession?.sessionId,
-    activeSession?.isHistorical,
-    activeSession?.contextRestoreState,
-    activeSession?.remoteConnectionId,
-    activeSession?.remoteSshHost,
-    hasPendingHistoryCompletion,
-    isViewportActive,
     isReadingTurnViewport,
+    isViewportActive,
     latestTurnId,
     latestTurnUsesFollowOutput,
-    latestTurnUsesStickyPin,
     turnSummaries.length,
-    visibleTurnInfo?.turnId,
   ]);
 
   useEffect(() => {
@@ -1527,10 +1468,108 @@ export const ModernFlowChatContainer: React.FC<ModernFlowChatContainerProps> = (
     return true;
   }, [activeSession?.sessionId, switchToLiveTailForSession]);
 
+  /*
+   * Keep a tail-anchored history window anchored as the session grows.
+   *
+   * A window paged in from the tail stops at the newest Turn that existed when
+   * it was cut. The session then appends a Turn and nothing moves the window's
+   * end, so the transcript on screen silently stops at the previous Turn: the
+   * message the user just sent is not rendered at all, and because
+   * `latestTurnId` is read off the rendered items, follow-output never even
+   * learns a new Turn exists — no pin, no follow, and no way to scroll to it.
+   *
+   * `resolveTailWindowGrowth` carries the reasoning and the reason it is not
+   * edge-triggered; this effect is only the plumbing.
+   */
+  const tailAnchoredWindowEndRef = useRef<number | null>(null);
+  useEffect(() => {
+    const sessionId = activeSession?.sessionId;
+    const windowEndOrdinalExclusive = sessionId
+      ? renderedHistoryPresentation?.range.endOrdinalExclusive ?? null
+      : null;
+    const growth = resolveTailWindowGrowth({
+      windowEndOrdinalExclusive,
+      knownTurnCount: activeSessionKnownTurnCount,
+      tailAnchoredWindowEnd: tailAnchoredWindowEndRef.current,
+    });
+
+    if (growth === 'release') {
+      tailAnchoredWindowEndRef.current = null;
+      return;
+    }
+    if (growth === 'anchor') {
+      tailAnchoredWindowEndRef.current = windowEndOrdinalExclusive;
+      return;
+    }
+    if (growth === 'none' || !sessionId || windowEndOrdinalExclusive === null) {
+      return;
+    }
+
+    const extended = flowChatStore.extendSessionHistoryWindow(sessionId, 'after');
+    // Requiring real growth keeps a store that declines to extend from being
+    // re-applied under an ever-rising revision forever.
+    if (extended && extended.range.endOrdinalExclusive > windowEndOrdinalExclusive) {
+      tailAnchoredWindowEndRef.current = extended.range.endOrdinalExclusive;
+      applyHistoryPresentation(sessionId, extended, { completedBoundary: 'after' });
+      return;
+    }
+
+    // The newest Turn is not inside the loaded range this window was cut from.
+    // Dropping back to the canonical tail costs a visible re-page of the
+    // history above, which is why it is the fallback and not the rule — but it
+    // is the only branch that always shows the message the user just sent.
+    restoreTailPresentation();
+  }, [
+    activeSession?.sessionId,
+    activeSessionKnownTurnCount,
+    applyHistoryPresentation,
+    renderedHistoryPresentation,
+    restoreTailPresentation,
+  ]);
+
   const jumpToLiveTail = useCallback(() => {
     return restoreTailPresentation({ followLatest: true });
   }, [restoreTailPresentation]);
 
+  /*
+   * A message sent from the composer gives up whatever history window is on
+   * screen.
+   *
+   * `resolveTailWindowGrowth` deliberately leaves a navigated window alone as
+   * the session grows, because a Turn arriving from elsewhere is no reason to
+   * take a reader out of the history they are in. A Turn they submitted
+   * themselves is, and nothing in the ledger tells the two apart — measured, a
+   * message sent while parked on the first Turn left the transcript on a
+   * 24-item window it was never in, with follow-output holding an answer it
+   * had nothing to align.
+   *
+   * Deliberately not `followLatest`. Restoring the tail is enough: the Turn
+   * comes into the transcript, and follow-output pins it to the viewport top
+   * the way it pins any newly submitted Turn.
+   */
+  useEffect(() => {
+    const handleMessageSubmitted = (event: Event) => {
+      const { sessionId } = (event as CustomEvent<FlowChatMessageSubmittedRequest>).detail ?? {};
+      const reaches = transcriptReachesLatestTurn({
+        windowEndOrdinalExclusive: renderedHistoryPresentation?.range.endOrdinalExclusive ?? null,
+        knownTurnCount: activeSessionKnownTurnCount,
+      });
+      if (!sessionId || sessionId !== activeSessionIdRef.current) return;
+      if (reaches) {
+        return;
+      }
+      restoreTailPresentation();
+    };
+    window.addEventListener(FLOWCHAT_MESSAGE_SUBMITTED_EVENT, handleMessageSubmitted);
+    return () => {
+      window.removeEventListener(FLOWCHAT_MESSAGE_SUBMITTED_EVENT, handleMessageSubmitted);
+    };
+  }, [
+    activeSessionKnownTurnCount,
+    renderedHistoryPresentation,
+    restoreTailPresentation,
+  ]);
+
   const handleSearchChange = useCallback((query: string) => {
     setSearchQuery(query);
     const sessionId = activeSession?.sessionId;
@@ -1573,8 +1612,8 @@ export const ModernFlowChatContainer: React.FC<ModernFlowChatContainerProps> = (
         turnId: renderedTargetId,
         source: isRenderingHistoryProjection ? 'history-range' : 'canonical-tail',
       });
-      const pinStatus = requestTurnNavigationPin(renderedTargetId);
-      if (pinStatus === 'settled' || pinStatus === 'pending') {
+      const navigationStatus = requestTurnNavigation(renderedTargetId);
+      if (navigationStatus === 'settled' || navigationStatus === 'pending') {
         setQueuedTurnNavigation(null);
         return true;
       }
@@ -1606,12 +1645,10 @@ export const ModernFlowChatContainer: React.FC<ModernFlowChatContainerProps> = (
         recentHistoryPresentation.range,
       );
       if (reactivatedPresentation) {
-        const preparedPin = virtualListRef.current?.prepareTurnPinToTop(recentHistoryTurn.id, {
+        const preparedNavigation = virtualListRef.current?.prepareTurnNavigation(recentHistoryTurn.id, {
           behavior: 'auto',
-          pinMode: 'transient',
-          alignmentPolicy: 'best-effort',
         }) ?? 'rejected';
-        if (preparedPin !== 'rejected') {
+        if (preparedNavigation !== 'rejected') {
           applyHistoryPresentation(sessionId, reactivatedPresentation, {
             viewportTarget: {
               ordinal: targetItem.ordinal,
@@ -1647,12 +1684,10 @@ export const ModernFlowChatContainer: React.FC<ModernFlowChatContainerProps> = (
         return false;
       }
 
-      const preparedPin = virtualListRef.current?.prepareTurnPinToTop(targetTurnId, {
+      const preparedNavigation = virtualListRef.current?.prepareTurnNavigation(targetTurnId, {
         behavior: 'auto',
-        pinMode: 'transient',
-        alignmentPolicy: 'best-effort',
       }) ?? 'rejected';
-      if (preparedPin === 'rejected') {
+      if (preparedNavigation === 'rejected') {
         return false;
       }
       const presentation = flowChatStore.activateSessionHistoryWindow(
@@ -1702,7 +1737,7 @@ export const ModernFlowChatContainer: React.FC<ModernFlowChatContainerProps> = (
     applyHistoryPresentation,
     isRenderingHistoryProjection,
     renderedTurnSummaries,
-    requestTurnNavigationPin,
+    requestTurnNavigation,
     restoreTailPresentation,
     turnRailItems,
     updateViewportIntent,
@@ -1774,7 +1809,6 @@ export const ModernFlowChatContainer: React.FC<ModernFlowChatContainerProps> = (
     virtualItems,
     virtualListRef,
     onExpandExploreGroup: handleExpandGroup,
-    onBeforeTurnPinRequest: handleBeforeTurnPinRequest,
     onNavigateToFocusTurn: handleNavigateToFocusTurn,
   });
 
@@ -1815,28 +1849,118 @@ export const ModernFlowChatContainer: React.FC<ModernFlowChatContainerProps> = (
         historyView?.catalog?.totalTurnCount ?? 0,
         session?.totalTurnCount ?? 0,
       );
-      let targetOrdinal: number;
-      if (presentation) {
-        targetOrdinal = direction === 'before'
-          ? presentation.range.startOrdinal - 1
-          : presentation.range.endOrdinalExclusive;
-      } else {
-        if (
-          direction !== 'before'
-          || session?.isPartial !== true
-          || session.turnCatalog?.sessionId !== sessionId
-        ) {
-          return 'cancelled';
+      const loadedTurnCount = session?.dialogTurns.length ?? 0;
+      recordHistoryPagingEvent(sessionId, 'requested', {
+        direction,
+        hasPresentation: presentation !== null,
+        isPartial: session?.isPartial,
+        historyState: session?.historyState,
+        turnCatalogMatches: session?.turnCatalog?.sessionId === sessionId,
+        catalogTotalTurnCount: historyView?.catalog?.totalTurnCount ?? null,
+        sessionTotalTurnCount: session?.totalTurnCount ?? null,
+        resolvedTotalTurnCount: totalTurnCount,
+        loadedTurnCount,
+        loadedRangeCount: historyView?.loadedRanges.length ?? null,
+      });
+
+      /*
+       * The range the ask is derived from is the one on screen, which is the
+       * continuous projection when that is what is rendered. `presentation`
+       * stays the store's window, because the extension below operates on it.
+       */
+      let renderedRange: RenderedTranscriptRange | null =
+        renderedHistoryPresentationRef.current?.sessionId === sessionId
+          ? renderedHistoryPresentationRef.current.range
+          : null;
+      if (!presentation) {
+        const precondition = resolveTailBoundaryPrecondition({
+          direction,
+          isPartial: session?.isPartial,
+          hasSession: session !== undefined,
+          turnCatalogMatches: session?.turnCatalog?.sessionId === sessionId,
+        });
+        if (precondition !== 'ask') {
+          /*
+           * Told apart because only one of them stops the asking. A boundary
+           * that answers `cancelled` is re-armed and asked again on the
+           * reader's next scroll event, which is right while the catalog is
+           * still on its way and is a treadmill once the session has every Turn
+           * it will ever have.
+           */
+          recordHistoryPagingEvent(
+            sessionId,
+            precondition === 'exhausted' ? 'outcome_exhausted' : 'outcome_cancelled',
+            {
+              direction,
+              reason: precondition === 'exhausted' ? 'no-window-nothing-loadable' : 'precondition',
+              isPartial: session?.isPartial,
+              turnCatalogMatches: session?.turnCatalog?.sessionId === sessionId,
+            },
+          );
+          return precondition;
         }
         const canonicalTailRange = flowChatStore.getSessionCanonicalTailRange(sessionId);
         if (!canonicalTailRange) {
+          recordHistoryPagingEvent(sessionId, 'outcome_not_ready', {
+            direction,
+            reason: 'no-canonical-tail-range',
+          });
           return 'not-ready';
         }
-        targetOrdinal = canonicalTailRange.startOrdinal - 1;
+        // No window, so the transcript on screen is the canonical tail: it
+        // starts where that range does and runs to the newest Turn.
+        renderedRange = {
+          startOrdinal: canonicalTailRange.startOrdinal,
+          endOrdinalExclusive: totalTurnCount,
+        };
+        recordHistoryPagingEvent(sessionId, 'target_resolved', {
+          direction,
+          canonicalTailStartOrdinal: canonicalTailRange.startOrdinal,
+          targetOrdinal: canonicalTailRange.startOrdinal - 1,
+        });
       }
-      if (targetOrdinal < 0 || targetOrdinal >= totalTurnCount) {
+      if (!renderedRange) {
+        recordHistoryPagingEvent(sessionId, 'outcome_not_ready', {
+          direction,
+          reason: 'no-rendered-range',
+        });
+        return 'not-ready';
+      }
+      const target = resolveHistoryBoundaryTarget({
+        direction,
+        renderedRange,
+        knownTurnCount: totalTurnCount,
+      });
+      if (target.status === 'exhausted') {
+        recordHistoryPagingEvent(sessionId, 'outcome_exhausted', {
+          direction,
+          reason: target.reason,
+          renderedStartOrdinal: renderedRange.startOrdinal,
+          renderedEndOrdinalExclusive: renderedRange.endOrdinalExclusive,
+          windowEndOrdinalExclusive: presentation?.range.endOrdinalExclusive ?? null,
+          totalTurnCount,
+        });
+        /*
+         * `exhausted` latches the direction off until the window moves, so
+         * reaching it on an unknown or contradictory total is how history goes
+         * silently missing rather than merely late.
+         *
+         * `reached-latest` is not that. It is what the bottom edge of a live
+         * transcript answers every time the reader arrives at it.
+         */
+        if (target.reason === 'beyond-known-total') {
+          warnHistoryPagingRefusedWithPendingTurns(sessionId, {
+            direction,
+            reason: totalTurnCount <= 0 ? 'exhausted-on-unknown-total' : 'exhausted-beyond-total',
+            isPartial: session?.isPartial,
+            loadedTurnCount,
+            totalTurnCount,
+            targetOrdinal: renderedRange.startOrdinal - 1,
+          });
+        }
         return 'exhausted';
       }
+      const targetOrdinal = target.targetOrdinal;
 
       setHistoryBoundaryState(previous => ({ ...previous, [direction]: 'loading' }));
       let viewportPreparationStarted = false;
@@ -1847,6 +1971,22 @@ export const ModernFlowChatContainer: React.FC<ModernFlowChatContainerProps> = (
           after: direction === 'after' ? 12 : 1,
         });
         if (!result.isCurrent || activeSessionIdRef.current !== sessionId) {
+          recordHistoryPagingEvent(sessionId, 'outcome_cancelled', {
+            direction,
+            reason: 'superseded',
+            targetOrdinal,
+            resultIsCurrent: result.isCurrent,
+            activeSessionIsCurrent: activeSessionIdRef.current === sessionId,
+          });
+          /*
+           * The status is ours to clear even though the load was not ours to
+           * finish. Left as it was, this returns silently with the boundary
+           * still reading `loading`, and the reader is shown history being
+           * prepared by nobody for the rest of the session.
+           */
+          if (activeSessionIdRef.current === sessionId) {
+            setHistoryBoundaryState(previous => ({ ...previous, [direction]: 'idle' }));
+          }
           return 'cancelled';
         }
         if (result.status !== 'ready') {
@@ -1856,10 +1996,27 @@ export const ModernFlowChatContainer: React.FC<ModernFlowChatContainerProps> = (
               'sequential-history-navigation',
             );
             if (historyReady && activeSessionIdRef.current === sessionId) {
+              recordHistoryPagingEvent(sessionId, 'outcome_applied', {
+                direction,
+                targetOrdinal,
+                reason: 'full-history-hydrated',
+              });
               setHistoryBoundaryState(previous => ({ ...previous, [direction]: 'idle' }));
               return 'applied';
             }
           }
+          /*
+           * A refusal the reader is shown. It was silent here, and a status the
+           * boundary keeps forever deserves a line saying which load produced
+           * it: 266 asks in one session all landed on `not-found` and left the
+           * status standing, with nothing in the trail between the ask and the
+           * complaint.
+           */
+          recordHistoryPagingEvent(sessionId, 'outcome_not_ready', {
+            direction,
+            reason: `load-${result.status}`,
+            targetOrdinal,
+          });
           setHistoryBoundaryState(previous => ({ ...previous, [direction]: 'error' }));
           return 'not-ready';
         }
@@ -1875,6 +2032,26 @@ export const ModernFlowChatContainer: React.FC<ModernFlowChatContainerProps> = (
           || !activeSessionIsCurrent
           || !presentationOwnerIsCurrent
         ) {
+          recordHistoryPagingEvent(sessionId, 'outcome_cancelled', {
+            direction,
+            reason: 'viewport-preparation',
+            preparationResult: preparationResult ?? null,
+            activeSessionIsCurrent,
+            presentationOwnerIsCurrent,
+          });
+          if (preparationResult === false && activeSessionIsCurrent) {
+            // The window was fetched and then thrown away: the Turns exist but
+            // never reach the transcript, and the boundary status goes back to
+            // idle exactly as if there were none.
+            warnHistoryPagingRefusedWithPendingTurns(sessionId, {
+              direction,
+              reason: 'viewport-preparation-declined',
+              isPartial: session?.isPartial,
+              loadedTurnCount,
+              totalTurnCount,
+              targetOrdinal,
+            });
+          }
           if (viewportPreparationStarted) {
             options?.cancelViewportPresentationCommit?.();
           }
@@ -1891,6 +2068,11 @@ export const ModernFlowChatContainer: React.FC<ModernFlowChatContainerProps> = (
           if (viewportPreparationStarted) {
             options?.cancelViewportPresentationCommit?.();
           }
+          recordHistoryPagingEvent(sessionId, 'outcome_not_ready', {
+            direction,
+            reason: 'no-next-presentation',
+            targetOrdinal,
+          });
           setHistoryBoundaryState(previous => ({ ...previous, [direction]: 'error' }));
           return 'not-ready';
         }
@@ -1905,6 +2087,12 @@ export const ModernFlowChatContainer: React.FC<ModernFlowChatContainerProps> = (
             },
           } : {}),
         });
+        recordHistoryPagingEvent(sessionId, 'outcome_applied', {
+          direction,
+          targetOrdinal,
+          startOrdinal: nextPresentation.range.startOrdinal,
+          endOrdinalExclusive: nextPresentation.range.endOrdinalExclusive,
+        });
         return 'applied';
       } catch (error) {
         if (viewportPreparationStarted) {
@@ -2306,16 +2494,19 @@ export const ModernFlowChatContainer: React.FC<ModernFlowChatContainerProps> = (
           onSend={handleSendBackgroundCommandInput}
         />
 
-        {activePermissionBatch && (
-          <PermissionRequestPanel
-            key={`${activePermissionBatch.sessionId}:${activePermissionBatch.roundId}`}
-            requests={activePermissionBatch.requests}
-            totalPendingCount={permissionRequests.length}
-            aboveChatInput={permissionPanelAboveChatInput}
-            onRespond={respondPermission}
-            onRespondBatch={respondPermissionBatch}
-          />
-        )}
+        <PresenceBoundary active={activePermissionPanelSnapshot != null}>
+          {renderedPermissionPanelSnapshot ? (
+            <PermissionRequestPanel
+              key={`${renderedPermissionPanelSnapshot.batch.sessionId}:${renderedPermissionPanelSnapshot.batch.roundId}`}
+              requests={renderedPermissionPanelSnapshot.batch.requests}
+              totalPendingCount={renderedPermissionPanelSnapshot.totalPendingCount}
+              aboveChatInput={renderedPermissionPanelSnapshot.aboveChatInput}
+              visible={activePermissionPanelSnapshot != null}
+              onRespond={renderedPermissionPanelSnapshot.onRespond}
+              onRespondBatch={renderedPermissionPanelSnapshot.onRespondBatch}
+            />
+          ) : null}
+        </PresenceBoundary>
 
         <div
           className="modern-flowchat-container__messages"
@@ -2376,7 +2567,7 @@ export const ModernFlowChatContainer: React.FC<ModernFlowChatContainerProps> = (
                   items={virtualItems}
                   isViewportActive={isViewportActive}
                   presentationMode={isRenderingHistoryProjection ? 'history-window' : 'tail'}
-                  viewportMode={isReadingTurnViewport ? 'history-reading' : 'live-tail'}
+                  viewportMode={isViewportDetachedFromLiveTail ? 'history-reading' : 'live-tail'}
                   historyWindow={isShowingHistoryPresentation ? activeHistoryPresentation?.range ?? null : null}
                   presentationRevision={isShowingHistoryPresentation ? activeHistoryPresentation?.revision ?? 0 : 0}
                   historyBoundaryState={historyBoundaryState}
diff --git a/src/web-ui/src/flow_chat/components/modern/PermissionRequestPanel.scss b/src/web-ui/src/flow_chat/components/modern/PermissionRequestPanel.scss
index 74c8529114..e5b4c6eda8 100644
--- a/src/web-ui/src/flow_chat/components/modern/PermissionRequestPanel.scss
+++ b/src/web-ui/src/flow_chat/components/modern/PermissionRequestPanel.scss
@@ -8,6 +8,15 @@
   width: min(460px, calc(100% - 40px));
   display: flex;
   justify-content: flex-end;
+  transition:
+    opacity 140ms ease,
+    transform 160ms cubic-bezier(0.23, 1, 0.32, 1);
+
+  &[data-visible='false'] {
+    opacity: 0;
+    transform: translateY(5px) scale(0.985);
+    pointer-events: none;
+  }
 }
 
 .permission-request-anchor--above-chat-input {
@@ -17,6 +26,10 @@
   left: 50%;
   width: min(884px, calc(100% - 16px));
   transform: translateX(-50%);
+
+  &[data-visible='false'] {
+    transform: translateX(-50%) translateY(5px) scale(0.985);
+  }
 }
 
 .permission-request-panel {
@@ -34,6 +47,10 @@
   color: var(--bf-appearance-token-color-text-primary);
   transform-origin: center bottom;
   animation: permission-request-panel-in 180ms cubic-bezier(0.23, 1, 0.32, 1);
+  transition:
+    opacity 120ms ease,
+    transform 150ms cubic-bezier(0.23, 1, 0.32, 1),
+    visibility 0s linear 0s;
 }
 
 .permission-request-panel__heading {
@@ -121,12 +138,40 @@
 }
 
 .permission-request-panel__collapsed-trigger {
-  position: relative;
+  position: absolute;
+  right: 0;
+  bottom: 0;
   width: 44px;
   height: 44px;
   padding: 0;
   border-radius: 50%;
   box-shadow: var(--bf-appearance-token-shadow-lg);
+  opacity: 0;
+  visibility: hidden;
+  pointer-events: none;
+  transform: translateY(4px) scale(0.94);
+  transition:
+    opacity 120ms ease,
+    transform 150ms cubic-bezier(0.23, 1, 0.32, 1),
+    visibility 0s linear 150ms;
+}
+
+.permission-request-anchor[data-collapsed='true'] {
+  .permission-request-panel {
+    opacity: 0;
+    visibility: hidden;
+    pointer-events: none;
+    transform: translateY(4px) scale(0.985);
+    transition-delay: 0s, 0s, 150ms;
+  }
+
+  .permission-request-panel__collapsed-trigger {
+    opacity: 1;
+    visibility: visible;
+    pointer-events: auto;
+    transform: translateY(0) scale(1);
+    transition-delay: 0s;
+  }
 }
 
 .permission-request-panel__collapsed-badge {
@@ -331,8 +376,13 @@
 }
 
 @media (prefers-reduced-motion: reduce) {
+  .permission-request-anchor {
+    transition: none;
+  }
+
   .permission-request-panel {
     animation: none;
+    transition: none;
   }
 
   .permission-request-panel__collapse,
diff --git a/src/web-ui/src/flow_chat/components/modern/PermissionRequestPanel.test.tsx b/src/web-ui/src/flow_chat/components/modern/PermissionRequestPanel.test.tsx
index 935bb64a4a..2a24232a14 100644
--- a/src/web-ui/src/flow_chat/components/modern/PermissionRequestPanel.test.tsx
+++ b/src/web-ui/src/flow_chat/components/modern/PermissionRequestPanel.test.tsx
@@ -368,20 +368,23 @@ describe('PermissionRequestPanel', () => {
       '[data-testid="permission-request-panel-collapse"]',
     );
     expect(collapseButton?.getAttribute('aria-expanded')).toBe('true');
+    collapseButton?.focus();
 
     act(() => collapseButton?.click());
 
-    expect(container.querySelector('.permission-request-panel')).toBeNull();
+    expect(container.querySelector('.permission-request-panel')?.getAttribute('aria-hidden')).toBe('true');
     const expandButton = container.querySelector<HTMLButtonElement>(
       '[data-testid="permission-request-panel-expand"]',
     );
     expect(expandButton?.textContent).toContain('3');
     expect(expandButton?.getAttribute('aria-label')).toBe('Expand 3 pending permission requests');
     expect(expandButton?.getAttribute('aria-expanded')).toBe('false');
+    expect(document.activeElement).toBe(expandButton);
 
     act(() => expandButton?.click());
 
-    expect(container.querySelector('.permission-request-panel')).not.toBeNull();
+    expect(container.querySelector('.permission-request-panel')?.getAttribute('aria-hidden')).toBe('false');
+    expect(document.activeElement).toBe(collapseButton);
   });
 
   it('expands again when a newly active permission batch replaces a collapsed one', () => {
diff --git a/src/web-ui/src/flow_chat/components/modern/PermissionRequestPanel.tsx b/src/web-ui/src/flow_chat/components/modern/PermissionRequestPanel.tsx
index 7028d0ad81..0cb4ebbee6 100644
--- a/src/web-ui/src/flow_chat/components/modern/PermissionRequestPanel.tsx
+++ b/src/web-ui/src/flow_chat/components/modern/PermissionRequestPanel.tsx
@@ -1,4 +1,4 @@
-import { useState, type CSSProperties } from 'react';
+import { useLayoutEffect, useRef, useState, type CSSProperties } from 'react';
 import { Check, ChevronsDown, ShieldAlert, X } from 'lucide-react';
 import { useTranslation } from 'react-i18next';
 import { Tooltip } from '@/component-library';
@@ -19,6 +19,7 @@ interface PermissionRequestPanelProps {
   onRespondBatch: (requestId: string, reply: PermissionReplyKind, feedback?: string) => Promise<void>;
   aboveChatInput?: boolean;
   totalPendingCount?: number;
+  visible?: boolean;
 }
 
 const PERMISSION_ACTION_LABEL_KEYS: Record<string, string> = {
@@ -88,12 +89,16 @@ export function PermissionRequestPanel({
   onRespondBatch,
   aboveChatInput = false,
   totalPendingCount,
+  visible = true,
 }: PermissionRequestPanelProps) {
   const { t } = useTranslation('flow-chat');
   const [feedback, setFeedback] = useState('');
   const [responding, setResponding] = useState(false);
   const [error, setError] = useState(false);
   const [isCollapsed, setIsCollapsed] = useState(false);
+  const collapseButtonRef = useRef<HTMLButtonElement>(null);
+  const expandButtonRef = useRef<HTMLButtonElement>(null);
+  const pendingFocusTargetRef = useRef<'collapsed' | 'expanded' | null>(null);
   const inputHeight = useChatInputState((state) => state.inputHeight);
   const request = requests[0];
   const risk = permissionRisk(request, t);
@@ -101,6 +106,16 @@ export function PermissionRequestPanel({
   const hasRejectFeedback = feedback.trim().length > 0;
   const allowActionsDisabledForFeedback = hasRejectFeedback && !responding;
 
+  useLayoutEffect(() => {
+    if (pendingFocusTargetRef.current === 'collapsed' && isCollapsed) {
+      expandButtonRef.current?.focus();
+      pendingFocusTargetRef.current = null;
+    } else if (pendingFocusTargetRef.current === 'expanded' && !isCollapsed) {
+      collapseButtonRef.current?.focus();
+      pendingFocusTargetRef.current = null;
+    }
+  }, [isCollapsed]);
+
   const alwaysAllowTooltip = request?.saveResources?.length
     ? request.projectPath?.trim()
       ? t('permission.allowAlwaysTooltip', { projectPath: request.projectPath.trim() })
@@ -144,19 +159,32 @@ export function PermissionRequestPanel({
   return (
     <div data-bf-component="permission-request-panel" data-bf-part="root"
       data-bf-state={[isCollapsed && 'collapsed', responding && 'responding', error && 'error'].filter(Boolean).join(' ')}
+      data-visible={visible ? 'true' : 'false'}
+      data-collapsed={isCollapsed ? 'true' : 'false'}
       className={`permission-request-anchor${aboveChatInput ? ' permission-request-anchor--above-chat-input' : ''}`}
       style={panelStyle}
+      aria-hidden={!visible}
+      {...(!visible ? { inert: '' } : {})}
     >
-      {isCollapsed ? (
-        <Tooltip content={t('permission.expandPanel', { count: pendingCount })} placement="top">
+      <Tooltip
+        content={t('permission.expandPanel', { count: pendingCount })}
+        placement="top"
+        disabled={!isCollapsed}
+      >
           <button
+            ref={expandButtonRef}
             type="button"
             data-bf-component="permission-request-panel"
             data-bf-part="collapsedTrigger"
             className="permission-request-panel__collapsed-trigger"
-            onClick={() => setIsCollapsed(false)}
+            onClick={() => {
+              pendingFocusTargetRef.current = 'expanded';
+              setIsCollapsed(false);
+            }}
             aria-label={t('permission.expandPanel', { count: pendingCount })}
             aria-expanded={false}
+            aria-hidden={!isCollapsed}
+            tabIndex={isCollapsed ? 0 : -1}
             data-testid="permission-request-panel-expand"
           >
             <ShieldAlert size={21} aria-hidden="true" />
@@ -164,14 +192,15 @@ export function PermissionRequestPanel({
               {pendingCount > 99 ? '99+' : pendingCount}
             </span>
           </button>
-        </Tooltip>
-      ) : (
+      </Tooltip>
         <section
           id="permission-request-panel"
           data-bf-component="permission-request-panel"
           data-bf-part="panel"
           className="permission-request-panel"
           aria-label={t('permission.title')}
+          aria-hidden={isCollapsed}
+          {...(isCollapsed ? { inert: '' } : {})}
         >
           <div data-bf-component="permission-request-panel" data-bf-part="heading" className="permission-request-panel__heading">
             <div className="permission-request-panel__heading-title">
@@ -184,9 +213,13 @@ export function PermissionRequestPanel({
               </span>
               <Tooltip content={t('permission.collapsePanel')} placement="top">
                 <button
+                  ref={collapseButtonRef}
                   type="button"
                   className="permission-request-panel__collapse"
-                  onClick={() => setIsCollapsed(true)}
+                  onClick={() => {
+                    pendingFocusTargetRef.current = 'collapsed';
+                    setIsCollapsed(true);
+                  }}
                   aria-label={t('permission.collapsePanel')}
                   aria-expanded={true}
                   data-testid="permission-request-panel-collapse"
@@ -301,7 +334,6 @@ export function PermissionRequestPanel({
             </div>
           </div>
         </section>
-      )}
     </div>
   );
 }
diff --git a/src/web-ui/src/flow_chat/components/modern/RuntimeStatusSlot.scss b/src/web-ui/src/flow_chat/components/modern/RuntimeStatusSlot.scss
index f3b07b1fef..2b6e524aa0 100644
--- a/src/web-ui/src/flow_chat/components/modern/RuntimeStatusSlot.scss
+++ b/src/web-ui/src/flow_chat/components/modern/RuntimeStatusSlot.scss
@@ -5,13 +5,8 @@
   flex: 0 0 24px;
   box-sizing: border-box;
   overflow: hidden;
-  visibility: hidden;
   pointer-events: none;
 
-  &--visible {
-    visibility: visible;
-  }
-
   &__content {
     display: flex;
     align-items: center;
@@ -21,7 +16,16 @@
     color: var(--bf-appearance-token-color-text-muted);
     font-size: var(--bf-appearance-token-flowchat-font-size-base);
     line-height: var(--bf-appearance-token-flowchat-support-line-height);
+    opacity: 0;
+    transform: translateY(3px);
+    transition:
+      opacity 140ms ease,
+      transform 160ms cubic-bezier(0.23, 1, 0.32, 1);
+  }
+
+  &--visible &__content {
     opacity: 0.86;
+    transform: translateY(0);
   }
 
   &__hint {
@@ -46,3 +50,10 @@
     }
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .runtime-status-slot__content {
+    transform: none;
+    transition: none;
+  }
+}
diff --git a/src/web-ui/src/flow_chat/components/modern/SessionFileModificationsBar.scss b/src/web-ui/src/flow_chat/components/modern/SessionFileModificationsBar.scss
index 8c7c3e24e4..6afa4274b4 100644
--- a/src/web-ui/src/flow_chat/components/modern/SessionFileModificationsBar.scss
+++ b/src/web-ui/src/flow_chat/components/modern/SessionFileModificationsBar.scss
@@ -16,7 +16,9 @@
   backdrop-filter: blur(20px) saturate(1.3);
   -webkit-backdrop-filter: blur(20px) saturate(1.3);
 
-  transition: all $motion-base $easing-standard;
+  transition:
+    background-color $motion-base $easing-standard,
+    border-color $motion-base $easing-standard;
   position: relative;
   z-index: 9;
 
@@ -88,7 +90,11 @@
     border-radius: 6px;
     color: var(--bf-appearance-token-color-text-secondary);
     cursor: pointer;
-    transition: all $motion-fast $easing-standard;
+    transition:
+      transform $motion-fast $easing-standard,
+      background-color $motion-fast $easing-standard,
+      color $motion-fast $easing-standard,
+      opacity $motion-fast $easing-standard;
     flex-shrink: 0;
 
     &:hover:not(:disabled) {
@@ -154,7 +160,7 @@
     font-size: var(--bf-appearance-token-tool-card-action-font-size);
     color: var(--bf-appearance-token-color-text-primary);
     cursor: pointer;
-    transition: all $motion-fast $easing-standard;
+    transition: background-color $motion-fast $easing-standard;
     user-select: none;
 
     &:hover {
diff --git a/src/web-ui/src/flow_chat/components/modern/SessionFilesBadge.scss b/src/web-ui/src/flow_chat/components/modern/SessionFilesBadge.scss
index 81ae155286..c1443936f7 100644
--- a/src/web-ui/src/flow_chat/components/modern/SessionFilesBadge.scss
+++ b/src/web-ui/src/flow_chat/components/modern/SessionFilesBadge.scss
@@ -25,7 +25,11 @@
     line-height: 1;
     color: var(--bf-appearance-token-color-text-secondary);
     cursor: pointer;
-    transition: all $motion-fast $easing-standard;
+    transition:
+      transform $motion-fast $easing-standard,
+      background-color $motion-fast $easing-standard,
+      color $motion-fast $easing-standard,
+      opacity $motion-fast $easing-standard;
     white-space: nowrap;
 
     // Avoid I-beam over label/icon; beat global :disabled cursor when chained with class.
@@ -86,7 +90,11 @@
     border-radius: $size-radius-base;
     color: var(--bf-appearance-token-color-text-muted);
     cursor: pointer;
-    transition: all $motion-fast $easing-standard;
+    transition:
+      transform $motion-fast $easing-standard,
+      background-color $motion-fast $easing-standard,
+      color $motion-fast $easing-standard,
+      opacity $motion-fast $easing-standard;
 
     span,
     svg {
@@ -236,7 +244,10 @@
     line-height: var(--bf-appearance-token-flowchat-compact-line-height);
     text-align: left;
     cursor: pointer;
-    transition: all $motion-fast $easing-standard;
+    transition:
+      background-color $motion-fast $easing-standard,
+      color $motion-fast $easing-standard,
+      opacity $motion-fast $easing-standard;
 
     span,
     svg {
@@ -404,7 +415,10 @@
     font-size: var(--bf-appearance-token-flowchat-font-size-sm);
     color: var(--bf-appearance-token-color-text-secondary);
     cursor: pointer;
-    transition: all $motion-fast $easing-standard;
+    transition:
+      background-color $motion-fast $easing-standard,
+      color $motion-fast $easing-standard,
+      opacity $motion-fast $easing-standard;
     user-select: none;
 
     span,
diff --git a/src/web-ui/src/flow_chat/components/modern/SessionTreePopover.scss b/src/web-ui/src/flow_chat/components/modern/SessionTreePopover.scss
index 12f813c8e5..611848d247 100644
--- a/src/web-ui/src/flow_chat/components/modern/SessionTreePopover.scss
+++ b/src/web-ui/src/flow_chat/components/modern/SessionTreePopover.scss
@@ -43,6 +43,8 @@
   }
 
   &__panel {
+    --session-tree-popover-offset: -4px;
+
     position: fixed;
     width: min(380px, calc(100vw - 16px));
     max-height: min(440px, calc(100vh - 16px));
@@ -58,6 +60,32 @@
     z-index: $z-popover;
     color: var(--bf-appearance-token-color-text-primary);
     font-family: var(--bf-appearance-token-font-family-sans);
+    transform-origin: center top;
+    transition:
+      opacity 100ms ease,
+      transform 120ms cubic-bezier(0.23, 1, 0.32, 1);
+
+    &[data-open='true']:not([data-keyboard-open='true']) {
+      @starting-style {
+        opacity: 0;
+        transform: translateY(var(--session-tree-popover-offset)) scale(0.985);
+      }
+    }
+
+    &[data-bf-placement='top'] {
+      --session-tree-popover-offset: 4px;
+      transform-origin: center bottom;
+    }
+
+    &[data-open='false'] {
+      opacity: 0;
+      transform: translateY(var(--session-tree-popover-offset)) scale(0.985);
+      pointer-events: none;
+    }
+
+    &[data-keyboard-open='true'] {
+      transition: none;
+    }
   }
 
   &__header {
@@ -287,3 +315,9 @@
     }
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .session-tree-popover__panel {
+    transition: opacity 100ms linear;
+  }
+}
diff --git a/src/web-ui/src/flow_chat/components/modern/SessionTreePopover.test.tsx b/src/web-ui/src/flow_chat/components/modern/SessionTreePopover.test.tsx
index 7c739510bf..f047f537bc 100644
--- a/src/web-ui/src/flow_chat/components/modern/SessionTreePopover.test.tsx
+++ b/src/web-ui/src/flow_chat/components/modern/SessionTreePopover.test.tsx
@@ -137,4 +137,48 @@ describe('SessionTreePopover', () => {
       isRoot: false,
     }));
   });
+
+  it('closes a sibling action-menu portal and restores focus with the parent', async () => {
+    const t = (key: string) => key;
+    await act(async () => {
+      root.render(
+        <SessionTreePopover
+          sessionId="root"
+          fallbackWorkspacePath="/workspace"
+          onCancelSession={vi.fn().mockResolvedValue(true)}
+          t={t}
+        />,
+      );
+    });
+
+    const trigger = container.querySelector<HTMLButtonElement>(
+      '[data-testid="flowchat-header-session-tree"]',
+    );
+    await act(async () => {
+      trigger?.click();
+      await Promise.resolve();
+    });
+
+    const panel = document.querySelector<HTMLElement>('.session-tree-popover__panel');
+    const actionButton = panel?.querySelector<HTMLButtonElement>(
+      '[aria-label="flowChatHeader.agentTreeActions"]',
+    );
+    await act(async () => {
+      actionButton?.click();
+    });
+
+    const actionMenuItem = document.querySelector<HTMLButtonElement>(
+      '[data-testid="flowchat-header-session-tree-menu"] [role="menuitem"]',
+    );
+    actionMenuItem?.focus();
+    expect(document.activeElement).toBe(actionMenuItem);
+
+    await act(async () => {
+      trigger?.click();
+    });
+
+    expect(document.querySelector('[data-testid="flowchat-header-session-tree-menu"]')).toBeNull();
+    expect(document.activeElement).toBe(trigger);
+    expect(panel?.getAttribute('aria-hidden')).toBe('true');
+  });
 });
diff --git a/src/web-ui/src/flow_chat/components/modern/SessionTreePopover.tsx b/src/web-ui/src/flow_chat/components/modern/SessionTreePopover.tsx
index cdafafaf34..4bc96090b7 100644
--- a/src/web-ui/src/flow_chat/components/modern/SessionTreePopover.tsx
+++ b/src/web-ui/src/flow_chat/components/modern/SessionTreePopover.tsx
@@ -10,6 +10,7 @@ import {
   Square,
 } from 'lucide-react';
 import { DotMatrixLoader, IconButton } from '@/component-library';
+import { PresenceBoundary } from '@/component-library/components/PresenceBoundary';
 import { sessionAPI, type SessionLineageSnapshot } from '@/infrastructure/api/service-api/SessionAPI';
 import { getAppearanceOverlayHost } from '@/infrastructure/appearance';
 import { computeFixedPopoverPosition } from '@/shared/utils/fixedPopoverViewport';
@@ -66,6 +67,7 @@ export const SessionTreePopover: React.FC<SessionTreePopoverProps> = ({
   t,
 }) => {
   const [isOpen, setIsOpen] = useState(false);
+  const [keyboardNavigationOpen, setKeyboardNavigationOpen] = useState(false);
   const [snapshot, setSnapshot] = useState<SessionLineageSnapshot | null>(null);
   const [isLoading, setIsLoading] = useState(false);
   const [loadFailed, setLoadFailed] = useState(false);
@@ -119,6 +121,7 @@ export const SessionTreePopover: React.FC<SessionTreePopoverProps> = ({
   useEffect(() => {
     requestGenerationRef.current += 1;
     setIsOpen(false);
+    setKeyboardNavigationOpen(false);
     setSnapshot(null);
     setLoadFailed(false);
     setExpandedSessionIds(new Set());
@@ -128,6 +131,28 @@ export const SessionTreePopover: React.FC<SessionTreePopoverProps> = ({
     setActionMenuPosition(null);
   }, [sessionId]);
 
+  const closePopover = useCallback((source: 'keyboard' | 'pointer' | 'selection') => {
+    const activeElement = document.activeElement;
+    const focusIsInside = Boolean(
+      activeElement
+      && (
+        panelRef.current?.contains(activeElement)
+        || actionMenuRef.current?.contains(activeElement)
+      ),
+    );
+
+    if (source === 'pointer') {
+      setKeyboardNavigationOpen(false);
+    }
+    if (source === 'keyboard' || source === 'selection' || focusIsInside) {
+      triggerRef.current?.focus();
+    }
+
+    setIsOpen(false);
+    setOpenActionSessionId(null);
+    setActionMenuPosition(null);
+  }, []);
+
   useEffect(() => {
     if (!isOpen) return;
     void refreshSnapshot();
@@ -154,14 +179,13 @@ export const SessionTreePopover: React.FC<SessionTreePopoverProps> = ({
         !panelRef.current?.contains(event.target as Node) &&
         !actionMenuRef.current?.contains(event.target as Node)
       ) {
-        setIsOpen(false);
-        setOpenActionSessionId(null);
+        closePopover('pointer');
       }
     };
     const handleKeyDown = (event: KeyboardEvent) => {
       if (event.key === 'Escape') {
-        setIsOpen(false);
-        setOpenActionSessionId(null);
+        event.preventDefault();
+        closePopover('keyboard');
       }
     };
     document.addEventListener('mousedown', handlePointerDown);
@@ -170,7 +194,7 @@ export const SessionTreePopover: React.FC<SessionTreePopoverProps> = ({
       document.removeEventListener('mousedown', handlePointerDown);
       document.removeEventListener('keydown', handleKeyDown);
     };
-  }, [isOpen]);
+  }, [closePopover, isOpen]);
 
   const updateActionMenuPosition = useCallback(() => {
     const anchor = actionMenuAnchorRef.current;
@@ -221,6 +245,11 @@ export const SessionTreePopover: React.FC<SessionTreePopoverProps> = ({
     gap: 8,
     layoutRevision: `${descendantCount}:${isLoading}:${loadFailed}`,
   });
+  const retainedPanelLayoutRef = useRef(panelLayout);
+  if (panelLayout) {
+    retainedPanelLayoutRef.current = panelLayout;
+  }
+  const renderedPanelLayout = panelLayout ?? retainedPanelLayoutRef.current;
 
   useEffect(() => {
     if (!tree) return;
@@ -266,9 +295,8 @@ export const SessionTreePopover: React.FC<SessionTreePopoverProps> = ({
       isRoot: node.isRoot,
     } satisfies SessionTreeSelection;
     onSelectSession?.(selection);
-    setIsOpen(false);
-    setOpenActionSessionId(null);
-  }, [onSelectSession]);
+    closePopover('selection');
+  }, [closePopover, onSelectSession]);
 
   const handleActionMenuToggle = useCallback((
     event: React.MouseEvent<HTMLButtonElement>,
@@ -457,7 +485,18 @@ export const SessionTreePopover: React.FC<SessionTreePopoverProps> = ({
         ].filter(Boolean).join(' ') || undefined}
         variant="ghost"
         size="xs"
-        onClick={() => setIsOpen(open => !open)}
+        onClick={(event) => {
+          const nextOpen = !isOpen;
+          if (nextOpen) {
+            setKeyboardNavigationOpen(event.detail === 0);
+            setIsOpen(true);
+          } else {
+            if (event.detail !== 0) {
+              setKeyboardNavigationOpen(false);
+            }
+            closePopover(event.detail === 0 ? 'keyboard' : 'pointer');
+          }
+        }}
         tooltip={panelLabel}
         aria-label={panelLabel}
         aria-expanded={isOpen}
@@ -473,19 +512,24 @@ export const SessionTreePopover: React.FC<SessionTreePopoverProps> = ({
         </span>
       </IconButton>
 
-      {isOpen ? createPortal(
-        <div
+      <PresenceBoundary active={isOpen}>
+        {createPortal(
+          <div
           ref={panelRef}
           className="session-tree-popover__panel"
           data-bf-component="flow-chat-header"
           data-bf-part="sessionTreePanel"
-          data-bf-placement={panelLayout?.placement ?? 'bottom'}
+          data-bf-placement={renderedPanelLayout?.placement ?? 'bottom'}
+          data-open={isOpen ? 'true' : 'false'}
+          data-keyboard-open={keyboardNavigationOpen ? 'true' : 'false'}
           role="dialog"
           aria-label={panelLabel}
+          aria-hidden={!isOpen}
+          {...(!isOpen ? { inert: '' } : {})}
           style={{
-            top: `${panelLayout?.top ?? 0}px`,
-            left: `${panelLayout?.left ?? 0}px`,
-            visibility: panelLayout ? 'visible' : 'hidden',
+            top: `${renderedPanelLayout?.top ?? 0}px`,
+            left: `${renderedPanelLayout?.left ?? 0}px`,
+            visibility: renderedPanelLayout ? 'visible' : 'hidden',
           }}
         >
           <div
@@ -544,9 +588,10 @@ export const SessionTreePopover: React.FC<SessionTreePopoverProps> = ({
               </div>
             ) : null}
           </div>
-        </div>,
-        getAppearanceOverlayHost(),
-      ) : null}
+          </div>,
+          getAppearanceOverlayHost(),
+        )}
+      </PresenceBoundary>
     </div>
   );
 };
diff --git a/src/web-ui/src/flow_chat/components/modern/UserMessageEditComposer.tsx b/src/web-ui/src/flow_chat/components/modern/UserMessageEditComposer.tsx
index 9dd8781c7e..4230bc2d4b 100644
--- a/src/web-ui/src/flow_chat/components/modern/UserMessageEditComposer.tsx
+++ b/src/web-ui/src/flow_chat/components/modern/UserMessageEditComposer.tsx
@@ -25,6 +25,7 @@ interface UserMessageEditComposerProps {
   presentation?: ComposerPresentation | null;
   workspacePath?: string;
   workspaceId?: string;
+  remoteConnectionId?: string;
   excludeSessionId?: string;
 }
 
@@ -44,6 +45,7 @@ const RichUserMessageEditComposer: React.FC<RichUserMessageEditComposerProps> =
   presentation,
   workspacePath,
   workspaceId,
+  remoteConnectionId,
   excludeSessionId,
 }) => {
   const editorRef = useRef<RichTextInputElement>(null);
@@ -133,6 +135,7 @@ const RichUserMessageEditComposer: React.FC<RichUserMessageEditComposerProps> =
           searchQuery={mentionState.query}
           workspacePath={workspacePath}
           workspaceId={workspaceId}
+          remoteConnectionId={remoteConnectionId}
           excludeSessionId={excludeSessionId}
           anchorRef={mentionAnchorRef}
           onSelect={handleSelectContext}
@@ -183,6 +186,7 @@ export const UserMessageEditComposer: React.FC<UserMessageEditComposerProps> = (
   presentation,
   workspacePath,
   workspaceId,
+  remoteConnectionId,
   excludeSessionId,
 }) => {
   const textareaRef = useRef<HTMLTextAreaElement>(null);
@@ -229,6 +233,7 @@ export const UserMessageEditComposer: React.FC<UserMessageEditComposerProps> = (
         presentation={presentation}
         workspacePath={workspacePath}
         workspaceId={workspaceId}
+        remoteConnectionId={remoteConnectionId}
         excludeSessionId={excludeSessionId}
       />
     );
diff --git a/src/web-ui/src/flow_chat/components/modern/UserMessageItem.scss b/src/web-ui/src/flow_chat/components/modern/UserMessageItem.scss
index e88d76b833..44d349fc7a 100644
--- a/src/web-ui/src/flow_chat/components/modern/UserMessageItem.scss
+++ b/src/web-ui/src/flow_chat/components/modern/UserMessageItem.scss
@@ -560,7 +560,7 @@
   display: flex;
   align-items: center;
   justify-content: center;
-  animation: lightboxFadeIn 180ms cubic-bezier(0.23, 1, 0.32, 1);
+  animation: user-message-lightbox-fade-in 180ms cubic-bezier(0.23, 1, 0.32, 1);
 
   img {
     max-width: 90vw;
@@ -601,22 +601,11 @@
   }
 }
 
-@keyframes lightboxFadeIn {
+@keyframes user-message-lightbox-fade-in {
   from { opacity: 0; }
   to { opacity: 1; }
 }
 
-@keyframes slideInUp {
-  from {
-    opacity: 0;
-    transform: translateY(10px);
-  }
-  to {
-    opacity: 1;
-    transform: translateY(0);
-  }
-}
-
 @media (prefers-reduced-motion: reduce) {
   .user-message-item,
   .user-message-item__copy-btn,
diff --git a/src/web-ui/src/flow_chat/components/modern/UserMessageItem.test.tsx b/src/web-ui/src/flow_chat/components/modern/UserMessageItem.test.tsx
index 8570937a01..10cf3318b1 100644
--- a/src/web-ui/src/flow_chat/components/modern/UserMessageItem.test.tsx
+++ b/src/web-ui/src/flow_chat/components/modern/UserMessageItem.test.tsx
@@ -7,14 +7,22 @@ import { FlowChatContext } from './FlowChatContext';
 import { UserMessageItem } from './UserMessageItem';
 import { globalEventBus } from '@/infrastructure/event-bus';
 import { useMessageEditStore } from '../../store/messageEditStore';
+import {
+  SessionExecutionEvent,
+  stateMachineManager,
+} from '../../state-machine';
 
 globalThis.IS_REACT_ACT_ENVIRONMENT = true;
 
 const activeSessionRef: { current: any } = {
   current: null,
 };
-const snapshotApiMock = vi.hoisted(() => ({
-  rollbackToTurn: vi.fn(async () => [] as string[]),
+const rollbackServiceMock = vi.hoisted(() => ({
+  rollbackSessionToTurn: vi.fn(async () => ({
+    restoredFiles: [],
+    fromTurnIndex: 0,
+    composerText: 'restored prompt',
+  })),
 }));
 const componentLibraryMock = vi.hoisted(() => ({
   confirmDanger: vi.fn(async () => true),
@@ -106,8 +114,7 @@ const flowChatStoreMock = vi.hoisted(() => ({
     sessions: new Map(),
     activeSessionId: null,
   })),
-  ensureSessionFullHistory: vi.fn(async () => true),
-  truncateDialogTurnsFrom: vi.fn(),
+  loadSessionHistory: vi.fn(async () => undefined),
 }));
 
 vi.mock('../../store/FlowChatStore', () => ({
@@ -117,9 +124,7 @@ vi.mock('../../store/FlowChatStore', () => ({
   flowChatStore: flowChatStoreMock,
 }));
 
-vi.mock('@/infrastructure/api', () => ({
-  snapshotAPI: snapshotApiMock,
-}));
+vi.mock('../../services/SessionRollbackService', () => rollbackServiceMock);
 
 vi.mock('@/shared/notification-system', () => ({
   notificationService: {
@@ -168,10 +173,15 @@ describe('UserMessageItem steering tag', () => {
       sessions: new Map(),
       activeSessionId: null,
     });
-    flowChatStoreMock.ensureSessionFullHistory.mockResolvedValue(true);
+    flowChatStoreMock.loadSessionHistory.mockResolvedValue(undefined);
     componentLibraryMock.confirmDanger.mockResolvedValue(true);
-    snapshotApiMock.rollbackToTurn.mockResolvedValue([]);
+    rollbackServiceMock.rollbackSessionToTurn.mockResolvedValue({
+      restoredFiles: [],
+      fromTurnIndex: 0,
+      composerText: 'restored prompt',
+    });
     editServiceMock.editAndRerunUserMessage.mockResolvedValue(undefined);
+    stateMachineManager.clear();
     useMessageEditStore.getState().cancelEdit();
     dom = new JSDOM('<!doctype html><html><body><div id="root"></div></body></html>', {
       pretendToBeVisual: true,
@@ -533,7 +543,7 @@ describe('UserMessageItem steering tag', () => {
     expect(container.querySelector<HTMLButtonElement>('.user-message-item__rollback-btn')?.disabled).toBe(false);
   });
 
-  it('hydrates partial history before rollback and uses the global Turn index', async () => {
+  it('rolls back partial history by stable Turn identity without full hydration', async () => {
     activeSessionRef.current = {
       sessionId: 'partial-session',
       sessionKind: 'normal',
@@ -591,12 +601,8 @@ describe('UserMessageItem steering tag', () => {
       await Promise.resolve();
     });
 
-    expect(flowChatStoreMock.ensureSessionFullHistory).toHaveBeenCalledWith(
-      'partial-session',
-      'user-message-rollback',
-    );
-    expect(snapshotApiMock.rollbackToTurn).toHaveBeenCalledWith('partial-session', 19, true);
-    expect(flowChatStoreMock.truncateDialogTurnsFrom).toHaveBeenCalledWith('partial-session', 19);
+    expect(rollbackServiceMock.rollbackSessionToTurn).toHaveBeenCalledWith(expect.objectContaining({ sessionId: 'partial-session', targetTurnId: 'turn-20', kind: 'rollback' }));
+    expect(flowChatStoreMock.loadSessionHistory).not.toHaveBeenCalled();
   });
 
   it('keeps edit and rollback available for a rendered Turn outside the canonical tail', () => {
@@ -628,7 +634,33 @@ describe('UserMessageItem steering tag', () => {
     expect(container.querySelector<HTMLButtonElement>('.user-message-item__rollback-btn')?.disabled).toBe(false);
   });
 
-  it('hydrates a cataloged history-window Turn before rollback', async () => {
+  it('disables edit and rollback while the Session is not idle', async () => {
+    activeSessionRef.current = createPartialHistorySession(false);
+    await stateMachineManager.transition('partial-session', SessionExecutionEvent.START);
+
+    await act(async () => {
+      root.render(
+        <FlowChatContext.Provider
+          value={{
+            sessionId: 'partial-session',
+            allowUserMessageRollback: true,
+            allowUserMessageEdit: true,
+          }}
+        >
+          <UserMessageItem
+            message={{ id: 'user-partial-5', content: 'older window prompt', timestamp: 1000 }}
+            turnId="turn-5"
+            absoluteTurnIndex={5}
+          />
+        </FlowChatContext.Provider>,
+      );
+    });
+
+    expect(container.querySelector<HTMLButtonElement>('.user-message-item__edit-btn')?.disabled).toBe(true);
+    expect(container.querySelector<HTMLButtonElement>('.user-message-item__rollback-btn')?.disabled).toBe(true);
+  });
+
+  it('rolls back a cataloged history-window Turn by stable identity', async () => {
     activeSessionRef.current = createPartialHistorySession(true);
     flowChatStoreMock.getState.mockReturnValue(
       createHydratedHistoryState(activeSessionRef.current),
@@ -657,15 +689,10 @@ describe('UserMessageItem steering tag', () => {
       await Promise.resolve();
     });
 
-    expect(flowChatStoreMock.ensureSessionFullHistory).toHaveBeenCalledWith(
-      'partial-session',
-      'user-message-rollback',
-    );
-    expect(snapshotApiMock.rollbackToTurn).toHaveBeenCalledWith('partial-session', 4, true);
-    expect(flowChatStoreMock.truncateDialogTurnsFrom).toHaveBeenCalledWith('partial-session', 4);
+    expect(rollbackServiceMock.rollbackSessionToTurn).toHaveBeenCalledWith(expect.objectContaining({ sessionId: 'partial-session', targetTurnId: 'turn-5', kind: 'rollback' }));
   });
 
-  it('hydrates a cataloged history-window Turn before editing and rerunning', async () => {
+  it('edits and reruns a cataloged history-window Turn without pre-hydration', async () => {
     activeSessionRef.current = createPartialHistorySession(true);
     flowChatStoreMock.getState.mockReturnValue(
       createHydratedHistoryState(activeSessionRef.current),
@@ -702,16 +729,12 @@ describe('UserMessageItem steering tag', () => {
       await Promise.resolve();
     });
 
-    expect(flowChatStoreMock.ensureSessionFullHistory).toHaveBeenCalledWith(
-      'partial-session',
-      'user-message-edit',
-    );
     expect(editServiceMock.editAndRerunUserMessage).toHaveBeenCalledWith(expect.objectContaining({
       sessionId: 'partial-session',
       turnId: 'turn-5',
-      turnIndex: 4,
       originalContent: 'older window prompt',
       editedContent: 'edited older window prompt',
     }));
+    expect(flowChatStoreMock.loadSessionHistory).not.toHaveBeenCalled();
   });
 });
diff --git a/src/web-ui/src/flow_chat/components/modern/UserMessageItem.tsx b/src/web-ui/src/flow_chat/components/modern/UserMessageItem.tsx
index d8b1a0a21c..c05411e3b1 100644
--- a/src/web-ui/src/flow_chat/components/modern/UserMessageItem.tsx
+++ b/src/web-ui/src/flow_chat/components/modern/UserMessageItem.tsx
@@ -12,8 +12,14 @@ import { flowChatManager } from '../../services/FlowChatManager';
 import { useFlowChatContext } from './FlowChatContext';
 import { useActiveSession } from '../../store/modernFlowChatStore';
 import { flowChatStore } from '../../store/FlowChatStore';
+import {
+  FLOWCHAT_TURNS_ROLLED_BACK_EVENT,
+  type FlowChatTurnsRolledBackRequest,
+} from '../../events/flowchatNavigation';
 import { useMessageEditStore } from '../../store/messageEditStore';
-import { snapshotAPI } from '@/infrastructure/api';
+import { useSessionMutationStore } from '../../store/sessionMutationStore';
+import { useSessionStateMachine } from '../../hooks/useSessionStateMachine';
+import { SessionExecutionState, stateMachineManager } from '../../state-machine';
 import { useI18n } from '@/infrastructure/i18n';
 import { notificationService } from '@/shared/notification-system';
 import { globalEventBus } from '@/infrastructure/event-bus';
@@ -27,6 +33,7 @@ import {
   describeUserMessageEditImpact,
   editAndRerunUserMessage,
 } from '../../services/UserMessageEditService';
+import { rollbackSessionToTurn } from '../../services/SessionRollbackService';
 import { createLogger } from '@/shared/utils/logger';
 import type { SessionUsageReport } from '@/infrastructure/api/service-api/SessionAPI';
 import { SessionUsageReportCard } from '../usage/SessionUsageReportCard';
@@ -101,7 +108,6 @@ export const UserMessageItem = React.memo<UserMessageItemProps>(
     const [copied, setCopied] = useState(false);
     const [expanded, setExpanded] = useState(false);
     const [hasOverflow, setHasOverflow] = useState(false);
-    const [isRollingBack, setIsRollingBack] = useState(false);
     const [lightboxImage, setLightboxImage] = useState<string | null>(null);
     // Fine-grained selectors: only the message being edited re-renders on
     // draft keystrokes; other list items subscribe to booleans that rarely flip.
@@ -144,6 +150,16 @@ export const UserMessageItem = React.memo<UserMessageItemProps>(
     const resolvedTurnStatus = dialogTurn?.status ?? turnStatus;
     const isFailed = resolvedTurnStatus === 'error';
     const resolvedSessionId = sessionId ?? currentSession?.sessionId;
+    const sessionMachine = useSessionStateMachine(resolvedSessionId ?? null);
+    const sessionExecutionState = sessionMachine && sessionMachine.sessionId === resolvedSessionId
+      ? sessionMachine.currentState
+      : resolvedSessionId
+        ? stateMachineManager.getCurrentState(resolvedSessionId)
+        : SessionExecutionState.IDLE;
+    const isSessionIdle = sessionExecutionState === SessionExecutionState.IDLE;
+    const sessionMutation = useSessionMutationStore(s => (
+      resolvedSessionId ? s.mutations.get(resolvedSessionId) : undefined
+    ));
     const resolvedAbsoluteTurnIndex = absoluteTurnIndex ?? (
       currentSession ? absoluteSessionTurnIndexForId(currentSession, turnId) : undefined
     );
@@ -160,7 +176,8 @@ export const UserMessageItem = React.memo<UserMessageItemProps>(
       !!resolvedSessionId &&
       actionTurnIndex >= 0 &&
       !isRemoteSession &&
-      !isRollingBack &&
+      isSessionIdle &&
+      !sessionMutation &&
       !isEditSubmitting;
     const canEditBase =
       allowUserMessageEdit &&
@@ -170,7 +187,7 @@ export const UserMessageItem = React.memo<UserMessageItemProps>(
       !isThreadGoalSystemMessage &&
       !isSystemTriggered &&
       !steeringStatus;
-    const canEdit = canEditBase && !isEditSubmitting && !isRollingBack;
+    const canEdit = canEditBase && isSessionIdle && !isEditSubmitting && !sessionMutation;
     const canShowEditAction = allowUserMessageEdit && !isFailed && !isThreadGoalSystemMessage;
     const editDisabledReason = isRemoteSession
       ? t('message.editDisabledRemote')
@@ -180,11 +197,15 @@ export const UserMessageItem = React.memo<UserMessageItemProps>(
           ? t('message.cannotEdit')
           : !resolvedSessionId || actionTurnIndex < 0
               ? t('message.editDisabledHistoryNotReady')
+              : !isSessionIdle
+                ? t('message.editDisabledBusy')
               : t('message.cannotEdit');
     const rollbackTooltip = canRollback
       ? t('message.rollbackTo', { index: actionTurnIndex + 1 })
       : isRemoteSession
         ? t('message.rollbackDisabledRemote')
+        : !isSessionIdle
+          ? t('message.rollbackDisabledBusy')
         : t('message.cannotRollback');
     const steeringTag = steeringStatus === 'pending'
       ? {
@@ -274,43 +295,24 @@ export const UserMessageItem = React.memo<UserMessageItemProps>(
       );
       if (!confirmed) return;
 
-      setIsRollingBack(true);
       try {
-        const historyReady = await flowChatStore.ensureSessionFullHistory(
-          resolvedSessionId,
-          'user-message-rollback',
-        );
-        const hydratedTurnIndex = flowChatStore
-          .getState()
-          .sessions
-          .get(resolvedSessionId)
-          ?.dialogTurns.findIndex(turn => turn.id === turnId) ?? -1;
-        if (!historyReady || hydratedTurnIndex < 0) {
-          throw new Error(t('message.cannotRollback'));
-        }
-
-        const restoredFiles = await snapshotAPI.rollbackToTurn(
-          resolvedSessionId,
-          hydratedTurnIndex,
-          true,
-        );
-
-        // 1) Truncate local dialog turns from this index.
-        flowChatStore.truncateDialogTurnsFrom(resolvedSessionId, hydratedTurnIndex);
+        const result = await rollbackSessionToTurn({
+          sessionId: resolvedSessionId,
+          targetTurnId: turnId,
+          kind: 'rollback',
+        });
 
-        // 2) Refresh file tree and open editors.
-        const { globalEventBus } = await import('@/infrastructure/event-bus');
-        globalEventBus.emit('file-tree:refresh');
-        restoredFiles.forEach(filePath => {
-          globalEventBus.emit('editor:file-changed', { filePath });
+        requestAnimationFrame(() => {
+          window.dispatchEvent(new CustomEvent<FlowChatTurnsRolledBackRequest>(
+            FLOWCHAT_TURNS_ROLLED_BACK_EVENT,
+            { detail: { sessionId: resolvedSessionId, fromTurnIndex: result.fromTurnIndex } },
+          ));
         });
 
-        // 3) Restore the original user input back into the chat input box.
-        //    Rollback is an explicit user action — always fill to avoid the
-        //    content silently disappearing when the input already has text.
-        if (messageContent.trim().length > 0) {
+        const composerContent = result.composerText ?? messageContent;
+        if (composerContent.trim().length > 0) {
           globalEventBus.emit('fill-chat-input', {
-            content: messageContent,
+            content: composerContent,
             ...(composerPresentation ? { composerPresentation } : {}),
           });
         }
@@ -319,8 +321,6 @@ export const UserMessageItem = React.memo<UserMessageItemProps>(
       } catch (error) {
         log.error('Rollback failed', error);
         notificationService.error(`${t('message.rollbackFailed')}: ${error instanceof Error ? error.message : String(error)}`);
-      } finally {
-        setIsRollingBack(false);
       }
     }, [actionTurnIndex, canRollback, composerPresentation, resolvedSessionId, t, turnId, messageContent]);
 
@@ -361,33 +361,21 @@ export const UserMessageItem = React.memo<UserMessageItemProps>(
 
       setEditSubmitting(true);
       try {
-        const historyReady = await flowChatStore.ensureSessionFullHistory(
-          resolvedSessionId,
-          'user-message-edit',
-        );
-        const hydratedTurnIndex = flowChatStore
-          .getState()
-          .sessions
-          .get(resolvedSessionId)
-          ?.dialogTurns.findIndex(turn => turn.id === turnId) ?? -1;
-        if (!historyReady || hydratedTurnIndex < 0) {
-          throw new Error(t('message.editDisabledHistoryNotReady'));
-        }
-
         await editAndRerunUserMessage({
           sessionId: resolvedSessionId,
           turnId,
-          turnIndex: hydratedTurnIndex,
           originalContent: messageContent,
           editedContent,
           agentType: currentSession?.mode,
-          rerun: (content, agentType) => {
+          rerun: (content, agentType, sessionMutationLeaseId) => {
             if (!editedPresentation) {
               return flowChatManager.sendMessage(
                 content,
                 resolvedSessionId,
                 undefined,
                 agentType,
+                undefined,
+                { sessionMutationLeaseId },
               );
             }
 
@@ -398,7 +386,10 @@ export const UserMessageItem = React.memo<UserMessageItemProps>(
               payload.displayMessage,
               agentType,
               undefined,
-              { userMessageMetadata: payload.userMessageMetadata },
+              {
+                userMessageMetadata: payload.userMessageMetadata,
+                sessionMutationLeaseId,
+              },
             );
           },
         });
@@ -539,6 +530,10 @@ export const UserMessageItem = React.memo<UserMessageItemProps>(
             presentation={composerPresentation}
             workspacePath={currentSession?.workspacePath}
             workspaceId={currentSession?.workspaceId}
+            remoteConnectionId={
+              currentSession?.remoteConnectionId
+              || currentSession?.config?.remoteConnectionId
+            }
             excludeSessionId={resolvedSessionId}
           />
         ) : (
@@ -644,7 +639,7 @@ export const UserMessageItem = React.memo<UserMessageItemProps>(
                     disabled={!canRollback}
                     title={rollbackTooltip}
                   >
-                    {isRollingBack ? (
+                    {sessionMutation?.kind === 'rollback' && sessionMutation.targetTurnId === turnId ? (
                       <Loader2 size={14} className="user-message-item__rollback-spinner" />
                     ) : (
                       <RotateCcw size={14} />
diff --git a/src/web-ui/src/flow_chat/components/modern/VirtualItemRenderer.scss b/src/web-ui/src/flow_chat/components/modern/VirtualItemRenderer.scss
index daa9aa97f6..560680ee97 100644
--- a/src/web-ui/src/flow_chat/components/modern/VirtualItemRenderer.scss
+++ b/src/web-ui/src/flow_chat/components/modern/VirtualItemRenderer.scss
@@ -20,6 +20,25 @@
     max-width: 100%;
   }
 
+  /*
+   * No mount animation survives inside a virtualized row.
+   *
+   * `.markdown-renderer` carries `animation: fadeIn 0.35s` from the shared
+   * component library, where a block is mounted once and a fade reads as the
+   * content arriving. Here a row mounts every time it enters the rendered
+   * window: the four Turns a history page brings, the rows the junction's own
+   * correction scrolls into view, and every row the reader scrolls back over
+   * afterwards. Each one fades from transparent, so a page up reads as the
+   * transcript dimming and coming back — the same reason `ModelRoundItem.scss`
+   * and the typewriter's `replayOnMount` refuse a mount animation of their own.
+   *
+   * Scoped to the wrapper rather than removed from the library: outside the
+   * list — docs, previews, panels — a markdown block really is mounted once.
+   */
+  .markdown-renderer {
+    animation: none;
+  }
+
   &--search-match {
     outline: 1px solid color-mix(in srgb, var(--bf-appearance-token-color-accent-500) 35%, transparent);
     outline-offset: -1px;
diff --git a/src/web-ui/src/flow_chat/components/modern/VirtualItemRenderer.tsx b/src/web-ui/src/flow_chat/components/modern/VirtualItemRenderer.tsx
index 00497c479c..cda9ad1c1c 100644
--- a/src/web-ui/src/flow_chat/components/modern/VirtualItemRenderer.tsx
+++ b/src/web-ui/src/flow_chat/components/modern/VirtualItemRenderer.tsx
@@ -18,10 +18,17 @@ import './VirtualItemRenderer.scss';
 interface VirtualItemRendererProps {
   item: VirtualItem;
   index: number;
+  /**
+   * Ref callback the virtualizer measures this item through.
+   *
+   * It reads `data-virtual-index` back off the element, so the attribute below
+   * and this callback have to land on the same node.
+   */
+  measureRef?: (element: HTMLElement | null) => void;
 }
 
 export const VirtualItemRenderer = React.memo<VirtualItemRendererProps>(
-  ({ item, index }) => {
+  ({ item, index, measureRef }) => {
     const { searchMatchIndices, searchCurrentMatchVirtualIndex } = useFlowChatVolatileContext();
     const isSearchMatch = searchMatchIndices != null && searchMatchIndices.size > 0
       ? searchMatchIndices.has(index)
@@ -62,6 +69,7 @@ export const VirtualItemRenderer = React.memo<VirtualItemRendererProps>(
               turnEndedAt={item.turnEndedAt}
               turnDurationMs={item.turnDurationMs}
               turnTokenUsage={item.turnTokenUsage}
+              expandedThinkingItemIds={item.layoutHints?.expandedThinkingItemIds ?? []}
             />
           );
         
@@ -109,6 +117,7 @@ export const VirtualItemRenderer = React.memo<VirtualItemRendererProps>(
 
     return (
       <div
+        ref={measureRef}
         data-bf-component="virtual-item"
         data-bf-part="root"
         data-bf-state={[isSearchMatch && 'searchMatch', isSearchCurrent && 'searchCurrent'].filter(Boolean).join(' ')}
@@ -125,7 +134,8 @@ export const VirtualItemRenderer = React.memo<VirtualItemRendererProps>(
   },
   (prev, next) => (
     prev.item === next.item &&
-    prev.index === next.index
+    prev.index === next.index &&
+    prev.measureRef === next.measureRef
   )
 );
 VirtualItemRenderer.displayName = 'VirtualItemRenderer';
diff --git a/src/web-ui/src/flow_chat/components/modern/VirtualMessageList.layout.test.ts b/src/web-ui/src/flow_chat/components/modern/VirtualMessageList.layout.test.ts
index aca78d3c4f..e2a0fc2f60 100644
--- a/src/web-ui/src/flow_chat/components/modern/VirtualMessageList.layout.test.ts
+++ b/src/web-ui/src/flow_chat/components/modern/VirtualMessageList.layout.test.ts
@@ -1,11 +1,14 @@
 import { describe, expect, it } from 'vitest';
 import {
   estimateTextHeightFromLength,
+  estimateVirtualMessageItemHeightWithContext,
   estimateVirtualMessageItemHeight,
   getVirtualMessageDefaultItemHeight,
   selectInitialHistoryRenderWindow,
 } from './virtualMessageListLayout';
+import { estimateToolHeight } from './virtualItemHeightEstimators';
 import type { VirtualItem } from '../../store/modernFlowChatStore';
+import type { FlowToolItem } from '../../types/flow-chat';
 
 describe('getVirtualMessageDefaultItemHeight', () => {
   it('keeps compact historical projections on the small row estimate', () => {
@@ -71,6 +74,35 @@ describe('estimateVirtualMessageItemHeight', () => {
     expect(estimateVirtualMessageItemHeight(item)).toBeGreaterThan(1000);
   });
 
+  it('uses the shared collapsed hint for completed thinking rounds', () => {
+    const item = {
+      type: 'model-round',
+      turnId: 'turn-1',
+      isLastRound: false,
+      isTurnComplete: true,
+      layoutHints: { expandedThinkingItemIds: [] },
+      data: {
+        id: 'round-thinking',
+        status: 'completed',
+        isStreaming: false,
+        items: [{
+          id: 'thinking-1',
+          type: 'thinking',
+          content: 'x'.repeat(13_016),
+          status: 'completed',
+          timestamp: 1,
+        }],
+      },
+    } as VirtualItem;
+
+    expect(estimateVirtualMessageItemHeight(item)).toBe(200);
+
+    expect(estimateVirtualMessageItemHeight({
+      ...item,
+      layoutHints: { expandedThinkingItemIds: ['thinking-1'] },
+    })).toBeGreaterThan(1000);
+  });
+
   it('keeps compact user-only rows small enough for partial history tails', () => {
     const item = {
       type: 'user-message',
@@ -84,6 +116,80 @@ describe('estimateVirtualMessageItemHeight', () => {
 
     expect(estimateVirtualMessageItemHeight(item)).toBeLessThanOrEqual(160);
   });
+
+  it('uses tool-owned data to distinguish compact and expanded Write estimates', () => {
+    const tool = {
+      id: 'write-1',
+      type: 'tool',
+      toolName: 'Write',
+      status: 'completed',
+      timestamp: 1,
+      toolCall: {
+        id: 'call-1',
+        input: { content: 'x'.repeat(600) },
+      },
+    } as FlowToolItem;
+
+    const completed = estimateToolHeight(tool);
+    const running = estimateToolHeight({
+      ...tool,
+      status: 'running',
+    } as FlowToolItem);
+
+    expect(completed.heightPx).toBeLessThan(running.heightPx);
+    expect(running.kind).toBe('tool-write');
+  });
+
+  it('uses layout width and explicit Explore state for unmeasured rows', () => {
+    const textItem = {
+      type: 'model-round',
+      turnId: 'turn-1',
+      isLastRound: true,
+      isTurnComplete: true,
+      data: {
+        id: 'round-width',
+        status: 'completed',
+        isStreaming: false,
+        items: [{
+          id: 'text-width',
+          type: 'text',
+          content: 'x'.repeat(600),
+          status: 'completed',
+          timestamp: 1,
+        }],
+      },
+    } as VirtualItem;
+    expect(estimateVirtualMessageItemHeightWithContext(textItem, { availableWidthPx: 360 }))
+      .toBeGreaterThan(estimateVirtualMessageItemHeightWithContext(textItem, { availableWidthPx: 1200 }));
+
+    const exploreItem = {
+      type: 'explore-group',
+      turnId: 'turn-1',
+      data: {
+        groupId: 'group-1',
+        allItems: [{
+          id: 'tool-1',
+          type: 'tool',
+          toolName: 'Write',
+          status: 'running',
+          timestamp: 1,
+          toolCall: { id: 'call-1', input: { content: 'x'.repeat(300) } },
+        }],
+        stats: { readCount: 0, searchCount: 0, commandCount: 0 },
+        rounds: [],
+        isGroupStreaming: false,
+        isLastGroupInTurn: true,
+        wasCutByCritical: true,
+      },
+    } as VirtualItem;
+    const collapsed = estimateVirtualMessageItemHeightWithContext(exploreItem, {
+      exploreGroupStates: new Map([['group-1', false]]),
+    });
+    const expanded = estimateVirtualMessageItemHeightWithContext(exploreItem, {
+      exploreGroupStates: new Map([['group-1', true]]),
+    });
+    expect(expanded).toBeGreaterThan(collapsed);
+  });
 });
 
 describe('selectInitialHistoryRenderWindow', () => {
diff --git a/src/web-ui/src/flow_chat/components/modern/VirtualMessageList.scss b/src/web-ui/src/flow_chat/components/modern/VirtualMessageList.scss
index 373b2be22f..35f1110e74 100644
--- a/src/web-ui/src/flow_chat/components/modern/VirtualMessageList.scss
+++ b/src/web-ui/src/flow_chat/components/modern/VirtualMessageList.scss
@@ -29,26 +29,42 @@
   }
   
   
-  // Ensure the Virtuoso container has correct sizing.
-  > div:first-child {
+  /*
+   * The scroller. It spans the full panel width even though message content
+   * inside it is max-width constrained, and `overflow-anchor: none` keeps the
+   * browser from adding a second opinion about where the viewport belongs —
+   * the viewport anchor is the only one.
+   */
+  &__scroller {
     width: 100%;
     height: 100%;
     position: relative;
     z-index: 1; // Keep scroll content below overlays.
-    overflow-x: hidden; // Disable horizontal scrolling.
+    overflow-y: auto;
+    overflow-x: hidden;
+    overflow-anchor: none;
+    scrollbar-gutter: stable;
   }
 
-  // Ensure the real scroller always spans the full panel width,
-  // even when inner message content is max-width constrained.
-  [data-virtuoso-scroller='true'],
-  [data-virtuoso-scroller] {
-    width: 100% !important;
-    max-width: none !important;
-    margin: 0 !important;
+  /*
+   * The rendered window. Everything outside it stands in as padding, so this
+   * element's height is the whole transcript's and it is what the resize
+   * observer watches for a content change.
+   */
+  &__items {
+    width: 100%;
     overflow-anchor: none;
-    scrollbar-gutter: stable;
   }
   
+  /*
+   * The opening viewport settles over several frames as items measure and
+   * history pages in. Keep it laid out and measurable but unpainted until then;
+   * see the opening-reveal effect in VirtualMessageList.tsx.
+   */
+  &[data-open-viewport-settled='false'] {
+    visibility: hidden;
+  }
+
   &--empty {
     display: flex;
     align-items: center;
@@ -62,11 +78,16 @@
     padding: 2rem;
   }
   
-  // Reserve space for the floating FlowChatHeader.
-  // Header height (36px) + border (1px) + blur area (16px) + extra gap (4px) = 57px.
+  // FlowChatHeader sits above the list in normal flow, so only a small
+  // breathing gap is needed before the first item. Its height is supplied
+  // inline from `FLOWCHAT_TURN_TOP_GAP_PX`, which every top-aligned Turn also
+  // scrolls to — the gap must be one number, not two that happen to match.
+  .message-list-header-block {
+    flex-shrink: 0;
+    overflow-anchor: none;
+  }
+
   .message-list-header {
-    height: 57px;
-    min-height: 57px;
     flex-shrink: 0;
   }
 
@@ -112,42 +133,20 @@
   }
   
   .message-list-footer {
-    /* Inline height from VirtualMessageList (measured drop-zone + bottom inset + tail clearance). */
-    height: 120px;
-    min-height: 72px;
+    /* Current input-stack inset is supplied inline by VirtualMessageList. */
     overflow-anchor: none;
   }
 
-  &__projection-handoff-items {
+  /*
+   * Resident tail reservation (~1 viewport, supplied inline). It exists so the
+   * browser cannot clamp scrollTop when content shrinks; see
+   * `flowChatTailFollow.ts`. Height must stay a function of the viewport only.
+   */
+  .message-list-tail-spacer {
     width: 100%;
-  }
-
-  &__projection-handoff-overlay {
-    position: absolute;
-    inset: 0;
-    z-index: 2;
-    overflow: hidden;
-    scrollbar-gutter: stable;
+    flex-shrink: 0;
     pointer-events: none;
-    background: var(--bf-appearance-token-color-bg-scene);
-    contain: paint;
-  }
-
-  &__projection-handoff-content {
-    width: 100%;
-    will-change: transform;
-
-    &--bottom {
-      position: absolute;
-      left: 0;
-      right: 0;
-      bottom: 0;
-      min-height: 100%;
-      display: flex;
-      flex-direction: column;
-      justify-content: flex-end;
-      transform: none;
-    }
+    overflow-anchor: none;
   }
 
 }
@@ -156,3 +155,9 @@
   from { transform: rotate(0deg); }
   to { transform: rotate(360deg); }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .virtual-message-list__history-paging-spinner {
+    animation: none;
+  }
+}
diff --git a/src/web-ui/src/flow_chat/components/modern/VirtualMessageList.session-boundary.test.tsx b/src/web-ui/src/flow_chat/components/modern/VirtualMessageList.session-boundary.test.tsx
index 8c292f2968..abf217ac86 100644
--- a/src/web-ui/src/flow_chat/components/modern/VirtualMessageList.session-boundary.test.tsx
+++ b/src/web-ui/src/flow_chat/components/modern/VirtualMessageList.session-boundary.test.tsx
@@ -1,444 +1,301 @@
 // @vitest-environment jsdom
 
-import React from 'react';
-import { act } from 'react';
+import React, { act } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import {
-  VirtualMessageList,
-  type VirtualMessageListRef,
-} from './VirtualMessageList';
-import { getLeadingVirtualItemIndexDelta } from './virtualMessageListLayout';
-import { FlowChatViewportCoordinator } from './FlowChatViewportCoordinator';
-import {
-  clampPinReservationPxToViewport,
-  consumeBottomReservationForContentGrowth,
-  ensureCollapseReservationForScrollTop,
-  getCanceledUnsettledStickyPinGrowthPx,
-  isTurnPinRequestIdentityCurrent,
-  protectCurrentCollapseReservation,
-  reconcileUnsignaledShrinkReservation,
-  releasePinReservationForUserNavigation,
-  resolveAutoCollapseAnchorScrollTop,
-  resolveCollapseIntentSettlementStrategy,
-  resolveFollowingTailShrinkClampRecovery,
-  resolveProvisionalStickyPinReservationPx,
-  resolveStickyPinGrowthSettlementStrategy,
-  settleRetainedCollapseReservationForAnchor,
-  settleCollapseReservationForViewport,
-  shouldBypassShrinkCompensationInTailFollow,
-  shouldClearExpiredProvisionalStickyPin,
-  shouldSyncPhysicalBottom,
-  shouldSuppressFollowingTailNegativeScrollBy,
-  transferCollapseReservationToPin,
-  transferPinReservationToProtectedCollapse,
-} from './flowChatScrollStability';
-import { activeSessionHistoryProjectionHandoff } from './historyProjectionHandoff';
-import type { Session } from '../../types/flow-chat';
-import type { VirtualItem } from '../../store/modernFlowChatStore';
+import { tailSpacerPxForViewport } from './flowChatTailFollow';
+import { ONE_SHOT_NAVIGATION_HOLD_MS } from './flowChatViewportOwnership';
+import { VirtualMessageList, type VirtualMessageListRef } from './VirtualMessageList';
 
 globalThis.IS_REACT_ACT_ENVIRONMENT = true;
 
-const stateMocks = vi.hoisted(() => ({
-  activeSession: null as Session | null,
-  virtualItems: [] as VirtualItem[],
-  visibleTurnInfo: null as unknown,
+const mocks = vi.hoisted(() => ({
+  items: [] as Array<Record<string, unknown>>,
+  activeSession: null as Record<string, unknown> | null,
+  scrollItemIntoView: vi.fn(),
+  scrollToOffset: vi.fn(),
+  cancelAim: vi.fn(),
   setVisibleTurnInfo: vi.fn(),
-}));
-const virtuosoMocks = vi.hoisted(() => ({
-  renderedRange: null as { start: number; end: number } | null,
-  scrollerScrollTo: vi.fn(),
-  scrollToIndex: vi.fn(),
-  initialTopMostItemIndex: null as unknown,
-  initialTopMostItemIndexHistory: [] as unknown[],
-  increaseViewportBy: null as unknown,
-  rangeChanged: null as (() => void) | null,
-}));
-const flowStoreMocks = vi.hoisted(() => ({
-  hasPendingSessionHistoryCompletion: vi.fn(() => false),
-  hasDeferredSessionHistoryProjection: vi.fn(() => false),
-  revealPreviousSessionHistoryWindow: vi.fn(() => false),
-  releaseSessionHistoryCompletionAfterInitialPaint: vi.fn(() => false),
-}));
-const inputStateMocks = vi.hoisted(() => ({
-  isActive: false,
-  isExpanded: false,
-  inputHeight: 0,
-}));
-const activeSessionStateMocks = vi.hoisted(() => ({
-  isProcessing: false,
-}));
-const flowDiagnosticsMocks = vi.hoisted(() => ({
-  enabled: false,
-  trace: vi.fn(),
-}));
-const resizeObserverMocks = vi.hoisted(() => ({
-  callbacks: [] as Array<() => void>,
-}));
-
-vi.mock('@/infrastructure/diagnostics/flowChatDiagnostics', () => ({
-  flowChatDiagnostics: {
-    isEnabled: () => flowDiagnosticsMocks.enabled,
-    trace: flowDiagnosticsMocks.trace,
-  },
+  enterFollowOutput: vi.fn(),
+  exitFollowOutput: vi.fn(),
+  handleUserScrollIntent: vi.fn(),
+  /**
+   * The two answers to "does follow own the viewport", which the real hook
+   * gives at two different moments: `isFollowingOutput` is a render value, and
+   * `followsNow` is the ref a gesture clears synchronously before it asks.
+   * Keeping both here is what lets a test put them out of step, which is the
+   * state the paging refusal used to read from the wrong side of.
+   */
+  isFollowingOutput: false,
+  followsNow: false,
+  scheduleFollowToLatest: vi.fn(),
+  /**
+   * The register the list built, reached through the hook it hands it to.
+   *
+   * Taking the viewport is what the follow hook does on entry, and the tests
+   * below need the list to face a register in that state — a displacement is
+   * refused by whoever holds a target, and that refusal is a contract with the
+   * holder rather than a dead end.
+   */
+  viewportOwner: null as null | { claim: (owner: string) => boolean },
+  /** False stands in for a Turn the virtualizer can place but the DOM cannot. */
+  renderItemMetadata: true,
 }));
 
-vi.mock('react-i18next', () => ({
-  initReactI18next: {
-    type: '3rdParty',
-    init: vi.fn(),
-  },
-  useTranslation: () => ({
-    t: (key: string) => {
-      const translations: Record<string, string> = {
-        'historyState.preparingOlderHistory': 'Preparing older history...',
-        'historyState.olderHistoryNotReady': 'Older history is not ready yet.',
-      };
-      return translations[key] ?? key;
-    },
-  }),
-}));
+/** Input-stack footer the chat-input mock produces: 140 + 4 + 24. */
+const BOTTOM_INSET = 168;
 
-vi.mock('react-virtuoso', () => ({
-  Virtuoso: React.forwardRef((props: any, ref) => {
-    const scrollerRef = React.useRef<HTMLDivElement | null>(null);
-    const [, rerender] = React.useReducer((value: number) => value + 1, 0);
-    virtuosoMocks.initialTopMostItemIndex = props.initialTopMostItemIndex;
-    virtuosoMocks.initialTopMostItemIndexHistory.push(props.initialTopMostItemIndex);
-    virtuosoMocks.increaseViewportBy = props.increaseViewportBy;
-    virtuosoMocks.rangeChanged = props.rangeChanged ?? null;
-    React.useImperativeHandle(ref, () => ({
-      scrollTo: vi.fn(),
-      scrollToIndex: vi.fn((options: { index: number }) => {
-        virtuosoMocks.scrollToIndex(options);
-        const localIndex = Math.max(0, options.index);
-        virtuosoMocks.renderedRange = {
-          start: localIndex,
-          end: Math.min(props.data?.length ?? 0, localIndex + 4),
-        };
-        rerender();
-      }),
-    }));
-
-    React.useLayoutEffect(() => {
-      if (!scrollerRef.current) {
-        return;
-      }
+/**
+ * jsdom has no layout engine, so both halves of the navigation clamp have to be
+ * supplied: the scroller's own box, and where a user message sits inside it.
+ */
+function fakeLayout(options: {
+  clientHeight: number;
+  /** A function where the range has to grow, as it does when history arrives. */
+  scrollHeight: number | (() => number);
+  turnTopFromScrollerTop: number;
+}) {
+  const readScrollHeight = typeof options.scrollHeight === 'function'
+    ? options.scrollHeight
+    : () => options.scrollHeight as number;
+  const originals = (['clientHeight', 'scrollHeight'] as const).map(name => {
+    const descriptor = Object.getOwnPropertyDescriptor(HTMLElement.prototype, name);
+    Object.defineProperty(HTMLElement.prototype, name, {
+      configurable: true,
+      get: () => (name === 'clientHeight' ? options.clientHeight : readScrollHeight()),
+    });
+    return [name, descriptor] as const;
+  });
+  const originalRect = HTMLElement.prototype.getBoundingClientRect;
+  HTMLElement.prototype.getBoundingClientRect = function getRect(this: HTMLElement) {
+    const top = this.classList.contains('virtual-item-wrapper')
+      ? options.turnTopFromScrollerTop
+      : 0;
+    return { ...new DOMRect(0, top, 0, 40), top, bottom: top + 40 } as DOMRect;
+  };
 
-      if (typeof scrollerRef.current.scrollTo !== 'function') {
-        Object.defineProperty(scrollerRef.current, 'scrollTo', {
-          configurable: true,
-          writable: true,
-          value: (options?: ScrollToOptions) => {
-            virtuosoMocks.scrollerScrollTo(options);
-            if (typeof options?.top === 'number') {
-              scrollerRef.current!.scrollTop = options.top;
-            }
-          },
-        });
+  return () => {
+    HTMLElement.prototype.getBoundingClientRect = originalRect;
+    originals.forEach(([name, descriptor]) => {
+      if (descriptor) {
+        Object.defineProperty(HTMLElement.prototype, name, descriptor);
+      } else {
+        delete (HTMLElement.prototype as unknown as Record<string, unknown>)[name];
       }
+    });
+  };
+}
 
-      props.scrollerRef?.(scrollerRef.current);
-      return () => {
-        props.scrollerRef?.(null);
+/*
+ * The virtualizer is mocked at FlowChat's own seam rather than at the library.
+ * These tests are about which scroll the list decides to ask for, and the seam
+ * is where that decision is expressed; the library's own behaviour belongs to
+ * the library. Every item is rendered, which is what a list shorter than the
+ * viewport would do anyway.
+ */
+vi.mock('./useFlowChatVirtualizer', async () => {
+  // The visible range is real geometry, and the paging rule reads it. Faking it
+  // would leave the rule tested against an answer no viewport can produce.
+  const actual = await vi.importActual<typeof import('./useFlowChatVirtualizer')>(
+    './useFlowChatVirtualizer',
+  );
+  return {
+    ...actual,
+    useFlowChatVirtualizer: (options: {
+      items: Array<Record<string, unknown>>;
+      getItemKey: (item: Record<string, unknown>) => string;
+      scrollerRef: { current: HTMLElement | null };
+    }) => {
+      const rows = options.items.map((item, index) => ({
+        index,
+        key: options.getItemKey(item),
+        startPx: index * 40,
+        endPx: index * 40 + 40,
+      }));
+      return {
+        rows,
+        paddingTopPx: 0,
+        paddingBottomPx: 0,
+        measureRowElement: () => {},
+        getItemBounds: (index: number) => (
+          index >= 0 && index < rows.length
+            ? { startPx: index * 40, endPx: index * 40 + 40 }
+            : null
+        ),
+        // The real one flushes the DOM's heights into the library's cache;
+        // these rows are placed by arithmetic, so there is nothing to flush.
+        measureRenderedItems: () => {},
+        getVisibleItemRange: () => {
+          const scroller = options.scrollerRef.current;
+          return scroller
+            ? actual.visibleRowRange(rows, scroller.scrollTop, scroller.clientHeight)
+            : null;
+        },
+        scrollItemIntoView: mocks.scrollItemIntoView,
+        scrollToOffset: mocks.scrollToOffset,
+        cancelAim: mocks.cancelAim,
       };
-    }, [props]);
-
-    React.useEffect(() => {
-      if (props.data?.[0]?.turnId === 'turn-a') {
-        props.atBottomStateChange?.(false);
-      }
-    }, [props]);
-
-    return (
-      <div
-        ref={scrollerRef}
-        data-testid="virtuoso"
-        data-virtuoso-scroller="true"
-        data-session-id={stateMocks.activeSession?.sessionId ?? ''}
-        tabIndex={0}
-      >
-        {props.components?.Header ? <props.components.Header context={props.context} /> : null}
-        {props.data
-          ?.map((item: VirtualItem, index: number) => ({ item, index }))
-          .filter(({ index }: { index: number }) => {
-            const range = virtuosoMocks.renderedRange;
-            return !range || (index >= range.start && index < range.end);
-          })
-          .map(({ item, index }: { item: VirtualItem; index: number }) => (
-            <div
-              key={`${item.type}:${item.turnId}`}
-              className="virtual-item-wrapper"
-              data-turn-id={item.turnId}
-              data-virtual-index={index}
-              data-item-type={item.type}
-            >
-              {item.type === 'user-message' ? item.data.content : item.turnId}
-            </div>
-          ))}
-        {props.components?.Footer ? <props.components.Footer context={props.context} /> : null}
-      </div>
-    );
-  }),
-}));
+    },
+  };
+});
 
 vi.mock('../../store/modernFlowChatStore', () => {
-  const useModernFlowChatStore = (selector: (state: any) => unknown) => selector({
-    visibleTurnInfo: stateMocks.visibleTurnInfo,
-  });
-  useModernFlowChatStore.getState = () => ({
-    visibleTurnInfo: stateMocks.visibleTurnInfo,
-    setVisibleTurnInfo: stateMocks.setVisibleTurnInfo,
-  });
-
+  const useModernFlowChatStore = Object.assign(
+    (selector: (state: Record<string, unknown>) => unknown) => selector({ visibleTurnInfo: null }),
+    { getState: () => ({ setVisibleTurnInfo: mocks.setVisibleTurnInfo }) },
+  );
   return {
-    useActiveSession: () => stateMocks.activeSession,
-    useVirtualItems: () => stateMocks.virtualItems,
+    useVirtualItems: () => mocks.items,
+    useActiveSession: () => mocks.activeSession,
     useModernFlowChatStore,
   };
 });
 
 vi.mock('../../hooks/useActiveSessionState', () => ({
-  useActiveSessionState: () => ({
-    isProcessing: activeSessionStateMocks.isProcessing,
-    processingPhase: null,
-  }),
+  useActiveSessionState: () => ({ isProcessing: false }),
 }));
 
 vi.mock('../../store/chatInputStateStore', () => ({
-  useChatInputState: (selector: (state: any) => unknown) => selector(inputStateMocks),
+  useChatInputState: (selector: (state: Record<string, unknown>) => unknown) => selector({
+    isActive: false,
+    isExpanded: false,
+    inputHeight: 140,
+  }),
 }));
 
-vi.mock('../../store/FlowChatStore', () => ({
-  flowChatStore: {
-    getState: () => ({
-      sessions: new Map(stateMocks.activeSession ? [[stateMocks.activeSession.sessionId, stateMocks.activeSession]] : []),
-    }),
-    hasPendingSessionHistoryCompletion: flowStoreMocks.hasPendingSessionHistoryCompletion,
-    hasDeferredSessionHistoryProjection: flowStoreMocks.hasDeferredSessionHistoryProjection,
-    revealPreviousSessionHistoryWindow: flowStoreMocks.revealPreviousSessionHistoryWindow,
-    releaseSessionHistoryCompletionAfterInitialPaint: flowStoreMocks.releaseSessionHistoryCompletionAfterInitialPaint,
+vi.mock('./useFlowChatFollowOutput', () => ({
+  useFlowChatFollowOutput: (options: {
+    viewportOwner: { claim: (owner: string) => boolean };
+  }) => {
+    mocks.viewportOwner = options.viewportOwner;
+    return {
+      isFollowingOutput: mocks.isFollowingOutput,
+      enterFollowOutput: mocks.enterFollowOutput,
+      exitFollowOutput: mocks.exitFollowOutput,
+      scheduleFollowToLatest: mocks.scheduleFollowToLatest,
+      isFollowingOutputNow: () => mocks.followsNow,
+      // Nothing streams here, so the frame loop is never correcting: the band is
+      // judged on the viewport itself, exactly as it is for a resting transcript.
+      isFollowCorrectingViewport: () => false,
+      handleUserScrollIntent: () => {
+        // What the real one does first: release, synchronously.
+        mocks.followsNow = false;
+        mocks.handleUserScrollIntent();
+      },
+      handleTurnsRolledBack: vi.fn(),
+      handleScroll: vi.fn(),
+      handleViewportResize: vi.fn(),
+      // Follow owns nothing here, which is what the real hook returns when
+      // `isFollowingOutput` is false.
+      getFollowTargetScrollTop: () => null,
+    };
   },
 }));
 
-vi.mock('@/shared/utils/startupTrace', () => ({
-  startupTrace: { markPhase: vi.fn() },
-}));
-
 vi.mock('./VirtualItemRenderer', () => ({
-  VirtualItemRenderer: ({ item, index }: { item: VirtualItem; index: number }) => (
-    <div className="virtual-item-wrapper" data-turn-id={item.turnId} data-virtual-index={index} data-item-type={item.type}>
-      {item.turnId}
+  VirtualItemRenderer: ({ item, index, measureRef }: {
+    item: any;
+    index: number;
+    measureRef?: (element: HTMLElement | null) => void;
+  }) => (
+    <div
+      ref={measureRef}
+      className="virtual-item-wrapper"
+      data-item-type={mocks.renderItemMetadata ? item.type : undefined}
+      data-turn-id={item.turnId}
+      data-virtual-index={index}
+    >
+      {item.data?.content ?? item.turnId}
     </div>
   ),
 }));
 
-vi.mock('../ScrollToLatestBar', () => ({
-  ScrollToLatestBar: ({ visible, onClick }: { visible: boolean; onClick?: () => void }) => (
-    <button type="button" data-testid="scroll-to-latest" data-visible={visible ? 'true' : 'false'} onClick={onClick} />
-  ),
-}));
-
-vi.mock('../ScrollToTurnHeaderButton', () => ({
-  ScrollToTurnHeaderButton: () => null,
-}));
-
 vi.mock('../../hooks/useScrollToTurnHeader', () => ({
-  useScrollToTurnHeader: () => ({
-    shouldShowButton: false,
-    handleClick: vi.fn(),
-  }),
-}));
-
-vi.mock('../../hooks/useVisibleTaskInfo', () => ({
-  useVisibleTaskInfo: () => ({
-    visibleTaskInfo: null,
-    scrollToTask: vi.fn(),
-  }),
+  useScrollToTurnHeader: () => ({ shouldShowButton: false, handleClick: vi.fn() }),
 }));
 
-vi.mock('../StickyTaskIndicator', () => ({
-  StickyTaskIndicator: () => null,
-}));
-
-function createSession(sessionId: string, turnId: string, overrides: Partial<Session> = {}): Session {
-  return {
-    sessionId,
-    title: sessionId,
-    dialogTurns: [{
-      id: turnId,
-      sessionId,
-      userMessage: { id: `user-${turnId}`, content: turnId, timestamp: 1 },
-      modelRounds: [],
-      status: 'completed',
-      startTime: 1,
-    }],
-    status: 'idle',
-    config: { agentType: 'agentic' },
-    createdAt: 1,
-    lastActiveAt: 1,
-    error: null,
-    isHistorical: false,
-    todos: [],
-    mode: 'agentic',
-    sessionKind: 'normal',
-    ...overrides,
-  } as Session;
-}
+vi.mock('./RuntimeStatusSlot', () => ({ RuntimeStatusSlot: () => <div data-runtime-status /> }));
+vi.mock('../ScrollToLatestBar', () => ({ ScrollToLatestBar: () => null }));
+vi.mock('../ScrollToTurnHeaderButton', () => ({ ScrollToTurnHeaderButton: () => null }));
 
-function createItem(turnId: string): VirtualItem {
+function userMessage(turnId: string, id: string, content: string) {
   return {
     type: 'user-message',
     turnId,
-    data: {
-      id: `user-${turnId}`,
-      content: turnId,
-      timestamp: 1,
-    },
-  } as VirtualItem;
-}
-
-function createModelItem(turnId: string): VirtualItem {
-  return {
-    type: 'model-round',
-    turnId,
-    isLastRound: true,
-    isTurnComplete: true,
-    data: {
-      id: `round-${turnId}`,
-      status: 'completed',
-      isStreaming: false,
-      items: [{
-        id: `text-${turnId}`,
-        type: 'text',
-        content: 'x'.repeat(2_000),
-        status: 'completed',
-        timestamp: 1,
-      }],
-    },
-  } as VirtualItem;
-}
-
-function createSessionWithTurns(sessionId: string, turnIds: string[], overrides: Partial<Session> = {}): Session {
-  return createSession(sessionId, turnIds[0] ?? 'turn-a', {
-    dialogTurns: turnIds.map((turnId, index) => ({
-      id: turnId,
-      sessionId,
-      userMessage: { id: `user-${turnId}`, content: turnId, timestamp: index + 1 },
-      modelRounds: [],
-      status: 'completed',
-      startTime: index + 1,
-    })),
-    ...overrides,
-  });
-}
-
-function setScrollerGeometry(scroller: HTMLElement, metrics: {
-  scrollHeight: number;
-  clientHeight: number;
-  scrollTop?: number;
-}): void {
-  Object.defineProperty(scroller, 'scrollHeight', {
-    configurable: true,
-    value: metrics.scrollHeight,
-  });
-  Object.defineProperty(scroller, 'clientHeight', {
-    configurable: true,
-    value: metrics.clientHeight,
-  });
-  if (metrics.scrollTop !== undefined) {
-    scroller.scrollTop = metrics.scrollTop;
-  }
-}
-
-function createRect(overrides: Partial<DOMRect>): DOMRect {
-  const left = overrides.left ?? 0;
-  const top = overrides.top ?? 0;
-  const width = overrides.width ?? 0;
-  const height = overrides.height ?? 0;
-  const right = overrides.right ?? left + width;
-  const bottom = overrides.bottom ?? top + height;
-
-  return {
-    x: overrides.x ?? left,
-    y: overrides.y ?? top,
-    left,
-    top,
-    width,
-    height,
-    right,
-    bottom,
-    toJSON: () => ({}),
-  } as DOMRect;
+    data: { id, content },
+  };
 }
 
-describe('VirtualMessageList session boundary', () => {
+describe('VirtualMessageList natural scroll contract', () => {
   let container: HTMLDivElement;
   let root: Root;
-  let rafCallbacks: FrameRequestCallback[];
-
-  const flushAnimationFrame = () => {
-    const callbacks = rafCallbacks;
-    rafCallbacks = [];
-    act(() => {
-      callbacks.forEach(callback => callback(performance.now()));
-    });
-  };
+  let animationFrames: Map<number, FrameRequestCallback>;
+  let nextAnimationFrameId: number;
+
+  /**
+   * Run the opening reveal to its end, which is what mounting a transcript
+   * really costs.
+   *
+   * The reveal holds the transcript hidden while it is placed, and the paging
+   * rule refuses a boundary derived from a viewport still being placed — so a
+   * test that asserts what the list asks for on mount has to get past it, the
+   * same way half a second of animation frames does in the app. Frames are a
+   * manual queue rather than jsdom's timer-backed ones so that draining them is
+   * a step in the test rather than a wait.
+   */
+  async function settleOpenReveal() {
+    // The reveal's own cap is 40 frames; a few more cover the commits its
+    // settling schedules.
+    for (let generation = 0; generation < 48; generation += 1) {
+      const pending = [...animationFrames.values()];
+      animationFrames.clear();
+      if (pending.length === 0) return;
+      await act(async () => {
+        pending.forEach(frame => frame(16));
+        await Promise.resolve();
+        await Promise.resolve();
+      });
+    }
+  }
 
   beforeEach(() => {
-    rafCallbacks = [];
-    vi.stubGlobal('requestAnimationFrame', vi.fn((callback: FrameRequestCallback) => {
-      rafCallbacks.push(callback);
-      return rafCallbacks.length;
-    }));
-    vi.stubGlobal('cancelAnimationFrame', vi.fn());
-    vi.stubGlobal('ResizeObserver', class {
-      constructor(callback: ResizeObserverCallback) {
-        resizeObserverMocks.callbacks.push(() => {
-          callback([], this as unknown as ResizeObserver);
-        });
-      }
-      observe = vi.fn();
-      unobserve = vi.fn();
-      disconnect = vi.fn();
-    });
     container = document.createElement('div');
     document.body.appendChild(container);
     root = createRoot(container);
-    stateMocks.visibleTurnInfo = null;
-    stateMocks.setVisibleTurnInfo.mockReset();
-    virtuosoMocks.renderedRange = null;
-    virtuosoMocks.scrollerScrollTo.mockReset();
-    virtuosoMocks.scrollToIndex.mockReset();
-    virtuosoMocks.initialTopMostItemIndex = null;
-    virtuosoMocks.initialTopMostItemIndexHistory = [];
-    virtuosoMocks.increaseViewportBy = null;
-    virtuosoMocks.rangeChanged = null;
-    flowStoreMocks.hasPendingSessionHistoryCompletion.mockReset();
-    flowStoreMocks.hasPendingSessionHistoryCompletion.mockReturnValue(false);
-    flowStoreMocks.hasDeferredSessionHistoryProjection.mockReset();
-    flowStoreMocks.hasDeferredSessionHistoryProjection.mockReturnValue(false);
-    flowStoreMocks.revealPreviousSessionHistoryWindow.mockReset();
-    flowStoreMocks.revealPreviousSessionHistoryWindow.mockReturnValue(false);
-    flowStoreMocks.releaseSessionHistoryCompletionAfterInitialPaint.mockReset();
-    flowStoreMocks.releaseSessionHistoryCompletionAfterInitialPaint.mockReturnValue(false);
-    inputStateMocks.isActive = false;
-    inputStateMocks.isExpanded = false;
-    inputStateMocks.inputHeight = 0;
-    activeSessionStateMocks.isProcessing = false;
-    flowDiagnosticsMocks.enabled = false;
-    flowDiagnosticsMocks.trace.mockReset();
-    resizeObserverMocks.callbacks = [];
-  });
-
-  it('keeps Virtuoso absolute indexes stable across prepend and remote-side trimming', () => {
-    const previous = ['turn-3', 'turn-4', 'turn-5', 'turn-6'].map(createItem);
-    const prepended = ['turn-1', 'turn-2', 'turn-3', 'turn-4', 'turn-5'].map(createItem);
-    const trimmed = ['turn-4', 'turn-5', 'turn-6', 'turn-7'].map(createItem);
-
-    const getStableKey = (item: VirtualItem) => `${item.type}:${item.turnId}`;
-    expect(getLeadingVirtualItemIndexDelta(previous, prepended, getStableKey)).toBe(-2);
-    expect(getLeadingVirtualItemIndexDelta(previous, trimmed, getStableKey)).toBe(1);
+    animationFrames = new Map();
+    nextAnimationFrameId = 0;
+    mocks.items = [
+      userMessage('turn-1', 'message-1', 'First'),
+      userMessage('turn-2', 'message-2', 'Second'),
+    ];
+    mocks.activeSession = {
+      sessionId: 'session-1',
+      dialogTurns: [],
+    };
+    mocks.isFollowingOutput = false;
+    mocks.followsNow = false;
+    mocks.scrollItemIntoView.mockReset();
+    mocks.scrollToOffset.mockReset();
+    mocks.cancelAim.mockReset();
+    mocks.enterFollowOutput.mockReset();
+    mocks.exitFollowOutput.mockReset();
+    mocks.handleUserScrollIntent.mockReset();
+    mocks.scheduleFollowToLatest.mockReset();
+    mocks.viewportOwner = null;
+    mocks.setVisibleTurnInfo.mockReset();
+    mocks.renderItemMetadata = true;
+    vi.stubGlobal('ResizeObserver', class {
+      observe() {}
+      disconnect() {}
+    });
+    vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => {
+      nextAnimationFrameId += 1;
+      animationFrames.set(nextAnimationFrameId, callback);
+      return nextAnimationFrameId;
+    });
+    vi.stubGlobal('cancelAnimationFrame', (id: number) => {
+      animationFrames.delete(id);
+    });
   });
 
   afterEach(() => {
@@ -447,3437 +304,654 @@ describe('VirtualMessageList session boundary', () => {
     vi.unstubAllGlobals();
   });
 
-  it('keeps the Virtuoso footer mounted across parent rerenders', () => {
-    stateMocks.activeSession = createSession('session-a', 'turn-a');
-    stateMocks.virtualItems = [createItem('turn-a')];
-
-    act(() => {
-      root.render(<VirtualMessageList />);
-    });
-    const firstFooter = container.querySelector('.message-list-footer');
-    expect(firstFooter).not.toBeNull();
-    if (!(firstFooter instanceof HTMLElement)) {
-      return;
-    }
-    firstFooter.style.height = '900px';
-    firstFooter.style.minHeight = '900px';
-
-    act(() => {
-      root.render(<VirtualMessageList />);
-    });
-
-    expect(container.querySelector('.message-list-footer')).toBe(firstFooter);
-    expect(firstFooter.style.height).toBe('900px');
-    expect(firstFooter.style.minHeight).toBe('900px');
+  it('renders only the current input layout inset in the Footer', () => {
+    act(() => root.render(<VirtualMessageList />));
+    const footer = container.querySelector<HTMLElement>('.message-list-footer');
+    expect(footer?.style.height).toBe('168px');
+    expect(footer?.style.minHeight).toBe('168px');
   });
 
-  it('rebases retained viewport geometry without converting inactive zero size into footer space', () => {
-    stateMocks.activeSession = createSessionWithTurns('session-a', ['turn-a', 'turn-b']);
-    stateMocks.virtualItems = ['turn-a', 'turn-b'].flatMap(turnId => [
-      createItem(turnId),
-      createModelItem(turnId),
-    ]);
-
-    act(() => {
-      root.render(<VirtualMessageList isViewportActive />);
+  it('reserves a tail spacer sized from the viewport and nothing else', () => {
+    // The session opens on the end of *real content*, which is above this
+    // reservation. Nothing aligns to the last item any more: the end of the
+    // scroll range is reserved blank, and opening there is opening on nothing.
+    const originalClientHeight = Object.getOwnPropertyDescriptor(
+      HTMLElement.prototype,
+      'clientHeight',
+    );
+    Object.defineProperty(HTMLElement.prototype, 'clientHeight', {
+      configurable: true,
+      get: () => 600,
     });
 
-    const scroller = container.querySelector<HTMLElement>('[data-virtuoso-scroller="true"]');
-    const footer = container.querySelector<HTMLElement>('.message-list-footer');
-    expect(scroller).not.toBeNull();
-    expect(footer).not.toBeNull();
-    if (!scroller || !footer) {
-      return;
+    try {
+      act(() => root.render(<VirtualMessageList />));
+
+      const expectedSpacerPx = tailSpacerPxForViewport(600, BOTTOM_INSET);
+      expect(expectedSpacerPx).toBeLessThan(600);
+      const spacer = container.querySelector<HTMLElement>('.message-list-tail-spacer');
+      expect(spacer?.style.height).toBe(`${expectedSpacerPx}px`);
+      // The input-stack footer stays a separate reservation. It feeds the
+      // spacer's size, but the two are never folded into one number.
+      expect(container.querySelector<HTMLElement>('.message-list-footer')?.style.height)
+        .toBe('168px');
+    } finally {
+      if (originalClientHeight) {
+        Object.defineProperty(HTMLElement.prototype, 'clientHeight', originalClientHeight);
+      } else {
+        delete (HTMLElement.prototype as unknown as Record<string, unknown>).clientHeight;
+      }
     }
+  });
 
-    let hidden = false;
-    let naturalContentHeight = 36_000;
-    let scrollTop = 34_500;
-    Object.defineProperties(scroller, {
-      clientHeight: {
-        configurable: true,
-        get: () => hidden ? 0 : 1_000,
-      },
-      scrollHeight: {
-        configurable: true,
-        get: () => hidden
-          ? 0
-          : naturalContentHeight + (Number.parseFloat(footer.style.height) || 0),
-      },
-      scrollTop: {
-        configurable: true,
-        get: () => scrollTop,
-        set: (value: number) => {
-          scrollTop = value;
-        },
-      },
-    });
-    vi.spyOn(scroller, 'getBoundingClientRect').mockImplementation(() => createRect({
-      top: 0,
-      bottom: hidden ? 0 : 1_000,
-      height: hidden ? 0 : 1_000,
-    }));
-
-    act(() => {
-      root.render(<VirtualMessageList isViewportActive />);
-    });
-    const baselineFooterHeight = Number.parseFloat(footer.style.height);
-
+  it('navigates a Turn with best-effort start alignment and no range reservation', () => {
+    const listRef = React.createRef<VirtualMessageListRef>();
+    act(() => root.render(<VirtualMessageList ref={listRef} />));
+    let accepted = false;
     act(() => {
-      root.render(<VirtualMessageList isViewportActive={false} />);
+      accepted = listRef.current?.navigateToTurn('turn-2', { behavior: 'auto' }) ?? false;
     });
-    hidden = true;
-    scrollTop = 0;
-    act(() => {
-      resizeObserverMocks.callbacks.at(-1)?.();
+    expect(accepted).toBe(true);
+    expect(mocks.exitFollowOutput).toHaveBeenCalledWith('scroll-to-turn');
+    // The breathing gap above a top-aligned Turn is the virtualizer's
+    // `scrollPaddingStart`, so an aim re-taken while items measure keeps it.
+    expect(mocks.scrollItemIntoView).toHaveBeenCalledWith(1, {
+      align: 'start',
+      behavior: 'auto',
+      // The aim carries its owner, so the re-aims it produces are still the
+      // navigation's and are refused for anything that outranks it.
+      owner: 'one-shot-navigation',
+      holdForMs: ONE_SHOT_NAVIGATION_HOLD_MS,
     });
-    for (let frame = 0; frame < 4; frame += 1) {
-      flushAnimationFrame();
-    }
-
-    expect(Number.parseFloat(footer.style.height)).toBe(baselineFooterHeight);
+    expect(container.querySelector('.message-list-footer')?.getAttribute('style')).toContain('168px');
+  });
 
-    naturalContentHeight += 600;
-    hidden = false;
-    act(() => {
-      root.render(<VirtualMessageList isViewportActive />);
+  it('top-aligns a Turn that still has a transcript below it', () => {
+    const listRef = React.createRef<VirtualMessageListRef>();
+    // Content end at 3000 - 392 - 600 = 2008, well below the Turn's top at 492.
+    const restoreLayout = fakeLayout({
+      clientHeight: 600,
+      scrollHeight: 3000,
+      turnTopFromScrollerTop: 500,
     });
-    for (let frame = 0; frame < 4; frame += 1) {
-      flushAnimationFrame();
+    try {
+      act(() => root.render(<VirtualMessageList ref={listRef} />));
+      act(() => { listRef.current?.navigateToTurn('turn-2', { behavior: 'smooth' }); });
+
+      expect(mocks.scrollItemIntoView).toHaveBeenCalledTimes(1);
+      expect(mocks.scrollItemIntoView).toHaveBeenCalledWith(1, {
+        align: 'start',
+        // A resolvable Turn is clamped before anything moves, so the requested
+        // animation survives.
+        behavior: 'smooth',
+        owner: 'one-shot-navigation',
+        holdForMs: ONE_SHOT_NAVIGATION_HOLD_MS,
+      });
+    } finally {
+      restoreLayout();
     }
-
-    expect(Number.parseFloat(footer.style.height)).toBeLessThanOrEqual(
-      baselineFooterHeight + 1,
-    );
-    expect(scroller.scrollTop).toBeGreaterThan(0);
-    expect(scroller.scrollHeight).toBeLessThan(40_000);
   });
 
-  it('does not convert Virtuoso estimate convergence into anonymous footer space', () => {
-    stateMocks.activeSession = createSessionWithTurns('session-a', ['turn-a', 'turn-b']);
-    stateMocks.virtualItems = ['turn-a', 'turn-b'].flatMap(turnId => [
-      createItem(turnId),
-      createModelItem(turnId),
-    ]);
-
-    act(() => {
-      root.render(<VirtualMessageList isViewportActive />);
+  it('stops a short tail Turn at the content end rather than in the blank', () => {
+    const listRef = React.createRef<VirtualMessageListRef>();
+    // Content end at 1000 - 392 - 600 = 8; top-aligning would mean 492, which
+    // is a screen of reserved blank nothing is going to fill.
+    const restoreLayout = fakeLayout({
+      clientHeight: 600,
+      scrollHeight: 1000,
+      turnTopFromScrollerTop: 500,
     });
-
-    const scroller = container.querySelector<HTMLElement>('[data-virtuoso-scroller="true"]');
-    const footer = container.querySelector<HTMLElement>('.message-list-footer');
-    expect(scroller).not.toBeNull();
-    expect(footer).not.toBeNull();
-    if (!scroller || !footer) {
-      return;
+    try {
+      act(() => root.render(<VirtualMessageList ref={listRef} />));
+      act(() => { listRef.current?.navigateToTurn('turn-2', { behavior: 'smooth' }); });
+
+      // Aimed at the end of real content, read off live geometry — not at the
+      // last item, whose end is the bottom of the reserved blank.
+      expect(mocks.scrollItemIntoView).not.toHaveBeenCalled();
+      expect(mocks.scrollToOffset).toHaveBeenCalledTimes(1);
+      expect(mocks.scrollToOffset).toHaveBeenCalledWith(
+        1000 - tailSpacerPxForViewport(600, BOTTOM_INSET) - 600,
+        {
+          behavior: 'smooth',
+          owner: 'one-shot-navigation',
+          // The clamp is still the navigation, so it states the same window.
+          // Without one it would hold the viewport for the rest of the session.
+          holdForMs: ONE_SHOT_NAVIGATION_HOLD_MS,
+        },
+      );
+    } finally {
+      restoreLayout();
     }
+  });
 
-    let naturalContentHeight = 14_457;
-    let scrollTop = 13_561.3330078125;
-    Object.defineProperties(scroller, {
-      clientHeight: { configurable: true, get: () => 1_020 },
-      scrollHeight: {
-        configurable: true,
-        get: () => naturalContentHeight + (Number.parseFloat(footer.style.height) || 0),
-      },
-      scrollTop: {
+  it('reads an unrendered Turn back from the virtualizer, and corrects through it', () => {
+    const listRef = React.createRef<VirtualMessageListRef>();
+    const restoreLayout = fakeLayout({
+      clientHeight: 600,
+      scrollHeight: 1000,
+      turnTopFromScrollerTop: 500,
+    });
+    try {
+      mocks.renderItemMetadata = false;
+      act(() => root.render(<VirtualMessageList ref={listRef} />));
+      const scroller = container.querySelector<HTMLElement>('[data-flowchat-scroller]')!;
+      Object.defineProperty(scroller, 'scrollTop', {
         configurable: true,
-        get: () => scrollTop,
-        set: (value: number) => {
-          scrollTop = value;
+        writable: true,
+        value: 0,
+      });
+      // Only the virtualizer knows where the Turn is; it lands the viewport in
+      // the reserved blank.
+      mocks.scrollItemIntoView.mockImplementation(() => { scroller.scrollTop = 900; });
+
+      act(() => { listRef.current?.navigateToTurn('turn-2', { behavior: 'smooth' }); });
+
+      // Placed instantly, because an animation would not have arrived yet and
+      // there would be nothing to read back.
+      expect(mocks.scrollItemIntoView).toHaveBeenCalledTimes(1);
+      expect(mocks.scrollItemIntoView).toHaveBeenCalledWith(1, {
+        align: 'start',
+        owner: 'one-shot-navigation',
+        holdForMs: ONE_SHOT_NAVIGATION_HOLD_MS,
+      });
+      // Corrected through the virtualizer, not the scroller: a direct write
+      // would leave the first call's re-aim pending, and it aims at the top.
+      expect(mocks.scrollToOffset).toHaveBeenCalledWith(
+        1000 - tailSpacerPxForViewport(600, BOTTOM_INSET) - 600,
+        {
+          behavior: 'auto',
+          owner: 'one-shot-navigation',
+          holdForMs: ONE_SHOT_NAVIGATION_HOLD_MS,
         },
-      },
-    });
-    vi.spyOn(scroller, 'getBoundingClientRect').mockReturnValue(createRect({
-      top: 0,
-      bottom: 1_020,
-      height: 1_020,
-    }));
-
-    act(() => {
-      root.render(<VirtualMessageList isViewportActive />);
-      resizeObserverMocks.callbacks.at(-1)?.();
-    });
-    for (let frame = 0; frame < 4; frame += 1) {
-      flushAnimationFrame();
+      );
+    } finally {
+      restoreLayout();
     }
-    const baselineFooterHeight = Number.parseFloat(footer.style.height);
+  });
+
+  describe('scrollbar drags release the viewport', () => {
+    // Content box ends at 0 + 1384; the gutter runs from there to 1394.
+    const CONTENT_BOX_WIDTH = 1384;
 
-    const convergenceSteps = [10_902, 7_529, 4_601, 3_693];
-    for (const nextNaturalContentHeight of convergenceSteps) {
-      naturalContentHeight = nextNaturalContentHeight;
-      scrollTop = Math.max(0, scroller.scrollHeight - scroller.clientHeight);
+    function pressAt(clientX: number) {
+      const scroller = container.querySelector<HTMLElement>('[data-flowchat-scroller]')!;
+      Object.defineProperty(scroller, 'clientWidth', {
+        configurable: true,
+        value: CONTENT_BOX_WIDTH,
+      });
       act(() => {
-        resizeObserverMocks.callbacks.at(-1)?.();
+        // jsdom has no PointerEvent; only `clientX` is read.
+        scroller.dispatchEvent(new MouseEvent('pointerdown', { clientX, bubbles: true }));
+        scroller.dispatchEvent(new Event('scroll'));
       });
-      for (let frame = 0; frame < 4; frame += 1) {
-        flushAnimationFrame();
-      }
     }
 
-    expect(Number.parseFloat(footer.style.height)).toBeCloseTo(baselineFooterHeight, 2);
-    expect(scroller.scrollHeight).toBeLessThan(4_000);
-  });
+    it('treats a scroll under a scrollbar press as intent', () => {
+      act(() => root.render(<VirtualMessageList />));
+      pressAt(CONTENT_BOX_WIDTH + 6);
+      expect(mocks.handleUserScrollIntent).toHaveBeenCalled();
+    });
 
-  it('reconciles a stream that ends while its viewport is inactive after reactivation', () => {
-    flowDiagnosticsMocks.enabled = true;
-    const listRef = React.createRef<VirtualMessageListRef>();
-    const session = createSession('session-a', 'turn-a');
-    session.dialogTurns[0].status = 'processing';
-    session.dialogTurns[0].modelRounds = [{
-      id: 'round-turn-a',
-      status: 'streaming',
-      isStreaming: true,
-      items: [],
-      startTime: 1,
-    } as typeof session.dialogTurns[number]['modelRounds'][number]];
-    stateMocks.activeSession = session;
-    stateMocks.virtualItems = [createItem('turn-a'), createModelItem('turn-a')];
+    it('leaves a scroll under a press on the transcript alone', () => {
+      // Layout growth and virtualizer remeasurement emit scroll events too, so
+      // the press is what qualifies one — not the event itself.
+      act(() => root.render(<VirtualMessageList />));
+      pressAt(CONTENT_BOX_WIDTH - 200);
+      expect(mocks.handleUserScrollIntent).not.toHaveBeenCalled();
+    });
 
-    act(() => {
-      root.render(<VirtualMessageList ref={listRef} isViewportActive />);
+    it('gives up an aim still in flight, which the claim alone cannot reach', () => {
+      /*
+       * The register refuses the re-aim's writes only while the gesture's hold
+       * is live — 200ms after the last notch, against a five-second re-aim —
+       * and the library never learns it was refused. Measured: a navigation
+       * placed at 5358, the reader took over 6ms later, and the re-aim asked
+       * for 7784 12ms after that.
+       */
+      act(() => root.render(<VirtualMessageList />));
+      pressAt(CONTENT_BOX_WIDTH + 6);
+      expect(mocks.cancelAim).toHaveBeenCalled();
     });
 
-    const scroller = container.querySelector<HTMLElement>('[data-virtuoso-scroller="true"]');
-    const footer = container.querySelector<HTMLElement>('.message-list-footer');
-    const target = container.querySelector<HTMLElement>(
-      '[data-turn-id="turn-a"][data-item-type="user-message"]',
-    );
-    expect(scroller).not.toBeNull();
-    expect(footer).not.toBeNull();
-    expect(target).not.toBeNull();
-    if (!scroller || !footer || !target) {
-      return;
+    it('disarms on release, so a later scroll is not intent', () => {
+      act(() => root.render(<VirtualMessageList />));
+      pressAt(CONTENT_BOX_WIDTH + 6);
+      mocks.handleUserScrollIntent.mockClear();
+
+      const scroller = container.querySelector<HTMLElement>('[data-flowchat-scroller]')!;
+      act(() => {
+        window.dispatchEvent(new MouseEvent('pointerup'));
+        scroller.dispatchEvent(new Event('scroll'));
+      });
+
+      expect(mocks.handleUserScrollIntent).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('history arriving above the viewport', () => {
+    /**
+     * A scroller whose range grows with the transcript, which is what makes the
+     * compensation measurable at all: the reserved height and the real height
+     * disagree while the arrived items are still estimates.
+     */
+    function withGrowingRange(
+      options: { scrollHeightPx: number; growthPx: number; scrollTopPx?: number },
+      run: (scroller: HTMLElement) => void,
+    ) {
+      let scrollHeightPx = options.scrollHeightPx;
+      const restoreLayout = fakeLayout({
+        clientHeight: 600,
+        scrollHeight: () => scrollHeightPx,
+        turnTopFromScrollerTop: 500,
+      });
+      try {
+        act(() => root.render(<VirtualMessageList />));
+        const scroller = container.querySelector<HTMLElement>('[data-flowchat-scroller]')!;
+        scroller.scrollTop = options.scrollTopPx ?? 500;
+        scrollHeightPx += options.growthPx;
+        run(scroller);
+      } finally {
+        restoreLayout();
+      }
     }
 
-    let hidden = false;
-    let scrollTop = 200;
-    Object.defineProperties(scroller, {
-      clientHeight: {
-        configurable: true,
-        get: () => hidden ? 0 : 1_000,
-      },
-      scrollHeight: {
-        configurable: true,
-        get: () => hidden
-          ? 0
-          : 1_200 + (Number.parseFloat(footer.style.height) || 0),
-      },
-      scrollTop: {
-        configurable: true,
-        get: () => scrollTop,
-        set: (value: number) => {
-          scrollTop = value;
-        },
-      },
-    });
-    vi.spyOn(scroller, 'getBoundingClientRect').mockImplementation(() => createRect({
-      top: 0,
-      bottom: hidden ? 0 : 1_000,
-      height: hidden ? 0 : 1_000,
-    }));
-    vi.spyOn(target, 'getBoundingClientRect').mockImplementation(() => {
-      const top = hidden ? 0 : 700 - scrollTop;
-      return createRect({ top, bottom: top + 40, height: hidden ? 0 : 40 });
+    function prependOlderTurns(count: number) {
+      mocks.items = [
+        ...Array.from({ length: count }, (_unused, index) => (
+          userMessage(`turn-old-${index}`, `message-old-${index}`, 'Older')
+        )),
+        ...mocks.items,
+      ];
+      act(() => root.render(<VirtualMessageList />));
+    }
+
+    it('moves the viewport by the height that was prepended', () => {
+      // Three 40px items arrived above, so the reader's content is 120px lower
+      // and the viewport follows it. Anything less leaves them looking at
+      // history they never asked to be shown.
+      withGrowingRange({ scrollHeightPx: 3000, growthPx: 120 }, scroller => {
+        prependOlderTurns(3);
+        expect(scroller.scrollTop).toBe(620);
+      });
     });
 
-    act(() => {
-      listRef.current?.pinTurnToTopWithStatus('turn-a', {
-        behavior: 'auto',
-        pinMode: 'sticky-latest',
+    it('moves it even while the reader is scrolling, because that is when history arrives', () => {
+      /*
+       * Paging up happens only while the reader scrolls up into the boundary,
+       * so a gesture that could refuse this would refuse all of it. Measured
+       * before this was a displacement rather than a position: 2494px arrived,
+       * `scrollTop` held at 40, the transcript jumped back thirteen Turns, and
+       * the boundary never re-armed because the reader was still at the head.
+       */
+      withGrowingRange({ scrollHeightPx: 3000, growthPx: 80 }, scroller => {
+        act(() => { scroller.dispatchEvent(new Event('wheel')); });
+        prependOlderTurns(2);
+        expect(scroller.scrollTop).toBe(580);
       });
     });
-    expect(Number.parseFloat(footer.style.height)).toBeGreaterThan(0);
 
-    act(() => {
-      root.render(<VirtualMessageList ref={listRef} isViewportActive={false} />);
-    });
-    hidden = true;
-    scrollTop = 0;
-    stateMocks.activeSession = {
-      ...session,
-      dialogTurns: session.dialogTurns.map(turn => ({
-        ...turn,
-        status: 'completed',
-        modelRounds: turn.modelRounds.map(round => ({
-          ...round,
-          status: 'completed',
-          isStreaming: false,
-        })),
-      })),
-    };
-    flowDiagnosticsMocks.trace.mockClear();
-    act(() => {
-      root.render(<VirtualMessageList ref={listRef} isViewportActive={false} />);
-      resizeObserverMocks.callbacks.at(-1)?.();
+    it('trusts the range the transcript actually gained over the height reserved for it', () => {
+      /*
+       * The arrived items are estimates in the virtualizer's cache while the
+       * DOM already holds their real heights, and the cache is the one that
+       * over-states. Measured twice in one session: 2174px reserved against
+       * 670px of real growth, then 2494px against 949px. Compensating by the
+       * reserved amount walks the reader down the transcript a page at a time.
+       */
+      withGrowingRange({ scrollHeightPx: 3000, growthPx: 50 }, scroller => {
+        prependOlderTurns(3);
+        expect(scroller.scrollTop).toBe(550);
+      });
     });
-    expect(flowDiagnosticsMocks.trace).not.toHaveBeenCalledWith(expect.objectContaining({
-      location: 'VirtualMessageList.streamEndReconciliation',
-    }));
 
-    hidden = false;
-    act(() => {
-      root.render(<VirtualMessageList ref={listRef} isViewportActive />);
+    it('never compensates past the end of real content', () => {
+      /*
+       * Content arriving above the reader cannot push them past the end of the
+       * transcript, so needing more than the range can absorb is proof the
+       * amount is wrong. Overshooting leaves them inside the reserved blank,
+       * where the reserved blank begins — which, since
+       * paging happens only while scrolling up, it then does every time.
+       */
+      const contentEndPx = 1000 - tailSpacerPxForViewport(600, BOTTOM_INSET) - 600;
+      withGrowingRange({ scrollHeightPx: 900, growthPx: 100, scrollTopPx: 0 }, scroller => {
+        prependOlderTurns(3);
+        expect(scroller.scrollTop).toBe(contentEndPx);
+      });
     });
-    for (let frame = 0; frame < 4; frame += 1) {
-      flushAnimationFrame();
-    }
 
-    expect(flowDiagnosticsMocks.trace).toHaveBeenCalledWith(expect.objectContaining({
-      location: 'VirtualMessageList.streamEndReconciliation',
-    }));
-    expect(Number.parseFloat(footer.style.height)).toBeLessThanOrEqual(1_124);
-    expect(scroller.scrollHeight).toBeLessThan(3_000);
-  });
+    it('leaves the viewport alone when the transcript grows at the end', () => {
+      act(() => root.render(<VirtualMessageList />));
+      const scroller = container.querySelector<HTMLElement>('[data-flowchat-scroller]')!;
+      scroller.scrollTop = 500;
 
-  it('routes jump-to-latest through the presentation owner while reading a history window', () => {
-    const onRequestJumpToLatest = vi.fn();
-    stateMocks.activeSession = createSession('session-a', 'turn-10');
-    stateMocks.virtualItems = [createItem('turn-10')];
+      mocks.items = [...mocks.items, userMessage('turn-3', 'message-3', 'Newer')];
+      act(() => root.render(<VirtualMessageList />));
 
-    act(() => {
-      root.render(
-        <VirtualMessageList
-          presentationMode="history-window"
-          historyWindow={{
-            startOrdinal: 2,
-            endOrdinalExclusive: 7,
-            targetTurnId: 'turn-5',
-            mode: 'history-window',
-          }}
-          presentationRevision={1}
-          onRequestJumpToLatest={onRequestJumpToLatest}
-        />,
-      );
+      expect(scroller.scrollTop).toBe(500);
     });
 
-    const jumpButton = container.querySelector<HTMLButtonElement>('[data-testid="scroll-to-latest"]');
-    expect(jumpButton?.dataset.visible).toBe('true');
-    act(() => jumpButton?.click());
-    expect(onRequestJumpToLatest).toHaveBeenCalledOnce();
-  });
+    it('leaves the viewport alone when the head is trimmed', () => {
+      act(() => root.render(<VirtualMessageList />));
+      const scroller = container.querySelector<HTMLElement>('[data-flowchat-scroller]')!;
+      scroller.scrollTop = 500;
 
-  it('keeps canonical streaming output hidden from tail follow in history-window mode', () => {
-    activeSessionStateMocks.isProcessing = true;
-    stateMocks.activeSession = createSession('session-a', 'turn-10', {
-      dialogTurns: [{
-        ...createSession('session-a', 'turn-10').dialogTurns[0],
-        status: 'processing',
-      }],
-    });
-    const historyItems = ['turn-3', 'turn-4', 'turn-5'].map(createItem);
-    stateMocks.virtualItems = historyItems;
+      // The item that was first is gone rather than moved, so there is no
+      // arrived height to account for and nothing to compensate with.
+      mocks.items = mocks.items.slice(1);
+      act(() => root.render(<VirtualMessageList />));
 
-    act(() => {
-      root.render(
-        <VirtualMessageList
-          items={historyItems}
-          presentationMode="history-window"
-          historyWindow={{
-            startOrdinal: 2,
-            endOrdinalExclusive: 5,
-            targetTurnId: 'turn-4',
-            mode: 'history-window',
-          }}
-          presentationRevision={1}
-        />,
-      );
+      expect(scroller.scrollTop).toBe(500);
     });
 
-    expect(container.querySelector('[data-testid="flowchat-message-list"]')?.getAttribute(
-      'data-streaming-output',
-    )).toBe('false');
-  });
+    it('wakes the follow rule it left the displacement to', () => {
+      /*
+       * Refusing the shift is a contract with whoever holds a target, and
+       * follow-output is the one holder that can be asleep: its ownership
+       * deliberately outlives its frame loop so streaming can resume without
+       * re-entering, and the loop stops once the transcript settles. So a page
+       * landing after that is left to a writer that will never act.
+       *
+       * Measured: 22301px of history arrived above a viewport at offset 0 on
+       * session open, the shift was refused with `heldBy: follow-output`, and
+       * nothing moved again — the transcript was revealed at the top of the
+       * window it had just pulled in, eight Turns above the tail.
+       */
+      withGrowingRange({ scrollHeightPx: 3000, growthPx: 120 }, scroller => {
+        // Follow-output takes the viewport, exactly as entering does.
+        mocks.viewportOwner?.claim('follow-output');
+        mocks.scheduleFollowToLatest.mockReset();
 
-  it('allows live-tail follow while retaining a history-window projection', () => {
-    activeSessionStateMocks.isProcessing = true;
-    stateMocks.activeSession = createSession('session-a', 'turn-10', {
-      dialogTurns: [{
-        ...createSession('session-a', 'turn-10').dialogTurns[0],
-        status: 'processing',
-      }],
-    });
-    const historyItems = ['turn-3', 'turn-4', 'turn-5'].map(createItem);
-    stateMocks.virtualItems = historyItems;
-    const onRequestJumpToLatest = vi.fn();
+        prependOlderTurns(3);
 
-    act(() => {
-      root.render(
-        <VirtualMessageList
-          items={historyItems}
-          presentationMode="history-window"
-          viewportMode="live-tail"
-          historyWindow={null}
-          presentationRevision={1}
-          onRequestJumpToLatest={onRequestJumpToLatest}
-        />,
-      );
+        // Refused, because the holder owns a target of its own...
+        expect(scroller.scrollTop).toBe(500);
+        // ...and asked to go and reach it.
+        expect(mocks.scheduleFollowToLatest).toHaveBeenCalled();
+      });
     });
 
-    expect(container.querySelector('[data-testid="flowchat-message-list"]')?.getAttribute(
-      'data-viewport-mode',
-    )).toBe('live-tail');
-    expect(container.querySelector('[data-testid="flowchat-message-list"]')?.getAttribute(
-      'data-streaming-output',
-    )).toBe('true');
-
-    const jumpButton = container.querySelector<HTMLButtonElement>('[data-testid="scroll-to-latest"]');
-    expect(jumpButton).not.toBeNull();
-    act(() => jumpButton?.click());
-    expect(onRequestJumpToLatest).not.toHaveBeenCalled();
+    it('wakes nobody when it could put the reader back itself', () => {
+      withGrowingRange({ scrollHeightPx: 3000, growthPx: 120 }, scroller => {
+        mocks.scheduleFollowToLatest.mockReset();
+
+        prependOlderTurns(3);
+
+        expect(scroller.scrollTop).toBe(620);
+        expect(mocks.scheduleFollowToLatest).not.toHaveBeenCalled();
+      });
+    });
   });
 
-  it('waits for quiet scroll input before capturing an adjacent history anchor', async () => {
-    let prepareViewportForPresentationCommit:
-      | (() => boolean | void | Promise<boolean | void>)
-      | undefined;
-    let resolveBoundaryIntent: ((handled: boolean) => void) | undefined;
-    const boundaryIntent = new Promise<boolean>(resolve => {
-      resolveBoundaryIntent = resolve;
+  describe('asking for older Turns', () => {
+    /** Twenty 40px rows, seen through a 200px viewport. */
+    const ROW_PX = 40;
+    const VIEWPORT_PX = 200;
+
+    /** A scroll, and the microtasks a boundary request resolves through. */
+    async function scrollTo(scroller: HTMLElement, topPx: number) {
+      await act(async () => {
+        scroller.scrollTop = topPx;
+        scroller.dispatchEvent(new Event('scroll'));
+        await Promise.resolve();
+        await Promise.resolve();
+      });
+    }
+
+    /**
+     * A transcript with a page already behind it.
+     *
+     * The list opens at the top, so once the reveal is over it asks and disarms
+     * `before`. That is the state both of these are about: one page dispatched,
+     * and what has to happen for the next one. `asked` is cleared afterwards so
+     * it counts only what the scrolls produced.
+     */
+    async function withPagedTranscript(
+      run: (scroller: HTMLElement, asked: string[]) => Promise<void>,
+    ) {
+      mocks.items = Array.from({ length: 20 }, (_unused, index) => (
+        userMessage(`turn-${index}`, `message-${index}`, 'Body')
+      ));
+      const restoreLayout = fakeLayout({
+        clientHeight: VIEWPORT_PX,
+        scrollHeight: 20 * ROW_PX,
+        turnTopFromScrollerTop: 0,
+      });
+      const asked: string[] = [];
+      try {
+        await act(async () => {
+          root.render(
+            <VirtualMessageList
+              onHistoryWindowBoundaryIntent={direction => {
+                asked.push(direction);
+                return 'applied';
+              }}
+            />,
+          );
+          await Promise.resolve();
+          await Promise.resolve();
+        });
+        // Nothing while the transcript is still being placed: at offset 0 of an
+        // unplaced viewport the head is trivially reached, and paging from
+        // there prepends history under the placement.
+        expect(asked).toEqual([]);
+        await settleOpenReveal();
+        expect(asked).toEqual(['before']);
+        asked.length = 0;
+        await run(container.querySelector<HTMLElement>('[data-flowchat-scroller]')!, asked);
+      } finally {
+        restoreLayout();
+      }
+    }
+
+    it('asks again once the reader is off the boundary, still within the lead', async () => {
+      /*
+       * The latch re-arms on the reader being *off* the boundary, and the ask
+       * goes out a screenful before they reach it — so those cannot be the same
+       * predicate. When they were, one page landed and everything after it was
+       * refused as `not-rearmed`: measured, six minutes of refusals while the
+       * reader scrolled into a wall two Turns from the top of what was loaded.
+       */
+      await withPagedTranscript(async (scroller, asked) => {
+        // Rows 3..7 are on screen, so nothing is reached; the head is 120px up,
+        // which is inside the one-screen lead.
+        await scrollTo(scroller, 120);
+        expect(asked).toEqual(['before']);
+      });
+    });
+
+    it('does not ask again while the reader is still on the head', async () => {
+      // The latch's own job, unchanged: after a prepend the visible range reads
+      // as the head for a commit, and that must not dispatch a second page.
+      await withPagedTranscript(async (scroller, asked) => {
+        await scrollTo(scroller, ROW_PX);
+        expect(asked).toEqual([]);
+      });
+    });
+
+    it('asks on a gesture that moves nothing, because at the top none of them do', async () => {
+      /*
+       * The deadlock this closes, measured on a tail window of three Turns that
+       * fitted inside the viewport — so the whole scroll range was reserved
+       * blank and the reader sat at offset 0 with the head already on screen.
+       *
+       * A wheel there changes no offset, so the scroller emits no `scroll`
+       * event and the evaluation that hangs off it never runs. The log shows
+       * twenty `user-gesture` claims across seven seconds with no scroll event,
+       * no anchor capture and not one boundary evaluation; the only evaluations
+       * in that session landed in the three milliseconds after follow-output
+       * handed the viewport to follow-output, and were refused for exactly that
+       * reason. Scrolling up did nothing, permanently.
+       */
+      mocks.items = Array.from({ length: 20 }, (_unused, index) => (
+        userMessage(`turn-${index}`, `message-${index}`, 'Body')
+      ));
+      const restoreLayout = fakeLayout({
+        clientHeight: VIEWPORT_PX,
+        scrollHeight: 20 * ROW_PX,
+        turnTopFromScrollerTop: 0,
+      });
+      const asked: string[] = [];
+      try {
+        await act(async () => {
+          root.render(
+            <VirtualMessageList
+              onHistoryWindowBoundaryIntent={direction => {
+                asked.push(direction);
+                // Not applied, so the direction arms again rather than waiting
+                // for a prepend that never comes — the state the reader is in.
+                return 'not-ready';
+              }}
+            />,
+          );
+          await Promise.resolve();
+          await Promise.resolve();
+        });
+        await settleOpenReveal();
+        expect(asked).toEqual(['before']);
+        asked.length = 0;
+
+        const scroller = container.querySelector<HTMLElement>('[data-flowchat-scroller]')!;
+        // A wheel and nothing else: no scroll event, because there is nowhere
+        // for the offset to go.
+        await act(async () => {
+          scroller.dispatchEvent(new Event('wheel'));
+          await Promise.resolve();
+          await Promise.resolve();
+        });
+
+        expect(asked).toEqual(['before']);
+      } finally {
+        restoreLayout();
+      }
     });
-    const onBoundaryIntent = vi.fn((
-      _direction: 'before' | 'after',
-      options?: {
-        prepareViewportForPresentationCommit?: () => boolean | void | Promise<boolean | void>;
-      },
-    ) => {
-      prepareViewportForPresentationCommit = options?.prepareViewportForPresentationCommit;
-      return boundaryIntent;
+
+    it('asks as the reader, not as the ownership their own gesture just ended', async () => {
+      /*
+       * `exitFollowOutput` clears ownership synchronously, but the list mirrored
+       * `isFollowingOutput` into a ref at render time — and no render happens
+       * inside an event handler. So the gesture released the viewport and then
+       * asked, and the ask was refused for an ownership that had already ended
+       * one line earlier. In the log: `followOutput.exit` and
+       * `historyPaging.refused: follow-output-owns-the-viewport` at the same
+       * millisecond, three entries apart.
+       */
+      mocks.items = Array.from({ length: 20 }, (_unused, index) => (
+        userMessage(`turn-${index}`, `message-${index}`, 'Body')
+      ));
+      // Follow owns the viewport as of the last render, and the gesture below
+      // releases it without a render in between.
+      mocks.isFollowingOutput = true;
+      mocks.followsNow = true;
+      const restoreLayout = fakeLayout({
+        clientHeight: VIEWPORT_PX,
+        scrollHeight: 20 * ROW_PX,
+        turnTopFromScrollerTop: 0,
+      });
+      const asked: string[] = [];
+      try {
+        await act(async () => {
+          root.render(
+            <VirtualMessageList
+              onHistoryWindowBoundaryIntent={direction => {
+                asked.push(direction);
+                return 'not-ready';
+              }}
+            />,
+          );
+          await Promise.resolve();
+          await Promise.resolve();
+        });
+        await settleOpenReveal();
+        // Refused on mount, correctly: follow owned it and nobody had gestured.
+        expect(asked).toEqual([]);
+
+        const scroller = container.querySelector<HTMLElement>('[data-flowchat-scroller]')!;
+        await act(async () => {
+          scroller.dispatchEvent(new Event('wheel'));
+          await Promise.resolve();
+          await Promise.resolve();
+        });
+
+        expect(asked).toEqual(['before']);
+      } finally {
+        restoreLayout();
+      }
     });
-    stateMocks.activeSession = createSession('session-a', 'turn-10');
-    const initialItems = ['turn-3', 'turn-4', 'turn-5', 'turn-6', 'turn-7'].map(createItem);
-    stateMocks.virtualItems = initialItems;
 
-    act(() => {
-      root.render(
+    it('stops treating a boundary as exhausted once the window has moved', async () => {
+      /*
+       * `exhausted` is a fact about a start ordinal, not about the session.
+       * Navigating to the first Turn asks `before`, the store answers
+       * `reached-start` for `targetOrdinal: -1` — correctly — and the latch then
+       * outlived that window. Measured: 3 Turns of 43 loaded, the reader jumped
+       * back to the tail, and `before` stayed latched off for good.
+       */
+      mocks.items = Array.from({ length: 20 }, (_unused, index) => (
+        userMessage(`turn-${index}`, `message-${index}`, 'Body')
+      ));
+      const restoreLayout = fakeLayout({
+        clientHeight: VIEWPORT_PX,
+        scrollHeight: 20 * ROW_PX,
+        turnTopFromScrollerTop: 0,
+      });
+      const asked: string[] = [];
+      const atFirstTurn = { startOrdinal: 0, endOrdinalExclusive: 8, targetTurnId: null, mode: 'history-window' as const };
+      const atTail = { startOrdinal: 35, endOrdinalExclusive: 43, targetTurnId: null, mode: 'history-window' as const };
+      const list = (window: typeof atFirstTurn) => (
         <VirtualMessageList
-          items={initialItems}
           presentationMode="history-window"
-          historyWindow={{
-            startOrdinal: 2,
-            endOrdinalExclusive: 7,
-            targetTurnId: 'turn-5',
-            mode: 'history-window',
+          historyWindow={window}
+          onHistoryWindowBoundaryIntent={direction => {
+            asked.push(direction);
+            // Nothing before the first Turn — true of this window, and only it.
+            return 'exhausted';
           }}
-          presentationRevision={1}
-          historyBoundaryState={{ before: 'idle', after: 'idle' }}
-          onHistoryWindowBoundaryIntent={onBoundaryIntent}
-        />,
+        />
       );
-    });
 
-    const scroller = container.querySelector<HTMLElement>('[data-testid="virtuoso"]');
-    const anchor = container.querySelector<HTMLElement>('[data-turn-id="turn-3"]');
-    expect(scroller).not.toBeNull();
-    expect(anchor).not.toBeNull();
-    if (!scroller || !anchor) return;
-
-    for (let frame = 0; frame < 8 && rafCallbacks.length > 0; frame += 1) {
-      flushAnimationFrame();
-    }
+      try {
+        await act(async () => {
+          root.render(list(atFirstTurn));
+          await Promise.resolve();
+          await Promise.resolve();
+        });
+        await settleOpenReveal();
+        expect(asked).toContain('before');
+        asked.length = 0;
+
+        // Latched: asking again from the same window changes nothing.
+        const scroller = container.querySelector<HTMLElement>('[data-flowchat-scroller]')!;
+        await act(async () => {
+          scroller.dispatchEvent(new Event('wheel'));
+          await Promise.resolve();
+          await Promise.resolve();
+        });
+        expect(asked).toEqual([]);
+
+        // The reader jumps back to the tail. The answer was about where they
+        // were, so it does not survive their leaving.
+        await act(async () => {
+          root.render(list(atTail));
+          await Promise.resolve();
+          await Promise.resolve();
+        });
+        await act(async () => {
+          scroller.dispatchEvent(new Event('wheel'));
+          await Promise.resolve();
+          await Promise.resolve();
+        });
 
-    setScrollerGeometry(scroller, {
-      clientHeight: 100,
-      scrollHeight: 500,
-      scrollTop: 40,
+        expect(asked).toContain('before');
+      } finally {
+        restoreLayout();
+      }
     });
-    scroller.getBoundingClientRect = () => createRect({ top: 0, bottom: 100, height: 100 });
-    let anchorDocumentTop = 60;
-    anchor.getBoundingClientRect = () => {
-      const top = anchorDocumentTop - scroller.scrollTop;
-      return createRect({ top, bottom: top + 20, height: 20 });
-    };
+  });
 
-    vi.useFakeTimers();
-    try {
-      act(() => {
-        scroller.dispatchEvent(new WheelEvent('wheel', { deltaY: -20, bubbles: true }));
-      });
-      expect(onBoundaryIntent).toHaveBeenCalledWith('before', expect.objectContaining({
-        prepareViewportForPresentationCommit: expect.any(Function),
-      }));
-
-      scroller.scrollTop = 80;
-      let preparationSettled = false;
-      const preparation = Promise.resolve(prepareViewportForPresentationCommit?.()).then(result => {
-        preparationSettled = true;
-        return result;
-      });
-
-      act(() => {
-        vi.advanceTimersByTime(319);
-        scroller.dispatchEvent(new WheelEvent('wheel', { deltaY: -20, bubbles: true }));
-        vi.advanceTimersByTime(319);
-      });
-      await Promise.resolve();
-      expect(preparationSettled).toBe(false);
-
-      await act(async () => {
-        vi.advanceTimersByTime(1);
-        expect(await preparation).not.toBe(false);
-      });
-
-      const extendedItems = ['turn-1', 'turn-2', ...initialItems.map(item => item.turnId)].map(createItem);
-      act(() => {
-        anchorDocumentTop = 120;
-        root.render(
-          <VirtualMessageList
-            items={extendedItems}
-            presentationMode="history-window"
-            historyWindow={{
-              startOrdinal: 0,
-              endOrdinalExclusive: 7,
-              targetTurnId: 'turn-5',
-              mode: 'history-window',
-            }}
-            presentationRevision={2}
-            historyBoundaryState={{ before: 'loading', after: 'idle' }}
-            onHistoryWindowBoundaryIntent={onBoundaryIntent}
-          />,
-        );
-        resolveBoundaryIntent?.(true);
-      });
-      await act(async () => {
-        await boundaryIntent;
-      });
-      flushAnimationFrame();
-      flushAnimationFrame();
-
-      expect(scroller.scrollTop).toBe(140);
-      expect(container.querySelector('[data-history-paging-sentinel="loading"]')).not.toBeNull();
-
-      act(() => {
-        root.render(
-          <VirtualMessageList
-            items={extendedItems}
-            presentationMode="history-window"
-            historyWindow={{
-              startOrdinal: 0,
-              endOrdinalExclusive: 7,
-              targetTurnId: 'turn-5',
-              mode: 'history-window',
-            }}
-            presentationRevision={2}
-            historyBoundaryState={{ before: 'idle', after: 'idle' }}
-            onHistoryWindowBoundaryIntent={onBoundaryIntent}
-          />,
-        );
-      });
-      expect(container.querySelector('[data-history-paging-sentinel]')).toBeNull();
-    } finally {
-      vi.useRealTimers();
-    }
-  });
-
-  it('releases the visible element anchor when an adjacent history request is not handled', async () => {
-    const onBoundaryIntent = vi.fn(async () => false);
-    stateMocks.activeSession = createSession('session-a', 'turn-10');
-    const initialItems = ['turn-3', 'turn-4', 'turn-5', 'turn-6', 'turn-7'].map(createItem);
-    stateMocks.virtualItems = initialItems;
-
-    act(() => {
-      root.render(
-        <VirtualMessageList
-          items={initialItems}
-          presentationMode="history-window"
-          historyWindow={{
-            startOrdinal: 2,
-            endOrdinalExclusive: 7,
-            targetTurnId: 'turn-5',
-            mode: 'history-window',
-          }}
-          presentationRevision={1}
-          historyBoundaryState={{ before: 'idle', after: 'idle' }}
-          onHistoryWindowBoundaryIntent={onBoundaryIntent}
-        />,
-      );
-    });
-
-    const scroller = container.querySelector<HTMLElement>('[data-testid="virtuoso"]');
-    const anchor = container.querySelector<HTMLElement>('[data-turn-id="turn-3"]');
-    expect(scroller).not.toBeNull();
-    expect(anchor).not.toBeNull();
-    if (!scroller || !anchor) return;
-
-    for (let frame = 0; frame < 8 && rafCallbacks.length > 0; frame += 1) {
-      flushAnimationFrame();
-    }
-
-    setScrollerGeometry(scroller, {
-      clientHeight: 100,
-      scrollHeight: 500,
-      scrollTop: 40,
-    });
-    scroller.getBoundingClientRect = () => createRect({ top: 0, bottom: 100, height: 100 });
-    let anchorDocumentTop = 60;
-    anchor.getBoundingClientRect = () => {
-      const top = anchorDocumentTop - scroller.scrollTop;
-      return createRect({ top, bottom: top + 20, height: 20 });
-    };
-
-    act(() => {
-      scroller.dispatchEvent(new WheelEvent('wheel', { deltaY: -20, bubbles: true }));
-    });
-    await act(async () => {
-      await Promise.resolve();
-    });
-    expect(onBoundaryIntent).toHaveBeenCalledWith('before', expect.objectContaining({
-      prepareViewportForPresentationCommit: expect.any(Function),
-    }));
-
-    scroller.scrollTop = 80;
-    anchorDocumentTop = 60;
-    flushAnimationFrame();
-
-    expect(scroller.scrollTop).toBe(80);
-  });
-
-  it('reports every turn intersecting the readable viewport in DOM order', () => {
-    stateMocks.setVisibleTurnInfo.mockImplementation((info: unknown) => {
-      stateMocks.visibleTurnInfo = info;
-    });
-    stateMocks.activeSession = createSessionWithTurns('session-a', ['turn-a', 'turn-b']);
-    stateMocks.virtualItems = [
-      createItem('turn-a'),
-      createModelItem('turn-a'),
-      createItem('turn-b'),
-      createModelItem('turn-b'),
-    ];
-
-    act(() => {
-      root.render(<VirtualMessageList />);
-    });
-
-    const scroller = container.querySelector<HTMLElement>('[data-virtuoso-scroller="true"]');
-    const renderedItems = Array.from(
-      container.querySelectorAll<HTMLElement>('.virtual-item-wrapper[data-turn-id]'),
-    );
-    expect(scroller).not.toBeNull();
-    expect(renderedItems).toHaveLength(4);
-    if (!scroller || renderedItems.length !== 4) return;
-
-    vi.spyOn(scroller, 'getBoundingClientRect').mockReturnValue(createRect({
-      top: 0,
-      bottom: 300,
-      height: 300,
-    }));
-    const itemRects = [
-      { top: 0, bottom: 50 },
-      { top: 50, bottom: 150 },
-      { top: 150, bottom: 210 },
-      { top: 210, bottom: 280 },
-    ];
-    renderedItems.forEach((item, index) => {
-      const rect = itemRects[index];
-      vi.spyOn(item, 'getBoundingClientRect').mockReturnValue(createRect({
-        top: rect.top,
-        bottom: rect.bottom,
-        height: rect.bottom - rect.top,
-      }));
-    });
-
-    act(() => {
-      scroller.dispatchEvent(new Event('scroll', { bubbles: true }));
-    });
-    for (let frame = 0; frame < 4; frame += 1) {
-      flushAnimationFrame();
-    }
-
-    expect(stateMocks.setVisibleTurnInfo).toHaveBeenLastCalledWith(expect.objectContaining({
-      turnId: 'turn-a',
-      visibleTurnIds: ['turn-a', 'turn-b'],
-    }));
-    const publishCount = stateMocks.setVisibleTurnInfo.mock.calls.length;
-
-    act(() => {
-      scroller.dispatchEvent(new Event('scroll', { bubbles: true }));
-    });
-    for (let frame = 0; frame < 4; frame += 1) {
-      flushAnimationFrame();
-    }
-
-    expect(stateMocks.setVisibleTurnInfo).toHaveBeenCalledTimes(publishCount);
-  });
-
-  it('transfers collapse space to a sticky pin in one reservation state', () => {
-    const currentState = {
-      collapse: { kind: 'collapse' as const, px: 1_583, floorPx: 181 },
-      pin: {
-        kind: 'pin' as const,
-        px: 0,
-        floorPx: 0,
-        mode: 'sticky-latest' as const,
-        targetTurnId: 'turn-a',
-      },
-    };
-    const nextPin = {
-      ...currentState.pin,
-      px: 559,
-      floorPx: 559,
-    };
-
-    expect(transferCollapseReservationToPin(currentState, nextPin)).toEqual({
-      collapse: { kind: 'collapse', px: 0, floorPx: 0 },
-      pin: nextPin,
-    });
-  });
-
-  it('transfers a released pin into a protected viewport range', () => {
-    const currentState = {
-      collapse: { kind: 'collapse' as const, px: 12, floorPx: 4 },
-      pin: {
-        kind: 'pin' as const,
-        px: 100,
-        floorPx: 100,
-        mode: 'sticky-latest' as const,
-        targetTurnId: 'turn-a',
-      },
-    };
-
-    expect(transferPinReservationToProtectedCollapse(currentState)).toEqual({
-      collapse: { kind: 'collapse', px: 112, floorPx: 104 },
-      pin: {
-        kind: 'pin',
-        px: 0,
-        floorPx: 0,
-        mode: 'transient',
-        targetTurnId: null,
-      },
-    });
-  });
-
-  it('invalidates pending turn pin work by generation, session, and target', () => {
-    const request = {
-      generation: 7,
-      sessionId: 'session-a',
-      turnId: 'turn-a',
-    };
-
-    expect(isTurnPinRequestIdentityCurrent(request, request)).toBe(true);
-    expect(isTurnPinRequestIdentityCurrent(request, {
-      ...request,
-      generation: 8,
-    })).toBe(false);
-    expect(isTurnPinRequestIdentityCurrent(request, {
-      ...request,
-      sessionId: 'session-b',
-    })).toBe(false);
-    expect(isTurnPinRequestIdentityCurrent(request, {
-      ...request,
-      turnId: 'turn-b',
-    })).toBe(false);
-  });
-
-  it('drops a provisional sticky pin on user intent without protecting its range', () => {
-    const currentState = {
-      collapse: { kind: 'collapse' as const, px: 12, floorPx: 4 },
-      pin: {
-        kind: 'pin' as const,
-        px: 3_780,
-        floorPx: 0,
-        mode: 'sticky-latest' as const,
-        targetTurnId: 'turn-a',
-      },
-    };
-
-    expect(releasePinReservationForUserNavigation(currentState, {
-      preserveCurrentRange: true,
-      ownsElementAnchor: false,
-    })).toEqual({
-      collapse: currentState.collapse,
-      pin: {
-        kind: 'pin',
-        px: 0,
-        floorPx: 0,
-        mode: 'transient',
-        targetTurnId: null,
-      },
-    });
-  });
-
-  it('protects an established sticky pin range when user intent exits it', () => {
-    const currentState = {
-      collapse: { kind: 'collapse' as const, px: 12, floorPx: 4 },
-      pin: {
-        kind: 'pin' as const,
-        px: 100,
-        floorPx: 100,
-        mode: 'sticky-latest' as const,
-        targetTurnId: 'turn-a',
-      },
-    };
-
-    expect(releasePinReservationForUserNavigation(currentState, {
-      preserveCurrentRange: true,
-      ownsElementAnchor: true,
-    })).toEqual(transferPinReservationToProtectedCollapse(currentState));
-  });
-
-  it('keeps unresolved sticky pin fallback reservation idempotent and viewport-bounded', () => {
-    expect(resolveProvisionalStickyPinReservationPx({
-      scrollHeight: 3_803,
-      clientHeight: 1_023,
-      currentPinPx: 0,
-    })).toBe(1_023);
-    expect(resolveProvisionalStickyPinReservationPx({
-      scrollHeight: 4_826,
-      clientHeight: 1_023,
-      currentPinPx: 1_023,
-    })).toBe(1_023);
-    expect(resolveProvisionalStickyPinReservationPx({
-      scrollHeight: 6_583,
-      clientHeight: 1_023,
-      currentPinPx: 5_560,
-    })).toBe(1_023);
-
-    expect(clampPinReservationPxToViewport(640, 1_023)).toBe(640);
-    expect(clampPinReservationPxToViewport(2_780, 1_023)).toBe(1_023);
-  });
-
-  it('clears only expired provisional sticky pins without an element anchor', () => {
-    const pinReservation = {
-      kind: 'pin' as const,
-      px: 2_780,
-      floorPx: 0,
-      mode: 'sticky-latest' as const,
-      targetTurnId: 'turn-a',
-    };
-    const baseOptions = {
-      requestTurnId: 'turn-a',
-      requestPinMode: 'sticky-latest' as const,
-      pinReservation,
-      ownsElementAnchor: false,
-    };
-
-    expect(shouldClearExpiredProvisionalStickyPin(baseOptions)).toBe(true);
-    expect(shouldClearExpiredProvisionalStickyPin({
-      ...baseOptions,
-      ownsElementAnchor: true,
-    })).toBe(false);
-    expect(shouldClearExpiredProvisionalStickyPin({
-      ...baseOptions,
-      pinReservation: { ...pinReservation, floorPx: 200 },
-    })).toBe(false);
-    expect(shouldClearExpiredProvisionalStickyPin({
-      ...baseOptions,
-      requestTurnId: 'turn-b',
-    })).toBe(false);
-  });
-
-  it('protects a settled element range from later unsignaled shrink reconciliation', () => {
-    const settledState = settleCollapseReservationForViewport({
-      collapse: { kind: 'collapse', px: 1_022, floorPx: 670 },
-      pin: {
-        kind: 'pin',
-        px: 0,
-        floorPx: 0,
-        mode: 'transient',
-        targetTurnId: null,
-      },
-    }, {
-      scrollTop: 686,
-      scrollHeight: 2_030,
-      clientHeight: 1_023,
-    });
-    expect(settledState.collapse).toEqual({
-      kind: 'collapse',
-      px: 702,
-      floorPx: 702,
-    });
-
-    const settledPinnedRange = settleCollapseReservationForViewport({
-      collapse: { kind: 'collapse', px: 152.7, floorPx: 67.7 },
-      pin: {
-        kind: 'pin',
-        px: 674.6,
-        floorPx: 674.6,
-        mode: 'sticky-latest',
-        targetTurnId: 'turn-a',
-      },
-    }, {
-      scrollTop: 5_122,
-      scrollHeight: 6_235,
-      clientHeight: 1_027,
-    });
-    expect(settledPinnedRange.collapse.px).toBeCloseTo(67.7, 1);
-    expect(settledPinnedRange.collapse.floorPx).toBeCloseTo(67.7, 1);
-
-    const protectedState = protectCurrentCollapseReservation({
-      collapse: { kind: 'collapse', px: 784, floorPx: 670 },
-      pin: {
-        kind: 'pin',
-        px: 0,
-        floorPx: 0,
-        mode: 'transient',
-        targetTurnId: null,
-      },
-    });
-
-    expect(protectedState.collapse).toEqual({
-      kind: 'collapse',
-      px: 784,
-      floorPx: 784,
-    });
-    expect(reconcileUnsignaledShrinkReservation(protectedState, 2).collapse).toEqual({
-      kind: 'collapse',
-      px: 784,
-      floorPx: 784,
-    });
-    expect(reconcileUnsignaledShrinkReservation({
-      ...protectedState,
-      collapse: { kind: 'collapse', px: 784, floorPx: 0 },
-    }, 2).collapse).toEqual({
-      kind: 'collapse',
-      px: 2,
-      floorPx: 0,
-    });
-    expect(reconcileUnsignaledShrinkReservation({
-      ...protectedState,
-      collapse: { kind: 'collapse', px: 0, floorPx: 0 },
-    }, 907.333, false).collapse).toEqual({
-      kind: 'collapse',
-      px: 0,
-      floorPx: 0,
-    });
-    expect(reconcileUnsignaledShrinkReservation({
-      ...protectedState,
-      collapse: { kind: 'collapse', px: 0, floorPx: 0 },
-    }, 907.333, true).collapse).toEqual({
-      kind: 'collapse',
-      px: 907.333,
-      floorPx: 0,
-    });
-  });
-
-  it('extends and protects collapse range needed to restore a captured scroll position', () => {
-    const currentState = {
-      collapse: { kind: 'collapse' as const, px: 111.5, floorPx: 0 },
-      pin: {
-        kind: 'pin' as const,
-        px: 0,
-        floorPx: 0,
-        mode: 'transient' as const,
-        targetTurnId: null,
-      },
-    };
-
-    const ensured = ensureCollapseReservationForScrollTop(currentState, {
-      targetScrollTop: 933.33,
-      scrollHeight: 1_897,
-      clientHeight: 1_023,
-    });
-
-    expect(ensured.collapse.px).toBeCloseTo(171.83, 2);
-    expect(ensured.collapse.floorPx).toBeCloseTo(171.83, 2);
-  });
-
-  it('does not synchronously shrink surplus collapse range while retaining an anchor', () => {
-    const retained = ensureCollapseReservationForScrollTop({
-      collapse: { kind: 'collapse', px: 205.85, floorPx: 0 },
-      pin: {
-        kind: 'pin',
-        px: 0,
-        floorPx: 0,
-        mode: 'transient',
-        targetTurnId: null,
-      },
-    }, {
-      targetScrollTop: 1_003.33,
-      scrollHeight: 2_242,
-      clientHeight: 1_023,
-    });
-
-    expect(retained).toEqual({
-      collapse: { kind: 'collapse', px: 205.85, floorPx: 0 },
-      pin: {
-        kind: 'pin',
-        px: 0,
-        floorPx: 0,
-        mode: 'transient',
-        targetTurnId: null,
-      },
-    });
-  });
-
-  it('does not reserve a viewport merely to keep scrollTop zero reachable', () => {
-    const retained = ensureCollapseReservationForScrollTop({
-      collapse: { kind: 'collapse', px: 559.49, floorPx: 559.49 },
-      pin: {
-        kind: 'pin',
-        px: 0,
-        floorPx: 0,
-        mode: 'transient',
-        targetTurnId: null,
-      },
-    }, {
-      targetScrollTop: 0,
-      scrollHeight: 1_023,
-      clientHeight: 1_023,
-    });
-
-    expect(retained.collapse).toEqual({
-      kind: 'collapse',
-      px: 559.49,
-      floorPx: 559.49,
-    });
-    expect(settleRetainedCollapseReservationForAnchor(retained, {
-      targetScrollTop: 0,
-      scrollHeight: 1_023,
-      clientHeight: 1_023,
-    }).collapse).toEqual({
-      kind: 'collapse',
-      px: 0,
-      floorPx: 0,
-    });
-  });
-
-  it('settles retained collapse estimates to the physical range required by the anchor', () => {
-    const settled = settleRetainedCollapseReservationForAnchor({
-      collapse: { kind: 'collapse', px: 1_669.04813, floorPx: 559.48962 },
-      pin: {
-        kind: 'pin',
-        px: 0,
-        floorPx: 0,
-        mode: 'transient',
-        targetTurnId: null,
-      },
-    }, {
-      targetScrollTop: 662,
-      scrollHeight: 3_354,
-      clientHeight: 1_023,
-    });
-
-    expect(settled.collapse.px).toBeCloseTo(1.04813, 4);
-    expect(settled.collapse.floorPx).toBeCloseTo(1.04813, 4);
-  });
-
-  it('drains a sticky pin floor only from measured content growth', () => {
-    const currentState = {
-      collapse: { kind: 'collapse' as const, px: 20, floorPx: 0 },
-      pin: {
-        kind: 'pin' as const,
-        px: 100,
-        floorPx: 100,
-        mode: 'sticky-latest' as const,
-        targetTurnId: 'turn-a',
-      },
-    };
-
-    expect(consumeBottomReservationForContentGrowth(currentState, 35, true)).toEqual({
-      collapse: { kind: 'collapse', px: 0, floorPx: 0 },
-      pin: {
-        ...currentState.pin,
-        px: 85,
-        floorPx: 85,
-      },
-    });
-    expect(consumeBottomReservationForContentGrowth(currentState, 35, false)).toEqual({
-      collapse: { kind: 'collapse', px: 0, floorPx: 0 },
-      pin: currentState.pin,
-    });
-    expect(consumeBottomReservationForContentGrowth(currentState, 35, true, true)).toEqual({
-      collapse: currentState.collapse,
-      pin: {
-        ...currentState.pin,
-        px: 65,
-        floorPx: 65,
-      },
-    });
-
-    expect(consumeBottomReservationForContentGrowth({
-      ...currentState,
-      collapse: { kind: 'collapse', px: 30, floorPx: 20 },
-    }, 25, false)).toEqual({
-      collapse: { kind: 'collapse', px: 5, floorPx: 5 },
-      pin: currentState.pin,
-    });
-  });
-
-  it('syncs the physical bottom only for a real viewport-height change', () => {
-    expect(shouldSyncPhysicalBottom({
-      viewportHeightChanged: true,
-      collapseProtectionActive: false,
-      wasAtPhysicalBottom: true,
-      ownsElementAnchor: true,
-      isFollowingTail: false,
-    })).toBe(false);
-    expect(shouldSyncPhysicalBottom({
-      viewportHeightChanged: true,
-      collapseProtectionActive: false,
-      wasAtPhysicalBottom: true,
-      ownsElementAnchor: false,
-      isFollowingTail: false,
-    })).toBe(true);
-    expect(shouldSyncPhysicalBottom({
-      viewportHeightChanged: true,
-      collapseProtectionActive: false,
-      wasAtPhysicalBottom: true,
-      ownsElementAnchor: false,
-      isFollowingTail: true,
-    })).toBe(false);
-    expect(shouldSyncPhysicalBottom({
-      viewportHeightChanged: false,
-      collapseProtectionActive: false,
-      wasAtPhysicalBottom: true,
-      ownsElementAnchor: false,
-      isFollowingTail: false,
-    })).toBe(false);
-  });
-
-  it('suppresses only negative virtualizer compensation while following the streaming tail', () => {
-    expect(shouldSuppressFollowingTailNegativeScrollBy({
-      requestedTop: -242,
-      isFollowingOutput: true,
-      isStreamingOutput: true,
-      wasAtPhysicalBottom: true,
-    })).toBe(true);
-    expect(shouldSuppressFollowingTailNegativeScrollBy({
-      requestedTop: 36,
-      isFollowingOutput: true,
-      isStreamingOutput: true,
-      wasAtPhysicalBottom: true,
-    })).toBe(false);
-    expect(shouldSuppressFollowingTailNegativeScrollBy({
-      requestedTop: -242,
-      isFollowingOutput: true,
-      isStreamingOutput: true,
-      wasAtPhysicalBottom: false,
-    })).toBe(false);
-    expect(shouldSuppressFollowingTailNegativeScrollBy({
-      requestedTop: -242,
-      isFollowingOutput: false,
-      isStreamingOutput: true,
-      wasAtPhysicalBottom: true,
-    })).toBe(false);
-  });
-
-  it('recognizes only a non-user physical-bottom clamp from a shrinking scroll range', () => {
-    const clampGeometry = {
-      previousGeometry: {
-        scrollTop: 645.3333129882812,
-        scrollHeight: 1_673,
-        clientHeight: 1_027,
-      },
-      currentGeometry: {
-        scrollTop: 402.6666564941406,
-        scrollHeight: 1_430,
-        clientHeight: 1_027,
-      },
-      isFollowingOutput: true,
-      isStreamingOutput: true,
-      hasRecentUserUpwardIntent: false,
-      scrollbarPointerInteractionActive: false,
-      collapseProtectionActive: false,
-    };
-
-    const recovery = resolveFollowingTailShrinkClampRecovery(clampGeometry);
-    expect(recovery?.targetScrollTop).toBe(645.3333129882812);
-    expect(recovery?.rangeShrinkPx).toBe(243);
-    expect(recovery?.scrollClampPx).toBeCloseTo(242.6666564941406, 10);
-    expect(resolveFollowingTailShrinkClampRecovery({
-      ...clampGeometry,
-      hasRecentUserUpwardIntent: true,
-    })).toBeNull();
-    expect(resolveFollowingTailShrinkClampRecovery({
-      ...clampGeometry,
-      isFollowingOutput: false,
-    })).toBeNull();
-    expect(resolveFollowingTailShrinkClampRecovery({
-      ...clampGeometry,
-      currentGeometry: {
-        ...clampGeometry.currentGeometry,
-        scrollTop: 500,
-      },
-    })).toBeNull();
-    expect(resolveFollowingTailShrinkClampRecovery({
-      ...clampGeometry,
-      currentGeometry: {
-        ...clampGeometry.currentGeometry,
-        clientHeight: 900,
-      },
-    })).toBeNull();
-  });
-
-  it('cancels unsettled sticky pin growth only for unsignaled height corrections', () => {
-    expect(getCanceledUnsettledStickyPinGrowthPx({
-      pendingGrowthPx: 207,
-      shrinkPx: 207,
-      hasActiveCollapseIntent: false,
-    })).toBe(207);
-    expect(getCanceledUnsettledStickyPinGrowthPx({
-      pendingGrowthPx: 207,
-      shrinkPx: 55,
-      hasActiveCollapseIntent: false,
-    })).toBe(55);
-    expect(getCanceledUnsettledStickyPinGrowthPx({
-      pendingGrowthPx: 207,
-      shrinkPx: 207,
-      hasActiveCollapseIntent: true,
-    })).toBe(0);
-  });
-
-  it('settles sticky pin growth as soon as it exhausts the remaining pin floor', () => {
-    expect(resolveStickyPinGrowthSettlementStrategy({
-      pendingGrowthPx: 0,
-      pinFloorPx: 11.77,
-      hasActiveCollapseIntent: false,
-    })).toBe('none');
-    expect(resolveStickyPinGrowthSettlementStrategy({
-      pendingGrowthPx: 10,
-      pinFloorPx: 11.77,
-      hasActiveCollapseIntent: false,
-    })).toBe('wait-for-quiet');
-    expect(resolveStickyPinGrowthSettlementStrategy({
-      pendingGrowthPx: 126,
-      pinFloorPx: 11.77,
-      hasActiveCollapseIntent: true,
-    })).toBe('wait-for-collapse');
-    expect(resolveStickyPinGrowthSettlementStrategy({
-      pendingGrowthPx: 126,
-      pinFloorPx: 11.77,
-      hasActiveCollapseIntent: false,
-    })).toBe('settle-now');
-  });
-
-  it('selects an explicit settlement strategy for each collapse viewport owner', () => {
-    const stickyReservation = {
-      collapse: { kind: 'collapse' as const, px: 152.7, floorPx: 67.7 },
-      pin: {
-        kind: 'pin' as const,
-        px: 674.6,
-        floorPx: 674.6,
-        mode: 'sticky-latest' as const,
-        targetTurnId: 'turn-a',
-      },
-    };
-
-    expect(resolveCollapseIntentSettlementStrategy({
-      coordinatorMode: 'pinned-item',
-      isFollowingOutput: false,
-      isStreamingOutput: true,
-      reservation: stickyReservation,
-    })).toBe('reconcile-sticky-pin');
-    expect(resolveCollapseIntentSettlementStrategy({
-      coordinatorMode: 'following-tail',
-      isFollowingOutput: true,
-      isStreamingOutput: true,
-      reservation: stickyReservation,
-    })).toBe('retain-following-tail');
-    expect(resolveCollapseIntentSettlementStrategy({
-      coordinatorMode: 'preserving-element',
-      isFollowingOutput: false,
-      isStreamingOutput: true,
-      reservation: stickyReservation,
-    })).toBe('settle-preserved-element');
-    expect(resolveCollapseIntentSettlementStrategy({
-      coordinatorMode: 'idle',
-      isFollowingOutput: false,
-      isStreamingOutput: true,
-      reservation: stickyReservation,
-    })).toBe('settle-protected-viewport');
-    expect(resolveCollapseIntentSettlementStrategy({
-      coordinatorMode: 'idle',
-      isFollowingOutput: false,
-      isStreamingOutput: true,
-      reservation: {
-        ...stickyReservation,
-        collapse: { ...stickyReservation.collapse, floorPx: 0 },
-      },
-    })).toBe('drain');
-  });
-
-  it('lets known streaming collapses reconcile without bypassing active intents', () => {
-    expect(shouldBypassShrinkCompensationInTailFollow({
-      isFollowingOutput: true,
-      isStreamingOutput: true,
-      hasActiveCollapseIntent: false,
-    })).toBe(true);
-    expect(shouldBypassShrinkCompensationInTailFollow({
-      isFollowingOutput: true,
-      isStreamingOutput: true,
-      hasActiveCollapseIntent: true,
-    })).toBe(false);
-  });
-
-  it('recovers the last stable scroll position when an auto collapse arrives after clamp', () => {
-    expect(resolveAutoCollapseAnchorScrollTop({
-      currentScrollTop: 1127.33,
-      previousStableScrollTop: 1302.67,
-      reason: 'auto',
-      isFollowingOutput: true,
-      isStreamingOutput: true,
-    })).toBe(1302.67);
-    expect(resolveAutoCollapseAnchorScrollTop({
-      currentScrollTop: 1127.33,
-      previousStableScrollTop: 1302.67,
-      reason: 'manual',
-      isFollowingOutput: true,
-      isStreamingOutput: true,
-    })).toBe(1127.33);
-    expect(resolveAutoCollapseAnchorScrollTop({
-      currentScrollTop: 1127.33,
-      previousStableScrollTop: 1302.67,
-      reason: 'auto',
-      isFollowingOutput: false,
-      isStreamingOutput: true,
-    })).toBe(1127.33);
-  });
-
-  it('resets viewport-local at-bottom state when the active session changes', () => {
-    stateMocks.activeSession = createSession('session-a', 'turn-a');
-    stateMocks.virtualItems = [createItem('turn-a')];
-
-    act(() => {
-      root.render(<VirtualMessageList />);
-    });
-
-    expect(container.querySelector('[data-testid="scroll-to-latest"]')?.getAttribute('data-visible')).toBe('true');
-
-    stateMocks.activeSession = createSession('session-b', 'turn-b');
-    stateMocks.virtualItems = [createItem('turn-b')];
-
-    act(() => {
-      root.render(<VirtualMessageList />);
-    });
-
-    expect(container.querySelector('[data-testid="scroll-to-latest"]')?.getAttribute('data-visible')).toBe('false');
-  });
-
-  it('resumes tail follow when a mounted streaming session receives its initial items', () => {
-    const session = createSession('session-a', 'turn-a');
-    session.dialogTurns[0].status = 'processing';
-    session.dialogTurns[0].modelRounds = [{
-      id: 'round-turn-a',
-      status: 'streaming',
-      isStreaming: true,
-      items: [],
-      startTime: 1,
-    } as typeof session.dialogTurns[number]['modelRounds'][number]];
-    stateMocks.activeSession = session;
-    stateMocks.virtualItems = [];
-
-    act(() => {
-      root.render(<VirtualMessageList />);
-    });
-    virtuosoMocks.scrollerScrollTo.mockClear();
-
-    stateMocks.virtualItems = [createItem('turn-a'), createModelItem('turn-a')];
-    act(() => {
-      root.render(<VirtualMessageList />);
-    });
-
-    expect(virtuosoMocks.scrollerScrollTo).toHaveBeenCalledWith(expect.objectContaining({
-      behavior: 'auto',
-    }));
-  });
-
-  it('restores a following-tail collapse anchor when delayed measurement clamps scrollTop', () => {
-    const session = createSession('session-a', 'turn-a');
-    session.dialogTurns[0].status = 'processing';
-    session.dialogTurns[0].modelRounds = [{
-      id: 'round-turn-a',
-      status: 'streaming',
-      isStreaming: true,
-      items: [],
-      startTime: 1,
-    } as typeof session.dialogTurns[number]['modelRounds'][number]];
-    stateMocks.activeSession = session;
-    stateMocks.virtualItems = [createItem('turn-a'), createModelItem('turn-a')];
-
-    act(() => {
-      root.render(<VirtualMessageList />);
-    });
-
-    const scroller = container.querySelector<HTMLElement>('[data-virtuoso-scroller="true"]');
-    const footer = container.querySelector<HTMLElement>('.message-list-footer');
-    const anchor = container.querySelector<HTMLElement>('[data-turn-id="turn-a"]');
-    expect(scroller).not.toBeNull();
-    expect(footer).not.toBeNull();
-    expect(anchor).not.toBeNull();
-    if (!scroller || !footer || !anchor) {
-      return;
-    }
-
-    let contentHeight = 2_076;
-    Object.defineProperties(scroller, {
-      clientHeight: { configurable: true, value: 1_000 },
-      scrollHeight: {
-        configurable: true,
-        get: () => contentHeight + (Number.parseFloat(footer.style.height) || 0),
-      },
-      scrollTop: { configurable: true, writable: true, value: 1_100 },
-    });
-    const footerHeightBeforeCollapse = Number.parseFloat(footer.style.height);
-    act(() => {
-      scroller.dispatchEvent(new Event('scroll', { bubbles: true }));
-    });
-
-    act(() => {
-      window.dispatchEvent(new CustomEvent('flowchat:tool-card-collapse-intent', {
-        detail: {
-          toolId: 'tool-a',
-          toolName: 'Write',
-          cardHeight: 200,
-          anchorElement: anchor,
-          reason: 'auto',
-        },
-      }));
-    });
-    expect(Number.parseFloat(footer.style.height)).toBeCloseTo(
-      footerHeightBeforeCollapse + 100,
-      2,
-    );
-
-    contentHeight -= 250;
-    scroller.scrollTop = 1_050;
-    act(() => {
-      scroller.dispatchEvent(new Event('scroll', { bubbles: true }));
-    });
-
-    expect(scroller.scrollTop).toBe(1_100);
-    expect(Number.parseFloat(footer.style.height)).toBeCloseTo(
-      footerHeightBeforeCollapse + 151,
-      2,
-    );
-  });
-
-  it('recovers a late following-tail shrink clamp after collapse protection was released', () => {
-    flowDiagnosticsMocks.enabled = true;
-    const session = createSession('session-a', 'turn-a');
-    session.dialogTurns[0].status = 'processing';
-    session.dialogTurns[0].modelRounds = [{
-      id: 'round-turn-a',
-      status: 'streaming',
-      isStreaming: true,
-      items: [],
-      startTime: 1,
-    } as typeof session.dialogTurns[number]['modelRounds'][number]];
-    stateMocks.activeSession = session;
-    stateMocks.virtualItems = [createItem('turn-a'), createModelItem('turn-a')];
-
-    act(() => {
-      root.render(<VirtualMessageList />);
-    });
-
-    const scroller = container.querySelector<HTMLElement>('[data-virtuoso-scroller="true"]');
-    const footer = container.querySelector<HTMLElement>('.message-list-footer');
-    expect(scroller).not.toBeNull();
-    expect(footer).not.toBeNull();
-    if (!scroller || !footer) {
-      return;
-    }
-
-    let contentHeight = 2_076;
-    Object.defineProperties(scroller, {
-      clientHeight: { configurable: true, value: 1_000 },
-      scrollHeight: {
-        configurable: true,
-        get: () => contentHeight + (Number.parseFloat(footer.style.height) || 0),
-      },
-      scrollTop: { configurable: true, writable: true, value: 0 },
-    });
-    const footerHeightBeforeClamp = Number.parseFloat(footer.style.height);
-    const stableScrollTop = scroller.scrollHeight - scroller.clientHeight;
-    scroller.scrollTop = stableScrollTop;
-    act(() => {
-      window.dispatchEvent(new Event('resize'));
-    });
-
-    contentHeight -= 250;
-    scroller.scrollTop = scroller.scrollHeight - scroller.clientHeight;
-    act(() => {
-      scroller.dispatchEvent(new Event('scroll', { bubbles: true }));
-    });
-
-    expect(scroller.scrollTop).toBe(stableScrollTop);
-    expect(Number.parseFloat(footer.style.height)).toBeCloseTo(
-      footerHeightBeforeClamp + 251,
-      2,
-    );
-    expect(flowDiagnosticsMocks.trace).toHaveBeenCalledWith(expect.objectContaining({
-      location: 'VirtualMessageList.handleScroll',
-      message: 'Following-tail shrink clamp recovered as a viewport transaction',
-    }));
-  });
-
-  it('retains following-tail collapse protection after the animation finalizer', () => {
-    flowDiagnosticsMocks.enabled = true;
-    const session = createSession('session-a', 'turn-a');
-    session.dialogTurns[0].status = 'processing';
-    session.dialogTurns[0].modelRounds = [{
-      id: 'round-turn-a',
-      status: 'streaming',
-      isStreaming: true,
-      items: [],
-      startTime: 1,
-    } as typeof session.dialogTurns[number]['modelRounds'][number]];
-    stateMocks.activeSession = session;
-    stateMocks.virtualItems = [createItem('turn-a'), createModelItem('turn-a')];
-
-    act(() => {
-      root.render(<VirtualMessageList />);
-    });
-
-    const scroller = container.querySelector<HTMLElement>('[data-virtuoso-scroller="true"]');
-    const footer = container.querySelector<HTMLElement>('.message-list-footer');
-    const anchor = container.querySelector<HTMLElement>('[data-turn-id="turn-a"]');
-    expect(scroller).not.toBeNull();
-    expect(footer).not.toBeNull();
-    expect(anchor).not.toBeNull();
-    if (!scroller || !footer || !anchor) {
-      return;
-    }
-
-    let contentHeight = 2_076;
-    Object.defineProperties(scroller, {
-      clientHeight: { configurable: true, value: 1_000 },
-      scrollHeight: {
-        configurable: true,
-        get: () => contentHeight + (Number.parseFloat(footer.style.height) || 0),
-      },
-      scrollTop: { configurable: true, writable: true, value: 1_100 },
-    });
-    const footerHeightBeforeCollapse = Number.parseFloat(footer.style.height);
-    act(() => {
-      scroller.dispatchEvent(new Event('scroll', { bubbles: true }));
-    });
-
-    vi.useFakeTimers();
-    try {
-      act(() => {
-        window.dispatchEvent(new CustomEvent('flowchat:tool-card-collapse-intent', {
-          detail: {
-            toolId: 'tool-a',
-            toolName: 'Write',
-            cardHeight: 200,
-            anchorElement: anchor,
-            reason: 'auto',
-          },
-        }));
-      });
-      expect(Number.parseFloat(footer.style.height)).toBeCloseTo(
-        footerHeightBeforeCollapse + 100,
-        2,
-      );
-
-      rafCallbacks = [];
-      act(() => {
-        vi.advanceTimersByTime(300);
-      });
-      for (let frame = 0; frame < 4; frame += 1) {
-        flushAnimationFrame();
-      }
-      const provisionalFooterHeight = Number.parseFloat(footer.style.height);
-      expect(provisionalFooterHeight).toBeCloseTo(
-        footerHeightBeforeCollapse + 100,
-        2,
-      );
-      const findRetainTrace = () => flowDiagnosticsMocks.trace.mock.calls.find(([event]) => (
-        event.location === 'VirtualMessageList.retainCollapseRangeForQuietSettlement'
-      ));
-      if (!findRetainTrace()) {
-        act(() => {
-          vi.advanceTimersByTime(1_000);
-        });
-      }
-      expect(findRetainTrace()).toBeDefined();
-
-      act(() => {
-        vi.advanceTimersByTime(120);
-      });
-      for (let frame = 0; frame < 4; frame += 1) {
-        flushAnimationFrame();
-      }
-      const settledFooterHeight = Number.parseFloat(footer.style.height);
-      const settleTrace = flowDiagnosticsMocks.trace.mock.calls.find(([event]) => (
-        event.location === 'VirtualMessageList.settleRetainedCollapseRange'
-      ));
-      expect(settleTrace).toBeDefined();
-      expect(settledFooterHeight).toBeLessThan(provisionalFooterHeight);
-      expect(scroller.scrollTop).toBe(1_100);
-
-      stateMocks.activeSession = {
-        ...session,
-        dialogTurns: session.dialogTurns.map(turn => ({
-          ...turn,
-          status: 'completed',
-          modelRounds: turn.modelRounds.map(round => ({
-            ...round,
-            status: 'completed',
-            isStreaming: false,
-          })),
-        })),
-      };
-      act(() => {
-        root.render(<VirtualMessageList />);
-      });
-      expect(Number.parseFloat(footer.style.height)).toBeCloseTo(settledFooterHeight, 2);
-
-      contentHeight -= 250;
-      scroller.scrollTop = 1_050;
-      act(() => {
-        scroller.dispatchEvent(new Event('scroll', { bubbles: true }));
-      });
-
-      expect(scroller.scrollTop).toBe(1_100);
-      expect(Number.parseFloat(footer.style.height)).toBeGreaterThan(settledFooterHeight);
-
-      act(() => {
-        vi.advanceTimersByTime(120);
-      });
-      for (let frame = 0; frame < 4; frame += 1) {
-        flushAnimationFrame();
-      }
-      const wasSettledAnchorReleased = () => flowDiagnosticsMocks.trace.mock.calls.some(([event]) => (
-        event.location === 'VirtualMessageList.releaseSettledCollapseAnchor'
-      ));
-      for (let attempt = 0; attempt < 3 && !wasSettledAnchorReleased(); attempt += 1) {
-        act(() => {
-          vi.runOnlyPendingTimers();
-        });
-        for (let frame = 0; frame < 4; frame += 1) {
-          flushAnimationFrame();
-        }
-      }
-      expect(wasSettledAnchorReleased()).toBe(true);
-    } finally {
-      vi.useRealTimers();
-    }
-  });
-
-  it('keeps the initial Virtuoso position when background updates arrive after an upward scroll', () => {
-    let nowMs = 1_000;
-    const nowSpy = vi.spyOn(performance, 'now').mockImplementation(() => nowMs);
-
-    try {
-      stateMocks.activeSession = createSessionWithTurns('session-a', ['turn-a', 'turn-b'], {
-        isHistorical: false,
-        historyState: 'ready',
-        contextRestoreState: 'pending',
-        isPartial: true,
-      });
-      stateMocks.virtualItems = [createItem('turn-a'), createItem('turn-b')];
-
-      act(() => {
-        root.render(<VirtualMessageList />);
-      });
-
-      const scroller = container.querySelector<HTMLElement>('[data-virtuoso-scroller="true"]');
-      expect(scroller).not.toBeNull();
-      if (!scroller) {
-        return;
-      }
-
-      setScrollerGeometry(scroller, {
-        scrollHeight: 5_000,
-        clientHeight: 1_000,
-        scrollTop: 4_000,
-      });
-
-      act(() => {
-        scroller.dispatchEvent(new Event('scroll', { bubbles: true }));
-      });
-
-      act(() => {
-        scroller.dispatchEvent(new WheelEvent('wheel', {
-          deltaY: -720,
-          bubbles: true,
-        }));
-        scroller.scrollTop = 1_800;
-        scroller.dispatchEvent(new Event('scroll', { bubbles: true }));
-      });
-      flushAnimationFrame();
-      expect(scroller.scrollTop).toBe(1_800);
-
-      nowMs = 2_000;
-      stateMocks.activeSession = createSessionWithTurns('session-a', ['turn-a', 'turn-b', 'turn-c'], {
-        isHistorical: false,
-        historyState: 'ready',
-        contextRestoreState: 'pending',
-        isPartial: true,
-      });
-      stateMocks.virtualItems = [createItem('turn-a'), createItem('turn-b'), createItem('turn-c')];
-
-      act(() => {
-        root.render(<VirtualMessageList />);
-      });
-
-      expect(scroller.scrollTop).toBe(1_800);
-    } finally {
-      nowSpy.mockRestore();
-    }
-  });
-
-  it('materializes an unrendered turn with an immediate auto index jump', () => {
-    const listRef = React.createRef<VirtualMessageListRef>();
-    const turnIds = Array.from(
-      { length: 24 },
-      (_, index) => `turn-${String(index + 1).padStart(2, '0')}`,
-    );
-    const targetTurnId = 'turn-02';
-
-    stateMocks.activeSession = createSessionWithTurns('session-a', turnIds);
-    stateMocks.virtualItems = turnIds.flatMap(turnId => [
-      createItem(turnId),
-      createModelItem(turnId),
-    ]);
-    virtuosoMocks.renderedRange = { start: 40, end: 48 };
-
-    act(() => {
-      root.render(<VirtualMessageList ref={listRef} />);
-    });
-
-    const scroller = container.querySelector<HTMLElement>('[data-virtuoso-scroller="true"]');
-    expect(scroller).not.toBeNull();
-    if (!scroller) {
-      return;
-    }
-    setScrollerGeometry(scroller, {
-      scrollHeight: 6_000,
-      clientHeight: 1_000,
-      scrollTop: 4_000,
-    });
-
-    expect(
-      container.querySelector(
-        `[data-turn-id="${targetTurnId}"][data-item-type="user-message"]`,
-      ),
-    ).toBeNull();
-    virtuosoMocks.scrollToIndex.mockClear();
-
-    let status: ReturnType<VirtualMessageListRef['pinTurnToTopWithStatus']> = 'rejected';
-    act(() => {
-      status = listRef.current?.pinTurnToTopWithStatus(targetTurnId, {
-        behavior: 'smooth',
-        pinMode: 'transient',
-      }) ?? 'rejected';
-    });
-
-    expect(status).toBe('pending');
-    expect(virtuosoMocks.scrollToIndex).toHaveBeenCalledWith(expect.objectContaining({
-      index: 2,
-      align: 'start',
-      behavior: 'auto',
-    }));
-    expect(virtuosoMocks.increaseViewportBy).toEqual({
-      top: 2_000,
-      bottom: 2_000,
-    });
-
-    const target = container.querySelector<HTMLElement>(
-      `[data-turn-id="${targetTurnId}"][data-item-type="user-message"]`,
-    );
-    expect(target).not.toBeNull();
-    if (!target) {
-      return;
-    }
-
-    vi.spyOn(scroller, 'getBoundingClientRect').mockReturnValue(createRect({
-      top: 0,
-      bottom: 1_000,
-      height: 1_000,
-    }));
-    const targetDocumentTop = 4_500;
-    vi.spyOn(target, 'getBoundingClientRect').mockImplementation(() => {
-      const top = targetDocumentTop - scroller.scrollTop;
-      return createRect({
-        top,
-        bottom: top + 40,
-        height: 40,
-      });
-    });
-
-    flushAnimationFrame();
-    flushAnimationFrame();
-    flushAnimationFrame();
-    flushAnimationFrame();
-    expect(scroller.scrollTop).toBe(4_443);
-    expect(target.getBoundingClientRect().top).toBe(57);
-    expect(virtuosoMocks.scrollToIndex).toHaveBeenCalledTimes(1);
-    expect(virtuosoMocks.increaseViewportBy).toEqual({
-      top: 600,
-      bottom: 600,
-    });
-  });
-
-  it('materializes the first turn before pinning when it is outside the rendered range', () => {
-    const listRef = React.createRef<VirtualMessageListRef>();
-    const turnIds = Array.from(
-      { length: 9 },
-      (_, index) => `turn-${String(index + 1).padStart(2, '0')}`,
-    );
-
-    stateMocks.activeSession = createSessionWithTurns('session-a', turnIds);
-    stateMocks.virtualItems = turnIds.flatMap(turnId => [
-      createItem(turnId),
-      createModelItem(turnId),
-    ]);
-    virtuosoMocks.renderedRange = { start: 12, end: 18 };
-
-    act(() => {
-      root.render(<VirtualMessageList ref={listRef} />);
-    });
-
-    expect(virtuosoMocks.initialTopMostItemIndexHistory).toContainEqual({
-      index: 17,
-      align: 'end',
-    });
-    expect(virtuosoMocks.initialTopMostItemIndex).toBeUndefined();
-    expect(container.querySelector(
-      '[data-turn-id="turn-01"][data-item-type="user-message"]',
-    )).toBeNull();
-    virtuosoMocks.scrollToIndex.mockClear();
-    const navigationRenderStart = virtuosoMocks.initialTopMostItemIndexHistory.length;
-
-    let status: ReturnType<VirtualMessageListRef['pinTurnToTopWithStatus']> = 'rejected';
-    act(() => {
-      status = listRef.current?.pinTurnToTopWithStatus('turn-01', {
-        behavior: 'auto',
-        pinMode: 'transient',
-      }) ?? 'rejected';
-    });
-
-    expect(status).toBe('pending');
-    expect(virtuosoMocks.scrollToIndex).toHaveBeenCalledWith(expect.objectContaining({
-      index: 0,
-      align: 'start',
-      behavior: 'auto',
-    }));
-    expect(virtuosoMocks.initialTopMostItemIndex).toBeUndefined();
-    const navigationInitialPositionProps =
-      virtuosoMocks.initialTopMostItemIndexHistory.slice(navigationRenderStart);
-    expect(navigationInitialPositionProps.length).toBeGreaterThan(0);
-    expect(navigationInitialPositionProps.every(value => value === undefined)).toBe(true);
-    expect(container.querySelector(
-      '[data-turn-id="turn-01"][data-item-type="user-message"]',
-    )).not.toBeNull();
-  });
-
-  it('settles best-effort navigation at the natural maximum without pin footer space', () => {
-    const listRef = React.createRef<VirtualMessageListRef>();
-    stateMocks.activeSession = createSessionWithTurns('session-a', ['turn-a', 'turn-b']);
-    stateMocks.virtualItems = [createItem('turn-a'), createItem('turn-b')];
-
-    act(() => {
-      root.render(<VirtualMessageList ref={listRef} />);
-    });
-
-    const scroller = container.querySelector<HTMLElement>('[data-virtuoso-scroller="true"]');
-    const footer = container.querySelector<HTMLElement>('.message-list-footer');
-    const target = container.querySelector<HTMLElement>(
-      '[data-turn-id="turn-b"][data-item-type="user-message"]',
-    );
-    expect(scroller).not.toBeNull();
-    expect(footer).not.toBeNull();
-    expect(target).not.toBeNull();
-    if (!scroller || !footer || !target) {
-      return;
-    }
-
-    setScrollerGeometry(scroller, {
-      scrollHeight: 1_200,
-      clientHeight: 1_000,
-      scrollTop: 0,
-    });
-    vi.spyOn(scroller, 'getBoundingClientRect').mockReturnValue(createRect({
-      top: 0,
-      bottom: 1_000,
-      height: 1_000,
-    }));
-    vi.spyOn(target, 'getBoundingClientRect').mockImplementation(() => {
-      const top = 900 - scroller.scrollTop;
-      return createRect({ top, bottom: top + 40, height: 40 });
-    });
-    const footerHeightBefore = footer.style.height;
-
-    let status: ReturnType<VirtualMessageListRef['pinTurnToTopWithStatus']> = 'rejected';
-    act(() => {
-      status = listRef.current?.pinTurnToTopWithStatus('turn-b', {
-        behavior: 'auto',
-        pinMode: 'transient',
-        alignmentPolicy: 'best-effort',
-      }) ?? 'rejected';
-    });
-
-    expect(status).toBe('settled');
-    expect(scroller.scrollTop).toBe(200);
-    expect(footer.style.height).toBe(footerHeightBefore);
-    expect(target.getBoundingClientRect().top).toBeGreaterThan(57);
-  });
-
-  it('keeps sticky-latest exact even when a best-effort policy is supplied', () => {
-    const listRef = React.createRef<VirtualMessageListRef>();
-    stateMocks.activeSession = createSessionWithTurns('session-a', ['turn-a', 'turn-b']);
-    const latestTurn = stateMocks.activeSession.dialogTurns[1];
-    latestTurn.status = 'processing';
-    latestTurn.modelRounds = [{
-      id: 'round-turn-b',
-      status: 'streaming',
-      isStreaming: true,
-      items: [],
-      startTime: 1,
-    } as typeof latestTurn.modelRounds[number]];
-    stateMocks.virtualItems = [createItem('turn-a'), createItem('turn-b')];
-
-    act(() => {
-      root.render(<VirtualMessageList ref={listRef} />);
-    });
-
-    const scroller = container.querySelector<HTMLElement>('[data-virtuoso-scroller="true"]');
-    const footer = container.querySelector<HTMLElement>('.message-list-footer');
-    const target = container.querySelector<HTMLElement>(
-      '[data-turn-id="turn-b"][data-item-type="user-message"]',
-    );
-    expect(scroller).not.toBeNull();
-    expect(footer).not.toBeNull();
-    expect(target).not.toBeNull();
-    if (!scroller || !footer || !target) {
-      return;
-    }
-
-    Object.defineProperties(scroller, {
-      clientHeight: { configurable: true, value: 1_000 },
-      scrollHeight: {
-        configurable: true,
-        get: () => 1_200 + (Number.parseFloat(footer.style.height) || 0),
-      },
-      scrollTop: { configurable: true, writable: true, value: 200 },
-    });
-    vi.spyOn(scroller, 'getBoundingClientRect').mockReturnValue(createRect({
-      top: 0,
-      bottom: 1_000,
-      height: 1_000,
-    }));
-    vi.spyOn(target, 'getBoundingClientRect').mockImplementation(() => {
-      const top = 700 - scroller.scrollTop;
-      return createRect({ top, bottom: top + 40, height: 40 });
-    });
-
-    let status: ReturnType<VirtualMessageListRef['pinTurnToTopWithStatus']> = 'rejected';
-    act(() => {
-      status = listRef.current?.pinTurnToTopWithStatus('turn-b', {
-        behavior: 'auto',
-        pinMode: 'sticky-latest',
-        alignmentPolicy: 'best-effort',
-      }) ?? 'rejected';
-    });
-
-    expect(status).toBe('settled');
-    expect(Number.parseFloat(footer.style.height)).toBeGreaterThan(0);
-    expect(target.getBoundingClientRect().top).toBe(57);
-  });
-
-  it('uses a prepared turn only for the initial Virtuoso mount', () => {
-    const listRef = React.createRef<VirtualMessageListRef>();
-    const turnIds = ['turn-01', 'turn-02', 'turn-03'];
-
-    stateMocks.activeSession = createSessionWithTurns('session-a', turnIds);
-    stateMocks.virtualItems = [];
-
-    act(() => {
-      root.render(<VirtualMessageList ref={listRef} />);
-    });
-    act(() => {
-      listRef.current?.prepareTurnPinToTop('turn-02', {
-        behavior: 'auto',
-        pinMode: 'transient',
-      });
-    });
-
-    virtuosoMocks.initialTopMostItemIndexHistory = [];
-    stateMocks.virtualItems = turnIds.flatMap(turnId => [
-      createItem(turnId),
-      createModelItem(turnId),
-    ]);
-    act(() => {
-      root.render(<VirtualMessageList ref={listRef} />);
-    });
-
-    expect(virtuosoMocks.initialTopMostItemIndexHistory).toContainEqual({
-      index: 2,
-      align: 'start',
-    });
-    expect(virtuosoMocks.initialTopMostItemIndex).toBeUndefined();
-  });
-
-  it('keeps the existing sticky range while a distant turn is materialized', () => {
-    const listRef = React.createRef<VirtualMessageListRef>();
-    const turnIds = Array.from({ length: 24 }, (_, index) => `turn-${String(index + 1).padStart(2, '0')}`);
-    const latestTurnId = turnIds[turnIds.length - 1];
-    const targetTurnId = turnIds[1];
-    const session = createSessionWithTurns('session-a', turnIds);
-    const latestTurn = session.dialogTurns[session.dialogTurns.length - 1];
-    latestTurn.status = 'processing';
-    latestTurn.modelRounds = [{
-      id: `round-${latestTurnId}`,
-      status: 'streaming',
-      isStreaming: true,
-      items: [],
-      startTime: 1,
-    } as typeof latestTurn.modelRounds[number]];
-    stateMocks.activeSession = session;
-    stateMocks.virtualItems = turnIds.flatMap(turnId => [
-      createItem(turnId),
-      createModelItem(turnId),
-    ]);
-    virtuosoMocks.renderedRange = { start: 40, end: 48 };
-
-    act(() => {
-      root.render(<VirtualMessageList ref={listRef} />);
-    });
-
-    const scroller = container.querySelector<HTMLElement>('[data-virtuoso-scroller="true"]');
-    const footer = container.querySelector<HTMLElement>('.message-list-footer');
-    const latestTarget = container.querySelector<HTMLElement>(
-      `[data-turn-id="${latestTurnId}"][data-item-type="user-message"]`,
-    );
-    expect(scroller).not.toBeNull();
-    expect(footer).not.toBeNull();
-    expect(latestTarget).not.toBeNull();
-    if (!scroller || !footer || !latestTarget) {
-      return;
-    }
-
-    Object.defineProperties(scroller, {
-      clientHeight: { configurable: true, value: 1_000 },
-      scrollHeight: {
-        configurable: true,
-        get: () => 1_200 + (Number.parseFloat(footer.style.height) || 0),
-      },
-      scrollTop: { configurable: true, writable: true, value: 200 },
-    });
-    vi.spyOn(scroller, 'getBoundingClientRect').mockReturnValue(createRect({
-      top: 0,
-      bottom: 1_000,
-      height: 1_000,
-    }));
-    const latestTargetDocumentTop = 700;
-    vi.spyOn(latestTarget, 'getBoundingClientRect').mockImplementation(() => {
-      const top = latestTargetDocumentTop - scroller.scrollTop;
-      return createRect({ top, bottom: top + 40, height: 40 });
-    });
-
-    let latestPinStatus: ReturnType<VirtualMessageListRef['pinTurnToTopWithStatus']> = 'rejected';
-    act(() => {
-      latestPinStatus = listRef.current?.pinTurnToTopWithStatus(latestTurnId, {
-        behavior: 'auto',
-        pinMode: 'sticky-latest',
-      }) ?? 'rejected';
-    });
-    expect(latestPinStatus).toBe('settled');
-    const stickyFooterHeight = Number.parseFloat(footer.style.height);
-    expect(stickyFooterHeight).toBeGreaterThan(0);
-
-    virtuosoMocks.scrollToIndex.mockClear();
-    let targetPinStatus: ReturnType<VirtualMessageListRef['pinTurnToTopWithStatus']> = 'rejected';
-    act(() => {
-      targetPinStatus = listRef.current?.pinTurnToTopWithStatus(targetTurnId, {
-        behavior: 'auto',
-        pinMode: 'transient',
-      }) ?? 'rejected';
-    });
-
-    expect(targetPinStatus).toBe('pending');
-    expect(Number.parseFloat(footer.style.height)).toBe(stickyFooterHeight);
-    expect(virtuosoMocks.scrollToIndex).toHaveBeenCalledWith(expect.objectContaining({
-      align: 'start',
-      behavior: 'auto',
-    }));
-
-    const target = container.querySelector<HTMLElement>(
-      `[data-turn-id="${targetTurnId}"][data-item-type="user-message"]`,
-    );
-    expect(target).not.toBeNull();
-    if (!target) {
-      return;
-    }
-    const targetDocumentTop = 800;
-    vi.spyOn(target, 'getBoundingClientRect').mockImplementation(() => {
-      const top = targetDocumentTop - scroller.scrollTop;
-      return createRect({ top, bottom: top + 40, height: 40 });
-    });
-
-    act(() => {
-      virtuosoMocks.rangeChanged?.();
-    });
-
-    expect(target.getBoundingClientRect().top).toBe(57);
-    expect(Number.parseFloat(footer.style.height)).toBeGreaterThan(0);
-  });
-
-  it('routes turn navigation through Virtuoso while the initial snapshot is visible', () => {
-    const listRef = React.createRef<VirtualMessageListRef>();
-    const turnIds = Array.from({ length: 8 }, (_, index) => `turn-${index}`);
-    const targetTurnId = 'turn-1';
-    stateMocks.activeSession = createSessionWithTurns('session-a', turnIds, {
-      contextRestoreState: 'pending',
-      isPartial: true,
-      historyState: 'ready',
-    });
-    stateMocks.virtualItems = turnIds.flatMap(turnId => [
-      createItem(turnId),
-      createModelItem(turnId),
-    ]);
-    virtuosoMocks.renderedRange = { start: 12, end: 16 };
-
-    act(() => {
-      root.render(<VirtualMessageList ref={listRef} />);
-    });
-    expect(container.querySelector('[data-testid="virtuoso"]')).not.toBeNull();
-    expect(container.querySelector('[data-initial-history-snapshot="true"]')).not.toBeNull();
-    virtuosoMocks.scrollToIndex.mockClear();
-
-    let status: ReturnType<VirtualMessageListRef['pinTurnToTopWithStatus']> = 'rejected';
-    act(() => {
-      status = listRef.current?.pinTurnToTopWithStatus(targetTurnId, {
-        behavior: 'smooth',
-        pinMode: 'transient',
-      }) ?? 'rejected';
-    });
-
-    expect(status).toBe('pending');
-    expect(virtuosoMocks.scrollToIndex).toHaveBeenCalledWith(expect.objectContaining({
-      index: 2,
-      align: 'start',
-      behavior: 'auto',
-    }));
-    expect(container.querySelector('[data-history-projection-handoff="true"]')?.getAttribute(
-      'data-target-turn-id',
-    )).toBe(targetTurnId);
-  });
-
-  it('releases the initial snapshot after Virtuoso renders readable target content', () => {
-    stateMocks.activeSession = createSessionWithTurns('session-a', ['turn-a', 'turn-b'], {
-      contextRestoreState: 'pending',
-      isPartial: true,
-      historyState: 'ready',
-    });
-    stateMocks.virtualItems = [createItem('turn-a'), createItem('turn-b')];
-
-    act(() => {
-      root.render(<VirtualMessageList />);
-    });
-
-    expect(container.querySelector('[data-testid="virtuoso"]')).not.toBeNull();
-    expect(container.querySelector('[data-initial-history-snapshot="true"]')).not.toBeNull();
-
-    const scroller = container.querySelector<HTMLElement>('[data-testid="virtuoso"]');
-    const target = scroller?.querySelector<HTMLElement>(
-      '[data-turn-id="turn-b"][data-item-type="user-message"]',
-    );
-    expect(scroller).not.toBeNull();
-    expect(target).not.toBeNull();
-    if (!scroller || !target) {
-      return;
-    }
-    vi.spyOn(scroller, 'getBoundingClientRect').mockReturnValue(createRect({
-      top: 0,
-      bottom: 1_000,
-      height: 1_000,
-    }));
-    vi.spyOn(target, 'getBoundingClientRect').mockReturnValue(createRect({
-      top: 200,
-      bottom: 240,
-      width: 400,
-      height: 40,
-    }));
-    Object.defineProperty(target, 'innerText', {
-      configurable: true,
-      value: 'turn-b',
-    });
-
-    for (let frame = 0; frame < 5; frame += 1) {
-      flushAnimationFrame();
-    }
-
-    expect(container.querySelector('[data-initial-history-snapshot="true"]')).toBeNull();
-    expect(container.querySelector('[data-testid="virtuoso"]')).not.toBeNull();
-  });
-
-  it('does not render an initial projection handoff over a history-window presentation', () => {
-    stateMocks.activeSession = createSessionWithTurns('session-a', ['turn-a', 'turn-b'], {
-      contextRestoreState: 'pending',
-      isPartial: true,
-      historyState: 'ready',
-    });
-    const tailItems = [createItem('turn-a'), createItem('turn-b')];
-    stateMocks.virtualItems = tailItems;
-
-    act(() => {
-      root.render(<VirtualMessageList items={tailItems} />);
-    });
-    expect(container.querySelector('[data-history-projection-handoff="true"]')).not.toBeNull();
-
-    const historyItems = [
-      createItem('turn-a'),
-      createModelItem('turn-a'),
-      createItem('turn-b'),
-      createModelItem('turn-b'),
-    ];
-    act(() => {
-      root.render(
-        <VirtualMessageList
-          items={historyItems}
-          presentationMode="history-window"
-          historyWindow={{
-            startOrdinal: 0,
-            endOrdinalExclusive: 2,
-            targetTurnId: 'turn-a',
-            mode: 'history-window',
-          }}
-          presentationRevision={1}
-        />,
-      );
-    });
-
-    expect(container.querySelector('[data-history-projection-handoff="true"]')).toBeNull();
-    expect(container.querySelector('[data-testid="virtuoso"]')).not.toBeNull();
-  });
-
-  it('does not let a canceled pending sticky pin RAF restore provisional footer space', () => {
-    const listRef = React.createRef<VirtualMessageListRef>();
-    const turnIds = Array.from(
-      { length: 24 },
-      (_, index) => `turn-${String(index + 1).padStart(2, '0')}`,
-    );
-    const latestTurnId = turnIds[turnIds.length - 1];
-    const session = createSessionWithTurns('session-a', turnIds);
-    const latestTurn = session.dialogTurns[session.dialogTurns.length - 1];
-    latestTurn.status = 'processing';
-    latestTurn.modelRounds = [{
-      id: `round-${latestTurnId}`,
-      status: 'streaming',
-      isStreaming: true,
-      items: [],
-      startTime: 1,
-    } as typeof latestTurn.modelRounds[number]];
-    stateMocks.activeSession = session;
-    stateMocks.virtualItems = turnIds.flatMap(turnId => [
-      createItem(turnId),
-      createModelItem(turnId),
-    ]);
-    virtuosoMocks.renderedRange = { start: 0, end: 4 };
-
-    act(() => {
-      root.render(<VirtualMessageList ref={listRef} />);
-    });
-
-    const scroller = container.querySelector<HTMLElement>('[data-virtuoso-scroller="true"]');
-    const footer = container.querySelector<HTMLElement>('.message-list-footer');
-    expect(scroller).not.toBeNull();
-    expect(footer).not.toBeNull();
-    if (!scroller || !footer) {
-      return;
-    }
-
-    setScrollerGeometry(scroller, {
-      scrollHeight: 5_000,
-      clientHeight: 1_000,
-      scrollTop: 0,
-    });
-    const baselineFooterHeight = Number.parseFloat(footer.style.height);
-
-    let status: ReturnType<VirtualMessageListRef['pinTurnToTopWithStatus']> = 'rejected';
-    act(() => {
-      status = listRef.current?.pinTurnToTopWithStatus(latestTurnId, {
-        behavior: 'auto',
-        pinMode: 'sticky-latest',
-      }) ?? 'rejected';
-    });
-    expect(status).toBe('pending');
-    expect(Number.parseFloat(footer.style.height)).toBeGreaterThan(baselineFooterHeight);
-    expect(Number.parseFloat(footer.style.height) - baselineFooterHeight)
-      .toBeLessThanOrEqual(scroller.clientHeight);
-
-    const target = container.querySelector<HTMLElement>(
-      `[data-turn-id="${latestTurnId}"][data-item-type="user-message"]`,
-    );
-    expect(target).not.toBeNull();
-    if (!target) {
-      return;
-    }
-    vi.spyOn(scroller, 'getBoundingClientRect').mockReturnValue(createRect({
-      top: 0,
-      bottom: 1_000,
-      height: 1_000,
-    }));
-    vi.spyOn(target, 'getBoundingClientRect').mockReturnValue(createRect({
-      top: 4_500,
-      bottom: 4_540,
-      height: 40,
-    }));
-
-    act(() => {
-      scroller.dispatchEvent(new WheelEvent('wheel', {
-        deltaY: -120,
-        bubbles: true,
-      }));
-    });
-    expect(Number.parseFloat(footer.style.height)).toBe(baselineFooterHeight);
-
-    flushAnimationFrame();
-    expect(Number.parseFloat(footer.style.height)).toBe(baselineFooterHeight);
-  });
-
-  it('releases a settled sticky pin at stream end even when its target is no longer rendered', () => {
-    const listRef = React.createRef<VirtualMessageListRef>();
-    const session = createSessionWithTurns('session-a', ['turn-a', 'turn-b']);
-    const latestTurn = session.dialogTurns[session.dialogTurns.length - 1];
-    latestTurn.status = 'processing';
-    latestTurn.modelRounds = [{
-      id: 'round-turn-b',
-      status: 'streaming',
-      isStreaming: true,
-      items: [],
-      startTime: 1,
-    } as typeof latestTurn.modelRounds[number]];
-    stateMocks.activeSession = session;
-    stateMocks.virtualItems = ['turn-a', 'turn-b'].flatMap(turnId => [
-      createItem(turnId),
-      createModelItem(turnId),
-    ]);
-
-    act(() => {
-      root.render(<VirtualMessageList ref={listRef} />);
-    });
-
-    const scroller = container.querySelector<HTMLElement>('[data-virtuoso-scroller="true"]');
-    const footer = container.querySelector<HTMLElement>('.message-list-footer');
-    const target = container.querySelector<HTMLElement>(
-      '[data-turn-id="turn-b"][data-item-type="user-message"]',
-    );
-    expect(scroller).not.toBeNull();
-    expect(footer).not.toBeNull();
-    expect(target).not.toBeNull();
-    if (!scroller || !footer || !target) {
-      return;
-    }
-
-    Object.defineProperties(scroller, {
-      clientHeight: { configurable: true, value: 1_000 },
-      scrollHeight: {
-        configurable: true,
-        get: () => 1_200 + (Number.parseFloat(footer.style.height) || 0),
-      },
-      scrollTop: { configurable: true, writable: true, value: 200 },
-    });
-    vi.spyOn(scroller, 'getBoundingClientRect').mockReturnValue(createRect({
-      top: 0,
-      bottom: 1_000,
-      height: 1_000,
-    }));
-    const targetDocumentTop = 700;
-    vi.spyOn(target, 'getBoundingClientRect').mockImplementation(() => {
-      const top = targetDocumentTop - scroller.scrollTop;
-      return createRect({ top, bottom: top + 40, height: 40 });
-    });
-
-    let status: ReturnType<VirtualMessageListRef['pinTurnToTopWithStatus']> = 'rejected';
-    act(() => {
-      status = listRef.current?.pinTurnToTopWithStatus('turn-b', {
-        behavior: 'auto',
-        pinMode: 'sticky-latest',
-      }) ?? 'rejected';
-    });
-    expect(status).toBe('settled');
-    expect(scroller.scrollTop).toBe(643);
-    const footerHeightBeforeStreamEnd = Number.parseFloat(footer.style.height);
-    expect(footerHeightBeforeStreamEnd).toBe(443);
-
-    const release = vi.spyOn(FlowChatViewportCoordinator.prototype, 'release');
-    virtuosoMocks.renderedRange = { start: 0, end: 2 };
-    stateMocks.activeSession = {
-      ...session,
-      dialogTurns: session.dialogTurns.map(turn => turn.id === latestTurn.id
-        ? {
-          ...turn,
-          status: 'completed',
-          modelRounds: turn.modelRounds.map(round => ({
-            ...round,
-            status: 'completed',
-            isStreaming: false,
-          })),
-        }
-        : turn),
-    };
-    act(() => {
-      root.render(<VirtualMessageList ref={listRef} />);
-    });
-
-    expect(container.querySelector(
-      '[data-turn-id="turn-b"][data-item-type="user-message"]',
-    )).toBeNull();
-    expect(release).toHaveBeenCalledWith('stream-end-pinned-item');
-    expect(Number.parseFloat(footer.style.height)).toBe(footerHeightBeforeStreamEnd);
-  });
-
-  it('centers the exact text range when navigating to a search match', () => {
-    const listRef = React.createRef<VirtualMessageListRef>();
-    stateMocks.activeSession = createSessionWithTurns('session-a', ['turn-a', 'turn-b']);
-    stateMocks.virtualItems = [
-      createItem('turn-a'),
-      {
-        ...createItem('turn-b'),
-        data: {
-          ...createItem('turn-b').data,
-          content: 'prefix needle suffix',
-        },
-      },
-    ];
-
-    act(() => {
-      root.render(<VirtualMessageList ref={listRef} />);
-    });
-
-    const scroller = container.querySelector<HTMLElement>('[data-virtuoso-scroller="true"]');
-    expect(scroller).not.toBeNull();
-    if (!scroller) {
-      return;
-    }
-
-    setScrollerGeometry(scroller, {
-      scrollHeight: 2_000,
-      clientHeight: 500,
-      scrollTop: 0,
-    });
-    vi.spyOn(scroller, 'getBoundingClientRect').mockReturnValue(createRect({
-      top: 0,
-      bottom: 500,
-      height: 500,
-    }));
-    Object.defineProperty(Range.prototype, 'getBoundingClientRect', {
-      configurable: true,
-      value: vi.fn(() => createRect({
-        top: 800,
-        bottom: 820,
-        height: 20,
-      })),
-    });
-    virtuosoMocks.scrollToIndex.mockClear();
-
-    act(() => {
-      listRef.current?.scrollToSearchMatch({
-        virtualItemIndex: 1,
-        query: 'needle',
-      });
-    });
-    flushAnimationFrame();
-
-    expect(virtuosoMocks.scrollToIndex).toHaveBeenCalledWith(expect.objectContaining({
-      align: 'center',
-      behavior: 'auto',
-    }));
-    expect(scroller.scrollTop).toBe(560);
-    delete (Range.prototype as Range & {
-      getBoundingClientRect?: () => DOMRect;
-    }).getBoundingClientRect;
-  });
-
-  it('keeps the initial snapshot bounded while search navigation uses Virtuoso', () => {
-    const listRef = React.createRef<VirtualMessageListRef>();
-    const turnIds = Array.from({ length: 8 }, (_, index) => `turn-${index}`);
-    const targetTurnId = 'turn-1';
-    const latestTurnId = 'turn-7';
-
-    stateMocks.activeSession = createSessionWithTurns('session-a', turnIds, {
-      isHistorical: false,
-      historyState: 'ready',
-      contextRestoreState: 'pending',
-      isPartial: true,
-    });
-    stateMocks.virtualItems = turnIds.flatMap(turnId => [
-      createItem(turnId),
-      createModelItem(turnId),
-    ]);
-    virtuosoMocks.renderedRange = { start: 12, end: 16 };
-
-    act(() => {
-      root.render(<VirtualMessageList ref={listRef} />);
-    });
-
-    const initialSnapshot = container.querySelector<HTMLElement>('[data-initial-history-snapshot="true"]');
-    expect(initialSnapshot).not.toBeNull();
-    expect(container.querySelector('[data-testid="virtuoso"]')).not.toBeNull();
-    expect(initialSnapshot?.querySelectorAll('.virtual-item-wrapper').length)
-      .toBeLessThan(stateMocks.virtualItems.length);
-    expect(initialSnapshot?.querySelector(
-      `[data-turn-id="${targetTurnId}"][data-item-type="user-message"]`,
-    )).toBeNull();
-    expect(initialSnapshot?.querySelector(
-      `[data-turn-id="${latestTurnId}"][data-item-type="user-message"]`,
-    )).not.toBeNull();
-    expect(container.querySelector(
-      `[data-turn-id="${targetTurnId}"][data-item-type="user-message"]`,
-    )).toBeNull();
-    virtuosoMocks.scrollToIndex.mockClear();
-
-    act(() => {
-      listRef.current?.scrollToSearchMatch({
-        virtualItemIndex: 2,
-        query: targetTurnId,
-      });
-    });
-
-    expect(virtuosoMocks.scrollToIndex).toHaveBeenCalledWith(expect.objectContaining({
-      index: 2,
-      align: 'center',
-      behavior: 'auto',
-    }));
-    expect(container.querySelector(
-      `[data-turn-id="${targetTurnId}"][data-item-type="user-message"]`,
-    )).not.toBeNull();
-  });
-
-  it('keeps Virtuoso navigation stable while an initial snapshot handoff is active', () => {
-    let nowMs = 1_000;
-    const nowSpy = vi.spyOn(performance, 'now').mockImplementation(() => nowMs);
-    const listRef = React.createRef<VirtualMessageListRef>();
-
-    try {
-      stateMocks.activeSession = createSessionWithTurns('session-a', ['turn-a', 'turn-b'], {
-        isHistorical: false,
-        historyState: 'ready',
-        contextRestoreState: 'pending',
-        isPartial: true,
-      });
-      stateMocks.virtualItems = [createItem('turn-a'), createItem('turn-b')];
-
-      act(() => {
-        root.render(<VirtualMessageList ref={listRef} />);
-      });
-
-      const scroller = container.querySelector<HTMLElement>('[data-virtuoso-scroller="true"]');
-      const target = container.querySelector<HTMLElement>('[data-turn-id="turn-a"][data-item-type="user-message"]');
-      expect(scroller).not.toBeNull();
-      expect(target).not.toBeNull();
-      if (!scroller || !target) {
-        return;
-      }
-
-      setScrollerGeometry(scroller, {
-        scrollHeight: 5_000,
-        clientHeight: 1_000,
-        scrollTop: 4_000,
-      });
-      Object.defineProperty(scroller, 'scrollTo', {
-        configurable: true,
-        value: vi.fn((options?: ScrollToOptions) => {
-          if (typeof options?.top === 'number') {
-            scroller.scrollTop = options.top;
-          }
-        }),
-      });
-      vi.spyOn(scroller, 'getBoundingClientRect').mockReturnValue(createRect({
-        top: 40,
-        bottom: 1_040,
-        height: 1_000,
-      }));
-      const targetDocumentTop = 2_800;
-      vi.spyOn(target, 'getBoundingClientRect').mockImplementation(() => {
-        const top = targetDocumentTop - scroller.scrollTop;
-        return createRect({
-          top,
-          bottom: top + 40,
-          height: 40,
-        });
-      });
-
-      act(() => {
-        scroller.dispatchEvent(new Event('scroll', { bubbles: true }));
-      });
-
-      stateMocks.activeSession = createSessionWithTurns('session-a', ['turn-a', 'turn-b', 'turn-c'], {
-        isHistorical: false,
-        historyState: 'ready',
-        contextRestoreState: 'pending',
-        isPartial: true,
-      });
-      stateMocks.virtualItems = [createItem('turn-a'), createItem('turn-b'), createItem('turn-c')];
-      setScrollerGeometry(scroller, {
-        scrollHeight: 5_200,
-        clientHeight: 1_000,
-      });
-
-      act(() => {
-        root.render(<VirtualMessageList ref={listRef} />);
-      });
-
-      expect(scroller.scrollTop).toBe(4_000);
-
-      let didPin = false;
-      act(() => {
-        didPin = listRef.current?.pinTurnToTop('turn-a', { behavior: 'auto' }) ?? false;
-      });
-
-      expect(didPin).toBe(true);
-      const pinnedScrollTop = scroller.scrollTop;
-      expect(pinnedScrollTop).toBe(2_703);
-      expect(target.getBoundingClientRect().top).toBe(97);
-
-      expect(rafCallbacks.length).toBeGreaterThan(0);
-      for (let frame = 0; frame < 4; frame += 1) {
-        nowMs += 16;
-        flushAnimationFrame();
-        expect(scroller.scrollTop).toBe(pinnedScrollTop);
-      }
-    } finally {
-      nowSpy.mockRestore();
-    }
-  });
-
-  it('keeps latest reachable after Virtuoso materializes an older turn during snapshot handoff', () => {
-    const listRef = React.createRef<VirtualMessageListRef>();
-    const onUserScrollIntent = vi.fn();
-    const turnIds = Array.from({ length: 8 }, (_, index) => `turn-${index}`);
-    const targetTurnId = 'turn-1';
-    const latestTurnId = 'turn-7';
-
-    stateMocks.activeSession = createSessionWithTurns('session-a', turnIds, {
-      isHistorical: false,
-      historyState: 'ready',
-      contextRestoreState: 'pending',
-      isPartial: true,
-    });
-    stateMocks.virtualItems = turnIds.flatMap(turnId => [
-      createItem(turnId),
-      createModelItem(turnId),
-    ]);
-    virtuosoMocks.renderedRange = { start: 12, end: 16 };
-
-    act(() => {
-      root.render(<VirtualMessageList ref={listRef} onUserScrollIntent={onUserScrollIntent} />);
-    });
-
-    const scroller = container.querySelector<HTMLElement>('[data-virtuoso-scroller="true"]');
-    expect(scroller).not.toBeNull();
-    if (!scroller) {
-      return;
-    }
-
-    Object.defineProperty(scroller, 'clientHeight', {
-      configurable: true,
-      value: 1_000,
-    });
-    Object.defineProperty(scroller, 'scrollHeight', {
-      configurable: true,
-      get: () => (
-        container.querySelector(`[data-turn-id="${latestTurnId}"][data-item-type="user-message"]`)
-          ? 12_000
-          : 9_000
-      ),
-    });
-    scroller.scrollTop = 11_000;
-    Object.defineProperty(scroller, 'scrollTo', {
-      configurable: true,
-      value: vi.fn((options?: ScrollToOptions) => {
-        if (typeof options?.top === 'number') {
-          scroller.scrollTop = options.top;
-        }
-      }),
-    });
-
-    expect(container.querySelector(`[data-turn-id="${targetTurnId}"][data-item-type="user-message"]`)).toBeNull();
-    expect(container.querySelector(`[data-turn-id="${latestTurnId}"][data-item-type="user-message"]`)).not.toBeNull();
-
-    let pinStatus: ReturnType<VirtualMessageListRef['pinTurnToTopWithStatus']> = 'rejected';
-    act(() => {
-      pinStatus = listRef.current?.pinTurnToTopWithStatus(targetTurnId, {
-        behavior: 'auto',
-      }) ?? 'rejected';
-    });
-
-    expect(pinStatus).toBe('pending');
-    expect(scroller.scrollTop).toBe(11_000);
-    expect(container.querySelector(`[data-turn-id="${targetTurnId}"][data-item-type="user-message"]`)).not.toBeNull();
-    expect(container.querySelector(
-      `[data-testid="virtuoso"] [data-turn-id="${latestTurnId}"][data-item-type="user-message"]`,
-    )).toBeNull();
-
-    act(() => {
-      container.querySelector<HTMLElement>('[data-testid="scroll-to-latest"]')?.dispatchEvent(
-        new MouseEvent('click', { bubbles: true }),
-      );
-    });
-
-    expect(onUserScrollIntent).toHaveBeenCalledTimes(1);
-    expect(scroller.scrollTop).toBe(11_000);
-  });
-
-  it('keeps a Virtuoso history pin when materialization reports the old bottom first', () => {
+  it('prepares history navigation without manufacturing bottom range', () => {
     const listRef = React.createRef<VirtualMessageListRef>();
-    const turnIds = Array.from({ length: 8 }, (_, index) => `turn-${index}`);
-    const targetTurnId = 'turn-1';
-    const latestTurnId = 'turn-7';
-
-    stateMocks.activeSession = createSessionWithTurns('session-a', turnIds, {
-      isHistorical: false,
-      historyState: 'ready',
-      contextRestoreState: 'pending',
-      isPartial: true,
-    });
-    stateMocks.virtualItems = turnIds.flatMap(turnId => [
-      createItem(turnId),
-      createModelItem(turnId),
-    ]);
-    virtuosoMocks.renderedRange = { start: 12, end: 16 };
-
-    act(() => {
-      root.render(<VirtualMessageList ref={listRef} />);
-    });
-
-    const scroller = container.querySelector<HTMLElement>('[data-virtuoso-scroller="true"]');
-    expect(scroller).not.toBeNull();
-    if (!scroller) {
-      return;
-    }
-
-    setScrollerGeometry(scroller, {
-      scrollHeight: 6_275,
-      clientHeight: 1_027,
-      scrollTop: 5_248,
-    });
-    const scrollTo = vi.fn((options?: ScrollToOptions) => {
-      if (options?.behavior !== 'smooth' && typeof options?.top === 'number') {
-        scroller.scrollTop = options.top;
-      }
-    });
-    Object.defineProperty(scroller, 'scrollTo', {
-      configurable: true,
-      value: scrollTo,
-    });
-
-    expect(container.querySelector(
-      `[data-turn-id="${targetTurnId}"][data-item-type="user-message"]`,
-    )).toBeNull();
-    expect(container.querySelector(
-      `[data-turn-id="${latestTurnId}"][data-item-type="user-message"]`,
-    )).not.toBeNull();
-
-    let pinStatus: ReturnType<VirtualMessageListRef['pinTurnToTopWithStatus']> = 'rejected';
-    act(() => {
-      pinStatus = listRef.current?.pinTurnToTopWithStatus(targetTurnId, {
-        behavior: 'smooth',
-      }) ?? 'rejected';
-    });
-
-    expect(pinStatus).toBe('pending');
-    expect(virtuosoMocks.scrollToIndex).toHaveBeenCalledWith(expect.objectContaining({
-      index: 2,
-      align: 'start',
-      behavior: 'auto',
-    }));
-    expect(container.querySelector(
-      `[data-turn-id="${targetTurnId}"][data-item-type="user-message"]`,
-    )).not.toBeNull();
-
-    // The browser clamps the old bottom position when the target window is
-    // materialized, before the smooth scroll animation has moved the pane.
-    setScrollerGeometry(scroller, {
-      scrollHeight: 2_693,
-      clientHeight: 1_027,
-      scrollTop: 1_666,
-    });
-    act(() => {
-      scroller.dispatchEvent(new Event('scroll', { bubbles: true }));
-    });
-
-    expect(container.querySelector(
-      `[data-turn-id="${targetTurnId}"][data-item-type="user-message"]`,
-    )).not.toBeNull();
-
-    // A real downward user gesture is still allowed to return to the latest
-    // window once the pane reaches its physical bottom.
-    act(() => {
-      scroller.dispatchEvent(new WheelEvent('wheel', { deltaY: 120, bubbles: true }));
-      scroller.dispatchEvent(new Event('scroll', { bubbles: true }));
-    });
-
-    expect(container.querySelector(
-      `[data-turn-id="${targetTurnId}"][data-item-type="user-message"]`,
-    )).not.toBeNull();
-  });
-
-  it('keeps the initial Virtuoso position when footer height changes after an upward scroll', () => {
-    let nowMs = 1_000;
-    const nowSpy = vi.spyOn(performance, 'now').mockImplementation(() => nowMs);
-
-    try {
-      stateMocks.activeSession = createSessionWithTurns('session-a', ['turn-a', 'turn-b'], {
-        isHistorical: false,
-        historyState: 'ready',
-        contextRestoreState: 'pending',
-        isPartial: true,
-      });
-      stateMocks.virtualItems = [createItem('turn-a'), createItem('turn-b')];
-
-      act(() => {
-        root.render(<VirtualMessageList />);
-      });
-
-      const scroller = container.querySelector<HTMLElement>('[data-virtuoso-scroller="true"]');
-      expect(scroller).not.toBeNull();
-      if (!scroller) {
-        return;
-      }
-
-      setScrollerGeometry(scroller, {
-        scrollHeight: 5_000,
-        clientHeight: 1_000,
-        scrollTop: 4_000,
-      });
-
-      act(() => {
-        scroller.dispatchEvent(new Event('scroll', { bubbles: true }));
-      });
-
-      act(() => {
-        scroller.dispatchEvent(new WheelEvent('wheel', {
-          deltaY: -720,
-          bubbles: true,
-        }));
-        scroller.scrollTop = 1_800;
-        scroller.dispatchEvent(new Event('scroll', { bubbles: true }));
-      });
-      flushAnimationFrame();
-      expect(scroller.scrollTop).toBe(1_800);
-
-      nowMs = 2_000;
-      inputStateMocks.isActive = true;
-      inputStateMocks.inputHeight = 320;
-      setScrollerGeometry(scroller, {
-        scrollHeight: 5_320,
-        clientHeight: 1_000,
-      });
-
-      act(() => {
-        root.render(<VirtualMessageList />);
-      });
-
-      expect(scroller.scrollTop).toBe(1_800);
-    } finally {
-      nowSpy.mockRestore();
-    }
-  });
-
-  it('does not let the initial snapshot become a collapse scroll writer', () => {
-    stateMocks.activeSession = createSessionWithTurns('session-a', ['turn-a', 'turn-b'], {
-      isHistorical: false,
-      historyState: 'ready',
-      contextRestoreState: 'pending',
-      isPartial: true,
-    });
-    stateMocks.virtualItems = [createItem('turn-a'), createItem('turn-b')];
-
-    act(() => {
-      root.render(<VirtualMessageList />);
-    });
-
-    const scroller = container.querySelector<HTMLElement>('[data-virtuoso-scroller="true"]');
-    expect(scroller).not.toBeNull();
-    if (!scroller) {
-      return;
-    }
-
-    setScrollerGeometry(scroller, {
-      scrollHeight: 5_000,
-      clientHeight: 1_000,
-      scrollTop: 4_000,
-    });
-
-    act(() => {
-      scroller.dispatchEvent(new Event('scroll', { bubbles: true }));
-      window.dispatchEvent(new CustomEvent('flowchat:tool-card-collapse-intent', {
-        detail: {
-          toolId: 'tool-a',
-          cardHeight: 300,
-          reason: 'test-collapse',
-        },
-      }));
-    });
-    setScrollerGeometry(scroller, {
-      scrollHeight: 5_300,
-      clientHeight: 1_000,
-      scrollTop: 4_000,
-    });
-
-    act(() => {
-      scroller.dispatchEvent(new Event('scroll', { bubbles: true }));
-    });
-
-    stateMocks.activeSession = createSessionWithTurns('session-a', ['turn-a', 'turn-b', 'turn-c'], {
-      isHistorical: false,
-      historyState: 'ready',
-      contextRestoreState: 'pending',
-      isPartial: true,
-    });
-    stateMocks.virtualItems = [createItem('turn-a'), createItem('turn-b'), createItem('turn-c')];
-    setScrollerGeometry(scroller, {
-      scrollHeight: 5_600,
-      clientHeight: 1_000,
-    });
-
-    act(() => {
-      root.render(<VirtualMessageList />);
-    });
-
-    expect(scroller.scrollTop).toBe(4_000);
-  });
-
-  it('does not expose stale history projection handoff snapshots across sessions', () => {
-    const snapshot = {
-      sessionId: 'session-a',
-      reason: 'session-open',
-      createdAtMs: 1,
-      items: [createItem('turn-a')],
-      mode: 'bottom-tail',
-      targetTurnId: 'turn-a',
-      footerHeightPx: 0,
-    } as const;
-
-    expect(activeSessionHistoryProjectionHandoff(snapshot, 'session-a')).toBe(snapshot);
-    expect(activeSessionHistoryProjectionHandoff(snapshot, 'session-b')).toBeNull();
-    expect(activeSessionHistoryProjectionHandoff(snapshot, null)).toBeNull();
-    expect(activeSessionHistoryProjectionHandoff(null, 'session-a')).toBeNull();
-  });
-
-  it('does not request full history projection for ordinary upward reading scroll', () => {
-    flowStoreMocks.hasDeferredSessionHistoryProjection.mockReturnValue(true);
-    stateMocks.activeSession = createSessionWithTurns('session-a', ['turn-a'], {
-      isHistorical: false,
-      historyState: 'ready',
-      contextRestoreState: 'ready',
-      isPartial: true,
-      dialogTurns: [
-        {
-          id: 'turn-a',
-          sessionId: 'session-a',
-          userMessage: { id: 'user-turn-a', content: 'older loaded prompt', timestamp: 1 },
-          modelRounds: [],
-          status: 'completed',
-          startTime: 1,
-        },
-        {
-          id: 'turn-b',
-          sessionId: 'session-a',
-          userMessage: { id: 'user-turn-b', content: 'latest loaded prompt', timestamp: 2 },
-          modelRounds: [],
-          status: 'completed',
-          startTime: 2,
-        },
-      ],
-    });
-    stateMocks.virtualItems = [createItem('turn-a'), createItem('turn-b')];
-
-    act(() => {
-      root.render(<VirtualMessageList />);
-    });
-
-    const scroller = container.querySelector('[data-virtuoso-scroller="true"]');
-    expect(scroller).not.toBeNull();
-
-    act(() => {
-      scroller?.dispatchEvent(new WheelEvent('wheel', {
-        deltaY: -120,
-        bubbles: true,
-      }));
-    });
-    flushAnimationFrame();
-    flushAnimationFrame();
-
-    expect(flowStoreMocks.revealPreviousSessionHistoryWindow).toHaveBeenCalledWith('session-a', 'wheel-up');
-  });
-
-  it('paginates partial history through Virtuoso after upward intent', () => {
-    flowStoreMocks.hasDeferredSessionHistoryProjection.mockReturnValue(true);
-    flowStoreMocks.revealPreviousSessionHistoryWindow.mockReturnValue(true);
-    stateMocks.activeSession = createSessionWithTurns('session-a', ['turn-3', 'turn-4', 'turn-5'], {
-      isHistorical: true,
-      historyState: 'ready',
-      contextRestoreState: 'pending',
-      isPartial: true,
-      loadedTurnCount: 3,
-      totalTurnCount: 6,
-    });
-    stateMocks.virtualItems = ['turn-3', 'turn-4', 'turn-5'].flatMap(turnId => [
-      createItem(turnId),
-      createModelItem(turnId),
-    ]);
-
-    act(() => {
-      root.render(<VirtualMessageList />);
-    });
-
-    const scroller = container.querySelector<HTMLElement>('[data-virtuoso-scroller="true"]');
-    expect(scroller).not.toBeNull();
-    expect(container.querySelector('[data-testid="virtuoso"]')).not.toBeNull();
-    expect(container.querySelector('[data-initial-history-snapshot="true"]')).not.toBeNull();
-
-    act(() => {
-      scroller?.dispatchEvent(new WheelEvent('wheel', {
-        deltaY: -120,
-        bubbles: true,
-      }));
-    });
-
-    expect(container.querySelector('[data-initial-history-snapshot="true"]')).toBeNull();
-    expect(container.querySelector('[data-turn-id="turn-3"]')).not.toBeNull();
-    expect(flowStoreMocks.revealPreviousSessionHistoryWindow).not.toHaveBeenCalled();
-
-    flushAnimationFrame();
-    flushAnimationFrame();
-
-    expect(flowStoreMocks.revealPreviousSessionHistoryWindow).toHaveBeenCalledWith('session-a', 'wheel-up');
-
-    stateMocks.activeSession = createSessionWithTurns(
-      'session-a',
-      ['turn-0', 'turn-1', 'turn-2', 'turn-3', 'turn-4', 'turn-5'],
-      {
-        isHistorical: true,
-        historyState: 'ready',
-        contextRestoreState: 'pending',
-        isPartial: false,
-        loadedTurnCount: 6,
-        totalTurnCount: 6,
-      },
-    );
-    stateMocks.virtualItems = ['turn-0', 'turn-1', 'turn-2', 'turn-3', 'turn-4', 'turn-5'].flatMap(turnId => [
-      createItem(turnId),
-      createModelItem(turnId),
-    ]);
-
-    act(() => {
-      root.render(<VirtualMessageList />);
-    });
-
-    expect(container.querySelector('[data-turn-id="turn-3"]')).not.toBeNull();
-    expect(container.querySelector('[data-history-paging-sentinel]')).toBeNull();
-  });
-
-  it('waits until the Virtuoso history boundary is near before starting pagination', () => {
-    flowStoreMocks.hasDeferredSessionHistoryProjection.mockReturnValue(true);
-    stateMocks.activeSession = createSessionWithTurns('session-a', ['turn-3', 'turn-4', 'turn-5'], {
-      isHistorical: true,
-      historyState: 'ready',
-      contextRestoreState: 'pending',
-      isPartial: true,
-      loadedTurnCount: 3,
-      totalTurnCount: 6,
-    });
-    stateMocks.virtualItems = ['turn-3', 'turn-4', 'turn-5'].flatMap(turnId => [
-      createItem(turnId),
-      createModelItem(turnId),
-    ]);
-
-    act(() => {
-      root.render(<VirtualMessageList />);
-    });
-
-    const scroller = container.querySelector<HTMLElement>('[data-virtuoso-scroller="true"]');
-    expect(scroller).not.toBeNull();
-    if (!scroller) {
-      return;
-    }
-
-    setScrollerGeometry(scroller, {
-      scrollHeight: 5_000,
-      clientHeight: 1_000,
-      scrollTop: 2_000,
-    });
-
-    act(() => {
-      scroller.dispatchEvent(new WheelEvent('wheel', { deltaY: -120, bubbles: true }));
-      scroller.dispatchEvent(new Event('scroll', { bubbles: true }));
-    });
-    flushAnimationFrame();
-    flushAnimationFrame();
-
-    expect(flowStoreMocks.revealPreviousSessionHistoryWindow).not.toHaveBeenCalled();
-
-    scroller.scrollTop = 1_000;
-    act(() => {
-      scroller.dispatchEvent(new Event('scroll', { bubbles: true }));
-    });
-    flushAnimationFrame();
-    flushAnimationFrame();
-
-    expect(flowStoreMocks.revealPreviousSessionHistoryWindow).toHaveBeenCalledWith('session-a', 'scroll-near-partial-history-boundary');
-  });
-
-  it('does not reveal previous history for upward scroll away from the history boundary', () => {
-    flowStoreMocks.hasDeferredSessionHistoryProjection.mockReturnValue(true);
-    stateMocks.activeSession = createSession('session-a', 'turn-a', {
-      isHistorical: false,
-      historyState: 'ready',
-      contextRestoreState: 'ready',
-      isPartial: true,
-      dialogTurns: [
-        {
-          id: 'turn-a',
-          sessionId: 'session-a',
-          userMessage: { id: 'user-turn-a', content: 'older loaded prompt', timestamp: 1 },
-          modelRounds: [],
-          status: 'completed',
-          startTime: 1,
-        },
-        {
-          id: 'turn-b',
-          sessionId: 'session-a',
-          userMessage: { id: 'user-turn-b', content: 'latest loaded prompt', timestamp: 2 },
-          modelRounds: [],
-          status: 'completed',
-          startTime: 2,
-        },
-      ],
-    });
-    stateMocks.virtualItems = [createItem('turn-a'), createItem('turn-b')];
-
-    act(() => {
-      root.render(<VirtualMessageList />);
-    });
-
-    const scroller = container.querySelector<HTMLElement>('[data-virtuoso-scroller="true"]');
-    expect(scroller).not.toBeNull();
-    if (scroller) {
-      scroller.scrollTop = 2000;
-    }
-
-    act(() => {
-      scroller?.dispatchEvent(new WheelEvent('wheel', {
-        deltaY: -120,
-        bubbles: true,
-      }));
-    });
-    flushAnimationFrame();
-    flushAnimationFrame();
-
-    expect(flowStoreMocks.revealPreviousSessionHistoryWindow).not.toHaveBeenCalled();
-    expect(container.querySelector('[data-history-boundary-status]')).toBeNull();
-  });
-
-  it('requests an adjacent Turn window for catalog-backed tail history', async () => {
-    const onHistoryWindowBoundaryIntent = vi.fn(async (
-      _direction: 'before' | 'after',
-      _options?: {
-        prepareViewportForPresentationCommit?: () => boolean | void | Promise<boolean | void>;
-      },
-    ) => {
-      return true;
-    });
-    stateMocks.activeSession = createSession('session-a', 'turn-a', {
-      isHistorical: false,
-      historyState: 'ready',
-      contextRestoreState: 'ready',
-      isPartial: true,
-      loadedTurnCount: 1,
-      totalTurnCount: 20,
-      turnCatalog: {
-        schemaVersion: 1,
-        sessionId: 'session-a',
-        revision: 'catalog-1',
-        totalTurnCount: 20,
-        complete: true,
-        entries: Array.from({ length: 20 }, (_, ordinal) => ({
-          ordinal,
-          storageTurnIndex: ordinal,
-          turnId: `turn-${ordinal + 1}`,
-          preview: `Prompt ${ordinal + 1}`,
-          previewTruncated: false,
-        })),
-      },
-      dialogTurns: [
-        {
-          id: 'turn-a',
-          sessionId: 'session-a',
-          userMessage: { id: 'user-turn-a', content: 'latest loaded prompt', timestamp: 1 },
-          modelRounds: [],
-          status: 'completed',
-          startTime: 1,
-        },
-      ],
-    });
-    stateMocks.virtualItems = [createItem('turn-a')];
-
-    act(() => {
-      root.render(
-        <VirtualMessageList onHistoryWindowBoundaryIntent={onHistoryWindowBoundaryIntent} />,
-      );
-    });
-
-    const scroller = container.querySelector('[data-virtuoso-scroller="true"]');
-    expect(scroller).not.toBeNull();
-    act(() => {
-      scroller?.dispatchEvent(new WheelEvent('wheel', {
-        deltaY: -120,
-        bubbles: true,
-      }));
-    });
-    flushAnimationFrame();
-    flushAnimationFrame();
-    await act(async () => {
-      await Promise.resolve();
-    });
-
-    expect(onHistoryWindowBoundaryIntent).toHaveBeenCalledWith('before', expect.objectContaining({
-      prepareViewportForPresentationCommit: expect.any(Function),
-    }));
-    expect(flowStoreMocks.revealPreviousSessionHistoryWindow).not.toHaveBeenCalled();
-    expect(flowStoreMocks.releaseSessionHistoryCompletionAfterInitialPaint).not.toHaveBeenCalled();
-  });
-
-  it('treats an exhausted catalog boundary as complete without showing a not-ready error', async () => {
-    const onHistoryWindowBoundaryIntent = vi.fn(async () => 'exhausted' as const);
-    stateMocks.activeSession = createSession('session-a', 'turn-a', {
-      isHistorical: false,
-      historyState: 'ready',
-      contextRestoreState: 'ready',
-      isPartial: true,
-      loadedTurnCount: 1,
-      totalTurnCount: 1,
-      turnCatalog: {
-        schemaVersion: 1,
-        sessionId: 'session-a',
-        revision: 'catalog-1',
-        totalTurnCount: 1,
-        complete: true,
-        entries: [{
-          ordinal: 0,
-          storageTurnIndex: 0,
-          turnId: 'turn-a',
-          preview: 'Prompt 1',
-          previewTruncated: false,
-        }],
-      },
-    });
-    stateMocks.virtualItems = [createItem('turn-a')];
-
-    act(() => {
-      root.render(
-        <VirtualMessageList onHistoryWindowBoundaryIntent={onHistoryWindowBoundaryIntent} />,
-      );
-    });
-
-    const scroller = container.querySelector('[data-virtuoso-scroller="true"]');
-    expect(scroller).not.toBeNull();
-    act(() => {
-      scroller?.dispatchEvent(new WheelEvent('wheel', {
-        deltaY: -120,
-        bubbles: true,
-      }));
-    });
-    flushAnimationFrame();
-    flushAnimationFrame();
-    await act(async () => {
-      await Promise.resolve();
-    });
-
-    expect(onHistoryWindowBoundaryIntent).toHaveBeenCalledOnce();
-    expect(container.querySelector('[data-history-boundary-status]')).toBeNull();
-  });
-
-  it('releases a pending catalog boundary transaction when returning from history to tail', () => {
-    const pendingBoundary = new Promise<'applied'>(() => {});
-    const onHistoryWindowBoundaryIntent = vi.fn(() => pendingBoundary);
-    stateMocks.activeSession = createSessionWithTurns('session-a', ['turn-a'], {
-      isHistorical: false,
-      historyState: 'ready',
-      contextRestoreState: 'ready',
-      isPartial: true,
-      loadedTurnCount: 1,
-      totalTurnCount: 2,
-      turnCatalog: {
-        schemaVersion: 1,
-        sessionId: 'session-a',
-        revision: 'catalog-1',
-        totalTurnCount: 2,
-        complete: true,
-        entries: Array.from({ length: 2 }, (_, ordinal) => ({
-          ordinal,
-          storageTurnIndex: ordinal,
-          turnId: `turn-${ordinal + 1}`,
-          preview: `Prompt ${ordinal + 1}`,
-          previewTruncated: false,
-        })),
-      },
-    });
-    stateMocks.virtualItems = [createItem('turn-a')];
-
-    act(() => {
-      root.render(
-        <VirtualMessageList
-          presentationMode="tail"
-          onHistoryWindowBoundaryIntent={onHistoryWindowBoundaryIntent}
-        />,
-      );
-    });
-
-    const scroller = container.querySelector('[data-virtuoso-scroller="true"]');
-    expect(scroller).not.toBeNull();
-    act(() => {
-      scroller?.dispatchEvent(new WheelEvent('wheel', {
-        deltaY: -120,
-        bubbles: true,
-      }));
-    });
-    flushAnimationFrame();
-    flushAnimationFrame();
-    expect(onHistoryWindowBoundaryIntent).toHaveBeenCalledOnce();
-
-    act(() => {
-      root.render(
-        <VirtualMessageList
-          presentationMode="history-window"
-          historyWindow={{
-            startOrdinal: 0,
-            endOrdinalExclusive: 2,
-            targetTurnId: null,
-            mode: 'history-window',
-          }}
-          onHistoryWindowBoundaryIntent={onHistoryWindowBoundaryIntent}
-        />,
-      );
-    });
-    act(() => {
-      root.render(
-        <VirtualMessageList
-          presentationMode="tail"
-          onHistoryWindowBoundaryIntent={onHistoryWindowBoundaryIntent}
-        />,
-      );
-    });
-
-    act(() => {
-      scroller?.dispatchEvent(new WheelEvent('wheel', {
-        deltaY: -120,
-        bubbles: true,
-      }));
-    });
-    flushAnimationFrame();
-    flushAnimationFrame();
-    expect(onHistoryWindowBoundaryIntent).toHaveBeenCalledTimes(2);
-  });
-
-  it('surfaces a not-ready boundary state when a deferred history window cannot be revealed', () => {
-    flowStoreMocks.hasDeferredSessionHistoryProjection.mockReturnValue(true);
-    flowStoreMocks.revealPreviousSessionHistoryWindow.mockReturnValue(false);
-    stateMocks.activeSession = createSession('session-a', 'turn-a', {
-      isHistorical: false,
-      historyState: 'ready',
-      contextRestoreState: 'ready',
-      isPartial: true,
-      dialogTurns: [
-        {
-          id: 'turn-a',
-          sessionId: 'session-a',
-          userMessage: { id: 'user-turn-a', content: 'latest loaded prompt', timestamp: 1 },
-          modelRounds: [],
-          status: 'completed',
-          startTime: 1,
-        },
-      ],
-    });
-    stateMocks.virtualItems = [createItem('turn-a')];
-
-    act(() => {
-      root.render(<VirtualMessageList />);
-    });
-
-    const scroller = container.querySelector('[data-virtuoso-scroller="true"]');
-    expect(scroller).not.toBeNull();
-
-    act(() => {
-      scroller?.dispatchEvent(new WheelEvent('wheel', {
-        deltaY: -120,
-        bubbles: true,
-      }));
-    });
-    flushAnimationFrame();
-    flushAnimationFrame();
-
-    expect(flowStoreMocks.revealPreviousSessionHistoryWindow).toHaveBeenCalledWith('session-a', 'wheel-up');
-    expect(container.querySelector('[data-history-boundary-status="not-ready"]')?.textContent).toBe('Older history is not ready yet.');
-  });
-
-  it('starts background cache preparation for ordinary upward scroll before deferred cache is ready', () => {
-    flowStoreMocks.hasPendingSessionHistoryCompletion.mockReturnValue(true);
-    stateMocks.activeSession = createSession('session-a', 'turn-a', {
-      isHistorical: false,
-      historyState: 'ready',
-      contextRestoreState: 'ready',
-      isPartial: true,
-      dialogTurns: [
-        {
-          id: 'turn-a',
-          sessionId: 'session-a',
-          userMessage: { id: 'user-turn-a', content: 'latest loaded prompt', timestamp: 1 },
-          modelRounds: [],
-          status: 'completed',
-          startTime: 1,
-        },
-      ],
-    });
-    stateMocks.virtualItems = [createItem('turn-a')];
-
-    act(() => {
-      root.render(<VirtualMessageList />);
-    });
-
-    const scroller = container.querySelector('[data-virtuoso-scroller="true"]');
-    expect(scroller).not.toBeNull();
-
-    act(() => {
-      scroller?.dispatchEvent(new WheelEvent('wheel', {
-        deltaY: -120,
-        bubbles: true,
-      }));
-    });
-    flushAnimationFrame();
-    flushAnimationFrame();
-
-    expect(flowStoreMocks.revealPreviousSessionHistoryWindow).not.toHaveBeenCalled();
-    expect(flowStoreMocks.releaseSessionHistoryCompletionAfterInitialPaint).toHaveBeenCalledWith('session-a', {
-      immediate: true,
-      reason: 'wheel-up',
-    });
-    expect(container.querySelector('[data-history-boundary-status="preparing"]')?.textContent).toBe('Preparing older history...');
-  });
-
-  it('surfaces a not-ready boundary state when older history work is unavailable', () => {
-    stateMocks.activeSession = createSession('session-a', 'turn-a', {
-      isHistorical: false,
-      historyState: 'ready',
-      contextRestoreState: 'ready',
-      isPartial: true,
-      dialogTurns: [
-        {
-          id: 'turn-a',
-          sessionId: 'session-a',
-          userMessage: { id: 'user-turn-a', content: 'latest loaded prompt', timestamp: 1 },
-          modelRounds: [],
-          status: 'completed',
-          startTime: 1,
-        },
-      ],
-    });
-    stateMocks.virtualItems = [createItem('turn-a')];
-
-    act(() => {
-      root.render(<VirtualMessageList />);
-    });
-
-    const scroller = container.querySelector('[data-virtuoso-scroller="true"]');
-    expect(scroller).not.toBeNull();
-
-    act(() => {
-      scroller?.dispatchEvent(new WheelEvent('wheel', {
-        deltaY: -120,
-        bubbles: true,
-      }));
-    });
-    flushAnimationFrame();
-    flushAnimationFrame();
-
-    expect(flowStoreMocks.revealPreviousSessionHistoryWindow).not.toHaveBeenCalled();
-    expect(flowStoreMocks.releaseSessionHistoryCompletionAfterInitialPaint).not.toHaveBeenCalled();
-    expect(container.querySelector('[data-history-boundary-status="not-ready"]')?.textContent).toBe('Older history is not ready yet.');
+    act(() => root.render(<VirtualMessageList ref={listRef} />));
+    expect(listRef.current?.prepareTurnNavigation('turn-2')).toBe('pending');
+    expect(container.querySelector('.message-list-footer')?.getAttribute('style')).toContain('168px');
   });
 });
diff --git a/src/web-ui/src/flow_chat/components/modern/VirtualMessageList.tsx b/src/web-ui/src/flow_chat/components/modern/VirtualMessageList.tsx
index 39a53c8838..16497179be 100644
--- a/src/web-ui/src/flow_chat/components/modern/VirtualMessageList.tsx
+++ b/src/web-ui/src/flow_chat/components/modern/VirtualMessageList.tsx
@@ -1,222 +1,128 @@
 /**
- * Virtualized message list.
- * Renders a flattened DialogTurn stream (user messages + model rounds).
+ * Virtualized FlowChat transcript with natural browser scroll range.
  *
- * Scroll policy (simplified):
- * - The list preserves the current viewport by default.
- * - A new turn first pins the latest user message near the top for reading.
- * - Follow mode starts explicitly via "jump to latest", or automatically once
- *   the latest turn's streaming output grows enough to consume the sticky tail space.
- * - User upward scroll intent exits follow and cancels any pending auto-follow arm.
- * - "Scroll to latest" bar appears whenever the list is not at bottom.
+ * The list never manufactures tail space for turn alignment or layout
+ * preservation. Navigation is best-effort within the physical content range,
+ * card collapses reflow naturally, and useFlowChatFollowOutput is the only
+ * continuous writer that follows streaming output.
  */
 
-import React, { useRef, useState, useCallback, useEffect, useLayoutEffect, forwardRef, useImperativeHandle } from 'react';
-import {
-  Virtuoso,
-  VirtuosoHandle,
-  type Components,
-  type ContextProp,
-} from 'react-virtuoso';
-import { useTranslation } from 'react-i18next';
+import React, {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
 import { Loader2 } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
 import { useActiveSessionState } from '../../hooks/useActiveSessionState';
-import { VirtualItemRenderer } from './VirtualItemRenderer';
-import { ScrollToLatestBar } from '../ScrollToLatestBar';
-import { ScrollToTurnHeaderButton } from '../ScrollToTurnHeaderButton';
 import { useScrollToTurnHeader } from '../../hooks/useScrollToTurnHeader';
-import { useVisibleTaskInfo } from '../../hooks/useVisibleTaskInfo';
-import { StickyTaskIndicator } from '../StickyTaskIndicator';
-import { RuntimeStatusSlot } from './RuntimeStatusSlot';
-import { useFlowChatFollowOutput } from './useFlowChatFollowOutput';
-import type { FlowChatPinTurnToTopMode } from '../../events/flowchatNavigation';
-import type { ActiveTurnRenderRange } from '../../types/flow-chat';
 import type { SessionHistoryWindowDirection } from '../../store/FlowChatStore';
-import { useVirtualItems, useActiveSession, useModernFlowChatStore, type VisibleTurnInfo, type VirtualItem } from '../../store/modernFlowChatStore';
-import { useChatInputState } from '../../store/chatInputStateStore';
-import {
-  computeFlowChatInputStackFooterPx,
-  FLOWCHAT_MESSAGE_TAIL_CLEARANCE_PX,
-} from '../../utils/flowChatScrollLayout';
-import {
-  findDialogTurn,
-  shouldUseStickyLatestPin,
-} from '../../utils/flowChatTurnScrollPolicy';
-import { flowChatStore } from '../../store/FlowChatStore';
-import { startupTrace } from '@/shared/utils/startupTrace';
-import { createLogger } from '@/shared/utils/logger';
-import { flowChatDiagnostics } from '@/infrastructure/diagnostics/flowChatDiagnostics';
 import {
-  estimateVirtualMessageItemHeight,
-  getLeadingVirtualItemIndexDelta,
-  getVirtualMessageDefaultItemHeight,
-  selectInitialHistoryRenderWindow,
-} from './virtualMessageListLayout';
+  FLOWCHAT_TURNS_ROLLED_BACK_EVENT,
+  type FlowChatTurnsRolledBackRequest,
+} from '../../events/flowchatNavigation';
 import {
-  activeSessionHistoryProjectionHandoff,
-  type HistoryProjectionHandoffSnapshot,
-} from './historyProjectionHandoff';
+  useActiveSession,
+  useModernFlowChatStore,
+  useVirtualItems,
+  type VirtualItem,
+} from '../../store/modernFlowChatStore';
+import { useChatInputState } from '../../store/chatInputStateStore';
+import type { ActiveTurnRenderRange } from '../../types/flow-chat';
+import { computeFlowChatInputStackFooterPx } from '../../utils/flowChatScrollLayout';
+import { getMotionAwareScrollBehavior } from '../../utils/motionPreference';
+import { ScrollToLatestBar } from '../ScrollToLatestBar';
+import { ScrollToTurnHeaderButton } from '../ScrollToTurnHeaderButton';
 import {
   findElementWithDataValue,
   findFlowChatSearchTextRanges,
   getFlowChatSearchTextRoot,
   setFlowChatSearchHighlight,
 } from './flowChatSearchDom';
+import { RuntimeStatusSlot } from './RuntimeStatusSlot';
+import { useFlowChatFollowOutput } from './useFlowChatFollowOutput';
+import { findRenderedTurnAnchorElement } from './flowChatViewportAnchor';
+import { useFlowChatViewportAnchor } from './useFlowChatViewportAnchor';
+import {
+  contentEndScrollTop,
+  FLOWCHAT_AT_CONTENT_END_THRESHOLD_PX as AT_CONTENT_END_THRESHOLD_PX,
+  FLOWCHAT_TURN_TOP_GAP_PX,
+  isViewportAtTail,
+  tailSpacerPxForViewport,
+  turnTopAlignmentEntersReservedBlank,
+} from './flowChatTailFollow';
+import { useFlowChatVirtualizer } from './useFlowChatVirtualizer';
+import { useFlowChatViewportOwner } from './useFlowChatViewportOwner';
 import {
-  areBottomReservationStatesEqual,
-  clampPinReservationPxToViewport,
-  COMPENSATION_EPSILON_PX,
-  consumeBottomReservationForContentGrowth,
-  createInitialBottomReservationState,
-  ensureCollapseReservationForScrollTop,
-  getCanceledUnsettledStickyPinGrowthPx,
-  getReservationTotalPx,
-  isTurnPinRequestIdentityCurrent,
-  protectCurrentCollapseReservation,
-  reconcileUnsignaledShrinkReservation,
-  releasePinReservationForUserNavigation,
-  resolveAutoCollapseAnchorScrollTop,
-  resolveCollapseIntentSettlementStrategy,
-  resolveFollowingTailShrinkClampRecovery,
-  resolveProvisionalStickyPinReservationPx,
-  resolveStickyPinGrowthSettlementStrategy,
-  sanitizeBottomReservationState,
-  settleCollapseReservationForViewport,
-  settleRetainedCollapseReservationForAnchor,
-  shouldBypassShrinkCompensationInTailFollow,
-  shouldClearExpiredProvisionalStickyPin,
-  shouldSuppressFollowingTailNegativeScrollBy,
-  shouldSyncPhysicalBottom,
-  transferCollapseReservationToPin,
-  type BottomReservationState,
-  type PinBottomReservation,
-} from './flowChatScrollStability';
+  ONE_SHOT_NAVIGATION_HOLD_MS,
+  type FlowChatViewportOwner,
+} from './flowChatViewportOwnership';
+import { USER_DRIVEN_SCROLL_WINDOW_MS } from './flowChatViewportAnchor';
 import {
-  canHandoffPinnedItemToTail,
-  FlowChatViewportCoordinator,
-  type FlowChatViewportRangeHost,
-} from './FlowChatViewportCoordinator';
+  historyBoundariesForVisibleRange,
+  historyBoundariesReached,
+  type HistoryBoundaryProximity,
+} from './flowChatHistoryBoundary';
+import { VirtualItemRenderer } from './VirtualItemRenderer';
+import { useFlowChatVolatileContext } from './FlowChatContext';
+import {
+  estimateVirtualMessageItemHeightWithContext,
+  type VirtualItemHeightEstimateContext,
+} from './virtualMessageListLayout';
+import { resolveVisibleFlowChatTurnIds } from './flowChatVisibleTurns';
+import { warnHistoryPagingRefusedWithPendingTurns } from '../../services/historySessionDiagnostics';
 import {
-  FLOWCHAT_AUTO_COLLAPSE_SETTLE_FRAMES,
-  FLOWCHAT_COLLAPSE_DURATION_MS,
-  FLOWCHAT_COLLAPSE_INTENT_TTL_MS,
-} from './flowChatCollapseMotion';
+  VIEWPORT_PLACEMENT_SETTLE_MS,
+  roundViewportPx,
+  traceViewport,
+  traceViewportPlacement,
+  traceViewportRepeating,
+} from '@/infrastructure/diagnostics/flowChatViewportDiagnostics';
+import { noteFlowListCommit } from '@/infrastructure/diagnostics/flowChatTailFollowDiagnostics';
 import './VirtualMessageList.scss';
 
-const log = createLogger('VirtualMessageList');
-
-const PINNED_TURN_VIEWPORT_OFFSET_PX = 57; // Keep in sync with `.message-list-header`.
-const TOUCH_SCROLL_INTENT_EXIT_THRESHOLD_PX = 6;
-const USER_UPWARD_SCROLL_INTENT_WINDOW_MS = 800;
-const LATEST_END_ANCHOR_STABILIZATION_MAX_ATTEMPTS = 120;
-const LATEST_END_ANCHOR_STABILIZATION_MIN_ATTEMPTS = 12;
-const LATEST_END_ANCHOR_STABLE_VISIBLE_FRAMES = 8;
-const LATEST_END_ANCHOR_VISIBILITY_MARGIN_PX = 4;
-const LATEST_END_ANCHOR_STABLE_EPSILON_PX = 1;
-const VIRTUOSO_FIRST_ITEM_INDEX_BASE = 1_000_000;
-const PARTIAL_HISTORY_INITIAL_TAIL_TURN_BUDGET = 16;
-const PARTIAL_HISTORY_FULL_PROJECTION_TOP_THRESHOLD_PX = 1200;
-const HISTORY_PROJECTION_HANDOFF_MAX_DURATION_MS = 5000;
-const TURN_PIN_REQUEST_TTL_MS = 5000;
-const TRANSIENT_TURN_PIN_STABLE_FRAME_COUNT = 2;
-const TRANSIENT_TURN_PIN_VIEWPORT_MULTIPLIER = 2;
-const SESSION_OPEN_HANDOFF_ITEM_BUDGET = 24;
-const PREVIOUS_HISTORY_BOUNDARY_STATUS_DURATION_MS = 2500;
 const SEARCH_NAVIGATION_MAX_ATTEMPTS = 24;
-const COLLAPSE_INTENT_TTL_MS = FLOWCHAT_COLLAPSE_INTENT_TTL_MS;
-const AUTO_COLLAPSE_SETTLE_FRAMES = FLOWCHAT_AUTO_COLLAPSE_SETTLE_FRAMES;
-const STICKY_PIN_GROWTH_SETTLE_MS = 300;
-const RETAINED_COLLAPSE_QUIET_SETTLE_MS = 120;
-const RETAINED_COLLAPSE_QUIET_SETTLE_FRAMES = 2;
-const RETAINED_COLLAPSE_RELEASE_QUIET_MS = COLLAPSE_INTENT_TTL_MS;
-const HISTORY_PRESENTATION_COMMIT_SCROLL_QUIET_MS = 320;
+/** Consecutive quiet frames that mark the opening viewport as settled. */
+const OPEN_REVEAL_QUIET_FRAMES = 2;
+/** Hard cap so the transcript is always revealed, settled or not. */
+const OPEN_REVEAL_MAX_FRAMES = 40;
+/**
+ * Resize callbacks over which a viewport resting at the end is re-aligned after
+ * the scroller's own box changes.
+ *
+ * One correction is not enough. A width change reflows every item, and a height
+ * change makes the virtualizer render a different number of them; either way it
+ * re-measures over the following passes, so the content end keeps moving after
+ * the first callback. The window closes on its own so that
+ * streaming content growth, which arrives through the same observer, never
+ * inherits it.
+ */
+const TAIL_REALIGN_RESIZE_CALLBACKS = 6;
+const HISTORY_WINDOW_DIRECTIONS: readonly SessionHistoryWindowDirection[] = ['before', 'after'];
+/**
+ * Transcripts mounted this session, counted.
+ *
+ * The list is keyed on the session id, so a switch is a full remount: new
+ * scroller, empty measurement cache, fresh opening reveal, and a follow hook
+ * that has never followed anything. Nothing in the trail said which instance a
+ * line came from, and two of the three viewport faults measured here turned out
+ * to be two instances disagreeing rather than one instance changing its mind.
+ */
+let nextViewportInstanceId = 0;
 const IDLE_HISTORY_WINDOW_BOUNDARY_STATE: Record<
   SessionHistoryWindowDirection,
   'idle' | 'loading' | 'error'
 > = { before: 'idle', after: 'idle' };
 
-type FlowChatVirtuosoContext = {
-  footerRef: React.RefCallback<HTMLDivElement>;
-  previousHistoryBoundaryStatusNode: React.ReactNode;
-  nextHistoryBoundaryStatusNode: React.ReactNode;
-  runtimeStatusSessionId: string | null;
-};
-
-const FlowChatVirtuosoHeader = ({ context }: ContextProp<FlowChatVirtuosoContext>) => (
-  <>
-    <div className="message-list-header"  data-bf-component="virtual-message-list" data-bf-part="header"/>
-    {context.previousHistoryBoundaryStatusNode}
-  </>
-);
-
-const FlowChatHistoryPagingSentinel = ({
-  state,
-  label,
-}: {
-  state: 'idle' | 'loading' | 'error';
-  label: string;
-}) => (
-  <div
-    className="virtual-message-list__history-paging-sentinel"
-    data-history-paging-sentinel={state}
-    data-history-boundary-status={state === 'loading' ? 'preparing' : state === 'error' ? 'not-ready' : undefined}
-    aria-hidden={state === 'idle'}
-    role={state === 'idle' ? undefined : 'status'}
-    aria-live={state === 'idle' ? undefined : 'polite'}
-  >
-    {state === 'loading' ? (
-      <Loader2 size={14} aria-hidden className="virtual-message-list__history-paging-spinner" />
-    ) : null}
-    <span>{label}</span>
-  </div>
-);
-
-const FlowChatVirtuosoFooter = ({ context }: ContextProp<FlowChatVirtuosoContext>) => (
-  <div
-    ref={context.footerRef}
-    className="message-list-footer"
-    data-bf-component="virtual-message-list"
-    data-bf-part="footer"
-  >
-    {context.nextHistoryBoundaryStatusNode}
-    <RuntimeStatusSlot sessionId={context.runtimeStatusSessionId} placement="footer" />
-  </div>
-);
-
-const FLOW_CHAT_VIRTUOSO_COMPONENTS: Components<VirtualItem, FlowChatVirtuosoContext> = {
-  Header: FlowChatVirtuosoHeader,
-  Footer: FlowChatVirtuosoFooter,
-};
-const FLOW_CHAT_VIRTUOSO_OVERSCAN = { main: 600, reverse: 600 } as const;
-const FLOW_CHAT_VIRTUOSO_VIEWPORT_INCREASE = { top: 600, bottom: 600 } as const;
-
-type LatestEndAnchorResolveReason =
-  | 'raf'
-  | 'range-changed'
-  | 'resize-observer'
-  | 'transition-finish';
-
-type InitialHistoryTransitionState = {
-  key: string;
-  sessionId: string;
-  isPartial: boolean;
-  contextRestoreState: string;
-  usesInitialHistoryRenderBudget: boolean;
-};
-
-// Read `FLOWCHAT_SCROLL_STABILITY.md` before changing collapse compensation logic.
+export type FlowChatTurnNavigationStatus = 'rejected' | 'pending' | 'settled';
 
-/**
- * Methods exposed by VirtualMessageList.
- */
-export type FlowChatTurnPinRequestStatus = 'rejected' | 'pending' | 'settled';
-
-export type TurnPinAlignmentPolicy = 'exact' | 'best-effort';
-
-export interface TurnPinOptions {
+export interface TurnNavigationOptions {
   behavior?: ScrollBehavior;
-  pinMode?: FlowChatPinTurnToTopMode;
-  alignmentPolicy?: TurnPinAlignmentPolicy;
 }
 
 export type HistoryWindowBoundaryIntentResult =
@@ -230,10 +136,14 @@ type HistoryWindowBoundaryIntentResponse =
   | boolean
   | void;
 
+export interface HistoryWindowBoundaryIntentOptions {
+  prepareViewportForPresentationCommit?: () => boolean | void | Promise<boolean | void>;
+  cancelViewportPresentationCommit?: () => void;
+}
+
 export interface VirtualMessageListRef {
   scrollToTurn: (turnIndex: number) => void;
   scrollToIndex: (index: number) => void;
-  // Materializes a virtual item, reveals collapsed search content, and centers the exact text range.
   scrollToSearchMatch: (target: {
     virtualItemIndex: number;
     query: string;
@@ -242,27 +152,29 @@ export interface VirtualMessageListRef {
     expandableIds?: readonly string[];
   }) => void;
   clearSearchMatch: () => void;
-  // Clears pin reservation first, then scrolls to the physical bottom.
-  scrollToPhysicalBottomAndClearPin: () => void;
-  // Clears pin reservation first, then keeps the target turn visible near the natural tail.
-  scrollToTurnEndAndClearPin: (turnId: string) => boolean;
-  // Checks the current rendered DOM instead of the possibly stale visible-turn store.
+  scrollToPhysicalBottom: () => void;
+  scrollToTurnEnd: (turnId: string) => boolean;
   isTurnRenderedInViewport: (turnId: string) => boolean;
-  // Checks whether the current rendered DOM has visible, readable text for the turn.
   isTurnTextRenderedInViewport: (turnId: string) => boolean;
-  // Preserves any existing pin reservation and behaves like an End-key scroll.
   scrollToLatestEndPosition: () => void;
-  // Aligns the target turn's user message to the viewport top.
-  pinTurnToTop: (turnId: string, options?: TurnPinOptions) => boolean;
-  // Detailed status for callers that must distinguish immediate feedback from deferred virtual-list settling.
-  pinTurnToTopWithStatus: (turnId: string, options?: TurnPinOptions) => FlowChatTurnPinRequestStatus;
-  // Establishes the existing pin transaction before a different presentation window is committed.
-  prepareTurnPinToTop: (turnId: string, options?: TurnPinOptions) => FlowChatTurnPinRequestStatus;
+  navigateToTurn: (turnId: string, options?: TurnNavigationOptions) => boolean;
+  navigateToTurnWithStatus: (
+    turnId: string,
+    options?: TurnNavigationOptions,
+  ) => FlowChatTurnNavigationStatus;
+  prepareTurnNavigation: (
+    turnId: string,
+    options?: TurnNavigationOptions,
+  ) => FlowChatTurnNavigationStatus;
+  /**
+   * Centre a flow item inside its Turn, through the register.
+   * `false` means it is not rendered yet, so the caller should ask again.
+   */
+  focusFlowItem: (flowItemId: string) => boolean;
 }
 
 export interface VirtualMessageListProps {
   items?: VirtualItem[];
-  /** Whether the host scene currently owns a visible, measurable viewport. */
   isViewportActive?: boolean;
   presentationMode?: 'tail' | 'history-window';
   viewportMode?: 'live-tail' | 'history-reading';
@@ -277,202 +189,115 @@ export interface VirtualMessageListProps {
   onUserScrollIntent?: () => void;
 }
 
-export interface HistoryWindowBoundaryIntentOptions {
-  prepareViewportForPresentationCommit?: () => boolean | void | Promise<boolean | void>;
-  cancelViewportPresentationCommit?: () => void;
-}
-
-interface PendingCollapseIntentState {
-  active: boolean;
-  anchorScrollTop: number;
-  toolId: string | null;
-  toolName: string | null;
-  expiresAtMs: number;
-  distanceFromBottomBeforeCollapse: number;
-  baseTotalCompensationPx: number;
-  cumulativeShrinkPx: number;
-}
-
-interface RetainedCollapseAnchorState {
-  anchorScrollTop: number;
-  toolId: string | null;
-  toolName: string | null;
-}
-
-type CollapseReservationOwnerKind =
-  | 'tool-collapse'
-  | 'retained-collapse'
-  | 'input-stack-shrink'
-  | 'preserved-element'
-  | 'late-shrink-clamp'
-  | 'protected-range';
-
-interface CollapseReservationOwnerState {
-  kind: CollapseReservationOwnerKind;
-  generation: number;
-}
-
-interface HistoryPresentationCommitQuietWaiter {
-  cancel: () => void;
-  restart: () => void;
-}
-
-interface PendingHistoryPrependAnchorState {
+type PreparedTurnNavigation = {
   turnId: string;
-  offsetFromScrollerTop: number;
-  beforeItemCount: number;
-  handoffRestored: boolean;
-  prependRestored: boolean;
-}
+  behavior: ScrollBehavior;
+};
 
-function createInactiveCollapseIntentState(): PendingCollapseIntentState {
-  return {
-    active: false,
-    anchorScrollTop: 0,
-    toolId: null,
-    toolName: null,
-    expiresAtMs: 0,
-    distanceFromBottomBeforeCollapse: 0,
-    baseTotalCompensationPx: 0,
-    cumulativeShrinkPx: 0,
-  };
-}
+/**
+ * The gap the first Turn sits below.
+ *
+ * Every other Turn is top-aligned to the same gap explicitly, so this height is
+ * the shared constant rather than a style of its own. It is also what the
+ * virtualizer's `scrollPaddingStart` reserves, so an aim that is re-taken while
+ * items measure keeps the same gap.
+ *
+ * Anything else rendered here is above the items in the scroll range, which is
+ * why the virtualizer measures this element rather than assuming its height.
+ */
+const FlowChatListHeader = forwardRef<HTMLDivElement, {
+  previousHistoryBoundaryStatusNode: React.ReactNode;
+}>(({ previousHistoryBoundaryStatusNode }, ref) => (
+  <div ref={ref} className="message-list-header-block">
+    <div
+      className="message-list-header"
+      data-bf-component="virtual-message-list"
+      data-bf-part="header"
+      style={{
+        height: `${FLOWCHAT_TURN_TOP_GAP_PX}px`,
+        minHeight: `${FLOWCHAT_TURN_TOP_GAP_PX}px`,
+      }}
+    />
+    {previousHistoryBoundaryStatusNode}
+  </div>
+));
+FlowChatListHeader.displayName = 'FlowChatListHeader';
+
+const FlowChatListFooter = ({
+  bottomLayoutInsetPx,
+  tailSpacerPx,
+  nextHistoryBoundaryStatusNode,
+  runtimeStatusSessionId,
+}: {
+  bottomLayoutInsetPx: number;
+  tailSpacerPx: number;
+  nextHistoryBoundaryStatusNode: React.ReactNode;
+  runtimeStatusSessionId: string | null;
+}) => (
+  <>
+    <div
+      className="message-list-footer"
+      data-bf-component="virtual-message-list"
+      data-bf-part="footer"
+      style={{
+        height: `${bottomLayoutInsetPx}px`,
+        minHeight: `${bottomLayoutInsetPx}px`,
+      }}
+    >
+      {nextHistoryBoundaryStatusNode}
+      <RuntimeStatusSlot sessionId={runtimeStatusSessionId} placement="footer" />
+    </div>
+    {/*
+      Resident tail reservation of roughly one viewport. Its height tracks the
+      viewport and nothing else — it must never react to a measured content
+      change, or it becomes the compensation scheme this replaced.
+    */}
+    <div
+      className="message-list-tail-spacer"
+      data-bf-component="virtual-message-list"
+      data-bf-part="tailSpacer"
+      aria-hidden="true"
+      style={{
+        height: `${tailSpacerPx}px`,
+        minHeight: `${tailSpacerPx}px`,
+      }}
+    />
+  </>
+);
+
+const FlowChatHistoryPagingSentinel = ({
+  state,
+  label,
+}: {
+  state: 'idle' | 'loading' | 'error';
+  label: string;
+}) => (
+  <div
+    className="virtual-message-list__history-paging-sentinel"
+    data-bf-component="virtual-message-list"
+    data-bf-part="boundaryStatus"
+    data-bf-state={state === 'loading' ? 'preparing' : state === 'error' ? 'unavailable' : undefined}
+    data-history-paging-sentinel={state}
+    data-history-boundary-status={state === 'loading' ? 'preparing' : state === 'error' ? 'not-ready' : undefined}
+    aria-hidden={state === 'idle'}
+    role={state === 'idle' ? undefined : 'status'}
+    aria-live={state === 'idle' ? undefined : 'polite'}
+  >
+    {state === 'loading' ? (
+      <Loader2 size={14} aria-hidden className="virtual-message-list__history-paging-spinner" />
+    ) : null}
+    <span>{label}</span>
+  </div>
+);
 
-function normalizeHistoryWindowBoundaryIntentResult(
+function normalizeBoundaryResult(
   result: HistoryWindowBoundaryIntentResponse,
 ): HistoryWindowBoundaryIntentResult {
-  if (result === true) {
-    return 'applied';
-  }
-  if (result === false || result === undefined) {
-    return 'not-ready';
-  }
+  if (result === true) return 'applied';
+  if (result === false || result === undefined) return 'not-ready';
   return result;
 }
 
-interface LatestEndAnchorRequestState {
-  turnId: string;
-  targetIndex: number;
-  attempts: number;
-  visibleFrames: number;
-  stableVisibleFrames: number;
-  lastScrollHeight: number | null;
-  lastScrollTop: number | null;
-  lastTargetTop: number | null;
-  lastTargetBottom: number | null;
-}
-
-type InitialTopMostItemIndex =
-  | number
-  | { index: number; align: 'start' | 'end' };
-
-interface ScrollerGeometrySnapshot {
-  scrollTop: number;
-  scrollHeight: number;
-  clientHeight: number;
-}
-
-interface PendingTurnPinState {
-  generation: number;
-  sessionId: string;
-  turnId: string;
-  behavior: ScrollBehavior;
-  pinMode: FlowChatPinTurnToTopMode;
-  alignmentPolicy: TurnPinAlignmentPolicy;
-  expiresAtMs: number;
-  attempts: number;
-}
-
-interface TransientTurnPinStabilizationState extends PendingTurnPinState {
-  stableAlignedFrames: number;
-  lastScrollTop: number | null;
-  lastTargetTop: number | null;
-}
-
-interface PreparedHistoryTurnPinState {
-  turnId: string;
-  behavior: ScrollBehavior;
-  pinMode: FlowChatPinTurnToTopMode;
-  alignmentPolicy: TurnPinAlignmentPolicy;
-}
-
-type TurnPinResolution =
-  | { kind: 'pending' }
-  | { kind: 'exact'; targetScrollTop: number }
-  | { kind: 'best-effort'; targetScrollTop: number };
-
-function sanitizeReservationPx(value: number): number {
-  return Number.isFinite(value) ? Math.max(0, value) : 0;
-}
-
-function isEditableElement(target: EventTarget | null): boolean {
-  if (!(target instanceof HTMLElement)) {
-    return false;
-  }
-
-  return (
-    target.isContentEditable ||
-    target.closest('input, textarea, select, [contenteditable="true"]') !== null
-  );
-}
-
-function isUpwardScrollIntentKey(event: KeyboardEvent): boolean {
-  if (event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey) {
-    return false;
-  }
-
-  return (
-    event.key === 'ArrowUp' ||
-    event.key === 'PageUp' ||
-    event.key === 'Home' ||
-    (event.key === ' ' && event.shiftKey)
-  );
-}
-
-function isScrollIntentKey(event: KeyboardEvent): boolean {
-  if (event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey) {
-    return false;
-  }
-
-  return (
-    event.key === 'ArrowUp' ||
-    event.key === 'ArrowDown' ||
-    event.key === 'PageUp' ||
-    event.key === 'PageDown' ||
-    event.key === 'Home' ||
-    event.key === 'End' ||
-    event.key === ' '
-  );
-}
-
-function isPointerOnScrollbarGutter(
-  scroller: HTMLElement,
-  clientX: number,
-  clientY: number,
-): boolean {
-  const rect = scroller.getBoundingClientRect();
-  const verticalScrollbarWidth = Math.max(0, scroller.offsetWidth - scroller.clientWidth);
-  const horizontalScrollbarHeight = Math.max(0, scroller.offsetHeight - scroller.clientHeight);
-
-  const isWithinVerticalScrollbar = (
-    verticalScrollbarWidth > 0 &&
-    clientX >= rect.right - verticalScrollbarWidth &&
-    clientX <= rect.right &&
-    clientY >= rect.top &&
-    clientY <= rect.bottom
-  );
-
-  const isWithinHorizontalScrollbar = (
-    horizontalScrollbarHeight > 0 &&
-    clientY >= rect.bottom - horizontalScrollbarHeight &&
-    clientY <= rect.bottom &&
-    clientX >= rect.left &&
-    clientX <= rect.right
-  );
-
-  return isWithinVerticalScrollbar || isWithinHorizontalScrollbar;
-}
-
 function getVirtualItemStableKey(item: VirtualItem): string {
   switch (item.type) {
     case 'user-message':
@@ -485,6365 +310,1265 @@ function getVirtualItemStableKey(item: VirtualItem): string {
     case 'turn-completion-notice':
       return `${item.type}:${item.turnId}:${item.data.reasonCode}`;
     case 'turn-failure-notice':
-      return `${item.type}:${item.turnId}`;
     case 'image-analyzing':
       return `${item.type}:${item.turnId}`;
   }
 }
 
+/**
+ * Whether a pointer press landed on the scroller's scrollbar rather than on the
+ * transcript.
+ *
+ * `clientWidth` stops at the scrollbar, so anything past the content box's
+ * trailing edge is the bar or its track. Measured on WebView2: a 10px gutter,
+ * a press on the transcript at `clientX` 1497 against a content box ending at
+ * 1641, and presses on the bar at 1643-1647.
+ *
+ * Chromium does dispatch `pointerdown` for a scrollbar press. WebKit-backed
+ * builds draw overlay scrollbars that take no layout width, leaving no gutter
+ * to test against, so this returns false there and the drag stays unnoticed.
+ */
+function isScrollbarPress(event: PointerEvent, scroller: HTMLElement): boolean {
+  return event.clientX > scroller.getBoundingClientRect().left + scroller.clientWidth;
+}
+
+function isElementVisibleInScroller(element: HTMLElement, scroller: HTMLElement): boolean {
+  const elementRect = element.getBoundingClientRect();
+  const scrollerRect = scroller.getBoundingClientRect();
+  return elementRect.bottom > scrollerRect.top && elementRect.top < scrollerRect.bottom;
+}
+
 const VirtualMessageListSession = forwardRef<VirtualMessageListRef, VirtualMessageListProps>(({
   items,
   isViewportActive = true,
   presentationMode = 'tail',
   viewportMode = presentationMode === 'history-window' ? 'history-reading' : 'live-tail',
   historyWindow = null,
-  presentationRevision = 0,
+  presentationRevision: _presentationRevision = 0,
   historyBoundaryState = IDLE_HISTORY_WINDOW_BOUNDARY_STATE,
   onHistoryWindowBoundaryIntent,
   onRequestJumpToLatest,
   onUserScrollIntent,
 }, ref) => {
   const { t } = useTranslation('flow-chat');
-  const virtuosoRef = useRef<VirtuosoHandle>(null);
+  /**
+   * This render, counted.
+   *
+   * The price of following the tail by growing an item is paid here: a height
+   * change makes the virtualizer re-measure, which lands back in this component.
+   * A follow that scrolls inside an item instead claims to cost nothing, and
+   * this is the counter that claim is checked against. Deliberately dependency
+   * free — every commit counts, whatever caused it.
+   */
+  useEffect(() => {
+    noteFlowListCommit();
+  });
   const canonicalVirtualItems = useVirtualItems();
   const virtualItems = items ?? canonicalVirtualItems;
+  const { exploreGroupStates } = useFlowChatVolatileContext();
   const activeSession = useActiveSession();
-  const hasPendingHistoryCompletion = activeSession?.sessionId
-    ? flowChatStore.hasPendingSessionHistoryCompletion(activeSession.sessionId)
-    : false;
-  const hasPartialHistoryInitialViewport =
-    activeSession?.historyState === 'ready' &&
-    activeSession.contextRestoreState === 'pending' &&
-    (activeSession.dialogTurns.length ?? 0) <= PARTIAL_HISTORY_INITIAL_TAIL_TURN_BUDGET;
-  const useInitialHistoryRenderBudget = hasPendingHistoryCompletion || hasPartialHistoryInitialViewport;
-  const virtuosoIndexStateRef = useRef<{
-    sessionId: string | null;
-    firstItemIndex: number;
-    virtualItems: VirtualItem[];
-  }>({
-    sessionId: null,
-    firstItemIndex: VIRTUOSO_FIRST_ITEM_INDEX_BASE,
-    virtualItems: [],
-  });
-  const virtuosoIndexState = virtuosoIndexStateRef.current;
+  const activeSessionState = useActiveSessionState();
   const activeSessionId = activeSession?.sessionId ?? null;
-  if (virtuosoIndexState.sessionId !== activeSessionId) {
-    virtuosoIndexState.sessionId = activeSessionId;
-    virtuosoIndexState.firstItemIndex = VIRTUOSO_FIRST_ITEM_INDEX_BASE;
-    virtuosoIndexState.virtualItems = virtualItems;
-  } else if (virtuosoIndexState.virtualItems !== virtualItems) {
-    const leadingIndexDelta = getLeadingVirtualItemIndexDelta(
-      virtuosoIndexState.virtualItems,
-      virtualItems,
-      getVirtualItemStableKey,
-    );
-    if (leadingIndexDelta !== 0) {
-      virtuosoIndexState.firstItemIndex = Math.max(
-        0,
-        virtuosoIndexState.firstItemIndex + leadingIndexDelta,
-      );
-    }
-    virtuosoIndexState.virtualItems = virtualItems;
+  /**
+   * The newest Turn the session has, which is what "a new Turn" means.
+   *
+   * Deliberately a fact about the ledger and not about the projection.
+   * `virtualItems.at(-1)` answers where the presentation currently *ends*, and
+   * a history window re-cut moves that to a Turn which has existed for hours:
+   * measured, navigating to Turn 2 landed correctly and was then overwritten
+   * twice, because each window loaded on the way ended somewhere new and each
+   * of those read as a submission, pinning the window's last Turn to the top.
+   *
+   * Whether the Turn can be *acted on* is a second question, and it belongs
+   * with the response rather than the identity — qualifying the identity by
+   * visibility instead makes a Turn that merely came into view look new, which
+   * is the same bug wearing the opposite sign.
+   */
+  const latestTurnId = activeSession?.dialogTurns.at(-1)?.id ?? null;
+  const viewportIdRef = useRef<number | null>(null);
+  if (viewportIdRef.current === null) {
+    nextViewportInstanceId += 1;
+    viewportIdRef.current = nextViewportInstanceId;
   }
-  const virtuosoFirstItemIndex = virtuosoIndexState.firstItemIndex;
-
-  const [isAtBottom, setIsAtBottom] = useState(true);
-  const [scrollerElement, setScrollerElement] = useState<HTMLElement | null>(null);
-  const [viewportActivityRevision, setViewportActivityRevision] = useState(0);
-  const [bottomReservationState, setBottomReservationState] = useState<BottomReservationState>(
-    () => createInitialBottomReservationState()
-  );
-  const [pendingTurnPin, setPendingTurnPin] = useState<PendingTurnPinState | null>(null);
-  const [historyProjectionHandoff, setHistoryProjectionHandoff] = useState<HistoryProjectionHandoffSnapshot | null>(null);
-  const [initialHistorySnapshotActive, setInitialHistorySnapshotActive] = useState(useInitialHistoryRenderBudget);
-  const [historyPagingActive, setHistoryPagingActive] = useState(false);
-  const [historyPagingLoading, setHistoryPagingLoading] = useState(false);
-  const [historyPagingAnchorTurnId, setHistoryPagingAnchorTurnId] = useState<string | null>(null);
-  const [previousHistoryBoundaryStatus, setPreviousHistoryBoundaryStatus] = useState<{
-    sessionId: string;
-    reason: string;
-    state: 'preparing' | 'not-ready';
-  } | null>(null);
-
-  const scrollerElementRef = useRef<HTMLElement | null>(null);
-  const footerElementRef = useRef<HTMLDivElement | null>(null);
-  const activeSessionIdRef = useRef<string | null>(null);
+  const viewportId = viewportIdRef.current;
+  // Mirrors, so the unmount line below can report the state it ended on rather
+  // than the state it was created with.
+  const activeSessionIdRef = useRef(activeSessionId);
+  activeSessionIdRef.current = activeSessionId;
   const isViewportActiveRef = useRef(isViewportActive);
-  const viewportGeometrySuspendedRef = useRef(!isViewportActive);
-  const viewportActivityGenerationRef = useRef(0);
-  const viewportReactivationFrameRef = useRef<number | null>(null);
-  const suspendedViewportScrollTopRef = useRef(0);
-  const historyProjectionHandoffRef = useRef<HistoryProjectionHandoffSnapshot | null>(null);
-  const historyProjectionHandoffReleaseFrameRef = useRef<number | null>(null);
-  const clearHistoryProjectionHandoffRef = useRef<(reason: string) => void>(() => {});
-  const latestVisibleHistoryTailSnapshotRef = useRef<HistoryProjectionHandoffSnapshot | null>(null);
-  const previousInitialHistoryTransitionStateRef = useRef<InitialHistoryTransitionState | null>(null);
-  const fullHistoryProjectionIntentFrameRef = useRef<number | null>(null);
-  const pendingFullHistoryProjectionReasonRef = useRef<string | null>(null);
-  const previousHistoryBoundaryStatusTimerRef = useRef<number | null>(null);
-  const sessionOpenHandoffSessionIdRef = useRef<string | null>(null);
-  const previousActiveSessionIdForOpenHandoffRef = useRef<string | null | undefined>(undefined);
-  const viewportCoordinatorRef = useRef(new FlowChatViewportCoordinator());
-  const bottomReservationStateRef = useRef<BottomReservationState>(createInitialBottomReservationState());
-  const collapseReservationOwnerRef = useRef<CollapseReservationOwnerState | null>(null);
-  const collapseReservationOwnerGenerationRef = useRef(0);
-  const restoreScrollerMethodsRef = useRef<(() => void) | null>(null);
-  const previousMeasuredHeightRef = useRef<number | null>(null);
-  const previousScrollTopRef = useRef(0);
-  const previousScrollerGeometryRef = useRef<ScrollerGeometrySnapshot | null>(null);
-  const markedInitialHistoryRenderWindowKeyRef = useRef<string | null>(null);
-  const initialHistorySnapshotCreatedAtMsRef = useRef(performance.now());
-  const pendingHistoryPrependAnchorRef = useRef<PendingHistoryPrependAnchorState | null>(null);
-  const historyPagingActiveRef = useRef(false);
-  const historyPagingRetryTimerRef = useRef<number | null>(null);
-  const catalogHistoryWindowRequestRef = useRef<Promise<HistoryWindowBoundaryIntentResult> | null>(null);
-  const previousViewportModeRef = useRef<'live-tail' | 'history-reading'>(viewportMode);
-  const lastUserScrollIntentAtMsRef = useRef(Number.NEGATIVE_INFINITY);
-  const historyPresentationCommitQuietGenerationRef = useRef(0);
-  const historyPresentationCommitQuietWaitersRef = useRef(
-    new Set<HistoryPresentationCommitQuietWaiter>(),
-  );
-  const preparedHistoryTurnPinRef = useRef<PreparedHistoryTurnPinState | null>(null);
-  const measureFrameRef = useRef<number | null>(null);
-  const visibleTurnMeasureFrameRef = useRef<number | null>(null);
-  const pinReservationReconcileFrameRef = useRef<number | null>(null);
-  const turnPinStabilizationFrameRef = useRef<number | null>(null);
-  const turnPinRequestGenerationRef = useRef(0);
-  const pendingTurnPinGenerationRef = useRef<number | null>(null);
-  const activeTurnPinRequestRef = useRef<PendingTurnPinState | null>(null);
-  const latestEndAnchorStabilizationFrameRef = useRef<number | null>(null);
-  const searchNavigationRequestIdRef = useRef(0);
-  const latestEndAnchorRequestRef = useRef<LatestEndAnchorRequestState | null>(null);
-  const virtuosoMountStateRef = useRef<{
-    sessionId: string | null;
-    mounted: boolean;
-  }>({
-    sessionId: null,
-    mounted: false,
+  isViewportActiveRef.current = isViewportActive;
+  const itemCountRef = useRef(virtualItems.length);
+  itemCountRef.current = virtualItems.length;
+  const scrollerElementRef = useRef<HTMLElement | null>(null);
+  /**
+   * Who is moving the viewport, for everything in this transcript that moves
+   * it. Declared here because the scroller is, and every writer below takes it
+   * from this one place rather than keeping its own opinion of the others.
+   */
+  const viewportOwner = useFlowChatViewportOwner(scrollerElementRef);
+  const headerElementRef = useRef<HTMLDivElement | null>(null);
+  const [scrollerElement, setScrollerElement] = useState<HTMLElement | null>(null);
+  const [viewportHeightPx, setViewportHeightPx] = useState(0);
+  const [viewportWidthPx, setViewportWidthPx] = useState(0);
+  /** Last scroller box the resize observer saw, to tell it apart from a content change. */
+  const observedViewportBoxRef = useRef({ width: 0, height: 0 });
+  /** Remaining resize callbacks over which to keep a resting viewport at the end. */
+  const tailRealignCallbacksRef = useRef(0);
+  /** Synchronous mirror of `isAtBottom`, read by a resize for the pre-resize answer. */
+  const isAtTailRef = useRef(true);
+  /** A pointer is held on the scrollbar, so the scrolling it causes is intent. */
+  const isScrollbarPressRef = useRef(false);
+  const [isAtBottom, setIsAtBottom] = useState(true);
+  const [isOpenViewportSettled, setIsOpenViewportSettled] = useState(false);
+  const preparedTurnNavigationRef = useRef<PreparedTurnNavigation | null>(null);
+  const boundaryRequestRef = useRef<Record<SessionHistoryWindowDirection, Promise<void> | null>>({
+    before: null,
+    after: null,
   });
-  const resolveLatestEndAnchorStabilizationRef = useRef<((reason: LatestEndAnchorResolveReason) => boolean) | null>(null);
-  const resizeObserverRef = useRef<ResizeObserver | null>(null);
-  const mutationObserverRef = useRef<MutationObserver | null>(null);
-  const touchScrollIntentStartYRef = useRef<number | null>(null);
-  const scrollbarPointerInteractionActiveRef = useRef(false);
-  // Timestamp until which we treat any upward scroll as user-initiated. Set by
-  // wheel/touch/keyboard/scrollbar handlers BEFORE the browser actually moves
-  // the scroller. Used by the handleScroll "shrink-clamp restore" intercept
-  // (below) to distinguish a genuine user upward scroll from a browser auto
-  // clamp caused by content shrinking near the bottom in follow mode.
-  const userInitiatedUpwardScrollUntilMsRef = useRef(0);
-  const pendingCollapseIntentRef = useRef<PendingCollapseIntentState>(
-    createInactiveCollapseIntentState(),
-  );
-  const retainedCollapseAnchorRef = useRef<RetainedCollapseAnchorState | null>(null);
-  const collapseIntentFinalizeTimerRef = useRef<number | null>(null);
-  const collapseIntentAnimationTimerRef = useRef<number | null>(null);
-  const collapseIntentSettleFrameRef = useRef<number | null>(null);
-  const retainedCollapseSettleTimerRef = useRef<number | null>(null);
-  const retainedCollapseSettleFrameRef = useRef<number | null>(null);
-  const retainedCollapseReleaseTimerRef = useRef<number | null>(null);
-  const retainedCollapseSettleGenerationRef = useRef(0);
-  const retainedCollapseGeometryGenerationRef = useRef(0);
-  const pendingStickyPinGrowthRef = useRef<{
-    targetTurnId: string | null;
-    amountPx: number;
-  }>({
-    targetTurnId: null,
-    amountPx: 0,
+  const exhaustedBoundaryRef = useRef<Record<SessionHistoryWindowDirection, boolean>>({
+    before: false,
+    after: false,
   });
-  const stickyPinGrowthSettleTimerRef = useRef<number | null>(null);
-  const settlePendingStickyPinGrowthRef = useRef<(reason: string) => void>(() => {});
-  const cancelUnresolvedTurnPinRef = useRef<() => void>(() => {});
-  const maybeHandoffPinnedTurnToTailRef = useRef<(reason: string) => boolean>(() => false);
-  const preparePinnedTurnFollowHandoffRef = useRef<() => void>(() => {});
-  const finalizeCollapseIntentRef = useRef<(
-    reason: string,
-    options?: { expectedExpiresAtMs?: number; suppressHandoff?: boolean },
-  ) => boolean>(() => false);
-  const exitPinnedViewportForUserIntentRef = useRef<(reason: string) => void>((reason) => {
-    viewportCoordinatorRef.current.release(reason);
+  /**
+   * `exhausted` describes the window that asked, not the session.
+   *
+   * "There is nothing before this" is true of a *start ordinal*. Navigate to
+   * the first Turn and the store answers `reached-start` for `targetOrdinal:
+   * -1`, correctly — and the latch then outlived the window by the rest of the
+   * session. Measured: 3 Turns of 43 loaded, `before` latched off from a visit
+   * to Turn 1, and after jumping back to the tail the reader could not page at
+   * all. The alarm fired (`latched-exhausted-while-partial`) and nothing acted
+   * on it.
+   *
+   * So the latch is cleared whenever the window moves. Only `applied` used to
+   * clear it, which is the one case where the window moves *because* of the
+   * page — every other way it moves left a stale answer behind.
+   */
+  const windowBoundsKey = historyWindow
+    ? `${historyWindow.startOrdinal}:${historyWindow.endOrdinalExclusive}`
+    : presentationMode;
+  const previousWindowBoundsKeyRef = useRef(windowBoundsKey);
+  if (previousWindowBoundsKeyRef.current !== windowBoundsKey) {
+    previousWindowBoundsKeyRef.current = windowBoundsKey;
+    exhaustedBoundaryRef.current = { before: false, after: false };
+  }
+  /**
+   * Whether a boundary may be asked about again.
+   *
+   * Prepend compensation puts the viewport back on the reader's content, but
+   * the virtualizer places its rows from a scroll offset it only refreshes on
+   * the next frame, so for one commit the visible range is still read against
+   * the head. Asking from that commit pages again and produces another one just
+   * like it: measured, a single junction paged a transcript back to its first
+   * Turn while the reader held still.
+   *
+   * A direction is armed by the visible range leaving it. react-virtuoso had
+   * this for free — the range it reported was absolute, so a prepend moved the
+   * local start index by the number of items added and the rule stopped
+   * applying by itself.
+   */
+  const boundaryArmedRef = useRef<Record<SessionHistoryWindowDirection, boolean>>({
+    before: true,
+    after: true,
   });
-  const followOutputControllerRef = useRef<{
-    handleUserScrollIntent: () => void;
-    handleScroll: () => void;
-    scheduleFollowToLatest: (reason: string) => void;
-  }>({
-    handleUserScrollIntent: () => {},
-    handleScroll: () => {},
-    scheduleFollowToLatest: () => {},
+  /** Assigned below, once the boundary evaluation it stands for exists. */
+  const evaluateHistoryBoundariesRef = useRef<() => void>(() => {});
+  const searchNavigationRequestIdRef = useRef(0);
+  const visibleTurnUpdateFrameRef = useRef<number | null>(null);
+
+  const virtualizer = useFlowChatVirtualizer({
+    items: virtualItems,
+    scrollerRef: scrollerElementRef,
+    headerRef: headerElementRef,
+    getItemKey: getVirtualItemStableKey,
+    estimateItemHeightPx: estimateVirtualMessageItemHeightWithContext,
+    estimateContext: {
+      availableWidthPx: viewportWidthPx > 0 ? viewportWidthPx : scrollerElement?.clientWidth,
+      isHistorical: activeSession?.isHistorical === true,
+      exploreGroupStates,
+    } satisfies VirtualItemHeightEstimateContext,
+    estimateContextRevision: [
+      viewportWidthPx,
+      activeSession?.isHistorical === true ? 'historical' : 'live',
+      [...(exploreGroupStates?.entries() ?? [])]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([groupId, expanded]) => `${groupId}:${expanded ? 1 : 0}`)
+        .join(','),
+    ].join('|'),
+    scrollPaddingStartPx: FLOWCHAT_TURN_TOP_GAP_PX,
+    writeViewport: viewportOwner.write,
+    shiftViewport: viewportOwner.shift,
   });
-  const deferredFollowReasonRef = useRef<string | null>(null);
-  // Mirror of `isFollowingOutput` for use inside listeners that are registered
-  // once per mount. When follow mode is active we deliberately bypass collapse
-  // pre-compensation and semantic-anchor restoration so the continuous follow
-  // loop can keep tracking the bottom without fighting layout stabilization.
-  const isFollowingOutputRef = useRef(false);
-  const isStreamingOutputRef = useRef(false);
-  const previousIsStreamingOutputRef = useRef(false);
-  const transientTurnPinStabilizationRef = useRef<TransientTurnPinStabilizationState | null>(null);
-  const scheduleTransientTurnPinStabilizationRef = useRef<(frames?: number) => void>(() => {});
-  activeSessionIdRef.current = activeSessionId;
-  isViewportActiveRef.current = isViewportActive;
-  if (!isViewportActive) {
-    viewportGeometrySuspendedRef.current = true;
-  }
 
-  const isScrollerViewportMeasurable = useCallback((scroller: HTMLElement | null): scroller is HTMLElement => (
-    Boolean(
-      isViewportActiveRef.current &&
-      scroller?.isConnected &&
-      (
-        scroller.clientHeight > COMPENSATION_EPSILON_PX ||
-        scroller.getBoundingClientRect().height > COMPENSATION_EPSILON_PX
+  const userMessageItems = useMemo(() => virtualItems
+    .map((item, index) => ({ item, index }))
+    .filter(({ item }) => item.type === 'user-message'), [virtualItems]);
+
+  const isStreamingOutput = useMemo(() => {
+    if (viewportMode === 'history-reading') return false;
+    if (activeSessionState.isProcessing) return true;
+    const latestTurn = activeSession?.dialogTurns.at(-1);
+    return Boolean(
+      latestTurn && (
+        latestTurn.status === 'processing' ||
+        latestTurn.status === 'finishing' ||
+        latestTurn.status === 'image_analyzing' ||
+        latestTurn.modelRounds.some(round => round.isStreaming)
       )
-    )
-  ), []);
-
-  const canProcessViewportGeometry = useCallback((scroller: HTMLElement | null): scroller is HTMLElement => (
-    !viewportGeometrySuspendedRef.current && isScrollerViewportMeasurable(scroller)
-  ), [isScrollerViewportMeasurable]);
-
-  const canCoordinateViewport = useCallback(() => (
-    isViewportActiveRef.current && !viewportGeometrySuspendedRef.current
-  ), []);
-
-  useEffect(() => {
-    const previousMode = previousViewportModeRef.current;
-    if (previousMode === 'history-reading' && viewportMode === 'live-tail') {
-      historyPresentationCommitQuietGenerationRef.current += 1;
-      Array.from(historyPresentationCommitQuietWaitersRef.current).forEach(waiter => waiter.cancel());
-      if (historyPagingRetryTimerRef.current !== null) {
-        window.clearTimeout(historyPagingRetryTimerRef.current);
-        historyPagingRetryTimerRef.current = null;
-      }
-      if (fullHistoryProjectionIntentFrameRef.current !== null) {
-        cancelAnimationFrame(fullHistoryProjectionIntentFrameRef.current);
-        fullHistoryProjectionIntentFrameRef.current = null;
-      }
-      if (previousHistoryBoundaryStatusTimerRef.current !== null) {
-        window.clearTimeout(previousHistoryBoundaryStatusTimerRef.current);
-        previousHistoryBoundaryStatusTimerRef.current = null;
-      }
-      pendingFullHistoryProjectionReasonRef.current = null;
-      catalogHistoryWindowRequestRef.current = null;
-      pendingHistoryPrependAnchorRef.current = null;
-      historyPagingActiveRef.current = false;
-      setHistoryPagingActive(false);
-      setHistoryPagingLoading(false);
-      setHistoryPagingAnchorTurnId(null);
-      setPreviousHistoryBoundaryStatus(null);
-    }
-    if (previousMode !== viewportMode) {
-      previousViewportModeRef.current = viewportMode;
-    }
-  }, [viewportMode]);
+    );
+  }, [activeSession, activeSessionState.isProcessing, viewportMode]);
 
   const isInputActive = useChatInputState(state => state.isActive);
   const isInputExpanded = useChatInputState(state => state.isExpanded);
   const inputHeight = useChatInputState(state => state.inputHeight);
+  const bottomLayoutInsetPx = computeFlowChatInputStackFooterPx(inputHeight);
 
-  const inputStackFooterPxRef = useRef(0);
-  const previousInputStackFooterPxRef = useRef(0);
-  // Snapshot scrollTop during render, before React commits the new (smaller)
-  // footer height.  The browser has not yet clamped, so this is the accurate
-  // pre-clamp value.  Used by the useLayoutEffect below to restore scrollTop
-  // after footer-shrink compensation.
-  const footerShrinkPreScrollTopRef = useRef(0);
-  const inputStackFooterPx = computeFlowChatInputStackFooterPx(inputHeight, isInputActive);
-  // Snapshot pre-commit scrollTop before we update the footer px ref.
-  // The scrollerElement may not be set on first mount; that's fine —
-  // useLayoutEffect checks scroller !== null before restoring.
-  if (scrollerElement && canProcessViewportGeometry(scrollerElement)) {
-    footerShrinkPreScrollTopRef.current = scrollerElement.scrollTop;
-  }
-  inputStackFooterPxRef.current = inputStackFooterPx;
+  const tailSpacerPx = tailSpacerPxForViewport(viewportHeightPx, bottomLayoutInsetPx);
+  const tailSpacerPxRef = useRef(tailSpacerPx);
+  useLayoutEffect(() => {
+    tailSpacerPxRef.current = tailSpacerPx;
+  }, [tailSpacerPx]);
+  const getTailSpacerPx = useCallback(() => tailSpacerPxRef.current, []);
+
+  /*
+   * The paging diagnostics need a few session facts, but `activeSession` is a
+   * fresh object on every streaming flush: depending on it would rebuild
+   * `requestHistoryBoundary` and therefore the rendered-range effect many times
+   * a second. Hold the session itself by reference — one assignment per render,
+   * no allocation — and read the fields only on the rare diagnostic path.
+   */
+  const activeSessionRef = useRef(activeSession);
+  activeSessionRef.current = activeSession;
+
+  const isOpenViewportSettledRef = useRef(isOpenViewportSettled);
+  isOpenViewportSettledRef.current = isOpenViewportSettled;
+  const isOpeningViewport = useCallback(() => !isOpenViewportSettledRef.current, []);
+
+  const getRenderedUserMessageElement = useCallback((turnId: string) => (
+    findRenderedTurnAnchorElement(scrollerElementRef.current, turnId)
+  ), []);
 
-  const activeSessionState = useActiveSessionState();
-  const isProcessing = activeSessionState.isProcessing;
+  const readContentEndScrollTop = useCallback((scroller: HTMLElement) => (
+    contentEndScrollTop({
+      scrollHeight: scroller.scrollHeight,
+      clientHeight: scroller.clientHeight,
+      tailSpacerPx: tailSpacerPxRef.current,
+    })
+  ), []);
 
-  const getFooterHeightPx = useCallback((compensationPx: number) => {
-    return inputStackFooterPxRef.current + compensationPx;
-  }, []);
+  /**
+   * The content-end scroll, issued *through the virtualizer*.
+   *
+   * Writing the scroller directly is cheaper, but it leaves any pending re-aim
+   * in place — the virtualizer keeps chasing its last target for as long as the
+   * measurements under it move. A caller correcting one of its own scrolls has
+   * to replace that chase rather than outrun it, and only another scroll issued
+   * through the virtualizer does.
+   *
+   * The target is read off live geometry rather than aligned to the last item,
+   * because the end of *real content* is above the resident tail spacer and no
+   * item knows where that is.
+   */
+  const scrollToContentEndThroughVirtualizer = useCallback((
+    behavior: 'auto' | 'smooth',
+    owner: FlowChatViewportOwner = 'follow-output',
+    // A one-shot owner has to state its window here as anywhere else. Only a
+    // writer that releases may hold the viewport without one.
+    holdForMs?: number,
+  ) => {
+    const scroller = scrollerElementRef.current;
+    if (!scroller) return;
+    virtualizer.scrollToOffset(readContentEndScrollTop(scroller), {
+      behavior,
+      owner,
+      holdForMs,
+    });
+  }, [readContentEndScrollTop, virtualizer]);
 
-  const getTotalBottomCompensationPx = useCallback((state: BottomReservationState = bottomReservationStateRef.current) => {
-    return getReservationTotalPx(state.collapse) + getReservationTotalPx(state.pin);
-  }, []);
-
-  const acquireCollapseReservationOwner = useCallback((kind: CollapseReservationOwnerKind) => {
-    const currentOwner = collapseReservationOwnerRef.current;
-    if (currentOwner?.kind === kind) {
-      return currentOwner;
-    }
-    const nextOwner: CollapseReservationOwnerState = {
-      kind,
-      generation: collapseReservationOwnerGenerationRef.current + 1,
-    };
-    collapseReservationOwnerGenerationRef.current = nextOwner.generation;
-    collapseReservationOwnerRef.current = nextOwner;
-    return nextOwner;
-  }, []);
-
-  const clearCollapseReservationOwner = useCallback(() => {
-    collapseReservationOwnerRef.current = null;
-  }, []);
-
-  const clearRetainedCollapseSettlement = useCallback(() => {
-    retainedCollapseSettleGenerationRef.current += 1;
-    retainedCollapseGeometryGenerationRef.current = 0;
-    if (retainedCollapseSettleTimerRef.current !== null) {
-      window.clearTimeout(retainedCollapseSettleTimerRef.current);
-      retainedCollapseSettleTimerRef.current = null;
-    }
-    if (retainedCollapseSettleFrameRef.current !== null) {
-      cancelAnimationFrame(retainedCollapseSettleFrameRef.current);
-      retainedCollapseSettleFrameRef.current = null;
-    }
-    if (retainedCollapseReleaseTimerRef.current !== null) {
-      window.clearTimeout(retainedCollapseReleaseTimerRef.current);
-      retainedCollapseReleaseTimerRef.current = null;
-    }
-  }, []);
-
-  const applyFooterHeightToElement = useCallback((footer: HTMLDivElement, compensationPx: number) => {
-    const heightPx = getFooterHeightPx(compensationPx);
-    footer.style.height = `${heightPx}px`;
-    footer.style.minHeight = `${heightPx}px`;
-  }, [getFooterHeightPx]);
-
-  const handleFooterElementRef = useCallback((element: HTMLDivElement | null) => {
-    footerElementRef.current = element;
-    if (!element) {
-      return;
-    }
-
-    // Virtuoso may replace its Footer during a measurement commit. Reapply
-    // the ref-owned reservation synchronously so the physical scroll range
-    // never falls back to a stale React render for one frame.
-    applyFooterHeightToElement(element, getTotalBottomCompensationPx());
-    void element.offsetHeight;
-    void scrollerElementRef.current?.scrollHeight;
-  }, [applyFooterHeightToElement, getTotalBottomCompensationPx]);
-
-  const snapshotMeasuredContentHeight = useCallback((
-    scroller: HTMLElement,
-    reservationState: BottomReservationState = bottomReservationStateRef.current,
-  ) => {
-    const compensationPx = getTotalBottomCompensationPx(reservationState);
-    return Math.max(0, scroller.scrollHeight - compensationPx - inputStackFooterPxRef.current);
-  }, [getTotalBottomCompensationPx]);
-
-  const recordScrollerGeometry = useCallback((scroller: HTMLElement) => {
-    if (!canCoordinateViewport()) {
-      return;
-    }
-    previousScrollerGeometryRef.current = {
-      scrollTop: scroller.scrollTop,
-      scrollHeight: scroller.scrollHeight,
-      clientHeight: scroller.clientHeight,
-    };
-  }, [canCoordinateViewport]);
-
-  const rebaseViewportMeasurements = useCallback(() => {
-    const scroller = scrollerElementRef.current;
-    if (!canProcessViewportGeometry(scroller)) {
-      previousMeasuredHeightRef.current = null;
-      previousScrollerGeometryRef.current = null;
-      return;
-    }
-    previousMeasuredHeightRef.current = snapshotMeasuredContentHeight(scroller);
-    previousScrollTopRef.current = scroller.scrollTop;
-    recordScrollerGeometry(scroller);
-  }, [canProcessViewportGeometry, recordScrollerGeometry, snapshotMeasuredContentHeight]);
-
-  const recordScrollerGeometryIfLayoutStable = useCallback((scroller: HTMLElement) => {
-    const previousGeometry = previousScrollerGeometryRef.current;
-    if (
-      previousGeometry &&
-      (
-        Math.abs(scroller.clientHeight - previousGeometry.clientHeight) > COMPENSATION_EPSILON_PX ||
-        Math.abs(scroller.scrollHeight - previousGeometry.scrollHeight) > COMPENSATION_EPSILON_PX
-      )
-    ) {
-      return;
-    }
-    recordScrollerGeometry(scroller);
-  }, [recordScrollerGeometry]);
-
-  const restartHistoryPresentationCommitQuietWaiters = useCallback(() => {
-    historyPresentationCommitQuietWaitersRef.current.forEach(waiter => waiter.restart());
-  }, []);
-
-  const cancelHistoryPresentationCommitQuietWaiters = useCallback(() => {
-    historyPresentationCommitQuietGenerationRef.current += 1;
-    const waiters = Array.from(historyPresentationCommitQuietWaitersRef.current);
-    waiters.forEach(waiter => waiter.cancel());
-  }, []);
-
-  const waitForHistoryPresentationCommitQuiet = useCallback((sessionId: string): Promise<boolean> => {
-    const generation = historyPresentationCommitQuietGenerationRef.current;
-
-    return new Promise(resolve => {
-      let timerId: number | null = null;
-      let settled = false;
-      let waiter: HistoryPresentationCommitQuietWaiter | null = null;
-
-      const finish = (ready: boolean) => {
-        if (settled) {
-          return;
-        }
-        settled = true;
-        if (timerId !== null) {
-          window.clearTimeout(timerId);
-          timerId = null;
-        }
-        if (waiter) {
-          historyPresentationCommitQuietWaitersRef.current.delete(waiter);
-        }
-        resolve(ready);
-      };
-
-      const check = () => {
-        timerId = null;
-        const scroller = scrollerElementRef.current;
-        if (
-          generation !== historyPresentationCommitQuietGenerationRef.current
-          || activeSessionIdRef.current !== sessionId
-          || !scroller?.isConnected
-        ) {
-          finish(false);
-          return;
-        }
-
-        const hasActivePointerGesture = (
-          touchScrollIntentStartYRef.current !== null
-          || scrollbarPointerInteractionActiveRef.current
-        );
-        const quietForMs = performance.now() - lastUserScrollIntentAtMsRef.current;
-        if (!hasActivePointerGesture && quietForMs >= HISTORY_PRESENTATION_COMMIT_SCROLL_QUIET_MS) {
-          finish(true);
-          return;
-        }
-
-        const remainingQuietMs = hasActivePointerGesture
-          ? HISTORY_PRESENTATION_COMMIT_SCROLL_QUIET_MS
-          : HISTORY_PRESENTATION_COMMIT_SCROLL_QUIET_MS - quietForMs;
-        timerId = window.setTimeout(check, Math.max(1, remainingQuietMs));
-      };
-
-      waiter = {
-        cancel: () => finish(false),
-        restart: () => {
-          if (settled) {
-            return;
-          }
-          if (timerId !== null) {
-            window.clearTimeout(timerId);
-            timerId = null;
-          }
-          timerId = window.setTimeout(check, HISTORY_PRESENTATION_COMMIT_SCROLL_QUIET_MS);
-        },
-      };
-      historyPresentationCommitQuietWaitersRef.current.add(waiter);
-      check();
-    });
-  }, []);
-
-  const notifyUserScrollIntent = useCallback((reason = 'user-scroll-intent') => {
-    lastUserScrollIntentAtMsRef.current = performance.now();
-    restartHistoryPresentationCommitQuietWaiters();
-    if (historyProjectionHandoffRef.current) {
-      clearHistoryProjectionHandoffRef.current(reason);
-    }
-    if (flowChatDiagnostics.isEnabled()) {
-      flowChatDiagnostics.trace({
-        hypothesis: 'A',
-        location: 'VirtualMessageList.notifyUserScrollIntent',
-        message: 'User scroll intent requested viewport ownership release',
-        data: () => {
-          const scroller = scrollerElementRef.current;
-          return {
-            reason,
-            coordinatorMode: viewportCoordinatorRef.current.getMode(),
-            isFollowingOutput: isFollowingOutputRef.current,
-            isStreamingOutput: isStreamingOutputRef.current,
-            reservation: bottomReservationStateRef.current,
-            pendingCollapseIntent: pendingCollapseIntentRef.current.active,
-            scrollTop: scroller?.scrollTop ?? null,
-            scrollHeight: scroller?.scrollHeight ?? null,
-            clientHeight: scroller?.clientHeight ?? null,
-          };
-        },
-      });
-    }
-    clearRetainedCollapseSettlement();
-    retainedCollapseAnchorRef.current = null;
-    exitPinnedViewportForUserIntentRef.current(reason);
-    followOutputControllerRef.current.handleUserScrollIntent();
-    onUserScrollIntent?.();
-  }, [
-    clearRetainedCollapseSettlement,
-    onUserScrollIntent,
-    restartHistoryPresentationCommitQuietWaiters,
-  ]);
-
-  const syncPhysicalBottomAfterViewportResize = useCallback((scroller: HTMLElement): boolean => {
-    if (!canProcessViewportGeometry(scroller)) {
-      return false;
-    }
-    const previousGeometry = previousScrollerGeometryRef.current;
-    if (!previousGeometry) {
-      return false;
-    }
-
-    // A growing message/footer changes scrollHeight, not the viewport. Only a
-    // client-height change is a real viewport resize that should preserve a
-    // physical-bottom anchor; otherwise a newly appended footer would push the
-    // existing transcript upward by re-pinning to the new bottom.
-    const viewportHeightChanged =
-      Math.abs(scroller.clientHeight - previousGeometry.clientHeight) > COMPENSATION_EPSILON_PX;
-    if (
-      !viewportHeightChanged ||
-      pendingCollapseIntentRef.current.active ||
-      retainedCollapseAnchorRef.current !== null
-    ) {
-      return false;
-    }
-
-    const previousMaxScrollTop = Math.max(0, previousGeometry.scrollHeight - previousGeometry.clientHeight);
-    const wasAtPhysicalBottom =
-      Math.abs(previousMaxScrollTop - previousGeometry.scrollTop) <= LATEST_END_ANCHOR_STABLE_EPSILON_PX;
-    if (!wasAtPhysicalBottom) {
-      return false;
-    }
-
-    const maxScrollTop = Math.max(0, scroller.scrollHeight - scroller.clientHeight);
-    const ownsElementAnchor = viewportCoordinatorRef.current.ownsElementAnchor();
-    const isFollowingTail = (
-      isFollowingOutputRef.current &&
-      isStreamingOutputRef.current &&
-      viewportCoordinatorRef.current.getMode() === 'following-tail'
-    );
-    const willWrite = shouldSyncPhysicalBottom({
-      viewportHeightChanged,
-      collapseProtectionActive: pendingCollapseIntentRef.current.active,
-      wasAtPhysicalBottom,
-      ownsElementAnchor,
-      isFollowingTail,
-    }) && Math.abs(maxScrollTop - scroller.scrollTop) > COMPENSATION_EPSILON_PX;
-    if (ownsElementAnchor) {
-      viewportCoordinatorRef.current.restoreElementAnchor(scroller, 'viewport-resize');
-      previousScrollTopRef.current = scroller.scrollTop;
-      recordScrollerGeometry(scroller);
-      return true;
-    }
-
-    if (willWrite) {
-      scroller.scrollTop = maxScrollTop;
-    }
-    previousScrollTopRef.current = scroller.scrollTop;
-    previousMeasuredHeightRef.current = snapshotMeasuredContentHeight(scroller);
-    recordScrollerGeometry(scroller);
-    return true;
-  }, [canProcessViewportGeometry, recordScrollerGeometry, snapshotMeasuredContentHeight]);
-
-  const updateBottomReservationState = useCallback((
-    updater: BottomReservationState | ((prev: BottomReservationState) => BottomReservationState),
-  ) => {
-    const previous = bottomReservationStateRef.current;
-    const rawNext = typeof updater === 'function' ? updater(previous) : updater;
-    const sanitizedNext = sanitizeBottomReservationState(rawNext);
-    const hasNextCollapseReservation = (
-      sanitizedNext.collapse.px > COMPENSATION_EPSILON_PX ||
-      sanitizedNext.collapse.floorPx > COMPENSATION_EPSILON_PX
-    );
-    const next = hasNextCollapseReservation && collapseReservationOwnerRef.current === null
-      ? sanitizeBottomReservationState({
-        ...sanitizedNext,
-        collapse: {
-          ...sanitizedNext.collapse,
-          px: 0,
-          floorPx: 0,
-        },
-      })
-      : sanitizedNext;
-    if (
-      hasNextCollapseReservation &&
-      collapseReservationOwnerRef.current === null &&
-      flowChatDiagnostics.isEnabled()
-    ) {
-      flowChatDiagnostics.trace({
-        hypothesis: 'C',
-        location: 'VirtualMessageList.updateBottomReservationState',
-        message: 'Anonymous collapse reservation was rejected',
-        data: () => ({
-          before: previous,
-          rejected: sanitizedNext,
-          accepted: next,
-          coordinatorMode: viewportCoordinatorRef.current.getMode(),
-          isFollowingOutput: isFollowingOutputRef.current,
-          isStreamingOutput: isStreamingOutputRef.current,
-        }),
-      });
-    }
-    if (
-      next.collapse.px <= COMPENSATION_EPSILON_PX &&
-      !pendingCollapseIntentRef.current.active &&
-      retainedCollapseAnchorRef.current === null
-    ) {
-      clearCollapseReservationOwner();
-    }
-    if (
-      flowChatDiagnostics.isEnabled() &&
-      !areBottomReservationStatesEqual(previous, next)
-    ) {
-      flowChatDiagnostics.trace({
-        hypothesis: 'A',
-        location: 'VirtualMessageList.updateBottomReservationState',
-        message: 'Bottom reservation state changed',
-        data: () => ({
-          before: previous,
-          after: next,
-          collapseReservationOwner: collapseReservationOwnerRef.current,
-          coordinatorMode: viewportCoordinatorRef.current.getMode(),
-          isFollowingOutput: isFollowingOutputRef.current,
-          isStreamingOutput: isStreamingOutputRef.current,
-        }),
-      });
-    }
-    bottomReservationStateRef.current = next;
-    setBottomReservationState(prev => {
-      return areBottomReservationStatesEqual(next, prev) ? prev : next;
-    });
-  }, [clearCollapseReservationOwner]);
-
-  const clearTurnPinRequest = useCallback(() => {
-    turnPinRequestGenerationRef.current += 1;
-    pendingTurnPinGenerationRef.current = null;
-    activeTurnPinRequestRef.current = null;
-    preparedHistoryTurnPinRef.current = null;
-    transientTurnPinStabilizationRef.current = null;
-
-    if (turnPinStabilizationFrameRef.current !== null) {
-      cancelAnimationFrame(turnPinStabilizationFrameRef.current);
-      turnPinStabilizationFrameRef.current = null;
-    }
-
-    setPendingTurnPin(null);
-  }, []);
-
-  const settleBestEffortTurnPin = useCallback((request: PendingTurnPinState) => {
-    if (request.alignmentPolicy !== 'best-effort') {
-      return false;
-    }
-
-    transientTurnPinStabilizationRef.current = null;
-    if (viewportCoordinatorRef.current.getMode() === 'pinned-item') {
-      viewportCoordinatorRef.current.release('best-effort-turn-pin-settled');
-    }
-    clearTurnPinRequest();
-    return true;
-  }, [clearTurnPinRequest]);
-
-  const cancelLatestEndAnchorStabilization = useCallback(() => {
-    if (latestEndAnchorStabilizationFrameRef.current !== null) {
-      cancelAnimationFrame(latestEndAnchorStabilizationFrameRef.current);
-      latestEndAnchorStabilizationFrameRef.current = null;
-    }
-    latestEndAnchorRequestRef.current = null;
-  }, []);
-
-  const activateTransientTurnPinStabilization = useCallback((request: PendingTurnPinState) => {
-    if (request.pinMode !== 'transient') {
-      return;
-    }
-
-    const current = transientTurnPinStabilizationRef.current;
-    const continuesCurrentRequest = current?.generation === request.generation;
-    transientTurnPinStabilizationRef.current = {
-      ...request,
-      behavior: 'auto',
-      attempts: continuesCurrentRequest
-        ? Math.max(request.attempts + 1, current.attempts)
-        : request.attempts + 1,
-      stableAlignedFrames: continuesCurrentRequest ? current.stableAlignedFrames : 0,
-      lastScrollTop: continuesCurrentRequest ? current.lastScrollTop : null,
-      lastTargetTop: continuesCurrentRequest ? current.lastTargetTop : null,
-    };
-  }, []);
-
-  const resetBottomReservations = useCallback(() => {
-    clearCollapseReservationOwner();
-    updateBottomReservationState(createInitialBottomReservationState());
-  }, [clearCollapseReservationOwner, updateBottomReservationState]);
-
-  const consumeBottomCompensation = useCallback((
-    amountPx: number,
-    options?: {
-      consumeStickyPinFloor?: boolean;
-      preserveCollapseReservation?: boolean;
-    },
-  ) => {
-    if (amountPx <= COMPENSATION_EPSILON_PX) {
-      return bottomReservationStateRef.current;
-    }
-
-    let resolvedNextState = bottomReservationStateRef.current;
-    updateBottomReservationState(prev => {
-      const nextState = consumeBottomReservationForContentGrowth(
-        prev,
-        amountPx,
-        options?.consumeStickyPinFloor === true,
-        options?.preserveCollapseReservation === true,
-      );
-      resolvedNextState = nextState;
-      return nextState;
-    });
-    return resolvedNextState;
-  }, [updateBottomReservationState]);
-
-  const applyFooterCompensationNow = useCallback((compensation: BottomReservationState) => {
-    const footer = footerElementRef.current;
-    const scroller = scrollerElementRef.current;
-    if (!footer || !scroller) return;
-
-    const appliedState = areBottomReservationStatesEqual(
-      compensation,
-      bottomReservationStateRef.current,
-    )
-      ? compensation
-      : bottomReservationStateRef.current;
-    const compensationPx = getTotalBottomCompensationPx(appliedState);
-    applyFooterHeightToElement(footer, compensationPx);
-    void footer.offsetHeight;
-    void scroller.scrollHeight;
-    if (flowChatDiagnostics.isEnabled()) {
-      flowChatDiagnostics.trace({
-        hypothesis: 'C',
-        location: 'VirtualMessageList.applyFooterCompensationNow',
-        message: 'Footer compensation applied synchronously',
-        data: () => ({
-          compensationPx,
-          renderedHeight: footer.getBoundingClientRect().height,
-          scrollTop: scroller.scrollTop,
-          scrollHeight: scroller.scrollHeight,
-          clientHeight: scroller.clientHeight,
-          coordinatorMode: viewportCoordinatorRef.current.getMode(),
-        }),
-      });
-    }
-  }, [applyFooterHeightToElement, getTotalBottomCompensationPx]);
-
-  const clearBottomReservationsForUserBrowsing = useCallback(() => {
-    const currentState = bottomReservationStateRef.current;
-    const nextState = createInitialBottomReservationState();
-    pendingCollapseIntentRef.current = createInactiveCollapseIntentState();
-    retainedCollapseAnchorRef.current = null;
-    clearCollapseReservationOwner();
-
-    if (areBottomReservationStatesEqual(currentState, nextState)) {
-      return;
-    }
-
-    updateBottomReservationState(nextState);
-    applyFooterCompensationNow(nextState);
-
-    const scroller = scrollerElementRef.current;
-    if (scroller) {
-      previousScrollTopRef.current = scroller.scrollTop;
-      previousMeasuredHeightRef.current = snapshotMeasuredContentHeight(scroller, nextState);
-      recordScrollerGeometry(scroller);
-    }
-  }, [
-    applyFooterCompensationNow,
-    clearCollapseReservationOwner,
-    recordScrollerGeometry,
-    snapshotMeasuredContentHeight,
-    updateBottomReservationState,
-  ]);
-
-  const preserveCollapseAnchorScrollTop = useCallback((
-    scroller: HTMLElement,
-    targetScrollTop: number,
-    source: string,
-  ) => {
-    const currentState = bottomReservationStateRef.current;
-    const nextState = ensureCollapseReservationForScrollTop(currentState, {
-      targetScrollTop,
-      scrollHeight: scroller.scrollHeight,
-      clientHeight: scroller.clientHeight,
-    });
-    const reservationChanged = !areBottomReservationStatesEqual(currentState, nextState);
-    if (reservationChanged) {
-      if (
-        nextState.collapse.px > COMPENSATION_EPSILON_PX &&
-        collapseReservationOwnerRef.current === null
-      ) {
-        acquireCollapseReservationOwner('preserved-element');
-      }
-      updateBottomReservationState(nextState);
-      applyFooterCompensationNow(nextState);
-    }
-
-    const scrollTopBefore = scroller.scrollTop;
-    const maxScrollTop = Math.max(0, scroller.scrollHeight - scroller.clientHeight);
-    const restoredScrollTop = Math.min(maxScrollTop, Math.max(scrollTopBefore, targetScrollTop));
-    const scrollTopChanged = restoredScrollTop - scrollTopBefore > COMPENSATION_EPSILON_PX;
-    if (scrollTopChanged) {
-      scroller.scrollTop = restoredScrollTop;
-    }
-
-    if (flowChatDiagnostics.isEnabled() && (reservationChanged || scrollTopChanged)) {
-      flowChatDiagnostics.trace({
-        hypothesis: 'E',
-        location: 'VirtualMessageList.preserveCollapseAnchorScrollTop',
-        message: 'Collapse anchor range restored synchronously',
-        data: () => ({
-          source,
-          targetScrollTop,
-          scrollTopBefore,
-          scrollTopAfter: scroller.scrollTop,
-          scrollHeight: scroller.scrollHeight,
-          clientHeight: scroller.clientHeight,
-          reservationBefore: currentState,
-          reservationAfter: bottomReservationStateRef.current,
-          coordinatorMode: viewportCoordinatorRef.current.getMode(),
-        }),
-      });
-    }
-
-    previousScrollTopRef.current = scroller.scrollTop;
-    previousMeasuredHeightRef.current = snapshotMeasuredContentHeight(
-      scroller,
-      bottomReservationStateRef.current,
-    );
-    recordScrollerGeometry(scroller);
-    return reservationChanged || scrollTopChanged;
-  }, [
-    applyFooterCompensationNow,
-    acquireCollapseReservationOwner,
-    recordScrollerGeometry,
-    snapshotMeasuredContentHeight,
-    updateBottomReservationState,
-  ]);
-
-  const settleRetainedCollapseRange = useCallback((reason: string, generation: number) => {
-    if (generation !== retainedCollapseSettleGenerationRef.current) {
-      return;
-    }
-    const retainedAnchor = retainedCollapseAnchorRef.current;
-    const scroller = scrollerElementRef.current;
-    if (!retainedAnchor || !scroller || pendingCollapseIntentRef.current.active) {
-      return;
-    }
-
-    const targetScrollTop = Math.max(retainedAnchor.anchorScrollTop, scroller.scrollTop);
-    retainedAnchor.anchorScrollTop = targetScrollTop;
-    const currentState = bottomReservationStateRef.current;
-    const nextState = settleRetainedCollapseReservationForAnchor(currentState, {
-      targetScrollTop,
-      scrollHeight: scroller.scrollHeight,
-      clientHeight: scroller.clientHeight,
-    });
-    const reservationChanged = !areBottomReservationStatesEqual(currentState, nextState);
-    if (reservationChanged) {
-      updateBottomReservationState(nextState);
-      applyFooterCompensationNow(nextState);
-    }
-    preserveCollapseAnchorScrollTop(scroller, targetScrollTop, `quiet-settle:${reason}`);
-
-    const releaseGeneration = retainedCollapseSettleGenerationRef.current;
-    retainedCollapseGeometryGenerationRef.current += 1;
-    const scheduleReleaseWhenQuiet = (geometryGeneration: number) => {
-      retainedCollapseReleaseTimerRef.current = window.setTimeout(() => {
-        retainedCollapseReleaseTimerRef.current = null;
-        if (releaseGeneration !== retainedCollapseSettleGenerationRef.current) {
-          return;
-        }
-        const currentGeometryGeneration = retainedCollapseGeometryGenerationRef.current;
-        if (currentGeometryGeneration !== geometryGeneration) {
-          scheduleReleaseWhenQuiet(currentGeometryGeneration);
-          return;
-        }
-        retainedCollapseAnchorRef.current = null;
-        retainedCollapseGeometryGenerationRef.current = 0;
-        if (bottomReservationStateRef.current.collapse.px <= COMPENSATION_EPSILON_PX) {
-          clearCollapseReservationOwner();
-        }
-        if (flowChatDiagnostics.isEnabled()) {
-          flowChatDiagnostics.trace({
-            hypothesis: 'F',
-            location: 'VirtualMessageList.releaseSettledCollapseAnchor',
-            message: 'Settled collapse anchor released after layout remained quiet',
-            data: () => ({
-              reason,
-              retainedAnchor,
-              reservation: bottomReservationStateRef.current,
-              scrollTop: scroller.scrollTop,
-              scrollHeight: scroller.scrollHeight,
-              clientHeight: scroller.clientHeight,
-              coordinatorMode: viewportCoordinatorRef.current.getMode(),
-            }),
-          });
-        }
-      }, RETAINED_COLLAPSE_RELEASE_QUIET_MS);
-    };
-    scheduleReleaseWhenQuiet(retainedCollapseGeometryGenerationRef.current);
-
-    if (flowChatDiagnostics.isEnabled()) {
-      flowChatDiagnostics.trace({
-        hypothesis: 'F',
-        location: 'VirtualMessageList.settleRetainedCollapseRange',
-        message: 'Retained collapse range settled to current anchor geometry',
-        data: () => ({
-          reason,
-          retainedAnchor,
-          targetScrollTop,
-          reservationBefore: currentState,
-          reservationAfter: bottomReservationStateRef.current,
-          releasedPx: Math.max(
-            0,
-            getReservationTotalPx(currentState.collapse) -
-              getReservationTotalPx(bottomReservationStateRef.current.collapse),
-          ),
-          scrollTop: scroller.scrollTop,
-          scrollHeight: scroller.scrollHeight,
-          clientHeight: scroller.clientHeight,
-          coordinatorMode: viewportCoordinatorRef.current.getMode(),
-        }),
-      });
-    }
-  }, [
-    applyFooterCompensationNow,
-    clearCollapseReservationOwner,
-    preserveCollapseAnchorScrollTop,
-    updateBottomReservationState,
-  ]);
-
-  const scheduleRetainedCollapseSettlement = useCallback((reason: string) => {
-    if (
-      retainedCollapseAnchorRef.current === null ||
-      pendingCollapseIntentRef.current.active
-    ) {
-      return;
-    }
-
-    clearRetainedCollapseSettlement();
-    retainedCollapseGeometryGenerationRef.current += 1;
-    const generation = retainedCollapseSettleGenerationRef.current;
-    retainedCollapseSettleTimerRef.current = window.setTimeout(() => {
-      retainedCollapseSettleTimerRef.current = null;
-      const settleAfterFrames = (remainingFrames: number) => {
-        retainedCollapseSettleFrameRef.current = requestAnimationFrame(() => {
-          if (generation !== retainedCollapseSettleGenerationRef.current) {
-            retainedCollapseSettleFrameRef.current = null;
-            return;
-          }
-          if (remainingFrames > 1) {
-            settleAfterFrames(remainingFrames - 1);
-            return;
-          }
-          retainedCollapseSettleFrameRef.current = null;
-          settleRetainedCollapseRange(reason, generation);
-        });
-      };
-      settleAfterFrames(RETAINED_COLLAPSE_QUIET_SETTLE_FRAMES);
-    }, RETAINED_COLLAPSE_QUIET_SETTLE_MS);
-  }, [clearRetainedCollapseSettlement, settleRetainedCollapseRange]);
-
-  const retainCollapseRangeForQuietSettlement = useCallback((
-    anchor: RetainedCollapseAnchorState,
-    reason: string,
-  ) => {
-    acquireCollapseReservationOwner(
-      anchor.toolName === 'late-shrink-clamp' ? 'late-shrink-clamp' : 'retained-collapse',
-    );
-    const scroller = scrollerElementRef.current;
-    const currentState = bottomReservationStateRef.current;
-    if (currentState.collapse.px <= COMPENSATION_EPSILON_PX) {
-      clearRetainedCollapseSettlement();
-      retainedCollapseAnchorRef.current = null;
-      clearCollapseReservationOwner();
-      return;
-    }
-    const previousRetainedAnchor = retainedCollapseAnchorRef.current;
-    const nextRetainedAnchor: RetainedCollapseAnchorState = {
-      anchorScrollTop: Math.max(
-        anchor.anchorScrollTop,
-        previousRetainedAnchor?.anchorScrollTop ?? 0,
-        scroller?.scrollTop ?? 0,
-      ),
-      toolId: anchor.toolId ?? previousRetainedAnchor?.toolId ?? null,
-      toolName: anchor.toolName ?? previousRetainedAnchor?.toolName ?? null,
-    };
-    retainedCollapseAnchorRef.current = nextRetainedAnchor;
-
-    const nextState = scroller
-      ? ensureCollapseReservationForScrollTop(currentState, {
-        targetScrollTop: nextRetainedAnchor.anchorScrollTop,
-        scrollHeight: scroller.scrollHeight,
-        clientHeight: scroller.clientHeight,
-      })
-      : protectCurrentCollapseReservation(currentState);
-    if (!areBottomReservationStatesEqual(currentState, nextState)) {
-      updateBottomReservationState(nextState);
-      applyFooterCompensationNow(nextState);
-    }
-    if (scroller) {
-      preserveCollapseAnchorScrollTop(
-        scroller,
-        nextRetainedAnchor.anchorScrollTop,
-        `retain:${reason}`,
-      );
-    }
-    scheduleRetainedCollapseSettlement(reason);
-
-    if (flowChatDiagnostics.isEnabled()) {
-      flowChatDiagnostics.trace({
-        hypothesis: 'E',
-        location: 'VirtualMessageList.retainCollapseRangeForQuietSettlement',
-        message: 'Collapse range retained until delayed measurements settle',
-        data: () => ({
-          reason,
-          retainedAnchor: nextRetainedAnchor,
-          reservationBefore: currentState,
-          reservationAfter: bottomReservationStateRef.current,
-          scrollTop: scroller?.scrollTop ?? null,
-          scrollHeight: scroller?.scrollHeight ?? null,
-          clientHeight: scroller?.clientHeight ?? null,
-        }),
-      });
-    }
-  }, [
-    applyFooterCompensationNow,
-    acquireCollapseReservationOwner,
-    clearCollapseReservationOwner,
-    clearRetainedCollapseSettlement,
-    preserveCollapseAnchorScrollTop,
-    scheduleRetainedCollapseSettlement,
-    updateBottomReservationState,
-  ]);
-
-  const clearPendingStickyPinGrowth = useCallback((_reason: string) => {
-    if (stickyPinGrowthSettleTimerRef.current !== null) {
-      window.clearTimeout(stickyPinGrowthSettleTimerRef.current);
-      stickyPinGrowthSettleTimerRef.current = null;
-    }
-    pendingStickyPinGrowthRef.current = {
-      targetTurnId: null,
-      amountPx: 0,
-    };
-  }, []);
-
-  const settlePendingStickyPinGrowth = useCallback((reason: string) => {
-    stickyPinGrowthSettleTimerRef.current = null;
-    const pending = pendingStickyPinGrowthRef.current;
-    if (pending.amountPx <= COMPENSATION_EPSILON_PX || !pending.targetTurnId) {
-      return;
-    }
-
-    const currentState = bottomReservationStateRef.current;
-    const pinReservation = currentState.pin;
-    if (
-      pinReservation.mode !== 'sticky-latest' ||
-      pinReservation.targetTurnId !== pending.targetTurnId ||
-      !viewportCoordinatorRef.current.ownsElementAnchor()
-    ) {
-      clearPendingStickyPinGrowth(`${reason}:pin-owner-changed`);
-      return;
-    }
-
-    if (pendingCollapseIntentRef.current.active) {
-      stickyPinGrowthSettleTimerRef.current = window.setTimeout(() => {
-        settlePendingStickyPinGrowthRef.current('collapse-settled-retry');
-      }, 50);
-      return;
-    }
-
-    const consumedPx = Math.min(pending.amountPx, pinReservation.floorPx);
-    pendingStickyPinGrowthRef.current = {
-      targetTurnId: null,
-      amountPx: 0,
-    };
-    if (consumedPx <= COMPENSATION_EPSILON_PX) {
-      clearPendingStickyPinGrowth(`${reason}:nothing-consumable`);
-      return;
-    }
-
-    const nextState = sanitizeBottomReservationState({
-      ...currentState,
-      pin: {
-        ...pinReservation,
-        px: pinReservation.px - consumedPx,
-        floorPx: pinReservation.floorPx - consumedPx,
-      },
-    });
-    updateBottomReservationState(nextState);
-    applyFooterCompensationNow(nextState);
-    const scroller = scrollerElementRef.current;
-    if (scroller) {
-      viewportCoordinatorRef.current.restoreElementAnchor(scroller, 'sticky-pin-growth-settled');
-      previousScrollTopRef.current = scroller.scrollTop;
-      previousMeasuredHeightRef.current = snapshotMeasuredContentHeight(scroller, nextState);
-      recordScrollerGeometry(scroller);
-    }
-    maybeHandoffPinnedTurnToTailRef.current(`sticky-pin-growth-settled:${reason}`);
-  }, [
-    applyFooterCompensationNow,
-    clearPendingStickyPinGrowth,
-    recordScrollerGeometry,
-    snapshotMeasuredContentHeight,
-    updateBottomReservationState,
-  ]);
-  settlePendingStickyPinGrowthRef.current = settlePendingStickyPinGrowth;
-
-  const reconcilePendingStickyPinGrowthSettlement = useCallback((
-    reason: string,
-    options?: { preserveExistingQuietTimer?: boolean },
-  ) => {
-    const pending = pendingStickyPinGrowthRef.current;
-    const strategy = resolveStickyPinGrowthSettlementStrategy({
-      pendingGrowthPx: pending.amountPx,
-      pinFloorPx: bottomReservationStateRef.current.pin.floorPx,
-      hasActiveCollapseIntent: pendingCollapseIntentRef.current.active,
-    });
-
-    if (strategy === 'none') {
-      clearPendingStickyPinGrowth(`${reason}:nothing-pending`);
-      return;
-    }
-    if (strategy === 'settle-now') {
-      if (stickyPinGrowthSettleTimerRef.current !== null) {
-        window.clearTimeout(stickyPinGrowthSettleTimerRef.current);
-        stickyPinGrowthSettleTimerRef.current = null;
-      }
-      settlePendingStickyPinGrowthRef.current(`${reason}:threshold-reached`);
-      return;
-    }
-    if (strategy === 'wait-for-collapse') {
-      if (stickyPinGrowthSettleTimerRef.current !== null) {
-        window.clearTimeout(stickyPinGrowthSettleTimerRef.current);
-        stickyPinGrowthSettleTimerRef.current = null;
-      }
-      return;
-    }
-    if (
-      options?.preserveExistingQuietTimer &&
-      stickyPinGrowthSettleTimerRef.current !== null
-    ) {
-      return;
-    }
-
-    if (stickyPinGrowthSettleTimerRef.current !== null) {
-      window.clearTimeout(stickyPinGrowthSettleTimerRef.current);
-    }
-    stickyPinGrowthSettleTimerRef.current = window.setTimeout(() => {
-      settlePendingStickyPinGrowthRef.current('settle-timeout');
-    }, STICKY_PIN_GROWTH_SETTLE_MS);
-  }, [clearPendingStickyPinGrowth]);
-
-  const queuePendingStickyPinGrowth = useCallback((targetTurnId: string, amountPx: number) => {
-    const sanitizedAmountPx = sanitizeReservationPx(amountPx);
-    if (sanitizedAmountPx <= COMPENSATION_EPSILON_PX) {
-      return;
-    }
-
-    const previousPending = pendingStickyPinGrowthRef.current;
-    const nextPending = previousPending.targetTurnId === targetTurnId
-      ? {
-        targetTurnId,
-        amountPx: previousPending.amountPx + sanitizedAmountPx,
-      }
-      : {
-        targetTurnId,
-        amountPx: sanitizedAmountPx,
-      };
-    pendingStickyPinGrowthRef.current = nextPending;
-    reconcilePendingStickyPinGrowthSettlement('growth-queued');
-  }, [reconcilePendingStickyPinGrowthSettlement]);
-
-  useEffect(() => () => {
-    if (stickyPinGrowthSettleTimerRef.current !== null) {
-      window.clearTimeout(stickyPinGrowthSettleTimerRef.current);
-      stickyPinGrowthSettleTimerRef.current = null;
-    }
-  }, []);
-
-  const ensureSemanticAnchorRange = useCallback((
-    options: Parameters<FlowChatViewportRangeHost['ensureBottomRange']>[0],
-  ) => {
-    const additionalPx = sanitizeReservationPx(options.additionalPx);
-    const footer = footerElementRef.current;
-    const scroller = scrollerElementRef.current;
-    if (
-      additionalPx <= COMPENSATION_EPSILON_PX ||
-      !footer ||
-      !canProcessViewportGeometry(scroller)
-    ) {
-      return false;
-    }
-
-    const previousState = bottomReservationStateRef.current;
-    const nextState: BottomReservationState = options.mode === 'pinned-item'
-      ? {
-        ...previousState,
-        pin: {
-          ...previousState.pin,
-          px: previousState.pin.px + additionalPx,
-          floorPx: previousState.pin.mode === 'sticky-latest'
-            ? previousState.pin.floorPx + additionalPx
-            : previousState.pin.floorPx,
-        },
-      }
-      : {
-        ...previousState,
-        collapse: {
-          ...previousState.collapse,
-          px: previousState.collapse.px + additionalPx,
-        },
-      };
-
-    if (
-      options.mode !== 'pinned-item' &&
-      collapseReservationOwnerRef.current === null
-    ) {
-      acquireCollapseReservationOwner('preserved-element');
-    }
-    updateBottomReservationState(nextState);
-    applyFooterCompensationNow(nextState);
-    previousMeasuredHeightRef.current = snapshotMeasuredContentHeight(scroller, nextState);
-    return true;
-  }, [
-    applyFooterCompensationNow,
-    acquireCollapseReservationOwner,
-    canProcessViewportGeometry,
-    snapshotMeasuredContentHeight,
-    updateBottomReservationState,
-  ]);
-
-  useLayoutEffect(() => {
-    const coordinator = viewportCoordinatorRef.current;
-    coordinator.setRangeHost({
-      ensureBottomRange: ensureSemanticAnchorRange,
-    });
-    return () => {
-      coordinator.setRangeHost(null);
-    };
-  }, [ensureSemanticAnchorRange]);
-
-  // When the input collapses (e.g. user sends a message), preserve its previous
-  // space as a reservation before synchronizing the ref-owned Footer height.
-  // The Virtuoso Footer has no React-owned height, so this layout effect is the
-  // single writer for input-stack height changes and cannot expose a smaller
-  // intermediate Footer to the browser.
-  //
-  // Detect the footer shrink in a useLayoutEffect (fires synchronously after
-  // commit, before paint) and extend the bottom collapse reservation by the
-  // shrink amount so the total footer height stays unchanged.  The reservation
-  // is later consumed organically by the grow branch of measureHeightChange as
-  // streaming content arrives.
-  useLayoutEffect(() => {
-    const prevFooterPx = previousInputStackFooterPxRef.current;
-    const currFooterPx = inputStackFooterPx;
-    previousInputStackFooterPxRef.current = currFooterPx;
-
-    const scroller = scrollerElementRef.current;
-    if (!canProcessViewportGeometry(scroller)) {
-      return;
-    }
-
-    const shrinkAmount = prevFooterPx - currFooterPx;
-    if (shrinkAmount <= COMPENSATION_EPSILON_PX) {
-      applyFooterCompensationNow(bottomReservationStateRef.current);
-      return;
-    }
-
-    // Use the pre-commit scrollTop captured during render. It also protects
-    // against any unrelated virtualizer measurement committed in this render.
-    const preClampScrollTop = footerShrinkPreScrollTopRef.current;
-
-    const baseState = bottomReservationStateRef.current;
-    const currentCollapsePx = getReservationTotalPx(baseState.collapse);
-    const nextReservationState: BottomReservationState = {
-      ...baseState,
-      collapse: {
-        ...baseState.collapse,
-        px: currentCollapsePx + shrinkAmount,
-      },
-    };
-    if (collapseReservationOwnerRef.current === null) {
-      acquireCollapseReservationOwner('input-stack-shrink');
-    }
-    updateBottomReservationState(nextReservationState);
-    applyFooterCompensationNow(nextReservationState);
-
-    // Restore scrollTop to the pre-clamp position if the browser already
-    // clamped it during the commit.  After extending the footer via
-    // compensation, the total scrollHeight is back to its pre-shrink value,
-    // so restoring the old scrollTop is safe.
-    if (scroller && preClampScrollTop !== undefined) {
-      const maxScrollTop = Math.max(
-        0,
-        scroller.scrollHeight - scroller.clientHeight,
-      );
-      scroller.scrollTop = Math.min(preClampScrollTop, maxScrollTop);
-    }
-
-    // If no streaming is in progress, schedule a consumption pass to drain
-    // the compensation added above. Without streaming, the grow branch of
-    // measureHeightChange never fires, so the residual collapse.px would
-    // persist as permanent footer whitespace (issue #1176).
-    if (!isStreamingOutputRef.current) {
-      requestAnimationFrame(() => {
-        const scrollerNow = scrollerElementRef.current;
-        if (!canProcessViewportGeometry(scrollerNow)) {
-          return;
-        }
-        // Do not drain if a collapse intent is still protecting an ongoing
-        // CSS transition or delayed virtualizer measurement.
-        const intent = pendingCollapseIntentRef.current;
-        if (intent.active || retainedCollapseAnchorRef.current) return;
-        const collapsePx = getReservationTotalPx(bottomReservationStateRef.current.collapse);
-        if (collapsePx <= COMPENSATION_EPSILON_PX) return;
-        const distanceFromBottom = Math.max(
-          0,
-          scrollerNow.scrollHeight - scrollerNow.clientHeight - scrollerNow.scrollTop,
-        );
-        if (distanceFromBottom <= COMPENSATION_EPSILON_PX) {
-          // User is at the bottom — safe to drain all collapse compensation.
-          const drained: BottomReservationState = {
-            ...bottomReservationStateRef.current,
-            collapse: {
-              ...bottomReservationStateRef.current.collapse,
-              px: 0,
-              floorPx: 0,
-            },
-          };
-          updateBottomReservationState(drained);
-          applyFooterCompensationNow(drained);
-        }
-      });
-    }
-  }, [
-    applyFooterCompensationNow,
-    acquireCollapseReservationOwner,
-    canProcessViewportGeometry,
-    inputStackFooterPx,
-    updateBottomReservationState,
-  ]);
-
-  const measureHeightChange = useCallback(() => {
-    const scroller = scrollerElementRef.current;
-    if (!scroller) return;
-    if (!canProcessViewportGeometry(scroller)) {
-      return;
-    }
-
-    const currentScrollTop = scroller.scrollTop;
-    const previousScrollTop = previousScrollTopRef.current;
-    const previousScrollerGeometry = previousScrollerGeometryRef.current;
-    const viewportHeightChanged = Boolean(
-      previousScrollerGeometry &&
-      Math.abs(scroller.clientHeight - previousScrollerGeometry.clientHeight) > COMPENSATION_EPSILON_PX
-    );
-    const wasAtPhysicalBottom = Boolean(
-      previousScrollerGeometry &&
-      Math.abs(
-        Math.max(0, previousScrollerGeometry.scrollHeight - previousScrollerGeometry.clientHeight) -
-        previousScrollerGeometry.scrollTop
-      ) <= LATEST_END_ANCHOR_STABLE_EPSILON_PX
-    );
-    const currentTotalCompensation = getTotalBottomCompensationPx();
-    const effectiveScrollHeight = Math.max(
-      0,
-      scroller.scrollHeight - currentTotalCompensation - inputStackFooterPxRef.current,
-    );
-    const previousMeasuredHeight = previousMeasuredHeightRef.current;
-    previousMeasuredHeightRef.current = effectiveScrollHeight;
-
-    if (previousMeasuredHeight === null) {
-      previousScrollTopRef.current = currentScrollTop;
-      recordScrollerGeometry(scroller);
-      return;
-    }
-
-    const heightDelta = effectiveScrollHeight - previousMeasuredHeight;
-    if (Math.abs(heightDelta) <= COMPENSATION_EPSILON_PX) {
-      previousScrollTopRef.current = currentScrollTop;
-      recordScrollerGeometry(scroller);
-      return;
-    }
-
-    if (retainedCollapseAnchorRef.current !== null) {
-      retainedCollapseGeometryGenerationRef.current += 1;
-    }
-
-    if (
-      heightDelta < -COMPENSATION_EPSILON_PX &&
-      retainedCollapseAnchorRef.current !== null &&
-      !pendingCollapseIntentRef.current.active
-    ) {
-      scheduleRetainedCollapseSettlement('delayed-negative-measurement');
-    }
-
-    if (flowChatDiagnostics.isEnabled()) {
-      flowChatDiagnostics.trace({
-        hypothesis: 'C',
-        location: 'VirtualMessageList.measureHeightChange',
-        message: 'Effective content height changed',
-        data: () => ({
-          heightDelta,
-          previousMeasuredHeight,
-          effectiveScrollHeight,
-          currentScrollTop,
-          previousScrollTop,
-          scrollHeight: scroller.scrollHeight,
-          clientHeight: scroller.clientHeight,
-          reservation: bottomReservationStateRef.current,
-          coordinatorMode: viewportCoordinatorRef.current.getMode(),
-          isFollowingOutput: isFollowingOutputRef.current,
-          isStreamingOutput: isStreamingOutputRef.current,
-          collapseIntentActive: pendingCollapseIntentRef.current.active,
-          retainedCollapseAnchor: retainedCollapseAnchorRef.current,
-          wasAtPhysicalBottom,
-          viewportHeightChanged,
-        }),
-      });
-    }
-
-    const ownsElementAnchor = viewportCoordinatorRef.current.ownsElementAnchor();
-    const isFollowingTail = (
-      isFollowingOutputRef.current &&
-      isStreamingOutputRef.current &&
-      viewportCoordinatorRef.current.getMode() === 'following-tail'
-    );
-    const hasCollapseAnchorProtection = (
-      pendingCollapseIntentRef.current.active ||
-      retainedCollapseAnchorRef.current !== null
-    );
-    if (shouldSyncPhysicalBottom({
-      viewportHeightChanged,
-      collapseProtectionActive: hasCollapseAnchorProtection,
-      wasAtPhysicalBottom,
-      ownsElementAnchor,
-      isFollowingTail,
-    })) {
-      if (wasAtPhysicalBottom) {
-        const maxScrollTop = Math.max(0, scroller.scrollHeight - scroller.clientHeight);
-        if (Math.abs(maxScrollTop - scroller.scrollTop) > COMPENSATION_EPSILON_PX) {
-          if (flowChatDiagnostics.isEnabled()) {
-            flowChatDiagnostics.trace({
-              hypothesis: 'C',
-              location: 'VirtualMessageList.measureHeightChange',
-              message: 'Content measurement synchronized the physical bottom',
-              data: () => ({
-                scrollTopBefore: scroller.scrollTop,
-                requestedScrollTop: maxScrollTop,
-                heightDelta,
-              }),
-            });
-          }
-          scroller.scrollTop = maxScrollTop;
-        }
-      }
-      previousScrollTopRef.current = scroller.scrollTop;
-      previousMeasuredHeightRef.current = snapshotMeasuredContentHeight(scroller);
-      recordScrollerGeometry(scroller);
-      return;
-    }
-
-    const distanceFromBottom = Math.max(
-      0,
-      scroller.scrollHeight - scroller.clientHeight - scroller.scrollTop
-    );
-
-    // Content grew: consume temporary footer padding first.
-    if (heightDelta > 0) {
-      const collapseIntent0 = pendingCollapseIntentRef.current;
-      const collapseProtectionActive = collapseIntent0.active;
-      const previousReservationState = bottomReservationStateRef.current;
-      const pinReservation = previousReservationState.pin;
-      const canSettleStickyPinGrowth = (
-        pinReservation.mode === 'sticky-latest' &&
-        Boolean(pinReservation.targetTurnId) &&
-        viewportCoordinatorRef.current.ownsElementAnchor()
-      );
-      const nextReservationState = consumeBottomCompensation(heightDelta, {
-        consumeStickyPinFloor: false,
-        preserveCollapseReservation: collapseProtectionActive,
-      });
-      const immediatelyConsumedPx = Math.max(
-        0,
-        getTotalBottomCompensationPx(previousReservationState) -
-        getTotalBottomCompensationPx(nextReservationState),
-      );
-      const unsettledGrowthPx = Math.max(0, heightDelta - immediatelyConsumedPx);
-      applyFooterCompensationNow(nextReservationState);
-      viewportCoordinatorRef.current.restoreElementAnchor(scroller, 'measure-grow');
-      previousScrollTopRef.current = scroller.scrollTop;
-      recordScrollerGeometry(scroller);
-      if (canSettleStickyPinGrowth && pinReservation.targetTurnId) {
-        // Queue after applying the measured state. Threshold settlement may
-        // synchronously shrink the Footer and hand ownership to tail-follow.
-        queuePendingStickyPinGrowth(
-          pinReservation.targetTurnId,
-          Math.min(unsettledGrowthPx, nextReservationState.pin.floorPx),
-        );
-      }
-      return;
-    }
-
-    // Content shrank: preserve the current visual anchor by extending the footer
-    // when the user does not already have enough distance from the bottom.
-    //
-    // Unsignaled shrinks in streaming tail-follow remain owned by the follow
-    // loop. A known collapse intent is different: its synchronous Footer
-    // reservation keeps both the physical bottom and the card header stable,
-    // so it must continue through the reconciliation path below.
-    const collapseIntent = pendingCollapseIntentRef.current;
-    const retainedCollapseAnchor = retainedCollapseAnchorRef.current;
-    if (retainedCollapseAnchor) {
-      preserveCollapseAnchorScrollTop(
-        scroller,
-        retainedCollapseAnchor.anchorScrollTop,
-        'measure-retained-shrink',
-      );
-      return;
-    }
-    if (shouldBypassShrinkCompensationInTailFollow({
-      isFollowingOutput: isFollowingOutputRef.current,
-      isStreamingOutput: isStreamingOutputRef.current,
-      hasActiveCollapseIntent: collapseIntent.active,
-    })) {
-      if (flowChatDiagnostics.isEnabled()) {
-        flowChatDiagnostics.trace({
-          hypothesis: 'D',
-          location: 'VirtualMessageList.measureHeightChange',
-          message: 'Unsignaled shrink delegated to streaming tail follow',
-          data: () => ({ heightDelta, currentScrollTop, previousScrollTop }),
-        });
-      }
-      previousScrollTopRef.current = currentScrollTop;
-      recordScrollerGeometry(scroller);
-      return;
-    }
-
-    const pendingStickyPinGrowth = pendingStickyPinGrowthRef.current;
-    const canceledPendingGrowthPx = getCanceledUnsettledStickyPinGrowthPx({
-      pendingGrowthPx: pendingStickyPinGrowth.amountPx,
-      shrinkPx: -heightDelta,
-      hasActiveCollapseIntent: collapseIntent.active,
-    });
-    if (canceledPendingGrowthPx > COMPENSATION_EPSILON_PX) {
-      pendingStickyPinGrowthRef.current = {
-        targetTurnId: pendingStickyPinGrowth.amountPx - canceledPendingGrowthPx > COMPENSATION_EPSILON_PX
-          ? pendingStickyPinGrowth.targetTurnId
-          : null,
-        amountPx: Math.max(0, pendingStickyPinGrowth.amountPx - canceledPendingGrowthPx),
-      };
-      if (
-        pendingStickyPinGrowthRef.current.amountPx <= COMPENSATION_EPSILON_PX &&
-        stickyPinGrowthSettleTimerRef.current !== null
-      ) {
-        window.clearTimeout(stickyPinGrowthSettleTimerRef.current);
-        stickyPinGrowthSettleTimerRef.current = null;
-      }
-    }
-    const shrinkAmount = Math.max(0, -heightDelta - canceledPendingGrowthPx);
-    if (shrinkAmount <= COMPENSATION_EPSILON_PX) {
-      viewportCoordinatorRef.current.restoreElementAnchor(scroller, 'measure-unsettled-growth-reverted');
-      previousScrollTopRef.current = scroller.scrollTop;
-      recordScrollerGeometry(scroller);
-      return;
-    }
-    const hasValidCollapseIntent = collapseIntent.active;
-    // For unsignaled shrinks, the visible gap to the bottom determines the
-    // required compensation. We no longer ratchet up via Math.max with the
-    // previous collapse.px: stale compensation from an earlier protected
-    // collapse is intentionally allowed to shrink when the current shrink
-    // needs less, preventing permanent whitespace accumulation (issue #1176).
-    const fallbackRequiredCollapseCompensation = Math.max(0, shrinkAmount - distanceFromBottom);
-    const cumulativeShrinkPx = hasValidCollapseIntent
-      ? collapseIntent.cumulativeShrinkPx + shrinkAmount
-      : 0;
-    const resolvedIntentCompensation = hasValidCollapseIntent
-      ? collapseIntent.baseTotalCompensationPx + Math.max(0, cumulativeShrinkPx - collapseIntent.distanceFromBottomBeforeCollapse)
-      : 0;
-    const reconciledOwnedState = hasValidCollapseIntent
-      ? null
-      : reconcileUnsignaledShrinkReservation(
-        bottomReservationStateRef.current,
-        fallbackRequiredCollapseCompensation,
-        collapseReservationOwnerRef.current !== null,
-      );
-    const nextTotalCompensation = hasValidCollapseIntent
-      ? Math.max(currentTotalCompensation, resolvedIntentCompensation)
-      : getTotalBottomCompensationPx(
-        reconciledOwnedState ?? bottomReservationStateRef.current,
-      );
-    if (hasValidCollapseIntent) {
-      pendingCollapseIntentRef.current = {
-        ...collapseIntent,
-        cumulativeShrinkPx,
-      };
-    }
-
-    if (!hasValidCollapseIntent && fallbackRequiredCollapseCompensation <= COMPENSATION_EPSILON_PX) {
-      // If the user is already far enough from the bottom, this shrink does not
-      // need protection. Reusing stale bottom compensation here makes the
-      // scroll listener restore an older anchor during upward scroll and causes
-      // the visible "wall hit" jitter.
-      previousScrollTopRef.current = currentScrollTop;
-      recordScrollerGeometry(scroller);
-      return;
-    }
-
-    const nextReservationState: BottomReservationState = reconciledOwnedState ?? {
-      ...bottomReservationStateRef.current,
-      collapse: {
-        ...bottomReservationStateRef.current.collapse,
-        px: Math.max(0, nextTotalCompensation - getReservationTotalPx(bottomReservationStateRef.current.pin)),
-      },
-    };
-    if (flowChatDiagnostics.isEnabled()) {
-      flowChatDiagnostics.trace({
-        hypothesis: hasValidCollapseIntent ? 'E' : 'C',
-        location: 'VirtualMessageList.measureHeightChange',
-        message: 'Content shrink resolved bottom compensation',
-        data: () => ({
-          heightDelta,
-          shrinkAmount,
-          distanceFromBottom,
-          hasValidCollapseIntent,
-          fallbackRequiredCollapseCompensation,
-          currentTotalCompensation,
-          nextTotalCompensation,
-          reservationBefore: bottomReservationStateRef.current,
-          reservationAfter: nextReservationState,
-        }),
-      });
-    }
-    updateBottomReservationState(nextReservationState);
-    if (nextTotalCompensation > COMPENSATION_EPSILON_PX) {
-      const anchorTarget =
-        hasValidCollapseIntent
-          ? collapseIntent.anchorScrollTop
-          : previousScrollTop;
-
-      applyFooterCompensationNow(nextReservationState);
-      if (hasValidCollapseIntent) {
-        preserveCollapseAnchorScrollTop(
-          scroller,
-          collapseIntent.anchorScrollTop,
-          'measure-active-collapse',
-        );
-      } else if (!(isFollowingOutputRef.current && isStreamingOutputRef.current)) {
-        viewportCoordinatorRef.current.restoreScrollPositionOnce(
-          scroller,
-          anchorTarget,
-          hasValidCollapseIntent ? 'transition-shrink' : 'instant-shrink',
-        );
-      }
-    }
-
-    previousScrollTopRef.current = scroller.scrollTop;
-    recordScrollerGeometry(scroller);
-  }, [
-    applyFooterCompensationNow,
-    canProcessViewportGeometry,
-    consumeBottomCompensation,
-    getTotalBottomCompensationPx,
-    queuePendingStickyPinGrowth,
-    preserveCollapseAnchorScrollTop,
-    recordScrollerGeometry,
-    snapshotMeasuredContentHeight,
-    scheduleRetainedCollapseSettlement,
-    updateBottomReservationState,
-  ]);
-
-  const scheduleHeightMeasure = useCallback((frames: number = 1) => {
-    if (measureFrameRef.current !== null) {
-      cancelAnimationFrame(measureFrameRef.current);
-      measureFrameRef.current = null;
-    }
-
-    const run = (remainingFrames: number) => {
-      measureFrameRef.current = requestAnimationFrame(() => {
-        if (remainingFrames > 1) {
-          run(remainingFrames - 1);
-          return;
-        }
-
-        measureFrameRef.current = null;
-        measureHeightChange();
-      });
-    };
-
-    run(Math.max(1, frames));
-  }, [measureHeightChange]);
-
-  const userMessageItems = React.useMemo(() => {
-    return virtualItems
-      .map((item, index) => ({ item, index }))
-      .filter(({ item }) => item.type === 'user-message');
-  }, [virtualItems]);
-
-  const latestTurnId = userMessageItems[userMessageItems.length - 1]?.item.turnId ?? null;
-  const latestUserMessageIndex = userMessageItems[userMessageItems.length - 1]?.index ?? 0;
-  const isTurnPinRequestCurrent = useCallback((request: PendingTurnPinState) => {
-    const currentSessionId = activeSessionIdRef.current;
-    const currentTargetTurnId = request.pinMode === 'sticky-latest'
-      ? latestTurnId
-      : request.turnId;
-    if (!currentSessionId || !currentTargetTurnId) {
-      return false;
-    }
-
-    return isTurnPinRequestIdentityCurrent(request, {
-      generation: turnPinRequestGenerationRef.current,
-      sessionId: currentSessionId,
-      turnId: currentTargetTurnId,
-    });
-  }, [latestTurnId]);
-  const hasPrimedMountedStreamingTurnFollowRef = useRef(false);
-  const previousLatestTurnIdForFollowRef = useRef<string | null>(latestTurnId);
-  const previousSessionIdForFollowRef = useRef<string | undefined>(activeSession?.sessionId);
-
-  const visibleTurnInfoByTurnId = React.useMemo(() => {
-    const infoMap = new Map<string, Omit<VisibleTurnInfo, 'visibleTurnIds'>>();
-
-    userMessageItems.forEach(({ item }, index) => {
-      if (item.type !== 'user-message') return;
-
-      infoMap.set(item.turnId, {
-        turnIndex: index + 1,
-        totalTurns: userMessageItems.length,
-        userMessage: item.data?.content || '',
-        turnId: item.turnId,
-      });
-    });
-
-    return infoMap;
-  }, [userMessageItems]);
-
-  const measureVisibleTurn = useCallback(() => {
-    const setVisibleTurnInfo = useModernFlowChatStore.getState().setVisibleTurnInfo;
-    const currentVisibleTurnInfo = useModernFlowChatStore.getState().visibleTurnInfo;
-
-    if (userMessageItems.length === 0) {
-      if (currentVisibleTurnInfo !== null) {
-        setVisibleTurnInfo(null);
-      }
-      return;
-    }
-
-    const scroller = scrollerElementRef.current;
-    if (scroller && !canProcessViewportGeometry(scroller)) {
-      return;
-    }
-    if (!scroller) {
-      const fallbackBaseInfo = visibleTurnInfoByTurnId.get(userMessageItems[0]?.item.turnId ?? '') ?? null;
-      const fallbackInfo: VisibleTurnInfo | null = fallbackBaseInfo
-        ? { ...fallbackBaseInfo, visibleTurnIds: [] }
-        : null;
-      if (
-        currentVisibleTurnInfo?.turnId !== fallbackInfo?.turnId ||
-        currentVisibleTurnInfo?.turnIndex !== fallbackInfo?.turnIndex ||
-        currentVisibleTurnInfo?.totalTurns !== fallbackInfo?.totalTurns ||
-        currentVisibleTurnInfo?.userMessage !== fallbackInfo?.userMessage ||
-        (currentVisibleTurnInfo?.visibleTurnIds?.length ?? 0) !== 0
-      ) {
-        setVisibleTurnInfo(fallbackInfo);
-      }
-      return;
-    }
-
-    const scrollerRect = scroller.getBoundingClientRect();
-    const viewportTop = scrollerRect.top + PINNED_TURN_VIEWPORT_OFFSET_PX;
-    const viewportBottom = scrollerRect.bottom;
-    const renderedItems = Array.from(
-      scroller.querySelectorAll<HTMLElement>('.virtual-item-wrapper[data-turn-id]')
-    );
-
-    const visibleTurnIds: string[] = [];
-    const visibleTurnIdSet = new Set<string>();
-    let topVisibleTurnId: string | null = null;
-    for (const node of renderedItems) {
-      const rect = node.getBoundingClientRect();
-      if (rect.bottom <= viewportTop || rect.top >= viewportBottom) {
-        continue;
-      }
-
-      const turnId = node.dataset.turnId;
-      if (!turnId) {
-        continue;
-      }
-
-      topVisibleTurnId ??= turnId;
-      if (!visibleTurnIdSet.has(turnId)) {
-        visibleTurnIdSet.add(turnId);
-        visibleTurnIds.push(turnId);
-      }
-    }
-
-    const nextTurnId = topVisibleTurnId ?? userMessageItems[0]?.item.turnId ?? null;
-    const nextBaseInfo = nextTurnId ? (visibleTurnInfoByTurnId.get(nextTurnId) ?? null) : null;
-    const nextInfo: VisibleTurnInfo | null = nextBaseInfo
-      ? { ...nextBaseInfo, visibleTurnIds }
-      : null;
-    const currentVisibleTurnIds = currentVisibleTurnInfo?.visibleTurnIds ?? [];
-    const visibleTurnIdsUnchanged =
-      currentVisibleTurnIds.length === visibleTurnIds.length &&
-      currentVisibleTurnIds.every((turnId, index) => turnId === visibleTurnIds[index]);
-
-    if (
-      currentVisibleTurnInfo?.turnId === nextInfo?.turnId &&
-      currentVisibleTurnInfo?.turnIndex === nextInfo?.turnIndex &&
-      currentVisibleTurnInfo?.totalTurns === nextInfo?.totalTurns &&
-      currentVisibleTurnInfo?.userMessage === nextInfo?.userMessage &&
-      visibleTurnIdsUnchanged
-    ) {
-      return;
-    }
-
-    setVisibleTurnInfo(nextInfo);
-  }, [canProcessViewportGeometry, userMessageItems, visibleTurnInfoByTurnId]);
-
-  const scheduleVisibleTurnMeasure = useCallback((frames: number = 1) => {
-    if (visibleTurnMeasureFrameRef.current !== null) {
-      cancelAnimationFrame(visibleTurnMeasureFrameRef.current);
-      visibleTurnMeasureFrameRef.current = null;
-    }
-
-    const run = (remainingFrames: number) => {
-      visibleTurnMeasureFrameRef.current = requestAnimationFrame(() => {
-        if (remainingFrames > 1) {
-          run(remainingFrames - 1);
-          return;
-        }
-
-        visibleTurnMeasureFrameRef.current = null;
-        measureVisibleTurn();
-      });
-    };
-
-    run(Math.max(1, frames));
-  }, [measureVisibleTurn]);
-
-  const escapeTurnIdSelector = useCallback((turnId: string) => (
-    typeof CSS !== 'undefined' && typeof CSS.escape === 'function'
-      ? CSS.escape(turnId)
-      : turnId.replace(/["\\]/g, '\\$&')
-  ), []);
-
-  const getRenderedTurnElements = useCallback((turnId: string, options?: { includeHistoryProjectionHandoff?: boolean }) => {
-    const scroller = scrollerElementRef.current;
-    if (!scroller) return [];
-
-    const escapedTurnId = escapeTurnIdSelector(turnId);
-    const nodes = Array.from(scroller.querySelectorAll<HTMLElement>(
-      `.virtual-item-wrapper[data-turn-id="${escapedTurnId}"]`,
-    ));
-
-    if (options?.includeHistoryProjectionHandoff === false) {
-      return nodes.filter(node => !node.closest('[data-history-projection-handoff="true"]'));
-    }
-
-    return nodes;
-  }, [escapeTurnIdSelector]);
-
-  const getRenderedUserMessageElement = useCallback((turnId: string) => {
-    const scroller = scrollerElementRef.current;
-    if (!scroller) return null;
-
-    const escapedTurnId = escapeTurnIdSelector(turnId);
-    return scroller.querySelector<HTMLElement>(
-      `.virtual-item-wrapper[data-item-type="user-message"][data-turn-id="${escapedTurnId}"]`,
-    );
-  }, [escapeTurnIdSelector]);
-
-  const getRenderedVirtualItemElement = useCallback((itemIndex: number) => {
-    const scroller = scrollerElementRef.current;
-    if (!scroller) return null;
-
-    return scroller.querySelector<HTMLElement>(
-      `.virtual-item-wrapper[data-virtual-index="${itemIndex}"]`,
-    );
-  }, []);
-
-  const isTurnRenderedInViewport = useCallback((turnId: string) => {
-    const scroller = scrollerElementRef.current;
-    if (!scroller) {
-      return false;
-    }
-
-    const scrollerRect = scroller.getBoundingClientRect();
-    const nodes = getRenderedTurnElements(turnId);
-
-    return nodes.some(node => {
-      const rect = node.getBoundingClientRect();
-      return rect.bottom > scrollerRect.top && rect.top < scrollerRect.bottom;
-    });
-  }, [getRenderedTurnElements]);
-
-  const isTurnTextRenderedInViewport = useCallback((turnId: string) => {
-    const scroller = scrollerElementRef.current;
-    if (!scroller) {
-      return false;
-    }
-
-    const scrollerRect = scroller.getBoundingClientRect();
-    const nodes = getRenderedTurnElements(turnId);
-
-    return nodes.some(node => {
-      const rect = node.getBoundingClientRect();
-      const visible = rect.bottom > scrollerRect.top && rect.top < scrollerRect.bottom;
-      return visible && (node.innerText?.trim().length ?? 0) > 0;
-    });
-  }, [getRenderedTurnElements]);
-
-  const isTurnTextRenderedInViewportOutsideHandoff = useCallback((turnId: string) => {
-    const scroller = scrollerElementRef.current;
-    if (!scroller) {
-      return false;
-    }
-
-    const scrollerRect = scroller.getBoundingClientRect();
-    const nodes = getRenderedTurnElements(turnId, { includeHistoryProjectionHandoff: false });
-
-    return nodes.some(node => {
-      const rect = node.getBoundingClientRect();
-      const visible = rect.bottom > scrollerRect.top && rect.top < scrollerRect.bottom;
-      return visible && (node.innerText?.trim().length ?? 0) > 0;
-    });
-  }, [getRenderedTurnElements]);
-
-  const hasVisibleRenderedVirtualItem = useCallback(() => {
-    const scroller = scrollerElementRef.current;
-    if (!scroller) {
-      return false;
-    }
-
-    const scrollerRect = scroller.getBoundingClientRect();
-    const nodes = Array.from(
-      scroller.querySelectorAll<HTMLElement>('.virtual-item-wrapper[data-turn-id]'),
-    );
-
-    return nodes.some(node => {
-      const rect = node.getBoundingClientRect();
-      const style = window.getComputedStyle(node);
-      return (
-        rect.bottom > scrollerRect.top &&
-        rect.top < scrollerRect.bottom &&
-        rect.width > 0 &&
-        rect.height > 0 &&
-        style.visibility !== 'hidden' &&
-        style.display !== 'none' &&
-        (node.innerText?.trim().length ?? 0) > 0
-      );
-    });
-  }, []);
-
-  const isHistoryProjectionHandoffTargetReady = useCallback((snapshot: HistoryProjectionHandoffSnapshot) => {
-    if (snapshot.targetTurnId) {
-      return isTurnTextRenderedInViewportOutsideHandoff(snapshot.targetTurnId);
-    }
-
-    return hasVisibleRenderedVirtualItem();
-  }, [
-    hasVisibleRenderedVirtualItem,
-    isTurnTextRenderedInViewportOutsideHandoff,
-  ]);
-
-  const clearHistoryProjectionHandoff = useCallback((reason: string) => {
-    if (historyProjectionHandoffReleaseFrameRef.current !== null) {
-      cancelAnimationFrame(historyProjectionHandoffReleaseFrameRef.current);
-      historyProjectionHandoffReleaseFrameRef.current = null;
-    }
-
-    const snapshot = historyProjectionHandoffRef.current;
-    historyProjectionHandoffRef.current = null;
-    setHistoryProjectionHandoff(null);
-    if (reason === 'session-reset' || reason === 'session-changed') {
-      previousMeasuredHeightRef.current = null;
-      previousScrollerGeometryRef.current = null;
-    }
-
-    if (snapshot) {
-      startupTrace.markPhase('flowchat_history_projection_handoff_cleared', {
-        sessionId: snapshot.sessionId,
-        reason,
-        handoffReason: snapshot.reason,
-        durationMs: Math.round(performance.now() - snapshot.createdAtMs),
-      });
-    }
-  }, []);
-  clearHistoryProjectionHandoffRef.current = clearHistoryProjectionHandoff;
-
-  useLayoutEffect(() => {
-    rebaseViewportMeasurements();
-  }, [historyProjectionHandoff, rebaseViewportMeasurements]);
-
-  const scheduleHistoryProjectionHandoffRelease = useCallback((frames = 1) => {
-    if (historyProjectionHandoffReleaseFrameRef.current !== null) {
-      cancelAnimationFrame(historyProjectionHandoffReleaseFrameRef.current);
-      historyProjectionHandoffReleaseFrameRef.current = null;
-    }
-
-    const run = (remainingFrames: number) => {
-      historyProjectionHandoffReleaseFrameRef.current = requestAnimationFrame(() => {
-        historyProjectionHandoffReleaseFrameRef.current = null;
-
-        const snapshot = historyProjectionHandoffRef.current;
-        if (!snapshot) {
-          return;
-        }
-
-        if (remainingFrames > 1) {
-          run(remainingFrames - 1);
-          return;
-        }
-
-        if (activeSessionIdRef.current !== snapshot.sessionId) {
-          clearHistoryProjectionHandoff('session-changed');
-          return;
-        }
-
-        if (isHistoryProjectionHandoffTargetReady(snapshot)) {
-          clearHistoryProjectionHandoff('target-content-ready');
-          return;
-        }
-
-        if (performance.now() - snapshot.createdAtMs >= HISTORY_PROJECTION_HANDOFF_MAX_DURATION_MS) {
-          clearHistoryProjectionHandoff('timeout');
-          return;
-        }
-
-        run(1);
-      });
-    };
-
-    run(Math.max(1, frames));
-  }, [clearHistoryProjectionHandoff, isHistoryProjectionHandoffTargetReady]);
-
-  const retargetHistoryProjectionHandoff = useCallback((turnId: string) => {
-    const snapshot = historyProjectionHandoffRef.current;
-    if (!snapshot || snapshot.targetTurnId === turnId) {
-      return;
-    }
-
-    const nextSnapshot: HistoryProjectionHandoffSnapshot = {
-      ...snapshot,
-      targetTurnId: turnId,
-      createdAtMs: performance.now(),
-    };
-    historyProjectionHandoffRef.current = nextSnapshot;
-    setHistoryProjectionHandoff(nextSnapshot);
-    scheduleHistoryProjectionHandoffRelease(2);
-  }, [scheduleHistoryProjectionHandoffRelease]);
-
-  const buildPinReservation = useCallback((
-    turnId: string,
-    pinMode: FlowChatPinTurnToTopMode,
-    requiredTailSpacePx: number,
-    maxPinReservationPx: number,
-    currentPinReservation: PinBottomReservation = bottomReservationStateRef.current.pin,
-  ): PinBottomReservation => {
-    const resolvedRequiredTailSpacePx = clampPinReservationPxToViewport(
-      requiredTailSpacePx,
-      maxPinReservationPx,
-    );
-    const nextFloorPx = pinMode === 'sticky-latest'
-      ? resolvedRequiredTailSpacePx
-      : 0;
-    // Only preserve a sticky pin after a real floor has been measured.
-    // Provisional fallback reservations should shrink on the next resolve.
-    const shouldPreserveCurrentPx = (
-      currentPinReservation.mode === pinMode &&
-      currentPinReservation.targetTurnId === turnId &&
-      (
-        pinMode === 'transient' ||
-        currentPinReservation.floorPx > COMPENSATION_EPSILON_PX
-      )
-    );
-    const preservedPx = shouldPreserveCurrentPx
-      ? clampPinReservationPxToViewport(currentPinReservation.px, maxPinReservationPx)
-      : 0;
-    const shouldRetainTarget = (
-      pinMode === 'sticky-latest' ||
-      resolvedRequiredTailSpacePx > COMPENSATION_EPSILON_PX ||
-      shouldPreserveCurrentPx
-    );
-
-    return {
-      kind: 'pin',
-      px: Math.max(nextFloorPx, resolvedRequiredTailSpacePx, preservedPx),
-      floorPx: nextFloorPx,
-      mode: pinMode,
-      targetTurnId: shouldRetainTarget ? turnId : null,
-    };
-  }, []);
-
-  const resolveTurnPinMetrics = useCallback((turnId: string, ignoredTailSpacePx: number = 0) => {
-    const scroller = scrollerElementRef.current;
-    if (!canProcessViewportGeometry(scroller)) {
-      return null;
-    }
-
-    const targetElement = getRenderedUserMessageElement(turnId);
-    if (!targetElement) return null;
-
-    const scrollerRect = scroller.getBoundingClientRect();
-    const targetRect = targetElement.getBoundingClientRect();
-    const viewportTop = scrollerRect.top + PINNED_TURN_VIEWPORT_OFFSET_PX;
-    const desiredScrollTop = Math.max(0, scroller.scrollTop + (targetRect.top - viewportTop));
-    const effectiveScrollHeight = Math.max(0, scroller.scrollHeight - Math.max(0, ignoredTailSpacePx));
-    const rawMaxScrollTop = effectiveScrollHeight - scroller.clientHeight;
-    const maxScrollTop = Math.max(0, rawMaxScrollTop);
-    // When content is shorter than the viewport, the clamped max scroll range is 0
-    // even though we still need to reserve the underflow gap before the target can pin.
-    const rawMissingTailSpace = Math.max(0, desiredScrollTop - rawMaxScrollTop);
-    const missingTailSpace = clampPinReservationPxToViewport(
-      rawMissingTailSpace,
-      scroller.clientHeight,
-    );
-    if (
-      flowChatDiagnostics.isEnabled() &&
-      rawMissingTailSpace - missingTailSpace > COMPENSATION_EPSILON_PX
-    ) {
-      flowChatDiagnostics.trace({
-        hypothesis: 'F',
-        location: 'VirtualMessageList.resolveTurnPinMetrics',
-        message: 'Pin reservation exceeded the viewport and was clamped',
-        data: () => ({
-          turnId,
-          rawMissingTailSpace,
-          missingTailSpace,
-          clientHeight: scroller.clientHeight,
-          desiredScrollTop,
-          rawMaxScrollTop,
-          effectiveScrollHeight,
-          ignoredTailSpacePx,
-        }),
-      });
-    }
-
-    return {
-      targetElement,
-      viewportTop,
-      desiredScrollTop,
-      maxScrollTop,
-      missingTailSpace,
-    };
-  }, [canProcessViewportGeometry, getRenderedUserMessageElement]);
-
-  const reconcileStickyPinReservation = useCallback(() => {
-    const scroller = scrollerElementRef.current;
-    const currentState = bottomReservationStateRef.current;
-    const pinReservation = currentState.pin;
-    if (
-      !canProcessViewportGeometry(scroller) ||
-      pinReservation.mode !== 'sticky-latest' ||
-      !pinReservation.targetTurnId
-    ) {
-      return false;
-    }
-
-    // A new arbitrary-turn navigation may be materializing a distant target
-    // while the previous sticky-latest footer still provides physical range.
-    // Do not let the old sticky target rewrite that reservation until the new
-    // request has either aligned or been cancelled.
-    const activeTurnPinTargetId = activeTurnPinRequestRef.current?.turnId ??
-      preparedHistoryTurnPinRef.current?.turnId ??
-      null;
-    if (
-      activeTurnPinTargetId &&
-      activeTurnPinTargetId !== pinReservation.targetTurnId
-    ) {
-      return false;
-    }
-
-    const collapseIntent = pendingCollapseIntentRef.current;
-    const hasActiveCollapseProtection = (
-      collapseIntent.active
-    );
-    // During a collapse animation, let collapse compensation own the footer space.
-    // Recomputing sticky pin floor from intermediate DOM heights causes the two
-    // reservations to fight each other and reintroduces visible vertical jitter.
-    if (hasActiveCollapseProtection) {
-      return false;
-    }
-
-    const resolvedMetrics = resolveTurnPinMetrics(
-      pinReservation.targetTurnId,
-      pinReservation.px,
-    );
-    if (!resolvedMetrics) {
-      return false;
-    }
-
-    const requiredFloorPx = clampPinReservationPxToViewport(
-      resolvedMetrics.missingTailSpace,
-      scroller.clientHeight,
-    );
-    const boundedCurrentPx = clampPinReservationPxToViewport(
-      pinReservation.px,
-      scroller.clientHeight,
-    );
-    const boundedCurrentFloorPx = clampPinReservationPxToViewport(
-      pinReservation.floorPx,
-      scroller.clientHeight,
-    );
-    const currentReservationExceedsViewport = (
-      pinReservation.px - boundedCurrentPx > COMPENSATION_EPSILON_PX ||
-      pinReservation.floorPx - boundedCurrentFloorPx > COMPENSATION_EPSILON_PX
-    );
-    // A live target rect is transient while Virtuoso is reconciling item
-    // measurements. It is safe to increase the range from that snapshot, but
-    // reducing the floor can remove scroll range for a frame and strand the
-    // semantic anchor at the physical bottom. Real content growth drains the
-    // floor through measureHeightChange instead; the viewport cap is the only
-    // synchronous reduction allowed here.
-    if (
-      requiredFloorPx <= pinReservation.floorPx + COMPENSATION_EPSILON_PX &&
-      !currentReservationExceedsViewport
-    ) {
-      return false;
-    }
-
-    const nextFloorPx = Math.max(requiredFloorPx, boundedCurrentFloorPx);
-    const nextPinReservation: PinBottomReservation = {
-      ...pinReservation,
-      px: clampPinReservationPxToViewport(
-        Math.max(nextFloorPx, boundedCurrentPx),
-        scroller.clientHeight,
-      ),
-      floorPx: nextFloorPx,
-    };
-
-    if (
-      Math.abs(nextPinReservation.px - pinReservation.px) <= COMPENSATION_EPSILON_PX &&
-      Math.abs(nextPinReservation.floorPx - pinReservation.floorPx) <= COMPENSATION_EPSILON_PX
-    ) {
-      return false;
-    }
-
-    const nextState: BottomReservationState = {
-      ...currentState,
-      pin: nextPinReservation,
-    };
-    updateBottomReservationState(nextState);
-    applyFooterCompensationNow(nextState);
-    viewportCoordinatorRef.current.restoreElementAnchor(scroller, 'pin-reservation-grow');
-    previousMeasuredHeightRef.current = snapshotMeasuredContentHeight(scroller, nextState);
-    return true;
-  }, [
-    applyFooterCompensationNow,
-    canProcessViewportGeometry,
-    resolveTurnPinMetrics,
-    snapshotMeasuredContentHeight,
-    updateBottomReservationState,
-  ]);
-
-  const schedulePinReservationReconcile = useCallback((frames: number = 1) => {
-    if (pinReservationReconcileFrameRef.current !== null) {
-      cancelAnimationFrame(pinReservationReconcileFrameRef.current);
-      pinReservationReconcileFrameRef.current = null;
-    }
-
-    const run = (remainingFrames: number) => {
-      pinReservationReconcileFrameRef.current = requestAnimationFrame(() => {
-        if (remainingFrames > 1) {
-          run(remainingFrames - 1);
-          return;
-        }
-
-        pinReservationReconcileFrameRef.current = null;
-        reconcileStickyPinReservation();
-      });
-    };
-
-    run(Math.max(1, frames));
-  }, [reconcileStickyPinReservation]);
-
-  const clearExpiredProvisionalStickyPin = useCallback((request: PendingTurnPinState) => {
-    const currentState = bottomReservationStateRef.current;
-    if (!shouldClearExpiredProvisionalStickyPin({
-      requestTurnId: request.turnId,
-      requestPinMode: request.pinMode,
-      pinReservation: currentState.pin,
-      ownsElementAnchor: viewportCoordinatorRef.current.ownsElementAnchor(),
-    })) {
-      return false;
-    }
-
-    const nextState: BottomReservationState = {
-      ...currentState,
-      pin: {
-        kind: 'pin',
-        px: 0,
-        floorPx: 0,
-        mode: 'transient',
-        targetTurnId: null,
-      },
-    };
-    viewportCoordinatorRef.current.release('unresolved-turn-pin-expired');
-    updateBottomReservationState(nextState);
-    applyFooterCompensationNow(nextState);
-
-    const scroller = scrollerElementRef.current;
-    if (scroller) {
-      previousScrollTopRef.current = scroller.scrollTop;
-      previousMeasuredHeightRef.current = snapshotMeasuredContentHeight(scroller, nextState);
-      recordScrollerGeometry(scroller);
-    }
-    return true;
-  }, [
-    applyFooterCompensationNow,
-    recordScrollerGeometry,
-    snapshotMeasuredContentHeight,
-    updateBottomReservationState,
-  ]);
-
-  const tryResolvePendingTurnPin = useCallback((request: PendingTurnPinState): TurnPinResolution => {
-    if (!isTurnPinRequestCurrent(request)) {
-      return { kind: 'pending' };
-    }
-
-    const scroller = scrollerElementRef.current;
-    const virtuoso = virtuosoRef.current;
-
-    if (!canCoordinateViewport() || !scroller || !virtuoso) {
-      startupTrace.markPhase('flowchat_turn_pin_resolve', {
-        result: 'inactive_or_missing_scroller_or_virtuoso',
-        turnId: request.turnId,
-        pinMode: request.pinMode,
-        attempt: request.attempts,
-        hasScroller: Boolean(scroller),
-        isViewportActive: isViewportActiveRef.current,
-        viewportGeometrySuspended: viewportGeometrySuspendedRef.current,
-        hasVirtuoso: Boolean(virtuoso),
-      });
-      return { kind: 'pending' };
-    }
-
-    const targetItem = userMessageItems.find(({ item }) => item.turnId === request.turnId);
-    if (!targetItem) {
-      startupTrace.markPhase('flowchat_turn_pin_resolve', {
-        result: 'missing_target_item',
-        turnId: request.turnId,
-        pinMode: request.pinMode,
-        attempt: request.attempts,
-        userMessageCount: userMessageItems.length,
-      });
-      return { kind: 'pending' };
-    }
-
-    const currentPinReservation = bottomReservationStateRef.current.pin;
-    // Existing pin tail space is synthetic footer reservation, not real content.
-    // Ignore it when resolving a new pin target so maxScrollTop is computed against
-    // the effective content height instead of the previous pin reservation.
-    let ignoredTailSpacePx = 0;
-    if (currentPinReservation.px > COMPENSATION_EPSILON_PX) {
-      ignoredTailSpacePx = currentPinReservation.px;
-    }
-    const resolvedMetrics = resolveTurnPinMetrics(request.turnId, ignoredTailSpacePx);
-    if (!resolvedMetrics) {
-      // A far smooth scroll can leave the target virtualized long enough for the
-      // deferred pin to expire. Materialize it first, then let the existing live
-      // geometry pass perform the exact alignment and stabilization.
-      const fallbackBehavior: ScrollBehavior = 'auto';
-      const provisionalPinPx = request.pinMode === 'sticky-latest'
-        ? resolveProvisionalStickyPinReservationPx({
-          scrollHeight: scroller.scrollHeight,
-          clientHeight: scroller.clientHeight,
-          currentPinPx: currentPinReservation.px,
-        })
-        : 0;
-
-      if (request.pinMode === 'sticky-latest' && provisionalPinPx > COMPENSATION_EPSILON_PX) {
-        // Reserve enough tail space before the target is rendered so the first
-        // fallback scroll does not briefly land on the physical bottom.
-        const nextReservationState: BottomReservationState = {
-          ...bottomReservationStateRef.current,
-          pin: {
-            kind: 'pin',
-            px: provisionalPinPx,
-            floorPx: 0,
-            mode: request.pinMode,
-            targetTurnId: request.turnId,
-          },
-        };
-        updateBottomReservationState(nextReservationState);
-        applyFooterCompensationNow(nextReservationState);
-        previousMeasuredHeightRef.current = snapshotMeasuredContentHeight(scroller, nextReservationState);
-      }
-
-      virtuoso.scrollToIndex({
-        index: targetItem.index,
-        align: 'start',
-        behavior: fallbackBehavior,
-      });
-      startupTrace.markPhase('flowchat_turn_pin_resolve', {
-        result: 'target_not_rendered_fallback_scroll_to_index',
-        turnId: request.turnId,
-        pinMode: request.pinMode,
-        attempt: request.attempts,
-        targetIndex: targetItem.index,
-        scrollTop: scroller.scrollTop,
-        scrollHeight: scroller.scrollHeight,
-        clientHeight: scroller.clientHeight,
-      });
-      return { kind: 'pending' };
-    }
-
-    const hasInsufficientNaturalRange = (
-      request.alignmentPolicy === 'best-effort' &&
-      resolvedMetrics.missingTailSpace > COMPENSATION_EPSILON_PX
-    );
-    const isBestEffortTransientPin = (
-      request.alignmentPolicy === 'best-effort' &&
-      request.pinMode === 'transient'
-    );
-    const nextPinReservation: PinBottomReservation = isBestEffortTransientPin
-      ? {
-        kind: 'pin',
-        px: 0,
-        floorPx: 0,
-        mode: 'transient',
-        targetTurnId: null,
-      }
-      : buildPinReservation(
-        request.turnId,
-        request.pinMode,
-        resolvedMetrics.missingTailSpace,
-        scroller.clientHeight,
-      );
-    const nextReservationState: BottomReservationState = {
-      ...bottomReservationStateRef.current,
-      pin: nextPinReservation,
-    };
-    updateBottomReservationState(nextReservationState);
-    applyFooterCompensationNow(nextReservationState);
-
-    const resolvedMaxScrollTop = hasInsufficientNaturalRange
-      ? resolvedMetrics.maxScrollTop
-      : Math.max(0, scroller.scrollHeight - scroller.clientHeight);
-    const targetScrollTop = Math.min(resolvedMetrics.desiredScrollTop, resolvedMaxScrollTop);
-    if (Math.abs(scroller.scrollTop - targetScrollTop) > COMPENSATION_EPSILON_PX) {
-      scroller.scrollTop = targetScrollTop;
-    }
-
-    // Some turn jumps align correctly at first, then drift on the next frame as
-    // Virtuoso finishes layout stabilization. Re-check the live DOM before we
-    // decide the pin has truly settled.
-    const verifyPinAlignment = (frameLabel: string) => {
-      const liveTargetElement = getRenderedUserMessageElement(request.turnId);
-      const liveRect = liveTargetElement?.getBoundingClientRect();
-      const viewportTop = liveTargetElement
-        ? scroller.getBoundingClientRect().top + PINNED_TURN_VIEWPORT_OFFSET_PX
-        : null;
-      const deltaToViewportTop = liveRect && viewportTop != null
-        ? liveRect.top - viewportTop
-        : null;
-
-      const stickyPinStillTargetsRequest = (
-        bottomReservationStateRef.current.pin.mode === 'sticky-latest' &&
-        bottomReservationStateRef.current.pin.targetTurnId === request.turnId
-      );
-      // Sticky latest pins should keep correcting post-layout drift until the
-      // target stabilizes, while transient jumps still back off if the user
-      // has already moved away from the requested position.
-      const shouldRealign = (
-        !hasInsufficientNaturalRange &&
-        frameLabel !== 'immediate' &&
-        deltaToViewportTop != null &&
-        Math.abs(deltaToViewportTop) > 1.5 &&
-        (
-          request.pinMode === 'transient'
-            ? Math.abs(scroller.scrollTop - targetScrollTop) <= 2
-            : stickyPinStillTargetsRequest
-        )
-      );
-      if (!shouldRealign) {
-        return;
-      }
-
-      const correctedMaxScrollTop = Math.max(0, scroller.scrollHeight - scroller.clientHeight);
-      const correctedScrollTop = Math.min(
-        correctedMaxScrollTop,
-        Math.max(0, scroller.scrollTop + deltaToViewportTop),
-      );
-      if (Math.abs(correctedScrollTop - scroller.scrollTop) <= COMPENSATION_EPSILON_PX) {
-        return;
-      }
-
-      scroller.scrollTop = correctedScrollTop;
-      previousScrollTopRef.current = correctedScrollTop;
-      previousMeasuredHeightRef.current = snapshotMeasuredContentHeight(
-        scroller,
-        bottomReservationStateRef.current,
-      );
-      recordScrollerGeometry(scroller);
-      scheduleVisibleTurnMeasure(2);
-      schedulePinReservationReconcile(2);
-    };
-    verifyPinAlignment('immediate');
-    // The observed drift lands after the initial alignment, so sample two
-    // follow-up frames and realign only if the target actually shifts.
-    requestAnimationFrame(() => {
-      verifyPinAlignment('raf-1');
-      requestAnimationFrame(() => {
-        verifyPinAlignment('raf-2');
-      });
-    });
-
-    previousScrollTopRef.current = targetScrollTop;
-    previousMeasuredHeightRef.current = snapshotMeasuredContentHeight(scroller, nextReservationState);
-    recordScrollerGeometry(scroller);
-
-    const alignedRect = resolvedMetrics.targetElement.getBoundingClientRect();
-    const alignedWithinTolerance = Math.abs(alignedRect.top - resolvedMetrics.viewportTop) <= 1.5;
-    if (alignedWithinTolerance && !hasInsufficientNaturalRange) {
-      viewportCoordinatorRef.current.pinElement(resolvedMetrics.targetElement);
-    }
-    startupTrace.markPhase('flowchat_turn_pin_resolve', {
-      result: hasInsufficientNaturalRange
-        ? 'best_effort_clamped'
-        : alignedWithinTolerance
-          ? 'aligned'
-          : 'not_aligned_after_scroll',
-      turnId: request.turnId,
-      pinMode: request.pinMode,
-      attempt: request.attempts,
-      targetIndex: targetItem.index,
-      targetScrollTop,
-      scrollTop: scroller.scrollTop,
-      targetTop: alignedRect.top,
-      viewportTop: resolvedMetrics.viewportTop,
-    });
-
-    if (hasInsufficientNaturalRange) {
-      return { kind: 'best-effort', targetScrollTop };
-    }
-
-    return alignedWithinTolerance
-      ? { kind: 'exact', targetScrollTop }
-      : { kind: 'pending' };
-  }, [
-    buildPinReservation,
-    applyFooterCompensationNow,
-    canCoordinateViewport,
-    getRenderedUserMessageElement,
-    isTurnPinRequestCurrent,
-    recordScrollerGeometry,
-    resolveTurnPinMetrics,
-    schedulePinReservationReconcile,
-    scheduleVisibleTurnMeasure,
-    snapshotMeasuredContentHeight,
-    updateBottomReservationState,
-    userMessageItems,
-  ]);
-
-  const reconcileTransientTurnPinStabilization = useCallback(() => {
-    const request = transientTurnPinStabilizationRef.current;
-    if (!request) {
-      return;
-    }
-    if (!canProcessViewportGeometry(scrollerElementRef.current)) {
-      return;
-    }
-
-
-    if (request.pinMode !== 'transient' || performance.now() > request.expiresAtMs) {
-      transientTurnPinStabilizationRef.current = null;
-      if (activeTurnPinRequestRef.current?.generation === request.generation) {
-        cancelUnresolvedTurnPinRef.current();
-      } else {
-        pendingTurnPinGenerationRef.current = null;
-        setPendingTurnPin(current => (
-          current?.generation === request.generation ? null : current
-        ));
-      }
-      return;
-    }
-
-    if (viewportCoordinatorRef.current.getMode() === 'idle') {
-      viewportCoordinatorRef.current.pinItem('transient-turn-pin-rematerializing');
-    }
-
-    const nextRequest: TransientTurnPinStabilizationState = {
-      ...request,
-      behavior: 'auto',
-      attempts: request.attempts + 1,
-    };
-    const resolved = tryResolvePendingTurnPin(nextRequest);
-    if (resolved.kind === 'best-effort' && settleBestEffortTurnPin(nextRequest)) {
-      scheduleVisibleTurnMeasure(2);
-      return;
-    }
-    const scroller = scrollerElementRef.current;
-    const targetElement = getRenderedUserMessageElement(nextRequest.turnId);
-    const targetRect = targetElement?.getBoundingClientRect();
-    const viewportTop = scroller
-      ? scroller.getBoundingClientRect().top + PINNED_TURN_VIEWPORT_OFFSET_PX
-      : null;
-    const aligned = Boolean(
-      resolved.kind === 'exact' &&
-      scroller &&
-      targetRect &&
-      viewportTop !== null &&
-      Math.abs(targetRect.top - viewportTop) <= 1.5
-    );
-    const geometryStable = Boolean(
-      aligned &&
-      request.lastScrollTop !== null &&
-      request.lastTargetTop !== null &&
-      scroller &&
-      targetRect &&
-      Math.abs(scroller.scrollTop - request.lastScrollTop) <= 1 &&
-      Math.abs(targetRect.top - request.lastTargetTop) <= 1
-    );
-    nextRequest.stableAlignedFrames = aligned
-      ? (geometryStable ? request.stableAlignedFrames + 1 : 1)
-      : 0;
-    nextRequest.lastScrollTop = aligned && scroller ? scroller.scrollTop : null;
-    nextRequest.lastTargetTop = aligned && targetRect ? targetRect.top : null;
-
-    if (nextRequest.stableAlignedFrames >= TRANSIENT_TURN_PIN_STABLE_FRAME_COUNT) {
-      if (activeTurnPinRequestRef.current?.generation === nextRequest.generation) {
-        activeTurnPinRequestRef.current = null;
-      }
-      transientTurnPinStabilizationRef.current = null;
-      pendingTurnPinGenerationRef.current = null;
-      setPendingTurnPin(current => (
-        current?.generation === nextRequest.generation ? null : current
-      ));
-      scheduleVisibleTurnMeasure(2);
-      return;
-    }
-
-    transientTurnPinStabilizationRef.current = nextRequest;
-    if (resolved.kind !== 'pending') {
-      scheduleVisibleTurnMeasure(2);
-    }
-    scheduleTransientTurnPinStabilizationRef.current(1);
-  }, [
-    canProcessViewportGeometry,
-    getRenderedUserMessageElement,
-    scheduleVisibleTurnMeasure,
-    settleBestEffortTurnPin,
-    tryResolvePendingTurnPin,
-  ]);
-
-  const scheduleTransientTurnPinStabilization = useCallback((frames: number = 1) => {
-    if (!transientTurnPinStabilizationRef.current) {
-      return;
-    }
-    if (!canProcessViewportGeometry(scrollerElementRef.current)) {
-      return;
-    }
-
-    if (turnPinStabilizationFrameRef.current !== null) {
-      cancelAnimationFrame(turnPinStabilizationFrameRef.current);
-      turnPinStabilizationFrameRef.current = null;
-    }
-
-    const run = (remainingFrames: number) => {
-      turnPinStabilizationFrameRef.current = requestAnimationFrame(() => {
-        if (remainingFrames > 1) {
-          run(remainingFrames - 1);
-          return;
-        }
-
-        turnPinStabilizationFrameRef.current = null;
-        reconcileTransientTurnPinStabilization();
-      });
-    };
-
-    run(Math.max(1, frames));
-  }, [canProcessViewportGeometry, reconcileTransientTurnPinStabilization]);
-  scheduleTransientTurnPinStabilizationRef.current = scheduleTransientTurnPinStabilization;
-
-  const drainCollapseReservationPreservingPinnedItem = useCallback((reason: string) => {
-    const currentState = bottomReservationStateRef.current;
-    if (getReservationTotalPx(currentState.collapse) <= COMPENSATION_EPSILON_PX) {
-      return currentState;
-    }
-
-    const scroller = scrollerElementRef.current;
-    const ownsPinnedItem = viewportCoordinatorRef.current.getMode() === 'pinned-item';
-    const stickyPinTarget = (
-      ownsPinnedItem &&
-      currentState.pin.mode === 'sticky-latest' &&
-      currentState.pin.targetTurnId
-    )
-      ? currentState.pin.targetTurnId
-      : null;
-    const resolvedPinMetrics = scroller && stickyPinTarget
-      ? resolveTurnPinMetrics(
-        stickyPinTarget,
-        getTotalBottomCompensationPx(currentState),
-      )
-      : null;
-    if (stickyPinTarget && !resolvedPinMetrics) {
-      return null;
-    }
-
-    const nextPinReservation = stickyPinTarget && resolvedPinMetrics && scroller
-      ? buildPinReservation(
-        stickyPinTarget,
-        'sticky-latest',
-        resolvedPinMetrics.missingTailSpace,
-        scroller.clientHeight,
-        currentState.pin,
-      )
-      : currentState.pin;
-    const nextState = transferCollapseReservationToPin(currentState, nextPinReservation);
-    updateBottomReservationState(nextState);
-    applyFooterCompensationNow(nextState);
-    if (scroller && stickyPinTarget) {
-      viewportCoordinatorRef.current.restoreElementAnchor(
-        scroller,
-        `collapse-drain:${reason}`,
-      );
-    }
-    return nextState;
-  }, [
-    applyFooterCompensationNow,
-    buildPinReservation,
-    getTotalBottomCompensationPx,
-    resolveTurnPinMetrics,
-    updateBottomReservationState,
-  ]);
-
-  const clearCollapseIntentScheduling = useCallback(() => {
-    if (collapseIntentFinalizeTimerRef.current !== null) {
-      window.clearTimeout(collapseIntentFinalizeTimerRef.current);
-      collapseIntentFinalizeTimerRef.current = null;
-    }
-    if (collapseIntentAnimationTimerRef.current !== null) {
-      window.clearTimeout(collapseIntentAnimationTimerRef.current);
-      collapseIntentAnimationTimerRef.current = null;
-    }
-    if (collapseIntentSettleFrameRef.current !== null) {
-      cancelAnimationFrame(collapseIntentSettleFrameRef.current);
-      collapseIntentSettleFrameRef.current = null;
-    }
-  }, []);
-
-  const finalizeCollapseIntent = useCallback((
-    reason: string,
-    options?: { expectedExpiresAtMs?: number; suppressHandoff?: boolean },
-  ) => {
-    const intent = pendingCollapseIntentRef.current;
-    if (
-      !intent.active ||
-      (
-        options?.expectedExpiresAtMs !== undefined &&
-        intent.expiresAtMs !== options.expectedExpiresAtMs
-      )
-    ) {
-      return false;
-    }
-
-    const coordinatorMode = viewportCoordinatorRef.current.getMode();
-    const reservationBeforeSettlement = bottomReservationStateRef.current;
-    const settlementStrategy = resolveCollapseIntentSettlementStrategy({
-      coordinatorMode,
-      isFollowingOutput: isFollowingOutputRef.current,
-      isStreamingOutput: isStreamingOutputRef.current,
-      reservation: reservationBeforeSettlement,
-    });
-
-    if (flowChatDiagnostics.isEnabled()) {
-      flowChatDiagnostics.trace({
-        hypothesis: 'E',
-        location: 'VirtualMessageList.finalizeCollapseIntent',
-        message: 'Collapse intent finalization started',
-        data: () => ({
-          reason,
-          intent,
-          coordinatorMode,
-          settlementStrategy,
-          reservation: reservationBeforeSettlement,
-          isFollowingOutput: isFollowingOutputRef.current,
-          isStreamingOutput: isStreamingOutputRef.current,
-        }),
-      });
-    }
-
-    clearCollapseIntentScheduling();
-    pendingCollapseIntentRef.current = createInactiveCollapseIntentState();
-    if (settlementStrategy === 'retain-following-tail') {
-      retainCollapseRangeForQuietSettlement(intent, reason);
-      if (deferredFollowReasonRef.current) {
-        const deferredReason = deferredFollowReasonRef.current;
-        deferredFollowReasonRef.current = null;
-        followOutputControllerRef.current.scheduleFollowToLatest(
-          `${deferredReason}-after-collapse`,
-        );
-      }
-      return true;
-    }
-
-    const scroller = scrollerElementRef.current;
-    const nextState = (() => {
-      switch (settlementStrategy) {
-        case 'reconcile-sticky-pin':
-        case 'drain':
-          return drainCollapseReservationPreservingPinnedItem(reason);
-        case 'settle-preserved-element':
-        case 'settle-protected-viewport':
-          return scroller
-            ? settleCollapseReservationForViewport(
-              bottomReservationStateRef.current,
-              {
-                scrollTop: scroller.scrollTop,
-                scrollHeight: scroller.scrollHeight,
-                clientHeight: scroller.clientHeight,
-              },
-            )
-            : protectCurrentCollapseReservation(bottomReservationStateRef.current);
-      }
-    })();
-    if (nextState === null) {
-      pendingCollapseIntentRef.current = intent;
-      collapseIntentFinalizeTimerRef.current = window.setTimeout(() => {
-        collapseIntentFinalizeTimerRef.current = null;
-        finalizeCollapseIntentRef.current('collapse-intent-target-retry', {
-          expectedExpiresAtMs: intent.expiresAtMs,
-          suppressHandoff: options?.suppressHandoff,
-        });
-      }, 50);
-      return false;
-    }
-
-    if (!areBottomReservationStatesEqual(bottomReservationStateRef.current, nextState)) {
-      updateBottomReservationState(nextState);
-      applyFooterCompensationNow(nextState);
-    }
-    if (nextState.collapse.px <= COMPENSATION_EPSILON_PX) {
-      clearCollapseReservationOwner();
-    }
-    if (flowChatDiagnostics.isEnabled()) {
-      flowChatDiagnostics.trace({
-        hypothesis: 'A',
-        location: 'VirtualMessageList.finalizeCollapseIntent',
-        message: 'Collapse intent reservation settlement completed',
-        data: () => ({
-          reason,
-          settlementStrategy,
-          coordinatorMode,
-          reservationBefore: reservationBeforeSettlement,
-          reservationAfter: bottomReservationStateRef.current,
-        }),
-      });
-    }
-    if (coordinatorMode === 'preserving-element' && scroller) {
-      viewportCoordinatorRef.current.restoreElementAnchor(
-        scroller,
-        `collapse-finalized:${reason}`,
-      );
-      const restoredState = protectCurrentCollapseReservation(
-        bottomReservationStateRef.current,
-      );
-      if (!areBottomReservationStatesEqual(bottomReservationStateRef.current, restoredState)) {
-        updateBottomReservationState(restoredState);
-        applyFooterCompensationNow(restoredState);
-      }
-      previousScrollTopRef.current = scroller.scrollTop;
-      previousMeasuredHeightRef.current = snapshotMeasuredContentHeight(scroller);
-      recordScrollerGeometry(scroller);
-    }
-    if (coordinatorMode === 'preserving-element') {
-      viewportCoordinatorRef.current.settleElementPreservation(
-        `collapse-finalized:${reason}`,
-      );
-    }
-
-    reconcilePendingStickyPinGrowthSettlement(
-      `collapse-finalized:${reason}`,
-      { preserveExistingQuietTimer: true },
-    );
-
-    if (deferredFollowReasonRef.current) {
-      const deferredReason = deferredFollowReasonRef.current;
-      deferredFollowReasonRef.current = null;
-      followOutputControllerRef.current.scheduleFollowToLatest(`${deferredReason}-after-collapse`);
-    }
-    if (!options?.suppressHandoff) {
-      maybeHandoffPinnedTurnToTailRef.current(`collapse-finalized:${reason}`);
-    }
-    return true;
-  }, [
-    applyFooterCompensationNow,
-    clearCollapseIntentScheduling,
-    clearCollapseReservationOwner,
-    drainCollapseReservationPreservingPinnedItem,
-    reconcilePendingStickyPinGrowthSettlement,
-    recordScrollerGeometry,
-    retainCollapseRangeForQuietSettlement,
-    snapshotMeasuredContentHeight,
-    updateBottomReservationState,
-  ]);
-  finalizeCollapseIntentRef.current = finalizeCollapseIntent;
-
-  const scheduleCollapseIntentFinalization = useCallback((
-    intent: PendingCollapseIntentState,
-    reason: string | null | undefined,
-  ) => {
-    clearCollapseIntentScheduling();
-    const expectedExpiresAtMs = intent.expiresAtMs;
-    collapseIntentFinalizeTimerRef.current = window.setTimeout(() => {
-      collapseIntentFinalizeTimerRef.current = null;
-      finalizeCollapseIntentRef.current('collapse-intent-timeout', {
-        expectedExpiresAtMs,
-      });
-    }, Math.max(0, expectedExpiresAtMs - performance.now()));
-
-    if (reason !== 'auto') {
-      return;
-    }
-
-    // Auto collapses animate for FLOWCHAT_COLLAPSE_DURATION_MS. Finalize only
-    // after that window plus a short settle so reservation tracks the moving
-    // height instead of ending while the box is still closing.
-    const settle = (remainingFrames: number) => {
-      collapseIntentSettleFrameRef.current = requestAnimationFrame(() => {
-        if (remainingFrames > 1) {
-          settle(remainingFrames - 1);
-          return;
-        }
-        collapseIntentSettleFrameRef.current = null;
-        finalizeCollapseIntentRef.current('auto-collapse-layout-settled', {
-          expectedExpiresAtMs,
-        });
-      });
-    };
-    collapseIntentAnimationTimerRef.current = window.setTimeout(() => {
-      collapseIntentAnimationTimerRef.current = null;
-      settle(AUTO_COLLAPSE_SETTLE_FRAMES);
-    }, FLOWCHAT_COLLAPSE_DURATION_MS);
-  }, [clearCollapseIntentScheduling]);
-
-  useEffect(() => clearCollapseIntentScheduling, [clearCollapseIntentScheduling]);
-
-  const handleScrollerRef = useCallback((el: HTMLElement | Window | null) => {
-    restoreScrollerMethodsRef.current?.();
-    restoreScrollerMethodsRef.current = null;
-
-    if (el && el instanceof HTMLElement) {
-      const originalScrollTo = el.scrollTo;
-      const originalScrollBy = el.scrollBy;
-      const wrapScrollMethod = (
-        method: 'scrollTo' | 'scrollBy',
-        original: typeof el.scrollTo,
-      ): typeof el.scrollTo => {
-        return ((...args: unknown[]) => {
-          let requestedTop: number | null = null;
-          const firstArg = args[0];
-          if (typeof firstArg === 'number' && typeof args[1] === 'number') {
-            requestedTop = args[1];
-          } else if (
-            firstArg !== null &&
-            typeof firstArg === 'object' &&
-            'top' in firstArg &&
-            typeof firstArg.top === 'number'
-          ) {
-            requestedTop = firstArg.top;
-          }
-          const previousGeometry = previousScrollerGeometryRef.current;
-          const previousMaxScrollTop = previousGeometry
-            ? Math.max(0, previousGeometry.scrollHeight - previousGeometry.clientHeight)
-            : null;
-          const wasAtPhysicalBottomBeforeScrollBy = Boolean(
-            previousGeometry &&
-            previousMaxScrollTop !== null &&
-            Math.abs(previousMaxScrollTop - previousGeometry.scrollTop) <= LATEST_END_ANCHOR_STABLE_EPSILON_PX
-          );
-          const hasSemanticAnchor = (
-            method === 'scrollBy' &&
-            viewportCoordinatorRef.current.ownsElementAnchor()
-          );
-          const suppressVirtualizerCompensation = (
-            hasSemanticAnchor ||
-            (
-              method === 'scrollBy' &&
-              shouldSuppressFollowingTailNegativeScrollBy({
-                requestedTop,
-                isFollowingOutput: isFollowingOutputRef.current,
-                isStreamingOutput: isStreamingOutputRef.current,
-                wasAtPhysicalBottom: wasAtPhysicalBottomBeforeScrollBy,
-              })
-            )
-          );
-          const diagnosticsEnabled = flowChatDiagnostics.isEnabled();
-          const scrollTopBefore = diagnosticsEnabled ? el.scrollTop : null;
-          if (!suppressVirtualizerCompensation) {
-            Reflect.apply(original, el, args);
-          }
-          if (diagnosticsEnabled) {
-            flowChatDiagnostics.trace({
-              hypothesis: 'D',
-              location: `VirtualMessageList.scroller.${method}`,
-              message: suppressVirtualizerCompensation
-                ? 'Virtualizer scroll request suppressed'
-                : 'Virtualizer scroll request applied',
-              data: () => ({
-                method,
-                requestedTop,
-                suppressVirtualizerCompensation,
-                hasSemanticAnchor,
-                wasAtPhysicalBottomBeforeScrollBy,
-                isFollowingOutput: isFollowingOutputRef.current,
-                isStreamingOutput: isStreamingOutputRef.current,
-                coordinatorMode: viewportCoordinatorRef.current.getMode(),
-                scrollTopBefore,
-                scrollTopAfter: el.scrollTop,
-                scrollHeight: el.scrollHeight,
-                clientHeight: el.clientHeight,
-              }),
-            });
-          }
-        }) as typeof el.scrollTo;
-      };
-      const wrappedScrollTo = typeof originalScrollTo === 'function'
-        ? wrapScrollMethod('scrollTo', originalScrollTo)
-        : null;
-      const wrappedScrollBy = typeof originalScrollBy === 'function'
-        ? wrapScrollMethod('scrollBy', originalScrollBy)
-        : null;
-      if (wrappedScrollTo) {
-        el.scrollTo = wrappedScrollTo;
-      }
-      if (wrappedScrollBy) {
-        el.scrollBy = wrappedScrollBy;
-      }
-      restoreScrollerMethodsRef.current = () => {
-        if (wrappedScrollTo && el.scrollTo === wrappedScrollTo) {
-          el.scrollTo = originalScrollTo;
-        }
-        if (wrappedScrollBy && el.scrollBy === wrappedScrollBy) {
-          el.scrollBy = originalScrollBy;
-        }
-      };
-      virtuosoMountStateRef.current = {
-        sessionId: activeSessionIdRef.current,
-        mounted: true,
-      };
-      scrollerElementRef.current = el;
-      setScrollerElement(el);
-      return;
-    }
-
-    scrollerElementRef.current = null;
-    setScrollerElement(null);
-  }, []);
-
-  const clearPreviousHistoryBoundaryStatus = useCallback(() => {
-    if (previousHistoryBoundaryStatusTimerRef.current !== null) {
-      window.clearTimeout(previousHistoryBoundaryStatusTimerRef.current);
-      previousHistoryBoundaryStatusTimerRef.current = null;
-    }
-    setPreviousHistoryBoundaryStatus(null);
-  }, []);
-
-  const showPreviousHistoryBoundaryStatus = useCallback((
-    sessionId: string,
-    reason: string,
-    state: 'preparing' | 'not-ready'
-  ) => {
-    if (previousHistoryBoundaryStatusTimerRef.current !== null) {
-      window.clearTimeout(previousHistoryBoundaryStatusTimerRef.current);
-      previousHistoryBoundaryStatusTimerRef.current = null;
-    }
-
-    setPreviousHistoryBoundaryStatus({
-      sessionId,
-      reason,
-      state,
-    });
-
-    previousHistoryBoundaryStatusTimerRef.current = window.setTimeout(() => {
-      previousHistoryBoundaryStatusTimerRef.current = null;
-      setPreviousHistoryBoundaryStatus(current => {
-        if (
-          current?.sessionId === sessionId &&
-          current.reason === reason &&
-          current.state === state
-        ) {
-          return null;
-        }
-        return current;
-      });
-    }, PREVIOUS_HISTORY_BOUNDARY_STATUS_DURATION_MS);
-  }, []);
-
-  useEffect(() => () => {
-    if (previousHistoryBoundaryStatusTimerRef.current !== null) {
-      window.clearTimeout(previousHistoryBoundaryStatusTimerRef.current);
-      previousHistoryBoundaryStatusTimerRef.current = null;
-    }
-    if (historyPagingRetryTimerRef.current !== null) {
-      window.clearTimeout(historyPagingRetryTimerRef.current);
-      historyPagingRetryTimerRef.current = null;
-    }
-  }, []);
-
-  useEffect(() => {
-    setPreviousHistoryBoundaryStatus(current => {
-      if (current && current.sessionId !== activeSessionId) {
-        return null;
-      }
-      return current;
-    });
-  }, [activeSessionId]);
-
-  const captureHistoryPrependAnchor = useCallback(() => {
-    const scroller = scrollerElementRef.current;
-    if (!scroller) {
-      return null;
-    }
-
-    const scrollerRect = scroller.getBoundingClientRect();
-    const nodes = Array.from(scroller.querySelectorAll<HTMLElement>(
-      '.virtual-item-wrapper[data-item-type="user-message"][data-turn-id]',
-    ));
-    const visibleNode = nodes.find(node => {
-      const rect = node.getBoundingClientRect();
-      return rect.bottom > scrollerRect.top && rect.top < scrollerRect.bottom;
-    });
-    const node = visibleNode ?? nodes[0];
-    const turnId = node?.dataset.turnId;
-    if (!node || !turnId) {
-      return null;
-    }
-
-    return {
-      turnId,
-      offsetFromScrollerTop: node.getBoundingClientRect().top - scrollerRect.top,
-      element: node,
-    };
-  }, []);
-
-  const requestHistoryWindowBoundaryForUserIntent = useCallback((
-    direction: SessionHistoryWindowDirection,
-    reason: string,
-    options?: { force?: boolean },
-  ) => {
-    if (
-      presentationMode !== 'history-window'
-      || !historyWindow
-      || !onHistoryWindowBoundaryIntent
-      || historyBoundaryState[direction] === 'loading'
-    ) {
-      return false;
-    }
-
-    const scroller = scrollerElementRef.current;
-    const sessionId = activeSessionIdRef.current;
-    if (!scroller || !sessionId) {
-      return false;
-    }
-    const thresholdPx = Math.max(
-      PARTIAL_HISTORY_FULL_PROJECTION_TOP_THRESHOLD_PX,
-      scroller.clientHeight * 2,
-    );
-    const distanceFromBoundary = direction === 'before'
-      ? scroller.scrollTop
-      : Math.max(0, scroller.scrollHeight - scroller.clientHeight - scroller.scrollTop);
-    if (!options?.force && distanceFromBoundary > thresholdPx) {
-      return false;
-    }
-
-    let preparedAnchorState: PendingHistoryPrependAnchorState | null = null;
-    const cancelViewportPresentationCommit = () => {
-      if (
-        preparedAnchorState
-        && pendingHistoryPrependAnchorRef.current === preparedAnchorState
-      ) {
-        pendingHistoryPrependAnchorRef.current = null;
-        setHistoryPagingAnchorTurnId(null);
-      }
-      setHistoryPagingLoading(false);
-      clearPreviousHistoryBoundaryStatus();
-    };
-    const prepareViewportForPresentationCommit = async () => {
-      const quietReady = await waitForHistoryPresentationCommitQuiet(sessionId);
-      if (!quietReady || activeSessionIdRef.current !== sessionId) {
-        return false;
-      }
-      const anchor = captureHistoryPrependAnchor();
-      if (anchor) {
-        historyPagingActiveRef.current = true;
-        setHistoryPagingActive(true);
-        setHistoryPagingAnchorTurnId(anchor.turnId);
-        preparedAnchorState = {
-          ...anchor,
-          beforeItemCount: virtualItems.length,
-          handoffRestored: true,
-          prependRestored: false,
-        };
-        pendingHistoryPrependAnchorRef.current = preparedAnchorState;
-      }
-      return true;
-    };
-    startupTrace.markPhase('flowchat_history_window_boundary_requested', {
-      sessionId: activeSessionIdRef.current,
-      direction,
-      reason,
-      startOrdinal: historyWindow.startOrdinal,
-      endOrdinalExclusive: historyWindow.endOrdinalExclusive,
-      presentationRevision,
-    });
-    try {
-      void Promise.resolve(onHistoryWindowBoundaryIntent(direction, {
-        prepareViewportForPresentationCommit,
-        cancelViewportPresentationCommit,
-      })).catch(() => {});
-    } catch {
-      return false;
-    }
-    return true;
-  }, [
-    captureHistoryPrependAnchor,
-    clearPreviousHistoryBoundaryStatus,
-    historyBoundaryState,
-    historyWindow,
-    onHistoryWindowBoundaryIntent,
-    presentationMode,
-    presentationRevision,
-    virtualItems.length,
-    waitForHistoryPresentationCommitQuiet,
-  ]);
-
-  const revealPreviousHistoryWindowForUserIntent = useCallback((reason: string) => {
-    const sessionId = activeSession?.sessionId;
-    if (
-      presentationMode === 'history-window' ||
-      !sessionId ||
-      activeSession.historyState !== 'ready' ||
-      activeSession.isPartial !== true
-    ) {
-      return;
-    }
-
-    const usesCatalogHistoryWindow = (
-      activeSession.turnCatalog?.sessionId === sessionId
-      && Boolean(onHistoryWindowBoundaryIntent)
-    );
-
-    if (!historyPagingActiveRef.current) {
-      const anchor = usesCatalogHistoryWindow ? null : captureHistoryPrependAnchor();
-      historyPagingActiveRef.current = true;
-      setHistoryPagingActive(true);
-      setHistoryPagingLoading(true);
-      if (anchor) {
-        setHistoryPagingAnchorTurnId(anchor.turnId);
-        pendingHistoryPrependAnchorRef.current = {
-          ...anchor,
-          beforeItemCount: virtualItems.length,
-          handoffRestored: false,
-          prependRestored: false,
-        };
-      }
-      showPreviousHistoryBoundaryStatus(sessionId, reason, 'preparing');
-    }
-
-    if (usesCatalogHistoryWindow && onHistoryWindowBoundaryIntent) {
-      setHistoryPagingLoading(true);
-      if (catalogHistoryWindowRequestRef.current) {
-        return;
-      }
-      let preparedAnchorState: PendingHistoryPrependAnchorState | null = null;
-      const resetCatalogHistoryPagingState = () => {
-        if (
-          preparedAnchorState
-          && pendingHistoryPrependAnchorRef.current === preparedAnchorState
-        ) {
-          pendingHistoryPrependAnchorRef.current = null;
-        }
-        historyPagingActiveRef.current = false;
-        setHistoryPagingActive(false);
-        setHistoryPagingLoading(false);
-        setHistoryPagingAnchorTurnId(null);
-        clearPreviousHistoryBoundaryStatus();
-      };
-      const cancelViewportPresentationCommit = resetCatalogHistoryPagingState;
-      const prepareViewportForPresentationCommit = async () => {
-        const quietReady = await waitForHistoryPresentationCommitQuiet(sessionId);
-        if (!quietReady || activeSessionIdRef.current !== sessionId) {
-          return false;
-        }
-        const anchor = captureHistoryPrependAnchor();
-        if (anchor) {
-          setHistoryPagingAnchorTurnId(anchor.turnId);
-          preparedAnchorState = {
-            ...anchor,
-            beforeItemCount: virtualItems.length,
-            handoffRestored: true,
-            prependRestored: false,
-          };
-          pendingHistoryPrependAnchorRef.current = preparedAnchorState;
-        }
-        return true;
-      };
-      const request = Promise.resolve(onHistoryWindowBoundaryIntent('before', {
-        prepareViewportForPresentationCommit,
-        cancelViewportPresentationCommit,
-      }))
-        .then(handled => {
-          const result = normalizeHistoryWindowBoundaryIntentResult(handled);
-          if (activeSessionIdRef.current !== sessionId) {
-            return result;
-          }
-          if (result === 'applied') {
-            if (!preparedAnchorState) {
-              resetCatalogHistoryPagingState();
-            }
-            return result;
-          }
-          if (result === 'exhausted' || result === 'cancelled') {
-            resetCatalogHistoryPagingState();
-            return result;
-          }
-          resetCatalogHistoryPagingState();
-          showPreviousHistoryBoundaryStatus(sessionId, reason, 'not-ready');
-          return result;
-        })
-        .catch(error => {
-          if (activeSessionIdRef.current === sessionId) {
-            resetCatalogHistoryPagingState();
-            showPreviousHistoryBoundaryStatus(sessionId, reason, 'not-ready');
-          }
-          log.warn('Failed to request an older catalog Turn window', {
-            sessionId,
-            error,
-          });
-          return 'not-ready' as const;
-        })
-        .finally(() => {
-          if (catalogHistoryWindowRequestRef.current === request) {
-            catalogHistoryWindowRequestRef.current = null;
-          }
-        });
-      catalogHistoryWindowRequestRef.current = request;
-      return;
-    }
-
-    const pendingAnchor = pendingHistoryPrependAnchorRef.current;
-    if (!pendingAnchor || pendingAnchor.prependRestored) {
-      const anchor = captureHistoryPrependAnchor();
-      if (anchor) {
-        setHistoryPagingAnchorTurnId(anchor.turnId);
-        pendingHistoryPrependAnchorRef.current = {
-          ...anchor,
-          beforeItemCount: virtualItems.length,
-          handoffRestored: true,
-          prependRestored: false,
-        };
-      }
-    }
-    setHistoryPagingLoading(true);
-
-    if (!flowChatStore.hasDeferredSessionHistoryProjection(sessionId)) {
-      if (flowChatStore.hasPendingSessionHistoryCompletion(sessionId)) {
-        const released = flowChatStore.releaseSessionHistoryCompletionAfterInitialPaint(sessionId, {
-          immediate: true,
-          reason,
-        });
-        showPreviousHistoryBoundaryStatus(sessionId, reason, 'preparing');
-        startupTrace.markPhase('flowchat_previous_history_window_preparing', {
-          sessionId,
-          reason,
-          released,
-        });
-        if (historyPagingRetryTimerRef.current === null) {
-          historyPagingRetryTimerRef.current = window.setTimeout(() => {
-            historyPagingRetryTimerRef.current = null;
-            if (activeSessionIdRef.current === sessionId && historyPagingActiveRef.current) {
-              revealPreviousHistoryWindowForUserIntent('history-ready-after-scroll');
-            }
-          }, 50);
-        }
-      } else {
-        setHistoryPagingLoading(false);
-        showPreviousHistoryBoundaryStatus(sessionId, reason, 'not-ready');
-        startupTrace.markPhase('flowchat_previous_history_window_not_ready', {
-          sessionId,
-          reason,
-        });
-      }
-      return;
-    }
-
-    const revealed = flowChatStore.revealPreviousSessionHistoryWindow(sessionId, reason);
-    if (historyPagingRetryTimerRef.current !== null) {
-      window.clearTimeout(historyPagingRetryTimerRef.current);
-      historyPagingRetryTimerRef.current = null;
-    }
-    if (revealed) {
-      clearPreviousHistoryBoundaryStatus();
-    } else {
-      setHistoryPagingLoading(false);
-      showPreviousHistoryBoundaryStatus(sessionId, reason, 'not-ready');
-    }
-    startupTrace.markPhase('flowchat_previous_history_window_requested', {
-      sessionId,
-      reason,
-      revealed,
-    });
-  }, [
-    activeSession?.historyState,
-    activeSession?.isPartial,
-    activeSession?.sessionId,
-    activeSession?.turnCatalog,
-    captureHistoryPrependAnchor,
-    clearPreviousHistoryBoundaryStatus,
-    showPreviousHistoryBoundaryStatus,
-    presentationMode,
-    onHistoryWindowBoundaryIntent,
-    virtualItems.length,
-    waitForHistoryPresentationCommitQuiet,
-  ]);
-
-  const shouldRevealPreviousHistoryWindowForUserIntent = useCallback((options?: { force?: boolean }) => {
-    if (options?.force === true) {
-      return true;
-    }
-
-    const scroller = scrollerElementRef.current;
-    if (!scroller) {
-      return false;
-    }
-
-    const topThresholdPx = Math.max(
-      PARTIAL_HISTORY_FULL_PROJECTION_TOP_THRESHOLD_PX,
-      scroller.clientHeight * 1.5,
-    );
-    return scroller.scrollTop <= topThresholdPx;
-  }, []);
-
-  const schedulePreviousHistoryWindowForUserIntent = useCallback((reason: string, options?: { force?: boolean }) => {
-    const scheduledSessionId = activeSession?.sessionId ?? null;
-    pendingFullHistoryProjectionReasonRef.current = reason;
-    if (fullHistoryProjectionIntentFrameRef.current !== null) {
-      cancelAnimationFrame(fullHistoryProjectionIntentFrameRef.current);
-      fullHistoryProjectionIntentFrameRef.current = null;
-    }
-
-    fullHistoryProjectionIntentFrameRef.current = requestAnimationFrame(() => {
-      fullHistoryProjectionIntentFrameRef.current = requestAnimationFrame(() => {
-        fullHistoryProjectionIntentFrameRef.current = null;
-        const pendingReason = pendingFullHistoryProjectionReasonRef.current;
-        pendingFullHistoryProjectionReasonRef.current = null;
-        if (!pendingReason || activeSessionIdRef.current !== scheduledSessionId) {
-          return;
-        }
-
-        if (!shouldRevealPreviousHistoryWindowForUserIntent(options)) {
-          return;
-        }
-
-        revealPreviousHistoryWindowForUserIntent(pendingReason);
-      });
-    });
-  }, [
-    activeSession?.sessionId,
-    revealPreviousHistoryWindowForUserIntent,
-    shouldRevealPreviousHistoryWindowForUserIntent,
-  ]);
-
-  const shouldSuspendAutoFollow = useCallback(() => {
-    const collapseIntent = pendingCollapseIntentRef.current;
-    return (
-      !isViewportActiveRef.current ||
-      viewportGeometrySuspendedRef.current ||
-      collapseIntent.active
-    );
-  }, []);
-
-  const scheduleFollowToLatestWithViewportState = useCallback((reason: string) => {
-    const collapseIntentActive = shouldSuspendAutoFollow();
-    if (collapseIntentActive) {
-      deferredFollowReasonRef.current = reason;
-      return;
-    }
-    deferredFollowReasonRef.current = null;
-    followOutputControllerRef.current.scheduleFollowToLatest(reason);
-  }, [shouldSuspendAutoFollow]);
-
-  useLayoutEffect(() => {
-    previousMeasuredHeightRef.current = null;
-    previousScrollTopRef.current = 0;
-    cancelHistoryPresentationCommitQuietWaiters();
-    viewportCoordinatorRef.current.release('session-reset');
-    clearTurnPinRequest();
-    cancelLatestEndAnchorStabilization();
-    clearCollapseIntentScheduling();
-    clearRetainedCollapseSettlement();
-    clearPendingStickyPinGrowth('session-reset');
-    pendingCollapseIntentRef.current = createInactiveCollapseIntentState();
-    retainedCollapseAnchorRef.current = null;
-    previousScrollerGeometryRef.current = null;
-    preparedHistoryTurnPinRef.current = null;
-    historyPagingActiveRef.current = false;
-    if (historyPagingRetryTimerRef.current !== null) {
-      window.clearTimeout(historyPagingRetryTimerRef.current);
-      historyPagingRetryTimerRef.current = null;
-    }
-    catalogHistoryWindowRequestRef.current = null;
-    pendingHistoryPrependAnchorRef.current = null;
-    setHistoryPagingActive(false);
-    setHistoryPagingLoading(false);
-    setHistoryPagingAnchorTurnId(null);
-    const currentSessionId = activeSession?.sessionId ?? null;
-    const activeHandoff = historyProjectionHandoffRef.current;
-    if (!activeHandoff || activeHandoff.sessionId !== currentSessionId) {
-      clearHistoryProjectionHandoff('session-reset');
-    }
-    resetBottomReservations();
-  }, [
-    activeSession?.sessionId,
-    cancelHistoryPresentationCommitQuietWaiters,
-    cancelLatestEndAnchorStabilization,
-    clearCollapseIntentScheduling,
-    clearRetainedCollapseSettlement,
-    clearPendingStickyPinGrowth,
-    clearHistoryProjectionHandoff,
-    clearTurnPinRequest,
-    resetBottomReservations,
-  ]);
-
-  useEffect(() => {
-    previousIsStreamingOutputRef.current = false;
-  }, [activeSession?.sessionId]);
-
-  useEffect(() => {
-    if (virtualItems.length === 0) {
-      previousMeasuredHeightRef.current = null;
-      clearTurnPinRequest();
-      cancelLatestEndAnchorStabilization();
-      clearPendingStickyPinGrowth('empty-list');
-      resetBottomReservations();
-    }
-  }, [
-    virtualItems.length,
-    cancelLatestEndAnchorStabilization,
-    clearPendingStickyPinGrowth,
-    clearTurnPinRequest,
-    resetBottomReservations,
-  ]);
-
-  useEffect(() => {
-    return () => {
-      cancelHistoryPresentationCommitQuietWaiters();
-      clearRetainedCollapseSettlement();
-      cancelLatestEndAnchorStabilization();
-      if (historyProjectionHandoffReleaseFrameRef.current !== null) {
-        cancelAnimationFrame(historyProjectionHandoffReleaseFrameRef.current);
-        historyProjectionHandoffReleaseFrameRef.current = null;
-      }
-    };
-  }, [
-    cancelHistoryPresentationCommitQuietWaiters,
-    cancelLatestEndAnchorStabilization,
-    clearRetainedCollapseSettlement,
-  ]);
-
-  useEffect(() => {
-    if (!scrollerElement) {
-      previousMeasuredHeightRef.current = null;
-      previousScrollerGeometryRef.current = null;
-      return;
-    }
-
-    const resizeTarget =
-      scrollerElement.firstElementChild instanceof HTMLElement
-        ? scrollerElement.firstElementChild
-        : scrollerElement;
-
-    if (canProcessViewportGeometry(scrollerElement)) {
-      previousMeasuredHeightRef.current = snapshotMeasuredContentHeight(scrollerElement);
-      previousScrollTopRef.current = scrollerElement.scrollTop;
-      recordScrollerGeometry(scrollerElement);
-    } else {
-      recordScrollerGeometry(scrollerElement);
-    }
-
-    // Batch observer-triggered work into a single rAF per frame
-    let observerBatchPending = false;
-    const scheduleObserverBatch = () => {
-      if (observerBatchPending) return;
-      observerBatchPending = true;
-      requestAnimationFrame(() => {
-        observerBatchPending = false;
-        scheduleHeightMeasure(2);
-        scheduleVisibleTurnMeasure(2);
-        schedulePinReservationReconcile(2);
-        scheduleTransientTurnPinStabilization(2);
-        scheduleFollowToLatestWithViewportState('observer');
-        scheduleHistoryProjectionHandoffRelease(1);
-      });
-    };
-
-    resizeObserverRef.current?.disconnect();
-    resizeObserverRef.current = new ResizeObserver(() => {
-      if (!canProcessViewportGeometry(scrollerElement)) {
-        return;
-      }
-      syncPhysicalBottomAfterViewportResize(scrollerElement);
-      resolveLatestEndAnchorStabilizationRef.current?.('resize-observer');
-      scheduleObserverBatch();
-    });
-    resizeObserverRef.current.observe(resizeTarget);
-    if (resizeTarget !== scrollerElement) {
-      resizeObserverRef.current.observe(scrollerElement);
-    }
-
-    const handleWindowResize = () => {
-      if (!canProcessViewportGeometry(scrollerElement)) {
-        return;
-      }
-      syncPhysicalBottomAfterViewportResize(scrollerElement);
-      resolveLatestEndAnchorStabilizationRef.current?.('resize-observer');
-      scheduleObserverBatch();
-    };
-    window.addEventListener('resize', handleWindowResize);
-    window.visualViewport?.addEventListener('resize', handleWindowResize);
-
-    mutationObserverRef.current?.disconnect();
-    let mutationPending = false;
-    mutationObserverRef.current = new MutationObserver((mutations) => {
-      if (mutationPending) return;
-      if (!canProcessViewportGeometry(scrollerElement)) {
-        return;
-      }
-      if (!isProcessing) {
-        return;
-      }
-      const characterDataMutations = mutations.filter(mutation => mutation.type === 'characterData');
-      const attributesMutations = mutations.filter(mutation => mutation.type === 'attributes');
-      const hasSemanticMutation = (
-        characterDataMutations.length > 0 ||
-        attributesMutations.length > 0
-      );
-      if (!hasSemanticMutation) {
-        return;
-      }
-      mutationPending = true;
-      requestAnimationFrame(() => {
-        mutationPending = false;
-        scheduleObserverBatch();
-      });
-    });
-    mutationObserverRef.current.observe(scrollerElement, {
-      subtree: true,
-      childList: true,
-      characterData: true,
-    });
-
-    // The owned timer/frame finalizer does not depend on scroll events. Keep
-    // this check only as a backup for browsers that throttle background timers.
-    const replayDeferredFollowIfSettled = () => {
-      const now = performance.now();
-      const intent = pendingCollapseIntentRef.current;
-      if (intent.active && intent.expiresAtMs < now) {
-        finalizeCollapseIntent('collapse-intent-scroll-backup', {
-          expectedExpiresAtMs: intent.expiresAtMs,
-        });
-      }
-    };
-
-    const handleScroll = () => {
-      if (!canProcessViewportGeometry(scrollerElement)) {
-        return;
-      }
-      const now = performance.now();
-      const intent = pendingCollapseIntentRef.current;
-      const retainedCollapseAnchor = retainedCollapseAnchorRef.current;
-      const collapseProtectionActive = intent.active || retainedCollapseAnchor !== null;
-
-      // Reactive shrink-clamp restore: in follow + streaming mode, an upward
-      // jump in scrollTop that we did NOT request from JS and that is NOT
-      // attributable to a user gesture is the browser auto-clamping scrollTop
-      // because `scrollHeight` shrunk below `scrollTop + clientHeight`
-      // (typical cause: an unsignaled item shrink from Virtuoso re-measure
-      // or a tool result finalizing). With `overflow-anchor: none` we cannot
-      // ask the browser to keep the visual anchor for us.
-      //
-      // Unsignaled follow-mode shrink remains owned by the continuous tail loop.
-      // A known active or retained collapse is different: its transaction owns
-      // a bounded target and can restore a non-user clamp synchronously.
-      const intentCheckScrollTop = scrollerElement.scrollTop;
-      const intentCheckPreviousScrollTop = previousScrollTopRef.current;
-      const intentCheckScrollDelta = intentCheckScrollTop - intentCheckPreviousScrollTop;
-      const hasRecentUserUpwardIntent = now <= userInitiatedUpwardScrollUntilMsRef.current;
-      const pendingHistoryAnchor = pendingHistoryPrependAnchorRef.current;
-      if (pendingHistoryAnchor && !pendingHistoryAnchor.prependRestored) {
-        const anchorElement = getRenderedUserMessageElement(pendingHistoryAnchor.turnId);
-        if (anchorElement) {
-          const scrollerRect = scrollerElement.getBoundingClientRect();
-          pendingHistoryAnchor.offsetFromScrollerTop =
-            anchorElement.getBoundingClientRect().top - scrollerRect.top;
-        }
-      }
-      if (
-        flowChatDiagnostics.isEnabled() &&
-        Math.abs(intentCheckScrollDelta) > COMPENSATION_EPSILON_PX
-      ) {
-        flowChatDiagnostics.trace({
-          hypothesis: 'A',
-          location: 'VirtualMessageList.handleScroll',
-          message: 'Scroller position changed',
-          data: () => ({
-            scrollTop: intentCheckScrollTop,
-            previousScrollTop: intentCheckPreviousScrollTop,
-            scrollDelta: intentCheckScrollDelta,
-            scrollHeight: scrollerElement.scrollHeight,
-            clientHeight: scrollerElement.clientHeight,
-            hasRecentUserUpwardIntent,
-            scrollbarPointerInteractionActive: scrollbarPointerInteractionActiveRef.current,
-            coordinatorMode: viewportCoordinatorRef.current.getMode(),
-            reservation: bottomReservationStateRef.current,
-            isFollowingOutput: isFollowingOutputRef.current,
-            isStreamingOutput: isStreamingOutputRef.current,
-            collapseProtectionActive,
-          }),
-        });
-      }
-      const collapseAnchorScrollTop = intent.active
-        ? intent.anchorScrollTop
-        : retainedCollapseAnchor?.anchorScrollTop ?? null;
-      if (
-        collapseAnchorScrollTop !== null &&
-        intentCheckScrollDelta < -COMPENSATION_EPSILON_PX &&
-        !hasRecentUserUpwardIntent &&
-        collapseAnchorScrollTop - intentCheckScrollTop > COMPENSATION_EPSILON_PX
-      ) {
-        preserveCollapseAnchorScrollTop(
-          scrollerElement,
-          collapseAnchorScrollTop,
-          intent.active ? 'scroll-active-collapse' : 'scroll-retained-collapse',
-        );
-        if (!intent.active) {
-          scheduleRetainedCollapseSettlement('delayed-scroll-clamp');
-        }
-        return;
-      }
-      const isFollowingTailShrinkClampCandidate = (
-        intentCheckScrollDelta < -COMPENSATION_EPSILON_PX &&
-        isFollowingOutputRef.current &&
-        isStreamingOutputRef.current &&
-        !hasRecentUserUpwardIntent &&
-        !scrollbarPointerInteractionActiveRef.current &&
-        !collapseProtectionActive
-      );
-      const previousScrollerGeometry = isFollowingTailShrinkClampCandidate
-        ? previousScrollerGeometryRef.current
-        : null;
-      const previousShrinkClampGeometry = previousScrollerGeometry
-        ? {
-          ...previousScrollerGeometry,
-          scrollTop: intentCheckPreviousScrollTop,
-        }
-        : null;
-      const currentScrollerGeometry: ScrollerGeometrySnapshot | null = (
-        isFollowingTailShrinkClampCandidate && previousShrinkClampGeometry
-      )
-        ? {
-          scrollTop: intentCheckScrollTop,
-          scrollHeight: scrollerElement.scrollHeight,
-          clientHeight: scrollerElement.clientHeight,
-        }
-        : null;
-      const followingTailShrinkClampRecovery = currentScrollerGeometry
-        ? resolveFollowingTailShrinkClampRecovery({
-          previousGeometry: previousShrinkClampGeometry,
-          currentGeometry: currentScrollerGeometry,
-          isFollowingOutput: isFollowingOutputRef.current,
-          isStreamingOutput: isStreamingOutputRef.current,
-          hasRecentUserUpwardIntent,
-          scrollbarPointerInteractionActive: scrollbarPointerInteractionActiveRef.current,
-          collapseProtectionActive,
-        })
-        : null;
-      if (followingTailShrinkClampRecovery) {
-        acquireCollapseReservationOwner('late-shrink-clamp');
-        retainedCollapseAnchorRef.current = {
-          anchorScrollTop: followingTailShrinkClampRecovery.targetScrollTop,
-          toolId: null,
-          toolName: 'late-shrink-clamp',
-        };
-        preserveCollapseAnchorScrollTop(
-          scrollerElement,
-          followingTailShrinkClampRecovery.targetScrollTop,
-          'scroll-following-tail-late-shrink-clamp',
-        );
-        scheduleRetainedCollapseSettlement('following-tail-late-shrink-clamp');
-        if (flowChatDiagnostics.isEnabled()) {
-          flowChatDiagnostics.trace({
-            hypothesis: 'G',
-            location: 'VirtualMessageList.handleScroll',
-            message: 'Following-tail shrink clamp recovered as a viewport transaction',
-            data: () => ({
-              recovery: followingTailShrinkClampRecovery,
-              previousGeometry: previousScrollerGeometry,
-              currentGeometry: currentScrollerGeometry,
-              reservation: bottomReservationStateRef.current,
-              scrollTopAfter: scrollerElement.scrollTop,
-            }),
-          });
-        }
-        return;
-      }
-      if (
-        retainedCollapseAnchorRef.current &&
-        intentCheckScrollDelta > COMPENSATION_EPSILON_PX &&
-        !hasRecentUserUpwardIntent &&
-        !scrollbarPointerInteractionActiveRef.current
-      ) {
-        retainedCollapseAnchorRef.current.anchorScrollTop = Math.max(
-          retainedCollapseAnchorRef.current.anchorScrollTop,
-          intentCheckScrollTop,
-        );
-      }
-      if (
-        intentCheckScrollDelta < -COMPENSATION_EPSILON_PX &&
-        isFollowingOutputRef.current &&
-        isStreamingOutputRef.current &&
-        !hasRecentUserUpwardIntent &&
-        !collapseProtectionActive
-      ) {
-        if (flowChatDiagnostics.isEnabled()) {
-          flowChatDiagnostics.trace({
-            hypothesis: 'D',
-            location: 'VirtualMessageList.handleScroll',
-            message: 'Upward clamp delegated to the streaming follow loop',
-            data: () => ({
-              scrollTop: intentCheckScrollTop,
-              previousScrollTop: intentCheckPreviousScrollTop,
-              scrollDelta: intentCheckScrollDelta,
-            }),
-          });
-        }
-        // Follow+streaming: do not inject compensation or restore old
-        // scrollTop. Let the follow loop handle the scroll naturally on the
-        // next animation frame. Return here to prevent the downstream follow
-        // controller (followOutputControllerRef.current.handleScroll) from
-        // seeing the browser-clamp delta and misclassifying it as a user
-        // upward scroll, which would incorrectly exit follow mode.
-        previousScrollTopRef.current = intentCheckScrollTop;
-        recordScrollerGeometry(scrollerElement);
-        return;
-      }
-
-      const currentTotalCompensation = getTotalBottomCompensationPx();
-      if (
-        currentTotalCompensation > COMPENSATION_EPSILON_PX &&
-        !intent.active
-      ) {
-        const nextScrollTop = scrollerElement.scrollTop;
-        const scrollDelta = nextScrollTop - previousScrollTopRef.current;
-        if (scrollDelta > COMPENSATION_EPSILON_PX) {
-          const nextCompensationState = consumeBottomCompensation(scrollDelta);
-          applyFooterCompensationNow(nextCompensationState);
-          if (retainedCollapseAnchorRef.current) {
-            retainedCollapseAnchorRef.current.anchorScrollTop = Math.max(
-              retainedCollapseAnchorRef.current.anchorScrollTop,
-              scrollerElement.scrollTop,
-            );
-          }
-          previousMeasuredHeightRef.current = snapshotMeasuredContentHeight(
-            scrollerElement,
-            nextCompensationState,
-          );
-        }
-      }
-
-      if (viewportCoordinatorRef.current.scheduleElementAnchorRestore(scrollerElement, 'scroll-handler')) {
-        previousScrollTopRef.current = scrollerElement.scrollTop;
-        recordScrollerGeometry(scrollerElement);
-        return;
-      }
-      previousScrollTopRef.current = scrollerElement.scrollTop;
-      recordScrollerGeometryIfLayoutStable(scrollerElement);
-      scheduleVisibleTurnMeasure();
-      followOutputControllerRef.current.handleScroll();
-      if (
-        performance.now() <= userInitiatedUpwardScrollUntilMsRef.current ||
-        scrollbarPointerInteractionActiveRef.current
-      ) {
-        schedulePreviousHistoryWindowForUserIntent('scroll-near-partial-history-boundary');
-      }
-
-      replayDeferredFollowIfSettled();
-    };
-    scrollerElement.addEventListener('scroll', handleScroll, { passive: true });
-
-    const handleWheel = (event: WheelEvent) => {
-      if (flowChatDiagnostics.isEnabled() && event.deltaY !== 0) {
-        flowChatDiagnostics.trace({
-          hypothesis: 'A',
-          location: 'VirtualMessageList.handleWheel',
-          message: 'Wheel scroll intent observed',
-          data: () => ({
-            deltaY: event.deltaY,
-            scrollTop: scrollerElement.scrollTop,
-            coordinatorMode: viewportCoordinatorRef.current.getMode(),
-          }),
-        });
-      }
-      if (event.deltaY !== 0) {
-        notifyUserScrollIntent();
-        clearTurnPinRequest();
-        cancelLatestEndAnchorStabilization();
-      }
-
-      if (event.deltaY > 0) {
-        requestHistoryWindowBoundaryForUserIntent('after', 'wheel-down');
-      } else if (event.deltaY < 0) {
-        requestHistoryWindowBoundaryForUserIntent('before', 'wheel-up');
-      }
-
-      if (event.deltaY < 0) {
-        userInitiatedUpwardScrollUntilMsRef.current =
-          performance.now() + USER_UPWARD_SCROLL_INTENT_WINDOW_MS;
-        schedulePreviousHistoryWindowForUserIntent('wheel-up');
-        followOutputControllerRef.current.handleUserScrollIntent();
-      }
-    };
-
-    const handleTouchStart = (event: TouchEvent) => {
-      touchScrollIntentStartYRef.current = event.touches[0]?.clientY ?? null;
-    };
-
-    const handleTouchMove = (event: TouchEvent) => {
-      const startY = touchScrollIntentStartYRef.current;
-      const currentY = event.touches[0]?.clientY;
-      if (startY === null || currentY === undefined) {
-        return;
-      }
-
-      if (Math.abs(currentY - startY) > TOUCH_SCROLL_INTENT_EXIT_THRESHOLD_PX) {
-        if (flowChatDiagnostics.isEnabled()) {
-          flowChatDiagnostics.trace({
-            hypothesis: 'A',
-            location: 'VirtualMessageList.handleTouchMove',
-            message: 'Touch scroll intent crossed the exit threshold',
-            data: () => ({ deltaY: currentY - startY, scrollTop: scrollerElement.scrollTop }),
-          });
-        }
-        notifyUserScrollIntent();
-        clearTurnPinRequest();
-        cancelLatestEndAnchorStabilization();
-
-        if (currentY - startY < -TOUCH_SCROLL_INTENT_EXIT_THRESHOLD_PX) {
-          requestHistoryWindowBoundaryForUserIntent('after', 'touch-scroll-down');
-        } else {
-          requestHistoryWindowBoundaryForUserIntent('before', 'touch-scroll-up');
-        }
-      }
-
-      if (currentY - startY > TOUCH_SCROLL_INTENT_EXIT_THRESHOLD_PX) {
-        clearBottomReservationsForUserBrowsing();
-        touchScrollIntentStartYRef.current = currentY;
-        userInitiatedUpwardScrollUntilMsRef.current =
-          performance.now() + USER_UPWARD_SCROLL_INTENT_WINDOW_MS;
-        schedulePreviousHistoryWindowForUserIntent('touch-scroll-up');
-        followOutputControllerRef.current.handleUserScrollIntent();
-      }
-      if (Math.abs(currentY - startY) > TOUCH_SCROLL_INTENT_EXIT_THRESHOLD_PX) {
-        touchScrollIntentStartYRef.current = currentY;
-      }
-    };
-
-    const resetTouchScrollIntent = () => {
-      touchScrollIntentStartYRef.current = null;
-      restartHistoryPresentationCommitQuietWaiters();
-    };
-
-    const handleKeyDown = (event: KeyboardEvent) => {
-      if (!isScrollIntentKey(event) || isEditableElement(event.target)) {
-        return;
-      }
-
-      notifyUserScrollIntent();
-      if (flowChatDiagnostics.isEnabled()) {
-        flowChatDiagnostics.trace({
-          hypothesis: 'A',
-          location: 'VirtualMessageList.handleKeyDown',
-          message: 'Keyboard scroll intent observed',
-          data: () => ({ key: event.key, scrollTop: scrollerElement.scrollTop }),
-        });
-      }
-      clearTurnPinRequest();
-      cancelLatestEndAnchorStabilization();
-
-      if (!isUpwardScrollIntentKey(event)) {
-        requestHistoryWindowBoundaryForUserIntent('after', `keyboard-${event.key}`);
-        return;
-      }
-
-      userInitiatedUpwardScrollUntilMsRef.current =
-        performance.now() + USER_UPWARD_SCROLL_INTENT_WINDOW_MS;
-      schedulePreviousHistoryWindowForUserIntent('keyboard-scroll-up', { force: event.key === 'Home' });
-      requestHistoryWindowBoundaryForUserIntent('before', `keyboard-${event.key}`, {
-        force: event.key === 'Home',
-      });
-      followOutputControllerRef.current.handleUserScrollIntent();
-    };
-
-    const handlePointerDown = (event: PointerEvent) => {
-      if (event.pointerType === 'touch' || event.button !== 0) {
-        return;
-      }
-
-      if (!isPointerOnScrollbarGutter(scrollerElement, event.clientX, event.clientY)) {
-        return;
-      }
-
-      scrollbarPointerInteractionActiveRef.current = true;
-      if (flowChatDiagnostics.isEnabled()) {
-        flowChatDiagnostics.trace({
-          hypothesis: 'A',
-          location: 'VirtualMessageList.handlePointerDown',
-          message: 'Scrollbar pointer interaction started',
-          data: () => ({ scrollTop: scrollerElement.scrollTop }),
-        });
-      }
-      notifyUserScrollIntent();
-      clearTurnPinRequest();
-      cancelLatestEndAnchorStabilization();
-      userInitiatedUpwardScrollUntilMsRef.current =
-        performance.now() + USER_UPWARD_SCROLL_INTENT_WINDOW_MS;
-      schedulePreviousHistoryWindowForUserIntent('scrollbar-pointer-down');
-      requestHistoryWindowBoundaryForUserIntent('before', 'scrollbar-pointer-down');
-      requestHistoryWindowBoundaryForUserIntent('after', 'scrollbar-pointer-down');
-      followOutputControllerRef.current.handleUserScrollIntent();
-    };
-
-    const handlePointerMove = (event: PointerEvent) => {
-      if (!scrollbarPointerInteractionActiveRef.current || event.pointerType === 'touch') {
-        return;
-      }
-
-      if ((event.buttons & 1) !== 1) {
-        scrollbarPointerInteractionActiveRef.current = false;
-        return;
-      }
-
-      clearBottomReservationsForUserBrowsing();
-      clearTurnPinRequest();
-      if (flowChatDiagnostics.isEnabled()) {
-        flowChatDiagnostics.trace({
-          hypothesis: 'A',
-          location: 'VirtualMessageList.handlePointerMove',
-          message: 'Scrollbar pointer interaction moved',
-          data: () => ({ scrollTop: scrollerElement.scrollTop }),
-        });
-      }
-      notifyUserScrollIntent();
-      cancelLatestEndAnchorStabilization();
-      userInitiatedUpwardScrollUntilMsRef.current =
-        performance.now() + USER_UPWARD_SCROLL_INTENT_WINDOW_MS;
-      schedulePreviousHistoryWindowForUserIntent('scrollbar-pointer-move');
-      requestHistoryWindowBoundaryForUserIntent('before', 'scrollbar-pointer-move');
-      requestHistoryWindowBoundaryForUserIntent('after', 'scrollbar-pointer-move');
-      followOutputControllerRef.current.handleUserScrollIntent();
-    };
-
-    const endScrollbarPointerInteraction = () => {
-      scrollbarPointerInteractionActiveRef.current = false;
-      restartHistoryPresentationCommitQuietWaiters();
-    };
-
-    scrollerElement.addEventListener('wheel', handleWheel, { passive: true });
-    scrollerElement.addEventListener('touchstart', handleTouchStart, { passive: true });
-    scrollerElement.addEventListener('touchmove', handleTouchMove, { passive: true });
-    scrollerElement.addEventListener('touchend', resetTouchScrollIntent, { passive: true });
-    scrollerElement.addEventListener('touchcancel', resetTouchScrollIntent, { passive: true });
-    scrollerElement.addEventListener('keydown', handleKeyDown, true);
-    scrollerElement.addEventListener('pointerdown', handlePointerDown, true);
-    window.addEventListener('pointermove', handlePointerMove, true);
-    window.addEventListener('pointerup', endScrollbarPointerInteraction, true);
-    window.addEventListener('pointercancel', endScrollbarPointerInteraction, true);
-
-    const handleToolCardToggle = () => {
-      scheduleHeightMeasure(2);
-      scheduleVisibleTurnMeasure(2);
-      schedulePinReservationReconcile(2);
-      scheduleHistoryProjectionHandoffRelease(1);
-    };
-
-    const handleToolCardCollapseIntent = (event: Event) => {
-      if (!canProcessViewportGeometry(scrollerElement)) {
-        return;
-      }
-      const detail = (event as CustomEvent<{
-        toolId?: string | null;
-        toolName?: string | null;
-        cardHeight?: number | null;
-        anchorElement?: HTMLElement | null;
-        filePath?: string | null;
-        reason?: string | null;
-      }>).detail;
-      acquireCollapseReservationOwner('tool-collapse');
-      const previousIntent = pendingCollapseIntentRef.current;
-      clearRetainedCollapseSettlement();
-      if (flowChatDiagnostics.isEnabled()) {
-        flowChatDiagnostics.trace({
-          hypothesis: 'E',
-          location: 'VirtualMessageList.handleToolCardCollapseIntent',
-          message: 'Tool card collapse intent received',
-          data: () => ({
-            reason: detail?.reason ?? null,
-            toolName: detail?.toolName ?? null,
-            cardHeight: detail?.cardHeight ?? null,
-            hasAnchorElement: Boolean(detail?.anchorElement),
-            anchorElementConnected: detail?.anchorElement?.isConnected ?? null,
-            previousIntent,
-            coordinatorMode: viewportCoordinatorRef.current.getMode(),
-            reservation: bottomReservationStateRef.current,
-            scrollTop: scrollerElement.scrollTop,
-            scrollHeight: scrollerElement.scrollHeight,
-            clientHeight: scrollerElement.clientHeight,
-            isFollowingOutput: isFollowingOutputRef.current,
-            isStreamingOutput: isStreamingOutputRef.current,
-          }),
-        });
-      }
-      // Coalesce overlapping collapses instead of finalizing the previous
-      // intent. Finalizing mid-animation can briefly drop footer protection and
-      // flash the pane when several cards compact in the same stream burst.
-      if (detail?.anchorElement) {
-        viewportCoordinatorRef.current.preserveElement(detail.anchorElement);
-      } else if (!previousIntent.active) {
-        viewportCoordinatorRef.current.preserveElement(null);
-      }
-
-      const baseTotalCompensationPx = previousIntent.active
-        ? previousIntent.baseTotalCompensationPx
-        : getTotalBottomCompensationPx();
-      const currentScrollTop = scrollerElement.scrollTop;
-      const previousStableScrollTop = previousScrollTopRef.current;
-      const anchorScrollTop = previousIntent.active
-        ? previousIntent.anchorScrollTop
-        : resolveAutoCollapseAnchorScrollTop({
-          currentScrollTop,
-          previousStableScrollTop,
-          reason: detail?.reason,
-          isFollowingOutput: isFollowingOutputRef.current,
-          isStreamingOutput: isStreamingOutputRef.current,
-        });
-      const distanceFromBottom = Math.max(
-        0,
-        scrollerElement.scrollHeight - scrollerElement.clientHeight - currentScrollTop
-      );
-      const currentTotalCompensationPx = getTotalBottomCompensationPx();
-      const effectiveDistanceFromBottom = previousIntent.active
-        ? previousIntent.distanceFromBottomBeforeCollapse
-        : Math.max(0, distanceFromBottom - currentTotalCompensationPx);
-      const estimatedShrink = Math.max(0, detail?.cardHeight ?? 0);
-      const cumulativeShrinkPx = previousIntent.active
-        ? previousIntent.cumulativeShrinkPx
-        : 0;
-      const provisionalTotalCompensationPx = Math.max(
-        currentTotalCompensationPx,
-        baseTotalCompensationPx + Math.max(
-          0,
-          cumulativeShrinkPx + estimatedShrink - effectiveDistanceFromBottom,
-        ),
-      );
-      const nextIntent: PendingCollapseIntentState = {
-        active: true,
-        anchorScrollTop,
-        toolId: detail?.toolId ?? previousIntent.toolId ?? null,
-        toolName: detail?.toolName ?? previousIntent.toolName ?? null,
-        expiresAtMs: performance.now() + COLLAPSE_INTENT_TTL_MS,
-        distanceFromBottomBeforeCollapse: effectiveDistanceFromBottom,
-        baseTotalCompensationPx,
-        cumulativeShrinkPx,
-      };
-      pendingCollapseIntentRef.current = nextIntent;
-      if (flowChatDiagnostics.isEnabled()) {
-        flowChatDiagnostics.trace({
-          hypothesis: 'E',
-          location: 'VirtualMessageList.handleToolCardCollapseIntent',
-          message: 'Tool card collapse reservation calculated',
-          data: () => ({
-            nextIntent,
-            baseTotalCompensationPx,
-            currentTotalCompensationPx,
-            provisionalTotalCompensationPx,
-            effectiveDistanceFromBottom,
-            estimatedShrink,
-            currentScrollTop,
-            previousStableScrollTop,
-            coordinatorMode: viewportCoordinatorRef.current.getMode(),
-          }),
-        });
-      }
-      if (provisionalTotalCompensationPx - baseTotalCompensationPx > COMPENSATION_EPSILON_PX) {
-        const nextReservationState: BottomReservationState = {
-          ...bottomReservationStateRef.current,
-          collapse: {
-            ...bottomReservationStateRef.current.collapse,
-            px: Math.max(0, provisionalTotalCompensationPx - getReservationTotalPx(bottomReservationStateRef.current.pin)),
-          },
-        };
-        updateBottomReservationState(nextReservationState);
-        applyFooterCompensationNow(nextReservationState);
-      }
-
-      if (anchorScrollTop - currentScrollTop > COMPENSATION_EPSILON_PX) {
-        let maxScrollTop = Math.max(
-          0,
-          scrollerElement.scrollHeight - scrollerElement.clientHeight,
-        );
-        let rangeExtensionPx = 0;
-        if (anchorScrollTop - maxScrollTop > COMPENSATION_EPSILON_PX) {
-          rangeExtensionPx = anchorScrollTop - maxScrollTop + 1;
-          const currentState = bottomReservationStateRef.current;
-          const extendedState: BottomReservationState = {
-            ...currentState,
-            collapse: {
-              ...currentState.collapse,
-              px: currentState.collapse.px + rangeExtensionPx,
-            },
-          };
-          updateBottomReservationState(extendedState);
-          applyFooterCompensationNow(extendedState);
-          maxScrollTop = Math.max(
-            0,
-            scrollerElement.scrollHeight - scrollerElement.clientHeight,
-          );
-        }
-        scrollerElement.scrollTop = Math.min(anchorScrollTop, maxScrollTop);
-        previousScrollTopRef.current = scrollerElement.scrollTop;
-        recordScrollerGeometry(scrollerElement);
-      }
-
-      scheduleCollapseIntentFinalization(nextIntent, detail?.reason);
-
-      scheduleVisibleTurnMeasure(2);
-      schedulePinReservationReconcile(2);
-    };
-
-    window.addEventListener('tool-card-toggle', handleToolCardToggle);
-    window.addEventListener('flowchat:tool-card-collapse-intent', handleToolCardCollapseIntent as EventListener);
-    scheduleVisibleTurnMeasure(2);
-
-    return () => {
-      scrollerElement.removeEventListener('scroll', handleScroll);
-      scrollerElement.removeEventListener('wheel', handleWheel);
-      scrollerElement.removeEventListener('touchstart', handleTouchStart);
-      scrollerElement.removeEventListener('touchmove', handleTouchMove);
-      scrollerElement.removeEventListener('touchend', resetTouchScrollIntent);
-      scrollerElement.removeEventListener('touchcancel', resetTouchScrollIntent);
-      scrollerElement.removeEventListener('keydown', handleKeyDown, true);
-      scrollerElement.removeEventListener('pointerdown', handlePointerDown, true);
-      window.removeEventListener('pointermove', handlePointerMove, true);
-      window.removeEventListener('pointerup', endScrollbarPointerInteraction, true);
-      window.removeEventListener('pointercancel', endScrollbarPointerInteraction, true);
-      window.removeEventListener('tool-card-toggle', handleToolCardToggle);
-      window.removeEventListener('flowchat:tool-card-collapse-intent', handleToolCardCollapseIntent as EventListener);
-      window.removeEventListener('resize', handleWindowResize);
-      window.visualViewport?.removeEventListener('resize', handleWindowResize);
-      resizeObserverRef.current?.disconnect();
-      resizeObserverRef.current = null;
-      mutationObserverRef.current?.disconnect();
-      mutationObserverRef.current = null;
-      touchScrollIntentStartYRef.current = null;
-      scrollbarPointerInteractionActiveRef.current = false;
-
-      if (measureFrameRef.current !== null) {
-        cancelAnimationFrame(measureFrameRef.current);
-        measureFrameRef.current = null;
-      }
-
-      if (visibleTurnMeasureFrameRef.current !== null) {
-        cancelAnimationFrame(visibleTurnMeasureFrameRef.current);
-        visibleTurnMeasureFrameRef.current = null;
-      }
-
-      if (pinReservationReconcileFrameRef.current !== null) {
-        cancelAnimationFrame(pinReservationReconcileFrameRef.current);
-        pinReservationReconcileFrameRef.current = null;
-      }
-
-      if (turnPinStabilizationFrameRef.current !== null) {
-        cancelAnimationFrame(turnPinStabilizationFrameRef.current);
-        turnPinStabilizationFrameRef.current = null;
-      }
-
-      if (fullHistoryProjectionIntentFrameRef.current !== null) {
-        cancelAnimationFrame(fullHistoryProjectionIntentFrameRef.current);
-        fullHistoryProjectionIntentFrameRef.current = null;
-      }
-      pendingFullHistoryProjectionReasonRef.current = null;
-    };
-  }, [
-    applyFooterCompensationNow,
-    acquireCollapseReservationOwner,
-    canProcessViewportGeometry,
-    cancelLatestEndAnchorStabilization,
-    clearBottomReservationsForUserBrowsing,
-    consumeBottomCompensation,
-    clearRetainedCollapseSettlement,
-    clearTurnPinRequest,
-    finalizeCollapseIntent,
-    getRenderedUserMessageElement,
-    getTotalBottomCompensationPx,
-    latestTurnId,
-    notifyUserScrollIntent,
-    pendingTurnPin?.pinMode,
-    pendingTurnPin?.turnId,
-    preserveCollapseAnchorScrollTop,
-    recordScrollerGeometry,
-    recordScrollerGeometryIfLayoutStable,
-    scheduleHeightMeasure,
-    scheduleFollowToLatestWithViewportState,
-    schedulePreviousHistoryWindowForUserIntent,
-    scheduleHistoryProjectionHandoffRelease,
-    schedulePinReservationReconcile,
-    requestHistoryWindowBoundaryForUserIntent,
-    restartHistoryPresentationCommitQuietWaiters,
-    scheduleRetainedCollapseSettlement,
-    scheduleTransientTurnPinStabilization,
-    scheduleVisibleTurnMeasure,
-    scrollerElement,
-    scheduleCollapseIntentFinalization,
-    snapshotMeasuredContentHeight,
-    syncPhysicalBottomAfterViewportResize,
-    isProcessing,
-    updateBottomReservationState,
-  ]);
-
-  const resolveLatestEndAnchorStabilization = useCallback((reason: LatestEndAnchorResolveReason) => {
-    const request = latestEndAnchorRequestRef.current;
-    if (!request) {
-      return false;
-    }
-    if (!canProcessViewportGeometry(scrollerElementRef.current)) {
-      return false;
-    }
-
-    const scheduleNextResolve = () => {
-      if (latestEndAnchorStabilizationFrameRef.current === null) {
-        latestEndAnchorStabilizationFrameRef.current = requestAnimationFrame(() => {
-          latestEndAnchorStabilizationFrameRef.current = null;
-          resolveLatestEndAnchorStabilization('raf');
-        });
-      }
-    };
-
-    const scroller = scrollerElementRef.current;
-    const virtuoso = virtuosoRef.current;
-    if (!scroller) {
-      request.attempts += 1;
-      if (request.attempts >= LATEST_END_ANCHOR_STABILIZATION_MAX_ATTEMPTS) {
-        cancelLatestEndAnchorStabilization();
-        startupTrace.markPhase('flowchat_latest_end_anchor_unresolved', {
-          attempts: request.attempts,
-          reason,
-          targetIndex: request.targetIndex,
-          turnId: request.turnId,
-          cause: 'missing_scroller',
-        });
-        return false;
-      }
-
-      scheduleNextResolve();
-      return false;
-    }
-
-    let targetIndex = request.targetIndex;
-    if (targetIndex < 0 || virtualItems[targetIndex]?.turnId !== request.turnId) {
-      targetIndex = -1;
-      for (let index = virtualItems.length - 1; index >= 0; index -= 1) {
-        if (virtualItems[index]?.turnId === request.turnId) {
-          targetIndex = index;
-          break;
-        }
-      }
-      request.targetIndex = targetIndex;
-    }
-
-    if (targetIndex < 0) {
-      cancelLatestEndAnchorStabilization();
-      return false;
-    }
-
-    request.attempts += 1;
-    const shouldSnapTargetToPhysicalBottom =
-      targetIndex >= virtualItems.length - 1 ||
-      request.turnId === latestTurnId;
-    const targetElement = getRenderedVirtualItemElement(targetIndex);
-    const scrollerRect = scroller.getBoundingClientRect();
-    const inputOverlayInsetPx = Math.max(
-      0,
-      inputStackFooterPxRef.current - FLOWCHAT_MESSAGE_TAIL_CLEARANCE_PX,
-    );
-    const visibleTop = scrollerRect.top + LATEST_END_ANCHOR_VISIBILITY_MARGIN_PX;
-    const visibleBottom = Math.max(
-      visibleTop + 1,
-      scrollerRect.bottom - inputOverlayInsetPx - LATEST_END_ANCHOR_VISIBILITY_MARGIN_PX,
-    );
-
-    const readTargetEndState = (currentTargetElement: HTMLElement | null) => {
-      if (!currentTargetElement) {
-        return null;
-      }
-      const rect = currentTargetElement.getBoundingClientRect();
-      const maxScrollTop = Math.max(0, scroller.scrollHeight - scroller.clientHeight);
-      const endDeltaPx = rect.bottom - visibleBottom;
-      const physicalBottomAnchored =
-        Math.abs(maxScrollTop - scroller.scrollTop) <= LATEST_END_ANCHOR_STABLE_EPSILON_PX;
-      const endAnchored = shouldSnapTargetToPhysicalBottom
-        ? physicalBottomAnchored
-        : (
-          Math.abs(endDeltaPx) <= LATEST_END_ANCHOR_STABLE_EPSILON_PX ||
-          (endDeltaPx > 0 && physicalBottomAnchored) ||
-          (endDeltaPx < 0 && scroller.scrollTop <= LATEST_END_ANCHOR_STABLE_EPSILON_PX)
-        );
-      return {
-        endAnchored,
-        endDeltaPx,
-        maxScrollTop,
-        rect,
-        visible: rect.bottom > visibleTop && rect.top < visibleBottom,
-      };
-    };
-
-    const settleIfStableEndAnchored = () => {
-      const currentTargetElement = getRenderedVirtualItemElement(targetIndex);
-      const state = readTargetEndState(currentTargetElement);
-      if (!state?.visible || !state.endAnchored) {
-        request.visibleFrames = 0;
-        request.stableVisibleFrames = 0;
-        return false;
-      }
-
-      const scrollHeight = scroller.scrollHeight;
-      const scrollTop = scroller.scrollTop;
-      const geometryStable = (
-        request.lastScrollHeight !== null &&
-        request.lastScrollTop !== null &&
-        request.lastTargetTop !== null &&
-        request.lastTargetBottom !== null &&
-        Math.abs(scrollHeight - request.lastScrollHeight) <= LATEST_END_ANCHOR_STABLE_EPSILON_PX &&
-        Math.abs(scrollTop - request.lastScrollTop) <= LATEST_END_ANCHOR_STABLE_EPSILON_PX &&
-        Math.abs(state.rect.top - request.lastTargetTop) <= LATEST_END_ANCHOR_STABLE_EPSILON_PX &&
-        Math.abs(state.rect.bottom - request.lastTargetBottom) <= LATEST_END_ANCHOR_STABLE_EPSILON_PX
-      );
-
-      request.lastScrollHeight = scrollHeight;
-      request.lastScrollTop = scrollTop;
-      request.lastTargetTop = state.rect.top;
-      request.lastTargetBottom = state.rect.bottom;
-      request.visibleFrames += 1;
-      request.stableVisibleFrames = geometryStable ? request.stableVisibleFrames + 1 : 1;
-
-      if (
-        request.attempts < LATEST_END_ANCHOR_STABILIZATION_MIN_ATTEMPTS ||
-        request.stableVisibleFrames < LATEST_END_ANCHOR_STABLE_VISIBLE_FRAMES
-      ) {
-        scheduleNextResolve();
-        return true;
-      }
-
-      startupTrace.markPhase('flowchat_latest_end_anchor_settled', {
-        attempts: request.attempts,
-        reason,
-        stableVisibleFrames: request.stableVisibleFrames,
-        targetIndex,
-        turnId: request.turnId,
-      });
-      cancelLatestEndAnchorStabilization();
-      scheduleVisibleTurnMeasure(1);
-      return true;
-    };
-
-    if (settleIfStableEndAnchored()) {
-      return true;
-    }
-
-    request.visibleFrames = 0;
-    request.stableVisibleFrames = 0;
-    request.lastScrollHeight = null;
-    request.lastScrollTop = null;
-    request.lastTargetTop = null;
-    request.lastTargetBottom = null;
-
-    if (targetElement) {
-      const state = readTargetEndState(targetElement);
-      let nextScrollTop = scroller.scrollTop;
-      if (state) {
-        nextScrollTop = shouldSnapTargetToPhysicalBottom
-          ? state.maxScrollTop
-          : Math.max(
-            0,
-            Math.min(state.maxScrollTop, scroller.scrollTop + state.endDeltaPx),
-          );
-      }
-
-      if (Math.abs(nextScrollTop - scroller.scrollTop) > COMPENSATION_EPSILON_PX) {
-        scroller.scrollTop = nextScrollTop;
-        previousScrollTopRef.current = nextScrollTop;
-        previousMeasuredHeightRef.current = snapshotMeasuredContentHeight(scroller);
-        recordScrollerGeometry(scroller);
-      }
-    } else if (virtuoso) {
-      request.visibleFrames = 0;
-      virtuoso.scrollToIndex({
-        index: targetIndex,
-        align: 'end',
-        behavior: 'auto',
-      });
-      const shouldUseTailFallback =
-        targetIndex >= virtualItems.length - 1 ||
-        request.turnId === latestTurnId;
-      if (shouldUseTailFallback) {
-        const maxScrollTop = Math.max(0, scroller.scrollHeight - scroller.clientHeight);
-        if (Math.abs(maxScrollTop - scroller.scrollTop) > COMPENSATION_EPSILON_PX) {
-          scroller.scrollTop = maxScrollTop;
-          previousScrollTopRef.current = maxScrollTop;
-          previousMeasuredHeightRef.current = snapshotMeasuredContentHeight(scroller);
-          recordScrollerGeometry(scroller);
-        }
-      }
-    } else {
-      request.visibleFrames = 0;
-      const maxScrollTop = Math.max(0, scroller.scrollHeight - scroller.clientHeight);
-      if (Math.abs(maxScrollTop - scroller.scrollTop) > COMPENSATION_EPSILON_PX) {
-        scroller.scrollTop = maxScrollTop;
-        previousScrollTopRef.current = maxScrollTop;
-        previousMeasuredHeightRef.current = snapshotMeasuredContentHeight(scroller);
-        recordScrollerGeometry(scroller);
-      }
-    }
-
-    if (settleIfStableEndAnchored()) {
-      return true;
-    }
-
-    if (request.attempts >= LATEST_END_ANCHOR_STABILIZATION_MAX_ATTEMPTS) {
-      cancelLatestEndAnchorStabilization();
-      scheduleVisibleTurnMeasure(1);
-      startupTrace.markPhase('flowchat_latest_end_anchor_unresolved', {
-        attempts: request.attempts,
-        reason,
-        targetIndex,
-        turnId: request.turnId,
-      });
-      return false;
-    }
-
-    scheduleNextResolve();
-
-    return false;
-  }, [
-    cancelLatestEndAnchorStabilization,
-    canProcessViewportGeometry,
-    getRenderedVirtualItemElement,
-    latestTurnId,
-    recordScrollerGeometry,
-    scheduleVisibleTurnMeasure,
-    snapshotMeasuredContentHeight,
-    virtualItems,
-  ]);
-  resolveLatestEndAnchorStabilizationRef.current = resolveLatestEndAnchorStabilization;
-
-  const resolvePendingTurnPinFromRangeChange = useCallback(() => {
-    if (
-      !pendingTurnPin ||
-      !isTurnPinRequestCurrent(pendingTurnPin) ||
-      performance.now() > pendingTurnPin.expiresAtMs
-    ) {
-      return;
-    }
-
-    const nextRequest: PendingTurnPinState = {
-      ...pendingTurnPin,
-      attempts: pendingTurnPin.attempts + 1,
-      behavior: 'auto',
-    };
-    const resolution = tryResolvePendingTurnPin(nextRequest);
-    if (resolution.kind === 'pending') {
-      setPendingTurnPin(current => (
-        current?.generation === nextRequest.generation ? nextRequest : current
-      ));
-      return;
-    }
-
-    if (resolution.kind === 'best-effort' && settleBestEffortTurnPin(nextRequest)) {
-      scheduleVisibleTurnMeasure(2);
-      return;
-    }
-
-    if (nextRequest.pinMode === 'transient') {
-      activateTransientTurnPinStabilization(nextRequest);
-      scheduleTransientTurnPinStabilization(2);
-      setPendingTurnPin(current => (
-        current?.generation === nextRequest.generation ? nextRequest : current
-      ));
-    } else {
-      clearTurnPinRequest();
-    }
-    scheduleVisibleTurnMeasure(2);
-  }, [
-    activateTransientTurnPinStabilization,
-    clearTurnPinRequest,
-    isTurnPinRequestCurrent,
-    pendingTurnPin,
-    scheduleTransientTurnPinStabilization,
-    scheduleVisibleTurnMeasure,
-    settleBestEffortTurnPin,
-    tryResolvePendingTurnPin,
-  ]);
-
-  // `rangeChanged` is affected by overscan/increaseViewportBy, so treat it as a
-  // "rendered DOM changed" signal and derive the pinned turn from real DOM visibility.
-  const handleRangeChanged = useCallback(() => {
-    if (!canProcessViewportGeometry(scrollerElementRef.current)) {
-      return;
-    }
-    resolvePendingTurnPinFromRangeChange();
-    resolveLatestEndAnchorStabilization('range-changed');
-    scheduleVisibleTurnMeasure(2);
-    schedulePinReservationReconcile(2);
-    scheduleTransientTurnPinStabilization(2);
-    scheduleFollowToLatestWithViewportState('range-changed');
-    // Reset the handoff release timer rather than accelerating it.
-    // A session-open projection handoff needs the Virtuoso measurement
-    // to settle before releasing; calling with 3 resets the countdown
-    // so the handoff stays until 3 frames of stability pass.
-    scheduleHistoryProjectionHandoffRelease(3);
-  }, [
-    resolvePendingTurnPinFromRangeChange,
-    canProcessViewportGeometry,
-    resolveLatestEndAnchorStabilization,
-    scheduleFollowToLatestWithViewportState,
-    scheduleHistoryProjectionHandoffRelease,
-    schedulePinReservationReconcile,
-    scheduleTransientTurnPinStabilization,
-    scheduleVisibleTurnMeasure,
-  ]);
-
-  useEffect(() => {
-    if (userMessageItems.length === 0) {
-      const setVisibleTurnInfo = useModernFlowChatStore.getState().setVisibleTurnInfo;
-      setVisibleTurnInfo(null);
-      return;
-    }
-
-    scheduleVisibleTurnMeasure(2);
-    schedulePinReservationReconcile(2);
-    scheduleTransientTurnPinStabilization(2);
-  }, [
-    activeSession?.sessionId,
-    schedulePinReservationReconcile,
-    scheduleTransientTurnPinStabilization,
-    scheduleVisibleTurnMeasure,
-    scrollerElement,
-    userMessageItems,
-    virtualItems.length,
-  ]);
-
-  useEffect(() => {
-    if (!pendingTurnPin) return;
-    if (!isViewportActive || viewportGeometrySuspendedRef.current) {
-      return;
-    }
-
-    if (!isTurnPinRequestCurrent(pendingTurnPin)) {
-      pendingTurnPinGenerationRef.current = null;
-      setPendingTurnPin(prev => (
-        prev?.generation === pendingTurnPin.generation ? null : prev
-      ));
-      return;
-    }
-
-    if (performance.now() > pendingTurnPin.expiresAtMs) {
-      if (clearExpiredProvisionalStickyPin(pendingTurnPin)) {
-        clearTurnPinRequest();
-        followOutputControllerRef.current.scheduleFollowToLatest(
-          'unresolved-turn-pin-expired',
-        );
-      } else {
-        cancelUnresolvedTurnPinRef.current();
-      }
-      return;
-    }
-
-    const frameId = requestAnimationFrame(() => {
-      if (pendingTurnPinGenerationRef.current !== pendingTurnPin.generation) {
-        return;
-      }
-      const resolved = tryResolvePendingTurnPin(pendingTurnPin);
-      if (resolved.kind !== 'pending') {
-        if (resolved.kind === 'best-effort' && settleBestEffortTurnPin(pendingTurnPin)) {
-          scheduleVisibleTurnMeasure(2);
-          return;
-        }
-        if (
-          pendingTurnPin.pinMode === 'transient' &&
-          performance.now() <= pendingTurnPin.expiresAtMs
-        ) {
-          activateTransientTurnPinStabilization(pendingTurnPin);
-          scheduleTransientTurnPinStabilization(2);
-          scheduleVisibleTurnMeasure(2);
-          return;
-        }
-
-        clearTurnPinRequest();
-        scheduleVisibleTurnMeasure(2);
-        return;
-      }
-
-      setPendingTurnPin(prev => {
-        if (
-          !prev ||
-          prev.generation !== pendingTurnPin.generation ||
-          !isTurnPinRequestCurrent(pendingTurnPin)
-        ) {
-          return prev;
-        }
-
-        return {
-          ...prev,
-          attempts: prev.attempts + 1,
-          behavior: 'auto',
-        };
-      });
-    });
-
-    return () => {
-      cancelAnimationFrame(frameId);
-    };
-  }, [
-    activateTransientTurnPinStabilization,
-    clearExpiredProvisionalStickyPin,
-    clearTurnPinRequest,
-    isTurnPinRequestCurrent,
-    pendingTurnPin,
-    isViewportActive,
-    scheduleTransientTurnPinStabilization,
-    scheduleVisibleTurnMeasure,
-    settleBestEffortTurnPin,
-    tryResolvePendingTurnPin,
-  ]);
-
-  // ── Navigation helpers ────────────────────────────────────────────────
-  const clearAllBottomReservationsForUserNavigation = useCallback(() => {
-    const currentState = bottomReservationStateRef.current;
-    const scroller = scrollerElementRef.current;
-    const nextReservationState = createInitialBottomReservationState();
-    const hasActiveReservation = !areBottomReservationStatesEqual(currentState, nextReservationState);
-
-    viewportCoordinatorRef.current.release('clear-all-reservations');
-    clearTurnPinRequest();
-    clearCollapseIntentScheduling();
-    clearPendingStickyPinGrowth('clear-all-reservations');
-    pendingCollapseIntentRef.current = createInactiveCollapseIntentState();
-    retainedCollapseAnchorRef.current = null;
-    clearCollapseReservationOwner();
-
-    if (!hasActiveReservation) {
-      return;
-    }
-
-    bottomReservationStateRef.current = nextReservationState;
-    updateBottomReservationState(nextReservationState);
-    applyFooterCompensationNow(nextReservationState);
-
-    if (scroller) {
-      previousScrollTopRef.current = scroller.scrollTop;
-      previousMeasuredHeightRef.current = snapshotMeasuredContentHeight(scroller, nextReservationState);
-      recordScrollerGeometry(scroller);
-    }
-  }, [
-    applyFooterCompensationNow,
-    clearTurnPinRequest,
-    clearCollapseIntentScheduling,
-    clearCollapseReservationOwner,
-    clearPendingStickyPinGrowth,
-    recordScrollerGeometry,
-    snapshotMeasuredContentHeight,
-    updateBottomReservationState,
-  ]);
-
-  const clearPinReservationForUserNavigation = useCallback((
-    reason = 'user-navigation',
-    options?: { preserveCurrentRange?: boolean },
-  ) => {
-    const currentState = bottomReservationStateRef.current;
-    const scroller = scrollerElementRef.current;
-    const hasActivePin = (
-      currentState.pin.px > COMPENSATION_EPSILON_PX ||
-      currentState.pin.floorPx > COMPENSATION_EPSILON_PX ||
-      currentState.pin.targetTurnId !== null ||
-      currentState.pin.mode !== 'transient'
-    );
-
-    if (flowChatDiagnostics.isEnabled()) {
-      flowChatDiagnostics.trace({
-        hypothesis: 'A',
-        location: 'VirtualMessageList.clearPinReservationForUserNavigation',
-        message: 'User navigation began pin reservation release',
-        data: () => ({
-          reason,
-          preserveCurrentRange: options?.preserveCurrentRange === true,
-          hasActivePin,
-          reservationBefore: currentState,
-          coordinatorMode: viewportCoordinatorRef.current.getMode(),
-          scrollTop: scroller?.scrollTop ?? null,
-          scrollHeight: scroller?.scrollHeight ?? null,
-          clientHeight: scroller?.clientHeight ?? null,
-        }),
-      });
-    }
-
-    clearTurnPinRequest();
-    clearPendingStickyPinGrowth(reason);
-
-    if (!hasActivePin) {
-      return;
-    }
-
-    const nextReservationState = releasePinReservationForUserNavigation(currentState, {
-      preserveCurrentRange: options?.preserveCurrentRange === true,
-      ownsElementAnchor: viewportCoordinatorRef.current.ownsElementAnchor(),
-    });
-    if (
-      nextReservationState.collapse.px > COMPENSATION_EPSILON_PX &&
-      collapseReservationOwnerRef.current === null
-    ) {
-      acquireCollapseReservationOwner('protected-range');
-    }
-    if (flowChatDiagnostics.isEnabled()) {
-      flowChatDiagnostics.trace({
-        hypothesis: 'A',
-        location: 'VirtualMessageList.clearPinReservationForUserNavigation',
-        message: 'Pin reservation released for user navigation',
-        data: () => ({
-          reason,
-          preserveCurrentRange: options?.preserveCurrentRange === true,
-          reservationBefore: currentState,
-          reservationAfter: nextReservationState,
-        }),
-      });
-    }
-    updateBottomReservationState(nextReservationState);
-    applyFooterCompensationNow(nextReservationState);
-
-    if (scroller) {
-      previousScrollTopRef.current = scroller.scrollTop;
-      previousMeasuredHeightRef.current = snapshotMeasuredContentHeight(scroller, nextReservationState);
-      recordScrollerGeometry(scroller);
-    }
-  }, [
-    applyFooterCompensationNow,
-    acquireCollapseReservationOwner,
-    clearPendingStickyPinGrowth,
-    clearTurnPinRequest,
-    recordScrollerGeometry,
-    snapshotMeasuredContentHeight,
-    updateBottomReservationState,
-  ]);
-
-  cancelUnresolvedTurnPinRef.current = () => {
-    clearPinReservationForUserNavigation('unresolved-turn-pin-expired', {
-      preserveCurrentRange: true,
-    });
-    viewportCoordinatorRef.current.release('unresolved-turn-pin-expired');
-  };
-
-  exitPinnedViewportForUserIntentRef.current = reason => {
-    if (flowChatDiagnostics.isEnabled()) {
-      flowChatDiagnostics.trace({
-        hypothesis: 'A',
-        location: 'VirtualMessageList.exitPinnedViewportForUserIntent',
-        message: 'User intent exited the pinned viewport',
-        data: () => ({
-          reason,
-          coordinatorModeBefore: viewportCoordinatorRef.current.getMode(),
-          reservationBefore: bottomReservationStateRef.current,
-        }),
-      });
-    }
-    viewportCoordinatorRef.current.release(reason);
-    clearPinReservationForUserNavigation(reason, { preserveCurrentRange: true });
-  };
-
-  const isStreamingOutput = React.useMemo(() => {
-    if (viewportMode === 'history-reading') {
-      return false;
-    }
-    if (isProcessing) {
-      return true;
-    }
-
-    const dialogTurns = activeSession?.dialogTurns;
-    const lastDialogTurn = dialogTurns && dialogTurns.length > 0
-      ? dialogTurns[dialogTurns.length - 1]
-      : undefined;
-
-    if (!lastDialogTurn) {
-      return false;
-    }
-
-    if (
-      lastDialogTurn.status === 'processing' ||
-      lastDialogTurn.status === 'finishing' ||
-      lastDialogTurn.status === 'image_analyzing'
-    ) {
-      return true;
-    }
-
-    return lastDialogTurn.modelRounds.some(round => round.isStreaming);
-  }, [activeSession, isProcessing, viewportMode]);
-  if (virtuosoMountStateRef.current.sessionId !== activeSessionId) {
-    virtuosoMountStateRef.current = {
-      sessionId: activeSessionId,
-      mounted: false,
-    };
-  }
-  if (virtualItems.length === 0) {
-    virtuosoMountStateRef.current.mounted = false;
-  }
-  const initialTopMostItemIndexCandidate = React.useMemo<InitialTopMostItemIndex>(() => {
-    const preparedTurnId = preparedHistoryTurnPinRef.current?.turnId;
-    if (preparedTurnId) {
-      const preparedTargetIndex = virtualItems.findIndex(item => (
-        item.turnId === preparedTurnId && item.type === 'user-message'
-      ));
-      if (preparedTargetIndex >= 0) {
-        return {
-          index: preparedTargetIndex,
-          align: 'start',
-        };
-      }
-    }
-
-    if (historyPagingActive && historyPagingAnchorTurnId) {
-      const anchorIndex = virtualItems.findIndex(item => (
-        item.turnId === historyPagingAnchorTurnId && item.type === 'user-message'
-      ));
-      if (anchorIndex >= 0) {
-        return {
-          index: anchorIndex,
-          align: 'start',
-        };
-      }
-    }
-
-    if (isStreamingOutput) {
-      return latestUserMessageIndex;
-    }
-
-    return {
-      index: Math.max(0, virtualItems.length - 1),
-      align: 'end',
-    };
-  }, [
-    historyPagingActive,
-    historyPagingAnchorTurnId,
-    isStreamingOutput,
-    latestUserMessageIndex,
-    virtualItems,
-  ]);
-  const initialTopMostItemIndex = virtuosoMountStateRef.current.mounted
-    ? undefined
-    : initialTopMostItemIndexCandidate;
-  const virtuosoViewportIncrease = React.useMemo(() => {
-    if (!pendingTurnPin) {
-      return FLOW_CHAT_VIRTUOSO_VIEWPORT_INCREASE;
-    }
-    const navigationRangePx = Math.max(
-      FLOW_CHAT_VIRTUOSO_VIEWPORT_INCREASE.top,
-      (scrollerElement?.clientHeight ?? 0) * TRANSIENT_TURN_PIN_VIEWPORT_MULTIPLIER,
-    );
-    return {
-      top: navigationRangePx,
-      bottom: navigationRangePx,
-    };
-  }, [pendingTurnPin, scrollerElement]);
-
-  useLayoutEffect(() => {
-    if (!historyPagingActive || !historyPagingAnchorTurnId) {
-      return;
-    }
-
-    const pendingAnchor = pendingHistoryPrependAnchorRef.current;
-    if (!pendingAnchor || pendingAnchor.turnId !== historyPagingAnchorTurnId) {
-      return;
-    }
-    const isPrependCommit = virtualItems.length > pendingAnchor.beforeItemCount;
-    if (isPrependCommit ? pendingAnchor.prependRestored : pendingAnchor.handoffRestored) {
-      return;
-    }
-
-    const scroller = scrollerElementRef.current;
-    const anchorElement = getRenderedUserMessageElement(historyPagingAnchorTurnId);
-    if (!scroller || !anchorElement) {
-      return;
-    }
-
-    const scrollerRect = scroller.getBoundingClientRect();
-    const actualOffset = anchorElement.getBoundingClientRect().top - scrollerRect.top;
-    const correction = actualOffset - pendingAnchor.offsetFromScrollerTop;
-    if (Math.abs(correction) > COMPENSATION_EPSILON_PX) {
-      scroller.scrollTop = Math.max(0, scroller.scrollTop + correction);
-    }
-    if (presentationMode === 'history-window') {
-      viewportCoordinatorRef.current.preserveElement(anchorElement);
-    }
-    if (isPrependCommit) {
-      pendingAnchor.prependRestored = true;
-      pendingHistoryPrependAnchorRef.current = null;
-      setHistoryPagingLoading(false);
-      setHistoryPagingAnchorTurnId(null);
-      clearPreviousHistoryBoundaryStatus();
-    } else {
-      pendingAnchor.handoffRestored = true;
-    }
-    previousScrollTopRef.current = scroller.scrollTop;
-    previousMeasuredHeightRef.current = snapshotMeasuredContentHeight(scroller);
-    recordScrollerGeometry(scroller);
-  }, [
-    clearPreviousHistoryBoundaryStatus,
-    getRenderedUserMessageElement,
-    historyPagingActive,
-    historyPagingAnchorTurnId,
-    presentationMode,
-    recordScrollerGeometry,
-    scrollerElement,
-    snapshotMeasuredContentHeight,
-    virtualItems,
-  ]);
-
-  useLayoutEffect(() => {
-    if (presentationMode !== 'history-window' || presentationRevision <= 0) {
-      return;
-    }
+  const scrollToContentEnd = useCallback((behavior: ScrollBehavior) => {
     const scroller = scrollerElementRef.current;
-    if (!scroller || !viewportCoordinatorRef.current.ownsElementAnchor()) {
-      return;
-    }
-
-    viewportCoordinatorRef.current.scheduleElementAnchorRestore(
-      scroller,
-      'history-window-presentation-commit',
-    );
-    let secondFrameId: number | null = null;
-    const firstFrameId = requestAnimationFrame(() => {
-      viewportCoordinatorRef.current.scheduleElementAnchorRestore(
-        scroller,
-        'history-window-presentation-measured',
-      );
-      secondFrameId = requestAnimationFrame(() => {
-        viewportCoordinatorRef.current.restoreElementAnchor(
-          scroller,
-          'history-window-presentation-settled',
-        );
-        viewportCoordinatorRef.current.settleElementPreservation(
-          'history-window-presentation-settled',
-        );
-        previousScrollTopRef.current = scroller.scrollTop;
-        previousMeasuredHeightRef.current = snapshotMeasuredContentHeight(scroller);
-        recordScrollerGeometry(scroller);
+    if (scroller) {
+      viewportOwner.write({
+        owner: 'follow-output',
+        topPx: readContentEndScrollTop(scroller),
+        behavior,
       });
-    });
-
-    return () => {
-      cancelAnimationFrame(firstFrameId);
-      if (secondFrameId !== null) {
-        cancelAnimationFrame(secondFrameId);
-      }
-    };
-  }, [
-    presentationMode,
-    presentationRevision,
-    recordScrollerGeometry,
-    snapshotMeasuredContentHeight,
-  ]);
-
-  useEffect(() => {
-    if (!isViewportActive || viewportGeometrySuspendedRef.current) {
-      return;
-    }
-    const wasStreaming = previousIsStreamingOutputRef.current;
-    previousIsStreamingOutputRef.current = isStreamingOutput;
-    if (!wasStreaming || isStreamingOutput) {
       return;
     }
+    scrollToContentEndThroughVirtualizer(behavior === 'smooth' ? 'smooth' : 'auto');
+  }, [readContentEndScrollTop, scrollToContentEndThroughVirtualizer, viewportOwner]);
 
-    const scroller = scrollerElementRef.current;
-
-    // Collapse compensation can be much larger than the tail space needed to
-    // keep a sticky user message pinned. Transfer it to the pin reservation in
-    // one DOM update so reducing the footer cannot temporarily remove the scroll
-    // range beneath the semantic anchor.
-    const currentReservationState = bottomReservationStateRef.current;
-    const coordinatorModeBefore = viewportCoordinatorRef.current.getMode();
-    const ownsElementAnchorBefore = viewportCoordinatorRef.current.ownsElementAnchor();
-    const collapsePx = getReservationTotalPx(currentReservationState.collapse);
-    const activeCollapseIntent = pendingCollapseIntentRef.current;
-    const retainedCollapseAnchor = retainedCollapseAnchorRef.current;
-    const collapseAnchorToRetain = activeCollapseIntent.active
-      ? activeCollapseIntent
-      : retainedCollapseAnchor;
-    const shouldRetainFollowingTailCollapse = (
-      coordinatorModeBefore === 'following-tail' &&
-      collapsePx > COMPENSATION_EPSILON_PX &&
-      collapseAnchorToRetain !== null
-    );
-    if (shouldRetainFollowingTailCollapse && collapseAnchorToRetain) {
-      retainCollapseRangeForQuietSettlement(
-        collapseAnchorToRetain,
-        'stream-end',
-      );
-    }
-    const pendingStickyPinGrowthPx = pendingStickyPinGrowthRef.current.amountPx;
-    const stickyPinTarget = (
-      currentReservationState.pin.mode === 'sticky-latest' &&
-      currentReservationState.pin.targetTurnId
-    )
-      ? currentReservationState.pin.targetTurnId
-      : null;
-    if (
-      !shouldRetainFollowingTailCollapse &&
-      (
-        collapsePx > COMPENSATION_EPSILON_PX ||
-        pendingStickyPinGrowthPx > COMPENSATION_EPSILON_PX ||
-        stickyPinTarget
-      )
-    ) {
-      const resolvedPinMetrics = scroller && stickyPinTarget
-        ? resolveTurnPinMetrics(
-          stickyPinTarget,
-          getTotalBottomCompensationPx(currentReservationState),
-        )
-        : null;
-      const requiredPinPx = resolvedPinMetrics
-        ? sanitizeReservationPx(resolvedPinMetrics.missingTailSpace)
-        : 0;
-      const nextPinReservation = stickyPinTarget && resolvedPinMetrics
-        ? {
-          ...currentReservationState.pin,
-          px: requiredPinPx,
-          floorPx: requiredPinPx,
-          mode: 'sticky-latest' as const,
-          targetTurnId: stickyPinTarget,
-        }
-        : currentReservationState.pin;
-      if (!stickyPinTarget || resolvedPinMetrics) {
-        const reconciledReservationState = transferCollapseReservationToPin(
-          currentReservationState,
-          nextPinReservation,
-        );
-        updateBottomReservationState(reconciledReservationState);
-        applyFooterCompensationNow(reconciledReservationState);
-      }
-      if (scroller && ownsElementAnchorBefore) {
-        viewportCoordinatorRef.current.restoreElementAnchor(scroller, 'stream-end-reservation-transfer');
-      }
-    }
-
-    // Stream end is an ownership boundary. Preserve the current physical range
-    // while removing the pin reservation, then release the semantic anchor so a
-    // residual floor cannot keep the coordinator alive after cancellation.
-    const shouldReleaseStreamPin = (
-      coordinatorModeBefore === 'pinned-item' ||
-      bottomReservationStateRef.current.pin.mode === 'sticky-latest'
-    );
-    if (shouldReleaseStreamPin) {
-      const releasedReservationState = releasePinReservationForUserNavigation(
-        bottomReservationStateRef.current,
-        {
-          preserveCurrentRange: true,
-          ownsElementAnchor: true,
-        },
-      );
-      if (
-        releasedReservationState.collapse.px > COMPENSATION_EPSILON_PX &&
-        collapseReservationOwnerRef.current === null
-      ) {
-        acquireCollapseReservationOwner('protected-range');
-      }
-      updateBottomReservationState(releasedReservationState);
-      applyFooterCompensationNow(releasedReservationState);
-    }
-    if (
-      coordinatorModeBefore === 'pinned-item' ||
-      (shouldReleaseStreamPin && coordinatorModeBefore === 'idle')
-    ) {
-      viewportCoordinatorRef.current.release('stream-end-pinned-item');
-    }
-
-    // Clear timer-owned work. A following-tail collapse anchor remains retained
-    // until delayed virtualizer measurements and real range consumption settle.
-    clearTurnPinRequest();
-    clearCollapseIntentScheduling();
-    clearPendingStickyPinGrowth('stream-end-reconciled');
-    pendingCollapseIntentRef.current = createInactiveCollapseIntentState();
-    if (!shouldReleaseStreamPin) {
-      viewportCoordinatorRef.current.settleElementPreservation('stream-end-reconciled');
-      maybeHandoffPinnedTurnToTailRef.current('stream-end');
-    }
-
-    if (flowChatDiagnostics.isEnabled()) {
-      flowChatDiagnostics.trace({
-        hypothesis: 'B',
-        location: 'VirtualMessageList.streamEndReconciliation',
-        message: 'Streaming viewport ownership reconciled',
-        data: () => ({
-          coordinatorModeBefore,
-          coordinatorModeAfter: viewportCoordinatorRef.current.getMode(),
-          ownsElementAnchorBefore,
-          reservationBefore: currentReservationState,
-          reservationAfter: bottomReservationStateRef.current,
-          scrollTop: scroller?.scrollTop ?? null,
-          scrollHeight: scroller?.scrollHeight ?? null,
-          clientHeight: scroller?.clientHeight ?? null,
-        }),
-      });
-    }
-
-    if (scroller) {
-      previousScrollTopRef.current = scroller.scrollTop;
-      previousMeasuredHeightRef.current = snapshotMeasuredContentHeight(
-        scroller,
-        bottomReservationStateRef.current,
-      );
-      recordScrollerGeometry(scroller);
-    }
-
-  }, [
-    applyFooterCompensationNow,
-    acquireCollapseReservationOwner,
-    clearCollapseIntentScheduling,
-    clearPendingStickyPinGrowth,
-    clearTurnPinRequest,
-    getTotalBottomCompensationPx,
-    isViewportActive,
-    isStreamingOutput,
-    recordScrollerGeometry,
-    retainCollapseRangeForQuietSettlement,
-    resolveTurnPinMetrics,
-    snapshotMeasuredContentHeight,
-    updateBottomReservationState,
-    viewportActivityRevision,
-  ]);
+  const scrollTurnToTop = useCallback((turnId: string) => {
+    const targetIndex = virtualItems.findIndex(item => (
+      item.turnId === turnId && item.type === 'user-message'
+    ));
+    if (targetIndex < 0) return false;
+    // Follow-output's answer to a new Turn, not a navigation: it is the same
+    // continuous writer, and a pin it cannot hold is not a pin.
+    virtualizer.scrollItemIntoView(targetIndex, { align: 'start', owner: 'follow-output' });
+    return true;
+  }, [virtualItems, virtualizer]);
 
-  const scrollToLatestEndPositionInternal = useCallback((behavior: 'auto' | 'smooth') => {
+  // Must agree with `scrollTurnToTop` down to the pixel: this is the offset the
+  // follow loop re-asserts every frame, so a disagreement is a fight.
+  const resolveTurnTopScrollTop = useCallback((turnId: string) => {
     const scroller = scrollerElementRef.current;
-    if (!canCoordinateViewport() || !scroller) {
-      return;
-    }
-
-    if (behavior === 'auto' && isStreamingOutputRef.current) {
-      clearPinReservationForUserNavigation();
-    }
-
-    const compensationPx = getTotalBottomCompensationPx();
-    // Auto-follow during streaming with active collapse compensation: scroll
-    // to the EFFECTIVE bottom (the top edge of the footer reservation), and
-    // preserve the reservation. Clearing it here would shrink `scrollHeight`
-    // by the full compensation amount in one frame, which clamps `scrollTop`
-    // downward and produces a visible whole-conversation "sink-down" jump.
-    // The reservation drains organically as the grow branch in
-    // `measureHeightChange` consumes it while new tokens stream in.
-    // 'smooth' is reserved for explicit user navigation ("jump to latest"),
-    // which intentionally clears reservations.
-    if (behavior === 'auto' && compensationPx > COMPENSATION_EPSILON_PX) {
-      const effectiveBottomTop = Math.max(
-        0,
-        scroller.scrollHeight - scroller.clientHeight - compensationPx,
-      );
-      // Only ever move DOWNWARD here. If `effectiveBottomTop` is above the
-      // current scrollTop (e.g. because the bottom reservation just grew to
-      // absorb an unsignaled shrink via the handleScroll auto-clamp restore),
-      // pulling scrollTop upward would itself produce a visible "sink-down"
-      // jump. Hold position; the reservation will be drained by future grow
-      // events.
-      if (effectiveBottomTop - scroller.scrollTop > COMPENSATION_EPSILON_PX) {
-        scroller.scrollTo({ top: effectiveBottomTop, behavior: 'auto' });
-      }
-      setIsAtBottom(true);
-      return;
-    }
-
-    if (behavior !== 'auto') {
-      clearAllBottomReservationsForUserNavigation();
-    }
-    scroller.scrollTo({
-      top: Math.max(0, scroller.scrollHeight - scroller.clientHeight),
-      behavior,
-    });
-    setIsAtBottom(true);
-  }, [
-    clearAllBottomReservationsForUserNavigation,
-    clearPinReservationForUserNavigation,
-    canCoordinateViewport,
-    getTotalBottomCompensationPx,
-  ]);
-
-  const requestTurnPinToTop = useCallback((turnId: string, options?: TurnPinOptions): FlowChatTurnPinRequestStatus => {
-    const requestedPinMode = options?.pinMode ?? 'transient';
-    const requestedBehavior = options?.behavior ?? 'auto';
-    const requestedAlignmentPolicy = requestedPinMode === 'sticky-latest'
-      ? 'exact'
-      : options?.alignmentPolicy ?? 'exact';
-    const targetTurn = findDialogTurn(activeSession?.dialogTurns, turnId);
-    if (requestedPinMode === 'sticky-latest' && !shouldUseStickyLatestPin(targetTurn)) {
-      return 'rejected';
-    }
-    const targetItem = userMessageItems.find(({ item }) => item.turnId === turnId);
-    if (!targetItem) {
-      return 'rejected';
-    }
-
-    // Replacing a pending navigation must invalidate its RAF/state generation,
-    // but it must not remove the footer range that keeps the current viewport
-    // physically reachable while the new target is being materialized.
-    clearTurnPinRequest();
-    retargetHistoryProjectionHandoff(turnId);
-
-    if (!canCoordinateViewport() || !virtuosoRef.current) {
-      preparedHistoryTurnPinRef.current = {
-        turnId,
-        behavior: requestedBehavior,
-        pinMode: requestedPinMode,
-        alignmentPolicy: requestedAlignmentPolicy,
-      };
-      return 'pending';
-    }
-
-    retainedCollapseAnchorRef.current = null;
-    if (requestedPinMode === 'sticky-latest' && turnId === latestTurnId) {
-      preparePinnedTurnFollowHandoffRef.current();
-    }
-    viewportCoordinatorRef.current.pinItem();
-
-    // The first turn is only deterministic after Virtuoso has materialized it.
-    // Keep it in the same materialize-then-align transaction as every other
-    // target; a loaded virtual item is not necessarily mounted in the DOM.
-
-    const requestSessionId = activeSessionIdRef.current;
-    if (!requestSessionId) {
-      return 'rejected';
-    }
-
-    const request: PendingTurnPinState = {
-      generation: turnPinRequestGenerationRef.current + 1,
-      sessionId: requestSessionId,
-      turnId,
-      behavior: requestedBehavior,
-      pinMode: requestedPinMode,
-      alignmentPolicy: requestedAlignmentPolicy,
-      expiresAtMs: performance.now() + TURN_PIN_REQUEST_TTL_MS,
-      attempts: 0,
-    };
-    turnPinRequestGenerationRef.current = request.generation;
-    activeTurnPinRequestRef.current = request;
-
-    startupTrace.markPhase('flowchat_turn_pin_request', {
-      turnId,
-      pinMode: requestedPinMode,
-      targetIndex: targetItem.index,
-      userMessageCount: userMessageItems.length,
-    });
-
-    const resolution = tryResolvePendingTurnPin(request);
-    if (resolution.kind !== 'pending') {
-      if (resolution.kind === 'best-effort' && settleBestEffortTurnPin(request)) {
-        scheduleVisibleTurnMeasure(2);
-        return 'settled';
-      }
-      if (requestedPinMode === 'transient') {
-        activateTransientTurnPinStabilization(request);
-        scheduleTransientTurnPinStabilization(2);
-      } else {
-        clearTurnPinRequest();
-      }
-      scheduleVisibleTurnMeasure(2);
-      return 'settled';
-    }
-
-    pendingTurnPinGenerationRef.current = request.generation;
-    setPendingTurnPin(request);
-    return 'pending';
-  }, [
-    activeSession?.dialogTurns,
-    activateTransientTurnPinStabilization,
-    canCoordinateViewport,
-    clearTurnPinRequest,
-    latestTurnId,
-    retargetHistoryProjectionHandoff,
-    scheduleTransientTurnPinStabilization,
-    scheduleVisibleTurnMeasure,
-    settleBestEffortTurnPin,
-    tryResolvePendingTurnPin,
-    userMessageItems,
-  ]);
-
-  useLayoutEffect(() => {
-    if (
-      !canCoordinateViewport() ||
-      !virtuosoRef.current ||
-      pendingTurnPin
-    ) {
-      return;
-    }
-
-    const preparedTurnPin = preparedHistoryTurnPinRef.current;
-    if (
-      !preparedTurnPin
-      || !userMessageItems.some(({ item }) => item.turnId === preparedTurnPin.turnId)
-    ) {
-      return;
-    }
-
-    preparedHistoryTurnPinRef.current = null;
-    requestTurnPinToTop(preparedTurnPin.turnId, {
-      behavior: preparedTurnPin.behavior,
-      pinMode: preparedTurnPin.pinMode,
-      alignmentPolicy: preparedTurnPin.alignmentPolicy,
-    });
-  }, [
-    pendingTurnPin,
-    canCoordinateViewport,
-    isViewportActive,
-    requestTurnPinToTop,
-    scrollerElement,
-    userMessageItems,
-    virtualItems.length,
-  ]);
-
-  const performAutoFollowSync = useCallback(() => {
-    if (!viewportCoordinatorRef.current.followTail()) {
-      return;
-    }
-    scrollToLatestEndPositionInternal('auto');
-  }, [scrollToLatestEndPositionInternal]);
+    const element = getRenderedUserMessageElement(turnId);
+    if (!scroller || !element) return null;
+    return Math.max(
+      0,
+      scroller.scrollTop
+        + element.getBoundingClientRect().top
+        - scroller.getBoundingClientRect().top
+        - FLOWCHAT_TURN_TOP_GAP_PX,
+    );
+  }, [getRenderedUserMessageElement]);
 
   const {
     isFollowingOutput,
     enterFollowOutput,
     exitFollowOutput,
-    preparePinnedTurnFollowHandoff,
-    armFollowOutputForNewTurn,
-    resumeFollowOutputForMountedStream,
-    activateArmedFollowOutput,
-    cancelPendingAutoFollowArm,
     scheduleFollowToLatest,
+    isFollowingOutputNow,
+    isFollowCorrectingViewport,
     handleUserScrollIntent,
-    handleScroll: handleFollowOutputScroll,
+    handleTurnsRolledBack,
+    handleScroll,
+    handleViewportResize,
+    getFollowTargetScrollTop,
   } = useFlowChatFollowOutput({
-    activeSessionId: activeSession?.sessionId,
+    activeSessionId: activeSessionId ?? undefined,
     latestTurnId,
+    dialogTurnCount: activeSession?.dialogTurns.length ?? 0,
     virtualItemCount: virtualItems.length,
     isStreaming: isStreamingOutput,
+    isViewportActive,
     scrollerRef: scrollerElementRef,
-    performUserFollowScroll: () => {
-      viewportCoordinatorRef.current.followTail({ force: true });
-      scrollToLatestEndPositionInternal('smooth');
-    },
-    performAutoFollowScroll: performAutoFollowSync,
-    performLatestTurnStickyPin: () => {
-      if (!latestTurnId) {
-        return;
-      }
-      const latestTurn = findDialogTurn(activeSession?.dialogTurns, latestTurnId);
-      if (!shouldUseStickyLatestPin(latestTurn)) {
-        return;
-      }
-      retainedCollapseAnchorRef.current = null;
-      requestTurnPinToTop(latestTurnId, {
-        behavior: 'auto',
-        pinMode: 'sticky-latest',
-      });
-    },
-    shouldSuspendAutoFollow,
-    canAnimateTailFollow: () => (
-      canProcessViewportGeometry(scrollerElementRef.current) &&
-      viewportCoordinatorRef.current.getMode() === 'following-tail' &&
-      !viewportCoordinatorRef.current.ownsElementAnchor()
-    ),
-    // Subtract the bottom-reservation footer so the follow controller treats
-    // synthetic footer space as "already at the bottom". Without this, the
-    // post-collapse footer (kept around to preserve the upper anchor) would be
-    // classified as "user fell behind the tail" and trigger
-    // `performAutoFollowScroll` -> `clearAllBottomReservationsForUserNavigation`,
-    // which snaps scrollTop down by the entire compensation amount and produces
-    // the visible "sink-down" jump the user reported. With this subtraction,
-    // the loop and the deferred-follow path stay quiet while the grow-branch in
-    // `measureHeightChange` consumes the footer organically as streaming tokens
-    // refill the bottom space.
-    getAutoFollowTargetScrollTop: (scroller) => {
-      const compensationPx = getTotalBottomCompensationPx();
-      return Math.max(
-        0,
-        scroller.scrollHeight - scroller.clientHeight - compensationPx,
-      );
-    },
-    onContinuousFollowFrame: undefined,
+    getTailSpacerPx,
+    scrollToContentEnd,
+    scrollTurnToTop,
+    resolveTurnTopScrollTop,
+    isOpeningViewport,
+    viewportOwner,
+    viewportId,
   });
-  preparePinnedTurnFollowHandoffRef.current = preparePinnedTurnFollowHandoff;
-
-  useEffect(() => {
-    if (viewportMode !== 'history-reading') {
-      return;
-    }
-    cancelPendingAutoFollowArm();
-    exitFollowOutput('pin-turn-to-top');
-  }, [cancelPendingAutoFollowArm, exitFollowOutput, viewportMode]);
 
+  /*
+   * The transcript's own lifetime, which every viewport line above is relative
+   * to. A remount resets the scroller to offset 0, empties the measurement
+   * cache and re-arms the opening reveal — so a placement that looks like it
+   * was undone is often a placement made to a scroller that no longer exists.
+   */
   useEffect(() => {
-    if (hasPrimedMountedStreamingTurnFollowRef.current) {
-      return;
-    }
-
-    if (!isStreamingOutput) {
-      hasPrimedMountedStreamingTurnFollowRef.current = true;
-      return;
-    }
-    if (!latestTurnId) {
-      return;
-    }
+    traceViewport({
+      location: 'virtualMessageList.mounted',
+      message: 'a transcript was mounted',
+      data: () => ({
+        viewportId,
+        sessionId: activeSessionIdRef.current,
+        itemCount: itemCountRef.current,
+        isViewportActive: isViewportActiveRef.current,
+      }),
+    });
+    return () => {
+      traceViewport({
+        location: 'virtualMessageList.unmounted',
+        message: 'a transcript was unmounted',
+        data: () => ({
+          viewportId,
+          sessionId: activeSessionIdRef.current,
+          itemCount: itemCountRef.current,
+          scrollTopPx: roundViewportPx(scrollerElementRef.current?.scrollTop ?? 0),
+        }),
+      });
+    };
+  }, [viewportId]);
+
+
+  /**
+   * The anchor stands down for anyone aiming at a target of their own — and for
+   * nobody else, the reader included.
+   *
+   * Its correction is a displacement repair, the same kind of act as the
+   * prepend compensation, so it asks the register the same question. Measured:
+   * with the anchor ranked under the gesture it stood down 23 times and
+   * corrected nothing at all, while the transcript shrank 200px under a reader
+   * who had not moved — and the compensation, which is a pixel delta, cannot
+   * follow a re-measurement that lands after it.
+   *
+   * The opening reveal is the one term left beside the register, because it is
+   * a phase rather than a writer and the thing moving the viewport during it is
+   * follow-output — see `flowChatViewportOwnership.ts`.
+   */
+  const isViewportOwnedElsewhere = useCallback(() => (
+    !viewportOwner.canShift() || isOpeningViewport()
+  ), [isOpeningViewport, viewportOwner]);
+
+  const shiftAnchorCorrection = useCallback((byPx: number) => {
+    viewportOwner.shift(byPx);
+  }, [viewportOwner]);
+
+  const viewportAnchor = useFlowChatViewportAnchor({
+    scrollerRef: scrollerElementRef,
+    isViewportOwnedElsewhere,
+    shiftViewport: shiftAnchorCorrection,
+  });
 
-    previousLatestTurnIdForFollowRef.current = latestTurnId;
-    hasPrimedMountedStreamingTurnFollowRef.current = resumeFollowOutputForMountedStream();
-  }, [
-    activeSession?.sessionId,
-    isStreamingOutput,
-    latestTurnId,
-    resumeFollowOutputForMountedStream,
-    virtualItems.length,
-  ]);
+  /**
+   * Keep the viewport on the same content when history is prepended.
+   *
+   * This is the half of react-virtuoso's `firstItemIndex` that nothing replaced.
+   * Keying measurements on item identity means a prepend invalidates none of
+   * them, which is the other half — but the scroll offset is still a number,
+   * and items arriving above it push the reader's content down by their height
+   * while it stays where it was.
+   *
+   * Everything downstream assumes this does not happen, and all three of the
+   * failures measured here were that assumption breaking:
+   *
+   * - The virtualizer re-windows from its own scroll offset, which lags by a
+   *   frame, so it renders the head. The paging rule reads that as the reader
+   *   having arrived at the head and pages again, and again.
+   * - The anchored Turn falls outside that window, so the anchor cannot find
+   *   its element, drops the anchor and corrects nothing — measured, 655px of
+   *   history arrived and `scrollTop` held at 23.
+   * - With the reader left at the head, the boundary never re-arms.
+   *
+   * The amount is a delta and not a total: the height of exactly the items that
+   * arrived above, read from the virtualizer's own placement of the item that
+   * used to be first. Their heights are estimates until they measure, so this
+   * lands close rather than exactly, and the anchor — which can now find its
+   * Turn — takes it the rest of the way.
+   */
+  const firstItemKeyRef = useRef<string | null>(null);
+  /**
+   * The scroll range as of the last render, so a prepend can be told what the
+   * transcript actually grew by rather than only what was reserved for it.
+   */
+  const previousScrollHeightRef = useRef(0);
+  useLayoutEffect(() => {
+    const previousFirstKey = firstItemKeyRef.current;
+    const nextFirstKey = virtualItems[0] ? getVirtualItemStableKey(virtualItems[0]) : null;
+    firstItemKeyRef.current = nextFirstKey;
 
-  useEffect(() => {
-    const previousSessionId = previousSessionIdForFollowRef.current;
-    if (previousSessionId !== activeSession?.sessionId) {
-      previousSessionIdForFollowRef.current = activeSession?.sessionId;
-      previousLatestTurnIdForFollowRef.current = latestTurnId;
-      const hasUnread = activeSession?.hasUnreadCompletion;
-      const isFinished = !isStreamingOutput;
-      if (hasUnread && isFinished && virtuosoRef.current && virtualItems.length > 0) {
-        // Use scrollToIndex instead of scrollTo({ top: largeNumber }) because
-        // Virtuoso's scrollHeight may not be stable immediately after a session
-        // switch; scrolling by index lets Virtuoso resolve the correct position.
-        const scrollToBottom = () => {
-          virtuosoRef.current?.scrollToIndex({
-            index: virtualItems.length - 1,
-            align: 'end',
-            behavior: 'auto',
-          });
+    const scroller = scrollerElementRef.current;
+    if (!scroller) return;
+    const previousScrollHeightPx = previousScrollHeightRef.current;
+    previousScrollHeightRef.current = scroller.scrollHeight;
+    if (previousFirstKey === null || previousFirstKey === nextFirstKey) return;
+    // Absent means the head was trimmed rather than extended, and there is no
+    // prepended height to account for.
+    const movedTo = virtualItems.findIndex(
+      item => getVirtualItemStableKey(item) === previousFirstKey,
+    );
+    if (movedTo <= 0) return;
+    /*
+     * The rows that arrived are already in the DOM at their real heights, and
+     * the cache still holds the estimates it reserved for them: the library
+     * skips its inline measurement while the reader is scrolling, and history
+     * arrives only then. Measuring here is the difference between a
+     * compensation derived from a guess and one derived from the layout the
+     * reader is looking at.
+     */
+    virtualizer.measureRenderedItems();
+    const arrived = virtualizer.getItemBounds(movedTo);
+    const head = virtualizer.getItemBounds(0);
+    if (!arrived || !head) return;
+    const prependedPx = arrived.startPx - head.startPx;
+    if (prependedPx <= 0) return;
+    /*
+     * A displacement, not a position, which is why it is a shift and not a
+     * write. It is left to whoever already holds a target — the follow loop
+     * re-asserting it, a navigation reaching a Turn — and to nobody else.
+     *
+     * A gesture in particular cannot refuse it. History pages in only while the
+     * reader is scrolling up into it, so routing this through the priority
+     * order refused every compensation there ever was.
+     */
+    const fromPx = scroller.scrollTop;
+    /*
+     * Three bounds on how far the reader has to move, and the smallest wins.
+     *
+     * Each is an upper bound on the true amount, and they fail in different
+     * directions, so the smallest is the only one that cannot overshoot:
+     *
+     * - `prependedPx` is what the virtualizer *reserved* for the items that
+     *   arrived. It over-states while they are estimates, and they are
+     *   estimates exactly when this runs: the DOM has already rendered them at
+     *   their real heights, and the measurement cache has not heard yet.
+     *   Measured, twice in one session: 2174px reserved against 670px of real
+     *   growth, then 2494px against 949px.
+     * - `scrollRangeGrowthPx` is what the scroll range actually gained, which
+     *   is the DOM's own answer. It over-states only if the transcript also
+     *   grew below the reader in the same commit.
+     * - What the range can absorb before the reader is inside the reserved
+     *   blank. Content arriving above them cannot push them past the end of the
+     *   transcript, so needing more than this is proof the amount is wrong.
+     *
+     * Overshooting is the expensive direction: it puts the reader below the
+     * content end, inside the reserved blank. Undershooting leaves
+     * them looking at slightly earlier content, which the anchor removes.
+     */
+    const contentEndPx = readContentEndScrollTop(scroller);
+    const scrollRangeGrowthPx = scroller.scrollHeight - previousScrollHeightPx;
+    const shiftedPx = Math.max(0, Math.min(
+      prependedPx,
+      scrollRangeGrowthPx,
+      contentEndPx - fromPx,
+    ));
+    const compensated = shiftedPx > 0 && viewportOwner.shift(shiftedPx);
+    /*
+     * This one movement is made on the anchor's behalf, so it is the one it
+     * must not read as the reader having scrolled. Everything else that changes
+     * `scrollTop` between two of its corrections is somebody's deliberate
+     * movement, and the anchor is right to leave those alone.
+     */
+    if (compensated) viewportAnchor.absorbViewportShift(shiftedPx);
+    /*
+     * A refusal leaves the displacement to whoever holds a target — so make
+     * sure they are awake to take it.
+     *
+     * Follow-output is the only holder that can be asleep. Its ownership
+     * deliberately outlives its frame loop, so that streaming can resume
+     * without re-entering, and the loop stops on its own once the transcript
+     * settles; a navigation's aim is still running by construction. So a page
+     * landing after the settle budget ran
+     * out is refused by a writer that will never act, and the reader is left
+     * holding an offset that now means something else.
+     *
+     * Measured, from the fault this was found in: 22301px of history arrived
+     * above a viewport at 0, the shift was refused with `heldBy:
+     * follow-output`, and nothing moved for the rest of the session — the
+     * transcript was revealed at the top of the window, eight Turns above the
+     * tail. Re-asserting is idempotent when the loop *is* running: it aims at
+     * the offset the follow rule already owns.
+     */
+    const wokeFollowOutput = !compensated
+      && shiftedPx > 0
+      && viewportOwner.currentOwner() === 'follow-output';
+    if (wokeFollowOutput) scheduleFollowToLatest();
+    /*
+     * Both amounts, because their disagreement is the diagnosis. `prependedPx`
+     * against what the scroll range actually grew by says how far the cache is
+     * ahead of the DOM; against `shiftedPx` it says how much of the
+     * compensation had to be given up, which is what the reader feels as a
+     * jump that the anchor then has to finish undoing.
+     */
+    traceViewport({
+      location: 'virtualMessageList.prependCompensated',
+      message: 'history arrived above the reader',
+      data: () => {
+        const followTargetPx = getFollowTargetScrollTop();
+        return {
+          viewportId,
+          compensated,
+          prependedPx: roundViewportPx(prependedPx),
+          shiftedPx: roundViewportPx(shiftedPx),
+          scrollRangeGrowthPx: roundViewportPx(scrollRangeGrowthPx),
+          itemsAbove: movedTo,
+          fromPx: roundViewportPx(fromPx),
+          contentEndPx: roundViewportPx(contentEndPx),
+          scrollTopPx: roundViewportPx(scroller.scrollTop),
+          /*
+           * Who the displacement was left to, and where they are taking it.
+           * A refused shift is only correct if the holder then places the
+           * reader itself; read after the re-assertion above, so `null` here
+           * with `wokeFollowOutput` true is a holder that could not be woken —
+           * the register believes someone owns the viewport and the follow rule
+           * believes it is not following, which is the one state nothing can
+           * recover from on its own.
+           */
+          followTargetPx: followTargetPx === null ? null : roundViewportPx(followTargetPx),
+          wokeFollowOutput,
+          isOpening: isOpeningViewport(),
+          // The baseline every later `anchor.correct` in this settle is read
+          // against: a correction that arrives with the range unchanged is a
+          // compensation that over-shot, and one that arrives with the range
+          // smaller is the transcript above the reader measuring down.
+          scrollRangePx: roundViewportPx(scroller.scrollHeight),
+          presentationMode,
         };
-        // Allow two frames for virtual items to settle before scrolling.
-        requestAnimationFrame(() => {
-          requestAnimationFrame(scrollToBottom);
-        });
-      }
-
-      // When switching to a streaming session, resume tail follow so the
-      // viewport tracks new content as it arrives. Without this, the
-      // Virtuoso stays at initialTopMostItemIndex (the user message),
-      // and if that position is not yet rendered or measured the
-      // viewport may show blank space.
-      if (isStreamingOutput) {
-        hasPrimedMountedStreamingTurnFollowRef.current = resumeFollowOutputForMountedStream();
-      }
-
-      return;
-    }
-
-    const previousLatestTurnId = previousLatestTurnIdForFollowRef.current;
-    if (previousLatestTurnId === latestTurnId) {
-      return;
-    }
-
-    previousLatestTurnIdForFollowRef.current = latestTurnId;
-
-    if (!latestTurnId) {
-      cancelPendingAutoFollowArm();
-      return;
-    }
-
-    armFollowOutputForNewTurn();
+      },
+    });
   }, [
-    activeSession?.sessionId,
-    activeSession?.hasUnreadCompletion,
-    armFollowOutputForNewTurn,
-    cancelPendingAutoFollowArm,
-    isStreamingOutput,
-    latestTurnId,
-    resumeFollowOutputForMountedStream,
-    virtualItems.length,
+    getFollowTargetScrollTop,
+    isOpeningViewport,
+    presentationMode,
+    readContentEndScrollTop,
+    scheduleFollowToLatest,
+    viewportAnchor,
+    viewportId,
+    viewportOwner,
+    virtualItems,
+    virtualizer,
   ]);
 
-  const maybeHandoffPinnedTurnToTail = useCallback((reason: string) => {
-    if (
-      !latestTurnId ||
-      isFollowingOutput ||
-      !canProcessViewportGeometry(scrollerElementRef.current)
-    ) {
-      return false;
-    }
-
-    const hasPendingLatestStickyPin = (
-      pendingTurnPin?.turnId === latestTurnId &&
-      pendingTurnPin.pinMode === 'sticky-latest'
-    );
-    if (hasPendingLatestStickyPin) {
-      return false;
-    }
-
-    const reservationState = bottomReservationStateRef.current;
-    if (
-      reservationState.pin.mode !== 'sticky-latest' ||
-      reservationState.pin.targetTurnId !== latestTurnId
-    ) {
-      return false;
-    }
-
-    const collapseIntent = pendingCollapseIntentRef.current;
-    const hasPendingCollapseIntent = (
-      collapseIntent.active
-    );
-    const pendingStickyPinGrowthPx = pendingStickyPinGrowthRef.current.amountPx;
-    const scroller = scrollerElementRef.current;
-    const viewport = scroller
-      ? {
-        scrollTop: scroller.scrollTop,
-        clientHeight: scroller.clientHeight,
-        naturalContentHeight: snapshotMeasuredContentHeight(scroller, reservationState),
-      }
-      : null;
-    if (!canHandoffPinnedItemToTail({
-      pinReservationPx: reservationState.pin.px,
-      collapseReservationPx: reservationState.collapse.px,
-      pendingStickyPinGrowthPx,
-      hasPendingCollapseIntent,
-      viewport,
-    })) {
-      if (flowChatDiagnostics.isEnabled()) {
-        flowChatDiagnostics.trace({
-          hypothesis: 'A',
-          location: 'VirtualMessageList.maybeHandoffPinnedTurnToTail',
-          message: 'Pinned item to tail handoff remained blocked',
-          data: () => ({
-            reason,
-            reservation: reservationState,
-            pendingStickyPinGrowthPx,
-            hasPendingCollapseIntent,
-            viewport,
-            coordinatorMode: viewportCoordinatorRef.current.getMode(),
-          }),
-        });
-      }
-      return false;
-    }
-
-    if (activateArmedFollowOutput()) {
-      if (flowChatDiagnostics.isEnabled()) {
-        flowChatDiagnostics.trace({
-          hypothesis: 'A',
-          location: 'VirtualMessageList.maybeHandoffPinnedTurnToTail',
-          message: 'Pinned item handed off to tail follow',
-          data: () => ({
-            reason,
-            reservation: reservationState,
-            pendingStickyPinGrowthPx,
-            viewport,
-          }),
-        });
-      }
-      return true;
-    }
-    return false;
+  useLayoutEffect(() => {
+    viewportAnchor.openSettleWindow();
+  }, [viewportAnchor, virtualItems]);
+
+  const notifyUserScrollIntent = useCallback(() => {
+    /*
+     * The reader outranks everything, and the claim is what makes that true of
+     * writers that are already in flight rather than only of ones yet to
+     * start. It lapses on its own after the same window the anchor uses to
+     * decide a scroll was theirs — a gesture has no completion event, so the
+     * hold has to end by itself or nothing below it could ever write again.
+     */
+    viewportOwner.claim('user-gesture', { holdForMs: USER_DRIVEN_SCROLL_WINDOW_MS });
+    /*
+     * The claim alone does not reach the library's re-aim. It goes on
+     * recomputing its target for five seconds and writes again whenever a
+     * measurement moves it, and the claim only refuses those writes while the
+     * gesture's own hold is live — 200ms after the last wheel notch, against a
+     * five-second re-aim. Measured: a Turn navigation placed at 5358, the
+     * reader took over 6ms later, and 12ms after that the re-aim asked for
+     * 7784 and was refused. Nothing had ended it; it was still armed when the
+     * recording stopped.
+     */
+    virtualizer.cancelAim();
+    viewportAnchor.markUserScrollIntent();
+    handleUserScrollIntent();
+    onUserScrollIntent?.();
+    /*
+     * A gesture that moves nothing is still the reader asking to go up, and it
+     * is the only signal there is once they are already at the top: the wheel
+     * emits no `scroll` event when the offset cannot change, so the scroll
+     * handler's evaluation never runs.
+     *
+     * Measured on a tail window of three Turns that fitted inside the viewport,
+     * so the whole scroll range was reserved blank: twenty gestures over seven
+     * seconds produced twenty `user-gesture` claims, no scroll events, and not
+     * one boundary evaluation. Nothing could ever page.
+     *
+     * After `handleUserScrollIntent`, which clears follow-output's ownership
+     * synchronously — so this asks as the reader rather than as our placement.
+     */
+    evaluateHistoryBoundariesRef.current();
   }, [
-    activateArmedFollowOutput,
-    canProcessViewportGeometry,
-    isFollowingOutput,
-    latestTurnId,
-    pendingTurnPin?.pinMode,
-    pendingTurnPin?.turnId,
-    snapshotMeasuredContentHeight,
+    handleUserScrollIntent,
+    onUserScrollIntent,
+    viewportAnchor,
+    viewportOwner,
+    virtualizer,
   ]);
-  maybeHandoffPinnedTurnToTailRef.current = maybeHandoffPinnedTurnToTail;
-
-  useLayoutEffect(() => {
-    const generation = viewportActivityGenerationRef.current + 1;
-    viewportActivityGenerationRef.current = generation;
 
-    if (!isViewportActive) {
-      const scroller = scrollerElementRef.current;
-      if (
-        scroller?.isConnected &&
-        scroller.clientHeight > COMPENSATION_EPSILON_PX
-      ) {
-        suspendedViewportScrollTopRef.current = scroller.scrollTop;
-      } else {
-        suspendedViewportScrollTopRef.current = previousScrollTopRef.current;
-      }
-
-      viewportGeometrySuspendedRef.current = true;
-
-      const outstandingPinRequest = activeTurnPinRequestRef.current ?? pendingTurnPin;
-      if (outstandingPinRequest) {
-        preparedHistoryTurnPinRef.current = {
-          turnId: outstandingPinRequest.turnId,
-          behavior: 'auto',
-          pinMode: outstandingPinRequest.pinMode,
-          alignmentPolicy: outstandingPinRequest.alignmentPolicy,
-        };
-        clearTurnPinRequest();
-      }
-
-      cancelLatestEndAnchorStabilization();
-      clearCollapseIntentScheduling();
-      clearRetainedCollapseSettlement();
-      clearPendingStickyPinGrowth('viewport-suspended');
-      pendingCollapseIntentRef.current = createInactiveCollapseIntentState();
-      retainedCollapseAnchorRef.current = null;
-
-      [
-        measureFrameRef,
-        visibleTurnMeasureFrameRef,
-        pinReservationReconcileFrameRef,
-        turnPinStabilizationFrameRef,
-        fullHistoryProjectionIntentFrameRef,
-      ].forEach(frameRef => {
-        if (frameRef.current !== null) {
-          cancelAnimationFrame(frameRef.current);
-          frameRef.current = null;
-        }
-      });
-      pendingFullHistoryProjectionReasonRef.current = null;
-      return;
-    }
+  const updateVisibleTurnInfoFromViewport = useCallback(() => {
+    const scroller = scrollerElementRef.current;
+    if (!scroller) return;
+    const scrollerRect = scroller.getBoundingClientRect();
+    const viewportEntries = Array.from(
+      scroller.querySelectorAll<HTMLElement>('.virtual-item-wrapper[data-turn-id]'),
+    ).map(element => {
+      const rect = element.getBoundingClientRect();
+      return {
+        turnId: element.dataset.turnId ?? null,
+        itemType: element.dataset.itemType ?? null,
+        top: rect.top,
+        bottom: rect.bottom,
+      };
+    });
+    const visibleTurnIds = resolveVisibleFlowChatTurnIds(
+      viewportEntries,
+      scrollerRect.top,
+      scrollerRect.bottom,
+    );
+    const currentTurnId = visibleTurnIds[0] ?? null;
+    const currentTurn = currentTurnId
+      ? userMessageItems.find(({ item }) => item.turnId === currentTurnId)
+      : undefined;
+    const store = useModernFlowChatStore.getState();
 
-    if (!viewportGeometrySuspendedRef.current) {
+    if (!currentTurn || currentTurn.item.type !== 'user-message') {
+      if (store.visibleTurnInfo !== null) store.setVisibleTurnInfo(null);
       return;
     }
 
-    const restoreVisibleViewport = () => {
-      viewportReactivationFrameRef.current = null;
-      if (
-        generation !== viewportActivityGenerationRef.current ||
-        !isViewportActiveRef.current
-      ) {
-        return;
-      }
-
-      const scroller = scrollerElementRef.current;
-      if (!isScrollerViewportMeasurable(scroller)) {
-        viewportReactivationFrameRef.current = requestAnimationFrame(restoreVisibleViewport);
-        return;
-      }
-
-      viewportGeometrySuspendedRef.current = false;
-
-      clearCollapseIntentScheduling();
-      clearRetainedCollapseSettlement();
-      clearPendingStickyPinGrowth('viewport-reactivated');
-      pendingCollapseIntentRef.current = createInactiveCollapseIntentState();
-      retainedCollapseAnchorRef.current = null;
-
-      const currentState = bottomReservationStateRef.current;
-      let nextState: BottomReservationState = {
-        ...currentState,
-        collapse: {
-          kind: 'collapse',
-          px: 0,
-          floorPx: 0,
-        },
-      };
-      let stickyPinMetrics: ReturnType<typeof resolveTurnPinMetrics> = null;
-      const stickyPinTarget = (
-        currentState.pin.mode === 'sticky-latest' &&
-        currentState.pin.targetTurnId
-      )
-        ? currentState.pin.targetTurnId
-        : null;
-      if (stickyPinTarget) {
-        stickyPinMetrics = resolveTurnPinMetrics(
-          stickyPinTarget,
-          getTotalBottomCompensationPx(currentState),
-        );
-        if (stickyPinMetrics) {
-          const requiredPinPx = clampPinReservationPxToViewport(
-            stickyPinMetrics.missingTailSpace,
-            scroller.clientHeight,
-          );
-          nextState = {
-            ...nextState,
-            pin: {
-              kind: 'pin',
-              px: requiredPinPx,
-              floorPx: requiredPinPx,
-              mode: 'sticky-latest',
-              targetTurnId: stickyPinTarget,
-            },
-          };
-        }
-      }
+    const nextVisibleTurnInfo = {
+      turnIndex: userMessageItems.indexOf(currentTurn) + 1,
+      totalTurns: userMessageItems.length,
+      userMessage: currentTurn.item.data.content ?? '',
+      turnId: currentTurn.item.turnId,
+      visibleTurnIds,
+    };
+    const previous = store.visibleTurnInfo;
+    const unchanged = previous?.turnId === nextVisibleTurnInfo.turnId
+      && previous.turnIndex === nextVisibleTurnInfo.turnIndex
+      && previous.totalTurns === nextVisibleTurnInfo.totalTurns
+      && previous.userMessage === nextVisibleTurnInfo.userMessage
+      && previous.visibleTurnIds.length === visibleTurnIds.length
+      && previous.visibleTurnIds.every((turnId, index) => turnId === visibleTurnIds[index]);
+    if (!unchanged) store.setVisibleTurnInfo(nextVisibleTurnInfo);
+  }, [userMessageItems]);
 
-      updateBottomReservationState(nextState);
-      applyFooterCompensationNow(nextState);
+  const scheduleVisibleTurnInfoUpdate = useCallback(() => {
+    if (visibleTurnUpdateFrameRef.current !== null) return;
+    visibleTurnUpdateFrameRef.current = requestAnimationFrame(() => {
+      visibleTurnUpdateFrameRef.current = null;
+      updateVisibleTurnInfoFromViewport();
+    });
+  }, [updateVisibleTurnInfoFromViewport]);
 
-      if (stickyPinTarget && stickyPinMetrics) {
-        viewportCoordinatorRef.current.pinItem('viewport-reactivated-sticky-pin');
-        const maxScrollTop = Math.max(0, scroller.scrollHeight - scroller.clientHeight);
-        scroller.scrollTop = Math.min(stickyPinMetrics.desiredScrollTop, maxScrollTop);
-      } else if (isFollowingOutputRef.current && isStreamingOutputRef.current) {
-        viewportCoordinatorRef.current.followTail({ force: true });
-        scrollToLatestEndPositionInternal('auto');
-      } else if (viewportCoordinatorRef.current.ownsElementAnchor()) {
-        viewportCoordinatorRef.current.restoreElementAnchor(scroller, 'viewport-reactivated');
-      } else {
-        const maxScrollTop = Math.max(0, scroller.scrollHeight - scroller.clientHeight);
-        scroller.scrollTop = Math.min(suspendedViewportScrollTopRef.current, maxScrollTop);
-      }
+  useEffect(() => () => {
+    if (visibleTurnUpdateFrameRef.current !== null) {
+      cancelAnimationFrame(visibleTurnUpdateFrameRef.current);
+      visibleTurnUpdateFrameRef.current = null;
+    }
+  }, []);
 
-      previousMeasuredHeightRef.current = snapshotMeasuredContentHeight(
-        scroller,
-        bottomReservationStateRef.current,
+  /*
+   * Opening reveal.
+   *
+   * A session mounts against an unmeasured transcript: for the first frames the
+   * real content is a few hundred pixels of estimate, so the end of content
+   * genuinely *is* the top, and the settle then walks the viewport down as items
+   * measure and history pages in. Every step of that walk is correct and every
+   * step is visible, which reads as a flash. Hold the transcript hidden — laid
+   * out and measurable, just not painted — until it stops moving.
+   */
+  useLayoutEffect(() => {
+    if (!scrollerElement || isOpenViewportSettled) return;
+
+    let frame = 0;
+    let quietFrames = 0;
+    let rafId: number | null = null;
+    const lastVirtualIndex = virtualItems.length - 1;
+
+    const check = () => {
+      frame += 1;
+      /*
+       * Geometry stability is not a settle signal on its own: before the virtualizer
+       * renders anything, `scrollHeight` and the content end sit unchanged at
+       * their unmeasured values, which is indistinguishable from having
+       * finished. Require the last item to actually be rendered with its end
+       * inside the viewport — that is the thing the reveal is waiting for.
+       */
+      const lastItem = scrollerElement.querySelector<HTMLElement>(
+        `.virtual-item-wrapper[data-virtual-index="${lastVirtualIndex}"]`,
       );
-      previousScrollTopRef.current = scroller.scrollTop;
-      recordScrollerGeometry(scroller);
-      setViewportActivityRevision(revision => revision + 1);
-
-      const preparedTurnPin = preparedHistoryTurnPinRef.current;
-      if (
-        preparedTurnPin &&
-        userMessageItems.some(({ item }) => item.turnId === preparedTurnPin.turnId)
-      ) {
-        preparedHistoryTurnPinRef.current = null;
-        requestTurnPinToTop(preparedTurnPin.turnId, {
-          behavior: 'auto',
-          pinMode: preparedTurnPin.pinMode,
-          alignmentPolicy: preparedTurnPin.alignmentPolicy,
+      const contentEnd = readContentEndScrollTop(scrollerElement);
+      const inPosition = Math.abs(scrollerElement.scrollTop - contentEnd) <= AT_CONTENT_END_THRESHOLD_PX;
+      const tailVisible = lastItem !== null
+        && lastItem.getBoundingClientRect().bottom
+          <= scrollerElement.getBoundingClientRect().bottom + AT_CONTENT_END_THRESHOLD_PX;
+      quietFrames = tailVisible && inPosition ? quietFrames + 1 : 0;
+
+      if (quietFrames >= OPEN_REVEAL_QUIET_FRAMES || frame >= OPEN_REVEAL_MAX_FRAMES) {
+        /*
+         * Revealed on the frame cap rather than on quiet means the transcript
+         * was still moving when it became visible, which is what the reader
+         * reports as the session flickering on open.
+         */
+        traceViewport({
+          location: 'virtualMessageList.openReveal',
+          message: 'transcript revealed',
+          data: () => {
+            const followTargetPx = getFollowTargetScrollTop();
+            return {
+              viewportId,
+              settled: quietFrames >= OPEN_REVEAL_QUIET_FRAMES,
+              frames: frame,
+              itemCount: virtualItems.length,
+              scrollTopPx: roundViewportPx(scrollerElement.scrollTop),
+              contentEndPx: roundViewportPx(readContentEndScrollTop(scrollerElement)),
+              /*
+               * Revealed away from the content end is the reader's "it opened
+               * on the wrong Turn", and these two say whose it is: a follow
+               * that owns a target it has not reached is a placement still on
+               * its way, and no target at all is nobody having taken the
+               * transcript on open.
+               */
+              followTargetPx: followTargetPx === null ? null : roundViewportPx(followTargetPx),
+              isFollowCorrecting: isFollowCorrectingViewport(),
+            };
+          },
         });
+        setIsOpenViewportSettled(true);
+        return;
       }
-
-      scheduleHeightMeasure(2);
-      scheduleVisibleTurnMeasure(2);
-      schedulePinReservationReconcile(2);
-      scheduleTransientTurnPinStabilization(2);
-      maybeHandoffPinnedTurnToTailRef.current('viewport-reactivated');
-      if (isFollowingOutputRef.current && isStreamingOutputRef.current) {
-        scheduleFollowToLatestWithViewportState('viewport-reactivated');
-      }
+      rafId = requestAnimationFrame(check);
     };
+    rafId = requestAnimationFrame(check);
 
-    viewportReactivationFrameRef.current = requestAnimationFrame(restoreVisibleViewport);
     return () => {
-      if (viewportReactivationFrameRef.current !== null) {
-        cancelAnimationFrame(viewportReactivationFrameRef.current);
-        viewportReactivationFrameRef.current = null;
-      }
+      if (rafId !== null) cancelAnimationFrame(rafId);
     };
   }, [
-    applyFooterCompensationNow,
-    cancelLatestEndAnchorStabilization,
-    clearCollapseIntentScheduling,
-    clearPendingStickyPinGrowth,
-    clearRetainedCollapseSettlement,
-    clearTurnPinRequest,
-    getTotalBottomCompensationPx,
-    isScrollerViewportMeasurable,
-    isViewportActive,
-    pendingTurnPin,
-    recordScrollerGeometry,
-    requestTurnPinToTop,
-    resolveTurnPinMetrics,
-    scheduleFollowToLatestWithViewportState,
-    scheduleHeightMeasure,
-    schedulePinReservationReconcile,
-    scheduleTransientTurnPinStabilization,
-    scheduleVisibleTurnMeasure,
-    scrollToLatestEndPositionInternal,
-    snapshotMeasuredContentHeight,
-    updateBottomReservationState,
-    userMessageItems,
+    getFollowTargetScrollTop,
+    isFollowCorrectingViewport,
+    isOpenViewportSettled,
+    readContentEndScrollTop,
+    scrollerElement,
+    viewportId,
+    virtualItems.length,
   ]);
 
+  /*
+   * "At the bottom" is a band, not a point. Its upper edge is the end of real
+   * content and its lower edge is whatever the follow rule owns, so a pinned
+   * Turn and a held collapse gap both count as being at the end — neither is a
+   * reason to offer a jump to the latest output. Below the band is reserved
+   * blank, which is: without the lower edge, parking a viewport deep in the
+   * spacer read as "at the bottom" and hid the only way back.
+   */
+  const updateIsAtBottom = useCallback(() => {
+    const scroller = scrollerElementRef.current;
+    if (!scroller) return;
+    const contentEnd = readContentEndScrollTop(scroller);
+    /*
+     * A follow still travelling counts as being at the end.
+     *
+     * The follow's write is eased, so it rides a little behind the offset it
+     * owns by design, and what it is behind is arriving on its own. Judged on
+     * the raw offset, a burst of two or three lines drops the viewport out of
+     * the band for a few frames and flashes the jump-to-latest bar over a
+     * transcript that is already following the newest output — and clicking it
+     * would have nothing to do. Ownership alone cannot stand in for this: it
+     * outlives the frame loop, which is exactly the state a viewport stranded
+     * in the reserved blank is in.
+     */
+    const atTail = isFollowCorrectingViewport() || isViewportAtTail({
+      scrollTop: scroller.scrollTop,
+      contentEndScrollTop: contentEnd,
+      // Nothing owns an offset outside follow, so the band collapses onto the
+      // content end.
+      followTargetScrollTop: getFollowTargetScrollTop() ?? contentEnd,
+      thresholdPx: AT_CONTENT_END_THRESHOLD_PX,
+    });
+    // Mirrored to a ref because a resize needs the answer from before it, and
+    // the state update does not land until the next render.
+    isAtTailRef.current = atTail;
+    setIsAtBottom(atTail);
+  }, [getFollowTargetScrollTop, isFollowCorrectingViewport, readContentEndScrollTop]);
+
+  /*
+   * The band's lower edge is whatever the follow rule owns, so it moves when
+   * ownership changes — and that can happen with the viewport perfectly still.
+   * A jump to latest that lands on a pin the viewport is already on writes
+   * nothing. That produces no scroll event, so without this the affordance
+   * stays as the last scroll
+   * left it: visible, over a viewport that is already at the tail, and inert
+   * because clicking it has nothing left to do.
+   */
   useEffect(() => {
-    maybeHandoffPinnedTurnToTail('reservation-state-change');
-  }, [
-    bottomReservationState.collapse.px,
-    bottomReservationState.pin.floorPx,
-    bottomReservationState.pin.mode,
-    bottomReservationState.pin.px,
-    bottomReservationState.pin.targetTurnId,
-    isStreamingOutput,
-    maybeHandoffPinnedTurnToTail,
-  ]);
-
-  followOutputControllerRef.current = {
-    handleUserScrollIntent,
-    handleScroll: handleFollowOutputScroll,
-    scheduleFollowToLatest,
-  };
-  isFollowingOutputRef.current = isFollowingOutput;
-  isStreamingOutputRef.current = isStreamingOutput;
+    updateIsAtBottom();
+  }, [isFollowingOutput, updateIsAtBottom]);
+
+  /*
+   * A rollback removed Turns from the session, so the transcript ends somewhere
+   * it did not a moment ago — and the Turn follow-output was pinning may be one
+   * of the ones that stopped existing. The follow rule settles on the new tail;
+   * it declines for a reader who owns the viewport, which is the case when the
+   * rollback came from the middle of a transcript they were reading.
+   */
+  useEffect(() => {
+    const handleTurnsRolledBackEvent = (event: Event) => {
+      const detail = (event as CustomEvent<FlowChatTurnsRolledBackRequest>).detail;
+      if (!detail?.sessionId || detail.sessionId !== activeSessionId) return;
+      handleTurnsRolledBack();
+    };
+    window.addEventListener(FLOWCHAT_TURNS_ROLLED_BACK_EVENT, handleTurnsRolledBackEvent);
+    return () => {
+      window.removeEventListener(FLOWCHAT_TURNS_ROLLED_BACK_EVENT, handleTurnsRolledBackEvent);
+    };
+  }, [activeSessionId, handleTurnsRolledBack]);
 
   useEffect(() => {
-    if (flowChatDiagnostics.isEnabled()) {
-      flowChatDiagnostics.trace({
-        hypothesis: 'D',
-        location: 'VirtualMessageList.followOutputEffect',
-        message: 'Follow output state synchronized with the viewport coordinator',
-        data: () => ({
-          isFollowingOutput,
-          isStreamingOutput,
-          coordinatorMode: viewportCoordinatorRef.current.getMode(),
-          reservation: bottomReservationStateRef.current,
-        }),
-      });
-    }
-    const coordinatorMode = viewportCoordinatorRef.current.getMode();
-    if (isFollowingOutput && coordinatorMode === 'pinned-item') {
-      const pinReservation = bottomReservationStateRef.current.pin;
-      const isPendingLatestStickyPin = (
-        pendingTurnPin?.pinMode === 'sticky-latest' &&
-        pendingTurnPin.turnId === latestTurnId
-      );
-      if (
-        (
-          pinReservation.mode === 'sticky-latest' &&
-          pinReservation.targetTurnId === latestTurnId
-        ) || isPendingLatestStickyPin
-      ) {
-        // React effects may still carry the previous render's follow value
-        // after a synchronous sticky-pin request. Repair the logical state
-        // without dropping the armed handoff.
-        preparePinnedTurnFollowHandoff();
-      } else {
-        exitFollowOutput('pin-turn-to-top');
+    if (!scrollerElement) return;
+    const handleNativeScroll = () => {
+      /*
+       * A scroll under a scrollbar press is the one case where a plain scroll
+       * event does carry intent — the press is what qualifies it. Left
+       * unqualified, a drag never released the viewport: follow-output kept
+       * writing its target every frame against the thumb (measured: a 100px
+       * oscillation, every frame, for as long as the drag lasted). Recognising
+       * the drag transfers ownership to the reader and preserves where it ends.
+       */
+      if (isScrollbarPressRef.current) notifyUserScrollIntent();
+      updateIsAtBottom();
+      handleScroll();
+      /*
+       * Re-anchor to wherever the user has arrived, and only there. The rule
+       * for "was this scroll the user's" lives with the anchor.
+       */
+      viewportAnchor.captureAnchorForScroll();
+      scheduleVisibleTurnInfoUpdate();
+      /*
+       * Paging is a question about where the reader is, so a scroll is its
+       * primary input. Through a ref: this listener must not be torn down and
+       * re-attached every time the transcript changes.
+       */
+      evaluateHistoryBoundariesRef.current();
+    };
+    const handleWheel = () => notifyUserScrollIntent();
+    const handleTouchMove = () => notifyUserScrollIntent();
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (['ArrowUp', 'ArrowDown', 'PageUp', 'PageDown', 'Home', 'End', ' '].includes(event.key)) {
+        notifyUserScrollIntent();
       }
-      return;
-    }
-    if (isFollowingOutput) {
-      viewportCoordinatorRef.current.followTail({ force: true });
-      return;
-    }
-    if (coordinatorMode === 'following-tail') {
-      viewportCoordinatorRef.current.release('follow-ended');
-    }
+    };
+    /*
+     * Arming rather than releasing outright: `scrollbar-gutter: stable` keeps
+     * the gutter reserved whether or not a bar is drawn in it, so a press there
+     * is only intent once something actually scrolls. A click on the thumb that
+     * moves nothing leaves the viewport where it was.
+     */
+    const handlePointerDown = (event: PointerEvent) => {
+      isScrollbarPressRef.current = isScrollbarPress(event, scrollerElement);
+    };
+    const handlePointerRelease = () => {
+      isScrollbarPressRef.current = false;
+    };
+    scrollerElement.addEventListener('scroll', handleNativeScroll, { passive: true });
+    scrollerElement.addEventListener('wheel', handleWheel, { passive: true });
+    scrollerElement.addEventListener('touchmove', handleTouchMove, { passive: true });
+    scrollerElement.addEventListener('keydown', handleKeyDown);
+    scrollerElement.addEventListener('pointerdown', handlePointerDown, { passive: true });
+    // On the window: a drag can be released anywhere, including outside it.
+    window.addEventListener('pointerup', handlePointerRelease, { passive: true });
+    window.addEventListener('pointercancel', handlePointerRelease, { passive: true });
+    return () => {
+      scrollerElement.removeEventListener('scroll', handleNativeScroll);
+      scrollerElement.removeEventListener('wheel', handleWheel);
+      scrollerElement.removeEventListener('touchmove', handleTouchMove);
+      scrollerElement.removeEventListener('keydown', handleKeyDown);
+      scrollerElement.removeEventListener('pointerdown', handlePointerDown);
+      window.removeEventListener('pointerup', handlePointerRelease);
+      window.removeEventListener('pointercancel', handlePointerRelease);
+    };
   }, [
-    exitFollowOutput,
-    isFollowingOutput,
-    isStreamingOutput,
-    latestTurnId,
-    pendingTurnPin?.pinMode,
-    pendingTurnPin?.turnId,
-    preparePinnedTurnFollowHandoff,
+    handleScroll,
+    notifyUserScrollIntent,
+    scheduleVisibleTurnInfoUpdate,
+    scrollerElement,
+    updateIsAtBottom,
+    viewportAnchor,
   ]);
 
-  // When entering follow-output during streaming, end any active protection
-  // window but keep its reservation. Once the intent is inactive, real content
-  // growth can consume that range without exposing a one-frame shrink.
-  const previousIsFollowingOutputRef = useRef(false);
   useEffect(() => {
-    if (!previousIsFollowingOutputRef.current && isFollowingOutput && isStreamingOutput) {
-      const intent = pendingCollapseIntentRef.current;
-      if (intent.active) {
-        finalizeCollapseIntent('follow-output-entered', {
-          expectedExpiresAtMs: intent.expiresAtMs,
-          suppressHandoff: true,
+    if (!scrollerElement) return;
+    const observer = new ResizeObserver(() => {
+      const nextViewportBox = {
+        width: scrollerElement.clientWidth,
+        height: scrollerElement.clientHeight,
+      };
+      /*
+       * This observer watches the content too. Content growth moves the follow
+       * target away from a resting viewport and can never strand it, so only a
+       * change to the scroller's own box opens the re-alignment window — a
+       * width change reflows the transcript, a height change moves the content
+       * end directly, and both keep settling for a few callbacks afterwards.
+       */
+      const previousViewportBox = observedViewportBoxRef.current;
+      const viewportBoxChanged = nextViewportBox.width !== previousViewportBox.width
+        || nextViewportBox.height !== previousViewportBox.height;
+      if (viewportBoxChanged) {
+        observedViewportBoxRef.current = nextViewportBox;
+        tailRealignCallbacksRef.current = TAIL_REALIGN_RESIZE_CALLBACKS;
+      }
+      setViewportHeightPx(nextViewportBox.height);
+      setViewportWidthPx(nextViewportBox.width);
+
+      /*
+       * Before paint, and ahead of everything below: this observer is the one
+       * callback the browser delivers between the transcript changing height
+       * and the frame being painted, which is the only place a correction can
+       * still be invisible. A viewport box change is not a content shift, so a
+       * genuine resize re-anchors instead of correcting.
+       */
+      if (viewportBoxChanged) {
+        viewportAnchor.captureAnchor();
+      } else {
+        viewportAnchor.openSettleWindow();
+      }
+
+      if (tailRealignCallbacksRef.current > 0) {
+        tailRealignCallbacksRef.current -= 1;
+        handleViewportResize({
+          // Non-zero only on the callback that carries the change itself; the
+          // rest of the window is there for the reflow settling afterwards.
+          viewportHeightDeltaPx: viewportBoxChanged
+            ? nextViewportBox.height - previousViewportBox.height
+            : 0,
+          // The band check from before this resize, so this must run ahead of
+          // `updateIsAtBottom` below.
+          wasAtTail: isAtTailRef.current,
         });
       }
-    }
-    previousIsFollowingOutputRef.current = isFollowingOutput;
-  }, [
-    finalizeCollapseIntent,
-    isFollowingOutput,
-    isStreamingOutput,
-  ]);
-
-  const scrollToTurn = useCallback((turnIndex: number) => {
-    if (!virtuosoRef.current) return;
-    if (turnIndex < 1 || turnIndex > userMessageItems.length) return;
-
-    const targetItem = userMessageItems[turnIndex - 1];
-    if (!targetItem) return;
-
-    retainedCollapseAnchorRef.current = null;
-    exitFollowOutput('scroll-to-turn');
-    clearPinReservationForUserNavigation();
-    retargetHistoryProjectionHandoff(targetItem.item.turnId);
-
-    if (targetItem.index === 0) {
-      virtuosoRef.current.scrollTo({ top: 0, behavior: 'smooth' });
-    } else {
-      virtuosoRef.current.scrollToIndex({
-        index: targetItem.index,
-        behavior: 'smooth',
-        align: 'center',
-      });
-    }
-  }, [
-    clearPinReservationForUserNavigation,
-    exitFollowOutput,
-    retargetHistoryProjectionHandoff,
-    userMessageItems,
-  ]);
-
-  const scrollToIndex = useCallback((index: number) => {
-    if (!virtuosoRef.current) return;
-    if (index < 0 || index >= virtualItems.length) return;
-
-    retainedCollapseAnchorRef.current = null;
-    exitFollowOutput('scroll-to-index');
-    clearPinReservationForUserNavigation();
-    const targetTurnId = virtualItems[index]?.turnId;
-    if (targetTurnId) {
-      retargetHistoryProjectionHandoff(targetTurnId);
-    }
 
-    if (index === 0) {
-      virtuosoRef.current.scrollTo({ top: 0, behavior: 'auto' });
-    } else {
-      virtuosoRef.current.scrollToIndex({ index, align: 'center', behavior: 'auto' });
-    }
+      scheduleFollowToLatest();
+      scheduleVisibleTurnInfoUpdate();
+      updateIsAtBottom();
+    });
+    /*
+     * The virtualizer's own first child is a viewport-sized box — it stays at
+     * the scroller's height no matter how much transcript there is, so
+     * observing it never reported a content change at all. The item list is
+     * the element that grows, and its padding is where the virtualizer parks
+     * item space, which the content box does not include.
+     */
+    const content = scrollerElement.querySelector('[data-testid="flowchat-item-list"]')
+      ?? scrollerElement.firstElementChild;
+    if (content) observer.observe(content, { box: 'border-box' });
+    observer.observe(scrollerElement);
+    return () => observer.disconnect();
   }, [
-    clearPinReservationForUserNavigation,
-    exitFollowOutput,
-    retargetHistoryProjectionHandoff,
-    virtualItems,
+    handleViewportResize,
+    scheduleFollowToLatest,
+    scheduleVisibleTurnInfoUpdate,
+    scrollerElement,
+    updateIsAtBottom,
+    viewportAnchor,
   ]);
 
-  const clearSearchMatch = useCallback(() => {
-    searchNavigationRequestIdRef.current += 1;
-    setFlowChatSearchHighlight(null);
-  }, []);
-
-  const scrollToSearchMatch = useCallback((target: {
-    virtualItemIndex: number;
-    query: string;
-    flowItemId?: string;
-    occurrenceIndex?: number;
-    expandableIds?: readonly string[];
-  }) => {
-    const query = target.query.trim();
-    if (
-      !query ||
-      target.virtualItemIndex < 0 ||
-      target.virtualItemIndex >= virtualItems.length
-    ) {
-      clearSearchMatch();
-      return;
-    }
-
-    const requestId = searchNavigationRequestIdRef.current + 1;
-    searchNavigationRequestIdRef.current = requestId;
-    setFlowChatSearchHighlight(null);
-    retainedCollapseAnchorRef.current = null;
-    exitFollowOutput('scroll-to-index');
-    clearPinReservationForUserNavigation();
-    const targetTurnId = virtualItems[target.virtualItemIndex]?.turnId;
-    if (targetTurnId) {
-      retargetHistoryProjectionHandoff(targetTurnId);
+  /**
+   * Top-align a Turn, without scrolling into the reserved blank to do it.
+   *
+   * The branch is on what is *knowable*, not on where the Turn is. A rendered
+   * Turn has a resolvable offset, so the clamp is decided before anything
+   * moves and the requested behaviour survives. An unrendered one is known
+   * only to the virtualizer, so it is placed instantly and the answer read back —
+   * both writes land in the same task, so the correction costs a second scroll
+   * but not a second visible movement.
+   */
+  const navigateToTurnWithStatus = useCallback((
+    turnId: string,
+    options?: TurnNavigationOptions,
+  ): FlowChatTurnNavigationStatus => {
+    const targetIndex = virtualItems.findIndex(item => (
+      item.turnId === turnId && item.type === 'user-message'
+    ));
+    if (targetIndex < 0) {
+      traceViewport({
+        location: 'turnNavigation.rejected',
+        message: 'the requested Turn is not in the presentation',
+        data: () => ({ turnId, itemCount: virtualItems.length, presentationMode }),
+      });
+      return 'rejected';
     }
+    exitFollowOutput('scroll-to-turn');
+    /*
+     * Ahead of the placement, so that nothing between here and the commit that
+     * renders it can restore the position being left. The reading position the
+     * reader is choosing is the one they are about to land on.
+     */
+    viewportAnchor.reanchorAfterNavigation();
+
+    const behavior = options?.behavior === 'smooth' ? 'smooth' : 'auto';
+    const alignTurnToTop = () => virtualizer.scrollItemIntoView(targetIndex, {
+      align: 'start',
+      behavior,
+      owner: 'one-shot-navigation',
+      holdForMs: ONE_SHOT_NAVIGATION_HOLD_MS,
+    });
+    const scroller = scrollerElementRef.current;
+    const renderedTurnTopScrollTop = resolveTurnTopScrollTop(turnId);
+    /*
+     * Which branch ran is most of the diagnosis. "It stopped on the wrong Turn"
+     * has already been a re-aim chasing a target below a moving measurement, a
+     * clamp into the reserved blank, and a window re-cut arriving underneath —
+     * and the branch, the target index and the drift afterwards tell them
+     * apart. The drift in particular: a navigation that lands and is then taken
+     * away leaves the same final position as one that never aimed right.
+     */
+    const traceNavigation = (
+      branch: string,
+      place: () => void,
+      targetPx?: number,
+      extra?: () => Record<string, unknown>,
+    ) => {
+      traceViewportPlacement(
+        scroller,
+        {
+          location: 'turnNavigation.placed',
+          message: 'Turn navigation placed the viewport',
+          targetPx,
+          /*
+           * Past the navigation's own hold, always. Everything the hold is
+           * postponing happens on the frame it lapses, so a sample taken
+           * inside it can only ever report success — measured: a placement
+           * reported `driftPx: 0` at 400ms and was dragged 1653px away 11ms
+           * later, while three identical placements that were sampled after
+           * the hold all reported the drift.
+           */
+          settleAfterMs: ONE_SHOT_NAVIGATION_HOLD_MS
+            + (behavior === 'smooth' ? 900 : VIEWPORT_PLACEMENT_SETTLE_MS),
+          data: () => ({
+            branch,
+            turnId,
+            targetIndex,
+            itemCount: virtualItems.length,
+            behavior,
+            presentationMode,
+            ...(extra?.() ?? {}),
+          }),
+        },
+        place,
+      );
+    };
 
-    const virtuoso = virtuosoRef.current;
-    if (virtuoso) {
-      if (target.virtualItemIndex === 0) {
-        virtuoso.scrollTo({ top: 0, behavior: 'auto' });
+    if (scroller && renderedTurnTopScrollTop !== null) {
+      if (turnTopAlignmentEntersReservedBlank({
+        turnTopScrollTop: renderedTurnTopScrollTop,
+        contentEndScrollTop: readContentEndScrollTop(scroller),
+      })) {
+        traceNavigation(
+          'rendered-clamped-to-content-end',
+          () => scrollToContentEndThroughVirtualizer(
+            behavior,
+            'one-shot-navigation',
+            ONE_SHOT_NAVIGATION_HOLD_MS,
+          ),
+        );
       } else {
-        virtuoso.scrollToIndex({
-          index: target.virtualItemIndex,
-          align: 'center',
-          behavior: 'auto',
-        });
+        traceNavigation('rendered-top-aligned', alignTurnToTop, renderedTurnTopScrollTop);
       }
+      return 'settled';
     }
 
-    let attempts = 0;
-    let revealedCollapsedContent = false;
-    // Scroll position the previous successful pass settled on. Expanding
-    // collapsed content reflows everything below it, so one more pass is needed
-    // after the expansion — but only until the answer stops moving. Re-arming
-    // unconditionally kept re-running the full tree-walk, re-highlight and
-    // ancestor `getComputedStyle` scan for all 24 attempts, roughly 22 of them
-    // recomputing a position that had already converged.
-    let lastResolvedScrollTop: number | null = null;
-    const resolveExactTextPosition = () => {
-      if (searchNavigationRequestIdRef.current !== requestId) {
-        return;
-      }
-
-      attempts += 1;
-      const scroller = scrollerElementRef.current;
-      const wrapper = getRenderedVirtualItemElement(target.virtualItemIndex);
-      if (!scroller || !wrapper) {
-        if (attempts < SEARCH_NAVIGATION_MAX_ATTEMPTS) {
-          requestAnimationFrame(resolveExactTextPosition);
-        }
-        return;
-      }
-
-      for (const expandableId of target.expandableIds ?? []) {
-        const expandable = findElementWithDataValue(
-          wrapper,
-          'data-tool-card-id',
-          expandableId,
-        );
-        if (!expandable) {
-          if (attempts < SEARCH_NAVIGATION_MAX_ATTEMPTS) {
-            requestAnimationFrame(resolveExactTextPosition);
-          }
-          return;
-        }
-
-        if (expandable.dataset.expanded === 'false') {
-          const toggle = expandable.querySelector<HTMLElement>(
-            '[data-testid="chat-explore-group-toggle"], [data-testid="chat-thinking-toggle"]',
-          );
-          if (toggle) {
-            revealedCollapsedContent = true;
-            toggle.click();
-          }
-          if (attempts < SEARCH_NAVIGATION_MAX_ATTEMPTS) {
-            requestAnimationFrame(resolveExactTextPosition);
-          }
-          return;
-        }
-      }
-
-      if (target.flowItemId) {
-        const flowItem = findElementWithDataValue(
-          wrapper,
-          'data-flow-item-id',
-          target.flowItemId,
-        );
-        const thinkingItem = findElementWithDataValue(
-          wrapper,
-          'data-tool-card-id',
-          target.flowItemId,
-        );
-        if (!flowItem && !thinkingItem) {
-          if (attempts < SEARCH_NAVIGATION_MAX_ATTEMPTS) {
-            requestAnimationFrame(resolveExactTextPosition);
-          }
+    /*
+     * Placed instantly on purpose: an animated scroll has not arrived yet, so
+     * there would be nothing to read back. The requested behaviour is spent on
+     * the placement, which is what turn-rail navigation already asks for.
+     *
+     * The clamp belongs to the same placement rather than being a second one.
+     * It is decided from where the instant placement landed and applied in the
+     * same task, so the reader sees one movement — and tracing it as two made
+     * the first one's outcome sample compare the offset the viewport came to
+     * rest at against a position this function had itself replaced 20ms
+     * earlier. Measured: `driftPx: -892.7` against a target of 2484 that was
+     * superseded by 1591, which is the clamp working exactly as intended
+     * reported as the largest displacement in the recording.
+     */
+    let clampedToContentEnd = false;
+    let unclampedPx: number | null = null;
+    traceNavigation(
+      'unrendered-placed-instantly',
+      () => {
+        virtualizer.scrollItemIntoView(targetIndex, {
+          align: 'start',
+          owner: 'one-shot-navigation',
+          holdForMs: ONE_SHOT_NAVIGATION_HOLD_MS,
+        });
+        if (!scroller) return;
+        unclampedPx = scroller.scrollTop;
+        if (!turnTopAlignmentEntersReservedBlank({
+          turnTopScrollTop: scroller.scrollTop,
+          // Re-read: placing the viewport renders items, which re-measures the
+          // transcript and moves the content end with it.
+          contentEndScrollTop: readContentEndScrollTop(scroller),
+        })) {
           return;
         }
-      }
-
-      const textRoot = getFlowChatSearchTextRoot(wrapper, target.flowItemId);
-      const userMessage = textRoot.closest<HTMLElement>('.user-message-item');
-      if (
-        userMessage &&
-        !userMessage.classList.contains('user-message-item--expanded') &&
-        textRoot.scrollHeight > textRoot.clientHeight + 1
-      ) {
-        revealedCollapsedContent = true;
-        textRoot.click();
-        if (attempts < SEARCH_NAVIGATION_MAX_ATTEMPTS) {
-          requestAnimationFrame(resolveExactTextPosition);
-        }
-        return;
-      }
-
-      const ranges = findFlowChatSearchTextRanges(textRoot, query);
-      if (ranges.length === 0) {
-        if (attempts < SEARCH_NAVIGATION_MAX_ATTEMPTS) {
-          requestAnimationFrame(resolveExactTextPosition);
-        }
-        return;
-      }
-
-      // Markdown syntax can make the raw-content occurrence count exceed the
-      // rendered one; clamping still lands navigation on a real occurrence.
-      const rangeIndex = Math.min(Math.max(target.occurrenceIndex ?? 0, 0), ranges.length - 1);
-      const range = ranges[rangeIndex];
-      setFlowChatSearchHighlight(range, ranges.filter((_, index) => index !== rangeIndex));
-
-      let ancestor = range.startContainer.parentElement;
-      while (ancestor && ancestor !== scroller && wrapper.contains(ancestor)) {
-        const styles = ancestor.ownerDocument.defaultView?.getComputedStyle(ancestor);
-        const canScrollVertically = (
-          ancestor.scrollHeight > ancestor.clientHeight + 1 &&
-          (styles?.overflowY === 'auto' || styles?.overflowY === 'scroll')
+        clampedToContentEnd = true;
+        scrollToContentEndThroughVirtualizer(
+          'auto',
+          'one-shot-navigation',
+          ONE_SHOT_NAVIGATION_HOLD_MS,
         );
-        if (canScrollVertically) {
-          const rangeRect = range.getBoundingClientRect();
-          const ancestorRect = ancestor.getBoundingClientRect();
-          const nextScrollTop = ancestor.scrollTop +
-            rangeRect.top -
-            ancestorRect.top -
-            Math.max(0, (ancestor.clientHeight - rangeRect.height) / 2);
-          ancestor.scrollTop = Math.max(
-            0,
-            Math.min(nextScrollTop, ancestor.scrollHeight - ancestor.clientHeight),
-          );
-        }
-        ancestor = ancestor.parentElement;
-      }
-
-      const rangeRect = range.getBoundingClientRect();
-      const scrollerRect = scroller.getBoundingClientRect();
-      const nextScrollTop = scroller.scrollTop +
-        rangeRect.top -
-        scrollerRect.top -
-        Math.max(0, (scroller.clientHeight - rangeRect.height) / 2);
-      scroller.scrollTop = Math.max(
-        0,
-        Math.min(nextScrollTop, scroller.scrollHeight - scroller.clientHeight),
-      );
-      previousScrollTopRef.current = scroller.scrollTop;
-      recordScrollerGeometry(scroller);
-      scheduleVisibleTurnMeasure(2);
-
-      const settled =
-        lastResolvedScrollTop !== null
-        && Math.abs(scroller.scrollTop - lastResolvedScrollTop) <= 1;
-      lastResolvedScrollTop = scroller.scrollTop;
-      if (
-        revealedCollapsedContent
-        && !settled
-        && attempts < SEARCH_NAVIGATION_MAX_ATTEMPTS
-      ) {
-        requestAnimationFrame(resolveExactTextPosition);
-      }
-    };
-
-    requestAnimationFrame(resolveExactTextPosition);
+      },
+      undefined,
+      // Where the Turn's own alignment would have put the viewport, kept
+      // because the clamp is only correct if that offset was in the blank.
+      () => ({
+        clampedToContentEnd,
+        unclampedPx: unclampedPx === null ? null : roundViewportPx(unclampedPx),
+      }),
+    );
+    return 'settled';
   }, [
-    clearPinReservationForUserNavigation,
-    clearSearchMatch,
     exitFollowOutput,
-    getRenderedVirtualItemElement,
-    recordScrollerGeometry,
-    retargetHistoryProjectionHandoff,
-    scheduleVisibleTurnMeasure,
+    presentationMode,
+    readContentEndScrollTop,
+    resolveTurnTopScrollTop,
+    scrollToContentEndThroughVirtualizer,
+    viewportAnchor,
     virtualItems,
+    virtualizer,
   ]);
 
-  useEffect(() => () => {
-    searchNavigationRequestIdRef.current += 1;
-    setFlowChatSearchHighlight(null);
-  }, []);
-
-  const pinTurnToTopWithStatus = useCallback((turnId: string, options?: TurnPinOptions): FlowChatTurnPinRequestStatus => {
-    const shouldExitFollowOutput = !(
-      options?.pinMode === 'sticky-latest' &&
-      turnId === latestTurnId
+  const navigateToTurn = useCallback((turnId: string, options?: TurnNavigationOptions) => (
+    navigateToTurnWithStatus(turnId, options) !== 'rejected'
+  ), [navigateToTurnWithStatus]);
+
+  /**
+   * Centre a flow item — a tool call, a text block — inside its Turn.
+   *
+   * The virtualizer cannot be asked for this: it aligns *items*, and a flow
+   * item lives inside one, so a centred model round is not a centred tool call.
+   * That is the carve-out the contract already makes for a target that is not
+   * an item, and the offset goes through the register like every other write.
+   *
+   * Returns whether the item was there to aim at. A focus request arriving
+   * before its Turn has rendered asks again on the next frame.
+   */
+  const focusFlowItem = useCallback((flowItemId: string): boolean => {
+    const scroller = scrollerElementRef.current;
+    if (!scroller || !flowItemId) return false;
+    const element = scroller.querySelector<HTMLElement>(
+      `[data-flow-item-id="${CSS.escape(flowItemId)}"]`,
     );
-    if (shouldExitFollowOutput) {
-      exitFollowOutput('pin-turn-to-top');
-    }
-
-    return requestTurnPinToTop(turnId, options);
-  }, [
-    exitFollowOutput,
-    latestTurnId,
-    requestTurnPinToTop,
-  ]);
+    if (!element) return false;
 
-  const prepareTurnPinToTop = useCallback((turnId: string, options?: TurnPinOptions): FlowChatTurnPinRequestStatus => {
-    if (!turnId || !activeSessionIdRef.current) {
-      return 'rejected';
-    }
-
-    exitFollowOutput('pin-turn-to-top');
-    clearTurnPinRequest();
-    cancelLatestEndAnchorStabilization();
-    retainedCollapseAnchorRef.current = null;
-    viewportCoordinatorRef.current.pinItem('prepare-history-window-turn-pin');
-    preparedHistoryTurnPinRef.current = {
-      turnId,
-      behavior: options?.behavior ?? 'auto',
-      pinMode: options?.pinMode ?? 'transient',
-      alignmentPolicy: options?.alignmentPolicy ?? 'exact',
-    };
-    retargetHistoryProjectionHandoff(turnId);
-    setIsAtBottom(false);
-    return 'pending';
-  }, [
-    cancelLatestEndAnchorStabilization,
-    clearTurnPinRequest,
-    exitFollowOutput,
-    retargetHistoryProjectionHandoff,
-  ]);
-
-  const pinTurnToTop = useCallback((turnId: string, options?: TurnPinOptions) => {
-    return pinTurnToTopWithStatus(turnId, options) !== 'rejected';
-  }, [pinTurnToTopWithStatus]);
-
-  const visibleTurnInfo = useModernFlowChatStore(state => state.visibleTurnInfo);
-
-  const handleJumpToCurrentTurn = useCallback(() => {
-    const currentTurnId = visibleTurnInfo?.turnId;
-    if (!currentTurnId) return;
-    pinTurnToTop(currentTurnId, { behavior: 'smooth', pinMode: 'transient' });
-  }, [visibleTurnInfo?.turnId, pinTurnToTop]);
-
-  const { shouldShowButton: shouldShowTurnHeaderButton, handleClick: handleTurnHeaderClick } = useScrollToTurnHeader({
-    scrollerRef: scrollerElementRef,
-    currentTurnId: visibleTurnInfo?.turnId ?? null,
-    currentTurnIndex: visibleTurnInfo?.turnIndex ?? 0,
-    visibleTurnInfo,
-    onJumpToCurrentTurn: handleJumpToCurrentTurn,
-  });
-
-  const { visibleTaskInfo, scrollToTask } = useVisibleTaskInfo({
-    scrollerRef: scrollerElementRef,
-    virtualItems,
-  });
-
-  const scrollToPhysicalBottomAndClearPin = useCallback(() => {
-    const scroller = scrollerElementRef.current;
-    if (canProcessViewportGeometry(scroller)) {
-      clearTurnPinRequest();
-      clearAllBottomReservationsForUserNavigation();
-      const nextScrollTop = Math.max(0, scroller.scrollHeight - scroller.clientHeight);
-      scroller.scrollTo({
-        top: nextScrollTop,
-        behavior: 'auto',
-      });
-      previousScrollTopRef.current = nextScrollTop;
-      previousMeasuredHeightRef.current = snapshotMeasuredContentHeight(scroller);
-      recordScrollerGeometry(scroller);
-      setIsAtBottom(true);
-    }
-  }, [
-    clearAllBottomReservationsForUserNavigation,
-    clearTurnPinRequest,
-    canProcessViewportGeometry,
-    recordScrollerGeometry,
-    snapshotMeasuredContentHeight,
-  ]);
+    exitFollowOutput('scroll-to-index');
+    const scrollerRect = scroller.getBoundingClientRect();
+    const elementRect = element.getBoundingClientRect();
+    const centred = scroller.scrollTop + elementRect.top - scrollerRect.top
+      - Math.max(0, (scroller.clientHeight - elementRect.height) / 2);
+    viewportOwner.write({
+      owner: 'one-shot-navigation',
+      holdForMs: ONE_SHOT_NAVIGATION_HOLD_MS,
+      topPx: Math.max(0, Math.min(scroller.scrollHeight - scroller.clientHeight, centred)),
+    });
+    return true;
+  }, [exitFollowOutput, viewportOwner]);
 
-  const scrollToTurnEndAndClearPin = useCallback((turnId: string) => {
-    const scroller = scrollerElementRef.current;
-    const reject = (cause: string, extra: Record<string, unknown> = {}) => {
-      startupTrace.markPhase('flowchat_latest_end_anchor_rejected', {
-        cause,
-        turnId,
-        virtualItemCount: virtualItems.length,
-        hasVirtuoso: Boolean(virtuosoRef.current),
-        ...extra,
-      });
-      return false;
+  const prepareTurnNavigation = useCallback((
+    turnId: string,
+    options?: TurnNavigationOptions,
+  ): FlowChatTurnNavigationStatus => {
+    if (!turnId || !activeSessionId) return 'rejected';
+    exitFollowOutput('scroll-to-turn');
+    preparedTurnNavigationRef.current = {
+      turnId,
+      behavior: options?.behavior ?? 'auto',
     };
+    return 'pending';
+  }, [activeSessionId, exitFollowOutput]);
 
-    if (!canProcessViewportGeometry(scroller) || virtualItems.length === 0) {
-      return reject(
-        !scroller
-          ? 'missing_scroller'
-          : !canProcessViewportGeometry(scroller)
-            ? 'inactive_viewport'
-            : 'empty_virtual_items',
-      );
-    }
+  useLayoutEffect(() => {
+    const prepared = preparedTurnNavigationRef.current;
+    if (!prepared) return;
+    const status = navigateToTurnWithStatus(prepared.turnId, { behavior: prepared.behavior });
+    if (status === 'settled') preparedTurnNavigationRef.current = null;
+  }, [navigateToTurnWithStatus, virtualItems]);
+
+  /**
+   * Land on a Turn by its position in the transcript on screen.
+   *
+   * Instant, like the other two ways the same request can be resolved. This is
+   * the last-resort branch of a focus request — `resolvedTurnId` and
+   * `resolvedVirtualIndex` are tried first, both instant — and which branch runs
+   * depends only on what the request happened to carry, not on anything the
+   * reader did. Animating this one made the same usage-report click animate or
+   * jump depending on whether the report knew the Turn's id.
+   */
+  const scrollToTurn = useCallback((turnIndex: number) => {
+    const target = userMessageItems[turnIndex - 1];
+    if (target) navigateToTurn(target.item.turnId, { behavior: 'auto' });
+  }, [navigateToTurn, userMessageItems]);
+
+  const scrollToIndex = useCallback((index: number) => {
+    if (index < 0 || index >= virtualItems.length) return;
+    exitFollowOutput('scroll-to-index');
+    virtualizer.scrollItemIntoView(index, {
+      align: 'center',
+      owner: 'one-shot-navigation',
+      holdForMs: ONE_SHOT_NAVIGATION_HOLD_MS,
+    });
+  }, [exitFollowOutput, virtualItems.length, virtualizer]);
 
+  const scrollToTurnEnd = useCallback((turnId: string) => {
     let targetIndex = -1;
     for (let index = virtualItems.length - 1; index >= 0; index -= 1) {
       if (virtualItems[index]?.turnId === turnId) {
@@ -6851,500 +1576,489 @@ const VirtualMessageListSession = forwardRef<VirtualMessageListRef, VirtualMessa
         break;
       }
     }
+    const scroller = scrollerElementRef.current;
+    const bounds = targetIndex < 0 ? null : virtualizer.getItemBounds(targetIndex);
+    if (!bounds || !scroller) return false;
+    // Deliberately does not exit follow-output. This is the session-open
+    // placement, which wants the same position the tail follow is settling on;
+    // releasing ownership here strands the viewport wherever this one early
+    // shot landed, before item measurement and history paging have finished.
+    //
+    // Aligned by hand rather than by asking for the last item's end: the
+    // virtualizer's own end alignment runs to the bottom of the scroll range,
+    // and the resident tail spacer lives down there.
+    virtualizer.scrollToOffset(bounds.endPx - scroller.clientHeight, {
+      owner: 'follow-output',
+    });
+    return true;
+  }, [virtualItems, virtualizer]);
 
-    if (targetIndex < 0) {
-      return reject('missing_target_index');
-    }
+  const isTurnRenderedInViewport = useCallback((turnId: string) => {
+    const scroller = scrollerElementRef.current;
+    const element = getRenderedUserMessageElement(turnId);
+    return Boolean(scroller && element && isElementVisibleInScroller(element, scroller));
+  }, [getRenderedUserMessageElement]);
 
-    exitFollowOutput('scroll-to-index');
-    clearTurnPinRequest();
-    clearAllBottomReservationsForUserNavigation();
+  const isTurnTextRenderedInViewport = useCallback((turnId: string) => {
+    const scroller = scrollerElementRef.current;
+    const element = getRenderedUserMessageElement(turnId);
+    return Boolean(
+      scroller &&
+      element &&
+      element.textContent?.trim() &&
+      isElementVisibleInScroller(element, scroller)
+    );
+  }, [getRenderedUserMessageElement]);
 
-    if (!virtuosoRef.current) {
-      return reject('missing_virtuoso', { targetIndex });
-    }
+  const clearSearchMatch = useCallback(() => {
+    searchNavigationRequestIdRef.current += 1;
+    setFlowChatSearchHighlight(null);
+  }, []);
 
-    latestEndAnchorRequestRef.current = {
-      turnId,
-      targetIndex,
-      attempts: 0,
-      visibleFrames: 0,
-      stableVisibleFrames: 0,
-      lastScrollHeight: null,
-      lastScrollTop: null,
-      lastTargetTop: null,
-      lastTargetBottom: null,
-    };
-    startupTrace.markPhase('flowchat_latest_end_anchor_request', {
-      targetIndex,
-      turnId,
-      virtualItemCount: virtualItems.length,
-    });
-    virtuosoRef.current.scrollToIndex({
-      index: targetIndex,
-      align: 'end',
-      behavior: 'auto',
+  const scrollToSearchMatch = useCallback((target: {
+    virtualItemIndex: number;
+    query: string;
+    flowItemId?: string;
+    occurrenceIndex?: number;
+    expandableIds?: readonly string[];
+  }) => {
+    clearSearchMatch();
+    exitFollowOutput('scroll-to-index');
+    const requestId = searchNavigationRequestIdRef.current;
+    virtualizer.scrollItemIntoView(target.virtualItemIndex, {
+      align: 'center',
+      owner: 'one-shot-navigation',
+      holdForMs: ONE_SHOT_NAVIGATION_HOLD_MS,
     });
-    if (latestEndAnchorStabilizationFrameRef.current === null) {
-      latestEndAnchorStabilizationFrameRef.current = requestAnimationFrame(() => {
-        latestEndAnchorStabilizationFrameRef.current = null;
-        resolveLatestEndAnchorStabilization('raf');
+    let attempts = 0;
+    const resolve = () => {
+      if (searchNavigationRequestIdRef.current !== requestId) return;
+      attempts += 1;
+      const scroller = scrollerElementRef.current;
+      const wrapper = Array.from(
+        scroller?.querySelectorAll<HTMLElement>('.virtual-item-wrapper') ?? [],
+      ).find(element => Number(element.dataset.virtualIndex) === target.virtualItemIndex);
+      if (!scroller || !wrapper) {
+        if (attempts < SEARCH_NAVIGATION_MAX_ATTEMPTS) requestAnimationFrame(resolve);
+        return;
+      }
+      for (const expandableId of target.expandableIds ?? []) {
+        const expandable = findElementWithDataValue(wrapper, 'data-tool-card-id', expandableId);
+        if (expandable?.dataset.expanded === 'false') {
+          expandable.querySelector<HTMLElement>(
+            '[data-testid="chat-explore-group-toggle"], [data-testid="chat-thinking-toggle"]',
+          )?.click();
+          if (attempts < SEARCH_NAVIGATION_MAX_ATTEMPTS) requestAnimationFrame(resolve);
+          return;
+        }
+      }
+      const root = getFlowChatSearchTextRoot(wrapper, target.flowItemId);
+      const ranges = findFlowChatSearchTextRanges(root, target.query);
+      const rangeIndex = Math.min(target.occurrenceIndex ?? 0, Math.max(0, ranges.length - 1));
+      const range = ranges[rangeIndex] ?? null;
+      if (!range) return;
+      setFlowChatSearchHighlight(range, ranges.filter((_, index) => index !== rangeIndex));
+      const rangeRect = range.getBoundingClientRect();
+      const scrollerRect = scroller.getBoundingClientRect();
+      viewportOwner.write({
+        owner: 'one-shot-navigation',
+        holdForMs: ONE_SHOT_NAVIGATION_HOLD_MS,
+        topPx: Math.max(
+          0,
+          Math.min(
+            scroller.scrollHeight - scroller.clientHeight,
+            scroller.scrollTop + rangeRect.top - scrollerRect.top -
+              Math.max(0, (scroller.clientHeight - rangeRect.height) / 2),
+          ),
+        ),
+      });
+    };
+    requestAnimationFrame(resolve);
+  }, [clearSearchMatch, exitFollowOutput, viewportOwner, virtualizer]);
+
+  useEffect(() => () => setFlowChatSearchHighlight(null), []);
+
+  const requestHistoryBoundary = useCallback((direction: SessionHistoryWindowDirection) => {
+    /*
+     * Three refusals, all asking whether the ask describes the reader.
+     *
+     * The first is the opening reveal. Until it ends the transcript is hidden
+     * and still being placed — item heights are estimates and the viewport is
+     * walking down to the content end — so the offset a boundary would be
+     * judged from is not a position anybody chose, and on a session whose
+     * loaded tail is shorter than one viewport the head is trivially "reached"
+     * at offset 0. Worse, what the page then does is prepend history *above*
+     * that viewport, and the compensation for it is deliberately left to
+     * whoever holds a target; landing it in the middle of the opening
+     * placement puts those two in a race that the reader loses by eight Turns.
+     * Measured: a re-opened session paged 140ms after mount, from a viewport
+     * still at 0, and was revealed at the top of the window it had just pulled
+     * in. Deferred rather than dropped — the reveal settling asks again.
+     *
+     * While the follow rule owns the viewport, the position the ask was derived
+     * from is our own placement — as true of a history window being opened as
+     * of the live tail, so the test is ownership and not which presentation is
+     * on screen. Ownership ends the moment the reader scrolls, which is exactly
+     * when the ask starts meaning something. Measured on session open: five
+     * pages landed in 890ms, each one displacing the viewport and so requesting
+     * the next, until history ran out.
+     *
+     * The third is the arming latch; see `boundaryArmedRef`.
+     *
+     * All three are invisible when they fire: the boundary status stays idle,
+     * which is also what "there is no more history" looks like. The faults have
+     * been at either extreme — pages arriving in a chain because no refusal
+     * fired, and a boundary that never pages because the latch stayed shut — so
+     * the reason is recorded rather than inferred from what did not happen.
+     */
+    if (isOpeningViewport()) {
+      traceViewportRepeating(`paging|${direction}|opening`, {
+        location: 'historyPaging.refused',
+        message: 'the transcript is still being placed, so the boundary is not the reader\'s',
+        data: () => ({
+          direction,
+          reason: 'opening-reveal',
+          viewportId,
+          scrollTopPx: roundViewportPx(scrollerElementRef.current?.scrollTop ?? 0),
+        }),
       });
-    }
-    scheduleVisibleTurnMeasure(2);
-    return true;
-  }, [
-    clearAllBottomReservationsForUserNavigation,
-    clearTurnPinRequest,
-    canProcessViewportGeometry,
-    exitFollowOutput,
-    resolveLatestEndAnchorStabilization,
-    scheduleVisibleTurnMeasure,
-    virtualItems,
-  ]);
-
-  const scrollToLatestEndPosition = useCallback(() => {
-    retainedCollapseAnchorRef.current = null;
-    clearTurnPinRequest();
-    if (latestTurnId) {
-      retargetHistoryProjectionHandoff(latestTurnId);
-    }
-    onUserScrollIntent?.();
-    enterFollowOutput('jump-to-latest');
-  }, [
-    clearTurnPinRequest,
-    enterFollowOutput,
-    latestTurnId,
-    onUserScrollIntent,
-    retargetHistoryProjectionHandoff,
-  ]);
-
-  const handleScrollToLatestRequest = useCallback(() => {
-    if (viewportMode === 'history-reading' && onRequestJumpToLatest) {
-      onRequestJumpToLatest();
       return;
     }
-    scrollToLatestEndPosition();
-  }, [onRequestJumpToLatest, scrollToLatestEndPosition, viewportMode]);
-
-  useImperativeHandle(ref, () => ({
-    scrollToTurn,
-    scrollToIndex,
-    scrollToSearchMatch,
-    clearSearchMatch,
-    scrollToPhysicalBottomAndClearPin,
-    scrollToTurnEndAndClearPin,
-    isTurnRenderedInViewport,
-    isTurnTextRenderedInViewport,
-    scrollToLatestEndPosition,
-    pinTurnToTop,
-    pinTurnToTopWithStatus,
-    prepareTurnPinToTop,
-  }), [
-    isTurnRenderedInViewport,
-    isTurnTextRenderedInViewport,
-    pinTurnToTop,
-    pinTurnToTopWithStatus,
-    prepareTurnPinToTop,
-    clearSearchMatch,
-    scrollToTurn,
-    scrollToIndex,
-    scrollToSearchMatch,
-    scrollToPhysicalBottomAndClearPin,
-    scrollToTurnEndAndClearPin,
-    scrollToLatestEndPosition,
-  ]);
-
-  const handleAtBottomStateChange = useCallback((atBottom: boolean) => {
-    setIsAtBottom(atBottom);
-  }, []);
-
-  const footerHeightPx = getFooterHeightPx(getTotalBottomCompensationPx());
-  const initialHistoryTransitionState = React.useMemo<InitialHistoryTransitionState | null>(() => {
-    if (!activeSessionId || !latestTurnId) {
-      return null;
+    if (isFollowingOutputNow()) {
+      traceViewportRepeating(`paging|${direction}|following`, {
+        location: 'historyPaging.refused',
+        message: 'the boundary was reached by our own placement, not by the reader',
+        data: () => ({ direction, reason: 'follow-output-owns-the-viewport' }),
+      });
+      return;
     }
-
-    const contextRestoreState = activeSession?.contextRestoreState ?? 'unknown';
-    const isPartial = activeSession?.isPartial === true;
-    const usesInitialHistoryRenderBudget = useInitialHistoryRenderBudget;
-    return {
-      key: [
-        activeSessionId,
-        latestTurnId,
-        virtualItems.length,
-        isPartial ? 'partial' : 'full',
-        contextRestoreState,
-        usesInitialHistoryRenderBudget ? 'initial-budget' : 'normal',
-      ].join(':'),
-      sessionId: activeSessionId,
-      isPartial,
-      contextRestoreState,
-      usesInitialHistoryRenderBudget,
-    };
-  }, [
-    activeSession?.contextRestoreState,
-    activeSession?.isPartial,
-    activeSessionId,
-    latestTurnId,
-    useInitialHistoryRenderBudget,
-    virtualItems.length,
-  ]);
-  useLayoutEffect(() => {
-    const previousState = previousInitialHistoryTransitionStateRef.current;
-    previousInitialHistoryTransitionStateRef.current = initialHistoryTransitionState;
-
-    if (presentationMode === 'history-window') {
-      if (historyProjectionHandoffRef.current) {
-        clearHistoryProjectionHandoffRef.current('history-window-presentation');
-      }
+    if (!boundaryArmedRef.current[direction]) {
+      traceViewportRepeating(`paging|${direction}|unarmed`, {
+        location: 'historyPaging.refused',
+        message: 'the boundary has not been left since the last page',
+        data: () => ({ direction, reason: 'not-rearmed' }),
+      });
       return;
     }
-
-    const shouldProtectTransition = Boolean(
-      previousState &&
-      initialHistoryTransitionState &&
-      previousState.sessionId === initialHistoryTransitionState.sessionId &&
-      previousState.key !== initialHistoryTransitionState.key &&
-      (
-        previousState.usesInitialHistoryRenderBudget ||
-        initialHistoryTransitionState.usesInitialHistoryRenderBudget ||
-        previousState.isPartial !== initialHistoryTransitionState.isPartial ||
-        previousState.contextRestoreState !== initialHistoryTransitionState.contextRestoreState
-      )
-    );
-
+    const latchedExhausted = exhaustedBoundaryRef.current[direction];
     if (
-      !shouldProtectTransition ||
-      !initialHistoryTransitionState ||
-      !activeSessionId ||
-      historyProjectionHandoffRef.current?.sessionId === activeSessionId
+      !onHistoryWindowBoundaryIntent ||
+      boundaryRequestRef.current[direction] ||
+      latchedExhausted
     ) {
+      /*
+       * The user has reached the head of the loaded window and we are declining
+       * to fetch more. That is correct once history really is exhausted, and a
+       * silent data loss when it is not — the boundary status stays idle either
+       * way, so the transcript looks like it simply has no earlier Turns.
+       *
+       * The head, and only the head. `after` latches the moment the reader
+       * reaches the newest Turn, which is every session that has ever been
+       * paged, and a partial session stays partial throughout — so raising this
+       * for it is a warning that fires on the ordinary case and means nothing.
+       * Measured: four of them in one recording, all `after`, all correct
+       * behaviour. `resolveHistoryBoundaryTarget` draws the same line one layer
+       * down, between `reached-latest` and `beyond-known-total`.
+       */
+      const session = activeSessionRef.current;
+      if (
+        direction === 'before'
+        && latchedExhausted
+        && session?.sessionId
+        && session.isPartial === true
+      ) {
+        warnHistoryPagingRefusedWithPendingTurns(session.sessionId, {
+          direction,
+          reason: 'latched-exhausted-while-partial',
+          isPartial: true,
+          latchedExhausted: true,
+          loadedTurnCount: session.dialogTurns.length,
+          totalTurnCount: session.totalTurnCount ?? 0,
+        });
+      }
       return;
     }
-
-    const snapshot = latestVisibleHistoryTailSnapshotRef.current;
-    if (!snapshot || snapshot.sessionId !== activeSessionId || snapshot.items.length === 0) {
-      return;
-    }
-
-    const handoff: HistoryProjectionHandoffSnapshot = {
-      ...snapshot,
-      reason: 'initial-history-content-transition',
-      createdAtMs: performance.now(),
-      targetTurnId: latestTurnId,
-      footerHeightPx,
-    };
-
-    historyProjectionHandoffRef.current = handoff;
-    setHistoryProjectionHandoff(handoff);
-    startupTrace.markPhase('flowchat_history_projection_handoff_activated', {
-      sessionId: handoff.sessionId,
-      reason: handoff.reason,
-      previousItemCount: handoff.items.length,
-      nextItemCount: virtualItems.length,
-      previousInitialHistoryBudget: previousState?.usesInitialHistoryRenderBudget ?? false,
-      nextInitialHistoryBudget: initialHistoryTransitionState.usesInitialHistoryRenderBudget,
+    // Disarmed for as long as this page is the reason the window sits at the
+    // boundary. Only the window moving off it arms the direction again.
+    boundaryArmedRef.current[direction] = false;
+    /*
+     * The ask itself, and the viewport it was derived from.
+     *
+     * Every refusal above is recorded, and the one that goes through was not —
+     * so a page that arrives while the transcript is still opening, from a
+     * viewport nobody is following and at an offset the reader never chose,
+     * looked exactly like a page the reader asked for. That page prepends
+     * history above them, and the compensation for it is deliberately left to
+     * whoever holds a target; with nothing holding one, this line is where that
+     * chain starts.
+     */
+    traceViewport({
+      location: 'historyPaging.asked',
+      message: 'the boundary was reached by the reader, so history was asked for',
+      data: () => ({
+        direction,
+        viewportId,
+        isOpening: isOpeningViewport(),
+        presentationMode,
+        itemCount: virtualItems.length,
+        scrollTopPx: roundViewportPx(scrollerElementRef.current?.scrollTop ?? 0),
+      }),
     });
-    scheduleHistoryProjectionHandoffRelease(2);
+    const request = Promise.resolve(onHistoryWindowBoundaryIntent(direction)).then(
+      normalizeBoundaryResult,
+    ).then(result => {
+      if (result === 'exhausted') {
+        exhaustedBoundaryRef.current[direction] = true;
+      } else if (result === 'applied') {
+        exhaustedBoundaryRef.current[direction] = false;
+      }
+      // Nothing was prepended, so the window sitting at the boundary is still
+      // the reader's own position rather than a consequence of this page.
+      if (result !== 'applied') {
+        boundaryArmedRef.current[direction] = true;
+      }
+    }).finally(() => {
+      boundaryRequestRef.current[direction] = null;
+    });
+    boundaryRequestRef.current[direction] = request;
   }, [
-    activeSessionId,
-    footerHeightPx,
-    initialHistoryTransitionState,
-    latestTurnId,
+    isFollowingOutputNow,
+    isOpeningViewport,
+    onHistoryWindowBoundaryIntent,
     presentationMode,
-    scheduleHistoryProjectionHandoffRelease,
+    viewportId,
     virtualItems.length,
   ]);
-  useLayoutEffect(() => {
-    if (!activeSessionId || !latestTurnId || virtualItems.length === 0) {
-      return;
-    }
-
-    if (!isTurnTextRenderedInViewportOutsideHandoff(latestTurnId)) {
-      return;
-    }
 
+  /**
+   * Whether either end of the loaded transcript is on screen, and act on it.
+   *
+   * Reads live geometry rather than the rendered window. The window carries
+   * overscan and, for a transcript short enough to render whole, reports the
+   * first and last item as present wherever the viewport is — which makes it
+   * mute on the only question being asked. Measured: a 21-item transcript
+   * rendered 21 rows from index 0 no matter where the reader stood, so the
+   * head boundary read as reached forever and the tail never re-armed.
+   *
+   * A scroll moves the viewport across the window without changing it, so this
+   * has to be a callback that both the scroll handler and the item-change
+   * effect can invoke, rather than a value either of them derives.
+   */
+  const readHistoryBoundaryProximity = useCallback((): HistoryBoundaryProximity | null => {
     const scroller = scrollerElementRef.current;
-    if (!scroller) {
+    if (!scroller) return null;
+    const head = virtualizer.getItemBounds(0);
+    const tail = virtualizer.getItemBounds(virtualItems.length - 1);
+    if (!head || !tail) return null;
+    return {
+      aboveViewportPx: scroller.scrollTop - head.startPx,
+      belowViewportPx: tail.endPx - (scroller.scrollTop + scroller.clientHeight),
+      viewportHeightPx: scroller.clientHeight,
+    };
+  }, [virtualItems.length, virtualizer]);
+
+  const evaluateHistoryBoundaries = useCallback(() => {
+    const range = virtualizer.getVisibleItemRange();
+    if (!range) {
+      /*
+       * No row intersects the viewport, so there is no reader position to
+       * derive a boundary from. That is a real state and not a degenerate one:
+       * a transcript shorter than the viewport puts the whole scroll range
+       * inside the reserved blank, and the bottom of it shows no Turn at all.
+       *
+       * Traced because the silence was the hard part to read. A session stuck
+       * here logged nothing for seven seconds while the reader kept scrolling,
+       * and the only way to tell "nobody asked" from "the ask was refused" was
+       * the absence of an anchor capture.
+       */
+      traceViewportRepeating('paging|no-visible-range', {
+        location: 'historyPaging.noVisibleRange',
+        message: 'no row is in the viewport, so there is no boundary to judge',
+        data: () => ({
+          itemCount: virtualItems.length,
+          scrollTopPx: roundViewportPx(scrollerElementRef.current?.scrollTop ?? 0),
+        }),
+      });
       return;
     }
-
-    const tailStartIndex = Math.max(0, virtualItems.length - SESSION_OPEN_HANDOFF_ITEM_BUDGET);
-    latestVisibleHistoryTailSnapshotRef.current = {
-      sessionId: activeSessionId,
-      reason: 'latest-visible-history-tail',
-      createdAtMs: performance.now(),
-      items: virtualItems.slice(tailStartIndex),
-      mode: 'bottom-tail',
-      targetTurnId: latestTurnId,
-      footerHeightPx,
-    };
+    /*
+     * Two answers, and the latch takes the narrower one.
+     *
+     * `reached` is where the reader actually is; `asking` adds the screenful of
+     * lead. Arming from `asking` walls the latch shut, because a boundary that
+     * counts as reached from a screen away is one the reader is never off:
+     * measured, one page fetched and then `not-rearmed` for the next six
+     * minutes while they kept scrolling into it.
+     *
+     * Re-arming and asking in the same pass is the point rather than an
+     * oversight — "the reader is not on the boundary, and is a screen from it"
+     * is exactly the state the lead exists to serve.
+     */
+    const reached = new Set(historyBoundariesReached(
+      range,
+      virtualItems.length,
+      presentationMode,
+    ));
+    const asking = new Set(historyBoundariesForVisibleRange(
+      range,
+      virtualItems.length,
+      presentationMode,
+      readHistoryBoundaryProximity(),
+    ));
+    for (const direction of HISTORY_WINDOW_DIRECTIONS) {
+      // Off the boundary: whatever the last page added has been absorbed, and
+      // arriving there again will be the reader's own doing.
+      if (!reached.has(direction)) {
+        boundaryArmedRef.current[direction] = true;
+      }
+      if (asking.has(direction)) requestHistoryBoundary(direction);
+    }
   }, [
-    activeSessionId,
-    footerHeightPx,
-    isTurnTextRenderedInViewportOutsideHandoff,
-    latestTurnId,
-    virtualItems,
-  ]);
-  const initialHistoryRenderWindow = React.useMemo(() => {
-    return selectInitialHistoryRenderWindow(virtualItems);
-  }, [virtualItems]);
-  const initialHistoryRenderKey = [
-    activeSessionId ?? 'no-active-session',
-    latestTurnId ?? 'no-latest-turn',
+    presentationMode,
+    readHistoryBoundaryProximity,
+    requestHistoryBoundary,
     virtualItems.length,
-    initialHistoryRenderWindow.startIndex,
-  ].join(':');
-  const initialHistorySnapshot = React.useMemo<HistoryProjectionHandoffSnapshot | null>(() => {
-    if (
-      !initialHistorySnapshotActive
-      || !useInitialHistoryRenderBudget
-      || !activeSessionId
-      || !latestTurnId
-      || initialHistoryRenderWindow.items.length === 0
-    ) {
-      return null;
-    }
+    virtualizer,
+  ]);
 
-    return {
-      sessionId: activeSessionId,
-      reason: 'initial-history-snapshot',
-      createdAtMs: initialHistorySnapshotCreatedAtMsRef.current,
-      items: initialHistoryRenderWindow.items,
-      mode: 'bottom-tail',
-      targetTurnId: preparedHistoryTurnPinRef.current?.turnId ?? latestTurnId,
-      footerHeightPx,
-    };
+  evaluateHistoryBoundariesRef.current = evaluateHistoryBoundaries;
+
+  useEffect(() => {
+    scheduleVisibleTurnInfoUpdate();
+    evaluateHistoryBoundaries();
   }, [
-    activeSessionId,
-    footerHeightPx,
-    initialHistoryRenderWindow.items,
-    initialHistorySnapshotActive,
-    latestTurnId,
-    useInitialHistoryRenderBudget,
+    evaluateHistoryBoundaries,
+    /*
+     * Follow-output releasing the viewport is a reason to ask again, not only a
+     * reason the last ask was declined.
+     */
+    isFollowingOutput,
+    /*
+     * And so is the transcript finishing its opening placement, for the same
+     * reason: the ask that the reveal refused above is owed a second chance,
+     * and this is the only thing that changes when the reveal ends. A session
+     * whose loaded tail is shorter than one viewport produces no scroll events
+     * at all — it has nowhere to scroll — so without this it would never page
+     * its older Turns in until the reader spun the wheel against a boundary
+     * that could not move.
+     */
+    isOpenViewportSettled,
+    scheduleVisibleTurnInfoUpdate,
+    virtualizer.rows,
   ]);
+
   useLayoutEffect(() => {
-    if (!initialHistorySnapshot) {
-      if (initialHistorySnapshotActive && !useInitialHistoryRenderBudget) {
-        setInitialHistorySnapshotActive(false);
-      }
-      return;
-    }
+    scheduleVisibleTurnInfoUpdate();
+  }, [scheduleVisibleTurnInfoUpdate, virtualItems]);
 
-    historyProjectionHandoffRef.current = initialHistorySnapshot;
-    setHistoryProjectionHandoff(initialHistorySnapshot);
-    setInitialHistorySnapshotActive(false);
-    if (markedInitialHistoryRenderWindowKeyRef.current !== initialHistoryRenderKey) {
-      markedInitialHistoryRenderWindowKeyRef.current = initialHistoryRenderKey;
-      startupTrace.markPhase('flowchat_initial_history_snapshot_activated', {
-        sessionId: activeSessionId,
-        startIndex: initialHistoryRenderWindow.startIndex,
-        renderedItemCount: initialHistoryRenderWindow.items.length,
-        totalItemCount: virtualItems.length,
-      });
+  useEffect(() => {
+    if (userMessageItems.length === 0) {
+      useModernFlowChatStore.getState().setVisibleTurnInfo(null);
     }
-    scheduleHistoryProjectionHandoffRelease(3);
-  }, [
-    activeSessionId,
-    initialHistoryRenderKey,
-    initialHistoryRenderWindow.items.length,
-    initialHistoryRenderWindow.startIndex,
-    initialHistorySnapshot,
-    initialHistorySnapshotActive,
-    scheduleHistoryProjectionHandoffRelease,
-    useInitialHistoryRenderBudget,
-    virtualItems.length,
-  ]);
-  const sessionOpenProjectionHandoff = React.useMemo<HistoryProjectionHandoffSnapshot | null>(() => {
-    const previousActiveSessionId = previousActiveSessionIdForOpenHandoffRef.current;
-    const isSessionSwitch = (
-      previousActiveSessionId !== undefined &&
-      previousActiveSessionId !== activeSessionId
-    );
+  }, [userMessageItems.length]);
 
-    if (
-      !activeSessionId ||
-      !isSessionSwitch ||
-      activeSession?.historyState !== 'ready' ||
-      activeSession?.isPartial === true ||
-      !latestTurnId ||
-      virtualItems.length < SESSION_OPEN_HANDOFF_ITEM_BUDGET ||
-      sessionOpenHandoffSessionIdRef.current === activeSessionId ||
-      historyProjectionHandoff?.sessionId === activeSessionId
-    ) {
-      return null;
+  const handleScrollerRef = useCallback((element: HTMLElement | null) => {
+    const scroller = element;
+    scrollerElementRef.current = scroller;
+    setScrollerElement(scroller);
+    if (scroller) {
+      if (!scroller.hasAttribute('tabindex')) {
+        scroller.tabIndex = -1;
+      }
+      setViewportHeightPx(scroller.clientHeight);
+      // Seed the box so the observer's first callback is not read as a resize.
+      observedViewportBoxRef.current = {
+        width: scroller.clientWidth,
+        height: scroller.clientHeight,
+      };
     }
+  }, []);
 
-    const budgetStartIndex = Math.max(0, virtualItems.length - SESSION_OPEN_HANDOFF_ITEM_BUDGET);
-    const latestStartIndex = Math.max(0, Math.min(latestUserMessageIndex, virtualItems.length - 1));
-    const startIndex = Math.min(budgetStartIndex, latestStartIndex);
-    const items = virtualItems.slice(startIndex);
-    if (items.length === 0) {
-      return null;
-    }
+  const scrollToPhysicalBottom = useCallback(() => {
+    enterFollowOutput('jump-to-latest');
+    updateIsAtBottom();
+  }, [enterFollowOutput, updateIsAtBottom]);
 
-    return {
-      sessionId: activeSessionId,
-      reason: 'session-open',
-      createdAtMs: performance.now(),
-      items,
-      mode: 'bottom-tail',
-      targetTurnId: latestTurnId,
-      footerHeightPx,
-    };
-  }, [
-    activeSession?.historyState,
-    activeSession?.isPartial,
-    activeSessionId,
-    footerHeightPx,
-    historyProjectionHandoff?.sessionId,
-    latestTurnId,
-    latestUserMessageIndex,
-    virtualItems,
-  ]);
-  useLayoutEffect(() => {
-    if (
-      !sessionOpenProjectionHandoff ||
-      sessionOpenHandoffSessionIdRef.current === sessionOpenProjectionHandoff.sessionId
-    ) {
-      return;
-    }
+  const scrollToLatestEndPosition = useCallback(() => {
+    onUserScrollIntent?.();
+    enterFollowOutput('jump-to-latest');
+    // Entering follow can leave the viewport exactly where it is, which
+    // produces no scroll event to recompute the band from.
+    updateIsAtBottom();
+  }, [enterFollowOutput, onUserScrollIntent, updateIsAtBottom]);
 
-    historyProjectionHandoffRef.current = sessionOpenProjectionHandoff;
-    sessionOpenHandoffSessionIdRef.current = sessionOpenProjectionHandoff.sessionId;
-    setHistoryProjectionHandoff(sessionOpenProjectionHandoff);
-    startupTrace.markPhase('flowchat_history_projection_handoff_activated', {
-      sessionId: sessionOpenProjectionHandoff.sessionId,
-      reason: sessionOpenProjectionHandoff.reason,
-      previousItemCount: 0,
-      nextItemCount: virtualItems.length,
-    });
-    // Use a longer initial delay (5 frames).  rangeChanged accelerations
-    // have been removed so the handoff is only released once the Virtuoso
-    // has had enough time to measure and position items, preventing a
-    // blank viewport ("white screen") on session switches.
-    scheduleHistoryProjectionHandoffRelease(5);
-  }, [
-    scheduleHistoryProjectionHandoffRelease,
-    sessionOpenProjectionHandoff,
-    virtualItems.length,
+  useImperativeHandle(ref, () => ({
+    scrollToTurn,
+    scrollToIndex,
+    scrollToSearchMatch,
+    clearSearchMatch,
+    scrollToPhysicalBottom,
+    scrollToTurnEnd,
+    isTurnRenderedInViewport,
+    isTurnTextRenderedInViewport,
+    scrollToLatestEndPosition,
+    navigateToTurn,
+    navigateToTurnWithStatus,
+    prepareTurnNavigation,
+    focusFlowItem,
+  }), [
+    clearSearchMatch,
+    focusFlowItem,
+    isTurnRenderedInViewport,
+    isTurnTextRenderedInViewport,
+    navigateToTurn,
+    navigateToTurnWithStatus,
+    prepareTurnNavigation,
+    scrollToIndex,
+    scrollToLatestEndPosition,
+    scrollToPhysicalBottom,
+    scrollToSearchMatch,
+    scrollToTurn,
+    scrollToTurnEnd,
   ]);
-  useLayoutEffect(() => {
-    previousActiveSessionIdForOpenHandoffRef.current = activeSessionId;
-  }, [activeSessionId]);
-  const activeHistoryProjectionHandoff = presentationMode === 'history-window'
-    ? null
-    : activeSessionHistoryProjectionHandoff(historyProjectionHandoff, activeSessionId) ??
-      activeSessionHistoryProjectionHandoff(sessionOpenProjectionHandoff, activeSessionId) ??
-      activeSessionHistoryProjectionHandoff(initialHistorySnapshot, activeSessionId);
-  const hasCompactHistoricalProjection = virtualItems.length >= 6 && virtualItems
-    .slice(-16)
-    .every(item =>
-      item.type === 'user-message' ||
-      item.type === 'user-steering-message' ||
-      item.type === 'turn-completion-notice' ||
-      item.type === 'turn-failure-notice' ||
-      item.type === 'explore-group'
-    );
-  const hasInitialHistoryModelRoundProjection =
-    useInitialHistoryRenderBudget &&
-    virtualItems.slice(-16).some(item => item.type === 'model-round');
-  const defaultItemHeight = getVirtualMessageDefaultItemHeight({
-    isHistorical: activeSession?.isHistorical === true,
-    hasCompactHistoricalProjection,
-    hasInitialHistoryModelRoundProjection,
-  });
-  const initialHistoryHeightEstimates = React.useMemo(
-    () => useInitialHistoryRenderBudget
-      ? virtualItems.map(estimateVirtualMessageItemHeight)
-      : undefined,
-    [useInitialHistoryRenderBudget, virtualItems],
-  );
-  const previousHistoryBoundaryStatusNode = React.useMemo(
-    () => previousHistoryBoundaryStatus?.sessionId === activeSessionId && (
-      previousHistoryBoundaryStatus.state === 'not-ready' || !historyPagingActive
-    ) ? (
-      <div
-        className="virtual-message-list__history-boundary-status"
-        data-history-boundary-status={previousHistoryBoundaryStatus.state}
-        role="status"
-        aria-live="polite"
-       data-bf-component="virtual-message-list" data-bf-part="boundaryStatus" data-bf-state={previousHistoryBoundaryStatus.state === 'preparing' ? 'preparing' : 'unavailable'}>
-        {previousHistoryBoundaryStatus.state === 'preparing'
-          ? t('historyState.preparingOlderHistory')
-          : t('historyState.olderHistoryNotReady')}
-      </div>
-    ) : null,
-    [activeSessionId, historyPagingActive, previousHistoryBoundaryStatus, t],
-  );
-  const historyPagingSentinelNode = React.useMemo(
-    () => (
-      presentationMode === 'tail'
-      && historyPagingActive
-      && activeSession?.isPartial === true
-    ) ? (
-      <FlowChatHistoryPagingSentinel
-        state={historyPagingLoading ? 'loading' : 'idle'}
-        label={t('historyState.preparingOlderHistory')}
-      />
-    ) : null,
-    [activeSession?.isPartial, historyPagingActive, historyPagingLoading, presentationMode, t],
-  );
-  const previousHistoryWindowSentinelNode = React.useMemo(() => {
-    if (presentationMode !== 'history-window' || historyBoundaryState.before === 'idle') {
-      return null;
+
+  const visibleTurnInfo = useModernFlowChatStore(state => state.visibleTurnInfo);
+  const handleJumpToCurrentTurn = useCallback(() => {
+    if (visibleTurnInfo?.turnId) {
+      navigateToTurn(visibleTurnInfo.turnId, {
+        behavior: getMotionAwareScrollBehavior('smooth'),
+      });
     }
-    return (
+  }, [navigateToTurn, visibleTurnInfo?.turnId]);
+  const { shouldShowButton: shouldShowTurnHeaderButton, handleClick: handleTurnHeaderClick } =
+    useScrollToTurnHeader({
+      scrollerRef: scrollerElementRef,
+      currentTurnId: visibleTurnInfo?.turnId ?? null,
+      currentTurnIndex: visibleTurnInfo?.turnIndex ?? 0,
+      visibleTurnInfo,
+      onJumpToCurrentTurn: handleJumpToCurrentTurn,
+    });
+  const previousHistoryBoundaryStatusNode = useMemo(() => (
+    historyBoundaryState.before !== 'idle' ? (
       <FlowChatHistoryPagingSentinel
         state={historyBoundaryState.before}
         label={historyBoundaryState.before === 'error'
           ? t('historyState.olderHistoryNotReady')
           : t('historyState.preparingOlderHistory')}
       />
-    );
-  }, [historyBoundaryState.before, presentationMode, t]);
-  const nextHistoryWindowSentinelNode = React.useMemo(() => {
-    if (presentationMode !== 'history-window' || historyBoundaryState.after === 'idle') {
-      return null;
-    }
-    return (
+    ) : null
+  ), [historyBoundaryState.before, t]);
+  const nextHistoryBoundaryStatusNode = useMemo(() => (
+    presentationMode === 'history-window' && historyBoundaryState.after !== 'idle' ? (
       <FlowChatHistoryPagingSentinel
         state={historyBoundaryState.after}
-        label={t('historyState.loadingDescription')}
+        /*
+         * By state, like the boundary above it. One label for both read as
+         * history being prepared forever whenever a page failed, which is the
+         * one case where the reader is owed the opposite of "hold on".
+         */
+        label={historyBoundaryState.after === 'error'
+          ? t('historyState.newerHistoryNotReady')
+          : t('historyState.loadingDescription')}
       />
-    );
-  }, [historyBoundaryState.after, presentationMode, t]);
-  const virtuosoContext = React.useMemo<FlowChatVirtuosoContext>(() => ({
-    // Reservation pixels are applied imperatively to the stable Footer node.
-    // Keeping them out of context prevents a measurement-sensitive Virtuoso
-    // render for every compensation update.
-    footerRef: handleFooterElementRef,
-    previousHistoryBoundaryStatusNode: <>
-      {previousHistoryWindowSentinelNode}
-      {historyPagingSentinelNode}
-      {previousHistoryBoundaryStatusNode}
-    </>,
-    nextHistoryBoundaryStatusNode: nextHistoryWindowSentinelNode,
-    runtimeStatusSessionId: activeSessionId,
-  }), [
-    activeSessionId,
-    handleFooterElementRef,
-    historyPagingSentinelNode,
-    nextHistoryWindowSentinelNode,
-    previousHistoryWindowSentinelNode,
-    previousHistoryBoundaryStatusNode,
-  ]);
-  const computeVirtuosoItemKey = useCallback((_: number, item: VirtualItem) => (
-    `${activeSessionId ?? 'no-active-session'}:${getVirtualItemStableKey(item)}`
-  ), [activeSessionId]);
-  const renderVirtuosoItem = useCallback((index: number, item: VirtualItem) => (
-    <VirtualItemRenderer
-      item={item}
-      index={index - virtuosoFirstItemIndex}
-    />
-  ), [virtuosoFirstItemIndex]);
-  // ── Render ────────────────────────────────────────────────────────────
+    ) : null
+  ), [historyBoundaryState.after, presentationMode, t]);
+
   if (virtualItems.length === 0) {
     return (
       <div
@@ -7370,96 +2084,61 @@ const VirtualMessageListSession = forwardRef<VirtualMessageListRef, VirtualMessa
       data-presentation-mode={presentationMode}
       data-viewport-mode={viewportMode}
       data-streaming-output={isStreamingOutput ? 'true' : 'false'}
+      data-open-viewport-settled={isOpenViewportSettled ? 'true' : 'false'}
     >
-      <Virtuoso
-        key={activeSessionId ?? 'no-active-session'}
-        ref={virtuosoRef}
-        data={virtualItems}
-        computeItemKey={computeVirtuosoItemKey}
-        itemContent={renderVirtuosoItem}
-        followOutput={false}
-
-        alignToBottom={false}
-        firstItemIndex={virtuosoFirstItemIndex}
-        // New mounts start near the latest user turn to avoid flashing older
-        // content before sticky pin logic can finish.
-        initialTopMostItemIndex={initialTopMostItemIndex}
-        overscan={FLOW_CHAT_VIRTUOSO_OVERSCAN}
-
-        atBottomThreshold={50}
-        atBottomStateChange={handleAtBottomStateChange}
-
-        rangeChanged={handleRangeChanged}
-
-        // Historical sessions often restore into compact user/explore rows.
-        // Keep live sessions on the legacy estimate because active assistant
-        // output can be much taller while streaming.
-        defaultItemHeight={defaultItemHeight}
-        heightEstimates={initialHistoryHeightEstimates}
-
-        increaseViewportBy={virtuosoViewportIncrease}
-
-        scrollerRef={handleScrollerRef}
-        context={virtuosoContext}
-        components={FLOW_CHAT_VIRTUOSO_COMPONENTS}
-      />
-
-      {activeHistoryProjectionHandoff ? (
+      <div
+        ref={handleScrollerRef}
+        className="virtual-message-list__scroller"
+        data-flowchat-scroller="true"
+        data-testid="flowchat-scroller"
+      >
+        <FlowChatListHeader
+          ref={headerElementRef}
+          previousHistoryBoundaryStatusNode={previousHistoryBoundaryStatusNode}
+        />
+        {/*
+          The window of rendered items, with the rest of the transcript standing
+          in as padding above and below. Items stay in normal flow so that one
+          growing reflows the ones under it in the same layout pass.
+        */}
         <div
-          className="virtual-message-list__projection-handoff-overlay"
+          className="virtual-message-list__items"
           data-bf-component="virtual-message-list"
-          data-bf-part="handoffOverlay"
-          data-history-projection-handoff="true"
-          data-initial-history-snapshot={
-            activeHistoryProjectionHandoff.reason === 'initial-history-snapshot' ? 'true' : 'false'
-          }
-          data-session-id={activeHistoryProjectionHandoff.sessionId}
-          data-target-turn-id={activeHistoryProjectionHandoff.targetTurnId ?? ''}
-          aria-hidden="true"
+          data-bf-part="items"
+          data-testid="flowchat-item-list"
+          style={{
+            paddingTop: `${virtualizer.paddingTopPx}px`,
+            paddingBottom: `${virtualizer.paddingBottomPx}px`,
+          }}
         >
-          <div
-            className="virtual-message-list__projection-handoff-content virtual-message-list__projection-handoff-content--bottom"
-            data-bf-component="virtual-message-list"
-            data-bf-part="handoffContent"
-          >
-            <div className="message-list-header" data-bf-component="virtual-message-list" data-bf-part="header" />
-            <div className="virtual-message-list__projection-handoff-items" data-bf-component="virtual-message-list" data-bf-part="items">
-              {activeHistoryProjectionHandoff.items.map((item, index) => (
-                <VirtualItemRenderer
-                  key={`history-projection-handoff:${activeHistoryProjectionHandoff.sessionId}:${getVirtualItemStableKey(item)}`}
-                  item={item}
-                  index={index}
-                />
-              ))}
-            </div>
-            <div
-              className="message-list-footer"
-              data-bf-component="virtual-message-list"
-              data-bf-part="footer"
-              style={{
-                height: `${activeHistoryProjectionHandoff.footerHeightPx}px`,
-                minHeight: `${activeHistoryProjectionHandoff.footerHeightPx}px`,
-              }}
+          {virtualizer.rows.map(row => (
+            <VirtualItemRenderer
+              key={row.key}
+              item={virtualItems[row.index]}
+              index={row.index}
+              measureRef={virtualizer.measureRowElement}
             />
-          </div>
+          ))}
         </div>
-      ) : null}
+        <FlowChatListFooter
+          bottomLayoutInsetPx={bottomLayoutInsetPx}
+          tailSpacerPx={tailSpacerPx}
+          nextHistoryBoundaryStatusNode={nextHistoryBoundaryStatusNode}
+          runtimeStatusSessionId={activeSessionId}
+        />
+      </div>
 
       <ScrollToTurnHeaderButton
         visible={shouldShowTurnHeaderButton}
         onClick={handleTurnHeaderClick}
         turnLabel={visibleTurnInfo ? `Turn ${visibleTurnInfo.turnIndex}` : undefined}
       />
-
-      <StickyTaskIndicator
-        visible={!!visibleTaskInfo}
-        taskInfo={visibleTaskInfo}
-        onClick={scrollToTask}
-      />
-
       <ScrollToLatestBar
         visible={(viewportMode === 'history-reading' || !isAtBottom) && virtualItems.length > 0}
-        onClick={handleScrollToLatestRequest}
+        onClick={viewportMode === 'history-reading' && onRequestJumpToLatest
+          ? onRequestJumpToLatest
+          : scrollToLatestEndPosition}
+        focusReturnRef={scrollerElementRef}
         isInputActive={isInputActive}
         isInputExpanded={isInputExpanded}
         inputHeight={inputHeight}
@@ -7472,9 +2151,7 @@ VirtualMessageListSession.displayName = 'VirtualMessageListSession';
 
 export const VirtualMessageList = forwardRef<VirtualMessageListRef, VirtualMessageListProps>((props, ref) => {
   const activeSession = useActiveSession();
-  const sessionKey = activeSession?.sessionId ?? 'no-active-session';
-
-  return <VirtualMessageListSession key={sessionKey} ref={ref} {...props} />;
+  return <VirtualMessageListSession key={activeSession?.sessionId ?? 'no-active-session'} ref={ref} {...props} />;
 });
 
 VirtualMessageList.displayName = 'VirtualMessageList';
diff --git a/src/web-ui/src/flow_chat/components/modern/appearance.ts b/src/web-ui/src/flow_chat/components/modern/appearance.ts
index 80e2c6af15..2245580aa5 100644
--- a/src/web-ui/src/flow_chat/components/modern/appearance.ts
+++ b/src/web-ui/src/flow_chat/components/modern/appearance.ts
@@ -10,8 +10,7 @@ export const virtualMessageListAppearanceDescriptor: AppearanceSurfaceDescriptor
     { id: 'boundaryStatus' },
     { id: 'items' },
     { id: 'footer' },
-    { id: 'handoffOverlay' },
-    { id: 'handoffContent' },
+    { id: 'tailSpacer' },
   ],
   states: [
     { id: 'empty', selector: { kind: 'self', suffix: '[data-bf-state~="empty"]' } },
diff --git a/src/web-ui/src/flow_chat/components/modern/flowChatCollapseMotion.test.ts b/src/web-ui/src/flow_chat/components/modern/flowChatCollapseMotion.test.ts
index 4e0a7c1a10..822e246e0b 100644
--- a/src/web-ui/src/flow_chat/components/modern/flowChatCollapseMotion.test.ts
+++ b/src/web-ui/src/flow_chat/components/modern/flowChatCollapseMotion.test.ts
@@ -1,15 +1,13 @@
 import { describe, expect, it } from 'vitest';
 
 import {
-  FLOWCHAT_AUTO_COLLAPSE_SETTLE_FRAMES,
   FLOWCHAT_COLLAPSE_DURATION_MS,
-  FLOWCHAT_COLLAPSE_INTENT_TTL_MS,
+  FLOWCHAT_COLLAPSE_EASING,
 } from './flowChatCollapseMotion';
 
 describe('flowChatCollapseMotion', () => {
-  it('keeps intent TTL above the animated collapse window', () => {
+  it('keeps automatic and manual collapse motion aligned', () => {
     expect(FLOWCHAT_COLLAPSE_DURATION_MS).toBe(300);
-    expect(FLOWCHAT_AUTO_COLLAPSE_SETTLE_FRAMES).toBeGreaterThan(0);
-    expect(FLOWCHAT_COLLAPSE_INTENT_TTL_MS).toBeGreaterThan(FLOWCHAT_COLLAPSE_DURATION_MS);
+    expect(FLOWCHAT_COLLAPSE_EASING).toContain('cubic-bezier');
   });
 });
diff --git a/src/web-ui/src/flow_chat/components/modern/flowChatCollapseMotion.ts b/src/web-ui/src/flow_chat/components/modern/flowChatCollapseMotion.ts
index 64a640dadf..418e2c2035 100644
--- a/src/web-ui/src/flow_chat/components/modern/flowChatCollapseMotion.ts
+++ b/src/web-ui/src/flow_chat/components/modern/flowChatCollapseMotion.ts
@@ -1,16 +1,9 @@
 /**
  * Shared FlowChat collapse / expand motion contract.
  *
- * Auto-collapse and manual toggles share one duration so VirtualMessageList
- * collapse-intent protection can cover the full animated height change.
+ * Auto-collapse and manual toggles share one local animation duration.
  */
 
 export const FLOWCHAT_COLLAPSE_DURATION_MS = 300;
 
 export const FLOWCHAT_COLLAPSE_EASING = 'cubic-bezier(0.4, 0, 0.2, 1)';
-
-/** Extra rAF frames after the CSS duration before finalizing an auto collapse intent. */
-export const FLOWCHAT_AUTO_COLLAPSE_SETTLE_FRAMES = 4;
-
-/** Hard backup TTL; must stay above duration + settle margin. */
-export const FLOWCHAT_COLLAPSE_INTENT_TTL_MS = 1000;
diff --git a/src/web-ui/src/flow_chat/components/modern/flowChatFocusTarget.ts b/src/web-ui/src/flow_chat/components/modern/flowChatFocusTarget.ts
index d2455687df..be6d5b9b9e 100644
--- a/src/web-ui/src/flow_chat/components/modern/flowChatFocusTarget.ts
+++ b/src/web-ui/src/flow_chat/components/modern/flowChatFocusTarget.ts
@@ -13,7 +13,7 @@ export interface ResolvedFocusTarget {
   resolvedTurnIndex?: number;
   focusItemId?: string;
   expandExploreGroupId?: string;
-  preferPinnedTurnNavigation: boolean;
+  preferTurnNavigation: boolean;
 }
 
 export function resolveFlowChatFocusTarget(
@@ -74,6 +74,6 @@ export function resolveFlowChatFocusTarget(
     resolvedTurnIndex,
     focusItemId: itemId,
     expandExploreGroupId,
-    preferPinnedTurnNavigation: source === 'btw-back',
+    preferTurnNavigation: source === 'btw-back',
   };
 }
diff --git a/src/web-ui/src/flow_chat/components/modern/flowChatHistoryBoundary.test.ts b/src/web-ui/src/flow_chat/components/modern/flowChatHistoryBoundary.test.ts
new file mode 100644
index 0000000000..cb690173b1
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/modern/flowChatHistoryBoundary.test.ts
@@ -0,0 +1,174 @@
+import { describe, expect, it } from 'vitest';
+import {
+  HISTORY_BOUNDARY_LEAD_SCREENS,
+  historyBoundariesForVisibleRange,
+  historyBoundariesReached,
+} from './flowChatHistoryBoundary';
+
+const ITEM_COUNT = 40;
+const VIEWPORT_PX = 600;
+const LEAD_PX = VIEWPORT_PX * HISTORY_BOUNDARY_LEAD_SCREENS;
+
+/** Far enough from both ends that only the argument under test can decide. */
+function proximity(overrides: { aboveViewportPx?: number; belowViewportPx?: number }) {
+  return {
+    aboveViewportPx: LEAD_PX * 10,
+    belowViewportPx: LEAD_PX * 10,
+    viewportHeightPx: VIEWPORT_PX,
+    ...overrides,
+  };
+}
+
+describe('historyBoundariesForVisibleRange', () => {
+  it('asks for nothing from the middle of the window', () => {
+    expect(historyBoundariesForVisibleRange(
+      { startIndex: 12, endIndex: 20 },
+      ITEM_COUNT,
+      'history-window',
+    )).toEqual([]);
+  });
+
+  it('reaches for older Turns before the leading item is alone on screen', () => {
+    // One item of slack: the leading item is a user message a couple of dozen
+    // pixels tall, so waiting for index 0 would start the fetch after the blank.
+    expect(historyBoundariesForVisibleRange({ startIndex: 1, endIndex: 9 }, ITEM_COUNT, 'tail'))
+      .toEqual(['before']);
+    expect(historyBoundariesForVisibleRange({ startIndex: 2, endIndex: 9 }, ITEM_COUNT, 'tail'))
+      .toEqual([]);
+  });
+
+  it('reaches for newer Turns near the end of a history window', () => {
+    expect(historyBoundariesForVisibleRange(
+      { startIndex: 30, endIndex: ITEM_COUNT - 2 },
+      ITEM_COUNT,
+      'history-window',
+    )).toEqual(['after']);
+    expect(historyBoundariesForVisibleRange(
+      { startIndex: 30, endIndex: ITEM_COUNT - 3 },
+      ITEM_COUNT,
+      'history-window',
+    )).toEqual([]);
+  });
+
+  it('never reaches past the end of a tail presentation', () => {
+    // A tail is already anchored to the newest Turn: there is nothing after it.
+    expect(historyBoundariesForVisibleRange(
+      { startIndex: 30, endIndex: ITEM_COUNT + 4 },
+      ITEM_COUNT,
+      'tail',
+    )).toEqual([]);
+  });
+
+  it('asks in both directions when the whole window fits on screen', () => {
+    expect(historyBoundariesForVisibleRange(
+      { startIndex: 0, endIndex: 5 },
+      6,
+      'history-window',
+    )).toEqual(['before', 'after']);
+  });
+
+  it('asks for older Turns first, so a reader scrolling up is served first', () => {
+    const [first] = historyBoundariesForVisibleRange(
+      { startIndex: 0, endIndex: 5 },
+      6,
+      'history-window',
+    );
+    expect(first).toBe('before');
+  });
+
+  describe('the lead time', () => {
+    it('reaches back a screenful before the head is on screen at all', () => {
+      // The whole point: the junction happens where the reader is not looking.
+      // The item range says the head is nowhere near, and it still asks.
+      expect(historyBoundariesForVisibleRange(
+        { startIndex: 12, endIndex: 20 },
+        ITEM_COUNT,
+        'history-window',
+        proximity({ aboveViewportPx: LEAD_PX - 1 }),
+      )).toEqual(['before']);
+    });
+
+    it('stays quiet a screenful and one pixel out', () => {
+      expect(historyBoundariesForVisibleRange(
+        { startIndex: 12, endIndex: 20 },
+        ITEM_COUNT,
+        'history-window',
+        proximity({ aboveViewportPx: LEAD_PX + 1 }),
+      )).toEqual([]);
+    });
+
+    it('reaches forward a screenful before the end of a history window', () => {
+      expect(historyBoundariesForVisibleRange(
+        { startIndex: 12, endIndex: 20 },
+        ITEM_COUNT,
+        'history-window',
+        proximity({ belowViewportPx: LEAD_PX - 1 }),
+      )).toEqual(['after']);
+    });
+
+    it('does not reach past the end of a tail, however close it is', () => {
+      expect(historyBoundariesForVisibleRange(
+        { startIndex: 12, endIndex: 20 },
+        ITEM_COUNT,
+        'tail',
+        proximity({ belowViewportPx: 0 }),
+      )).toEqual([]);
+    });
+
+    it('still answers from the item range when there is no geometry to read', () => {
+      // A boundary genuinely on screen is never missed for want of a
+      // measurement; only the lead is lost.
+      expect(historyBoundariesForVisibleRange(
+        { startIndex: 0, endIndex: 9 },
+        ITEM_COUNT,
+        'tail',
+        null,
+      )).toEqual(['before']);
+    });
+
+    it('asks once, not once per rule, when both agree', () => {
+      expect(historyBoundariesForVisibleRange(
+        { startIndex: 0, endIndex: 9 },
+        ITEM_COUNT,
+        'tail',
+        proximity({ aboveViewportPx: 0 }),
+      )).toEqual(['before']);
+    });
+  });
+});
+
+describe('historyBoundariesReached', () => {
+  /*
+   * The arming latch's question, and the reason it is a second function. The
+   * latch disarms a direction on dispatch and re-arms it when the reader is no
+   * longer at the boundary — so if "at the boundary" reached a screen out, the
+   * latch had no way back. Measured: one page fetched, then `not-rearmed`
+   * refusals for the next six minutes while the reader scrolled into a wall.
+   */
+  it('says nothing is reached from a screenful away, however keen the ask is', () => {
+    const near = proximity({ aboveViewportPx: 0, belowViewportPx: 0 });
+    const range = { startIndex: 12, endIndex: 20 };
+
+    expect(historyBoundariesForVisibleRange(range, ITEM_COUNT, 'history-window', near))
+      .toEqual(['before', 'after']);
+    expect(historyBoundariesReached(range, ITEM_COUNT, 'history-window')).toEqual([]);
+  });
+
+  it('says a boundary on screen is reached', () => {
+    expect(historyBoundariesReached({ startIndex: 1, endIndex: 9 }, ITEM_COUNT, 'tail'))
+      .toEqual(['before']);
+    expect(historyBoundariesReached(
+      { startIndex: 30, endIndex: ITEM_COUNT - 2 },
+      ITEM_COUNT,
+      'history-window',
+    )).toEqual(['after']);
+  });
+
+  it('never reports the end of a tail as reached', () => {
+    expect(historyBoundariesReached(
+      { startIndex: 30, endIndex: ITEM_COUNT + 4 },
+      ITEM_COUNT,
+      'tail',
+    )).toEqual([]);
+  });
+});
diff --git a/src/web-ui/src/flow_chat/components/modern/flowChatHistoryBoundary.ts b/src/web-ui/src/flow_chat/components/modern/flowChatHistoryBoundary.ts
new file mode 100644
index 0000000000..8897486544
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/modern/flowChatHistoryBoundary.ts
@@ -0,0 +1,152 @@
+/**
+ * When looking at the transcript should pull more of it in.
+ *
+ * This is the policy half of history paging: it decides *that* a boundary is
+ * worth asking about, from where the reader is and nothing else. Whether the
+ * ask is honoured — budgets, in-flight requests, exhausted directions — belongs
+ * to the container, and how the position was arrived at belongs to whatever is
+ * placing the items.
+ *
+ * Two questions, deliberately two functions, because one predicate cannot serve
+ * both and it was tried:
+ *
+ * - **Has the reader arrived?** `historyBoundariesReached`, from the item range
+ *   alone. This is what the container's arming latch turns on.
+ * - **Is it worth asking?** `historyBoundariesForVisibleRange`, which adds a
+ *   screenful of lead so the page lands off screen.
+ *
+ * Serving the latch from the wider answer walls it shut. The latch disarms a
+ * direction on dispatch and re-arms it when the reader is no longer at the
+ * boundary, so a boundary that counts as reached from a screen away is one the
+ * reader can never be off — measured: one page fetched, then `not-rearmed`
+ * refusals for eleven seconds while the reader kept scrolling into a wall.
+ */
+
+import type { SessionHistoryWindowDirection } from '../../store/FlowChatStore';
+
+export interface VisibleItemRange {
+  startIndex: number;
+  endIndex: number;
+}
+
+/**
+ * How close to the first item counts as reaching for older Turns.
+ *
+ * One item of slack, not zero: the leading item is a user message a couple of
+ * dozen pixels tall, so a reader who has arrived at it is already looking at
+ * the top of the window, and waiting for it to be the *only* thing on screen
+ * would start the fetch after the blank appears rather than before.
+ */
+const LEADING_ITEM_SLACK = 1;
+
+/**
+ * How close to the last item counts as reaching for newer Turns.
+ *
+ * Two items, because the trailing edge of a Turn is a model round followed by
+ * its user message, and reaching the round means the window ends within a
+ * screen or so.
+ */
+const TRAILING_ITEM_SLACK = 2;
+
+/**
+ * How far ahead of the boundary the fetch goes out, in screenfuls.
+ *
+ * A page is not a quiet event. The items arrive above the reader and everything
+ * below them moves; the virtualizer picks its window from a scroll offset it
+ * only learns from scroll events, so for one commit it renders from a position
+ * the reader has already been moved off and the transcript under them goes
+ * blank; the rows then measure and the whole thing settles a second time. All
+ * of that is correct and all of it is visible — the reader described it as a
+ * flicker and a jolt, at the junction, every time.
+ *
+ * None of it is visible if it happens off screen. Asking a screenful early puts
+ * the junction above the viewport: the reader keeps scrolling into content that
+ * is already there and already measured. It costs one page of history fetched
+ * slightly sooner than it is needed, and nothing at all on session open, where
+ * the boundary is a whole transcript away.
+ *
+ * One screen rather than two because the lead only has to outlast the fetch. At
+ * a brisk wheel scroll the reader covers a few hundred pixels in the time a
+ * page takes to arrive from local storage, and a lead longer than it needs to
+ * be just loads history nobody reaches.
+ */
+export const HISTORY_BOUNDARY_LEAD_SCREENS = 1;
+
+/**
+ * How much transcript is left between the reader and each end of what is loaded.
+ *
+ * In scroller coordinates, so these are distances the reader still has to
+ * travel — the same space `scrollTop` is in. The heights they are composed of
+ * are estimates wherever an item has not been rendered yet, which is exactly
+ * the space above a reader who is scrolling up; that makes this an honest
+ * measure of remaining scroll and a poor one of remaining content, and
+ * remaining scroll is the question.
+ */
+export interface HistoryBoundaryProximity {
+  /** From the top edge of the viewport back to the start of the first item. */
+  aboveViewportPx: number;
+  /** From the bottom edge of the viewport on to the end of the last item. */
+  belowViewportPx: number;
+  /** One screenful, which is the unit the lead is expressed in. */
+  viewportHeightPx: number;
+}
+
+/**
+ * Directions the visible range is sitting on — the reader has arrived.
+ *
+ * The arming latch's question, and only ever this one. It has to be answerable
+ * as false while the reader is still near the boundary, or a direction disarmed
+ * on dispatch has no way back.
+ *
+ * `'after'` only applies to a history window. A tail presentation is already
+ * anchored to the newest Turn, so there is nothing past its end to fetch.
+ */
+export function historyBoundariesReached(
+  range: VisibleItemRange,
+  itemCount: number,
+  presentationMode: 'tail' | 'history-window',
+): SessionHistoryWindowDirection[] {
+  const directions: SessionHistoryWindowDirection[] = [];
+  if (range.startIndex <= LEADING_ITEM_SLACK) {
+    directions.push('before');
+  }
+  if (presentationMode === 'history-window' && range.endIndex >= itemCount - TRAILING_ITEM_SLACK) {
+    directions.push('after');
+  }
+  return directions;
+}
+
+/**
+ * Directions worth asking about from where the reader stands.
+ *
+ * Everything already reached, plus everything within a screenful of being
+ * reached. Never the other way round: the lead is an argument for asking
+ * sooner, not for calling a boundary arrived at.
+ *
+ * `proximity` is null when the geometry cannot be read — no scroller, or an end
+ * of the transcript the virtualizer has no place for yet. The item range still
+ * answers, so a boundary that is genuinely on screen is never missed for want
+ * of a measurement; only the lead is lost.
+ */
+export function historyBoundariesForVisibleRange(
+  range: VisibleItemRange,
+  itemCount: number,
+  presentationMode: 'tail' | 'history-window',
+  proximity: HistoryBoundaryProximity | null = null,
+): SessionHistoryWindowDirection[] {
+  const reached = new Set(historyBoundariesReached(range, itemCount, presentationMode));
+  if (proximity === null) return [...reached];
+
+  const leadPx = Math.max(0, proximity.viewportHeightPx) * HISTORY_BOUNDARY_LEAD_SCREENS;
+  const directions: SessionHistoryWindowDirection[] = [];
+  if (reached.has('before') || proximity.aboveViewportPx <= leadPx) {
+    directions.push('before');
+  }
+  if (
+    presentationMode === 'history-window' &&
+    (reached.has('after') || proximity.belowViewportPx <= leadPx)
+  ) {
+    directions.push('after');
+  }
+  return directions;
+}
diff --git a/src/web-ui/src/flow_chat/components/modern/flowChatLiveTailWindow.test.ts b/src/web-ui/src/flow_chat/components/modern/flowChatLiveTailWindow.test.ts
new file mode 100644
index 0000000000..ad6b3648e8
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/modern/flowChatLiveTailWindow.test.ts
@@ -0,0 +1,225 @@
+import { describe, expect, it } from 'vitest';
+import {
+  resolveHistoryBoundaryTarget,
+  resolveTailBoundaryPrecondition,
+  resolveTailWindowGrowth,
+  transcriptReachesLatestTurn,
+} from './flowChatLiveTailWindow';
+
+describe('transcriptReachesLatestTurn', () => {
+  it('counts the canonical transcript, which always holds the live tail', () => {
+    expect(transcriptReachesLatestTurn({
+      windowEndOrdinalExclusive: null,
+      knownTurnCount: 28,
+    })).toBe(true);
+  });
+
+  it('counts a window paged in from the tail', () => {
+    // The window the automatic paging produces on open: it ends exactly where
+    // the session does, so the viewport on it is on the newest output.
+    expect(transcriptReachesLatestTurn({
+      windowEndOrdinalExclusive: 27,
+      knownTurnCount: 27,
+    })).toBe(true);
+  });
+
+  it('excludes a window the session has since grown past', () => {
+    expect(transcriptReachesLatestTurn({
+      windowEndOrdinalExclusive: 27,
+      knownTurnCount: 28,
+    })).toBe(false);
+  });
+
+  it('excludes a window the user navigated into the middle of', () => {
+    expect(transcriptReachesLatestTurn({
+      windowEndOrdinalExclusive: 10,
+      knownTurnCount: 28,
+    })).toBe(false);
+  });
+});
+
+describe('resolveTailWindowGrowth', () => {
+  it('remembers the end of a window that reaches the newest Turn', () => {
+    expect(resolveTailWindowGrowth({
+      windowEndOrdinalExclusive: 27,
+      knownTurnCount: 27,
+      tailAnchoredWindowEnd: null,
+    })).toBe('anchor');
+  });
+
+  it('grows the tail-anchored window when a Turn is appended', () => {
+    // Without this the newest Turn is not rendered at all: the message the user
+    // just sent is missing, and since the follow rule reads the latest Turn off
+    // the rendered items it never learns the Turn exists.
+    expect(resolveTailWindowGrowth({
+      windowEndOrdinalExclusive: 27,
+      knownTurnCount: 28,
+      tailAnchoredWindowEnd: 27,
+    })).toBe('extend');
+  });
+
+  it('keeps asking until the window is actually repaired', () => {
+    // The whole reason this is not edge-triggered. A failed extension leaves
+    // the state untouched, and the next render asks again.
+    const stillBroken = {
+      windowEndOrdinalExclusive: 27,
+      knownTurnCount: 28,
+      tailAnchoredWindowEnd: 27,
+    };
+    expect(resolveTailWindowGrowth(stillBroken)).toBe('extend');
+    expect(resolveTailWindowGrowth(stillBroken)).toBe('extend');
+  });
+
+  it('re-anchors once the window has caught up', () => {
+    expect(resolveTailWindowGrowth({
+      windowEndOrdinalExclusive: 28,
+      knownTurnCount: 28,
+      tailAnchoredWindowEnd: 27,
+    })).toBe('anchor');
+  });
+
+  it('grows again when a partial extension still falls short', () => {
+    // Two Turns arrived and the loaded range only covered one of them.
+    expect(resolveTailWindowGrowth({
+      windowEndOrdinalExclusive: 28,
+      knownTurnCount: 29,
+      tailAnchoredWindowEnd: 28,
+    })).toBe('extend');
+  });
+
+  it('leaves a window the user navigated to alone', () => {
+    // Its end is not where a tail-reaching window's end was, so the session
+    // growing says nothing about it.
+    expect(resolveTailWindowGrowth({
+      windowEndOrdinalExclusive: 10,
+      knownTurnCount: 28,
+      tailAnchoredWindowEnd: 27,
+    })).toBe('none');
+  });
+
+  it('leaves a mid-session window alone even with no anchor on record', () => {
+    expect(resolveTailWindowGrowth({
+      windowEndOrdinalExclusive: 10,
+      knownTurnCount: 28,
+      tailAnchoredWindowEnd: null,
+    })).toBe('none');
+  });
+
+  it('releases the anchor when no window is rendered', () => {
+    expect(resolveTailWindowGrowth({
+      windowEndOrdinalExclusive: null,
+      knownTurnCount: 28,
+      tailAnchoredWindowEnd: 27,
+    })).toBe('release');
+  });
+});
+
+describe('resolveHistoryBoundaryTarget', () => {
+  it('asks for the Turn before the transcript on screen', () => {
+    expect(resolveHistoryBoundaryTarget({
+      direction: 'before',
+      renderedRange: { startOrdinal: 12, endOrdinalExclusive: 24 },
+      knownTurnCount: 40,
+    })).toEqual({ status: 'ask', targetOrdinal: 11 });
+  });
+
+  it('asks for the Turn after the transcript on screen', () => {
+    expect(resolveHistoryBoundaryTarget({
+      direction: 'after',
+      renderedRange: { startOrdinal: 12, endOrdinalExclusive: 24 },
+      knownTurnCount: 40,
+    })).toEqual({ status: 'ask', targetOrdinal: 24 });
+  });
+
+  it('is exhausted at the head of the session', () => {
+    expect(resolveHistoryBoundaryTarget({
+      direction: 'before',
+      renderedRange: { startOrdinal: 0, endOrdinalExclusive: 24 },
+      knownTurnCount: 40,
+    })).toEqual({ status: 'exhausted', reason: 'reached-start' });
+  });
+
+  it('is exhausted at the newest Turn, and says which nothing that is', () => {
+    /*
+     * The reported case, in ordinals. A window paged in from the tail ended at
+     * 6 while the session had grown to 10, the continuous projection spliced
+     * the two so the transcript on screen ran to the newest Turn, and reaching
+     * its bottom asked to load ordinal 6 — a Turn already on screen, which the
+     * catalog could not resolve. 266 asks, every one answered `not-found`, and
+     * a boundary status the reader read as history being prepared forever.
+     *
+     * Judged against the rendered range there is nothing to ask for, which is
+     * the honest answer and the one that latches the direction quiet.
+     */
+    expect(resolveHistoryBoundaryTarget({
+      direction: 'after',
+      renderedRange: { startOrdinal: 0, endOrdinalExclusive: 10 },
+      knownTurnCount: 10,
+    })).toEqual({ status: 'exhausted', reason: 'reached-latest' });
+  });
+
+  it('would still ask against the window the store cut, which is the bug', () => {
+    // The same session, judged against the store's window instead of the
+    // transcript: an ordinal that is both already rendered and unresolvable.
+    expect(resolveHistoryBoundaryTarget({
+      direction: 'after',
+      renderedRange: { startOrdinal: 0, endOrdinalExclusive: 6 },
+      knownTurnCount: 10,
+    })).toEqual({ status: 'ask', targetOrdinal: 6 });
+  });
+
+  it('separates asking past the head from asking past the newest Turn', () => {
+    // Only the first is a symptom: it means Turns the session claims to have
+    // are not reachable, which is how history goes missing rather than late.
+    expect(resolveHistoryBoundaryTarget({
+      direction: 'before',
+      renderedRange: { startOrdinal: 41, endOrdinalExclusive: 48 },
+      knownTurnCount: 40,
+    })).toEqual({ status: 'exhausted', reason: 'beyond-known-total' });
+  });
+});
+
+describe('resolveTailBoundaryPrecondition', () => {
+  const ask = {
+    direction: 'before' as const,
+    isPartial: true,
+    hasSession: true,
+    turnCatalogMatches: true,
+  };
+
+  it('asks when there is history the catalog can resolve', () => {
+    expect(resolveTailBoundaryPrecondition(ask)).toBe('ask');
+  });
+
+  it('is exhausted for a session that holds every Turn it has', () => {
+    /*
+     * The treadmill this closes: 652 asks in one session, 648 answered
+     * `precondition` because the session was fully loaded and the reader was
+     * resting at its head. A cancel re-arms the direction, so the next scroll
+     * event asked again, and the next.
+     */
+    expect(resolveTailBoundaryPrecondition({ ...ask, isPartial: false })).toBe('exhausted');
+    expect(resolveTailBoundaryPrecondition({ ...ask, isPartial: undefined })).toBe('exhausted');
+  });
+
+  it('cancels below the tail rather than latch a direction that cannot re-arm', () => {
+    // True that nothing follows the canonical tail, but this is only reached
+    // through the retained continuous projection, whose bounds never change —
+    // so the latch would never be cleared again.
+    expect(resolveTailBoundaryPrecondition({ ...ask, direction: 'after' })).toBe('cancelled');
+  });
+
+  it('cancels rather than latches while the catalog is still on its way', () => {
+    // Expected to turn up, so the direction has to stay armed for it.
+    expect(resolveTailBoundaryPrecondition({ ...ask, turnCatalogMatches: false })).toBe('cancelled');
+  });
+
+  it('cancels for a session that is not in the store at all', () => {
+    // Absent is not the same fact as complete, and only one of them is final.
+    expect(resolveTailBoundaryPrecondition({
+      ...ask,
+      hasSession: false,
+      isPartial: undefined,
+    })).toBe('cancelled');
+  });
+});
diff --git a/src/web-ui/src/flow_chat/components/modern/flowChatLiveTailWindow.ts b/src/web-ui/src/flow_chat/components/modern/flowChatLiveTailWindow.ts
new file mode 100644
index 0000000000..cdf9f8c208
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/modern/flowChatLiveTailWindow.ts
@@ -0,0 +1,187 @@
+/**
+ * Where a rendered history window stands relative to the live tail.
+ *
+ * Both questions here used to be answered by the viewport intent, which was a
+ * faithful proxy only while turn navigation was the sole thing that activated a
+ * window. Automatic tail paging activates one with nobody navigating, and the
+ * proxy then reports "the user is reading history" for a viewport sitting on
+ * the newest output. These are the ordinal facts the callers actually need —
+ * ledger numbers, not measurements.
+ */
+
+export interface RenderedWindowPosition {
+  /** End of the rendered history window, or `null` when none is rendered. */
+  windowEndOrdinalExclusive: number | null;
+  /** Turns the session is known to hold, loaded or not. */
+  knownTurnCount: number;
+}
+
+/**
+ * Whether the transcript on screen still reaches the newest Turn.
+ *
+ * Rendering no window means rendering the canonical transcript, which contains
+ * the live tail by definition.
+ */
+export function transcriptReachesLatestTurn(input: RenderedWindowPosition): boolean {
+  return input.windowEndOrdinalExclusive === null
+    || input.windowEndOrdinalExclusive >= input.knownTurnCount;
+}
+
+export type TailWindowGrowthAction =
+  /** No window is rendered; forget any remembered tail anchor. */
+  | 'release'
+  /** The window reaches the newest Turn; remember its end as the tail anchor. */
+  | 'anchor'
+  /** The session grew out from under the tail-anchored window; grow it too. */
+  | 'extend'
+  /** A window that was never anchored to the tail. Leave it where it is. */
+  | 'none';
+
+export interface TailWindowGrowthInput extends RenderedWindowPosition {
+  /** End of the window last seen reaching the newest Turn, if any. */
+  tailAnchoredWindowEnd: number | null;
+}
+
+/**
+ * Decide what a rendered history window owes the live tail.
+ *
+ * This is deliberately a function of the *current* state rather than of a
+ * transition. An edge — "it reached the tail last render and does not now" — is
+ * consumed whether or not the caller managed to act on it, which strands the
+ * window permanently on a single failure. Here the answer stays `'extend'`
+ * until the window is actually repaired, so every render retries it.
+ *
+ * `tailAnchoredWindowEnd` is what separates a window paged in from the tail
+ * from one the user navigated to: only a window whose end is exactly where a
+ * tail-reaching window's end was may grow. A window sitting in the middle of
+ * the session has a different end and is left alone.
+ */
+export function resolveTailWindowGrowth(
+  input: TailWindowGrowthInput,
+): TailWindowGrowthAction {
+  if (input.windowEndOrdinalExclusive === null) {
+    return 'release';
+  }
+  if (transcriptReachesLatestTurn(input)) {
+    return 'anchor';
+  }
+  return input.tailAnchoredWindowEnd === input.windowEndOrdinalExclusive
+    ? 'extend'
+    : 'none';
+}
+
+export interface RenderedTranscriptRange {
+  startOrdinal: number;
+  endOrdinalExclusive: number;
+}
+
+export type TailBoundaryPrecondition =
+  /** The ask can be resolved against the catalog; carry on. */
+  | 'ask'
+  /** There is nothing in this direction until the presentation changes. */
+  | 'exhausted'
+  /** Not answerable *yet*, so the direction stays armed. */
+  | 'cancelled';
+
+/**
+ * Whether a boundary ask made with no history window open is worth resolving.
+ *
+ * The three answers are not interchangeable, and the difference is entirely
+ * about what happens next: `cancelled` re-arms the direction, `exhausted`
+ * latches it off until the window moves. Getting that wrong in the safe-looking
+ * direction costs a boundary that asks forever — measured, 652 asks in one
+ * session, 648 of them answered `precondition` because the session had every
+ * Turn it was ever going to have and the reader was resting at its head. Every
+ * one re-armed, and the next scroll event asked again.
+ *
+ * A session that is not partial *is* the transcript on screen, so its head is
+ * the first Turn and there is nothing before it — the same fact
+ * `resolveHistoryBoundaryTarget` reports as `reached-start`, arrived at from
+ * the ledger rather than from an ordinal.
+ *
+ * A catalog that has not arrived is the opposite case and must stay
+ * `cancelled`: nothing can be resolved against it yet, and it is expected to
+ * turn up.
+ */
+export function resolveTailBoundaryPrecondition(input: {
+  direction: 'before' | 'after';
+  /** Absent when the session is not in the store at all. */
+  isPartial: boolean | undefined;
+  hasSession: boolean;
+  turnCatalogMatches: boolean;
+}): TailBoundaryPrecondition {
+  /*
+   * `after` is deliberately not latched, even though the canonical tail ends at
+   * the newest Turn by construction.
+   *
+   * It reaches here at all only through the retained continuous projection,
+   * which renders as a history window while the viewport intent is the live
+   * tail — and the latch is cleared by the *window bounds* changing, which that
+   * projection does not have. Latching would therefore be permanent for the
+   * rest of the presentation, to save asks that are not the ones being
+   * measured: of 652 wasted asks in the reported session, 648 were `before`
+   * against a fully loaded transcript and none were this.
+   */
+  if (input.direction === 'after') {
+    return 'cancelled';
+  }
+  if (!input.hasSession) {
+    return 'cancelled';
+  }
+  if (input.isPartial !== true) {
+    return 'exhausted';
+  }
+  return input.turnCatalogMatches ? 'ask' : 'cancelled';
+}
+
+export type HistoryBoundaryTargetResolution =
+  /** The ordinal a page in this direction has to load. */
+  | { status: 'ask'; targetOrdinal: number }
+  /** There is nothing in this direction, and which nothing it is. */
+  | {
+      status: 'exhausted';
+      reason: 'reached-start' | 'reached-latest' | 'beyond-known-total';
+    };
+
+/**
+ * What paging past an edge of the transcript on screen would have to load.
+ *
+ * **The range is the one the reader is looking at, never the window the store
+ * cut.** Those are the same thing only until the continuous projection splices
+ * a window that starts at ordinal 0 with the live tail: the rendered transcript
+ * then runs to the newest Turn while the store's window still ends where it was
+ * paged in.
+ *
+ * Deriving the ask from the store's window there asks to load a Turn that is
+ * already on screen, and it fails in the worst available way. Measured: a
+ * window ending at ordinal 6 against a session of 10, projected continuous, so
+ * the reader was at the newest output; reaching the bottom asked for ordinal 6,
+ * which the *catalog* — six entries, and not extended as the session streamed —
+ * could not resolve. 266 asks in one session, every one answered `not-found`,
+ * every one leaving a boundary status the reader saw as "preparing history"
+ * over a transcript that was already complete.
+ *
+ * `reached-latest` is separated from `beyond-known-total` because only the
+ * second is a symptom. Asking past the newest Turn is what the bottom edge of a
+ * live transcript does every time the reader reaches it; asking past the known
+ * total in the *other* direction means Turns have gone missing.
+ */
+export function resolveHistoryBoundaryTarget(input: {
+  direction: 'before' | 'after';
+  renderedRange: RenderedTranscriptRange;
+  knownTurnCount: number;
+}): HistoryBoundaryTargetResolution {
+  const targetOrdinal = input.direction === 'before'
+    ? input.renderedRange.startOrdinal - 1
+    : input.renderedRange.endOrdinalExclusive;
+  if (targetOrdinal < 0) {
+    return { status: 'exhausted', reason: 'reached-start' };
+  }
+  if (targetOrdinal >= input.knownTurnCount) {
+    return {
+      status: 'exhausted',
+      reason: input.direction === 'after' ? 'reached-latest' : 'beyond-known-total',
+    };
+  }
+  return { status: 'ask', targetOrdinal };
+}
diff --git a/src/web-ui/src/flow_chat/components/modern/flowChatScrollStability.ts b/src/web-ui/src/flow_chat/components/modern/flowChatScrollStability.ts
deleted file mode 100644
index 9c06e9ff59..0000000000
--- a/src/web-ui/src/flow_chat/components/modern/flowChatScrollStability.ts
+++ /dev/null
@@ -1,659 +0,0 @@
-import type { FlowChatPinTurnToTopMode } from '../../events/flowchatNavigation';
-import type { FlowChatViewportAnchorMode } from './FlowChatViewportCoordinator';
-
-export const COMPENSATION_EPSILON_PX = 0.5;
-const FOLLOWING_TAIL_SHRINK_CLAMP_TOLERANCE_PX = 2;
-
-type BottomReservationKind = 'collapse' | 'pin';
-
-interface BottomReservationBase {
-  kind: BottomReservationKind;
-  px: number;
-  floorPx: number;
-}
-
-interface CollapseBottomReservation extends BottomReservationBase {
-  kind: 'collapse';
-}
-
-export interface PinBottomReservation extends BottomReservationBase {
-  kind: 'pin';
-  mode: FlowChatPinTurnToTopMode;
-  targetTurnId: string | null;
-}
-
-export interface BottomReservationState {
-  collapse: CollapseBottomReservation;
-  pin: PinBottomReservation;
-}
-
-export interface TurnPinRequestIdentity {
-  generation: number;
-  sessionId: string;
-  turnId: string;
-}
-
-export function isTurnPinRequestIdentityCurrent(
-  request: TurnPinRequestIdentity,
-  current: TurnPinRequestIdentity,
-): boolean {
-  return (
-    request.generation === current.generation &&
-    request.sessionId === current.sessionId &&
-    request.turnId === current.turnId
-  );
-}
-
-export function transferCollapseReservationToPin(
-  currentState: BottomReservationState,
-  nextPinReservation: PinBottomReservation,
-): BottomReservationState {
-  return {
-    ...currentState,
-    collapse: {
-      ...currentState.collapse,
-      px: 0,
-      floorPx: 0,
-    },
-    pin: nextPinReservation,
-  };
-}
-
-export function transferPinReservationToProtectedCollapse(
-  currentState: BottomReservationState,
-): BottomReservationState {
-  const transferredPx = getReservationTotalPx(currentState.pin);
-  return sanitizeBottomReservationState({
-    ...currentState,
-    collapse: {
-      ...currentState.collapse,
-      px: currentState.collapse.px + transferredPx,
-      floorPx: currentState.collapse.floorPx + transferredPx,
-    },
-    pin: {
-      kind: 'pin',
-      px: 0,
-      floorPx: 0,
-      mode: 'transient',
-      targetTurnId: null,
-    },
-  });
-}
-
-export function releasePinReservationForUserNavigation(
-  currentState: BottomReservationState,
-  options: {
-    preserveCurrentRange: boolean;
-    ownsElementAnchor: boolean;
-  },
-): BottomReservationState {
-  const isProvisionalStickyPin = (
-    currentState.pin.mode === 'sticky-latest' &&
-    currentState.pin.floorPx <= COMPENSATION_EPSILON_PX &&
-    !options.ownsElementAnchor
-  );
-  if (options.preserveCurrentRange && !isProvisionalStickyPin) {
-    return transferPinReservationToProtectedCollapse(currentState);
-  }
-
-  return sanitizeBottomReservationState({
-    ...currentState,
-    pin: {
-      kind: 'pin',
-      px: 0,
-      floorPx: 0,
-      mode: 'transient',
-      targetTurnId: null,
-    },
-  });
-}
-
-export function protectCurrentCollapseReservation(
-  currentState: BottomReservationState,
-): BottomReservationState {
-  return sanitizeBottomReservationState({
-    ...currentState,
-    collapse: {
-      ...currentState.collapse,
-      floorPx: currentState.collapse.px,
-    },
-  });
-}
-
-export function settleCollapseReservationForViewport(
-  currentState: BottomReservationState,
-  geometry: {
-    scrollTop: number;
-    scrollHeight: number;
-    clientHeight: number;
-    rangeGuardPx?: number;
-  },
-): BottomReservationState {
-  const currentTotalPx = getReservationTotalPx(currentState.collapse) +
-    getReservationTotalPx(currentState.pin);
-  const contentHeightWithoutReservation = Math.max(
-    0,
-    geometry.scrollHeight - currentTotalPx,
-  );
-  const requiredTotalPx = Math.max(
-    getRequiredTotalPxForScrollTop({
-      targetScrollTop: geometry.scrollTop,
-      contentHeightWithoutReservation,
-      clientHeight: geometry.clientHeight,
-      rangeGuardPx: geometry.rangeGuardPx,
-    }),
-  );
-  const protectedTotalPx = Math.max(
-    getReservationTotalPx(currentState.pin) + currentState.collapse.floorPx,
-    requiredTotalPx,
-  );
-  const settledTotalPx = Math.min(currentTotalPx, protectedTotalPx);
-  const settledCollapsePx = Math.max(
-    0,
-    settledTotalPx - getReservationTotalPx(currentState.pin),
-  );
-
-  return sanitizeBottomReservationState({
-    ...currentState,
-    collapse: {
-      ...currentState.collapse,
-      px: settledCollapsePx,
-      floorPx: settledCollapsePx,
-    },
-  });
-}
-
-export function ensureCollapseReservationForScrollTop(
-  currentState: BottomReservationState,
-  geometry: {
-    targetScrollTop: number;
-    scrollHeight: number;
-    clientHeight: number;
-    rangeGuardPx?: number;
-  },
-): BottomReservationState {
-  const currentPinPx = getReservationTotalPx(currentState.pin);
-  const currentCollapsePx = getReservationTotalPx(currentState.collapse);
-  const currentTotalPx = currentCollapsePx + currentPinPx;
-  const contentHeightWithoutReservation = Math.max(
-    0,
-    sanitizeReservationPx(geometry.scrollHeight) - currentTotalPx,
-  );
-  const requiredTotalPx = Math.max(
-    currentPinPx,
-    getRequiredTotalPxForScrollTop({
-      targetScrollTop: geometry.targetScrollTop,
-      contentHeightWithoutReservation,
-      clientHeight: geometry.clientHeight,
-      rangeGuardPx: geometry.rangeGuardPx,
-    }),
-  );
-  const requiredCollapsePx = Math.max(0, requiredTotalPx - currentPinPx);
-  const nextCollapsePx = Math.max(currentCollapsePx, requiredCollapsePx);
-
-  return sanitizeBottomReservationState({
-    ...currentState,
-    collapse: {
-      ...currentState.collapse,
-      px: nextCollapsePx,
-      floorPx: Math.max(currentState.collapse.floorPx, requiredCollapsePx),
-    },
-  });
-}
-
-export function settleRetainedCollapseReservationForAnchor(
-  currentState: BottomReservationState,
-  geometry: {
-    targetScrollTop: number;
-    scrollHeight: number;
-    clientHeight: number;
-    rangeGuardPx?: number;
-  },
-): BottomReservationState {
-  const currentPinPx = getReservationTotalPx(currentState.pin);
-  const currentCollapsePx = getReservationTotalPx(currentState.collapse);
-  const contentHeightWithoutReservation = Math.max(
-    0,
-    sanitizeReservationPx(geometry.scrollHeight) - currentPinPx - currentCollapsePx,
-  );
-  const requiredTotalPx = Math.max(
-    currentPinPx,
-    getRequiredTotalPxForScrollTop({
-      targetScrollTop: geometry.targetScrollTop,
-      contentHeightWithoutReservation,
-      clientHeight: geometry.clientHeight,
-      rangeGuardPx: geometry.rangeGuardPx,
-    }),
-  );
-  const requiredCollapsePx = Math.max(0, requiredTotalPx - currentPinPx);
-
-  return sanitizeBottomReservationState({
-    ...currentState,
-    collapse: {
-      ...currentState.collapse,
-      px: requiredCollapsePx,
-      floorPx: requiredCollapsePx,
-    },
-  });
-}
-
-export function reconcileUnsignaledShrinkReservation(
-  currentState: BottomReservationState,
-  fallbackRequiredCollapsePx: number,
-  hasCollapseOwner = (
-    currentState.collapse.px > COMPENSATION_EPSILON_PX ||
-    currentState.collapse.floorPx > COMPENSATION_EPSILON_PX
-  ),
-): BottomReservationState {
-  if (!hasCollapseOwner) {
-    return sanitizeBottomReservationState({
-      ...currentState,
-      collapse: {
-        ...currentState.collapse,
-        px: 0,
-        floorPx: 0,
-      },
-    });
-  }
-
-  return sanitizeBottomReservationState({
-    ...currentState,
-    collapse: {
-      ...currentState.collapse,
-      px: Math.max(
-        currentState.collapse.floorPx,
-        sanitizeReservationPx(fallbackRequiredCollapsePx),
-      ),
-    },
-  });
-}
-
-export function clampPinReservationPxToViewport(
-  reservationPx: number,
-  clientHeight: number,
-): number {
-  return Math.min(
-    sanitizeReservationPx(reservationPx),
-    sanitizeReservationPx(clientHeight),
-  );
-}
-
-export function resolveProvisionalStickyPinReservationPx(options: {
-  scrollHeight: number;
-  clientHeight: number;
-  currentPinPx: number;
-}): number {
-  const currentPinPx = sanitizeReservationPx(options.currentPinPx);
-  const effectiveScrollHeight = Math.max(
-    0,
-    sanitizeReservationPx(options.scrollHeight) - currentPinPx,
-  );
-  const effectiveMaxScrollTop = Math.max(
-    0,
-    effectiveScrollHeight - sanitizeReservationPx(options.clientHeight),
-  );
-  return clampPinReservationPxToViewport(
-    Math.max(currentPinPx, effectiveMaxScrollTop),
-    options.clientHeight,
-  );
-}
-
-export function shouldClearExpiredProvisionalStickyPin(options: {
-  requestTurnId: string;
-  requestPinMode: FlowChatPinTurnToTopMode;
-  pinReservation: PinBottomReservation;
-  ownsElementAnchor: boolean;
-}): boolean {
-  return (
-    options.requestPinMode === 'sticky-latest' &&
-    options.pinReservation.mode === 'sticky-latest' &&
-    options.pinReservation.targetTurnId === options.requestTurnId &&
-    options.pinReservation.floorPx <= COMPENSATION_EPSILON_PX &&
-    !options.ownsElementAnchor
-  );
-}
-
-export function createInitialBottomReservationState(): BottomReservationState {
-  return {
-    collapse: {
-      kind: 'collapse',
-      px: 0,
-      floorPx: 0,
-    },
-    pin: {
-      kind: 'pin',
-      px: 0,
-      floorPx: 0,
-      mode: 'transient',
-      targetTurnId: null,
-    },
-  };
-}
-
-function sanitizeReservationPx(value: number): number {
-  return Number.isFinite(value) ? Math.max(0, value) : 0;
-}
-
-function getRequiredTotalPxForScrollTop(geometry: {
-  targetScrollTop: number;
-  contentHeightWithoutReservation: number;
-  clientHeight: number;
-  rangeGuardPx?: number;
-}): number {
-  const targetScrollTop = sanitizeReservationPx(geometry.targetScrollTop);
-  if (targetScrollTop <= COMPENSATION_EPSILON_PX) {
-    return 0;
-  }
-  return Math.max(
-    0,
-    targetScrollTop +
-      sanitizeReservationPx(geometry.clientHeight) -
-      sanitizeReservationPx(geometry.contentHeightWithoutReservation) +
-      sanitizeReservationPx(geometry.rangeGuardPx ?? 1),
-  );
-}
-
-export function sanitizeBottomReservationState(state: BottomReservationState): BottomReservationState {
-  const collapsePx = sanitizeReservationPx(state.collapse.px);
-  const collapseFloorPx = Math.min(collapsePx, sanitizeReservationPx(state.collapse.floorPx));
-  const pinPx = sanitizeReservationPx(state.pin.px);
-  const pinFloorPx = Math.min(pinPx, sanitizeReservationPx(state.pin.floorPx));
-
-  return {
-    collapse: {
-      kind: 'collapse',
-      px: collapsePx,
-      floorPx: collapseFloorPx,
-    },
-    pin: {
-      kind: 'pin',
-      px: pinPx,
-      floorPx: pinFloorPx,
-      mode: state.pin.mode ?? 'transient',
-      targetTurnId: state.pin.targetTurnId ?? null,
-    },
-  };
-}
-
-export function areBottomReservationStatesEqual(
-  left: BottomReservationState,
-  right: BottomReservationState,
-): boolean {
-  return (
-    Math.abs(left.collapse.px - right.collapse.px) <= COMPENSATION_EPSILON_PX &&
-    Math.abs(left.collapse.floorPx - right.collapse.floorPx) <= COMPENSATION_EPSILON_PX &&
-    Math.abs(left.pin.px - right.pin.px) <= COMPENSATION_EPSILON_PX &&
-    Math.abs(left.pin.floorPx - right.pin.floorPx) <= COMPENSATION_EPSILON_PX &&
-    left.pin.mode === right.pin.mode &&
-    left.pin.targetTurnId === right.pin.targetTurnId
-  );
-}
-
-export function getReservationTotalPx(reservation: BottomReservationBase): number {
-  return Math.max(0, reservation.px);
-}
-
-function getReservationConsumablePx(reservation: BottomReservationBase): number {
-  return Math.max(0, reservation.px - reservation.floorPx);
-}
-
-export function consumeBottomReservationForContentGrowth(
-  state: BottomReservationState,
-  amountPx: number,
-  consumeStickyPinFloor: boolean,
-  preserveCollapseReservation = false,
-): BottomReservationState {
-  let remaining = Math.max(0, amountPx);
-
-  const collapseConsumablePx = preserveCollapseReservation
-    ? 0
-    : getReservationConsumablePx(state.collapse);
-  const collapseAboveFloorConsumed = Math.min(collapseConsumablePx, remaining);
-  remaining -= collapseAboveFloorConsumed;
-  const collapseFloorConsumed = preserveCollapseReservation
-    ? 0
-    : Math.min(state.collapse.floorPx, remaining);
-  const collapseConsumed = collapseAboveFloorConsumed + collapseFloorConsumed;
-  remaining -= collapseFloorConsumed;
-
-  const pinConsumablePx = getReservationConsumablePx(state.pin);
-  const pinConsumed = Math.min(pinConsumablePx, remaining);
-  remaining -= pinConsumed;
-
-  const stickyPinFloorConsumed = consumeStickyPinFloor && state.pin.mode === 'sticky-latest'
-    ? Math.min(state.pin.floorPx, remaining)
-    : 0;
-
-  return sanitizeBottomReservationState({
-    collapse: {
-      ...state.collapse,
-      px: state.collapse.px - collapseConsumed,
-      floorPx: state.collapse.floorPx - collapseFloorConsumed,
-    },
-    pin: {
-      ...state.pin,
-      px: state.pin.px - pinConsumed - stickyPinFloorConsumed,
-      floorPx: state.pin.floorPx - stickyPinFloorConsumed,
-    },
-  });
-}
-
-export function shouldSyncPhysicalBottom(options: {
-  viewportHeightChanged: boolean;
-  collapseProtectionActive: boolean;
-  wasAtPhysicalBottom: boolean;
-  ownsElementAnchor: boolean;
-  isFollowingTail: boolean;
-}): boolean {
-  return (
-    options.viewportHeightChanged &&
-    !options.collapseProtectionActive &&
-    options.wasAtPhysicalBottom &&
-    !options.ownsElementAnchor &&
-    !options.isFollowingTail
-  );
-}
-
-export function shouldSuppressFollowingTailNegativeScrollBy(options: {
-  requestedTop: number | null;
-  isFollowingOutput: boolean;
-  isStreamingOutput: boolean;
-  wasAtPhysicalBottom: boolean;
-}): boolean {
-  return (
-    options.requestedTop !== null &&
-    options.requestedTop < -COMPENSATION_EPSILON_PX &&
-    options.isFollowingOutput &&
-    options.isStreamingOutput &&
-    options.wasAtPhysicalBottom
-  );
-}
-
-export interface FollowingTailShrinkClampRecovery {
-  targetScrollTop: number;
-  rangeShrinkPx: number;
-  scrollClampPx: number;
-}
-
-/** Distinguishes a browser range clamp from user or programmatic upward scrolling. */
-export function resolveFollowingTailShrinkClampRecovery(options: {
-  previousGeometry: {
-    scrollTop: number;
-    scrollHeight: number;
-    clientHeight: number;
-  } | null;
-  currentGeometry: {
-    scrollTop: number;
-    scrollHeight: number;
-    clientHeight: number;
-  };
-  isFollowingOutput: boolean;
-  isStreamingOutput: boolean;
-  hasRecentUserUpwardIntent: boolean;
-  scrollbarPointerInteractionActive: boolean;
-  collapseProtectionActive: boolean;
-}): FollowingTailShrinkClampRecovery | null {
-  if (
-    !options.previousGeometry ||
-    !options.isFollowingOutput ||
-    !options.isStreamingOutput ||
-    options.hasRecentUserUpwardIntent ||
-    options.scrollbarPointerInteractionActive ||
-    options.collapseProtectionActive
-  ) {
-    return null;
-  }
-
-  const previous = options.previousGeometry;
-  const current = options.currentGeometry;
-  const values = [
-    previous.scrollTop,
-    previous.scrollHeight,
-    previous.clientHeight,
-    current.scrollTop,
-    current.scrollHeight,
-    current.clientHeight,
-  ];
-  if (values.some(value => !Number.isFinite(value))) {
-    return null;
-  }
-
-  if (
-    Math.abs(previous.clientHeight - current.clientHeight) >
-      FOLLOWING_TAIL_SHRINK_CLAMP_TOLERANCE_PX
-  ) {
-    return null;
-  }
-
-  const previousMaxScrollTop = Math.max(0, previous.scrollHeight - previous.clientHeight);
-  const currentMaxScrollTop = Math.max(0, current.scrollHeight - current.clientHeight);
-  const rangeShrinkPx = previousMaxScrollTop - currentMaxScrollTop;
-  const scrollClampPx = previous.scrollTop - current.scrollTop;
-  if (
-    rangeShrinkPx <= COMPENSATION_EPSILON_PX ||
-    scrollClampPx <= COMPENSATION_EPSILON_PX ||
-    Math.abs(previousMaxScrollTop - previous.scrollTop) >
-      FOLLOWING_TAIL_SHRINK_CLAMP_TOLERANCE_PX ||
-    Math.abs(currentMaxScrollTop - current.scrollTop) >
-      FOLLOWING_TAIL_SHRINK_CLAMP_TOLERANCE_PX ||
-    Math.abs(rangeShrinkPx - scrollClampPx) >
-      FOLLOWING_TAIL_SHRINK_CLAMP_TOLERANCE_PX
-  ) {
-    return null;
-  }
-
-  return {
-    targetScrollTop: previous.scrollTop,
-    rangeShrinkPx,
-    scrollClampPx,
-  };
-}
-
-export function getCanceledUnsettledStickyPinGrowthPx(options: {
-  pendingGrowthPx: number;
-  shrinkPx: number;
-  hasActiveCollapseIntent: boolean;
-}): number {
-  if (options.hasActiveCollapseIntent) {
-    return 0;
-  }
-  return Math.min(
-    sanitizeReservationPx(options.pendingGrowthPx),
-    sanitizeReservationPx(options.shrinkPx),
-  );
-}
-
-export type StickyPinGrowthSettlementStrategy =
-  | 'none'
-  | 'wait-for-quiet'
-  | 'wait-for-collapse'
-  | 'settle-now';
-
-export function resolveStickyPinGrowthSettlementStrategy(options: {
-  pendingGrowthPx: number;
-  pinFloorPx: number;
-  hasActiveCollapseIntent: boolean;
-}): StickyPinGrowthSettlementStrategy {
-  const pendingGrowthPx = sanitizeReservationPx(options.pendingGrowthPx);
-  const pinFloorPx = sanitizeReservationPx(options.pinFloorPx);
-  if (
-    pendingGrowthPx <= COMPENSATION_EPSILON_PX ||
-    pinFloorPx <= COMPENSATION_EPSILON_PX
-  ) {
-    return 'none';
-  }
-
-  if (pendingGrowthPx + COMPENSATION_EPSILON_PX < pinFloorPx) {
-    return 'wait-for-quiet';
-  }
-
-  return options.hasActiveCollapseIntent
-    ? 'wait-for-collapse'
-    : 'settle-now';
-}
-
-export function shouldBypassShrinkCompensationInTailFollow(options: {
-  isFollowingOutput: boolean;
-  isStreamingOutput: boolean;
-  hasActiveCollapseIntent: boolean;
-}): boolean {
-  return (
-    options.isFollowingOutput &&
-    options.isStreamingOutput &&
-    !options.hasActiveCollapseIntent
-  );
-}
-
-export type CollapseIntentSettlementStrategy =
-  | 'reconcile-sticky-pin'
-  | 'retain-following-tail'
-  | 'settle-preserved-element'
-  | 'settle-protected-viewport'
-  | 'drain';
-
-export function resolveCollapseIntentSettlementStrategy(options: {
-  coordinatorMode: FlowChatViewportAnchorMode;
-  isFollowingOutput: boolean;
-  isStreamingOutput: boolean;
-  reservation: BottomReservationState;
-}): CollapseIntentSettlementStrategy {
-  const ownsStickyPin = (
-    options.coordinatorMode === 'pinned-item' &&
-    options.reservation.pin.mode === 'sticky-latest' &&
-    Boolean(options.reservation.pin.targetTurnId)
-  );
-  if (ownsStickyPin) {
-    return 'reconcile-sticky-pin';
-  }
-  if (
-    options.coordinatorMode === 'following-tail' &&
-    options.isFollowingOutput &&
-    options.isStreamingOutput
-  ) {
-    return 'retain-following-tail';
-  }
-  if (options.coordinatorMode === 'preserving-element') {
-    return 'settle-preserved-element';
-  }
-  if (options.reservation.collapse.floorPx > COMPENSATION_EPSILON_PX) {
-    return 'settle-protected-viewport';
-  }
-  return 'drain';
-}
-
-export function resolveAutoCollapseAnchorScrollTop(options: {
-  currentScrollTop: number;
-  previousStableScrollTop: number;
-  reason: string | null | undefined;
-  isFollowingOutput: boolean;
-  isStreamingOutput: boolean;
-}): number {
-  if (
-    options.reason !== 'auto' ||
-    !options.isFollowingOutput ||
-    !options.isStreamingOutput
-  ) {
-    return options.currentScrollTop;
-  }
-  return Math.max(options.currentScrollTop, options.previousStableScrollTop);
-}
diff --git a/src/web-ui/src/flow_chat/components/modern/flowChatTailFollow.test.ts b/src/web-ui/src/flow_chat/components/modern/flowChatTailFollow.test.ts
new file mode 100644
index 0000000000..35bed7719d
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/modern/flowChatTailFollow.test.ts
@@ -0,0 +1,504 @@
+import { describe, expect, it } from 'vitest';
+import {
+  contentEndScrollTop,
+  FLOWCHAT_ANIMATED_JUMP_MAX_VIEWPORTS,
+  FLOWCHAT_AT_CONTENT_END_THRESHOLD_PX,
+  isTailBlankMeasurable,
+  isViewportAtTail,
+  memorylessFollowState,
+  nextTailFollowState,
+  resolveAnimatedJumpBehavior,
+  resolveTailDepartureCrossing,
+  shouldResumeFollowAfterDeparture,
+  tailHoldMaxGapPx,
+  tailSpacerPxForViewport,
+  turnTopAlignmentEntersReservedBlank,
+  type TailFollowState,
+} from './flowChatTailFollow';
+
+const VIEWPORT = 800;
+const BOTTOM_INSET = 168;
+const SPACER = tailSpacerPxForViewport(VIEWPORT, BOTTOM_INSET);
+const MAX_GAP = tailHoldMaxGapPx(VIEWPORT);
+const THRESHOLD = FLOWCHAT_AT_CONTENT_END_THRESHOLD_PX;
+
+function holding(target: number): TailFollowState {
+  return { mode: 'hold-tail', target };
+}
+
+function pinning(target: number): TailFollowState {
+  return { mode: 'pin-turn-top', target };
+}
+
+describe('tailSpacerPxForViewport', () => {
+  it('reserves exactly enough to put a bare new Turn on the top edge', () => {
+    // Worst case for the pin: the user message is the newest item and nothing
+    // has answered it, so the message, the input inset and the spacer are all
+    // that lie below its top. One viewport of them is what the pin needs.
+    const spacer = tailSpacerPxForViewport(VIEWPORT, BOTTOM_INSET);
+    const smallestUserMessagePx = VIEWPORT - BOTTOM_INSET - spacer;
+    expect(smallestUserMessagePx).toBeGreaterThan(0);
+    expect(smallestUserMessagePx).toBeLessThan(64);
+  });
+
+  it('never reserves less than the gap the hold rule may be holding', () => {
+    // A composer expanded most of the way up the viewport leaves the pin almost
+    // nothing to reserve, but `hold-tail` still parks up to `tailHoldMaxGapPx`
+    // past the content end — and an offset the browser clamps is an offset the
+    // hold rule does not get to hold.
+    expect(tailSpacerPxForViewport(VIEWPORT, VIEWPORT - 80))
+      .toBe(tailHoldMaxGapPx(VIEWPORT));
+  });
+
+  it('stays well under a full viewport, so the scroll range does not end in blank', () => {
+    expect(tailSpacerPxForViewport(VIEWPORT, BOTTOM_INSET)).toBeLessThan(VIEWPORT);
+  });
+
+  it('reserves nothing before the scroller has been measured', () => {
+    expect(tailSpacerPxForViewport(0, BOTTOM_INSET)).toBe(0);
+  });
+});
+
+describe('turnTopAlignmentEntersReservedBlank', () => {
+  it('leaves a Turn with content below it top-aligned', () => {
+    expect(turnTopAlignmentEntersReservedBlank({
+      turnTopScrollTop: 400,
+      contentEndScrollTop: 3000,
+    })).toBe(false);
+  });
+
+  it('clamps a Turn whose top lies past the end of real content', () => {
+    // Everything below it is the reserved blank, which follow-output holds for
+    // output that is arriving. Nothing arrives under a navigated Turn.
+    expect(turnTopAlignmentEntersReservedBlank({
+      turnTopScrollTop: 3200,
+      contentEndScrollTop: 3000,
+    })).toBe(true);
+  });
+
+  it('asks nothing about which Turn it is', () => {
+    // The last Turn of a long transcript top-aligns like any other; short and
+    // long is the result of the comparison, not an input to it.
+    expect(turnTopAlignmentEntersReservedBlank({
+      turnTopScrollTop: 3000 - VIEWPORT,
+      contentEndScrollTop: 3000,
+    })).toBe(false);
+  });
+
+  it('treats the content end itself as still on the transcript', () => {
+    expect(turnTopAlignmentEntersReservedBlank({
+      turnTopScrollTop: 3000,
+      contentEndScrollTop: 3000,
+    })).toBe(false);
+  });
+});
+
+describe('contentEndScrollTop', () => {
+  it('excludes the resident tail spacer from the tail target', () => {
+    expect(contentEndScrollTop({
+      scrollHeight: 5000 + SPACER,
+      clientHeight: VIEWPORT,
+      tailSpacerPx: SPACER,
+    })).toBe(5000 - VIEWPORT);
+  });
+
+  it('clamps to the top when the transcript is shorter than the viewport', () => {
+    expect(contentEndScrollTop({
+      scrollHeight: 300 + SPACER,
+      clientHeight: VIEWPORT,
+      tailSpacerPx: SPACER,
+    })).toBe(0);
+  });
+});
+
+describe('nextTailFollowState hold-tail', () => {
+  it('follows content growth', () => {
+    const next = nextTailFollowState(holding(4000), {
+      desiredScrollTop: 4200,
+      pinScrollTop: null,
+      maxGapPx: MAX_GAP,
+    });
+    expect(next).toEqual({ mode: 'hold-tail', target: 4200 });
+  });
+
+  it('holds its offset when a collapse fits the tolerated gap', () => {
+    // A card above the live output collapses by 300px: the tail rises, but the
+    // viewport must not move or earlier content would visually drop by 300px.
+    const next = nextTailFollowState(holding(4000), {
+      desiredScrollTop: 3700,
+      pinScrollTop: null,
+      maxGapPx: MAX_GAP,
+    });
+    expect(next.target).toBe(4000);
+  });
+
+  it('gives ground only past the tolerated gap, and only by the excess', () => {
+    const next = nextTailFollowState(holding(4000), {
+      desiredScrollTop: 1000,
+      pinScrollTop: null,
+      maxGapPx: MAX_GAP,
+    });
+    expect(next.target).toBe(1000 + MAX_GAP);
+  });
+
+  it('never drops below the content-end target', () => {
+    const next = nextTailFollowState(holding(100), {
+      desiredScrollTop: 900,
+      pinScrollTop: null,
+      maxGapPx: MAX_GAP,
+    });
+    expect(next.target).toBe(900);
+  });
+});
+
+describe('nextTailFollowState pin-turn-top', () => {
+  it('holds a new Turn at the viewport top while its answer is short', () => {
+    const next = nextTailFollowState(pinning(0), {
+      desiredScrollTop: 4300,
+      pinScrollTop: 5000,
+      maxGapPx: MAX_GAP,
+    });
+    expect(next).toEqual({ mode: 'pin-turn-top', target: 5000 });
+  });
+
+  it('ignores the gap tolerance while pinned', () => {
+    // The blank below a freshly submitted Turn is the point of the mode.
+    const next = nextTailFollowState(pinning(5000), {
+      desiredScrollTop: 4300,
+      pinScrollTop: 5000,
+      maxGapPx: 10,
+    });
+    expect(next.target).toBe(5000);
+  });
+
+  it('stays put while a collapse shrinks content under the pin', () => {
+    const first = nextTailFollowState(pinning(0), {
+      desiredScrollTop: 4400,
+      pinScrollTop: 5000,
+      maxGapPx: MAX_GAP,
+    });
+    const afterCollapse = nextTailFollowState(first, {
+      desiredScrollTop: 4100,
+      pinScrollTop: 5000,
+      maxGapPx: MAX_GAP,
+    });
+    expect(afterCollapse.target).toBe(5000);
+  });
+
+  it('hands off to hold-tail once the answer overflows the viewport', () => {
+    const next = nextTailFollowState(pinning(5000), {
+      desiredScrollTop: 5000,
+      pinScrollTop: 5000,
+      maxGapPx: MAX_GAP,
+    });
+    expect(next).toEqual({ mode: 'hold-tail', target: 5000 });
+  });
+
+  it('does not regress after handing off', () => {
+    const handoff = nextTailFollowState(pinning(5000), {
+      desiredScrollTop: 5200,
+      pinScrollTop: 5000,
+      maxGapPx: MAX_GAP,
+    });
+    expect(handoff.mode).toBe('hold-tail');
+    const afterCollapse = nextTailFollowState(handoff, {
+      desiredScrollTop: 5000,
+      pinScrollTop: 5000,
+      maxGapPx: MAX_GAP,
+    });
+    expect(afterCollapse.target).toBe(5200);
+  });
+
+  it('falls back to the tail target until the Turn can be measured', () => {
+    const next = nextTailFollowState(pinning(0), {
+      desiredScrollTop: 4300,
+      pinScrollTop: null,
+      maxGapPx: MAX_GAP,
+    });
+    expect(next).toEqual({ mode: 'pin-turn-top', target: 4300 });
+  });
+});
+
+describe('memorylessFollowState', () => {
+  it('drops a held collapse gap the user has already scrolled away from', () => {
+    // The hold rule's refusal to move backwards protects a viewport it has been
+    // holding continuously. After a takeover there is nothing left to protect,
+    // and reinstating the old offset would land on a position nobody chose.
+    expect(memorylessFollowState('hold-tail', {
+      desiredScrollTop: 3700,
+      pinScrollTop: null,
+      maxGapPx: MAX_GAP,
+    }).target).toBe(3700);
+  });
+
+  it('still prefers a pinned Turn over the content end', () => {
+    expect(memorylessFollowState('pin-turn-top', {
+      desiredScrollTop: 4300,
+      pinScrollTop: 5000,
+      maxGapPx: MAX_GAP,
+    })).toEqual({ mode: 'pin-turn-top', target: 5000 });
+  });
+
+  it('reports the crossover so a suspended pin can be retired', () => {
+    // No frame loop runs while the user owns the viewport, so this is the only
+    // place a pin whose answer outgrew the viewport can be noticed.
+    expect(memorylessFollowState('pin-turn-top', {
+      desiredScrollTop: 5200,
+      pinScrollTop: 5000,
+      maxGapPx: MAX_GAP,
+    })).toEqual({ mode: 'hold-tail', target: 5200 });
+  });
+});
+
+describe('isViewportAtTail', () => {
+  const contentEnd = 4000;
+
+  it('counts the content end itself', () => {
+    expect(isViewportAtTail({
+      scrollTop: contentEnd,
+      contentEndScrollTop: contentEnd,
+      followTargetScrollTop: contentEnd,
+      thresholdPx: THRESHOLD,
+    })).toBe(true);
+  });
+
+  it('counts a pinned Turn, which is at the tail by its own rule', () => {
+    expect(isViewportAtTail({
+      scrollTop: 5000,
+      contentEndScrollTop: contentEnd,
+      followTargetScrollTop: 5000,
+      thresholdPx: THRESHOLD,
+    })).toBe(true);
+  });
+
+  it('excludes a viewport parked in the reserved blank', () => {
+    // The one-sided test this replaced reported "at the bottom" here, which hid
+    // the jump-to-latest affordance on a screen with nothing on it.
+    expect(isViewportAtTail({
+      scrollTop: contentEnd + SPACER,
+      contentEndScrollTop: contentEnd,
+      followTargetScrollTop: contentEnd,
+      thresholdPx: THRESHOLD,
+    })).toBe(false);
+  });
+
+  it('excludes a viewport scrolled up into the transcript', () => {
+    expect(isViewportAtTail({
+      scrollTop: 100,
+      contentEndScrollTop: contentEnd,
+      followTargetScrollTop: contentEnd,
+      thresholdPx: THRESHOLD,
+    })).toBe(false);
+  });
+});
+
+describe('resolveAnimatedJumpBehavior', () => {
+  const budget = VIEWPORT * FLOWCHAT_ANIMATED_JUMP_MAX_VIEWPORTS;
+
+  it('animates a jump the reader can follow', () => {
+    expect(resolveAnimatedJumpBehavior({
+      fromPx: 4000,
+      targetPx: 4000 + VIEWPORT,
+      clientHeight: VIEWPORT,
+    })).toBe('smooth');
+  });
+
+  it('animates a pinned Turn coming back into place, which is under a screen', () => {
+    // The `pin-turn-top` branch of a jump to latest, where the newest Turn's
+    // answer is shorter than the viewport by construction.
+    expect(resolveAnimatedJumpBehavior({
+      fromPx: 12_000,
+      targetPx: 12_180,
+      clientHeight: VIEWPORT,
+    })).toBe('smooth');
+  });
+
+  it('lands a jump from the head of a long transcript outright', () => {
+    /*
+     * The measurement the budget comes from: a jump issued for 8717px animated
+     * 5480 of them inside the yield and was finished by the follow loop in one
+     * 3290px write. Reading it as an animation is the mistake — what the reader
+     * saw was two thirds of a scroll and then a jump.
+     */
+    expect(resolveAnimatedJumpBehavior({
+      fromPx: 0,
+      targetPx: 8717,
+      clientHeight: VIEWPORT,
+    })).toBe('auto');
+  });
+
+  it('measures the distance in viewports, not pixels', () => {
+    // The same travel, on a display tall enough to still show where it went.
+    const travelPx = VIEWPORT * FLOWCHAT_ANIMATED_JUMP_MAX_VIEWPORTS + 400;
+    expect(resolveAnimatedJumpBehavior({
+      fromPx: 0,
+      targetPx: travelPx,
+      clientHeight: VIEWPORT,
+    })).toBe('auto');
+    expect(resolveAnimatedJumpBehavior({
+      fromPx: 0,
+      targetPx: travelPx,
+      clientHeight: travelPx,
+    })).toBe('smooth');
+  });
+
+  it('takes the budget itself as near enough', () => {
+    expect(resolveAnimatedJumpBehavior({
+      fromPx: 0,
+      targetPx: budget,
+      clientHeight: VIEWPORT,
+    })).toBe('smooth');
+    expect(resolveAnimatedJumpBehavior({
+      fromPx: 0,
+      targetPx: budget + 1,
+      clientHeight: VIEWPORT,
+    })).toBe('auto');
+  });
+
+  it('judges the distance travelled, whichever way it goes', () => {
+    // A jump to latest normally scrolls down, but `pin-turn-top` can aim above
+    // the viewport when a restored tail presentation arrives under a pin.
+    expect(resolveAnimatedJumpBehavior({
+      fromPx: 9000,
+      targetPx: 9000 - budget - 1,
+      clientHeight: VIEWPORT,
+    })).toBe('auto');
+  });
+
+  it('does not animate against a scroller that has not been measured', () => {
+    // No budget to scale and nothing on screen to follow. Every other reading
+    // of a zero height makes this a *short* jump, which is the wrong one.
+    expect(resolveAnimatedJumpBehavior({
+      fromPx: 0,
+      targetPx: 0,
+      clientHeight: 0,
+    })).toBe('auto');
+  });
+});
+
+describe('resolveTailDepartureCrossing', () => {
+  it('keeps watching while the blank is still on screen', () => {
+    expect(resolveTailDepartureCrossing({
+      blankPx: 180,
+      contentDeltaPx: 40,
+      scrollDeltaPx: 0,
+    })).toBe('watching');
+  });
+
+  it('reads content rising to meet a stationary reader as the tail catching up', () => {
+    // The case the resume acts on: the reader has not moved, and the empty
+    // space they were left looking at has just been filled.
+    expect(resolveTailDepartureCrossing({
+      blankPx: -12,
+      contentDeltaPx: 190,
+      scrollDeltaPx: 0,
+    })).toBe('content-caught-up');
+  });
+
+  it('reads a reader climbing out past a still content end as reading history', () => {
+    expect(resolveTailDepartureCrossing({
+      blankPx: -240,
+      contentDeltaPx: 0,
+      scrollDeltaPx: -420,
+    })).toBe('reader-left-blank');
+  });
+
+  it('gives a crossing where both moved to whichever moved further', () => {
+    // Streaming does not stop because the reader scrolled, so both sides move
+    // between samples and the tie-break decides. Callers record the two deltas
+    // beside the verdict so this line can be revisited from the trail.
+    expect(resolveTailDepartureCrossing({
+      blankPx: -5,
+      contentDeltaPx: 120,
+      scrollDeltaPx: -40,
+    })).toBe('content-caught-up');
+    expect(resolveTailDepartureCrossing({
+      blankPx: -5,
+      contentDeltaPx: 40,
+      scrollDeltaPx: -120,
+    })).toBe('reader-left-blank');
+  });
+
+  it('counts the blank as gone the moment content reaches the bottom edge', () => {
+    // `blankPx` is `scrollTop - contentEnd`, so zero is the content end exactly
+    // on the viewport's bottom edge — no blank, and the departure is over.
+    expect(resolveTailDepartureCrossing({
+      blankPx: 0,
+      contentDeltaPx: 30,
+      scrollDeltaPx: 0,
+    })).toBe('content-caught-up');
+    expect(resolveTailDepartureCrossing({
+      blankPx: 0.5,
+      contentDeltaPx: 30,
+      scrollDeltaPx: 0,
+    })).toBe('watching');
+  });
+
+  it('does not read a shrinking transcript as the reader leaving', () => {
+    // A tool card collapsing moves the content end *down*, which cannot end a
+    // departure — and if it somehow coincides with a crossing, a negative
+    // content delta must not out-vote the reader.
+    expect(resolveTailDepartureCrossing({
+      blankPx: -30,
+      contentDeltaPx: -200,
+      scrollDeltaPx: -60,
+    })).toBe('reader-left-blank');
+  });
+});
+
+describe('isTailBlankMeasurable', () => {
+  it('accepts a blank the reserved spacer can account for', () => {
+    expect(isTailBlankMeasurable({ blankPx: SPACER, tailSpacerPx: SPACER })).toBe(true);
+    expect(isTailBlankMeasurable({ blankPx: -400, tailSpacerPx: SPACER })).toBe(true);
+  });
+
+  it('refuses a blank larger than the whole spacer, which cannot have been seen', () => {
+    /*
+     * `scrollTop` is clamped to `scrollHeight - clientHeight`, so a settled
+     * viewport is never more than the spacer past the content end. Measured on
+     * a session that paged its whole history on the first scroll up: the
+     * prepend shifted the viewport 14252px to hold the reader's Turn still,
+     * against a content end still reading 989 — a blank of 6239px in a
+     * transcript reserving a few hundred.
+     */
+    expect(isTailBlankMeasurable({ blankPx: 6239, tailSpacerPx: SPACER })).toBe(false);
+  });
+});
+
+describe('shouldResumeFollowAfterDeparture', () => {
+  it('takes the viewport back when output caught up with a reader who had stopped', () => {
+    expect(shouldResumeFollowAfterDeparture({
+      crossing: 'content-caught-up',
+      gestureLive: false,
+    })).toBe(true);
+  });
+
+  it('leaves a reader who is still scrolling alone, whatever the geometry says', () => {
+    /*
+     * Measured, and the reason the gesture is an input at all: 320ms into a
+     * live gesture the reader had climbed 200px while content grew 237, so the
+     * tie-break called the crossing for the content — correctly — and acting on
+     * it would have taken the viewport back mid-scroll.
+     */
+    expect(shouldResumeFollowAfterDeparture({
+      crossing: 'content-caught-up',
+      gestureLive: true,
+    })).toBe(false);
+  });
+
+  it('never resumes for a reader who climbed out past the content end', () => {
+    // Reading history is the case the whole departure exists to tell apart, and
+    // a lapsed gesture claim does not make it something else.
+    expect(shouldResumeFollowAfterDeparture({
+      crossing: 'reader-left-blank',
+      gestureLive: false,
+    })).toBe(false);
+  });
+
+  it('decides nothing while the departure is still open', () => {
+    expect(shouldResumeFollowAfterDeparture({
+      crossing: 'watching',
+      gestureLive: false,
+    })).toBe(false);
+  });
+});
diff --git a/src/web-ui/src/flow_chat/components/modern/flowChatTailFollow.ts b/src/web-ui/src/flow_chat/components/modern/flowChatTailFollow.ts
new file mode 100644
index 0000000000..599035c9a8
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/modern/flowChatTailFollow.ts
@@ -0,0 +1,396 @@
+/**
+ * FlowChat tail-follow geometry.
+ *
+ * The transcript keeps a resident tail spacer below the real content, sized
+ * from the viewport and the current input-stack inset. The spacer is static: it
+ * never reacts to a measured content change, so it is a reservation rather than
+ * a compensation.
+ *
+ * The spacer alone does not stabilise the viewport. It only removes the
+ * browser's forced `scrollTop` clamp when content shrinks; the follow target
+ * below is what then chooses to stay where it is instead of dragging earlier
+ * content down. Both halves are required.
+ */
+
+/** Blank tail tolerated below the live output, as a share of the viewport. */
+export const FLOWCHAT_TAIL_HOLD_GAP_RATIO = 0.6;
+
+/**
+ * Distance from an owned offset still treated as being on it.
+ *
+ * One constant deliberately serves both "the viewport is at the end" and "the
+ * viewport has come to rest too far below the end". They are the two sides of
+ * the same band; separate tolerances would leave a seam where the jump-to-latest
+ * affordance is shown but nothing snaps back, or the reverse.
+ */
+export const FLOWCHAT_AT_CONTENT_END_THRESHOLD_PX = 50;
+
+export type TailFollowMode = 'pin-turn-top' | 'hold-tail';
+
+export interface TailFollowState {
+  mode: TailFollowMode;
+  /** Scroll offset the viewport currently owns. */
+  target: number;
+}
+
+export interface TailFollowGeometry {
+  scrollHeight: number;
+  clientHeight: number;
+  tailSpacerPx: number;
+}
+
+export interface TailFollowInput {
+  /** Offset placing the end of real content at the viewport bottom. */
+  desiredScrollTop: number;
+  /** Offset placing the pinned Turn's user message at the viewport top. */
+  pinScrollTop: number | null;
+  /** Largest blank tail the hold rule accepts before it gives ground. */
+  maxGapPx: number;
+}
+
+/**
+ * Breathing gap held above a Turn whose user message is aligned to the viewport
+ * top.
+ *
+ * The first Turn gets this for free: `.message-list-header` sits above it in
+ * the scroll content, so a transcript resting at `scrollTop: 0` already shows
+ * the gap. Every other Turn is reached by a scroll that lands its message flat
+ * on the top edge, which read as a different alignment rather than the same one
+ * — so top-aligning aims at `top - this` instead, and the header renders at
+ * exactly this height so the two cannot drift apart.
+ */
+export const FLOWCHAT_TURN_TOP_GAP_PX = 8;
+
+/**
+ * Lower bound on the rendered height of a user-message item.
+ *
+ * This sizes the pin reserve below, so it must be an *under*estimate. Too low
+ * only leaves the pin a few spare pixels; too high makes the pinned offset
+ * exceed the scroll range, and the browser clamps the Turn back down from the
+ * viewport top with the follow loop rewriting the clamped offset every frame.
+ * A single line with no timestamp row is comfortably above this at any
+ * supported font size, and the item is free to be taller.
+ */
+const PINNED_TURN_MIN_ITEM_HEIGHT_PX = 40;
+
+/**
+ * Height of the resident tail spacer.
+ *
+ * The spacer exists to keep two offsets inside the scroll range, and it is
+ * sized to the larger of what they need — one viewport was simply the cheapest
+ * bound that covered both, and it costs a full screen of blank at the end of
+ * the scroll range.
+ *
+ * - **A pinned Turn.** Worst case its user message is the newest item and
+ *   nothing has answered it yet, so everything below the message top is the
+ *   message, the input-stack inset, and this spacer. Reserving
+ *   `clientHeight - bottomInsetPx - PINNED_TURN_MIN_ITEM_HEIGHT_PX` is exactly
+ *   enough to put that message on the top edge.
+ * - **A held collapse gap.** `hold-tail` keeps an offset up to
+ *   `tailHoldMaxGapPx` past the content end, and an offset the browser clamps
+ *   is an offset the hold rule does not actually get to hold.
+ *
+ * `bottomInsetPx` is the input-stack footer, which grows as the composer does.
+ * That is a layout input, not a content measurement — and while the pin reserve
+ * is the binding bound the two sum to a constant, so growing the composer moves
+ * the content end without moving the end of the scroll range.
+ */
+export function tailSpacerPxForViewport(
+  clientHeight: number,
+  bottomInsetPx: number,
+): number {
+  const pinnedTurnReservePx = clientHeight - bottomInsetPx - PINNED_TURN_MIN_ITEM_HEIGHT_PX;
+  return Math.max(0, Math.round(Math.max(pinnedTurnReservePx, tailHoldMaxGapPx(clientHeight))));
+}
+
+/**
+ * Scroll offset that places the end of real content at the viewport bottom.
+ * The tail spacer sits below that point and is deliberately excluded.
+ */
+export function contentEndScrollTop(geometry: TailFollowGeometry): number {
+  return Math.max(
+    0,
+    geometry.scrollHeight - geometry.tailSpacerPx - geometry.clientHeight,
+  );
+}
+
+export function tailHoldMaxGapPx(clientHeight: number): number {
+  return Math.max(0, Math.round(clientHeight * FLOWCHAT_TAIL_HOLD_GAP_RATIO));
+}
+
+export interface TurnTopAlignmentInput {
+  /** Offset that would place the Turn's user message at the viewport top. */
+  turnTopScrollTop: number;
+  contentEndScrollTop: number;
+}
+
+/**
+ * Whether top-aligning a Turn would park the viewport in the reserved blank.
+ *
+ * The blank belongs to follow-output. `pin-turn-top` holds it for output that
+ * is on its way, and nothing is on its way under a Turn the user navigated to
+ * — so a navigation that lands there shows a screen of nothing, and the snap
+ * back then reclaims it as a second, visible movement.
+ *
+ * A clamp at the content end is the whole rule. There is no "is this the last
+ * Turn" test and no measurement of what lies below it: a Turn with a viewport
+ * of content under it has its top above the content end already, so this
+ * returns false and the alignment stands. Before the resident spacer the
+ * browser did exactly this for free, by clamping at the end of the scroll
+ * range; reserving the blank is what removed the clamp.
+ */
+export function turnTopAlignmentEntersReservedBlank(
+  input: TurnTopAlignmentInput,
+): boolean {
+  return input.turnTopScrollTop > input.contentEndScrollTop;
+}
+
+/**
+ * Resolve the next follow target.
+ *
+ * `pin-turn-top` holds a freshly submitted Turn at the viewport top while its
+ * answer is still shorter than one viewport, then hands off to `hold-tail` at
+ * the crossover. The pinned phase ignores `maxGapPx`: the blank below a new
+ * Turn is the point of the mode, not a failure of it.
+ *
+ * `hold-tail` never moves backwards for free. It keeps its previous offset when
+ * content shrinks, which is what leaves earlier content visually still, and
+ * only gives ground once the blank below the live output exceeds `maxGapPx`.
+ */
+export function nextTailFollowState(
+  previous: TailFollowState,
+  input: TailFollowInput,
+): TailFollowState {
+  if (previous.mode === 'pin-turn-top') {
+    if (input.pinScrollTop === null) {
+      // The Turn is not measurable yet; behave like a plain tail follow so the
+      // viewport is never stranded, and pin once the element resolves.
+      return { mode: 'pin-turn-top', target: input.desiredScrollTop };
+    }
+    if (input.desiredScrollTop < input.pinScrollTop) {
+      return { mode: 'pin-turn-top', target: input.pinScrollTop };
+    }
+    return { mode: 'hold-tail', target: input.desiredScrollTop };
+  }
+
+  return {
+    mode: 'hold-tail',
+    target: Math.max(
+      input.desiredScrollTop,
+      Math.min(previous.target, input.desiredScrollTop + input.maxGapPx),
+    ),
+  };
+}
+
+/**
+ * The state the follow rule would hold right now, judged from live geometry
+ * alone.
+ *
+ * `hold-tail` normally refuses to move backwards, and that refusal is what
+ * keeps a collapse from dragging earlier content down. The memory it refuses
+ * with belongs to a viewport the follow rule has been holding continuously;
+ * once the user has taken over and come to rest somewhere else there is nothing
+ * left to preserve, and carrying the stale offset forward would land them on a
+ * position neither side chose.
+ *
+ * The returned mode still matters: a pinned Turn whose answer has outgrown the
+ * viewport reports `hold-tail`, which is how a caller learns the pin has
+ * crossed over even though no follow loop was running to notice.
+ */
+export function memorylessFollowState(
+  mode: TailFollowMode,
+  input: TailFollowInput,
+): TailFollowState {
+  return nextTailFollowState({ mode, target: input.desiredScrollTop }, input);
+}
+
+export type TailDepartureCrossing =
+  /** The blank is still on screen; nothing has been crossed. */
+  | 'watching'
+  /** Output grew until the blank was gone under a reader who stayed put. */
+  | 'content-caught-up'
+  /** The reader scrolled up past the end of content. Reading history. */
+  | 'reader-left-blank';
+
+/**
+ * Where a reader stands relative to the reserved blank, and who moved them
+ * there.
+ *
+ * Losing the follow permanently is right only for a reader who left the live
+ * region, and `scrollTop > contentEnd` says they have not. The reserved blank
+ * is up to `tailHoldMaxGapPx` under `hold-tail` and the whole gap under a
+ * pinned Turn, so a small scroll up can leave the reader looking at empty space
+ * below the newest output — nothing hidden from them yet — until output grows
+ * past the bottom edge and they silently stop seeing it.
+ *
+ * The follow target may sit inside the blank while a new Turn is pinned, but
+ * this watch deliberately uses the real content end: it only observes output
+ * catching up with a reader, never a user's resting position.
+ *
+ * `watching` is a *position*, not a pending outcome: the blank is on screen
+ * right now. It says nothing about whether the reader has ever left it, and the
+ * caller is the one that remembers — the transition from `watching` to either
+ * verdict is the event, and a reader who has been above the content end for
+ * minutes reports `reader-left-blank` on every sample without anything having
+ * happened.
+ *
+ * The two ways out are told apart by which side moved. Content rising to meet a
+ * stationary reader is the case `shouldResumeFollowAfterDeparture` acts on; a
+ * reader climbing out past a stationary content end is the case it must leave
+ * alone. When both moved, the larger one is the cause — and callers record the
+ * raw deltas beside the verdict, so the tie-break can be revisited from the
+ * trail.
+ */
+export function resolveTailDepartureCrossing(input: {
+  /** `scrollTop - contentEndScrollTop` now. Positive while blank is on screen. */
+  blankPx: number;
+  /** How far the content end rose since the previous sample. */
+  contentDeltaPx: number;
+  /** How far the reader moved the viewport since the previous sample. */
+  scrollDeltaPx: number;
+}): TailDepartureCrossing {
+  if (input.blankPx > 0) {
+    return 'watching';
+  }
+  return input.contentDeltaPx >= Math.abs(input.scrollDeltaPx)
+    ? 'content-caught-up'
+    : 'reader-left-blank';
+}
+
+/**
+ * Whether a departure that has just ended hands the viewport back to follow.
+ *
+ * `content-caught-up` is the case the whole rule exists for, but it is not
+ * sufficient on its own. Streaming does not stop because the reader scrolled,
+ * so a reader still working the wheel can cross the same line by scrolling into
+ * output that is rising to meet them — and resuming there takes the viewport
+ * out of their hands while their hand is still on it.
+ *
+ * Measured over one session's twenty departures: nine left blank on screen, and
+ * exactly two of those ended `content-caught-up`. One was a reader who had
+ * stopped 1.6s earlier and was overtaken by output, which is the case to act
+ * on. The other was 320ms into a live gesture, with the reader climbing 200px
+ * while content grew 237 — the tie-break called it for the content, correctly,
+ * and acting on it would have yanked the viewport back mid-scroll. The register
+ * separates the two cleanly, because a wheel claim lapses
+ * `USER_DRIVEN_SCROLL_WINDOW_MS` after the last notch and notches arrive faster
+ * than that.
+ *
+ * A refusal here defers the crossing rather than settling it. The caller keeps
+ * its "blank was visible" latch, so the same transition is judged again on the
+ * next sample: a reader who carries on climbing out-moves the content and is
+ * let go by a verdict that never needed the veto, and one who has stopped is
+ * followed as soon as the claim lapses. Nothing has to be given up to stay off
+ * a live gesture — only postponed by one sample.
+ */
+export function shouldResumeFollowAfterDeparture(input: {
+  crossing: TailDepartureCrossing;
+  /** Whether the reader's own claim on the viewport is still live. */
+  gestureLive: boolean;
+}): boolean {
+  return input.crossing === 'content-caught-up' && !input.gestureLive;
+}
+
+/**
+ * Whether the blank a sample just measured can be real.
+ *
+ * `scrollTop` is clamped to `scrollHeight - clientHeight`, and the spacer is
+ * everything below the end of real content, so no settled viewport can be more
+ * than `tailSpacerPx` past it. A larger reading means the two halves were read
+ * from different moments — the transcript has been restructured and the browser
+ * has not clamped `scrollTop` to the new range yet, or something wrote the
+ * offset to compensate for content that has not been measured.
+ *
+ * Measured on a session that paged its whole history on the first scroll up:
+ * the prepend shifted the viewport 14252px to hold the reader's Turn still,
+ * against a content end that was still 989 — a blank of 6239px in a transcript
+ * whose spacer reserves a few hundred. Read as a reader sitting deep in the
+ * blank, which is the one state the follow rule is watching for, so the next
+ * sample would have handed the viewport to follow and pulled them out of the
+ * history they had just asked for.
+ */
+export function isTailBlankMeasurable(input: {
+  blankPx: number;
+  tailSpacerPx: number;
+}): boolean {
+  return input.blankPx <= input.tailSpacerPx;
+}
+
+export interface ViewportAtTailInput {
+  scrollTop: number;
+  contentEndScrollTop: number;
+  /** Upper bound of the band; the content end when nothing owns the viewport. */
+  followTargetScrollTop: number;
+  thresholdPx: number;
+}
+
+/**
+ * Whether the viewport counts as being at the end of the transcript.
+ *
+ * The band runs from the content end down to whatever the follow rule owns, so
+ * a pinned Turn and a held collapse gap both sit inside it — neither is a
+ * reason to offer a jump to the latest output. Past the lower bound is reserved
+ * blank, which is.
+ */
+export function isViewportAtTail(input: ViewportAtTailInput): boolean {
+  return input.scrollTop >= input.contentEndScrollTop - input.thresholdPx
+    && input.scrollTop <= input.followTargetScrollTop + input.thresholdPx;
+}
+
+/**
+ * Viewports a jump to the latest output may animate across.
+ *
+ * Counted in viewports rather than pixels because the question is whether the
+ * reader can follow the movement, and what they can follow is a share of what
+ * they can see: the same 2000px is two and a half screens on a laptop and most
+ * of one on a tall display.
+ *
+ * Three is about the largest number the animation reliably finishes. The frame
+ * loop yields to a smooth scroll for a bounded time and takes the viewport back
+ * afterwards wherever it has got to — measured, a jump issued for 8717px
+ * animated 5480 of them and was finished by the loop in a single 3290px write.
+ * That is 38% of the distance delivered as a hard jump at the end of an
+ * animation, which is worse than either half on its own. The same measurement
+ * puts the sustained rate near 4570px/s, so three 800px viewports travel in
+ * roughly half the budget.
+ *
+ * `followOutput.animatedScrollEnded` is where this number is checked: a
+ * `backstop` reason means an animation ran out its yield without arriving, and
+ * this is then too high.
+ */
+export const FLOWCHAT_ANIMATED_JUMP_MAX_VIEWPORTS = 3;
+
+export interface AnimatedJumpInput {
+  /** Where the viewport is now. */
+  fromPx: number;
+  /** Where the jump would leave it. */
+  targetPx: number;
+  clientHeight: number;
+}
+
+/**
+ * How a jump to the latest output should travel.
+ *
+ * An animation earns its cost only while the reader can read it. Its whole job
+ * is spatial continuity — showing which way and how far the viewport went — and
+ * past a few screens the transcript in between goes by faster than anyone can
+ * track, leaving a wait where the answer was. So a far jump lands instantly,
+ * the way every other navigation in the transcript already does, and a near one
+ * animates.
+ *
+ * Distance also costs more than it looks. Animating across N screens of a
+ * virtualized transcript renders and measures every item passed while the
+ * animation runs, and heights are estimates until they are measured — so the
+ * content end moves under an animation aimed at where it used to be, and the
+ * follow loop corrects that afterwards as a second, visible movement. A jump
+ * inside a few viewports passes items that are already rendered and measured.
+ */
+export function resolveAnimatedJumpBehavior(input: AnimatedJumpInput): 'smooth' | 'auto' {
+  // An unmeasured scroller is not a short distance, it is no distance at all:
+  // there is nothing to scale the budget by and nothing on screen to follow.
+  if (input.clientHeight <= 0) return 'auto';
+  return Math.abs(input.targetPx - input.fromPx)
+    <= input.clientHeight * FLOWCHAT_ANIMATED_JUMP_MAX_VIEWPORTS
+    ? 'smooth'
+    : 'auto';
+}
diff --git a/src/web-ui/src/flow_chat/components/modern/flowChatViewportAnchor.test.ts b/src/web-ui/src/flow_chat/components/modern/flowChatViewportAnchor.test.ts
new file mode 100644
index 0000000000..ace2fed234
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/modern/flowChatViewportAnchor.test.ts
@@ -0,0 +1,135 @@
+import { describe, expect, it } from 'vitest';
+import {
+  ANCHOR_SETTLE_FRAMES,
+  USER_DRIVEN_SCROLL_WINDOW_MS,
+  selectViewportAnchor,
+  shouldCaptureViewportAnchorOnScroll,
+  viewportAnchorCorrectionPx,
+  type ViewportAnchorCandidate,
+} from './flowChatViewportAnchor';
+
+function candidate(
+  turnId: string | null,
+  top: number,
+  height = 40,
+): ViewportAnchorCandidate {
+  return {
+    turnId,
+    offsetFromScrollerTop: top,
+    bottomOffsetFromScrollerTop: top + height,
+  };
+}
+
+const VIEWPORT_HEIGHT = 800;
+
+describe('selectViewportAnchor', () => {
+  it('anchors to the topmost Turn the viewport still shows', () => {
+    expect(selectViewportAnchor([
+      candidate('turn-1', -900),
+      // Scrolled past the top edge, but its Turn still fills the screen.
+      candidate('turn-2', -120, 300),
+      candidate('turn-3', 260),
+    ], VIEWPORT_HEIGHT)).toEqual({ turnId: 'turn-2', offsetFromScrollerTop: -120 });
+  });
+
+  it('keeps a Turn that is scrolled past the top edge but still on screen', () => {
+    // Its top is above the viewport and its bottom is not: this is what the
+    // reader is looking at, and the offset that describes it is negative.
+    expect(selectViewportAnchor([candidate('turn-1', -30)], VIEWPORT_HEIGHT))
+      .toEqual({ turnId: 'turn-1', offsetFromScrollerTop: -30 });
+  });
+
+  it('has no anchor when every Turn is above the viewport', () => {
+    expect(selectViewportAnchor([
+      candidate('turn-1', -900),
+      candidate('turn-2', -400, 300),
+    ], VIEWPORT_HEIGHT)).toBeNull();
+  });
+
+  it('has no anchor when every Turn is below the viewport', () => {
+    /*
+     * The reader is inside an answer taller than the screen, so the Turn they
+     * are reading has no marker on it and the next one is far past the bottom
+     * edge. Measured: an anchor taken at an offset of 1695.5px in a scroller at
+     * most 1325.7px tall — at least 370px out of sight.
+     *
+     * Anchoring there inverts what the anchor is for. Content below the
+     * viewport re-measuring moves nothing the reader can see, so every
+     * correction against a marker down there is a displacement being created
+     * rather than repaired.
+     */
+    expect(selectViewportAnchor([
+      candidate('turn-1', -1_700),
+      candidate('turn-2', 1_695.5),
+    ], VIEWPORT_HEIGHT)).toBeNull();
+  });
+
+  it('has no anchor when the topmost visible candidate carries no Turn', () => {
+    // Falling through to the next one would anchor to a Turn further down the
+    // screen than the reading position belongs to.
+    expect(selectViewportAnchor([
+      candidate(null, -30),
+      candidate('turn-2', 260),
+    ], VIEWPORT_HEIGHT)).toBeNull();
+  });
+
+  it('anchors to the last Turn on screen when it is the only one', () => {
+    // The bottom edge is a bound, not a preference: a marker just inside it is
+    // still something the reader can see.
+    expect(selectViewportAnchor(
+      [candidate('turn-9', VIEWPORT_HEIGHT - 1)],
+      VIEWPORT_HEIGHT,
+    )).toEqual({ turnId: 'turn-9', offsetFromScrollerTop: VIEWPORT_HEIGHT - 1 });
+  });
+
+  it('has no anchor when nothing is rendered', () => {
+    expect(selectViewportAnchor([], VIEWPORT_HEIGHT)).toBeNull();
+  });
+});
+
+describe('viewportAnchorCorrectionPx', () => {
+  it('reports the drift as the amount scrollTop has to grow', () => {
+    const anchor = { turnId: 'turn-1', offsetFromScrollerTop: -120 };
+    // The Turn ended up 880px further down the screen than it was.
+    expect(viewportAnchorCorrectionPx(anchor, 760)).toBe(880);
+  });
+
+  it('is negative when the transcript moved up under the reader', () => {
+    const anchor = { turnId: 'turn-1', offsetFromScrollerTop: 200 };
+    expect(viewportAnchorCorrectionPx(anchor, -60)).toBe(-260);
+  });
+
+  it('is zero when the Turn is where it was', () => {
+    const anchor = { turnId: 'turn-1', offsetFromScrollerTop: 200 };
+    expect(viewportAnchorCorrectionPx(anchor, 200)).toBe(0);
+  });
+});
+
+describe('shouldCaptureViewportAnchorOnScroll', () => {
+  it('captures a scroll the user drove', () => {
+    expect(shouldCaptureViewportAnchorOnScroll(true, 40)).toBe(true);
+  });
+
+  it('ignores a scroll nobody asked for', () => {
+    // The transcript moved under the reader. Re-anchoring here would adopt the
+    // displacement as the new reading position.
+    expect(shouldCaptureViewportAnchorOnScroll(true, USER_DRIVEN_SCROLL_WINDOW_MS + 1))
+      .toBe(false);
+  });
+
+  it('captures without intent when there is no anchor yet', () => {
+    expect(shouldCaptureViewportAnchorOnScroll(false, 10_000)).toBe(true);
+  });
+});
+
+describe('the anchor constants', () => {
+  it('holds the anchor over more than a couple of frames', () => {
+    // A prepend settles through a margin, then padding, then a margin release,
+    // and no single callback covers all of it.
+    expect(ANCHOR_SETTLE_FRAMES).toBeGreaterThan(2);
+  });
+
+  it('keeps the intent window shorter than a deliberate pause', () => {
+    expect(USER_DRIVEN_SCROLL_WINDOW_MS).toBeLessThan(500);
+  });
+});
diff --git a/src/web-ui/src/flow_chat/components/modern/flowChatViewportAnchor.ts b/src/web-ui/src/flow_chat/components/modern/flowChatViewportAnchor.ts
new file mode 100644
index 0000000000..72e8a6baf3
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/modern/flowChatViewportAnchor.ts
@@ -0,0 +1,229 @@
+/**
+ * Geometry for the element-anchored viewport keeper.
+ *
+ * The keeper restores a *relationship* — a Turn at an offset from the viewport
+ * top — rather than replaying a scroll delta. That is what makes it idempotent:
+ * applying it when nothing moved is a no-op, and applying it twice is the same
+ * as applying it once. Every offset here is measured from the scroller's top
+ * edge for the same reason. No absolute `scrollTop` survives a re-measure, but
+ * the offset of a rendered Turn from the viewport top does.
+ *
+ * Nothing here knows which virtualizer placed the items, or that there is one.
+ */
+
+/**
+ * DOM contract for the anchor element.
+ *
+ * A Turn's user message is the anchor: it is the one item every Turn has, it is
+ * short enough that its own height rarely changes under a re-measure, and it is
+ * what the reader is looking for when they scroll back through history.
+ */
+const TURN_ANCHOR_SELECTOR = '.virtual-item-wrapper[data-item-type="user-message"]';
+
+/**
+ * Where the user is reading, expressed as a Turn rather than an offset.
+ *
+ * `scrollTop` is not a stable description of a reading position in a list whose
+ * item heights are discovered lazily: every late measurement rewrites the offset
+ * of everything below it, so the same number means a different place.
+ */
+export interface ViewportAnchor {
+  turnId: string;
+  offsetFromScrollerTop: number;
+}
+
+export interface ViewportAnchorCandidate {
+  turnId: string | null;
+  offsetFromScrollerTop: number;
+  bottomOffsetFromScrollerTop: number;
+}
+
+/**
+ * How long after a wheel, touch, key, or scrollbar press the scrolling it
+ * causes still counts as the user's.
+ *
+ * The anchor has to distinguish "the user went somewhere" from "the transcript
+ * moved underneath them", and a scroll event says nothing about which. Intent
+ * events do — but they fire *before* the scroll they cause, so the position
+ * worth recording is the one that arrives shortly after, not the one at the
+ * moment of the gesture. Recording at the gesture instead is what drags a
+ * scrolling viewport backwards.
+ *
+ * Short enough that a mutation arriving in a pause is not mistaken for the
+ * user. Deliberately *not* long enough to cover every scroll a gesture causes,
+ * and it cannot be: the window runs from the input event while the scrolling it
+ * authorises outlives it, and a busy main thread delivers the whole travel in
+ * one event after it has closed. Measured over 181 seconds of reading:
+ * fourteen gestures produced one capture.
+ *
+ * So this decides whether a *new* Turn is taken as the reading position, not
+ * whether the reader's travel counts. A scroll that falls outside it and that
+ * no registered writer owns is carried instead — see `captureAnchorForScroll`.
+ */
+export const USER_DRIVEN_SCROLL_WINDOW_MS = 200;
+
+/**
+ * Frames the viewport anchor keeps being re-asserted after the transcript moves.
+ *
+ * A virtualizer settles a prepend over several frames — a margin holds the
+ * position, then the real item heights land in padding, then the margin is
+ * released — and a margin change fires no ResizeObserver at all. There is
+ * therefore no single callback that can catch every step, so the anchor is
+ * re-asserted for a window instead. Measured: four consecutive painted frames
+ * displaced by 896px before the correction arrived, which is the flicker.
+ *
+ * Refreshed whenever a correction is actually needed, so a long settle keeps
+ * the window open rather than running out halfway through it.
+ */
+export const ANCHOR_SETTLE_FRAMES = 20;
+
+/**
+ * Attempts an anchored Turn may be missing from the rendered window before the
+ * anchor is given up on.
+ *
+ * Absent for one frame is normal and absent for good is not, and only time
+ * tells them apart. The virtualizer windows from a scroll offset it learns from
+ * scroll events, so the commit that prepends history renders the position the
+ * reader has just been moved off — the Turn arrives a frame later. Dropping on
+ * the first miss threw the reading position away exactly there, at four
+ * junctions in a row.
+ *
+ * Long enough to outlast that, and to cover the settle window it usually runs
+ * inside; short enough that a Turn scrolled far out of the window is released
+ * rather than held onto, since a stale anchor is a correction waiting to
+ * happen. Reaching the end is not a failure — the next scroll anchors to a Turn
+ * that is actually on screen.
+ */
+export const ANCHOR_MISSING_TURN_ATTEMPTS = 20;
+
+/** Below this a correction is rounding, not movement. */
+export const ANCHOR_CORRECTION_EPSILON_PX = 0.5;
+
+/**
+ * Above this a correction is something the reader can feel.
+ *
+ * Used to keep the two apart in the trail, and only there. Corrections repeat
+ * at frame rate so they are coalesced, and a single run collapses whatever it
+ * spans into its first sample: two rounds of diagnosis in a row read `0.7px`
+ * against a suppressed travel of 458.7px over seven samples, which is a
+ * different fault entirely and could not be attributed to any anchor. A run
+ * that a real correction can fall into unseen is not a trail.
+ */
+export const ANCHOR_NOTABLE_CORRECTION_PX = 8;
+
+/**
+ * The topmost Turn the viewport still shows any part of.
+ *
+ * A candidate that has not reached the top edge yet is the one the reader is
+ * looking at, so the first one whose bottom is inside the viewport wins. If
+ * that candidate carries no Turn there is no anchor at all — falling through to
+ * the next one would anchor to a Turn further down the screen than the one the
+ * reading position belongs to.
+ *
+ * **Both edges are tested, and the bottom one is not optional.** A Turn marker
+ * is the Turn's user message, which is short, so a reader inside an answer
+ * taller than the viewport has no marker on screen at all — and "the first one
+ * below the top edge" then answers with the *next* Turn, however far down that
+ * is. Measured: anchored at an offset of 1695.5px with the scroller at most
+ * 1325.7px tall, so the anchor was at least 370px below the bottom edge.
+ *
+ * That is not a near miss, it inverts what the anchor is for. Content above the
+ * viewport re-measuring moves everything below it, the on-screen transcript
+ * included, so a marker above the fold is a faithful proxy for what the reader
+ * sees. Content *below* the viewport re-measuring moves nothing they can see —
+ * so a marker below the fold reports movement that did not happen, and the
+ * correction manufactures the displacement instead of repairing one.
+ *
+ * No anchor is the honest answer there, and it is the one this already gives
+ * when every marker has gone off the top. A reader with no marker on screen
+ * gets no correction; the next scroll takes one as soon as a Turn is visible.
+ */
+export function selectViewportAnchor(
+  candidates: readonly ViewportAnchorCandidate[],
+  viewportHeightPx: number,
+): ViewportAnchor | null {
+  const candidate = candidates.find(entry => (
+    entry.bottomOffsetFromScrollerTop > 0 && entry.offsetFromScrollerTop < viewportHeightPx
+  ));
+  if (!candidate?.turnId) return null;
+  return {
+    turnId: candidate.turnId,
+    offsetFromScrollerTop: candidate.offsetFromScrollerTop,
+  };
+}
+
+/**
+ * How far the anchored Turn has drifted from where it was.
+ *
+ * Positive means it moved down the screen, which is also how much `scrollTop`
+ * has to grow to put it back — the sign is the correction, not its opposite.
+ *
+ * **Only meaningful against an anchor whose offset was agreed at the viewport
+ * position it is being measured from.** A displacement moves the transcript
+ * underneath a `scrollTop` that does not change; that is what makes it a
+ * displacement. So any change to `scrollTop` since the offset was agreed
+ * belongs to whoever made it, and has to be taken into the anchor before this
+ * is asked — the caller does that, and the two halves move together there.
+ *
+ * Subtracting it here instead was tried and is why this note exists. It leaves
+ * the offset and the position it was agreed at free to drift apart, and a frame
+ * with nothing to correct then banks the reader's travel as a debt the next
+ * frame collects: measured as a 32px scroll and an 81px scroll each reported
+ * back as a correction of exactly itself.
+ */
+export function viewportAnchorCorrectionPx(
+  anchor: ViewportAnchor,
+  currentOffsetFromScrollerTop: number,
+): number {
+  return currentOffsetFromScrollerTop - anchor.offsetFromScrollerTop;
+}
+
+/**
+ * Whether a scroll event should move the anchor to where the viewport now is.
+ *
+ * Keying off "did the content height change" instead does not work: lazy
+ * measurement changes it on almost every frame, so the anchor froze seconds in
+ * the past and the keeper spent its corrections dragging a scrolling viewport
+ * backwards. Measured: 1075 blocked captures against 8 accepted ones, and a
+ * 1037px correction against the user's own gesture.
+ *
+ * Having no anchor overrides the window, which is also what bootstraps the very
+ * first one.
+ *
+ * False is not "ignore this scroll". It only means the scroll is not proof of a
+ * new reading position; whether the reader's travel is credited is a separate
+ * question, answered by who owns the viewport.
+ */
+export function shouldCaptureViewportAnchorOnScroll(
+  hasAnchor: boolean,
+  msSinceUserScrollIntent: number,
+): boolean {
+  return !hasAnchor || msSinceUserScrollIntent <= USER_DRIVEN_SCROLL_WINDOW_MS;
+}
+
+export function readViewportAnchorCandidates(scroller: HTMLElement): ViewportAnchorCandidate[] {
+  const scrollerTop = scroller.getBoundingClientRect().top;
+  return Array.from(
+    scroller.querySelectorAll<HTMLElement>(TURN_ANCHOR_SELECTOR),
+  ).map(element => {
+    const rect = element.getBoundingClientRect();
+    return {
+      turnId: element.dataset.turnId ?? null,
+      offsetFromScrollerTop: rect.top - scrollerTop,
+      bottomOffsetFromScrollerTop: rect.bottom - scrollerTop,
+    };
+  });
+}
+
+export function findRenderedTurnAnchorElement(
+  scroller: HTMLElement | null,
+  turnId: string,
+): HTMLElement | null {
+  return Array.from(
+    scroller?.querySelectorAll<HTMLElement>(TURN_ANCHOR_SELECTOR) ?? [],
+  ).find(element => element.dataset.turnId === turnId) ?? null;
+}
+
+export function readTurnAnchorOffsetPx(scroller: HTMLElement, element: HTMLElement): number {
+  return element.getBoundingClientRect().top - scroller.getBoundingClientRect().top;
+}
diff --git a/src/web-ui/src/flow_chat/components/modern/flowChatViewportOwnership.test.ts b/src/web-ui/src/flow_chat/components/modern/flowChatViewportOwnership.test.ts
new file mode 100644
index 0000000000..0587625bdf
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/modern/flowChatViewportOwnership.test.ts
@@ -0,0 +1,200 @@
+import { describe, expect, it } from 'vitest';
+import {
+  activeViewportClaim,
+  canOwnViewport,
+  canShiftViewport,
+  claimViewport,
+  defaultViewportHoldMs,
+  FLOWCHAT_VIEWPORT_OWNERS,
+  releaseViewport,
+  type ViewportClaim,
+} from './flowChatViewportOwnership';
+
+const NOW = 1_000;
+
+/**
+ * A claim already standing. An omitted hold is the shape only an owner that
+ * releases can have — see `defaultViewportHoldMs`.
+ */
+function heldBy(
+  owner: ViewportClaim['owner'],
+  options?: { holdForMs?: number; atMs?: number },
+): ViewportClaim {
+  const claimedAtMs = options?.atMs ?? NOW;
+  return {
+    owner,
+    claimedAtMs,
+    expiresAtMs: options?.holdForMs === undefined
+      ? Number.POSITIVE_INFINITY
+      : claimedAtMs + options.holdForMs,
+  };
+}
+
+describe('the order of viewport owners', () => {
+  it('puts the reader first and the corrections last', () => {
+    // The order is the whole design, so it is asserted rather than assumed.
+    expect(FLOWCHAT_VIEWPORT_OWNERS).toEqual([
+      'user-gesture',
+      'one-shot-navigation',
+      'follow-output',
+      'layout-correction',
+    ]);
+  });
+
+  it('does not rank a displacement repair, which is a different question', () => {
+    // Putting the reader back where a prepend or a late measurement moved them
+    // is `canShiftViewport`, and its answer for the reader's own gesture is the
+    // opposite of what any ranking here could give it.
+    expect(FLOWCHAT_VIEWPORT_OWNERS).not.toContain('anchor-correction');
+  });
+
+  it('does not rank the opening reveal, which is a phase and not a writer', () => {
+    // Follow-output is what moves the viewport while the transcript is hidden.
+    // A claim standing in for the reveal would outrank it and refuse it.
+    expect(FLOWCHAT_VIEWPORT_OWNERS).not.toContain('opening-reveal');
+  });
+});
+
+describe('claimViewport', () => {
+  it('grants an unheld viewport to anyone', () => {
+    const outcome = claimViewport(null, { owner: 'layout-correction', nowMs: NOW });
+    expect(outcome.granted).toBe(true);
+    expect(outcome.claim?.owner).toBe('layout-correction');
+  });
+
+  it('lets a gesture take the viewport from the follow loop', () => {
+    const outcome = claimViewport(heldBy('follow-output'), {
+      owner: 'user-gesture',
+      nowMs: NOW,
+    });
+    expect(outcome.granted).toBe(true);
+    expect(outcome.claim?.owner).toBe('user-gesture');
+  });
+
+  it('leaves the register untouched when it refuses', () => {
+    const held = heldBy('one-shot-navigation', { holdForMs: 600 });
+    const outcome = claimViewport(held, { owner: 'follow-output', nowMs: NOW });
+    expect(outcome.granted).toBe(false);
+    expect(outcome.claim).toEqual(held);
+  });
+
+  it('lets an owner renew its own claim', () => {
+    // How a continuous writer holds on, and how a correction runs on
+    // consecutive frames.
+    const outcome = claimViewport(heldBy('follow-output'), {
+      owner: 'follow-output',
+      nowMs: NOW + 16,
+    });
+    expect(outcome.granted).toBe(true);
+    expect(outcome.claim?.claimedAtMs).toBe(NOW + 16);
+  });
+
+  it('grants a lapsed viewport to a lower priority', () => {
+    const gesture = heldBy('user-gesture', { holdForMs: 200 });
+    const outcome = claimViewport(gesture, {
+      owner: 'layout-correction',
+      nowMs: NOW + 201,
+    });
+    expect(outcome.granted).toBe(true);
+    expect(outcome.claim?.owner).toBe('layout-correction');
+  });
+
+  it('holds a claim without an expiry until it is released', () => {
+    const outcome = claimViewport(null, { owner: 'follow-output', nowMs: NOW });
+    expect(outcome.claim?.expiresAtMs).toBe(Number.POSITIVE_INFINITY);
+    expect(canOwnViewport(outcome.claim, 'layout-correction', NOW + 1_000_000)).toBe(false);
+  });
+
+  it('only lets an owner that releases hold the viewport indefinitely', () => {
+    // Follow-output is the one writer with an `exitFollowOutput`. Everything
+    // else that said nothing about a window would hold the viewport for the
+    // rest of the session, and nothing below it could ever write again.
+    for (const owner of FLOWCHAT_VIEWPORT_OWNERS) {
+      expect(defaultViewportHoldMs(owner)).toBe(
+        owner === 'follow-output' ? Number.POSITIVE_INFINITY : 0,
+      );
+    }
+  });
+
+  it('lapses a one-shot claim that named no window, rather than starving follow', () => {
+    /*
+     * Measured on session open: the virtualizer placed the scroller at 0 before
+     * any aim of ours, the write took an unbounded claim, and follow-output was
+     * refused for the whole opening reveal — the transcript stayed at the top
+     * of its loaded window instead of at the newest Turn.
+     */
+    const stray = claimViewport(null, { owner: 'one-shot-navigation', nowMs: NOW });
+    expect(stray.granted).toBe(true);
+
+    const follow = claimViewport(stray.claim, { owner: 'follow-output', nowMs: NOW });
+    expect(follow.granted).toBe(true);
+    expect(follow.claim?.owner).toBe('follow-output');
+  });
+
+  it('still resolves a correction against whoever holds the viewport', () => {
+    // A zero-length hold is not the absence of a claim: the question it answers
+    // is whether the write happens at all.
+    const outcome = claimViewport(null, {
+      owner: 'layout-correction',
+      nowMs: NOW + 16,
+    });
+    expect(outcome.granted).toBe(true);
+  });
+});
+
+describe('canShiftViewport', () => {
+  it('lets a displacement through while the reader holds the viewport', () => {
+    /*
+     * The failure this separates out: history pages in only while the reader
+     * scrolls up into it, so a gesture refusing the compensation refused all of
+     * them. 2494px of history arrived, `scrollTop` stayed at 40, and the
+     * transcript jumped back thirteen Turns.
+     */
+    expect(canShiftViewport(heldBy('user-gesture', { holdForMs: 200 }), NOW)).toBe(true);
+  });
+
+  it('leaves the displacement to navigation and follow targets', () => {
+    // Those writers re-assert a position of their own. Snap-back is different:
+    // a late history measurement invalidates its target coordinate, so the
+    // displacement must cancel the stale animation and be reconsidered.
+    expect(canShiftViewport(heldBy('follow-output'), NOW)).toBe(false);
+    expect(canShiftViewport(heldBy('one-shot-navigation', { holdForMs: 600 }), NOW)).toBe(false);
+    expect(canShiftViewport(null, NOW)).toBe(true);
+  });
+
+  it('shifts an unheld viewport, and one held only by a correction', () => {
+    expect(canShiftViewport(null, NOW)).toBe(true);
+    expect(canShiftViewport(heldBy('layout-correction', { holdForMs: 0 }), NOW)).toBe(true);
+  });
+
+  it('shifts once a target holder has lapsed', () => {
+    expect(canShiftViewport(heldBy('one-shot-navigation', { holdForMs: 600 }), NOW + 601))
+      .toBe(true);
+  });
+});
+
+describe('activeViewportClaim', () => {
+  it('reports a claim that has not lapsed', () => {
+    const claim = heldBy('user-gesture', { holdForMs: 200 });
+    expect(activeViewportClaim(claim, NOW + 199)).toBe(claim);
+  });
+
+  it('reports nothing once the hold has elapsed', () => {
+    // A missed release costs a bounded wait, never a viewport nobody may write.
+    expect(activeViewportClaim(heldBy('user-gesture', { holdForMs: 200 }), NOW + 200)).toBeNull();
+  });
+});
+
+describe('releaseViewport', () => {
+  it('gives the viewport back', () => {
+    expect(releaseViewport(heldBy('follow-output'), 'follow-output')).toBeNull();
+  });
+
+  it('ignores a release from an owner that was preempted', () => {
+    // Finishing late must not clear the claim of whoever took over: that
+    // release is indistinguishable from the new owner having finished, and it
+    // would hand the viewport to the next corrector mid-movement.
+    const held = heldBy('user-gesture');
+    expect(releaseViewport(held, 'follow-output')).toEqual(held);
+  });
+});
diff --git a/src/web-ui/src/flow_chat/components/modern/flowChatViewportOwnership.ts b/src/web-ui/src/flow_chat/components/modern/flowChatViewportOwnership.ts
new file mode 100644
index 0000000000..90ab519888
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/modern/flowChatViewportOwnership.ts
@@ -0,0 +1,228 @@
+/**
+ * Who is moving the FlowChat viewport right now.
+ *
+ * Several things move it, and each of them has to know not to fight the
+ * others. That was a hand-written predicate per writer, which is O(n²) pairs
+ * and fails the moment one is forgotten: two otherwise valid movements can
+ * fight because one writer was missing from another writer's predicate.
+ *
+ * The pairs collapse into one register. A writer claims the viewport for as
+ * long as it is moving it, and everything else asks the register rather than
+ * asking about each writer.
+ *
+ * The register decides *whether* someone may write. It never decides where the
+ * viewport should go — targets stay with the writer that owns them, and the
+ * correction that restores a reading position stays idempotent. Ordering
+ * answers the question idempotency cannot: whether a movement was ours on
+ * purpose or something to be undone.
+ */
+
+/**
+ * Ordered most authoritative first. The order is the design; everything else
+ * here is bookkeeping.
+ *
+ * - `user-gesture` — the reader's own hands, which nothing overrides.
+ * - `one-shot-navigation` — a Turn, search hit, or focus request being reached.
+ * - `follow-output` — the continuous writer that follows streaming output.
+ * - `layout-correction` — the scroller's own box changed and a viewport nobody
+ *   was following has to be re-aligned to the end it was resting against.
+ *
+ * The last is a correction rather than a movement: it holds the viewport for
+ * the frame it acts in and yields to anything above it, because a movement made
+ * on purpose is not a displacement to undo.
+ *
+ * **Repairing a displacement is not on this list at all.** Putting the reader
+ * back after history arrived above them, or after a late measurement moved the
+ * transcript under them, is `canShiftViewport` — a different question, with a
+ * different answer for the reader's own gesture. See below.
+ *
+ * **The opening reveal is not here, and that is deliberate.** It is a phase
+ * rather than a writer — the thing actually moving the viewport while the
+ * transcript is hidden is follow-output — so ranking it above follow-output
+ * would have follow refused by a claim standing in for itself. One slot cannot
+ * hold a phase and a writer at the same time, so the reveal stays an explicit
+ * condition where corrections are suppressed, alongside this register.
+ */
+export const FLOWCHAT_VIEWPORT_OWNERS = [
+  'user-gesture',
+  'one-shot-navigation',
+  'follow-output',
+  'layout-correction',
+] as const;
+
+export type FlowChatViewportOwner = (typeof FLOWCHAT_VIEWPORT_OWNERS)[number];
+
+function priorityOf(owner: FlowChatViewportOwner): number {
+  return FLOWCHAT_VIEWPORT_OWNERS.indexOf(owner);
+}
+
+/**
+ * How long a one-shot navigation keeps the viewport after issuing its aim.
+ *
+ * The virtualizer re-aims while the measurements under the target move, and
+ * those later writes are the same request — so they have to still be allowed
+ * when they land. There is no signal for the aim settling, so this is a
+ * backstop: long enough to cover the re-aim, short enough that a transcript
+ * which then starts streaming is not held off for noticeably long. A gesture
+ * ends it immediately regardless, which is the rule that matters.
+ */
+export const ONE_SHOT_NAVIGATION_HOLD_MS = 600;
+
+/**
+ * The owners that give the viewport back.
+ *
+ * This is the whole of who may hold it indefinitely, because a claim with no
+ * expiry and no release is a viewport nobody below it can ever write again.
+ * Measured, from the trail this register keeps: a library write at session open
+ * took an unbounded claim, and follow-output was refused eleven times over half
+ * a second while the transcript stood at the top of its loaded window — the
+ * session opened on the wrong Turn and stayed there.
+ *
+ * Everything else states its own window. A gesture goes quiet, an animation may
+ * never report completion, a re-aim runs while measurements settle: each of
+ * those ends by wall clock, and saying nothing means the write is instantaneous
+ * and owns only itself.
+ */
+const OWNERS_THAT_RELEASE: ReadonlySet<FlowChatViewportOwner> = new Set([
+  'follow-output',
+]);
+
+/**
+ * How long a claim stands when the writer does not say.
+ *
+ * Zero is not "no claim": the write still resolves against whoever holds the
+ * viewport, which is the question that decides whether it happens at all. It
+ * only means nothing is held afterwards.
+ */
+export function defaultViewportHoldMs(owner: FlowChatViewportOwner): number {
+  return OWNERS_THAT_RELEASE.has(owner) ? Number.POSITIVE_INFINITY : 0;
+}
+
+export interface ViewportClaim {
+  owner: FlowChatViewportOwner;
+  claimedAtMs: number;
+  /**
+   * When the claim lapses without being renewed.
+   *
+   * Only an owner that releases carries `Infinity`; see `OWNERS_THAT_RELEASE`.
+   * Anything whose end is a wall-clock fact carries its own expiry, so that a
+   * missed release costs a bounded wait rather than a viewport nobody may
+   * write.
+   */
+  expiresAtMs: number;
+}
+
+export interface ViewportClaimRequest {
+  owner: FlowChatViewportOwner;
+  nowMs: number;
+  /** Omitted takes `defaultViewportHoldMs`, which only a releaser may hold. */
+  holdForMs?: number;
+}
+
+export interface ViewportClaimOutcome {
+  granted: boolean;
+  /** The register afterwards, whether or not the claim was granted. */
+  claim: ViewportClaim | null;
+}
+
+/** The claim still standing at `nowMs`, or null once it has lapsed. */
+export function activeViewportClaim(
+  claim: ViewportClaim | null,
+  nowMs: number,
+): ViewportClaim | null {
+  if (!claim) return null;
+  return nowMs < claim.expiresAtMs ? claim : null;
+}
+
+/**
+ * Whether `owner` may write the viewport right now.
+ *
+ * An owner is never blocked by itself: renewing is how a continuous writer
+ * holds on, and re-entering is how a correction runs on consecutive frames.
+ */
+export function canOwnViewport(
+  claim: ViewportClaim | null,
+  owner: FlowChatViewportOwner,
+  nowMs: number,
+): boolean {
+  const held = activeViewportClaim(claim, nowMs);
+  return held === null || priorityOf(owner) <= priorityOf(held.owner);
+}
+
+/**
+ * Take the viewport, if the register allows it.
+ *
+ * A refused claim leaves the register untouched — the point of refusing is that
+ * the writer does not act, and a refusal that still recorded something would
+ * make the next writer's answer depend on who has been turned away.
+ */
+export function claimViewport(
+  claim: ViewportClaim | null,
+  request: ViewportClaimRequest,
+): ViewportClaimOutcome {
+  const held = activeViewportClaim(claim, request.nowMs);
+  if (!canOwnViewport(claim, request.owner, request.nowMs)) {
+    return { granted: false, claim: held };
+  }
+  const holdForMs = request.holdForMs ?? defaultViewportHoldMs(request.owner);
+  return {
+    granted: true,
+    claim: {
+      owner: request.owner,
+      claimedAtMs: request.nowMs,
+      expiresAtMs: request.nowMs + holdForMs,
+    },
+  };
+}
+
+/**
+ * The owners that hold a target and re-assert it.
+ *
+ * `follow-output` recomputes its target every frame, and a navigation's aim is
+ * re-taken by the virtualizer while the measurements under it settle. Both
+ * already say where the reader belongs, so a displacement applied underneath
+ * them is either redundant or a fight.
+ * `user-gesture` is deliberately not one of them, and that is the whole point
+ * of this being a separate question.
+ */
+const OWNERS_THAT_HOLD_A_TARGET: ReadonlySet<FlowChatViewportOwner> = new Set([
+  'one-shot-navigation',
+  'follow-output',
+]);
+
+/**
+ * Whether the viewport may be shifted by a displacement right now.
+ *
+ * A shift is not a movement and does not go through the priority order. It says
+ * "whatever the reader is looking at moved by this much, put it back" — content
+ * arriving above them changes what their offset *means*, and restoring that
+ * meaning is not competing with anyone for where the viewport should be.
+ *
+ * Which is why a gesture cannot refuse one. The reader chose a position in the
+ * transcript, not a number of pixels; refusing on their behalf leaves them
+ * somewhere they did not ask to be. Measured: history pages in only while the
+ * reader scrolls up into it, so a gesture holding the viewport refused every
+ * compensation there was — 2494px of history arrived, `scrollTop` stayed at 40,
+ * and the transcript jumped back thirteen Turns. The boundary then never
+ * re-armed, because the reader was still sitting at the head of the window they
+ * had just been moved to.
+ */
+export function canShiftViewport(claim: ViewportClaim | null, nowMs: number): boolean {
+  const held = activeViewportClaim(claim, nowMs);
+  return held === null || !OWNERS_THAT_HOLD_A_TARGET.has(held.owner);
+}
+
+/**
+ * Give the viewport back.
+ *
+ * Only the current holder can, so a writer that was preempted and finishes
+ * late cannot clear the claim of whoever took it — that release would be
+ * indistinguishable from the new owner having finished, and the register would
+ * hand the viewport to the next corrector mid-movement.
+ */
+export function releaseViewport(
+  claim: ViewportClaim | null,
+  owner: FlowChatViewportOwner,
+): ViewportClaim | null {
+  return claim === null || claim.owner === owner ? null : claim;
+}
diff --git a/src/web-ui/src/flow_chat/components/modern/flowChatVisibleTurns.test.ts b/src/web-ui/src/flow_chat/components/modern/flowChatVisibleTurns.test.ts
new file mode 100644
index 0000000000..a6ea145987
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/modern/flowChatVisibleTurns.test.ts
@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { resolveVisibleFlowChatTurnIds } from './flowChatVisibleTurns';
+
+describe('resolveVisibleFlowChatTurnIds', () => {
+  it('excludes mounted overscan items that are outside the physical viewport', () => {
+    expect(resolveVisibleFlowChatTurnIds([
+      { turnId: 'turn-1', top: -180, bottom: -20 },
+      { turnId: 'turn-2', top: 40, bottom: 260 },
+    ], 0, 800)).toEqual(['turn-2']);
+  });
+
+  it('keeps a Turn visible through its content after its user-message header is gone', () => {
+    expect(resolveVisibleFlowChatTurnIds([
+      { turnId: 'turn-2', top: -120, bottom: 420 },
+      { turnId: 'turn-2', top: 420, bottom: 900 },
+    ], 0, 800)).toEqual(['turn-2']);
+  });
+
+  it('deduplicates visible Turn ids while preserving transcript order', () => {
+    expect(resolveVisibleFlowChatTurnIds([
+      { turnId: 'turn-1', top: -30, bottom: 100 },
+      { turnId: 'turn-1', top: 100, bottom: 300 },
+      { turnId: 'turn-2', top: 300, bottom: 700 },
+    ], 0, 600)).toEqual(['turn-1', 'turn-2']);
+  });
+});
diff --git a/src/web-ui/src/flow_chat/components/modern/flowChatVisibleTurns.ts b/src/web-ui/src/flow_chat/components/modern/flowChatVisibleTurns.ts
new file mode 100644
index 0000000000..9d3eb5f13d
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/modern/flowChatVisibleTurns.ts
@@ -0,0 +1,35 @@
+export interface FlowChatTurnViewportEntry {
+  turnId: string | null;
+  top: number;
+  bottom: number;
+}
+
+/**
+ * Resolve visible Turns from physical item geometry, not the virtualizer's
+ * rendered range. The rendered range includes overscan and a Turn can remain
+ * visible after its user-message header has been virtualized away.
+ */
+export function resolveVisibleFlowChatTurnIds(
+  entries: readonly FlowChatTurnViewportEntry[],
+  viewportTop: number,
+  viewportBottom: number,
+): string[] {
+  const visibleTurnIds: string[] = [];
+  const seenTurnIds = new Set<string>();
+
+  for (const entry of entries) {
+    const { turnId } = entry;
+    if (
+      !turnId
+      || seenTurnIds.has(turnId)
+      || entry.bottom <= viewportTop
+      || entry.top >= viewportBottom
+    ) {
+      continue;
+    }
+    seenTurnIds.add(turnId);
+    visibleTurnIds.push(turnId);
+  }
+
+  return visibleTurnIds;
+}
diff --git a/src/web-ui/src/flow_chat/components/modern/historyProjectionHandoff.ts b/src/web-ui/src/flow_chat/components/modern/historyProjectionHandoff.ts
deleted file mode 100644
index c924cd6489..0000000000
--- a/src/web-ui/src/flow_chat/components/modern/historyProjectionHandoff.ts
+++ /dev/null
@@ -1,18 +0,0 @@
-import type { VirtualItem } from '../../store/modernFlowChatStore';
-
-export interface HistoryProjectionHandoffSnapshot {
-  sessionId: string;
-  reason: string;
-  createdAtMs: number;
-  items: VirtualItem[];
-  mode: 'bottom-tail';
-  targetTurnId: string | null;
-  footerHeightPx: number;
-}
-
-export function activeSessionHistoryProjectionHandoff(
-  snapshot: HistoryProjectionHandoffSnapshot | null,
-  activeSessionId: string | null
-): HistoryProjectionHandoffSnapshot | null {
-  return snapshot?.sessionId === activeSessionId ? snapshot : null;
-}
diff --git a/src/web-ui/src/flow_chat/components/modern/useFlowChatFollowOutput.test.tsx b/src/web-ui/src/flow_chat/components/modern/useFlowChatFollowOutput.test.tsx
index 5daf1ac810..0dcacb698f 100644
--- a/src/web-ui/src/flow_chat/components/modern/useFlowChatFollowOutput.test.tsx
+++ b/src/web-ui/src/flow_chat/components/modern/useFlowChatFollowOutput.test.tsx
@@ -2,20 +2,38 @@
 
 import React, { act } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
+import { flushSync } from 'react-dom';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { tailSpacerPxForViewport } from './flowChatTailFollow';
 import {
-  computeContinuousFollowStep,
-  useFlowChatFollowOutput,
-} from './useFlowChatFollowOutput';
+  TAIL_EASE_ALPHA,
+  TAIL_EASE_LINE_PX,
+  TAIL_EASE_SNAP_ABOVE_PX,
+} from '../../utils/flowChatTailEase';
+import { SMOOTH_SCROLL_STALL_MS, useFlowChatFollowOutput } from './useFlowChatFollowOutput';
+import {
+  useFlowChatViewportOwner,
+  type FlowChatViewportOwnerApi,
+} from './useFlowChatViewportOwner';
+import { USER_DRIVEN_SCROLL_WINDOW_MS } from './flowChatViewportAnchor';
 
 globalThis.IS_REACT_ACT_ENVIRONMENT = true;
 
-type FollowOutputController = ReturnType<typeof useFlowChatFollowOutput>;
+type Controller = ReturnType<typeof useFlowChatFollowOutput>;
+
+const VIEWPORT = 500;
+/** Input-stack footer the harness renders below the transcript. */
+const BOTTOM_INSET = 100;
+/** The spacer the component would render for a given viewport. */
+const spacerFor = (clientHeight: number) => tailSpacerPxForViewport(clientHeight, BOTTOM_INSET);
+const TAIL_SPACER = spacerFor(VIEWPORT);
+/** Matches `tailHoldMaxGapPx(VIEWPORT)`. */
+const MAX_GAP = 300;
 
 function setScrollerMetrics(
   scroller: HTMLElement,
   metrics: { scrollHeight: number; clientHeight: number; scrollTop: number },
-): void {
+) {
   Object.defineProperties(scroller, {
     scrollHeight: { configurable: true, value: metrics.scrollHeight },
     clientHeight: { configurable: true, value: metrics.clientHeight },
@@ -23,412 +41,1449 @@ function setScrollerMetrics(
   });
 }
 
+/**
+ * `turn-N` is the Nth Turn of the session, so the ledger holds N of them.
+ *
+ * A Turn arriving grows the ledger, which is what every test walking `turn-1`
+ * to `turn-2` means. A rollback is the one case where the identity moves and
+ * the ledger does not grow, and those tests state the count themselves.
+ */
+const turnCountFor = (turnId: string) => Number(turnId.replace('turn-', '')) || 1;
+
+interface HarnessProps {
+  latestTurnId: string;
+  /** Turns in the session ledger. Defaults to what `latestTurnId` implies. */
+  dialogTurnCount?: number;
+  isStreaming?: boolean;
+  scroller: HTMLElement;
+  scrollToContentEnd?: (behavior: ScrollBehavior) => void;
+  scrollTurnToTop?: (turnId: string) => boolean;
+  resolveTurnTopScrollTop?: (turnId: string) => number | null;
+  isOpeningViewport?: boolean;
+  onController: (controller: Controller) => void;
+  /** The register the hook writes through, for a test that has to hold it. */
+  onViewportOwner?: (owner: FlowChatViewportOwnerApi) => void;
+}
+
 function Harness({
+  latestTurnId,
+  dialogTurnCount = turnCountFor(latestTurnId),
+  isStreaming = true,
   scroller,
+  scrollToContentEnd = () => {},
+  scrollTurnToTop = () => false,
+  resolveTurnTopScrollTop = () => null,
+  isOpeningViewport = false,
   onController,
-  performAutoFollowScroll,
-  performLatestTurnStickyPin = vi.fn(),
-  canAnimateTailFollow,
-  getAutoFollowTargetScrollTop,
-}: {
-  scroller: HTMLElement;
-  onController: (controller: FollowOutputController) => void;
-  performAutoFollowScroll: () => void;
-  performLatestTurnStickyPin?: () => void;
-  canAnimateTailFollow?: () => boolean;
-  getAutoFollowTargetScrollTop?: (scroller: HTMLElement) => number;
-}) {
+  onViewportOwner,
+}: HarnessProps) {
   const scrollerRef = React.useRef<HTMLElement | null>(scroller);
-  scrollerRef.current = scroller;
-
+  // The real register, not a stand-in: what this hook is allowed to write is
+  // now part of its behaviour, so a permissive fake would test the wrong thing.
+  const viewportOwner = useFlowChatViewportOwner(scrollerRef);
+  onViewportOwner?.(viewportOwner);
   const controller = useFlowChatFollowOutput({
     activeSessionId: 'session-1',
-    latestTurnId: 'turn-2',
-    virtualItemCount: 20,
-    isStreaming: true,
+    latestTurnId,
+    dialogTurnCount,
+    virtualItemCount: 2,
+    isStreaming,
+    isViewportActive: true,
     scrollerRef,
-    performUserFollowScroll: vi.fn(),
-    performAutoFollowScroll,
-    performLatestTurnStickyPin,
-    canAnimateTailFollow,
-    getAutoFollowTargetScrollTop,
+    // Sized from live layout, exactly as the component's state does.
+    getTailSpacerPx: () => tailSpacerPxForViewport(scroller.clientHeight, BOTTOM_INSET),
+    scrollToContentEnd,
+    scrollTurnToTop,
+    resolveTurnTopScrollTop,
+    isOpeningViewport: () => isOpeningViewport,
+    viewportOwner,
   });
-
   onController(controller);
-  return <div data-following-output={String(controller.isFollowingOutput)} />;
+  return <div data-following={String(controller.isFollowingOutput)} />;
 }
 
 describe('useFlowChatFollowOutput', () => {
   let container: HTMLDivElement;
   let root: Root;
-  let controller: FollowOutputController | null;
+  let scroller: HTMLDivElement;
+  let controller: Controller | null;
+  let frames: FrameRequestCallback[];
+  let scrollTo: ReturnType<typeof vi.fn>;
+
+  function runNextFrame() {
+    const frame = frames.shift();
+    expect(frame).toBeDefined();
+    act(() => frame?.(16));
+  }
 
   beforeEach(() => {
     container = document.createElement('div');
-    document.body.appendChild(container);
+    scroller = document.createElement('div');
+    document.body.append(container, scroller);
+    // jsdom has no layout engine, so the animated scroll is a no-op here and
+    // the tests place the viewport where the animation would have left it.
+    scrollTo = vi.fn();
+    scroller.scrollTo = scrollTo as unknown as HTMLElement['scrollTo'];
     root = createRoot(container);
     controller = null;
+    frames = [];
     vi.stubGlobal('requestAnimationFrame', vi.fn((callback: FrameRequestCallback) => {
-      void callback;
-      return 1;
+      frames.push(callback);
+      return frames.length;
     }));
     vi.stubGlobal('cancelAnimationFrame', vi.fn());
   });
 
   afterEach(() => {
-    act(() => {
-      root.unmount();
-    });
+    act(() => root.unmount());
     container.remove();
+    scroller.remove();
     vi.unstubAllGlobals();
   });
 
-  it('eases a small tail gap without using a second full-scroll action', () => {
-    expect(computeContinuousFollowStep(24, 1000 / 60)).toBeGreaterThan(0);
-    expect(computeContinuousFollowStep(24, 1000 / 60)).toBeLessThan(24);
-    expect(computeContinuousFollowStep(240, 1000 / 60)).toBeLessThanOrEqual(32);
-    expect(computeContinuousFollowStep(Number.NaN, 1000 / 60)).toBe(0);
-
-    const queuedFrames: FrameRequestCallback[] = [];
-    let nextFrameId = 0;
-    vi.stubGlobal('requestAnimationFrame', vi.fn((callback: FrameRequestCallback) => {
-      queuedFrames.push(callback);
-      nextFrameId += 1;
-      return nextFrameId;
-    }));
-
-    const scroller = document.createElement('div');
-    setScrollerMetrics(scroller, {
-      scrollHeight: 1500,
-      clientHeight: 500,
-      scrollTop: 1000,
-    });
-    const performAutoFollowScroll = vi.fn(() => {
-      scroller.scrollTop = scroller.scrollHeight - scroller.clientHeight;
-    });
+  it('opens a newly submitted Turn at the viewport top instead of the tail', () => {
+    const scrollTurnToTop = vi.fn(() => true);
+    const scrollToContentEnd = vi.fn();
+    const props = {
+      scroller,
+      scrollToContentEnd,
+      scrollTurnToTop,
+      onController: (next: Controller) => { controller = next; },
+    };
 
     act(() => {
-      root.render(
-        <Harness
-          scroller={scroller}
-          onController={nextController => {
-            controller = nextController;
-          }}
-          performAutoFollowScroll={performAutoFollowScroll}
-        />,
-      );
+      root.render(<Harness {...props} latestTurnId="turn-1" isStreaming={false} />);
     });
+    // Mount settles on the content end; only the *new Turn* must not.
+    expect(scrollToContentEnd).toHaveBeenCalledWith('auto');
+    scrollToContentEnd.mockClear();
 
     act(() => {
-      controller?.enterFollowOutput('auto-follow');
+      root.render(<Harness {...props} latestTurnId="turn-2" isStreaming={false} />);
     });
-    expect(performAutoFollowScroll).toHaveBeenCalledTimes(1);
 
-    setScrollerMetrics(scroller, {
-      scrollHeight: 1524,
-      clientHeight: 500,
-      scrollTop: 1000,
-    });
-    const firstFollowFrame = queuedFrames.shift();
-    expect(firstFollowFrame).toBeDefined();
+    expect(scrollTurnToTop).toHaveBeenCalledWith('turn-2');
+    expect(scrollToContentEnd).not.toHaveBeenCalled();
+    expect(controller?.isFollowingOutput).toBe(true);
+  });
+
+  it('does not read a rolled-back Turn as a newly arrived one', () => {
+    /*
+     * Measured as a report: send a message, watch it pin, roll it back, and the
+     * Turn *before* it takes the viewport top. `latestTurnId` is right — it is
+     * the ledger's last Turn — but the detector asked whether the identity had
+     * changed, and a truncation changes it without anything having arrived.
+     */
+    const scrollTurnToTop = vi.fn(() => true);
+    const props = {
+      scroller,
+      scrollTurnToTop,
+      onController: (next: Controller) => { controller = next; },
+    };
 
     act(() => {
-      firstFollowFrame?.(1000 / 60);
+      root.render(<Harness {...props} latestTurnId="turn-2" isStreaming={false} />);
     });
+    scrollTurnToTop.mockClear();
 
+    // The rollback removes turn-2, so the ledger's last Turn is turn-1 again.
     act(() => {
-      controller?.scheduleFollowToLatest('observer-growth');
+      root.render(
+        <Harness {...props} latestTurnId="turn-1" dialogTurnCount={1} isStreaming={false} />,
+      );
     });
 
-    expect(performAutoFollowScroll).toHaveBeenCalledTimes(1);
-    expect(scroller.scrollTop).toBeGreaterThan(1000);
-    expect(scroller.scrollTop).toBeLessThan(1024);
+    expect(scrollTurnToTop).not.toHaveBeenCalled();
   });
 
-  it('does not animate until the tail coordinator owns the viewport', () => {
-    const queuedFrames: FrameRequestCallback[] = [];
-    let nextFrameId = 0;
-    vi.stubGlobal('requestAnimationFrame', vi.fn((callback: FrameRequestCallback) => {
-      queuedFrames.push(callback);
-      nextFrameId += 1;
-      return nextFrameId;
-    }));
+  it('returns to the end of the transcript when a rollback takes the Turn it was following', () => {
+    const scrollToContentEnd = vi.fn();
+    const props = {
+      scroller,
+      scrollToContentEnd,
+      scrollTurnToTop: () => true,
+      onController: (next: Controller) => { controller = next; },
+    };
 
-    const scroller = document.createElement('div');
-    setScrollerMetrics(scroller, {
-      scrollHeight: 1500,
-      clientHeight: 500,
-      scrollTop: 1000,
+    act(() => {
+      root.render(<Harness {...props} latestTurnId="turn-2" isStreaming={false} />);
     });
-    const performAutoFollowScroll = vi.fn(() => {
-      scroller.scrollTop = scroller.scrollHeight - scroller.clientHeight;
+    scrollToContentEnd.mockClear();
+
+    act(() => {
+      root.render(
+        <Harness {...props} latestTurnId="turn-1" dialogTurnCount={1} isStreaming={false} />,
+      );
     });
+    // Nothing on its own: a shorter ledger is not a reason to move, because
+    // hydration and window merges write it too.
+    expect(scrollToContentEnd).not.toHaveBeenCalled();
 
+    // The rollback says so itself, and the answer is the tail.
+    act(() => { controller?.handleTurnsRolledBack(); });
+    expect(scrollToContentEnd).toHaveBeenCalledWith('auto');
+  });
+
+  it('settles a rollback on the new tail even after the reader took the viewport', () => {
+    /*
+     * Gating this on ownership made it dead code in the case it was written
+     * for. Reaching a Turn far enough up to want it gone means scrolling, and
+     * scrolling is what hands the viewport back to the reader — so the answer
+     * never ran, the anchor held the reader's Turn at its offset from the
+     * viewport top, and an 8-Turn session rolled back at Turn 7 came to rest on
+     * Turns 2..6 with the new last Turn's answer below the fold.
+     *
+     * Taking it is safe because a rollback at Turn N
+     * removes N and everything after it, and N was on screen. The new tail is
+     * within a Turn of where the reader already is.
+     */
+    const scrollToContentEnd = vi.fn();
     act(() => {
       root.render(
         <Harness
+          latestTurnId="turn-2"
+          isStreaming={false}
           scroller={scroller}
-          onController={nextController => {
-            controller = nextController;
-          }}
-          performAutoFollowScroll={performAutoFollowScroll}
-          canAnimateTailFollow={() => false}
+          scrollToContentEnd={scrollToContentEnd}
+          onController={next => { controller = next; }}
         />,
       );
     });
+    act(() => { controller?.handleUserScrollIntent(); });
+    expect(controller?.isFollowingOutput).toBe(false);
+    scrollToContentEnd.mockClear();
+
+    act(() => { controller?.handleTurnsRolledBack(); });
+    expect(scrollToContentEnd).toHaveBeenCalledWith('auto');
+    expect(controller?.isFollowingOutput).toBe(true);
+  });
 
+  it('settles on the content end when a session opens without streaming', () => {
+    const scrollToContentEnd = vi.fn();
     act(() => {
-      controller?.enterFollowOutput('auto-follow');
+      root.render(
+        <Harness
+          latestTurnId="turn-1"
+          isStreaming={false}
+          scroller={scroller}
+          scrollToContentEnd={scrollToContentEnd}
+          onController={next => { controller = next; }}
+        />,
+      );
     });
+
+    expect(scrollToContentEnd).toHaveBeenCalledWith('auto');
+    expect(controller?.isFollowingOutput).toBe(true);
+  });
+
+  it('tracks the content end exactly while the transcript is still opening', () => {
+    // The virtualizer compensates a history prepend by writing scrollTop before the
+    // prepended heights reach the DOM. While opening, the transcript is hidden
+    // and we are authoritative — accommodating that write would be invisible
+    // now and permanent once paging stops.
     setScrollerMetrics(scroller, {
-      scrollHeight: 1524,
-      clientHeight: 500,
-      scrollTop: 1000,
+      scrollHeight: 1500 + TAIL_SPACER,
+      clientHeight: VIEWPORT,
+      scrollTop: 0,
     });
-    const firstFollowFrame = queuedFrames.shift();
-    expect(firstFollowFrame).toBeDefined();
-
     act(() => {
-      firstFollowFrame?.(1000 / 60);
+      root.render(
+        <Harness
+          latestTurnId="turn-1"
+          scroller={scroller}
+          isOpeningViewport
+          onController={next => { controller = next; }}
+        />,
+      );
     });
+    runNextFrame();
+    expect(scroller.scrollTop).toBe(1000);
 
-    expect(performAutoFollowScroll).toHaveBeenCalledTimes(1);
+    scroller.scrollTop = 1000 + 380;
+    runNextFrame();
     expect(scroller.scrollTop).toBe(1000);
   });
 
-  it('does not animate upward when the effective target moves backward', () => {
-    const queuedFrames: FrameRequestCallback[] = [];
-    let nextFrameId = 0;
-    vi.stubGlobal('requestAnimationFrame', vi.fn((callback: FrameRequestCallback) => {
-      queuedFrames.push(callback);
-      nextFrameId += 1;
-      return nextFrameId;
-    }));
-
-    const scroller = document.createElement('div');
+  it('does not strand the viewport inside the tail spacer after opening', () => {
+    // Regression: the gap tolerance is a streaming allowance. Applied to a
+    // foreign forward move it parked the content end mid-viewport forever,
+    // because nothing pulls the target back down once paging stops.
     setScrollerMetrics(scroller, {
-      scrollHeight: 1500,
-      clientHeight: 500,
-      scrollTop: 1000,
+      scrollHeight: 1500 + TAIL_SPACER,
+      clientHeight: VIEWPORT,
+      scrollTop: 0,
     });
-    const performAutoFollowScroll = vi.fn();
-
     act(() => {
       root.render(
         <Harness
+          latestTurnId="turn-1"
           scroller={scroller}
-          onController={nextController => {
-            controller = nextController;
-          }}
-          performAutoFollowScroll={performAutoFollowScroll}
-          getAutoFollowTargetScrollTop={() => 980}
+          isOpeningViewport
+          onController={next => { controller = next; }}
         />,
       );
     });
+    runNextFrame();
+
+    scroller.scrollTop = 1000 + 380;
+    runNextFrame();
+    expect(scroller.scrollTop).toBe(1000);
+    expect(1000).toBeLessThan(1000 + MAX_GAP);
+  });
+
+  it('falls back to the content end when the new Turn cannot be targeted', () => {
+    const scrollToContentEnd = vi.fn();
+    const props = {
+      scroller,
+      scrollToContentEnd,
+      scrollTurnToTop: () => false,
+      onController: (next: Controller) => { controller = next; },
+    };
 
     act(() => {
-      controller?.enterFollowOutput('auto-follow');
+      root.render(<Harness {...props} latestTurnId="turn-1" isStreaming={false} />);
     });
-    const firstFollowFrame = queuedFrames.shift();
-    expect(firstFollowFrame).toBeDefined();
-
     act(() => {
-      firstFollowFrame?.(1000 / 60);
+      root.render(<Harness {...props} latestTurnId="turn-2" isStreaming={false} />);
     });
 
-    expect(scroller.scrollTop).toBe(1000);
+    expect(scrollToContentEnd).toHaveBeenCalledWith('auto');
+    expect(controller?.isFollowingOutput).toBe(true);
   });
 
-  it('exits output follow immediately when explicit user scroll intent is already away from bottom', () => {
-    const scroller = document.createElement('div');
+  it('holds the pinned Turn at the top while its answer is shorter than the viewport', () => {
+    // Real content ends at 1200, so the tail target is 700 — well above the
+    // pinned Turn at 900. The pin must win until the answer overflows.
     setScrollerMetrics(scroller, {
-      scrollHeight: 1500,
-      clientHeight: 500,
-      scrollTop: 1000,
-    });
-    const performAutoFollowScroll = vi.fn(() => {
-      scroller.scrollTop = 1000;
+      scrollHeight: 1200 + TAIL_SPACER,
+      clientHeight: VIEWPORT,
+      scrollTop: 900,
     });
+    const props = {
+      scroller,
+      scrollTurnToTop: () => true,
+      resolveTurnTopScrollTop: () => 900,
+      onController: (next: Controller) => { controller = next; },
+    };
 
     act(() => {
-      root.render(
-        <Harness
-          scroller={scroller}
-          onController={nextController => {
-            controller = nextController;
-          }}
-          performAutoFollowScroll={performAutoFollowScroll}
-        />,
-      );
+      root.render(<Harness {...props} latestTurnId="turn-1" />);
     });
-
     act(() => {
-      controller?.enterFollowOutput('auto-follow');
+      root.render(<Harness {...props} latestTurnId="turn-2" />);
     });
 
-    expect(controller?.isFollowingOutput).toBe(true);
+    scroller.scrollTop = 0;
+    runNextFrame();
+    expect(scroller.scrollTop).toBe(900);
+  });
 
+  it('hands the pinned Turn off to tail follow once the answer overflows', () => {
     setScrollerMetrics(scroller, {
-      scrollHeight: 1500,
-      clientHeight: 500,
-      scrollTop: 600,
+      scrollHeight: 2000 + TAIL_SPACER,
+      clientHeight: VIEWPORT,
+      scrollTop: 900,
     });
+    const props = {
+      scroller,
+      scrollTurnToTop: () => true,
+      resolveTurnTopScrollTop: () => 900,
+      onController: (next: Controller) => { controller = next; },
+    };
 
     act(() => {
-      controller?.handleUserScrollIntent();
+      root.render(<Harness {...props} latestTurnId="turn-1" />);
+    });
+    act(() => {
+      root.render(<Harness {...props} latestTurnId="turn-2" />);
     });
 
-    expect(controller?.isFollowingOutput).toBe(false);
+    runNextFrame();
+    // Content end (2000 - 500) has overtaken the pin, so the tail owns it.
+    expect(scroller.scrollTop).toBe(1500);
   });
 
-  it('exits output follow for explicit upward intent before browser scroll metrics move', () => {
-    const scroller = document.createElement('div');
+  it('follows content growth against the content end, not the tail spacer', () => {
     setScrollerMetrics(scroller, {
-      scrollHeight: 1500,
-      clientHeight: 500,
+      scrollHeight: 1500 + TAIL_SPACER,
+      clientHeight: VIEWPORT,
       scrollTop: 1000,
     });
-    const performAutoFollowScroll = vi.fn(() => {
-      scroller.scrollTop = 1000;
-    });
 
     act(() => {
       root.render(
         <Harness
+          latestTurnId="turn-1"
           scroller={scroller}
-          onController={nextController => {
-            controller = nextController;
-          }}
-          performAutoFollowScroll={performAutoFollowScroll}
+          onController={next => { controller = next; }}
         />,
       );
     });
+    expect(controller?.isFollowingOutput).toBe(true);
 
-    act(() => {
-      controller?.enterFollowOutput('auto-follow');
+    setScrollerMetrics(scroller, {
+      scrollHeight: 1800 + TAIL_SPACER,
+      clientHeight: VIEWPORT,
+      scrollTop: 1000,
     });
+    runNextFrame();
 
-    expect(controller?.isFollowingOutput).toBe(true);
+    expect(scroller.scrollTop).toBe(1300);
+  });
 
+  it('holds its offset when a collapse shrinks content under the viewport', () => {
+    // The regression this whole mechanism exists for: a tool card collapsing
+    // above the live output must not drag earlier content down.
+    setScrollerMetrics(scroller, {
+      scrollHeight: 1500 + TAIL_SPACER,
+      clientHeight: VIEWPORT,
+      scrollTop: 0,
+    });
     act(() => {
-      controller?.handleUserScrollIntent();
+      root.render(
+        <Harness
+          latestTurnId="turn-1"
+          scroller={scroller}
+          onController={next => { controller = next; }}
+        />,
+      );
     });
+    runNextFrame();
+    expect(scroller.scrollTop).toBe(1000);
 
-    expect(controller?.isFollowingOutput).toBe(false);
+    setScrollerMetrics(scroller, {
+      scrollHeight: 1200 + TAIL_SPACER,
+      clientHeight: VIEWPORT,
+      scrollTop: 1000,
+    });
+    runNextFrame();
+
+    expect(scroller.scrollTop).toBe(1000);
   });
 
-  it('cancels armed auto-follow when upward intent arrives during the programmatic guard', () => {
-    const scroller = document.createElement('div');
+  it('gives ground only past the tolerated gap after a very large collapse', () => {
     setScrollerMetrics(scroller, {
-      scrollHeight: 1500,
-      clientHeight: 500,
-      scrollTop: 1000,
+      scrollHeight: 1500 + TAIL_SPACER,
+      clientHeight: VIEWPORT,
+      scrollTop: 0,
+    });
+    act(() => {
+      root.render(
+        <Harness
+          latestTurnId="turn-1"
+          scroller={scroller}
+          onController={next => { controller = next; }}
+        />,
+      );
     });
-    const performAutoFollowScroll = vi.fn(() => {
-      scroller.scrollTop = 1000;
+    runNextFrame();
+
+    setScrollerMetrics(scroller, {
+      scrollHeight: 700 + TAIL_SPACER,
+      clientHeight: VIEWPORT,
+      scrollTop: 1000,
     });
+    runNextFrame();
+
+    expect(scroller.scrollTop).toBe(200 + MAX_GAP);
+  });
 
+  it('does not force the content end when a resize re-asserts follow', () => {
+    const scrollToContentEnd = vi.fn();
+    setScrollerMetrics(scroller, {
+      scrollHeight: 1500 + TAIL_SPACER,
+      clientHeight: VIEWPORT,
+      scrollTop: 0,
+    });
     act(() => {
       root.render(
         <Harness
+          latestTurnId="turn-1"
           scroller={scroller}
-          onController={nextController => {
-            controller = nextController;
-          }}
-          performAutoFollowScroll={performAutoFollowScroll}
+          scrollToContentEnd={scrollToContentEnd}
+          onController={next => { controller = next; }}
         />,
       );
     });
+    runNextFrame();
+    scrollToContentEnd.mockClear();
+
+    setScrollerMetrics(scroller, {
+      scrollHeight: 1200 + TAIL_SPACER,
+      clientHeight: VIEWPORT,
+      scrollTop: 1000,
+    });
+    act(() => controller?.scheduleFollowToLatest());
 
+    expect(scrollToContentEnd).not.toHaveBeenCalled();
+    expect(scroller.scrollTop).toBe(1000);
+  });
+
+  it('settles the held blank once streaming stops', () => {
+    const scrollToContentEnd = vi.fn();
+    const props = {
+      scroller,
+      scrollToContentEnd,
+      onController: (next: Controller) => { controller = next; },
+    };
+    setScrollerMetrics(scroller, {
+      scrollHeight: 1500 + TAIL_SPACER,
+      clientHeight: VIEWPORT,
+      scrollTop: 0,
+    });
     act(() => {
-      controller?.armFollowOutputForNewTurn();
+      root.render(<Harness {...props} latestTurnId="turn-1" />);
     });
+    runNextFrame();
 
-    expect(controller?.isFollowingOutput).toBe(false);
+    setScrollerMetrics(scroller, {
+      scrollHeight: 1200 + TAIL_SPACER,
+      clientHeight: VIEWPORT,
+      scrollTop: 1000,
+    });
+    runNextFrame();
+    scrollToContentEnd.mockClear();
 
     act(() => {
-      controller?.handleUserScrollIntent();
+      root.render(<Harness {...props} latestTurnId="turn-1" isStreaming={false} />);
     });
 
-    let activated = true;
+    expect(scrollToContentEnd).toHaveBeenCalledWith('smooth');
+  });
+
+  it('lets explicit user scroll intent exit follow immediately', () => {
     act(() => {
-      activated = controller?.activateArmedFollowOutput() ?? true;
+      root.render(
+        <Harness
+          latestTurnId="turn-1"
+          scroller={scroller}
+          onController={next => { controller = next; }}
+        />,
+      );
     });
+    act(() => controller?.enterFollowOutput('jump-to-latest'));
+    expect(controller?.isFollowingOutput).toBe(true);
 
-    expect(activated).toBe(false);
+    act(() => controller?.handleUserScrollIntent());
     expect(controller?.isFollowingOutput).toBe(false);
+    expect(cancelAnimationFrame).toHaveBeenCalled();
   });
 
-  it('keeps a sticky pin armed while clearing logical follow ownership', () => {
-    const scroller = document.createElement('div');
+  /** Mount on a transcript of `contentEndPx`, then jump to latest from the top. */
+  function jumpToLatestAcross(contentEndPx: number) {
+    const scrollToContentEnd = vi.fn();
     setScrollerMetrics(scroller, {
-      scrollHeight: 1500,
-      clientHeight: 500,
-      scrollTop: 1000,
+      scrollHeight: contentEndPx + VIEWPORT + TAIL_SPACER,
+      clientHeight: VIEWPORT,
+      scrollTop: 0,
     });
-    const performAutoFollowScroll = vi.fn();
-
     act(() => {
       root.render(
         <Harness
+          latestTurnId="turn-1"
           scroller={scroller}
-          onController={nextController => {
-            controller = nextController;
-          }}
-          performAutoFollowScroll={performAutoFollowScroll}
+          scrollToContentEnd={scrollToContentEnd}
+          onController={next => { controller = next; }}
         />,
       );
     });
+    runNextFrame();
+    expect(scroller.scrollTop).toBe(contentEndPx);
+    scroller.scrollTop = 0;
+    scrollToContentEnd.mockClear();
+    act(() => controller?.enterFollowOutput('jump-to-latest'));
+    return scrollToContentEnd;
+  }
 
-    act(() => {
-      controller?.enterFollowOutput('auto-follow');
-      controller?.preparePinnedTurnFollowHandoff();
-    });
+  it('uses smooth behavior only for an explicit jump to latest', () => {
+    // Well inside `FLOWCHAT_ANIMATED_JUMP_MAX_VIEWPORTS`, so the distance is not
+    // what this is testing.
+    expect(jumpToLatestAcross(VIEWPORT)).toHaveBeenCalledWith('smooth');
+  });
 
-    expect(controller?.isFollowingOutput).toBe(false);
+  it('lands a near jump immediately when reduced motion is requested', () => {
+    vi.stubGlobal('matchMedia', vi.fn(() => ({ matches: true })));
 
-    let activated = false;
-    act(() => {
-      activated = controller?.activateArmedFollowOutput() ?? false;
-    });
+    expect(jumpToLatestAcross(VIEWPORT)).toHaveBeenCalledWith('auto');
+  });
 
-    expect(activated).toBe(true);
-    expect(controller?.isFollowingOutput).toBe(true);
+  it('lands a jump too far to follow rather than animate part of it', () => {
+    /*
+     * The animation cannot finish this and the frame loop takes the viewport
+     * back wherever it has got to — measured, a jump issued for 8717px animated
+     * 5480 of them and was finished in one 3290px write. The reader sees two
+     * thirds of a scroll and then a jump, which is worse than either.
+     *
+     * It would not be worth watching even if it did finish: three screens on,
+     * the transcript in between is going past faster than anyone can read it,
+     * so the continuity an animation exists to show is not there to see.
+     */
+    expect(jumpToLatestAcross(VIEWPORT * 10)).toHaveBeenCalledWith('auto');
   });
 
-  it('resumes a mounted streaming session at the tail without replaying sticky pin', () => {
-    const scroller = document.createElement('div');
+  it('yields the frame loop to its own animated scroll instead of overwriting it', () => {
+    // The loop assigns scrollTop outright, which cancels an in-flight smooth
+    // scroll on the very next frame: `jump-to-latest` asked for an animation
+    // and got a jump.
     setScrollerMetrics(scroller, {
-      scrollHeight: 1500,
-      clientHeight: 500,
+      scrollHeight: 1500 + TAIL_SPACER,
+      clientHeight: VIEWPORT,
       scrollTop: 0,
     });
-    const performAutoFollowScroll = vi.fn(() => {
-      scroller.scrollTop = 1000;
-    });
-    const performLatestTurnStickyPin = vi.fn();
-
     act(() => {
       root.render(
         <Harness
+          latestTurnId="turn-1"
           scroller={scroller}
-          onController={nextController => {
-            controller = nextController;
-          }}
-          performAutoFollowScroll={performAutoFollowScroll}
-          performLatestTurnStickyPin={performLatestTurnStickyPin}
+          onController={next => { controller = next; }}
         />,
       );
     });
+    runNextFrame();
+    expect(scroller.scrollTop).toBe(1000);
 
-    let resumed = false;
-    act(() => {
-      resumed = controller?.resumeFollowOutputForMountedStream() ?? false;
+    scroller.scrollTop = 0;
+    act(() => controller?.enterFollowOutput('jump-to-latest'));
+    runNextFrame();
+
+    expect(scroller.scrollTop).toBe(0);
+  });
+
+  describe('standing down for its own animated scroll', () => {
+    /**
+     * A clock the test moves by hand.
+     *
+     * The stand-down ends on a *duration* without travel, so a test that runs
+     * its frames in microseconds of real time proves nothing about it either
+     * way. Every frame below states how much time it took.
+     */
+    let nowMs = 0;
+    let nowSpy: ReturnType<typeof vi.spyOn>;
+
+    beforeEach(() => {
+      nowMs = 1_000;
+      nowSpy = vi.spyOn(performance, 'now').mockImplementation(() => nowMs);
     });
 
-    expect(resumed).toBe(true);
-    expect(controller?.isFollowingOutput).toBe(true);
-    expect(performAutoFollowScroll).toHaveBeenCalledTimes(1);
-    expect(performLatestTurnStickyPin).not.toHaveBeenCalled();
+    afterEach(() => {
+      nowSpy.mockRestore();
+    });
+
+    /*
+     * A viewport tall enough that the jump below is one the follow rule agrees
+     * to animate at all: only a jump inside
+     * `FLOWCHAT_ANIMATED_JUMP_MAX_VIEWPORTS` is animated, and everything in
+     * this block is about what happens *during* an animation, so it has to be
+     * given one. The distance is left where it was so the frame counts below
+     * still mean what their comments say.
+     */
+    const TALL_VIEWPORT = 1_600;
+    const CONTENT_END = 4_500;
+
+    /**
+     * Mounts a transcript whose content ends at `CONTENT_END`, settles there,
+     * and then issues an animated jump to latest from the top.
+     *
+     * jsdom does not animate, so the animation is played by hand below. That is
+     * the point of these tests: what ends the stand-down is the viewport having
+     * stopped moving, and only a test that moves it can tell that apart from a
+     * budget running out.
+     */
+    function jumpToLatestFromTheTop() {
+      setScrollerMetrics(scroller, {
+        scrollHeight: CONTENT_END + TALL_VIEWPORT + spacerFor(TALL_VIEWPORT),
+        clientHeight: TALL_VIEWPORT,
+        scrollTop: 0,
+      });
+      act(() => {
+        root.render(
+          <Harness
+            latestTurnId="turn-1"
+            scroller={scroller}
+            onController={next => { controller = next; }}
+          />,
+        );
+      });
+      runNextFrame();
+      expect(scroller.scrollTop).toBe(CONTENT_END);
+      scroller.scrollTop = 0;
+      act(() => controller?.enterFollowOutput('jump-to-latest'));
+    }
+
+    /** One frame, `forMs` after the last, in which the animation moved `byPx`. */
+    function animateFrame(byPx: number, forMs = 5) {
+      nowMs += forMs;
+      scroller.scrollTop += byPx;
+      runNextFrame();
+    }
+
+    it('stays out of the way for as long as the animation is still travelling', () => {
+      // The stand-down used to be 45 frames, which is 0.75s at 60Hz and 0.52s
+      // on a busy 200Hz display — measured, a jump issued for 8717px animated
+      // 5480 of them and was finished by the loop in one 3290px write.
+      jumpToLatestFromTheTop();
+
+      for (let frame = 0; frame < 60; frame += 1) {
+        animateFrame(50);
+        expect(scroller.scrollTop).toBe(50 * (frame + 1));
+      }
+    });
+
+    it('sits through the frames a smooth scroll takes to visibly start', () => {
+      /*
+       * The regression this pair of constants exists for. A programmatic smooth
+       * scroll eases in — measured on WebView2, 2px in its first 50ms against
+       * 9734px to travel — and with scroll offsets quantised to 0.8px the early
+       * frames genuinely do not move. Counting two still *frames* took the
+       * viewport back 21ms after asking for the animation, and the reader saw
+       * an instant jump.
+       */
+      jumpToLatestFromTheTop();
+
+      for (let frame = 0; frame < 20; frame += 1) {
+        animateFrame(0);
+      }
+      expect(scroller.scrollTop).toBe(0);
+
+      // 100ms in, still inside the window, and the animation finally shows.
+      animateFrame(0.8);
+      expect(scroller.scrollTop).toBe(0.8);
+    });
+
+    it('resumes once the animation stops moving the viewport', () => {
+      jumpToLatestFromTheTop();
+      animateFrame(50);
+
+      // Still inside the window a stalling animation is given.
+      animateFrame(0, SMOOTH_SCROLL_STALL_MS - 10);
+      expect(scroller.scrollTop).toBe(50);
+
+      animateFrame(0, 20);
+      expect(scroller.scrollTop).toBe(CONTENT_END);
+    });
+
+    it('takes the viewport back on the backstop when the animation never ends', () => {
+      jumpToLatestFromTheTop();
+      // Travelling the whole time, so nothing but the backstop can end this.
+      for (let frame = 0; frame < 12; frame += 1) {
+        animateFrame(1, 100);
+      }
+
+      expect(scroller.scrollTop).toBe(CONTENT_END);
+    });
+  });
+
+  describe('easing the follow across the frames it has', () => {
+    /** Mounts a streaming transcript resting exactly on its content end. */
+    function followFromContentEnd() {
+      setScrollerMetrics(scroller, {
+        scrollHeight: 1500 + TAIL_SPACER,
+        clientHeight: VIEWPORT,
+        scrollTop: 1000,
+      });
+      act(() => {
+        root.render(
+          <Harness
+            latestTurnId="turn-1"
+            scroller={scroller}
+            onController={next => { controller = next; }}
+          />,
+        );
+      });
+    }
+
+    /** Grows real content by `byPx`, which is what moves the follow target. */
+    function growContentBy(byPx: number) {
+      setScrollerMetrics(scroller, {
+        scrollHeight: 1500 + byPx + TAIL_SPACER,
+        clientHeight: VIEWPORT,
+        scrollTop: scroller.scrollTop,
+      });
+    }
+
+    it('spends a line of growth over the frames that were empty', () => {
+      // Markdown reflows a line at a time, so an outright write puts all 24px
+      // on one frame out of seven and none on the rest.
+      followFromContentEnd();
+      growContentBy(TAIL_EASE_LINE_PX);
+
+      runNextFrame();
+
+      expect(scroller.scrollTop).toBeCloseTo(1000 + TAIL_EASE_LINE_PX * TAIL_EASE_ALPHA, 5);
+      expect(scroller.scrollTop - 1000).toBeLessThan(TAIL_EASE_LINE_PX);
+    });
+
+    it('keeps stepping until it has landed on the target', () => {
+      followFromContentEnd();
+      growContentBy(TAIL_EASE_LINE_PX);
+
+      let previousPx = 1000;
+      for (let frame = 0; frame < 20; frame += 1) {
+        runNextFrame();
+        // Every step is under a line: that is the bar the ease has to clear to
+        // be worth having, since a line is what it set out to replace.
+        expect(scroller.scrollTop - previousPx).toBeLessThan(TAIL_EASE_LINE_PX);
+        previousPx = scroller.scrollTop;
+      }
+
+      // Inside the loop's own `BOTTOM_EPSILON_PX`, where it stops writing at
+      // all — the ease converges on the target rather than stalling short of
+      // it or ringing around it.
+      expect(1000 + TAIL_EASE_LINE_PX - scroller.scrollTop).toBeLessThan(2);
+      expect(scroller.scrollTop).toBeLessThanOrEqual(1000 + TAIL_EASE_LINE_PX);
+    });
+
+    it('jumps when an ease would open with a bigger step than the jump it replaces', () => {
+      // A burst arriving further behind than four lines: a quarter of that is
+      // already worse than having simply gone the whole way.
+      followFromContentEnd();
+      growContentBy(TAIL_EASE_SNAP_ABOVE_PX + 100);
+
+      runNextFrame();
+
+      expect(scroller.scrollTop).toBe(1000 + TAIL_EASE_SNAP_ABOVE_PX + 100);
+    });
+
+    it('does not ease while the transcript is still opening', () => {
+      // The reveal waits for the viewport to reach the content end, and while
+      // it waits nothing is painted — so an ease there is travel nobody sees,
+      // holding open the one phase whose whole point is to be over.
+      setScrollerMetrics(scroller, {
+        scrollHeight: 1500 + TAIL_SPACER,
+        clientHeight: VIEWPORT,
+        scrollTop: 1000,
+      });
+      act(() => {
+        root.render(
+          <Harness
+            latestTurnId="turn-1"
+            scroller={scroller}
+            isOpeningViewport
+            onController={next => { controller = next; }}
+          />,
+        );
+      });
+      growContentBy(TAIL_EASE_LINE_PX);
+
+      runNextFrame();
+
+      expect(scroller.scrollTop).toBe(1000 + TAIL_EASE_LINE_PX);
+    });
+
+    it('goes the whole way at once when content shrinks under the viewport', () => {
+      // Easing down through a shrink reads as the transcript being clawed
+      // backwards, which is worse than the jump it would replace.
+      followFromContentEnd();
+      setScrollerMetrics(scroller, {
+        scrollHeight: 700 + TAIL_SPACER,
+        clientHeight: VIEWPORT,
+        scrollTop: 1000,
+      });
+
+      runNextFrame();
+
+      // Past the tolerated gap, so the hold rule gives ground — in one step.
+      expect(scroller.scrollTop).toBe(200 + MAX_GAP);
+    });
+  });
+
+  describe('jumping to latest while the newest Turn is pinned', () => {
+    /** Pins `turn-2` at 900 with real content ending at 1200 (tail target 700). */
+    function pinLatestTurn(overrides?: { resolveTurnTopScrollTop?: () => number | null }) {
+      setScrollerMetrics(scroller, {
+        scrollHeight: 1200 + TAIL_SPACER,
+        clientHeight: VIEWPORT,
+        scrollTop: 900,
+      });
+      const props = {
+        scroller,
+        scrollTurnToTop: () => true,
+        resolveTurnTopScrollTop: overrides?.resolveTurnTopScrollTop ?? (() => 900),
+        onController: (next: Controller) => { controller = next; },
+      };
+      act(() => {
+        root.render(<Harness {...props} latestTurnId="turn-1" isStreaming={false} />);
+      });
+      act(() => {
+        root.render(<Harness {...props} latestTurnId="turn-2" isStreaming={false} />);
+      });
+    }
+
+    it('returns to the pin rather than the end of content', () => {
+      // Restoring the tail presentation asks for a jump to latest one frame
+      // after the Turn that caused it got pinned, which used to overwrite the
+      // pin. Aiming at the content end here also scrolls *up*, shoving the
+      // message the user just sent into the middle of the viewport.
+      const scrollToContentEnd = vi.fn();
+      setScrollerMetrics(scroller, {
+        scrollHeight: 1200 + TAIL_SPACER,
+        clientHeight: VIEWPORT,
+        scrollTop: 900,
+      });
+      const props = {
+        scroller,
+        scrollToContentEnd,
+        scrollTurnToTop: () => true,
+        resolveTurnTopScrollTop: () => 900,
+        onController: (next: Controller) => { controller = next; },
+      };
+      act(() => {
+        root.render(<Harness {...props} latestTurnId="turn-1" isStreaming={false} />);
+      });
+      scrollToContentEnd.mockClear();
+      act(() => {
+        root.render(<Harness {...props} latestTurnId="turn-2" isStreaming={false} />);
+      });
+
+      act(() => controller?.enterFollowOutput('jump-to-latest'));
+
+      expect(scrollToContentEnd).not.toHaveBeenCalled();
+      scroller.scrollTop = 0;
+      runNextFrame();
+      expect(scroller.scrollTop).toBe(900);
+    });
+
+    it('animates back to the pin instead of jumping', () => {
+      // The frame loop assigns scrollTop outright, so without the yield budget
+      // this branch was an instant move where every other jump to latest is
+      // animated.
+      pinLatestTurn();
+      scroller.scrollTop = 0;
+      scrollTo.mockClear();
+
+      act(() => controller?.enterFollowOutput('jump-to-latest'));
+
+      expect(scrollTo).toHaveBeenCalledWith({ top: 900, behavior: 'smooth' });
+      runNextFrame();
+      // jsdom does not animate, so the loop must have left the viewport alone.
+      expect(scroller.scrollTop).toBe(0);
+    });
+
+    it('resumes at the content end once the pin has been retired', () => {
+      // The exemption is only for a Turn whose answer still fits one viewport.
+      // Past the crossover the pin is gone and the ordinary rule applies.
+      const scrollToContentEnd = vi.fn();
+      setScrollerMetrics(scroller, {
+        scrollHeight: 2000 + TAIL_SPACER,
+        clientHeight: VIEWPORT,
+        scrollTop: 900,
+      });
+      const props = {
+        scroller,
+        scrollToContentEnd,
+        scrollTurnToTop: () => true,
+        resolveTurnTopScrollTop: () => 900,
+        onController: (next: Controller) => { controller = next; },
+      };
+      act(() => {
+        root.render(<Harness {...props} latestTurnId="turn-1" isStreaming={false} />);
+      });
+      act(() => {
+        root.render(<Harness {...props} latestTurnId="turn-2" isStreaming={false} />);
+      });
+      // Content end (1500) has overtaken the pin, which retires it.
+      runNextFrame();
+      scrollToContentEnd.mockClear();
+
+      act(() => controller?.enterFollowOutput('jump-to-latest'));
+
+      expect(scrollToContentEnd).toHaveBeenCalledWith('smooth');
+    });
+  });
+
+  describe('user-controlled reserved blank', () => {
+    it('keeps a reader in the blank after their scroll ends', () => {
+      setScrollerMetrics(scroller, {
+        scrollHeight: 1500 + TAIL_SPACER,
+        clientHeight: VIEWPORT,
+        scrollTop: 0,
+      });
+      act(() => {
+        root.render(
+          <Harness
+            latestTurnId="turn-1"
+            isStreaming={false}
+            scroller={scroller}
+            onController={next => { controller = next; }}
+          />,
+        );
+      });
+      act(() => controller?.handleUserScrollIntent());
+      scrollTo.mockClear();
+
+      scroller.scrollTop = 1000 + TAIL_SPACER;
+      act(() => controller?.handleScroll());
+
+      expect(scroller.scrollTop).toBe(1000 + TAIL_SPACER);
+      expect(scrollTo).not.toHaveBeenCalled();
+      expect(controller?.isFollowingOutput).toBe(false);
+    });
+  });
+
+  describe('anchoring the viewport bottom across a resize', () => {
+    /** Mounts at the content end, then hands the viewport to the user. */
+    function restAtContentEnd() {
+      setScrollerMetrics(scroller, {
+        scrollHeight: 1500 + spacerFor(VIEWPORT),
+        clientHeight: VIEWPORT,
+        scrollTop: 0,
+      });
+      act(() => {
+        root.render(
+          <Harness
+            latestTurnId="turn-1"
+            isStreaming={false}
+            scroller={scroller}
+            onController={next => { controller = next; }}
+          />,
+        );
+      });
+      runNextFrame();
+      expect(scroller.scrollTop).toBe(1000);
+      act(() => controller?.handleUserScrollIntent());
+    }
+
+    /** Content and footer stay at 1500; only the viewport, and so the spacer, change. */
+    function resizeViewportTo(clientHeight: number, scrollTop: number) {
+      setScrollerMetrics(scroller, {
+        scrollHeight: 1500 + spacerFor(clientHeight),
+        clientHeight,
+        scrollTop,
+      });
+    }
+
+    it('keeps content against the viewport bottom when the viewport grows', () => {
+      // A viewport 200px taller lowers the content end by 200px. Without the
+      // clamp the spacer removed, the resting viewport is left that far into
+      // the blank.
+      restAtContentEnd();
+      resizeViewportTo(VIEWPORT + 200, 1000);
+
+      act(() => controller?.handleViewportResize({
+        viewportHeightDeltaPx: 200,
+        wasAtTail: true,
+      }));
+
+      expect(scroller.scrollTop).toBe(800);
+    });
+
+    it('keeps content against the viewport bottom when the viewport shrinks', () => {
+      // The opposite direction: the content end moves down past the viewport,
+      // cutting off the bottom of what was on screen.
+      restAtContentEnd();
+      resizeViewportTo(VIEWPORT - 200, 1000);
+
+      act(() => controller?.handleViewportResize({
+        viewportHeightDeltaPx: -200,
+        wasAtTail: true,
+      }));
+
+      expect(scroller.scrollTop).toBe(1200);
+    });
+
+    it('anchors the bottom for a viewport reading history too', () => {
+      // The rule is not about the tail. A plain scroller preserves scrollTop
+      // and reveals or swallows content at the bottom edge; for a transcript
+      // the bottom edge is the one worth holding still.
+      restAtContentEnd();
+      resizeViewportTo(VIEWPORT + 200, 600);
+
+      act(() => controller?.handleViewportResize({
+        viewportHeightDeltaPx: 200,
+        wasAtTail: false,
+      }));
+
+      expect(scroller.scrollTop).toBe(400);
+    });
+
+    it('does not drag a viewport reading history to the tail', () => {
+      restAtContentEnd();
+      resizeViewportTo(VIEWPORT - 200, 600);
+
+      act(() => controller?.handleViewportResize({
+        viewportHeightDeltaPx: -200,
+        wasAtTail: false,
+      }));
+
+      // Bottom-anchored, and nowhere near the content end at 1200.
+      expect(scroller.scrollTop).toBe(800);
+    });
+
+    it('corrects instantly, since the content does not appear to move', () => {
+      restAtContentEnd();
+      scrollTo.mockClear();
+      resizeViewportTo(VIEWPORT + 200, 1000);
+
+      act(() => controller?.handleViewportResize({
+        viewportHeightDeltaPx: 200,
+        wasAtTail: true,
+      }));
+
+      expect(scrollTo).not.toHaveBeenCalled();
+    });
+
+    it('does not hand the viewport back to follow', () => {
+      // A gesture ending in the blank means "take me to the end"; a layout
+      // change means nothing at all.
+      restAtContentEnd();
+      resizeViewportTo(VIEWPORT + 200, 1000);
+
+      act(() => controller?.handleViewportResize({
+        viewportHeightDeltaPx: 200,
+        wasAtTail: true,
+      }));
+
+      expect(controller?.isFollowingOutput).toBe(false);
+    });
+
+    it('follows the content end while a reflow keeps moving it', () => {
+      // A width change reflows every item, and arithmetic cannot track where
+      // the bottom line went. The end of the transcript is the one position
+      // that can be recomputed, so a viewport resting on it is put back on it —
+      // repeatedly, because the virtualizer re-estimates over several passes.
+      restAtContentEnd();
+
+      // Narrower: the same text wraps into 300px more content.
+      setScrollerMetrics(scroller, {
+        scrollHeight: 1800 + spacerFor(VIEWPORT),
+        clientHeight: VIEWPORT,
+        scrollTop: 1000,
+      });
+      act(() => controller?.handleViewportResize({
+        viewportHeightDeltaPx: 0,
+        wasAtTail: true,
+      }));
+      expect(scroller.scrollTop).toBe(1300);
+
+      // Re-measurement adds another 200px above the viewport.
+      setScrollerMetrics(scroller, {
+        scrollHeight: 2000 + spacerFor(VIEWPORT),
+        clientHeight: VIEWPORT,
+        scrollTop: 1300,
+      });
+      act(() => controller?.handleViewportResize({
+        viewportHeightDeltaPx: 0,
+        wasAtTail: true,
+      }));
+      expect(scroller.scrollTop).toBe(1500);
+    });
+
+    it('leaves a reflow alone for a viewport that was not at the end', () => {
+      restAtContentEnd();
+      setScrollerMetrics(scroller, {
+        scrollHeight: 1800 + spacerFor(VIEWPORT),
+        clientHeight: VIEWPORT,
+        scrollTop: 200,
+      });
+
+      act(() => controller?.handleViewportResize({
+        viewportHeightDeltaPx: 0,
+        wasAtTail: false,
+      }));
+
+      expect(scroller.scrollTop).toBe(200);
+    });
+
+    it('does not pull a user-controlled blank position back to the tail', () => {
+      restAtContentEnd();
+      setScrollerMetrics(scroller, {
+        scrollHeight: 1800 + spacerFor(VIEWPORT),
+        clientHeight: VIEWPORT,
+        scrollTop: 1600,
+      });
+
+      act(() => controller?.handleViewportResize({
+        viewportHeightDeltaPx: 0,
+        wasAtTail: false,
+      }));
+
+      expect(scroller.scrollTop).toBe(1600);
+      expect(controller?.isFollowingOutput).toBe(false);
+    });
+  });
+
+  describe('ownership across renders', () => {
+    /*
+     * Ownership is a ref because the loop reads it between renders, and it was
+     * *also* assigned from the `isFollowingOutput` state on every render. Those
+     * two writers disagree for exactly as long as a state update is queued, and
+     * React is free to render in that window: an update scheduled from a
+     * passive effect sits at a lower priority than a synchronous render, which
+     * then renders the value from before it and put the ref back to `false`.
+     *
+     * Measured on session open, which is where this always happens — the entry
+     * comes from a mount effect: `followOutput.enter` recorded, then the very
+     * first frame of the loop stood down with `not-following` and its settle
+     * budget untouched, and no `followOutput.exit` anywhere in the trail
+     * because nothing had exited. The register still held `follow-output`, so
+     * the prepend compensation for a history window that arrived 90ms later was
+     * left to a writer that was no longer running, and the transcript stayed at
+     * offset 0 — the top of the window, eight Turns above the tail.
+     */
+    it('survives a render that has not seen the entry yet', () => {
+      act(() => {
+        root.render(
+          <Harness
+            scroller={scroller}
+            latestTurnId="turn-1"
+            isStreaming={false}
+            onController={(next) => { controller = next; }}
+          />,
+        );
+      });
+      act(() => controller?.handleUserScrollIntent());
+      expect(controller?.isFollowingOutputNow()).toBe(false);
+
+      // Outside `act`, so the state update this schedules is still queued.
+      controller?.enterFollowOutput('jump-to-latest');
+      expect(controller?.isFollowingOutputNow()).toBe(true);
+
+      // A synchronous render, which does not carry the queued update.
+      flushSync(() => {
+        root.render(
+          <Harness
+            scroller={scroller}
+            latestTurnId="turn-1"
+            isStreaming={false}
+            onController={(next) => { controller = next; }}
+          />,
+        );
+      });
+
+      expect(controller?.isFollowingOutputNow()).toBe(true);
+    });
+  });
+
+  /*
+   * Scrolling up gives the follow away, and the reserved blank is what makes
+   * that too blunt on its own: a reader can leave the tail by a hundred pixels
+   * and still be looking at empty space below the newest output, having missed
+   * nothing. The departure watches those readers until the blank is gone, and
+   * which side closed it decides who keeps the viewport.
+   */
+  describe('resuming a follow that output caught up with', () => {
+    const CONTENT_END = 1_000;
+    let viewportOwner: FlowChatViewportOwnerApi | null = null;
+
+    /** Move the end of real content, leaving the viewport where it is. */
+    function setContentEnd(contentEndPx: number) {
+      Object.defineProperty(scroller, 'scrollHeight', {
+        configurable: true,
+        value: contentEndPx + VIEWPORT + TAIL_SPACER,
+      });
+    }
+
+    /**
+     * Mount a following transcript, then have the reader take the viewport from
+     * `blankPx` into the reserved blank — `0` being the end of real content, on
+     * the viewport's bottom edge. Returns the one-shot scroll, so a test can
+     * assert nothing reached for it.
+     */
+    function departWithBlank(blankPx: number) {
+      const scrollToContentEnd = vi.fn();
+      setScrollerMetrics(scroller, {
+        scrollHeight: CONTENT_END + VIEWPORT + TAIL_SPACER,
+        clientHeight: VIEWPORT,
+        scrollTop: CONTENT_END,
+      });
+      act(() => {
+        root.render(
+          <Harness
+            latestTurnId="turn-1"
+            scroller={scroller}
+            scrollToContentEnd={scrollToContentEnd}
+            onController={next => { controller = next; }}
+            onViewportOwner={next => { viewportOwner = next; }}
+          />,
+        );
+      });
+      expect(controller?.isFollowingOutput).toBe(true);
+      scrollToContentEnd.mockClear();
+      frames.length = 0;
+
+      scroller.scrollTop = CONTENT_END + blankPx;
+      act(() => controller?.handleUserScrollIntent());
+      expect(controller?.isFollowingOutput).toBe(false);
+      return scrollToContentEnd;
+    }
+
+    it('takes the viewport back when output fills the blank under a stationary reader', () => {
+      departWithBlank(100);
+
+      // The resize observer's signal, which is the only one that arrives when
+      // the content moves and the reader does not.
+      setContentEnd(CONTENT_END + 150);
+      act(() => controller?.scheduleFollowToLatest());
+
+      expect(controller?.isFollowingOutput).toBe(true);
+    });
+
+    it('resumes where the reader is instead of scrolling them to the end', () => {
+      const scrollToContentEnd = departWithBlank(100);
+      setContentEnd(CONTENT_END + 150);
+      act(() => controller?.scheduleFollowToLatest());
+
+      // Nothing to travel that the follow loop is not already about to cover:
+      // the blank closing *is* the two offsets meeting. What is left is the one
+      // sample of growth that closed it, and the loop eases that away — a
+      // quarter of the 50px on the first frame it runs, which is the one the
+      // resume's own re-render asks for.
+      expect(scrollToContentEnd).not.toHaveBeenCalled();
+      expect(scroller.scrollTop).toBe(CONTENT_END + 100 + 50 * TAIL_EASE_ALPHA);
+    });
+
+    it('leaves the viewport with a reader whose hand is still on it', () => {
+      /*
+       * Measured: 320ms into a live gesture, a reader had climbed 200px while
+       * content grew 237, so the crossing was attributed to the content — which
+       * is correct, and acting on it would still have been wrong.
+       */
+      departWithBlank(400);
+      viewportOwner?.claim('user-gesture', { holdForMs: USER_DRIVEN_SCROLL_WINDOW_MS });
+
+      scroller.scrollTop = CONTENT_END + 200;
+      setContentEnd(CONTENT_END + 237);
+      act(() => controller?.handleScroll());
+
+      expect(controller?.isFollowingOutput).toBe(false);
+    });
+
+    it('leaves a reader who climbed out past the content end reading history', () => {
+      departWithBlank(100);
+
+      scroller.scrollTop = CONTENT_END - 300;
+      act(() => controller?.handleScroll());
+      // Output arriving afterwards must not fetch them back down.
+      setContentEnd(CONTENT_END + 150);
+      act(() => controller?.scheduleFollowToLatest());
+
+      expect(controller?.isFollowingOutput).toBe(false);
+    });
+
+    it('leaves a reader who was never in the blank where they are', () => {
+      // Nothing crossed: they were above the end of content when they took the
+      // viewport and they are still above it. Only a transition is a question.
+      departWithBlank(0);
+
+      setContentEnd(CONTENT_END + 150);
+      act(() => controller?.scheduleFollowToLatest());
+
+      expect(controller?.isFollowingOutput).toBe(false);
+    });
+
+    it('follows a reader who left the blank and came back down into it', () => {
+      /*
+       * The case a per-departure watch got wrong, and the reason the watch runs
+       * for as long as the reader holds the viewport. Measured as a report:
+       * scroll up until the blank is gone, scroll back down until it shows
+       * again, wait — and nothing happened, because the one crossing the watch
+       * was given had been spent on the way up.
+       */
+      departWithBlank(400);
+
+      // Up and out of the blank entirely.
+      scroller.scrollTop = CONTENT_END - 200;
+      act(() => controller?.handleScroll());
+      expect(controller?.isFollowingOutput).toBe(false);
+
+      // Back down until the blank is on screen again, and stop.
+      scroller.scrollTop = CONTENT_END + 300;
+      act(() => controller?.handleScroll());
+      expect(controller?.isFollowingOutput).toBe(false);
+
+      setContentEnd(CONTENT_END + 300);
+      act(() => controller?.scheduleFollowToLatest());
+
+      expect(controller?.isFollowingOutput).toBe(true);
+    });
+
+    it('watches a reader who took the viewport from a follow that was already gone', () => {
+      // Every wheel notch exits, and only the first finds follow to give up.
+      // Gating the watch on that notch left the rest of the gesture unwatched.
+      departWithBlank(0);
+      act(() => controller?.handleUserScrollIntent());
+
+      scroller.scrollTop = CONTENT_END + 300;
+      act(() => controller?.handleScroll());
+      setContentEnd(CONTENT_END + 300);
+      act(() => controller?.scheduleFollowToLatest());
+
+      expect(controller?.isFollowingOutput).toBe(true);
+    });
+
+    it('reads nothing into a viewport a history prepend has just shifted', () => {
+      /*
+       * Measured: a session opened on three Turns, one scroll up paged the whole
+       * seven, and the prepend shifted the viewport 14252px to hold the reader's
+       * Turn still — before those heights were in the scroll range, so the blank
+       * between the two read as 6239px against a spacer of a few hundred. Taken
+       * at face value that is a reader sitting deep in the blank, which is the
+       * one state this rule acts on, and the next sample would have pulled them
+       * out of the history they had just asked for.
+       */
+      departWithBlank(0);
+
+      // The compensation: the viewport moves, the content end has not caught up.
+      scroller.scrollTop = CONTENT_END + TAIL_SPACER + 5_000;
+      act(() => controller?.handleScroll());
+      // ...and now it has. Nothing crossed, because nothing was ever measured.
+      setContentEnd(CONTENT_END + TAIL_SPACER + 5_000);
+      act(() => controller?.scheduleFollowToLatest());
+
+      expect(controller?.isFollowingOutput).toBe(false);
+    });
+
+    it('judges a vetoed crossing again rather than spending it', () => {
+      /*
+       * The veto is about the reader's hand being on the wheel, not about the
+       * crossing being wrong. Deferring costs one sample; settling it would cost
+       * the whole episode.
+       */
+      departWithBlank(400);
+      viewportOwner?.claim('user-gesture', { holdForMs: USER_DRIVEN_SCROLL_WINDOW_MS });
+
+      setContentEnd(CONTENT_END + 400);
+      act(() => controller?.scheduleFollowToLatest());
+      expect(controller?.isFollowingOutput).toBe(false);
+
+      // The claim lapses, the reader has not moved, and output is still coming.
+      viewportOwner?.release('user-gesture');
+      setContentEnd(CONTENT_END + 420);
+      act(() => controller?.scheduleFollowToLatest());
+
+      expect(controller?.isFollowingOutput).toBe(true);
+    });
+
+    it('lets a reader who kept climbing through a vetoed crossing go', () => {
+      departWithBlank(400);
+      viewportOwner?.claim('user-gesture', { holdForMs: USER_DRIVEN_SCROLL_WINDOW_MS });
+
+      setContentEnd(CONTENT_END + 400);
+      act(() => controller?.scheduleFollowToLatest());
+      expect(controller?.isFollowingOutput).toBe(false);
+
+      // Still climbing, and now out-moving the content: the deferred crossing
+      // resolves against them, and the latch is spent for good.
+      scroller.scrollTop = CONTENT_END + 100;
+      setContentEnd(CONTENT_END + 410);
+      act(() => controller?.handleScroll());
+      viewportOwner?.release('user-gesture');
+      setContentEnd(CONTENT_END + 430);
+      act(() => controller?.scheduleFollowToLatest());
+
+      expect(controller?.isFollowingOutput).toBe(false);
+    });
+
+    it('keeps watching while the blank is only partly filled', () => {
+      departWithBlank(400);
+
+      setContentEnd(CONTENT_END + 150);
+      act(() => controller?.scheduleFollowToLatest());
+      expect(controller?.isFollowingOutput).toBe(false);
+
+      setContentEnd(CONTENT_END + 400);
+      act(() => controller?.scheduleFollowToLatest());
+      expect(controller?.isFollowingOutput).toBe(true);
+    });
   });
 });
diff --git a/src/web-ui/src/flow_chat/components/modern/useFlowChatFollowOutput.ts b/src/web-ui/src/flow_chat/components/modern/useFlowChatFollowOutput.ts
index 48c1557937..ea988aa541 100644
--- a/src/web-ui/src/flow_chat/components/modern/useFlowChatFollowOutput.ts
+++ b/src/web-ui/src/flow_chat/components/modern/useFlowChatFollowOutput.ts
@@ -1,552 +1,1480 @@
-/**
- * Follow-output controller for the modern virtualized FlowChat list.
- *
- * Keeps follow state local to the viewport layer while separating the
- * "when should we follow" policy from the low-level list scroll mechanics.
- */
-
 import { useCallback, useEffect, useRef, useState, type RefObject } from 'react';
-
-const PROGRAMMATIC_SCROLL_GUARD_MS = 160;
-const AUTO_FOLLOW_BOTTOM_THRESHOLD_PX = 24;
-const USER_SCROLL_DIRECTION_EPSILON_PX = 0.5;
-const USER_SCROLL_INTENT_WINDOW_MS = 450;
-const USER_SCROLL_INTENT_PROGRAMMATIC_GRACE_MS = 80;
-const CONTINUOUS_FOLLOW_TIME_CONSTANT_MS = 70;
-const CONTINUOUS_FOLLOW_MIN_STEP_PX = 0.75;
-const CONTINUOUS_FOLLOW_MAX_STEP_PX = 32;
-const CONTINUOUS_FOLLOW_SNAP_THRESHOLD_PX = 0.5;
-const CONTINUOUS_FOLLOW_MAX_ANIMATED_DISTANCE_PX = 96;
-const CONTINUOUS_FOLLOW_MAX_FRAME_DELTA_MS = 34;
-const NATIVE_SMOOTH_FOLLOW_GRACE_MS = 320;
-
-export function computeContinuousFollowStep(
-  distancePx: number,
-  frameDeltaMs: number,
-): number {
-  const distance = Number.isFinite(distancePx) ? Math.max(0, distancePx) : 0;
-  if (distance <= CONTINUOUS_FOLLOW_SNAP_THRESHOLD_PX) {
-    return distance;
-  }
-
-  const deltaMs = Number.isFinite(frameDeltaMs)
-    ? Math.min(CONTINUOUS_FOLLOW_MAX_FRAME_DELTA_MS, Math.max(0, frameDeltaMs))
-    : 0;
-  const easedStep = distance * (
-    1 - Math.exp(-deltaMs / CONTINUOUS_FOLLOW_TIME_CONSTANT_MS)
-  );
-  const step = Math.min(
-    distance,
-    CONTINUOUS_FOLLOW_MAX_STEP_PX,
-    Math.max(CONTINUOUS_FOLLOW_MIN_STEP_PX, easedStep),
-  );
-
-  return distance - step <= CONTINUOUS_FOLLOW_SNAP_THRESHOLD_PX
-    ? distance
-    : step;
-}
-
-export type FollowOutputEnterReason = 'jump-to-latest' | 'auto-follow';
+import {
+  isViewportDiagnosticsEnabled,
+  roundViewportPx,
+  traceViewport,
+  traceViewportRepeating,
+} from '@/infrastructure/diagnostics/flowChatViewportDiagnostics';
+import {
+  isTailFollowDiagnosticsEnabled,
+  noteTailFollowStep,
+} from '@/infrastructure/diagnostics/flowChatTailFollowDiagnostics';
+import {
+  nextEasedScrollTopPx,
+  shouldEaseTailFollow,
+} from '../../utils/flowChatTailEase';
+import { getMotionAwareScrollBehavior } from '../../utils/motionPreference';
+import type { FlowChatViewportOwnerApi } from './useFlowChatViewportOwner';
+import {
+  contentEndScrollTop,
+  FLOWCHAT_AT_CONTENT_END_THRESHOLD_PX,
+  isTailBlankMeasurable,
+  memorylessFollowState,
+  nextTailFollowState,
+  resolveAnimatedJumpBehavior,
+  resolveTailDepartureCrossing,
+  shouldResumeFollowAfterDeparture,
+  tailHoldMaxGapPx,
+  type TailFollowState,
+} from './flowChatTailFollow';
+
+export type FollowOutputEnterReason =
+  | 'jump-to-latest'
+  | 'new-turn'
+  | 'session-open'
+  | 'streaming-resumed'
+  | 'tail-caught-up'
+  | 'turns-rolled-back';
 export type FollowOutputExitReason =
   | 'session-changed'
-  | 'user-scroll-up'
+  | 'user-scroll'
   | 'scroll-to-turn'
-  | 'scroll-to-index'
-  | 'pin-turn-to-top';
+  | 'scroll-to-index';
+
+/**
+ * Why a watch over a reader who owns the viewport ended.
+ *
+ * All four are follow taking it back or the transcript going away. A *crossing*
+ * is deliberately not on this list: the reader can climb out of the reserved
+ * blank and scroll back down into it any number of times before either happens,
+ * and each of those is another chance for output to catch up with them.
+ */
+type TailWatchOutcome =
+  /** Something handed the viewport back — a new Turn, a jump, a snap, this. */
+  | 'followed-again'
+  | 'navigated'
+  | 'session-changed'
+  | 'unmounted';
 
 interface UseFlowChatFollowOutputOptions {
   activeSessionId?: string;
   latestTurnId: string | null;
+  /**
+   * Turns in the session ledger, so that an arrival can be told from a
+   * truncation. `latestTurnId` alone cannot: a rollback moves it backwards to a
+   * Turn that has been there all along, which is a change and not an arrival.
+   */
+  dialogTurnCount: number;
   virtualItemCount: number;
   isStreaming: boolean;
+  isViewportActive: boolean;
   scrollerRef: RefObject<HTMLElement | null>;
-  performUserFollowScroll: () => void;
-  performAutoFollowScroll: () => void;
-  performLatestTurnStickyPin: () => void;
+  /** Height of the resident tail spacer currently rendered below the content. */
+  getTailSpacerPx: () => number;
+  /** One-shot scroll placing the end of real content at the viewport bottom. */
+  scrollToContentEnd: (behavior: ScrollBehavior) => void;
+  /** One-shot scroll placing a Turn's user message at the viewport top. */
+  scrollTurnToTop: (turnId: string) => boolean;
+  /** Offset that would place a Turn's user message at the viewport top, if rendered. */
+  resolveTurnTopScrollTop: (turnId: string) => number | null;
+  /** True while the transcript is still hidden for the opening reveal. */
+  isOpeningViewport: () => boolean;
   /**
-   * Returns true when auto-follow should be suspended for layout-protection
-   * reasons (collapse animation, layout transition, pending collapse intent).
-   * Both the event-driven `scheduleFollowToLatest` and the continuous follow
-   * loop honour this signal: while a known collapse animation is in flight we
-   * must not fight the anchor-lock + bottom-reservation machinery, otherwise
-   * the conversation visibly "sinks down" each time content above shrinks.
-   * The continuous loop keeps requesting frames while suspended and resumes
-   * bottom-tracking on the next frame after the suspension clears.
+   * Who is moving the viewport. Every write below goes through it, so that
+   * nothing else has to carry a private opinion about when this hook is busy.
    */
-  shouldSuspendAutoFollow?: () => boolean;
-  canAnimateTailFollow?: () => boolean;
-  getAutoFollowTargetScrollTop?: (scroller: HTMLElement) => number;
+  viewportOwner: FlowChatViewportOwnerApi;
   /**
-   * Optional per-frame hook invoked from inside the continuous follow loop.
-   * Used to reconcile sticky-latest pin floor in lockstep with the scroll
-   * adjustment so the pin reservation never lags behind a shrinking layout.
+   * Which transcript this hook belongs to, for the trail only.
+   *
+   * The list is keyed on the session, so every switch is a fresh instance with
+   * a fresh scroller — and two of them can overlap, or a second pane can hold
+   * one of its own. Read on its own, `followOutput.enter` followed by a
+   * boundary ask that passes the "is follow following" gate reads as an exit
+   * that left no trace; with this it reads as two instances, which is a
+   * different fault entirely.
    */
-  onContinuousFollowFrame?: () => void;
+  viewportId?: number;
+}
+
+export interface ViewportResizeInput {
+  /** Change in the scroller's client height; `0` on a reflow-only callback. */
+  viewportHeightDeltaPx: number;
+  /**
+   * Whether the viewport was resting at the end of the transcript *before* the
+   * resize. Afterwards that is unknowable — a viewport on the content end and
+   * one parked deliberately above it are the same geometry.
+   */
+  wasAtTail: boolean;
 }
 
 interface UseFlowChatFollowOutputResult {
   isFollowingOutput: boolean;
   enterFollowOutput: (reason: FollowOutputEnterReason) => void;
   exitFollowOutput: (reason: FollowOutputExitReason) => void;
-  preparePinnedTurnFollowHandoff: () => void;
-  armFollowOutputForNewTurn: () => void;
-  resumeFollowOutputForMountedStream: () => boolean;
-  activateArmedFollowOutput: () => boolean;
-  cancelPendingAutoFollowArm: () => void;
-  scheduleFollowToLatest: (reason: string) => void;
+  scheduleFollowToLatest: () => void;
+  /** Whether follow-output owns the viewport now, not one render ago. */
+  isFollowingOutputNow: () => boolean;
+  /**
+   * Whether the frame loop is actively moving the viewport right now.
+   *
+   * Not the same question as ownership, which outlives the loop on purpose so
+   * that streaming can resume following after the settle budget runs out.
+   */
+  isFollowCorrectingViewport: () => boolean;
   handleUserScrollIntent: () => void;
+  /** Turns were rolled back out of the session; end on the new tail. */
+  handleTurnsRolledBack: () => void;
   handleScroll: () => void;
+  /**
+   * The viewport was resized; keep whatever was on the bottom edge there.
+   */
+  handleViewportResize: (input: ViewportResizeInput) => void;
+  /** Offset the follow rule owns, or `null` when it does not own the viewport. */
+  getFollowTargetScrollTop: () => number | null;
 }
 
-function getDistanceFromBottom(scroller: HTMLElement): number {
-  return Math.max(0, scroller.scrollHeight - scroller.clientHeight - scroller.scrollTop);
-}
+const BOTTOM_EPSILON_PX = 2;
+
+/**
+ * Frames a pinned Turn may stay unmeasurable before the pin is abandoned.
+ * The virtualizer renders the tail immediately, so this only guards against a Turn
+ * that never mounts at all.
+ */
+const PIN_RESOLVE_MAX_ATTEMPTS = 30;
+
+/**
+ * How long a programmatic smooth scroll of ours may own the viewport before the
+ * follow loop resumes writing.
+ *
+ * The loop assigns `scrollTop` outright, which cancels an in-flight smooth
+ * scroll on the very next frame — every `'smooth'` request in this hook was in
+ * practice a jump until it yielded.
+ *
+ * A backstop rather than the actual terminator: the yield normally ends when
+ * the animation stops moving the viewport, and this only covers an animation
+ * that never finishes at all. It was a *frame* count and could not be — 45
+ * frames is 0.75s at 60Hz and 0.52s on a busy 200Hz display, so the duration a
+ * caller was buying depended on the machine. Measured: a jump to latest issued
+ * for 8717px animated 5480 of them and was finished by the loop in one 3290px
+ * write, 38% short.
+ */
+const SMOOTH_SCROLL_YIELD_MS = 1_200;
+
+/**
+ * How long the viewport may sit still before our animated scroll counts as over.
+ *
+ * A duration and not a frame count, for the same reason the backstop above is:
+ * this was two frames, and two frames is 33ms at 60Hz and 10ms at 200Hz, where
+ * a smooth scroll has not visibly started. Measured on WebView2: a jump issued
+ * for 9734px was taken back 21ms after it was asked for, having animated
+ * nothing at all, and the reader saw an instant jump where the whole point was
+ * an animation.
+ *
+ * The number comes from the shape of the curve rather than from the platform's
+ * startup latency, which is the shorter of the two. A programmatic smooth
+ * scroll eases in: measured, 2px in its first 50ms against 9734px to travel.
+ * With scroll offsets quantised to 0.8px on that display, the early frames
+ * genuinely do not move, and visible increments arrive up to ~40ms apart. This
+ * is that, doubled.
+ *
+ * What it costs is the follow resuming this late after an animation that ends
+ * somewhere other than its target — which only happens while streaming moves
+ * the target underneath it, and is then a dozen pixels the ease absorbs.
+ * Arriving ends the yield immediately and does not wait for this.
+ */
+export const SMOOTH_SCROLL_STALL_MS = 120;
+
+/**
+ * Frames the follow target keeps being re-asserted after a non-streaming entry,
+ * refreshed whenever it actually moves.
+ *
+ * A session opens against an unsettled transcript: item heights are still
+ * estimates and `isPartial` sessions page older Turns in, so the end of content
+ * can travel thousands of pixels after the first alignment. The browser used to
+ * absorb that for free — a bottom-aligned scroll was clamped at `scrollHeight -
+ * clientHeight`, so any target at or past the end snapped onto it. The resident
+ * tail spacer removes that clamp, so the settle has to be explicit.
+ */
+const SETTLE_FRAMES = 90;
 
 export function useFlowChatFollowOutput({
   activeSessionId,
   latestTurnId,
+  dialogTurnCount,
   virtualItemCount,
   isStreaming,
+  isViewportActive,
   scrollerRef,
-  performUserFollowScroll,
-  performAutoFollowScroll,
-  performLatestTurnStickyPin,
-  shouldSuspendAutoFollow,
-  canAnimateTailFollow,
-  getAutoFollowTargetScrollTop,
-  onContinuousFollowFrame,
+  getTailSpacerPx,
+  scrollToContentEnd,
+  scrollTurnToTop,
+  resolveTurnTopScrollTop,
+  isOpeningViewport,
+  viewportOwner,
+  viewportId = 0,
 }: UseFlowChatFollowOutputOptions): UseFlowChatFollowOutputResult {
   const [isFollowingOutput, setIsFollowingOutput] = useState(false);
-
-  const isFollowingOutputRef = useRef(isFollowingOutput);
-  const programmaticScrollUntilMsRef = useRef(0);
-  const explicitUserScrollIntentUntilMsRef = useRef(0);
-  const lastObservedScrollTopRef = useRef(0);
-  const previousSessionIdRef = useRef<string | undefined>(activeSessionId);
-  const armedAutoFollowTurnIdRef = useRef<string | null>(null);
-  const continuousFollowFrameRef = useRef<number | null>(null);
-  const lastContinuousFollowFrameMsRef = useRef<number | null>(null);
-  const nativeSmoothFollowUntilMsRef = useRef(0);
+  const isFollowingOutputRef = useRef(false);
   const isStreamingRef = useRef(isStreaming);
-  const onContinuousFollowFrameRef = useRef(onContinuousFollowFrame);
-  const canAnimateTailFollowRef = useRef(canAnimateTailFollow);
-  const getAutoFollowTargetScrollTopRef = useRef(getAutoFollowTargetScrollTop);
-  const shouldSuspendAutoFollowRef = useRef(shouldSuspendAutoFollow);
-
+  const isViewportActiveRef = useRef(isViewportActive);
+  const latestTurnIdRef = useRef(latestTurnId);
+  const followFrameRef = useRef<number | null>(null);
+  const previousSessionIdRef = useRef(activeSessionId);
+  const previousLatestTurnIdRef = useRef<string | null>(latestTurnId);
+  const previousDialogTurnCountRef = useRef(dialogTurnCount);
+  const hasMountedRef = useRef(false);
+  const wasStreamingRef = useRef(isStreaming);
+
+  const followStateRef = useRef<TailFollowState>({ mode: 'hold-tail', target: 0 });
+  const pinTurnIdRef = useRef<string | null>(null);
+  const pinScrollTopRef = useRef<number | null>(null);
+  const pinAttemptsRef = useRef(0);
+  /**
+   * A Turn that arrived while it was not in the transcript on screen.
+   *
+   * Submitting from inside a history window is the case: the session gains the
+   * Turn a beat before the presentation is restored to the live tail, so the
+   * one moment the arrival is *detectable* is not a moment it can be answered.
+   * The answer is deferred rather than dropped — kept until the Turn can
+   * actually be aligned, which is what the reader is waiting to see.
+   */
+  const pendingNewTurnIdRef = useRef<string | null>(null);
+  const settleFramesRef = useRef(0);
+  /** When the yield to our own animated scroll lapses, if it has not ended. */
+  const smoothScrollUntilMsRef = useRef(0);
+  /** Where the viewport was on the previous frame of that yield. */
+  const smoothScrollLastTopRef = useRef(0);
+  /** When that yield last saw the viewport move, which is what ends it. */
+  const smoothScrollLastMoveAtMsRef = useRef(0);
+  /** Where the animation started, so the trace can say how far it got. */
+  const smoothScrollFromPxRef = useRef(0);
+
+  /*
+   * Deliberately *not* mirrored from `isFollowingOutput` here.
+   *
+   * Every other ref on this line is a prop, and a prop is whatever the render
+   * that assigned it was given — consistent by construction. Ownership is not:
+   * it is written imperatively by `enterFollowOutput` and `exitFollowOutput`,
+   * and the state is only how the rest of the component hears about it. Between
+   * the two, React is free to render the value from *before* the update — an
+   * update scheduled from a passive effect sits at a lower priority than a
+   * synchronous render, which then renders without it — and the assignment took
+   * ownership away from a writer that had just taken it, with nothing anywhere
+   * saying so.
+   *
+   * Measured on session open, which is the entry that comes from a mount
+   * effect and so hits this every time: `followOutput.enter` recorded at 31976,
+   * the first frame of the loop stood down 345ms later with `not-following` and
+   * its 90-frame budget untouched, and no `followOutput.exit` in the trail
+   * because nothing exited. The register still held `follow-output`, so the
+   * 22301px prepend that landed in between was left to a writer that was no
+   * longer running — `followTargetPx: null` while `heldBy: follow-output` — and
+   * the session was revealed at offset 0 of a window starting eight Turns above
+   * the tail.
+   */
   isStreamingRef.current = isStreaming;
-  onContinuousFollowFrameRef.current = onContinuousFollowFrame;
-  canAnimateTailFollowRef.current = canAnimateTailFollow;
-  getAutoFollowTargetScrollTopRef.current = getAutoFollowTargetScrollTop;
-  shouldSuspendAutoFollowRef.current = shouldSuspendAutoFollow;
-
-  const setFollowingOutput = useCallback((nextValue: boolean) => {
-    isFollowingOutputRef.current = nextValue;
-    setIsFollowingOutput(prev => (prev === nextValue ? prev : nextValue));
-    if (!nextValue && continuousFollowFrameRef.current !== null) {
-      cancelAnimationFrame(continuousFollowFrameRef.current);
-      continuousFollowFrameRef.current = null;
-    }
-    if (!nextValue) {
-      lastContinuousFollowFrameMsRef.current = null;
-      nativeSmoothFollowUntilMsRef.current = 0;
-    }
-  }, []);
+  isViewportActiveRef.current = isViewportActive;
+  latestTurnIdRef.current = latestTurnId;
 
-  const stopContinuousFollowLoop = useCallback(() => {
-    if (continuousFollowFrameRef.current !== null) {
-      cancelAnimationFrame(continuousFollowFrameRef.current);
-      continuousFollowFrameRef.current = null;
+  const stopFollowFrame = useCallback(() => {
+    if (followFrameRef.current !== null) {
+      cancelAnimationFrame(followFrameRef.current);
+      followFrameRef.current = null;
     }
-    lastContinuousFollowFrameMsRef.current = null;
   }, []);
 
   /**
-   * Continuous RAF-driven follow loop.
+   * Whether the frame loop is actively moving the viewport.
    *
-   * Why this exists:
-   *  - Streaming text + auto-collapsing tool cards generate dense bursts of
-   *    DOM mutations and CSS transitions. Event-driven follow (via observers)
-   *    is gated by `shouldSuspendAutoFollow` during transitions, which makes
-   *    the viewport visibly stall and then jump after the transition ends.
-   *  - This loop runs every animation frame while follow + streaming is
-   *    active, pushing scrollTop toward the latest token regardless of any
-   *    intermediate layout shrink. The result is a smooth, continuous tail.
+   * Ownership is the other question and outlives this one: the loop stops once
+   * the settle budget runs out, and follow keeps the viewport so that streaming
+   * can resume. Reading ownership as "something is correcting this" hands the
+   * viewport to a loop that is not running — measured, a drag came to rest
+   * 813px into the reserved blank with `isFollowingOutput` true, the loop
+   * asleep, and nothing to bring it back.
+   */
+  const isFollowCorrectingViewport = useCallback(() => (
+    isFollowingOutputRef.current && followFrameRef.current !== null
+  ), []);
+
+  const readContentEndScrollTop = useCallback((scroller: HTMLElement) => (
+    contentEndScrollTop({
+      scrollHeight: scroller.scrollHeight,
+      clientHeight: scroller.clientHeight,
+      tailSpacerPx: getTailSpacerPx(),
+    })
+  ), [getTailSpacerPx]);
+
+  /**
+   * Forget which Turn is pinned.
    *
-   * Safety:
-   *  - Programmatic scrolls inside this loop bump
-   *    `programmaticScrollUntilMsRef` so the user-intent detector does not
-   *    misclassify them as upward scrolls.
-   *  - The loop bails out as soon as follow is exited, streaming ends, the
-   *    scroller disappears, or the viewport is already pinned to the bottom.
+   * This is the pin's *identity*, not its activity. A user takeover suspends
+   * the pin, while an explicit jump to latest may still return to it. Only
+   * three things retire a pin: the crossover to `hold-tail`, a newer Turn
+   * replacing it, and the session changing. The crossover is one-way by
+   * construction, since nothing re-pins a Turn whose identity has been
+   * dropped; a card collapse that pulls content back under one viewport must
+   * not resurrect the pin.
    */
-  const runContinuousFollowFrame = useCallback((nowMs: number) => {
-    continuousFollowFrameRef.current = null;
+  const retirePin = useCallback(() => {
+    pinTurnIdRef.current = null;
+    pinScrollTopRef.current = null;
+    pinAttemptsRef.current = 0;
+  }, []);
 
-    if (!isFollowingOutputRef.current || !isStreamingRef.current) {
-      lastContinuousFollowFrameMsRef.current = null;
-      return;
+  /**
+   * Resolve the pinned Turn's offset from live layout every frame rather than
+   * caching it once. Unrendered items are estimates until measured, and every
+   * measurement shifts the absolute offsets below it; a cached pin would drift.
+   */
+  const readPinScrollTop = useCallback((): number | null => {
+    const pinTurnId = pinTurnIdRef.current;
+    if (!pinTurnId) {
+      return null;
     }
 
-    const scroller = scrollerRef.current;
-    if (!scroller) {
-      lastContinuousFollowFrameMsRef.current = null;
-      return;
+    const resolved = resolveTurnTopScrollTop(pinTurnId);
+    if (resolved !== null) {
+      pinScrollTopRef.current = resolved;
+      pinAttemptsRef.current = 0;
+      return resolved;
     }
 
-    if (document.hidden) {
-      lastContinuousFollowFrameMsRef.current = null;
-      return;
+    if (pinScrollTopRef.current === null) {
+      pinAttemptsRef.current += 1;
+      if (pinAttemptsRef.current >= PIN_RESOLVE_MAX_ATTEMPTS) {
+        retirePin();
+      }
     }
+    return pinScrollTopRef.current;
+  }, [retirePin, resolveTurnTopScrollTop]);
 
-    const scheduleNextFrame = () => {
-      if (!isFollowingOutputRef.current || !isStreamingRef.current || document.hidden) {
-        return;
-      }
-      continuousFollowFrameRef.current = requestAnimationFrame(runContinuousFollowFrame);
+  /**
+   * The state the follow rule would hold for the current geometry, ignoring any
+   * offset it was holding. Used to resolve explicit follow targets and to
+   * resume on the live content end.
+   *
+   * Retires a pin that has crossed over on the way past: with no frame loop
+   * running, this is the only place that crossover can be noticed.
+   */
+  const resolveFollowState = useCallback((scroller: HTMLElement): TailFollowState => {
+    const desired = readContentEndScrollTop(scroller);
+    const next = memorylessFollowState(
+      pinTurnIdRef.current ? 'pin-turn-top' : 'hold-tail',
+      {
+        desiredScrollTop: desired,
+        pinScrollTop: readPinScrollTop(),
+        maxGapPx: tailHoldMaxGapPx(scroller.clientHeight),
+      },
+    );
+    if (next.mode === 'hold-tail') {
+      retirePin();
+    }
+    return next;
+  }, [readContentEndScrollTop, readPinScrollTop, retirePin]);
+
+  const resolveFollowTargetScrollTop = useCallback((scroller: HTMLElement) => (
+    resolveFollowState(scroller).target
+  ), [resolveFollowState]);
+
+  /*
+   * ---------------------------------------------------------------------------
+   * A viewport in the reader's hands, watched for output catching up with them.
+   *
+   * Scrolling up gives the follow away, and that is right only if the reader
+   * actually left the live region. They may not have. The reserved blank is up
+   * to 60% of a viewport under `hold-tail` and the whole gap under a pinned
+   * Turn, so a small scroll up can leave the reader still looking at empty space
+   * below the newest output — nothing is being hidden from them yet — and then
+   * output grows past the bottom edge and they silently stop seeing it.
+   *
+   * "Still looking at the blank" is `scrollTop > contentEnd`, because
+   * `contentEnd` is by definition the offset that puts the end of real content
+   * on the viewport's bottom edge. This watch only handles output catching up
+   * with a stationary reader; it never turns a user's resting position into a
+   * follow target.
+   *
+   * The watch therefore runs for as long as the reader holds the viewport, not
+   * for one crossing. `blankWasVisible` is the whole state it keeps between
+   * samples, and the rule is the obvious one: the blank was on screen and now it
+   * is not. Scoping it to a single crossing was tried and is wrong — a reader
+   * who climbs out of the blank, reads for a while and scrolls back down to sit
+   * in it again is in exactly the position the rule exists for, and had already
+   * spent the one crossing it was given.
+   *
+   * `content-caught-up` is what hands the viewport back, subject to
+   * `shouldResumeFollowAfterDeparture`; `reader-left-blank` is a reader who
+   * really did go and read history, and only clears the latch. Both raw deltas
+   * and the gesture claim are traced at each crossing rather than only the
+   * verdict, so the tie-break can still be revisited from a trail.
+   * ---------------------------------------------------------------------------
+   */
+  const tailWatchRef = useRef<{
+    openedAtMs: number;
+    /** Blank on screen when the reader took the viewport. */
+    exitBlankPx: number;
+    exitScrollTopPx: number;
+    exitContentEndPx: number;
+    exitPinned: boolean;
+    exitStreaming: boolean;
+    /** Previous sample, so a crossing can be attributed to whatever moved. */
+    lastScrollTopPx: number;
+    lastContentEndPx: number;
+    /** Whether the reserved blank was on screen as of the previous sample. */
+    blankWasVisible: boolean;
+    samples: number;
+    crossings: number;
+  } | null>(null);
+
+  const closeTailWatch = useCallback((
+    outcome: TailWatchOutcome,
+    extra?: Record<string, unknown>,
+  ) => {
+    const watch = tailWatchRef.current;
+    if (!watch) return;
+    tailWatchRef.current = null;
+    const scroller = scrollerRef.current;
+    const scrollTopPx = scroller?.scrollTop ?? watch.lastScrollTopPx;
+    const contentEndPx = scroller
+      ? readContentEndScrollTop(scroller)
+      : watch.lastContentEndPx;
+    traceViewport({
+      location: 'followOutput.tailWatchEnded',
+      message: 'follow-output has the viewport back',
+      data: () => ({
+        outcome,
+        viewportId,
+        forMs: Math.round(performance.now() - watch.openedAtMs),
+        samples: watch.samples,
+        crossings: watch.crossings,
+        blankAtExitPx: roundViewportPx(watch.exitBlankPx),
+        blankNowPx: roundViewportPx(scrollTopPx - contentEndPx),
+        // The two movements, over the whole life of the watch.
+        contentGrewPx: roundViewportPx(contentEndPx - watch.exitContentEndPx),
+        readerMovedPx: roundViewportPx(scrollTopPx - watch.exitScrollTopPx),
+        pinnedAtExit: watch.exitPinned,
+        streamingAtExit: watch.exitStreaming,
+        streamingNow: isStreamingRef.current,
+        ...(extra ?? {}),
+      }),
+    });
+  }, [readContentEndScrollTop, scrollerRef, viewportId]);
+  /*
+   * Held by identity for the unmount cleanup below.
+   *
+   * That cleanup must run when the transcript goes away and at no other time,
+   * and depending on the callback would instead run it whenever the callback is
+   * rebuilt — which is whenever `getTailSpacerPx` changes identity, and so
+   * potentially on every render of whoever owns this hook. A watch lives for as
+   * long as the reader keeps the viewport and spans many renders by
+   * construction, so an effect that tears down with the callback closes every
+   * one of them a frame after it opens.
+   */
+  const closeTailWatchRef = useRef(closeTailWatch);
+  closeTailWatchRef.current = closeTailWatch;
+
+  /**
+   * Start watching a viewport the reader has taken.
+   *
+   * Opened whether or not blank is on screen at the time. Where the reader was
+   * standing when they took it settles nothing — they can scroll down into the
+   * blank at any point afterwards, and the whole question is where they are when
+   * output next reaches the bottom edge.
+   */
+  const openTailWatch = useCallback(() => {
+    const scroller = scrollerRef.current;
+    if (!scroller) return;
+    const contentEndPx = readContentEndScrollTop(scroller);
+    const blankPx = scroller.scrollTop - contentEndPx;
+    const pinned = pinTurnIdRef.current !== null;
+    traceViewport({
+      location: 'followOutput.tailWatch',
+      message: 'the reader has the viewport, and is watched for output catching up',
+      data: () => ({
+        viewportId,
+        blankPx: roundViewportPx(blankPx),
+        blankVisible: blankPx > 0,
+        scrollTopPx: roundViewportPx(scroller.scrollTop),
+        contentEndPx: roundViewportPx(contentEndPx),
+        clientHeightPx: scroller.clientHeight,
+        // A pin is the case where the gap between the two predicates is widest.
+        pinned,
+        isStreaming: isStreamingRef.current,
+      }),
+    });
+    tailWatchRef.current = {
+      openedAtMs: performance.now(),
+      exitBlankPx: blankPx,
+      exitScrollTopPx: scroller.scrollTop,
+      exitContentEndPx: contentEndPx,
+      exitPinned: pinned,
+      exitStreaming: isStreamingRef.current,
+      lastScrollTopPx: scroller.scrollTop,
+      lastContentEndPx: contentEndPx,
+      blankWasVisible: blankPx > 0,
+      samples: 0,
+      crossings: 0,
     };
+  }, [readContentEndScrollTop, scrollerRef, viewportId]);
 
-    if (canAnimateTailFollowRef.current?.() === false) {
-      lastContinuousFollowFrameMsRef.current = null;
-      return;
+  /**
+   * Stand the frame loop down for an animated scroll this hook is about to
+   * issue. Taken from the viewport as it is now, so the first frame of the
+   * yield can tell travel from a stall.
+   */
+  const beginSmoothScrollYield = useCallback(() => {
+    const nowMs = performance.now();
+    smoothScrollUntilMsRef.current = nowMs + SMOOTH_SCROLL_YIELD_MS;
+    smoothScrollLastMoveAtMsRef.current = nowMs;
+    smoothScrollLastTopRef.current = scrollerRef.current?.scrollTop ?? 0;
+    smoothScrollFromPxRef.current = smoothScrollLastTopRef.current;
+  }, [scrollerRef]);
+
+  /**
+   * Take the viewport back, and say why.
+   *
+   * Every way this ends looks the same from outside — the follow simply starts
+   * writing again — and they are not the same fact. `stalled` after no travel
+   * at all is an animation that never ran, which is what a reader reports as
+   * the jump to latest having lost its animation; the same reason after most
+   * of the distance is the ordinary end of one.
+   */
+  const endSmoothScrollYield = useCallback((
+    reason: 'arrived' | 'stalled' | 'backstop' | 'superseded',
+  ) => {
+    if (smoothScrollUntilMsRef.current !== 0 && reason !== 'superseded') {
+      const travelledPx = (scrollerRef.current?.scrollTop ?? 0) - smoothScrollFromPxRef.current;
+      traceViewportRepeating(`smoothYield|${reason}|${Math.abs(travelledPx) < 1}`, {
+        location: 'followOutput.animatedScrollEnded',
+        message: 'the frame loop took the viewport back from its own animation',
+        travelPx: travelledPx,
+        data: () => ({
+          reason,
+          travelledPx: roundViewportPx(travelledPx),
+          fromPx: roundViewportPx(smoothScrollFromPxRef.current),
+          scrollTopPx: roundViewportPx(scrollerRef.current?.scrollTop ?? 0),
+        }),
+      });
     }
+    smoothScrollUntilMsRef.current = 0;
+  }, [scrollerRef]);
 
-    const previousFrameMs = lastContinuousFollowFrameMsRef.current;
-    const frameDeltaMs = previousFrameMs === null
-      ? 1000 / 60
-      : nowMs - previousFrameMs;
-    lastContinuousFollowFrameMsRef.current = nowMs;
+  /**
+   * Issue the one-shot content-end scroll, yielding the frame loop to it when
+   * it is animated. Without the yield the next frame overwrites `scrollTop` and
+   * the animation never plays.
+   */
+  const runContentEndScroll = useCallback((behavior: ScrollBehavior) => {
+    const resolvedBehavior = getMotionAwareScrollBehavior(
+      behavior === 'smooth' ? 'smooth' : 'auto',
+    );
+    if (resolvedBehavior === 'smooth') {
+      beginSmoothScrollYield();
+    } else {
+      // An instant scroll of ours replaces whatever was travelling.
+      endSmoothScrollYield('superseded');
+    }
+    scrollToContentEnd(resolvedBehavior);
+  }, [beginSmoothScrollYield, endSmoothScrollYield, scrollToContentEnd]);
 
-    if (nowMs < nativeSmoothFollowUntilMsRef.current) {
-      scheduleNextFrame();
+  /**
+   * Decide how a jump to latest travels, and record the decision.
+   *
+   * Traced because the two outcomes are indistinguishable afterwards — an
+   * animation that was never issued and one the loop cut short both end as a
+   * viewport that arrived without moving through anything — and they call for
+   * opposite fixes. This line says which one a reader is describing.
+  */
+  const resolveJumpBehavior = useCallback((scroller: HTMLElement, targetPx: number) => {
+    const distanceBehavior = resolveAnimatedJumpBehavior({
+      fromPx: scroller.scrollTop,
+      targetPx,
+      clientHeight: scroller.clientHeight,
+    });
+    const behavior = getMotionAwareScrollBehavior(distanceBehavior);
+    const distancePx = Math.abs(targetPx - scroller.scrollTop);
+    traceViewportRepeating(`follow|jumpBehavior|${behavior}`, {
+      location: 'followOutput.jumpBehavior',
+      message: behavior === 'smooth'
+        ? 'the jump to latest is near enough to animate'
+        : distanceBehavior === 'smooth'
+          ? 'the jump to latest lands outright because reduced motion is enabled'
+          : 'the jump to latest is too far to animate, so it lands outright',
+      travelPx: targetPx - scroller.scrollTop,
+      data: () => ({
+        behavior,
+        distanceBehavior,
+        viewportId,
+        distancePx: roundViewportPx(distancePx),
+        viewports: scroller.clientHeight > 0
+          ? Math.round((distancePx / scroller.clientHeight) * 10) / 10
+          : null,
+        clientHeightPx: scroller.clientHeight,
+      }),
+    });
+    return behavior;
+  }, [viewportId]);
+
+  /** Move the viewport to whatever the follow state currently owns. */
+  const applyFollowTarget = useCallback(() => {
+    const scroller = scrollerRef.current;
+    if (!scroller) {
       return;
     }
 
-    // While a known collapse animation / layout transition is in flight, the
-    // VirtualMessageList anchor-lock + bottom-reservation footer is preserving
-    // the upper visual anchor. The loop remains alive but must not write until
-    // that transaction releases ownership.
-    const isSuspended = shouldSuspendAutoFollowRef.current?.() === true;
-    if (!isSuspended) {
-      onContinuousFollowFrameRef.current?.();
-      const targetScrollTop = getAutoFollowTargetScrollTopRef.current?.(scroller)
-        ?? Math.max(0, scroller.scrollHeight - scroller.clientHeight);
-      const distanceToTarget = Math.max(0, targetScrollTop - scroller.scrollTop);
-
-      if (distanceToTarget > CONTINUOUS_FOLLOW_SNAP_THRESHOLD_PX) {
-        const nextScrollTop = distanceToTarget > CONTINUOUS_FOLLOW_MAX_ANIMATED_DISTANCE_PX
-          ? targetScrollTop
-          : scroller.scrollTop + computeContinuousFollowStep(distanceToTarget, frameDeltaMs);
-        programmaticScrollUntilMsRef.current = nowMs + PROGRAMMATIC_SCROLL_GUARD_MS;
-        explicitUserScrollIntentUntilMsRef.current = 0;
-        scroller.scrollTop = Math.min(targetScrollTop, nextScrollTop);
-        lastObservedScrollTopRef.current = scroller.scrollTop;
-      }
+    const remembered = followStateRef.current;
+    const desired = readContentEndScrollTop(scroller);
+    /*
+     * While the transcript is opening it is still hidden, so nothing is gained
+     * by remembering an earlier offset: drop the memory and track the content
+     * end exactly. The virtualizer writes `scrollTop` too during this window — it
+     * compensates a history prepend from the item index before the prepended
+     * heights reach the DOM — and any accommodation of that is both invisible
+     * and, once paging stops, permanent. The gap tolerance is a *streaming*
+     * allowance: blank below the live output is acceptable only because more
+     * output is about to fill it.
+     */
+    const previous: TailFollowState = isOpeningViewport()
+      ? { mode: remembered.mode, target: desired }
+      : remembered;
+    const pin = readPinScrollTop();
+    const next = nextTailFollowState(previous, {
+      desiredScrollTop: desired,
+      pinScrollTop: pin,
+      maxGapPx: tailHoldMaxGapPx(scroller.clientHeight),
+    });
+    followStateRef.current = next;
+    if (next.mode === 'hold-tail') {
+      retirePin();
+    }
+    // Content is still moving, so keep the settle window open.
+    if (Math.abs(next.target - previous.target) > BOTTOM_EPSILON_PX) {
+      settleFramesRef.current = SETTLE_FRAMES;
     }
 
-    if (!isFollowingOutputRef.current || !isStreamingRef.current) {
-      return;
+    const onTarget = Math.abs(next.target - scroller.scrollTop) <= BOTTOM_EPSILON_PX;
+    /*
+     * What the loop decided this frame, coalesced by the decision.
+     *
+     * A frame that writes nothing is the interesting one: it means the follow
+     * rule believes the viewport is already where it belongs, and the reader is
+     * looking at something else. Measured on a reopened session, that is the
+     * whole fault — a history window arrived above a viewport at 0 during the
+     * opening reveal, and whether the loop then aimed at the new content end or
+     * was still reading an unmeasured 0 could not be told apart from outside.
+     */
+    if (isViewportDiagnosticsEnabled()) {
+      // Guarded rather than left to the coalescer, which is the rule for
+      // anything on this path: it runs on every frame of every follow, and even
+      // the key would be a string built sixty times a second for a switch that
+      // is off.
+      traceViewportRepeating(
+        `follow|frame|${onTarget}|${isOpeningViewport()}|${next.mode}`,
+        {
+          location: 'followOutput.frame',
+          message: onTarget
+            ? 'the viewport is already on the offset the follow rule owns'
+            : 'the follow rule is moving the viewport to the offset it owns',
+          travelPx: next.target - scroller.scrollTop,
+          data: () => ({
+            viewportId,
+            onTarget,
+            mode: next.mode,
+            isOpening: isOpeningViewport(),
+            desiredPx: roundViewportPx(desired),
+            targetPx: roundViewportPx(next.target),
+            pinPx: pin === null ? null : roundViewportPx(pin),
+            scrollTopPx: roundViewportPx(scroller.scrollTop),
+            scrollRangePx: roundViewportPx(scroller.scrollHeight),
+            settleFrames: settleFramesRef.current,
+            smoothYieldActive: smoothScrollUntilMsRef.current !== 0,
+          }),
+        },
+      );
+    }
+    if (smoothScrollUntilMsRef.current !== 0) {
+      /*
+       * An animated scroll of ours is in flight and heading for this same
+       * target. Track the state, but leave the writing to it.
+       *
+       * It ends when the viewport stops moving for `SMOOTH_SCROLL_STALL_MS`,
+       * which is the animation's own answer rather than a guess at how long it
+       * takes: the browser scales the duration with the distance, and a jump to
+       * latest from the top of a transcript takes longer than anything else
+       * this issues. Arriving ends it too, and sooner.
+       */
+      const nowMs = performance.now();
+      if (scroller.scrollTop !== smoothScrollLastTopRef.current) {
+        smoothScrollLastTopRef.current = scroller.scrollTop;
+        smoothScrollLastMoveAtMsRef.current = nowMs;
+      }
+      if (onTarget) {
+        endSmoothScrollYield('arrived');
+      } else if (nowMs >= smoothScrollUntilMsRef.current) {
+        endSmoothScrollYield('backstop');
+      } else if (nowMs - smoothScrollLastMoveAtMsRef.current >= SMOOTH_SCROLL_STALL_MS) {
+        endSmoothScrollYield('stalled');
+      } else {
+        return;
+      }
+      /*
+       * The animation is over, and the target has moved on under it — it aims
+       * at the offset it was issued for, and content arrives while it travels.
+       * Falling through rather than returning is what covers that growth on
+       * this frame instead of the next one.
+       */
     }
 
-    scheduleNextFrame();
-  }, [scrollerRef]);
+    if (!onTarget) {
+      const fromPx = scroller.scrollTop;
+      /*
+       * Eased across the frames the follow already has, rather than written in
+       * one step.
+       *
+       * The target moves when Markdown reflows, which is a whole line at a
+       * time with nothing in between, so an outright write spends a line of
+       * travel on one frame out of seven. This spends the same distance over
+       * all seven. It buys latency, not speed: under steady growth the offset
+       * settles where its per-frame catch-up equals the growth, so the step
+       * converges on the content's growth per frame whatever the fraction is.
+       *
+       * Only the *write* is eased. `followStateRef` still holds the true
+       * target, so the settle budget and the at-tail band both
+       * keep reading the offset the follow rule owns rather than how far
+       * behind its own ease is riding.
+       *
+       * Not while the transcript is opening. There the target is authoritative
+       * and the transcript is hidden, so an ease would only make the reveal
+       * wait for travel nobody can see — and the reveal is watching for the
+       * viewport to reach the content end.
+       */
+      const step = !isOpeningViewport() && shouldEaseTailFollow({
+        scrollHeightPx: scroller.scrollHeight,
+        clientHeightPx: scroller.clientHeight,
+      })
+        ? nextEasedScrollTopPx(fromPx, next.target)
+        : { offsetPx: next.target, outcome: 'snapped' as const };
+      viewportOwner.write({ owner: 'follow-output', topPx: step.offsetPx });
+      /*
+       * Read back rather than taken from the step. The register can refuse
+       * this write outright, and a refused follow moves nothing — believing
+       * the step there would report a follow that is being outranked as the
+       * smoothest one in the session, and would book the frame below forever
+       * over travel that never happens.
+       */
+      const movedPx = scroller.scrollTop - fromPx;
+      /*
+       * An ease in flight is a reason to run again, and the only one it has
+       * once the target stops moving: the budget is refreshed by the *target*
+       * travelling, so a correction arriving on the last frame of a settle
+       * would otherwise be abandoned partway. Bounded by the ease itself,
+       * which halves what is left every frame and is inside `BOTTOM_EPSILON_PX`
+       * within a handful of them.
+       */
+      if (step.outcome === 'eased' && movedPx !== 0) {
+        settleFramesRef.current = Math.max(settleFramesRef.current, 1);
+      }
+      if (isTailFollowDiagnosticsEnabled()) {
+        noteTailFollowStep('list', {
+          stepPx: movedPx,
+          lagPx: next.target - fromPx,
+          innerScroll: true,
+          snapped: step.outcome === 'snapped',
+        });
+      }
+    }
+  }, [
+    endSmoothScrollYield,
+    isOpeningViewport,
+    readContentEndScrollTop,
+    readPinScrollTop,
+    retirePin,
+    scrollerRef,
+    viewportId,
+    viewportOwner,
+  ]);
 
-  const startContinuousFollowLoop = useCallback(() => {
-    if (continuousFollowFrameRef.current !== null) {
+  const runFollowFrame = useCallback(() => {
+    followFrameRef.current = null;
+    /*
+     * Why the loop is not running, which the trail could not say.
+     *
+     * "The session opened on the wrong Turn" has looked identical from outside
+     * whether follow was refused the viewport, was never following, or simply
+     * ran out of budget — all three are a viewport that stops where it was left
+     * and a log with nothing in it after `followOutput.enter`. Measured on a
+     * reopened session: `enter` at session-open, a history window prepended
+     * 22317px above 136ms later, and not one write for the next half second.
+     */
+    const standDownReason = !isFollowingOutputRef.current
+      ? 'not-following'
+      : !isViewportActiveRef.current
+        ? 'viewport-inactive'
+        : document.hidden
+          ? 'document-hidden'
+          : (!isStreamingRef.current && settleFramesRef.current <= 0)
+            // Streaming holds the loop open indefinitely; anything else runs
+            // only until the transcript stops moving.
+            ? 'settle-exhausted'
+            : null;
+    if (standDownReason !== null) {
+      traceViewportRepeating(`follow|standDown|${standDownReason}`, {
+        location: 'followOutput.frameStoodDown',
+        message: 'the follow loop stopped running',
+        data: () => ({
+          reason: standDownReason,
+          viewportId,
+          settleFrames: settleFramesRef.current,
+          isStreaming: isStreamingRef.current,
+          isOpening: isOpeningViewport(),
+          followTargetPx: roundViewportPx(followStateRef.current.target),
+          scrollTopPx: roundViewportPx(scrollerRef.current?.scrollTop ?? 0),
+        }),
+      });
       return;
     }
-    if (!isFollowingOutputRef.current || !isStreamingRef.current) {
-      return;
+    if (!isStreamingRef.current) {
+      settleFramesRef.current -= 1;
     }
-    continuousFollowFrameRef.current = requestAnimationFrame(runContinuousFollowFrame);
-  }, [runContinuousFollowFrame]);
 
-  const cancelPendingAutoFollowArm = useCallback(() => {
-    armedAutoFollowTurnIdRef.current = null;
-  }, []);
+    applyFollowTarget();
+    followFrameRef.current = requestAnimationFrame(runFollowFrame);
+  }, [applyFollowTarget, isOpeningViewport, scrollerRef, viewportId]);
 
-  const runProgrammaticScroll = useCallback((scrollAction: () => void) => {
-    programmaticScrollUntilMsRef.current = performance.now() + PROGRAMMATIC_SCROLL_GUARD_MS;
-    explicitUserScrollIntentUntilMsRef.current = 0;
-    scrollAction();
-    const scroller = scrollerRef.current;
-    if (scroller) {
-      lastObservedScrollTopRef.current = scroller.scrollTop;
+  const startFollowFrame = useCallback(() => {
+    if (
+      followFrameRef.current === null &&
+      isFollowingOutputRef.current &&
+      (isStreamingRef.current || settleFramesRef.current > 0)
+    ) {
+      followFrameRef.current = requestAnimationFrame(runFollowFrame);
     }
-  }, [scrollerRef]);
+  }, [runFollowFrame]);
 
   const enterFollowOutput = useCallback((reason: FollowOutputEnterReason) => {
-    cancelPendingAutoFollowArm();
-    explicitUserScrollIntentUntilMsRef.current = 0;
-    nativeSmoothFollowUntilMsRef.current = reason === 'jump-to-latest'
-      ? performance.now() + NATIVE_SMOOTH_FOLLOW_GRACE_MS
-      : 0;
-    setFollowingOutput(true);
-    const followAction = reason === 'jump-to-latest'
-      ? performUserFollowScroll
-      : performAutoFollowScroll;
-    runProgrammaticScroll(followAction);
-  }, [
-    cancelPendingAutoFollowArm,
-    performAutoFollowScroll,
-    performUserFollowScroll,
-    runProgrammaticScroll,
-    setFollowingOutput,
-  ]);
-
-  const exitFollowOutput = useCallback((_reason: FollowOutputExitReason) => {
-    cancelPendingAutoFollowArm();
-    explicitUserScrollIntentUntilMsRef.current = 0;
-    nativeSmoothFollowUntilMsRef.current = 0;
-    setFollowingOutput(false);
-    const scroller = scrollerRef.current;
-    if (scroller) {
-      lastObservedScrollTopRef.current = scroller.scrollTop;
+    if (!isViewportActiveRef.current) {
+      /*
+       * The one way this hook can decline to take the viewport and leave no
+       * trace at all — and it leaves the transcript with no continuous writer
+       * for the rest of its life, because nothing asks again until a Turn
+       * arrives or the session changes. A second pane holding an inactive copy
+       * of the same transcript looks exactly like this from the trail.
+       */
+      traceViewportRepeating(`follow|enterDeclined|${reason}`, {
+        location: 'followOutput.enterDeclined',
+        message: 'follow-output was asked for a viewport that is not active',
+        data: () => ({
+          reason,
+          viewportId,
+          scrollTopPx: roundViewportPx(scrollerRef.current?.scrollTop ?? 0),
+        }),
+      });
+      return;
     }
-  }, [cancelPendingAutoFollowArm, scrollerRef, setFollowingOutput]);
 
-  // Pinned latest turns are a handoff transaction: the pin owns the viewport
-  // until its reservation is consumed, then the armed turn may resume tail
-  // follow. Keep the arm while clearing logical follow ownership so the two
-  // semantic owners can never be active at the same time.
-  const preparePinnedTurnFollowHandoff = useCallback(() => {
-    if (!latestTurnId) {
-      return;
+    /*
+     * A newly submitted Turn opens at the viewport top, and that is the whole
+     * of the answer to one arriving. Until it is in the transcript on screen
+     * there is nothing to align, and the fallback below — the end of real
+     * content — is not a stand-in for it: it would leave the Turn unpinned
+     * where the reader was, or pull them out of a history window entirely.
+     *
+     * So the answer waits for the Turn instead. Resolved before ownership
+     * changes hands, because waiting has to leave the viewport exactly as it
+     * was found.
+     */
+    const pinTurnId = reason === 'new-turn' ? latestTurnIdRef.current : null;
+    const pinnedTurnToTop = pinTurnId !== null && scrollTurnToTop(pinTurnId);
+    if (reason === 'new-turn') {
+      pendingNewTurnIdRef.current = pinnedTurnToTop ? null : pinTurnId;
+      if (!pinnedTurnToTop) {
+        /*
+         * The viewport is deliberately left exactly as it was, so the only
+         * evidence that a submission was answered at all is this line. A
+         * deferral with no `followOutput.enter` after it is the reader's
+         * "nothing happened when I sent a message".
+         */
+        traceViewportRepeating('follow|deferred-new-turn', {
+          location: 'followOutput.deferNewTurn',
+          message: 'new Turn is not in the transcript on screen yet, so the answer waits',
+          data: () => ({ turnId: pinTurnId }),
+        });
+        return;
+      }
     }
 
-    armedAutoFollowTurnIdRef.current = latestTurnId;
-    explicitUserScrollIntentUntilMsRef.current = 0;
-    nativeSmoothFollowUntilMsRef.current = 0;
-    setFollowingOutput(false);
-  }, [latestTurnId, setFollowingOutput]);
+    isFollowingOutputRef.current = true;
+    setIsFollowingOutput(true);
+    // Whatever this entry is, follow has the viewport, so there is nothing left
+    // to watch for. The crossing route comes through here too, having already
+    // traced why.
+    closeTailWatch('followed-again', { enterReason: reason });
+    settleFramesRef.current = SETTLE_FRAMES;
+    traceViewportRepeating(`follow|enter|${reason}`, {
+      location: 'followOutput.enter',
+      message: 'follow-output took the viewport',
+      data: () => ({
+        reason,
+        viewportId,
+        pinnedTurnId: pinnedTurnToTop ? pinTurnId : pinTurnIdRef.current,
+        isStreaming: isStreamingRef.current,
+        scrollTopPx: roundViewportPx(scrollerRef.current?.scrollTop ?? 0),
+      }),
+    });
+    /*
+     * Ownership is taken here rather than at each write, because following is
+     * continuous: between two frames of the loop the viewport is still ours,
+     * and a correction slipping into that gap is the thing this prevents. A
+     * refused claim is not a reason to stop following — the loop keeps its
+     * state and simply writes nothing until whoever outranks it is done.
+     */
+    viewportOwner.claim('follow-output');
 
-  const armFollowOutputForNewTurn = useCallback(() => {
-    if (!latestTurnId) {
-      cancelPendingAutoFollowArm();
+    const scroller = scrollerRef.current;
+    const contentEnd = scroller ? readContentEndScrollTop(scroller) : 0;
+
+    /*
+     * A pin on the newest Turn already satisfies "show me the latest output".
+     * The mode only holds while that Turn's answer is shorter than one
+     * viewport, so everything it has produced is on screen; re-aiming at the
+     * content end would scroll *up* and shove the message the user just sent
+     * into the middle of the viewport.
+     *
+     * This fires for real: restoring the tail presentation asks for a jump to
+     * latest one frame after the Turn that caused it got pinned, which
+     * overwrote the pin every time.
+     */
+    if (
+      reason === 'jump-to-latest' &&
+      pinTurnIdRef.current !== null &&
+      pinTurnIdRef.current === latestTurnIdRef.current
+    ) {
+      const pinTarget = readPinScrollTop() ?? scroller?.scrollTop ?? contentEnd;
+      followStateRef.current = { mode: 'pin-turn-top', target: pinTarget };
+      // Travels like every other jump to latest, animated or not. The frame
+      // loop would cancel an animation on its next tick, so it stands down for
+      // this one exactly as it does for `runContentEndScroll` — and an instant
+      // write of ours replaces whatever was still travelling.
+      if (scroller && Math.abs(scroller.scrollTop - pinTarget) > BOTTOM_EPSILON_PX) {
+        const behavior = resolveJumpBehavior(scroller, pinTarget);
+        if (behavior === 'smooth') {
+          beginSmoothScrollYield();
+        } else {
+          endSmoothScrollYield('superseded');
+        }
+        viewportOwner.write({
+          owner: 'follow-output',
+          topPx: pinTarget,
+          behavior,
+        });
+      }
+      startFollowFrame();
       return;
     }
 
-    preparePinnedTurnFollowHandoff();
-    runProgrammaticScroll(performLatestTurnStickyPin);
+    // Every other entry reason resumes at the end of real content.
+    if (pinnedTurnToTop) {
+      pinTurnIdRef.current = pinTurnId;
+      pinScrollTopRef.current = null;
+      pinAttemptsRef.current = 0;
+      endSmoothScrollYield('superseded');
+      followStateRef.current = { mode: 'pin-turn-top', target: scroller?.scrollTop ?? contentEnd };
+    } else {
+      /*
+       * The pin is dropped here even when the departure happened under one, and
+       * that is deliberate. The pin's reservation is the blank the reader just
+       * scrolled out of; restoring it would pull them back down to the offset
+       * they left. Following the content end keeps them where they put
+       * themselves and shows what arrives below.
+       */
+      retirePin();
+      followStateRef.current = { mode: 'hold-tail', target: contentEnd };
+      /*
+       * Output that caught up with a stationary reader is already at the end —
+       * the blank between them closing is what raised this — so the whole
+       * distance left is one sample of growth, and the frame loop's ease covers
+       * it on the next few frames. A one-shot scroll would spend that as a snap
+       * the reader can see, for a correction they cannot.
+       */
+      if (reason !== 'tail-caught-up') {
+        /*
+         * Only a jump to latest is ever a candidate for an animation, and only
+         * a near one. Every other entry reason is the transcript resuming a
+         * follow it already owned, where an animation would be a movement the
+         * reader did not ask for.
+         */
+        runContentEndScroll(
+          reason === 'jump-to-latest' && scroller
+            ? resolveJumpBehavior(scroller, contentEnd)
+            : 'auto',
+        );
+      }
+    }
+
+    startFollowFrame();
   }, [
-    cancelPendingAutoFollowArm,
-    latestTurnId,
-    performLatestTurnStickyPin,
-    preparePinnedTurnFollowHandoff,
-    runProgrammaticScroll,
+    viewportOwner,
+    beginSmoothScrollYield,
+    closeTailWatch,
+    endSmoothScrollYield,
+    readContentEndScrollTop,
+    readPinScrollTop,
+    resolveJumpBehavior,
+    retirePin,
+    runContentEndScroll,
+    scrollTurnToTop,
+    scrollerRef,
+    startFollowFrame,
+    viewportId,
   ]);
 
-  const resumeFollowOutputForMountedStream = useCallback(() => {
-    if (!latestTurnId || !isStreaming || virtualItemCount === 0) {
-      return false;
+  /**
+   * Release the viewport without forgetting the pin. The user owns it from
+   * here; the pin stays on record so an explicit jump to latest can restore
+   * the mode rather than fall through to the tail.
+   */
+  const exitFollowOutput = useCallback((reason: FollowOutputExitReason) => {
+    /*
+     * Traced whether or not there was anything to give up. An exit that finds
+     * follow already released is the answer to "who ended the follow this
+     * session opened with" being nobody — and gating the line on ownership is
+     * what made that case indistinguishable from the exit never being reached.
+     */
+    traceViewportRepeating(`follow|exit|${reason}|${isFollowingOutputRef.current}`, {
+      location: 'followOutput.exit',
+      message: isFollowingOutputRef.current
+        ? 'follow-output gave the viewport up'
+        : 'follow-output was released while it held nothing',
+      data: () => ({
+        reason,
+        viewportId,
+        wasFollowing: isFollowingOutputRef.current,
+        pinnedTurnId: pinTurnIdRef.current,
+        scrollTopPx: roundViewportPx(scrollerRef.current?.scrollTop ?? 0),
+      }),
+    });
+    isFollowingOutputRef.current = false;
+    setIsFollowingOutput(false);
+    endSmoothScrollYield('superseded');
+    viewportOwner.release('follow-output');
+    stopFollowFrame();
+
+    /*
+     * A watch is open exactly while the reader holds the viewport, which is what
+     * every branch below maintains. `wasFollowing` is deliberately not the gate:
+     * this runs on every wheel notch rather than once per gesture, so gating on
+     * it would open a watch on the notch that took the viewport and nowhere
+     * else, and any exit that found follow already released — a reader scrolling
+     * on from a navigation, say — would be watched by nothing.
+     *
+     * Re-opening is what must not happen instead. The offsets a crossing is
+     * judged against are the previous sample's, and re-baselining them halfway
+     * through the gesture being judged is how a reader climbing steadily reads
+     * as one standing still.
+     */
+    if (reason === 'session-changed') {
+      closeTailWatch('session-changed');
+      return;
     }
-
-    enterFollowOutput('auto-follow');
-    return true;
-  }, [enterFollowOutput, isStreaming, latestTurnId, virtualItemCount]);
-
-  const activateArmedFollowOutput = useCallback(() => {
-    const armedTurnId = armedAutoFollowTurnIdRef.current;
-    const isAlreadyFollowing = isFollowingOutputRef.current;
-    const isArmedForLatestTurn = Boolean(latestTurnId && armedTurnId === latestTurnId);
-    const isAutoFollowSuspended = shouldSuspendAutoFollow?.() === true;
-
-    if (!latestTurnId || !isArmedForLatestTurn || isAlreadyFollowing) {
-      return false;
+    if (reason === 'scroll-to-turn' || reason === 'scroll-to-index') {
+      // A navigation puts the reader somewhere they did not travel to, so the
+      // watch starts again from there rather than carrying offsets across it.
+      closeTailWatch('navigated', { navigationReason: reason });
     }
-
-    if (isAutoFollowSuspended) {
-      return false;
+    if (tailWatchRef.current === null) {
+      openTailWatch();
     }
-
-    cancelPendingAutoFollowArm();
-    nativeSmoothFollowUntilMsRef.current = 0;
-    setFollowingOutput(true);
-    runProgrammaticScroll(performAutoFollowScroll);
-    return true;
   }, [
-    cancelPendingAutoFollowArm,
-    latestTurnId,
-    performAutoFollowScroll,
-    runProgrammaticScroll,
-    setFollowingOutput,
-    shouldSuspendAutoFollow,
+    closeTailWatch,
+    endSmoothScrollYield,
+    openTailWatch,
+    scrollerRef,
+    stopFollowFrame,
+    viewportId,
+    viewportOwner,
   ]);
 
-  const handleUserScrollIntent = useCallback(() => {
-    if (!isFollowingOutputRef.current && armedAutoFollowTurnIdRef.current === null) {
+  /**
+   * One sample of an open watch, from wherever the geometry can change.
+   *
+   * Costs a null check whenever follow owns the viewport, which is when nothing
+   * is being watched. Otherwise it reads `scrollHeight` — the same measurement
+   * the follow loop takes every frame while it *does* own the viewport, so this
+   * is that measurement continuing across the gap where it does not.
+   *
+   * Defined below `enterFollowOutput` because a crossing can hand the viewport
+   * back, which is the whole point of watching.
+   */
+  const sampleTailWatch = useCallback(() => {
+    const watch = tailWatchRef.current;
+    if (!watch) return;
+    const scroller = scrollerRef.current;
+    if (!scroller) return;
+
+    const scrollTopPx = scroller.scrollTop;
+    const contentEndPx = readContentEndScrollTop(scroller);
+    const blankPx = scrollTopPx - contentEndPx;
+    const contentDeltaPx = contentEndPx - watch.lastContentEndPx;
+    const scrollDeltaPx = scrollTopPx - watch.lastScrollTopPx;
+    watch.lastScrollTopPx = scrollTopPx;
+    watch.lastContentEndPx = contentEndPx;
+    watch.samples += 1;
+
+    /*
+     * Geometry read from two different moments, so neither the latch nor a
+     * verdict can be taken from it. A history prepend is the case: it shifts the
+     * viewport by the height it inserted, before that height has been measured
+     * into the scroll range, and the blank between the two reads as thousands of
+     * pixels. Left alone rather than cleared — a restructure says nothing about
+     * where the reader was standing before it, and the next honest sample is a
+     * frame away.
+     */
+    if (!isTailBlankMeasurable({ blankPx, tailSpacerPx: getTailSpacerPx() })) return;
+
+    const crossing = resolveTailDepartureCrossing({
+      blankPx,
+      contentDeltaPx,
+      scrollDeltaPx,
+    });
+    if (crossing === 'watching') {
+      watch.blankWasVisible = true;
       return;
     }
-
-    const now = performance.now();
-    if (now <= programmaticScrollUntilMsRef.current) {
-      const scroller = scrollerRef.current;
-      const alreadyAwayFromBottom = scroller
-        ? getDistanceFromBottom(scroller) > AUTO_FOLLOW_BOTTOM_THRESHOLD_PX
-        : false;
-
-      if (
-        !alreadyAwayFromBottom &&
-        !isFollowingOutputRef.current &&
-        armedAutoFollowTurnIdRef.current === null
-      ) {
-        return;
-      }
-
-      programmaticScrollUntilMsRef.current = Math.min(
-        programmaticScrollUntilMsRef.current,
-        now + USER_SCROLL_INTENT_PROGRAMMATIC_GRACE_MS,
-      );
+    /*
+     * The blank is gone, but it was already gone last time: the reader is above
+     * the end of content and staying there, which is reading history and is not
+     * a crossing of anything. Only the transition is a question.
+     */
+    if (!watch.blankWasVisible) return;
+
+    // Whether the reader's hand is still on it. The claim lapses on its own,
+    // so this separates a crossing during a gesture from one after it.
+    const gestureLive = viewportOwner.currentOwner() === 'user-gesture';
+    const resumed = shouldResumeFollowAfterDeparture({ crossing, gestureLive });
+    watch.crossings += 1;
+    /*
+     * A crossing the gesture vetoed keeps the latch, so the next sample judges
+     * the same transition again: the reader either keeps climbing, and is let go
+     * by a verdict that no longer needs the veto, or stops, and is followed once
+     * the claim lapses. Every other verdict is final for this crossing — coming
+     * back is what the reader has to do to raise the question again.
+     */
+    if (!(crossing === 'content-caught-up' && gestureLive)) {
+      watch.blankWasVisible = false;
     }
-    explicitUserScrollIntentUntilMsRef.current = now + USER_SCROLL_INTENT_WINDOW_MS;
-    nativeSmoothFollowUntilMsRef.current = 0;
-
-    if (isFollowingOutputRef.current) {
-      // Input handlers see the upward intent before scrollTop necessarily moves.
-      exitFollowOutput('user-scroll-up');
-      return;
+    traceViewport({
+      location: 'followOutput.tailCrossing',
+      message: resumed
+        ? 'output caught up with the reader, so follow takes the viewport back'
+        : 'the blank closed under the reader, and follow leaves it alone',
+      data: () => ({
+        crossing,
+        resumed,
+        gestureLive,
+        viewportId,
+        blankPx: roundViewportPx(blankPx),
+        contentDeltaPx: roundViewportPx(contentDeltaPx),
+        scrollDeltaPx: roundViewportPx(scrollDeltaPx),
+        scrollTopPx: roundViewportPx(scrollTopPx),
+        contentEndPx: roundViewportPx(contentEndPx),
+        crossingIndex: watch.crossings,
+        intoWatchMs: Math.round(performance.now() - watch.openedAtMs),
+      }),
+    });
+    if (resumed) {
+      enterFollowOutput('tail-caught-up');
     }
+  }, [
+    enterFollowOutput,
+    getTailSpacerPx,
+    readContentEndScrollTop,
+    scrollerRef,
+    viewportId,
+    viewportOwner,
+  ]);
 
-    cancelPendingAutoFollowArm();
-  }, [cancelPendingAutoFollowArm, exitFollowOutput, scrollerRef]);
-
-  const scheduleFollowToLatest = useCallback((_reason: string) => {
-    if (
-      !isFollowingOutputRef.current ||
-      !isStreamingRef.current ||
-      virtualItemCount === 0 ||
-      shouldSuspendAutoFollow?.() === true
-    ) {
+  /**
+   * Re-assert ownership after a layout change. This deliberately does not force
+   * the viewport to the content end: a tool-card collapse resizes the content
+   * too, and the hold rule is what keeps that from dragging earlier content
+   * down.
+   */
+  const scheduleFollowToLatest = useCallback(() => {
+    if (!isFollowingOutputRef.current || !isViewportActiveRef.current) {
+      /*
+       * This is the transcript's content-change signal — the resize observer
+       * calls it before paint on every content box change — and for a viewport
+       * nobody is following it is the one place a blank closing under a
+       * stationary reader can be seen at all. Without it the departure would
+       * only ever be sampled when the reader moved, which is the case it is not
+       * watching for.
+       */
+      sampleTailWatch();
       return;
     }
+    settleFramesRef.current = SETTLE_FRAMES;
+    applyFollowTarget();
+    startFollowFrame();
+  }, [applyFollowTarget, sampleTailWatch, startFollowFrame]);
 
-    // Follow events only wake the single tail writer. They must not launch a
-    // second scroll action that competes with the RAF loop or the virtualizer.
-    startContinuousFollowLoop();
-  }, [shouldSuspendAutoFollow, startContinuousFollowLoop, virtualItemCount]);
+  const handleUserScrollIntent = useCallback(() => {
+    exitFollowOutput('user-scroll');
+  }, [exitFollowOutput]);
+
+  /**
+   * Turns were rolled back out of the session.
+   *
+   * The ledger cannot say this on its own — a shorter `dialogTurns` is also
+   * what a window re-cut and a hydration merge look like — so the rollback
+   * announces it, the same way a submission does. What it asks for is the
+   * *absence* of the pin: the Turn that was pinned is one of the ones that just
+   * stopped existing, and the transcript now ends somewhere else.
+   *
+   * This takes the viewport whether or not follow owned it. A rollback at
+   * Turn N removes N and everything after it, and the reader had N on screen —
+   * they clicked its own button. So the new tail is always within a Turn of
+   * where they already are, and there is no history below them to be pulled out
+   * of. Gating this on ownership instead made it dead code in the case it was
+   * written for: reaching a Turn far enough up to want it gone means scrolling,
+   * and scrolling is exactly what hands the viewport back to the reader.
+   *
+   * Without it the viewport anchor answers instead, and answers the wrong
+   * question — it holds the reader's Turn at its offset from the viewport top,
+   * so an 8-Turn session rolled back at Turn 7 came to rest showing Turns 2..6
+   * with the new last Turn's answer below the fold.
+   */
+  const handleTurnsRolledBack = useCallback(() => {
+    pendingNewTurnIdRef.current = null;
+    enterFollowOutput('turns-rolled-back');
+  }, [enterFollowOutput]);
 
   const handleScroll = useCallback(() => {
+    // Scroll events describe the resulting viewport position, but do not prove user intent.
+    // Layout growth and virtualizer remeasurement can emit them while output follow still owns
+    // the viewport. Explicit wheel, touch, and keyboard handlers release that ownership instead.
+    //
+    // The other half of the departure sampler. Without it the remembered offset
+    // goes stale whenever the reader moves and the content does not, and the
+    // next crossing is attributed to the wrong one — which here would mean
+    // handing the viewport back to a reader who is still climbing out of it.
+    sampleTailWatch();
+  }, [sampleTailWatch]);
+
+  const getFollowTargetScrollTop = useCallback(() => (
+    isFollowingOutputRef.current ? followStateRef.current.target : null
+  ), []);
+
+  /**
+   * Whether follow-output owns the viewport *now*.
+   *
+   * The `isFollowingOutput` state answers the same question one render later,
+   * which is a different answer inside an event handler that just released it.
+   * A reader's gesture releases ownership and then asks whether the boundary
+   * they are on is worth paging: mirroring the state into a ref at render time
+   * made that ask see the ownership it had itself just ended, and refuse.
+   */
+  const isFollowingOutputNow = useCallback(() => isFollowingOutputRef.current, []);
+
+  /**
+   * The viewport was resized. Keep whatever was on the bottom edge on the
+   * bottom edge.
+   *
+   * A plain scroller preserves `scrollTop`, which anchors the *top* edge: the
+   * bottom is where content gets revealed or swallowed. For a transcript that
+   * is backwards — the interesting end is the bottom — so this anchors there
+   * instead. Follow output already behaves this way for a viewport it owns;
+   * this is the same rule for one it does not.
+   *
+   * The two halves are not equally capable, and the difference is worth
+   * knowing:
+   *
+   * - **A height change moves no content.** Preserving `scrollTop +
+   *   clientHeight` is therefore exact and needs no judgement about what the
+   *   user was doing. It also preserves the distance to the content end, so a
+   *   viewport that was at the end stays at the end for free. Growing the
+   *   viewport is additionally a restoration: the browser used to clamp a
+   *   bottom-anchored viewport at `scrollHeight - clientHeight`, and the
+   *   resident spacer removed that clamp.
+   * - **A width change reflows the transcript.** Where the line that was on the
+   *   bottom edge went is a DOM question, and by the time a resize is observed
+   *   the reflow has already happened — answering it would mean sampling an
+   *   element anchor on the scroll path. The end of the transcript is the one
+   *   position that can be recomputed from geometry, so that case is handled
+   *   and the general one is not.
+   *
+   * Never animated. A height change moves the viewport by exactly the height
+   * that was added or removed, so nothing appears to move at all; the rest is a
+   * correction the user is already watching happen under their cursor.
+   * Ownership does not change either: a gesture ending in the blank expresses
+   * an intent to be at the end, a layout change expresses nothing.
+   */
+  const handleViewportResize = useCallback((input: ViewportResizeInput) => {
     const scroller = scrollerRef.current;
-    if (!scroller) {
+    if (!scroller || isFollowingOutputRef.current) {
+      // Follow re-asserts its own target through `scheduleFollowToLatest`.
       return;
     }
 
-    const currentScrollTop = scroller.scrollTop;
-    const previousScrollTop = lastObservedScrollTopRef.current;
-    lastObservedScrollTopRef.current = currentScrollTop;
-
-    if (!isFollowingOutputRef.current && armedAutoFollowTurnIdRef.current === null) {
-      return;
+    traceViewportRepeating(`resize|${input.wasAtTail}|${input.viewportHeightDeltaPx !== 0}`, {
+      location: 'followOutput.viewportResize',
+      message: 'the scroller box changed under a viewport nobody was following',
+      travelPx: input.viewportHeightDeltaPx,
+      data: () => ({
+        viewportHeightDeltaPx: roundViewportPx(input.viewportHeightDeltaPx),
+        wasAtTail: input.wasAtTail,
+        scrollTopPx: roundViewportPx(scroller.scrollTop),
+        clientHeightPx: scroller.clientHeight,
+      }),
+    });
+
+    if (input.viewportHeightDeltaPx !== 0) {
+      viewportOwner.write({
+        owner: 'layout-correction',
+        topPx: Math.max(0, scroller.scrollTop - input.viewportHeightDeltaPx),
+      });
     }
 
-    if (performance.now() <= programmaticScrollUntilMsRef.current) {
+    const followTarget = resolveFollowTargetScrollTop(scroller);
+    if (
+      input.wasAtTail &&
+      followTarget - scroller.scrollTop > FLOWCHAT_AT_CONTENT_END_THRESHOLD_PX
+    ) {
+      viewportOwner.write({ owner: 'layout-correction', topPx: followTarget });
       return;
     }
 
-    const upwardDelta = previousScrollTop - currentScrollTop;
-    if (upwardDelta > USER_SCROLL_DIRECTION_EPSILON_PX) {
-      const now = performance.now();
-      const hasRecentExplicitUserIntent = now <= explicitUserScrollIntentUntilMsRef.current;
-      const distanceFromBottom = getDistanceFromBottom(scroller);
-      if (!hasRecentExplicitUserIntent) {
-        if (
-          isFollowingOutputRef.current &&
-          distanceFromBottom <= AUTO_FOLLOW_BOTTOM_THRESHOLD_PX
-        ) {
-          return;
-        }
-        return;
-      }
-
-      if (shouldSuspendAutoFollow?.() === true) {
-        if (isFollowingOutputRef.current && hasRecentExplicitUserIntent) {
-          exitFollowOutput('user-scroll-up');
-        }
-        explicitUserScrollIntentUntilMsRef.current = 0;
-        return;
-      }
+  }, [resolveFollowTargetScrollTop, scrollerRef, viewportOwner]);
 
-      explicitUserScrollIntentUntilMsRef.current = 0;
-
-      if (!isFollowingOutputRef.current) {
-        cancelPendingAutoFollowArm();
-        return;
+  useEffect(() => {
+    if (!hasMountedRef.current) {
+      hasMountedRef.current = true;
+      if (virtualItemCount > 0) {
+        enterFollowOutput(isStreaming ? 'streaming-resumed' : 'session-open');
       }
-
-      exitFollowOutput('user-scroll-up');
+      return;
     }
-  }, [cancelPendingAutoFollowArm, exitFollowOutput, scrollerRef, shouldSuspendAutoFollow]);
 
-  useEffect(() => {
-    const scroller = scrollerRef.current;
-    if (scroller) {
-      lastObservedScrollTopRef.current = scroller.scrollTop;
+    if (previousSessionIdRef.current !== activeSessionId) {
+      previousSessionIdRef.current = activeSessionId;
+      previousLatestTurnIdRef.current = latestTurnId;
+      previousDialogTurnCountRef.current = dialogTurnCount;
+      exitFollowOutput('session-changed');
+      retirePin();
+      // A Turn waiting to be shown belongs to the session that gained it.
+      pendingNewTurnIdRef.current = null;
+      if (virtualItemCount > 0) {
+        enterFollowOutput(isStreaming ? 'streaming-resumed' : 'session-open');
+      }
+      return;
     }
-  }, [scrollerRef]);
 
-  useEffect(() => {
-    const previousSessionId = previousSessionIdRef.current;
-    if (previousSessionId === activeSessionId) {
+    /*
+     * An arrival, not a change. `latestTurnId` is the ledger's last Turn and it
+     * is the right identity — but a rollback truncates the ledger, which moves
+     * that identity *backwards* onto a Turn that has been there all along. Read
+     * as an arrival it pinned the survivor to the viewport top, which is the
+     * reader's "I undid my message and it jumped to the one before it".
+     *
+     * The ledger growing is what separates the two. Nothing else that rewrites
+     * `dialogTurns` — a history page merging in above, a window re-cut, a
+     * hydration — moves the last Turn, so requiring growth costs nothing and
+     * excludes every truncation.
+     */
+    const previousDialogTurnCount = previousDialogTurnCountRef.current;
+    previousDialogTurnCountRef.current = dialogTurnCount;
+    const isNewTurn = Boolean(
+      latestTurnId
+      && latestTurnId !== previousLatestTurnIdRef.current
+      && dialogTurnCount > previousDialogTurnCount,
+    );
+    previousLatestTurnIdRef.current = latestTurnId;
+    if (virtualItemCount === 0) {
       return;
     }
-
-    previousSessionIdRef.current = activeSessionId;
-    cancelPendingAutoFollowArm();
-    explicitUserScrollIntentUntilMsRef.current = 0;
-    nativeSmoothFollowUntilMsRef.current = 0;
-    const nextFollowState = Boolean(activeSessionId && virtualItemCount === 0);
-
-    if (nextFollowState) {
-      setFollowingOutput(true);
+    if (isNewTurn) {
+      enterFollowOutput('new-turn');
       return;
     }
-
-    setFollowingOutput(false);
+    /*
+     * The transcript changed without a new Turn, which is the moment a deferred
+     * one can become alignable — the presentation being restored to the live
+     * tail is exactly that. A retry that still cannot align it leaves the
+     * viewport alone and stays pending.
+     */
+    if (pendingNewTurnIdRef.current === latestTurnId && latestTurnId !== null) {
+      enterFollowOutput('new-turn');
+    }
   }, [
     activeSessionId,
-    cancelPendingAutoFollowArm,
+    dialogTurnCount,
+    enterFollowOutput,
+    exitFollowOutput,
+    isStreaming,
     latestTurnId,
-    setFollowingOutput,
+    retirePin,
     virtualItemCount,
   ]);
 
   useEffect(() => {
-    if (!isFollowingOutput || !isStreaming) {
-      stopContinuousFollowLoop();
+    if (!isViewportActive) {
+      stopFollowFrame();
+      return;
+    }
+    if (isFollowingOutput && isStreaming) {
+      scheduleFollowToLatest();
+    }
+  }, [isFollowingOutput, isStreaming, isViewportActive, scheduleFollowToLatest, stopFollowFrame]);
+
+  // Settle any blank the hold rule accumulated once output stops arriving.
+  // A pinned Turn keeps its blank: that space is the mode, not a leftover.
+  useEffect(() => {
+    const wasStreaming = wasStreamingRef.current;
+    wasStreamingRef.current = isStreaming;
+    if (wasStreaming === isStreaming || isStreaming) {
+      return;
+    }
+    if (!isFollowingOutputRef.current || followStateRef.current.mode !== 'hold-tail') {
       return;
     }
 
-    scheduleFollowToLatest('streaming-started');
-    startContinuousFollowLoop();
-  }, [isFollowingOutput, isStreaming, scheduleFollowToLatest, startContinuousFollowLoop, stopContinuousFollowLoop]);
+    const scroller = scrollerRef.current;
+    if (!scroller) {
+      return;
+    }
+    const contentEnd = readContentEndScrollTop(scroller);
+    if (followStateRef.current.target - contentEnd > BOTTOM_EPSILON_PX) {
+      followStateRef.current = { mode: 'hold-tail', target: contentEnd };
+      runContentEndScroll('smooth');
+    }
+  }, [isStreaming, readContentEndScrollTop, runContentEndScroll, scrollerRef]);
 
-  // Restart follow loop when the page becomes visible again
   useEffect(() => {
-    const handleVisibility = () => {
-      if (!document.hidden && isFollowingOutputRef.current && isStreamingRef.current) {
-        startContinuousFollowLoop();
+    const handleVisibilityChange = () => {
+      if (!document.hidden) {
+        scheduleFollowToLatest();
       }
     };
-    document.addEventListener('visibilitychange', handleVisibility);
-    return () => document.removeEventListener('visibilitychange', handleVisibility);
-  }, [startContinuousFollowLoop]);
+    document.addEventListener('visibilitychange', handleVisibilityChange);
+    return () => document.removeEventListener('visibilitychange', handleVisibilityChange);
+  }, [scheduleFollowToLatest]);
 
-  useEffect(() => {
-    return () => {
-      stopContinuousFollowLoop();
-    };
-  }, [stopContinuousFollowLoop]);
+  useEffect(() => stopFollowFrame, [stopFollowFrame]);
+  // A watch the transcript outlived is not an outcome, and leaving it open
+  // would drop it from the trail entirely.
+  useEffect(() => () => closeTailWatchRef.current('unmounted'), []);
 
   return {
     isFollowingOutput,
     enterFollowOutput,
     exitFollowOutput,
-    preparePinnedTurnFollowHandoff,
-    armFollowOutputForNewTurn,
-    resumeFollowOutputForMountedStream,
-    activateArmedFollowOutput,
-    cancelPendingAutoFollowArm,
     scheduleFollowToLatest,
+    isFollowingOutputNow,
+    isFollowCorrectingViewport,
     handleUserScrollIntent,
+    handleTurnsRolledBack,
     handleScroll,
+    handleViewportResize,
+    getFollowTargetScrollTop,
   };
 }
diff --git a/src/web-ui/src/flow_chat/components/modern/useFlowChatNavigation.focus.test.tsx b/src/web-ui/src/flow_chat/components/modern/useFlowChatNavigation.focus.test.tsx
new file mode 100644
index 0000000000..52770ff04f
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/modern/useFlowChatNavigation.focus.test.tsx
@@ -0,0 +1,147 @@
+// @vitest-environment jsdom
+
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+/*
+ * The two properties this file exists for, both measured from a usage-report
+ * click before they held:
+ *
+ * - the aim goes through the register, not `element.scrollIntoView`;
+ * - it is attempted in the same task as the Turn navigation, so the reader is
+ *   not shown the Turn placement and then moved off it. Measured: the Turn
+ *   navigation settled 178px and 334.7px from where it put itself, because
+ *   this aim arrived three frames later and the intermediate frame was painted.
+ */
+
+const mocks = vi.hoisted(() => ({
+  resolveFlowChatFocusTarget: vi.fn(),
+  switchChatSession: vi.fn(),
+  activeSessionId: 'session-1' as string | undefined,
+}));
+
+vi.mock('../../services/FlowChatManager', () => ({
+  flowChatManager: { switchChatSession: mocks.switchChatSession },
+}));
+vi.mock('../../store/FlowChatStore', () => ({
+  flowChatStore: { getState: () => ({ sessions: new Map() }) },
+}));
+vi.mock('../../store/modernFlowChatStore', () => ({
+  useModernFlowChatStore: {
+    getState: () => ({ activeSession: { sessionId: mocks.activeSessionId } }),
+  },
+}));
+vi.mock('./flowChatFocusTarget', () => ({
+  resolveFlowChatFocusTarget: mocks.resolveFlowChatFocusTarget,
+}));
+
+const { globalEventBus } = await import('@/infrastructure/event-bus');
+const { FLOWCHAT_FOCUS_ITEM_EVENT } = await import('../../events/flowchatNavigation');
+const { useFlowChatNavigation } = await import('./useFlowChatNavigation');
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+// jsdom ships no CSS.escape. The ids here need no escaping; this only has to
+// exist so the selector can be built.
+if (typeof globalThis.CSS === 'undefined') {
+  (globalThis as { CSS?: unknown }).CSS = {};
+}
+if (typeof CSS.escape !== 'function') {
+  CSS.escape = (value: string) => value.replace(/["\\]/g, '\\$&');
+}
+
+const FOCUS_ITEM_ID = 'call_00_zknuBLUKP7Y6JTioDI5Z8386';
+
+function Harness({ listRef }: { listRef: React.RefObject<any> }) {
+  useFlowChatNavigation({
+    activeSessionId: 'session-1',
+    virtualItems: [],
+    virtualListRef: listRef,
+  });
+  return null;
+}
+
+describe('useFlowChatNavigation focus placement', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+  let frames: FrameRequestCallback[];
+  let listRef: React.RefObject<any>;
+  let focusFlowItem: ReturnType<typeof vi.fn>;
+  let scrollIntoView: ReturnType<typeof vi.fn>;
+
+  function renderItem() {
+    const element = document.createElement('div');
+    element.dataset.flowItemId = FOCUS_ITEM_ID;
+    element.scrollIntoView = scrollIntoView as unknown as HTMLElement['scrollIntoView'];
+    document.body.append(element);
+    return element;
+  }
+
+  async function dispatchFocusRequest() {
+    await act(async () => {
+      globalEventBus.emit(FLOWCHAT_FOCUS_ITEM_EVENT, {
+        sessionId: 'session-1',
+        itemId: FOCUS_ITEM_ID,
+      });
+      // Let the handler's own awaits resolve, without granting it a frame.
+      await Promise.resolve();
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+  }
+
+  beforeEach(() => {
+    mocks.activeSessionId = 'session-1';
+    mocks.resolveFlowChatFocusTarget.mockReturnValue({ preferTurnNavigation: false });
+    scrollIntoView = vi.fn();
+    focusFlowItem = vi.fn(() => true);
+    listRef = { current: { focusFlowItem, navigateToTurn: vi.fn(), scrollToIndex: vi.fn(), scrollToTurn: vi.fn() } };
+    frames = [];
+    vi.stubGlobal('requestAnimationFrame', vi.fn((callback: FrameRequestCallback) => {
+      frames.push(callback);
+      return frames.length;
+    }));
+    vi.stubGlobal('cancelAnimationFrame', vi.fn());
+    container = document.createElement('div');
+    document.body.append(container);
+    root = createRoot(container);
+    act(() => root.render(<Harness listRef={listRef} />));
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    document.body.replaceChildren();
+    vi.unstubAllGlobals();
+    vi.clearAllMocks();
+  });
+
+  it('aims through the register rather than the element', async () => {
+    renderItem();
+    await dispatchFocusRequest();
+
+    expect(focusFlowItem).toHaveBeenCalledWith(FOCUS_ITEM_ID);
+    expect(scrollIntoView).not.toHaveBeenCalled();
+  });
+
+  it('aims without first yielding a frame to the Turn placement', async () => {
+    renderItem();
+    await dispatchFocusRequest();
+
+    // Nothing has been given a frame yet: every queued callback is still queued.
+    expect(frames).toHaveLength(0);
+    expect(focusFlowItem).toHaveBeenCalledTimes(1);
+  });
+
+  it('asks again on the next frame while the item is still unrendered', async () => {
+    await dispatchFocusRequest();
+    expect(focusFlowItem).not.toHaveBeenCalled();
+    expect(frames).toHaveLength(1);
+
+    renderItem();
+    await act(async () => { frames.shift()?.(16); });
+
+    expect(focusFlowItem).toHaveBeenCalledWith(FOCUS_ITEM_ID);
+  });
+});
diff --git a/src/web-ui/src/flow_chat/components/modern/useFlowChatNavigation.test.ts b/src/web-ui/src/flow_chat/components/modern/useFlowChatNavigation.test.ts
index 2827475dd9..f27a7f7a6f 100644
--- a/src/web-ui/src/flow_chat/components/modern/useFlowChatNavigation.test.ts
+++ b/src/web-ui/src/flow_chat/components/modern/useFlowChatNavigation.test.ts
@@ -1,313 +1,17 @@
-// @vitest-environment jsdom
+import fs from 'node:fs';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
 
-import React, { act, useRef } from 'react';
-import { createRoot } from 'react-dom/client';
-import { describe, expect, it, vi } from 'vitest';
-import { globalEventBus } from '@/infrastructure/event-bus';
-import type { FlowToolItem, ModelRound, Session } from '../../types/flow-chat';
-import { useModernFlowChatStore, type VirtualItem } from '../../store/modernFlowChatStore';
-import {
-  FLOWCHAT_FOCUS_ITEM_EVENT,
-  FLOWCHAT_PIN_TURN_TO_TOP_EVENT,
-  type FlowChatFocusItemRequest,
-  type FlowChatPinTurnToTopRequest,
-} from '../../events/flowchatNavigation';
-import { resolveFlowChatFocusTarget } from './flowChatFocusTarget';
-import { useFlowChatNavigation } from './useFlowChatNavigation';
-import type { VirtualMessageListRef } from './VirtualMessageList';
+const source = fs.readFileSync(path.resolve(__dirname, 'useFlowChatNavigation.ts'), 'utf8');
 
-globalThis.IS_REACT_ACT_ENVIRONMENT = true;
-
-function makeReadTool(id: string): FlowToolItem {
-  return {
-    id,
-    type: 'tool',
-    toolName: 'Read',
-    timestamp: 1000,
-    status: 'completed',
-    toolCall: {
-      id,
-      input: { file_path: 'src/main.rs' },
-    },
-    toolResult: {
-      result: 'file contents',
-      success: true,
-    },
-  };
-}
-
-function makeRound(items: FlowToolItem[]): ModelRound {
-  return {
-    id: 'round-1',
-    index: 0,
-    items,
-    isStreaming: false,
-    isComplete: true,
-    status: 'completed',
-    startTime: 1000,
-  };
-}
-
-function makeSession(round: ModelRound): Session {
-  return {
-    sessionId: 'session-1',
-    dialogTurns: [{
-      id: 'turn-1',
-      sessionId: 'session-1',
-      userMessage: {
-        id: 'user-1',
-        content: 'Inspect the file',
-        timestamp: 900,
-      },
-      modelRounds: [round],
-      status: 'completed',
-      startTime: 900,
-    }],
-    status: 'idle',
-    config: {},
-    createdAt: 800,
-    lastActiveAt: 1000,
-    error: null,
-    sessionKind: 'flow_chat',
-  };
-}
-
-describe('useFlowChatNavigation focus resolution', () => {
-  it('requests explore group expansion before focusing a grouped tool item', () => {
-    const tool = makeReadTool('tool-1');
-    const round = makeRound([tool]);
-    const session = makeSession(round);
-    const virtualItems: VirtualItem[] = [
-      {
-        type: 'user-message',
-        data: session.dialogTurns[0].userMessage,
-        turnId: 'turn-1',
-      },
-      {
-        type: 'explore-group',
-        turnId: 'turn-1',
-        data: {
-          groupId: 'round-1',
-          rounds: [round],
-          allItems: [tool],
-          stats: {
-            readCount: 1,
-            searchCount: 0,
-            commandCount: 0,
-          },
-          isGroupStreaming: false,
-          isLastGroupInTurn: true,
-        },
-      },
-    ];
-
-    const target = resolveFlowChatFocusTarget({
-      sessionId: session.sessionId,
-      turnIndex: 1,
-      itemId: tool.id,
-      source: 'usage-report',
-    }, virtualItems, session);
-
-    expect(target).toMatchObject({
-      resolvedVirtualIndex: 1,
-      resolvedTurnId: 'turn-1',
-      resolvedTurnIndex: 1,
-      expandExploreGroupId: 'round-1',
-      focusItemId: tool.id,
-      preferPinnedTurnNavigation: false,
-    });
-  });
-
-  it('resolves absolute Turn indexes through the catalog instead of the partial tail array', () => {
-    const session: Session = {
-      ...makeSession(makeRound([])),
-      dialogTurns: [98, 99, 100].map(turnIndex => ({
-        id: `turn-${turnIndex}`,
-        sessionId: 'session-1',
-        backendTurnIndex: turnIndex - 1,
-        userMessage: {
-          id: `user-${turnIndex}`,
-          content: `Prompt ${turnIndex}`,
-          timestamp: 1000,
-        },
-        modelRounds: [],
-        status: 'completed' as const,
-        startTime: 1000,
-      })),
-      isPartial: true,
-      loadedTurnCount: 3,
-      totalTurnCount: 100,
-      turnCatalog: {
-        schemaVersion: 1,
-        sessionId: 'session-1',
-        revision: 'catalog-1',
-        totalTurnCount: 100,
-        complete: true,
-        entries: Array.from({ length: 100 }, (_, ordinal) => ({
-          ordinal,
-          storageTurnIndex: ordinal,
-          turnId: `turn-${ordinal + 1}`,
-          preview: `Prompt ${ordinal + 1}`,
-          previewTruncated: false,
-        })),
-      },
-    };
-
-    expect(resolveFlowChatFocusTarget({
-      sessionId: session.sessionId,
-      turnIndex: 2,
-      source: 'usage-report',
-    }, [], session)).toMatchObject({
-      resolvedTurnId: 'turn-2',
-      resolvedTurnIndex: 2,
-    });
-    expect(resolveFlowChatFocusTarget({
-      sessionId: session.sessionId,
-      turnIndex: 99,
-      source: 'usage-report',
-    }, [], session)).toMatchObject({
-      resolvedTurnId: 'turn-99',
-      resolvedTurnIndex: 99,
-    });
-  });
-
-  it('treats an explicit stable Turn id as authoritative', () => {
-    const session = makeSession(makeRound([]));
-    const target = resolveFlowChatFocusTarget({
-      sessionId: session.sessionId,
-      turnId: 'persisted-parent-turn',
-      turnIndex: 1,
-      source: 'btw-back',
-    }, [], session);
-
-    expect(target).toMatchObject({
-      resolvedTurnId: 'persisted-parent-turn',
-      resolvedTurnIndex: 1,
-      preferPinnedTurnNavigation: true,
-    });
+describe('useFlowChatNavigation natural navigation contract', () => {
+  it('uses natural Turn navigation for resolved focus targets', () => {
+    expect(source).toContain('list.navigateToTurn(target.resolvedTurnId');
+    expect(source).not.toContain('pinTurnToTop');
   });
-});
-
-describe('useFlowChatNavigation Turn pin handling', () => {
-  it('does not reuse an absolute Turn index as a local index after delegated navigation fails', async () => {
-    const container = document.createElement('div');
-    document.body.appendChild(container);
-    const root = createRoot(container);
-    const scrollToTurn = vi.fn();
-    const onNavigateToFocusTurn = vi.fn(async () => false);
-    const partialSession: Session = {
-      ...makeSession(makeRound([])),
-      dialogTurns: [98, 99, 100].map(turnIndex => ({
-        id: `turn-${turnIndex}`,
-        sessionId: 'session-1',
-        backendTurnIndex: turnIndex - 1,
-        userMessage: {
-          id: `user-${turnIndex}`,
-          content: `Prompt ${turnIndex}`,
-          timestamp: 1000,
-        },
-        modelRounds: [],
-        status: 'completed' as const,
-        startTime: 1000,
-      })),
-      isPartial: true,
-      loadedTurnCount: 3,
-      totalTurnCount: 100,
-    };
-    useModernFlowChatStore.getState().setActiveSession(partialSession);
-
-    function Harness() {
-      const virtualListRef = useRef<VirtualMessageListRef | null>({
-        scrollToTurn,
-      } as unknown as VirtualMessageListRef);
-      useFlowChatNavigation({
-        activeSessionId: partialSession.sessionId,
-        virtualItems: useModernFlowChatStore.getState().virtualItems,
-        virtualListRef,
-        onNavigateToFocusTurn,
-      });
-      return null;
-    }
-
-    await act(async () => {
-      root.render(React.createElement(Harness));
-    });
-    const request: FlowChatFocusItemRequest = {
-      sessionId: partialSession.sessionId,
-      turnIndex: 2,
-      source: 'usage-report',
-    };
-    await act(async () => {
-      globalEventBus.emit(FLOWCHAT_FOCUS_ITEM_EVENT, request, 'test');
-      await new Promise(resolve => window.setTimeout(resolve, 0));
-    });
-
-    expect(onNavigateToFocusTurn).toHaveBeenCalledWith(request);
-    expect(scrollToTurn).not.toHaveBeenCalled();
-
-    await act(async () => {
-      root.unmount();
-    });
-    useModernFlowChatStore.getState().clear();
-    container.remove();
-  });
-
-  it('runs the pre-pin callback before pinning a newly submitted Turn', async () => {
-    const container = document.createElement('div');
-    document.body.appendChild(container);
-    const root = createRoot(container);
-    const onBeforeTurnPinRequest = vi.fn();
-    const pinTurnToTop = vi.fn(() => true);
-    const virtualItems: VirtualItem[] = [{
-      type: 'user-message',
-      turnId: 'turn-2',
-      data: {
-        id: 'user-2',
-        content: 'New prompt',
-        timestamp: 1000,
-      },
-    }];
-
-    function Harness() {
-      const virtualListRef = useRef<VirtualMessageListRef | null>({
-        pinTurnToTop,
-      } as unknown as VirtualMessageListRef);
-      useFlowChatNavigation({
-        activeSessionId: 'session-1',
-        virtualItems,
-        virtualListRef,
-        onBeforeTurnPinRequest,
-      });
-      return null;
-    }
-
-    await act(async () => {
-      root.render(React.createElement(Harness));
-    });
-    const request: FlowChatPinTurnToTopRequest = {
-      sessionId: 'session-1',
-      turnId: 'turn-2',
-      behavior: 'auto',
-      source: 'send-message',
-      pinMode: 'sticky-latest',
-    };
-    await act(async () => {
-      globalEventBus.emit(FLOWCHAT_PIN_TURN_TO_TOP_EVENT, request, 'test');
-      await Promise.resolve();
-    });
-
-    expect(onBeforeTurnPinRequest).toHaveBeenCalledWith(request);
-    expect(pinTurnToTop).toHaveBeenCalledWith('turn-2', {
-      behavior: 'auto',
-      pinMode: 'sticky-latest',
-    });
-    expect(onBeforeTurnPinRequest.mock.invocationCallOrder[0]).toBeLessThan(
-      pinTurnToTop.mock.invocationCallOrder[0],
-    );
 
-    await act(async () => {
-      root.unmount();
-    });
-    container.remove();
+  it('does not subscribe to a send-message positioning event', () => {
+    expect(source).not.toContain('sticky-latest');
+    expect(source).not.toContain('PIN_TURN_TO_TOP');
   });
 });
diff --git a/src/web-ui/src/flow_chat/components/modern/useFlowChatNavigation.ts b/src/web-ui/src/flow_chat/components/modern/useFlowChatNavigation.ts
index 69f457ba74..c5ebeac772 100644
--- a/src/web-ui/src/flow_chat/components/modern/useFlowChatNavigation.ts
+++ b/src/web-ui/src/flow_chat/components/modern/useFlowChatNavigation.ts
@@ -1,11 +1,10 @@
 /**
  * FlowChat navigation side effects.
  *
- * Handles cross-session focus requests and turn pinning events for the modern
- * virtualized list.
+ * Handles cross-session focus requests for the modern virtualized list.
  */
 
-import { useEffect, useLayoutEffect, useRef, useState, type RefObject } from 'react';
+import { useEffect, useLayoutEffect, useRef, type RefObject } from 'react';
 import { globalEventBus } from '@/infrastructure/event-bus';
 import { createLogger } from '@/shared/utils/logger';
 import { flowChatStore } from '../../store/FlowChatStore';
@@ -13,9 +12,7 @@ import { useModernFlowChatStore, type VirtualItem } from '../../store/modernFlow
 import { flowChatManager } from '../../services/FlowChatManager';
 import {
   FLOWCHAT_FOCUS_ITEM_EVENT,
-  FLOWCHAT_PIN_TURN_TO_TOP_EVENT,
   type FlowChatFocusItemRequest,
-  type FlowChatPinTurnToTopRequest,
 } from '../../events/flowchatNavigation';
 import type { VirtualMessageListRef } from './VirtualMessageList';
 import { resolveFlowChatFocusTarget, type ResolvedFocusTarget } from './flowChatFocusTarget';
@@ -27,7 +24,6 @@ interface UseFlowChatNavigationOptions {
   virtualItems: VirtualItem[];
   virtualListRef: RefObject<VirtualMessageListRef | null>;
   onExpandExploreGroup?: (groupId: string) => void;
-  onBeforeTurnPinRequest?: (request: FlowChatPinTurnToTopRequest) => void;
   onNavigateToFocusTurn?: (request: FlowChatFocusItemRequest) => Promise<boolean> | boolean;
 }
 
@@ -40,14 +36,6 @@ async function waitForCondition(predicate: () => boolean, timeoutMs: number): Pr
   return predicate();
 }
 
-async function waitForAnimationFrames(frameCount: number): Promise<void> {
-  let remaining = Math.max(0, frameCount);
-  while (remaining > 0) {
-    await new Promise<void>(resolve => requestAnimationFrame(() => resolve()));
-    remaining -= 1;
-  }
-}
-
 function navigateToResolvedTarget(
   virtualListRef: RefObject<VirtualMessageListRef | null>,
   target: ResolvedFocusTarget,
@@ -56,8 +44,8 @@ function navigateToResolvedTarget(
   const list = virtualListRef.current;
   if (!list) return;
 
-  if (target.preferPinnedTurnNavigation && target.resolvedTurnId) {
-    list.pinTurnToTop(target.resolvedTurnId, { behavior: 'auto' });
+  if (target.preferTurnNavigation && target.resolvedTurnId) {
+    list.navigateToTurn(target.resolvedTurnId, { behavior: 'auto' });
     return;
   }
 
@@ -76,10 +64,8 @@ export function useFlowChatNavigation({
   virtualItems,
   virtualListRef,
   onExpandExploreGroup,
-  onBeforeTurnPinRequest,
   onNavigateToFocusTurn,
 }: UseFlowChatNavigationOptions): void {
-  const [pendingTurnPinRequest, setPendingTurnPinRequest] = useState<FlowChatPinTurnToTopRequest | null>(null);
   const virtualItemsRef = useRef(virtualItems);
   const onExpandExploreGroupRef = useRef(onExpandExploreGroup);
   const onNavigateToFocusTurnRef = useRef(onNavigateToFocusTurn);
@@ -90,35 +76,6 @@ export function useFlowChatNavigation({
     onNavigateToFocusTurnRef.current = onNavigateToFocusTurn;
   }, [onExpandExploreGroup, onNavigateToFocusTurn, virtualItems]);
 
-  useEffect(() => {
-    const unsubscribe = globalEventBus.on<FlowChatPinTurnToTopRequest>(FLOWCHAT_PIN_TURN_TO_TOP_EVENT, (request) => {
-      if (!request || request.sessionId !== activeSessionId) {
-        return;
-      }
-
-      onBeforeTurnPinRequest?.(request);
-      setPendingTurnPinRequest(request);
-    });
-
-    return unsubscribe;
-  }, [activeSessionId, onBeforeTurnPinRequest]);
-
-  useEffect(() => {
-    if (!pendingTurnPinRequest) return;
-    if (pendingTurnPinRequest.sessionId !== activeSessionId) {
-      setPendingTurnPinRequest(null);
-      return;
-    }
-
-    const accepted = virtualListRef.current?.pinTurnToTop(pendingTurnPinRequest.turnId, {
-      behavior: pendingTurnPinRequest.behavior ?? 'auto',
-      pinMode: pendingTurnPinRequest.pinMode,
-    }) ?? false;
-    if (accepted) {
-      setPendingTurnPinRequest(null);
-    }
-  }, [activeSessionId, pendingTurnPinRequest, virtualItems, virtualListRef]);
-
   useEffect(() => {
     const unsubscribe = globalEventBus.on<FlowChatFocusItemRequest>(FLOWCHAT_FOCUS_ITEM_EVENT, async (request) => {
       const { sessionId, itemId } = request;
@@ -183,8 +140,6 @@ export function useFlowChatNavigation({
 
       if (!itemId) return;
 
-      await waitForAnimationFrames(2);
-
       const maxAttempts = 120;
       let attempts = 0;
       let expandedExploreGroupId: string | null = null;
@@ -204,11 +159,11 @@ export function useFlowChatNavigation({
         }
         const focusItemId = currentTarget.focusItemId ?? itemId;
         const element = document.querySelector(`[data-flow-item-id="${CSS.escape(focusItemId)}"]`) as HTMLElement | null;
-        if (!element) {
+        if (!element || !virtualListRef.current?.focusFlowItem(focusItemId)) {
           if (
             attempts % 12 === 0
             && !delegatedTurnNavigationAttempted
-            && !currentTarget.preferPinnedTurnNavigation
+            && !currentTarget.preferTurnNavigation
           ) {
             navigateToResolvedTarget(virtualListRef, currentTarget);
           }
@@ -218,12 +173,24 @@ export function useFlowChatNavigation({
           return;
         }
 
-        element.scrollIntoView({ block: 'center', inline: 'nearest', behavior: 'auto' });
         element.classList.add('flowchat-flow-item--focused');
         window.setTimeout(() => element.classList.remove('flowchat-flow-item--focused'), 1600);
       };
 
-      requestAnimationFrame(tryFocus);
+      /*
+       * Tried in this task before yielding a frame, because the Turn navigation
+       * above has already placed the viewport and every frame between the two
+       * placements is one the reader watches the transcript land and jump
+       * again. Measured from two usage-report clicks: the Turn navigation
+       * settled 178px and 334.7px away from where it put itself, because this
+       * aim arrived 41ms — three frames — later, and the intermediate position
+       * was painted (`nextFramePx` equalled it both times).
+       *
+       * When the item is not rendered yet the retry loop below is unchanged,
+       * and the Turn placement is what the reader looks at until it is. That
+       * part is unavoidable: something has to be on screen while we wait.
+       */
+      tryFocus();
     });
 
     return unsubscribe;
diff --git a/src/web-ui/src/flow_chat/components/modern/useFlowChatViewportAnchor.test.tsx b/src/web-ui/src/flow_chat/components/modern/useFlowChatViewportAnchor.test.tsx
new file mode 100644
index 0000000000..ff13505b55
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/modern/useFlowChatViewportAnchor.test.tsx
@@ -0,0 +1,643 @@
+// @vitest-environment jsdom
+
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  ANCHOR_MISSING_TURN_ATTEMPTS,
+  ANCHOR_SETTLE_FRAMES,
+  USER_DRIVEN_SCROLL_WINDOW_MS,
+} from './flowChatViewportAnchor';
+import {
+  useFlowChatViewportAnchor,
+  type FlowChatViewportAnchorApi,
+} from './useFlowChatViewportAnchor';
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+/*
+ * The one trace here that is asserted on rather than merely tolerated. The rest
+ * of the trail is coalesced and reports whatever the last of a series happened
+ * to hold; this one fires once per wait and its numbers are the whole point of
+ * it, so it is worth pinning that it fires exactly once and says the truth.
+ */
+const mocks = vi.hoisted(() => ({ traceViewport: vi.fn() }));
+vi.mock('@/infrastructure/diagnostics/flowChatViewportDiagnostics', async () => {
+  const actual = await vi.importActual<
+    typeof import('@/infrastructure/diagnostics/flowChatViewportDiagnostics')
+  >('@/infrastructure/diagnostics/flowChatViewportDiagnostics');
+  return { ...actual, traceViewport: mocks.traceViewport };
+});
+
+const VIEWPORT_HEIGHT = 500;
+const TURN_HEIGHT = 40;
+
+function rect(top: number, height: number): DOMRect {
+  return {
+    top,
+    bottom: top + height,
+    height,
+    left: 0,
+    right: 800,
+    width: 800,
+    x: 0,
+    y: top,
+    toJSON: () => ({}),
+  } as DOMRect;
+}
+
+interface HarnessProps {
+  scroller: HTMLElement;
+  isViewportOwnedElsewhere: () => boolean;
+  onApi: (api: FlowChatViewportAnchorApi) => void;
+}
+
+function Harness({ scroller, isViewportOwnedElsewhere, onApi }: HarnessProps) {
+  const scrollerRef = React.useRef<HTMLElement | null>(scroller);
+  // The anchor no longer touches the scroller itself; the register does, and
+  // here that is the plain displacement it used to apply.
+  const shiftViewport = React.useCallback((byPx: number) => {
+    scroller.scrollTop += byPx;
+  }, []);
+  onApi(useFlowChatViewportAnchor({ scrollerRef, isViewportOwnedElsewhere, shiftViewport }));
+  return null;
+}
+
+describe('useFlowChatViewportAnchor', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+  let isMounted: boolean;
+  let scroller: HTMLDivElement;
+  let api: FlowChatViewportAnchorApi;
+  let frames: FrameRequestCallback[];
+  let now: number;
+  let isOwnedElsewhere: boolean;
+
+  /**
+   * Place Turns in the transcript's own coordinate space.
+   *
+   * Rects are read back relative to the viewport, so writing `scrollTop` moves
+   * them exactly as a real scroller would — which is what makes a correction
+   * observable, and a second correction a no-op.
+   */
+  function layoutTurns(turnTops: Record<string, number>) {
+    scroller.replaceChildren();
+    for (const [turnId, contentTop] of Object.entries(turnTops)) {
+      const element = document.createElement('div');
+      element.className = 'virtual-item-wrapper';
+      element.dataset.itemType = 'user-message';
+      element.dataset.turnId = turnId;
+      element.getBoundingClientRect = () => rect(contentTop - scroller.scrollTop, TURN_HEIGHT);
+      scroller.append(element);
+    }
+  }
+
+  function runFrame() {
+    const frame = frames.shift();
+    expect(frame).toBeDefined();
+    act(() => frame?.(16));
+  }
+
+  function unmount() {
+    if (!isMounted) return;
+    isMounted = false;
+    act(() => root.unmount());
+  }
+
+  beforeEach(() => {
+    mocks.traceViewport.mockReset();
+    container = document.createElement('div');
+    scroller = document.createElement('div');
+    document.body.append(container, scroller);
+    scroller.getBoundingClientRect = () => rect(0, VIEWPORT_HEIGHT);
+    // jsdom leaves this at 0, and the anchor uses it to tell a marker on screen
+    // from one past the bottom edge.
+    Object.defineProperty(scroller, 'clientHeight', {
+      configurable: true,
+      value: VIEWPORT_HEIGHT,
+    });
+    Object.defineProperty(scroller, 'scrollTop', { configurable: true, writable: true, value: 0 });
+    frames = [];
+    now = 10_000;
+    isOwnedElsewhere = false;
+    vi.stubGlobal('requestAnimationFrame', vi.fn((callback: FrameRequestCallback) => {
+      frames.push(callback);
+      return frames.length;
+    }));
+    vi.stubGlobal('cancelAnimationFrame', vi.fn());
+    vi.spyOn(performance, 'now').mockImplementation(() => now);
+
+    root = createRoot(container);
+    isMounted = true;
+    act(() => root.render(
+      <Harness
+        scroller={scroller}
+        isViewportOwnedElsewhere={() => isOwnedElsewhere}
+        onApi={next => { api = next; }}
+      />,
+    ));
+  });
+
+  afterEach(() => {
+    unmount();
+    container.remove();
+    scroller.remove();
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it('puts the anchored Turn back where the reader left it', () => {
+    scroller.scrollTop = 1000;
+    layoutTurns({ 'turn-3': 980, 'turn-4': 1440 });
+    api.captureAnchor();
+
+    // A late measurement above the viewport pushes everything down 880px.
+    layoutTurns({ 'turn-3': 1860, 'turn-4': 2320 });
+
+    expect(api.restoreAnchor()).toBe(true);
+    expect(scroller.scrollTop).toBe(1880);
+  });
+
+  it('is idempotent, because it restores a relationship and not a delta', () => {
+    scroller.scrollTop = 1000;
+    layoutTurns({ 'turn-3': 980 });
+    api.captureAnchor();
+    layoutTurns({ 'turn-3': 1860 });
+
+    api.restoreAnchor();
+    const settled = scroller.scrollTop;
+    api.restoreAnchor();
+    api.restoreAnchor();
+
+    expect(scroller.scrollTop).toBe(settled);
+  });
+
+  it('reports that it could not answer when there is no anchor', () => {
+    layoutTurns({ 'turn-3': 100 });
+    // Nothing captured yet: the caller has to fall back on something coarser.
+    expect(api.restoreAnchor()).toBe(false);
+    expect(scroller.scrollTop).toBe(0);
+  });
+
+  it('stays out of the way while another writer owns the viewport', () => {
+    scroller.scrollTop = 1000;
+    layoutTurns({ 'turn-3': 980 });
+    api.captureAnchor();
+    layoutTurns({ 'turn-3': 1860 });
+
+    isOwnedElsewhere = true;
+
+    expect(api.restoreAnchor()).toBe(false);
+    expect(scroller.scrollTop).toBe(1000);
+  });
+
+  it('keeps an anchor whose Turn is merely not rendered yet', () => {
+    /*
+     * One frame of absence is the normal case at a history junction: the
+     * virtualizer windows from a scroll offset it learns from scroll events, so
+     * the commit that prepends is still rendering the position the reader has
+     * just been moved off. Dropping there loses the reading position one frame
+     * before it could be used.
+     */
+    scroller.scrollTop = 1000;
+    layoutTurns({ 'turn-3': 980 });
+    api.captureAnchor();
+
+    layoutTurns({ 'turn-9': 980 });
+    expect(api.restoreAnchor()).toBe(false);
+    expect(scroller.scrollTop).toBe(1000);
+
+    // The Turn arrives, and the anchor is still the one the reader had.
+    layoutTurns({ 'turn-3': 1200, 'turn-9': 980 });
+    expect(api.restoreAnchor()).toBe(true);
+    expect(scroller.scrollTop).toBe(1220);
+  });
+
+  it('drops an anchor whose Turn has stayed out of the rendered window', () => {
+    scroller.scrollTop = 1000;
+    layoutTurns({ 'turn-3': 980 });
+    api.captureAnchor();
+
+    layoutTurns({ 'turn-9': 980 });
+    for (let attempt = 0; attempt < ANCHOR_MISSING_TURN_ATTEMPTS; attempt += 1) {
+      expect(api.restoreAnchor()).toBe(false);
+    }
+    expect(scroller.scrollTop).toBe(1000);
+
+    // Dropped rather than kept: the next scroll anchors to a Turn that is
+    // actually on screen, without waiting for an intent event to allow it.
+    layoutTurns({ 'turn-9': 1200 });
+    api.captureAnchorForScroll();
+    layoutTurns({ 'turn-9': 1700 });
+    expect(api.restoreAnchor()).toBe(true);
+    expect(scroller.scrollTop).toBe(1500);
+  });
+
+  it('carries the anchor through a scroll while its Turn is still unrendered', () => {
+    /*
+     * The junction case, measured. The anchor was owed 104px, then 140px, then
+     * an amount never established; at each one a scroll 77ms later replaced it
+     * with a Turn at its displaced position, and two of the three were never
+     * corrected at all. The reader is always scrolling here — paging up is what
+     * they are doing — so refusing the scroll outright is not an option either.
+     */
+    scroller.scrollTop = 1000;
+    layoutTurns({ 'turn-3': 980, 'turn-9': 3000 });
+    api.captureAnchor();
+
+    // History arrives: the transcript has moved 140px further down than it was
+    // compensated for, and the reader's own Turn is out of the rendered window,
+    // so the displacement cannot be measured yet.
+    layoutTurns({ 'turn-9': 3140 });
+    expect(api.restoreAnchor()).toBe(false);
+
+    // They keep scrolling up 200px while that repair is still owed. Re-reading
+    // the anchor here takes whatever *is* rendered, at its already-displaced
+    // position, and the 140px is gone for good.
+    scroller.scrollTop = 800;
+    api.markUserScrollIntent();
+    api.captureAnchorForScroll();
+
+    // Their Turn comes back, still 140px low. Nothing else has moved since, so
+    // the whole correction is that 140 — and none of the 200 they scrolled.
+    layoutTurns({ 'turn-3': 1120, 'turn-9': 3140 });
+    expect(api.restoreAnchor()).toBe(true);
+    expect(scroller.scrollTop).toBe(940);
+  });
+
+  it('reports what a wait for the anchored Turn cost, once, when it ends', async () => {
+    /*
+     * The wait is what decides whether a junction is seen: a correction that
+     * shares the prepend's frame costs nothing, and one a frame later is a
+     * visible jump. `attempts` cannot answer how long a wait ran — its trace is
+     * coalesced, so only the first of a series is ever emitted — so the whole
+     * of it is reported at the one moment it exists.
+     */
+    scroller.scrollTop = 1000;
+    layoutTurns({ 'turn-3': 980 });
+    api.captureAnchor();
+
+    layoutTurns({ 'turn-9': 980 });
+    api.openSettleWindow();
+    runFrame();
+    runFrame();
+    now += 48;
+
+    layoutTurns({ 'turn-3': 1100, 'turn-9': 980 });
+    runFrame();
+
+    const waits = mocks.traceViewport.mock.calls
+      .map(([probe]) => probe)
+      .filter(probe => probe.location === 'anchor.turnReturned');
+    expect(waits).toHaveLength(1);
+    expect(waits[0].data()).toMatchObject({
+      turnId: 'turn-3',
+      outcome: 'returned',
+      waitedForMs: 48,
+      // Two settle frames ran and still did not find it; the third did.
+      waitedFrames: 2,
+    });
+
+    // Ended, not merely reported: a second answered frame says nothing more.
+    runFrame();
+    expect(mocks.traceViewport.mock.calls
+      .filter(([probe]) => probe.location === 'anchor.turnReturned')).toHaveLength(1);
+  });
+
+  it('re-anchors on a scroll the user drove, and not on one they did not', () => {
+    scroller.scrollTop = 1000;
+    layoutTurns({ 'turn-3': 980, 'turn-4': 2500 });
+    api.captureAnchor();
+
+    // The transcript moved under the reader, with no gesture behind it.
+    layoutTurns({ 'turn-3': 1860, 'turn-4': 3380 });
+    now += 5_000;
+    api.captureAnchorForScroll();
+    expect(api.restoreAnchor()).toBe(true);
+    expect(scroller.scrollTop).toBe(1880);
+
+    // The reader scrolls on: the position they arrived at is the new anchor,
+    // and turn-4 is what they are now looking at.
+    scroller.scrollTop = 3400;
+    api.markUserScrollIntent();
+    now += USER_DRIVEN_SCROLL_WINDOW_MS - 1;
+    api.captureAnchorForScroll();
+
+    layoutTurns({ 'turn-3': 2360, 'turn-4': 3880 });
+    expect(api.restoreAnchor()).toBe(true);
+    expect(scroller.scrollTop).toBe(3900);
+  });
+
+  it('credits a scroll to the reader when its event arrives after the window', () => {
+    /*
+     * The window is measured from the *input* event and the scrolling it
+     * authorises outlives it: a wheel notch smooth-scrolls for longer than the
+     * window, and a busy main thread delivers the scroll event carrying the
+     * whole travel after it has closed. Measured over 181 seconds: fourteen
+     * gestures, one capture, and seven corrections between 308px and 618px that
+     * each returned the viewport to exactly where its gesture had started.
+     *
+     * Nobody else can account for it — no owner holds the viewport — so it is
+     * theirs, and the anchor goes with them rather than undoing them.
+     */
+    scroller.scrollTop = 1450;
+    layoutTurns({ 'turn-3': 1500 });
+    api.captureAnchor();
+
+    api.markUserScrollIntent();
+    now += USER_DRIVEN_SCROLL_WINDOW_MS * 2;
+    scroller.scrollTop = 834;
+    api.captureAnchorForScroll();
+
+    // In place, not corrected: their 616px is where they asked to be.
+    expect(api.restoreAnchor()).toBe(true);
+    expect(scroller.scrollTop).toBe(834);
+  });
+
+  it('leaves a registered writer where it put the viewport, and still repairs', () => {
+    /*
+     * The other thing that changes `scrollTop`, and it is not drift either: a
+     * writer that owns the viewport chose that position, which is the whole
+     * point of the register. So its travel is taken out of the correction the
+     * same way the reader's is, and what is left is the displacement — here the
+     * 100px the transcript really moved while `scrollTop` stood still.
+     */
+    scroller.scrollTop = 1450;
+    layoutTurns({ 'turn-3': 1500 });
+    api.captureAnchor();
+
+    isOwnedElsewhere = true;
+    now += USER_DRIVEN_SCROLL_WINDOW_MS * 2;
+    scroller.scrollTop = 834;
+    api.captureAnchorForScroll();
+    isOwnedElsewhere = false;
+
+    layoutTurns({ 'turn-3': 1400 });
+    expect(api.restoreAnchor()).toBe(true);
+    expect(scroller.scrollTop).toBe(734);
+  });
+
+  it('does not undo a scroll the settle loop beat the scroll event to', () => {
+    /*
+     * The measured shape, and the one that survived two rounds of fixes. The
+     * settle loop reads `scrollTop` from the DOM, a commit opens a window on
+     * almost every frame, and the scroll event carrying the reader's travel is
+     * delivered after all of that — so a correction runs against a reading
+     * position agreed hundreds of pixels ago, with no capture in between.
+     *
+     * Measured: an anchor agreed at scrollTop 144.7 corrected by -515.8px with
+     * the reader at 652.7, of which 7.8px was the transcript actually moving.
+     */
+    scroller.scrollTop = 144.7;
+    layoutTurns({ 'turn-3': 303.5 });
+    api.captureAnchor();
+
+    // They scroll 508px and no scroll event has been delivered yet, so nothing
+    // re-anchors. Meanwhile the transcript moves 7.8px up underneath them.
+    scroller.scrollTop = 652.7;
+    layoutTurns({ 'turn-3': 295.7 });
+
+    expect(api.restoreAnchor()).toBe(true);
+    expect(scroller.scrollTop).toBeCloseTo(644.9, 6);
+  });
+
+  it('does not bank a frame with nothing to correct as a debt against the reader', () => {
+    /*
+     * The offset and the viewport position it was agreed at are two halves of
+     * one fact, and a frame that advances only one of them leaves the anchor
+     * claiming a repair it does not have. It is reached constantly: a frame in
+     * which only the reader moved has a correction of exactly zero, so this is
+     * the ordinary outcome of a settle rather than a rarity.
+     *
+     * Measured over one reproduction: a 32px scroll and an 81px scroll, each
+     * reported back a frame later as a correction of exactly itself, with the
+     * anchored Turn provably not having moved.
+     */
+    scroller.scrollTop = 414.7;
+    layoutTurns({ 'turn-3': 603.9 });
+    api.captureAnchor();
+
+    // They scroll 32px. Nothing else moved, so there is nothing to correct.
+    scroller.scrollTop = 446.7;
+    expect(api.restoreAnchor()).toBe(true);
+    expect(scroller.scrollTop).toBeCloseTo(446.7, 6);
+
+    // And still nothing on the frame after it.
+    expect(api.restoreAnchor()).toBe(true);
+    expect(scroller.scrollTop).toBeCloseTo(446.7, 6);
+  });
+
+  it('does not re-owe a correction it has just made', () => {
+    /*
+     * The same two halves, on the other branch. The shift puts the Turn back at
+     * the stored offset, so the position advances by the correction and the
+     * offset stays. Get that pair wrong and the repair is read as movement on
+     * the frame after it and undone — which only shows up when the reader has
+     * travelled since the anchor was agreed, so it is the case a repair made
+     * while they are scrolling always falls into.
+     */
+    scroller.scrollTop = 1_000;
+    layoutTurns({ 'turn-3': 980 });
+    api.captureAnchor();
+
+    // They scroll 100px with no scroll event delivered to re-anchor them, and
+    // the transcript moves 40px down underneath them in the same frame.
+    scroller.scrollTop = 1_100;
+    layoutTurns({ 'turn-3': 1_020 });
+    expect(api.restoreAnchor()).toBe(true);
+    expect(scroller.scrollTop).toBe(1_140);
+
+    // Their 100px is theirs and the repair is not movement to undo.
+    expect(api.restoreAnchor()).toBe(true);
+    expect(scroller.scrollTop).toBe(1_140);
+  });
+
+  it('takes a new reading position from where a navigation landed', () => {
+    /*
+     * A navigation is not a displacement, and standing down for it only
+     * postpones the correction. Measured over four clicks on one Turn: the aim
+     * placed the viewport at 287px each time, and each time the anchor put it
+     * back 1653px away on the first frame after the hold lapsed, still anchored
+     * to the Turn the reader had jumped away from.
+     */
+    scroller.scrollTop = 1894;
+    layoutTurns({ 'turn-9': 2295 });
+    api.captureAnchor();
+
+    api.reanchorAfterNavigation();
+    // Nothing to restore in between, which is the point: the position being
+    // left has stopped being the one to put back.
+    expect(api.restoreAnchor()).toBe(false);
+    expect(scroller.scrollTop).toBe(1894);
+
+    // The aim lands, and the commit that renders it opens a settle window.
+    scroller.scrollTop = 287;
+    layoutTurns({ 'turn-1': 300, 'turn-9': 2295 });
+    api.openSettleWindow();
+
+    // A late measurement moves the transcript under the Turn they navigated to,
+    // and the correction is that displacement — not the jump.
+    layoutTurns({ 'turn-1': 400, 'turn-9': 2395 });
+    runFrame();
+    expect(scroller.scrollTop).toBe(387);
+  });
+
+  it('re-asserts the anchor across the frames a settle takes', () => {
+    scroller.scrollTop = 1000;
+    layoutTurns({ 'turn-3': 980 });
+    api.captureAnchor();
+
+    api.openSettleWindow();
+    // Nothing has moved yet on the first frame — the heights land later.
+    runFrame();
+    expect(scroller.scrollTop).toBe(1000);
+
+    layoutTurns({ 'turn-3': 1860 });
+    runFrame();
+    expect(scroller.scrollTop).toBe(1880);
+
+    // And again, for a second batch of measurements in the same settle.
+    layoutTurns({ 'turn-3': 2500 });
+    runFrame();
+    expect(scroller.scrollTop).toBe(2520);
+  });
+
+  it('corrects in the caller\'s own frame, so the displacement is never painted', () => {
+    /*
+     * Measured at a history junction: the prepend compensation moved the
+     * viewport 949px in a layout effect and the anchor took 177px back on the
+     * next frame, so every page up was two visible movements. The caller is a
+     * layout effect or a ResizeObserver callback — both still beat the paint.
+     */
+    scroller.scrollTop = 1000;
+    layoutTurns({ 'turn-3': 980 });
+    api.captureAnchor();
+
+    layoutTurns({ 'turn-3': 1157 });
+    api.openSettleWindow();
+
+    expect(scroller.scrollTop).toBe(1177);
+    // The window still opens, for the measurements that land after this frame.
+    expect(frames).toHaveLength(1);
+  });
+
+  it('opens one settle window at a time', () => {
+    layoutTurns({ 'turn-3': 100 });
+    api.captureAnchor();
+
+    api.openSettleWindow();
+    api.openSettleWindow();
+    api.openSettleWindow();
+
+    expect(frames).toHaveLength(1);
+  });
+
+  it('winds the settle window down once there is no anchor to keep', () => {
+    // No anchor was ever captured, so every frame is a wasted one and the
+    // window has to end on its own rather than run forever.
+    api.openSettleWindow();
+    let ranFrames = 0;
+    while (frames.length > 0 && ranFrames < 100) {
+      runFrame();
+      ranFrames += 1;
+    }
+    expect(ranFrames).toBeGreaterThan(1);
+    expect(frames).toHaveLength(0);
+  });
+
+  it('winds the settle window down when the anchor stays in place', () => {
+    /*
+     * An in-place frame means the relationship is already stable. It spends
+     * the remaining settle budget instead of refreshing it, so an open
+     * transcript that nobody else is writing to does not keep a RAF loop alive.
+     */
+    layoutTurns({ 'turn-3': 100 });
+    api.captureAnchor();
+    api.openSettleWindow();
+
+    let ranFrames = 0;
+    while (frames.length > 0 && ranFrames < 60) {
+      runFrame();
+      ranFrames += 1;
+    }
+
+    expect(ranFrames).toBe(ANCHOR_SETTLE_FRAMES);
+    expect(frames).toHaveLength(0);
+    expect(scroller.scrollTop).toBe(0);
+  });
+
+  it('winds the settle window down while another owner holds the viewport', () => {
+    /*
+     * Measured: 27 seconds of `anchor.stoodDown`, one per frame, with the
+     * viewport parked at 985.3 and follow-output resting on it — which at the
+     * tail is where it lives, not a transient. The loop read the missing-Turn
+     * count left by the frame *before* the stand-down as evidence it was still
+     * waiting for something, and refreshed its own budget on it; that count can
+     * only advance on a frame that does not stand down, so the one condition
+     * jammed the loop and made its only exit unreachable. It ended when the
+     * reader scrolled, and not before.
+     */
+    scroller.scrollTop = 1000;
+    layoutTurns({ 'turn-3': 980 });
+    api.captureAnchor();
+
+    // The anchored Turn leaves the rendered window, and then another writer
+    // takes the viewport — the order that left a stale count behind.
+    layoutTurns({ 'turn-9': 980 });
+    api.openSettleWindow();
+    runFrame();
+    isOwnedElsewhere = true;
+
+    let ranFrames = 0;
+    while (frames.length > 0 && ranFrames < 200) {
+      runFrame();
+      ranFrames += 1;
+    }
+
+    expect(ranFrames).toBeLessThanOrEqual(ANCHOR_SETTLE_FRAMES);
+    expect(frames).toHaveLength(0);
+    // Given up on nothing: the reader is still owed a correction, and the
+    // carry that depends on this count still has to work when the owner lets
+    // go and the transcript moves again.
+    expect(scroller.scrollTop).toBe(1000);
+  });
+
+  it('does not count a frame it stood down on as a frame spent waiting', () => {
+    /*
+     * `waitedFrames` is read as painted frames the reader spent in the wrong
+     * place. Frames the anchor never looked on are not that, and counting them
+     * reported a 6609-frame wait for a reading position that was correct
+     * throughout.
+     */
+    scroller.scrollTop = 1000;
+    layoutTurns({ 'turn-3': 980 });
+    api.captureAnchor();
+
+    layoutTurns({ 'turn-9': 980 });
+    api.openSettleWindow();
+    runFrame();
+
+    isOwnedElsewhere = true;
+    for (let index = 0; index < 5; index += 1) runFrame();
+
+    isOwnedElsewhere = false;
+    layoutTurns({ 'turn-3': 1100, 'turn-9': 980 });
+    runFrame();
+
+    const waits = mocks.traceViewport.mock.calls
+      .map(([probe]) => probe)
+      .filter(probe => probe.location === 'anchor.turnReturned');
+    expect(waits).toHaveLength(1);
+    expect(waits[0].data()).toMatchObject({ waitedFrames: 1 });
+  });
+
+  it('stops re-asserting after the component goes away', () => {
+    layoutTurns({ 'turn-3': 100 });
+    api.captureAnchor();
+    api.openSettleWindow();
+
+    unmount();
+
+    expect(cancelAnimationFrame).toHaveBeenCalled();
+  });
+});
diff --git a/src/web-ui/src/flow_chat/components/modern/useFlowChatViewportAnchor.ts b/src/web-ui/src/flow_chat/components/modern/useFlowChatViewportAnchor.ts
new file mode 100644
index 0000000000..3be60d3714
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/modern/useFlowChatViewportAnchor.ts
@@ -0,0 +1,735 @@
+/**
+ * The reading position, kept where the reader left it.
+ *
+ * A virtualizer places items in the scroll range before it knows how tall they
+ * are, so every late measurement rewrites the offset of everything below it.
+ * react-virtuoso's own correction for that is a scroll by the change in *total*
+ * list height, which assumes the change happened above the viewport, and it is
+ * gated on scroll direction and on no programmatic scroll being in flight.
+ * Measured on a 27-Turn session: one item measuring 38px -> 1003px produced a
+ * 965px scroll across a whole Turn, and a 1680px growth that really was above
+ * the viewport produced no correction at all — `scrollTop` held at 1133 while
+ * `scrollHeight` went 8393 -> 10073, sliding the transcript down by the full
+ * amount.
+ *
+ * So the correction cannot be delegated to whatever is doing the placing. This
+ * restores a relationship instead of a delta, which makes it idempotent: when
+ * the placement was right the correction is zero, and when it was wrong or
+ * never came, this is what makes it right.
+ *
+ * It is also why capture and restore are separate: the scheme this replaced
+ * captured once per prepend, in the commit that changed the item list, which is
+ * a frame before the heights it was meant to compensate reach the DOM.
+ * Measured corrections over three reproductions: +1, 0, 0.
+ *
+ * This hook talks to a scroller element and the DOM inside it, and to nothing
+ * else. It is deliberately independent of the virtualizer.
+ */
+
+import { useCallback, useEffect, useMemo, useRef, type RefObject } from 'react';
+import {
+  roundViewportPx,
+  traceViewport,
+  traceViewportRepeating,
+} from '@/infrastructure/diagnostics/flowChatViewportDiagnostics';
+import {
+  ANCHOR_CORRECTION_EPSILON_PX,
+  ANCHOR_MISSING_TURN_ATTEMPTS,
+  ANCHOR_NOTABLE_CORRECTION_PX,
+  ANCHOR_SETTLE_FRAMES,
+  findRenderedTurnAnchorElement,
+  readTurnAnchorOffsetPx,
+  readViewportAnchorCandidates,
+  selectViewportAnchor,
+  shouldCaptureViewportAnchorOnScroll,
+  viewportAnchorCorrectionPx,
+  type ViewportAnchor,
+} from './flowChatViewportAnchor';
+
+export interface UseFlowChatViewportAnchorOptions {
+  scrollerRef: RefObject<HTMLElement | null>;
+  /**
+   * Someone is aiming the viewport at a target of their own, so the anchor must
+   * stay quiet.
+   *
+   * The anchor judges by geometry alone, which cannot tell a movement made on
+   * purpose from a displacement to undo — so it is told. The caller answers
+   * from the viewport register; this hook only needs the answer, which is what
+   * keeps it independent of everything that moves the viewport.
+   *
+   * Deliberately *not* true of the reader scrolling. A gesture chooses a
+   * position in the transcript; it does not stop the transcript from moving
+   * underneath them, and undoing that is all this hook does. The reader is also
+   * re-anchored on every scroll of theirs, so a correction during a gesture is
+   * zero unless something else really moved.
+   */
+  isViewportOwnedElsewhere: () => boolean;
+  /**
+   * Move the viewport *by* the correction. Supplied rather than performed here
+   * so that the repair is registered like every other one, without this hook
+   * having to know what else writes.
+   */
+  shiftViewport: (byPx: number) => void;
+}
+
+/**
+ * What an attempt to put the reading position back actually did.
+ *
+ * The settle window refreshes on evidence that the settle is still running, and
+ * only a frame that got as far as looking at the DOM has any. A boolean cannot
+ * carry that: `false` is a stand-down, a Turn not rendered yet, and no anchor at
+ * all, and the loop used to tell those apart by reading a counter that two of
+ * the three never touch. Measured: 27 seconds of `anchor.stoodDown`, one per
+ * frame, with the viewport parked and follow-output resting on it.
+ */
+type AnchorRestoreOutcome =
+  | 'corrected'
+  | 'in-place'
+  | 'awaiting-turn'
+  | 'stood-down'
+  | 'no-anchor';
+
+export interface FlowChatViewportAnchorApi {
+  /** Anchor to wherever the viewport is now, unconditionally. */
+  captureAnchor: () => void;
+  /**
+   * Somebody else moved the viewport to keep the reading position, and this
+   * much of where it now sits is not the reader.
+   *
+   * The anchor measures a correction against the viewport position its offset
+   * was agreed at, and treats every other change to `scrollTop` as somebody's
+   * deliberate movement rather than drift. A compensation is the one movement
+   * made *on the anchor's behalf*, so it has to be told, or the repair it was
+   * half of gets credited away and never finishes.
+   *
+   * This used to be a blanket "the viewport as of now is the baseline",
+   * re-taken every time a settle window opened. That also discarded whatever
+   * the reader had scrolled since the last capture — and a commit opens a
+   * window on almost every frame, so the discard was the common case, not the
+   * rare one.
+   */
+  absorbViewportShift: (byPx: number) => void;
+  /**
+   * The reader asked to be somewhere else, so the position they were at stops
+   * being the one to restore.
+   *
+   * A navigation is not a displacement. The anchor cannot tell the two apart by
+   * geometry — both are the viewport ending up somewhere it was not — and while
+   * a navigation holds the register the anchor merely stands down, which
+   * postpones the correction rather than cancelling it. Measured over four
+   * clicks on one Turn: the aim placed the viewport at 287px each time, and
+   * each time the anchor put it back 1653px away on the first frame after the
+   * hold lapsed, still anchored to the Turn the reader had jumped away from.
+   *
+   * So the old anchor is dropped here and a new one is taken from the placement
+   * once it has been rendered, in the settle window the commit opens. Between
+   * the two there is no anchor, which is the one state that cannot restore
+   * anything.
+   */
+  reanchorAfterNavigation: () => void;
+  /**
+   * Account for a scroll, by whichever of three answers fits it.
+   *
+   * A scroll event alone cannot say whether the user moved or the transcript
+   * moved under them, and the reading position has to survive either way:
+   *
+   * - **Captured**, when a recent intent event says the scroll was theirs. The
+   *   Turn they arrived at becomes the new reading position.
+   * - **Carried**, when it was not provably theirs and nobody else can account
+   *   for it. The anchored Turn is kept and only its expected offset moves, so
+   *   a repair that was still owed survives the scroll instead of being
+   *   forgotten at the displaced position. This covers both a Turn still
+   *   missing from the rendered window and a gesture whose scroll event was
+   *   delivered after the intent window closed.
+   * - **Left alone**, when a registered writer owns the viewport. That
+   *   movement is theirs and crediting it to the reader would drag the anchor
+   *   along with every follow and aim.
+   */
+  captureAnchorForScroll: () => void;
+  /** The user did something that scrolls, by their own hand. */
+  markUserScrollIntent: () => void;
+  /**
+   * Put the anchored Turn back where it was. False when there was no anchor to
+   * work from, which is the caller's signal to fall back on something coarser.
+   *
+   * Call where a correction can still beat the paint: a ResizeObserver
+   * callback, which the browser delivers after layout and before painting, or
+   * a layout effect.
+   */
+  restoreAnchor: () => boolean;
+  /**
+   * Correct now, and hold the anchor across the settle that follows.
+   *
+   * One callback per change is not enough, and no callback covers all of it, so
+   * every signal that the transcript moved opens a window and the anchor is
+   * re-asserted on each frame of it. A frame that had to correct refreshes the
+   * window, so a settle that runs long is followed to its end rather than
+   * abandoned partway.
+   *
+   * The first correction is synchronous because the caller is where the paint
+   * can still be beaten. It is not always *able* to correct there — at a
+   * history junction the anchored Turn is one frame away from being rendered —
+   * but where it is, the displacement and its repair are one paint instead of
+   * two.
+   */
+  openSettleWindow: () => void;
+}
+
+export function useFlowChatViewportAnchor({
+  scrollerRef,
+  isViewportOwnedElsewhere,
+  shiftViewport,
+}: UseFlowChatViewportAnchorOptions): FlowChatViewportAnchorApi {
+  const shiftViewportRef = useRef(shiftViewport);
+  shiftViewportRef.current = shiftViewport;
+  const anchorRef = useRef<ViewportAnchor | null>(null);
+  /** Consecutive attempts the anchored Turn has been missing from the window. */
+  const missingTurnAttemptsRef = useRef(0);
+  /**
+   * The viewport position the anchor's offset was last agreed against.
+   *
+   * Only read while the anchored Turn is missing. It is what lets the reader go
+   * on scrolling through a repair they are owed: a scroll they made is a change
+   * to `scrollTop`, and crediting it to the anchor keeps the rest — the part
+   * the transcript moved — outstanding.
+   */
+  const anchorScrollTopRef = useRef(0);
+  /*
+   * How long the anchored Turn has been out of the rendered window this time.
+   *
+   * The wait is the thing that decides whether a junction is seen. The
+   * synchronous correction in the commit is the one that costs nothing — it
+   * shares the paint with the displacement — and at a history junction it has
+   * never once been able to run, because the virtualizer windows from a scroll
+   * offset it only learns from scroll events and so renders the position the
+   * reader has just been moved off. Every correction therefore falls to the
+   * settle loop, and whether the reader sees it is a race: measured over five
+   * junctions, four corrections shared the prepend's frame and one landed 27ms
+   * into the next, visible as a 93px jump.
+   *
+   * `attempts` alone cannot answer how long the wait is. It counts restore
+   * calls, its trace is coalesced so only the first is ever emitted, and it
+   * says nothing about frames or milliseconds. These say what the wait cost, at
+   * the one moment it is known: when it ends.
+   */
+  const missingSinceMsRef = useRef<number | null>(null);
+  /** Settle frames that have run while the anchored Turn was missing. */
+  const missingFramesRef = useRef(0);
+  /** Reader travel credited to the anchor while it waited. */
+  const carriedDuringWaitPxRef = useRef(0);
+  /** The rAF timestamp of the frame a settle correction is running in, if any. */
+  const correctionFrameStartMsRef = useRef<number | null>(null);
+  /** When the user last did something that scrolls, by their own hand. */
+  const lastUserScrollIntentAtRef = useRef(0);
+  /** Frames left in which the anchor is still being re-asserted. */
+  const settleFramesRef = useRef(0);
+  /**
+   * The next settle window takes a reading position instead of restoring one.
+   *
+   * Set by a navigation, consumed by the commit that renders where it landed.
+   * Nothing else can say when the placement is on screen: the target is
+   * commonly outside the rendered window when the aim is issued, so reading the
+   * DOM in that same task anchors to whatever the reader was moved off.
+   */
+  const recaptureOnNextSettleRef = useRef(false);
+  const settleFrameRef = useRef<number | null>(null);
+  /*
+   * The settle loop is installed once and outlives every render, so it cannot
+   * close over anything that changes identity between them.
+   */
+  const isViewportOwnedElsewhereRef = useRef(isViewportOwnedElsewhere);
+  isViewportOwnedElsewhereRef.current = isViewportOwnedElsewhere;
+
+  /**
+   * Forget a wait, without reporting it. For the cases where the wait stopped
+   * being about anything rather than ending in an answer.
+   */
+  const endMissingTurnWait = useCallback(() => {
+    missingTurnAttemptsRef.current = 0;
+    missingSinceMsRef.current = null;
+    missingFramesRef.current = 0;
+    carriedDuringWaitPxRef.current = 0;
+  }, []);
+
+  /**
+   * What a wait for the anchored Turn cost, reported where it is known.
+   *
+   * Once per wait, at its end, because that is the only moment the whole of it
+   * exists. `outcome` separates the Turn coming back from the anchor being
+   * given up on: both end the wait, and only one of them can still repair
+   * anything.
+   */
+  const reportMissingTurnWait = useCallback((
+    scroller: HTMLElement,
+    turnId: string,
+    outcome: 'returned' | 'given-up',
+  ) => {
+    const startedAtMs = missingSinceMsRef.current;
+    if (startedAtMs === null) return;
+    /*
+     * Read out here rather than inside the thunk. The wait ends on the next
+     * line, and a `data` callback is evaluated by the trace, not by this — so
+     * a thunk over the refs would report the state after the reset every time.
+     */
+    const waited = {
+      turnId,
+      outcome,
+      waitedForMs: Math.round(performance.now() - startedAtMs),
+      waitedFrames: missingFramesRef.current,
+      waitedAttempts: missingTurnAttemptsRef.current,
+      carriedPx: roundViewportPx(carriedDuringWaitPxRef.current),
+      scrollTopPx: roundViewportPx(scroller.scrollTop),
+      scrollRangePx: roundViewportPx(scroller.scrollHeight),
+    };
+    endMissingTurnWait();
+    traceViewport({
+      location: outcome === 'returned' ? 'anchor.turnReturned' : 'anchor.waitAbandoned',
+      message: outcome === 'returned'
+        ? 'the anchored Turn came back into the rendered window'
+        : 'the anchored Turn never came back',
+      data: () => waited,
+    });
+  }, [endMissingTurnWait]);
+
+  /**
+   * Where the reading position is taken from, and when.
+   *
+   * Traced because capture is the half of this hook that decides what every
+   * correction afterwards will restore *to*, and it is otherwise invisible: a
+   * correction that returns the reader to a position the transcript held for
+   * one frame mid-settle looks exactly like a correction that worked. The
+   * source matters as much as the value — a scroll event carries no proof of
+   * whose scroll it was, and this hook's own writes produce them too.
+   */
+  const captureAnchorAt = useCallback((source: 'explicit' | 'scroll' | 'navigation') => {
+    const scroller = scrollerRef.current;
+    if (!scroller) return;
+    const previous = anchorRef.current;
+    const next = selectViewportAnchor(
+      readViewportAnchorCandidates(scroller),
+      scroller.clientHeight,
+    );
+    anchorRef.current = next;
+    anchorScrollTopRef.current = scroller.scrollTop;
+    // A new reading position is not the old one arriving, so whatever the old
+    // one was waiting for stops being a fact about anything.
+    endMissingTurnWait();
+    traceViewportRepeating(`anchor|captured|${source}|${next?.turnId ?? 'none'}`, {
+      location: 'anchor.captured',
+      message: 'reading position taken',
+      data: () => ({
+        source,
+        turnId: next?.turnId ?? null,
+        offsetFromScrollerTopPx: next === null ? null : roundViewportPx(next.offsetFromScrollerTop),
+        replacedTurnId: previous?.turnId ?? null,
+        replacedOffsetPx: previous === null
+          ? null
+          : roundViewportPx(previous.offsetFromScrollerTop),
+        scrollTopPx: roundViewportPx(scroller.scrollTop),
+        // Read against the offset: an anchor is only a proxy for what the
+        // reader sees while it is on screen, and the offset alone cannot say
+        // whether it is.
+        viewportHeightPx: roundViewportPx(scroller.clientHeight),
+      }),
+    });
+  }, [endMissingTurnWait, scrollerRef]);
+
+  const captureAnchor = useCallback(() => {
+    captureAnchorAt('explicit');
+  }, [captureAnchorAt]);
+
+  const absorbViewportShift = useCallback((byPx: number) => {
+    anchorScrollTopRef.current += byPx;
+  }, []);
+
+  const reanchorAfterNavigation = useCallback(() => {
+    const previous = anchorRef.current;
+    anchorRef.current = null;
+    endMissingTurnWait();
+    recaptureOnNextSettleRef.current = true;
+    traceViewport({
+      location: 'anchor.releasedForNavigation',
+      message: 'the reader asked to be somewhere else, so the old reading position was dropped',
+      data: () => ({
+        replacedTurnId: previous?.turnId ?? null,
+        replacedOffsetPx: previous === null
+          ? null
+          : roundViewportPx(previous.offsetFromScrollerTop),
+        scrollTopPx: roundViewportPx(scrollerRef.current?.scrollTop ?? 0),
+      }),
+    });
+  }, [endMissingTurnWait, scrollerRef]);
+
+  const markUserScrollIntent = useCallback(() => {
+    lastUserScrollIntentAtRef.current = performance.now();
+  }, []);
+
+  /**
+   * Carry the anchor through a scroll instead of replacing it.
+   *
+   * Take a movement of the viewport into the anchor instead of measuring
+   * against it.
+   *
+   * The offset and the viewport position it was agreed at are two halves of one
+   * fact, and this is the only thing that advances both. A change to
+   * `scrollTop` is somebody moving the viewport — the reader, most of the time
+   * — and never a displacement, because a displacement moves the transcript
+   * underneath a `scrollTop` that stays put. So it is subtracted from where the
+   * Turn is expected to be, and whatever remains is the drift to repair.
+   *
+   * Two callers, one rule:
+   *
+   * - **`awaiting-turn`** — a scroll while the anchored Turn is missing from
+   *   the rendered window, where a correction is owed and cannot yet be
+   *   measured. Re-reading the anchor from the DOM there accepts the reader's
+   *   movement *and* the transcript's as one, and files the displacement away
+   *   as the reader's own choice. Measured at three junctions in one session:
+   *   the anchor was owed 104px, then 140px, then an amount never established,
+   *   and at each of them a scroll 77ms later replaced it with a Turn at its
+   *   displaced position. Two of the three were never corrected at all.
+   * - **`viewport-moved`** — every restore, before anything is measured. The
+   *   settle loop reads the DOM directly and a commit opens a window on almost
+   *   every frame, so a correction routinely runs before the scroll event
+   *   carrying the reader's travel has been delivered.
+   */
+  const carryAnchorThroughScroll = useCallback((
+    scroller: HTMLElement,
+    reason: 'awaiting-turn' | 'unclaimed-scroll' | 'viewport-moved',
+  ) => {
+    const anchor = anchorRef.current;
+    if (!anchor) return;
+    const travelledPx = scroller.scrollTop - anchorScrollTopRef.current;
+    anchorScrollTopRef.current = scroller.scrollTop;
+    if (travelledPx === 0) return;
+    if (missingSinceMsRef.current !== null) carriedDuringWaitPxRef.current += travelledPx;
+    anchorRef.current = {
+      ...anchor,
+      offsetFromScrollerTop: anchor.offsetFromScrollerTop - travelledPx,
+    };
+    traceViewportRepeating(`anchor|carried|${reason}|${anchor.turnId}`, {
+      location: 'anchor.carried',
+      message: 'the reader scrolled and the anchor went with them',
+      travelPx: travelledPx,
+      data: () => ({
+        reason,
+        turnId: anchor.turnId,
+        travelledPx: roundViewportPx(travelledPx),
+        expectedOffsetPx: roundViewportPx(anchor.offsetFromScrollerTop - travelledPx),
+        missingAttempts: missingTurnAttemptsRef.current,
+        scrollTopPx: roundViewportPx(scroller.scrollTop),
+      }),
+    });
+  }, []);
+
+  const captureAnchorForScroll = useCallback(() => {
+    const scroller = scrollerRef.current;
+    if (!scroller) return;
+    if (missingTurnAttemptsRef.current > 0) {
+      carryAnchorThroughScroll(scroller, 'awaiting-turn');
+      return;
+    }
+    const msSinceUserScrollIntent = performance.now() - lastUserScrollIntentAtRef.current;
+    if (shouldCaptureViewportAnchorOnScroll(anchorRef.current !== null, msSinceUserScrollIntent)) {
+      captureAnchorAt('scroll');
+      return;
+    }
+    /*
+     * Not provably the reader's — and still theirs, if nobody else can account
+     * for it.
+     *
+     * The window is measured from the *input* event, and the scrolling it
+     * authorises outlives it: a wheel notch smooth-scrolls for longer than the
+     * window, and under a busy main thread the scroll event carrying the whole
+     * travel is delivered after it has closed. Ignoring the event then leaves
+     * the reader's own movement credited to nobody, and the next settle undoes
+     * it in full. Measured over 181 seconds: fourteen gestures, one capture, and
+     * seven corrections of 308px to 618px that each returned the viewport to
+     * exactly where the gesture had started.
+     *
+     * Carrying is what "credited to nobody" was missing, and it is safe where a
+     * capture is not: it keeps the anchored Turn and only moves its expected
+     * offset, so a repair that was still owed survives instead of being
+     * forgotten at the displaced position.
+     *
+     * Owned elsewhere is the case this must not touch. A registered writer
+     * moving the viewport is the one other thing that changes `scrollTop`
+     * without the reader, and crediting *that* to them would carry the anchor
+     * along with every follow and aim.
+     */
+    if (!isViewportOwnedElsewhereRef.current()) {
+      carryAnchorThroughScroll(scroller, 'unclaimed-scroll');
+      return;
+    }
+    traceViewportRepeating('anchor|scroll-left-alone', {
+      location: 'anchor.scrollLeftAlone',
+      message: 'a scroll was neither the reader\'s nor ours to credit',
+      data: () => ({
+        turnId: anchorRef.current?.turnId ?? null,
+        msSinceUserScrollIntent: Math.round(msSinceUserScrollIntent),
+        scrollTopPx: roundViewportPx(scroller.scrollTop),
+      }),
+    });
+  }, [captureAnchorAt, carryAnchorThroughScroll, scrollerRef]);
+
+  const attemptRestore = useCallback((): AnchorRestoreOutcome => {
+    const scroller = scrollerRef.current;
+    const anchor = anchorRef.current;
+    if (!scroller || !anchor) return 'no-anchor';
+    /*
+     * Every way this declines is silent and looks like the transcript simply
+     * not moving, which is why each of them is traced. Standing down for
+     * another owner is the intended case; the other two are how a reading
+     * position gets lost, and they have both happened.
+     */
+    if (isViewportOwnedElsewhereRef.current()) {
+      traceViewportRepeating('anchor|owned-elsewhere', {
+        location: 'anchor.stoodDown',
+        message: 'anchor stood down for another owner',
+        data: () => ({ turnId: anchor.turnId, scrollTopPx: roundViewportPx(scroller.scrollTop) }),
+      });
+      return 'stood-down';
+    }
+    const element = findRenderedTurnAnchorElement(scroller, anchor.turnId);
+    /*
+     * The anchored Turn can be absent from the rendered window, and one frame
+     * of absence is not the same fact as the reader having left it behind.
+     *
+     * The single frame is the common case: the virtualizer chooses its window
+     * from a scroll offset it only learns from scroll events, so the commit
+     * that prepends history is still windowing the position the reader has just
+     * been moved off, and their Turn arrives a frame later. Dropping there threw
+     * away the only record of where they were reading, one frame before it
+     * could have been used — measured at four junctions in a row, every one a
+     * drop and not one correction.
+     */
+    if (!element) {
+      if (missingSinceMsRef.current === null) missingSinceMsRef.current = performance.now();
+      missingTurnAttemptsRef.current += 1;
+      const givingUp = missingTurnAttemptsRef.current >= ANCHOR_MISSING_TURN_ATTEMPTS;
+      traceViewportRepeating(`anchor|turn-not-rendered|${givingUp}`, {
+        location: givingUp ? 'anchor.dropped' : 'anchor.turnNotRendered',
+        message: givingUp
+          ? 'anchored Turn stayed out of the rendered window, so the anchor was given up'
+          : 'anchored Turn is not in the rendered window yet',
+        data: () => ({
+          turnId: anchor.turnId,
+          attempts: missingTurnAttemptsRef.current,
+          scrollTopPx: roundViewportPx(scroller.scrollTop),
+          scrollRangePx: roundViewportPx(scroller.scrollHeight),
+        }),
+      });
+      if (givingUp) {
+        reportMissingTurnWait(scroller, anchor.turnId, 'given-up');
+        anchorRef.current = null;
+        return 'no-anchor';
+      }
+      return 'awaiting-turn';
+    }
+    // The wait is reported before the correction it made possible, so the two
+    // read as cause and effect in the order they are written down.
+    reportMissingTurnWait(scroller, anchor.turnId, 'returned');
+    /*
+     * Whatever moved the viewport since the offset was agreed is taken into the
+     * anchor before anything is measured against it, and it is never a
+     * displacement — a displacement moves the transcript under a `scrollTop`
+     * that stays put. Almost always it is the reader, whose scroll event has
+     * simply not been delivered yet: the settle loop reads the DOM directly and
+     * a commit can open a window before the event arrives, so a correction gets
+     * there first and undoes them.
+     *
+     * Taken in *here* rather than subtracted in the correction, because the
+     * offset and the position it was agreed at are two halves of one fact and
+     * every writer has to move both. Subtracting it left the two branches below
+     * advancing only the position, and a frame with nothing to correct then
+     * banked the reader's travel as a debt the next frame collected. Measured:
+     * a 32px scroll and an 81px scroll, each reported back as a correction of
+     * exactly itself with `scrolledSincePx: 0`.
+     */
+    const scrolledSincePx = scroller.scrollTop - anchorScrollTopRef.current;
+    carryAnchorThroughScroll(scroller, 'viewport-moved');
+    const rebased = anchorRef.current ?? anchor;
+    const correction = viewportAnchorCorrectionPx(
+      rebased,
+      readTurnAnchorOffsetPx(scroller, element),
+    );
+    /*
+     * Already where it belongs, which still counts as answered — and is now the
+     * common outcome rather than a rarity, since a frame in which only the
+     * reader moved lands here exactly. Traced for that reason: it is reached
+     * every frame of every settle, and it is where a reading position that has
+     * quietly stopped meaning anything would sit unnoticed.
+     */
+    if (Math.abs(correction) < ANCHOR_CORRECTION_EPSILON_PX) {
+      traceViewportRepeating(`anchor|in-place|${rebased.turnId}`, {
+        location: 'anchor.inPlace',
+        message: 'the reading position is where it belongs',
+        data: () => ({
+          turnId: rebased.turnId,
+          anchoredOffsetPx: roundViewportPx(rebased.offsetFromScrollerTop),
+          scrolledSincePx: roundViewportPx(scrolledSincePx),
+          scrollTopPx: roundViewportPx(scroller.scrollTop),
+        }),
+      });
+      return 'in-place';
+    }
+    /*
+     * Keyed by which anchor and by whether the reader can feel it, because a
+     * coalesced run collapses to its first sample and the rest becomes a sum.
+     * Under one key, two rounds of diagnosis in a row read `correctionPx: 0.7`
+     * against 458.7px of suppressed travel spanning three different anchors —
+     * every correction that mattered was inside the summary, attributable to
+     * nothing.
+     */
+    const felt = Math.abs(correction) >= ANCHOR_NOTABLE_CORRECTION_PX;
+    traceViewportRepeating(`anchor|correcting|${felt ? 'felt' : 'rounding'}|${rebased.turnId}`, {
+      location: 'anchor.correct',
+      message: 'anchor put the reading position back',
+      travelPx: correction,
+      data: () => ({
+        turnId: rebased.turnId,
+        correctionPx: roundViewportPx(correction),
+        /*
+         * Where the anchored Turn is being held, against how much of the
+         * scroller there is to hold it in. A correction restores a marker the
+         * reader cannot see if this falls outside the viewport, and then it is
+         * reporting movement that never reached the screen.
+         */
+        anchoredOffsetPx: roundViewportPx(rebased.offsetFromScrollerTop),
+        viewportHeightPx: roundViewportPx(scroller.clientHeight),
+        /*
+         * The part of the drift that was somebody moving the viewport rather
+         * than the transcript moving. Read against `correctionPx`: what is
+         * left over is the displacement, and the two being equal and opposite
+         * is a correction that would have undone a scroll.
+         */
+        scrolledSincePx: roundViewportPx(scrolledSincePx),
+        frameStartMs: correctionFrameStartMsRef.current === null
+          ? null
+          : Math.round(correctionFrameStartMsRef.current),
+        scrollTopPx: roundViewportPx(scroller.scrollTop),
+        /*
+         * The scroll range, so a correction can be told apart from the reason
+         * for it. A large correction means either that whoever moved the
+         * viewport last over-shot, or that the transcript above the reader
+         * measured smaller than it had reserved — and those differ by whether
+         * the range changed since the change that opened this settle. Without
+         * it, a 412px correction and a 412px mistake read the same.
+         */
+        scrollRangePx: roundViewportPx(scroller.scrollHeight),
+      }),
+    });
+    shiftViewportRef.current(correction);
+    /*
+     * The shift put the Turn back at the stored offset, so advancing only the
+     * position keeps the two halves agreeing. This is the one movement of
+     * `scrollTop` that must not be taken into the offset — it is the repair.
+     */
+    anchorScrollTopRef.current = scroller.scrollTop;
+    return 'corrected';
+  }, [carryAnchorThroughScroll, reportMissingTurnWait, scrollerRef]);
+
+  const attemptRestoreRef = useRef(attemptRestore);
+  attemptRestoreRef.current = attemptRestore;
+
+  /*
+   * The public answer is "did this leave the reading position where it belongs",
+   * which the outcome refines rather than replaces. Callers outside the settle
+   * loop only ever needed the two.
+   */
+  const restoreAnchor = useCallback((): boolean => {
+    const outcome = attemptRestoreRef.current();
+    return outcome === 'corrected' || outcome === 'in-place';
+  }, []);
+
+  const openSettleWindow = useCallback(() => {
+    settleFramesRef.current = ANCHOR_SETTLE_FRAMES;
+    if (recaptureOnNextSettleRef.current) {
+      /*
+       * The first commit after a navigation, which is where the placement is
+       * finally on screen. Taking the reading position here rather than
+       * restoring one is the whole difference between a jump that holds and a
+       * jump that is undone the moment the register lets go.
+       */
+      recaptureOnNextSettleRef.current = false;
+      captureAnchorAt('navigation');
+    } else {
+      // In the caller's own frame, so the displacement and its correction are
+      // one paint rather than two. Callers are a layout effect or a
+      // ResizeObserver callback; both still run before the browser paints.
+      attemptRestoreRef.current();
+    }
+    if (settleFrameRef.current !== null) return;
+    const step = (frameStartMs: number) => {
+      settleFrameRef.current = null;
+      settleFramesRef.current -= 1;
+      /*
+       * The frame this correction belongs to, which is the only way to tell a
+       * repair the reader never saw from one they watched happen. A correction
+       * whose frame started before the displacement's own frame was painted is
+       * invisible; one a frame or more later is the flicker.
+       */
+      correctionFrameStartMsRef.current = frameStartMs;
+      /*
+       * A frame that made a correction refreshes the window, and so does one
+       * still waiting for the anchored Turn to be rendered. "Not there yet" is
+       * neither a repair nor a failure, and spending a frame on it makes the
+       * settle outlast the wait only for as long as `ANCHOR_SETTLE_FRAMES` and
+       * `ANCHOR_MISSING_TURN_ATTEMPTS` happen to be the same number. They are
+       * independent constants describing different things; this says what was
+       * meant instead of relying on them coinciding. An in-place frame is
+       * already settled and must consume the remaining budget, otherwise an
+       * anchor that never moves keeps this RAF loop alive forever.
+       */
+      const outcome = attemptRestoreRef.current();
+      // Counted here rather than beside `attempts`, because it is frames the
+      // wait is measured in: a Turn that arrives in the next frame costs the
+      // reader nothing, and one that takes five is five painted frames of
+      // being in the wrong place. A frame that stood down is none of those —
+      // it never looked, and counting it reported a 28-second wait for a
+      // reading position that was correct the whole time.
+      if (outcome === 'awaiting-turn') missingFramesRef.current += 1;
+      /*
+       * Only a frame that looked can say the settle is still running. A
+       * stand-down looked at nothing — the owner it deferred to is placing the
+       * viewport, and while that owner rests on it, as follow-output does at
+       * the tail, nothing here will ever change. Refreshing on it kept the loop
+       * alive off a missing-Turn count left by the last frame that *did* look,
+       * and that count can only advance on a frame that does not stand down:
+       * the one condition jammed the loop and made its only exit unreachable.
+       */
+      if (outcome === 'corrected' || outcome === 'awaiting-turn') {
+        settleFramesRef.current = ANCHOR_SETTLE_FRAMES;
+      }
+      correctionFrameStartMsRef.current = null;
+      if (settleFramesRef.current > 0) {
+        settleFrameRef.current = requestAnimationFrame(step);
+      }
+    };
+    settleFrameRef.current = requestAnimationFrame(step);
+  }, [captureAnchorAt]);
+
+  useEffect(() => () => {
+    if (settleFrameRef.current !== null) {
+      cancelAnimationFrame(settleFrameRef.current);
+      settleFrameRef.current = null;
+    }
+  }, []);
+
+  return useMemo(() => ({
+    captureAnchor,
+    absorbViewportShift,
+    reanchorAfterNavigation,
+    captureAnchorForScroll,
+    markUserScrollIntent,
+    restoreAnchor,
+    openSettleWindow,
+  }), [
+    absorbViewportShift,
+    captureAnchor,
+    captureAnchorForScroll,
+    markUserScrollIntent,
+    openSettleWindow,
+    reanchorAfterNavigation,
+    restoreAnchor,
+  ]);
+}
diff --git a/src/web-ui/src/flow_chat/components/modern/useFlowChatViewportOwner.ts b/src/web-ui/src/flow_chat/components/modern/useFlowChatViewportOwner.ts
new file mode 100644
index 0000000000..9b4d01a6ec
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/modern/useFlowChatViewportOwner.ts
@@ -0,0 +1,212 @@
+/**
+ * The register, wired to a live scroller.
+ *
+ * `flowChatViewportOwnership.ts` decides who may write; this holds the current
+ * claim and performs the write. The two are one call on purpose: taking
+ * ownership and moving the viewport being the same action is what keeps a new
+ * writer from being added without the rest of FlowChat knowing about it.
+ *
+ * Everything here is refs. A claim changes many times per frame — the follow
+ * loop renews on every one — and none of it belongs in a render.
+ */
+
+import { useCallback, useMemo, useRef, type RefObject } from 'react';
+import {
+  isViewportDiagnosticsEnabled,
+  roundViewportPx,
+  traceViewportRepeating,
+} from '@/infrastructure/diagnostics/flowChatViewportDiagnostics';
+import {
+  activeViewportClaim,
+  canShiftViewport,
+  claimViewport,
+  releaseViewport,
+  type FlowChatViewportOwner,
+  type ViewportClaim,
+} from './flowChatViewportOwnership';
+import { getMotionAwareScrollBehavior } from '../../utils/motionPreference';
+
+export interface ViewportWriteRequest {
+  owner: FlowChatViewportOwner;
+  /** Offset in scroller coordinates. */
+  topPx: number;
+  behavior?: ScrollBehavior;
+  /**
+   * How long ownership stands after this write.
+   *
+   * Omitted holds it for the frame the write happens in, which is what a
+   * correction wants. An animated write has to outlast its own animation, or
+   * the first frame of travel is read as a displacement by whatever corrects
+ * next — see the follow and viewport rules in `FLOWCHAT_SCROLL_STABILITY.md`.
+   */
+  holdForMs?: number;
+}
+
+export interface FlowChatViewportOwnerApi {
+  /**
+   * Take the viewport without writing it yet, for a writer whose movement is
+   * issued by something else — a virtualizer aiming at an item, or a browser
+   * animation. Returns whether the claim was granted.
+   */
+  claim: (owner: FlowChatViewportOwner, options?: { holdForMs?: number }) => boolean;
+  /** Give it back. A writer that was preempted cannot release the new owner. */
+  release: (owner: FlowChatViewportOwner) => void;
+  /** Whether a displacement repair may act — see `canShiftViewport`. */
+  canShift: () => boolean;
+  /** The owner holding the viewport, for diagnostics. Null when it is free. */
+  currentOwner: () => FlowChatViewportOwner | null;
+  /**
+   * Move the viewport, if the register allows it. False means the write did
+   * not happen — the caller has been outranked and must not fall back to
+   * writing the scroller itself.
+   */
+  write: (request: ViewportWriteRequest) => boolean;
+  /**
+   * Move the viewport *by* an amount, because what it is showing moved by that
+   * amount. Takes no ownership: a displacement has no opinion about where the
+   * viewport belongs, so there is nothing for it to hold against anyone.
+   *
+   * Refused only by an owner that holds a target — see `canShiftViewport`. A
+   * gesture is not one, and must not be: the reader chose a position in the
+   * transcript, and this is what keeps that position meaning the same thing.
+   */
+  shift: (byPx: number) => boolean;
+}
+
+export function useFlowChatViewportOwner(
+  scrollerRef: RefObject<HTMLElement | null>,
+): FlowChatViewportOwnerApi {
+  const claimRef = useRef<ViewportClaim | null>(null);
+
+  /**
+   * Take the viewport and report who was holding it, which the register drops
+   * once the outcome is known. Both public entry points go through this so a
+   * write is one line in the log rather than a claim and a write.
+   */
+  const takeViewport = useCallback((
+    owner: FlowChatViewportOwner,
+    holdForMs: number | undefined,
+  ): { granted: boolean; heldBy: FlowChatViewportOwner | null } => {
+    const nowMs = performance.now();
+    // Read before the claim resolves: on a refusal this is who refused, and on
+    // a grant it is who was preempted, which is the same question either way.
+    const heldBy = activeViewportClaim(claimRef.current, nowMs)?.owner ?? null;
+    const outcome = claimViewport(claimRef.current, { owner, nowMs, holdForMs });
+    claimRef.current = outcome.claim;
+    return { granted: outcome.granted, heldBy };
+  }, []);
+
+  const claim = useCallback((
+    owner: FlowChatViewportOwner,
+    options?: { holdForMs?: number },
+  ): boolean => {
+    const { granted, heldBy } = takeViewport(owner, options?.holdForMs);
+    if (isViewportDiagnosticsEnabled()) {
+      traceViewportRepeating(`claim|${owner}|${granted}|${heldBy}`, {
+        location: 'viewportOwner.claim',
+        message: granted ? 'took the viewport' : 'refused the viewport',
+        data: () => ({ owner, granted, heldBy, holdForMs: options?.holdForMs ?? null }),
+      });
+    }
+    return granted;
+  }, [takeViewport]);
+
+  const release = useCallback((owner: FlowChatViewportOwner) => {
+    const heldBy = claimRef.current?.owner ?? null;
+    claimRef.current = releaseViewport(claimRef.current, owner);
+    if (isViewportDiagnosticsEnabled() && heldBy !== null) {
+      traceViewportRepeating(`release|${owner}|${heldBy}`, {
+        location: 'viewportOwner.release',
+        message: heldBy === owner
+          ? 'gave the viewport back'
+          : 'released nothing, having already been preempted',
+        data: () => ({ owner, heldBy }),
+      });
+    }
+  }, []);
+
+  const canShift = useCallback(() => (
+    canShiftViewport(claimRef.current, performance.now())
+  ), []);
+
+  const currentOwner = useCallback(() => {
+    const nowMs = performance.now();
+    const held = claimRef.current;
+    return held && nowMs < held.expiresAtMs ? held.owner : null;
+  }, []);
+
+  const write = useCallback((request: ViewportWriteRequest): boolean => {
+    const scroller = scrollerRef.current;
+    if (!scroller) return false;
+    const { granted, heldBy } = takeViewport(request.owner, request.holdForMs);
+    /*
+     * The one place that sees every deliberate movement, and the only place a
+     * refusal is visible at all — a writer that was outranked leaves no trace
+     * anywhere else, and "nothing moved" is the more common complaint.
+     */
+    const behavior = getMotionAwareScrollBehavior(
+      request.behavior === 'smooth' ? 'smooth' : 'auto',
+    );
+    if (isViewportDiagnosticsEnabled()) {
+      const fromPx = scroller.scrollTop;
+      traceViewportRepeating(`write|${request.owner}|${granted}|${heldBy}`, {
+        location: 'viewportOwner.write',
+        message: granted ? 'moved the viewport' : 'was refused the viewport',
+        travelPx: request.topPx - fromPx,
+        data: () => ({
+          owner: request.owner,
+          granted,
+          heldBy,
+          fromPx: roundViewportPx(fromPx),
+          toPx: roundViewportPx(request.topPx),
+          behavior,
+          holdForMs: request.holdForMs ?? null,
+        }),
+      });
+    }
+    if (!granted) return false;
+    if (behavior === 'smooth') {
+      scroller.scrollTo({ top: request.topPx, behavior });
+    } else {
+      // Assigned rather than `scrollTo({behavior:'auto'})`: an assignment also
+      // cancels any animation still running, which is what a writer taking the
+      // viewport from an animated one means to do.
+      scroller.scrollTop = request.topPx;
+    }
+    return true;
+  }, [scrollerRef, takeViewport]);
+
+  const shift = useCallback((byPx: number): boolean => {
+    const scroller = scrollerRef.current;
+    if (!scroller) return false;
+    const allowed = canShift();
+    if (isViewportDiagnosticsEnabled()) {
+      const fromPx = scroller.scrollTop;
+      traceViewportRepeating(`shift|${allowed}|${currentOwner()}`, {
+        location: 'viewportOwner.shift',
+        message: allowed
+          ? 'moved the viewport by what moved under it'
+          : 'left the displacement to whoever holds a target',
+        travelPx: byPx,
+        data: () => ({
+          allowed,
+          heldBy: currentOwner(),
+          fromPx: roundViewportPx(fromPx),
+          byPx: roundViewportPx(byPx),
+        }),
+      });
+    }
+    if (!allowed) return false;
+    scroller.scrollTop += byPx;
+    return true;
+  }, [canShift, currentOwner, scrollerRef]);
+
+  return useMemo(() => ({
+    claim,
+    release,
+    canShift,
+    currentOwner,
+    write,
+    shift,
+  }), [canShift, claim, currentOwner, release, shift, write]);
+}
diff --git a/src/web-ui/src/flow_chat/components/modern/useFlowChatVirtualizer.aim.test.tsx b/src/web-ui/src/flow_chat/components/modern/useFlowChatVirtualizer.aim.test.tsx
new file mode 100644
index 0000000000..29d8cc6aea
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/modern/useFlowChatVirtualizer.aim.test.tsx
@@ -0,0 +1,212 @@
+// @vitest-environment jsdom
+
+/**
+ * The re-aim, and giving it up.
+ *
+ * An aim at an item is not one write. The library recomputes the target offset
+ * every frame from measurements that are still landing, and writes again
+ * whenever it moves — for up to five seconds. That is the whole reason to
+ * prefer `scrollItemIntoView` over an offset, and it is also the reason a
+ * reader who takes the viewport over can be pulled back to where they were
+ * going seconds after they stopped going there.
+ *
+ * The first test here exists to prove the mechanism runs at all, because the
+ * second one is only meaningful if it does: "no second write" is what a
+ * re-aim that never armed looks like too.
+ */
+
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { useFlowChatVirtualizer, type FlowChatVirtualizer } from './useFlowChatVirtualizer';
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+/** What the reservation says a row is before anything has measured. */
+const ESTIMATE_PX = 100;
+/** What the rows turn out to be — over by more than a factor of two. */
+const REAL_PX = 40;
+const TARGET_INDEX = 5;
+
+interface Item {
+  key: string;
+}
+
+interface HarnessProps {
+  scroller: HTMLElement;
+  header: HTMLElement;
+  items: Item[];
+  writeViewport: (request: { topPx: number }) => boolean;
+  onApi: (api: FlowChatVirtualizer) => void;
+}
+
+function Harness({ scroller, header, items, writeViewport, onApi }: HarnessProps) {
+  const scrollerRef = React.useRef<HTMLElement | null>(scroller);
+  const headerRef = React.useRef<HTMLElement | null>(header);
+  onApi(useFlowChatVirtualizer({
+    items,
+    scrollerRef,
+    headerRef,
+    getItemKey: (item: Item) => item.key,
+    estimateItemHeightPx: () => ESTIMATE_PX,
+    scrollPaddingStartPx: 0,
+    writeViewport,
+  }));
+  return null;
+}
+
+describe('useFlowChatVirtualizer aim', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+  let scroller: HTMLDivElement;
+  let header: HTMLDivElement;
+  let api: FlowChatVirtualizer;
+  let writes: number[];
+  let frames: FrameRequestCallback[];
+
+  /**
+   * A row at a height jsdom would otherwise report as zero. `offsetHeight`
+   * rather than a rect, because that is what the library's measurement reads.
+   */
+  function renderRow(index: number, heightPx: number) {
+    const element = document.createElement('div');
+    element.setAttribute('data-virtual-index', String(index));
+    Object.defineProperty(element, 'offsetHeight', { configurable: true, value: heightPx });
+    scroller.appendChild(element);
+  }
+
+  /**
+   * Shrink everything above the target, which is what moves the target's own
+   * offset: 5 rows reserved at 100px turn out to be 40px, so an aim placed at
+   * 500 belongs at 200.
+   */
+  function measureRowsAboveTarget() {
+    act(() => {
+      for (let index = 0; index < TARGET_INDEX; index += 1) renderRow(index, REAL_PX);
+      api.measureRenderedItems();
+    });
+  }
+
+  function runFrames(count: number) {
+    for (let index = 0; index < count; index += 1) {
+      const frame = frames.shift();
+      if (!frame) return;
+      act(() => frame(16));
+    }
+  }
+
+  beforeEach(() => {
+    vi.stubGlobal('ResizeObserver', class {
+      observe() {}
+      unobserve() {}
+      disconnect() {}
+    });
+    frames = [];
+    vi.stubGlobal('requestAnimationFrame', vi.fn((callback: FrameRequestCallback) => {
+      frames.push(callback);
+      return frames.length;
+    }));
+    vi.stubGlobal('cancelAnimationFrame', vi.fn());
+
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+    scroller = document.createElement('div');
+    header = document.createElement('div');
+    container.appendChild(scroller);
+    // Without a scroll range the library clamps every aim to 0, which would
+    // make all of these pass for the wrong reason.
+    Object.defineProperty(scroller, 'scrollHeight', { configurable: true, value: 10_000 });
+    Object.defineProperty(scroller, 'clientHeight', { configurable: true, value: 500 });
+    Object.defineProperty(scroller, 'scrollTop', { configurable: true, writable: true, value: 0 });
+
+    writes = [];
+    const writeViewport = ({ topPx }: { topPx: number }) => {
+      writes.push(topPx);
+      // The register's granted write, and the scroll event it produces — which
+      // is the only way the library learns where the viewport actually is.
+      scroller.scrollTop = topPx;
+      scroller.dispatchEvent(new Event('scroll'));
+      return true;
+    };
+
+    const items = Array.from({ length: 10 }, (_, index) => ({ key: `item-${index}` }));
+    act(() => root.render(
+      <Harness
+        scroller={scroller}
+        header={header}
+        items={items}
+        writeViewport={writeViewport}
+        onApi={next => { api = next; }}
+      />,
+    ));
+    // The library places the scroller against its own state on mount. That
+    // write belongs to no aim, and counting it would hide the ones that do.
+    writes = [];
+    frames = [];
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    vi.unstubAllGlobals();
+  });
+
+  it('re-aims at the item when a measurement moves it', () => {
+    act(() => api.scrollItemIntoView(TARGET_INDEX, {
+      align: 'start',
+      owner: 'one-shot-navigation',
+    }));
+    expect(writes).toEqual([TARGET_INDEX * ESTIMATE_PX]);
+
+    measureRowsAboveTarget();
+    runFrames(1);
+
+    // The aim followed its item down rather than staying at the offset it was
+    // first given. This is the behaviour worth keeping.
+    expect(writes).toEqual([TARGET_INDEX * ESTIMATE_PX, TARGET_INDEX * REAL_PX]);
+  });
+
+  it('stops re-aiming once the aim has been given up', () => {
+    /*
+     * Measured: a Turn navigation placed the viewport at 5358, the reader took
+     * over 6ms later, and 12ms after that the re-aim asked for 7784 and was
+     * refused. The refusal is not the fix — the library never learns of it, and
+     * the gesture's hold in the register lasts 200ms against a five-second
+     * re-aim, so the write after the hold lapses is granted.
+     */
+    act(() => api.scrollItemIntoView(TARGET_INDEX, {
+      align: 'start',
+      owner: 'one-shot-navigation',
+    }));
+    act(() => api.cancelAim());
+    // The cancel aims at the offset the scroller already holds, which is how it
+    // leaves the re-aim with no index to recompute from.
+    expect(writes).toEqual([TARGET_INDEX * ESTIMATE_PX, TARGET_INDEX * ESTIMATE_PX]);
+
+    measureRowsAboveTarget();
+    runFrames(5);
+
+    expect(writes).toEqual([TARGET_INDEX * ESTIMATE_PX, TARGET_INDEX * ESTIMATE_PX]);
+  });
+
+  it('does nothing when there is no aim to give up', () => {
+    // Called on every wheel notch, so this is the common case by a long way.
+    act(() => api.cancelAim());
+    act(() => api.cancelAim());
+
+    expect(writes).toEqual([]);
+  });
+
+  it('gives up an aim only once', () => {
+    act(() => api.scrollItemIntoView(TARGET_INDEX, {
+      align: 'start',
+      owner: 'one-shot-navigation',
+    }));
+    act(() => api.cancelAim());
+    act(() => api.cancelAim());
+    act(() => api.cancelAim());
+
+    expect(writes).toHaveLength(2);
+  });
+});
diff --git a/src/web-ui/src/flow_chat/components/modern/useFlowChatVirtualizer.measurement.test.tsx b/src/web-ui/src/flow_chat/components/modern/useFlowChatVirtualizer.measurement.test.tsx
new file mode 100644
index 0000000000..8bcfd76eb7
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/modern/useFlowChatVirtualizer.measurement.test.tsx
@@ -0,0 +1,160 @@
+// @vitest-environment jsdom
+
+/**
+ * Item positions, against the DOM rather than against the reservation.
+ *
+ * This is the one place FlowChat depends on how the library keeps its
+ * measurement cache, and the dependency is invisible from the outside: a
+ * position read too early is a plausible number, not an error. It is also the
+ * dependency most likely to move under a version bump — `getMeasurements` is
+ * `private` in the published types, and `resizeItem` is the only public way in.
+ */
+
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { useFlowChatVirtualizer, type FlowChatVirtualizer } from './useFlowChatVirtualizer';
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+/** What the estimate says before anything has been rendered. */
+const ESTIMATE_PX = 100;
+/** What the rows turn out to be, which is the whole gap this closes. */
+const REAL_PX = 40;
+
+interface Item {
+  key: string;
+}
+
+interface HarnessProps {
+  scroller: HTMLElement;
+  header: HTMLElement;
+  items: Item[];
+  onApi: (api: FlowChatVirtualizer) => void;
+}
+
+function Harness({ scroller, header, items, onApi }: HarnessProps) {
+  const scrollerRef = React.useRef<HTMLElement | null>(scroller);
+  const headerRef = React.useRef<HTMLElement | null>(header);
+  onApi(useFlowChatVirtualizer({
+    items,
+    scrollerRef,
+    headerRef,
+    getItemKey: (item: Item) => item.key,
+    estimateItemHeightPx: () => ESTIMATE_PX,
+    scrollPaddingStartPx: 0,
+    writeViewport: () => true,
+  }));
+  return null;
+}
+
+describe('useFlowChatVirtualizer measurement', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+  let scroller: HTMLDivElement;
+  let header: HTMLDivElement;
+  let api: FlowChatVirtualizer;
+
+  /**
+   * A row in the DOM, at a height jsdom would otherwise report as zero.
+   *
+   * `offsetHeight` and not a rect, because that is what the library's own
+   * `measureElement` reads — the border box as an integer.
+   */
+  function renderRow(index: number, heightPx: number) {
+    const element = document.createElement('div');
+    element.setAttribute('data-virtual-index', String(index));
+    Object.defineProperty(element, 'offsetHeight', { configurable: true, value: heightPx });
+    scroller.appendChild(element);
+  }
+
+  beforeEach(() => {
+    vi.stubGlobal('ResizeObserver', class {
+      observe() {}
+      unobserve() {}
+      disconnect() {}
+    });
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+    scroller = document.createElement('div');
+    header = document.createElement('div');
+    container.appendChild(scroller);
+
+    const items = [{ key: 'a' }, { key: 'b' }, { key: 'c' }];
+    act(() => root.render(
+      <Harness
+        scroller={scroller}
+        header={header}
+        items={items}
+        onApi={next => { api = next; }}
+      />,
+    ));
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    vi.unstubAllGlobals();
+  });
+
+  it('places items by estimate until something has measured', () => {
+    expect(api.getItemBounds(1)).toEqual({ startPx: ESTIMATE_PX, endPx: ESTIMATE_PX * 2 });
+  });
+
+  /**
+   * Measure and read without letting React in between, which is the only
+   * situation this exists for.
+   *
+   * The caller is a layout effect in the commit that prepended: the
+   * re-render `resizeItem` schedules has not run, so anything reading the
+   * `measurementsCache` field instead of the measurement pass still sees the
+   * reservation. Letting `act` flush first would hide exactly that.
+   */
+  function measureAndRead(indexes: number[]) {
+    let bounds: Array<{ startPx: number; endPx: number } | null> = [];
+    act(() => {
+      api.measureRenderedItems();
+      bounds = indexes.map(index => api.getItemBounds(index));
+    });
+    return bounds;
+  }
+
+  it('places them by what the DOM says once the rendered rows are measured', () => {
+    // The reservation was 100px a row and they are 40px, which is the shape of
+    // every history junction measured: over by more than a factor of two.
+    [0, 1, 2].forEach(index => renderRow(index, REAL_PX));
+
+    expect(measureAndRead([0, 1, 2])).toEqual([
+      { startPx: 0, endPx: REAL_PX },
+      { startPx: REAL_PX, endPx: REAL_PX * 2 },
+      { startPx: REAL_PX * 2, endPx: REAL_PX * 3 },
+    ]);
+  });
+
+  it('leaves an item that is not rendered on its estimate', () => {
+    // Only what has a height to read is read. The rest stay estimates, which is
+    // what a virtualizer is — but they move, because the item above them did.
+    renderRow(0, REAL_PX);
+
+    expect(measureAndRead([0, 1])).toEqual([
+      { startPx: 0, endPx: REAL_PX },
+      { startPx: REAL_PX, endPx: REAL_PX + ESTIMATE_PX },
+    ]);
+  });
+
+  it('ignores an element carrying no usable index', () => {
+    const stray = document.createElement('div');
+    stray.setAttribute('data-virtual-index', 'not-an-index');
+    Object.defineProperty(stray, 'offsetHeight', { configurable: true, value: 999 });
+    scroller.appendChild(stray);
+    renderRow(0, REAL_PX);
+
+    expect(measureAndRead([0])).toEqual([{ startPx: 0, endPx: REAL_PX }]);
+  });
+
+  it('reports nothing for an index the transcript has no item at', () => {
+    expect(api.getItemBounds(3)).toBeNull();
+    expect(api.getItemBounds(-1)).toBeNull();
+  });
+});
diff --git a/src/web-ui/src/flow_chat/components/modern/useFlowChatVirtualizer.test.ts b/src/web-ui/src/flow_chat/components/modern/useFlowChatVirtualizer.test.ts
new file mode 100644
index 0000000000..fe5127de6c
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/modern/useFlowChatVirtualizer.test.ts
@@ -0,0 +1,119 @@
+import { describe, expect, it } from 'vitest';
+import {
+  isItemFullyAboveViewport,
+  virtualWindowPaddingPx,
+  visibleRowRange,
+  type FlowChatVirtualRow,
+} from './useFlowChatVirtualizer';
+
+describe('isItemFullyAboveViewport', () => {
+  it('does not compensate a row that is partly visible', () => {
+    expect(isItemFullyAboveViewport(8280, 5450)).toBe(false);
+  });
+
+  it('compensates only a row whose end is above the viewport', () => {
+    expect(isItemFullyAboveViewport(4722, 5450)).toBe(true);
+  });
+});
+
+/** Header above the items, which every offset below is measured past. */
+const CONTENT_START = 24;
+
+function row(index: number, startPx: number, sizePx: number): FlowChatVirtualRow {
+  return { index, key: `item-${index}`, startPx, endPx: startPx + sizePx };
+}
+
+describe('virtualWindowPaddingPx', () => {
+  it('stands in for the transcript on both sides of the window', () => {
+    // 40 items of 100px: the window holds 10..14, so 10 are above and 25 below.
+    const rows = [10, 11, 12, 13, 14].map(index => row(index, CONTENT_START + index * 100, 100));
+    expect(virtualWindowPaddingPx(rows, 4000, CONTENT_START)).toEqual({
+      paddingTopPx: 1000,
+      paddingBottomPx: 2500,
+    });
+  });
+
+  it('reserves nothing above a window that starts at the first item', () => {
+    const rows = [row(0, CONTENT_START, 100), row(1, CONTENT_START + 100, 100)];
+    expect(virtualWindowPaddingPx(rows, 4000, CONTENT_START)).toEqual({
+      paddingTopPx: 0,
+      paddingBottomPx: 3800,
+    });
+  });
+
+  it('reserves nothing below a window that ends at the last item', () => {
+    const rows = [row(38, CONTENT_START + 3800, 100), row(39, CONTENT_START + 3900, 100)];
+    expect(virtualWindowPaddingPx(rows, 4000, CONTENT_START)).toEqual({
+      paddingTopPx: 3800,
+      paddingBottomPx: 0,
+    });
+  });
+
+  it('reserves nothing at all for an empty window', () => {
+    // Nothing to be outside of. Deriving padding from a row that is not there
+    // would reserve the whole transcript on one side and nothing on the other.
+    expect(virtualWindowPaddingPx([], 4000, CONTENT_START)).toEqual({
+      paddingTopPx: 0,
+      paddingBottomPx: 0,
+    });
+  });
+
+  it('never reserves negative space while the header height is settling', () => {
+    // The header is measured, so for a frame its height can exceed the offsets
+    // computed against the previous one.
+    const rows = [row(0, 8, 100)];
+    expect(virtualWindowPaddingPx(rows, 4000, CONTENT_START)).toEqual({
+      paddingTopPx: 0,
+      paddingBottomPx: 3916,
+    });
+  });
+});
+
+describe('visibleRowRange', () => {
+  /** 21 items of 100px, all rendered — the transcript is barely one screen. */
+  const wholeTranscript = Array.from({ length: 21 }, (_, index) => (
+    row(index, CONTENT_START + index * 100, 100)
+  ));
+
+  it('answers where the reader is, not what is rendered', () => {
+    // The defect this exists for: every row is rendered wherever the viewport
+    // stands, so the rendered window reports index 0 as present forever.
+    expect(visibleRowRange(wholeTranscript, 1200, 500)).toEqual({
+      startIndex: 11,
+      endIndex: 16,
+    });
+  });
+
+  it('reports the head only when the first item is on screen', () => {
+    expect(visibleRowRange(wholeTranscript, 0, 500)).toEqual({
+      startIndex: 0,
+      endIndex: 4,
+    });
+  });
+
+  it('counts an item the viewport edge merely clips', () => {
+    // Half of item 4 and a sliver of item 9 are on screen, and both are things
+    // the reader can see.
+    expect(visibleRowRange(wholeTranscript, CONTENT_START + 450, 500)).toEqual({
+      startIndex: 4,
+      endIndex: 9,
+    });
+  });
+
+  it('excludes an item that ends exactly on the viewport top', () => {
+    expect(visibleRowRange(wholeTranscript, CONTENT_START + 500, 500)).toEqual({
+      startIndex: 5,
+      endIndex: 9,
+    });
+  });
+
+  it('reports no boundary from inside the reserved tail blank', () => {
+    // Past every item. The reader is at neither end of the loaded transcript,
+    // and answering "the last one" would page on a viewport full of nothing.
+    expect(visibleRowRange(wholeTranscript, 5000, 500)).toBeNull();
+  });
+
+  it('reports nothing when there is nothing rendered', () => {
+    expect(visibleRowRange([], 0, 500)).toBeNull();
+  });
+});
diff --git a/src/web-ui/src/flow_chat/components/modern/useFlowChatVirtualizer.ts b/src/web-ui/src/flow_chat/components/modern/useFlowChatVirtualizer.ts
new file mode 100644
index 0000000000..2d7f8cf970
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/modern/useFlowChatVirtualizer.ts
@@ -0,0 +1,607 @@
+/**
+ * FlowChat's virtualizer.
+ *
+ * Everything that knows which library places the items lives here. The rest of
+ * FlowChat asks for offsets in scroller coordinates and gets them back; it never
+ * sees an index space of the virtualizer's own, because there isn't one —
+ * measurements are cached against item keys, so a history prepend leaves every
+ * measured item exactly where it was.
+ *
+ * The reason this is TanStack Virtual and not react-virtuoso is one line of its
+ * measurement pass:
+ *
+ *     const size = measured ?? this.options.estimateSize(i)
+ *
+ * A per-item estimate for everything unmeasured. react-virtuoso reserves a
+ * single scalar for all of them, and this transcript alternates 38px user
+ * messages with model rounds up to 5012px, so the scroll range was wrong by an
+ * order of magnitude until an item was actually measured. Scrolling into a
+ * freshly paged block then forced a burst of measurement — stalls of 119ms and
+ * 295ms with no animation frame at all — and a correction of up to 11705px.
+ *
+ * Items are laid out in normal flow inside a padded window, not absolutely
+ * positioned. When an item inside the window changes height the browser reflows
+ * the ones below it in the same layout pass, so there is no frame where the
+ * scroll has been corrected but the items have not moved yet.
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState, type RefObject } from 'react';
+import { useVirtualizer } from '@tanstack/react-virtual';
+import {
+  roundViewportPx,
+  traceViewport,
+  traceViewportRepeating,
+  isViewportDiagnosticsEnabled,
+} from '@/infrastructure/diagnostics/flowChatViewportDiagnostics';
+import type { FlowChatViewportOwner } from './flowChatViewportOwnership';
+import {
+  describeVirtualItemEstimate,
+  type VirtualItemHeightEstimateContext,
+} from './virtualMessageListLayout';
+
+/** Item-count overscan. Roughly two Turns either side of the viewport. */
+const FLOW_CHAT_OVERSCAN_ITEMS = 6;
+
+/**
+ * How long the library goes on re-aiming after an aim, mirrored from it.
+ *
+ * `MAX_RECONCILE_MS` in `virtual-core`, which is a local constant inside
+ * `reconcileScroll` and so cannot be imported. Only ever read to decide that a
+ * cancel has nothing left to cancel, so being out of date by a version bump
+ * costs a redundant offset aim and nothing else.
+ */
+const VIRTUALIZER_REAIM_WINDOW_MS = 5_000;
+
+/**
+ * TanStack's default late-measurement adjustment is not safe for this list.
+ *
+ * Its rule is the right shape — adjust by *this item's* delta, and only for an
+ * item above the viewport — but it applies that delta to `scrollOffset`, which
+ * is the library's own copy of the scroll position and is refreshed only from
+ * scroll events. Every continuous writer here assigns `scrollTop` directly, and
+ * the scroll event for that assignment does not land until the following frame,
+ * so a measurement arriving in between is compensated from a position the
+ * viewport has already left. Measured on session open: nine corrections across
+ * two frames walked the viewport from 7440 back to 3556 before the follow loop
+ * wrote 7440 again.
+ *
+ * For a row wholly above the reader, the real viewport owner applies the
+ * measured delta before TanStack updates its cache. Rows intersecting the
+ * viewport are left alone: their content is what the reader is looking at.
+ */
+export interface FlowChatVirtualRow {
+  index: number;
+  key: string;
+  startPx: number;
+  endPx: number;
+}
+
+export interface FlowChatItemBounds {
+  startPx: number;
+  endPx: number;
+}
+
+/** A resize can shift the reader only when the whole row is above it. */
+export function isItemFullyAboveViewport(itemEndPx: number, scrollTopPx: number): boolean {
+  return itemEndPx <= scrollTopPx;
+}
+
+function resizeDeltaBand(deltaPx: number): string {
+  const magnitudePx = Math.abs(deltaPx);
+  if (magnitudePx < 1) return 'subpixel';
+  if (magnitudePx < 16) return 'small';
+  if (magnitudePx < 128) return 'medium';
+  return 'large';
+}
+
+/**
+ * The measurement pass, which the published types keep to themselves.
+ *
+ * `measurementsCache` is a public field, but it is only the place the memo
+ * behind `getMeasurements` leaves its answer — reading it returns whatever the
+ * last render put there, and a measurement arriving since then has invalidated
+ * the memo without re-running it. `getMeasurements` is `private` in the `.d.ts`
+ * although it is a plain instance field at runtime, so it is reached through
+ * this shape rather than through some other public call whose side effect
+ * happens to refresh the field.
+ */
+interface MeasuringVirtualizer {
+  getMeasurements: () => ReadonlyArray<{ start: number; end: number }>;
+}
+
+export interface UseFlowChatVirtualizerOptions<T> {
+  items: readonly T[];
+  scrollerRef: RefObject<HTMLElement | null>;
+  /**
+   * Content rendered above the items, inside the same scroller.
+   *
+   * Its height is the offset every item start is expressed against, so it is
+   * measured rather than assumed: the history paging sentinel appears and
+   * disappears inside it while the reader is scrolling.
+   */
+  headerRef: RefObject<HTMLElement | null>;
+  getItemKey: (item: T) => string;
+  estimateItemHeightPx: (item: T, context?: VirtualItemHeightEstimateContext) => number;
+  /** Data-driven inputs used by estimates before an item is mounted. */
+  estimateContext?: VirtualItemHeightEstimateContext;
+  /** Stable identity for data that changes an unmeasured row's estimate. */
+  estimateContextRevision?: string | number;
+  /**
+   * Gap kept above a Turn that has been scrolled to the top of the viewport.
+   * Applied by the virtualizer itself so that its re-aim, which runs while
+   * items below the target are still measuring, keeps the same gap.
+   */
+  scrollPaddingStartPx: number;
+  /**
+   * Every write the library makes goes through this.
+   *
+   * `scrollToFn` is a first-class option, so `scrollToIndex`, `scrollToOffset`
+   * and the re-aim that follows them all arrive here — which is what makes
+   * "nothing moves the viewport unregistered" true rather than aspirational.
+   * The library's writes are a continuation of whoever asked for the aim, so
+   * they are attributed to that owner and not to the library.
+   */
+  writeViewport: (request: {
+    owner: FlowChatViewportOwner;
+    topPx: number;
+    behavior?: ScrollBehavior;
+    holdForMs?: number;
+  }) => boolean;
+  /** Shift the viewport before a measurement changes row heights. */
+  shiftViewport?: (byPx: number) => boolean;
+}
+
+export interface FlowChatVirtualizer {
+  /** The window of items to render, in order. */
+  rows: FlowChatVirtualRow[];
+  /** Space standing in for the items above the window. */
+  paddingTopPx: number;
+  /** Space standing in for the items below the window. */
+  paddingBottomPx: number;
+  /** Ref callback for a rendered row's outermost element. */
+  measureRowElement: (element: HTMLElement | null) => void;
+  /** Where an item sits in scroller coordinates, or null if it has no place yet. */
+  getItemBounds: (index: number) => FlowChatItemBounds | null;
+  /**
+   * Bring the measurement cache level with the DOM for every rendered row.
+   *
+   * For callers that have to read a position in the same commit that changed
+   * the items, before the library's own measurement has caught up.
+   */
+  measureRenderedItems: () => void;
+  /**
+   * The items intersecting the viewport right now, read from live geometry.
+   *
+   * A callback rather than a value because it has to answer during a scroll,
+   * which moves the viewport across the rendered window without changing it.
+   */
+  getVisibleItemRange: () => FlowChatVisibleItemRange | null;
+  /**
+   * Scroll so that an item lands at the viewport's start or centre.
+   *
+   * Preferred over an offset wherever it fits: the virtualizer re-aims at the
+   * item for as long as the measurements under it keep moving, which an offset
+   * cannot do because the offset is already stale by then.
+   */
+  scrollItemIntoView: (
+    index: number,
+    options: {
+      align: 'start' | 'center';
+      behavior?: 'auto' | 'smooth';
+      /** Who the aim, and every re-aim it produces, belongs to. */
+      owner: FlowChatViewportOwner;
+      holdForMs?: number;
+    },
+  ) => void;
+  /** Scroll to an offset in scroller coordinates. */
+  scrollToOffset: (
+    offsetPx: number,
+    options: {
+      behavior?: 'auto' | 'smooth';
+      owner: FlowChatViewportOwner;
+      holdForMs?: number;
+    },
+  ) => void;
+  /**
+   * Give up an aim that is still chasing its target.
+   *
+   * For the reader taking the viewport over. The re-aim is the other half of
+   * `scrollItemIntoView` — it is what makes an aim at an item survive the
+   * measurements landing under it — and it has no idea a gesture happened.
+   *
+   * A no-op when no aim is in flight, so it is safe on every wheel notch.
+   */
+  cancelAim: () => void;
+}
+
+export interface FlowChatVisibleItemRange {
+  startIndex: number;
+  endIndex: number;
+}
+
+/**
+ * The items the reader can actually see.
+ *
+ * Deliberately not the rendered window: that carries overscan, and a transcript
+ * short enough to render whole reports the first and last item as rendered no
+ * matter where the viewport is. Anything asking "has the reader reached the end
+ * of what is loaded" needs this instead, or it is asking whether the item
+ * exists.
+ *
+ * Null when no item intersects the viewport at all, which is a real state — the
+ * reserved tail blank is below every item — and the honest answer is that the
+ * reader is at neither boundary.
+ */
+export function visibleRowRange(
+  rows: readonly FlowChatVirtualRow[],
+  scrollTopPx: number,
+  clientHeightPx: number,
+): FlowChatVisibleItemRange | null {
+  const viewportEndPx = scrollTopPx + clientHeightPx;
+  let startIndex = -1;
+  let endIndex = -1;
+  for (const row of rows) {
+    if (row.endPx <= scrollTopPx || row.startPx >= viewportEndPx) continue;
+    if (startIndex === -1) startIndex = row.index;
+    endIndex = row.index;
+  }
+  return startIndex === -1 ? null : { startIndex, endIndex };
+}
+
+export interface FlowChatVirtualWindowPadding {
+  paddingTopPx: number;
+  paddingBottomPx: number;
+}
+
+/**
+ * The space that stands in for the transcript outside the rendered window.
+ *
+ * The scroll range has to be the whole transcript's even though only a window
+ * of it exists, and this is what makes up the difference. Offsets arrive in
+ * scroller coordinates — measured from the top of the scroller, past whatever
+ * is rendered above the items — so `contentStartPx` comes back off both ends:
+ * padding is measured inside the element that holds the items.
+ *
+ * An empty window reserves nothing. There is no window to be outside of, and a
+ * padding derived from one row that is not there would be the whole transcript
+ * on one side and nothing on the other.
+ */
+export function virtualWindowPaddingPx(
+  rows: readonly FlowChatVirtualRow[],
+  totalSizePx: number,
+  contentStartPx: number,
+): FlowChatVirtualWindowPadding {
+  const first = rows[0];
+  const last = rows[rows.length - 1];
+  if (!first || !last) return { paddingTopPx: 0, paddingBottomPx: 0 };
+  return {
+    paddingTopPx: Math.max(0, first.startPx - contentStartPx),
+    paddingBottomPx: Math.max(0, totalSizePx - (last.endPx - contentStartPx)),
+  };
+}
+
+export function useFlowChatVirtualizer<T>({
+  items,
+  scrollerRef,
+  headerRef,
+  getItemKey,
+  estimateItemHeightPx,
+  estimateContext,
+  estimateContextRevision,
+  scrollPaddingStartPx,
+  writeViewport,
+  shiftViewport = () => false,
+}: UseFlowChatVirtualizerOptions<T>): FlowChatVirtualizer {
+  const itemsRef = useRef(items);
+  itemsRef.current = items;
+  const writeViewportRef = useRef(writeViewport);
+  writeViewportRef.current = writeViewport;
+  /**
+   * Who the aim currently in flight belongs to.
+   *
+   * The library re-aims for as long as the measurements under its target keep
+   * moving, and those later writes arrive with no caller of ours on the stack.
+   * They are still the same request, so they are attributed to whoever made
+   * it — which is also what lets a gesture preempt a navigation that is still
+   * chasing its Turn.
+   *
+   * Until anyone has asked for an aim, the library still writes: it places the
+   * scroller against its own state on mount. That write belongs to no request
+   * of ours, so it is attributed to the lowest authority that describes it —
+   * the library putting content where it thinks it goes. Naming a navigation
+   * here instead let a 0px write on session open outrank follow-output for the
+   * whole of the opening reveal.
+   */
+  const aimOwnerRef = useRef<FlowChatViewportOwner>('layout-correction');
+  const aimHoldForMsRef = useRef<number | undefined>(undefined);
+  /**
+   * When the aim that is still being re-aimed at was made, if there is one.
+   *
+   * The library does not say when it stops, so this is how a cancel knows
+   * whether there is anything to cancel: cleared when it is given up, and read
+   * against the library's own window when it was not. Wrong only in the
+   * direction of cancelling an aim that had already finished, which writes
+   * nothing.
+   */
+  const aimStartedAtMsRef = useRef<number | null>(null);
+  const getItemKeyRef = useRef(getItemKey);
+  getItemKeyRef.current = getItemKey;
+  const estimateItemHeightRef = useRef(estimateItemHeightPx);
+  estimateItemHeightRef.current = estimateItemHeightPx;
+  const estimateContextRef = useRef(estimateContext);
+  estimateContextRef.current = estimateContext;
+
+  const [contentStartPx, setContentStartPx] = useState(0);
+  useEffect(() => {
+    const header = headerRef.current;
+    if (!header) return;
+    const observer = new ResizeObserver(() => {
+      setContentStartPx(header.offsetHeight);
+    });
+    observer.observe(header, { box: 'border-box' });
+    setContentStartPx(header.offsetHeight);
+    return () => observer.disconnect();
+  }, [headerRef]);
+
+  /*
+   * Stable across renders on purpose. The virtualizer keys its measurement pass
+   * on the identity of these, so a fresh closure per render would re-measure
+   * the whole transcript every time a single streaming item changed. They read
+   * the current items through a ref instead, which is sound because a change
+   * that matters — an item added or removed — moves `count` as well.
+   */
+  const estimateSize = useCallback((index: number) => {
+    const item = itemsRef.current[index];
+    return item === undefined ? 0 : estimateItemHeightRef.current(item, estimateContextRef.current);
+  }, []);
+
+  const resolveItemKey = useCallback((index: number) => {
+    // Recreate the callback when estimate inputs change. TanStack uses the
+    // callback identity to invalidate its derived measurement positions while
+    // retaining DOM-measured sizes in its key cache.
+    void estimateContextRevision;
+    const item = itemsRef.current[index];
+    return item === undefined ? index : getItemKeyRef.current(item);
+  }, [estimateContextRevision]);
+
+  const virtualizer = useVirtualizer({
+    count: items.length,
+    getScrollElement: () => scrollerRef.current,
+    estimateSize,
+    getItemKey: resolveItemKey,
+    // Items carry their own index attribute already; measuring reads it back.
+    indexAttribute: 'data-virtual-index',
+    overscan: FLOW_CHAT_OVERSCAN_ITEMS,
+    scrollMargin: contentStartPx,
+    scrollPaddingStart: scrollPaddingStartPx,
+    /*
+     * The library's only way out to the DOM. Routing it through the register
+     * is what closes the gap the contract used to describe as unclosable: a
+     * write from inside the library is now a write like any other, refusable
+     * by whatever outranks the aim it came from.
+     */
+    scrollToFn: (offsetPx, { behavior }) => {
+      writeViewportRef.current({
+        owner: aimOwnerRef.current,
+        topPx: offsetPx,
+        behavior,
+        holdForMs: aimHoldForMsRef.current,
+      });
+    },
+  });
+  // An instance field rather than an option, so it is assigned here — before
+  // any measurement callback can reach `resizeItem`.
+  virtualizer.shouldAdjustScrollPositionOnItemSizeChange = (item, delta) => {
+    const scroller = scrollerRef.current;
+    if (!scroller) return false;
+    const beforeScrollTopPx = scroller.scrollTop;
+    const beforeScrollHeightPx = scroller.scrollHeight;
+    // A row that merely starts above the viewport may still be visible. Its
+    // resize changes content inside the reader rather than moving content that
+    // is wholly above it, so compensating its full delta would pull the reader
+    // by the size of a row they are looking at (history model rounds can be
+    // several thousand pixels). Only a row whose end is above the viewport can
+    // move the reader's existing content and needs a viewport shift.
+    const fullyAboveViewport = isItemFullyAboveViewport(item.end, beforeScrollTopPx);
+    const applied = fullyAboveViewport ? shiftViewport(delta) : false;
+    const virtualItem = itemsRef.current[item.index];
+    if (isViewportDiagnosticsEnabled()) {
+      const diagnosticItem = virtualItem as {
+        type?: unknown;
+        turnId?: unknown;
+      } | undefined;
+      const itemKey = virtualItem === undefined ? null : getItemKeyRef.current(virtualItem);
+      traceViewportRepeating(
+        `itemResize|${itemKey ?? 'unknown'}|${fullyAboveViewport}|${applied}|${resizeDeltaBand(delta)}`,
+        {
+          location: 'virtualizer.itemResize',
+          message: 'an item changed size during virtualizer measurement',
+          travelPx: delta,
+          data: () => ({
+            index: item.index,
+            itemKey,
+            itemType: typeof diagnosticItem?.type === 'string' ? diagnosticItem.type : null,
+            turnId: typeof diagnosticItem?.turnId === 'string' ? diagnosticItem.turnId : null,
+            estimatedSizePx: virtualItem === undefined
+              ? null
+              : roundViewportPx(estimateItemHeightRef.current(virtualItem)),
+            previousItemSizePx: roundViewportPx(item.size),
+            nextItemSizePx: roundViewportPx(item.size + delta),
+            itemStartPx: roundViewportPx(item.start),
+            itemEndPx: roundViewportPx(item.end),
+            deltaPx: roundViewportPx(delta),
+            fullyAboveViewport,
+            beforeScrollTopPx: roundViewportPx(beforeScrollTopPx),
+            beforeScrollHeightPx: roundViewportPx(beforeScrollHeightPx),
+            applied,
+            afterScrollTopPx: roundViewportPx(scroller.scrollTop),
+            afterScrollHeightPx: roundViewportPx(scroller.scrollHeight),
+            estimateBreakdown: virtualItem && typeof virtualItem === 'object' && 'type' in virtualItem
+              ? describeVirtualItemEstimate(virtualItem as unknown as Parameters<typeof describeVirtualItemEstimate>[0])
+              : null,
+          }),
+        },
+      );
+    }
+    /*
+     * TanStack's default adjustment is based on its cached scroll offset. This
+     * list writes the real scroller through the viewport register, so that copy
+     * can be one frame stale. Move the real viewport before the new size enters
+     * the cache; otherwise a shrinking range can make the browser clamp
+     * scrollTop to the physical tail before the reader's anchor gets a chance
+     * to restore it.
+     */
+    return false;
+  };
+
+  const virtualRows = virtualizer.getVirtualItems();
+  const totalSizePx = virtualizer.getTotalSize();
+
+  const rows = useMemo<FlowChatVirtualRow[]>(() => virtualRows.map(row => ({
+    index: row.index,
+    key: String(row.key),
+    startPx: row.start,
+    endPx: row.end,
+  })), [virtualRows]);
+
+  const { paddingTopPx, paddingBottomPx } = virtualWindowPaddingPx(
+    rows,
+    totalSizePx,
+    contentStartPx,
+  );
+
+  const measureRowElement = virtualizer.measureElement;
+
+  const rowsRef = useRef(rows);
+  rowsRef.current = rows;
+
+  const getVisibleItemRange = useCallback((): FlowChatVisibleItemRange | null => {
+    const scroller = scrollerRef.current;
+    if (!scroller) return null;
+    return visibleRowRange(rowsRef.current, scroller.scrollTop, scroller.clientHeight);
+  }, [scrollerRef]);
+
+  /**
+   * Everything rendered, measured now rather than whenever the library gets to it.
+   *
+   * The library measures a row inline as its ref attaches, but only when the
+   * reader is holding still:
+   *
+   *     if ((!this.isScrolling || this.scrollState) && ...) this.resizeItem(...)
+   *
+   * History pages in exactly when they are not: the reader scrolls up into the
+   * boundary, the rows arrive in the DOM at their real heights, and the cache
+   * keeps the estimates it reserved for them. The ResizeObserver does catch
+   * them — after the layout effects of the commit that added them, which is a
+   * frame later than the one reader of these positions that cannot wait. The
+   * prepend compensation has to move the reader in the same paint as the rows
+   * that displaced them. Measured across four junctions, height reserved
+   * against scroll range actually gained: 2174/670, 2494/949, 2346/609,
+   * 2580/1917.
+   *
+   * Rendered rows only, because only they have a height to read; the rest stay
+   * estimates, which is what a virtualizer is. A row whose height has not
+   * changed costs nothing — `resizeItem` returns on a zero delta — so this is
+   * the same work the ResizeObserver was going to do, done a frame earlier.
+   */
+  const measureRenderedItems = useCallback(() => {
+    const scroller = scrollerRef.current;
+    if (!scroller) return;
+    const elements = scroller.querySelectorAll<HTMLElement>('[data-virtual-index]');
+    for (const element of elements) {
+      const index = Number(element.getAttribute('data-virtual-index'));
+      if (!Number.isInteger(index)) continue;
+      virtualizer.resizeItem(
+        index,
+        virtualizer.options.measureElement(element, undefined, virtualizer),
+      );
+    }
+  }, [scrollerRef, virtualizer]);
+
+  const getItemBounds = useCallback((index: number): FlowChatItemBounds | null => {
+    const measurement = (virtualizer as unknown as MeasuringVirtualizer)
+      .getMeasurements()[index];
+    return measurement ? { startPx: measurement.start, endPx: measurement.end } : null;
+  }, [virtualizer]);
+
+  const scrollItemIntoView = useCallback((
+    index: number,
+    options: {
+      align: 'start' | 'center';
+      behavior?: 'auto' | 'smooth';
+      owner: FlowChatViewportOwner;
+      holdForMs?: number;
+    },
+  ) => {
+    aimOwnerRef.current = options.owner;
+    aimHoldForMsRef.current = options.holdForMs;
+    aimStartedAtMsRef.current = performance.now();
+    virtualizer.scrollToIndex(index, {
+      align: options.align,
+      behavior: options.behavior ?? 'auto',
+    });
+  }, [virtualizer]);
+
+  const scrollToOffset = useCallback((
+    offsetPx: number,
+    options: {
+      behavior?: 'auto' | 'smooth';
+      owner: FlowChatViewportOwner;
+      holdForMs?: number;
+    },
+  ) => {
+    aimOwnerRef.current = options.owner;
+    aimHoldForMsRef.current = options.holdForMs;
+    aimStartedAtMsRef.current = performance.now();
+    virtualizer.scrollToOffset(offsetPx, {
+      align: 'start',
+      behavior: options.behavior ?? 'auto',
+    });
+  }, [virtualizer]);
+
+  const cancelAim = useCallback(() => {
+    const startedAtMs = aimStartedAtMsRef.current;
+    if (startedAtMs === null) return;
+    aimStartedAtMsRef.current = null;
+    const scroller = scrollerRef.current;
+    // Already over, by the library's own clock. Aiming again would only start
+    // another reconcile to sit out.
+    if (!scroller || performance.now() - startedAtMs > VIRTUALIZER_REAIM_WINDOW_MS) return;
+    /*
+     * Aimed at the offset the scroller is already at, rather than by clearing
+     * the library's `scrollState`, which is private and would have to be
+     * reached through a cast that no version bump would warn us about.
+     *
+     * An offset aim carries no index, and the reconcile recomputes its target
+     * from the index — so with none, the target can never change again, and
+     * writing again is the only thing it does when the target changes. The
+     * write this makes goes to the position the scroller already holds, which
+     * is a no-op whether the register grants it or refuses it.
+     */
+    aimOwnerRef.current = 'layout-correction';
+    aimHoldForMsRef.current = undefined;
+    const givenUpAtPx = scroller.scrollTop;
+    virtualizer.scrollToOffset(givenUpAtPx, { align: 'start', behavior: 'auto' });
+    traceViewport({
+      location: 'virtualizer.aimCancelled',
+      message: 'an aim was given up because the reader took the viewport',
+      data: () => ({
+        givenUpAtPx: roundViewportPx(givenUpAtPx),
+        aimAgeMs: Math.round(performance.now() - startedAtMs),
+      }),
+    });
+  }, [scrollerRef, virtualizer]);
+
+  return {
+    rows,
+    paddingTopPx,
+    paddingBottomPx,
+    measureRowElement,
+    getItemBounds,
+    measureRenderedItems,
+    getVisibleItemRange,
+    scrollItemIntoView,
+    scrollToOffset,
+    cancelAim,
+  };
+}
diff --git a/src/web-ui/src/flow_chat/components/modern/virtualItemHeightEstimators.ts b/src/web-ui/src/flow_chat/components/modern/virtualItemHeightEstimators.ts
new file mode 100644
index 0000000000..171c5088fa
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/modern/virtualItemHeightEstimators.ts
@@ -0,0 +1,287 @@
+/**
+ * Pure, data-driven height estimates used before a virtual row mounts.
+ *
+ * These are deliberately separate from React renderers: TanStack must reserve
+ * space for an item before its DOM exists. Once mounted, ResizeObserver/DOM
+ * measurement remains authoritative and replaces this estimate.
+ */
+import type {
+  AnyFlowItem,
+  FlowToolItem,
+} from '../../types/flow-chat';
+import type { VirtualItem } from '../../store/modernFlowChatStore';
+import { getEffectiveToolName } from '../../utils/toolInvocationIdentity';
+
+export interface VirtualItemHeightEstimateContext {
+  /** Width available to the reading column, excluding the scrollbar. */
+  availableWidthPx?: number;
+  isHistorical?: boolean;
+  expandedThinkingItemIds?: readonly string[];
+  exploreGroupStates?: ReadonlyMap<string, boolean>;
+}
+
+export interface VirtualItemHeightEstimate {
+  heightPx: number;
+  confidence: 'high' | 'medium' | 'low';
+  kind: string;
+}
+
+const DEFAULT_WIDTH_PX = 900;
+const MIN_TEXT_LINE_WIDTH_PX = 24;
+const USER_MESSAGE_BASE_HEIGHT_PX = 96;
+const USER_MESSAGE_LINE_HEIGHT_PX = 22;
+const MODEL_ROUND_BASE_HEIGHT_PX = 80;
+const MODEL_ROUND_TEXT_BASE_HEIGHT_PX = 72;
+const MODEL_ROUND_TEXT_LINE_HEIGHT_PX = 30;
+const TOOL_HEADER_HEIGHT_PX = 38;
+const TOOL_COMPACT_HEIGHT_PX = 53;
+const TODO_COMPACT_HEIGHT_PX = 24;
+const TOOL_EXPANDED_BASE_HEIGHT_PX = 96;
+const EXPLORE_GROUP_HEADER_HEIGHT_PX = 20;
+const EXPLORE_GROUP_MAX_CONTENT_HEIGHT_PX = 400;
+const ESTIMATED_TEXT_CHARS_PER_LINE = 60;
+const TERMINAL_TOOL_NAMES = new Set(['Bash', 'ExecCommand', 'WriteStdin', 'ExecControl', 'TerminalControl']);
+const COLLAPSED_TOOL_STATUSES = new Set(['completed', 'cancelled', 'error', 'rejected']);
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
+function widthScale(widthPx: number | undefined): number {
+  const width = Math.min(
+    DEFAULT_WIDTH_PX,
+    Math.max(MIN_TEXT_LINE_WIDTH_PX, widthPx ?? DEFAULT_WIDTH_PX),
+  );
+  return DEFAULT_WIDTH_PX / width;
+}
+
+function estimateTextLines(text: string, widthPx: number | undefined): number {
+  return estimateTextLineCount(text.length, widthPx);
+}
+
+function estimateTextLineCount(textLength: number, widthPx: number | undefined): number {
+  const scale = widthScale(widthPx);
+  return Math.max(1, Math.ceil(textLength * scale / ESTIMATED_TEXT_CHARS_PER_LINE));
+}
+
+function estimateTextHeight(
+  text: string,
+  basePx: number,
+  lineHeightPx: number,
+  widthPx: number | undefined,
+): number {
+  return basePx + estimateTextLines(text, widthPx) * lineHeightPx;
+}
+
+function stringValue(value: unknown): string {
+  return typeof value === 'string' ? value : '';
+}
+
+function objectValue(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === 'object' ? value as Record<string, unknown> : {};
+}
+
+function toolInput(tool: FlowToolItem): Record<string, unknown> {
+  return objectValue(tool.partialParams ?? tool.toolCall?.input);
+}
+
+function toolResultText(tool: FlowToolItem): string {
+  const result = objectValue(tool.toolResult?.result);
+  return stringValue(
+    result.output
+      ?? result.content
+      ?? result.result
+      ?? tool.toolResult?.resultForAssistant
+      ?? tool.toolResult?.error,
+  );
+}
+
+function toolContentLength(tool: FlowToolItem): number {
+  const input = toolInput(tool);
+  const candidates = [
+    input.content,
+    input.contents,
+    input.new_string,
+    input.old_string,
+    input.command,
+    input.cmd,
+    input.description,
+    toolResultText(tool),
+  ];
+  return candidates.reduce<number>((total, value) => total + stringValue(value).length, 0);
+}
+
+function todoCount(tool: FlowToolItem): number {
+  const input = toolInput(tool);
+  const result = objectValue(tool.toolResult?.result);
+  const todos = input.todos ?? result.todos;
+  return Array.isArray(todos) ? todos.length : 0;
+}
+
+function isTerminalTool(toolName: string): boolean {
+  return TERMINAL_TOOL_NAMES.has(toolName);
+}
+
+function isCollapsedByStatus(tool: FlowToolItem): boolean {
+  return COLLAPSED_TOOL_STATUSES.has(tool.status);
+}
+
+export function estimateFlowItemHeight(
+  item: AnyFlowItem,
+  context: VirtualItemHeightEstimateContext = {},
+): VirtualItemHeightEstimate {
+  if (item.type === 'thinking' && !(context.expandedThinkingItemIds ?? []).includes(item.id)) {
+    return { heightPx: 40, confidence: 'high', kind: 'thinking-collapsed' };
+  }
+
+  if (item.type === 'text' || item.type === 'thinking' || item.type === 'user-steering') {
+    return {
+      heightPx: clamp(
+        estimateTextHeight(item.content, MODEL_ROUND_TEXT_BASE_HEIGHT_PX, MODEL_ROUND_TEXT_LINE_HEIGHT_PX, context.availableWidthPx),
+        40,
+        3200,
+      ),
+      confidence: 'medium',
+      kind: item.type,
+    };
+  }
+
+  if (item.type === 'image-analysis') {
+    return { heightPx: 320, confidence: 'low', kind: 'image-analysis' };
+  }
+
+  if (item.type === 'tool') {
+    return estimateToolHeight(item, context);
+  }
+
+  return { heightPx: 72, confidence: 'low', kind: 'flow-item' };
+}
+
+export function estimateToolHeight(
+  tool: FlowToolItem,
+  context: VirtualItemHeightEstimateContext = {},
+): VirtualItemHeightEstimate {
+  const toolName = getEffectiveToolName(tool);
+  const contentLength = toolContentLength(tool);
+  const collapsed = isCollapsedByStatus(tool);
+  const contentLines = estimateTextLineCount(contentLength, context.availableWidthPx);
+
+  if (toolName === 'TodoWrite') {
+    const count = todoCount(tool);
+    return {
+      heightPx: collapsed ? TODO_COMPACT_HEIGHT_PX : clamp(TOOL_EXPANDED_BASE_HEIGHT_PX + count * 30, 96, 360),
+      confidence: count > 0 ? 'high' : 'medium',
+      kind: 'tool-todo-write',
+    };
+  }
+
+  if (toolName === 'Write' || toolName === 'Edit' || toolName === 'CreateCanvas' || toolName === 'UpdateCanvas') {
+    return {
+      heightPx: collapsed
+        ? TOOL_COMPACT_HEIGHT_PX
+        : clamp(TOOL_EXPANDED_BASE_HEIGHT_PX + contentLines * 22, TOOL_EXPANDED_BASE_HEIGHT_PX, 480),
+      confidence: contentLength > 0 ? 'high' : 'medium',
+      kind: `tool-${toolName.toLowerCase()}`,
+    };
+  }
+
+  if (isTerminalTool(toolName)) {
+    const outputLines = Math.max(1, Math.min(15, contentLines));
+    return {
+      heightPx: collapsed
+        ? TOOL_COMPACT_HEIGHT_PX
+        : TOOL_HEADER_HEIGHT_PX + 22 * outputLines + 40,
+      confidence: contentLength > 0 ? 'medium' : 'low',
+      kind: 'tool-terminal',
+    };
+  }
+
+  if (collapsed) {
+    return { heightPx: TOOL_COMPACT_HEIGHT_PX, confidence: 'medium', kind: 'tool-collapsed' };
+  }
+
+  return {
+    heightPx: clamp(TOOL_HEADER_HEIGHT_PX + contentLines * 22, 72, 420),
+    confidence: 'low',
+    kind: 'tool-generic',
+  };
+}
+
+export function estimateModelRoundHeight(
+  item: Extract<VirtualItem, { type: 'model-round' }>,
+  context: VirtualItemHeightEstimateContext = {},
+): VirtualItemHeightEstimate {
+  const flowItems = item.data.items ?? [];
+  if (flowItems.length === 0) {
+    return { heightPx: 200, confidence: 'low', kind: 'model-round-empty' };
+  }
+  const contentHeight = flowItems.reduce(
+    (total, flowItem) => total + estimateFlowItemHeight(flowItem, context).heightPx,
+    0,
+  );
+  return {
+    heightPx: clamp(MODEL_ROUND_BASE_HEIGHT_PX + contentHeight, 200, 3600),
+    confidence: flowItems.some(flowItem => flowItem.type === 'tool') ? 'medium' : 'high',
+    kind: 'model-round',
+  };
+}
+
+export function estimateExploreGroupHeight(
+  item: Extract<VirtualItem, { type: 'explore-group' }>,
+  context: VirtualItemHeightEstimateContext = {},
+): VirtualItemHeightEstimate {
+  const isExpanded = context.exploreGroupStates?.has(item.data.groupId)
+    ? context.exploreGroupStates.get(item.data.groupId)
+    : !item.data.wasCutByCritical;
+  const contentHeight = item.data.allItems.reduce<number>(
+    (total, flowItem) => total + estimateFlowItemHeight(flowItem as AnyFlowItem, context).heightPx,
+    0,
+  );
+  return {
+    heightPx: isExpanded
+      ? EXPLORE_GROUP_HEADER_HEIGHT_PX + Math.min(EXPLORE_GROUP_MAX_CONTENT_HEIGHT_PX, contentHeight)
+      : EXPLORE_GROUP_HEADER_HEIGHT_PX,
+    confidence: 'medium',
+    kind: isExpanded ? 'explore-group-expanded' : 'explore-group-collapsed',
+  };
+}
+
+export function estimateVirtualItemHeight(
+  item: VirtualItem,
+  context: VirtualItemHeightEstimateContext = {},
+): VirtualItemHeightEstimate {
+  switch (item.type) {
+    case 'user-message':
+    case 'user-steering-message':
+      return {
+        heightPx: clamp(
+          estimateTextHeight(item.data.content, USER_MESSAGE_BASE_HEIGHT_PX, USER_MESSAGE_LINE_HEIGHT_PX, context.availableWidthPx),
+          96,
+          320,
+        ),
+        confidence: 'high',
+        kind: 'user-message',
+      };
+    case 'model-round':
+      return estimateModelRoundHeight(item, {
+        ...context,
+        expandedThinkingItemIds: item.layoutHints?.expandedThinkingItemIds
+          ?? context.expandedThinkingItemIds,
+      });
+    case 'explore-group':
+      return estimateExploreGroupHeight(item, context);
+    case 'turn-completion-notice':
+      return { heightPx: 120, confidence: 'high', kind: 'turn-completion-notice' };
+    case 'turn-failure-notice':
+      return { heightPx: 160, confidence: 'medium', kind: 'turn-failure-notice' };
+    case 'image-analyzing':
+      return { heightPx: 200, confidence: 'low', kind: 'image-analyzing' };
+  }
+}
+
+export function estimateVirtualItemHeightPx(
+  item: VirtualItem,
+  context: VirtualItemHeightEstimateContext = {},
+): number {
+  return estimateVirtualItemHeight(item, context).heightPx;
+}
diff --git a/src/web-ui/src/flow_chat/components/modern/virtualMessageListLayout.ts b/src/web-ui/src/flow_chat/components/modern/virtualMessageListLayout.ts
index 6653b9af76..38d23a73f9 100644
--- a/src/web-ui/src/flow_chat/components/modern/virtualMessageListLayout.ts
+++ b/src/web-ui/src/flow_chat/components/modern/virtualMessageListLayout.ts
@@ -1,5 +1,13 @@
-import type { AnyFlowItem } from '../../types/flow-chat';
+import type { AnyFlowItem, FlowItem, FlowToolItem } from '../../types/flow-chat';
 import type { VirtualItem } from '../../store/modernFlowChatStore';
+import { getEffectiveToolName } from '../../utils/toolInvocationIdentity';
+import {
+  estimateFlowItemHeight as estimateFlowItemHeightByOwner,
+  estimateVirtualItemHeight as estimateVirtualItemHeightByOwner,
+  type VirtualItemHeightEstimateContext,
+} from './virtualItemHeightEstimators';
+
+export type { VirtualItemHeightEstimateContext, VirtualItemHeightEstimate } from './virtualItemHeightEstimators';
 
 export const LIVE_SESSION_DEFAULT_ITEM_HEIGHT_PX = 200;
 export const HISTORICAL_SESSION_DEFAULT_ITEM_HEIGHT_PX = 72;
@@ -7,14 +15,6 @@ export const HISTORICAL_SESSION_MODEL_ROUND_DEFAULT_ITEM_HEIGHT_PX = 960;
 export const INITIAL_HISTORY_RENDER_MIN_TURN_COUNT = 2;
 const INITIAL_HISTORY_RENDER_USER_ONLY_LATEST_MIN_TURN_COUNT = 3;
 export const INITIAL_HISTORY_RENDER_MIN_ESTIMATED_HEIGHT_PX = 1400;
-const USER_MESSAGE_BASE_HEIGHT_PX = 96;
-const USER_MESSAGE_LINE_HEIGHT_PX = 22;
-const MODEL_ROUND_BASE_HEIGHT_PX = 80;
-const MODEL_ROUND_TEXT_BASE_HEIGHT_PX = 72;
-const MODEL_ROUND_TEXT_LINE_HEIGHT_PX = 30;
-const TOOL_CARD_ESTIMATE_HEIGHT_PX = 88;
-const EXPLORE_GROUP_BASE_HEIGHT_PX = 96;
-const ESTIMATED_TEXT_CHARS_PER_LINE = 60;
 
 export function getLeadingVirtualItemIndexDelta<T>(
   previousItems: readonly T[],
@@ -57,86 +57,97 @@ export function getVirtualMessageDefaultItemHeight(params: {
 }
 
 export function estimateTextHeightFromLength(textLength: number, basePx: number, lineHeightPx: number): number {
+  const ESTIMATED_TEXT_CHARS_PER_LINE = 60;
   const lineCount = Math.max(1, Math.ceil(textLength / ESTIMATED_TEXT_CHARS_PER_LINE));
   return basePx + lineCount * lineHeightPx;
 }
 
-function estimateTextHeight(content: string, basePx: number, lineHeightPx: number): number {
-  return estimateTextHeightFromLength(content.length, basePx, lineHeightPx);
-}
-
-function getFlowItemTextLength(item: AnyFlowItem): number {
-  if (item.type === 'text' || item.type === 'thinking' || item.type === 'user-steering') {
-    return item.content.length;
-  }
-  return 0;
+function describeFlowItemEstimate(
+  item: FlowItem,
+  index: number,
+  totalCount: number,
+  expandedThinkingItemIds: readonly string[],
+): Record<string, unknown> {
+  const content = item.type === 'text' || item.type === 'thinking' || item.type === 'user-steering'
+    ? (item as AnyFlowItem & { content: string }).content
+    : null;
+  return {
+    index,
+    type: item.type,
+    ...(item.type === 'tool'
+      ? {
+          toolName: getEffectiveToolName(item as FlowToolItem),
+          status: item.status,
+          isStreaming: (item as FlowToolItem).isParamsStreaming ?? false,
+        }
+      : {}),
+    ...(content === null
+      ? {}
+      : {
+          contentLength: content.length,
+          lineCount: content.length === 0 ? 0 : content.split('\n').length,
+        }),
+    isLastItem: index === totalCount - 1,
+    estimatedHeightPx: estimateFlowItemHeightByOwner(item as AnyFlowItem, {
+      expandedThinkingItemIds,
+    }).heightPx,
+  };
 }
 
-function estimateFlowItemHeight(item: AnyFlowItem): number {
-  const textLength = getFlowItemTextLength(item);
-  if (textLength > 0) {
-    return Math.min(
-      3200,
-      estimateTextHeightFromLength(
-        textLength,
-        MODEL_ROUND_TEXT_BASE_HEIGHT_PX,
-        MODEL_ROUND_TEXT_LINE_HEIGHT_PX,
+/** Bounded, content-free estimate details for FlowChat viewport diagnostics. */
+export function describeVirtualItemEstimate(item: VirtualItem): Record<string, unknown> {
+  if (item.type === 'model-round') {
+    const flowItems = item.data.items ?? [];
+    const expandedThinkingItemIds = item.layoutHints?.expandedThinkingItemIds ?? [];
+    const itemEstimates = flowItems.map((flowItem, index) => describeFlowItemEstimate(
+      flowItem,
+      index,
+      flowItems.length,
+      expandedThinkingItemIds,
+    ));
+    return {
+      estimateKind: 'model-round',
+      isLastRound: item.isLastRound,
+      isTurnComplete: item.isTurnComplete,
+      isStreaming: item.data.isStreaming,
+      expandedThinkingItemIds,
+      baseHeightPx: 80,
+      contentEstimatePx: itemEstimates.reduce(
+        (total, entry) => total + Number(entry.estimatedHeightPx ?? 0),
+        0,
       ),
-    );
-  }
-
-  if (item.type === 'tool') {
-    return TOOL_CARD_ESTIMATE_HEIGHT_PX;
-  }
-
-  if (item.type === 'image-analysis') {
-    return 320;
+      itemEstimates,
+    };
   }
 
-  return HISTORICAL_SESSION_DEFAULT_ITEM_HEIGHT_PX;
-}
-
-function estimateModelRoundHeight(item: Extract<VirtualItem, { type: 'model-round' }>): number {
-  const flowItems = item.data.items ?? [];
-  if (flowItems.length === 0) {
-    return LIVE_SESSION_DEFAULT_ITEM_HEIGHT_PX;
+  if (item.type === 'explore-group') {
+    const itemEstimates = item.data.allItems.map((flowItem, index) => describeFlowItemEstimate(
+      flowItem as AnyFlowItem,
+      index,
+      item.data.allItems.length,
+      [],
+    ));
+    return {
+      estimateKind: 'explore-group',
+      itemCount: item.data.allItems.length,
+      defaultExpanded: !item.data.wasCutByCritical,
+      estimatedHeightPx: estimateVirtualItemHeightByOwner(item).heightPx,
+      itemEstimates,
+    };
   }
 
-  const contentHeight = flowItems.reduce(
-    (total, flowItem) => total + estimateFlowItemHeight(flowItem),
-    0,
-  );
-  return Math.min(3600, Math.max(LIVE_SESSION_DEFAULT_ITEM_HEIGHT_PX, MODEL_ROUND_BASE_HEIGHT_PX + contentHeight));
-}
-
-function estimateUserMessageHeight(content: string | undefined): number {
-  return Math.min(
-    320,
-    estimateTextHeight(content ?? '', USER_MESSAGE_BASE_HEIGHT_PX, USER_MESSAGE_LINE_HEIGHT_PX),
-  );
+  return { estimateKind: item.type };
 }
 
-function estimateExploreGroupHeight(item: Extract<VirtualItem, { type: 'explore-group' }>): number {
-  const visibleRowCount = Math.min(10, item.data.allItems.length);
-  return Math.min(420, EXPLORE_GROUP_BASE_HEIGHT_PX + visibleRowCount * 24);
+export function estimateVirtualMessageItemHeight(item: VirtualItem): number {
+  return estimateVirtualItemHeightByOwner(item).heightPx;
 }
 
-export function estimateVirtualMessageItemHeight(item: VirtualItem): number {
-  switch (item.type) {
-    case 'user-message':
-    case 'user-steering-message':
-      return estimateUserMessageHeight(item.data.content);
-    case 'model-round':
-      return estimateModelRoundHeight(item);
-    case 'explore-group':
-      return estimateExploreGroupHeight(item);
-    case 'turn-completion-notice':
-      return 120;
-    case 'turn-failure-notice':
-      return 160;
-    case 'image-analyzing':
-      return LIVE_SESSION_DEFAULT_ITEM_HEIGHT_PX;
-  }
+export function estimateVirtualMessageItemHeightWithContext(
+  item: VirtualItem,
+  context: VirtualItemHeightEstimateContext = {},
+): number {
+  return estimateVirtualItemHeightByOwner(item, context).heightPx;
 }
 
 export interface InitialHistoryRenderWindow {
diff --git a/src/web-ui/src/flow_chat/components/session-menu/SessionMenu.scss b/src/web-ui/src/flow_chat/components/session-menu/SessionMenu.scss
index 6e4272c4fe..d7dd3ac550 100644
--- a/src/web-ui/src/flow_chat/components/session-menu/SessionMenu.scss
+++ b/src/web-ui/src/flow_chat/components/session-menu/SessionMenu.scss
@@ -24,7 +24,11 @@ $session-menu-timing: cubic-bezier(0.4, 0, 0.2, 1);
   color: var(--bf-appearance-token-color-text-muted);
   border-radius: var(--bf-appearance-token-size-radius-sm);
   cursor: pointer;
-  transition: all 0.2s $session-menu-timing;
+  transition:
+    transform 120ms cubic-bezier(0.23, 1, 0.32, 1),
+    background-color 160ms ease,
+    color 160ms ease,
+    opacity 160ms ease;
 
   &:hover:not(:disabled) {
     background: var(--bf-appearance-token-color-accent-200);
diff --git a/src/web-ui/src/flow_chat/components/smart-recommendations/SmartRecommendations.scss b/src/web-ui/src/flow_chat/components/smart-recommendations/SmartRecommendations.scss
index 49079549c6..3455d60558 100644
--- a/src/web-ui/src/flow_chat/components/smart-recommendations/SmartRecommendations.scss
+++ b/src/web-ui/src/flow_chat/components/smart-recommendations/SmartRecommendations.scss
@@ -8,7 +8,7 @@
   border-radius: 8px;
   padding: 12px 16px;
   margin-bottom: 12px;
-  animation: slideDown 0.2s ease-out;
+  animation: smart-recommendations-enter 160ms cubic-bezier(0.23, 1, 0.32, 1);
 
   &__header {
     display: flex;
@@ -33,7 +33,10 @@
     display: flex;
     align-items: center;
     justify-content: center;
-    transition: all 0.2s;
+    transition:
+      background-color 160ms ease,
+      color 160ms ease,
+      scale 120ms cubic-bezier(0.23, 1, 0.32, 1);
 
     &:hover {
       background: var(--bf-appearance-token-element-bg-hover);
@@ -59,7 +62,13 @@
     font-size: var(--bf-appearance-token-tool-card-action-font-size);
     font-weight: 500;
     cursor: pointer;
-    transition: all 0.2s;
+    transition:
+      transform 120ms cubic-bezier(0.23, 1, 0.32, 1),
+      scale 120ms cubic-bezier(0.23, 1, 0.32, 1),
+      background-color 160ms ease,
+      border-color 160ms ease,
+      box-shadow 180ms ease,
+      opacity 160ms ease;
     white-space: nowrap;
 
     svg {
@@ -108,14 +117,14 @@
   }
 
   &__loading {
-    animation: blink 1s infinite;
+    animation: smart-recommendations-loading 1s ease-in-out infinite;
   }
 }
 
-@keyframes slideDown {
+@keyframes smart-recommendations-enter {
   from {
     opacity: 0;
-    transform: translateY(-10px);
+    transform: translateY(-4px);
   }
   to {
     opacity: 1;
@@ -123,7 +132,7 @@
   }
 }
 
-@keyframes blink {
+@keyframes smart-recommendations-loading {
   0%, 100% {
     opacity: 1;
   }
@@ -132,3 +141,9 @@
   }
 }
 
+@media (prefers-reduced-motion: reduce) {
+  .bitfun-smart-recommendations,
+  .bitfun-smart-recommendations__loading {
+    animation: none;
+  }
+}
diff --git a/src/web-ui/src/flow_chat/components/toolbar-mode/ToolbarMode.scss b/src/web-ui/src/flow_chat/components/toolbar-mode/ToolbarMode.scss
index 5c554f975c..5918e67cdf 100644
--- a/src/web-ui/src/flow_chat/components/toolbar-mode/ToolbarMode.scss
+++ b/src/web-ui/src/flow_chat/components/toolbar-mode/ToolbarMode.scss
@@ -142,7 +142,11 @@ $transition-timing: cubic-bezier(0.4, 0, 0.2, 1);
   color: var(--bf-appearance-token-color-text-muted);
   border-radius: var(--bf-appearance-token-size-radius-sm);
   cursor: pointer;
-  transition: all 0.2s $transition-timing;
+  transition:
+    transform 120ms cubic-bezier(0.23, 1, 0.32, 1),
+    background-color 160ms ease,
+    color 160ms ease,
+    opacity 160ms ease;
 
   &:hover:not(:disabled) {
     background: var(--bf-appearance-token-color-accent-200);
@@ -570,7 +574,11 @@ $transition-timing: cubic-bezier(0.4, 0, 0.2, 1);
   display: flex;
   align-items: center;
   justify-content: center;
-  transition: all 0.15s ease;
+  transition:
+    transform 120ms cubic-bezier(0.23, 1, 0.32, 1),
+    background-color 150ms ease,
+    color 150ms ease,
+    opacity 150ms ease;
   -webkit-appearance: none;
   -moz-appearance: none;
   appearance: none;
@@ -862,3 +870,14 @@ $transition-timing: cubic-bezier(0.4, 0, 0.2, 1);
     transform: translateX(0);
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .bitfun-toolbar-mode,
+  .bitfun-toolbar-mode--processing::before,
+  .bitfun-toolbar-mode__text--streaming::after,
+  .toolbar-btn--cancel,
+  .animate-spin,
+  .animate-pulse {
+    animation: none;
+  }
+}
diff --git a/src/web-ui/src/flow_chat/components/usage/SessionUsageComponents.test.tsx b/src/web-ui/src/flow_chat/components/usage/SessionUsageComponents.test.tsx
index 7b6125f8e9..80c4826e7c 100644
--- a/src/web-ui/src/flow_chat/components/usage/SessionUsageComponents.test.tsx
+++ b/src/web-ui/src/flow_chat/components/usage/SessionUsageComponents.test.tsx
@@ -209,6 +209,8 @@ vi.mock('react-i18next', async (importOriginal) => ({
         'usage.slowestKinds.turn': 'Turn',
         'usage.slowestLabels.modelCall': 'Turn {{turn}} model call',
         'usage.slowestLabels.modelCallUnknown': 'Model call',
+        'usage.slowestLabels.turn': 'Turn {{turn}}',
+        'usage.slowestLabels.turnUnknown': 'Turn',
         'usage.table.rowLimitSummary': 'Showing {{visible}} of {{total}} rows',
         'usage.table.showAllRows': 'Show all {{count}} rows',
         'usage.table.showFewerRows': 'Show first {{count}} rows',
@@ -306,6 +308,8 @@ const USAGE_LOCALE_REQUIRED_KEYS = [
   'usage.slowestKinds.turn',
   'usage.slowestLabels.modelCall',
   'usage.slowestLabels.modelCallUnknown',
+  'usage.slowestLabels.turn',
+  'usage.slowestLabels.turnUnknown',
 ];
 
 function getLocaleValue(messages: unknown, key: string): unknown {
@@ -1460,13 +1464,16 @@ describe('Session usage report UI components', () => {
     });
 
     expect(container.textContent).toContain('Slow spans are derived from recorded turn, model, and tool timestamps');
-    expect(container.textContent).toContain('turn 2');
+    // Built from `turnIndex: 2`, not the report's own `label: 'turn 2'`, which
+    // is hard-coded English numbered from zero.
+    expect(container.textContent).toContain('Turn 3');
+    expect(container.textContent).not.toContain('turn 2');
     expect(container.textContent).toContain('1m 35s');
     expect(container.textContent).toContain('Redacted');
     expect(container.textContent).not.toContain('secret shell command');
 
     const turnLink = container.querySelector<HTMLButtonElement>('.session-usage-panel__turn-link');
-    expect(turnLink?.textContent).toBe('turn 2');
+    expect(turnLink?.textContent).toBe('Turn 3');
     act(() => {
       turnLink?.dispatchEvent(new dom.window.MouseEvent('click', { bubbles: true }));
     });
@@ -1574,7 +1581,13 @@ describe('Session usage report UI components', () => {
       slowestTab?.dispatchEvent(new dom.window.MouseEvent('click', { bubbles: true }));
     });
 
-    expect(container.textContent).toContain('Turn 4 model call');
+    /*
+     * The same number the jump below asks for. This test asserted `Turn 4`
+     * here and `turnIndex: 5` there, four lines apart, and the disagreement
+     * was the defect: the report indexes Turns from zero, every other reader
+     * adds one, and only this label did not.
+     */
+    expect(container.textContent).toContain('Turn 5 model call');
     expect(container.textContent).toContain('Model call');
     expect(container.textContent).not.toContain('gpt-5.4');
     expect(container.querySelector('[data-tooltip="Model call in this turn. Model: gpt-5.4. Jump to this turn"]'))
diff --git a/src/web-ui/src/flow_chat/components/usage/SessionUsageModal.appearance.ts b/src/web-ui/src/flow_chat/components/usage/SessionUsageModal.appearance.ts
new file mode 100644
index 0000000000..8ea62b78c9
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/usage/SessionUsageModal.appearance.ts
@@ -0,0 +1,8 @@
+import type { AppearanceSurfaceDescriptor } from '@/infrastructure/appearance';
+
+export const sessionUsageModalAppearanceDescriptor: AppearanceSurfaceDescriptor = {
+  id: 'session-usage-modal',
+  parts: [
+    { id: 'content' },
+  ],
+};
diff --git a/src/web-ui/src/flow_chat/components/usage/SessionUsageModal.scss b/src/web-ui/src/flow_chat/components/usage/SessionUsageModal.scss
new file mode 100644
index 0000000000..0d9197629e
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/usage/SessionUsageModal.scss
@@ -0,0 +1,24 @@
+@use '../../../component-library/styles/tokens' as *;
+
+/*
+ * The card was drawn to sit in the transcript: side margins that line it up
+ * with the message column, and a frame that separates it from the messages
+ * around it. Inside a dialog both are wrong — the margins indent it from a
+ * surface that is already inset, and the frame draws a box inside a box.
+ *
+ * Its own `padding` is kept, and becomes the dialog's inset. It is the spacing
+ * the report was drawn with, and it is equal on all four sides, which neither
+ * of the dialog's own options is: `.modal__content` ships `padding: 0`, and
+ * `contentInset` sets `padding-inline` only.
+ *
+ * Everything else inside the card is left exactly as the transcript renders
+ * it, which is the point of reusing the component rather than restyling it.
+ */
+.session-usage-modal__content {
+  .session-usage-report-card {
+    margin: 0;
+    border: none;
+    background: none;
+    box-shadow: none;
+  }
+}
diff --git a/src/web-ui/src/flow_chat/components/usage/SessionUsageModal.test.tsx b/src/web-ui/src/flow_chat/components/usage/SessionUsageModal.test.tsx
new file mode 100644
index 0000000000..b30331e21a
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/usage/SessionUsageModal.test.tsx
@@ -0,0 +1,140 @@
+// @vitest-environment jsdom
+
+/**
+ * The two things the overlay does that the service cannot be asked about: it
+ * takes Escape away from the container, and opening the panel closes it.
+ */
+
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { SessionUsageReport } from '@/infrastructure/api/service-api/SessionAPI';
+import { isChatPopupActive } from '../chatPopupState';
+import {
+  closeSessionUsageModal,
+  getSessionUsageModalState,
+  openSessionUsageModal,
+  showSessionUsageModalReport,
+} from './sessionUsageModalState';
+import { SessionUsageModal } from './SessionUsageModal';
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+const mocks = vi.hoisted(() => ({ openSessionUsagePanel: vi.fn() }));
+vi.mock('../../services/openSessionUsageReport', () => ({
+  openSessionUsagePanel: mocks.openSessionUsagePanel,
+}));
+
+vi.mock('react-i18next', async () => {
+  const actual = await vi.importActual<typeof import('react-i18next')>('react-i18next');
+  return { ...actual, useTranslation: () => ({ t: (key: string) => key }) };
+});
+
+const report = (): SessionUsageReport => ({
+  schemaVersion: 1,
+  reportId: 'usage-report-1',
+  sessionId: 'session-1',
+  generatedAt: 100,
+  workspace: { kind: 'local', pathLabel: 'D:/workspace/BitFun' },
+  scope: { kind: 'entire_session', turnCount: 3, includesSubagents: false },
+  coverage: { level: 'complete', available: [], missing: [], notes: [] },
+  time: { accounting: 'approximate', denominator: 'session_wall_time', wallTimeMs: 1000 },
+  tokens: {
+    source: 'token_usage_records',
+    inputTokens: 10,
+    outputTokens: 5,
+    totalTokens: 15,
+    cacheCoverage: 'unavailable',
+  },
+  models: [],
+  tools: [],
+  files: { scope: 'unavailable', files: [] },
+  compression: { compactionCount: 0, manualCompactionCount: 0, automaticCompactionCount: 0 },
+  errors: { totalErrors: 0, toolErrors: 0, modelErrors: 0, examples: [] },
+  slowest: [],
+  privacy: {
+    promptContentIncluded: false,
+    toolInputsIncluded: false,
+    commandOutputsIncluded: false,
+    fileContentsIncluded: false,
+    redactedFields: [],
+  },
+});
+
+describe('SessionUsageModal', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  function showReport() {
+    act(() => {
+      openSessionUsageModal({ sessionId: 'session-1', workspacePath: 'D:/workspace/BitFun' });
+      showSessionUsageModalReport({
+        sessionId: 'session-1',
+        report: report(),
+        markdown: '# Session Usage Report',
+      });
+    });
+  }
+
+  beforeEach(() => {
+    mocks.openSessionUsagePanel.mockReset();
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+    act(() => root.render(<SessionUsageModal />));
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    closeSessionUsageModal();
+  });
+
+  it('renders nothing until there is a report to show', () => {
+    expect(document.querySelector('[data-testid="session-usage-modal"]')).toBeNull();
+    expect(isChatPopupActive()).toBe(false);
+  });
+
+  it('takes Escape away from the container while it is open', () => {
+    /*
+     * The container disables its own Escape shortcut while a chat popup is
+     * active. Without this latch, dismissing a report would also cancel
+     * whatever the session is running.
+     */
+    showReport();
+    expect(isChatPopupActive()).toBe(true);
+
+    act(() => closeSessionUsageModal());
+    expect(isChatPopupActive()).toBe(false);
+  });
+
+  it('gives Escape back when it goes away with the report still open', () => {
+    showReport();
+    act(() => root.unmount());
+    expect(isChatPopupActive()).toBe(false);
+    // The afterEach unmount would otherwise run against a torn-down root.
+    root = createRoot(container);
+  });
+
+  it('hands over to the panel rather than competing with it', async () => {
+    showReport();
+    const details = document.querySelector<HTMLButtonElement>(
+      '.session-usage-report-card__details-button',
+    );
+    expect(details).not.toBeNull();
+
+    await act(async () => {
+      details?.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+      // The panel module is imported on demand.
+      await Promise.resolve();
+    });
+
+    expect(mocks.openSessionUsagePanel).toHaveBeenCalledWith(expect.objectContaining({
+      sessionId: 'session-1',
+      workspacePath: 'D:/workspace/BitFun',
+      markdown: '# Session Usage Report',
+      expand: true,
+    }));
+    expect(getSessionUsageModalState().open).toBe(false);
+  });
+});
diff --git a/src/web-ui/src/flow_chat/components/usage/SessionUsageModal.tsx b/src/web-ui/src/flow_chat/components/usage/SessionUsageModal.tsx
new file mode 100644
index 0000000000..947c42b305
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/usage/SessionUsageModal.tsx
@@ -0,0 +1,92 @@
+/**
+ * The session usage report, as a dismissable overlay.
+ *
+ * Mounted once at the app root, like `ConfirmDialogRenderer`, and driven from
+ * `sessionUsageModalState` — the request that produces a report runs several
+ * layers below any component, and the report is not owned by whichever session
+ * view happens to be mounted.
+ *
+ * The card inside is the same `SessionUsageReportCard` the transcript renders
+ * for reports written by earlier versions, including its own waiting state.
+ */
+
+import React, { useCallback, useEffect, useSyncExternalStore } from 'react';
+import { useTranslation } from 'react-i18next';
+import { Modal } from '@/component-library';
+import type { SessionUsageReport } from '@/infrastructure/api/service-api/SessionAPI';
+import { setChatPopupActive } from '../chatPopupState';
+import { SessionUsageReportCard } from './SessionUsageReportCard';
+import type { SessionUsagePanelTab } from './sessionUsagePanelTypes';
+import {
+  closeSessionUsageModal,
+  getSessionUsageModalState,
+  subscribeSessionUsageModal,
+} from './sessionUsageModalState';
+import './SessionUsageModal.scss';
+
+export const SessionUsageModal: React.FC = () => {
+  const { t } = useTranslation('flow-chat');
+  const state = useSyncExternalStore(subscribeSessionUsageModal, getSessionUsageModalState);
+  const { open, isLoading, report, markdown, sessionId, workspacePath } = state;
+
+  /*
+   * The same latch the slash-command and @-mention popups use. Without it the
+   * container's global Escape shortcut fires alongside the modal's own, and
+   * dismissing a report would cancel whatever the session is running.
+   */
+  useEffect(() => {
+    if (!open) return undefined;
+    setChatPopupActive(true);
+    return () => setChatPopupActive(false);
+  }, [open]);
+
+  const handleOpenDetails = useCallback((
+    detailReport: SessionUsageReport,
+    initialTab?: SessionUsagePanelTab,
+  ) => {
+    void import('../../services/openSessionUsageReport').then(({ openSessionUsagePanel }) => {
+      openSessionUsagePanel({
+        report: detailReport,
+        markdown,
+        sessionId,
+        workspacePath,
+        initialTab,
+        title: t('usage.title'),
+        expand: true,
+      });
+      // The panel is the fuller answer to the same question, so the summary
+      // stops competing with it for the screen.
+      closeSessionUsageModal();
+    });
+  }, [markdown, sessionId, t, workspacePath]);
+
+  if (!open) return null;
+
+  return (
+    <Modal
+      isOpen
+      onClose={closeSessionUsageModal}
+      title={t('usage.title')}
+      size="large"
+      testId="session-usage-modal"
+    >
+      <div
+        className="session-usage-modal__content"
+        data-bf-component="session-usage-modal"
+        data-bf-part="content"
+      >
+        <SessionUsageReportCard
+          report={report}
+          markdown={markdown}
+          generatedAt={report?.generatedAt}
+          isLoading={isLoading}
+          onOpenDetails={report ? handleOpenDetails : undefined}
+        />
+      </div>
+    </Modal>
+  );
+};
+
+SessionUsageModal.displayName = 'SessionUsageModal';
+
+export default SessionUsageModal;
diff --git a/src/web-ui/src/flow_chat/components/usage/SessionUsagePanel.tsx b/src/web-ui/src/flow_chat/components/usage/SessionUsagePanel.tsx
index f8bb478de4..449acafac5 100644
--- a/src/web-ui/src/flow_chat/components/usage/SessionUsagePanel.tsx
+++ b/src/web-ui/src/flow_chat/components/usage/SessionUsagePanel.tsx
@@ -46,6 +46,7 @@ import {
   getUsageExportRedactPathsPreference,
   setUsageExportRedactPathsPreference,
   subscribeUsageExportRedactPathsPreference,
+  getDisplayTurnIndex,
 } from './usageReportUtils';
 import type { SessionUsagePanelTab } from './sessionUsagePanelTypes';
 import './SessionUsagePanel.scss';
@@ -543,10 +544,6 @@ function UsageFileTurnIndexesValue({
   );
 }
 
-function getDisplayTurnIndex(rawTurnIndex: number): number {
-  return Math.max(0, Math.trunc(rawTurnIndex)) + 1;
-}
-
 function getStableFileToolAnchorId(
   scope: SessionUsageReport['files']['scope'],
   file: SessionUsageReport['files']['files'][number]
diff --git a/src/web-ui/src/flow_chat/components/usage/SessionUsageReportCard.scss b/src/web-ui/src/flow_chat/components/usage/SessionUsageReportCard.scss
index 3263bb019f..42ef3b07af 100644
--- a/src/web-ui/src/flow_chat/components/usage/SessionUsageReportCard.scss
+++ b/src/web-ui/src/flow_chat/components/usage/SessionUsageReportCard.scss
@@ -14,7 +14,6 @@
   background: color-mix(in srgb, var(--bf-appearance-token-color-bg-secondary) 82%, var(--bf-appearance-token-color-bg-scene));
   box-shadow: 0 1px 0 color-mix(in srgb, var(--bf-appearance-token-color-text-primary) 4%, transparent) inset;
   color: var(--bf-appearance-token-color-text-primary);
-  animation: slideInUp 0.3s ease;
 
   &--fallback {
     position: relative;
diff --git a/src/web-ui/src/flow_chat/components/usage/sessionUsageModalState.ts b/src/web-ui/src/flow_chat/components/usage/sessionUsageModalState.ts
new file mode 100644
index 0000000000..73d90f8a14
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/usage/sessionUsageModalState.ts
@@ -0,0 +1,107 @@
+/**
+ * The usage report, held for as long as it is on screen and no longer.
+ *
+ * It used to be a `DialogTurn` appended to `session.dialogTurns` and persisted
+ * to the backend as a `local_command` turn. A report about a session is not an
+ * event in it: the turn carried no user message and no model round, and the
+ * backend already answered "is this part of the conversation" with no in six
+ * places — `is_model_visible` and `is_transcript_visible` are both false for
+ * `LocalCommand`, and the usage report excludes its own turns from its own
+ * scope.
+ *
+ * The front end could not keep the same story straight. The turn grew
+ * `dialogTurns` and moved `at(-1)`, which is exactly what follow-output reads
+ * as a Turn arriving, so a report pinned itself to the top of the viewport. And
+ * the filter meant to keep it out of the Turn rail required
+ * `usageReportProvisional`, a flag that `commitLocalUsageReportTurn` deleted on
+ * successful persistence — so it worked until the moment persistence made it
+ * matter, and a `/usage` report then took a numbered Turn slot.
+ *
+ * Reports written by earlier versions are still on disk and still render, in
+ * `UserMessageItem`; only the writer is gone.
+ *
+ * Module state rather than React state because the caller is a service several
+ * layers below any component — the same shape as `chatPopupState.ts`.
+ */
+
+import type { SessionUsageReport } from '@/infrastructure/api/service-api/SessionAPI';
+
+export interface SessionUsageModalState {
+  open: boolean;
+  sessionId: string;
+  workspacePath?: string;
+  /** The request is in flight; the card draws its own waiting state. */
+  isLoading: boolean;
+  report?: SessionUsageReport;
+  /** The rendered report, for copying and for the fallback view. */
+  markdown: string;
+}
+
+const CLOSED: SessionUsageModalState = {
+  open: false,
+  sessionId: '',
+  isLoading: false,
+  markdown: '',
+};
+
+let state: SessionUsageModalState = CLOSED;
+const listeners = new Set<() => void>();
+
+function setState(next: SessionUsageModalState) {
+  state = next;
+  listeners.forEach(listener => listener());
+}
+
+/*
+ * Identity is stable while nothing changes, which `useSyncExternalStore`
+ * requires of a snapshot — it re-reads on every render and treats a new object
+ * as a change.
+ */
+export function getSessionUsageModalState(): SessionUsageModalState {
+  return state;
+}
+
+export function subscribeSessionUsageModal(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => { listeners.delete(listener); };
+}
+
+/** Open on the waiting state, before the report exists. */
+export function openSessionUsageModal(params: {
+  sessionId: string;
+  workspacePath?: string;
+}): void {
+  setState({
+    open: true,
+    sessionId: params.sessionId,
+    workspacePath: params.workspacePath,
+    isLoading: true,
+    markdown: '',
+  });
+}
+
+/**
+ * Show the report that arrived.
+ *
+ * Ignored if the modal has been closed in the meantime: the reader dismissing
+ * the wait is them saying they no longer want it, and a request already in
+ * flight cannot be recalled.
+ */
+export function showSessionUsageModalReport(params: {
+  sessionId: string;
+  report: SessionUsageReport;
+  markdown: string;
+}): void {
+  if (!state.open || state.sessionId !== params.sessionId) return;
+  setState({
+    ...state,
+    isLoading: false,
+    report: params.report,
+    markdown: params.markdown,
+  });
+}
+
+export function closeSessionUsageModal(): void {
+  if (!state.open) return;
+  setState(CLOSED);
+}
diff --git a/src/web-ui/src/flow_chat/components/usage/usageReportUtils.test.ts b/src/web-ui/src/flow_chat/components/usage/usageReportUtils.test.ts
index 770c71ca96..0a63b447c1 100644
--- a/src/web-ui/src/flow_chat/components/usage/usageReportUtils.test.ts
+++ b/src/web-ui/src/flow_chat/components/usage/usageReportUtils.test.ts
@@ -9,6 +9,7 @@ import {
   getModelHelp,
   getModelLabel,
   getSlowSpanHelp,
+  getDisplayTurnIndex,
   getSlowSpanLabel,
   getTopFiles,
 } from './usageReportUtils';
@@ -26,6 +27,8 @@ const t = (key: string, options?: Record<string, unknown>): string => {
   if (key === 'usage.help.slowestModelCall') return `Model call: ${options?.model}`;
   if (key === 'usage.slowestLabels.modelCall') return `Turn ${options?.turn} model call`;
   if (key === 'usage.slowestLabels.modelCallUnknown') return 'Model call';
+  if (key === 'usage.slowestLabels.turn') return `Turn ${options?.turn}`;
+  if (key === 'usage.slowestLabels.turnUnknown') return 'Turn';
   if (key === 'usage.redacted') return 'Redacted';
   return key;
 };
@@ -164,7 +167,46 @@ describe('usageReportUtils', () => {
       redacted: false,
       turnIndex: 3,
       modelIdSource: 'inferred_session_model',
-    }, t)).toBe('Turn 3 model call');
+    }, t)).toBe('Turn 4 model call');
+  });
+
+  it('numbers a slow span the way its own jump does', () => {
+    /*
+     * The report indexes Turns from zero and every reader adds one. This label
+     * did not, so a row read "Turn 7" while clicking it asked for Turn 8 — the
+     * Turn the rail, numbering the same way, also calls 8. Label and
+     * destination have to come from the same function, so here they do.
+     */
+    for (const rawTurnIndex of [0, 3, 7]) {
+      expect(getSlowSpanLabel({
+        label: 'gpt-5.4',
+        kind: 'model',
+        durationMs: 100,
+        redacted: false,
+        turnIndex: rawTurnIndex,
+      }, t)).toBe(`Turn ${getDisplayTurnIndex(rawTurnIndex)} model call`);
+    }
+    // And the offset itself: zero-based in, one-based out, never negative.
+    expect(getDisplayTurnIndex(0)).toBe(1);
+    expect(getDisplayTurnIndex(7)).toBe(8);
+    expect(getDisplayTurnIndex(-4)).toBe(1);
+  });
+
+  it('builds a Turn span label rather than rendering the report\'s own', () => {
+    /*
+     * The report synthesises this one itself — `format!("turn {}", turn_index)`
+     * — so it arrives hard-coded in English and numbered from zero. Rendered
+     * verbatim it read "turn 7" next to a row this file had numbered 8.
+     */
+    const span = {
+      label: 'turn 7',
+      kind: 'turn' as const,
+      durationMs: 100,
+      redacted: false,
+      turnIndex: 7,
+    };
+    expect(getSlowSpanLabel(span, t)).toBe('Turn 8');
+    expect(getSlowSpanLabel({ ...span, turnIndex: undefined }, t)).toBe('Turn');
   });
 
   it('returns model identity tooltip copy when the source is inferred or legacy', () => {
diff --git a/src/web-ui/src/flow_chat/components/usage/usageReportUtils.ts b/src/web-ui/src/flow_chat/components/usage/usageReportUtils.ts
index cff236e9b3..c430ae4253 100644
--- a/src/web-ui/src/flow_chat/components/usage/usageReportUtils.ts
+++ b/src/web-ui/src/flow_chat/components/usage/usageReportUtils.ts
@@ -201,6 +201,19 @@ export function getModelHelp(
   return undefined;
 }
 
+/**
+ * The Turn number a reader sees, from the report's own zero-based index.
+ *
+ * Exported because the report is read in two files and the offset used to be a
+ * convention rather than a function: every call site in the panel applied it,
+ * `getSlowSpanLabel` did not, and a row therefore read "Turn 7" while its own
+ * jump asked for Turn 8 — which is the Turn the rail, numbering the same way,
+ * calls 8. The label was the outlier; the navigation was right.
+ */
+export function getDisplayTurnIndex(rawTurnIndex: number): number {
+  return Math.max(0, Math.trunc(rawTurnIndex)) + 1;
+}
+
 export function getSlowSpanLabel(
   span: SessionUsageReport['slowest'][number],
   t: Translator
@@ -210,9 +223,21 @@ export function getSlowSpanLabel(
   }
   if (span.kind === 'model') {
     return typeof span.turnIndex === 'number' && Number.isFinite(span.turnIndex)
-      ? t('usage.slowestLabels.modelCall', { turn: span.turnIndex })
+      ? t('usage.slowestLabels.modelCall', { turn: getDisplayTurnIndex(span.turnIndex) })
       : t('usage.slowestLabels.modelCallUnknown');
   }
+  /*
+   * A Turn span's `label` is the one display string the report synthesises
+   * itself — `format!("turn {}", turn.turn_index)` — so it arrives hard-coded
+   * in English and numbered from zero, and rendering it put "turn 7" beside a
+   * row this file had already numbered 8. Built here instead, from the same
+   * index and the same offset as every other reader.
+   */
+  if (span.kind === 'turn') {
+    return typeof span.turnIndex === 'number' && Number.isFinite(span.turnIndex)
+      ? t('usage.slowestLabels.turn', { turn: getDisplayTurnIndex(span.turnIndex) })
+      : t('usage.slowestLabels.turnUnknown');
+  }
   return span.label;
 }
 
diff --git a/src/web-ui/src/flow_chat/events/flowchatNavigation.ts b/src/web-ui/src/flow_chat/events/flowchatNavigation.ts
index db94e9d953..987c1eee2a 100644
--- a/src/web-ui/src/flow_chat/events/flowchatNavigation.ts
+++ b/src/web-ui/src/flow_chat/events/flowchatNavigation.ts
@@ -3,11 +3,8 @@
  */
 
 export const FLOWCHAT_FOCUS_ITEM_EVENT = 'flowchat:focus-item';
-export const FLOWCHAT_PIN_TURN_TO_TOP_EVENT = 'flowchat:pin-turn-to-top';
 
 export type FlowChatFocusItemSource = 'btw-back' | 'usage-report' | 'background-activity';
-export type FlowChatPinTurnToTopSource = 'send-message' | 'usage-report';
-export type FlowChatPinTurnToTopMode = 'transient' | 'sticky-latest';
 
 export interface FlowChatFocusItemRequest {
   sessionId: string;
@@ -19,12 +16,35 @@ export interface FlowChatFocusItemRequest {
   source?: FlowChatFocusItemSource;
 }
 
-export interface FlowChatPinTurnToTopRequest {
+/**
+ * A message has been submitted to a Session from the composer.
+ *
+ * The transcript may be showing a history window the reader navigated to, and
+ * the Turn they just sent is not in it. Session growth alone cannot ask for
+ * that window to be given up — a Turn arriving from anywhere else must leave a
+ * reader where they are — so the submission says so itself.
+ */
+export const FLOWCHAT_MESSAGE_SUBMITTED_EVENT = 'flowchat:message-submitted';
+
+export interface FlowChatMessageSubmittedRequest {
+  sessionId: string;
+}
+
+/**
+ * Turns have been rolled back out of a Session, and the transcript now ends
+ * somewhere it did not a moment ago.
+ *
+ * The ledger cannot say this by itself. A shorter `dialogTurns` is also what a
+ * history window re-cut and a hydration merge look like, and there are two
+ * dozen writers of that array — so, as with a submission, the actor announces
+ * it rather than leaving the viewport to infer an action from a count.
+ */
+export const FLOWCHAT_TURNS_ROLLED_BACK_EVENT = 'flowchat:turns-rolled-back';
+
+export interface FlowChatTurnsRolledBackRequest {
   sessionId: string;
-  turnId: string;
-  behavior?: ScrollBehavior;
-  source?: FlowChatPinTurnToTopSource;
-  pinMode?: FlowChatPinTurnToTopMode;
+  /** First Turn index removed; everything from here on is gone. */
+  fromTurnIndex: number;
 }
 
 /**
diff --git a/src/web-ui/src/flow_chat/hooks/useAutoScroll.ts b/src/web-ui/src/flow_chat/hooks/useAutoScroll.ts
index 14a3e3c889..b31ec3b70b 100644
--- a/src/web-ui/src/flow_chat/hooks/useAutoScroll.ts
+++ b/src/web-ui/src/flow_chat/hooks/useAutoScroll.ts
@@ -5,6 +5,7 @@
  */
 
 import { useRef, useCallback, useState, useEffect, RefObject } from 'react';
+import { getMotionAwareScrollBehavior } from '../utils/motionPreference';
 
 interface UseAutoScrollOptions {
   enabled?: boolean;
@@ -49,7 +50,9 @@ export const useAutoScroll = (
     
     // Force scroll, or auto-scroll when user is at the bottom.
     if (force || (enabled && !isUserScrolledUp)) {
-      messagesEndRef.current.scrollIntoView({ behavior: 'smooth' });
+      messagesEndRef.current.scrollIntoView({
+        behavior: force ? getMotionAwareScrollBehavior('smooth') : 'auto',
+      });
       
       // Reset the user-scrolled-up state on force.
       if (force) {
@@ -94,4 +97,3 @@ export const useAutoScroll = (
     shouldShowScrollButton
   };
 };
-
diff --git a/src/web-ui/src/flow_chat/hooks/useMessageSender.ts b/src/web-ui/src/flow_chat/hooks/useMessageSender.ts
index 54be293991..f6d5b4da25 100644
--- a/src/web-ui/src/flow_chat/hooks/useMessageSender.ts
+++ b/src/web-ui/src/flow_chat/hooks/useMessageSender.ts
@@ -20,6 +20,10 @@ import type {
 import { createLogger } from '@/shared/utils/logger';
 import { formatContextForPrompt } from '@/shared/utils/contextPrompt';
 import { buildImagePayload } from '../utils/imagePayload';
+import {
+  FLOWCHAT_MESSAGE_SUBMITTED_EVENT,
+  type FlowChatMessageSubmittedRequest,
+} from '../events/flowchatNavigation';
 import {
   composerPresentationSessionReferences,
   type ComposerPresentation,
@@ -248,6 +252,16 @@ export function useMessageSender(props: UseMessageSenderProps): UseMessageSender
       onExitTemplateMode?.();
 
       onSuccess?.(trimmedMessage);
+      /*
+       * The transcript may be showing a history window this Turn is not in, and
+       * only the submission knows that showing it was asked for. Announced
+       * rather than returned: the composer and the transcript are siblings, and
+       * every host that sends through this hook gets the behaviour.
+       */
+      window.dispatchEvent(new CustomEvent<FlowChatMessageSubmittedRequest>(
+        FLOWCHAT_MESSAGE_SUBMITTED_EVENT,
+        { detail: { sessionId } },
+      ));
       log.info('Message sent successfully', {
         sessionId,
         agentType: agentTypeForSend,
diff --git a/src/web-ui/src/flow_chat/hooks/useThreadGoalController.ts b/src/web-ui/src/flow_chat/hooks/useThreadGoalController.ts
index 7de061f39b..22ef834bc1 100644
--- a/src/web-ui/src/flow_chat/hooks/useThreadGoalController.ts
+++ b/src/web-ui/src/flow_chat/hooks/useThreadGoalController.ts
@@ -6,9 +6,9 @@ import type { Session } from '../types/flow-chat';
 import { flowChatStore } from '../store/FlowChatStore';
 import {
   dismissResumePrompt,
-  isResumePromptDismissed,
+  resumePromptKey,
+  shouldOpenResumePrompt,
   threadGoalActionsForStatus,
-  threadGoalStatusNeedsResumePrompt,
   type ThreadGoalUiAction,
 } from '../services/threadGoalActions';
 import { parseGoalCommand } from '../services/goalCommandParser';
@@ -105,12 +105,13 @@ function useStableThreadGoalSnapshot(sessionId: string | undefined): ThreadGoalS
 
 export function useThreadGoalController(
   session: Session | undefined,
-  options?: { isBtwSession?: boolean; disabled?: boolean }
+  options?: { isBtwSession?: boolean; disabled?: boolean; sceneActive?: boolean }
 ): ThreadGoalController {
   const { t } = useTranslation('flow-chat');
   const sessionId = session?.sessionId;
   const isBtwSession = Boolean(options?.isBtwSession);
   const disabled = isBtwSession || Boolean(options?.disabled);
+  const sceneActive = options?.sceneActive ?? true;
 
   const storeGoal = useStableThreadGoalSnapshot(sessionId);
 
@@ -161,30 +162,36 @@ export function useThreadGoalController(
     void refreshGoal();
   }, [session?.isHistorical, sessionId, disabled, refreshGoal]);
 
-  const goalId = goal?.goalId;
-  const goalStatus = goal?.status;
-  const goalUpdatedAt = goal?.updatedAt;
+  /** Which session the user is actually looking at through this controller. */
+  const visitKey = sceneActive && sessionId ? sessionId : null;
+
+  /**
+   * Every scene stays mounted, so a paused goal must not raise its modal over
+   * whatever scene is in front. Leaving this session — or opening another one —
+   * retracts the prompt and re-arms the gate, which brings the prompt back when
+   * the user opens the paused session again. Declared before the effect below
+   * so a new visit re-arms first and can then re-open in the same commit.
+   */
+  useEffect(() => {
+    lastResumePromptKey.current = null;
+    setResumeOpen(false);
+  }, [visitKey]);
 
   useEffect(() => {
     if (
-      disabled
-      || !sessionId
-      || !goalId
-      || !goalStatus
-      || !threadGoalStatusNeedsResumePrompt(goalStatus)
+      !shouldOpenResumePrompt({
+        sessionId,
+        goal,
+        sceneActive,
+        disabled,
+        lastPromptedKey: lastResumePromptKey.current,
+      })
     ) {
       return;
     }
-    if (!goal || isResumePromptDismissed(sessionId, goal)) {
-      return;
-    }
-    const key = `${goalId}:${goalUpdatedAt ?? 0}:${goalStatus}`;
-    if (lastResumePromptKey.current === key) {
-      return;
-    }
-    lastResumePromptKey.current = key;
+    lastResumePromptKey.current = resumePromptKey(goal);
     setResumeOpen(true);
-  }, [disabled, goal, goalId, goalStatus, goalUpdatedAt, sessionId]);
+  }, [disabled, goal, sceneActive, sessionId]);
 
   const openMenu = useCallback(() => {
     setMenuOpen(true);
diff --git a/src/web-ui/src/flow_chat/hooks/useVisibleTaskInfo.ts b/src/web-ui/src/flow_chat/hooks/useVisibleTaskInfo.ts
deleted file mode 100644
index e2033a2c92..0000000000
--- a/src/web-ui/src/flow_chat/hooks/useVisibleTaskInfo.ts
+++ /dev/null
@@ -1,186 +0,0 @@
-/**
- * Hook to detect the nearest Task tool item above the current viewport.
- * Used to show a sticky indicator of which Task the user is currently reading.
- *
- * - Scans virtualItems for FlowToolItem entries with toolName === 'Task'.
- * - Uses the DOM position of rendered Task items to determine which one is
- *   just above the viewport top.
- * - Returns the Task description and a callback to scroll to it.
- */
-
-import { useRef, useCallback, useState, useEffect } from 'react';
-import type { VirtualItem } from '../store/modernFlowChatStore';
-import type { FlowToolItem } from '../types/flow-chat';
-import { getEffectiveToolName, projectEffectiveToolItem } from '../utils/toolInvocationIdentity';
-
-const VIEWPORT_TOP_OFFSET_PX = 57; // Keep in sync with PINNED_TURN_VIEWPORT_OFFSET_PX.
-const TASK_TOOL_NAME = 'Task';
-
-export interface VisibleTaskInfo {
-  /** The virtual item index of the Task tool. */
-  virtualIndex: number;
-  /** The FlowItem id of the Task tool. */
-  itemId: string;
-  /** Display label for the Task (description or prompt). */
-  label: string;
-  /** The turnId this Task belongs to. */
-  turnId: string;
-}
-
-interface UseVisibleTaskInfoOptions {
-  scrollerRef: React.RefObject<HTMLElement | null>;
-  virtualItems: VirtualItem[];
-}
-
-interface UseVisibleTaskInfoReturn {
-  visibleTaskInfo: VisibleTaskInfo | null;
-  /** Scroll the list so the indicated Task is at the viewport top. */
-  scrollToTask: () => void;
-}
-
-function getTaskLabel(toolItem: FlowToolItem): string {
-  const input = projectEffectiveToolItem(toolItem).toolCall?.input;
-  if (!input) return '';
-  const desc = input.description || input.prompt || input.task || '';
-  return typeof desc === 'string' ? desc.trim() : '';
-}
-
-function findTaskVirtualItems(virtualItems: VirtualItem[]): Array<{
-  index: number;
-  itemId: string;
-  turnId: string;
-  label: string;
-}> {
-  const result: Array<{ index: number; itemId: string; turnId: string; label: string }> = [];
-
-  for (let i = 0; i < virtualItems.length; i++) {
-    const vItem = virtualItems[i];
-    if (vItem.type !== 'model-round') continue;
-
-    const round = vItem.data;
-    for (const flowItem of round.items) {
-      if (flowItem.type === 'tool' && getEffectiveToolName(flowItem as FlowToolItem) === TASK_TOOL_NAME) {
-        result.push({
-          index: i,
-          itemId: flowItem.id,
-          turnId: vItem.turnId,
-          label: getTaskLabel(flowItem as FlowToolItem),
-        });
-      }
-    }
-  }
-
-  return result;
-}
-
-export function useVisibleTaskInfo(options: UseVisibleTaskInfoOptions): UseVisibleTaskInfoReturn {
-  const { scrollerRef, virtualItems } = options;
-  const [visibleTaskInfo, setVisibleTaskInfo] = useState<VisibleTaskInfo | null>(null);
-  const lastVisibleRef = useRef<VisibleTaskInfo | null>(null);
-  const taskItemsRef = useRef(findTaskVirtualItems(virtualItems));
-
-  // Keep task items cache in sync without triggering re-renders.
-  useEffect(() => {
-    taskItemsRef.current = findTaskVirtualItems(virtualItems);
-  }, [virtualItems]);
-
-  const checkVisibleTask = useCallback(() => {
-    const scroller = scrollerRef.current;
-    if (!scroller) return;
-
-    const taskItems = taskItemsRef.current;
-    if (taskItems.length === 0) {
-      if (lastVisibleRef.current !== null) {
-        lastVisibleRef.current = null;
-        setVisibleTaskInfo(null);
-      }
-      return;
-    }
-
-    const scrollerRect = scroller.getBoundingClientRect();
-    const viewportTop = scrollerRect.top + VIEWPORT_TOP_OFFSET_PX;
-
-    // Find the last Task whose DOM element top is above the viewport top.
-    let matched: VisibleTaskInfo | null = null;
-
-    for (let i = taskItems.length - 1; i >= 0; i--) {
-      const task = taskItems[i];
-      const element = scroller.querySelector<HTMLElement>(
-        `.flowchat-flow-item[data-flow-item-id="${CSS.escape(task.itemId)}"][data-tool-name="${TASK_TOOL_NAME}"]`,
-      );
-      if (!element) continue;
-
-      const rect = element.getBoundingClientRect();
-      // Task element must be above or crossing the viewport top.
-      if (rect.top <= viewportTop) {
-        matched = {
-          virtualIndex: task.index,
-          itemId: task.itemId,
-          label: task.label,
-          turnId: task.turnId,
-        };
-        break;
-      }
-    }
-
-    if (
-      matched?.itemId !== lastVisibleRef.current?.itemId ||
-      matched?.label !== lastVisibleRef.current?.label
-    ) {
-      lastVisibleRef.current = matched;
-      setVisibleTaskInfo(matched);
-    }
-  }, [scrollerRef]);
-
-  useEffect(() => {
-    const scroller = scrollerRef.current;
-    if (!scroller) return;
-
-    let rafId: number | null = null;
-    const throttledCheck = () => {
-      if (rafId) return;
-      rafId = requestAnimationFrame(() => {
-        checkVisibleTask();
-        rafId = null;
-      });
-    };
-
-    scroller.addEventListener('scroll', throttledCheck, { passive: true });
-    checkVisibleTask();
-
-    return () => {
-      scroller.removeEventListener('scroll', throttledCheck);
-      if (rafId) cancelAnimationFrame(rafId);
-    };
-  }, [checkVisibleTask, scrollerRef]);
-
-  // Reset when session / items change.
-  useEffect(() => {
-    lastVisibleRef.current = null;
-    setVisibleTaskInfo(null);
-  }, [virtualItems]);
-
-  const scrollToTask = useCallback(() => {
-    const info = lastVisibleRef.current ?? visibleTaskInfo;
-    if (!info) return;
-
-    const scroller = scrollerRef.current;
-    if (!scroller) return;
-
-    const element = scroller.querySelector<HTMLElement>(
-      `.flowchat-flow-item[data-flow-item-id="${CSS.escape(info.itemId)}"][data-tool-name="${TASK_TOOL_NAME}"]`,
-    );
-    if (!element) return;
-
-    const scrollerRect = scroller.getBoundingClientRect();
-    const elementRect = element.getBoundingClientRect();
-    const offset = elementRect.top - scrollerRect.top - VIEWPORT_TOP_OFFSET_PX + scroller.scrollTop;
-
-    scroller.scrollTo({ top: offset, behavior: 'smooth' });
-  }, [visibleTaskInfo, scrollerRef]);
-
-  return {
-    visibleTaskInfo,
-    scrollToTask,
-  };
-}
diff --git a/src/web-ui/src/flow_chat/services/AgenticEventListener.ts b/src/web-ui/src/flow_chat/services/AgenticEventListener.ts
index 7d358e1c48..76addd3e18 100644
--- a/src/web-ui/src/flow_chat/services/AgenticEventListener.ts
+++ b/src/web-ui/src/flow_chat/services/AgenticEventListener.ts
@@ -24,6 +24,7 @@ import type {
   DeepReviewQueueStateChangedEvent,
   AcpContextUsageUpdatedEvent,
   OpenBuiltInBrowserEvent,
+  InterruptedDialogTurnEvent,
 } from '@/infrastructure/api/service-api/AgentAPI';
 import { createLogger } from '@/shared/utils/logger';
 
@@ -48,6 +49,8 @@ export interface AgenticEventCallbacks {
   onDialogTurnCompleted?: (event: AgenticEvent) => void;
   onDialogTurnFailed?: (event: AgenticEvent) => void;
   onDialogTurnCancelled?: (event: AgenticEvent) => void;
+  onDialogTurnInterrupted?: (event: InterruptedDialogTurnEvent) => void;
+  onDialogTurnRecovered?: (event: InterruptedDialogTurnEvent) => void;
   onTokenUsageUpdated?: (event: AgenticEvent) => void;
   onAcpContextUsageUpdated?: (event: AcpContextUsageUpdatedEvent) => void;
   onContextCompressionStarted?: (event: AgenticEvent) => void;
@@ -204,6 +207,22 @@ export class AgenticEventListener {
         this.unlistenFunctions.push(unlisten);
       }
 
+      if (callbacks.onDialogTurnInterrupted) {
+        const unlisten = agentAPI.onDialogTurnInterrupted((event) => {
+          logger.debug('Dialog turn interrupted:', event);
+          callbacks.onDialogTurnInterrupted?.(event);
+        });
+        this.unlistenFunctions.push(unlisten);
+      }
+
+      if (callbacks.onDialogTurnRecovered) {
+        const unlisten = agentAPI.onDialogTurnRecovered((event) => {
+          logger.debug('Dialog turn recovered:', event);
+          callbacks.onDialogTurnRecovered?.(event);
+        });
+        this.unlistenFunctions.push(unlisten);
+      }
+
       if (callbacks.onTokenUsageUpdated) {
         const unlisten = agentAPI.onTokenUsageUpdated((event) => {
           logger.debug('Token usage updated:', event);
@@ -368,6 +387,12 @@ export class AgenticEventListener {
       case 'agentic://dialog-turn-cancelled':
         callbacks.onDialogTurnCancelled?.(payload as AgenticEvent);
         break;
+      case 'agentic://dialog-turn-interrupted':
+        callbacks.onDialogTurnInterrupted?.(payload as unknown as InterruptedDialogTurnEvent);
+        break;
+      case 'agentic://dialog-turn-recovered':
+        callbacks.onDialogTurnRecovered?.(payload as unknown as InterruptedDialogTurnEvent);
+        break;
       case 'agentic://token-usage-updated':
         callbacks.onTokenUsageUpdated?.(payload as AgenticEvent);
         break;
diff --git a/src/web-ui/src/flow_chat/services/FlowChatManager.test.ts b/src/web-ui/src/flow_chat/services/FlowChatManager.test.ts
index 6f687e6aaa..89e09d08ec 100644
--- a/src/web-ui/src/flow_chat/services/FlowChatManager.test.ts
+++ b/src/web-ui/src/flow_chat/services/FlowChatManager.test.ts
@@ -1,5 +1,10 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { FlowChatManager } from './FlowChatManager';
+import {
+  activateSurface,
+  isSurfaceChangedError,
+  resetDeviceSurfaceForTest,
+} from '@/infrastructure/peer-device/deviceSurface';
 
 const storeMocks = vi.hoisted(() => ({
   store: {} as any,
@@ -12,7 +17,9 @@ const storeMocks = vi.hoisted(() => ({
 }));
 
 vi.mock('./ProcessingStatusManager', () => ({
-  processingStatusManager: {},
+  processingStatusManager: {
+    clearSurface: vi.fn(),
+  },
 }));
 
 vi.mock('./flow-chat-manager/PeerSessionRefreshModule', () => ({
@@ -46,7 +53,9 @@ vi.mock('@/infrastructure/api/service-api/ACPClientAPI', () => ({
 }));
 
 vi.mock('../state-machine', () => ({
-  stateMachineManager: {},
+  stateMachineManager: {
+    clearSurface: vi.fn(),
+  },
 }));
 
 vi.mock('./EventBatcher', () => ({
@@ -85,6 +94,9 @@ vi.mock('./flow-chat-manager', () => ({
   cancelSessionTask: vi.fn(),
   installPendingQueueDrainListener: vi.fn(),
   drainPendingQueue: vi.fn(),
+  pendingQueueManager: {
+    clearSurface: vi.fn(),
+  },
   initializeEventListeners: storeMocks.initializeEventListeners,
   processBatchedEvents: vi.fn(),
   addDialogTurn: vi.fn(),
@@ -133,6 +145,7 @@ function createHistoricalSession(overrides: Record<string, unknown> = {}) {
 
 describe('FlowChatManager initialization', () => {
   beforeEach(() => {
+    resetDeviceSurfaceForTest();
     (FlowChatManager as any).instance = undefined;
     vi.clearAllMocks();
     storeMocks.eventBatchers.length = 0;
@@ -183,6 +196,7 @@ describe('FlowChatManager initialization', () => {
     storeMocks.initializeEventListeners.mockReturnValue(listenerInitialization.promise);
     storeMocks.store = {
       registerPersistUnreadCompletionCallback: vi.fn(),
+      getSurfaceGeneration: vi.fn(() => 0),
       loadSessionMetadataPage: vi.fn(async () => ({
         sessions: [],
         totalTopLevelCount: 0,
@@ -216,6 +230,7 @@ describe('FlowChatManager initialization', () => {
 
     storeMocks.store = {
       registerPersistUnreadCompletionCallback: vi.fn(),
+      getSurfaceGeneration: vi.fn(() => 0),
       loadSessionMetadataPage: vi.fn(() => metadataLoad.promise),
       getState: vi.fn(() => ({
         sessions,
@@ -269,6 +284,7 @@ describe('FlowChatManager initialization', () => {
 
     storeMocks.store = {
       registerPersistUnreadCompletionCallback: vi.fn(),
+      getSurfaceGeneration: vi.fn(() => 0),
       loadSessionMetadataPage: vi.fn(async () => ({
         sessions: [],
         totalTopLevelCount: 2,
@@ -321,6 +337,7 @@ describe('FlowChatManager initialization', () => {
 
     storeMocks.store = {
       registerPersistUnreadCompletionCallback: vi.fn(),
+      getSurfaceGeneration: vi.fn(() => 0),
       loadSessionMetadataPage: vi.fn(async () => ({
         sessions: [],
         totalTopLevelCount: 1,
@@ -369,6 +386,7 @@ describe('FlowChatManager initialization', () => {
 
     storeMocks.store = {
       registerPersistUnreadCompletionCallback: vi.fn(),
+      getSurfaceGeneration: vi.fn(() => 0),
       loadSessionMetadataPage: vi.fn(async (
         workspacePath: string,
       ) => ({
@@ -435,6 +453,7 @@ describe('FlowChatManager initialization', () => {
 
     storeMocks.store = {
       registerPersistUnreadCompletionCallback: vi.fn(),
+      getSurfaceGeneration: vi.fn(() => 0),
       loadSessionMetadataPage: vi.fn(async () => ({
         sessions: [],
         totalTopLevelCount: 2,
@@ -457,4 +476,140 @@ describe('FlowChatManager initialization', () => {
     expect(storeMocks.store.switchSession).toHaveBeenCalledWith('parent-1');
     expect(storeMocks.store.switchSession).not.toHaveBeenCalledWith('subagent-1');
   });
+
+  // The page describes the device it was read from and has already landed in
+  // that surface's own container. Selecting out of it after the window moved
+  // would apply one device's history to another; the device now on screen runs
+  // its own bootstrap.
+  it('abandons a workspace bootstrap when the window switches device mid-load', async () => {
+    const sessions = new Map<string, any>();
+
+    storeMocks.store = {
+      registerPersistUnreadCompletionCallback: vi.fn(),
+      getSurfaceGeneration: vi.fn(() => 0),
+      loadSessionMetadataPage: vi.fn(async () => {
+        activateSurface('device-b');
+        sessions.set('history-1', createHistoricalSession({ historyState: 'ready', isHistorical: false }));
+        return { sessions: [{ sessionId: 'history-1' }], totalTopLevelCount: 1, hasMore: false };
+      }),
+      getState: vi.fn(() => ({ sessions, activeSessionId: null })),
+      loadSessionHistory: vi.fn(async () => undefined),
+      switchSession: vi.fn(),
+    };
+
+    const manager = FlowChatManager.getInstance();
+    await expect(manager.initialize('D:/workspace/BitFun')).rejects.toSatisfy(isSurfaceChangedError);
+
+    expect(storeMocks.store.loadSessionMetadataPage).toHaveBeenCalledTimes(1);
+    expect(storeMocks.store.switchSession).not.toHaveBeenCalled();
+  });
+
+  // The same repository is routinely open at the same path on two devices, so a
+  // request key without the surface handed device A's bootstrap the in-flight
+  // initialization of device B — and A then read back B's session list.
+  it('does not deduplicate initialization for the same path across devices', async () => {
+    const metadataLoads = [
+      createDeferred<Record<string, unknown>>(),
+      createDeferred<Record<string, unknown>>(),
+    ];
+    const peerSessions = new Map<string, any>();
+    let activeSessionId: string | null = null;
+
+    storeMocks.store = {
+      registerPersistUnreadCompletionCallback: vi.fn(),
+      getSurfaceGeneration: vi.fn(() => 0),
+      loadSessionMetadataPage: vi.fn(
+        () => metadataLoads[storeMocks.store.loadSessionMetadataPage.mock.calls.length - 1].promise,
+      ),
+      getState: vi.fn(() => ({ sessions: peerSessions, activeSessionId })),
+      loadSessionHistory: vi.fn(async () => undefined),
+      switchSession: vi.fn((sessionId: string) => {
+        activeSessionId = sessionId;
+      }),
+    };
+
+    const manager = FlowChatManager.getInstance();
+    const localInitialize = manager.initialize('D:/workspace/BitFun');
+    await flushAsyncWork();
+    expect(storeMocks.store.loadSessionMetadataPage).toHaveBeenCalledTimes(1);
+
+    activateSurface('device-b');
+    const peerInitialize = manager.initialize('D:/workspace/BitFun');
+    await flushAsyncWork();
+    // A shared key would have handed this bootstrap the local device's request.
+    expect(storeMocks.store.loadSessionMetadataPage).toHaveBeenCalledTimes(2);
+
+    peerSessions.set('peer-1', createHistoricalSession({
+      sessionId: 'peer-1',
+      historyState: 'ready',
+      isHistorical: false,
+    }));
+    metadataLoads[0].resolve({ sessions: [], totalTopLevelCount: 0, hasMore: false });
+    metadataLoads[1].resolve({
+      sessions: [{ sessionId: 'peer-1' }],
+      totalTopLevelCount: 1,
+      hasMore: false,
+    });
+
+    // The local bootstrap started under a surface this window left; it must not
+    // adopt the peer's answer.
+    await expect(localInitialize).rejects.toSatisfy(isSurfaceChangedError);
+    await expect(peerInitialize).resolves.toBe(true);
+    expect(storeMocks.store.switchSession).toHaveBeenCalledTimes(1);
+    expect(storeMocks.store.switchSession).toHaveBeenCalledWith('peer-1');
+  });
+
+  it('restores history for a session that is already active but still metadata-only', async () => {
+    const activeSession = createHistoricalSession({ sessionId: 'active-1' });
+    const sessions = new Map<string, any>([['active-1', activeSession]]);
+
+    storeMocks.store = {
+      registerPersistUnreadCompletionCallback: vi.fn(),
+      getSurfaceGeneration: vi.fn(() => 0),
+      loadSessionMetadataPage: vi.fn(async () => ({
+        sessions: [{ sessionId: 'active-1' }],
+        totalTopLevelCount: 1,
+        hasMore: false,
+      })),
+      getState: vi.fn(() => ({ sessions, activeSessionId: 'active-1' })),
+      loadSessionHistory: vi.fn(async () => undefined),
+      switchSession: vi.fn(),
+    };
+
+    const manager = FlowChatManager.getInstance();
+    await expect(manager.initialize('D:/workspace/BitFun')).resolves.toBe(true);
+
+    // Without this the breadcrumb and turn rail render from the catalog while
+    // the message area stays blank until the user clicks the session.
+    expect(storeMocks.store.loadSessionHistory).toHaveBeenCalledWith(
+      'active-1',
+      'D:/workspace/BitFun',
+      undefined,
+      undefined,
+      undefined,
+    );
+  });
+
+  it('reports no history when metadata claims sessions but none are selectable', async () => {
+    storeMocks.store = {
+      registerPersistUnreadCompletionCallback: vi.fn(),
+      getSurfaceGeneration: vi.fn(() => 7),
+      loadSessionMetadataPage: vi.fn(async () => ({
+        sessions: [{ sessionId: 'history-1' }],
+        totalTopLevelCount: 1,
+        hasMore: false,
+      })),
+      getState: vi.fn(() => ({ sessions: new Map(), activeSessionId: null })),
+      loadSessionHistory: vi.fn(async () => undefined),
+      switchSession: vi.fn(),
+    };
+
+    const manager = FlowChatManager.getInstance();
+
+    // `false` is the caller's signal to create a session against the live
+    // workspace. Returning `true` here would leave the surface with no active
+    // session and no new one.
+    await expect(manager.initialize('D:/workspace/BitFun')).resolves.toBe(false);
+    expect(storeMocks.store.switchSession).not.toHaveBeenCalled();
+  });
 });
diff --git a/src/web-ui/src/flow_chat/services/FlowChatManager.ts b/src/web-ui/src/flow_chat/services/FlowChatManager.ts
index b7586da60b..58a8bea2ab 100644
--- a/src/web-ui/src/flow_chat/services/FlowChatManager.ts
+++ b/src/web-ui/src/flow_chat/services/FlowChatManager.ts
@@ -15,6 +15,12 @@ import { ACPClientAPI } from '@/infrastructure/api/service-api/ACPClientAPI';
 import { stateMachineManager } from '../state-machine';
 import { EventBatcher } from './EventBatcher';
 import { createLogger } from '@/shared/utils/logger';
+import {
+  getActiveSurfaceId,
+  getActiveSurfaceScope,
+  isSurfaceChangedError,
+  type DeviceSurfaceId,
+} from '@/infrastructure/peer-device/deviceSurface';
 import type { WorkspaceInfo } from '@/shared/types';
 import type { Session } from '../types/flow-chat';
 import {
@@ -48,6 +54,8 @@ import {
   cancelSessionTask as cancelSessionTaskModule,
   installPendingQueueDrainListener,
   drainPendingQueue,
+  waitForInFlightSubmissions,
+  pendingQueueManager,
   initializeEventListeners,
   processBatchedEvents,
   addDialogTurn as addDialogTurnModule,
@@ -112,8 +120,11 @@ export class FlowChatManager {
   }
 
   /** Public hook used by the queue panel "send now" fallback to drain head item. */
-  async drainPendingQueueForSession(sessionId: string): Promise<void> {
-    return drainPendingQueue(this.context, sessionId);
+  async drainPendingQueueForSession(
+    sessionId: string,
+    options?: { allowInterruptedRecoveryAbandon?: boolean },
+  ): Promise<void> {
+    return drainPendingQueue(this.context, sessionId, options);
   }
 
   public static getInstance(): FlowChatManager {
@@ -166,6 +177,11 @@ export class FlowChatManager {
     return request;
   }
 
+  /**
+   * The same repository is routinely open at the same path on two devices, so
+   * without the surface a bootstrap for one device is handed the in-flight
+   * initialization of another — and reads back the wrong device's session list.
+   */
   private static createInitializationRequestKey(
     workspacePath: string,
     preferredMode?: string,
@@ -173,6 +189,7 @@ export class FlowChatManager {
     remoteSshHost?: string
   ): string {
     return JSON.stringify([
+      getActiveSurfaceId(),
       workspacePath,
       preferredMode ?? '',
       remoteConnectionId ?? '',
@@ -187,6 +204,7 @@ export class FlowChatManager {
     remoteConnectionId?: string,
     remoteSshHost?: string
   ): Promise<boolean> {
+    const scope = getActiveSurfaceScope();
     try {
       await this.initializeEventListeners();
       if (this.disposed) {
@@ -214,6 +232,12 @@ export class FlowChatManager {
         return false;
       }
 
+      // This page belongs to the device it was read from and has already landed
+      // in that surface's own container. Selecting a session out of it now would
+      // apply one device's history to another; the surface this window moved to
+      // runs its own bootstrap.
+      scope.assertCurrent('initializeWorkspace');
+
       const sessionMatchesWorkspace = (session: {
         workspacePath?: string;
         remoteConnectionId?: string;
@@ -262,6 +286,7 @@ export class FlowChatManager {
           if (this.disposed) {
             return false;
           }
+          scope.assertCurrent('initializeWorkspace');
           state = this.context.flowChatStore.getState();
           workspaceSessions = Array
             .from(state.sessions.values())
@@ -287,6 +312,30 @@ export class FlowChatManager {
         !!activeSession && sessionMatchesWorkspace(activeSession);
       const activeSessionIdAtAutoSelectStart = state.activeSessionId;
 
+      // History is only restored on the auto-select path below. A session that
+      // is already active — restored by the nav list after a Peer Device
+      // surface switch, for example — keeps its metadata-only projection, so
+      // the breadcrumb and turn rail render from the catalog while the message
+      // area stays empty until the user clicks the session by hand.
+      if (
+        activeSessionBelongsToWorkspace &&
+        activeSession &&
+        activeSession.isHistorical === true &&
+        isCurrentInitializationRequest()
+      ) {
+        await this.context.flowChatStore.loadSessionHistory(
+          activeSession.sessionId,
+          workspacePath,
+          undefined,
+          activeSession.remoteConnectionId,
+          activeSession.remoteSshHost,
+        );
+        if (this.disposed) {
+          return false;
+        }
+        scope.assertCurrent('initializeWorkspace');
+      }
+
       if (hasHistoricalSessions && !activeSessionBelongsToWorkspace) {
         if (!isCurrentInitializationRequest()) {
           return hasHistoricalSessions;
@@ -297,8 +346,17 @@ export class FlowChatManager {
           : undefined) || sortedWorkspaceSessions[0];
 
         if (!latestSession) {
+          // The caller reads the return value as "a session is available, do
+          // not create one". Reporting history we cannot select would leave the
+          // surface with no active session and no new one, so report no history
+          // and let the caller create against the live workspace instead.
           this.context.currentWorkspacePath = workspacePath;
-          return hasHistoricalSessions;
+          log.warn('Session metadata reported history with nothing selectable for this workspace', {
+            workspacePath,
+            metadataSessionCount: initialMetadataPage.sessions.length,
+            totalTopLevelCount: initialMetadataPage.totalTopLevelCount,
+          });
+          return false;
         }
 
         if (latestSession.isHistorical) {
@@ -312,6 +370,7 @@ export class FlowChatManager {
           if (this.disposed) {
             return false;
           }
+          scope.assertCurrent('initializeWorkspace');
         }
 
         if (!isCurrentInitializationRequest()) {
@@ -344,10 +403,18 @@ export class FlowChatManager {
 
       return hasHistoricalSessions;
     } catch (error) {
-      log.error('Initialization failed', error);
       // Must not return false: callers treat false as "no history → create
       // session", which in Peer Device Mode can create on the peer with a
-      // stale controller workspace path.
+      // stale controller workspace path. A surface change is not a failure
+      // either — this bootstrap simply no longer owns the rendered device —
+      // but it must still not report "no history" to the caller.
+      if (isSurfaceChangedError(error)) {
+        log.debug('Abandoned workspace initialization after a device surface switch', {
+          workspacePath,
+        });
+        throw error;
+      }
+      log.error('Initialization failed', error);
       throw error;
     }
   }
@@ -402,8 +469,31 @@ export class FlowChatManager {
   }
 
   /**
-   * Clear all session UI state when entering/exiting Peer Device Mode so the
-   * next workspace bootstrap loads the target device's session list only.
+   * Let submissions that already created a projection turn hand it to their
+   * host before the rendered transport changes.
+   *
+   * Without this, a switch during the async window in `startTurn` (state
+   * transition, worktree binding, model sync) resumes against a store that no
+   * longer holds the session, and the turn is lost before `start_dialog_turn`
+   * ever runs. A timeout is safe: `sendMessage` detects the surface change and
+   * re-queues the message.
+   */
+  public async waitForInFlightSubmissions(timeoutMs: number): Promise<boolean> {
+    return waitForInFlightSubmissions(timeoutMs);
+  }
+
+  /**
+   * Detach this window from the device it is rendering, before the transport
+   * swaps to another one.
+   *
+   * The store keeps that device's sessions in its own container, so nothing is
+   * deleted here: state machines and processing status stay alive for work the
+   * device may still be running, and returning to it renders immediately.
+   *
+   * Debounced disk writes are the exception. They are addressed by session id
+   * only, so a checkpoint that fires after the transport swap would persist one
+   * device's turn onto another's disk. Drop them; the host keeps its own copy
+   * and reconciliation re-reads it.
    */
   public resetForPeerModeSwitch(): string[] {
     this.cleanupEventListeners();
@@ -412,19 +502,30 @@ export class FlowChatManager {
     // Drop controller-local path so createChatSession cannot reuse a stale
     // Windows/Mac path against the peer host after the surface switch.
     this.context.currentWorkspacePath = null;
-    const removedSessionIds = this.context.flowChatStore.clearAllSessionsForPeerSwitch();
-    removedSessionIds.forEach(sessionId => {
-      stateMachineManager.delete(sessionId);
-      this.context.processingManager.clearSessionStatus(sessionId);
+    const detachedSessionIds = Array.from(
+      this.context.flowChatStore.getState().sessions.keys(),
+    );
+    detachedSessionIds.forEach(sessionId => {
       cleanupSaveState(this.context, sessionId);
       cleanupSessionBuffers(this.context, sessionId);
     });
+    this.context.flowChatStore.prepareForSurfaceSwitch();
     try {
       useModernFlowChatStore.getState().clear();
     } catch (error) {
       log.warn('Failed to clear modern FlowChat store during peer switch', error);
     }
-    return removedSessionIds;
+    // No session ids: a switch removes nothing, and callers must not tear down
+    // runtime state for sessions that still exist on their own device.
+    return [];
+  }
+
+  /** Permanently forget a peer that was explicitly detached or became lost. */
+  public discardDeviceSurface(surfaceId: DeviceSurfaceId): void {
+    this.context.flowChatStore.discardSurfaceState(surfaceId);
+    stateMachineManager.clearSurface(surfaceId);
+    this.context.processingManager.clearSurface(surfaceId);
+    pendingQueueManager.clearSurface(surfaceId);
   }
 
   public destroy(): void {
@@ -675,6 +776,7 @@ export class FlowChatManager {
       preserveTurnOnStartError?: boolean;
       onSessionConflictRetryStart?: () => void;
       onSessionConflictRetrySuccess?: () => void;
+      sessionMutationLeaseId?: string;
     }
   ): Promise<void> {
     const targetSessionId = sessionId || this.context.flowChatStore.getState().activeSessionId;
@@ -708,11 +810,11 @@ export class FlowChatManager {
     return driverForSession(sessionId, session).compactSession(this.context, sessionId);
   }
 
-  /** Generate and insert the session usage report through its driver. */
+  /** Produce the session usage report and show it, through its driver. */
   async runSessionUsageReport(
     sessionId: string,
     uiParams: import('../session-drivers/types').UsageReportUiParams,
-  ): Promise<{ inserted: boolean }> {
+  ): Promise<{ shown: boolean }> {
     const session = this.context.flowChatStore.getState().sessions.get(sessionId);
     return driverForSession(sessionId, session).runUsageReport(this.context, sessionId, uiParams);
   }
diff --git a/src/web-ui/src/flow_chat/services/ProcessingStatusManager.test.ts b/src/web-ui/src/flow_chat/services/ProcessingStatusManager.test.ts
new file mode 100644
index 0000000000..362ca2c712
--- /dev/null
+++ b/src/web-ui/src/flow_chat/services/ProcessingStatusManager.test.ts
@@ -0,0 +1,59 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  LOCAL_SURFACE_ID,
+  activateSurface,
+} from '@/infrastructure/peer-device/deviceSurface';
+import { ProcessingStatusManager } from './ProcessingStatusManager';
+
+describe('ProcessingStatusManager device surfaces', () => {
+  let manager: ProcessingStatusManager;
+
+  beforeEach(() => {
+    activateSurface(LOCAL_SURFACE_ID);
+    manager = new ProcessingStatusManager();
+  });
+
+  it('selects only the rendered surface and notifies with an empty projection', () => {
+    manager.registerStatus({
+      sessionId: 'same-session',
+      status: 'thinking',
+      message: 'local',
+    });
+    const listener = vi.fn();
+    manager.addListener(listener);
+
+    activateSurface('peer-b');
+    expect(manager.getAllStatuses()).toEqual([]);
+    expect(listener).toHaveBeenLastCalledWith([]);
+    manager.registerStatus({
+      sessionId: 'same-session',
+      status: 'thinking',
+      message: 'peer',
+    });
+
+    activateSurface(LOCAL_SURFACE_ID);
+    expect(manager.getSessionStatuses('same-session')).toMatchObject([
+      { message: 'local' },
+    ]);
+  });
+
+  it('clears one detached surface without deleting the local status', () => {
+    manager.registerStatus({
+      sessionId: 'same-session',
+      status: 'thinking',
+      message: 'local',
+    });
+    activateSurface('peer-b');
+    manager.registerStatus({
+      sessionId: 'same-session',
+      status: 'thinking',
+      message: 'peer',
+    });
+
+    manager.clearSurface('peer-b');
+    expect(manager.getAllStatuses()).toEqual([]);
+    activateSurface(LOCAL_SURFACE_ID);
+    expect(manager.getAllStatuses()).toMatchObject([{ message: 'local' }]);
+  });
+});
diff --git a/src/web-ui/src/flow_chat/services/ProcessingStatusManager.ts b/src/web-ui/src/flow_chat/services/ProcessingStatusManager.ts
index f1364d1e30..a8c8a46da9 100644
--- a/src/web-ui/src/flow_chat/services/ProcessingStatusManager.ts
+++ b/src/web-ui/src/flow_chat/services/ProcessingStatusManager.ts
@@ -4,6 +4,11 @@
  */
 
 import { createLogger } from '@/shared/utils/logger';
+import {
+  getActiveSurfaceId,
+  onSurfaceActivated,
+  type DeviceSurfaceId,
+} from '@/infrastructure/peer-device/deviceSurface';
 
 const log = createLogger('ProcessingStatusManager');
 
@@ -21,18 +26,27 @@ export interface ProcessingStatusListener {
   (statuses: ProcessingStatus[]): void;
 }
 
+interface SurfaceProcessingStatus extends ProcessingStatus {
+  surfaceId: DeviceSurfaceId;
+}
+
 export class ProcessingStatusManager {
-  private statuses: Map<string, ProcessingStatus> = new Map();
-  private completedStatuses: ProcessingStatus[] = [];
+  private statuses: Map<string, SurfaceProcessingStatus> = new Map();
+  private completedStatusesBySurface = new Map<DeviceSurfaceId, ProcessingStatus[]>();
   private listeners: Set<ProcessingStatusListener> = new Set();
   private cleanupIntervalId: ReturnType<typeof setInterval> | null = null;
 
+  constructor() {
+    onSurfaceActivated(() => this.notifyListeners());
+  }
+
   registerStatus(status: Omit<ProcessingStatus, 'id' | 'startTime'>): string {
     const id = this.generateId();
-    const fullStatus: ProcessingStatus = {
+    const fullStatus: SurfaceProcessingStatus = {
       ...status,
       id,
-      startTime: Date.now()
+      startTime: Date.now(),
+      surfaceId: getActiveSurfaceId(),
     };
 
     this.statuses.set(id, fullStatus);
@@ -48,9 +62,14 @@ export class ProcessingStatusManager {
       return;
     }
 
-    const updated = { ...existing, ...updates };
+    const updated: SurfaceProcessingStatus = {
+      ...existing,
+      ...updates,
+      // Identity is immutable even if an overly broad patch is supplied.
+      surfaceId: existing.surfaceId,
+    };
     this.statuses.set(id, updated);
-    this.notifyListeners();
+    this.notifySurfaceListeners(existing.surfaceId);
   }
 
   removeStatus(id: string): void {
@@ -64,10 +83,12 @@ export class ProcessingStatusManager {
         status.message.includes('completed') || 
         status.message.includes('success') ||
         status.metadata?.isCompleted === true) {
-      this.completedStatuses.unshift(status);
-      if (this.completedStatuses.length > 10) {
-        this.completedStatuses = this.completedStatuses.slice(0, 10);
+      const completed = this.completedStatusesBySurface.get(status.surfaceId) ?? [];
+      completed.unshift(this.publicStatus(status));
+      if (completed.length > 10) {
+        completed.length = 10;
       }
+      this.completedStatusesBySurface.set(status.surfaceId, completed);
     }
 
     const minDisplayTime = this.getMinDisplayTime(status);
@@ -79,31 +100,40 @@ export class ProcessingStatusManager {
       setTimeout(() => {
         if (this.statuses.has(id)) {
           this.statuses.delete(id);
-          this.notifyListeners();
+          this.notifySurfaceListeners(status.surfaceId);
         }
       }, delay);
     } else {
       this.statuses.delete(id);
-      this.notifyListeners();
+      this.notifySurfaceListeners(status.surfaceId);
     }
   }
 
   clearSessionStatus(sessionId: string): void {
+    this.clearSessionStatusForSurface(getActiveSurfaceId(), sessionId);
+  }
+
+  /** Clear a submission stranded on a surface that is no longer rendered. */
+  clearSessionStatusForSurface(surfaceId: DeviceSurfaceId, sessionId: string): void {
     let hasChanges = false;
     for (const [id, status] of this.statuses.entries()) {
-      if (status.sessionId === sessionId) {
+      if (status.surfaceId === surfaceId && status.sessionId === sessionId) {
         this.statuses.delete(id);
         hasChanges = true;
       }
     }
     
-    if (hasChanges) {
+    if (hasChanges && surfaceId === getActiveSurfaceId()) {
       this.notifyListeners();
     }
   }
 
   getAllStatuses(): ProcessingStatus[] {
-    return Array.from(this.statuses.values()).sort((a, b) => a.startTime - b.startTime);
+    const surfaceId = getActiveSurfaceId();
+    return Array.from(this.statuses.values())
+      .filter(status => status.surfaceId === surfaceId)
+      .map(status => this.publicStatus(status))
+      .sort((a, b) => a.startTime - b.startTime);
   }
 
   getSessionStatuses(sessionId: string): ProcessingStatus[] {
@@ -111,7 +141,7 @@ export class ProcessingStatusManager {
   }
 
   hasActiveStatus(): boolean {
-    return this.statuses.size > 0;
+    return this.getAllStatuses().length > 0;
   }
 
   getCurrentMainStatus(): ProcessingStatus | null {
@@ -138,21 +168,48 @@ export class ProcessingStatusManager {
     });
   }
 
+  private notifySurfaceListeners(surfaceId: DeviceSurfaceId): void {
+    if (surfaceId === getActiveSurfaceId()) {
+      this.notifyListeners();
+    }
+  }
+
+  private publicStatus(status: SurfaceProcessingStatus): ProcessingStatus {
+    const { surfaceId: _surfaceId, ...result } = status;
+    return result;
+  }
+
   private generateId(): string {
     return `status_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
   }
 
   clearAll(): void {
     this.statuses.clear();
+    this.completedStatusesBySurface.clear();
     this.notifyListeners();
   }
 
+  /** Permanently forget status owned by one detached device. */
+  clearSurface(surfaceId: DeviceSurfaceId): void {
+    let activeChanged = false;
+    for (const [id, status] of this.statuses) {
+      if (status.surfaceId === surfaceId) {
+        this.statuses.delete(id);
+        activeChanged ||= surfaceId === getActiveSurfaceId();
+      }
+    }
+    this.completedStatusesBySurface.delete(surfaceId);
+    if (activeChanged) {
+      this.notifyListeners();
+    }
+  }
+
   getCompletedSteps(): ProcessingStatus[] {
-    return [...this.completedStatuses];
+    return [...(this.completedStatusesBySurface.get(getActiveSurfaceId()) ?? [])];
   }
 
   clearCompletedHistory(): void {
-    this.completedStatuses = [];
+    this.completedStatusesBySurface.delete(getActiveSurfaceId());
   }
 
   startCleanupTimer(): void {
@@ -192,15 +249,16 @@ export class ProcessingStatusManager {
     const now = Date.now();
     const timeout = 5 * 60 * 1000;
     
-    let hasChanges = false;
+    let activeChanged = false;
+    const activeSurfaceId = getActiveSurfaceId();
     for (const [id, status] of this.statuses.entries()) {
       if (now - status.startTime > timeout) {
         this.statuses.delete(id);
-        hasChanges = true;
+        activeChanged ||= status.surfaceId === activeSurfaceId;
       }
     }
-    
-    if (hasChanges) {
+
+    if (activeChanged) {
       this.notifyListeners();
     }
   }
@@ -209,4 +267,4 @@ export class ProcessingStatusManager {
 
 export const processingStatusManager = new ProcessingStatusManager();
 
-processingStatusManager.startCleanupTimer();
\ No newline at end of file
+processingStatusManager.startCleanupTimer();
diff --git a/src/web-ui/src/flow_chat/services/SessionRollbackService.test.ts b/src/web-ui/src/flow_chat/services/SessionRollbackService.test.ts
new file mode 100644
index 0000000000..812ee8571f
--- /dev/null
+++ b/src/web-ui/src/flow_chat/services/SessionRollbackService.test.ts
@@ -0,0 +1,315 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const agentApiMock = vi.hoisted(() => ({ rollbackSessionToTurn: vi.fn() }));
+const eventBusMock = vi.hoisted(() => ({ emit: vi.fn() }));
+const loadSessionHistory = vi.hoisted(() => vi.fn(async () => undefined));
+const sessions = vi.hoisted(() => new Map<string, any>());
+const historyViews = vi.hoisted(() => new Map<string, any>());
+
+vi.mock('@/infrastructure/api', () => ({ agentAPI: agentApiMock }));
+vi.mock('@/infrastructure/event-bus', () => ({ globalEventBus: eventBusMock }));
+vi.mock('../store/FlowChatStore', () => ({
+  flowChatStore: {
+    getState: () => ({ sessions }),
+    getSessionHistoryViewState: (sessionId: string) => historyViews.get(sessionId),
+    loadSessionHistory,
+  },
+}));
+
+import { rollbackSessionToTurn } from './SessionRollbackService';
+import {
+  isSessionTurnRetired,
+  useSessionMutationStore,
+} from '../store/sessionMutationStore';
+import {
+  SessionExecutionEvent,
+  stateMachineManager,
+} from '../state-machine';
+import { pendingQueueManager } from './flow-chat-manager/PendingQueueModule';
+
+describe('SessionRollbackService', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    loadSessionHistory.mockResolvedValue(undefined);
+    sessions.clear();
+    historyViews.clear();
+    stateMachineManager.clear();
+    pendingQueueManager.clear('session-1');
+    useSessionMutationStore.setState({ mutations: new Map(), retiredTurnIds: new Map() });
+    sessions.set('session-1', {
+      sessionId: 'session-1',
+      workspacePath: 'E:/workspace',
+      config: {},
+      isPartial: true,
+      dialogTurns: [{ id: 'turn-7', storageTurnIndex: 7 }],
+      turnCatalog: {
+        sessionId: 'session-1',
+        revision: 'catalog-3',
+        entries: [{ ordinal: 2, storageTurnIndex: 7, turnId: 'turn-7' }],
+      },
+    });
+  });
+
+  it('submits stable persisted identity and reloads only after completion', async () => {
+    agentApiMock.rollbackSessionToTurn.mockResolvedValue({
+      status: 'completed',
+      restoredFiles: ['src/lib.rs'],
+      composer: { kind: 'replace', text: 'prompt' },
+      retiredTurnIds: ['turn-7', 'turn-8'],
+    });
+
+    const result = await rollbackSessionToTurn({
+      sessionId: 'session-1',
+      targetTurnId: 'turn-7',
+      kind: 'rollback',
+    });
+
+    expect(agentApiMock.rollbackSessionToTurn).toHaveBeenCalledWith(expect.objectContaining({
+      sessionId: 'session-1',
+      targetTurnId: 'turn-7',
+      expectedStorageTurnIndex: 7,
+      expectedCatalogRevision: 'catalog-3',
+    }));
+    expect(loadSessionHistory).toHaveBeenCalledTimes(1);
+    expect(result).toMatchObject({ fromTurnIndex: 2, composerText: 'prompt' });
+    expect(isSessionTurnRetired('session-1', 'turn-7')).toBe(true);
+    expect(isSessionTurnRetired('session-1', 'turn-8')).toBe(true);
+  });
+
+  it('omits a stale catalog revision when the current Turn is not represented', async () => {
+    const session = sessions.get('session-1');
+    session.turnCatalog.entries[0].turnId = 'retired-turn-7';
+    agentApiMock.rollbackSessionToTurn.mockResolvedValue({
+      status: 'completed',
+      restoredFiles: [],
+      retiredTurnIds: ['turn-7'],
+      composer: { kind: 'preserve' },
+    });
+
+    await rollbackSessionToTurn({
+      sessionId: 'session-1',
+      targetTurnId: 'turn-7',
+      kind: 'rollback',
+    });
+
+    expect(agentApiMock.rollbackSessionToTurn).toHaveBeenCalledWith(expect.objectContaining({
+      targetTurnId: 'turn-7',
+      expectedStorageTurnIndex: 7,
+      expectedCatalogRevision: undefined,
+    }));
+  });
+
+  it('rolls back an older Turn materialized only in a history window', async () => {
+    const session = sessions.get('session-1');
+    const olderTurn = { id: 'turn-2', storageTurnIndex: 2 };
+    const catalog = {
+      sessionId: 'session-1',
+      revision: 'catalog-history',
+      entries: [
+        { ordinal: 0, storageTurnIndex: 2, turnId: 'turn-2' },
+        { ordinal: 2, storageTurnIndex: 7, turnId: 'turn-7' },
+      ],
+    };
+    session.turnCatalog = catalog;
+    historyViews.set('session-1', {
+      catalog,
+      loadedRanges: [{ startOrdinal: 0, endOrdinalExclusive: 1, turns: [olderTurn] }],
+    });
+    agentApiMock.rollbackSessionToTurn.mockResolvedValue({
+      status: 'completed',
+      restoredFiles: [],
+      retiredTurnIds: ['turn-2', 'turn-7'],
+      composer: { kind: 'preserve' },
+    });
+
+    const result = await rollbackSessionToTurn({
+      sessionId: 'session-1',
+      targetTurnId: 'turn-2',
+      kind: 'rollback',
+    });
+
+    expect(agentApiMock.rollbackSessionToTurn).toHaveBeenCalledWith(expect.objectContaining({
+      targetTurnId: 'turn-2',
+      expectedStorageTurnIndex: 2,
+      expectedCatalogRevision: 'catalog-history',
+    }));
+    expect(result.fromTurnIndex).toBe(0);
+  });
+
+  it('derives the ordinal from a materialized range when its catalog is unavailable', async () => {
+    const olderTurn = { id: 'turn-12', storageTurnIndex: 12 };
+    sessions.get('session-1').turnCatalog = undefined;
+    historyViews.set('session-1', {
+      catalog: null,
+      loadedRanges: [{
+        startOrdinal: 10,
+        endOrdinalExclusive: 13,
+        turns: [
+          { id: 'turn-10', storageTurnIndex: 10 },
+          { id: 'turn-11', storageTurnIndex: 11 },
+          olderTurn,
+        ],
+      }],
+    });
+    agentApiMock.rollbackSessionToTurn.mockResolvedValue({
+      status: 'completed',
+      restoredFiles: [],
+      retiredTurnIds: ['turn-12'],
+      composer: { kind: 'preserve' },
+    });
+
+    const result = await rollbackSessionToTurn({
+      sessionId: 'session-1',
+      targetTurnId: 'turn-12',
+      kind: 'rollback',
+    });
+
+    expect(agentApiMock.rollbackSessionToTurn).toHaveBeenCalledWith(expect.objectContaining({
+      targetTurnId: 'turn-12',
+      expectedStorageTurnIndex: 12,
+      expectedCatalogRevision: undefined,
+    }));
+    expect(result.fromTurnIndex).toBe(12);
+  });
+
+  it('keeps a catalog-only target valid after its history window is pruned', async () => {
+    const session = sessions.get('session-1');
+    const catalog = {
+      sessionId: 'session-1',
+      revision: 'catalog-history',
+      entries: [
+        { ordinal: 0, storageTurnIndex: 2, turnId: 'turn-2' },
+        { ordinal: 2, storageTurnIndex: 7, turnId: 'turn-7' },
+      ],
+    };
+    session.turnCatalog = catalog;
+    historyViews.set('session-1', { catalog, loadedRanges: [] });
+    agentApiMock.rollbackSessionToTurn.mockResolvedValue({
+      status: 'completed',
+      restoredFiles: [],
+      retiredTurnIds: ['turn-2', 'turn-7'],
+      composer: { kind: 'preserve' },
+    });
+
+    const result = await rollbackSessionToTurn({
+      sessionId: 'session-1',
+      targetTurnId: 'turn-2',
+      kind: 'rollback',
+    });
+
+    expect(agentApiMock.rollbackSessionToTurn).toHaveBeenCalledWith(expect.objectContaining({
+      targetTurnId: 'turn-2',
+      expectedStorageTurnIndex: 2,
+      expectedCatalogRevision: 'catalog-history',
+    }));
+    expect(result.fromTurnIndex).toBe(0);
+  });
+
+  it('admits only one mutation per Session', async () => {
+    let settle!: (value: any) => void;
+    agentApiMock.rollbackSessionToTurn.mockReturnValue(new Promise(resolve => { settle = resolve; }));
+    const first = rollbackSessionToTurn({
+      sessionId: 'session-1', targetTurnId: 'turn-7', kind: 'rollback',
+    });
+    await expect(rollbackSessionToTurn({
+      sessionId: 'session-1', targetTurnId: 'turn-7', kind: 'edit-rerun',
+    })).rejects.toThrow('already in progress');
+    settle({
+      status: 'completed',
+      restoredFiles: [],
+      retiredTurnIds: ['turn-7'],
+      composer: { kind: 'preserve' },
+    });
+    await first;
+    expect(agentApiMock.rollbackSessionToTurn).toHaveBeenCalledTimes(1);
+  });
+
+  it('rejects history mutation unless the Session is idle', async () => {
+    await stateMachineManager.transition('session-1', SessionExecutionEvent.START);
+
+    await expect(rollbackSessionToTurn({
+      sessionId: 'session-1', targetTurnId: 'turn-7', kind: 'rollback',
+    })).rejects.toThrow('Session is idle');
+    expect(agentApiMock.rollbackSessionToTurn).not.toHaveBeenCalled();
+    expect(useSessionMutationStore.getState().mutations.has('session-1')).toBe(false);
+  });
+
+  it('rejects history mutation while a message is pending', async () => {
+    pendingQueueManager.enqueue({
+      sessionId: 'session-1',
+      content: 'queued follow-up',
+    });
+
+    await expect(rollbackSessionToTurn({
+      sessionId: 'session-1', targetTurnId: 'turn-7', kind: 'edit-rerun',
+    })).rejects.toThrow('pending message queue');
+    expect(agentApiMock.rollbackSessionToTurn).not.toHaveBeenCalled();
+    expect(useSessionMutationStore.getState().mutations.has('session-1')).toBe(false);
+  });
+
+  it('refreshes affected state and reloads on recovery-required outcome', async () => {
+    agentApiMock.rollbackSessionToTurn.mockResolvedValue({
+      status: 'recovery_required',
+      affectedFiles: ['src/recovery.rs'],
+      reason: 'staged marker remains',
+    });
+    await expect(rollbackSessionToTurn({
+      sessionId: 'session-1', targetTurnId: 'turn-7', kind: 'rollback',
+    })).rejects.toThrow('requires recovery');
+    expect(eventBusMock.emit).toHaveBeenCalledWith('editor:file-changed', {
+      filePath: 'src/recovery.rs',
+    });
+    expect(loadSessionHistory).toHaveBeenCalledTimes(1);
+    expect(useSessionMutationStore.getState().mutations.has('session-1')).toBe(false);
+  });
+
+  it('keeps the Session blocked when recovery reload fails', async () => {
+    agentApiMock.rollbackSessionToTurn.mockResolvedValue({
+      status: 'recovery_required',
+      affectedFiles: ['src/recovery.rs'],
+      reason: 'staged marker remains',
+    });
+    loadSessionHistory.mockRejectedValueOnce(new Error('recovery reload failed'));
+
+    await expect(rollbackSessionToTurn({
+      sessionId: 'session-1', targetTurnId: 'turn-7', kind: 'rollback',
+    })).rejects.toThrow('recovery reload failed');
+
+    expect(useSessionMutationStore.getState().mutations.get('session-1')).toMatchObject({
+      phase: 'reconciliation_required',
+      reconciliationReason: 'staged marker remains',
+    });
+    await expect(rollbackSessionToTurn({
+      sessionId: 'session-1', targetTurnId: 'turn-7', kind: 'rollback',
+    })).rejects.toThrow('already in progress');
+    expect(agentApiMock.rollbackSessionToTurn).toHaveBeenCalledTimes(1);
+  });
+
+  it('keeps the Session blocked when authoritative reload fails after commit', async () => {
+    agentApiMock.rollbackSessionToTurn.mockResolvedValue({
+      status: 'completed',
+      restoredFiles: ['src/committed.rs'],
+      retiredTurnIds: ['turn-7'],
+      composer: { kind: 'replace', text: 'prompt' },
+      hiddenTurnCount: 1,
+      boundaryStorageTurnIndex: 7,
+      targetTurnId: 'turn-7',
+      reloadRequired: true,
+      reloadReason: 'transcript read failed',
+    });
+    loadSessionHistory.mockRejectedValueOnce(new Error('reload failed'));
+
+    await expect(rollbackSessionToTurn({
+      sessionId: 'session-1', targetTurnId: 'turn-7', kind: 'rollback',
+    })).rejects.toThrow('reload failed');
+
+    expect(useSessionMutationStore.getState().mutations.get('session-1')).toMatchObject({
+      phase: 'reconciliation_required',
+      reconciliationReason: 'reload failed',
+    });
+    await expect(rollbackSessionToTurn({
+      sessionId: 'session-1', targetTurnId: 'turn-7', kind: 'rollback',
+    })).rejects.toThrow('already in progress');
+    expect(agentApiMock.rollbackSessionToTurn).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/src/web-ui/src/flow_chat/services/SessionRollbackService.ts b/src/web-ui/src/flow_chat/services/SessionRollbackService.ts
new file mode 100644
index 0000000000..ced54d6683
--- /dev/null
+++ b/src/web-ui/src/flow_chat/services/SessionRollbackService.ts
@@ -0,0 +1,159 @@
+import { agentAPI } from '@/infrastructure/api';
+import { globalEventBus } from '@/infrastructure/event-bus';
+import { createLogger } from '@/shared/utils/logger';
+import { flowChatStore } from '../store/FlowChatStore';
+import {
+  assertSessionMutationLease,
+  completeSessionMutationReconciliation,
+  endSessionMutation,
+  markSessionTurnsRetired,
+  requireSessionMutationReconciliation,
+  tryBeginSessionMutation,
+  type SessionMutationLease,
+  type SessionMutationKind,
+} from '../store/sessionMutationStore';
+import {
+  resolveMaterializedSessionTurnIdentity,
+  resolveStorageTurnIndex,
+} from '../utils/flowChatTurnIdentity';
+import { requireSessionProjectWorkspacePath } from '../utils/sessionWorkspace';
+import type { Session } from '../types/flow-chat';
+import type { SessionTurnCatalog } from '@/shared/types/session-history';
+import { pendingQueueManager } from './flow-chat-manager/PendingQueueModule';
+import { SessionExecutionState, stateMachineManager } from '../state-machine';
+
+const log = createLogger('SessionRollbackService');
+
+export interface RollbackSessionToTurnRequest {
+  sessionId: string;
+  targetTurnId: string;
+  kind: SessionMutationKind;
+  lease?: SessionMutationLease;
+}
+
+export interface RollbackSessionToTurnResult {
+  restoredFiles: string[];
+  fromTurnIndex: number;
+  composerText?: string;
+}
+
+async function reloadAuthoritativeSession(sessionId: string, workspacePath: string): Promise<void> {
+  await flowChatStore.loadSessionHistory(sessionId, workspacePath, undefined, undefined, undefined, {
+    deferFullHistoryUntilActive: true,
+  });
+  completeSessionMutationReconciliation(sessionId);
+}
+
+function refreshFiles(paths: string[]): void {
+  globalEventBus.emit('file-tree:refresh');
+  paths.forEach(filePath => globalEventBus.emit('editor:file-changed', { filePath }));
+}
+
+function assertSessionIdleForHistoryMutation(sessionId: string): void {
+  if (stateMachineManager.getCurrentState(sessionId) !== SessionExecutionState.IDLE) {
+    throw new Error('Wait until the Session is idle before changing its history');
+  }
+  if (pendingQueueManager.list(sessionId).length > 0) {
+    throw new Error('Clear the pending message queue before changing Session history');
+  }
+}
+
+function validProjectedCatalogRevision(
+  session: Session,
+  catalog: SessionTurnCatalog | undefined,
+): string | undefined {
+  if (!catalog || catalog.sessionId !== session.sessionId) {
+    return undefined;
+  }
+  const coversProjectedTurns = session.dialogTurns.every((turn) => {
+    const storageTurnIndex = resolveStorageTurnIndex(session, turn);
+    return storageTurnIndex !== undefined && catalog.entries.some(
+      entry => entry.storageTurnIndex === storageTurnIndex && entry.turnId === turn.id,
+    );
+  });
+  return coversProjectedTurns ? catalog.revision : undefined;
+}
+
+export async function rollbackSessionToTurn(
+  request: RollbackSessionToTurnRequest,
+): Promise<RollbackSessionToTurnResult> {
+  const lease = request.lease
+    ?? tryBeginSessionMutation(request.sessionId, request.kind, request.targetTurnId);
+  if (!lease) {
+    throw new Error('Another Session history mutation is already in progress');
+  }
+  if (request.lease) {
+    if (
+      lease.sessionId !== request.sessionId
+      || lease.kind !== request.kind
+      || lease.targetTurnId !== request.targetTurnId
+    ) {
+      throw new Error('Session history mutation lease does not match the rollback request');
+    }
+    assertSessionMutationLease(lease);
+  }
+  const releaseLease = request.lease === undefined;
+
+  try {
+    assertSessionIdleForHistoryMutation(request.sessionId);
+    const session = flowChatStore.getState().sessions.get(request.sessionId);
+    if (!session) {
+      throw new Error(`Session does not exist: ${request.sessionId}`);
+    }
+    const target = resolveMaterializedSessionTurnIdentity(
+      session,
+      flowChatStore.getSessionHistoryViewState(request.sessionId),
+      request.targetTurnId,
+    );
+    if (!target) {
+      throw new Error('Rollback target is no longer available');
+    }
+    const workspacePath = requireSessionProjectWorkspacePath(session, request.sessionId);
+    const expectedStorageTurnIndex = target.storageTurnIndex;
+    const expectedCatalogRevision = validProjectedCatalogRevision(session, target.catalog);
+    const fromTurnIndex = target.ordinal
+      ?? session.dialogTurns.findIndex(turn => turn.id === request.targetTurnId);
+
+    const outcome = await agentAPI.rollbackSessionToTurn({
+      workspacePath,
+      sessionId: request.sessionId,
+      targetTurnId: request.targetTurnId,
+      expectedStorageTurnIndex,
+      expectedCatalogRevision,
+    });
+    if (outcome.status === 'recovery_required') {
+      refreshFiles(outcome.affectedFiles);
+      requireSessionMutationReconciliation(lease, outcome.reason);
+      await reloadAuthoritativeSession(request.sessionId, workspacePath);
+      throw new Error(`Rollback requires recovery: ${outcome.reason}`);
+    }
+
+    markSessionTurnsRetired(request.sessionId, outcome.retiredTurnIds);
+    refreshFiles(outcome.restoredFiles);
+    try {
+      await reloadAuthoritativeSession(request.sessionId, workspacePath);
+    } catch (error) {
+      requireSessionMutationReconciliation(
+        lease,
+        error instanceof Error ? error.message : String(error),
+      );
+      throw error;
+    }
+    return {
+      restoredFiles: outcome.restoredFiles,
+      fromTurnIndex: Math.max(0, fromTurnIndex),
+      composerText: outcome.composer.kind === 'replace' ? outcome.composer.text : undefined,
+    };
+  } catch (error) {
+    log.error('Session rollback failed', {
+      sessionId: request.sessionId,
+      targetTurnId: request.targetTurnId,
+      error,
+    });
+    throw error;
+  } finally {
+    if (releaseLease) {
+      endSessionMutation(lease);
+    }
+  }
+}
diff --git a/src/web-ui/src/flow_chat/services/UserMessageEditService.test.ts b/src/web-ui/src/flow_chat/services/UserMessageEditService.test.ts
new file mode 100644
index 0000000000..b18516cd3b
--- /dev/null
+++ b/src/web-ui/src/flow_chat/services/UserMessageEditService.test.ts
@@ -0,0 +1,111 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const rollbackSessionToTurn = vi.hoisted(() => vi.fn(async () => ({
+  restoredFiles: [],
+  fromTurnIndex: 0,
+  composerText: 'original',
+})));
+const sessions = vi.hoisted(() => new Map<string, any>());
+const historyViews = vi.hoisted(() => new Map<string, any>());
+
+vi.mock('../store/FlowChatStore', () => ({
+  flowChatStore: {
+    getState: () => ({ sessions }),
+    getSessionHistoryViewState: (sessionId: string) => historyViews.get(sessionId),
+  },
+}));
+vi.mock('./SessionRollbackService', () => ({ rollbackSessionToTurn }));
+
+import { editAndRerunUserMessage } from './UserMessageEditService';
+import {
+  assertSessionSubmissionAllowed,
+  useSessionMutationStore,
+} from '../store/sessionMutationStore';
+
+describe('UserMessageEditService', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    sessions.clear();
+    historyViews.clear();
+    sessions.set('session-1', {
+      sessionId: 'session-1',
+      dialogTurns: [{
+        id: 'turn-7',
+        userMessage: { metadata: { triggerSource: 'desktop_ui' } },
+      }],
+    });
+    useSessionMutationStore.setState({ mutations: new Map(), retiredTurnIds: new Map() });
+  });
+
+  it('holds one lease through rollback, reload, and rerun admission', async () => {
+    let admitRerun!: () => void;
+    const rerun = vi.fn(() => new Promise<void>(resolve => {
+      admitRerun = resolve;
+    }));
+
+    const editing = editAndRerunUserMessage({
+      sessionId: 'session-1',
+      turnId: 'turn-7',
+      originalContent: 'original',
+      editedContent: 'edited',
+      agentType: 'agentic',
+      rerun,
+    });
+
+    await vi.waitFor(() => expect(rerun).toHaveBeenCalledTimes(1));
+    const mutation = useSessionMutationStore.getState().mutations.get('session-1');
+    expect(mutation).toMatchObject({ kind: 'edit-rerun', phase: 'active' });
+    expect(rollbackSessionToTurn).toHaveBeenCalledWith(expect.objectContaining({
+      lease: expect.objectContaining({ leaseId: mutation?.leaseId }),
+    }));
+    expect(rerun).toHaveBeenCalledWith('edited', 'agentic', mutation?.leaseId);
+    expect(() => assertSessionSubmissionAllowed('session-1')).toThrow('history mutation');
+    expect(() => assertSessionSubmissionAllowed('session-1', mutation?.leaseId)).not.toThrow();
+
+    admitRerun();
+    await editing;
+    expect(useSessionMutationStore.getState().mutations.has('session-1')).toBe(false);
+  });
+
+  it('releases the lease when rollback fails before reconciliation', async () => {
+    rollbackSessionToTurn.mockRejectedValueOnce(new Error('stale target'));
+
+    await expect(editAndRerunUserMessage({
+      sessionId: 'session-1',
+      turnId: 'turn-7',
+      originalContent: 'original',
+      editedContent: 'edited',
+      rerun: vi.fn(async () => undefined),
+    })).rejects.toThrow('stale target');
+
+    expect(useSessionMutationStore.getState().mutations.has('session-1')).toBe(false);
+  });
+
+  it('edits a message materialized only in a history window', async () => {
+    sessions.get('session-1').dialogTurns = [];
+    historyViews.set('session-1', {
+      catalog: null,
+      loadedRanges: [{
+        startOrdinal: 0,
+        endOrdinalExclusive: 1,
+        turns: [{
+          id: 'turn-7',
+          storageTurnIndex: 7,
+          userMessage: { metadata: { triggerSource: 'desktop_ui' } },
+        }],
+      }],
+    });
+    const rerun = vi.fn(async () => undefined);
+
+    await editAndRerunUserMessage({
+      sessionId: 'session-1',
+      turnId: 'turn-7',
+      originalContent: 'original',
+      editedContent: 'edited',
+      rerun,
+    });
+
+    expect(rollbackSessionToTurn).toHaveBeenCalled();
+    expect(rerun).toHaveBeenCalledWith('edited', undefined, expect.any(String));
+  });
+});
diff --git a/src/web-ui/src/flow_chat/services/UserMessageEditService.ts b/src/web-ui/src/flow_chat/services/UserMessageEditService.ts
index 56427736b6..253008581d 100644
--- a/src/web-ui/src/flow_chat/services/UserMessageEditService.ts
+++ b/src/web-ui/src/flow_chat/services/UserMessageEditService.ts
@@ -1,10 +1,11 @@
-import { snapshotAPI } from '@/infrastructure/api';
-import { globalEventBus } from '@/infrastructure/event-bus';
 import { createLogger } from '@/shared/utils/logger';
 import { flowChatStore } from '../store/FlowChatStore';
-import { pendingQueueManager } from './flow-chat-manager/PendingQueueModule';
-import { stateMachineManager } from '../state-machine';
-import { SessionExecutionEvent, SessionExecutionState } from '../state-machine/types';
+import {
+  endSessionMutation,
+  tryBeginSessionMutation,
+} from '../store/sessionMutationStore';
+import { resolveMaterializedSessionTurnIdentity } from '../utils/flowChatTurnIdentity';
+import { rollbackSessionToTurn } from './SessionRollbackService';
 
 const log = createLogger('UserMessageEditService');
 
@@ -18,19 +19,15 @@ export interface UserMessageEditImpact {
 export interface EditAndRerunUserMessageRequest {
   sessionId: string;
   turnId: string;
-  turnIndex: number;
   originalContent: string;
   editedContent: string;
   agentType?: string;
-  rerun: (content: string, agentType?: string) => Promise<void>;
+  rerun: (content: string, agentType: string | undefined, leaseId: string) => Promise<void>;
 }
 
-export function describeUserMessageEditImpact(sessionId: string): UserMessageEditImpact {
-  const currentState = stateMachineManager.getCurrentState(sessionId);
+export function describeUserMessageEditImpact(_sessionId: string): UserMessageEditImpact {
   return {
-    willStopRunningTask:
-      currentState === SessionExecutionState.PROCESSING ||
-      currentState === SessionExecutionState.FINISHING,
+    willStopRunningTask: false,
     willRestoreFiles: true,
     willDeleteTurns: true,
     willRerun: true,
@@ -74,8 +71,12 @@ export async function editAndRerunUserMessage(
     throw new Error(`Session does not exist: ${request.sessionId}`);
   }
 
-  const targetTurn = session.dialogTurns[request.turnIndex];
-  if (!targetTurn || targetTurn.id !== request.turnId) {
+  const targetTurn = resolveMaterializedSessionTurnIdentity(
+    session,
+    flowChatStore.getSessionHistoryViewState(request.sessionId),
+    request.turnId,
+  )?.turn;
+  if (!targetTurn) {
     throw new Error('Message edit target is no longer available');
   }
 
@@ -84,31 +85,25 @@ export async function editAndRerunUserMessage(
     throw new Error('Only messages sent from the desktop chat input can be edited');
   }
 
-  if (pendingQueueManager.list(request.sessionId).length > 0) {
-    throw new Error('Edit the message after clearing the pending queue');
-  }
-
-  const currentState = stateMachineManager.getCurrentState(request.sessionId);
-  if (currentState === SessionExecutionState.PROCESSING || currentState === SessionExecutionState.FINISHING) {
-    await stateMachineManager.transition(request.sessionId, SessionExecutionEvent.USER_CANCEL);
-  } else if (currentState === SessionExecutionState.ERROR) {
-    await stateMachineManager.transition(request.sessionId, SessionExecutionEvent.RESET);
-  }
-
   log.info('Editing user message and rerunning from turn', {
     sessionId: request.sessionId,
-    turnIndex: request.turnIndex,
     turnId: request.turnId,
   });
 
-  const restoredFiles = await snapshotAPI.rollbackToTurn(request.sessionId, request.turnIndex, true);
-
-  flowChatStore.truncateDialogTurnsFrom(request.sessionId, request.turnIndex);
-
-  globalEventBus.emit('file-tree:refresh');
-  restoredFiles.forEach(filePath => {
-    globalEventBus.emit('editor:file-changed', { filePath });
-  });
-
-  await request.rerun(trimmedEditedContent, request.agentType);
+  const lease = tryBeginSessionMutation(request.sessionId, 'edit-rerun', request.turnId);
+  if (!lease) {
+    throw new Error('Another Session history mutation is already in progress');
+  }
+  try {
+    await rollbackSessionToTurn({
+      sessionId: request.sessionId,
+      targetTurnId: request.turnId,
+      kind: 'edit-rerun',
+      lease,
+    });
+
+    await request.rerun(trimmedEditedContent, request.agentType, lease.leaseId);
+  } finally {
+    endSessionMutation(lease);
+  }
 }
diff --git a/src/web-ui/src/flow_chat/services/flow-chat-manager/EventHandlerModule.test.ts b/src/web-ui/src/flow_chat/services/flow-chat-manager/EventHandlerModule.test.ts
index 5462ae2c1f..645bed7cd1 100644
--- a/src/web-ui/src/flow_chat/services/flow-chat-manager/EventHandlerModule.test.ts
+++ b/src/web-ui/src/flow_chat/services/flow-chat-manager/EventHandlerModule.test.ts
@@ -5,15 +5,21 @@ import {
   handleSessionStateChanged,
   insertSteeringItemIfAbsent,
   isAppWindowFocused,
+  projectDialogTurnRecovered,
   shouldProcessEvent,
 } from './EventHandlerModule';
 import { stateMachineManager } from '../../state-machine';
 import { SessionExecutionEvent, SessionExecutionState } from '../../state-machine/types';
 import { FlowChatStore } from '../../store/FlowChatStore';
+import {
+  markSessionTurnsRetired,
+  useSessionMutationStore,
+} from '../../store/sessionMutationStore';
 import { notificationService } from '../../../shared/notification-system/services/NotificationService';
 import type { DialogTurn, FlowToolItem, FlowUserSteeringItem, ModelRound, Session } from '../../types/flow-chat';
 import type { FlowChatContext } from './types';
 import { markOptimisticDispatchTurnMetadata } from '@/features/dispatch/optimisticDispatchTurn';
+import { interruptedTurnRecoveryGate } from '../interruptedTurnRecoveryGate';
 
 const { handleCompressionCompleted, handleTokenUsageUpdate } = __test_only__;
 
@@ -31,6 +37,339 @@ describe('isAppWindowFocused', () => {
   });
 });
 
+describe('interrupted turn lifecycle', () => {
+  beforeEach(() => {
+    resetFlowChatStore();
+    stateMachineManager.clear();
+    interruptedTurnRecoveryGate.resetForTests();
+  });
+
+  afterEach(() => {
+    resetFlowChatStore();
+    stateMachineManager.clear();
+    interruptedTurnRecoveryGate.resetForTests();
+  });
+
+  it('projects the authoritative recovered fence and releases the shared gate', async () => {
+    const turn: DialogTurn = {
+      id: 'turn-1',
+      sessionId: 'session-1',
+      agentType: 'agentic',
+      userMessage: { id: 'user-1', content: 'continue this work', timestamp: 1 },
+      modelRounds: [{
+        id: 'round-0',
+        index: 0,
+        items: [],
+        isStreaming: true,
+        isComplete: false,
+        status: 'streaming',
+        startTime: 1,
+      }],
+      status: 'processing',
+      startTime: 1,
+    };
+    FlowChatStore.getInstance().setState(() => ({
+      sessions: new Map([['session-1', {
+        sessionId: 'session-1',
+        dialogTurns: [turn],
+        status: 'active',
+        config: { agentType: 'agentic' },
+        createdAt: 1,
+        lastActiveAt: 1,
+        error: null,
+        sessionKind: 'normal',
+      } as Session]]),
+      activeSessionId: 'session-1',
+    }));
+    await stateMachineManager.transition('session-1', SessionExecutionEvent.START, {
+      taskId: 'session-1',
+      dialogTurnId: 'turn-1',
+    });
+    const context = createFlowChatContext();
+
+    __test_only__.handleDialogTurnInterrupted(context, {
+      sessionId: 'session-1',
+      turnId: 'turn-1',
+      executionGeneration: 0,
+    });
+    await Promise.resolve();
+
+    let session = FlowChatStore.getInstance().getState().sessions.get('session-1')!;
+    expect(session.dialogTurns).toHaveLength(1);
+    expect(session.dialogTurns[0]).toMatchObject({
+      id: 'turn-1',
+      status: 'cancelled',
+      finishReason: 'interrupted',
+      recovery: { status: 'interrupted', executionGeneration: 0 },
+    });
+    expect(stateMachineManager.getCurrentState('session-1')).toBe(SessionExecutionState.IDLE);
+
+    expect(interruptedTurnRecoveryGate.tryBegin({
+      sessionId: 'session-1',
+      turnId: 'turn-1',
+      executionGeneration: 0,
+    })).toBe(true);
+
+    __test_only__.handleDialogTurnRecovered(context, {
+      sessionId: 'session-1',
+      turnId: 'turn-1',
+      executionGeneration: 1,
+    });
+    await Promise.resolve();
+
+    session = FlowChatStore.getInstance().getState().sessions.get('session-1')!;
+    expect(session.dialogTurns).toHaveLength(1);
+    expect(session.dialogTurns[0]).toMatchObject({
+      id: 'turn-1',
+      status: 'processing',
+      recovery: { status: 'recovering', executionGeneration: 1 },
+    });
+    expect(stateMachineManager.getCurrentState('session-1')).toBe(
+      SessionExecutionState.PROCESSING,
+    );
+    expect(interruptedTurnRecoveryGate.isSessionInFlight('session-1')).toBe(false);
+
+    __test_only__.handleDialogTurnInterrupted(context, {
+      sessionId: 'session-1',
+      turnId: 'turn-1',
+      executionGeneration: 0,
+    });
+    await Promise.resolve();
+
+    session = FlowChatStore.getInstance().getState().sessions.get('session-1')!;
+    expect(session.dialogTurns[0]).toMatchObject({
+      status: 'processing',
+      recovery: { status: 'recovering', executionGeneration: 1 },
+    });
+    expect(stateMachineManager.getCurrentState('session-1')).toBe(
+      SessionExecutionState.PROCESSING,
+    );
+  });
+
+  it('does not settle a newer turn when an older interrupted event arrives late', async () => {
+    const oldTurn: DialogTurn = {
+      id: 'turn-1',
+      sessionId: 'session-1',
+      agentType: 'agentic',
+      userMessage: { id: 'user-1', content: 'old work', timestamp: 1 },
+      modelRounds: [],
+      status: 'processing',
+      startTime: 1,
+    };
+    createSessionWithTurn(oldTurn);
+    await stateMachineManager.transition('session-1', SessionExecutionEvent.START, {
+      taskId: 'session-1',
+      dialogTurnId: 'turn-1',
+    });
+    const context = createFlowChatContext();
+
+    await stateMachineManager.transition(
+      'session-1',
+      SessionExecutionEvent.BACKEND_STREAM_COMPLETED,
+    );
+    handleSessionStateChanged(context, {
+      sessionId: 'session-1',
+      newState: 'Idle',
+    });
+    await Promise.resolve();
+
+    const newTurn: DialogTurn = {
+      id: 'turn-2',
+      sessionId: 'session-1',
+      agentType: 'agentic',
+      userMessage: { id: 'user-2', content: 'new work', timestamp: 2 },
+      modelRounds: [],
+      status: 'processing',
+      startTime: 2,
+    };
+    FlowChatStore.getInstance().setState(state => {
+      const sessions = new Map(state.sessions);
+      const session = sessions.get('session-1')!;
+      sessions.set('session-1', {
+        ...session,
+        dialogTurns: [...session.dialogTurns, newTurn],
+      });
+      return { ...state, sessions };
+    });
+    await stateMachineManager.transition('session-1', SessionExecutionEvent.START, {
+      taskId: 'session-1',
+      dialogTurnId: 'turn-2',
+    });
+
+    __test_only__.handleDialogTurnInterrupted(context, {
+      sessionId: 'session-1',
+      turnId: 'turn-1',
+      executionGeneration: 0,
+    });
+    await Promise.resolve();
+
+    const session = FlowChatStore.getInstance().getState().sessions.get('session-1')!;
+    expect(session.dialogTurns[0]).toMatchObject({
+      id: 'turn-1',
+      status: 'cancelled',
+      recovery: { status: 'interrupted', executionGeneration: 0 },
+    });
+    expect(session.dialogTurns[1]).toMatchObject({ id: 'turn-2', status: 'processing' });
+    expect(stateMachineManager.getCurrentState('session-1')).toBe(
+      SessionExecutionState.PROCESSING,
+    );
+    expect(stateMachineManager.get('session-1')?.getContext().currentDialogTurnId).toBe('turn-2');
+  });
+
+  it('does not revive a recovered generation after it was interrupted again', async () => {
+    const turn: DialogTurn = {
+      id: 'turn-1',
+      sessionId: 'session-1',
+      agentType: 'agentic',
+      userMessage: { id: 'user-1', content: 'resume safely', timestamp: 1 },
+      modelRounds: [],
+      status: 'cancelled',
+      finishReason: 'interrupted',
+      recovery: { status: 'interrupted', executionGeneration: 0, resumeCount: 0 },
+      startTime: 1,
+    };
+    createSessionWithTurn(turn);
+    const context = createFlowChatContext();
+
+    projectDialogTurnRecovered(context, {
+      sessionId: 'session-1',
+      turnId: 'turn-1',
+      executionGeneration: 1,
+    });
+    await Promise.resolve();
+    __test_only__.handleDialogTurnInterrupted(context, {
+      sessionId: 'session-1',
+      turnId: 'turn-1',
+      executionGeneration: 1,
+    });
+    await Promise.resolve();
+
+    __test_only__.handleDialogTurnRecovered(context, {
+      sessionId: 'session-1',
+      turnId: 'turn-1',
+      executionGeneration: 1,
+    });
+    await Promise.resolve();
+
+    const current = FlowChatStore.getInstance().getState().sessions
+      .get('session-1')!.dialogTurns[0];
+    expect(current).toMatchObject({
+      status: 'cancelled',
+      finishReason: 'interrupted',
+      recovery: { status: 'interrupted', executionGeneration: 1 },
+    });
+    expect(stateMachineManager.getCurrentState('session-1')).toBe(SessionExecutionState.IDLE);
+  });
+
+  it('accepts durable recovered completion when the recovered event was dropped', async () => {
+    vi.useFakeTimers();
+    const turn: DialogTurn = {
+      id: 'turn-1',
+      sessionId: 'session-1',
+      agentType: 'agentic',
+      userMessage: { id: 'user-1', content: 'keep retryable', timestamp: 1 },
+      modelRounds: [],
+      status: 'cancelled',
+      finishReason: 'interrupted',
+      recovery: { status: 'interrupted', executionGeneration: 1, resumeCount: 1 },
+      startTime: 1,
+    };
+    createSessionWithTurn(turn);
+    const context = createFlowChatContext();
+
+    handleDialogTurnComplete(context, {
+      sessionId: 'session-1',
+      turnId: 'turn-1',
+      success: true,
+      finishReason: 'complete',
+    }, vi.fn());
+    await vi.advanceTimersByTimeAsync(500);
+
+    expect(FlowChatStore.getInstance().getState().sessions
+      .get('session-1')!.dialogTurns[0]).toMatchObject({
+      status: 'completed',
+      finishReason: 'complete',
+    });
+    expect(FlowChatStore.getInstance().getState().sessions
+      .get('session-1')!.dialogTurns[0].recovery).toBeUndefined();
+    vi.useRealTimers();
+  });
+
+  it('does not settle a newer turn when an older cancelled event arrives late', async () => {
+    const oldTurn: DialogTurn = {
+      id: 'turn-1',
+      sessionId: 'session-1',
+      agentType: 'agentic',
+      userMessage: { id: 'user-1', content: 'old', timestamp: 1 },
+      modelRounds: [],
+      status: 'processing',
+      startTime: 1,
+    };
+    const newTurn: DialogTurn = {
+      id: 'turn-2',
+      sessionId: 'session-1',
+      agentType: 'agentic',
+      userMessage: { id: 'user-2', content: 'new', timestamp: 2 },
+      modelRounds: [],
+      status: 'processing',
+      startTime: 2,
+    };
+    createSessionWithTurn(oldTurn);
+    FlowChatStore.getInstance().setState(state => {
+      const sessions = new Map(state.sessions);
+      sessions.set('session-1', { ...sessions.get('session-1')!, dialogTurns: [oldTurn, newTurn] });
+      return { ...state, sessions };
+    });
+    await stateMachineManager.transition('session-1', SessionExecutionEvent.START, {
+      taskId: 'session-1',
+      dialogTurnId: 'turn-2',
+    });
+    const context = createFlowChatContext();
+
+    __test_only__.handleDialogTurnCancelled(context, {
+      sessionId: 'session-1',
+      turnId: 'turn-1',
+    }, vi.fn());
+    await Promise.resolve();
+
+    expect(FlowChatStore.getInstance().getState().sessions
+      .get('session-1')!.dialogTurns[1]).toMatchObject({ id: 'turn-2', status: 'processing' });
+    expect(stateMachineManager.getCurrentState('session-1')).toBe(
+      SessionExecutionState.PROCESSING,
+    );
+  });
+
+  it('holds finishing when backend idle arrives before the cancellation outcome', async () => {
+    const turn: DialogTurn = {
+      id: 'turn-1',
+      sessionId: 'session-1',
+      agentType: 'agentic',
+      userMessage: { id: 'user-1', content: 'stop', timestamp: 1 },
+      modelRounds: [],
+      status: 'processing',
+      startTime: 1,
+    };
+    createSessionWithTurn(turn);
+    await stateMachineManager.transition('session-1', SessionExecutionEvent.START, {
+      taskId: 'session-1',
+      dialogTurnId: 'turn-1',
+    });
+    await stateMachineManager.transition(
+      'session-1',
+      SessionExecutionEvent.BACKEND_STREAM_COMPLETED,
+    );
+    const context = createFlowChatContext();
+    context.userCancelledSessionIds.add('session-1');
+
+    handleSessionStateChanged(context, { sessionId: 'session-1', newState: 'Idle' });
+    await Promise.resolve();
+
+    expect(stateMachineManager.getCurrentState('session-1')).toBe(
+      SessionExecutionState.FINISHING,
+    );
+  });
+});
+
 describe('resolveDialogTurnDisplayContent', () => {
   it('prefers original user input for ordinary turns', () => {
     expect(
@@ -420,11 +759,13 @@ describe('shouldProcessEvent', () => {
   beforeEach(() => {
     vi.restoreAllMocks();
     resetFlowChatStore();
+    useSessionMutationStore.setState({ mutations: new Map(), retiredTurnIds: new Map() });
   });
 
   afterEach(() => {
     resetFlowChatStore();
     stateMachineManager.clear();
+    useSessionMutationStore.setState({ mutations: new Map(), retiredTurnIds: new Map() });
   });
 
   it('returns false for data event when no state machine exists', () => {
@@ -619,6 +960,26 @@ describe('shouldProcessEvent', () => {
       shouldProcessEvent(mockSessionId, mockTurnId, 'data', 'TextChunk'),
     ).toBe(true);
   });
+
+  it('drops data and turn-start events for a retired rollback suffix', () => {
+    const context = createFlowChatContext();
+    stateMachineManager.getOrCreate(mockSessionId);
+    markSessionTurnsRetired(mockSessionId, [mockTurnId]);
+
+    expect(
+      shouldProcessEvent(mockSessionId, mockTurnId, 'data', 'TextChunk'),
+    ).toBe(false);
+
+    __test_only__.handleDialogTurnStarted(context, {
+      sessionId: mockSessionId,
+      turnId: mockTurnId,
+      turnIndex: 7,
+      userInput: 'late rollback event',
+    });
+    expect(
+      FlowChatStore.getInstance().getState().sessions.get(mockSessionId),
+    ).toBeUndefined();
+  });
 });
 
 describe('handleDialogTurnFailed', () => {
@@ -647,6 +1008,7 @@ describe('handleDialogTurnFailed', () => {
       startTime: 900,
     });
     const context = createFlowChatContext();
+    context.userCancelledSessionIds.add('session-1');
 
     __test_only__.handleDialogTurnFailed(context, {
       sessionId: 'session-1',
@@ -674,6 +1036,7 @@ describe('handleDialogTurnFailed', () => {
     });
     expect(notificationService.error).not.toHaveBeenCalled();
     expect(notificationService.warning).not.toHaveBeenCalled();
+    expect(context.userCancelledSessionIds.has('session-1')).toBe(false);
   });
 });
 
@@ -1129,6 +1492,31 @@ describe('handleDialogTurnComplete', () => {
     expect(finalizedTurn?.status).toBe('completed');
     expect(finalizedTurn?.endTime).toBe(eventOwnedEndTime);
   });
+
+  it('clears the cancellation gate when the same turn completes during cancel', async () => {
+    vi.useFakeTimers();
+    try {
+      putFinishingSessionInStore();
+      const context = createFlowChatContext();
+      context.userCancelledSessionIds.add('session-1');
+      await setFinishingMachine();
+
+      handleDialogTurnComplete(context, {
+        sessionId: 'session-1',
+        turnId: 'turn-1',
+        success: true,
+        finishReason: 'complete',
+        hasFinalResponse: true,
+      }, vi.fn());
+
+      expect(context.userCancelledSessionIds.has('session-1')).toBe(true);
+      await vi.advanceTimersByTimeAsync(500);
+      expect(context.userCancelledSessionIds.has('session-1')).toBe(false);
+      expect(stateMachineManager.getCurrentState('session-1')).toBe(SessionExecutionState.IDLE);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
 });
 
 describe('handleCompressionCompleted', () => {
diff --git a/src/web-ui/src/flow_chat/services/flow-chat-manager/EventHandlerModule.ts b/src/web-ui/src/flow_chat/services/flow-chat-manager/EventHandlerModule.ts
index f39592b038..a428af3335 100644
--- a/src/web-ui/src/flow_chat/services/flow-chat-manager/EventHandlerModule.ts
+++ b/src/web-ui/src/flow_chat/services/flow-chat-manager/EventHandlerModule.ts
@@ -4,6 +4,7 @@
  */
 
 import { FlowChatStore, mergeModelRoundAttemptDiagnostics } from '../../store/FlowChatStore';
+import { isSessionTurnRetired } from '../../store/sessionMutationStore';
 import { stateMachineManager } from '../../state-machine';
 import { SessionExecutionEvent, SessionExecutionState } from '../../state-machine/types';
 import { agenticEventListener, type AgenticEventCallbacks } from '../AgenticEventListener';
@@ -37,11 +38,13 @@ import type {
   SessionModelAutoMigratedEvent,
   SessionReasoningPresetAutoClearedEvent,
   SubagentSessionLinkedEvent,
+  RecoverInterruptedDialogTurnResponse,
 } from '@/infrastructure/api/service-api/AgentAPI';
 import { MCPAPI } from '@/infrastructure/api/service-api/MCPAPI';
 import { ACPClientAPI, type AcpPermissionRequestEvent } from '@/infrastructure/api/service-api/ACPClientAPI';
 import { globalEventBus } from '@/infrastructure/event-bus';
 import type { FlowChatContext, DialogTurn, ModelRound, FlowToolItem } from './types';
+import type { Session, SteeringImage } from '../../types/flow-chat';
 import {
   normalizeAiErrorDetail,
   type AiErrorDetail,
@@ -52,6 +55,7 @@ import { useBackgroundCommandActivityStore } from '../../store/backgroundCommand
 import { useBackgroundSubagentActivityStore } from '../../store/backgroundSubagentActivityStore';
 import { createTab } from '@/shared/utils/tabUtils';
 import { splitFilePathAndContent } from '@/shared/utils/partialJsonParser';
+import { interruptedTurnRecoveryGate } from '../interruptedTurnRecoveryGate';
 
 const pendingImageAnalysisTurns = new Map<string, string>();
 import { 
@@ -165,6 +169,9 @@ export const __test_only__ = {
   handleModelRoundStart,
   handleTokenUsageUpdate,
   handleCompressionCompleted,
+  handleDialogTurnInterrupted,
+  handleDialogTurnRecovered,
+  handleDialogTurnCancelled,
 };
 
 function shouldMarkUnreadCompletion(sessionId: string): boolean {
@@ -172,6 +179,17 @@ function shouldMarkUnreadCompletion(sessionId: string): boolean {
   return sessionId !== activeSessionId || !isAppWindowFocused();
 }
 
+function eventOwnsLatestSessionTurn(
+  session: Session,
+  sessionId: string,
+  turnId: string,
+): boolean {
+  if (session.dialogTurns.at(-1)?.id !== turnId) return false;
+  const machine = stateMachineManager.get(sessionId);
+  const currentTurnId = machine?.getContext().currentDialogTurnId;
+  return !currentTurnId || currentTurnId === turnId;
+}
+
 function logDroppedDataEvent(
   eventName: string,
   sessionId: string,
@@ -623,6 +641,13 @@ export function shouldProcessEvent(
   eventType: 'data' | 'control' | 'state_sync',
   eventName = 'unknown'
 ): boolean {
+  if (turnId && isSessionTurnRetired(sessionId, turnId)) {
+    if (eventType === 'data') {
+      logDroppedDataEvent(eventName, sessionId, turnId, { reason: 'retired_turn' });
+    }
+    return false;
+  }
+
   if (eventType === 'state_sync') {
     return true;
   }
@@ -794,6 +819,12 @@ export async function initializeEventListeners(
     onDialogTurnCancelled: (event) => {
       handleDialogTurnCancelled(context, event, onTodoWriteResult);
     },
+    onDialogTurnInterrupted: (event) => {
+      handleDialogTurnInterrupted(context, event);
+    },
+    onDialogTurnRecovered: (event) => {
+      handleDialogTurnRecovered(context, event);
+    },
     onTokenUsageUpdated: (event) => {
       handleTokenUsageUpdate(context, event);
     },
@@ -1057,6 +1088,9 @@ function finalizeTurnCompletionState(
     clearPendingTurnCompletion(context, sessionId, turnId);
     return;
   }
+  const runtimeOwnsTurnPersistence = Boolean(
+    session.dialogTurns.find(turn => turn.id === turnId)?.recovery,
+  );
 
   completeActiveTextItems(context, sessionId, turnId);
   clearRuntimeStatus(context, sessionId, turnId);
@@ -1087,7 +1121,8 @@ function finalizeTurnCompletionState(
       ...turn,
       modelRounds: updatedModelRounds,
       status: 'completed' as const,
-      endTime: turn.endTime ?? completedAt
+      endTime: turn.endTime ?? completedAt,
+      recovery: undefined,
     };
   });
   reconcileBackgroundSubagentSession(sessionId);
@@ -1104,9 +1139,13 @@ function finalizeTurnCompletionState(
     appendPlanDisplayItemsIfNeeded(context, sessionId, turnId, dialogTurn);
   }
 
-  saveDialogTurnToDisk(context, sessionId, turnId).catch(error => {
-    log.warn('Failed to save dialog turn (non-critical)', { sessionId, turnId, error });
-  });
+  if (!runtimeOwnsTurnPersistence) {
+    saveDialogTurnToDisk(context, sessionId, turnId).catch(error => {
+      log.warn('Failed to save dialog turn (non-critical)', { sessionId, turnId, error });
+    });
+  }
+
+  context.userCancelledSessionIds.delete(sessionId);
 
   if (shouldMarkUnreadCompletion(sessionId)) {
     const pending = context.pendingTurnCompletions.get(sessionId);
@@ -1241,10 +1280,12 @@ export function insertSteeringItemIfAbsent(params: {
   turnId: string;
   steeringId: string;
   content: string;
+  /** Images sent with the steering message, rendered under its text. */
+  images?: SteeringImage[];
   roundIndex?: number;
   status?: 'pending' | 'completed';
 }): boolean {
-  const { sessionId, turnId, steeringId, content } = params;
+  const { sessionId, turnId, steeringId, content, images } = params;
   const roundIndex = typeof params.roundIndex === 'number' ? params.roundIndex : 0;
   const status = params.status ?? 'completed';
 
@@ -1278,6 +1319,7 @@ export function insertSteeringItemIfAbsent(params: {
     status,
     steeringId,
     content,
+    images: images?.length ? images : undefined,
     roundIndex,
   };
 
@@ -1376,6 +1418,12 @@ export function handleSessionStateChanged(context: FlowChatContext, event: any):
   machineContext.backendSyncedAt = Date.now();
 
   if (isExpectedFinishingDrift) {
+    if (context.userCancelledSessionIds.has(sessionId)) {
+      log.debug('Holding FINISHING until the cancellation outcome is authoritative', {
+        sessionId,
+      });
+      return;
+    }
     finalizePendingTurnCompletionNow(context, sessionId);
     if (stateMachineManager.getCurrentState(sessionId) === SessionExecutionState.FINISHING) {
       const finishingTurnId = findFinishingTurnForBackendIdle(
@@ -1533,6 +1581,11 @@ function handleImageAnalysisCompleted(_context: FlowChatContext, event: ImageAna
 function handleDialogTurnStarted(context: FlowChatContext, event: any): void {
   const { sessionId, turnId, turnIndex, userInput, originalUserInput, userMessageMetadata } = event;
 
+  if (isSessionTurnRetired(sessionId, turnId)) {
+    log.debug('Dropped DialogTurnStarted for retired turn', { sessionId, turnId });
+    return;
+  }
+
   finalizePendingTurnCompletionNow(context, sessionId);
   clearPendingTurnCompletion(context, sessionId, turnId);
 
@@ -1687,6 +1740,11 @@ function handleDialogTurnStarted(context: FlowChatContext, event: any): void {
   if (projectedNewTurn) {
     reconcileBackgroundSubagentSession(sessionId);
 
+    // Backend admission of a distinct new Turn supersedes any stale local
+    // cancellation gate for the previous Turn. Late terminal events remain
+    // identity-guarded and cannot settle this new execution.
+    context.userCancelledSessionIds.delete(sessionId);
+
     context.contentBuffers.set(sessionId, new Map());
     context.activeTextItems.set(sessionId, new Map());
 
@@ -1715,7 +1773,10 @@ function handleDialogTurnStarted(context: FlowChatContext, event: any): void {
       kind: turn.kind || turnKind,
       userMessage: {
         ...turn.userMessage,
-        metadata: turn.userMessage.metadata || userMessageMetadata,
+        metadata: {
+          ...(turn.userMessage.metadata ?? {}),
+          ...(userMessageMetadata ?? {}),
+        },
       },
       storageTurnIndex: turnIndex,
       backendTurnIndex: turnIndex,
@@ -2400,6 +2461,11 @@ export function handleDialogTurnComplete(
     log.warn('DialogTurnCompleted missing sessionId or turnId', { event });
     return;
   }
+  interruptedTurnRecoveryGate.clearTerminal(sessionId, turnId);
+
+
+  const store = FlowChatStore.getInstance();
+  const session = store.getState().sessions.get(sessionId);
 
   if (success === false) {
     handleDialogTurnFailed(context, {
@@ -2421,23 +2487,36 @@ export function handleDialogTurnComplete(
   }
   context.handledTerminalTurnEvents.add(terminalKey);
 
-  const machine = stateMachineManager.get(sessionId);
-  if (machine) {
-    const ctx = machine.getContext();
-    if (ctx.currentDialogTurnId !== turnId) {
-      ctx.currentDialogTurnId = turnId;
-    }
-  }
-
-  const store = FlowChatStore.getInstance();
-  const session = store.getState().sessions.get(sessionId);
-  
   if (!session) {
     log.debug('Session not found (dialog turn complete)', { sessionId });
     return;
   }
+  const ownsSessionSettlement = eventOwnsLatestSessionTurn(session, sessionId, turnId);
 
   context.flowChatStore.updateDialogTurn(sessionId, turnId, turn => {
+    if (!ownsSessionSettlement) {
+      const completedAt = Date.now();
+      return {
+        ...turn,
+        modelRounds: turn.modelRounds.map(round => round.isStreaming
+          ? {
+              ...round,
+              isStreaming: false,
+              isComplete: true,
+              status: 'completed' as const,
+              endTime: round.endTime ?? completedAt,
+            }
+          : round),
+        status: 'completed' as const,
+        endTime: durationMs === undefined
+          ? turn.endTime ?? completedAt
+          : turn.startTime + Math.max(0, durationMs),
+        success: success ?? undefined,
+        finishReason: finishReason ?? undefined,
+        hasFinalResponse: typeof hasFinalResponse === 'boolean' ? hasFinalResponse : undefined,
+        recovery: undefined,
+      };
+    }
     return {
       ...turn,
       status: 'finishing' as const,
@@ -2452,7 +2531,7 @@ export function handleDialogTurnComplete(
   reconcileBackgroundSubagentSession(sessionId);
 
   const currentState = stateMachineManager.getCurrentState(sessionId);
-  if (currentState === SessionExecutionState.PROCESSING) {
+  if (ownsSessionSettlement && currentState === SessionExecutionState.PROCESSING) {
     void stateMachineManager
       .transition(sessionId, SessionExecutionEvent.BACKEND_STREAM_COMPLETED)
       .catch(error => {
@@ -2462,7 +2541,9 @@ export function handleDialogTurnComplete(
     log.debug('Skipping BACKEND_STREAM_COMPLETED transition', { currentState, sessionId, turnId });
   }
 
-  beginTurnCompletion(context, sessionId, turnId, partialRecoveryReason);
+  if (ownsSessionSettlement) {
+    beginTurnCompletion(context, sessionId, turnId, partialRecoveryReason);
+  }
 }
 
 function normalizeDialogErrorDetail(event: any): AiErrorDetail {
@@ -2478,6 +2559,10 @@ function handleDialogTurnFailed(context: FlowChatContext, event: any): void {
   const { sessionId, turnId, error } = event;
   const errorDetail = normalizeDialogErrorDetail(event);
 
+  if (sessionId && turnId) {
+    interruptedTurnRecoveryGate.clearTerminal(sessionId, turnId);
+  }
+
   // P1-11: Idempotent terminal-event handling.
   if (sessionId && turnId) {
     const terminalKey = `${sessionId}:${turnId}`;
@@ -2499,21 +2584,16 @@ function handleDialogTurnFailed(context: FlowChatContext, event: any): void {
     log.debug('Session not found (dialog turn failed)', { sessionId });
     return;
   }
+  const ownsSessionSettlement = eventOwnsLatestSessionTurn(session, sessionId, turnId);
   
-  const sessionActiveTextItems = context.activeTextItems.get(sessionId);
-  if (sessionActiveTextItems) {
-    sessionActiveTextItems.clear();
-  }
-  
-  const sessionContentBuffer = context.contentBuffers.get(sessionId);
-  if (sessionContentBuffer) {
-    sessionContentBuffer.clear();
+  if (ownsSessionSettlement) {
+    cleanupSessionBuffers(context, sessionId);
+    context.flowChatStore.markSessionFinished(sessionId);
   }
-
-  context.flowChatStore.markSessionFinished(sessionId);
   
   const dialogTurn = session.dialogTurns.find(turn => turn.id === turnId);
   if (dialogTurn) {
+    const runtimeOwnsTurnPersistence = Boolean(dialogTurn.recovery);
     const terminalError = typeof error === 'string' && error.trim()
       ? error
       : errorDetail.rawMessage || errorDetail.providerMessage || 'Execution failed';
@@ -2537,18 +2617,21 @@ function handleDialogTurnFailed(context: FlowChatContext, event: any): void {
         status: 'error' as const,
         error: terminalError,
         errorDetail,
-        endTime: Date.now()
+        endTime: Date.now(),
+        recovery: undefined,
       };
     });
     
-    saveDialogTurnToDisk(context, sessionId, turnId).catch(err => {
-      log.warn('Failed to save failed dialog turn', { sessionId, turnId, error: err });
-    });
+    if (!runtimeOwnsTurnPersistence) {
+      saveDialogTurnToDisk(context, sessionId, turnId).catch(err => {
+        log.warn('Failed to save failed dialog turn', { sessionId, turnId, error: err });
+      });
+    }
   }
   reconcileBackgroundSubagentSession(sessionId);
   
   const currentState = stateMachineManager.getCurrentState(sessionId);
-  if (isStreamingExecutionState(currentState)) {
+  if (ownsSessionSettlement && isStreamingExecutionState(currentState)) {
     stateMachineManager.transition(sessionId, SessionExecutionEvent.ERROR_OCCURRED, {
       error: error || 'Execution failed'
     }).catch(err => {
@@ -2559,9 +2642,12 @@ function handleDialogTurnFailed(context: FlowChatContext, event: any): void {
     });
   }
   
-  if (shouldMarkUnreadCompletion(sessionId)) {
+  if (ownsSessionSettlement && shouldMarkUnreadCompletion(sessionId)) {
     context.flowChatStore.markSessionUnreadCompletion(sessionId, 'error');
   }
+  if (ownsSessionSettlement) {
+    context.userCancelledSessionIds.delete(sessionId);
+  }
 }
 
 /**
@@ -2574,6 +2660,10 @@ function handleDialogTurnCancelled(
 ): void {
   const { sessionId, turnId } = event;
 
+  if (sessionId && turnId) {
+    interruptedTurnRecoveryGate.clearTerminal(sessionId, turnId);
+  }
+
   // P1-11: Idempotent terminal-event handling. The execution engine may emit
   // DialogTurnCancelled when it detects cancellation between rounds, and the
   // coordinator wrapper unconditionally re-emits one when the turn returns
@@ -2599,18 +2689,15 @@ function handleDialogTurnCancelled(
     log.debug('Session not found (dialog turn cancelled)', { sessionId });
     return;
   }
+  const ownsSessionSettlement = eventOwnsLatestSessionTurn(session, sessionId, turnId);
   
-  const sessionActiveTextItems = context.activeTextItems.get(sessionId);
-  if (sessionActiveTextItems) {
-    sessionActiveTextItems.clear();
-  }
-  
-  const sessionContentBuffer = context.contentBuffers.get(sessionId);
-  if (sessionContentBuffer) {
-    sessionContentBuffer.clear();
+  if (ownsSessionSettlement) {
+    cleanupSessionBuffers(context, sessionId);
+    context.flowChatStore.markSessionFinished(sessionId);
   }
-
-  context.flowChatStore.markSessionFinished(sessionId);
+  const runtimeOwnsTurnPersistence = Boolean(
+    session.dialogTurns.find(turn => turn.id === turnId)?.recovery,
+  );
   
   context.flowChatStore.updateDialogTurn(sessionId, turnId, turn => {
     const updatedModelRounds = turn.modelRounds.map((round) => {
@@ -2630,7 +2717,8 @@ function handleDialogTurnCancelled(
       ...turn,
       modelRounds: updatedModelRounds,
       status: 'cancelled' as const,
-      endTime: Date.now()
+      endTime: Date.now(),
+      recovery: undefined,
     };
   });
   reconcileBackgroundSubagentSession(sessionId);
@@ -2640,16 +2728,18 @@ function handleDialogTurnCancelled(
     appendPlanDisplayItemsIfNeeded(context, sessionId, turnId, dialogTurn);
   }
   
-  saveDialogTurnToDisk(context, sessionId, turnId).catch(err => {
-    log.warn('Failed to save cancelled dialog turn', { sessionId, turnId, error: err });
-  });
+  if (!runtimeOwnsTurnPersistence) {
+    saveDialogTurnToDisk(context, sessionId, turnId).catch(err => {
+      log.warn('Failed to save cancelled dialog turn', { sessionId, turnId, error: err });
+    });
+  }
 
   // Transition state machine to IDLE.  When the desktop's own stop button
   // is used, USER_CANCEL is dispatched before DialogTurnCancelled arrives,
   // so the machine is already IDLE.  When cancellation comes from an
   // external source (mobile remote), the machine is still PROCESSING.
   const currentState = stateMachineManager.getCurrentState(sessionId);
-  if (isStreamingExecutionState(currentState)) {
+  if (ownsSessionSettlement && isStreamingExecutionState(currentState)) {
     void stateMachineManager
       .transition(sessionId, SessionExecutionEvent.FINISHING_SETTLED)
       .catch(error => {
@@ -2657,10 +2747,197 @@ function handleDialogTurnCancelled(
       });
   }
 
-  if (shouldMarkUnreadCompletion(sessionId) && !context.userCancelledSessionIds.has(sessionId)) {
+  if (
+    ownsSessionSettlement
+    && shouldMarkUnreadCompletion(sessionId)
+    && !context.userCancelledSessionIds.has(sessionId)
+  ) {
     context.flowChatStore.markSessionUnreadCompletion(sessionId, 'completed');
   }
-  context.userCancelledSessionIds.delete(sessionId);
+  if (ownsSessionSettlement) {
+    context.userCancelledSessionIds.delete(sessionId);
+  }
+}
+
+function handleDialogTurnInterrupted(context: FlowChatContext, event: any): void {
+  const sessionId = event?.sessionId ?? event?.session_id;
+  const turnId = event?.turnId ?? event?.turn_id;
+  const executionGeneration = optionalNumber(
+    event?.executionGeneration ?? event?.execution_generation,
+  );
+  const rawModelId = event?.modelId ?? event?.model_id;
+  const modelId = typeof rawModelId === 'string' && rawModelId.trim()
+    ? rawModelId.trim()
+    : undefined;
+  if (!sessionId || !turnId || executionGeneration === undefined) {
+    log.warn('DialogTurnInterrupted missing identity or generation', { event });
+    return;
+  }
+  interruptedTurnRecoveryGate.clearInterrupted({ sessionId, turnId, executionGeneration });
+  if (context.handledTerminalTurnEvents.has(`${sessionId}:${turnId}`)) {
+    log.debug('Ignoring DialogTurnInterrupted after authoritative terminal settlement', {
+      sessionId,
+      turnId,
+      executionGeneration,
+    });
+    return;
+  }
+  const currentTurn = context.flowChatStore
+    .getState()
+    .sessions.get(sessionId)
+    ?.dialogTurns.find(turn => turn.id === turnId);
+  const currentGeneration = currentTurn?.recovery?.executionGeneration;
+  if (
+    currentGeneration !== undefined
+    && (currentGeneration > executionGeneration
+      || (currentGeneration === executionGeneration
+        && currentTurn?.recovery?.status === 'interrupted'))
+  ) {
+    log.debug('Ignoring stale or duplicate DialogTurnInterrupted', {
+      sessionId,
+      turnId,
+      executionGeneration,
+      currentGeneration,
+    });
+    return;
+  }
+
+  const machine = stateMachineManager.get(sessionId);
+  const session = context.flowChatStore.getState().sessions.get(sessionId);
+  const latestTurnId = session?.dialogTurns.at(-1)?.id;
+  const currentState = stateMachineManager.getCurrentState(sessionId);
+  const ownsSessionSettlement = latestTurnId === turnId
+    && (machine?.getContext().currentDialogTurnId === turnId
+      || currentState === SessionExecutionState.IDLE);
+
+  clearPendingTurnCompletion(context, sessionId, turnId);
+  clearRuntimeStatus(context, sessionId, turnId);
+  if (ownsSessionSettlement) {
+    cleanupSessionBuffers(context, sessionId);
+    context.flowChatStore.markSessionFinished(sessionId);
+  }
+  context.flowChatStore.updateDialogTurn(sessionId, turnId, turn => ({
+    ...turn,
+    modelRounds: turn.modelRounds.map(round => ({
+      ...round,
+      isStreaming: false,
+      isComplete: true,
+      status: round.isStreaming ? 'cancelled' as const : round.status,
+      endTime: round.isStreaming ? Date.now() : round.endTime,
+    })),
+    status: 'cancelled' as const,
+    finishReason: 'interrupted',
+    endTime: Date.now(),
+    recovery: {
+      status: 'interrupted' as const,
+      executionGeneration,
+      resumeCount: executionGeneration,
+      interruptedAt: Date.now(),
+      modelId: modelId ?? turn.recovery?.modelId,
+    },
+  }));
+
+  if (ownsSessionSettlement && isStreamingExecutionState(currentState)) {
+    void stateMachineManager
+      .transition(sessionId, SessionExecutionEvent.FINISHING_SETTLED)
+      .catch(error => {
+        log.error('State machine transition failed on interrupted turn settlement', {
+          sessionId,
+          turnId,
+          error,
+        });
+      });
+  }
+  if (ownsSessionSettlement && shouldMarkUnreadCompletion(sessionId)) {
+    context.flowChatStore.markSessionUnreadCompletion(sessionId, 'interrupted');
+  }
+  if (ownsSessionSettlement) {
+    context.userCancelledSessionIds.delete(sessionId);
+  }
+}
+
+function handleDialogTurnRecovered(context: FlowChatContext, event: any): void {
+  const sessionId = event?.sessionId ?? event?.session_id;
+  const turnId = event?.turnId ?? event?.turn_id;
+  const executionGeneration = optionalNumber(
+    event?.executionGeneration ?? event?.execution_generation,
+  );
+  if (!sessionId || !turnId || executionGeneration === undefined) {
+    log.warn('DialogTurnRecovered missing identity or generation', { event });
+    return;
+  }
+  if (projectDialogTurnRecovered(context, { sessionId, turnId, executionGeneration })) {
+    interruptedTurnRecoveryGate.clearRecovered({ sessionId, turnId, executionGeneration });
+  }
+}
+
+/** Apply one authoritative recovery admission from either RPC or broadcast. */
+export function projectDialogTurnRecovered(
+  context: FlowChatContext,
+  outcome: RecoverInterruptedDialogTurnResponse,
+): boolean {
+  const { sessionId, turnId, executionGeneration } = outcome;
+  const currentTurn = context.flowChatStore
+    .getState()
+    .sessions.get(sessionId)
+    ?.dialogTurns.find(turn => turn.id === turnId);
+  const recovery = currentTurn?.recovery;
+  const session = context.flowChatStore.getState().sessions.get(sessionId);
+  const isMonotonicRecovery = session?.dialogTurns.at(-1)?.id === turnId
+    && currentTurn?.status === 'cancelled'
+    && currentTurn.finishReason === 'interrupted'
+    && recovery?.status === 'interrupted'
+    && executionGeneration === recovery.executionGeneration + 1;
+  if (!isMonotonicRecovery) {
+    log.debug('Ignoring non-monotonic DialogTurnRecovered', {
+      sessionId,
+      turnId,
+      executionGeneration,
+      currentGeneration: recovery?.executionGeneration,
+      recoveryStatus: recovery?.status,
+    });
+    return false;
+  }
+
+  context.handledTerminalTurnEvents.delete(`${sessionId}:${turnId}`);
+  context.contentBuffers.set(sessionId, new Map());
+  context.activeTextItems.set(sessionId, new Map());
+  context.flowChatStore.updateDialogTurn(sessionId, turnId, turn => ({
+    ...turn,
+    status: 'processing' as const,
+    finishReason: undefined,
+    endTime: undefined,
+    success: undefined,
+    hasFinalResponse: undefined,
+    recovery: {
+      ...turn.recovery,
+      status: 'recovering' as const,
+      executionGeneration,
+      resumeCount: executionGeneration,
+    },
+  }));
+
+  const machine = stateMachineManager.get(sessionId);
+  if (machine) {
+    const machineContext = machine.getContext();
+    machineContext.taskId = sessionId;
+    machineContext.currentDialogTurnId = turnId;
+  }
+  if (stateMachineManager.getCurrentState(sessionId) === SessionExecutionState.IDLE) {
+    void stateMachineManager
+      .transition(sessionId, SessionExecutionEvent.START, {
+        taskId: sessionId,
+        dialogTurnId: turnId,
+      })
+      .catch(error => {
+        log.error('State machine transition failed on interrupted turn recovery', {
+          sessionId,
+          turnId,
+          error,
+        });
+      });
+  }
+  return true;
 }
 
 /**
diff --git a/src/web-ui/src/flow_chat/services/flow-chat-manager/MessageModule.test.ts b/src/web-ui/src/flow_chat/services/flow-chat-manager/MessageModule.test.ts
index 837d7973ff..55274b5653 100644
--- a/src/web-ui/src/flow_chat/services/flow-chat-manager/MessageModule.test.ts
+++ b/src/web-ui/src/flow_chat/services/flow-chat-manager/MessageModule.test.ts
@@ -1,14 +1,29 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { cancelSessionTask, sendMessage, syncSessionModelSelection } from './MessageModule';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  cancelSessionTask,
+  drainPendingQueue,
+  sendMessage,
+  syncSessionModelSelection,
+} from './MessageModule';
 import { SessionExecutionEvent } from '../../state-machine/types';
 import {
   getRuntimeStatus,
   resetRuntimeStatuses,
 } from '../../store/runtimeStatusStore';
+import {
+  tryBeginSessionMutation,
+  useSessionMutationStore,
+} from '../../store/sessionMutationStore';
+import { interruptedTurnRecoveryGate } from '../interruptedTurnRecoveryGate';
+import {
+  LOCAL_SURFACE_ID,
+  activateSurface,
+} from '@/infrastructure/peer-device/deviceSurface';
 
 const mockTransition = vi.fn();
 const mockGetCurrentState = vi.fn(() => 'processing');
 const mockGetStateMachine = vi.fn(() => null);
+const mockResetForSurface = vi.fn();
 const mockUpdateSessionModel = vi.fn();
 const mockStartDialogTurn = vi.fn();
 const mockGetConfigs = vi.fn();
@@ -22,6 +37,9 @@ const mockNotificationError = vi.fn();
 const mockNotificationDismiss = vi.fn();
 const mockPendingList = vi.fn((): unknown[] => []);
 const mockPendingEnqueue = vi.fn();
+const mockPendingEnqueueForSurface = vi.fn();
+const mockPendingSetStatus = vi.fn();
+const mockPendingRemove = vi.fn();
 
 vi.mock('../../state-machine', () => ({
   SessionExecutionEvent: {
@@ -29,12 +47,15 @@ vi.mock('../../state-machine', () => ({
     USER_CANCEL: 'user_cancel',
   },
   SessionExecutionState: {
+    IDLE: 'idle',
     PROCESSING: 'processing',
+    FINISHING: 'finishing',
   },
   stateMachineManager: {
     getCurrentState: (...args: unknown[]) => mockGetCurrentState(...args),
     get: (...args: unknown[]) => mockGetStateMachine(...args),
     transition: (...args: any[]) => mockTransition(...args),
+    resetForSurface: (...args: unknown[]) => mockResetForSurface(...args),
   },
 }));
 
@@ -97,6 +118,9 @@ vi.mock('./PendingQueueModule', () => ({
   pendingQueueManager: {
     list: (...args: unknown[]) => mockPendingList(...args),
     enqueue: (...args: unknown[]) => mockPendingEnqueue(...args),
+    enqueueForSurface: (...args: unknown[]) => mockPendingEnqueueForSurface(...args),
+    setStatus: (...args: unknown[]) => mockPendingSetStatus(...args),
+    remove: (...args: unknown[]) => mockPendingRemove(...args),
   },
 }));
 
@@ -106,6 +130,37 @@ vi.mock('@/infrastructure/i18n', () => ({
   },
 }));
 
+describe('MessageModule Session mutation admission', () => {
+  beforeEach(() => {
+    useSessionMutationStore.setState({ mutations: new Map(), retiredTurnIds: new Map() });
+  });
+  afterEach(() => {
+    useSessionMutationStore.setState({ mutations: new Map(), retiredTurnIds: new Map() });
+  });
+
+  it('rejects an ordinary submission while Session history is mutating', async () => {
+    const session = {
+      sessionId: 'session-mutating',
+      mode: 'agentic',
+      dialogTurns: [],
+      config: {},
+      titleStatus: 'generated',
+    };
+    const context: any = {
+      flowChatStore: {
+        getSurfaceGeneration: () => 0,
+        getState: () => ({ sessions: new Map([[session.sessionId, session]]) }),
+      },
+    };
+    tryBeginSessionMutation(session.sessionId, 'rollback', 'turn-7');
+
+    await expect(sendMessage(context, 'interleaving prompt', session.sessionId)).rejects.toThrow(
+      'history mutation',
+    );
+    expect(mockStartDialogTurn).not.toHaveBeenCalled();
+  });
+});
+
 describe('MessageModule session writer conflict', () => {
   function deferred<T>() {
     let resolve!: (value: T | PromiseLike<T>) => void;
@@ -130,6 +185,7 @@ describe('MessageModule session writer conflict', () => {
       session,
       context: {
         flowChatStore: {
+          getSurfaceGeneration: () => 0,
           getState: () => ({ sessions: new Map([[sessionId, session]]) }),
           addDialogTurn: vi.fn((_id: string, turn: any) => session.dialogTurns.push(turn)),
           deleteDialogTurn: vi.fn((_id: string, turnId: string) => {
@@ -179,6 +235,7 @@ describe('MessageModule session writer conflict', () => {
     };
     const context: any = {
       flowChatStore: {
+        getSurfaceGeneration: () => 0,
         getState: () => ({ sessions: new Map([['session-1', session]]) }),
         deleteDialogTurn: vi.fn(),
       },
@@ -376,12 +433,16 @@ describe('MessageModule session writer conflict', () => {
 describe('MessageModule cancellation', () => {
   beforeEach(() => {
     vi.clearAllMocks();
+    interruptedTurnRecoveryGate.resetForTests();
     resetRuntimeStatuses();
     mockGetCurrentState.mockReturnValue('processing');
     mockTransition.mockResolvedValue(true);
   });
 
   it('cancels persistent /btw sessions through the ordinary dialog-turn path', async () => {
+    mockGetCurrentState
+      .mockReturnValueOnce('processing')
+      .mockReturnValue('finishing');
     const session = {
       sessionId: 'btw-child',
       isTransient: false,
@@ -394,6 +455,7 @@ describe('MessageModule cancellation', () => {
     const activeTextItems = new Map([['btw-child', new Map([['round-1', 'item-1']])]]);
     const context: any = {
       flowChatStore: {
+        getSurfaceGeneration: () => 0,
         getState: () => ({
           activeSessionId: 'parent',
           sessions: new Map([['btw-child', session]]),
@@ -423,11 +485,229 @@ describe('MessageModule cancellation', () => {
     expect(contentBuffers.has('btw-child')).toBe(false);
     expect(activeTextItems.has('btw-child')).toBe(false);
   });
+
+  it('preserves the running UI when the interrupt transition rolls back to processing', async () => {
+    mockGetCurrentState.mockReturnValue('processing');
+    const session = {
+      sessionId: 'session-interrupt-rejected',
+      sessionKind: 'normal',
+      dialogTurns: [],
+      config: {},
+    };
+    const contentBuffers = new Map([[session.sessionId, new Map([['round-1', 'text']])]]);
+    const activeTextItems = new Map([[session.sessionId, new Map([['round-1', 'item-1']])]]);
+    const context: any = {
+      flowChatStore: {
+        getSurfaceGeneration: () => 0,
+        getState: () => ({ sessions: new Map([[session.sessionId, session]]) }),
+      },
+      userCancelledSessionIds: new Set<string>(),
+      eventBatcher: { getBufferSize: vi.fn(() => 0), clear: vi.fn() },
+      pendingTurnCompletions: new Map(),
+      runtimeStatusTimers: new Map(),
+      handledTerminalTurnEvents: new Set<string>(),
+      contentBuffers,
+      activeTextItems,
+    };
+
+    await expect(cancelSessionTask(context, session.sessionId)).resolves.toBe(false);
+
+    expect(context.userCancelledSessionIds.has(session.sessionId)).toBe(false);
+    expect(contentBuffers.has(session.sessionId)).toBe(true);
+    expect(activeTextItems.has(session.sessionId)).toBe(true);
+  });
+
+  it('queues a direct send while the cancellation outcome still owns the session', async () => {
+    mockGetCurrentState.mockReturnValue('idle');
+    mockPendingList.mockReturnValue([]);
+    mockPendingEnqueue.mockReturnValue({ id: 'queued-during-cancel' });
+    const session = {
+      sessionId: 'session-cancel-in-flight',
+      sessionKind: 'normal',
+      dialogTurns: [],
+      config: {},
+    };
+    const context: any = {
+      flowChatStore: {
+        getSurfaceGeneration: () => 0,
+        getState: () => ({ sessions: new Map([[session.sessionId, session]]) }),
+      },
+      userCancelledSessionIds: new Set([session.sessionId]),
+    };
+
+    await sendMessage(context, 'follow-up', session.sessionId);
+
+    expect(mockPendingEnqueue).toHaveBeenCalledWith(expect.objectContaining({
+      sessionId: session.sessionId,
+      content: 'follow-up',
+    }));
+    expect(mockStartDialogTurn).not.toHaveBeenCalled();
+  });
+
+  it('holds pending input while an interrupt outcome is still in flight', async () => {
+    mockGetCurrentState.mockReturnValue('idle');
+    mockPendingList.mockReturnValue([{
+      id: 'pending-1',
+      sessionId: 'session-1',
+      content: 'do not auto-send',
+      status: 'queued',
+      retryCount: 0,
+    }]);
+    const context: any = {
+      flowChatStore: {
+        getSurfaceGeneration: () => 0,
+        getState: () => ({
+          sessions: new Map([['session-1', {
+            sessionId: 'session-1',
+            dialogTurns: [],
+            config: {},
+          }]]),
+        }),
+      },
+      userCancelledSessionIds: new Set(['session-1']),
+    };
+
+    await drainPendingQueue(context, 'session-1');
+
+    expect(mockPendingSetStatus).not.toHaveBeenCalled();
+    expect(mockStartDialogTurn).not.toHaveBeenCalled();
+    expect(mockPendingRemove).not.toHaveBeenCalled();
+  });
+
+  it('rejects every direct submission while recovery admission is in flight', async () => {
+    const session: any = {
+      sessionId: 'session-interrupted',
+      dialogTurns: [],
+      config: {},
+    };
+    const context: any = {
+      flowChatStore: {
+        getSurfaceGeneration: () => 0,
+        getState: () => ({ sessions: new Map([[session.sessionId, session]]) }),
+      },
+    };
+    interruptedTurnRecoveryGate.tryBegin({
+      sessionId: session.sessionId,
+      turnId: 'interrupted-turn',
+      executionGeneration: 0,
+    });
+
+    await expect(sendMessage(context, 'must not race recovery', session.sessionId)).rejects.toThrow(
+      'recovery is in flight',
+    );
+    expect(mockPendingEnqueue).not.toHaveBeenCalled();
+    expect(mockStartDialogTurn).not.toHaveBeenCalled();
+  });
+
+  it('lets an explicit send-now abandon interrupted recovery', async () => {
+    mockGetCurrentState.mockReturnValue('idle');
+    mockEnsureBackendSession.mockResolvedValue(undefined);
+    mockStartDialogTurn.mockResolvedValue({
+      sessionId: 'session-interrupted',
+      turnId: 'new-turn',
+      status: 'started',
+    });
+    const pendingItem = {
+      id: 'pending-explicit',
+      sessionId: 'session-interrupted',
+      content: 'start new work',
+      status: 'queued',
+      retryCount: 0,
+    };
+    mockPendingList.mockReturnValue([pendingItem]);
+    const session: any = {
+      sessionId: 'session-interrupted',
+      sessionKind: 'normal',
+      mode: 'agentic',
+      titleStatus: 'generated',
+      dialogTurns: [{
+        id: 'interrupted-turn',
+        status: 'cancelled',
+        finishReason: 'interrupted',
+        recovery: { status: 'interrupted', executionGeneration: 0 },
+      }],
+      config: { modelName: 'auto' },
+      maxContextTokens: 32_000,
+    };
+    const context: any = {
+      flowChatStore: {
+        getSurfaceGeneration: () => 0,
+        getState: () => ({ sessions: new Map([[session.sessionId, session]]) }),
+        addDialogTurn: vi.fn((_sessionId: string, turn: any) => session.dialogTurns.push(turn)),
+        deleteDialogTurn: vi.fn((_sessionId: string, turnId: string) => {
+          session.dialogTurns = session.dialogTurns.filter((turn: any) => turn.id !== turnId);
+        }),
+        updateSessionLastSubmittedMode: vi.fn(),
+        updateSessionMode: vi.fn(),
+        updateSessionModelName: vi.fn(),
+        updateSessionMaxContextTokens: vi.fn(),
+      },
+      processingManager: {
+        registerStatus: vi.fn(),
+        clearSessionStatus: vi.fn(),
+      },
+      userCancelledSessionIds: new Set<string>(),
+      pendingHistoryLoads: new Map(),
+      contentBuffers: new Map(),
+      activeTextItems: new Map(),
+    };
+
+    await drainPendingQueue(context, session.sessionId);
+    expect(mockStartDialogTurn).not.toHaveBeenCalled();
+
+    await drainPendingQueue(context, session.sessionId, {
+      allowInterruptedRecoveryAbandon: true,
+    });
+
+    expect(mockStartDialogTurn).toHaveBeenCalledTimes(1);
+    expect(mockPendingRemove).toHaveBeenCalledWith(session.sessionId, pendingItem.id);
+  });
+
+  it('holds an explicit send-now while recovery admission is in flight', async () => {
+    mockGetCurrentState.mockReturnValue('idle');
+    mockPendingList.mockReturnValue([{
+      id: 'pending-race',
+      sessionId: 'session-interrupted',
+      content: 'must wait',
+      status: 'queued',
+      retryCount: 0,
+    }]);
+    const session: any = {
+      sessionId: 'session-interrupted',
+      dialogTurns: [{
+        id: 'interrupted-turn',
+        status: 'cancelled',
+        finishReason: 'interrupted',
+        recovery: { status: 'interrupted', executionGeneration: 0 },
+      }],
+      config: {},
+    };
+    const context: any = {
+      flowChatStore: {
+        getSurfaceGeneration: () => 0,
+        getState: () => ({ sessions: new Map([[session.sessionId, session]]) }),
+      },
+      userCancelledSessionIds: new Set<string>(),
+    };
+    interruptedTurnRecoveryGate.tryBegin({
+      sessionId: session.sessionId,
+      turnId: 'interrupted-turn',
+      executionGeneration: 0,
+    });
+
+    await drainPendingQueue(context, session.sessionId, {
+      allowInterruptedRecoveryAbandon: true,
+    });
+
+    expect(mockStartDialogTurn).not.toHaveBeenCalled();
+    expect(mockPendingSetStatus).not.toHaveBeenCalled();
+  });
 });
 
 describe('MessageModule detached dispatch', () => {
   beforeEach(() => {
     vi.clearAllMocks();
+    mockPendingList.mockReturnValue([]);
     mockGetCurrentState.mockReturnValue('idle');
     mockDispatchSubmit.mockResolvedValue({
       accepted: true,
@@ -477,6 +757,7 @@ describe('MessageModule detached dispatch', () => {
       session,
       context: {
         flowChatStore: {
+          getSurfaceGeneration: () => 0,
           getState: () => ({
             activeSessionId: session.sessionId,
             sessions: new Map([[session.sessionId, session]]),
@@ -658,6 +939,7 @@ describe('MessageModule model synchronization', () => {
     const updateSessionMaxContextTokens = vi.fn();
     const context: any = {
       flowChatStore: {
+        getSurfaceGeneration: () => 0,
         getState: () => ({ sessions: new Map([['session-auto', session]]) }),
         updateSessionModelName,
         updateSessionMaxContextTokens,
@@ -689,6 +971,7 @@ describe('MessageModule model synchronization', () => {
     const updateSessionMaxContextTokens = vi.fn();
     const context: any = {
       flowChatStore: {
+        getSurfaceGeneration: () => 0,
         getState: () => ({ sessions: new Map([['legacy-session', session]]) }),
         updateSessionModelName,
         updateSessionMaxContextTokens,
@@ -710,3 +993,138 @@ describe('MessageModule model synchronization', () => {
     });
   });
 });
+
+describe('MessageModule device surface switch', () => {
+  /**
+   * A device-surface switch clears every session projection. A submission
+   * caught in `startTurn`'s async window (state transition, worktree bind,
+   * model sync) used to resume against an empty store and throw
+   * "Session lost after adding dialog turn" — reported as a turn failure even
+   * though the turn had never reached a host, so the message was lost.
+   */
+  function switchingContext(sessionId: string, options?: { switchAfterTransition?: boolean }) {
+    const session = {
+      sessionId,
+      mode: 'agentic',
+      dialogTurns: [] as any[],
+      config: { modelName: 'auto', workspacePath: '/repo' },
+      titleStatus: 'generated',
+      maxContextTokens: 32000,
+    };
+    const sessions = new Map<string, any>([[sessionId, session]]);
+    let surfaceGeneration = 0;
+
+    const switchSurface = () => {
+      surfaceGeneration += 1;
+      sessions.clear();
+      activateSurface('peer-switch-target');
+    };
+
+    if (options?.switchAfterTransition) {
+      // The switch lands while the state machine transition is awaited, which
+      // is exactly where the reported failure happened.
+      mockTransition.mockImplementation(async () => {
+        switchSurface();
+        return true;
+      });
+    }
+
+    return {
+      session,
+      switchSurface,
+      context: {
+        flowChatStore: {
+          getSurfaceGeneration: () => surfaceGeneration,
+          getState: () => ({ sessions }),
+          addDialogTurn: vi.fn((_id: string, turn: any) => session.dialogTurns.push(turn)),
+          deleteDialogTurn: vi.fn(),
+          abandonOptimisticDialogTurn: vi.fn(),
+          updateSessionLastSubmittedMode: vi.fn(),
+          updateSessionMode: vi.fn(),
+          updateSessionModelName: vi.fn(),
+          updateSessionMaxContextTokens: vi.fn(),
+        },
+        processingManager: {
+          registerStatus: vi.fn(),
+          clearSessionStatus: vi.fn(),
+          clearSessionStatusForSurface: vi.fn(),
+        },
+        pendingHistoryLoads: new Map(),
+        contentBuffers: new Map(),
+        activeTextItems: new Map(),
+      } as any,
+    };
+  }
+
+  beforeEach(() => {
+    activateSurface(LOCAL_SURFACE_ID);
+    vi.resetAllMocks();
+    mockGetCurrentState.mockReturnValue('idle');
+    mockGetStateMachine.mockReturnValue(null);
+    mockTransition.mockResolvedValue(true);
+    mockUpdateSessionModel.mockResolvedValue(undefined);
+    mockStartDialogTurn.mockResolvedValue(undefined);
+    mockPendingList.mockReturnValue([]);
+    mockPendingEnqueue.mockReturnValue({ id: 'requeued' });
+    mockPendingEnqueueForSurface.mockReturnValue({ id: 'requeued' });
+    mockEnsureBackendSession.mockResolvedValue(undefined);
+  });
+
+  it('does not report a turn failure when the surface switched mid-submission', async () => {
+    const { context } = switchingContext('session-switch', { switchAfterTransition: true });
+
+    await expect(
+      sendMessage(context, 'keep working', 'session-switch'),
+    ).resolves.toBeUndefined();
+
+    expect(mockNotificationError).not.toHaveBeenCalled();
+  });
+
+  it('re-queues the message when the host never accepted the turn', async () => {
+    const { context } = switchingContext('session-switch', { switchAfterTransition: true });
+
+    await sendMessage(context, 'keep working', 'session-switch');
+
+    expect(mockStartDialogTurn).not.toHaveBeenCalled();
+    expect(mockPendingEnqueueForSurface).toHaveBeenCalledWith(
+      'local',
+      expect.objectContaining({ sessionId: 'session-switch', content: 'keep working' }),
+    );
+    expect(context.processingManager.registerStatus).not.toHaveBeenCalled();
+    expect(context.flowChatStore.abandonOptimisticDialogTurn).toHaveBeenCalledWith(
+      'local',
+      'session-switch',
+      expect.any(String),
+    );
+    expect(mockResetForSurface).toHaveBeenCalledWith('local', 'session-switch');
+    expect(context.processingManager.clearSessionStatusForSurface).toHaveBeenCalledWith(
+      'local',
+      'session-switch',
+    );
+  });
+
+  it('leaves an accepted turn alone when the surface switches after submission', async () => {
+    const { context, switchSurface } = switchingContext('session-accepted');
+    // The host takes the turn, and only then does the user switch device.
+    mockStartDialogTurn.mockImplementation(async () => {
+      switchSurface();
+    });
+
+    await sendMessage(context, 'already running', 'session-accepted');
+
+    expect(mockStartDialogTurn).toHaveBeenCalledTimes(1);
+    expect(mockPendingEnqueueForSurface).not.toHaveBeenCalled();
+    expect(mockNotificationError).not.toHaveBeenCalled();
+  });
+
+  it('still reports ordinary failures when the surface did not change', async () => {
+    const { context } = switchingContext('session-normal');
+    mockStartDialogTurn.mockRejectedValue(new Error('backend exploded'));
+
+    await expect(
+      sendMessage(context, 'boom', 'session-normal'),
+    ).rejects.toThrow('backend exploded');
+
+    expect(mockNotificationError).toHaveBeenCalled();
+  });
+});
diff --git a/src/web-ui/src/flow_chat/services/flow-chat-manager/MessageModule.ts b/src/web-ui/src/flow_chat/services/flow-chat-manager/MessageModule.ts
index 6cd42765ca..19c3c3ac18 100644
--- a/src/web-ui/src/flow_chat/services/flow-chat-manager/MessageModule.ts
+++ b/src/web-ui/src/flow_chat/services/flow-chat-manager/MessageModule.ts
@@ -10,6 +10,11 @@ import { notificationService } from '../../../shared/notification-system';
 import { stateMachineManager } from '../../state-machine';
 import { SessionExecutionEvent, SessionExecutionState } from '../../state-machine/types';
 import { createLogger } from '@/shared/utils/logger';
+import {
+  getActiveSurfaceScope,
+  isSurfaceChangedError,
+  type DeviceSurfaceId,
+} from '@/infrastructure/peer-device/deviceSurface';
 import type { FlowChatContext } from './types';
 import { isProjectedSessionEmpty } from '../../utils/flowChatTurnIdentity';
 import type { ImageContextData as ImageInputContextData } from '@/infrastructure/api/service-api/ImageContextTypes';
@@ -18,6 +23,9 @@ import { isSessionInUseError } from '@/infrastructure/api/errors/TauriCommandErr
 import { i18nService } from '@/infrastructure/i18n';
 import { driverForSession } from '../../session-drivers/registry';
 import type { SendMessageOptions, SubmissionDraft, TurnTracker } from '../../session-drivers/types';
+import { assertSessionSubmissionAllowed } from '../../store/sessionMutationStore';
+import { hasInterruptedTurnHoldingQueue } from '../../utils/interruptedTurnRecovery';
+import { interruptedTurnRecoveryGate } from '../interruptedTurnRecoveryGate';
 
 export { syncSessionModelSelection } from '../../utils/modelSync';
 export { markCurrentTurnItemsAsCancelled } from '../../utils/turnCancellation';
@@ -33,32 +41,154 @@ interface SessionConflictRetry {
 const sessionConflictRetries = new Map<string, SessionConflictRetry>();
 const latestSendBySession = new Map<string, symbol>();
 
-function clearSessionConflictRetry(sessionId: string): void {
-  const current = sessionConflictRetries.get(sessionId);
+function clearSessionConflictRetry(sendKey: string): void {
+  const current = sessionConflictRetries.get(sendKey);
   if (!current) return;
   current.active = false;
-  sessionConflictRetries.delete(sessionId);
+  sessionConflictRetries.delete(sendKey);
   notificationService.dismiss(current.notificationId);
 }
 
-function beginSessionSend(sessionId: string): symbol {
+function beginSessionSend(sendKey: string, sessionId: string): symbol {
   const attempt = Symbol(sessionId);
-  latestSendBySession.set(sessionId, attempt);
-  clearSessionConflictRetry(sessionId);
+  latestSendBySession.set(sendKey, attempt);
+  clearSessionConflictRetry(sendKey);
   return attempt;
 }
 
 function completeSessionSend(
-  sessionId: string,
+  sendKey: string,
   attempt: symbol,
   retrySuccess?: () => void,
 ): void {
-  if (latestSendBySession.get(sessionId) !== attempt) return;
-  latestSendBySession.delete(sessionId);
-  clearSessionConflictRetry(sessionId);
+  if (latestSendBySession.get(sendKey) !== attempt) return;
+  latestSendBySession.delete(sendKey);
+  clearSessionConflictRetry(sendKey);
   retrySuccess?.();
 }
 
+/**
+ * Submissions that have created a projection turn but have not yet handed the
+ * turn to a host.
+ *
+ * Switching the rendered device surface selects another projection. A
+ * submission caught mid-flight must not resume through that new projection —
+ * and because the throw may land before `start_dialog_turn`, the surface switch
+ * waits for submissions to drain first.
+ */
+let inFlightSubmissions = 0;
+const inFlightSubmissionWaiters = new Set<() => void>();
+
+function beginSubmission(): void {
+  inFlightSubmissions += 1;
+}
+
+function endSubmission(): void {
+  inFlightSubmissions = Math.max(0, inFlightSubmissions - 1);
+  if (inFlightSubmissions === 0 && inFlightSubmissionWaiters.size > 0) {
+    for (const notify of Array.from(inFlightSubmissionWaiters)) {
+      notify();
+    }
+    inFlightSubmissionWaiters.clear();
+  }
+}
+
+export function inFlightSubmissionCount(): number {
+  return inFlightSubmissions;
+}
+
+/**
+ * Salvage a submission that lost the race against a device-surface switch.
+ *
+ * When the host never accepted the turn the message exists nowhere, so it goes
+ * back onto the session's pending queue — queues are keyed by surface and
+ * session id, so returning to that device drains it. When the
+ * host did accept it, the turn is already running there and nothing is owed.
+ */
+function recoverSubmissionAfterSurfaceSwitch(
+  context: FlowChatContext,
+  surfaceId: DeviceSurfaceId,
+  sessionId: string,
+  turnTracker: TurnTracker,
+  draft: {
+    message: string;
+    displayMessage?: string;
+    agentType?: string;
+    options?: SendMessageOptions;
+  },
+): void {
+  if (turnTracker.hostAcceptedTurn) {
+    log.info('Device surface switched after the host accepted the turn; it keeps running there', {
+      sessionId,
+    });
+    return;
+  }
+  if (turnTracker.createdLocalTurnId) {
+    context.flowChatStore.abandonOptimisticDialogTurn(
+      surfaceId,
+      sessionId,
+      turnTracker.createdLocalTurnId,
+    );
+    stateMachineManager.resetForSurface(surfaceId, sessionId);
+    context.processingManager.clearSessionStatusForSurface(surfaceId, sessionId);
+  }
+  try {
+    pendingQueueManager.enqueueForSurface(surfaceId, {
+      sessionId,
+      content: draft.message,
+      displayMessage: draft.displayMessage,
+      agentType: draft.agentType,
+      imageContexts: draft.options?.imageContexts,
+      imageDisplayData: draft.options?.imageDisplayData,
+      userMessageMetadata: draft.options?.userMessageMetadata,
+    });
+    log.info('Device surface switched before submit reached the host; message re-queued', {
+      sessionId,
+    });
+  } catch (error) {
+    // A full queue is the only expected failure, and dropping the message
+    // silently would be worse than the original error toast.
+    log.error('Failed to re-queue a message after a device surface switch', {
+      sessionId,
+      error,
+    });
+    notificationService.error(
+      i18nService.t('flow-chat:session.surfaceSwitchDropped'),
+      { title: i18nService.t('flow-chat:session.surfaceSwitchDroppedTitle'), duration: 6000 },
+    );
+  }
+}
+
+/**
+ * Wait until no submission is mid-flight, or until `timeoutMs` elapses.
+ *
+ * Returns whether the wait drained. A timeout is not fatal: `sendMessage`
+ * detects the surface change and recovers the message onto the pending queue.
+ */
+export function waitForInFlightSubmissions(timeoutMs: number): Promise<boolean> {
+  if (inFlightSubmissions === 0) {
+    return Promise.resolve(true);
+  }
+  return new Promise<boolean>((resolve) => {
+    let settled = false;
+    // `endSubmission` clears the waiter set before notifying, so the drained
+    // path does not have to unregister itself; only a timeout leaves a stale
+    // waiter behind.
+    const notify = (): void => {
+      if (settled) return;
+      settled = true;
+      resolve(true);
+    };
+    inFlightSubmissionWaiters.add(notify);
+    setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      inFlightSubmissionWaiters.delete(notify);
+      resolve(false);
+    }, timeoutMs);
+  });
+}
+
 function acpClientIdFromMode(mode: string | undefined): string | null {
   const value = mode?.trim();
   if (!value?.startsWith('acp:')) return null;
@@ -87,18 +217,29 @@ export async function sendMessage(
   if (!session) {
     throw new Error(`Session does not exist: ${sessionId}`);
   }
-  const sendAttempt = beginSessionSend(sessionId);
+  const surfaceScopeAtSend = getActiveSurfaceScope();
+  const sendCoordinationKey = surfaceScopeAtSend.key(
+    'session-send',
+    surfaceScopeAtSend.epoch,
+    sessionId,
+  );
+  if (interruptedTurnRecoveryGate.isSessionInFlight(sessionId)) {
+    throw new Error('Interrupted turn recovery is in flight');
+  }
+  assertSessionSubmissionAllowed(sessionId, options?.sessionMutationLeaseId);
+  const sendAttempt = beginSessionSend(sendCoordinationKey, sessionId);
   const draft: SubmissionDraft = {
     message,
     displayMessage,
-    hasImages: (options?.imageContexts?.length ?? 0) > 0,
+    imageContexts: options?.imageContexts,
   };
 
   if (!options?.bypassPendingQueue) {
     const machineState = stateMachineManager.getCurrentState(sessionId);
     const sessionBusy =
       machineState === SessionExecutionState.PROCESSING ||
-      machineState === SessionExecutionState.FINISHING;
+      machineState === SessionExecutionState.FINISHING ||
+      context.userCancelledSessionIds?.has(sessionId) === true;
     const hasPendingQueue = pendingQueueManager.list(sessionId).length > 0;
 
     if (sessionBusy || hasPendingQueue) {
@@ -143,7 +284,7 @@ export async function sendMessage(
         throw error;
       }
       completeSessionSend(
-        sessionId,
+        sendCoordinationKey,
         sendAttempt,
         options?.fromSessionConflictRetry
           ? options.onSessionConflictRetrySuccess
@@ -161,7 +302,12 @@ export async function sendMessage(
     }));
   }
 
-  const turnTracker: TurnTracker = { createdLocalTurnId: null };
+  const turnTracker: TurnTracker = { createdLocalTurnId: null, hostAcceptedTurn: false };
+  // A device-surface switch swaps the projection this submission reads through.
+  // Anything read back after an await belongs to the surface captured here.
+  const surfaceGenerationAtSend = context.flowChatStore.getSurfaceGeneration();
+  const surfaceIdAtSend = surfaceScopeAtSend.surfaceId;
+  beginSubmission();
 
   try {
     const refreshedSession = context.flowChatStore.getState().sessions.get(sessionId) ?? session;
@@ -183,7 +329,11 @@ export async function sendMessage(
       context.flowChatStore.updateSessionMode(sessionId, currentAgentType);
     }
 
-    if (context.pendingHistoryLoads.has(sessionId)) {
+    if (
+      context.pendingHistoryLoads.has(
+        surfaceScopeAtSend.key('history-load', surfaceScopeAtSend.epoch, sessionId),
+      )
+    ) {
       throw new Error('Session history is still restoring, please retry once loading finishes');
     }
 
@@ -194,6 +344,7 @@ export async function sendMessage(
       const readiness = driver.ensureReady(context, sessionId);
       if (readiness) {
         await readiness;
+        surfaceScopeAtSend.assertCurrent('prepare session submission');
       }
     }
 
@@ -208,6 +359,7 @@ export async function sendMessage(
     const outcome = await driver.startTurn(
       context,
       {
+        surfaceScope: surfaceScopeAtSend,
         sessionId,
         message,
         displayMessage,
@@ -226,7 +378,7 @@ export async function sendMessage(
     }
 
     completeSessionSend(
-      sessionId,
+      sendCoordinationKey,
       sendAttempt,
       options?.fromSessionConflictRetry
         ? options.onSessionConflictRetrySuccess
@@ -234,6 +386,26 @@ export async function sendMessage(
     );
 
   } catch (error) {
+    // The window moved to another device mid-submission. That is not a turn
+    // failure: the session still exists on its own device, and the state
+    // machine and turn we would "clean up" no longer belong to the rendered
+    // surface. Recover the message instead of reporting an error.
+    if (
+      isSurfaceChangedError(error)
+      || context.flowChatStore.getSurfaceGeneration() !== surfaceGenerationAtSend
+    ) {
+      recoverSubmissionAfterSurfaceSwitch(context, surfaceIdAtSend, sessionId, turnTracker, {
+        message,
+        displayMessage,
+        agentType,
+        options,
+      });
+      if (latestSendBySession.get(sendCoordinationKey) === sendAttempt) {
+        latestSendBySession.delete(sendCoordinationKey);
+      }
+      return;
+    }
+
     log.error('Failed to send message', { sessionId: sessionId, error });
 
     // Map the "workspace folder deleted/moved" backend error to a localized
@@ -266,10 +438,10 @@ export async function sendMessage(
 
     if (!options?.preserveTurnOnStartError) {
       if (isSessionInUseError(error)) {
-        if (latestSendBySession.get(sessionId) !== sendAttempt) {
+        if (latestSendBySession.get(sendCoordinationKey) !== sendAttempt) {
           throw error;
         }
-        clearSessionConflictRetry(sessionId);
+        clearSessionConflictRetry(sendCoordinationKey);
         const retry: SessionConflictRetry = {
           notificationId: '',
           active: true,
@@ -286,7 +458,8 @@ export async function sendMessage(
               if (
                 !retry.active ||
                 retry.inFlight ||
-                sessionConflictRetries.get(sessionId) !== retry
+                !surfaceScopeAtSend.isCurrent() ||
+                sessionConflictRetries.get(sendCoordinationKey) !== retry
               ) {
                 return;
               }
@@ -305,21 +478,23 @@ export async function sendMessage(
             },
           }],
         });
-        sessionConflictRetries.set(sessionId, retry);
+        sessionConflictRetries.set(sendCoordinationKey, retry);
       } else {
-        if (latestSendBySession.get(sessionId) === sendAttempt) {
-          latestSendBySession.delete(sessionId);
+        if (latestSendBySession.get(sendCoordinationKey) === sendAttempt) {
+          latestSendBySession.delete(sendCoordinationKey);
           notificationService.error(errorMessage, {
             title: 'Thinking process error',
             duration: 5000
           });
         }
       }
-    } else if (latestSendBySession.get(sessionId) === sendAttempt) {
-      latestSendBySession.delete(sessionId);
+    } else if (latestSendBySession.get(sendCoordinationKey) === sendAttempt) {
+      latestSendBySession.delete(sendCoordinationKey);
     }
 
     throw error;
+  } finally {
+    endSubmission();
   }
 }
 
@@ -352,11 +527,30 @@ export async function cancelCurrentTask(context: FlowChatContext): Promise<boole
 export async function drainPendingQueue(
   context: FlowChatContext,
   sessionId: string,
+  options?: { allowInterruptedRecoveryAbandon?: boolean },
 ): Promise<void> {
   const machineState = stateMachineManager.getCurrentState(sessionId);
   if (machineState !== SessionExecutionState.IDLE) {
     return;
   }
+  if (interruptedTurnRecoveryGate.isSessionInFlight(sessionId)) {
+    log.debug('Pending queue held while interrupted recovery admission is in flight', {
+      sessionId,
+    });
+    return;
+  }
+  if (context.userCancelledSessionIds.has(sessionId)) {
+    log.debug('Pending queue held until cancellation outcome is authoritative', { sessionId });
+    return;
+  }
+  const session = context.flowChatStore.getState().sessions.get(sessionId);
+  if (
+    hasInterruptedTurnHoldingQueue(session)
+    && !options?.allowInterruptedRecoveryAbandon
+  ) {
+    log.debug('Pending queue held for interrupted turn recovery decision', { sessionId });
+    return;
+  }
   // Find the head item *that is still eligible for auto-drain*. Items with
   // `retryCount > 0` (e.g. restored from a failed turn) are deliberately
   // skipped here — the user must explicitly act on them to avoid re-entering
diff --git a/src/web-ui/src/flow_chat/services/flow-chat-manager/PeerSessionRefreshModule.test.ts b/src/web-ui/src/flow_chat/services/flow-chat-manager/PeerSessionRefreshModule.test.ts
index c0f85d2ad5..3342811f0f 100644
--- a/src/web-ui/src/flow_chat/services/flow-chat-manager/PeerSessionRefreshModule.test.ts
+++ b/src/web-ui/src/flow_chat/services/flow-chat-manager/PeerSessionRefreshModule.test.ts
@@ -118,3 +118,98 @@ describe('PeerSessionRefreshModule', () => {
     cleanup();
   });
 });
+
+describe('PeerSessionRefreshModule re-attach after a surface switch', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    peerModeMock.active = true;
+    vi.stubGlobal('document', {
+      visibilityState: 'visible',
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+    });
+    vi.stubGlobal('window', { addEventListener: vi.fn(), removeEventListener: vi.fn() });
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+  });
+
+  function contextWithSnapshot(
+    refreshPeerSessionSnapshot: ReturnType<typeof vi.fn>,
+  ) {
+    const state = {
+      activeSessionId: 'session-1',
+      sessions: new Map([
+        ['session-1', {
+          sessionId: 'session-1',
+          workspacePath: '/repo/BitFun',
+          historyState: 'ready',
+          isHistorical: false,
+          isTransient: false,
+          dialogTurns: [{
+            id: 'turn-live',
+            status: 'processing',
+            modelRounds: [{ id: 'round-0', items: [] }],
+          }],
+        }],
+      ]),
+    };
+    return {
+      flowChatStore: {
+        getState: () => state,
+        subscribeSelector: vi.fn(() => () => {}),
+        refreshPeerSessionSnapshot,
+      },
+      eventBatcher: { flushNow: vi.fn() },
+      contentBuffers: new Map(),
+      activeTextItems: new Map(),
+    } as any;
+  }
+
+  it('re-attaches an executing turn when the snapshot was refused or unchanged', async () => {
+    // The content-safety guard can refuse a snapshot that would gut the turn.
+    // The host is still executing, so the rebuilt surface must reattach anyway.
+    stateMachineMock.get.mockReturnValue({
+      getCurrentState: () => 'idle',
+      getContext: () => ({ lastUpdateTime: 0, version: 0 }),
+    });
+    const refresh = vi.fn(async () => ({
+      applied: false,
+      backendState: 'Processing { current_turn_id: "turn-live", phase: Streaming }',
+      latestTurnId: 'turn-live',
+      latestTurnStatus: 'processing',
+    }));
+
+    const cleanup = installPeerSessionRefresh(contextWithSnapshot(refresh));
+    await vi.advanceTimersByTimeAsync(1);
+    await vi.advanceTimersByTimeAsync(PEER_SESSION_REFRESH_INTERVAL_MS);
+
+    expect(refresh).toHaveBeenCalled();
+    expect(stateMachineMock.transition).toHaveBeenCalled();
+    cleanup();
+  });
+
+  it('does not churn the state machine while a turn is already streaming', async () => {
+    stateMachineMock.get.mockReturnValue({
+      getCurrentState: () => 'processing',
+      getContext: () => ({ lastUpdateTime: Date.now(), version: 0 }),
+    });
+    const refresh = vi.fn(async () => ({
+      applied: false,
+      backendState: 'Processing { current_turn_id: "turn-live", phase: Streaming }',
+      latestTurnId: 'turn-live',
+      latestTurnStatus: 'processing',
+    }));
+
+    const cleanup = installPeerSessionRefresh(contextWithSnapshot(refresh));
+    await vi.advanceTimersByTimeAsync(1);
+    await vi.advanceTimersByTimeAsync(PEER_SESSION_REFRESH_INTERVAL_MS);
+
+    expect(refresh).toHaveBeenCalled();
+    expect(stateMachineMock.reset).not.toHaveBeenCalled();
+    cleanup();
+  });
+});
diff --git a/src/web-ui/src/flow_chat/services/flow-chat-manager/PeerSessionRefreshModule.ts b/src/web-ui/src/flow_chat/services/flow-chat-manager/PeerSessionRefreshModule.ts
index 6b71e32197..5cb6c9fdc7 100644
--- a/src/web-ui/src/flow_chat/services/flow-chat-manager/PeerSessionRefreshModule.ts
+++ b/src/web-ui/src/flow_chat/services/flow-chat-manager/PeerSessionRefreshModule.ts
@@ -1,14 +1,18 @@
 /**
- * Peer Device active-session snapshot reconciliation.
+ * Active-session snapshot reconciliation for the rendered device surface.
  *
  * DeviceEvent fan-out is the real-time path, but the relay protocol has no
  * ACK/replay recovery. A controller that attaches mid-turn can therefore miss
- * lifecycle events required by the local FlowChat state machine. This module
- * periodically reconciles a small host snapshot and also supports immediate
- * refresh requests when an event gap is detected.
+ * lifecycle events required by the local FlowChat state machine. The same gap
+ * exists on the **local** surface: a turn that keeps running on this machine
+ * while the UI renders another device produces events that surface routing
+ * drops, so returning to it needs the same repair. This module periodically
+ * reconciles a small host snapshot and also supports immediate refresh
+ * requests when an event gap is detected.
  */
 
-import { isPeerDeviceModeActive } from '@/infrastructure/peer-device/peerModeFlag';
+import { isSurfaceChangedError } from '@/infrastructure/peer-device/deviceSurface';
+import { isSurfaceReconcileEnabled } from '@/infrastructure/peer-device/deviceSurfaceReconcile';
 import { createLogger } from '@/shared/utils/logger';
 import {
   isBackendSessionActivelyProcessing,
@@ -30,7 +34,7 @@ type RefreshRequester = (sessionId?: string) => void;
 let installedRefreshRequester: RefreshRequester | null = null;
 
 export function requestPeerSessionRefresh(sessionId?: string): void {
-  if (!isPeerDeviceModeActive()) {
+  if (!isSurfaceReconcileEnabled()) {
     return;
   }
   installedRefreshRequester?.(sessionId);
@@ -122,7 +126,7 @@ export function installPeerSessionRefresh(context: FlowChatContext): () => void
   let immediateTimer: ReturnType<typeof setTimeout> | null = null;
 
   async function runRefresh(requestedSessionId?: string): Promise<void> {
-    if (disposed || inFlight || !isPeerDeviceModeActive()) {
+    if (disposed || inFlight || !isSurfaceReconcileEnabled()) {
       if (inFlight) {
         queued = true;
       }
@@ -171,7 +175,7 @@ export function installPeerSessionRefresh(context: FlowChatContext): () => void
           replaceRunningSnapshot,
           requireActiveSession: true,
           shouldApply: () => {
-            if (!isPeerDeviceModeActive()) {
+            if (!isSurfaceReconcileEnabled()) {
               return false;
             }
             const currentMachine = stateMachineManager.get(sessionId);
@@ -180,6 +184,29 @@ export function installPeerSessionRefresh(context: FlowChatContext): () => void
         },
       );
       if (!result.applied) {
+        // A snapshot that changed nothing — or that was refused because it
+        // would have dropped projected content — still reports whether the
+        // host is executing. After a device-surface switch the rebuilt
+        // projection has no state machine, so an executing turn would render
+        // as static history and later chunks would be dropped. Re-attach on
+        // that narrow case only: while a turn really is streaming the machine
+        // is already processing, so this cannot churn it every tick.
+        const machine = stateMachineManager.get(sessionId);
+        const machineIsIdle =
+          (machine?.getCurrentState() ?? SessionExecutionState.IDLE)
+            === SessionExecutionState.IDLE;
+        if (machineIsIdle && isBackendSessionActivelyProcessing(result.backendState)) {
+          await alignStateMachineWithSnapshot(
+            context,
+            sessionId,
+            result.backendState,
+            result.latestTurnId,
+          );
+          log.debug('Re-attached an executing session after a surface switch', {
+            sessionId,
+            backendState: result.backendState,
+          });
+        }
         return;
       }
       await alignStateMachineWithSnapshot(
@@ -194,6 +221,13 @@ export function installPeerSessionRefresh(context: FlowChatContext): () => void
         latestTurnId: result.latestTurnId,
       });
     } catch (error) {
+      if (isSurfaceChangedError(error)) {
+        // The snapshot belongs to a device this window stopped rendering. Its
+        // own container keeps the projection; the surface now on screen
+        // reconciles itself on the next tick.
+        log.debug('Discarded a snapshot for a device surface we left', { sessionId });
+        return;
+      }
       // Realtime DeviceEvents remain usable when a background refresh fails.
       // The next interval or gap-triggered request retries without forcing an
       // auto-exit from Peer Mode.
diff --git a/src/web-ui/src/flow_chat/services/flow-chat-manager/PendingQueueModule.test.ts b/src/web-ui/src/flow_chat/services/flow-chat-manager/PendingQueueModule.test.ts
index a571e1e79c..a508841f69 100644
--- a/src/web-ui/src/flow_chat/services/flow-chat-manager/PendingQueueModule.test.ts
+++ b/src/web-ui/src/flow_chat/services/flow-chat-manager/PendingQueueModule.test.ts
@@ -1,10 +1,11 @@
 // @vitest-environment jsdom
 
-import { afterEach, describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { pendingQueueManager } from './PendingQueueModule';
 import {
-  pendingQueueManager,
-  queuedMessageHasUnsupportedSteeringPayload,
-} from './PendingQueueModule';
+  LOCAL_SURFACE_ID,
+  activateSurface,
+} from '@/infrastructure/peer-device/deviceSurface';
 
 const sessions: string[] = [];
 
@@ -14,7 +15,12 @@ function testSession(): string {
   return sessionId;
 }
 
+beforeEach(() => {
+  activateSurface(LOCAL_SURFACE_ID);
+});
+
 afterEach(() => {
+  activateSurface(LOCAL_SURFACE_ID);
   for (const sessionId of sessions.splice(0)) {
     pendingQueueManager.clear(sessionId);
   }
@@ -57,40 +63,24 @@ describe('PendingQueueModule', () => {
     expect(items[0].retryCount).toBe(0);
   });
 
-  it('rejects only payloads that the text-only steering contract would flatten', () => {
-    const plain = {
-      id: 'plain',
-      sessionId: 'session-1',
-      content: 'plain text',
-      timestamp: 1,
-      status: 'queued' as const,
-      retryCount: 0,
-    };
+  it('keeps equal session ids isolated across device surfaces', () => {
+    const sessionId = testSession();
+    pendingQueueManager.enqueue({ sessionId, content: 'local draft' });
+
+    activateSurface('peer-b');
+    expect(pendingQueueManager.list(sessionId)).toEqual([]);
+    pendingQueueManager.enqueue({ sessionId, content: 'peer draft' });
+
+    activateSurface(LOCAL_SURFACE_ID);
+    expect(pendingQueueManager.list(sessionId).map(item => item.content)).toEqual([
+      'local draft',
+    ]);
+    activateSurface('peer-b');
+    expect(pendingQueueManager.list(sessionId).map(item => item.content)).toEqual([
+      'peer draft',
+    ]);
 
-    expect(queuedMessageHasUnsupportedSteeringPayload(plain)).toBe(false);
-    expect(
-      queuedMessageHasUnsupportedSteeringPayload({
-        ...plain,
-        imageContexts: [{ id: 'image-1' }],
-      }),
-    ).toBe(true);
-    expect(
-      queuedMessageHasUnsupportedSteeringPayload({
-        ...plain,
-        userMessageMetadata: { deepReviewRunManifest: { requestId: 'review-1' } },
-      }),
-    ).toBe(true);
-    expect(
-      queuedMessageHasUnsupportedSteeringPayload({
-        ...plain,
-        userMessageMetadata: { sessionReferences: [{ sessionId: 'source' }] },
-      }),
-    ).toBe(true);
-    expect(
-      queuedMessageHasUnsupportedSteeringPayload({
-        ...plain,
-        userMessageMetadata: { composerPresentation: { parts: [] } },
-      }),
-    ).toBe(true);
+    pendingQueueManager.clearSurface('peer-b');
+    activateSurface(LOCAL_SURFACE_ID);
   });
 });
diff --git a/src/web-ui/src/flow_chat/services/flow-chat-manager/PendingQueueModule.ts b/src/web-ui/src/flow_chat/services/flow-chat-manager/PendingQueueModule.ts
index 9cf9ea6428..b488b75f49 100644
--- a/src/web-ui/src/flow_chat/services/flow-chat-manager/PendingQueueModule.ts
+++ b/src/web-ui/src/flow_chat/services/flow-chat-manager/PendingQueueModule.ts
@@ -8,15 +8,26 @@
  * the "send now" action which triggers `agentAPI.steerDialogTurn`, injecting
  * the message mid-turn.
  *
- * State is persisted per session so the queue survives a page refresh.
+ * State is persisted per device surface and session so the queue survives a
+ * page refresh without letting equal session ids on two devices collide.
  */
 
 import { createLogger } from '@/shared/utils/logger';
 import type { QueuedMessage } from '../../types/flow-chat';
+import {
+  getActiveSurfaceId,
+  onSurfaceActivated,
+  surfaceScopedKey,
+  type DeviceSurfaceId,
+} from '@/infrastructure/peer-device/deviceSurface';
 
 const log = createLogger('PendingQueueModule');
 
 const STORAGE_PREFIX = 'flowChat.pendingQueue.';
+// Keep peer records outside the legacy prefix. Older builds interpret every
+// key under STORAGE_PREFIX as a local session id, so nesting peer data there
+// would make a downgrade load encoded peer queues as bogus local sessions.
+const PEER_STORAGE_PREFIX = 'flowChat.peerPendingQueue.v1.';
 const MAX_QUEUE_DEPTH = 20;
 
 export interface EnqueueInput {
@@ -43,23 +54,12 @@ export interface EnqueueInput {
 
 export type PendingQueueListener = (sessionId: string, items: QueuedMessage[]) => void;
 
-/**
- * The core steering contract is text-only. Keep payloads that need structured
- * attachment/reference metadata queued for the regular turn submission path.
- */
-export function queuedMessageHasUnsupportedSteeringPayload(item: QueuedMessage): boolean {
-  if ((item.imageContexts?.length ?? 0) > 0 || (item.imageDisplayData?.length ?? 0) > 0) {
-    return true;
-  }
-  const metadata = item.userMessageMetadata;
-  return metadata != null && Object.keys(metadata).length > 0;
-}
-
 class PendingQueueManager {
   private static _instance: PendingQueueManager | null = null;
   private queues = new Map<string, QueuedMessage[]>();
   private listeners = new Set<PendingQueueListener>();
   private hydrated = false;
+  private lastSurfaceId = getActiveSurfaceId();
 
   static getInstance(): PendingQueueManager {
     if (!PendingQueueManager._instance) {
@@ -70,6 +70,47 @@ class PendingQueueManager {
 
   private constructor() {
     this.hydrateFromStorage();
+    onSurfaceActivated((scope) => {
+      const previousSurfaceId = this.lastSurfaceId;
+      this.lastSurfaceId = scope.surfaceId;
+      const affectedSessionIds = new Set([
+        ...this.sessionIdsForSurface(previousSurfaceId),
+        ...this.sessionIdsForSurface(scope.surfaceId),
+      ]);
+      // A component may keep the same session id across two device surfaces.
+      // Notify the union so it replaces A's queue with B's queue (or empty).
+      for (const sessionId of affectedSessionIds) {
+        this.notify(sessionId);
+      }
+    });
+  }
+
+  private queueKey(sessionId: string, surfaceId = getActiveSurfaceId()): string {
+    return surfaceScopedKey(surfaceId, sessionId);
+  }
+
+  private storageKey(sessionId: string, surfaceId: DeviceSurfaceId): string {
+    if (surfaceId === 'local') {
+      // Keep the legacy local key so an older BitFun install can still read it.
+      return STORAGE_PREFIX + sessionId;
+    }
+    return PEER_STORAGE_PREFIX + encodeURIComponent(JSON.stringify([surfaceId, sessionId]));
+  }
+
+  private sessionIdsForSurface(surfaceId: DeviceSurfaceId): string[] {
+    const sessionIds: string[] = [];
+    for (const key of this.queues.keys()) {
+      try {
+        const [ownedSurfaceId, sessionId] = JSON.parse(key) as [string, string];
+        if (ownedSurfaceId === surfaceId) {
+          sessionIds.push(sessionId);
+        }
+      } catch {
+        // Internal keys are always generated by surfaceScopedKey. Ignore a
+        // malformed entry rather than making a surface switch fail.
+      }
+    }
+    return sessionIds;
   }
 
   /** Lazily load all per-session queues from localStorage on first construction. */
@@ -80,14 +121,31 @@ class PendingQueueManager {
     try {
       for (let i = 0; i < window.localStorage.length; i++) {
         const key = window.localStorage.key(i);
-        if (!key || !key.startsWith(STORAGE_PREFIX)) continue;
-        const sessionId = key.slice(STORAGE_PREFIX.length);
+        if (
+          !key
+          || (!key.startsWith(STORAGE_PREFIX) && !key.startsWith(PEER_STORAGE_PREFIX))
+        ) {
+          continue;
+        }
+        let surfaceId: DeviceSurfaceId = 'local';
+        let sessionId = key.slice(STORAGE_PREFIX.length);
+        if (key.startsWith(PEER_STORAGE_PREFIX)) {
+          const encoded = key.slice(PEER_STORAGE_PREFIX.length);
+          try {
+            [surfaceId, sessionId] = JSON.parse(decodeURIComponent(encoded)) as [string, string];
+            if (!surfaceId || !sessionId) {
+              continue;
+            }
+          } catch {
+            continue;
+          }
+        }
         const raw = window.localStorage.getItem(key);
         if (!raw) continue;
         try {
           const parsed = JSON.parse(raw) as QueuedMessage[];
           if (Array.isArray(parsed) && parsed.length > 0) {
-            this.queues.set(sessionId, parsed);
+            this.queues.set(this.queueKey(sessionId, surfaceId), parsed);
           }
         } catch (err) {
           log.warn('Failed to parse persisted queue, dropping', { sessionId, err });
@@ -99,10 +157,10 @@ class PendingQueueManager {
     }
   }
 
-  private persist(sessionId: string): void {
+  private persist(sessionId: string, surfaceId = getActiveSurfaceId()): void {
     if (typeof window === 'undefined' || !window.localStorage) return;
-    const items = this.queues.get(sessionId);
-    const key = STORAGE_PREFIX + sessionId;
+    const items = this.queues.get(this.queueKey(sessionId, surfaceId));
+    const key = this.storageKey(sessionId, surfaceId);
     try {
       if (!items || items.length === 0) {
         window.localStorage.removeItem(key);
@@ -115,7 +173,11 @@ class PendingQueueManager {
   }
 
   list(sessionId: string): QueuedMessage[] {
-    return this.queues.get(sessionId) ?? [];
+    return this.listForSurface(getActiveSurfaceId(), sessionId);
+  }
+
+  listForSurface(surfaceId: DeviceSurfaceId, sessionId: string): QueuedMessage[] {
+    return this.queues.get(this.queueKey(sessionId, surfaceId)) ?? [];
   }
 
   isFull(sessionId: string): boolean {
@@ -123,7 +185,12 @@ class PendingQueueManager {
   }
 
   enqueue(input: EnqueueInput): QueuedMessage {
-    const items = this.queues.get(input.sessionId) ?? [];
+    return this.enqueueForSurface(getActiveSurfaceId(), input);
+  }
+
+  enqueueForSurface(surfaceId: DeviceSurfaceId, input: EnqueueInput): QueuedMessage {
+    const key = this.queueKey(input.sessionId, surfaceId);
+    const items = this.queues.get(key) ?? [];
     if (items.length >= MAX_QUEUE_DEPTH) {
       throw new Error(`Pending queue is full (max ${MAX_QUEUE_DEPTH})`);
     }
@@ -141,9 +208,9 @@ class PendingQueueManager {
       userMessageMetadata: input.userMessageMetadata,
     };
     items.push(item);
-    this.queues.set(input.sessionId, items);
-    this.persist(input.sessionId);
-    this.notify(input.sessionId);
+    this.queues.set(key, items);
+    this.persist(input.sessionId, surfaceId);
+    this.notifySurface(surfaceId, input.sessionId);
     return item;
   }
 
@@ -152,7 +219,7 @@ class PendingQueueManager {
     id: string,
     patch: Partial<Pick<QueuedMessage, 'content' | 'displayMessage'>>,
   ): boolean {
-    const items = this.queues.get(sessionId);
+    const items = this.queues.get(this.queueKey(sessionId));
     if (!items) return false;
     const idx = items.findIndex(item => item.id === id);
     if (idx === -1) return false;
@@ -163,14 +230,16 @@ class PendingQueueManager {
   }
 
   remove(sessionId: string, id: string): boolean {
-    const items = this.queues.get(sessionId);
+    const surfaceId = getActiveSurfaceId();
+    const key = this.queueKey(sessionId, surfaceId);
+    const items = this.queues.get(key);
     if (!items) return false;
     const next = items.filter(item => item.id !== id);
     if (next.length === items.length) return false;
     if (next.length === 0) {
-      this.queues.delete(sessionId);
+      this.queues.delete(key);
     } else {
-      this.queues.set(sessionId, next);
+      this.queues.set(key, next);
     }
     this.persist(sessionId);
     this.notify(sessionId);
@@ -179,7 +248,7 @@ class PendingQueueManager {
 
   /** Confirm a queued item for immediate idle-session drain without rebuilding its payload. */
   promoteForExplicitDrain(sessionId: string, id: string): boolean {
-    const items = this.queues.get(sessionId);
+    const items = this.queues.get(this.queueKey(sessionId));
     if (!items) return false;
     const index = items.findIndex(item => item.id === id);
     if (index === -1) return false;
@@ -196,7 +265,7 @@ class PendingQueueManager {
   }
 
   setStatus(sessionId: string, id: string, status: QueuedMessage['status']): void {
-    const items = this.queues.get(sessionId);
+    const items = this.queues.get(this.queueKey(sessionId));
     if (!items) return;
     const idx = items.findIndex(item => item.id === id);
     if (idx === -1) return;
@@ -207,13 +276,15 @@ class PendingQueueManager {
 
   /** Pop and return the head item (FIFO). */
   consumeNext(sessionId: string): QueuedMessage | undefined {
-    const items = this.queues.get(sessionId);
+    const surfaceId = getActiveSurfaceId();
+    const key = this.queueKey(sessionId, surfaceId);
+    const items = this.queues.get(key);
     if (!items || items.length === 0) return undefined;
     const [head, ...rest] = items;
     if (rest.length === 0) {
-      this.queues.delete(sessionId);
+      this.queues.delete(key);
     } else {
-      this.queues.set(sessionId, rest);
+      this.queues.set(key, rest);
     }
     this.persist(sessionId);
     this.notify(sessionId);
@@ -221,12 +292,24 @@ class PendingQueueManager {
   }
 
   clear(sessionId: string): void {
-    if (!this.queues.has(sessionId)) return;
-    this.queues.delete(sessionId);
+    const surfaceId = getActiveSurfaceId();
+    const key = this.queueKey(sessionId, surfaceId);
+    if (!this.queues.has(key)) return;
+    this.queues.delete(key);
     this.persist(sessionId);
     this.notify(sessionId);
   }
 
+  /** Permanently discard every queued message owned by one detached peer. */
+  clearSurface(surfaceId: DeviceSurfaceId): void {
+    const sessionIds = this.sessionIdsForSurface(surfaceId);
+    for (const sessionId of sessionIds) {
+      this.queues.delete(this.queueKey(sessionId, surfaceId));
+      this.persist(sessionId, surfaceId);
+      this.notifySurface(surfaceId, sessionId);
+    }
+  }
+
   subscribe(listener: PendingQueueListener): () => void {
     this.listeners.add(listener);
     return () => {
@@ -244,6 +327,12 @@ class PendingQueueManager {
       }
     });
   }
+
+  private notifySurface(surfaceId: DeviceSurfaceId, sessionId: string): void {
+    if (surfaceId === getActiveSurfaceId()) {
+      this.notify(sessionId);
+    }
+  }
 }
 
 export const pendingQueueManager = PendingQueueManager.getInstance();
diff --git a/src/web-ui/src/flow_chat/services/flow-chat-manager/PersistenceModule.test.ts b/src/web-ui/src/flow_chat/services/flow-chat-manager/PersistenceModule.test.ts
index 4da3c07dc1..a103610810 100644
--- a/src/web-ui/src/flow_chat/services/flow-chat-manager/PersistenceModule.test.ts
+++ b/src/web-ui/src/flow_chat/services/flow-chat-manager/PersistenceModule.test.ts
@@ -343,6 +343,21 @@ describe('PersistenceModule', () => {
     expect(mockSaveSessionTurn).toHaveBeenCalledTimes(1);
   });
 
+  it('does not overwrite Runtime-owned interrupted or recovering turns', async () => {
+    const turn = createDialogTurn('processing');
+    turn.recovery = {
+      status: 'recovering',
+      executionGeneration: 1,
+      resumeCount: 1,
+    };
+    const context = createContext(turn);
+
+    await saveDialogTurnToDisk(context, SESSION_ID, TURN_ID);
+    await flushMicrotasks();
+
+    expect(mockSaveSessionTurn).not.toHaveBeenCalled();
+  });
+
   it('defers partial-history saves until a storage identity is available', async () => {
     const turn = createDialogTurn('completed');
     delete turn.storageTurnIndex;
diff --git a/src/web-ui/src/flow_chat/services/flow-chat-manager/PersistenceModule.ts b/src/web-ui/src/flow_chat/services/flow-chat-manager/PersistenceModule.ts
index fc6bffd29e..2b466fa08e 100644
--- a/src/web-ui/src/flow_chat/services/flow-chat-manager/PersistenceModule.ts
+++ b/src/web-ui/src/flow_chat/services/flow-chat-manager/PersistenceModule.ts
@@ -309,6 +309,18 @@ async function performSaveDialogTurnToDisk(
       log.debug('Dialog turn not found, skipping save', { sessionId, turnId });
       return;
     }
+    if (dialogTurn.recovery) {
+      // The Runtime owns the durable snapshot and generation CAS for an
+      // interrupted/recovered turn. A frontend whole-turn save can otherwise
+      // overwrite newly appended rounds or restore stale recovery metadata.
+      log.debug('Runtime owns persistence for recoverable dialog turn', {
+        sessionId,
+        turnId,
+        recoveryStatus: dialogTurn.recovery.status,
+        executionGeneration: dialogTurn.recovery.executionGeneration,
+      });
+      return;
+    }
 
     const turnIndex = resolveStorageTurnIndex(session, dialogTurn);
     if (turnIndex === undefined) {
@@ -522,6 +534,7 @@ export function convertDialogTurnToBackendFormat(dialogTurn: DialogTurn, turnInd
         }
       : undefined,
     finishReason: dialogTurn.finishReason,
+    recovery: dialogTurn.recovery,
     hasFinalResponse: dialogTurn.hasFinalResponse,
     error: dialogTurn.error,
     errorDetail: dialogTurn.errorDetail,
diff --git a/src/web-ui/src/flow_chat/services/flow-chat-manager/SessionModule.test.ts b/src/web-ui/src/flow_chat/services/flow-chat-manager/SessionModule.test.ts
index deeea61101..38442ed547 100644
--- a/src/web-ui/src/flow_chat/services/flow-chat-manager/SessionModule.test.ts
+++ b/src/web-ui/src/flow_chat/services/flow-chat-manager/SessionModule.test.ts
@@ -5,6 +5,7 @@ import {
   deleteChatSession,
   ensureBackendSession,
   hydrateSessionHistoryForDetail,
+  pendingHistoryLoadKey,
   preloadHistoricalSessionForOpen,
   reloadSessionTitle,
   retryCreateBackendSession,
@@ -12,6 +13,10 @@ import {
   SESSION_ACTIVITY_TOUCH_DELAY_MS,
   switchChatSession,
 } from './SessionModule';
+import {
+  activateSurface,
+  LOCAL_SURFACE_ID,
+} from '@/infrastructure/peer-device/deviceSurface';
 import {
   clearRecentHistorySessionOpenIntent,
   dispatchHistorySessionOpenIntent,
@@ -342,6 +347,53 @@ describe('createChatSession', () => {
     expect(agentApiMocks.createSession).toHaveBeenCalledTimes(1);
   });
 
+  it('does not reuse or project a session creation from a superseded device activation', async () => {
+    const firstResponse = createDeferred<{ sessionId: string }>();
+    const secondResponse = createDeferred<{ sessionId: string }>();
+    agentApiMocks.createSession
+      .mockReturnValueOnce(firstResponse.promise)
+      .mockReturnValueOnce(secondResponse.promise);
+    const first = createContext(createSession({ workspacePath: '/shared/repo' }));
+    const second = createContext(createSession({ workspacePath: '/shared/repo' }));
+    let firstCreate: Promise<string> | undefined;
+    let secondCreate: Promise<string> | undefined;
+
+    try {
+      activateSurface('peer-a');
+      firstCreate = createChatSession(
+        first.context,
+        { workspacePath: '/shared/repo' },
+        'agentic',
+      );
+      await vi.waitFor(() => {
+        expect(agentApiMocks.createSession).toHaveBeenCalledTimes(1);
+      });
+
+      activateSurface('peer-b');
+      secondCreate = createChatSession(
+        second.context,
+        { workspacePath: '/shared/repo' },
+        'agentic',
+      );
+      await vi.waitFor(() => {
+        expect(agentApiMocks.createSession).toHaveBeenCalledTimes(2);
+      });
+
+      secondResponse.resolve({ sessionId: 'peer-b-created' });
+      await expect(secondCreate).resolves.toBe('peer-b-created');
+      expect(second.flowChatStore.createSession).toHaveBeenCalledTimes(1);
+
+      firstResponse.resolve({ sessionId: 'peer-a-created' });
+      await expect(firstCreate).rejects.toMatchObject({ isSurfaceChangedError: true });
+      expect(first.flowChatStore.createSession).not.toHaveBeenCalled();
+    } finally {
+      firstResponse.resolve({ sessionId: 'peer-a-created' });
+      secondResponse.resolve({ sessionId: 'peer-b-created' });
+      activateSurface(LOCAL_SURFACE_ID);
+      await Promise.allSettled([firstCreate, secondCreate].filter(Boolean) as Promise<string>[]);
+    }
+  });
+
   it('projects the runtime-resolved model for a newly created session', async () => {
     configManagerMocks.getConfigs.mockImplementation(async (paths: string[]) => {
       if (paths.length === 1 && paths[0] === 'ai.agent_model_defaults') {
@@ -571,7 +623,7 @@ describe('SessionModule historical session coordination', () => {
   it('keeps metadata-only historical sessions out of the active render path until hydrated', async () => {
     const load = createDeferred<void>();
     const { context, flowChatStore } = createContext(createSession());
-    context.pendingHistoryLoads.set('history-other', Promise.resolve());
+    context.pendingHistoryLoads.set(pendingHistoryLoadKey('history-other'), Promise.resolve());
     flowChatStore.loadSessionHistory.mockReturnValueOnce(load.promise);
     persistenceMocks.touchSessionActivity.mockResolvedValueOnce(undefined);
 
@@ -696,6 +748,27 @@ describe('SessionModule historical session coordination', () => {
     expect(persistenceMocks.touchSessionActivity).not.toHaveBeenCalled();
   });
 
+  it('does not touch activity on the device activated after the delay was scheduled', async () => {
+    const session = createSession({
+      historyState: 'ready',
+      dialogTurns: [{ id: 'turn-1', userMessage: { content: 'one' } } as any],
+    });
+    const { context } = createContext(session);
+    persistenceMocks.touchSessionActivity.mockResolvedValue(undefined);
+
+    try {
+      activateSurface('peer-a');
+      await switchChatSession(context, 'history-1');
+
+      activateSurface('peer-b');
+      await vi.advanceTimersByTimeAsync(SESSION_ACTIVITY_TOUCH_DELAY_MS);
+
+      expect(persistenceMocks.touchSessionActivity).not.toHaveBeenCalled();
+    } finally {
+      activateSurface(LOCAL_SURFACE_ID);
+    }
+  });
+
   it('does not block remote metadata-only historical sessions on local pre-hydration before switching', async () => {
     const load = createDeferred<void>();
     const { context, flowChatStore } = createContext(createSession({
@@ -717,7 +790,7 @@ describe('SessionModule historical session coordination', () => {
   it('preloads a local metadata-only historical session during a competing history load without switching', async () => {
     const load = createDeferred<void>();
     const { context, flowChatStore } = createContext(createSession());
-    context.pendingHistoryLoads.set('history-other', Promise.resolve());
+    context.pendingHistoryLoads.set(pendingHistoryLoadKey('history-other'), Promise.resolve());
     flowChatStore.loadSessionHistory.mockReturnValueOnce(load.promise);
 
     preloadHistoricalSessionForOpen(context, 'history-1');
@@ -757,6 +830,46 @@ describe('SessionModule historical session coordination', () => {
     await Promise.all([first, second]);
   });
 
+  it('does not reuse a same-id history load from another device activation', async () => {
+    const firstLoad = createDeferred<void>();
+    const secondLoad = createDeferred<void>();
+    const first = createContext(createSession());
+    const second = createContext(createSession());
+    const sharedPendingLoads = new Map<string, Promise<void>>();
+    const sharedCapabilities = new Map();
+    first.context.pendingHistoryLoads = sharedPendingLoads;
+    second.context.pendingHistoryLoads = sharedPendingLoads;
+    first.context.pendingHistoryLoadCapabilities = sharedCapabilities;
+    second.context.pendingHistoryLoadCapabilities = sharedCapabilities;
+    first.flowChatStore.loadSessionHistory.mockReturnValueOnce(firstLoad.promise);
+    second.flowChatStore.loadSessionHistory.mockReturnValueOnce(secondLoad.promise);
+    let firstHydrate: Promise<void> | undefined;
+    let secondHydrate: Promise<void> | undefined;
+
+    try {
+      activateSurface('peer-a');
+      firstHydrate = hydrateSessionHistoryForDetail(first.context, 'history-1');
+      expect(first.flowChatStore.loadSessionHistory).toHaveBeenCalledTimes(1);
+
+      activateSurface('peer-b');
+      secondHydrate = hydrateSessionHistoryForDetail(second.context, 'history-1');
+      expect(second.flowChatStore.loadSessionHistory).toHaveBeenCalledTimes(1);
+      expect(sharedPendingLoads.size).toBe(2);
+
+      secondLoad.resolve();
+      await expect(secondHydrate).resolves.toBeUndefined();
+
+      firstLoad.resolve();
+      await expect(firstHydrate).rejects.toMatchObject({ isSurfaceChangedError: true });
+      expect(sharedPendingLoads.size).toBe(0);
+    } finally {
+      firstLoad.resolve();
+      secondLoad.resolve();
+      activateSurface(LOCAL_SURFACE_ID);
+      await Promise.allSettled([firstHydrate, secondHydrate].filter(Boolean) as Promise<void>[]);
+    }
+  });
+
   it('uses the owning panel scope when a legacy child is missing its workspace location', async () => {
     const { context, flowChatStore } = createContext(createSession({
       workspacePath: undefined,
@@ -814,7 +927,7 @@ describe('SessionModule historical session coordination', () => {
     const { context, flowChatStore } = createContext(createSession({
       sessionKind: 'subagent',
     }));
-    context.pendingHistoryLoads.set('history-other', Promise.resolve());
+    context.pendingHistoryLoads.set(pendingHistoryLoadKey('history-other'), Promise.resolve());
     flowChatStore.loadSessionHistory
       .mockReturnValueOnce(preload.promise)
       .mockResolvedValueOnce(undefined);
@@ -844,7 +957,7 @@ describe('SessionModule historical session coordination', () => {
     const stalePreload = createDeferred<void>();
     const retryLoad = createDeferred<void>();
     const { context, flowChatStore } = createContext(createSession());
-    context.pendingHistoryLoads.set('history-other', Promise.resolve());
+    context.pendingHistoryLoads.set(pendingHistoryLoadKey('history-other'), Promise.resolve());
     persistenceMocks.touchSessionActivity.mockResolvedValue(undefined);
     flowChatStore.loadSessionHistory
       .mockReturnValueOnce(stalePreload.promise)
@@ -899,7 +1012,7 @@ describe('SessionModule historical session coordination', () => {
     const stalePreload = createDeferred<void>();
     const newerSwitchLoad = createDeferred<void>();
     const { context, flowChatStore } = createContext(createSession());
-    context.pendingHistoryLoads.set('history-other', Promise.resolve());
+    context.pendingHistoryLoads.set(pendingHistoryLoadKey('history-other'), Promise.resolve());
     flowChatStore.setState((prev: any) => ({
       ...prev,
       sessions: new Map(prev.sessions).set('history-2', createSession({
@@ -970,7 +1083,7 @@ describe('SessionModule historical session coordination', () => {
       remoteSshHost: 'remote-host',
     });
     const { context, flowChatStore } = createContext(remoteSession);
-    context.pendingHistoryLoads.set('history-other', Promise.resolve());
+    context.pendingHistoryLoads.set(pendingHistoryLoadKey('history-other'), Promise.resolve());
 
     preloadHistoricalSessionForOpen(context, 'history-1');
 
@@ -1196,7 +1309,7 @@ describe('SessionModule historical session coordination', () => {
   it('reuses pending historical hydration before ensuring the backend session', async () => {
     const pendingHydrate = createDeferred<void>();
     const { context, flowChatStore } = createContext(createSession());
-    context.pendingHistoryLoads.set('history-1', pendingHydrate.promise);
+    context.pendingHistoryLoads.set(pendingHistoryLoadKey('history-1'), pendingHydrate.promise);
     agentApiMocks.ensureCoordinatorSession.mockResolvedValueOnce(undefined);
 
     const ensure = ensureBackendSession(context, 'history-1');
@@ -1282,6 +1395,56 @@ describe('SessionModule historical session coordination', () => {
     });
   });
 
+  it('does not reuse or commit a same-id context restore across device activations', async () => {
+    const createRestoringContext = () => createContext(createSession({
+      isHistorical: false,
+      historyState: 'ready',
+      contextRestoreState: 'pending',
+      dialogTurns: [{ id: 'turn-1' } as any],
+    } as any));
+    const first = createRestoringContext();
+    const second = createRestoringContext();
+    const sharedRestores = new Map<string, Promise<void>>();
+    first.context.pendingContextRestores = sharedRestores;
+    second.context.pendingContextRestores = sharedRestores;
+    const firstRestore = createDeferred<void>();
+    const secondRestore = createDeferred<void>();
+    agentApiMocks.ensureCoordinatorSession
+      .mockReturnValueOnce(firstRestore.promise)
+      .mockReturnValueOnce(secondRestore.promise);
+    let firstEnsure: Promise<void> | undefined;
+    let secondEnsure: Promise<void> | undefined;
+
+    try {
+      activateSurface('peer-a');
+      firstEnsure = ensureBackendSession(first.context, 'history-1');
+      expect(agentApiMocks.ensureCoordinatorSession).toHaveBeenCalledTimes(1);
+
+      activateSurface('peer-b');
+      secondEnsure = ensureBackendSession(second.context, 'history-1');
+      expect(agentApiMocks.ensureCoordinatorSession).toHaveBeenCalledTimes(2);
+      expect(sharedRestores.size).toBe(2);
+
+      secondRestore.resolve();
+      await expect(secondEnsure).resolves.toBeUndefined();
+      expect(second.flowChatStore.getState().sessions.get('history-1')).toMatchObject({
+        contextRestoreState: 'ready',
+      });
+
+      firstRestore.resolve();
+      await expect(firstEnsure).rejects.toMatchObject({ isSurfaceChangedError: true });
+      expect(first.flowChatStore.getState().sessions.get('history-1')).toMatchObject({
+        contextRestoreState: 'pending',
+      });
+      expect(sharedRestores.size).toBe(0);
+    } finally {
+      firstRestore.resolve();
+      secondRestore.resolve();
+      activateSurface(LOCAL_SURFACE_ID);
+      await Promise.allSettled([firstEnsure, secondEnsure].filter(Boolean) as Promise<void>[]);
+    }
+  });
+
   it('does not recreate a view-restored session with loaded turns when context restore fails', async () => {
     const { context } = createContext(createSession({
       isHistorical: false,
diff --git a/src/web-ui/src/flow_chat/services/flow-chat-manager/SessionModule.ts b/src/web-ui/src/flow_chat/services/flow-chat-manager/SessionModule.ts
index 14583d867c..862690540c 100644
--- a/src/web-ui/src/flow_chat/services/flow-chat-manager/SessionModule.ts
+++ b/src/web-ui/src/flow_chat/services/flow-chat-manager/SessionModule.ts
@@ -14,6 +14,11 @@ import { elapsedMs, nowMs } from '@/shared/utils/timing';
 import { i18nService } from '@/infrastructure/i18n';
 import { workspaceManager } from '@/infrastructure/services/business/workspaceManager';
 import { isPeerDeviceModeActive } from '@/infrastructure/peer-device/peerModeFlag';
+import {
+  getActiveSurfaceScope,
+  isSurfaceChangedError,
+  type SurfaceScope,
+} from '@/infrastructure/peer-device/deviceSurface';
 import { normalizeRemoteWorkspacePath } from '@/shared/utils/pathUtils';
 import { isRemoteWorkspace, WorkspaceKind, type WorkspaceInfo } from '@/shared/types';
 import type {
@@ -70,12 +75,15 @@ export const SESSION_ACTIVITY_TOUCH_DELAY_MS = 350;
 let latestSwitchRequestId = 0;
 let pendingActivityTouchTimer: ReturnType<typeof setTimeout> | null = null;
 
-function scheduleSessionActivityTouch(task: () => void): void {
+function scheduleSessionActivityTouch(scope: SurfaceScope, task: () => void): void {
   if (pendingActivityTouchTimer !== null) {
     clearTimeout(pendingActivityTouchTimer);
   }
   pendingActivityTouchTimer = setTimeout(() => {
     pendingActivityTouchTimer = null;
+    if (!scope.isCurrent()) {
+      return;
+    }
     task();
   }, SESSION_ACTIVITY_TOUCH_DELAY_MS);
 }
@@ -85,9 +93,43 @@ const normalizeOptional = (value: string | undefined): string | undefined => {
   return trimmed ? trimmed : undefined;
 };
 
-function hasCompetingHistoryLoad(context: FlowChatContext, sessionId: string): boolean {
-  return Array.from(context.pendingHistoryLoads.keys())
-    .some(pendingSessionId => pendingSessionId !== sessionId);
+export function pendingHistoryLoadKey(
+  sessionId: string,
+  scope: SurfaceScope = getActiveSurfaceScope(),
+): string {
+  return scope.key('history-load', scope.epoch, sessionId);
+}
+
+function pendingHistoryLoadSessionId(
+  key: string,
+  scope: SurfaceScope,
+): string | null {
+  try {
+    const parsed = JSON.parse(key) as unknown;
+    if (
+      Array.isArray(parsed)
+      && parsed[0] === scope.surfaceId
+      && parsed[1] === 'history-load'
+      && parsed[2] === scope.epoch
+      && typeof parsed[3] === 'string'
+    ) {
+      return parsed[3];
+    }
+  } catch {
+    // In-flight keys are internal and non-persistent; unknown keys are ignored.
+  }
+  return null;
+}
+
+function hasCompetingHistoryLoad(
+  context: FlowChatContext,
+  sessionId: string,
+  scope: SurfaceScope = getActiveSurfaceScope(),
+): boolean {
+  return Array.from(context.pendingHistoryLoads.keys()).some(key => {
+    const pendingSessionId = pendingHistoryLoadSessionId(key, scope);
+    return pendingSessionId !== null && pendingSessionId !== sessionId;
+  });
 }
 
 const hostFromSshConnectionId = (connectionId: string | undefined): string | undefined => {
@@ -172,9 +214,11 @@ async function hydrateHistoricalSession(
     location?: SessionHistoryHydrationLocation;
   },
 ): Promise<void> {
-  const existing = context.pendingHistoryLoads.get(sessionId);
+  const surfaceScope = getActiveSurfaceScope();
+  const pendingKey = pendingHistoryLoadKey(sessionId, surfaceScope);
+  const existing = context.pendingHistoryLoads.get(pendingKey);
   if (existing) {
-    const existingCapabilities = context.pendingHistoryLoadCapabilities?.get(sessionId);
+    const existingCapabilities = context.pendingHistoryLoadCapabilities?.get(pendingKey);
     const requestedLocationKey = getHydrationLocationKey(options?.location);
     const requiresStrongerHydrate =
       (options?.includeInternal === true && existingCapabilities?.includeInternal !== true) ||
@@ -190,16 +234,18 @@ async function hydrateHistoricalSession(
     let existingError: unknown;
     try {
       await existing;
+      surfaceScope.assertCurrent('reuse historical session hydration');
     } catch (error) {
       existingFailed = true;
       existingError = error;
     }
     if (requiresStrongerHydrate) {
-      if (context.pendingHistoryLoads.get(sessionId) === existing) {
-        context.pendingHistoryLoads.delete(sessionId);
+      surfaceScope.assertCurrent('upgrade historical session hydration');
+      if (context.pendingHistoryLoads.get(pendingKey) === existing) {
+        context.pendingHistoryLoads.delete(pendingKey);
       }
-      if (context.pendingHistoryLoadCapabilities?.get(sessionId)?.promise === existing) {
-        context.pendingHistoryLoadCapabilities.delete(sessionId);
+      if (context.pendingHistoryLoadCapabilities?.get(pendingKey)?.promise === existing) {
+        context.pendingHistoryLoadCapabilities.delete(pendingKey);
       }
       await hydrateHistoricalSession(context, sessionId, notifyOnError, options);
       return;
@@ -219,8 +265,8 @@ async function hydrateHistoricalSession(
       retryStillRelevant &&
       shouldRetryActiveStale
     ) {
-      if (context.pendingHistoryLoads.get(sessionId) === existing) {
-        context.pendingHistoryLoads.delete(sessionId);
+      if (context.pendingHistoryLoads.get(pendingKey) === existing) {
+        context.pendingHistoryLoads.delete(pendingKey);
       }
       startupTrace.markPhase('historical_session_hydrate_retry_active_stale_reuse', {
         sessionId,
@@ -237,6 +283,7 @@ async function hydrateHistoricalSession(
   const traceStartedAt = nowMs();
 
   const loadPromise = (async () => {
+    surfaceScope.assertCurrent('start historical session hydration');
     const session = context.flowChatStore.getState().sessions.get(sessionId);
     if (!session || (!session.isHistorical && options?.allowNonHistorical !== true)) {
       recordHistorySessionDiagnosticEvent(sessionId, 'hydrate_request_skipped', {
@@ -291,12 +338,13 @@ async function hydrateHistoricalSession(
         deferFullHistoryUntilActive,
       },
     );
+    surfaceScope.assertCurrent('finish historical session hydration');
   })();
 
-  context.pendingHistoryLoads.set(sessionId, loadPromise);
+  context.pendingHistoryLoads.set(pendingKey, loadPromise);
   const pendingHistoryLoadCapabilities =
     context.pendingHistoryLoadCapabilities ??= new Map();
-  pendingHistoryLoadCapabilities.set(sessionId, {
+  pendingHistoryLoadCapabilities.set(pendingKey, {
     promise: loadPromise,
     includeInternal: options?.includeInternal === true,
     deferFullHistoryUntilActive: options?.deferFullHistoryUntilActive ?? true,
@@ -310,6 +358,9 @@ async function hydrateHistoricalSession(
       durationMs: elapsedMs(traceStartedAt),
     });
   } catch (error) {
+    if (isSurfaceChangedError(error)) {
+      throw error;
+    }
     recordHistorySessionDiagnosticEvent(sessionId, 'hydrate_request_failed');
     startupTrace.markPhase('historical_session_hydrate_request_failed', {
       durationMs: elapsedMs(traceStartedAt),
@@ -322,14 +373,16 @@ async function hydrateHistoricalSession(
     }
     throw error;
   } finally {
-    clearHistorySessionHydratePending(sessionId, 'settled', {
-      pendingStillCurrent: context.pendingHistoryLoads.get(sessionId) === loadPromise,
-    });
-    if (context.pendingHistoryLoads.get(sessionId) === loadPromise) {
-      context.pendingHistoryLoads.delete(sessionId);
+    if (surfaceScope.isCurrent()) {
+      clearHistorySessionHydratePending(sessionId, 'settled', {
+        pendingStillCurrent: context.pendingHistoryLoads.get(pendingKey) === loadPromise,
+      });
     }
-    if (context.pendingHistoryLoadCapabilities?.get(sessionId)?.promise === loadPromise) {
-      context.pendingHistoryLoadCapabilities.delete(sessionId);
+    if (context.pendingHistoryLoads.get(pendingKey) === loadPromise) {
+      context.pendingHistoryLoads.delete(pendingKey);
+    }
+    if (context.pendingHistoryLoadCapabilities?.get(pendingKey)?.promise === loadPromise) {
+      context.pendingHistoryLoadCapabilities.delete(pendingKey);
     }
   }
 }
@@ -386,6 +439,9 @@ export function preloadHistoricalSessionForOpen(
   }
 
   void hydrateHistoricalSession(context, sessionId, false).catch(error => {
+    if (isSurfaceChangedError(error)) {
+      return;
+    }
     log.debug('Historical session preload failed', { sessionId, error });
   });
 }
@@ -524,6 +580,9 @@ export const resolveAgentTypeForSessionCreation = async (
       modeId: configuredDefaultMode,
     });
   } catch (error) {
+    if (isSurfaceChangedError(error)) {
+      throw error;
+    }
     log.warn('Failed to resolve default chat input mode preference during session creation', {
       error,
     });
@@ -552,6 +611,7 @@ export async function createChatSession(
   config: SessionConfig,
   mode?: string
 ): Promise<string> {
+  const surfaceScope = getActiveSurfaceScope();
   try {
     const workspacePath = resolveSessionWorkspacePath(context, config);
     const workspace = resolveSessionWorkspace(context, config);
@@ -567,6 +627,7 @@ export async function createChatSession(
         ? workspace.sshHost?.trim() || undefined
         : undefined;
     const agentType = await resolveAgentTypeForSessionCreation(mode, workspace);
+    surfaceScope.assertCurrent('resolve session creation mode');
     const sessionMode = normalizeSessionDisplayMode(agentType, workspace);
     const workspaceCreationKey =
       workspace?.id?.trim()
@@ -574,12 +635,14 @@ export async function createChatSession(
         : remoteConnectionId != null && remoteConnectionId !== ''
           ? `${remoteConnectionId}\n${workspacePath}`
           : workspacePath;
-    const creationKey = JSON.stringify([
+    const creationKey = surfaceScope.key(
+      'session-create',
+      surfaceScope.epoch,
       workspaceCreationKey,
       agentType,
-      config.executionTargetRequest ?? { kind: 'local' },
-      config.dispatchTargetRequest ?? { kind: 'local' },
-    ]);
+      JSON.stringify(config.executionTargetRequest ?? { kind: 'local' }),
+      JSON.stringify(config.dispatchTargetRequest ?? { kind: 'local' }),
+    );
 
     const pendingCreation = pendingSessionCreations.get(creationKey);
     if (pendingCreation) {
@@ -589,6 +652,7 @@ export async function createChatSession(
     // Register the pending promise before any async work below. Remote workspace
     // activation can rerun initialization while model config is still loading.
     const createPromise = Promise.resolve().then(async () => {
+      surfaceScope.assertCurrent('start session creation');
       const sameModeCount = getNextDefaultSessionTitleCount(
         context.flowChatStore.getState().sessions.values(),
         {
@@ -606,7 +670,8 @@ export async function createChatSession(
       );
       const sessionName = titleDescriptor.text;
 
-      return driverForCreation(config).createSession(context, {
+      const sessionId = await driverForCreation(config).createSession(context, {
+        surfaceScope,
         config,
         agentType,
         sessionName,
@@ -617,6 +682,8 @@ export async function createChatSession(
         remoteConnectionId,
         remoteSshHost,
       });
+      surfaceScope.assertCurrent('finish session creation');
+      return sessionId;
     });
 
     pendingSessionCreations.set(creationKey, createPromise);
@@ -628,6 +695,9 @@ export async function createChatSession(
       }
     }
   } catch (error) {
+    if (isSurfaceChangedError(error)) {
+      throw error;
+    }
     log.error('Failed to create chat session', { config, error });
     
     notificationService.error('Failed to create chat session', {
@@ -644,6 +714,7 @@ export async function switchChatSession(
   context: FlowChatContext,
   sessionId: string
 ): Promise<void> {
+  const surfaceScope = getActiveSurfaceScope();
   try {
     const switchRequestId = ++latestSwitchRequestId;
     const session = context.flowChatStore.getState().sessions.get(sessionId);
@@ -666,7 +737,7 @@ export async function switchChatSession(
       if (driverForSession(sessionId, session).id === 'dispatch') {
         return;
       }
-      scheduleSessionActivityTouch(() => {
+      scheduleSessionActivityTouch(surfaceScope, () => {
         const latestState = context.flowChatStore.getState();
         const latestSession = latestState.sessions.get(sessionId);
         if (switchRequestId !== latestSwitchRequestId || latestState.activeSessionId !== sessionId || !latestSession) {
@@ -678,6 +749,9 @@ export async function switchChatSession(
           latestSession.remoteConnectionId,
           latestSession.remoteSshHost
         ).catch(error => {
+          if (isSurfaceChangedError(error)) {
+            return;
+          }
           log.debug('Failed to touch session activity', { sessionId, error });
         });
       });
@@ -699,10 +773,16 @@ export async function switchChatSession(
     if (shouldHydrateBeforeSwitch) {
       try {
         await hydrateHistoricalSession(context, sessionId, true, {
-          isRetryStillRelevant: () => switchRequestId === latestSwitchRequestId,
+          isRetryStillRelevant: () => (
+            surfaceScope.isCurrent() && switchRequestId === latestSwitchRequestId
+          ),
           retryActiveStaleReuse: shouldActivateBeforeHydrate,
         });
-      } catch {
+        surfaceScope.assertCurrent('hydrate session before switch');
+      } catch (error) {
+        if (isSurfaceChangedError(error)) {
+          throw error;
+        }
         // The hydrate path already marks the session failed and notifies the user.
         // Continue with activation so the failed state is visible.
       }
@@ -725,6 +805,7 @@ export async function switchChatSession(
     // In that explicit path the intent shield keeps metadata-only content from
     // flashing while the old large session is unmounted immediately.
     if (!shouldActivateBeforeHydrate) {
+      surfaceScope.assertCurrent('activate switched session');
       context.flowChatStore.switchSession(sessionId);
       recordHistorySessionDiagnosticEvent(sessionId, 'switch_activated_after_hydrate', {
         switchRequestId,
@@ -743,9 +824,16 @@ export async function switchChatSession(
       recordHistorySessionDiagnosticEvent(sessionId, 'switch_background_hydrate_started', {
         switchRequestId,
       });
-      void hydrateHistoricalSession(context, sessionId, true);
+      void hydrateHistoricalSession(context, sessionId, true).catch(error => {
+        if (!isSurfaceChangedError(error)) {
+          log.debug('Historical session background hydrate failed', { sessionId, error });
+        }
+      });
     }
   } catch (error) {
+    if (isSurfaceChangedError(error)) {
+      throw error;
+    }
     log.error('Failed to switch chat session', { sessionId, error });
     notificationService.error('Failed to switch session', {
       duration: 3000
@@ -940,6 +1028,7 @@ export async function ensureBackendSession(
   context: FlowChatContext,
   sessionId: string
 ): Promise<void> {
+  const surfaceScope = getActiveSurfaceScope();
   const session = context.flowChatStore.getState().sessions.get(sessionId);
   if (!session) {
     throw new Error(`Session does not exist: ${sessionId}`);
@@ -953,6 +1042,7 @@ export async function ensureBackendSession(
 
   if (session.isHistorical) {
     await hydrateHistoricalSession(context, sessionId, false);
+    surfaceScope.assertCurrent('hydrate session before backend readiness');
   }
 
   const latestSession = context.flowChatStore.getState().sessions.get(sessionId) ?? session;
@@ -988,6 +1078,7 @@ export async function ensureBackendSession(
 
   const markBackendContextReady = () => {
     if (!isHistoricalSession && !requiresContextRestore) return;
+    if (!surfaceScope.isCurrent()) return;
     context.flowChatStore.setState(prev => {
       const newSessions = new Map(prev.sessions);
       const sess = newSessions.get(sessionId);
@@ -1005,6 +1096,7 @@ export async function ensureBackendSession(
 
   const markBackendContextFailed = () => {
     if (!requiresContextRestore) return;
+    if (!surfaceScope.isCurrent()) return;
     context.flowChatStore.setState(prev => {
       const newSessions = new Map(prev.sessions);
       const sess = newSessions.get(sessionId);
@@ -1016,6 +1108,7 @@ export async function ensureBackendSession(
   };
 
   const ensureCoordinator = async () => {
+    surfaceScope.assertCurrent('ensure coordinator session');
     await agentAPI.ensureCoordinatorSession({
       sessionId,
       workspacePath: projectWorkspacePath,
@@ -1023,6 +1116,7 @@ export async function ensureBackendSession(
       remoteSshHost: effectiveSshHost,
       includeInternal: latestSession.sessionKind === 'subagent',
     });
+    surfaceScope.assertCurrent('ensure coordinator session');
     markBackendContextReady();
   };
 
@@ -1030,20 +1124,25 @@ export async function ensureBackendSession(
     if (!context.pendingContextRestores) {
       context.pendingContextRestores = new Map();
     }
-    const restoreKey = [
+    const restoreKey = surfaceScope.key(
+      'context-restore',
+      surfaceScope.epoch,
       sessionId,
       projectWorkspacePath,
-      effectiveConnectionId ?? '',
-      effectiveSshHost ?? '',
-    ].join('\u001f');
+      effectiveConnectionId,
+      effectiveSshHost,
+    );
     const existingRestore = context.pendingContextRestores.get(restoreKey);
     if (existingRestore) {
       await existingRestore;
+      surfaceScope.assertCurrent('reuse backend context restore');
       return;
     }
 
     const restorePromise = ensureCoordinator().catch(error => {
-      markBackendContextFailed();
+      if (!isSurfaceChangedError(error)) {
+        markBackendContextFailed();
+      }
       throw error;
     }).finally(() => {
       if (context.pendingContextRestores?.get(restoreKey) === restorePromise) {
@@ -1062,6 +1161,10 @@ export async function ensureBackendSession(
 
     await ensureCoordinator();
   } catch (e: any) {
+    if (isSurfaceChangedError(e)) {
+      throw e;
+    }
+    surfaceScope.assertCurrent('handle coordinator session failure');
     if (isSessionInUseError(e)) {
       throw e;
     }
@@ -1075,6 +1178,7 @@ export async function ensureBackendSession(
     }
 
     log.debug('Coordinator session missing, creating backend session', { sessionId, error: e });
+    surfaceScope.assertCurrent('recreate backend session');
     await agentAPI.createSession({
       sessionId: sessionId,
       sessionName:
@@ -1104,6 +1208,7 @@ export async function ensureBackendSession(
         remoteSshHost: effectiveSshHost,
       }
     });
+    surfaceScope.assertCurrent('recreate backend session');
     markBackendContextReady();
   }
 }
diff --git a/src/web-ui/src/flow_chat/services/flow-chat-manager/index.ts b/src/web-ui/src/flow_chat/services/flow-chat-manager/index.ts
index 4b99a7092f..791c396472 100644
--- a/src/web-ui/src/flow_chat/services/flow-chat-manager/index.ts
+++ b/src/web-ui/src/flow_chat/services/flow-chat-manager/index.ts
@@ -48,7 +48,9 @@ export {
   cancelSessionTask,
   markCurrentTurnItemsAsCancelled,
   drainPendingQueue,
-  installPendingQueueDrainListener
+  installPendingQueueDrainListener,
+  inFlightSubmissionCount,
+  waitForInFlightSubmissions
 } from './MessageModule';
 
 export { pendingQueueManager } from './PendingQueueModule';
@@ -58,7 +60,8 @@ export {
   shouldProcessEvent,
   mapBackendStateToFrontend,
   initializeEventListeners,
-  processBatchedEvents
+  processBatchedEvents,
+  projectDialogTurnRecovered,
 } from './EventHandlerModule';
 
 export {
diff --git a/src/web-ui/src/flow_chat/services/flow-chat-manager/types.ts b/src/web-ui/src/flow_chat/services/flow-chat-manager/types.ts
index c9e1f3fc31..4a66a2a755 100644
--- a/src/web-ui/src/flow_chat/services/flow-chat-manager/types.ts
+++ b/src/web-ui/src/flow_chat/services/flow-chat-manager/types.ts
@@ -21,7 +21,7 @@ export interface FlowChatContext {
     /** Set when the turn completed with a partial stream recovery. */
     partialRecoveryReason?: string;
   }>;
-  /** In-flight historical session hydration: sessionId -> promise */
+  /** In-flight historical hydration keyed by device surface, epoch, and session. */
   pendingHistoryLoads: Map<string, Promise<void>>;
   /** Capabilities of each in-flight hydrate, used to avoid reusing a weaker preload. */
   pendingHistoryLoadCapabilities?: Map<string, {
@@ -30,7 +30,7 @@ export interface FlowChatContext {
     deferFullHistoryUntilActive: boolean;
     locationKey: string;
   }>;
-  /** In-flight backend context restore for view-restored historical sessions. */
+  /** In-flight backend context restore keyed by device surface and activation. */
   pendingContextRestores?: Map<string, Promise<void>>;
   /** Content buffers: sessionId -> (roundId -> content) */
   contentBuffers: Map<string, Map<string, string>>;
diff --git a/src/web-ui/src/flow_chat/services/goalService.test.ts b/src/web-ui/src/flow_chat/services/goalService.test.ts
new file mode 100644
index 0000000000..0fe697b234
--- /dev/null
+++ b/src/web-ui/src/flow_chat/services/goalService.test.ts
@@ -0,0 +1,214 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { Session } from '../types/flow-chat';
+import { runGoalCommand } from './goalService';
+
+const mocks = vi.hoisted(() => ({
+  activateSessionGoal: vi.fn(),
+  bindSession: vi.fn(),
+  getSessionThreadGoal: vi.fn(),
+  getState: vi.fn(),
+  pendingList: vi.fn(),
+  pendingRemove: vi.fn(),
+  setSessionWorktreeIsolationRequested: vi.fn(),
+  setThreadGoal: vi.fn(),
+  updateSessionExecutionTarget: vi.fn(),
+  notificationSuccess: vi.fn(),
+}));
+
+vi.mock('@/infrastructure/api/service-api/AgentAPI', () => ({
+  agentAPI: {
+    activateSessionGoal: (params: unknown) => mocks.activateSessionGoal(params),
+    clearSessionThreadGoal: vi.fn(),
+    getSessionThreadGoal: (params: unknown) => mocks.getSessionThreadGoal(params),
+    setSessionThreadGoalStatus: vi.fn(),
+    updateSessionThreadGoalObjective: vi.fn(),
+  },
+}));
+
+vi.mock('@/infrastructure/api/service-api/WorktreeAPI', () => ({
+  worktreeAPI: {
+    bindSession: (...args: unknown[]) => mocks.bindSession(...args),
+  },
+}));
+
+vi.mock('@/shared/notification-system', () => ({
+  notificationService: {
+    error: vi.fn(),
+    info: vi.fn(),
+    success: (...args: unknown[]) => mocks.notificationSuccess(...args),
+  },
+}));
+
+vi.mock('../store/FlowChatStore', () => ({
+  flowChatStore: {
+    getState: () => mocks.getState(),
+    setSessionWorktreeIsolationRequested: (...args: unknown[]) => (
+      mocks.setSessionWorktreeIsolationRequested(...args)
+    ),
+    setThreadGoal: (...args: unknown[]) => mocks.setThreadGoal(...args),
+    updateSessionExecutionTarget: (...args: unknown[]) => (
+      mocks.updateSessionExecutionTarget(...args)
+    ),
+  },
+}));
+
+vi.mock('./flow-chat-manager/PendingQueueModule', () => ({
+  pendingQueueManager: {
+    list: (...args: unknown[]) => mocks.pendingList(...args),
+    remove: (...args: unknown[]) => mocks.pendingRemove(...args),
+  },
+}));
+
+describe('/goal worktree preparation', () => {
+  let currentSession: Session;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    currentSession = {
+      sessionId: 'session-1',
+      dialogTurns: [],
+      status: 'active',
+      config: {
+        workspacePath: '/repo',
+        projectWorkspacePath: '/repo',
+        executionTarget: {
+          kind: 'local',
+          rootPath: '/repo',
+        },
+        worktreeIsolationRequested: true,
+      },
+      workspacePath: '/repo',
+      projectWorkspacePath: '/repo',
+      createdAt: 0,
+      lastActiveAt: 0,
+      error: null,
+      sessionKind: 'normal',
+    };
+
+    mocks.getState.mockImplementation(() => ({
+      sessions: new Map([[currentSession.sessionId, currentSession]]),
+    }));
+    mocks.pendingList.mockReturnValue([]);
+    mocks.getSessionThreadGoal.mockResolvedValue({ goal: null });
+    mocks.bindSession.mockResolvedValue({
+      sessionId: currentSession.sessionId,
+      workspacePath: '/worktrees/wt-1',
+      projectWorkspacePath: '/repo',
+      workspaceId: 'workspace-1',
+      executionTarget: {
+        kind: 'managedWorktree',
+        worktreeId: 'wt-1',
+        rootPath: '/worktrees/wt-1',
+      },
+    });
+    mocks.updateSessionExecutionTarget.mockImplementation((
+      _sessionId: string,
+      binding: {
+        workspacePath: string;
+        projectWorkspacePath: string;
+        workspaceId?: string;
+        executionTarget: Session['config']['executionTarget'];
+      },
+    ) => {
+      currentSession = {
+        ...currentSession,
+        workspacePath: binding.workspacePath,
+        projectWorkspacePath: binding.projectWorkspacePath,
+        workspaceId: binding.workspaceId,
+        config: {
+          ...currentSession.config,
+          workspacePath: binding.workspacePath,
+          projectWorkspacePath: binding.projectWorkspacePath,
+          workspaceId: binding.workspaceId,
+          executionTarget: binding.executionTarget,
+        },
+      };
+    });
+    mocks.setSessionWorktreeIsolationRequested.mockImplementation((
+      _sessionId: string,
+      requested: boolean | undefined,
+    ) => {
+      currentSession = {
+        ...currentSession,
+        config: {
+          ...currentSession.config,
+          worktreeIsolationRequested: requested,
+        },
+      };
+    });
+    mocks.activateSessionGoal.mockResolvedValue({
+      goal: {
+        goalId: 'goal-1',
+        objective: 'finish the task',
+        status: 'active',
+      },
+    });
+  });
+
+  it('materializes the pending worktree before activating a new goal', async () => {
+    const result = await runGoalCommand({
+      session: currentSession,
+      action: { kind: 'set', objective: 'finish the task' },
+      usageMessage: 'usage',
+      failedTitle: 'failed',
+      unknownErrorMessage: 'unknown',
+      activatedTitle: 'activated',
+      clearedTitle: 'cleared',
+      pausedTitle: 'paused',
+      resumedTitle: 'resumed',
+      editedTitle: 'edited',
+    });
+
+    expect(mocks.bindSession).toHaveBeenCalledWith(
+      'session-1',
+      true,
+      expect.any(String),
+      '/repo',
+    );
+    expect(mocks.activateSessionGoal).toHaveBeenCalledWith({
+      sessionId: 'session-1',
+      workspacePath: '/repo',
+      remoteConnectionId: undefined,
+      remoteSshHost: undefined,
+      userHint: 'finish the task',
+    });
+    expect(mocks.bindSession.mock.invocationCallOrder[0]).toBeLessThan(
+      mocks.activateSessionGoal.mock.invocationCallOrder[0],
+    );
+    expect(currentSession.config.executionTarget?.worktreeId).toBe('wt-1');
+    expect(currentSession.config.worktreeIsolationRequested).toBeUndefined();
+    expect(result).toMatchObject({
+      goalId: 'goal-1',
+      objective: 'finish the task',
+      status: 'active',
+    });
+  });
+
+  it('clears a stale worktree request instead of rebinding a nonempty session', async () => {
+    currentSession = {
+      ...currentSession,
+      totalTurnCount: 1,
+    };
+
+    await runGoalCommand({
+      session: currentSession,
+      action: { kind: 'set', objective: 'finish the task' },
+      usageMessage: 'usage',
+      failedTitle: 'failed',
+      unknownErrorMessage: 'unknown',
+      activatedTitle: 'activated',
+      clearedTitle: 'cleared',
+      pausedTitle: 'paused',
+      resumedTitle: 'resumed',
+      editedTitle: 'edited',
+    });
+
+    expect(mocks.bindSession).not.toHaveBeenCalled();
+    expect(mocks.setSessionWorktreeIsolationRequested).toHaveBeenCalledWith(
+      'session-1',
+      undefined,
+    );
+    expect(mocks.activateSessionGoal).toHaveBeenCalledOnce();
+    expect(currentSession.config.worktreeIsolationRequested).toBeUndefined();
+  });
+});
diff --git a/src/web-ui/src/flow_chat/services/goalService.ts b/src/web-ui/src/flow_chat/services/goalService.ts
index dfbecd51f8..7d123dcb86 100644
--- a/src/web-ui/src/flow_chat/services/goalService.ts
+++ b/src/web-ui/src/flow_chat/services/goalService.ts
@@ -1,10 +1,12 @@
 import { agentAPI } from '@/infrastructure/api/service-api/AgentAPI';
+import { worktreeAPI } from '@/infrastructure/api/service-api/WorktreeAPI';
 import { notificationService } from '@/shared/notification-system';
 import type { Session } from '../types/flow-chat';
 import { flowChatStore } from '../store/FlowChatStore';
 import { pendingQueueManager } from './flow-chat-manager/PendingQueueModule';
 import type { GoalCommandAction } from './goalCommandParser';
 import { sessionProjectWorkspacePath } from '../utils/sessionWorkspace';
+import { sessionWorktreeMaterializationPlan } from '../utils/sessionWorktree';
 
 export { isGoalSlashCommand, parseGoalCommand } from './goalCommandParser';
 export type { GoalCommandAction } from './goalCommandParser';
@@ -113,6 +115,39 @@ async function sessionRequestBase(session: Session) {
   };
 }
 
+/**
+ * `/goal` can start backend work without passing through the normal first-message
+ * driver. Materialize the composer's pending worktree choice before any goal
+ * action that can start or steer a turn. For an older session with a stale
+ * pending flag, the plan is intentionally empty and we only clear that flag.
+ */
+async function prepareSessionForGoalTurn(session: Session): Promise<Session> {
+  const sessionId = session.sessionId;
+  const latest = flowChatStore.getState().sessions.get(sessionId) ?? session;
+  if (latest.config.worktreeIsolationRequested === undefined) {
+    return latest;
+  }
+
+  const materialization = sessionWorktreeMaterializationPlan(latest);
+  if (materialization) {
+    const result = await worktreeAPI.bindSession(
+      sessionId,
+      materialization.enabled,
+      globalThis.crypto?.randomUUID?.() ?? `goal-worktree-${Date.now()}`,
+      materialization.projectWorkspacePath,
+    );
+    flowChatStore.updateSessionExecutionTarget(sessionId, {
+      workspacePath: result.workspacePath,
+      projectWorkspacePath: result.projectWorkspacePath,
+      workspaceId: result.workspaceId,
+      executionTarget: result.executionTarget,
+    });
+  }
+
+  flowChatStore.setSessionWorktreeIsolationRequested(sessionId, undefined);
+  return flowChatStore.getState().sessions.get(sessionId) ?? latest;
+}
+
 export async function fetchSessionThreadGoal(
   session: Session
 ): Promise<ThreadGoalSnapshot | null> {
@@ -186,7 +221,12 @@ export async function runGoalCommand(params: GoalCommandParams): Promise<ThreadG
       return snapshot;
     }
     case 'resume': {
-      const goal = await agentAPI.setSessionThreadGoalStatus({ ...base, status: 'active' });
+      const preparedSession = await prepareSessionForGoalTurn(params.session);
+      const preparedBase = await sessionRequestBase(preparedSession);
+      const goal = await agentAPI.setSessionThreadGoalStatus({
+        ...preparedBase,
+        status: 'active',
+      });
       const snapshot = mapGoal(goal);
       syncGoalToStore(params.session.sessionId, snapshot);
       notificationService.success(goal.objective, {
@@ -212,8 +252,10 @@ export async function runGoalCommand(params: GoalCommandParams): Promise<ThreadG
         }
       }
 
+      const preparedSession = await prepareSessionForGoalTurn(params.session);
+      const preparedBase = await sessionRequestBase(preparedSession);
       const activation = await agentAPI.activateSessionGoal({
-        ...base,
+        ...preparedBase,
         userHint: params.action.objective,
       });
 
@@ -289,8 +331,6 @@ export async function saveThreadGoalObjective(
     throw new Error('A workspace is required to use /goal.');
   }
 
-  const base = await sessionRequestBase(session);
-
   if (mode === 'create') {
     return runGoalCommand({
       session,
@@ -309,8 +349,10 @@ export async function saveThreadGoalObjective(
     });
   }
 
+  const preparedSession = await prepareSessionForGoalTurn(session);
+  const preparedBase = await sessionRequestBase(preparedSession);
   const goal = await agentAPI.updateSessionThreadGoalObjective({
-    ...base,
+    ...preparedBase,
     objective: trimmed,
   });
   const snapshot = mapGoal(goal);
diff --git a/src/web-ui/src/flow_chat/services/historySessionDiagnostics.test.ts b/src/web-ui/src/flow_chat/services/historySessionDiagnostics.test.ts
index a596556c42..669b6f6cdd 100644
--- a/src/web-ui/src/flow_chat/services/historySessionDiagnostics.test.ts
+++ b/src/web-ui/src/flow_chat/services/historySessionDiagnostics.test.ts
@@ -1,8 +1,10 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import {
   beginHistorySessionDiagnostics,
+  recordHistoryPagingEvent,
   recordHistorySessionDiagnosticEvent,
   resetHistorySessionDiagnosticsForTests,
+  warnHistoryPagingRefusedWithPendingTurns,
   warnHistorySessionLoadingLayerStalled,
 } from './historySessionDiagnostics';
 
@@ -15,6 +17,12 @@ vi.mock('@/shared/utils/logger', () => ({
   createLogger: () => loggerMock,
 }));
 
+const flowChatDiagnosticsMock = vi.hoisted(() => ({ trace: vi.fn() }));
+
+vi.mock('@/infrastructure/diagnostics/flowChatDiagnostics', () => ({
+  flowChatDiagnostics: flowChatDiagnosticsMock,
+}));
+
 describe('historySessionDiagnostics', () => {
   beforeEach(() => {
     loggerMock.debug.mockReset();
@@ -94,3 +102,111 @@ describe('historySessionDiagnostics', () => {
     );
   });
 });
+
+describe('history paging diagnostics', () => {
+  beforeEach(() => {
+    loggerMock.debug.mockReset();
+    loggerMock.warn.mockReset();
+    resetHistorySessionDiagnosticsForTests();
+  });
+
+  it('warns once with the paging trail when older Turns are refused', () => {
+    recordHistoryPagingEvent('paging-1', 'requested', {
+      direction: 'before',
+      resolvedTotalTurnCount: 0,
+      loadedTurnCount: 3,
+    });
+    recordHistoryPagingEvent('paging-1', 'outcome_exhausted', {
+      direction: 'before',
+      reason: 'beyond-known-total',
+      targetOrdinal: 2,
+      totalTurnCount: 0,
+    });
+
+    warnHistoryPagingRefusedWithPendingTurns('paging-1', {
+      direction: 'before',
+      reason: 'exhausted-on-unknown-total',
+      isPartial: true,
+      loadedTurnCount: 3,
+      totalTurnCount: 0,
+      targetOrdinal: 2,
+    });
+
+    expect(loggerMock.warn).toHaveBeenCalledTimes(2);
+    const [refusal, trail] = loggerMock.warn.mock.calls;
+    expect(refusal[0]).toContain('declined to page older Turns');
+    expect(refusal[1]).toMatchObject({
+      sessionId: 'paging-1',
+      reason: 'exhausted-on-unknown-total',
+      isPartial: true,
+      totalTurnCount: 0,
+    });
+    // The decisive prior step travels with the warning.
+    expect(refusal[1].lastOutcome).toBe('history_paging_outcome_exhausted');
+    expect(refusal[1].lastOutcomeData).toMatchObject({ reason: 'beyond-known-total' });
+    expect(trail[1].events.map((event: { event: string }) => event.event)).toEqual([
+      'history_paging_requested',
+      'history_paging_outcome_exhausted',
+      'history_paging_refused_with_pending_turns',
+    ]);
+  });
+
+  it('stays quiet on repeat refusals so scrolling cannot flood the log', () => {
+    const snapshot = {
+      direction: 'before',
+      reason: 'latched-exhausted-while-partial',
+      isPartial: true,
+      loadedTurnCount: 3,
+      totalTurnCount: 22,
+    };
+    warnHistoryPagingRefusedWithPendingTurns('paging-2', snapshot);
+    warnHistoryPagingRefusedWithPendingTurns('paging-2', snapshot);
+    warnHistoryPagingRefusedWithPendingTurns('paging-2', snapshot);
+
+    expect(loggerMock.warn).toHaveBeenCalledTimes(2);
+  });
+
+  it('keeps the latch per session', () => {
+    const snapshot = { direction: 'before', reason: 'latched-exhausted-while-partial' };
+    warnHistoryPagingRefusedWithPendingTurns('paging-3', snapshot);
+    warnHistoryPagingRefusedWithPendingTurns('paging-4', snapshot);
+
+    expect(loggerMock.warn).toHaveBeenCalledTimes(4);
+  });
+});
+
+describe('history paging log routing', () => {
+  beforeEach(() => {
+    loggerMock.debug.mockReset();
+    loggerMock.warn.mockReset();
+    flowChatDiagnosticsMock.trace.mockReset();
+    resetHistorySessionDiagnosticsForTests();
+  });
+
+  it('streams paging steps to flowchat.log and keeps them out of webview.log', () => {
+    recordHistoryPagingEvent('routing-1', 'requested', { direction: 'before' });
+
+    expect(loggerMock.debug).not.toHaveBeenCalled();
+    expect(flowChatDiagnosticsMock.trace).toHaveBeenCalledTimes(1);
+    const probe = flowChatDiagnosticsMock.trace.mock.calls[0][0];
+    expect(probe.hypothesis).toBe('history-paging');
+    expect(probe.location).toBe('historySessionDiagnostics.requested');
+    // Payload stays behind a thunk so a disabled channel costs nothing.
+    expect(typeof probe.data).toBe('function');
+    expect(probe.data()).toMatchObject({ sessionId: 'routing-1', direction: 'before' });
+  });
+
+  it('reports the refusal on both channels', () => {
+    warnHistoryPagingRefusedWithPendingTurns('routing-2', {
+      direction: 'before',
+      reason: 'latched-exhausted-while-partial',
+    });
+
+    // Always-on alarm, independent of the diagnostics flag.
+    expect(loggerMock.warn).toHaveBeenCalledTimes(2);
+    // Mirrored so the flowchat.log stream is self-contained.
+    expect(flowChatDiagnosticsMock.trace).toHaveBeenCalledTimes(1);
+    expect(flowChatDiagnosticsMock.trace.mock.calls[0][0].location)
+      .toBe('historySessionDiagnostics.refusedWithPendingTurns');
+  });
+});
diff --git a/src/web-ui/src/flow_chat/services/historySessionDiagnostics.ts b/src/web-ui/src/flow_chat/services/historySessionDiagnostics.ts
index 35702d8bd5..bae7a642dc 100644
--- a/src/web-ui/src/flow_chat/services/historySessionDiagnostics.ts
+++ b/src/web-ui/src/flow_chat/services/historySessionDiagnostics.ts
@@ -1,8 +1,12 @@
 import { createLogger } from '@/shared/utils/logger';
 import { elapsedMs, nowMs, roundDurationMs } from '@/shared/utils/timing';
+import { flowChatDiagnostics } from '@/infrastructure/diagnostics/flowChatDiagnostics';
 
 const log = createLogger('HistorySessionDiagnostics');
 
+/** Probe tag for the older-history paging handshake in `flowchat.log`. */
+const HISTORY_PAGING_PROBE = 'history-paging';
+
 const RECENT_EVENT_LIMIT = 30;
 const WARN_EVENT_LIMIT = 15;
 const MAX_SESSION_DIAGNOSTICS = 50;
@@ -32,6 +36,7 @@ interface HistorySessionDiagnosticState {
   pendingHydrateStartedAtMs?: number;
   pendingHydrateData?: HistorySessionDiagnosticData;
   stalledWarned: boolean;
+  pagingRefusalWarned: boolean;
 }
 
 export interface HistorySessionLoadingStallSnapshot extends HistorySessionDiagnosticData {
@@ -44,6 +49,26 @@ export interface HistorySessionLoadingStallSnapshot extends HistorySessionDiagno
   dialogTurnCount?: number;
 }
 
+/**
+ * State captured when the transcript declines to page older Turns even though
+ * the session still reports unloaded ones.
+ *
+ * Every way this can fail — a precondition miss, a cancelled viewport
+ * preparation, a spurious `exhausted` that latches the direction off — looks
+ * identical in the UI to "there is no more history": the boundary status
+ * returns to idle and no indicator is shown. The trail is the only way to tell
+ * them apart after the fact, which matters because the failure is intermittent.
+ */
+export interface HistoryPagingRefusalSnapshot extends HistorySessionDiagnosticData {
+  direction: string;
+  reason: string;
+  isPartial?: boolean;
+  latchedExhausted?: boolean;
+  loadedTurnCount?: number;
+  totalTurnCount?: number;
+  targetOrdinal?: number;
+}
+
 const diagnosticsBySession = new Map<string, HistorySessionDiagnosticState>();
 let diagnosticSequence = 0;
 
@@ -75,6 +100,7 @@ function getOrCreateDiagnostic(sessionId: string): HistorySessionDiagnosticState
     startedAtMs: nowMs(),
     events: [],
     stalledWarned: false,
+    pagingRefusalWarned: false,
   };
   diagnosticsBySession.set(sessionId, created);
   trimOldDiagnostics();
@@ -141,6 +167,7 @@ export function beginHistorySessionDiagnostics(
     startedAtMs: nowMs(),
     events: [],
     stalledWarned: false,
+    pagingRefusalWarned: false,
   };
   diagnosticsBySession.set(sessionId, state);
   trimOldDiagnostics();
@@ -230,3 +257,78 @@ export function resetHistorySessionDiagnosticsForTests(): void {
   diagnosticsBySession.clear();
   diagnosticSequence = 0;
 }
+
+/**
+ * Record one step of the older-history paging handshake.
+ *
+ * The in-memory trail is always kept — it is what makes the refusal warning
+ * self-sufficient without asking the user to reproduce with a flag on. The full
+ * uncapped stream goes to `flowchat.log` through the FlowChat diagnostics
+ * channel, which is opt-in via `app.logging.flow_chat_diagnostics`, so it stays
+ * out of `webview.log`.
+ */
+export function recordHistoryPagingEvent(
+  sessionId: string,
+  event: string,
+  data?: HistorySessionDiagnosticData,
+): void {
+  const state = getOrCreateDiagnostic(sessionId);
+  pushEvent(state, `history_paging_${event}`, data, { logEvent: false });
+  flowChatDiagnostics.trace({
+    hypothesis: HISTORY_PAGING_PROBE,
+    location: `historySessionDiagnostics.${event}`,
+    message: `history paging ${event}`,
+    data: () => ({
+      diagnosticId: state.diagnosticId,
+      sessionId,
+      ...(data ?? {}),
+    }),
+  });
+}
+
+/**
+ * Report that older Turns were not loaded although the session still has some,
+ * together with the trail that led there. Warns once per session so a user
+ * scrolling repeatedly against a dead boundary does not flood the log.
+ */
+export function warnHistoryPagingRefusedWithPendingTurns(
+  sessionId: string,
+  snapshot: HistoryPagingRefusalSnapshot,
+): void {
+  const state = getOrCreateDiagnostic(sessionId);
+  if (state.pagingRefusalWarned) {
+    return;
+  }
+
+  state.pagingRefusalWarned = true;
+  pushEvent(state, 'history_paging_refused_with_pending_turns', snapshot, { logEvent: false });
+
+  const lastOutcome = findLastEvent(state, event => event.event.startsWith('history_paging_outcome'));
+  const lastRequest = findLastEvent(state, event => event.event.startsWith('history_paging_requested'));
+
+  log.warn('FlowChat declined to page older Turns while the session reports more', {
+    diagnosticId: state.diagnosticId,
+    sessionId,
+    ...snapshot,
+    lastOutcome: lastOutcome?.event,
+    lastOutcomeData: lastOutcome?.data,
+    lastRequestData: lastRequest?.data,
+  });
+  log.warn('FlowChat history paging trail', {
+    diagnosticId: state.diagnosticId,
+    sessionId,
+    events: summarizeEvents(state),
+  });
+  // Mirror the alarm into flowchat.log so that stream is self-contained when
+  // FlowChat diagnostics are on.
+  flowChatDiagnostics.trace({
+    hypothesis: HISTORY_PAGING_PROBE,
+    location: 'historySessionDiagnostics.refusedWithPendingTurns',
+    message: 'declined to page older Turns while the session reports more',
+    data: () => ({
+      diagnosticId: state.diagnosticId,
+      sessionId,
+      ...snapshot,
+    }),
+  });
+}
\ No newline at end of file
diff --git a/src/web-ui/src/flow_chat/services/interruptedTurnRecoveryGate.test.ts b/src/web-ui/src/flow_chat/services/interruptedTurnRecoveryGate.test.ts
new file mode 100644
index 0000000000..b1371b6dd2
--- /dev/null
+++ b/src/web-ui/src/flow_chat/services/interruptedTurnRecoveryGate.test.ts
@@ -0,0 +1,59 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { interruptedTurnRecoveryGate } from './interruptedTurnRecoveryGate';
+
+const first = {
+  sessionId: 'session-1',
+  turnId: 'turn-1',
+  executionGeneration: 0,
+};
+
+afterEach(() => {
+  interruptedTurnRecoveryGate.resetForTests();
+});
+
+describe('interruptedTurnRecoveryGate', () => {
+  it('keeps one session-scoped operation until an authoritative event clears it', () => {
+    const listener = vi.fn();
+    const unsubscribe = interruptedTurnRecoveryGate.subscribe(listener);
+
+    expect(interruptedTurnRecoveryGate.tryBegin(first)).toBe(true);
+    expect(interruptedTurnRecoveryGate.tryBegin(first)).toBe(false);
+    expect(interruptedTurnRecoveryGate.isSessionInFlight(first.sessionId)).toBe(true);
+    expect(interruptedTurnRecoveryGate.isSessionInFlight('session-2')).toBe(false);
+
+    interruptedTurnRecoveryGate.clearRecovered({
+      ...first,
+      executionGeneration: 1,
+    });
+    expect(interruptedTurnRecoveryGate.isSessionInFlight(first.sessionId)).toBe(false);
+    expect(listener).toHaveBeenCalledTimes(2);
+    unsubscribe();
+  });
+
+  it('does not clear for stale recovery or interruption events', () => {
+    expect(interruptedTurnRecoveryGate.tryBegin(first)).toBe(true);
+
+    interruptedTurnRecoveryGate.clearRecovered(first);
+    interruptedTurnRecoveryGate.clearInterrupted(first);
+    expect(interruptedTurnRecoveryGate.isSessionInFlight(first.sessionId)).toBe(true);
+
+    interruptedTurnRecoveryGate.clearInterrupted({
+      ...first,
+      executionGeneration: 1,
+    });
+    expect(interruptedTurnRecoveryGate.isSessionInFlight(first.sessionId)).toBe(false);
+  });
+
+  it('clears an RPC failure only for the exact request identity', () => {
+    expect(interruptedTurnRecoveryGate.tryBegin(first)).toBe(true);
+
+    interruptedTurnRecoveryGate.clearExact({
+      ...first,
+      turnId: 'another-turn',
+    });
+    expect(interruptedTurnRecoveryGate.isSessionInFlight(first.sessionId)).toBe(true);
+
+    interruptedTurnRecoveryGate.clearExact(first);
+    expect(interruptedTurnRecoveryGate.isSessionInFlight(first.sessionId)).toBe(false);
+  });
+});
diff --git a/src/web-ui/src/flow_chat/services/interruptedTurnRecoveryGate.ts b/src/web-ui/src/flow_chat/services/interruptedTurnRecoveryGate.ts
new file mode 100644
index 0000000000..cbf3d6c7bf
--- /dev/null
+++ b/src/web-ui/src/flow_chat/services/interruptedTurnRecoveryGate.ts
@@ -0,0 +1,88 @@
+export interface InterruptedTurnRecoveryOperation {
+  sessionId: string;
+  turnId: string;
+  executionGeneration: number;
+}
+
+type Listener = () => void;
+
+function sameOperation(
+  left: InterruptedTurnRecoveryOperation,
+  right: InterruptedTurnRecoveryOperation,
+): boolean {
+  return left.sessionId === right.sessionId
+    && left.turnId === right.turnId
+    && left.executionGeneration === right.executionGeneration;
+}
+
+class InterruptedTurnRecoveryGate {
+  private readonly operations = new Map<string, InterruptedTurnRecoveryOperation>();
+  private readonly listeners = new Set<Listener>();
+  private version = 0;
+
+  public readonly subscribe = (listener: Listener): (() => void) => {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+
+  public readonly getSnapshot = (): number => this.version;
+
+  public tryBegin(operation: InterruptedTurnRecoveryOperation): boolean {
+    if (this.operations.has(operation.sessionId)) return false;
+    this.operations.set(operation.sessionId, operation);
+    this.emit();
+    return true;
+  }
+
+  public isSessionInFlight(sessionId: string | null | undefined): boolean {
+    return Boolean(sessionId && this.operations.has(sessionId));
+  }
+
+  public clearExact(operation: InterruptedTurnRecoveryOperation): void {
+    const current = this.operations.get(operation.sessionId);
+    if (!current || !sameOperation(current, operation)) return;
+    this.operations.delete(operation.sessionId);
+    this.emit();
+  }
+
+  public clearRecovered(operation: InterruptedTurnRecoveryOperation): void {
+    this.clearNextGeneration(operation);
+  }
+
+  public clearInterrupted(operation: InterruptedTurnRecoveryOperation): void {
+    this.clearNextGeneration(operation);
+  }
+
+  public clearTerminal(sessionId: string, turnId: string): void {
+    const current = this.operations.get(sessionId);
+    if (!current || current.turnId !== turnId) return;
+    this.operations.delete(sessionId);
+    this.emit();
+  }
+
+  public resetForTests(): void {
+    if (this.operations.size === 0) return;
+    this.operations.clear();
+    this.emit();
+  }
+
+  private clearNextGeneration(operation: InterruptedTurnRecoveryOperation): void {
+    const current = this.operations.get(operation.sessionId);
+    if (
+      !current
+      || current.turnId !== operation.turnId
+      || operation.executionGeneration <= current.executionGeneration
+    ) {
+      return;
+    }
+    this.operations.delete(operation.sessionId);
+    this.emit();
+  }
+
+  private emit(): void {
+    this.version += 1;
+    for (const listener of this.listeners) listener();
+  }
+}
+
+export const interruptedTurnRecoveryGate = new InterruptedTurnRecoveryGate();
diff --git a/src/web-ui/src/flow_chat/services/threadGoalActions.test.ts b/src/web-ui/src/flow_chat/services/threadGoalActions.test.ts
index 8d2d7f8573..279fa5208e 100644
--- a/src/web-ui/src/flow_chat/services/threadGoalActions.test.ts
+++ b/src/web-ui/src/flow_chat/services/threadGoalActions.test.ts
@@ -1,5 +1,12 @@
-import { describe, expect, it } from 'vitest';
-import { threadGoalActionsForStatus } from './threadGoalActions';
+// @vitest-environment jsdom
+import { beforeEach, describe, expect, it } from 'vitest';
+import {
+  dismissResumePrompt,
+  resumePromptKey,
+  shouldOpenResumePrompt,
+  threadGoalActionsForStatus,
+} from './threadGoalActions';
+import type { ThreadGoalSnapshot } from './goalService';
 
 describe('threadGoalActionsForStatus', () => {
   it('offers resume for paused goals after user stop', () => {
@@ -10,3 +17,64 @@ describe('threadGoalActionsForStatus', () => {
     expect(threadGoalActionsForStatus('active')).toEqual(['edit', 'pause', 'clear']);
   });
 });
+
+const pausedGoal: ThreadGoalSnapshot = {
+  goalId: 'goal-1',
+  objective: 'ship the thing',
+  status: 'paused',
+  updatedAt: 42,
+};
+
+function gate(overrides: Partial<Parameters<typeof shouldOpenResumePrompt>[0]> = {}) {
+  return shouldOpenResumePrompt({
+    sessionId: 'session-1',
+    goal: pausedGoal,
+    sceneActive: true,
+    disabled: false,
+    lastPromptedKey: null,
+    ...overrides,
+  });
+}
+
+describe('resumePromptKey', () => {
+  it('keys the prompt by goal, revision and status', () => {
+    expect(resumePromptKey(pausedGoal)).toBe('goal-1:42:paused');
+  });
+
+  it('has no key for statuses that never prompt', () => {
+    expect(resumePromptKey({ ...pausedGoal, status: 'active' })).toBeNull();
+    expect(resumePromptKey(null)).toBeNull();
+  });
+});
+
+describe('shouldOpenResumePrompt', () => {
+  beforeEach(() => {
+    sessionStorage.clear();
+  });
+
+  it('prompts while the user is looking at the session that owns the goal', () => {
+    expect(gate()).toBe(true);
+  });
+
+  it('stays closed while the session sits in a background scene', () => {
+    expect(gate({ sceneActive: false })).toBe(false);
+  });
+
+  it('prompts again once the user opens that session, after the gate is re-armed', () => {
+    const key = resumePromptKey(pausedGoal);
+    expect(gate({ lastPromptedKey: key })).toBe(false);
+    expect(gate({ lastPromptedKey: null })).toBe(true);
+  });
+
+  it('respects an explicit leave-paused dismissal', () => {
+    dismissResumePrompt('session-1', pausedGoal);
+    expect(gate()).toBe(false);
+  });
+
+  it('does not prompt for goals that are not paused, or when goals are disabled', () => {
+    expect(gate({ goal: { ...pausedGoal, status: 'active' } })).toBe(false);
+    expect(gate({ goal: null })).toBe(false);
+    expect(gate({ disabled: true })).toBe(false);
+    expect(gate({ sessionId: undefined })).toBe(false);
+  });
+});
diff --git a/src/web-ui/src/flow_chat/services/threadGoalActions.ts b/src/web-ui/src/flow_chat/services/threadGoalActions.ts
index 0120ffdc4d..33b06b19d9 100644
--- a/src/web-ui/src/flow_chat/services/threadGoalActions.ts
+++ b/src/web-ui/src/flow_chat/services/threadGoalActions.ts
@@ -43,3 +43,40 @@ export function dismissResumePrompt(sessionId: string, goal: ThreadGoalSnapshot)
     // ignore storage failures
   }
 }
+
+/**
+ * Identifies one paused-goal state, so the resume prompt opens once per visit to
+ * the session instead of on every effect run. Null when the goal cannot prompt.
+ */
+export function resumePromptKey(goal: ThreadGoalSnapshot | null | undefined): string | null {
+  if (!goal?.goalId || !threadGoalStatusNeedsResumePrompt(goal.status)) return null;
+  return `${goal.goalId}:${goal.updatedAt ?? 0}:${goal.status}`;
+}
+
+export interface ResumePromptGate {
+  sessionId: string | undefined;
+  goal: ThreadGoalSnapshot | null;
+  /** False while the session sits in a scene the user is not looking at. */
+  sceneActive: boolean;
+  disabled: boolean;
+  /** State this controller already prompted for during the current visit. */
+  lastPromptedKey: string | null;
+}
+
+/**
+ * The prompt belongs to the session the user opened. Every scene stays mounted,
+ * so without the `sceneActive` gate a paused goal would raise its modal on top
+ * of whatever unrelated scene happens to be in front.
+ */
+export function shouldOpenResumePrompt({
+  sessionId,
+  goal,
+  sceneActive,
+  disabled,
+  lastPromptedKey,
+}: ResumePromptGate): boolean {
+  if (disabled || !sceneActive || !sessionId || !goal) return false;
+  const key = resumePromptKey(goal);
+  if (!key || key === lastPromptedKey) return false;
+  return !isResumePromptDismissed(sessionId, goal);
+}
diff --git a/src/web-ui/src/flow_chat/services/usageReportService.test.ts b/src/web-ui/src/flow_chat/services/usageReportService.test.ts
index 4f722e3eaa..1e91b2b503 100644
--- a/src/web-ui/src/flow_chat/services/usageReportService.test.ts
+++ b/src/web-ui/src/flow_chat/services/usageReportService.test.ts
@@ -2,14 +2,15 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import type {
   SessionUsageReport,
 } from '@/infrastructure/api/service-api/SessionAPI';
-import type { DialogTurnData } from '@/shared/types/session-history';
 import type { FlowChatState, Session } from '../types/flow-chat';
 import { flowChatStore } from '../store/FlowChatStore';
+import {
+  closeSessionUsageModal,
+  getSessionUsageModalState,
+} from '../components/usage/sessionUsageModalState';
 
 const sessionApiMocks = vi.hoisted(() => ({
   getSessionUsageReport: vi.fn(),
-  saveSessionTurn: vi.fn(),
-  recordLocalCommandTurn: vi.fn(),
 }));
 
 vi.mock('@/infrastructure/api/service-api/SessionAPI', () => ({
@@ -101,6 +102,18 @@ const usageReport = (overrides: Partial<SessionUsageReport> = {}): SessionUsageR
   ...overrides,
 });
 
+const uiParams = {
+  isProcessing: false,
+  busyMessage: 'busy',
+  noWorkspaceMessage: 'missing workspace',
+  failedTitle: 'failed',
+  unknownErrorMessage: 'unknown',
+};
+
+const transcriptOf = (sessionId = 'session-1') => (
+  flowChatStore.getState().sessions.get(sessionId)?.dialogTurns ?? []
+);
+
 describe('runUsageReportCommand', () => {
   beforeEach(() => {
     flowChatStore.setState((): FlowChatState => ({
@@ -108,79 +121,46 @@ describe('runUsageReportCommand', () => {
       activeSessionId: 'session-1',
     }));
     sessionApiMocks.getSessionUsageReport.mockReset();
-    sessionApiMocks.saveSessionTurn.mockReset();
-    sessionApiMocks.recordLocalCommandTurn.mockReset();
-    sessionApiMocks.saveSessionTurn.mockResolvedValue(undefined);
-    sessionApiMocks.recordLocalCommandTurn.mockImplementation(
-      async (turnData: DialogTurnData) => ({
-        turnId: turnData.turnId,
-        storageTurnIndex: 0,
-        totalTurnCount: 1,
-        turnCatalog: {
-          schemaVersion: 1,
-          sessionId: turnData.sessionId,
-          revision: 'catalog-1',
-          totalTurnCount: 1,
-          complete: true,
-          entries: [{
-            ordinal: 0,
-            storageTurnIndex: 0,
-            turnId: turnData.turnId,
-            previewTruncated: false,
-          }],
-        },
-      }),
-    );
   });
 
   afterEach(() => {
+    closeSessionUsageModal();
     flowChatStore.setState((): FlowChatState => ({
       sessions: new Map(),
       activeSessionId: null,
     }));
   });
 
-  it('inserts a loading usage card immediately and replaces it with the final report', async () => {
+  it('shows the waiting state immediately and replaces it with the report', async () => {
     let resolveReport: (report: SessionUsageReport) => void = () => {};
     sessionApiMocks.getSessionUsageReport.mockReturnValue(new Promise<SessionUsageReport>(resolve => {
       resolveReport = resolve;
     }));
     const { runUsageReportCommand } = await import('./usageReportService');
 
-    const pending = runUsageReportCommand({
-      session: createSession(),
-      isProcessing: false,
-      busyMessage: 'busy',
-      noWorkspaceMessage: 'missing workspace',
-      failedTitle: 'failed',
-      unknownErrorMessage: 'unknown',
-      loadingMarkdown: 'Generating usage report...',
-    });
+    const pending = runUsageReportCommand({ session: createSession(), ...uiParams });
 
-    const loadingTurn = flowChatStore.getState().sessions.get('session-1')?.dialogTurns[0];
-    expect(loadingTurn?.userMessage.content).toBe('Generating usage report...');
-    expect(loadingTurn?.userMessage.metadata).toMatchObject({
-      localCommandKind: 'usage_report',
-      usageReportStatus: 'loading',
-      modelVisible: false,
+    // Open before the request resolves. The wait is the whole reason the report
+    // used to be inserted as a turn in two stages.
+    expect(getSessionUsageModalState()).toMatchObject({
+      open: true,
+      isLoading: true,
+      sessionId: 'session-1',
     });
+    expect(getSessionUsageModalState().report).toBeUndefined();
 
     resolveReport(usageReport());
     const result = await pending;
 
-    const finalTurn = flowChatStore.getState().sessions.get('session-1')?.dialogTurns[0];
-    expect(result.inserted).toBe(true);
-    expect(finalTurn?.id).toBe(loadingTurn?.id);
-    expect(finalTurn?.status).toBe('completed');
-    expect(finalTurn?.userMessage.content).toContain('# Session Usage Report');
-    expect(finalTurn?.userMessage.content).toContain('Session span');
-    expect(finalTurn?.userMessage.content).toContain('not reported');
-    expect(finalTurn?.userMessage.content).not.toContain('Wall time');
-    expect(finalTurn?.userMessage.content).not.toContain('Cached | unavailable');
-    expect(finalTurn?.userMessage.metadata).toMatchObject({
-      reportId: 'usage-report-1',
-      usageReportStatus: 'completed',
-    });
+    expect(result.shown).toBe(true);
+    const state = getSessionUsageModalState();
+    expect(state).toMatchObject({ open: true, isLoading: false });
+    expect(state.report?.reportId).toBe('usage-report-1');
+    expect(state.markdown).toContain('# Session Usage Report');
+    expect(state.markdown).toContain('Session span');
+    expect(state.markdown).toContain('not reported');
+    expect(state.markdown).not.toContain('Wall time');
+    expect(state.markdown).not.toContain('Cached | unavailable');
     expect(sessionApiMocks.getSessionUsageReport).toHaveBeenCalledWith({
       sessionId: 'session-1',
       workspacePath: 'D:/workspace/BitFun',
@@ -188,53 +168,51 @@ describe('runUsageReportCommand', () => {
       remoteSshHost: undefined,
       includeHiddenSubagents: true,
     });
-    expect(sessionApiMocks.recordLocalCommandTurn).toHaveBeenCalledWith(
-      expect.objectContaining({
-        turnId: finalTurn?.id,
-        turnIndex: 0,
-        kind: 'local_command',
-      }),
-      'D:/workspace/BitFun',
-      undefined,
-      undefined,
-    );
-    const persistedTurn = sessionApiMocks.recordLocalCommandTurn.mock.calls[0][0] as DialogTurnData;
-    expect(persistedTurn.userMessage.metadata).not.toHaveProperty('usageReportProvisional');
-    expect(sessionApiMocks.saveSessionTurn).not.toHaveBeenCalled();
-    expect(finalTurn?.backendTurnIndex).toBe(0);
-    expect(finalTurn?.userMessage.metadata?.usageReportProvisional).toBeUndefined();
-    expect(flowChatStore.getState().sessions.get('session-1')).toMatchObject({
-      totalTurnCount: 1,
-      turnCatalog: { totalTurnCount: 1 },
-    });
   });
 
-  it('removes the provisional report when authoritative persistence fails', async () => {
+  it('leaves the transcript alone, which is the point of it', async () => {
+    /*
+     * A report about a session is not an event in it. As a turn it grew
+     * `dialogTurns` and moved `at(-1)`, which is what follow-output reads as a
+     * Turn arriving, so a report pinned itself to the top of the viewport; and
+     * once persisted it took a numbered slot in the Turn rail.
+     */
     sessionApiMocks.getSessionUsageReport.mockResolvedValue(usageReport());
-    sessionApiMocks.recordLocalCommandTurn.mockRejectedValueOnce(new Error('record failed'));
     const { runUsageReportCommand } = await import('./usageReportService');
 
-    await expect(runUsageReportCommand({
-      session: createSession(),
-      isProcessing: false,
-      busyMessage: 'busy',
-      noWorkspaceMessage: 'missing workspace',
-      failedTitle: 'failed',
-      unknownErrorMessage: 'unknown',
-      loadingMarkdown: 'Generating usage report...',
-    })).rejects.toThrow('record failed');
-
-    expect(flowChatStore.getState().sessions.get('session-1')?.dialogTurns).toEqual([]);
+    await runUsageReportCommand({ session: createSession(), ...uiParams });
+
+    expect(transcriptOf()).toEqual([]);
+  });
+
+  it('closes the waiting state when the report cannot be produced', async () => {
+    sessionApiMocks.getSessionUsageReport.mockRejectedValueOnce(new Error('report failed'));
+    const { runUsageReportCommand } = await import('./usageReportService');
+
+    await expect(runUsageReportCommand({ session: createSession(), ...uiParams }))
+      .rejects.toThrow('report failed');
+
+    // Left open it would wait forever: no second request is coming.
+    expect(getSessionUsageModalState().open).toBe(false);
+    expect(transcriptOf()).toEqual([]);
+  });
+
+  it('does not open at all when there is no workspace to report on', async () => {
+    const { runUsageReportCommand } = await import('./usageReportService');
+
+    const result = await runUsageReportCommand({
+      session: createSession({ workspacePath: undefined }),
+      ...uiParams,
+    });
+
+    expect(result).toMatchObject({ shown: false, reason: 'missing_workspace' });
+    expect(getSessionUsageModalState().open).toBe(false);
   });
 
   it('infers legacy model rows from the session model without showing raw missing-model copy', async () => {
     const session = createSession({
       config: { agentType: 'agentic', modelName: 'gpt-5.4' },
     });
-    flowChatStore.setState((): FlowChatState => ({
-      sessions: new Map([['session-1', session]]),
-      activeSessionId: 'session-1',
-    }));
     sessionApiMocks.getSessionUsageReport.mockResolvedValue(usageReport({
       models: [{
         modelId: 'unknown_model',
@@ -250,15 +228,7 @@ describe('runUsageReportCommand', () => {
     }));
     const { runUsageReportCommand } = await import('./usageReportService');
 
-    const result = await runUsageReportCommand({
-      session,
-      isProcessing: false,
-      busyMessage: 'busy',
-      noWorkspaceMessage: 'missing workspace',
-      failedTitle: 'failed',
-      unknownErrorMessage: 'unknown',
-      loadingMarkdown: 'Generating usage report...',
-    });
+    const result = await runUsageReportCommand({ session, ...uiParams });
 
     expect(result.report?.models[0]).toMatchObject({
       modelId: 'gpt-5.4',
@@ -270,15 +240,13 @@ describe('runUsageReportCommand', () => {
     });
     expect(result.report?.slowest[0].label).not.toBe('unknown_model');
 
-    const finalTurn = flowChatStore.getState().sessions.get('session-1')?.dialogTurns[0];
-    expect(finalTurn?.userMessage.metadata?.usageReport).toMatchObject({
-      models: [expect.objectContaining({
-        modelId: 'gpt-5.4',
-        modelIdSource: 'inferred_session_model',
-      })],
+    const state = getSessionUsageModalState();
+    expect(state.report?.models[0]).toMatchObject({
+      modelId: 'gpt-5.4',
+      modelIdSource: 'inferred_session_model',
     });
-    expect(finalTurn?.userMessage.content).toContain('gpt-5.4 (inferred)');
-    expect(finalTurn?.userMessage.content).not.toContain('Model not recorded');
+    expect(state.markdown).toContain('gpt-5.4 (inferred)');
+    expect(state.markdown).not.toContain('Model not recorded');
   });
 
   it('does not infer legacy model rows from opaque session model identifiers', async () => {
@@ -291,10 +259,6 @@ describe('runUsageReportCommand', () => {
       const session = createSession({
         config: { agentType: 'agentic', modelName: opaqueModelId },
       });
-      flowChatStore.setState((): FlowChatState => ({
-        sessions: new Map([['session-1', session]]),
-        activeSessionId: 'session-1',
-      }));
       sessionApiMocks.getSessionUsageReport.mockResolvedValueOnce(usageReport({
         models: [{
           modelId: 'unknown_model',
@@ -309,15 +273,7 @@ describe('runUsageReportCommand', () => {
         }],
       }));
 
-      const result = await runUsageReportCommand({
-        session,
-        isProcessing: false,
-        busyMessage: 'busy',
-        noWorkspaceMessage: 'missing workspace',
-        failedTitle: 'failed',
-        unknownErrorMessage: 'unknown',
-        loadingMarkdown: 'Generating usage report...',
-      });
+      const result = await runUsageReportCommand({ session, ...uiParams });
 
       expect(result.report?.models[0]).toMatchObject({
         modelId: 'unknown_model',
@@ -328,10 +284,11 @@ describe('runUsageReportCommand', () => {
         modelIdSource: 'legacy_missing',
       });
 
-      const finalTurn = flowChatStore.getState().sessions.get('session-1')?.dialogTurns[0];
-      expect(finalTurn?.userMessage.content).toContain('Legacy model not tracked');
-      expect(finalTurn?.userMessage.content).not.toContain(opaqueModelId);
-      expect(finalTurn?.userMessage.content).not.toContain('(inferred)');
+      const { markdown } = getSessionUsageModalState();
+      expect(markdown).toContain('Legacy model not tracked');
+      expect(markdown).not.toContain(opaqueModelId);
+      expect(markdown).not.toContain('(inferred)');
+      closeSessionUsageModal();
     }
   });
 
@@ -339,10 +296,6 @@ describe('runUsageReportCommand', () => {
     const session = createSession({
       config: { agentType: 'agentic', modelName: '019e0c07-c7bc-73f1-b1d6-5260ed215fe0' },
     });
-    flowChatStore.setState((): FlowChatState => ({
-      sessions: new Map([['session-1', session]]),
-      activeSessionId: 'session-1',
-    }));
     sessionApiMocks.getSessionUsageReport.mockResolvedValue(usageReport({
       models: [{
         modelId: 'model round 0',
@@ -358,15 +311,7 @@ describe('runUsageReportCommand', () => {
     }));
     const { runUsageReportCommand } = await import('./usageReportService');
 
-    const result = await runUsageReportCommand({
-      session,
-      isProcessing: false,
-      busyMessage: 'busy',
-      noWorkspaceMessage: 'missing workspace',
-      failedTitle: 'failed',
-      unknownErrorMessage: 'unknown',
-      loadingMarkdown: 'Generating usage report...',
-    });
+    const result = await runUsageReportCommand({ session, ...uiParams });
 
     expect(result.report?.models[0]).toMatchObject({
       modelId: 'unknown_model',
@@ -377,8 +322,8 @@ describe('runUsageReportCommand', () => {
       modelIdSource: 'legacy_missing',
     });
 
-    const finalTurn = flowChatStore.getState().sessions.get('session-1')?.dialogTurns[0];
-    expect(finalTurn?.userMessage.content).toContain('Legacy model not tracked');
-    expect(finalTurn?.userMessage.content).not.toContain('model round');
+    const { markdown } = getSessionUsageModalState();
+    expect(markdown).toContain('Legacy model not tracked');
+    expect(markdown).not.toContain('model round');
   });
 });
diff --git a/src/web-ui/src/flow_chat/services/usageReportService.ts b/src/web-ui/src/flow_chat/services/usageReportService.ts
index fdbd6bce33..4fc2d7a273 100644
--- a/src/web-ui/src/flow_chat/services/usageReportService.ts
+++ b/src/web-ui/src/flow_chat/services/usageReportService.ts
@@ -1,9 +1,12 @@
 import { sessionAPI } from '@/infrastructure/api/service-api/SessionAPI';
 import type { SessionUsageReport } from '@/infrastructure/api/service-api/SessionAPI';
 import { notificationService } from '@/shared/notification-system';
-import type { DialogTurnData } from '@/shared/types/session-history';
-import { flowChatStore } from '../store/FlowChatStore';
-import type { DialogTurn, Session } from '../types/flow-chat';
+import {
+  closeSessionUsageModal,
+  openSessionUsageModal,
+  showSessionUsageModalReport,
+} from '../components/usage/sessionUsageModalState';
+import type { Session } from '../types/flow-chat';
 import { sessionProjectWorkspacePath } from '../utils/sessionWorkspace';
 
 const UNKNOWN_MODEL_ID = 'unknown_model';
@@ -18,54 +21,49 @@ export interface UsageReportCommandParams {
   noWorkspaceMessage: string;
   failedTitle: string;
   unknownErrorMessage: string;
-  loadingMarkdown: string;
   /**
    * Where the report comes from. Defaults to the local backend; a dispatch
    * projection supplies the target's `query` verb instead.
    */
   fetchReport?: () => Promise<SessionUsageReport>;
-  /**
-   * Persist the rendered turn to the backend session. Observer projections
-   * must not persist locally — their transcript cache captures the turn.
-   */
-  persistTurn?: boolean;
 }
 
 export interface UsageReportCommandResult {
-  inserted: boolean;
+  /** The report was produced and put on screen. */
+  shown: boolean;
   reason?: 'busy' | 'missing_workspace';
   report?: SessionUsageReport;
 }
 
+/**
+ * Produce the session usage report and show it.
+ *
+ * The report is not written into the transcript. It is a report *about* the
+ * session rather than an event in it, and the synthetic Turn it used to be read
+ * as a Turn arriving to everything downstream — see `sessionUsageModalState`.
+ */
 export async function runUsageReportCommand(
   params: UsageReportCommandParams
 ): Promise<UsageReportCommandResult> {
   if (params.isProcessing) {
     notificationService.warning(params.busyMessage);
-    return { inserted: false, reason: 'busy' };
+    return { shown: false, reason: 'busy' };
   }
 
   if (!params.session.workspacePath) {
     notificationService.error(params.noWorkspaceMessage);
-    return { inserted: false, reason: 'missing_workspace' };
+    return { shown: false, reason: 'missing_workspace' };
   }
 
-  const requestedAt = Date.now();
   const projectWorkspacePath = sessionProjectWorkspacePath(params.session);
   if (!projectWorkspacePath) {
     notificationService.error(params.noWorkspaceMessage);
-    return { inserted: false, reason: 'missing_workspace' };
+    return { shown: false, reason: 'missing_workspace' };
   }
-  const pendingReportId = `pending-${params.session.sessionId}-${requestedAt}`;
-  const pendingTurn = flowChatStore.addLocalUsageReportTurn({
+  openSessionUsageModal({
     sessionId: params.session.sessionId,
-    markdown: params.loadingMarkdown,
-    reportId: pendingReportId,
-    schemaVersion: 1,
-    generatedAt: requestedAt,
-    status: 'loading',
+    workspacePath: params.session.workspacePath,
   });
-  let provisionalTurnId = pendingTurn?.id;
 
   try {
     const rawReport = params.fetchReport
@@ -78,45 +76,15 @@ export async function runUsageReportCommand(
         includeHiddenSubagents: true,
       });
     const report = enrichUsageReportModelIdentity(rawReport, params.session);
-    const markdown = renderUsageReportMarkdown(report);
-    const turn = pendingTurn
-      ? updatePendingUsageReportTurn({
-        sessionId: params.session.sessionId,
-        dialogTurnId: pendingTurn.id,
-        markdown,
-        report,
-      })
-      : flowChatStore.addLocalUsageReportTurn({
-        sessionId: params.session.sessionId,
-        markdown,
-        reportId: report.reportId,
-        schemaVersion: report.schemaVersion,
-        generatedAt: report.generatedAt,
-        report: report as unknown as Record<string, any>,
-      });
-    provisionalTurnId = turn?.id ?? provisionalTurnId;
-
-    if (turn && params.persistTurn !== false) {
-      const recorded = await sessionAPI.recordLocalCommandTurn(
-        toPersistedLocalReportTurn(turn),
-        projectWorkspacePath,
-        params.session.remoteConnectionId,
-        params.session.remoteSshHost,
-      );
-      if (!flowChatStore.commitLocalUsageReportTurn({
-        sessionId: params.session.sessionId,
-        dialogTurnId: turn.id,
-        ...recorded,
-      })) {
-        throw new Error('Failed to reconcile persisted usage report turn');
-      }
-    }
+    showSessionUsageModalReport({
+      sessionId: params.session.sessionId,
+      report,
+      markdown: renderUsageReportMarkdown(report),
+    });
 
-    return { inserted: !!turn, report };
+    return { shown: true, report };
   } catch (error) {
-    if (provisionalTurnId) {
-      flowChatStore.deleteDialogTurn(params.session.sessionId, provisionalTurnId);
-    }
+    closeSessionUsageModal();
     notificationService.error(
       error instanceof Error ? error.message : params.unknownErrorMessage,
       {
@@ -158,42 +126,6 @@ export function enrichUsageReportModelIdentity(
   };
 }
 
-function updatePendingUsageReportTurn(params: {
-  sessionId: string;
-  dialogTurnId: string;
-  markdown: string;
-  report: SessionUsageReport;
-}): DialogTurn | null {
-  flowChatStore.updateDialogTurn(
-    params.sessionId,
-    params.dialogTurnId,
-    turn => ({
-      ...turn,
-      status: 'completed',
-      userMessage: {
-        ...turn.userMessage,
-        content: params.markdown,
-        timestamp: params.report.generatedAt,
-        metadata: {
-          ...turn.userMessage.metadata,
-          reportId: params.report.reportId,
-          schemaVersion: params.report.schemaVersion,
-          generatedAt: params.report.generatedAt,
-          usageReportStatus: 'completed',
-          usageReport: params.report as unknown as Record<string, any>,
-        },
-      },
-      startTime: params.report.generatedAt,
-      endTime: params.report.generatedAt,
-    }),
-    { touchActivity: false },
-  );
-
-  return flowChatStore.getState().sessions
-    .get(params.sessionId)
-    ?.dialogTurns.find(turn => turn.id === params.dialogTurnId) ?? null;
-}
-
 export function renderUsageReportMarkdown(report: SessionUsageReport): string {
   const lines: string[] = [
     '# Session Usage Report',
@@ -298,30 +230,6 @@ export function renderUsageReportMarkdown(report: SessionUsageReport): string {
   return lines.join('\n');
 }
 
-function toPersistedLocalReportTurn(turn: DialogTurn): DialogTurnData {
-  const metadata = { ...turn.userMessage.metadata };
-  delete metadata.usageReportProvisional;
-  return {
-    turnId: turn.id,
-    // Local commands receive their storage identity only after persistence.
-    turnIndex: 0,
-    sessionId: turn.sessionId,
-    timestamp: turn.startTime,
-    kind: 'local_command',
-    userMessage: {
-      id: turn.userMessage.id,
-      content: turn.userMessage.content,
-      timestamp: turn.userMessage.timestamp,
-      metadata,
-    },
-    modelRounds: [],
-    startTime: turn.startTime,
-    endTime: turn.endTime,
-    durationMs: 0,
-    status: 'completed',
-  };
-}
-
 function formatNumber(value: number | undefined): string {
   return value === undefined ? 'unavailable' : String(value);
 }
diff --git a/src/web-ui/src/flow_chat/session-drivers/dispatch/DispatchSessionDriver.ts b/src/web-ui/src/flow_chat/session-drivers/dispatch/DispatchSessionDriver.ts
index 86e8457976..842078ea47 100644
--- a/src/web-ui/src/flow_chat/session-drivers/dispatch/DispatchSessionDriver.ts
+++ b/src/web-ui/src/flow_chat/session-drivers/dispatch/DispatchSessionDriver.ts
@@ -10,7 +10,6 @@
  */
 
 import { createLogger } from '@/shared/utils/logger';
-import { globalEventBus } from '@/infrastructure/event-bus';
 import { i18nService } from '@/infrastructure/i18n';
 import type {
   PermissionReplyKind,
@@ -32,10 +31,6 @@ import type {
   TurnTracker,
   UsageReportUiParams,
 } from '../types';
-import {
-  FLOWCHAT_PIN_TURN_TO_TOP_EVENT,
-  type FlowChatPinTurnToTopRequest,
-} from '../../events/flowchatNavigation';
 import {
   isDispatchJobTerminal,
   isNonLocalDispatchTarget,
@@ -117,25 +112,12 @@ function dispatchAttachments(
   return attachments;
 }
 
-function pinTurnToTop(sessionId: string, turnId: string): void {
-  globalEventBus.emit(
-    FLOWCHAT_PIN_TURN_TO_TOP_EVENT,
-    {
-      sessionId,
-      turnId,
-      behavior: 'auto',
-      source: 'send-message',
-      pinMode: 'sticky-latest',
-    } satisfies FlowChatPinTurnToTopRequest,
-    'DispatchSessionDriver',
-  );
-}
-
 async function appendToDispatchJob(
   sessionId: string,
   jobId: string,
   message: string,
   displayMessage: string | undefined,
+  attachments?: import('@/features/dispatch/dispatchApi').DispatchInlineAttachment[],
 ): Promise<void> {
   // Keep the id stable across an ambiguous transport failure. A retry with
   // the same message can then ask the target mailbox for the same idempotent
@@ -154,6 +136,7 @@ async function appendToDispatchJob(
     message,
     displayMessage,
     retry.id,
+    attachments,
   );
   if (!response.accepted) {
     releaseSubmissionRetry(APPEND_RETRY_SCOPE, sessionId, retry.id);
@@ -228,7 +211,6 @@ async function continueDispatchJob(
     status: 'pending',
     startTime: Date.now(),
   });
-  pinTurnToTop(sessionId, optimisticTurnId);
 
   try {
     const response = await dispatchApi.continueJob(
@@ -318,6 +300,7 @@ export const dispatchSessionDriver: SessionDriver = {
 
   async createSession(context: FlowChatContext, seed: SessionCreationSeed): Promise<string> {
     const {
+      surfaceScope,
       config,
       agentType,
       sessionName,
@@ -328,6 +311,7 @@ export const dispatchSessionDriver: SessionDriver = {
       remoteConnectionId,
       remoteSshHost,
     } = seed;
+    surfaceScope.assertCurrent('start dispatch session creation');
 
     if (!isNonLocalDispatchTarget(config.dispatchTargetRequest)) {
       throw new Error(
@@ -379,6 +363,7 @@ export const dispatchSessionDriver: SessionDriver = {
 
     // This is an observer projection only. In particular, do not call
     // agentAPI.createSession: the target CLI owns the durable session.
+    surfaceScope.assertCurrent('create dispatch session projection');
     context.flowChatStore.createSession(
       sessionId,
       resolvedConfig,
@@ -540,7 +525,7 @@ export const dispatchSessionDriver: SessionDriver = {
     context: FlowChatContext,
     sessionId: string,
     uiParams: UsageReportUiParams,
-  ): Promise<{ inserted: boolean }> {
+  ): Promise<{ shown: boolean }> {
     const session = context.flowChatStore.getState().sessions.get(sessionId);
     if (!session) {
       throw new Error(
@@ -557,16 +542,14 @@ export const dispatchSessionDriver: SessionDriver = {
     const result = await runUsageReportCommand({
       session,
       ...uiParams,
-      // The target computes the report from its persisted session; the
-      // rendered turn stays in the projection (transcript cache), never in
-      // local session persistence.
+      // The target computes the report from its persisted session; nothing is
+      // written back, here or there.
       fetchReport: async () => {
         const response = await dispatchApi.query(jobId, 'usageReport');
         return response.report as SessionUsageReport;
       },
-      persistTurn: false,
     });
-    return { inserted: result.inserted };
+    return { shown: result.shown };
   },
 
   permissionRequestSource(sessionId: string) {
@@ -629,11 +612,7 @@ export const dispatchSessionDriver: SessionDriver = {
     return [];
   },
 
-  planSubmission(
-    context: FlowChatContext,
-    sessionId: string,
-    draft: SubmissionDraft,
-  ): SubmissionPlan {
+  planSubmission(context: FlowChatContext, sessionId: string): SubmissionPlan {
     const session = context.flowChatStore.getState().sessions.get(sessionId);
     if (
       !isNonLocalDispatchTarget(session?.config.dispatchTarget)
@@ -645,16 +624,6 @@ export const dispatchSessionDriver: SessionDriver = {
     ) {
       return { kind: 'queue' };
     }
-    if (draft.hasImages) {
-      // Steering has no attachment channel; the runtime accepts images only
-      // at turn boundaries.
-      return {
-        kind: 'reject',
-        reason: i18nService.t(
-          'flow-chat:chatInput.dispatch.errors.imagesWhileRunning',
-        ),
-      };
-    }
     return { kind: 'steer' };
   },
 
@@ -670,7 +639,13 @@ export const dispatchSessionDriver: SessionDriver = {
         i18nService.t('flow-chat:chatInput.dispatch.errors.sessionUnavailable'),
       );
     }
-    await appendToDispatchJob(sessionId, jobId, draft.message, draft.displayMessage);
+    await appendToDispatchJob(
+      sessionId,
+      jobId,
+      draft.message,
+      draft.displayMessage,
+      dispatchAttachments(session, draft.imageContexts),
+    );
   },
 
   async startTurn(
@@ -698,15 +673,15 @@ export const dispatchSessionDriver: SessionDriver = {
     }
     const dispatchState = readySession.config.dispatchJobState;
     if (dispatchState === 'queued' || dispatchState === 'running') {
-      if ((options?.imageContexts?.length ?? 0) > 0) {
-        // Steering has no attachment channel; images ride turn boundaries.
-        throw new Error(
-          i18nService.t('flow-chat:chatInput.dispatch.errors.imagesWhileRunning'),
-        );
-      }
       // A turn is already in flight; this message steers it rather than
-      // starting another one underneath it.
-      await appendToDispatchJob(sessionId, jobId, message, displayMessage);
+      // starting another one underneath it. Attachments ride along.
+      await appendToDispatchJob(
+        sessionId,
+        jobId,
+        message,
+        displayMessage,
+        dispatchAttachments(readySession, options?.imageContexts),
+      );
       return 'detached';
     }
     if (dispatchState && isDispatchJobTerminal(dispatchState)) {
@@ -751,7 +726,6 @@ export const dispatchSessionDriver: SessionDriver = {
     };
     context.flowChatStore.addDialogTurn(sessionId, optimisticTurn);
     tracker.createdLocalTurnId = optimisticTurnId;
-    pinTurnToTop(sessionId, optimisticTurnId);
 
     const includeUncommitted = readySession.config.dispatchIncludeUncommitted ?? false;
     const baseRef = readySession.config.dispatchBaseRef?.trim() || 'HEAD';
@@ -797,6 +771,7 @@ export const dispatchSessionDriver: SessionDriver = {
         i18nService.t('flow-chat:chatInput.dispatch.errors.submissionUnconfirmed'),
       );
     }
+    tracker.hostAcceptedTurn = true;
     context.flowChatStore.applyDispatchSnapshot(sessionId, {
       jobId,
       state: response.state,
diff --git a/src/web-ui/src/flow_chat/session-drivers/local/LocalSessionDriver.test.ts b/src/web-ui/src/flow_chat/session-drivers/local/LocalSessionDriver.test.ts
new file mode 100644
index 0000000000..77f706ce82
--- /dev/null
+++ b/src/web-ui/src/flow_chat/session-drivers/local/LocalSessionDriver.test.ts
@@ -0,0 +1,145 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { localSessionDriver } from './LocalSessionDriver';
+import type { DialogTurn } from '../../types/flow-chat';
+import { getActiveSurfaceScope } from '@/infrastructure/peer-device/deviceSurface';
+
+const { mockStartAcpDialogTurn, mockStartAgenticDialogTurn, mockTransition } = vi.hoisted(() => ({
+  mockStartAcpDialogTurn: vi.fn(),
+  mockStartAgenticDialogTurn: vi.fn(),
+  mockTransition: vi.fn(),
+}));
+
+vi.mock('@/infrastructure/api/service-api/ACPClientAPI', () => ({
+  ACPClientAPI: { startDialogTurn: mockStartAcpDialogTurn },
+}));
+
+vi.mock('@/infrastructure/api/service-api/AgentAPI', () => ({
+  agentAPI: { startDialogTurn: mockStartAgenticDialogTurn },
+}));
+
+vi.mock('@/infrastructure/api/service-api/SessionAPI', () => ({ sessionAPI: {} }));
+vi.mock('@/infrastructure/api/service-api/WorktreeAPI', () => ({ worktreeAPI: {} }));
+
+vi.mock('../../state-machine', () => ({
+  stateMachineManager: {
+    transition: mockTransition,
+    getCurrentState: () => 'idle',
+    get: () => undefined,
+  },
+}));
+
+vi.mock('../shared', () => ({ applyGeneratingTitlePlaceholder: vi.fn() }));
+
+vi.mock('../../utils/modelSync', () => ({ syncSessionModelSelection: vi.fn() }));
+
+const SESSION_ID = 'acp_dsh_session';
+const WORKSPACE_PATH = '/Users/user/workspace/project';
+
+function persistedTurn(id: string, storageTurnIndex: number): DialogTurn {
+  return {
+    id,
+    sessionId: SESSION_ID,
+    userMessage: { id: `user-${id}`, content: 'earlier', timestamp: 1 },
+    modelRounds: [],
+    status: 'completed',
+    startTime: 1,
+    storageTurnIndex,
+  };
+}
+
+function createHarness(existingTurns: DialogTurn[]) {
+  const session: any = {
+    sessionId: SESSION_ID,
+    dialogTurns: [...existingTurns],
+    workspacePath: WORKSPACE_PATH,
+    config: {},
+    mode: 'acp:dsh',
+  };
+  const addedTurns: DialogTurn[] = [];
+
+  const context: any = {
+    flowChatStore: {
+      getState: () => ({ sessions: new Map([[SESSION_ID, session]]) }),
+      addDialogTurn: (_sessionId: string, turn: DialogTurn) => {
+        addedTurns.push(turn);
+        session.dialogTurns = [...session.dialogTurns, turn];
+      },
+      deleteDialogTurn: vi.fn(),
+      updateSessionLastSubmittedMode: vi.fn(),
+      setSessionWorktreeIsolationRequested: vi.fn(),
+    },
+    processingManager: {
+      registerStatus: vi.fn(),
+      clearSessionStatus: vi.fn(),
+    },
+    pendingHistoryLoads: new Set<string>(),
+    contentBuffers: new Map(),
+    activeTextItems: new Map(),
+  };
+
+  return { context, session, addedTurns };
+}
+
+function startTurnInput(session: any) {
+  return {
+    surfaceScope: getActiveSurfaceScope(),
+    sessionId: SESSION_ID,
+    message: 'hello',
+    displayMessage: 'hello',
+    currentAgentType: 'acp:dsh',
+    acpClientId: 'dsh',
+    isFirstMessage: session.dialogTurns.length === 0,
+    readySession: session,
+    options: undefined,
+  } as any;
+}
+
+describe('localSessionDriver.startTurn on an ACP session', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockTransition.mockResolvedValue(true);
+    mockStartAcpDialogTurn.mockResolvedValue(undefined);
+  });
+
+  it('gives the first turn a storage slot so it can be persisted', async () => {
+    const { context, session, addedTurns } = createHarness([]);
+
+    await localSessionDriver.startTurn(context, startTurnInput(session), {
+      createdLocalTurnId: null,
+      hostAcceptedTurn: false,
+    });
+
+    expect(mockStartAcpDialogTurn).toHaveBeenCalledTimes(1);
+    expect(addedTurns).toHaveLength(1);
+    expect(addedTurns[0].storageTurnIndex).toBe(0);
+  });
+
+  it('continues after the turns already on disk when the session is resumed', async () => {
+    const { context, session, addedTurns } = createHarness([
+      persistedTurn('a', 0),
+      persistedTurn('b', 1),
+    ]);
+
+    await localSessionDriver.startTurn(context, startTurnInput(session), {
+      createdLocalTurnId: null,
+      hostAcceptedTurn: false,
+    });
+
+    expect(addedTurns[0].storageTurnIndex).toBe(2);
+  });
+
+  it('leaves the slot to the runtime for a non-ACP turn', async () => {
+    const { context, session, addedTurns } = createHarness([]);
+    mockStartAgenticDialogTurn.mockResolvedValue(undefined);
+
+    await localSessionDriver.startTurn(
+      context,
+      { ...startTurnInput(session), acpClientId: undefined, currentAgentType: 'agentic' },
+      { createdLocalTurnId: null, hostAcceptedTurn: false },
+    );
+
+    expect(mockStartAgenticDialogTurn).toHaveBeenCalledTimes(1);
+    expect(addedTurns[0].storageTurnIndex).toBeUndefined();
+  });
+});
diff --git a/src/web-ui/src/flow_chat/session-drivers/local/LocalSessionDriver.ts b/src/web-ui/src/flow_chat/session-drivers/local/LocalSessionDriver.ts
index a9dfe3858d..ba0ed33bce 100644
--- a/src/web-ui/src/flow_chat/session-drivers/local/LocalSessionDriver.ts
+++ b/src/web-ui/src/flow_chat/session-drivers/local/LocalSessionDriver.ts
@@ -12,7 +12,6 @@ import { agentAPI } from '@/infrastructure/api/service-api/AgentAPI';
 import { ACPClientAPI } from '@/infrastructure/api/service-api/ACPClientAPI';
 import { sessionAPI } from '@/infrastructure/api/service-api/SessionAPI';
 import { worktreeAPI } from '@/infrastructure/api/service-api/WorktreeAPI';
-import { globalEventBus } from '@/infrastructure/event-bus';
 import { createLogger } from '@/shared/utils/logger';
 import { stateMachineManager } from '../../state-machine';
 import { SessionExecutionEvent, SessionExecutionState } from '../../state-machine/types';
@@ -27,15 +26,12 @@ import type {
   TurnTracker,
   UsageReportUiParams,
 } from '../types';
-import {
-  FLOWCHAT_PIN_TURN_TO_TOP_EVENT,
-  type FlowChatPinTurnToTopRequest,
-} from '../../events/flowchatNavigation';
 import {
   getModelMaxTokens,
   resolveReasoningPresetForSessionCreation,
 } from '../../utils/modelResolution';
 import { syncSessionModelSelection } from '../../utils/modelSync';
+import { nextStorageTurnIndex } from '../../utils/flowChatTurnIdentity';
 import { markCurrentTurnItemsAsCancelled } from '../../utils/turnCancellation';
 import {
   requireSessionProjectWorkspacePath,
@@ -53,6 +49,7 @@ export const localSessionDriver: SessionDriver = {
 
   async createSession(context: FlowChatContext, seed: SessionCreationSeed): Promise<string> {
     const {
+      surfaceScope,
       config,
       agentType,
       sessionName,
@@ -63,12 +60,14 @@ export const localSessionDriver: SessionDriver = {
       remoteConnectionId,
       remoteSshHost,
     } = seed;
+    surfaceScope.assertCurrent('start local session creation');
 
     const explicitModelName = config.modelName?.trim() || undefined;
     const reasoningPreset = config.reasoningPreset
       ?? (explicitModelName
         ? await resolveReasoningPresetForSessionCreation(explicitModelName)
         : undefined);
+    surfaceScope.assertCurrent('resolve session creation reasoning preset');
 
     const response = await agentAPI.createSession({
       sessionName,
@@ -91,9 +90,11 @@ export const localSessionDriver: SessionDriver = {
         remoteSshHost,
       }
     });
+    surfaceScope.assertCurrent('create local backend session');
 
     const sessionModelName = response.modelId ?? explicitModelName;
     const maxContextTokens = await getModelMaxTokens(sessionModelName, agentType);
+    surfaceScope.assertCurrent('resolve created session model');
     const mergedConfig: SessionConfig = {
       ...config,
       modelName: sessionModelName,
@@ -210,17 +211,28 @@ export const localSessionDriver: SessionDriver = {
 
   async cancel(context: FlowChatContext, sessionId: string): Promise<boolean> {
     const currentState = stateMachineManager.getCurrentState(sessionId);
-    const success = currentState === SessionExecutionState.PROCESSING
-      ? await stateMachineManager.transition(sessionId, SessionExecutionEvent.USER_CANCEL)
-      : false;
+    if (currentState !== SessionExecutionState.PROCESSING) {
+      return false;
+    }
+    // Gate pending-queue auto-drain before the asynchronous interrupt RPC can
+    // race an Idle/terminal event back to the UI.
+    context.userCancelledSessionIds.add(sessionId);
+    const success = await stateMachineManager.transition(
+      sessionId,
+      SessionExecutionEvent.USER_CANCEL,
+    );
+    const settledInFinishing = success
+      && stateMachineManager.getCurrentState(sessionId) === SessionExecutionState.FINISHING;
+    if (!settledInFinishing) {
+      context.userCancelledSessionIds.delete(sessionId);
+    }
 
-    if (success) {
-      context.userCancelledSessionIds.add(sessionId);
+    if (settledInFinishing) {
       markCurrentTurnItemsAsCancelled(context, sessionId);
       cleanupSessionBuffers(context, sessionId);
     }
 
-    return success;
+    return settledInFinishing;
   },
 
   planSubmission(): SubmissionPlan {
@@ -246,14 +258,14 @@ export const localSessionDriver: SessionDriver = {
     context: FlowChatContext,
     sessionId: string,
     uiParams: UsageReportUiParams,
-  ): Promise<{ inserted: boolean }> {
+  ): Promise<{ shown: boolean }> {
     const session = context.flowChatStore.getState().sessions.get(sessionId);
     if (!session) {
       throw new Error(`Session does not exist: ${sessionId}`);
     }
     const { runUsageReportCommand } = await import('../../services/usageReportService');
     const result = await runUsageReportCommand({ session, ...uiParams });
-    return { inserted: result.inserted };
+    return { shown: result.shown };
   },
 
   permissionRequestSource(): 'live' {
@@ -288,6 +300,7 @@ export const localSessionDriver: SessionDriver = {
     tracker: TurnTracker,
   ): Promise<StartTurnResult> {
     const {
+      surfaceScope,
       sessionId,
       message,
       displayMessage,
@@ -302,6 +315,20 @@ export const localSessionDriver: SessionDriver = {
       `dialog_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
     const hasImages = (options?.imageContexts?.length ?? 0) > 0;
 
+    // An ACP agent runs outside the local runtime, so no backend
+    // DialogTurnStarted arrives with a storage slot for this Turn. Without one
+    // every save of the Turn is deferred and the Session never reaches disk, so
+    // the projection — the only writer of these Turns — allocates it here.
+    const acpStorageTurnIndex = acpClientId
+      ? nextStorageTurnIndex(readySession)
+      : undefined;
+    if (acpClientId && acpStorageTurnIndex === undefined) {
+      log.warn('ACP turn starts without a storage slot; its saves stay deferred', {
+        sessionId,
+        dialogTurnId,
+      });
+    }
+
     const dialogTurn: DialogTurn = {
       id: dialogTurnId,
       sessionId: sessionId,
@@ -318,22 +345,17 @@ export const localSessionDriver: SessionDriver = {
       // Images are attached for multimodal primary models or reduced to text placeholders for text-only models.
       // We don't run a separate frontend "image pre-analysis" phase here.
       status: 'pending',
-      startTime: Date.now()
+      startTime: Date.now(),
+      storageTurnIndex: acpStorageTurnIndex,
     };
 
     context.flowChatStore.addDialogTurn(sessionId, dialogTurn);
     tracker.createdLocalTurnId = dialogTurnId;
-    const pinRequest: FlowChatPinTurnToTopRequest = {
-      sessionId,
-      turnId: dialogTurnId,
-      behavior: 'auto',
-      source: 'send-message',
-      pinMode: 'sticky-latest',
-    };
-    globalEventBus.emit(FLOWCHAT_PIN_TURN_TO_TOP_EVENT, pinRequest, 'MessageModule');
-
     const isRestoringHistoricalSession =
-      readySession.isHistorical || context.pendingHistoryLoads.has(sessionId);
+      readySession.isHistorical
+      || context.pendingHistoryLoads.has(
+        surfaceScope.key('history-load', surfaceScope.epoch, sessionId),
+      );
     if (isRestoringHistoricalSession) {
       context.processingManager.clearSessionStatus(sessionId);
       context.flowChatStore.deleteDialogTurn(sessionId, dialogTurnId);
@@ -344,6 +366,7 @@ export const localSessionDriver: SessionDriver = {
       taskId: sessionId,
       dialogTurnId,
     });
+    surfaceScope.assertCurrent('start session state machine');
     if (!startOk) {
       const currentState = stateMachineManager.getCurrentState(sessionId);
       throw new Error(`Session is still busy finishing the previous turn (current state: ${currentState})`);
@@ -370,6 +393,7 @@ export const localSessionDriver: SessionDriver = {
           globalThis.crypto?.randomUUID?.() ?? `worktree-first-turn-${Date.now()}`,
           materialization.projectWorkspacePath,
         );
+        surfaceScope.assertCurrent('bind session worktree');
         context.flowChatStore.updateSessionExecutionTarget(sessionId, {
           workspacePath: result.workspacePath,
           projectWorkspacePath: result.projectWorkspacePath,
@@ -391,7 +415,7 @@ export const localSessionDriver: SessionDriver = {
     }
 
     if (!acpClientId) {
-      await syncSessionModelSelection(context, sessionId, currentAgentType);
+      await syncSessionModelSelection(context, sessionId, currentAgentType, surfaceScope);
     }
 
     const updatedSession = context.flowChatStore.getState().sessions.get(sessionId);
@@ -418,6 +442,8 @@ export const localSessionDriver: SessionDriver = {
         remoteConnectionId: updatedSession.remoteConnectionId,
         remoteSshHost: updatedSession.remoteSshHost,
       });
+      tracker.hostAcceptedTurn = true;
+      surfaceScope.assertCurrent('start ACP dialog turn');
       context.flowChatStore.updateSessionLastSubmittedMode(sessionId, currentAgentType);
     } else {
       try {
@@ -435,6 +461,8 @@ export const localSessionDriver: SessionDriver = {
           userMessageMetadata: options?.userMessageMetadata,
           execution: options?.execution,
         });
+        tracker.hostAcceptedTurn = true;
+        surfaceScope.assertCurrent('start dialog turn');
         context.flowChatStore.updateSessionLastSubmittedMode(sessionId, currentAgentType);
       } catch (error: any) {
         if (error?.message?.includes('Session does not exist') || error?.message?.includes('Not found')) {
@@ -447,7 +475,9 @@ export const localSessionDriver: SessionDriver = {
           // driver registry, so a static import would create a module cycle.
           const { retryCreateBackendSession } =
             await import('../../services/flow-chat-manager/SessionModule');
+          surfaceScope.assertCurrent('load backend session retry');
           await retryCreateBackendSession(context, sessionId);
+          surfaceScope.assertCurrent('retry backend session creation');
 
           await agentAPI.startDialogTurn({
             sessionId: sessionId,
@@ -463,6 +493,8 @@ export const localSessionDriver: SessionDriver = {
             userMessageMetadata: options?.userMessageMetadata,
             execution: options?.execution,
           });
+          tracker.hostAcceptedTurn = true;
+          surfaceScope.assertCurrent('retry dialog turn submission');
           context.flowChatStore.updateSessionLastSubmittedMode(sessionId, currentAgentType);
         } else {
           throw error;
diff --git a/src/web-ui/src/flow_chat/session-drivers/types.ts b/src/web-ui/src/flow_chat/session-drivers/types.ts
index 9854d83be9..35bd9fdd57 100644
--- a/src/web-ui/src/flow_chat/session-drivers/types.ts
+++ b/src/web-ui/src/flow_chat/session-drivers/types.ts
@@ -18,6 +18,7 @@ import type { Session } from '../types/flow-chat';
 import type { SessionTitleDescriptor } from '../utils/sessionTitle';
 import type { ImageContextData as ImageInputContextData } from '@/infrastructure/api/service-api/ImageContextTypes';
 import type { SessionDriverId } from './resolve';
+import type { SurfaceScope } from '@/infrastructure/peer-device/deviceSurface';
 
 export type { SessionDriverId } from './resolve';
 
@@ -44,13 +45,20 @@ export interface SendMessageOptions {
   onSessionConflictRetryStart?: () => void;
   onSessionConflictRetrySuccess?: () => void;
   fromSessionConflictRetry?: boolean;
+  /** Identifies the edit-rerun mutation lease allowed to submit this Turn. */
+  sessionMutationLeaseId?: string;
 }
 
 /** The message content of one submission, before flavor routing. */
 export interface SubmissionDraft {
   message: string;
   displayMessage?: string;
-  hasImages: boolean;
+  /**
+   * Composer image contexts for this submission. Steering carries them just
+   * like a turn submission does, so a message with attachments does not have
+   * to wait for a turn boundary.
+   */
+  imageContexts?: ImageInputContextData[];
 }
 
 /**
@@ -64,6 +72,8 @@ export type SubmissionPlan =
   | { kind: 'reject'; reason: string };
 
 export interface StartTurnInput {
+  /** Device activation that owns every projection write in this submission. */
+  surfaceScope: SurfaceScope;
   sessionId: string;
   message: string;
   displayMessage?: string;
@@ -83,6 +93,12 @@ export interface StartTurnInput {
  */
 export interface TurnTracker {
   createdLocalTurnId: string | null;
+  /**
+   * Set once a host has accepted the turn. Until then the turn exists only as a
+   * local projection, so a submission interrupted by a device-surface switch
+   * must recover the message rather than assume it is running somewhere.
+   */
+  hostAcceptedTurn: boolean;
 }
 
 /**
@@ -99,7 +115,6 @@ export interface UsageReportUiParams {
   noWorkspaceMessage: string;
   failedTitle: string;
   unknownErrorMessage: string;
-  loadingMarkdown: string;
 }
 
 /**
@@ -130,6 +145,8 @@ export type PermissionReplyKindLike = 'once' | 'always' | 'reject';
  * driver takes over: workspace identity, agent type, and the initial title.
  */
 export interface SessionCreationSeed {
+  /** Device activation that owns the created session projection. */
+  surfaceScope: SurfaceScope;
   config: SessionConfig;
   agentType: string;
   sessionName: string;
@@ -223,15 +240,15 @@ export interface SessionDriver {
   compactSession(context: FlowChatContext, sessionId: string): Promise<void>;
 
   /**
-   * Generate and insert the session usage report turn. `uiParams` carries the
-   * caller's localized strings; the driver decides where the report data
-   * comes from and whether the rendered turn persists.
+   * Produce the session usage report and show it. `uiParams` carries the
+   * caller's localized strings; the driver decides where the report data comes
+   * from. The report is not written into the transcript.
    */
   runUsageReport(
     context: FlowChatContext,
     sessionId: string,
     uiParams: UsageReportUiParams,
-  ): Promise<{ inserted: boolean }>;
+  ): Promise<{ shown: boolean }>;
 
   /** How pending permission requests for this session are obtained. */
   permissionRequestSource(sessionId: string): PermissionRequestSource;
diff --git a/src/web-ui/src/flow_chat/state-machine/SessionStateMachine.test.ts b/src/web-ui/src/flow_chat/state-machine/SessionStateMachine.test.ts
new file mode 100644
index 0000000000..02366a0522
--- /dev/null
+++ b/src/web-ui/src/flow_chat/state-machine/SessionStateMachine.test.ts
@@ -0,0 +1,52 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { SessionStateMachineImpl } from './SessionStateMachine';
+import { SessionExecutionEvent } from './types';
+
+const cancelSessionTask = vi.fn();
+const interruptDialogTurn = vi.fn();
+
+vi.mock('@/flow_chat/store/FlowChatStore', () => ({
+  flowChatStore: {
+    cancelSessionTask,
+    getState: () => ({
+      sessions: new Map([['session-1', {
+        sessionId: 'session-1',
+        sessionKind: 'normal',
+        mode: 'agentic',
+        config: { agentType: 'agentic' },
+      }]]),
+    }),
+  },
+}));
+
+vi.mock('@/infrastructure/api/service-api/AgentAPI', () => ({
+  agentAPI: {
+    interruptDialogTurn,
+    cancelDialogTurn: vi.fn(),
+  },
+}));
+
+vi.mock('@/infrastructure/peer-device/peerModeFlag', () => ({
+  isPeerDeviceModeActive: () => false,
+}));
+
+describe('SessionStateMachine recoverable interruption', () => {
+  beforeEach(() => {
+    cancelSessionTask.mockReset();
+    interruptDialogTurn.mockReset();
+    interruptDialogTurn.mockResolvedValue(undefined);
+  });
+
+  it('does not run the legacy optimistic turn persistence before Runtime interruption', async () => {
+    const machine = new SessionStateMachineImpl('session-1');
+    await machine.transition(SessionExecutionEvent.START, {
+      taskId: 'session-1',
+      dialogTurnId: 'turn-1',
+    });
+
+    await machine.transition(SessionExecutionEvent.USER_CANCEL);
+
+    expect(interruptDialogTurn).toHaveBeenCalledWith('session-1', 'turn-1');
+    expect(cancelSessionTask).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/web-ui/src/flow_chat/state-machine/SessionStateMachine.ts b/src/web-ui/src/flow_chat/state-machine/SessionStateMachine.ts
index 897a0849c8..a66d616c1c 100644
--- a/src/web-ui/src/flow_chat/state-machine/SessionStateMachine.ts
+++ b/src/web-ui/src/flow_chat/state-machine/SessionStateMachine.ts
@@ -261,8 +261,6 @@ export class SessionStateMachineImpl {
 
     if (event === SessionExecutionEvent.USER_CANCEL && this.context.taskId && this.context.currentDialogTurnId) {
       const { flowChatStore } = await import('@/flow_chat/store/FlowChatStore');
-      flowChatStore.cancelSessionTask(this.sessionId);
-
       const sessionId = this.context.taskId;
       const dialogTurnId = this.context.currentDialogTurnId;
       const { acpClientIdFromAgentType } = await import('@/flow_chat/utils/acpSession');
@@ -283,11 +281,37 @@ export class SessionStateMachineImpl {
           });
         } else {
           const { agentAPI } = await import('@/infrastructure/api/service-api/AgentAPI');
-          await agentAPI.cancelDialogTurn(sessionId, dialogTurnId);
+          const { isPeerDeviceModeActive } = await import(
+            '@/infrastructure/peer-device/peerModeFlag'
+          );
+          const goalStatus = session?.threadGoal?.status?.toLowerCase();
+          const supportsRecoverableInterruption =
+            session?.sessionKind === 'normal'
+            && !session.remoteConnectionId
+            && !session.remoteSshHost
+            && !session.config?.remoteConnectionId
+            && !session.config?.remoteSshHost
+            && !session.config?.dispatchTarget
+            && !session.config?.dispatchJobId
+            && goalStatus !== 'active'
+            && goalStatus !== 'paused'
+            && !isPeerDeviceModeActive();
+          if (supportsRecoverableInterruption) {
+            await agentAPI.interruptDialogTurn(sessionId, dialogTurnId);
+          } else {
+            await agentAPI.cancelDialogTurn(sessionId, dialogTurnId);
+          }
         }
-        log.debug('Backend cancellation completed', { sessionId, dialogTurnId, acpClientId });
+        log.debug('Backend interruption completed', { sessionId, dialogTurnId, acpClientId });
       } catch (error) {
         log.error('Backend cancellation failed', { sessionId, dialogTurnId, acpClientId, error });
+        await this.transition(SessionExecutionEvent.USER_CANCEL_FAILED).catch(transitionError => {
+          log.error('Failed to restore processing state after cancellation failure', {
+            sessionId,
+            dialogTurnId,
+            transitionError,
+          });
+        });
       }
     }
 
diff --git a/src/web-ui/src/flow_chat/state-machine/SessionStateMachineManager.test.ts b/src/web-ui/src/flow_chat/state-machine/SessionStateMachineManager.test.ts
new file mode 100644
index 0000000000..e1dd996ece
--- /dev/null
+++ b/src/web-ui/src/flow_chat/state-machine/SessionStateMachineManager.test.ts
@@ -0,0 +1,71 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  LOCAL_SURFACE_ID,
+  activateSurface,
+} from '@/infrastructure/peer-device/deviceSurface';
+import { stateMachineManager } from './SessionStateMachineManager';
+import {
+  SessionExecutionEvent,
+  SessionExecutionState,
+} from './types';
+
+describe('SessionStateMachineManager device surfaces', () => {
+  beforeEach(() => {
+    stateMachineManager.clear();
+    activateSurface(LOCAL_SURFACE_ID);
+  });
+
+  it('keeps equal session ids in independent state machines', async () => {
+    await stateMachineManager.transition('same-session', SessionExecutionEvent.START);
+    await stateMachineManager.transition(
+      'same-session',
+      SessionExecutionEvent.BACKEND_STREAM_COMPLETED,
+    );
+    expect(stateMachineManager.getCurrentState('same-session')).toBe(
+      SessionExecutionState.FINISHING,
+    );
+
+    activateSurface('peer-b');
+    expect(stateMachineManager.getCurrentState('same-session')).toBe(SessionExecutionState.IDLE);
+    await stateMachineManager.transition('same-session', SessionExecutionEvent.START);
+    expect(stateMachineManager.getCurrentState('same-session')).toBe(
+      SessionExecutionState.PROCESSING,
+    );
+
+    activateSurface(LOCAL_SURFACE_ID);
+    expect(stateMachineManager.getCurrentState('same-session')).toBe(
+      SessionExecutionState.FINISHING,
+    );
+  });
+
+  it('does not publish a background surface machine update to active listeners', async () => {
+    activateSurface('peer-b');
+    const peerMachine = stateMachineManager.getOrCreate('same-session');
+    const listener = vi.fn();
+    const unsubscribe = stateMachineManager.subscribeGlobal(listener);
+
+    await peerMachine.transition(SessionExecutionEvent.START);
+    expect(listener).toHaveBeenCalledTimes(1);
+    listener.mockClear();
+
+    activateSurface(LOCAL_SURFACE_ID);
+    peerMachine.reset();
+    expect(listener).not.toHaveBeenCalled();
+    unsubscribe();
+  });
+
+  it('discards only the requested peer surface', async () => {
+    await stateMachineManager.transition('same-session', SessionExecutionEvent.START);
+    activateSurface('peer-b');
+    await stateMachineManager.transition('same-session', SessionExecutionEvent.START);
+
+    stateMachineManager.clearSurface('peer-b');
+    expect(stateMachineManager.getCurrentState('same-session')).toBe(SessionExecutionState.IDLE);
+
+    activateSurface(LOCAL_SURFACE_ID);
+    expect(stateMachineManager.getCurrentState('same-session')).toBe(
+      SessionExecutionState.PROCESSING,
+    );
+  });
+});
diff --git a/src/web-ui/src/flow_chat/state-machine/SessionStateMachineManager.ts b/src/web-ui/src/flow_chat/state-machine/SessionStateMachineManager.ts
index 4057e3f6fd..df9e283329 100644
--- a/src/web-ui/src/flow_chat/state-machine/SessionStateMachineManager.ts
+++ b/src/web-ui/src/flow_chat/state-machine/SessionStateMachineManager.ts
@@ -10,12 +10,19 @@ import {
   SessionStateMachine,
 } from './types';
 import { createLogger } from '@/shared/utils/logger';
+import {
+  getActiveSurfaceId,
+  type DeviceSurfaceId,
+} from '@/infrastructure/peer-device/deviceSurface';
 
 const log = createLogger('SessionStateMachineManager');
 
 export class SessionStateMachineManager {
   private static instance: SessionStateMachineManager;
-  private machines = new Map<string, SessionStateMachineImpl>();
+  private machinesBySurface = new Map<
+    DeviceSurfaceId,
+    Map<string, SessionStateMachineImpl>
+  >();
   private globalListeners: Set<(sessionId: string, machine: SessionStateMachine) => void> = new Set();
 
   private constructor() {
@@ -28,23 +35,42 @@ export class SessionStateMachineManager {
     return SessionStateMachineManager.instance;
   }
 
+  private surfaceMachines(
+    surfaceId: DeviceSurfaceId = getActiveSurfaceId(),
+    create = true,
+  ): Map<string, SessionStateMachineImpl> | undefined {
+    const existing = this.machinesBySurface.get(surfaceId);
+    if (existing || !create) {
+      return existing;
+    }
+    const machines = new Map<string, SessionStateMachineImpl>();
+    this.machinesBySurface.set(surfaceId, machines);
+    return machines;
+  }
+
   getOrCreate(sessionId: string): SessionStateMachineImpl {
-    let machine = this.machines.get(sessionId);
-    
+    const surfaceId = getActiveSurfaceId();
+    const machines = this.surfaceMachines(surfaceId)!;
+    let machine = machines.get(sessionId);
+
     if (!machine) {
       machine = new SessionStateMachineImpl(sessionId);
-      this.machines.set(sessionId, machine);
-      
+      machines.set(sessionId, machine);
+
       machine.subscribe((snapshot) => {
-        this.notifyGlobalListeners(sessionId, snapshot);
+        // A peer left running in the background may still settle local state.
+        // Its update must not wake consumers for whichever device is rendered.
+        if (surfaceId === getActiveSurfaceId()) {
+          this.notifyGlobalListeners(sessionId, snapshot);
+        }
       });
     }
-    
+
     return machine;
   }
 
   get(sessionId: string): SessionStateMachineImpl | null {
-    return this.machines.get(sessionId) || null;
+    return this.surfaceMachines(getActiveSurfaceId(), false)?.get(sessionId) || null;
   }
 
   async transition(
@@ -57,26 +83,31 @@ export class SessionStateMachineManager {
   }
 
   getCurrentState(sessionId: string): SessionExecutionState {
-    const machine = this.machines.get(sessionId);
+    const machine = this.surfaceMachines(getActiveSurfaceId(), false)?.get(sessionId);
     return machine ? machine.getCurrentState() : SessionExecutionState.IDLE;
   }
 
   getSnapshot(sessionId: string): SessionStateMachine | null {
-    const machine = this.machines.get(sessionId);
+    const machine = this.surfaceMachines(getActiveSurfaceId(), false)?.get(sessionId);
     return machine ? machine.getSnapshot() : null;
   }
 
   delete(sessionId: string): void {
-    this.machines.delete(sessionId);
+    this.surfaceMachines(getActiveSurfaceId(), false)?.delete(sessionId);
   }
 
   reset(sessionId: string): void {
-    const machine = this.machines.get(sessionId);
+    const machine = this.surfaceMachines(getActiveSurfaceId(), false)?.get(sessionId);
     if (machine) {
       machine.reset();
     }
   }
 
+  /** Reset a submission stranded on a surface that is no longer rendered. */
+  resetForSurface(surfaceId: DeviceSurfaceId, sessionId: string): void {
+    this.surfaceMachines(surfaceId, false)?.get(sessionId)?.reset();
+  }
+
   subscribeGlobal(
     listener: (sessionId: string, machine: SessionStateMachine) => void
   ): () => void {
@@ -97,13 +128,17 @@ export class SessionStateMachineManager {
   }
 
   getAllSessionIds(): string[] {
-    return Array.from(this.machines.keys());
+    return Array.from(this.surfaceMachines(getActiveSurfaceId(), false)?.keys() ?? []);
+  }
+
+  /** Permanently forget one detached device without touching other surfaces. */
+  clearSurface(surfaceId: DeviceSurfaceId): void {
+    this.machinesBySurface.delete(surfaceId);
   }
 
   clear(): void {
-    this.machines.clear();
+    this.machinesBySurface.clear();
   }
 }
 
 export const stateMachineManager = SessionStateMachineManager.getInstance();
-
diff --git a/src/web-ui/src/flow_chat/state-machine/transitions.test.ts b/src/web-ui/src/flow_chat/state-machine/transitions.test.ts
new file mode 100644
index 0000000000..f49a6764e0
--- /dev/null
+++ b/src/web-ui/src/flow_chat/state-machine/transitions.test.ts
@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest';
+import { getNextState } from './transitions';
+import { SessionExecutionEvent, SessionExecutionState } from './types';
+
+describe('recoverable interruption transitions', () => {
+  it('keeps the session finishing until backend settlement is observed', () => {
+    expect(getNextState(
+      SessionExecutionState.PROCESSING,
+      SessionExecutionEvent.USER_CANCEL,
+    )).toBe(SessionExecutionState.FINISHING);
+    expect(getNextState(
+      SessionExecutionState.FINISHING,
+      SessionExecutionEvent.FINISHING_SETTLED,
+    )).toBe(SessionExecutionState.IDLE);
+  });
+
+  it('returns to processing if the backend rejects interruption admission', () => {
+    expect(getNextState(
+      SessionExecutionState.FINISHING,
+      SessionExecutionEvent.USER_CANCEL_FAILED,
+    )).toBe(SessionExecutionState.PROCESSING);
+  });
+});
diff --git a/src/web-ui/src/flow_chat/state-machine/transitions.ts b/src/web-ui/src/flow_chat/state-machine/transitions.ts
index ff957f76b4..c86c7ca548 100644
--- a/src/web-ui/src/flow_chat/state-machine/transitions.ts
+++ b/src/web-ui/src/flow_chat/state-machine/transitions.ts
@@ -13,7 +13,8 @@ import { SessionExecutionState, SessionExecutionEvent, StateTransitionTable, Pro
  * - FINISHING: backend completed, frontend is draining late events before becoming idle
  * - ERROR: error state, can reset or retry
  * 
- * Cancellation logic: USER_CANCEL → immediately switch to IDLE (no backend wait)
+ * Cancellation logic: USER_CANCEL enters FINISHING until the backend confirms
+ * the old execution has settled, so queued input cannot race tail writes.
  */
 export const STATE_TRANSITIONS: StateTransitionTable = {
   [SessionExecutionState.IDLE]: {
@@ -21,7 +22,7 @@ export const STATE_TRANSITIONS: StateTransitionTable = {
   },
   
   [SessionExecutionState.PROCESSING]: {
-    [SessionExecutionEvent.USER_CANCEL]: SessionExecutionState.IDLE,
+    [SessionExecutionEvent.USER_CANCEL]: SessionExecutionState.FINISHING,
     [SessionExecutionEvent.FINISHING_SETTLED]: SessionExecutionState.IDLE,
     
     [SessionExecutionEvent.ERROR_OCCURRED]: SessionExecutionState.ERROR,
@@ -40,7 +41,8 @@ export const STATE_TRANSITIONS: StateTransitionTable = {
   },
 
   [SessionExecutionState.FINISHING]: {
-    [SessionExecutionEvent.USER_CANCEL]: SessionExecutionState.IDLE,
+    [SessionExecutionEvent.USER_CANCEL]: SessionExecutionState.FINISHING,
+    [SessionExecutionEvent.USER_CANCEL_FAILED]: SessionExecutionState.PROCESSING,
     [SessionExecutionEvent.ERROR_OCCURRED]: SessionExecutionState.ERROR,
     [SessionExecutionEvent.FINISHING_SETTLED]: SessionExecutionState.IDLE,
     [SessionExecutionEvent.COMPACTION_STARTED]: SessionExecutionState.FINISHING,
@@ -78,6 +80,7 @@ export const PHASE_TRANSITIONS: Record<SessionExecutionEvent, ProcessingPhase |
   [SessionExecutionEvent.BACKEND_STREAM_COMPLETED]: ProcessingPhase.FINALIZING,
   [SessionExecutionEvent.FINISHING_SETTLED]: null,
   [SessionExecutionEvent.USER_CANCEL]: null,
+  [SessionExecutionEvent.USER_CANCEL_FAILED]: null,
   [SessionExecutionEvent.ERROR_OCCURRED]: null,
   [SessionExecutionEvent.RESET]: null,
 };
diff --git a/src/web-ui/src/flow_chat/state-machine/types.ts b/src/web-ui/src/flow_chat/state-machine/types.ts
index 1f60b307e7..5e9782d08b 100644
--- a/src/web-ui/src/flow_chat/state-machine/types.ts
+++ b/src/web-ui/src/flow_chat/state-machine/types.ts
@@ -58,6 +58,7 @@ export enum SessionExecutionEvent {
   BACKEND_STREAM_COMPLETED = 'backend_stream_completed',
   FINISHING_SETTLED = 'finishing_settled',
   USER_CANCEL = 'user_cancel',
+  USER_CANCEL_FAILED = 'user_cancel_failed',
   ERROR_OCCURRED = 'error_occurred',
   RESET = 'reset',
 }
diff --git a/src/web-ui/src/flow_chat/store/FlowChatStore.test.ts b/src/web-ui/src/flow_chat/store/FlowChatStore.test.ts
index e75c0e6eaa..14f836fe3c 100644
--- a/src/web-ui/src/flow_chat/store/FlowChatStore.test.ts
+++ b/src/web-ui/src/flow_chat/store/FlowChatStore.test.ts
@@ -1,5 +1,11 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { flowChatStore, mergeModelRoundAttemptDiagnostics } from './FlowChatStore';
+import {
+  LOCAL_SURFACE_ID,
+  SurfaceChangedError,
+  activateSurface,
+  isSurfaceChangedError,
+} from '@/infrastructure/peer-device/deviceSurface';
 import type { FlowChatState, Session } from '../types/flow-chat';
 import { startupTrace } from '@/shared/utils/startupTrace';
 import { projectEffectiveToolItem } from '../utils/toolInvocationIdentity';
@@ -106,6 +112,14 @@ vi.mock('../state-machine', () => ({
 }));
 
 const resetStore = () => {
+  // A test that rendered another device leaves that surface's container behind.
+  activateSurface(LOCAL_SURFACE_ID);
+  const surfaceContainers = (flowChatStore as any).surfaceContainers as Map<string, unknown>;
+  Array.from(surfaceContainers.keys())
+    .filter(surfaceId => surfaceId !== LOCAL_SURFACE_ID)
+    .forEach(surfaceId => {
+      flowChatStore.discardSurfaceState(surfaceId);
+    });
   const metadataListRequests = (flowChatStore as any).metadataListRequests as
     | Map<string, { cleanupTimer?: ReturnType<typeof setTimeout> }>
     | undefined;
@@ -1181,104 +1195,6 @@ describe('FlowChatStore round attempts', () => {
   });
 });
 
-describe('FlowChatStore local usage reports', () => {
-  afterEach(() => {
-    resetStore();
-  });
-
-  it('inserts a local usage report as user-visible content', () => {
-    const session = createSession({ lastActiveAt: 1234 });
-    flowChatStore.setState(() => ({
-      sessions: new Map([[session.sessionId, session]]),
-      activeSessionId: session.sessionId,
-    }));
-
-    const turn = flowChatStore.addLocalUsageReportTurn({
-      sessionId: session.sessionId,
-      markdown: '# Session Usage Report',
-      reportId: 'usage-1',
-      schemaVersion: 1,
-      generatedAt: 10,
-    });
-
-    const stored = flowChatStore.getState().sessions.get(session.sessionId)?.dialogTurns[0];
-    expect(turn).not.toBeNull();
-    expect(stored?.kind).toBe('local_command');
-    expect(stored?.userMessage.content).toBe('# Session Usage Report');
-    expect(stored?.userMessage.metadata).toMatchObject({
-      localCommandKind: 'usage_report',
-      modelVisible: false,
-    });
-    expect(flowChatStore.getState().sessions.get(session.sessionId)?.lastActiveAt)
-      .toBe(1234);
-  });
-
-  it('can update local usage reports without touching session activity', () => {
-    const session = createSession({ lastActiveAt: 4321 });
-    flowChatStore.setState(() => ({
-      sessions: new Map([[session.sessionId, session]]),
-      activeSessionId: session.sessionId,
-    }));
-
-    const turn = flowChatStore.addLocalUsageReportTurn({
-      sessionId: session.sessionId,
-      markdown: '# Loading',
-      reportId: 'usage-1',
-      schemaVersion: 1,
-      generatedAt: 10,
-      status: 'loading',
-    });
-
-    expect(turn).not.toBeNull();
-    flowChatStore.updateDialogTurn(
-      session.sessionId,
-      turn!.id,
-      current => ({
-        ...current,
-        status: 'completed',
-        userMessage: {
-          ...current.userMessage,
-          content: '# Complete',
-        },
-      }),
-      { touchActivity: false },
-    );
-
-    const stored = flowChatStore.getState().sessions.get(session.sessionId);
-    expect(stored?.dialogTurns[0].userMessage.content).toBe('# Complete');
-    expect(stored?.lastActiveAt).toBe(4321);
-  });
-
-  it('appends repeated usage reports as separate snapshots', () => {
-    const session = createSession();
-    flowChatStore.setState(() => ({
-      sessions: new Map([[session.sessionId, session]]),
-      activeSessionId: session.sessionId,
-    }));
-
-    flowChatStore.addLocalUsageReportTurn({
-      sessionId: session.sessionId,
-      markdown: '# Usage 1',
-      reportId: 'usage-1',
-      schemaVersion: 1,
-      generatedAt: 10,
-    });
-    flowChatStore.addLocalUsageReportTurn({
-      sessionId: session.sessionId,
-      markdown: '# Usage 2',
-      reportId: 'usage-2',
-      schemaVersion: 1,
-      generatedAt: 20,
-    });
-
-    const turns = flowChatStore.getState().sessions.get(session.sessionId)?.dialogTurns || [];
-    expect(turns).toHaveLength(2);
-    expect(turns.map(turn => turn.id)).toEqual([
-      'local-usage-usage-1',
-      'local-usage-usage-2',
-    ]);
-  });
-});
 
 describe('FlowChatStore ACP context usage', () => {
   afterEach(() => {
@@ -1455,6 +1371,7 @@ describe('FlowChatStore historical session hydration state', () => {
     peerModeFlagMock.active = false;
     apiMocks.restoreSessionView.mockReset();
     apiMocks.restoreSessionWithTurns.mockReset();
+    apiMocks.loadSessionTurns.mockReset();
     apiMocks.loadSessionTurnWindow.mockReset();
     apiMocks.accountFetchSessionTurns.mockResolvedValue(false);
     vi.stubGlobal('CustomEvent', class {
@@ -3656,6 +3573,7 @@ describe('FlowChatStore historical session hydration state', () => {
     }));
 
     ((flowChatStore as any).fullHistoryHydrationRequests as Map<string, unknown>).set('pending-history-1', {
+      surfaceId: LOCAL_SURFACE_ID,
       sessionId: 'history-1',
       remote: false,
       requireActiveSession: true,
@@ -4674,6 +4592,92 @@ describe('FlowChatStore historical session hydration state', () => {
     ).toEqual(['turn-12', 'turn-13', 'turn-14']);
   });
 
+  it('discards cached history windows when an authoritative restore changes the catalog', async () => {
+    const beforeCatalog = createTurnCatalog(8, 'catalog-before');
+    const afterCatalog = createTurnCatalog(6, 'catalog-after');
+    apiMocks.restoreSessionView
+      .mockResolvedValueOnce({
+        session: {
+          sessionId: 'history-1',
+          sessionName: 'History 1',
+          agentType: 'agentic',
+          state: 'Idle',
+          turnCount: 8,
+          createdAt: 1,
+        },
+        turns: [5, 6, 7].map(index => createPersistedTurn(index)),
+        turnCatalog: beforeCatalog,
+        contextRestoreState: 'pending',
+        isPartial: true,
+        loadedTurnCount: 3,
+        totalTurnCount: 8,
+      })
+      .mockResolvedValueOnce({
+        session: {
+          sessionId: 'history-1',
+          sessionName: 'History 1',
+          agentType: 'agentic',
+          state: 'Idle',
+          turnCount: 6,
+          createdAt: 1,
+        },
+        turns: [3, 4, 5].map(index => createPersistedTurn(index)),
+        turnCatalog: afterCatalog,
+        contextRestoreState: 'pending',
+        isPartial: true,
+        loadedTurnCount: 3,
+        totalTurnCount: 6,
+      });
+    apiMocks.loadSessionTurnWindow.mockResolvedValueOnce({
+      status: 'ready',
+      catalogRevision: beforeCatalog.revision,
+      totalTurnCount: 8,
+      startOrdinal: 0,
+      endOrdinalExclusive: 8,
+      targetTurnId: 'turn-0',
+      turns: Array.from({ length: 8 }, (_, index) => createPersistedTurn(index)),
+    });
+    flowChatStore.setState(() => ({
+      sessions: new Map([[
+        'history-1',
+        createSession({
+          sessionId: 'history-1',
+          isHistorical: true,
+          historyState: 'metadata-only',
+        }),
+      ]]),
+      activeSessionId: 'history-1',
+    }));
+
+    await flowChatStore.loadSessionHistory('history-1', 'D:/workspace/BitFun');
+    const loaded = await flowChatStore.loadSessionTurnWindow('history-1', 0, {
+      source: 'target',
+    });
+    expect(loaded.status).toBe('ready');
+    expect(flowChatStore.activateSessionHistoryWindow(
+      'history-1',
+      0,
+      loaded.navigationGeneration,
+    )?.range).toMatchObject({ startOrdinal: 0, endOrdinalExclusive: 8 });
+
+    await flowChatStore.loadSessionHistory('history-1', 'D:/workspace/BitFun');
+
+    expect(flowChatStore.getSessionHistoryViewState('history-1')).toMatchObject({
+      catalog: { revision: 'catalog-after', totalTurnCount: 6 },
+      activeRange: null,
+      pendingTargetOrdinal: null,
+      loadedRanges: [{
+        startOrdinal: 3,
+        endOrdinalExclusive: 6,
+        turns: [
+          expect.objectContaining({ id: 'turn-3' }),
+          expect.objectContaining({ id: 'turn-4' }),
+          expect.objectContaining({ id: 'turn-5' }),
+        ],
+      }],
+    });
+  });
+
   it('activates an adjacent catalog window from the restored tail without hydrating the session', async () => {
     const catalog = createTurnCatalog(15);
     apiMocks.restoreSessionView.mockResolvedValueOnce({
@@ -4754,107 +4758,6 @@ describe('FlowChatStore historical session hydration state', () => {
     expect(apiMocks.loadSessionTurnWindow).toHaveBeenCalledTimes(1);
   });
 
-  it('commits a provisional usage report at its authoritative ordinal without corrupting the restored tail', async () => {
-    const catalog = createTurnCatalog(7);
-    apiMocks.restoreSessionView.mockResolvedValueOnce({
-      session: {
-        sessionId: 'history-1',
-        sessionName: 'History 1',
-        agentType: 'agentic',
-        state: 'Idle',
-        turnCount: 7,
-        createdAt: 1,
-      },
-      turns: [4, 5, 6].map(index => createPersistedTurn(index)),
-      turnCatalog: catalog,
-      contextRestoreState: 'pending',
-      isPartial: true,
-      loadedTurnCount: 3,
-      totalTurnCount: 7,
-    });
-    flowChatStore.setState(() => ({
-      sessions: new Map([[
-        'history-1',
-        createSession({
-          sessionId: 'history-1',
-          isHistorical: true,
-          historyState: 'metadata-only',
-        }),
-      ]]),
-      activeSessionId: 'history-1',
-    }));
-
-    await flowChatStore.loadSessionHistory('history-1', 'D:/workspace/BitFun');
-    const provisional = flowChatStore.addLocalUsageReportTurn({
-      sessionId: 'history-1',
-      markdown: '# Session Usage Report',
-      reportId: 'usage-1',
-      schemaVersion: 1,
-      generatedAt: 10,
-    });
-    expect(provisional?.backendTurnIndex).toBeUndefined();
-    expect(provisional?.userMessage.metadata?.usageReportProvisional).toBe(true);
-    expect(flowChatStore.getSessionHistoryViewState('history-1')?.loadedRanges).toMatchObject([{
-      startOrdinal: 4,
-      endOrdinalExclusive: 7,
-    }]);
-
-    const authoritativeCatalog = {
-      ...createTurnCatalog(8, 'catalog-2'),
-      entries: [
-        ...createTurnCatalog(8, 'catalog-2').entries.slice(0, 7),
-        {
-          ordinal: 7,
-          storageTurnIndex: 7,
-          turnId: provisional?.id,
-          preview: 'Session Usage Report',
-          previewTruncated: false,
-        },
-      ],
-    };
-    expect(flowChatStore.commitLocalUsageReportTurn({
-      sessionId: 'history-1',
-      dialogTurnId: provisional!.id,
-      turnId: provisional!.id,
-      storageTurnIndex: 7,
-      totalTurnCount: 8,
-      turnCatalog: authoritativeCatalog,
-    })).toBe(true);
-
-    const session = flowChatStore.getState().sessions.get('history-1');
-    expect(session).toMatchObject({
-      isPartial: true,
-      loadedTurnCount: 4,
-      totalTurnCount: 8,
-    });
-    expect(session?.dialogTurns.find(turn => turn.id === 'turn-4')?.backendTurnIndex).toBe(4);
-    const committedReport = session?.dialogTurns.find(turn => turn.id === provisional?.id);
-    expect(committedReport?.backendTurnIndex).toBe(7);
-    expect(committedReport?.userMessage.metadata).not.toHaveProperty('usageReportProvisional');
-    expect(flowChatStore.getSessionHistoryViewState('history-1')?.loadedRanges).toMatchObject([{
-      startOrdinal: 4,
-      endOrdinalExclusive: 8,
-    }]);
-
-    apiMocks.loadSessionTurnWindow.mockResolvedValueOnce({
-      status: 'ready',
-      catalogRevision: authoritativeCatalog.revision,
-      totalTurnCount: 8,
-      startOrdinal: 0,
-      endOrdinalExclusive: 4,
-      targetTurnId: 'turn-3',
-      turns: [0, 1, 2, 3].map(index => createPersistedTurn(index)),
-    });
-    await expect(flowChatStore.loadSessionTurnWindow('history-1', 3)).resolves.toMatchObject({
-      status: 'ready',
-      isCurrent: true,
-    });
-    expect(flowChatStore.activateSessionHistoryWindowFromTail('history-1', 3)?.range).toMatchObject({
-      startOrdinal: 0,
-      endOrdinalExclusive: 8,
-      mode: 'history-window',
-    });
-  });
 
   it('caches an optimistic turn after a partial restored tail at its absolute ordinal', async () => {
     const catalog = createTurnCatalog(23);
@@ -5032,52 +4935,6 @@ describe('FlowChatStore historical session hydration state', () => {
       .toMatchObject([{ startOrdinal: 20, endOrdinalExclusive: 24 }]);
   });
 
-  it('does not change projected counts when removing a provisional usage report', async () => {
-    const catalog = createTurnCatalog(23);
-    apiMocks.restoreSessionView.mockResolvedValueOnce({
-      session: {
-        sessionId: 'history-1',
-        sessionName: 'History 1',
-        agentType: 'agentic',
-        state: 'Idle',
-        turnCount: 23,
-        createdAt: 1,
-      },
-      turns: [20, 21, 22].map(index => createPersistedTurn(index)),
-      turnCatalog: catalog,
-      contextRestoreState: 'pending',
-      isPartial: true,
-      loadedTurnCount: 3,
-      totalTurnCount: 23,
-    });
-    flowChatStore.setState(() => ({
-      sessions: new Map([['history-1', createSession({
-        sessionId: 'history-1',
-        isHistorical: true,
-        historyState: 'metadata-only',
-      })]]),
-      activeSessionId: 'history-1',
-    }));
-    await flowChatStore.loadSessionHistory('history-1', 'D:/workspace/BitFun');
-    const provisional = flowChatStore.addLocalUsageReportTurn({
-      sessionId: 'history-1',
-      markdown: '# Loading',
-      reportId: 'usage-1',
-      schemaVersion: 1,
-      generatedAt: 24,
-      status: 'loading',
-    });
-
-    flowChatStore.deleteDialogTurn('history-1', provisional!.id);
-
-    expect(flowChatStore.getState().sessions.get('history-1')).toMatchObject({
-      loadedTurnCount: 3,
-      totalTurnCount: 23,
-      dialogTurns: [{ id: 'turn-20' }, { id: 'turn-21' }, { id: 'turn-22' }],
-    });
-    expect(flowChatStore.getSessionHistoryViewState('history-1')?.loadedRanges)
-      .toMatchObject([{ startOrdinal: 20, endOrdinalExclusive: 23 }]);
-  });
 
   it('invalidates cached history and catalog entries after truncating a complete session', async () => {
     const catalog = createTurnCatalog(10);
@@ -5558,6 +5415,7 @@ describe('FlowChatStore historical session hydration state', () => {
     }));
     const startFallback = vi.fn();
     ((flowChatStore as any).fullHistoryHydrationRequests as Map<string, unknown>).set('fallback', {
+      surfaceId: LOCAL_SURFACE_ID,
       sessionId: 'history-1',
       remote: false,
       requireActiveSession: true,
@@ -6096,3 +5954,378 @@ describe('FlowChatStore historical session hydration state', () => {
     expect(flowChatStore.getState().sessions.get('history-1')?.currentTokenUsage).toBeUndefined();
   });
 });
+
+describe('FlowChatStore reconcile snapshot content safety', () => {
+  const HYDRATED_ROUND = {
+    id: 'round-0',
+    turnId: 'turn-0',
+    roundIndex: 0,
+    timestamp: 2,
+    textItems: [{ id: 'text-0', content: 'BitFun is an agentic IDE…', timestamp: 2 }],
+    toolItems: [],
+    thinkingItems: [],
+    startTime: 2,
+    status: 'completed',
+  };
+
+  const hostSession = (state = 'Idle') => ({
+    sessionId: 'history-1',
+    sessionName: 'History 1',
+    agentType: 'agentic',
+    state,
+    turnCount: 1,
+    createdAt: 1,
+  });
+
+  beforeEach(() => {
+    peerModeFlagMock.active = false;
+    apiMocks.restoreSessionView.mockReset();
+    apiMocks.accountFetchSessionTurns.mockResolvedValue(false);
+    vi.stubGlobal('CustomEvent', class {
+      type: string;
+      detail: unknown;
+
+      constructor(type: string, init?: { detail?: unknown }) {
+        this.type = type;
+        this.detail = init?.detail;
+      }
+    });
+    vi.stubGlobal('window', { dispatchEvent: vi.fn() });
+  });
+
+  afterEach(() => {
+    resetStore();
+    vi.clearAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  async function hydrateSessionWithContent(): Promise<void> {
+    flowChatStore.setState(() => ({
+      sessions: new Map([
+        ['history-1', createSession({
+          sessionId: 'history-1',
+          workspacePath: '/repo/BitFun',
+          isHistorical: true,
+          historyState: 'metadata-only',
+        })],
+      ]),
+      activeSessionId: 'history-1',
+    }));
+    apiMocks.restoreSessionView.mockResolvedValueOnce({
+      session: hostSession(),
+      turns: [{ ...createPersistedTurn(0), modelRounds: [HYDRATED_ROUND], endTime: 3 }],
+      contextRestoreState: 'ready',
+    });
+    await flowChatStore.loadSessionHistory('history-1', '/repo/BitFun');
+  }
+
+  it('keeps a hydrated turn when a wholesale replace snapshot carries none of its work', async () => {
+    // The reported failure: after switching device away and back, the rebuilt
+    // projection has no state machines, so every turn reads as idle and every
+    // snapshot qualifies for wholesale replacement. A windowed snapshot names
+    // the turn but carries no rounds, so replacing it left the user prompt on
+    // screen with the whole response gone.
+    await hydrateSessionWithContent();
+    expect(
+      flowChatStore.getState().sessions.get('history-1')?.dialogTurns[0].modelRounds,
+    ).toHaveLength(1);
+
+    apiMocks.restoreSessionView.mockResolvedValueOnce({
+      session: hostSession(),
+      turns: [{ ...createPersistedTurn(0), modelRounds: [] }],
+      contextRestoreState: 'ready',
+    });
+
+    const result = await flowChatStore.refreshPeerSessionSnapshot(
+      'history-1',
+      '/repo/BitFun',
+      { replaceRunningSnapshot: true, requireActiveSession: true },
+    );
+
+    expect(result.applied).toBe(false);
+    const turn = flowChatStore.getState().sessions.get('history-1')?.dialogTurns[0];
+    expect(turn?.modelRounds).toHaveLength(1);
+    expect(turn?.modelRounds[0].items).toHaveLength(1);
+  });
+
+  it('refuses a replace that would drop a round the projection already shows', async () => {
+    await hydrateSessionWithContent();
+
+    apiMocks.restoreSessionView.mockResolvedValueOnce({
+      session: hostSession(),
+      turns: [{
+        ...createPersistedTurn(0),
+        modelRounds: [{ ...HYDRATED_ROUND, id: 'round-other' }],
+      }],
+      contextRestoreState: 'ready',
+    });
+
+    await flowChatStore.refreshPeerSessionSnapshot(
+      'history-1',
+      '/repo/BitFun',
+      { replaceRunningSnapshot: true, requireActiveSession: true },
+    );
+
+    expect(
+      flowChatStore.getState().sessions.get('history-1')?.dialogTurns[0].modelRounds[0].id,
+    ).toBe('round-0');
+  });
+
+  it('still adopts the host copy when the snapshot carries the projected work', async () => {
+    // The guard must not disable wholesale replacement, which is how a settled
+    // turn picks up the host's authoritative copy.
+    await hydrateSessionWithContent();
+
+    apiMocks.restoreSessionView.mockResolvedValueOnce({
+      session: hostSession(),
+      turns: [{
+        ...createPersistedTurn(0),
+        modelRounds: [{
+          ...HYDRATED_ROUND,
+          textItems: [
+            { id: 'text-0', content: 'BitFun is an agentic IDE…', timestamp: 2 },
+            { id: 'text-1', content: '…with multi-device control.', timestamp: 3 },
+          ],
+        }],
+      }],
+      contextRestoreState: 'ready',
+    });
+
+    const result = await flowChatStore.refreshPeerSessionSnapshot(
+      'history-1',
+      '/repo/BitFun',
+      { replaceRunningSnapshot: true, requireActiveSession: true },
+    );
+
+    expect(result.applied).toBe(true);
+    expect(
+      flowChatStore.getState().sessions.get('history-1')?.dialogTurns[0].modelRounds[0].items,
+    ).toHaveLength(2);
+  });
+});
+
+describe('FlowChatStore device surfaces', () => {
+  const PEER_SURFACE_ID = 'device-b';
+
+  const restoredTurn = (sessionId: string) => ({
+    turnId: `${sessionId}-turn-1`,
+    turnIndex: 0,
+    sessionId,
+    timestamp: 1,
+    userMessage: { id: `${sessionId}-user-1`, content: 'hello', timestamp: 1 },
+    modelRounds: [],
+    startTime: 1,
+    status: 'completed',
+  });
+
+  const restoredSession = (sessionId: string) => ({
+    sessionId,
+    sessionName: sessionId,
+    agentType: 'agentic',
+    state: 'Idle',
+    turnCount: 1,
+    createdAt: 1,
+  });
+
+  const seedSession = (sessionId: string) => {
+    flowChatStore.setState(() => ({
+      sessions: new Map([
+        [sessionId, createSession({
+          sessionId,
+          isHistorical: true,
+          historyState: 'metadata-only',
+        })],
+      ]),
+      activeSessionId: sessionId,
+    }));
+  };
+
+  beforeEach(() => {
+    peerModeFlagMock.active = false;
+    apiMocks.restoreSessionView.mockReset();
+    apiMocks.restoreSessionWithTurns.mockReset();
+    apiMocks.listSessionsPage.mockReset();
+    apiMocks.accountFetchSessionTurns.mockResolvedValue(false);
+  });
+
+  afterEach(() => {
+    resetStore();
+  });
+
+  // The capability record used to collapse every non-SSH host onto `'local'`,
+  // so one peer that rejects the command downgraded this machine's own history
+  // restore for the rest of the session.
+  it('keeps an unsupported restore command on the device that rejected it', async () => {
+    activateSurface(PEER_SURFACE_ID);
+    seedSession('peer-1');
+    apiMocks.restoreSessionView.mockRejectedValueOnce(
+      new Error('unknown command restore_session_view'),
+    );
+    apiMocks.restoreSessionWithTurns.mockResolvedValueOnce({
+      session: restoredSession('peer-1'),
+      turns: [restoredTurn('peer-1')],
+    });
+
+    await flowChatStore.loadSessionHistory('peer-1', '/repo/BitFun');
+    expect(apiMocks.restoreSessionView).toHaveBeenCalledTimes(1);
+    expect(apiMocks.restoreSessionWithTurns).toHaveBeenCalledTimes(1);
+
+    activateSurface(LOCAL_SURFACE_ID);
+    seedSession('local-1');
+    apiMocks.restoreSessionView.mockResolvedValueOnce({
+      session: restoredSession('local-1'),
+      turns: [restoredTurn('local-1')],
+      contextRestoreState: 'ready',
+    });
+
+    await flowChatStore.loadSessionHistory('local-1', '/repo/BitFun');
+
+    expect(apiMocks.restoreSessionView).toHaveBeenCalledTimes(2);
+    expect(apiMocks.restoreSessionWithTurns).toHaveBeenCalledTimes(1);
+    expect(flowChatStore.getState().sessions.get('local-1')).toMatchObject({
+      historyState: 'ready',
+    });
+  });
+
+  it('keeps each device sessions across a switch away and back', async () => {
+    seedSession('local-1');
+
+    activateSurface(PEER_SURFACE_ID);
+    expect(flowChatStore.getState().sessions.has('local-1')).toBe(false);
+    seedSession('peer-1');
+
+    activateSurface(LOCAL_SURFACE_ID);
+    const localState = flowChatStore.getState();
+    expect(localState.activeSessionId).toBe('local-1');
+    expect(localState.sessions.has('local-1')).toBe(true);
+    expect(localState.sessions.has('peer-1')).toBe(false);
+
+    activateSurface(PEER_SURFACE_ID);
+    const peerState = flowChatStore.getState();
+    expect(peerState.activeSessionId).toBe('peer-1');
+    expect(peerState.sessions.has('peer-1')).toBe(true);
+  });
+
+  it('abandons an optimistic turn on its owning device without touching an equal peer session', () => {
+    seedSession('shared-session');
+    const optimisticTurn = {
+      id: 'optimistic-turn',
+      sessionId: 'shared-session',
+      agentType: 'agentic',
+      userMessage: { id: 'user-1', content: 'hello', timestamp: 1 },
+      modelRounds: [],
+      status: 'pending' as const,
+      startTime: 1,
+    };
+    flowChatStore.addDialogTurn('shared-session', optimisticTurn);
+
+    activateSurface(PEER_SURFACE_ID);
+    seedSession('shared-session');
+    flowChatStore.addDialogTurn('shared-session', {
+      ...optimisticTurn,
+      id: 'peer-turn',
+    });
+
+    flowChatStore.abandonOptimisticDialogTurn(
+      LOCAL_SURFACE_ID,
+      'shared-session',
+      'optimistic-turn',
+    );
+
+    expect(flowChatStore.getState().sessions.get('shared-session')?.dialogTurns)
+      .toHaveLength(1);
+    activateSurface(LOCAL_SURFACE_ID);
+    expect(flowChatStore.getState().sessions.get('shared-session')?.dialogTurns)
+      .toHaveLength(0);
+  });
+
+  // The rendered pane is derived from the store through this subscription, so
+  // selecting another container has to announce itself or the previous device's
+  // messages stay on screen.
+  it('notifies subscribers when another device becomes the rendered one', () => {
+    seedSession('local-1');
+    const observedActiveSessionIds: Array<string | null> = [];
+    const unsubscribe = flowChatStore.subscribe(state => {
+      observedActiveSessionIds.push(state.activeSessionId);
+    });
+
+    try {
+      activateSurface(PEER_SURFACE_ID);
+      expect(observedActiveSessionIds).toEqual([null]);
+
+      seedSession('peer-1');
+      activateSurface(LOCAL_SURFACE_ID);
+      expect(observedActiveSessionIds).toEqual([null, 'peer-1', 'local-1']);
+    } finally {
+      unsubscribe();
+    }
+  });
+
+  it('reports the switch through the surface generation without dropping sessions', () => {
+    seedSession('local-1');
+    const generationBefore = flowChatStore.getSurfaceGeneration();
+
+    flowChatStore.prepareForSurfaceSwitch();
+    activateSurface(PEER_SURFACE_ID);
+
+    expect(flowChatStore.getSurfaceGeneration()).toBeGreaterThan(generationBefore);
+    activateSurface(LOCAL_SURFACE_ID);
+    expect(flowChatStore.getState().sessions.has('local-1')).toBe(true);
+  });
+
+  it('loads session metadata once per device for the same workspace path', async () => {
+    apiMocks.listSessionsPage.mockResolvedValue({
+      sessions: [],
+      totalTopLevelCount: 0,
+      loadedTopLevelCount: 0,
+      nextCursor: undefined,
+      hasMore: false,
+    });
+
+    await flowChatStore.loadSessionMetadataPage('/repo/BitFun', 5);
+    expect(apiMocks.listSessionsPage).toHaveBeenCalledTimes(1);
+
+    // Same path, other machine: the dedup entry must not answer for it.
+    activateSurface(PEER_SURFACE_ID);
+    await flowChatStore.loadSessionMetadataPage('/repo/BitFun', 5);
+
+    expect(apiMocks.listSessionsPage).toHaveBeenCalledTimes(2);
+  });
+
+  it('abandons a history restore that lands after the window switched device', async () => {
+    seedSession('local-1');
+    apiMocks.restoreSessionView.mockImplementationOnce(async () => {
+      activateSurface(PEER_SURFACE_ID);
+      return {
+        session: restoredSession('local-1'),
+        turns: [restoredTurn('local-1')],
+        contextRestoreState: 'ready',
+      };
+    });
+
+    await expect(
+      flowChatStore.loadSessionHistory('local-1', '/repo/BitFun'),
+    ).rejects.toSatisfy(isSurfaceChangedError);
+
+    // Neither device may be told the restore failed: the peer never asked, and
+    // the local projection is intact in its own container.
+    expect(flowChatStore.getState().sessions.has('local-1')).toBe(false);
+    activateSurface(LOCAL_SURFACE_ID);
+    expect(flowChatStore.getState().sessions.get('local-1')).toMatchObject({
+      historyState: 'metadata-only',
+    });
+  });
+
+  it('does not fall back onto the next device after a typed surface cancellation', async () => {
+    seedSession('local-1');
+    apiMocks.restoreSessionView.mockRejectedValueOnce(
+      new SurfaceChangedError(LOCAL_SURFACE_ID, 1, 'restore session view'),
+    );
+
+    await expect(
+      flowChatStore.loadSessionHistory('local-1', '/repo/BitFun'),
+    ).rejects.toSatisfy(isSurfaceChangedError);
+
+    expect(apiMocks.loadSessionTurns).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/web-ui/src/flow_chat/store/FlowChatStore.ts b/src/web-ui/src/flow_chat/store/FlowChatStore.ts
index 5acfa2b024..2b08c9dbb8 100644
--- a/src/web-ui/src/flow_chat/store/FlowChatStore.ts
+++ b/src/web-ui/src/flow_chat/store/FlowChatStore.ts
@@ -35,10 +35,17 @@ import {
 import { elapsedMs, nowMs } from '@/shared/utils/timing';
 import { normalizeRemoteSessionScope } from '@/shared/utils/remoteSessionScope';
 import { isPeerDeviceModeActive } from '@/infrastructure/peer-device/peerModeFlag';
+import {
+  getActiveSurfaceId,
+  getActiveSurfaceScope,
+  isSurfaceChangedError,
+  onSurfaceActivated,
+  surfaceScopedKey,
+  type DeviceSurfaceId,
+} from '@/infrastructure/peer-device/deviceSurface';
 import { i18nService } from '@/infrastructure/i18n/core/I18nService';
 import type {
   DialogTurnData,
-  LocalCommandMetadata,
   SessionContextUsage,
   SessionKind,
   SessionTurnCatalog,
@@ -82,6 +89,7 @@ import { resolveThreadGoalUserMessageDisplay } from '../utils/threadGoalDisplay'
 import { cleanRemoteUserInput } from '../utils/userInputText';
 import { useBackgroundSubagentActivityStore } from './backgroundSubagentActivityStore';
 import { sessionComposerStore } from './sessionComposerStore';
+import { completeSessionMutationReconciliation } from './sessionMutationStore';
 import { recordHistorySessionDiagnosticEvent } from '../services/historySessionDiagnostics';
 import {
   isDispatchJobTerminal,
@@ -374,6 +382,7 @@ interface OrdinalInterval {
 }
 
 interface SessionTurnWindowProtection extends OrdinalInterval {
+  surfaceId: DeviceSurfaceId;
   sessionId: string;
   retainCount: number;
 }
@@ -635,6 +644,45 @@ function isRunningSnapshotForwardProgress(
   return advanced;
 }
 
+/**
+ * Whether replacing `current` with `snapshot` would erase projected content.
+ *
+ * Reconciliation repairs a projection; it must never gut one. The wholesale
+ * replace path exists so a settled turn can adopt the host's authoritative
+ * copy, and it skips the forward-progress comparator to do that. But a turn
+ * carries its identity and user message independently of its rounds, so a
+ * windowed or not-yet-checkpointed snapshot can name the same turn while
+ * carrying none of its work. Replacing then leaves the user prompt on screen
+ * with the entire response gone.
+ *
+ * This is reachable on any surface, and guaranteed right after a device-surface
+ * switch: the rebuilt projection has no state machines, so every turn reads as
+ * idle and every snapshot qualifies for replacement.
+ */
+function snapshotDropsProjectedTurnContent(
+  current: DialogTurn,
+  snapshot: DialogTurn,
+): boolean {
+  if (snapshot.modelRounds.length < current.modelRounds.length) {
+    return true;
+  }
+
+  for (const currentRound of current.modelRounds) {
+    const snapshotRound = snapshot.modelRounds.find(round => round.id === currentRound.id);
+    if (!snapshotRound) {
+      return true;
+    }
+    if (streamProgressEntries(snapshotRound).size < streamProgressEntries(currentRound).size) {
+      return true;
+    }
+    if (toolProgressEntries(snapshotRound).size < toolProgressEntries(currentRound).size) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
 function itemMatchesIdentity(item: AnyFlowItem, itemId: string): boolean {
   if (item.id === itemId) {
     return true;
@@ -960,6 +1008,7 @@ interface MetadataPageRequest {
 }
 
 interface FullHistoryHydrationRequest {
+  surfaceId: DeviceSurfaceId;
   sessionId: string;
   remote: boolean;
   requireActiveSession: boolean;
@@ -1437,16 +1486,33 @@ function isSessionRestoreTransportError(error: unknown): boolean {
   );
 }
 
+/** `surfaceScopedKey` puts the surface first, so a key can name its own owner. */
+function surfaceOfScopedKey(key: string): DeviceSurfaceId | null {
+  try {
+    const parsed = JSON.parse(key) as unknown[];
+    return typeof parsed[0] === 'string' ? parsed[0] : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A capability is negotiated with one host, not with a path: an older peer that
+ * rejects `restore_session_view` says nothing about this machine. Without the
+ * surface every non-SSH host collapsed onto `'local'`, so one switch permanently
+ * downgraded local history restore.
+ */
 function restoreCommandSupportKey(
   command: string,
   remoteConnectionId?: string,
   remoteSshHost?: string
 ): string {
-  return JSON.stringify([
+  return surfaceScopedKey(
+    getActiveSurfaceId(),
     command,
     remoteConnectionId?.trim() || 'local',
     remoteSshHost?.trim().toLowerCase() || '',
-  ]);
+  );
 }
 
 function isValidPersistedAgentType(agentType: string): boolean {
@@ -1461,36 +1527,122 @@ interface SelectorListener<T = any> {
   hasLastValue: boolean;
 }
 
+/**
+ * One device's world.
+ *
+ * Sessions and their history projections are addressed by session id and
+ * workspace path, and neither is unique across devices — the same repository is
+ * routinely open at the same path on two machines. Each surface therefore keeps
+ * its own container, and a switch *selects* one instead of destroying it: the
+ * device you return to still has its sessions, and reconciliation repairs them
+ * instead of reloading from nothing.
+ */
+interface SurfaceStateContainer {
+  readonly surfaceId: DeviceSurfaceId;
+  state: FlowChatState;
+  readonly sessionHistoryViews: Map<string, SessionHistoryViewState>;
+  readonly sessionHistoryTurnAccessTimes: Map<string, Map<number, number>>;
+  readonly deferredFullHistoryProjections: Map<string, DeferredFullHistoryProjection>;
+  readonly fullHistoryProjectionApplyRequests: Set<string>;
+  readonly pendingRemoveSessionOptions: Map<string, RemoveSessionOptions>;
+}
+
+function createSurfaceStateContainer(surfaceId: DeviceSurfaceId): SurfaceStateContainer {
+  return {
+    surfaceId,
+    state: {
+      sessions: new Map(),
+      activeSessionId: null,
+    },
+    sessionHistoryViews: new Map(),
+    sessionHistoryTurnAccessTimes: new Map(),
+    deferredFullHistoryProjections: new Map(),
+    fullHistoryProjectionApplyRequests: new Set(),
+    pendingRemoveSessionOptions: new Map(),
+  };
+}
+
 export class FlowChatStore {
   private static instance: FlowChatStore;
-  private state: FlowChatState;
+  private surfaceContainers = new Map<DeviceSurfaceId, SurfaceStateContainer>();
   private listeners: Set<(state: FlowChatState) => void> = new Set();
   private selectorListeners: Set<SelectorListener> = new Set();
   private silentMode = false;
+  /**
+   * Request dedup and negotiated capabilities outlive the switch that stranded
+   * them, so their keys carry the surface instead of the container: an entry
+   * created under one activation is still reaped correctly after another one
+   * takes over.
+   */
   private metadataListRequests = new Map<string, MetadataListRequest>();
   private metadataPageRequests = new Map<string, MetadataPageRequest>();
-  /** Bumped on peer mode surface reset; stale metadata loads must not write. */
-  private surfaceGeneration = 0;
+  /** Announced switches, for the window before a surface activation lands. */
+  private detachedSurfaceGeneration = 0;
   private fullHistoryHydrationRequests = new Map<string, FullHistoryHydrationRequest>();
-  private deferredFullHistoryProjections = new Map<string, DeferredFullHistoryProjection>();
-  private fullHistoryProjectionApplyRequests = new Set<string>();
-  private sessionHistoryViews = new Map<string, SessionHistoryViewState>();
-  /** Per-ordinal recency survives adjacent range merges and enables stable range slicing. */
-  private sessionHistoryTurnAccessTimes = new Map<string, Map<number, number>>();
   private sessionHistoryAccessClock = 0;
   private sessionTurnWindowRequests = new Map<string, Promise<LoadSessionTurnWindowResponse>>();
   /** Requested intervals remain protected until every deduplicated caller processes the response. */
   private sessionTurnWindowProtections = new Map<string, SessionTurnWindowProtection>();
   private unsupportedRestoreCommands = new Set<string>();
-  private pendingRemoveSessionOptions = new Map<string, RemoveSessionOptions>();
   private onPersistUnreadCompletion?: (sessionId: string, value: 'completed' | 'error' | 'interrupted' | undefined) => void;
 
   private constructor() {
     this.clearOldStorage();
-    this.state = {
-      sessions: new Map(),
-      activeSessionId: null
-    };
+    // Selecting another surface swaps the whole visible state; subscribers keep
+    // rendering the previous device's sessions until they are told.
+    onSurfaceActivated(() => {
+      this.notifyListeners();
+    });
+  }
+
+  private get activeSurface(): SurfaceStateContainer {
+    const surfaceId = getActiveSurfaceId();
+    const existing = this.surfaceContainers.get(surfaceId);
+    if (existing) {
+      return existing;
+    }
+    const created = createSurfaceStateContainer(surfaceId);
+    this.surfaceContainers.set(surfaceId, created);
+    return created;
+  }
+
+  private get state(): FlowChatState {
+    return this.activeSurface.state;
+  }
+
+  private set state(next: FlowChatState) {
+    this.activeSurface.state = next;
+  }
+
+  private get sessionHistoryViews(): Map<string, SessionHistoryViewState> {
+    return this.activeSurface.sessionHistoryViews;
+  }
+
+  /** Per-ordinal recency survives adjacent range merges and enables stable range slicing. */
+  private get sessionHistoryTurnAccessTimes(): Map<string, Map<number, number>> {
+    return this.activeSurface.sessionHistoryTurnAccessTimes;
+  }
+
+  private get deferredFullHistoryProjections(): Map<string, DeferredFullHistoryProjection> {
+    return this.activeSurface.deferredFullHistoryProjections;
+  }
+
+  private get fullHistoryProjectionApplyRequests(): Set<string> {
+    return this.activeSurface.fullHistoryProjectionApplyRequests;
+  }
+
+  private get pendingRemoveSessionOptions(): Map<string, RemoveSessionOptions> {
+    return this.activeSurface.pendingRemoveSessionOptions;
+  }
+
+  /** Key a store-level cache entry to the surface that asked for it. */
+  private surfaceKey(...parts: Array<string | number | undefined | null>): string {
+    return surfaceScopedKey(getActiveSurfaceId(), ...parts);
+  }
+
+  /** Records outlive a switch; only the rendered surface may observe its own. */
+  private ownedByActiveSurface(record: { surfaceId: DeviceSurfaceId }): boolean {
+    return record.surfaceId === getActiveSurfaceId();
   }
 
   private clearOldStorage(): void {
@@ -1906,7 +2058,7 @@ export class FlowChatStore {
       }
     }
     for (const protection of this.sessionTurnWindowProtections.values()) {
-      if (protection.sessionId !== sessionId) {
+      if (!this.ownedByActiveSurface(protection) || protection.sessionId !== sessionId) {
         continue;
       }
       intervals.push({
@@ -2094,6 +2246,18 @@ export class FlowChatStore {
     const catalog = session.turnCatalog?.sessionId === sessionId
       ? session.turnCatalog
       : undefined;
+    const existingView = this.sessionHistoryViews.get(sessionId);
+    if (
+      catalog
+      && existingView?.catalog
+      && existingView.catalog.revision !== catalog.revision
+    ) {
+      existingView.navigationGeneration += 1;
+      existingView.pendingTargetOrdinal = null;
+      existingView.activeRange = null;
+      existingView.loadedRanges = [];
+      this.sessionHistoryTurnAccessTimes.delete(sessionId);
+    }
     const view = this.ensureSessionHistoryView(sessionId, catalog ?? null);
     if (catalog) {
       view.catalog = catalog;
@@ -2227,11 +2391,11 @@ export class FlowChatStore {
     remoteConnectionId?: string,
     remoteSshHost?: string,
   ): string {
-    return JSON.stringify([
+    return this.surfaceKey(
       workspacePath,
       remoteConnectionId || '',
       remoteSshHost || '',
-    ]);
+    );
   }
 
   private getMetadataPageRequestKey(
@@ -2241,13 +2405,13 @@ export class FlowChatStore {
     remoteConnectionId?: string,
     remoteSshHost?: string,
   ): string {
-    return JSON.stringify([
+    return this.surfaceKey(
       workspacePath,
       remoteConnectionId || '',
       remoteSshHost || '',
       cursor || '',
       limit,
-    ]);
+    );
   }
 
   private getFullHistoryHydrationKey(
@@ -2257,13 +2421,13 @@ export class FlowChatStore {
     remoteSshHost?: string,
     includeInternal?: boolean,
   ): string {
-    return JSON.stringify([
+    return this.surfaceKey(
       sessionId,
       workspacePath,
       remoteConnectionId || '',
       remoteSshHost || '',
-      includeInternal === true,
-    ]);
+      includeInternal === true ? 1 : 0,
+    );
   }
 
   private scheduleCompleteSessionHistoryLoad(
@@ -2322,6 +2486,9 @@ export class FlowChatStore {
               sessionId: request.sessionId,
               sessionTraceId: `${request.initialSessionTraceId}-full`,
             });
+            if (isSurfaceChangedError(error)) {
+              return;
+            }
             log.warn('Failed to complete partial session history restore', {
               sessionId: request.sessionId,
               error,
@@ -2351,6 +2518,7 @@ export class FlowChatStore {
     });
 
     const hydrationRequest: FullHistoryHydrationRequest = {
+      surfaceId: getActiveSurfaceId(),
       sessionId: request.sessionId,
       remote,
       requireActiveSession,
@@ -2379,7 +2547,12 @@ export class FlowChatStore {
   private cancelLocalSessionHistoryCompletion(sessionId: string, reason: string): boolean {
     let cancelled = false;
     for (const [requestKey, request] of this.fullHistoryHydrationRequests) {
-      if (request.sessionId !== sessionId || request.remote || !request.requireActiveSession) {
+      if (
+        !this.ownedByActiveSurface(request)
+        || request.sessionId !== sessionId
+        || request.remote
+        || !request.requireActiveSession
+      ) {
         continue;
       }
       request.cancel?.();
@@ -2402,7 +2575,7 @@ export class FlowChatStore {
     }
 
     for (const [requestKey, request] of this.fullHistoryHydrationRequests) {
-      if (!removedSessionIds.has(request.sessionId)) {
+      if (!this.ownedByActiveSurface(request) || !removedSessionIds.has(request.sessionId)) {
         continue;
       }
 
@@ -2423,10 +2596,11 @@ export class FlowChatStore {
       this.sessionHistoryTurnAccessTimes.delete(sessionId);
     }
 
+    const activeSurfaceId = getActiveSurfaceId();
     for (const requestKey of this.sessionTurnWindowRequests.keys()) {
       try {
-        const [sessionId] = JSON.parse(requestKey) as [string];
-        if (removedSessionIds.has(sessionId)) {
+        const [surfaceId, sessionId] = JSON.parse(requestKey) as [DeviceSurfaceId, string];
+        if (surfaceId === activeSurfaceId && removedSessionIds.has(sessionId)) {
           this.sessionTurnWindowRequests.delete(requestKey);
         }
       } catch {
@@ -2434,7 +2608,7 @@ export class FlowChatStore {
       }
     }
     for (const [requestKey, protection] of this.sessionTurnWindowProtections) {
-      if (removedSessionIds.has(protection.sessionId)) {
+      if (this.ownedByActiveSurface(protection) && removedSessionIds.has(protection.sessionId)) {
         this.sessionTurnWindowProtections.delete(requestKey);
       }
     }
@@ -2485,7 +2659,7 @@ export class FlowChatStore {
 
   public hasPendingSessionHistoryCompletion(sessionId: string): boolean {
     for (const request of this.fullHistoryHydrationRequests.values()) {
-      if (request.sessionId === sessionId) {
+      if (this.ownedByActiveSurface(request) && request.sessionId === sessionId) {
         return true;
       }
     }
@@ -2512,7 +2686,7 @@ export class FlowChatStore {
     }
 
     let hydrationRequest = Array.from(this.fullHistoryHydrationRequests.values()).find(
-      request => request.sessionId === sessionId,
+      request => this.ownedByActiveSurface(request) && request.sessionId === sessionId,
     );
     if (!hydrationRequest) {
       const canonicalTurns = canonicalSessionTurns(session);
@@ -2573,7 +2747,7 @@ export class FlowChatStore {
 
   private retainSessionTurnWindowProtection(
     key: string,
-    protection: Omit<SessionTurnWindowProtection, 'retainCount'>,
+    protection: Omit<SessionTurnWindowProtection, 'retainCount' | 'surfaceId'>,
   ): () => void {
     const existing = this.sessionTurnWindowProtections.get(key);
     if (existing) {
@@ -2581,6 +2755,7 @@ export class FlowChatStore {
     } else {
       this.sessionTurnWindowProtections.set(key, {
         ...protection,
+        surfaceId: getActiveSurfaceId(),
         retainCount: 1,
       });
     }
@@ -2752,6 +2927,7 @@ export class FlowChatStore {
     generation: number;
     staleRetryCount: number;
   }): Promise<SessionTurnWindowLoadResult> {
+    const scope = getActiveSurfaceScope();
     const supportKey = restoreCommandSupportKey(
       'load_session_turn_window',
       request.remoteConnectionId,
@@ -2780,7 +2956,7 @@ export class FlowChatStore {
       };
     }
 
-    const requestKey = JSON.stringify([
+    const requestKey = this.surfaceKey(
       request.sessionId,
       request.workspacePath,
       request.remoteConnectionId ?? '',
@@ -2789,7 +2965,7 @@ export class FlowChatStore {
       request.catalog.revision,
       request.before,
       request.after,
-    ]);
+    );
     const releaseWindowProtection = this.retainSessionTurnWindowProtection(
       requestKey,
       {
@@ -2847,6 +3023,8 @@ export class FlowChatStore {
     }
 
     try {
+      // Windows are cached against the projection they were requested for.
+      scope.assertCurrent('loadSessionTurnWindow');
       if (response.status === 'ready') {
         if (
           response.endOrdinalExclusive <= response.startOrdinal
@@ -2962,7 +3140,7 @@ export class FlowChatStore {
   ): boolean {
     let released = false;
     for (const request of this.fullHistoryHydrationRequests.values()) {
-      if (request.sessionId !== sessionId) {
+      if (!this.ownedByActiveSurface(request) || request.sessionId !== sessionId) {
         continue;
       }
       if (!request.releaseAfterInitialPaint) {
@@ -3253,6 +3431,7 @@ export class FlowChatStore {
       loadedTurnCount: request.expectedDialogTurnIds.length,
     });
 
+    const scope = getActiveSurfaceScope();
     const { agentAPI } = await import('@/infrastructure/api/service-api/AgentAPI');
     const restored = await agentAPI.restoreSessionView(
       request.sessionId,
@@ -3263,6 +3442,7 @@ export class FlowChatStore {
       request.includeInternal,
       undefined,
     );
+    scope.assertCurrent('completeSessionHistoryLoad');
 
     if (request.requireActiveSession === true && !remote && this.state.activeSessionId !== request.sessionId) {
       startupTrace.markPhase('historical_session_full_hydrate_skipped', {
@@ -4782,28 +4962,94 @@ export class FlowChatStore {
   }
 
   /**
-   * Drop all in-memory sessions and metadata request caches before switching
-   * Peer Device Mode data plane. Prevents local sessionIds from blocking peer
-   * metadata import (existingSession skip).
+   * Detach from the rendered surface without discarding it.
+   *
+   * A switch is a view change, not a teardown: this device's container stays, so
+   * returning to it shows its sessions immediately and reconciliation repairs
+   * them instead of reloading from nothing. Only its metadata dedup entries are
+   * dropped, so the next activation re-reads the list rather than adopting a
+   * request that raced the switch.
+   *
+   * Returns no session ids on purpose — nothing was removed, and callers must
+   * not tear down state machines for sessions that still exist on their device.
    */
-  public clearAllSessionsForPeerSwitch(): string[] {
-    this.surfaceGeneration += 1;
-    const removedSessionIds = Array.from(this.state.sessions.keys());
-    this.metadataListRequests.clear();
-    this.metadataPageRequests.clear();
-    if (removedSessionIds.length === 0) {
-      this.setState(prev => ({
-        ...prev,
-        sessions: new Map(),
-        activeSessionId: null,
-      }));
-      return [];
+  public prepareForSurfaceSwitch(): string[] {
+    this.detachedSurfaceGeneration = this.getSurfaceGeneration() + 1;
+    this.forgetSurfaceMetadataRequests(getActiveSurfaceId());
+    return [];
+  }
+
+  /**
+   * Forget a device entirely: its sessions, caches and negotiated capabilities.
+   * For a device that is gone (attachment dropped for good), never for a switch.
+   */
+  public discardSurfaceState(surfaceId: DeviceSurfaceId): string[] {
+    const container = this.surfaceContainers.get(surfaceId);
+    const removedSessionIds = container
+      ? Array.from(container.state.sessions.keys())
+      : [];
+    this.surfaceContainers.delete(surfaceId);
+    sessionComposerStore.getState().removeSurfaceDrafts(surfaceId);
+    this.forgetSurfaceMetadataRequests(surfaceId);
+
+    for (const [requestKey, request] of this.fullHistoryHydrationRequests) {
+      if (request.surfaceId !== surfaceId) {
+        continue;
+      }
+      request.cancel?.();
+      this.fullHistoryHydrationRequests.delete(requestKey);
+    }
+    for (const [requestKey, protection] of this.sessionTurnWindowProtections) {
+      if (protection.surfaceId === surfaceId) {
+        this.sessionTurnWindowProtections.delete(requestKey);
+      }
+    }
+    for (const requestKey of this.sessionTurnWindowRequests.keys()) {
+      if (surfaceOfScopedKey(requestKey) === surfaceId) {
+        this.sessionTurnWindowRequests.delete(requestKey);
+      }
+    }
+    for (const supportKey of this.unsupportedRestoreCommands) {
+      if (surfaceOfScopedKey(supportKey) === surfaceId) {
+        this.unsupportedRestoreCommands.delete(supportKey);
+      }
+    }
+
+    if (surfaceId === getActiveSurfaceId()) {
+      this.notifyListeners();
+    }
+    return removedSessionIds;
+  }
+
+  private forgetSurfaceMetadataRequests(surfaceId: DeviceSurfaceId): void {
+    for (const [requestKey, request] of this.metadataListRequests) {
+      if (surfaceOfScopedKey(requestKey) !== surfaceId) {
+        continue;
+      }
+      if (request.cleanupTimer) {
+        clearTimeout(request.cleanupTimer);
+      }
+      this.metadataListRequests.delete(requestKey);
+    }
+    for (const [requestKey, request] of this.metadataPageRequests) {
+      if (surfaceOfScopedKey(requestKey) !== surfaceId) {
+        continue;
+      }
+      if (request.cleanupTimer) {
+        clearTimeout(request.cleanupTimer);
+      }
+      this.metadataPageRequests.delete(requestKey);
     }
-    return this.removeSessionsByIds(removedSessionIds);
   }
 
+  /**
+   * Activation epochs, not store wipes. Callers compare this across an await to
+   * decide whether what they read back still belongs to the rendered surface, so
+   * it must also move in the window between an announced switch and the
+   * activation that follows it.
+   */
   public getSurfaceGeneration(): number {
-    return this.surfaceGeneration;
+    return Math.max(this.detachedSurfaceGeneration, getActiveSurfaceScope().epoch);
   }
 
   public getActiveSession(): Session | null {
@@ -4879,169 +5125,6 @@ export class FlowChatStore {
     }
   }
 
-  public addLocalUsageReportTurn(params: {
-    sessionId: string;
-    markdown: string;
-    reportId: string;
-    schemaVersion: number;
-    generatedAt: number;
-    report?: Record<string, any>;
-    status?: 'loading' | 'completed';
-  }): DialogTurn | null {
-    const session = this.state.sessions.get(params.sessionId);
-    if (!session) {
-      log.warn('Session not found, cannot add local usage report', { sessionId: params.sessionId });
-      return null;
-    }
-
-    const metadata: LocalCommandMetadata = {
-      localCommandKind: 'usage_report',
-      reportId: params.reportId,
-      schemaVersion: params.schemaVersion,
-      generatedAt: params.generatedAt,
-      modelVisible: false,
-      usageReport: params.report,
-      usageReportStatus: params.status ?? 'completed',
-      usageReportProvisional: true,
-    };
-    const dialogTurn: DialogTurn = {
-      id: `local-usage-${params.reportId}`,
-      sessionId: params.sessionId,
-      kind: 'local_command',
-      userMessage: {
-        id: `local-usage-user-${params.reportId}`,
-        content: params.markdown,
-        timestamp: params.generatedAt,
-        metadata,
-      },
-      modelRounds: [],
-      status: params.status === 'loading' ? 'processing' : 'completed',
-      startTime: params.generatedAt,
-      endTime: params.generatedAt,
-    };
-
-    this.setState(prev => {
-      const currentSession = prev.sessions.get(params.sessionId);
-      if (!currentSession) return prev;
-
-      if (currentSession.dialogTurns.some(turn => turn.id === dialogTurn.id)) {
-        return prev;
-      }
-
-      const newSessions = new Map(prev.sessions);
-      newSessions.set(params.sessionId, {
-        ...currentSession,
-        dialogTurns: [...currentSession.dialogTurns, dialogTurn],
-      });
-
-      return {
-        ...prev,
-        sessions: newSessions,
-      };
-    });
-    return dialogTurn;
-  }
-
-  public commitLocalUsageReportTurn(params: {
-    sessionId: string;
-    dialogTurnId: string;
-    turnId: string;
-    storageTurnIndex: number;
-    totalTurnCount: number;
-    turnCatalog: SessionTurnCatalog;
-  }): boolean {
-    if (
-      params.turnCatalog.sessionId !== params.sessionId
-      || params.totalTurnCount !== params.turnCatalog.totalTurnCount
-      || !Number.isInteger(params.storageTurnIndex)
-      || params.storageTurnIndex < 0
-    ) {
-      log.warn('Cannot commit local usage report with an invalid authoritative catalog', {
-        sessionId: params.sessionId,
-        dialogTurnId: params.dialogTurnId,
-        turnId: params.turnId,
-        storageTurnIndex: params.storageTurnIndex,
-      });
-      return false;
-    }
-    const catalogEntry = params.turnCatalog.entries.find(entry =>
-      entry.turnId === params.turnId
-      && entry.storageTurnIndex === params.storageTurnIndex
-    );
-    if (!catalogEntry) {
-      log.warn('Cannot commit local usage report missing from authoritative catalog', {
-        sessionId: params.sessionId,
-        dialogTurnId: params.dialogTurnId,
-        turnId: params.turnId,
-        storageTurnIndex: params.storageTurnIndex,
-      });
-      return false;
-    }
-
-    let committedTurn: DialogTurn | null = null;
-    this.setState(prev => {
-      const session = prev.sessions.get(params.sessionId);
-      const provisionalTurn = session?.dialogTurns.find(turn => turn.id === params.dialogTurnId);
-      if (
-        !session
-        || !provisionalTurn
-        || provisionalTurn.id !== params.turnId
-        || !isProvisionalUsageReportTurn(provisionalTurn)
-      ) {
-        return prev;
-      }
-
-      const dialogTurns = session.dialogTurns.map(turn => {
-        if (turn.id !== params.dialogTurnId) {
-          return turn;
-        }
-        const metadata = { ...turn.userMessage.metadata } as LocalCommandMetadata;
-        delete metadata.usageReportProvisional;
-        const nextTurn: DialogTurn = {
-          ...turn,
-          storageTurnIndex: params.storageTurnIndex,
-          backendTurnIndex: params.storageTurnIndex,
-          userMessage: {
-            ...turn.userMessage,
-            metadata,
-          },
-        };
-        committedTurn = nextTurn;
-        return nextTurn;
-      });
-      const newSessions = new Map(prev.sessions);
-      newSessions.set(params.sessionId, {
-        ...session,
-        dialogTurns,
-        turnCatalog: params.turnCatalog,
-        totalTurnCount: params.totalTurnCount,
-        loadedTurnCount: canonicalSessionTurns({ dialogTurns }).length,
-      });
-      return {
-        ...prev,
-        sessions: newSessions,
-      };
-    });
-
-    if (!committedTurn) {
-      log.warn('Cannot commit missing provisional local usage report', {
-        sessionId: params.sessionId,
-        dialogTurnId: params.dialogTurnId,
-      });
-      return false;
-    }
-
-    this.ensureSessionHistoryView(params.sessionId, params.turnCatalog).catalog = params.turnCatalog;
-    this.cacheSessionLoadedTurnRange(params.sessionId, {
-      startOrdinal: catalogEntry.ordinal,
-      endOrdinalExclusive: catalogEntry.ordinal + 1,
-      turns: [committedTurn],
-      lastAccessedAt: Date.now(),
-      source: 'live',
-    }, params.turnCatalog, catalogEntry.ordinal);
-    return true;
-  }
-
   public deleteDialogTurn(sessionId: string, dialogTurnId: string): void {
     let deletedTurn: DialogTurn | undefined;
     let deletedOrdinal: number | undefined;
@@ -5167,6 +5250,59 @@ export class FlowChatStore {
     }
   }
 
+  /**
+   * Remove a local optimistic turn whose submission was cancelled by a device
+   * switch before any host accepted it. This deliberately addresses the owning
+   * surface instead of the rendered one; otherwise a same-id session on the new
+   * device is edited while the original stays permanently busy.
+   */
+  public abandonOptimisticDialogTurn(
+    surfaceId: DeviceSurfaceId,
+    sessionId: string,
+    dialogTurnId: string,
+  ): void {
+    const container = this.surfaceContainers.get(surfaceId);
+    const session = container?.state.sessions.get(sessionId);
+    const deletedTurn = session?.dialogTurns.find(turn => turn.id === dialogTurnId);
+    if (!container || !session || !deletedTurn) {
+      return;
+    }
+
+    const dialogTurns = session.dialogTurns.filter(turn => turn.id !== dialogTurnId);
+    const countedOptimisticTurn = resolveStorageTurnIndex(session, deletedTurn) === undefined
+      && !isProvisionalUsageReportTurn(deletedTurn);
+    const canonicalTurnCount = canonicalSessionTurns({ dialogTurns }).length;
+    const sessions = new Map(container.state.sessions);
+    sessions.set(sessionId, {
+      ...session,
+      dialogTurns,
+      currentTokenUsage: currentTokenUsageAfterSourceRemoval(
+        session,
+        dialogTurns,
+        session.currentTokenUsage?.turnId === dialogTurnId,
+      ),
+      loadedTurnCount: canonicalTurnCount,
+      totalTurnCount: countedOptimisticTurn
+        ? Math.max(canonicalTurnCount, projectedSessionTurnCount(session) - 1)
+        : session.totalTurnCount,
+      lastUserDialogMode: this.deriveLastUserDialogMode(dialogTurns),
+      lastActiveAt: Date.now(),
+    });
+    container.state = { ...container.state, sessions };
+
+    // The optimistic turn may have been included in a loaded-range projection.
+    // Rebuild that derived cache when the device is rendered again rather than
+    // retaining an ordinal that no longer exists.
+    container.sessionHistoryViews.delete(sessionId);
+    container.sessionHistoryTurnAccessTimes.delete(sessionId);
+    container.deferredFullHistoryProjections.delete(sessionId);
+    container.fullHistoryProjectionApplyRequests.delete(sessionId);
+
+    if (surfaceId === getActiveSurfaceId()) {
+      this.notifyListeners();
+    }
+  }
+
   /**
    * Delete all dialog turns from turnIndex (inclusive)
    * Used for turn rollback: revert to before this turn and remove this turn and all subsequent history
@@ -6325,7 +6461,7 @@ export class FlowChatStore {
       defaultModels: Record<string, string>;
     }>,
   ): Promise<void> {
-    const surfaceGeneration = this.surfaceGeneration;
+    const scope = getActiveSurfaceScope();
     const [
       { stateMachineManager },
       { models, defaultModels },
@@ -6333,16 +6469,15 @@ export class FlowChatStore {
       import('../state-machine'),
       modelConfigPromise ?? this.loadSessionMetadataModelConfig(),
     ]);
-    if (surfaceGeneration !== this.surfaceGeneration) {
-      return;
-    }
+    // This page describes the device it was read from. Importing it into
+    // whichever surface happens to be rendered now would mix two devices'
+    // session lists under one workspace path.
+    scope.assertCurrent('processPersistedSessionMetadataList');
 
     const processSession = async (metadata: any) => {
       try {
         logPersistedDispatchMetadataOverlap(metadata, 'metadata-page');
-        if (surfaceGeneration !== this.surfaceGeneration) {
-          return;
-        }
+        scope.assertCurrent('processPersistedSessionMetadata');
         const existingSession = this.state.sessions.get(metadata.sessionId);
         if (existingSession) {
           return;
@@ -6385,10 +6520,7 @@ export class FlowChatStore {
         const persistedCurrentContextUsage = persistedCurrentContextUsageValue(metadata);
 
         this.setState(prev => {
-          if (surfaceGeneration !== this.surfaceGeneration) {
-            return prev;
-          }
-          if (prev.sessions.has(metadata.sessionId)) {
+          if (!scope.isCurrent() || prev.sessions.has(metadata.sessionId)) {
             return prev;
           }
 
@@ -6458,6 +6590,9 @@ export class FlowChatStore {
           };
         });
       } catch (error) {
+        if (isSurfaceChangedError(error)) {
+          throw error;
+        }
         log.warn('Failed to process persisted session metadata', {
           sessionId: metadata?.sessionId,
           error,
@@ -6668,6 +6803,15 @@ export class FlowChatStore {
         metadataListTraceId,
         durationMs: elapsedMs(traceStartedAt),
       });
+      if (isSurfaceChangedError(error)) {
+        // The page belongs to a device this window no longer renders. Its own
+        // container kept whatever landed; abandoning is not a load failure.
+        log.debug('Abandoned a session metadata page after a device surface switch', {
+          workspacePath,
+          source: traceSource,
+        });
+        throw error;
+      }
       log.error('Failed to load persisted session metadata page', error);
       throw error;
     }
@@ -6688,10 +6832,12 @@ export class FlowChatStore {
       source: traceSource,
       metadataListTraceId,
     });
+    const scope = getActiveSurfaceScope();
     try {
       const { sessionAPI } = await import('@/infrastructure/api/service-api/SessionAPI');
       const sessions = await sessionAPI.listSessions(workspacePath, remoteConnectionId, remoteSshHost);
       sessionCount = sessions.length;
+      scope.assertCurrent('initializeFromDisk');
       startupTrace.markPhase('session_metadata_list_loaded', {
         remote,
         source: traceSource,
@@ -6726,6 +6872,7 @@ export class FlowChatStore {
       const processSession = async (metadata: any) => {
         try {
           logPersistedDispatchMetadataOverlap(metadata, 'metadata-list');
+          scope.assertCurrent('initializeFromDiskSession');
           const existingSession = this.state.sessions.get(metadata.sessionId);
           if (existingSession) {
             return;
@@ -6768,7 +6915,7 @@ export class FlowChatStore {
           const persistedCurrentContextUsage = persistedCurrentContextUsageValue(metadata);
 
           this.setState(prev => {
-            if (prev.sessions.has(metadata.sessionId)) {
+            if (!scope.isCurrent() || prev.sessions.has(metadata.sessionId)) {
               return prev;
             }
 
@@ -6838,13 +6985,16 @@ export class FlowChatStore {
             };
           });
         } catch (error) {
+          if (isSurfaceChangedError(error)) {
+            throw error;
+          }
           log.warn('Failed to process persisted session metadata', {
             sessionId: metadata?.sessionId,
             error,
           });
         }
       };
-      
+
       await Promise.all(sessions.map(processSession));
       startupTrace.markPhase('session_metadata_list_end', {
         remote,
@@ -6862,6 +7012,13 @@ export class FlowChatStore {
         sessionCount,
         durationMs: elapsedMs(traceStartedAt),
       });
+      if (isSurfaceChangedError(error)) {
+        log.debug('Abandoned a session metadata list after a device surface switch', {
+          workspacePath,
+          source: traceSource,
+        });
+        return false;
+      }
       log.error('Failed to load persisted sessions', error);
       return false;
     }
@@ -6927,6 +7084,7 @@ export class FlowChatStore {
       shouldApply?: () => boolean;
     },
   ): Promise<PeerSessionSnapshotRefreshResult> {
+    const scope = getActiveSurfaceScope();
     const initialSession = this.state.sessions.get(sessionId);
     if (!initialSession) {
       return {
@@ -6944,6 +7102,9 @@ export class FlowChatStore {
       undefined,
       PEER_SESSION_REFRESH_TAIL_TURN_COUNT,
     );
+    // This snapshot describes the device it was read from; reconciling it into
+    // the surface that is rendered now would merge two devices' turns.
+    scope.assertCurrent('refreshPeerSessionSnapshot');
     const backendActive = isBackendSessionActivelyProcessing(restored.session.state);
     const activeTurnId = backendActive
       ? restored.turns[restored.turns.length - 1]?.turnId
@@ -6979,8 +7140,9 @@ export class FlowChatStore {
           mergedTurns.push(snapshotTurn);
           turnsChanged = true;
         } else if (
-          replaceExistingTurns ||
-          isRunningSnapshotForwardProgress(mergedTurns[existingIndex], snapshotTurn)
+          replaceExistingTurns
+            ? !snapshotDropsProjectedTurnContent(mergedTurns[existingIndex], snapshotTurn)
+            : isRunningSnapshotForwardProgress(mergedTurns[existingIndex], snapshotTurn)
         ) {
           mergedTurns[existingIndex] = snapshotTurn;
           turnsChanged = true;
@@ -7086,6 +7248,7 @@ export class FlowChatStore {
       sessionId,
       sessionTraceId,
     });
+    const scope = getActiveSurfaceScope();
     const initialSession = this.state.sessions.get(sessionId);
     const preserveDispatchObserverProjection = (): boolean => {
       const latestSession = this.state.sessions.get(sessionId);
@@ -7345,6 +7508,9 @@ export class FlowChatStore {
             durationMs: elapsedMs(restoreStartedAt),
           });
         } catch (error) {
+          if (isSurfaceChangedError(error)) {
+            throw error;
+          }
           if (isSessionRestoreTransportError(error)) {
             throw error;
           }
@@ -7384,6 +7550,10 @@ export class FlowChatStore {
         });
       }
       const stateMachineModule = await stateMachineManagerPromise;
+      // Restored turns belong to the device they were read from, and the state
+      // machine they are about to drive is shared, so a stale hydrate must stop
+      // here rather than commit into whichever surface is rendered now.
+      scope.assertCurrent('loadSessionHistory');
       // A local restore may have started just before the observer bound this
       // session. Re-check ownership after every restore await and before any
       // commit or state-machine mutation so that late empty history cannot
@@ -7554,6 +7724,7 @@ export class FlowChatStore {
           dialogTurnId: activeTurnId,
         });
       }
+      completeSessionMutationReconciliation(sessionId);
       startupTrace.markPhase('historical_session_hydrate_end', {
         remote,
         sessionId,
@@ -7608,6 +7779,19 @@ export class FlowChatStore {
         finishDispatchObserverSkip('failed');
         return;
       }
+      if (isSurfaceChangedError(error)) {
+        // Abandoned, not failed: the session is intact on its own device, and
+        // painting `failed` here would do it against another one.
+        startupTrace.markPhase('historical_session_hydrate_end', {
+          remote,
+          sessionId,
+          sessionTraceId,
+          skipped: true,
+          reason: 'device-surface-changed',
+          durationMs: elapsedMs(traceStartedAt),
+        });
+        throw error;
+      }
       this.setState(prev => {
         const session = prev.sessions.get(sessionId);
         if (!session) return prev;
@@ -7824,6 +8008,7 @@ export class FlowChatStore {
       finishReason: isLiveTurn
         ? persistedFinishReason
         : normalizeRecoveredTurnFinishReason(turn.status, persistedFinishReason),
+      recovery: turn.recovery,
       hasFinalResponse:
         typeof turn.hasFinalResponse === 'boolean'
           ? turn.hasFinalResponse
diff --git a/src/web-ui/src/flow_chat/store/modernFlowChatStore.test.ts b/src/web-ui/src/flow_chat/store/modernFlowChatStore.test.ts
index f3deb996ee..970553b466 100644
--- a/src/web-ui/src/flow_chat/store/modernFlowChatStore.test.ts
+++ b/src/web-ui/src/flow_chat/store/modernFlowChatStore.test.ts
@@ -11,10 +11,26 @@ vi.mock('./FlowChatStore', () => ({
 }));
 
 vi.mock('../tool-cards/toolCardMetadata', () => ({
-  isCollapsibleTool: (toolName: string) => ['Read', 'LS', 'Grep', 'Glob', 'WebSearch', 'Bash', 'Git'].includes(toolName),
+  isCollapsibleTool: (toolName: string) => [
+    'Read',
+    'LS',
+    'Grep',
+    'Glob',
+    'WebSearch',
+    'WebFetch',
+    'GetFileDiff',
+    'GetToolSpec',
+    'ReviewSessionSummary',
+    'TerminalControl',
+    'SessionControl',
+    'ExecControl',
+    'view_image',
+    'ReadCanvas',
+    'ControlHub',
+  ].includes(toolName),
   READ_TOOL_NAMES: new Set(['Read']),
   SEARCH_TOOL_NAMES: new Set(['Grep', 'Glob', 'WebSearch']),
-  COMMAND_TOOL_NAMES: new Set(['Bash', 'Git']),
+  COMMAND_TOOL_NAMES: new Set(),
 }));
 
 import { sessionToVirtualItems, type VirtualItem } from './modernFlowChatStore';
@@ -136,6 +152,70 @@ describe('sessionToVirtualItems explore grouping', () => {
     expect(items.map(item => item.type)).toEqual(['user-message', 'explore-group']);
   });
 
+  it.each([
+    'WebFetch',
+    'GetFileDiff',
+    'GetToolSpec',
+    'ReviewSessionSummary',
+    'TerminalControl',
+    'SessionControl',
+    'ExecControl',
+    'view_image',
+    'ReadCanvas',
+    'ControlHub',
+  ])('collects non-critical %s rounds into explore groups', (toolName) => {
+    const session = makeSession({
+      sessionId: `non-critical-${toolName}`,
+      dialogTurns: [{
+        id: 'turn-1',
+        sessionId: `non-critical-${toolName}`,
+        userMessage: {
+          id: 'user-1',
+          content: 'Help',
+          timestamp: 900,
+        },
+        modelRounds: [makeRound({
+          items: [makeTool(`tool-${toolName}`, toolName)],
+        })],
+        status: 'completed',
+        startTime: 900,
+      }],
+    });
+
+    expect(sessionToVirtualItems(session).map(item => item.type)).toEqual([
+      'user-message',
+      'explore-group',
+    ]);
+  });
+
+  it.each(['Bash', 'Git', 'ExecCommand', 'TodoWrite', 'ContextCompression', 'Skill', 'SessionMessage'])(
+    'keeps conditionally important %s rounds visible',
+    (toolName) => {
+      const session = makeSession({
+        sessionId: `critical-${toolName}`,
+        dialogTurns: [{
+          id: 'turn-1',
+          sessionId: `critical-${toolName}`,
+          userMessage: {
+            id: 'user-1',
+            content: 'Help',
+            timestamp: 900,
+          },
+          modelRounds: [makeRound({
+            items: [makeTool(`tool-${toolName}`, toolName)],
+          })],
+          status: 'completed',
+          startTime: 900,
+        }],
+      });
+
+      expect(sessionToVirtualItems(session).map(item => item.type)).toEqual([
+        'user-message',
+        'model-round',
+      ]);
+    },
+  );
+
   it('projects the absolute Turn index for a sparse history-window message', () => {
     const session = makeSession({
       sessionId: 'history-window-session',
@@ -370,6 +450,55 @@ describe('sessionToVirtualItems explore grouping', () => {
     expect(items.map(item => item.type)).toEqual(['user-message', 'model-round']);
   });
 
+  it('projects the thinking expansion state used by the renderer into layout hints', () => {
+    const thinkingItem = {
+      id: 'thinking-1',
+      type: 'thinking' as const,
+      content: 'Inspecting the implementation',
+      isStreaming: true,
+      timestamp: 1000,
+      status: 'streaming' as const,
+    };
+    const session = makeSession({
+      sessionId: 'thinking-layout-session',
+      dialogTurns: [{
+        id: 'turn-1',
+        sessionId: 'thinking-layout-session',
+        userMessage: {
+          id: 'user-1',
+          content: 'Help',
+          timestamp: 900,
+        },
+        modelRounds: [
+          makeRound({
+            id: 'earlier-thinking',
+            items: [{ ...thinkingItem, id: 'thinking-0', isStreaming: false, status: 'completed' }],
+            renderHints: { disableExploreGrouping: true },
+          }),
+          makeRound({
+            id: 'active-thinking',
+            index: 1,
+            items: [thinkingItem],
+            isStreaming: true,
+            isComplete: false,
+            status: 'streaming',
+            renderHints: { disableExploreGrouping: true },
+          }),
+        ],
+        status: 'processing',
+        startTime: 900,
+      }],
+    });
+
+    const modelRounds = sessionToVirtualItems(session)
+      .filter((item): item is ModelRoundVirtualItem => item.type === 'model-round');
+
+    expect(modelRounds.map(item => item.layoutHints?.expandedThinkingItemIds)).toEqual([
+      [],
+      ['thinking-1'],
+    ]);
+  });
+
   it('appends a completion notice for abnormal completed turns', () => {
     const session = makeSession({
       dialogTurns: [{
diff --git a/src/web-ui/src/flow_chat/store/modernFlowChatStore.ts b/src/web-ui/src/flow_chat/store/modernFlowChatStore.ts
index 589ff3dd40..621616775d 100644
--- a/src/web-ui/src/flow_chat/store/modernFlowChatStore.ts
+++ b/src/web-ui/src/flow_chat/store/modernFlowChatStore.ts
@@ -76,6 +76,9 @@ export type VirtualItem =
       turnId: string;
       isLastRound: boolean;
       isTurnComplete: boolean;
+      layoutHints?: {
+        expandedThinkingItemIds: string[];
+      };
       turnStartedAt?: number;
       turnEndedAt?: number;
       turnDurationMs?: number;
@@ -124,7 +127,7 @@ interface ModernFlowChatState {
  * adjacent explore groups to reduce visual noise from standalone "thinking N chars" lines.
  * Pure text rounds (like final replies) should not be collapsed.
  * Explore-capable rounds keep explore-group identity from the first render so
- * settling a streaming narrative cannot swap Virtuoso keys and remount the pane.
+ * settling a streaming narrative cannot swap virtual-item keys and remount the pane.
  * Typewriter remount risk is covered by useTypewriter(replayOnMount: false).
  */
 function hasTrailingVisibleText(round: ModelRound): boolean {
@@ -493,7 +496,7 @@ export function sessionToVirtualItems(session: Session | null): VirtualItem[] {
           groupIndex++;
         } else {
           // One round is always exactly one virtual item. Splitting a completed
-          // round into segments swaps a single Virtuoso key for N new keys,
+          // round into segments swaps a single virtual-item key for N new keys,
           // which remounts the visible assistant message and flashes the pane.
           items.push({
             type: 'model-round',
@@ -501,6 +504,12 @@ export function sessionToVirtualItems(session: Session | null): VirtualItem[] {
             turnId: turn.id,
             isLastRound: roundIndex === rounds.length - 1,
             isTurnComplete,
+            layoutHints: {
+              expandedThinkingItemIds: roundIndex === rounds.length - 1
+                && round.items.at(-1)?.type === 'thinking'
+                ? [round.items.at(-1)!.id]
+                : [],
+            },
             turnStartedAt: turn.startTime,
             turnEndedAt: turn.endTime,
             turnDurationMs: typeof turn.endTime === 'number'
diff --git a/src/web-ui/src/flow_chat/store/sessionComposerStore.test.ts b/src/web-ui/src/flow_chat/store/sessionComposerStore.test.ts
index b649ca8605..686176d150 100644
--- a/src/web-ui/src/flow_chat/store/sessionComposerStore.test.ts
+++ b/src/web-ui/src/flow_chat/store/sessionComposerStore.test.ts
@@ -3,6 +3,10 @@ import { beforeEach, describe, expect, it } from 'vitest';
 import type { ContextItem } from '@/shared/types/context';
 import type { ComposerPresentation } from '../utils/composerPresentation';
 import { sessionComposerStore } from './sessionComposerStore';
+import {
+  LOCAL_SURFACE_ID,
+  activateSurface,
+} from '@/infrastructure/peer-device/deviceSurface';
 
 function context(id: string): ContextItem {
   return {
@@ -15,6 +19,7 @@ function context(id: string): ContextItem {
 
 describe('sessionComposerStore', () => {
   beforeEach(() => {
+    activateSurface(LOCAL_SURFACE_ID);
     sessionComposerStore.setState({ drafts: {} });
   });
 
@@ -102,7 +107,34 @@ describe('sessionComposerStore', () => {
 
     store.removeDrafts(['session-a']);
 
-    expect(sessionComposerStore.getState().drafts['session-a']).toBeUndefined();
+    expect(sessionComposerStore.getState().getDraft('session-a').value).toBe('');
     expect(sessionComposerStore.getState().getDraft('session-b').value).toBe('draft b');
   });
+
+  it('keeps equal session ids isolated across device surfaces', () => {
+    sessionComposerStore.getState().setValue('same-session', 'local draft');
+
+    activateSurface('peer-b');
+    expect(sessionComposerStore.getState().getDraft('same-session').value).toBe('');
+    sessionComposerStore.getState().setValue('same-session', 'peer draft');
+
+    activateSurface(LOCAL_SURFACE_ID);
+    expect(sessionComposerStore.getState().getDraft('same-session').value).toBe('local draft');
+    activateSurface('peer-b');
+    expect(sessionComposerStore.getState().getDraft('same-session').value).toBe('peer draft');
+  });
+
+  it('does not save the previous surface contexts into the new surface', () => {
+    activateSurface('peer-b');
+
+    sessionComposerStore.getState().activateDraft(
+      'local-session',
+      'peer-session',
+      [context('local-context')],
+      null,
+      false,
+    );
+
+    expect(sessionComposerStore.getState().getDraft('local-session').contexts).toEqual([]);
+  });
 });
diff --git a/src/web-ui/src/flow_chat/store/sessionComposerStore.ts b/src/web-ui/src/flow_chat/store/sessionComposerStore.ts
index f0cb62404b..e2895d70b2 100644
--- a/src/web-ui/src/flow_chat/store/sessionComposerStore.ts
+++ b/src/web-ui/src/flow_chat/store/sessionComposerStore.ts
@@ -1,6 +1,11 @@
 import { create } from 'zustand';
 
 import type { ContextItem } from '@/shared/types/context';
+import {
+  getActiveSurfaceId,
+  surfaceScopedKey,
+  type DeviceSurfaceId,
+} from '@/infrastructure/peer-device/deviceSurface';
 import type { ComposerPresentation } from '../utils/composerPresentation';
 
 export type PendingLargePasteMap = Record<string, string>;
@@ -21,6 +26,7 @@ interface SessionComposerState {
     nextSessionId: string | null,
     currentContexts: ContextItem[],
     currentPresentation: ComposerPresentation | null,
+    persistPreviousContexts?: boolean,
   ) => SessionComposerDraft;
   setValue: (sessionId: string, value: string) => void;
   setContexts: (sessionId: string, contexts: ContextItem[]) => void;
@@ -28,6 +34,7 @@ interface SessionComposerState {
   setPendingLargePastes: (sessionId: string, pendingLargePastes: PendingLargePasteMap) => void;
   clearDraft: (sessionId: string) => void;
   removeDrafts: (sessionIds: Iterable<string>) => void;
+  removeSurfaceDrafts: (surfaceId: DeviceSurfaceId) => void;
 }
 
 const EMPTY_CONTEXTS: ContextItem[] = [];
@@ -43,16 +50,21 @@ function createEmptyDraft(): SessionComposerDraft {
   };
 }
 
+function draftKey(sessionId: string, surfaceId = getActiveSurfaceId()): string {
+  return surfaceScopedKey(surfaceId, sessionId);
+}
+
 function updateDraft(
   state: SessionComposerState,
   sessionId: string,
   update: Partial<Omit<SessionComposerDraft, 'updatedAt'>>,
 ): Pick<SessionComposerState, 'drafts'> {
-  const current = state.drafts[sessionId] ?? createEmptyDraft();
+  const key = draftKey(sessionId);
+  const current = state.drafts[key] ?? createEmptyDraft();
   return {
     drafts: {
       ...state.drafts,
-      [sessionId]: {
+      [key]: {
         ...current,
         ...update,
         updatedAt: Date.now(),
@@ -64,15 +76,20 @@ function updateDraft(
 export const useSessionComposerStore = create<SessionComposerState>((set, get) => ({
   drafts: {},
 
-  getDraft: (sessionId) => get().drafts[sessionId] ?? createEmptyDraft(),
+  getDraft: (sessionId) => get().drafts[draftKey(sessionId)] ?? createEmptyDraft(),
 
   activateDraft: (
     previousSessionId,
     nextSessionId,
     currentContexts,
     currentPresentation,
+    persistPreviousContexts = true,
   ) => {
-    if (previousSessionId && previousSessionId !== nextSessionId) {
+    if (
+      persistPreviousContexts
+      && previousSessionId
+      && previousSessionId !== nextSessionId
+    ) {
       get().setContexts(previousSessionId, currentContexts);
       get().setPresentation(previousSessionId, currentPresentation);
     }
@@ -99,7 +116,7 @@ export const useSessionComposerStore = create<SessionComposerState>((set, get) =
 
   clearDraft: (sessionId) => {
     set(state => {
-      if (!state.drafts[sessionId]) {
+      if (!state.drafts[draftKey(sessionId)]) {
         return state;
       }
 
@@ -113,7 +130,7 @@ export const useSessionComposerStore = create<SessionComposerState>((set, get) =
   },
 
   removeDrafts: (sessionIds) => {
-    const ids = new Set(sessionIds);
+    const ids = new Set(Array.from(sessionIds, sessionId => draftKey(sessionId)));
     if (ids.size === 0) {
       return;
     }
@@ -121,15 +138,34 @@ export const useSessionComposerStore = create<SessionComposerState>((set, get) =
     set(state => {
       const drafts = { ...state.drafts };
       let changed = false;
-      ids.forEach(sessionId => {
-        if (sessionId in drafts) {
-          delete drafts[sessionId];
+      ids.forEach(key => {
+        if (key in drafts) {
+          delete drafts[key];
           changed = true;
         }
       });
       return changed ? { drafts } : state;
     });
   },
+
+  removeSurfaceDrafts: (surfaceId) => {
+    set(state => {
+      const drafts = { ...state.drafts };
+      let changed = false;
+      for (const key of Object.keys(drafts)) {
+        try {
+          const [ownedSurfaceId] = JSON.parse(key) as [DeviceSurfaceId, string];
+          if (ownedSurfaceId === surfaceId) {
+            delete drafts[key];
+            changed = true;
+          }
+        } catch {
+          // Ignore legacy/malformed in-memory keys; no persisted shape exists.
+        }
+      }
+      return changed ? { drafts } : state;
+    });
+  },
 }));
 
 export const sessionComposerStore = useSessionComposerStore;
diff --git a/src/web-ui/src/flow_chat/store/sessionMutationStore.test.ts b/src/web-ui/src/flow_chat/store/sessionMutationStore.test.ts
new file mode 100644
index 0000000000..b7494d29d4
--- /dev/null
+++ b/src/web-ui/src/flow_chat/store/sessionMutationStore.test.ts
@@ -0,0 +1,43 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+
+import {
+  assertSessionSubmissionAllowed,
+  endSessionMutation,
+  requireSessionMutationReconciliation,
+  tryBeginSessionMutation,
+  useSessionMutationStore,
+} from './sessionMutationStore';
+
+describe('sessionMutationStore', () => {
+  beforeEach(() => {
+    useSessionMutationStore.setState({ mutations: new Map(), retiredTurnIds: new Map() });
+  });
+
+  it('allows only the edit rerun that owns the active lease to submit', () => {
+    const lease = tryBeginSessionMutation('session-1', 'edit-rerun', 'turn-7');
+    expect(lease).not.toBeNull();
+
+    expect(() => assertSessionSubmissionAllowed('session-1')).toThrow('history mutation');
+    expect(() => assertSessionSubmissionAllowed('session-1', 'wrong-lease')).toThrow(
+      'history mutation',
+    );
+    expect(() => assertSessionSubmissionAllowed('session-1', lease!.leaseId)).not.toThrow();
+
+    endSessionMutation(lease!);
+    expect(useSessionMutationStore.getState().mutations.has('session-1')).toBe(false);
+  });
+
+  it('does not release a reconciliation-required Session through normal lease cleanup', () => {
+    const lease = tryBeginSessionMutation('session-1', 'rollback', 'turn-7');
+    expect(lease).not.toBeNull();
+    requireSessionMutationReconciliation(lease!, 'reload failed');
+
+    endSessionMutation(lease!);
+
+    expect(useSessionMutationStore.getState().mutations.get('session-1')).toMatchObject({
+      phase: 'reconciliation_required',
+      reconciliationReason: 'reload failed',
+    });
+    expect(() => assertSessionSubmissionAllowed('session-1')).toThrow('must be reloaded');
+  });
+});
diff --git a/src/web-ui/src/flow_chat/store/sessionMutationStore.ts b/src/web-ui/src/flow_chat/store/sessionMutationStore.ts
new file mode 100644
index 0000000000..db5db87f95
--- /dev/null
+++ b/src/web-ui/src/flow_chat/store/sessionMutationStore.ts
@@ -0,0 +1,160 @@
+import { create } from 'zustand';
+
+export type SessionMutationKind = 'rollback' | 'edit-rerun';
+export type SessionMutationPhase = 'active' | 'reconciliation_required';
+
+export interface SessionMutationLease {
+  sessionId: string;
+  leaseId: string;
+  kind: SessionMutationKind;
+  targetTurnId: string;
+}
+
+export interface SessionMutation extends SessionMutationLease {
+  startedAt: number;
+  phase: SessionMutationPhase;
+  reconciliationReason?: string;
+}
+
+interface SessionMutationState {
+  mutations: ReadonlyMap<string, SessionMutation>;
+  retiredTurnIds: ReadonlyMap<string, ReadonlySet<string>>;
+  tryBegin: (
+    sessionId: string,
+    mutation: Pick<SessionMutation, 'kind' | 'targetTurnId'>,
+  ) => SessionMutationLease | null;
+  end: (lease: SessionMutationLease) => void;
+  requireReconciliation: (lease: SessionMutationLease, reason: string) => void;
+  completeReconciliation: (sessionId: string) => void;
+  markRetired: (sessionId: string, turnIds: Iterable<string>) => void;
+}
+
+let nextLeaseId = 0;
+
+export const useSessionMutationStore = create<SessionMutationState>((set, get) => ({
+  mutations: new Map(),
+  retiredTurnIds: new Map(),
+  tryBegin: (sessionId, mutation) => {
+    if (get().mutations.has(sessionId)) {
+      return null;
+    }
+    const lease: SessionMutationLease = {
+      sessionId,
+      leaseId: `session-mutation-${Date.now()}-${nextLeaseId++}`,
+      ...mutation,
+    };
+    const mutations = new Map(get().mutations);
+    mutations.set(sessionId, { ...lease, startedAt: Date.now(), phase: 'active' });
+    set({ mutations });
+    return lease;
+  },
+  end: lease => {
+    const current = get().mutations.get(lease.sessionId);
+    if (
+      !current
+      || current.leaseId !== lease.leaseId
+      || current.phase === 'reconciliation_required'
+    ) {
+      return;
+    }
+    const mutations = new Map(get().mutations);
+    mutations.delete(lease.sessionId);
+    set({ mutations });
+  },
+  requireReconciliation: (lease, reason) => {
+    const current = get().mutations.get(lease.sessionId);
+    if (!current || current.leaseId !== lease.leaseId) {
+      return;
+    }
+    const mutations = new Map(get().mutations);
+    mutations.set(lease.sessionId, {
+      ...current,
+      phase: 'reconciliation_required',
+      reconciliationReason: reason,
+    });
+    set({ mutations });
+  },
+  completeReconciliation: sessionId => {
+    const current = get().mutations.get(sessionId);
+    if (!current || current.phase !== 'reconciliation_required') {
+      return;
+    }
+    const mutations = new Map(get().mutations);
+    mutations.delete(sessionId);
+    set({ mutations });
+  },
+  markRetired: (sessionId, turnIds) => {
+    const nextSessionIds = new Set(get().retiredTurnIds.get(sessionId));
+    for (const turnId of turnIds) {
+      if (turnId) {
+        nextSessionIds.add(turnId);
+      }
+    }
+    if (nextSessionIds.size === 0) {
+      return;
+    }
+    const retiredTurnIds = new Map(get().retiredTurnIds);
+    retiredTurnIds.set(sessionId, nextSessionIds);
+    set({ retiredTurnIds });
+  },
+}));
+
+export function tryBeginSessionMutation(
+  sessionId: string,
+  kind: SessionMutationKind,
+  targetTurnId: string,
+): SessionMutationLease | null {
+  return useSessionMutationStore.getState().tryBegin(sessionId, { kind, targetTurnId });
+}
+
+export function assertSessionMutationLease(lease: SessionMutationLease): void {
+  const current = useSessionMutationStore.getState().mutations.get(lease.sessionId);
+  if (
+    !current
+    || current.leaseId !== lease.leaseId
+    || current.kind !== lease.kind
+    || current.targetTurnId !== lease.targetTurnId
+    || current.phase !== 'active'
+  ) {
+    throw new Error('Session history mutation lease is no longer active');
+  }
+}
+
+export function endSessionMutation(lease: SessionMutationLease): void {
+  useSessionMutationStore.getState().end(lease);
+}
+
+export function requireSessionMutationReconciliation(
+  lease: SessionMutationLease,
+  reason: string,
+): void {
+  useSessionMutationStore.getState().requireReconciliation(lease, reason);
+}
+
+export function completeSessionMutationReconciliation(sessionId: string): void {
+  useSessionMutationStore.getState().completeReconciliation(sessionId);
+}
+
+export function assertSessionSubmissionAllowed(
+  sessionId: string,
+  leaseId?: string,
+): void {
+  const current = useSessionMutationStore.getState().mutations.get(sessionId);
+  if (!current) {
+    return;
+  }
+  if (current.phase === 'reconciliation_required') {
+    throw new Error('Session history must be reloaded before submitting another message');
+  }
+  if (current.kind !== 'edit-rerun' || !leaseId || current.leaseId !== leaseId) {
+    throw new Error('Wait for the current Session history mutation to finish');
+  }
+}
+
+export function markSessionTurnsRetired(sessionId: string, turnIds: Iterable<string>): void {
+  useSessionMutationStore.getState().markRetired(sessionId, turnIds);
+}
+
+export function isSessionTurnRetired(sessionId: string, turnId: string): boolean {
+  return useSessionMutationStore.getState().retiredTurnIds.get(sessionId)?.has(turnId) === true;
+}
diff --git a/src/web-ui/src/flow_chat/tool-cards/AskUserQuestionCard.scss b/src/web-ui/src/flow_chat/tool-cards/AskUserQuestionCard.scss
index 344773af69..3d6c33bc45 100644
--- a/src/web-ui/src/flow_chat/tool-cards/AskUserQuestionCard.scss
+++ b/src/web-ui/src/flow_chat/tool-cards/AskUserQuestionCard.scss
@@ -16,7 +16,9 @@
   border: 1px solid var(--bf-appearance-token-border-base);
   background: var(--bf-appearance-token-color-bg-scene);
   backdrop-filter: blur(10px);
-  transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+  transition:
+    border-color 160ms ease,
+    box-shadow 180ms ease;
   overflow: hidden;
   position: relative;
 
@@ -195,7 +197,10 @@
   border: 1px solid var(--bf-appearance-token-border-base);
   border-radius: var(--bf-appearance-token-size-radius-md);
   cursor: pointer;
-  transition: all 0.15s ease;
+  transition:
+    background-color 150ms ease,
+    border-color 150ms ease,
+    opacity 150ms ease;
 
   &:hover:not(:has(input:disabled)) {
     background: var(--bf-appearance-token-element-bg-subtle);
@@ -245,7 +250,9 @@
     border: 1.5px solid var(--bf-appearance-token-border-base);
     border-radius: 50%;
     background: transparent;
-    transition: all 0.15s ease;
+    transition:
+      background-color 150ms ease,
+      border-color 150ms ease;
   }
 
   &::after {
@@ -257,8 +264,12 @@
     height: 6px;
     border-radius: 50%;
     background: transparent;
-    transition: all 0.15s ease;
-    transform: scale(0);
+    opacity: 0;
+    transform: scale(0.8);
+    transition:
+      background-color 150ms ease,
+      opacity 120ms cubic-bezier(0.23, 1, 0.32, 1),
+      transform 120ms cubic-bezier(0.23, 1, 0.32, 1);
   }
 
   input:checked + &::before {
@@ -267,6 +278,7 @@
 
   input:checked + &::after {
     background: var(--bf-appearance-token-color-text-primary);
+    opacity: 1;
     transform: scale(1);
   }
 
@@ -297,7 +309,9 @@
     border: 1.5px solid var(--bf-appearance-token-border-base);
     border-radius: 3px;
     background: transparent;
-    transition: all 0.15s ease;
+    transition:
+      background-color 150ms ease,
+      border-color 150ms ease;
   }
 
   &::after {
@@ -309,8 +323,12 @@
     height: 8px;
     border: solid transparent;
     border-width: 0 1.5px 1.5px 0;
-    transform: rotate(45deg) scale(0);
-    transition: all 0.15s ease;
+    opacity: 0;
+    transform: rotate(45deg) scale(0.8);
+    transition:
+      border-color 150ms ease,
+      opacity 120ms cubic-bezier(0.23, 1, 0.32, 1),
+      transform 120ms cubic-bezier(0.23, 1, 0.32, 1);
   }
 
   input:checked + &::before {
@@ -320,6 +338,7 @@
 
   input:checked + &::after {
     border-color: var(--bf-appearance-token-color-text-primary);
+    opacity: 1;
     transform: rotate(45deg) scale(1);
   }
 
@@ -420,7 +439,10 @@
   font-size: var(--bf-appearance-token-tool-card-action-font-size);
   color: var(--bf-appearance-token-color-text-primary);
   background: var(--bf-appearance-token-color-bg-tertiary);
-  transition: all 0.15s ease;
+  transition:
+    background-color 150ms ease,
+    border-color 150ms ease,
+    opacity 150ms ease;
   min-width: 0;
 
   &:focus {
@@ -453,7 +475,11 @@
   font-size: var(--bf-appearance-token-tool-card-action-font-size);
   font-weight: 500;
   cursor: pointer;
-  transition: all 0.15s ease;
+  transition:
+    scale 120ms cubic-bezier(0.23, 1, 0.32, 1),
+    background-color 150ms ease,
+    border-color 150ms ease,
+    opacity 150ms ease;
   white-space: nowrap;
 
   &:hover:not(:disabled) {
@@ -546,7 +572,6 @@
   margin-top: 0;
   padding-top: 12px;
   border-top: 1px solid var(--bf-appearance-token-border-base);
-  animation: expandDown 0.2s ease-out;
 
   .option-label {
     pointer-events: none;
@@ -584,10 +609,16 @@
 }
 
 .animate-spin {
-  animation: spin 1s linear infinite;
+  animation: ask-user-question-spin 1s linear infinite;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .animate-spin {
+    animation: none;
+  }
 }
 
-@keyframes spin {
+@keyframes ask-user-question-spin {
   from {
     transform: rotate(0deg);
   }
diff --git a/src/web-ui/src/flow_chat/tool-cards/AskUserQuestionCard.tsx b/src/web-ui/src/flow_chat/tool-cards/AskUserQuestionCard.tsx
index 51523a69f9..dddd50c3ec 100644
--- a/src/web-ui/src/flow_chat/tool-cards/AskUserQuestionCard.tsx
+++ b/src/web-ui/src/flow_chat/tool-cards/AskUserQuestionCard.tsx
@@ -125,8 +125,6 @@ export const AskUserQuestionCard: React.FC<ToolCardProps> = ({
     if (shouldCompactCompleted) {
       applyExpandedState(true, false, (nextExpanded) => {
         setShowCompletedSummary(!nextExpanded);
-      }, {
-        reason: 'auto',
       });
       return;
     }
diff --git a/src/web-ui/src/flow_chat/tool-cards/BaseToolCard.scss b/src/web-ui/src/flow_chat/tool-cards/BaseToolCard.scss
index 8f939dc376..e38c23c4c8 100644
--- a/src/web-ui/src/flow_chat/tool-cards/BaseToolCard.scss
+++ b/src/web-ui/src/flow_chat/tool-cards/BaseToolCard.scss
@@ -16,7 +16,9 @@
   border: 1px solid var(--bf-appearance-token-border-base);
   background: var(--bf-appearance-token-color-bg-scene);
   backdrop-filter: blur(10px);
-  transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+  transition:
+    border-color 160ms ease,
+    box-shadow 180ms ease;
   overflow: hidden;
   width: 100%;
   box-sizing: border-box;
@@ -58,7 +60,7 @@
       0 0 0 1px color-mix(in srgb, var(--bf-appearance-token-color-warning) 15%, transparent),
       0 0 12px color-mix(in srgb, var(--bf-appearance-token-color-warning) 20%, transparent),
       inset 0 0 8px color-mix(in srgb, var(--bf-appearance-token-color-warning) 5%, transparent);
-    animation: confirmationPulse 2s ease-in-out infinite;
+    animation: base-tool-card-confirmation-pulse 2s ease-in-out infinite;
     
     &:hover {
       border-color: var(--bf-appearance-token-color-warning);
@@ -92,7 +94,7 @@
     0 0 0 1px color-mix(in srgb, var(--bf-appearance-token-color-warning) 15%, transparent),
     0 0 12px color-mix(in srgb, var(--bf-appearance-token-color-warning) 20%, transparent),
     inset 0 0 8px color-mix(in srgb, var(--bf-appearance-token-color-warning) 5%, transparent);
-  animation: confirmationPulse 2s ease-in-out infinite;
+  animation: base-tool-card-confirmation-pulse 2s ease-in-out infinite;
 }
 
 .flow-tool-card-wrapper--permission-pending > :first-child:hover {
@@ -264,20 +266,8 @@
   }
 }
 
-/* ========== Expand animation ========== */
-@keyframes expandDown {
-  from {
-    opacity: 0;
-    transform: translateY(-4px);
-  }
-  to {
-    opacity: 1;
-    transform: translateY(0);
-  }
-}
-
 /* ========== Confirmation state pulse animation ========== */
-@keyframes confirmationPulse {
+@keyframes base-tool-card-confirmation-pulse {
   0%, 100% {
     box-shadow: 
       0 0 0 1px color-mix(in srgb, var(--bf-appearance-token-color-warning) 15%, transparent),
@@ -292,6 +282,13 @@
   }
 }
 
+@media (prefers-reduced-motion: reduce) {
+  .base-tool-card-wrapper.requires-confirmation,
+  .flow-tool-card-wrapper--permission-pending > :first-child {
+    animation: none;
+  }
+}
+
 /* ========== Different state styles ========== */
 
 /* Completed state */
@@ -334,10 +331,10 @@
 .base-tool-card-wrapper--loading-shimmer .tool-card-icon-marks,
 .base-tool-card-wrapper--loading-shimmer .tool-card-action,
 .base-tool-card-wrapper--loading-shimmer .tool-card-content {
-  animation: tool-card-text-fade 2.2s ease-in-out infinite;
+  animation: base-tool-card-loading-fade 2.2s ease-in-out infinite;
 }
 
-@keyframes tool-card-text-fade {
+@keyframes base-tool-card-loading-fade {
   0%, 100% {
     opacity: 1;
   }
diff --git a/src/web-ui/src/flow_chat/tool-cards/CodeReviewToolCard.scss b/src/web-ui/src/flow_chat/tool-cards/CodeReviewToolCard.scss
index 454943b3d7..f136cb6c27 100644
--- a/src/web-ui/src/flow_chat/tool-cards/CodeReviewToolCard.scss
+++ b/src/web-ui/src/flow_chat/tool-cards/CodeReviewToolCard.scss
@@ -64,7 +64,10 @@
   background: transparent;
   color: var(--bf-appearance-token-color-text-muted);
   cursor: pointer;
-  transition: all 0.2s ease;
+  transition:
+    scale 120ms cubic-bezier(0.23, 1, 0.32, 1),
+    background-color 160ms ease,
+    color 160ms ease;
   flex-shrink: 0;
 
   &:hover {
@@ -544,7 +547,9 @@
     padding: 10px;
     font-size: var(--bf-appearance-token-tool-card-action-font-size);
     line-height: var(--bf-appearance-token-flowchat-support-line-height);
-    transition: all 0.2s ease;
+    transition:
+      background-color 160ms ease,
+      border-color 160ms ease;
     position: relative;
     overflow: hidden;
 
@@ -768,7 +773,9 @@
         padding: 10px;
         font-size: var(--bf-appearance-token-tool-card-action-font-size);
         line-height: var(--bf-appearance-token-flowchat-support-line-height);
-        transition: all 0.2s ease;
+        transition:
+          background-color 160ms ease,
+          border-color 160ms ease;
         position: relative;
         overflow: hidden;
 
diff --git a/src/web-ui/src/flow_chat/tool-cards/CodeReviewToolCard.tsx b/src/web-ui/src/flow_chat/tool-cards/CodeReviewToolCard.tsx
index 0f4859c1f9..ee99f746c4 100644
--- a/src/web-ui/src/flow_chat/tool-cards/CodeReviewToolCard.tsx
+++ b/src/web-ui/src/flow_chat/tool-cards/CodeReviewToolCard.tsx
@@ -41,6 +41,7 @@ import { CodeReviewReportExportActions } from './CodeReviewReportExportActions';
 import { DEEP_REVIEW_SCROLL_TO_EVENT, type DeepReviewScrollToRequest } from '../events/flowchatNavigation';
 import { globalEventBus } from '@/infrastructure/event-bus';
 import { normalizeDecisionEntry, type DecisionContext } from '../utils/codeReviewReport';
+import { getMotionAwareScrollBehavior } from '../utils/motionPreference';
 import type { ReviewTeamRunManifest } from '@/shared/services/reviewTeamService';
 import './CodeReviewToolCard.scss';
 
@@ -458,7 +459,10 @@ export const CodeReviewToolCard: React.FC<ToolCardProps> = React.memo(({
             anchor = document.getElementById(`review-remediation-${request.groupId}-${request.groupIndex}`);
           }
           if (anchor) {
-            anchor.scrollIntoView({ behavior: 'smooth', block: 'center' });
+            anchor.scrollIntoView({
+              behavior: getMotionAwareScrollBehavior('smooth'),
+              block: 'center',
+            });
             anchor.classList.add('is-highlighted');
             setTimeout(() => anchor!.classList.remove('is-highlighted'), 2000);
           }
diff --git a/src/web-ui/src/flow_chat/tool-cards/CompactToolCard.scss b/src/web-ui/src/flow_chat/tool-cards/CompactToolCard.scss
index efa764bfbc..5cac85e42f 100644
--- a/src/web-ui/src/flow_chat/tool-cards/CompactToolCard.scss
+++ b/src/web-ui/src/flow_chat/tool-cards/CompactToolCard.scss
@@ -95,13 +95,13 @@
 /* E — action + content breathe; keep tool-identifier-icon steady */
 .compact-tool-card-wrapper--loading-shimmer .compact-card-action,
 .compact-tool-card-wrapper--loading-shimmer .compact-card-content {
-  animation: tool-card-text-fade 2.2s ease-in-out infinite;
+  animation: compact-tool-card-loading-fade 2.2s ease-in-out infinite;
 }
 
 /* Legacy compact cards that still use status icon as left icon (no .tool-identifier-icon child):
    fade the icon-marks too for the original shimmer effect. */
 .compact-tool-card-wrapper--loading-shimmer .tool-card-icon-marks:not(:has(.tool-identifier-icon)) {
-  animation: tool-card-text-fade 2.2s ease-in-out infinite;
+  animation: compact-tool-card-loading-fade 2.2s ease-in-out infinite;
 }
 
 /* ========== Card body - transparent, no border ========== */
@@ -179,7 +179,7 @@
   line-height: var(--bf-appearance-token-tool-card-action-line-height);
   font-weight: var(--bf-appearance-token-font-weight-medium);
   color: var(--bf-appearance-token-color-text-muted);
-  transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
+  transition: color 160ms ease;
   flex-shrink: 0;
 }
 
@@ -389,7 +389,9 @@
   .inline-icon {
     flex-shrink: 0;
     color: var(--bf-appearance-token-color-text-muted);
-    transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
+    transition:
+      transform 120ms cubic-bezier(0.23, 1, 0.32, 1),
+      color 160ms ease;
   }
 }
 
@@ -432,19 +434,7 @@
   }
 }
 
-/* ========== Expand animation ========== */
-@keyframes expandDown {
-  from {
-    opacity: 0;
-    transform: translateY(-10px);
-  }
-  to {
-    opacity: 1;
-    transform: translateY(0);
-  }
-}
-
-@keyframes tool-card-text-fade {
+@keyframes compact-tool-card-loading-fade {
   0%, 100% {
     opacity: 1;
   }
@@ -452,3 +442,11 @@
     opacity: 0.68;
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .compact-tool-card-wrapper--loading-shimmer .compact-card-action,
+  .compact-tool-card-wrapper--loading-shimmer .compact-card-content,
+  .compact-tool-card-wrapper--loading-shimmer .tool-card-icon-marks:not(:has(.tool-identifier-icon)) {
+    animation: none;
+  }
+}
diff --git a/src/web-ui/src/flow_chat/tool-cards/CompactToolCard.tsx b/src/web-ui/src/flow_chat/tool-cards/CompactToolCard.tsx
index 83705a812c..f94e62637e 100644
--- a/src/web-ui/src/flow_chat/tool-cards/CompactToolCard.tsx
+++ b/src/web-ui/src/flow_chat/tool-cards/CompactToolCard.tsx
@@ -8,10 +8,11 @@
  * - Simple gray style, text brightens on hover
  */
 
-import React, { ReactNode } from 'react';
+import React, { ReactNode, useEffect, useRef, useState } from 'react';
 import { shouldIgnoreCardToggleClick } from '@/shared/utils/textSelection';
 import { BaseToolCard, type BaseToolCardProps } from './BaseToolCard';
 import { SmoothHeightCollapse } from '../components/modern/SmoothHeightCollapse';
+import { FLOWCHAT_COLLAPSE_DURATION_MS } from '../components/modern/flowChatCollapseMotion';
 import { ToolCardIconSlot } from './ToolCardIconSlot';
 import { ToolCardStatusIcon } from './ToolCardStatusIcon';
 import type { ToolCardHeaderAffordanceKind } from './ToolCardHeaderLayoutContext';
@@ -67,11 +68,53 @@ export const CompactToolCard: React.FC<CompactToolCardProps> = ({
     status === 'running' ||
     status === 'analyzing';
 
-  if (isExpanded && expandedContent) {
+  const hasExpandedContent = Boolean(expandedContent);
+  const collapseTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const [useExpandedShell, setUseExpandedShell] = useState(
+    Boolean(isExpanded && hasExpandedContent),
+  );
+
+  useEffect(() => {
+    if (collapseTimerRef.current !== null) {
+      clearTimeout(collapseTimerRef.current);
+      collapseTimerRef.current = null;
+    }
+
+    const isCurrentlyExpanded = Boolean(isExpanded && hasExpandedContent);
+
+    if (isCurrentlyExpanded) {
+      setUseExpandedShell(true);
+      return;
+    }
+
+    if (!hasExpandedContent) {
+      setUseExpandedShell(false);
+      return;
+    }
+
+    if (useExpandedShell && hasExpandedContent) {
+      collapseTimerRef.current = setTimeout(() => {
+        collapseTimerRef.current = null;
+        setUseExpandedShell(false);
+      }, FLOWCHAT_COLLAPSE_DURATION_MS);
+    }
+  }, [hasExpandedContent, isExpanded, useExpandedShell]);
+
+  useEffect(() => () => {
+    if (collapseTimerRef.current !== null) {
+      clearTimeout(collapseTimerRef.current);
+    }
+  }, []);
+
+  const shouldRenderExpandedShell = Boolean(
+    useExpandedShell || (isExpanded && hasExpandedContent),
+  );
+
+  if (shouldRenderExpandedShell) {
     return (
       <BaseToolCard
         status={status}
-        isExpanded
+        isExpanded={isExpanded}
         onClick={handleWrapperClick}
         className={`compact-tool-card-wrapper--expanded-card ${className}`.trim()}
         header={header}
diff --git a/src/web-ui/src/flow_chat/tool-cards/CreatePlanDisplay.scss b/src/web-ui/src/flow_chat/tool-cards/CreatePlanDisplay.scss
index c9d71830ac..66f5c2fdc7 100644
--- a/src/web-ui/src/flow_chat/tool-cards/CreatePlanDisplay.scss
+++ b/src/web-ui/src/flow_chat/tool-cards/CreatePlanDisplay.scss
@@ -153,7 +153,12 @@
       background: transparent;
       color: var(--bf-appearance-token-color-text-muted);
       cursor: pointer;
-      transition: all 0.15s ease;
+      transition:
+        scale 120ms cubic-bezier(0.23, 1, 0.32, 1),
+        background-color 150ms ease,
+        border-color 150ms ease,
+        color 150ms ease,
+        opacity 150ms ease;
 
       &:hover:not(:disabled) {
         border-color: color-mix(in srgb, var(--bf-appearance-token-color-warning) 35%, transparent);
@@ -178,7 +183,7 @@
 
     &--loading-shimmer {
       .file-name {
-        animation: tool-card-text-fade 2.2s ease-in-out infinite;
+        animation: create-plan-loading-fade 2.2s ease-in-out infinite;
       }
     }
   }
@@ -223,7 +228,11 @@
       background: transparent;
       color: var(--bf-appearance-token-color-text-muted);
       cursor: pointer;
-      transition: all 0.15s ease;
+      transition:
+        scale 120ms cubic-bezier(0.23, 1, 0.32, 1),
+        background-color 150ms ease,
+        border-color 150ms ease,
+        color 150ms ease;
 
       svg {
         width: 22px;
@@ -379,7 +388,11 @@
       border: none;
       border-radius: 4px;
       cursor: pointer;
-      transition: all 0.15s ease;
+      transition:
+        scale 120ms cubic-bezier(0.23, 1, 0.32, 1),
+        background-color 150ms ease,
+        color 150ms ease,
+        opacity 150ms ease;
 
       &:hover:not(:disabled) {
         color: var(--bf-appearance-token-color-text-primary);
@@ -408,7 +421,10 @@
       border: none;
       border-radius: 4px;
       cursor: pointer;
-      transition: all 0.15s ease;
+      transition:
+        transform 120ms cubic-bezier(0.23, 1, 0.32, 1),
+        box-shadow 180ms ease,
+        opacity 150ms ease;
       box-shadow: 0 1px 2px var(--bf-appearance-token-color-overlay-black-12);
 
       &:hover:not(:disabled) {
@@ -464,7 +480,13 @@
   }
 }
 
-@keyframes tool-card-text-fade {
+@media (prefers-reduced-motion: reduce) {
+  .create-plan-display--loading-shimmer .create-plan-header--loading-shimmer .file-name {
+    animation: none;
+  }
+}
+
+@keyframes create-plan-loading-fade {
   0%, 100% {
     opacity: 1;
   }
diff --git a/src/web-ui/src/flow_chat/tool-cards/DefaultToolCard.scss b/src/web-ui/src/flow_chat/tool-cards/DefaultToolCard.scss
index e568dcb978..fe70b2abb0 100644
--- a/src/web-ui/src/flow_chat/tool-cards/DefaultToolCard.scss
+++ b/src/web-ui/src/flow_chat/tool-cards/DefaultToolCard.scss
@@ -157,7 +157,12 @@
     font-size: var(--bf-appearance-token-tool-card-action-font-size);
     font-weight: 600;
     cursor: pointer;
-    transition: all 0.2s ease;
+    transition:
+      scale 120ms cubic-bezier(0.23, 1, 0.32, 1),
+      background-color 160ms ease,
+      border-color 160ms ease,
+      color 160ms ease,
+      opacity 160ms ease;
   }
 
   .default-tool-card__button:disabled {
@@ -202,3 +207,9 @@
     }
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .default-tool-card.requires-confirmation .compact-tool-card {
+    animation: none;
+  }
+}
diff --git a/src/web-ui/src/flow_chat/tool-cards/ExecProcessToolCardView.test.tsx b/src/web-ui/src/flow_chat/tool-cards/ExecProcessToolCardView.test.tsx
index 22788d9fc5..185657da00 100644
--- a/src/web-ui/src/flow_chat/tool-cards/ExecProcessToolCardView.test.tsx
+++ b/src/web-ui/src/flow_chat/tool-cards/ExecProcessToolCardView.test.tsx
@@ -253,5 +253,16 @@ describe('ExecProcessToolCardView', () => {
       vi.advanceTimersByTime(1);
     });
     expect(container.querySelector('.base-tool-card.expanded')).toBeNull();
+    expect(container.querySelector('.terminal-result-container')).not.toBeNull();
+
+    act(() => {
+      vi.advanceTimersByTime(299);
+    });
+    expect(container.querySelector('.terminal-result-container')).not.toBeNull();
+
+    act(() => {
+      vi.advanceTimersByTime(1);
+    });
+    expect(container.querySelector('.terminal-result-container')).toBeNull();
   });
 });
diff --git a/src/web-ui/src/flow_chat/tool-cards/ExecProcessToolCardView.tsx b/src/web-ui/src/flow_chat/tool-cards/ExecProcessToolCardView.tsx
index f63c1bfbed..db3e1b0fc8 100644
--- a/src/web-ui/src/flow_chat/tool-cards/ExecProcessToolCardView.tsx
+++ b/src/web-ui/src/flow_chat/tool-cards/ExecProcessToolCardView.tsx
@@ -11,7 +11,7 @@ import { ToolCardCopyAction, ToolCardHeaderActions } from './ToolCardHeaderActio
 import { CopyableTextPreview } from '../components/CopyableTextPreview';
 import { ToolTimeoutIndicator } from './ToolTimeoutIndicator';
 import { DotMatrixLoader } from '../../component-library';
-import { useToolCardHeightContract, type ToolCardCollapseReason } from './useToolCardHeightContract';
+import { useToolCardHeightContract } from './useToolCardHeightContract';
 import { useToolCardCompletionGracePeriod } from './useToolCardCompletionGracePeriod';
 import { formatSessionViewPreviewText } from '../utils/sessionViewPreview';
 import './ExecProcessToolCard.scss';
@@ -209,23 +209,17 @@ export const ExecProcessToolCardView: React.FC<ExecProcessToolCardViewProps> = (
       !userToggledRef.current,
   });
 
-  const applyExecExpandedState = useCallback((
-    nextExpanded: boolean,
-    options?: { reason?: ToolCardCollapseReason },
-  ) => {
+  const applyExecExpandedState = useCallback((nextExpanded: boolean) => {
     if (nextExpanded === isExpanded) {
       return;
     }
 
-    applyExpandedState(isExpanded, nextExpanded, setIsExpandedState, {
-      reason: options?.reason ?? 'manual',
-      onExpand,
-    });
+    applyExpandedState(isExpanded, nextExpanded, setIsExpandedState, { onExpand });
   }, [applyExpandedState, isExpanded, onExpand]);
 
   const toggleExpanded = useCallback(() => {
     userToggledRef.current = true;
-    applyExecExpandedState(!isExpanded, { reason: 'manual' });
+    applyExecExpandedState(!isExpanded);
   }, [applyExecExpandedState, isExpanded]);
 
   useLayoutEffect(() => {
@@ -236,7 +230,7 @@ export const ExecProcessToolCardView: React.FC<ExecProcessToolCardViewProps> = (
     const keepTailPreview = isCollapsedStatus(status) && beginCompletionPreview();
     const nextExpanded = getAutoExpandedStateForStatus(status, isLastItem, keepTailPreview);
     if (nextExpanded !== null) {
-      applyExecExpandedState(nextExpanded, { reason: 'auto' });
+      applyExecExpandedState(nextExpanded);
     }
   }, [
     applyExecExpandedState,
@@ -419,10 +413,6 @@ export const ExecProcessToolCardView: React.FC<ExecProcessToolCardViewProps> = (
   );
 
   const renderExpandedContent = () => {
-    if (!isExpanded) {
-      return null;
-    }
-
     if (status === 'completed') {
       return (
         <div data-bf-component="exec-process-tool-card" data-bf-part="result" className="terminal-result-container">
@@ -520,7 +510,10 @@ export const ExecProcessToolCardView: React.FC<ExecProcessToolCardViewProps> = (
         onClick={handleCardClick}
         className={`terminal-tool-card exec-process-tool-card${!isExpanded ? ' terminal-tool-card--compact-truncated' : ''}`}
         header={renderHeader()}
-        expandedContent={isExpanded ? renderExpandedContent() : null}
+        // Keep the previous result mounted while SmoothHeightCollapse animates
+        // from its measured height to zero. Removing it in the same render as
+        // isExpanded=false makes the collapse jump instead of animate.
+        expandedContent={renderExpandedContent()}
         errorContent={renderErrorContent()}
         isFailed={status === 'error'}
         requiresConfirmation={status === 'pending_confirmation'}
diff --git a/src/web-ui/src/flow_chat/tool-cards/FileOperationToolCard.scss b/src/web-ui/src/flow_chat/tool-cards/FileOperationToolCard.scss
index b14c80b2df..8546e0af65 100644
--- a/src/web-ui/src/flow_chat/tool-cards/FileOperationToolCard.scss
+++ b/src/web-ui/src/flow_chat/tool-cards/FileOperationToolCard.scss
@@ -273,7 +273,7 @@
   align-items: center;
   gap: 4px;
   color: var(--bf-appearance-token-color-text-muted);
-  transition: all 0.2s ease;
+  transition: color 160ms ease;
   flex-shrink: 0;
   cursor: pointer;
 
@@ -431,3 +431,9 @@
     box-shadow: 0 2px 8px var(--bf-appearance-token-color-error-bg);
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .params-streaming-indicator {
+    animation: none;
+  }
+}
diff --git a/src/web-ui/src/flow_chat/tool-cards/FileOperationToolCard.tsx b/src/web-ui/src/flow_chat/tool-cards/FileOperationToolCard.tsx
index ffc0cf22dc..034f235963 100644
--- a/src/web-ui/src/flow_chat/tool-cards/FileOperationToolCard.tsx
+++ b/src/web-ui/src/flow_chat/tool-cards/FileOperationToolCard.tsx
@@ -2,15 +2,9 @@
  * File operation tool card - refactored based on BaseToolCard
  * Supports Write/Edit/Delete file operations
  *
- * Height-stability contract:
- * - Any state-driven height change must go through
- *   `useToolCardHeightContract.applyExpandedState(...)`.
- * - Any status/render-path change that removes expanded content without
- *   toggling local expand state must dispatch
- *   `flowchat:tool-card-collapse-intent` before the shrink happens.
- * - If preview/result variants stop sharing roughly the same visual height in
- *   the future, treat that as another shrink path and protect it explicitly
- *   instead of relying on `VirtualMessageList` fallback compensation.
+ * Card height changes reflow naturally. Expanded-state changes use
+ * `useToolCardHeightContract.applyExpandedState(...)` only to notify the virtualizer
+ * that it should remeasure the card after the transition.
  */
 
 import React, { useEffect, useCallback, useMemo, useState, useRef, useLayoutEffect, useSyncExternalStore } from 'react';
@@ -142,7 +136,6 @@ export const FileOperationToolCard: React.FC<FileOperationToolCardProps> = ({
   const {
     cardRootRef,
     applyExpandedState: applyHeightContractExpandedState,
-    dispatchCollapseIntent,
     dispatchToolCardToggle,
   } = useToolCardHeightContract({
     toolId,
@@ -399,19 +392,14 @@ export const FileOperationToolCard: React.FC<FileOperationToolCardProps> = ({
       isContentExpanded,
       nextExpanded,
       setIsContentExpanded,
-      { reason },
     );
   }, [applyHeightContractExpandedState, isContentExpanded]);
 
-  const applyErrorExpandedState = useCallback((
-    nextExpanded: boolean,
-    reason: 'manual' | 'auto',
-  ) => {
+  const applyErrorExpandedState = useCallback((nextExpanded: boolean) => {
     applyHeightContractExpandedState(
       isErrorExpanded,
       nextExpanded,
       setIsErrorExpanded,
-      { reason },
     );
   }, [applyHeightContractExpandedState, isErrorExpanded]);
 
@@ -588,13 +576,9 @@ export const FileOperationToolCard: React.FC<FileOperationToolCardProps> = ({
       return;
     }
 
-    dispatchCollapseIntent('auto', {
-      filePath: currentFilePath || null,
-    });
     dispatchToolCardToggle();
   }, [
     currentFilePath,
-    dispatchCollapseIntent,
     dispatchToolCardToggle,
     isContentExpanded,
     status,
@@ -706,7 +690,7 @@ export const FileOperationToolCard: React.FC<FileOperationToolCardProps> = ({
     }
     
     if (isFailed) {
-      applyErrorExpandedState(!isErrorExpanded, 'manual');
+      applyErrorExpandedState(!isErrorExpanded);
       return;
     }
 
diff --git a/src/web-ui/src/flow_chat/tool-cards/MCPToolDisplay.scss b/src/web-ui/src/flow_chat/tool-cards/MCPToolDisplay.scss
index d68bcf58fb..12736c0b36 100644
--- a/src/web-ui/src/flow_chat/tool-cards/MCPToolDisplay.scss
+++ b/src/web-ui/src/flow_chat/tool-cards/MCPToolDisplay.scss
@@ -164,7 +164,11 @@
     background: transparent;
     cursor: pointer;
     border-radius: 4px;
-    transition: all 0.2s ease;
+    transition:
+      scale 120ms cubic-bezier(0.23, 1, 0.32, 1),
+      background-color 160ms ease,
+      color 160ms ease,
+      opacity 160ms ease;
     
     &:disabled {
       opacity: 0.4;
diff --git a/src/web-ui/src/flow_chat/tool-cards/MCPToolDisplay.tsx b/src/web-ui/src/flow_chat/tool-cards/MCPToolDisplay.tsx
index 5b5d238d92..6d895af64d 100644
--- a/src/web-ui/src/flow_chat/tool-cards/MCPToolDisplay.tsx
+++ b/src/web-ui/src/flow_chat/tool-cards/MCPToolDisplay.tsx
@@ -252,9 +252,7 @@ export const MCPToolDisplay: React.FC<ToolCardProps> = ({
   // Auto-expand when MCP App UI is ready so user sees the interactive UI immediately
   useLayoutEffect(() => {
     if (mcpAppState?.html && !isExpanded) {
-      applyExpandedState(isExpanded, true, setIsExpanded, {
-        reason: 'auto',
-      });
+      applyExpandedState(isExpanded, true, setIsExpanded);
     }
   }, [applyExpandedState, isExpanded, mcpAppState?.html]);
 
diff --git a/src/web-ui/src/flow_chat/tool-cards/ModelThinkingDisplay.tsx b/src/web-ui/src/flow_chat/tool-cards/ModelThinkingDisplay.tsx
index 4dc636a31b..1dc67f74ce 100644
--- a/src/web-ui/src/flow_chat/tool-cards/ModelThinkingDisplay.tsx
+++ b/src/web-ui/src/flow_chat/tool-cards/ModelThinkingDisplay.tsx
@@ -14,6 +14,14 @@ import type { FlowThinkingItem } from '../types/flow-chat';
 import { useTypewriter } from '../hooks/useTypewriter';
 import { useReportTypewriterReveal } from '../hooks/typewriterRevealGateContext';
 import { useToolCardHeightContract } from './useToolCardHeightContract';
+import {
+  nextEasedScrollTopPx,
+  shouldEaseTailFollow,
+} from '../utils/flowChatTailEase';
+import {
+  isTailFollowDiagnosticsEnabled,
+  noteTailFollowStep,
+} from '@/infrastructure/diagnostics/flowChatTailFollowDiagnostics';
 import { Markdown } from '@/component-library/components/Markdown/Markdown';
 import './ModelThinkingDisplay.scss';
 
@@ -21,12 +29,14 @@ interface ModelThinkingDisplayProps {
   thinkingItem: FlowThinkingItem;
   /** Whether this is the last item in the current round. */
   isLastItem?: boolean;
+  forceExpanded?: boolean;
   displayContext?: 'default' | 'subagent-projection';
 }
 
 export const ModelThinkingDisplay: React.FC<ModelThinkingDisplayProps> = ({
   thinkingItem,
   isLastItem = true,
+  forceExpanded = false,
   displayContext = 'default',
 }) => {
   const { t } = useTranslation('flow-chat');
@@ -35,15 +45,18 @@ export const ModelThinkingDisplay: React.FC<ModelThinkingDisplayProps> = ({
   const shouldFollowTailRef = useRef(true);
   const tailFollowPauseVersionRef = useRef(0);
   const tailFollowUserPauseUntilMsRef = useRef(0);
+  /** Frame the follow has booked, and the sign that it is still travelling. */
+  const tailFollowFrameRef = useRef<number | null>(null);
   const touchScrollStartYRef = useRef<number | null>(null);
 
   const isActive = isStreaming || status === 'streaming';
   const { displayText: displayContent, isRevealing } = useTypewriter(content, isActive);
   useReportTypewriterReveal(thinkingItem.id, isRevealing);
-  const shouldDefaultExpanded =
+  const shouldDefaultExpanded = forceExpanded || (
     displayContext === 'subagent-projection'
       ? isActive || isLastItem
-      : isLastItem;
+      : isLastItem
+  );
 
   const [isExpanded, setIsExpanded] = useState(shouldDefaultExpanded);
   const userToggledRef = useRef(false);
@@ -55,9 +68,7 @@ export const ModelThinkingDisplay: React.FC<ModelThinkingDisplayProps> = ({
   useLayoutEffect(() => {
     if (userToggledRef.current) return;
     if (isExpanded !== shouldDefaultExpanded) {
-      applyExpandedState(isExpanded, shouldDefaultExpanded, setIsExpanded, {
-        reason: 'auto',
-      });
+      applyExpandedState(isExpanded, shouldDefaultExpanded, setIsExpanded);
     }
   }, [applyExpandedState, isExpanded, shouldDefaultExpanded]);
 
@@ -74,23 +85,74 @@ export const ModelThinkingDisplay: React.FC<ModelThinkingDisplayProps> = ({
     el.scrollHeight - el.scrollTop - el.clientHeight
   ), []);
 
-  const scrollThinkingToBottom = useCallback((expectedPauseVersion?: number) => {
-    const el = contentRef.current;
-    if (!el) return;
-    if (
-      expectedPauseVersion !== undefined &&
-      expectedPauseVersion !== tailFollowPauseVersionRef.current
-    ) {
-      return;
-    }
-    if (!shouldFollowTailRef.current) {
-      return;
-    }
+  const stopTailFollow = useCallback(() => {
+    if (tailFollowFrameRef.current === null) return;
+    cancelAnimationFrame(tailFollowFrameRef.current);
+    tailFollowFrameRef.current = null;
+  }, []);
+
+  /**
+   * Follow the tail across the frames it is given, rather than in one write.
+   *
+   * The card's box stops growing at its `max-height` and everything after that
+   * happens inside it, so this moves a scroll offset and no layout outside the
+   * card — which is why it can afford to run every frame where the message list
+   * cannot. Below that height it snaps, because easing there would mean easing
+   * a height and charging the virtualizer for each step.
+   *
+   * The pause version is captured for the whole run: a reader who scrolls up
+   * mid-follow bumps it, and the next frame stands down rather than dragging
+   * them back. A call arriving while a run is in flight is ignored — the run
+   * re-reads its target every frame and has already seen what prompted it.
+   */
+  const scheduleTailFollow = useCallback((expectedPauseVersion: number) => {
+    if (tailFollowFrameRef.current !== null) return;
+
+    const runFrame = () => {
+      tailFollowFrameRef.current = null;
+      const el = contentRef.current;
+      if (!el) return;
+      if (expectedPauseVersion !== tailFollowPauseVersionRef.current) return;
+      if (!shouldFollowTailRef.current) return;
+
+      const beforePx = el.scrollTop;
+      const targetPx = el.scrollHeight - el.clientHeight;
+      const step = shouldEaseTailFollow({
+        scrollHeightPx: el.scrollHeight,
+        clientHeightPx: el.clientHeight,
+      })
+        ? nextEasedScrollTopPx(beforePx, targetPx)
+        : { offsetPx: targetPx, outcome: 'snapped' as const };
+
+      el.scrollTop = step.offsetPx;
+      // Read back rather than taken from the step: the browser clamps to the
+      // scrollable range, and a platform without fractional scroll offsets
+      // rounds the last part of an ease away entirely. Believing the step there
+      // would book frames forever over a fraction of a pixel nobody can see.
+      const movedPx = el.scrollTop - beforePx;
+      shouldFollowTailRef.current = true;
+      if (step.outcome === 'eased' && movedPx !== 0) {
+        tailFollowFrameRef.current = requestAnimationFrame(runFrame);
+      }
 
-    el.scrollTop = el.scrollHeight;
-    shouldFollowTailRef.current = true;
+      if (isTailFollowDiagnosticsEnabled()) {
+        noteTailFollowStep('thinking', {
+          stepPx: movedPx,
+          lagPx: targetPx - beforePx,
+          // Below the card's `max-height` the box is still growing, so each of
+          // these steps also costs the list a re-measure. Above it, none do.
+          innerScroll: el.scrollHeight > el.clientHeight,
+          snapped: step.outcome === 'snapped',
+        });
+      }
+    };
+
+    tailFollowFrameRef.current = requestAnimationFrame(runFrame);
   }, []);
 
+  /** A follow in flight outlives neither the card nor its collapse. */
+  useEffect(() => stopTailFollow, [isExpanded, stopTailFollow]);
+
   const pauseTailFollowForUserScroll = useCallback(() => {
     shouldFollowTailRef.current = false;
     tailFollowPauseVersionRef.current += 1;
@@ -109,17 +171,14 @@ export const ModelThinkingDisplay: React.FC<ModelThinkingDisplayProps> = ({
       }
       const shouldScroll = shouldFollowTailRef.current || (wasNearBottom && !userPauseActive);
       if (shouldScroll) {
-        const scheduledPauseVersion = tailFollowPauseVersionRef.current;
-        requestAnimationFrame(() => {
-          scrollThinkingToBottom(scheduledPauseVersion);
-        });
+        scheduleTailFollow(tailFollowPauseVersionRef.current);
       }
     }
   }, [
     displayContent,
     getThinkingScrollGap,
     isExpanded,
-    scrollThinkingToBottom,
+    scheduleTailFollow,
   ]);
 
   useEffect(() => {
@@ -130,10 +189,7 @@ export const ModelThinkingDisplay: React.FC<ModelThinkingDisplayProps> = ({
 
     const observer = new ResizeObserver(() => {
       if (isActive && shouldFollowTailRef.current) {
-        const scheduledPauseVersion = tailFollowPauseVersionRef.current;
-        requestAnimationFrame(() => {
-          scrollThinkingToBottom(scheduledPauseVersion);
-        });
+        scheduleTailFollow(tailFollowPauseVersionRef.current);
       }
     });
 
@@ -144,7 +200,7 @@ export const ModelThinkingDisplay: React.FC<ModelThinkingDisplayProps> = ({
     }
 
     return () => observer.disconnect();
-  }, [isActive, isExpanded, scrollThinkingToBottom]);
+  }, [isActive, isExpanded, scheduleTailFollow]);
 
   // Scroll-state detection for fade gradients.
   const [scrollState, setScrollState] = useState({ hasScroll: false, atTop: true, atBottom: true });
@@ -156,7 +212,16 @@ export const ModelThinkingDisplay: React.FC<ModelThinkingDisplayProps> = ({
     const nextScrollState = {
       hasScroll: el.scrollHeight > el.clientHeight,
       atTop: el.scrollTop <= 5,
-      atBottom: gap <= 5,
+      /**
+       * A follow still travelling counts as being at the bottom.
+       *
+       * The bottom fade means "there is more below that you have not seen". An
+       * eased follow rides a little behind the tail by design, and what it is
+       * behind is arriving on its own — fading that would put a gradient under
+       * every streaming thinking card, which is the opposite of what the fade
+       * is for.
+       */
+      atBottom: gap <= 5 || tailFollowFrameRef.current !== null,
     };
     if (
       nextScrollState.atBottom &&
@@ -164,11 +229,19 @@ export const ModelThinkingDisplay: React.FC<ModelThinkingDisplayProps> = ({
     ) {
       shouldFollowTailRef.current = true;
     }
-    setScrollState({
-      hasScroll: nextScrollState.hasScroll,
-      atTop: nextScrollState.atTop,
-      atBottom: nextScrollState.atBottom,
-    });
+    // Scroll events arrive every frame once the follow is eased, and each one
+    // that changes nothing would still re-render the card.
+    setScrollState((current) => (
+      current.hasScroll === nextScrollState.hasScroll &&
+      current.atTop === nextScrollState.atTop &&
+      current.atBottom === nextScrollState.atBottom
+        ? current
+        : {
+          hasScroll: nextScrollState.hasScroll,
+          atTop: nextScrollState.atTop,
+          atBottom: nextScrollState.atBottom,
+        }
+    ));
   }, [getThinkingScrollGap]);
 
   useEffect(() => {
diff --git a/src/web-ui/src/flow_chat/tool-cards/README.md b/src/web-ui/src/flow_chat/tool-cards/README.md
index 99cb1f9e44..1fca399e6c 100644
--- a/src/web-ui/src/flow_chat/tool-cards/README.md
+++ b/src/web-ui/src/flow_chat/tool-cards/README.md
@@ -56,44 +56,9 @@ Preferred pattern:
 
 ## Known Height Changes
 
-If a tool card performs a user-triggered or predictable collapse that can reduce
-its height near the bottom of the conversation, dispatch
-`flowchat:tool-card-collapse-intent` before the collapse happens so
-`VirtualMessageList` can pre-compensate.
-
-This applies to both:
-
-- manual expand/collapse actions
-- automatic status-driven collapses such as collapsing when a tool completes
-
-After a height-changing expand/collapse actually happens, also dispatch
-`tool-card-toggle` so `VirtualMessageList` can schedule follow-up measurement
-and reconcile the final layout.
-
-Tool cards should treat the list's bottom-spacing logic as an internal
-implementation detail. Do not couple card behavior to specific reservation or
-compensation fields inside `VirtualMessageList`; the stable contract for cards is
-still the event pair above plus `useToolCardHeightContract`.
-
-Preferred pattern:
-
-```tsx
-const cardHeight = cardRootRef.current?.getBoundingClientRect().height ?? null;
-
-if (willCollapse) {
-  window.dispatchEvent(new CustomEvent('flowchat:tool-card-collapse-intent', {
-    detail: {
-      toolId,
-      toolName,
-      cardHeight,
-      reason: 'manual', // or 'auto'
-    }
-  }));
-}
-
-setIsExpanded(nextExpanded);
-window.dispatchEvent(new CustomEvent('tool-card-toggle'));
-```
+Tool-card height changes use normal layout reflow. FlowChat does not reserve
+tail space or preserve a card header before a collapse. After a real
+expanded-state change, dispatch `tool-card-toggle` so Virtuoso can remeasure.
 
 Preferred implementation:
 
@@ -106,18 +71,11 @@ const { cardRootRef, applyExpandedState } = useToolCardHeightContract({
   toolName,
 });
 
-applyExpandedState(isExpanded, nextExpanded, setIsExpanded, {
-  reason: 'manual', // or 'auto'
-  detail: {
-    filePath,
-  },
-});
+applyExpandedState(isExpanded, nextExpanded, setIsExpanded);
 ```
 
-Attach `cardRootRef` to the visible outer box that actually collapses. Do not
-use an inner scroll container's `scrollHeight`: bounded cards can contain much
-more hidden scroll content than the layout height removed by a collapse, which
-would over-reserve FlowChat footer space.
+Attach `cardRootRef` to the visible outer box. Do not calculate or write the
+outer FlowChat viewport position from a card.
 
 Current examples:
 
@@ -129,4 +87,7 @@ Current examples:
 
 For details, read:
 
-- `src/web-ui/src/flow_chat/components/modern/FLOWCHAT_SCROLL_STABILITY.md`
+- `src/web-ui/src/flow_chat/components/modern/AGENTS.md` — the rules, and a map
+  of which viewport document covers what. A card's height contract is in
+  `FLOWCHAT_SCROLL_STABILITY.md`; what a card may render inside a virtualized
+  row is in `FLOWCHAT_VIRTUALIZATION.md`.
diff --git a/src/web-ui/src/flow_chat/tool-cards/RunCodeToolCard.appearance.ts b/src/web-ui/src/flow_chat/tool-cards/RunCodeToolCard.appearance.ts
new file mode 100644
index 0000000000..bd39720970
--- /dev/null
+++ b/src/web-ui/src/flow_chat/tool-cards/RunCodeToolCard.appearance.ts
@@ -0,0 +1,13 @@
+import type { AppearanceSurfaceDescriptor } from '@/infrastructure/appearance';
+
+export const runCodeToolCardAppearanceDescriptor: AppearanceSurfaceDescriptor = {
+  id: 'run-code-tool-card',
+  parts: [
+    { id: 'root' }, { id: 'expanded' }, { id: 'section' },
+    { id: 'label' }, { id: 'output' }, { id: 'error' },
+  ],
+  states: [
+    { id: 'expanded', selector: { kind: 'self', suffix: '[data-bf-state~="expanded"]' } },
+    { id: 'failed', selector: { kind: 'self', suffix: '[data-bf-state~="failed"]' } },
+  ],
+};
diff --git a/src/web-ui/src/flow_chat/tool-cards/RunCodeToolCard.scss b/src/web-ui/src/flow_chat/tool-cards/RunCodeToolCard.scss
new file mode 100644
index 0000000000..ddc8725f6d
--- /dev/null
+++ b/src/web-ui/src/flow_chat/tool-cards/RunCodeToolCard.scss
@@ -0,0 +1,30 @@
+.run-code-tool-card__expanded {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.run-code-tool-card__section {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.run-code-tool-card__label {
+  color: var(--bf-appearance-token-color-text-muted);
+  font-size: var(--bf-appearance-token-flowchat-font-size-xs);
+  font-weight: 600;
+  letter-spacing: 0.01em;
+  text-transform: uppercase;
+}
+
+.run-code-tool-card__output pre {
+  margin: 0;
+}
+
+.run-code-tool-card__error {
+  color: var(--bf-appearance-token-color-error);
+  font-size: var(--bf-appearance-token-tool-card-action-font-size);
+  line-height: var(--bf-appearance-token-flowchat-text-line-height);
+  white-space: pre-wrap;
+}
diff --git a/src/web-ui/src/flow_chat/tool-cards/RunCodeToolCard.test.tsx b/src/web-ui/src/flow_chat/tool-cards/RunCodeToolCard.test.tsx
new file mode 100644
index 0000000000..037992e58d
--- /dev/null
+++ b/src/web-ui/src/flow_chat/tool-cards/RunCodeToolCard.test.tsx
@@ -0,0 +1,157 @@
+import React from 'react';
+import { act } from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createRoot, type Root } from 'react-dom/client';
+import { JSDOM } from 'jsdom';
+
+import { RunCodeToolCard } from './RunCodeToolCard';
+import type { FlowToolItem, ToolCardConfig } from '../types/flow-chat';
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+vi.mock('react-i18next', async () => {
+  const actual = await vi.importActual<typeof import('react-i18next')>('react-i18next');
+  return {
+    ...actual,
+    useTranslation: () => ({
+      t: (key: string, options?: { defaultValue?: string }) => options?.defaultValue ?? key,
+    }),
+  };
+});
+
+vi.mock('../../component-library', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../../component-library')>();
+  return {
+    ...actual,
+    ToolProcessingDots: () => <span data-testid="tool-processing-dots" />,
+  };
+});
+
+// Prism loads asynchronously and paints nothing under jsdom; the plain fallback
+// is what the assertions below read.
+vi.mock('@/shared/utils/syntaxHighlighterLoader', () => ({
+  getLoadedPrismSyntaxHighlighter: () => null,
+  loadPrismSyntaxHighlighter: () => Promise.resolve(null),
+}));
+
+const config: ToolCardConfig = {
+  toolName: 'RunCode',
+  displayName: 'Run Code',
+  icon: 'CODE',
+  requiresConfirmation: false,
+  resultDisplayType: 'detailed',
+  description: 'Run a program and show what it printed',
+  displayMode: 'standard',
+};
+
+const PROGRAM = 'const listing = await tools.bash({ command: "ls -la" });\nconsole.log(listing.stdout);';
+
+function runCodeItem(overrides: Partial<FlowToolItem> = {}): FlowToolItem {
+  return {
+    id: 'tool-run-code-1',
+    type: 'tool',
+    toolName: 'RunCode',
+    status: 'completed',
+    timestamp: Date.now(),
+    toolCall: {
+      id: 'call-run-code-1',
+      input: {
+        code: PROGRAM,
+        description: 'Explore project root structure',
+      },
+    },
+    toolResult: {
+      success: true,
+      result: { output: 'total 0\ndrwxr-xr-x  4 user  staff' },
+    },
+    ...overrides,
+  };
+}
+
+describe('RunCodeToolCard', () => {
+  let dom: JSDOM;
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    dom = new JSDOM('<!doctype html><html><body><div id="root"></div></body></html>', {
+      pretendToBeVisual: true,
+    });
+    vi.stubGlobal('window', dom.window);
+    vi.stubGlobal('document', dom.window.document);
+    vi.stubGlobal('HTMLElement', dom.window.HTMLElement);
+    vi.stubGlobal('CustomEvent', dom.window.CustomEvent);
+    vi.stubGlobal('ResizeObserver', class {
+      observe = vi.fn();
+      disconnect = vi.fn();
+    });
+
+    container = dom.window.document.getElementById('root') as HTMLDivElement;
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => {
+      root.unmount();
+    });
+    vi.unstubAllGlobals();
+  });
+
+  function render(item: FlowToolItem) {
+    act(() => {
+      root.render(<RunCodeToolCard toolItem={item} config={config} />);
+    });
+  }
+
+  function expand() {
+    const card = container.querySelector('.compact-tool-card');
+    expect(card).not.toBeNull();
+    act(() => {
+      card?.dispatchEvent(new dom.window.MouseEvent('click', { bubbles: true }));
+    });
+  }
+
+  it('summarizes the call by what the program was for', () => {
+    render(runCodeItem());
+
+    expect(container.textContent).toContain('Explore project root structure');
+  });
+
+  it('falls back to the first real line of the program when there is no description', () => {
+    render(runCodeItem({
+      toolCall: {
+        id: 'call-run-code-1',
+        input: { code: `// gather the listing\n\n${PROGRAM}` },
+      },
+    }));
+
+    expect(container.textContent).toContain('const listing = await tools.bash');
+  });
+
+  it('shows the program and its output once expanded', () => {
+    render(runCodeItem());
+    expand();
+
+    expect(container.textContent).toContain('console.log(listing.stdout);');
+    expect(container.textContent).toContain('drwxr-xr-x  4 user  staff');
+  });
+
+  it('reads output out of a result that only carries stdout', () => {
+    render(runCodeItem({
+      toolResult: { success: true, result: { stdout: 'hello from the program' } },
+    }));
+    expand();
+
+    expect(container.textContent).toContain('hello from the program');
+  });
+
+  it('shows the failure instead of an empty output section', () => {
+    render(runCodeItem({
+      status: 'error',
+      toolResult: { success: false, error: 'ReferenceError: tools is not defined' },
+    }));
+    expand();
+
+    expect(container.textContent).toContain('ReferenceError: tools is not defined');
+  });
+});
diff --git a/src/web-ui/src/flow_chat/tool-cards/RunCodeToolCard.tsx b/src/web-ui/src/flow_chat/tool-cards/RunCodeToolCard.tsx
new file mode 100644
index 0000000000..ce22a8c5a0
--- /dev/null
+++ b/src/web-ui/src/flow_chat/tool-cards/RunCodeToolCard.tsx
@@ -0,0 +1,178 @@
+/**
+ * Run Code tool card.
+ *
+ * Code-mode agents answer a step by writing one program — DeepSeek Harness's
+ * PTC preset calls it `run_code` — instead of one tool call per file read or
+ * shell command. The program is the action, so the card shows it as code and
+ * whatever it printed underneath, rather than squeezing a TypeScript source
+ * file into a terminal card's command line.
+ */
+
+import React, { useCallback, useMemo, useState } from 'react';
+import { Code2 } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+
+import type { ToolCardProps } from '../types/flow-chat';
+import { CodePreview } from '../components/CodePreview';
+import { CompactToolCard, CompactToolCardHeader } from './CompactToolCard';
+import { ToolCardStatusSlot } from './ToolCardStatusSlot';
+import { ToolCardCopyAction, ToolCardHeaderActions } from './ToolCardHeaderActions';
+import { useToolCardHeightContract } from './useToolCardHeightContract';
+import { formatSessionViewPreviewText } from '../utils/sessionViewPreview';
+import './RunCodeToolCard.scss';
+
+/** Enough of the program to recognize it in a collapsed header. */
+const SUMMARY_CHARS = 80;
+
+function asText(value: unknown): string {
+  return typeof value === 'string' ? value : '';
+}
+
+/**
+ * The first line that says something about what the program does — skipping
+ * the comment banners and blank lines a model tends to open with.
+ */
+function firstMeaningfulLine(code: string): string {
+  for (const line of code.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('//') || trimmed.startsWith('/*') || trimmed.startsWith('*')) {
+      continue;
+    }
+    return trimmed.length > SUMMARY_CHARS ? `${trimmed.slice(0, SUMMARY_CHARS)}...` : trimmed;
+  }
+  return '';
+}
+
+function readOutput(result: unknown): string {
+  if (typeof result === 'string') return formatSessionViewPreviewText(result);
+  if (!result || typeof result !== 'object') return '';
+
+  const record = result as Record<string, unknown>;
+  const stdout = asText(record.stdout);
+  const stderr = asText(record.stderr);
+  const combined = [stdout, stderr].filter((value) => value.length > 0).join('\n');
+  return formatSessionViewPreviewText(asText(record.output) || combined);
+}
+
+export const RunCodeToolCard: React.FC<ToolCardProps> = ({
+  toolItem,
+  config,
+  onExpand,
+}) => {
+  const { t } = useTranslation('flow-chat');
+  const { toolCall, toolResult, status } = toolItem;
+  const [isExpanded, setIsExpanded] = useState(false);
+  const toolId = toolItem.id ?? toolCall?.id;
+  const { cardRootRef, applyExpandedState } = useToolCardHeightContract({
+    toolId,
+    toolName: config.toolName,
+  });
+
+  const code = asText(toolCall?.input?.code);
+  const description = asText(toolCall?.input?.description).trim();
+  const output = useMemo(() => readOutput(toolResult?.result), [toolResult?.result]);
+  const errorMessage = status === 'error'
+    ? toolResult?.error || t('toolCards.runCode.failed')
+    : null;
+
+  const canExpand = Boolean(code || output || errorMessage);
+  const getCopyCodeText = useCallback(() => code, [code]);
+
+  const handleToggleExpand = useCallback(() => {
+    if (!canExpand) return;
+
+    applyExpandedState(isExpanded, !isExpanded, setIsExpanded, { onExpand });
+  }, [applyExpandedState, canExpand, isExpanded, onExpand]);
+
+  const summary = useMemo(() => {
+    if (errorMessage) return errorMessage;
+
+    const subject = description || firstMeaningfulLine(code);
+    if (status === 'completed') {
+      return subject || t('toolCards.runCode.completed');
+    }
+    if (status === 'cancelled') {
+      return t('toolCards.runCode.cancelled');
+    }
+    if (status === 'rejected') {
+      return t('toolCards.runCode.rejected');
+    }
+    if (subject) return subject;
+
+    return code ? t('toolCards.runCode.running') : t('toolCards.runCode.writing');
+  }, [code, description, errorMessage, status, t]);
+
+  return (
+    <div
+      data-bf-component="run-code-tool-card"
+      data-bf-part="root"
+      data-bf-state={[isExpanded && 'expanded', Boolean(errorMessage) && 'failed'].filter(Boolean).join(' ')}
+      ref={cardRootRef}
+      data-tool-card-id={toolId ?? ''}
+    >
+      <CompactToolCard
+        status={status}
+        isExpanded={isExpanded}
+        onClick={handleToggleExpand}
+        className="run-code-tool-card"
+        clickable={canExpand}
+        header={(
+          <CompactToolCardHeader
+            icon={<ToolCardStatusSlot status={status} toolIcon={<Code2 size={16} />} />}
+            action={t('toolCards.runCode.title')}
+            content={summary}
+            extra={code ? (
+              <ToolCardHeaderActions className="run-code-tool-card__actions">
+                <ToolCardCopyAction
+                  className="run-code-tool-card__copy"
+                  getText={getCopyCodeText}
+                  tooltip={t('toolCards.runCode.copyCode')}
+                  copiedTooltip={t('toolCards.runCode.codeCopied')}
+                  successMessage={t('toolCards.runCode.codeCopied')}
+                  failureMessage={t('toolCards.runCode.copyCodeFailed')}
+                  ariaLabel={t('toolCards.runCode.copyCode')}
+                  showSuccessNotification={false}
+                />
+              </ToolCardHeaderActions>
+            ) : undefined}
+          />
+        )}
+        expandedContent={canExpand ? (
+          <div data-bf-component="run-code-tool-card" data-bf-part="expanded" className="run-code-tool-card__expanded">
+            {code && (
+              <section data-bf-component="run-code-tool-card" data-bf-part="section" className="run-code-tool-card__section">
+                <div data-bf-component="run-code-tool-card" data-bf-part="label" className="run-code-tool-card__label">
+                  {t('toolCards.runCode.programLabel')}
+                </div>
+                <CodePreview
+                  content={code}
+                  language="typescript"
+                  showLineNumbers={false}
+                  maxHeight={320}
+                  autoScrollToBottom={false}
+                />
+              </section>
+            )}
+
+            {(output || errorMessage) && (
+              <section data-bf-component="run-code-tool-card" data-bf-part="section" className="run-code-tool-card__section">
+                <div data-bf-component="run-code-tool-card" data-bf-part="label" className="run-code-tool-card__label">
+                  {t('toolCards.runCode.outputLabel')}
+                </div>
+                {errorMessage ? (
+                  <div data-bf-component="run-code-tool-card" data-bf-part="error" className="run-code-tool-card__error">{errorMessage}</div>
+                ) : (
+                  <div data-bf-component="run-code-tool-card" data-bf-part="output" className="compact-result-content run-code-tool-card__output">
+                    <pre>{output}</pre>
+                  </div>
+                )}
+              </section>
+            )}
+          </div>
+        ) : undefined}
+      />
+    </div>
+  );
+};
+
+export default RunCodeToolCard;
diff --git a/src/web-ui/src/flow_chat/tool-cards/SnapshotFullscreenDiffViewer.css b/src/web-ui/src/flow_chat/tool-cards/SnapshotFullscreenDiffViewer.css
index fb47358fe9..8fc3cd213a 100644
--- a/src/web-ui/src/flow_chat/tool-cards/SnapshotFullscreenDiffViewer.css
+++ b/src/web-ui/src/flow_chat/tool-cards/SnapshotFullscreenDiffViewer.css
@@ -110,7 +110,12 @@
   font-size: var(--bf-appearance-token-tool-card-action-font-size);
   font-weight: 500;
   cursor: pointer;
-  transition: all 0.2s ease;
+  transition:
+    scale 120ms cubic-bezier(0.23, 1, 0.32, 1),
+    background-color 160ms ease,
+    border-color 160ms ease,
+    color 160ms ease,
+    opacity 160ms ease;
 }
 
 .header-btn:disabled {
@@ -181,7 +186,11 @@
   background: var(--bf-appearance-token-color-overlay-white-08);
   color: var(--bf-appearance-token-color-overlay-white-70);
   cursor: pointer;
-  transition: all 0.2s ease;
+  transition:
+    scale 120ms cubic-bezier(0.23, 1, 0.32, 1),
+    background-color 160ms ease,
+    color 160ms ease,
+    opacity 160ms ease;
   flex-shrink: 0;
 }
 
@@ -219,7 +228,10 @@
   background: transparent;
   color: var(--bf-appearance-token-color-overlay-white-60);
   cursor: pointer;
-  transition: all 0.2s ease;
+  transition:
+    background-color 160ms ease,
+    border-color 160ms ease,
+    color 160ms ease;
   white-space: nowrap;
   flex-shrink: 0;
   font-size: var(--bf-appearance-token-tool-card-action-font-size);
@@ -332,7 +344,12 @@
   font-size: var(--bf-appearance-token-tool-card-action-font-size);
   font-weight: 500;
   cursor: pointer;
-  transition: all 0.2s ease;
+  transition:
+    scale 120ms cubic-bezier(0.23, 1, 0.32, 1),
+    background-color 160ms ease,
+    border-color 160ms ease,
+    color 160ms ease,
+    opacity 160ms ease;
 }
 
 .file-action-btn:disabled {
@@ -413,10 +430,10 @@
   border: 2px solid var(--bf-appearance-token-color-overlay-white-20);
   border-top: 2px solid var(--private-diff-fullscreen-selected-color);
   border-radius: 50%;
-  animation: spin 1s linear infinite;
+  animation: snapshot-fullscreen-diff-spin 1s linear infinite;
 }
 
-@keyframes spin {
+@keyframes snapshot-fullscreen-diff-spin {
   0% { transform: rotate(0deg); }
   100% { transform: rotate(360deg); }
 }
@@ -522,3 +539,9 @@
   stroke-linecap: round;
   stroke-linejoin: round;
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .snapshot-fullscreen-overlay .loading-spinner {
+    animation: none;
+  }
+}
diff --git a/src/web-ui/src/flow_chat/tool-cards/TaskToolDisplay.scss b/src/web-ui/src/flow_chat/tool-cards/TaskToolDisplay.scss
index ade4241b94..a32a17f426 100644
--- a/src/web-ui/src/flow_chat/tool-cards/TaskToolDisplay.scss
+++ b/src/web-ui/src/flow_chat/tool-cards/TaskToolDisplay.scss
@@ -488,7 +488,12 @@
     font-size: var(--bf-appearance-token-tool-card-action-font-size);
     font-weight: 500;
     cursor: pointer;
-    transition: all 0.2s ease;
+    transition:
+      scale 120ms cubic-bezier(0.23, 1, 0.32, 1),
+      background-color 160ms ease,
+      border-color 160ms ease,
+      color 160ms ease,
+      opacity 160ms ease;
     border: none;
 
     &:disabled {
@@ -649,7 +654,7 @@
 
 /* E — task description text fades with the card */
 .task-tool-display.base-tool-card-wrapper--loading-shimmer .task-action {
-  animation: tool-card-text-fade 2.2s ease-in-out infinite;
+  animation: task-tool-loading-fade 2.2s ease-in-out infinite;
 }
 
 /* Reviewer context block — replaces raw prompt for review-team members. */
@@ -691,13 +696,18 @@
   }
 }
 
-@keyframes slideDown {
-  from {
-    opacity: 0;
-    transform: translateY(-8px);
-  }
-  to {
+@keyframes task-tool-loading-fade {
+  0%, 100% {
     opacity: 1;
-    transform: translateY(0);
+  }
+  50% {
+    opacity: 0.68;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .task-tool-display .task-subagent-stop-button:disabled svg,
+  .task-tool-display.base-tool-card-wrapper--loading-shimmer .task-action {
+    animation: none;
   }
 }
diff --git a/src/web-ui/src/flow_chat/tool-cards/TaskToolDisplay.tsx b/src/web-ui/src/flow_chat/tool-cards/TaskToolDisplay.tsx
index cc7bca2ed7..b9e6ecb130 100644
--- a/src/web-ui/src/flow_chat/tool-cards/TaskToolDisplay.tsx
+++ b/src/web-ui/src/flow_chat/tool-cards/TaskToolDisplay.tsx
@@ -299,7 +299,7 @@ export const TaskToolDisplay: React.FC<ToolCardProps> = ({
       /* Sync before the next commit paints so subagent wrapper + task card merge in one frame. */
       taskCollapseStateManager.setCollapsed(toolItem.id, !nextExpanded);
     }
-    applyExpandedState(isExpanded, nextExpanded, setIsExpanded, { reason });
+    applyExpandedState(isExpanded, nextExpanded, setIsExpanded);
   }, [applyExpandedState, isExpanded, toolItem.id]);
 
   useLayoutEffect(() => {
diff --git a/src/web-ui/src/flow_chat/tool-cards/TerminalToolCard.scss b/src/web-ui/src/flow_chat/tool-cards/TerminalToolCard.scss
index c266079451..526aa37ca0 100644
--- a/src/web-ui/src/flow_chat/tool-cards/TerminalToolCard.scss
+++ b/src/web-ui/src/flow_chat/tool-cards/TerminalToolCard.scss
@@ -160,7 +160,6 @@
   border: none !important;
   outline: none !important;
   box-shadow: none !important;
-  transition: all 0.2s ease;
   line-height: var(--bf-appearance-token-flowchat-compact-line-height);
   box-sizing: border-box;
 
@@ -299,7 +298,12 @@
   color: var(--bf-appearance-token-color-text-muted);
   cursor: pointer;
   font-size: var(--bf-appearance-token-flowchat-font-size-sm);
-  transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
+  transition:
+    transform 120ms cubic-bezier(0.23, 1, 0.32, 1),
+    background-color 160ms ease,
+    color 160ms ease,
+    box-shadow 180ms ease,
+    opacity 160ms ease;
   padding: 0;
   position: relative;
   overflow: hidden;
diff --git a/src/web-ui/src/flow_chat/tool-cards/TerminalToolCard.tsx b/src/web-ui/src/flow_chat/tool-cards/TerminalToolCard.tsx
index 60ba976a98..b6e9a72799 100644
--- a/src/web-ui/src/flow_chat/tool-cards/TerminalToolCard.tsx
+++ b/src/web-ui/src/flow_chat/tool-cards/TerminalToolCard.tsx
@@ -24,7 +24,7 @@ import { ToolCardStatusSlot } from './ToolCardStatusSlot';
 import { DotMatrixLoader, IconButton } from '../../component-library';
 import { LazyTerminalOutputRenderer } from '@/tools/terminal/components/LazyTerminalOutputRenderer';
 import { createLogger } from '@/shared/utils/logger';
-import { useToolCardHeightContract, type ToolCardCollapseReason } from './useToolCardHeightContract';
+import { useToolCardHeightContract } from './useToolCardHeightContract';
 import { useToolCardCompletionGracePeriod } from './useToolCardCompletionGracePeriod';
 import { getTerminalViewState, type TerminalViewState } from './terminalToolCardState';
 import { ToolTimeoutIndicator } from './ToolTimeoutIndicator';
@@ -305,23 +305,17 @@ export const TerminalToolCard: React.FC<TerminalToolCardProps> = ({
       isExpanded &&
       !userToggledRef.current,
   });
-  const applyTerminalExpandedState = useCallback((
-    nextExpanded: boolean,
-    options?: { reason?: ToolCardCollapseReason },
-  ) => {
+  const applyTerminalExpandedState = useCallback((nextExpanded: boolean) => {
     if (nextExpanded === isExpanded) {
       return;
     }
 
-    applyExpandedState(isExpanded, nextExpanded, setIsExpandedState, {
-      reason: options?.reason ?? 'manual',
-      onExpand,
-    });
+    applyExpandedState(isExpanded, nextExpanded, setIsExpandedState, { onExpand });
   }, [applyExpandedState, isExpanded, onExpand]);
 
   const toggleExpanded = useCallback(() => {
     userToggledRef.current = true;
-    applyTerminalExpandedState(!isExpanded, { reason: 'manual' });
+    applyTerminalExpandedState(!isExpanded);
   }, [applyTerminalExpandedState, isExpanded]);
 
   const [interruptRequested, setInterruptRequested] = useState(false);
@@ -342,7 +336,7 @@ export const TerminalToolCard: React.FC<TerminalToolCardProps> = ({
     const keepTailPreview = isCollapsedTerminalStatus(status) && beginCompletionPreview();
     const nextExpanded = getAutoExpandedStateForTerminalStatus(status, isLastItem, keepTailPreview);
     if (nextExpanded !== null) {
-      applyTerminalExpandedState(nextExpanded, { reason: 'auto' });
+      applyTerminalExpandedState(nextExpanded);
     }
   }, [
     applyTerminalExpandedState,
diff --git a/src/web-ui/src/flow_chat/tool-cards/TodoWriteDisplay.test.tsx b/src/web-ui/src/flow_chat/tool-cards/TodoWriteDisplay.test.tsx
index 1d17199494..7f44c366b8 100644
--- a/src/web-ui/src/flow_chat/tool-cards/TodoWriteDisplay.test.tsx
+++ b/src/web-ui/src/flow_chat/tool-cards/TodoWriteDisplay.test.tsx
@@ -8,6 +8,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import type { FlowToolItem, ToolCardConfig } from '../types/flow-chat';
 import { createTodoRenderItems } from './todoRenderItems';
 import { TodoWriteDisplay } from './TodoWriteDisplay';
+import { FLOWCHAT_COLLAPSE_DURATION_MS } from '../components/modern/flowChatCollapseMotion';
 
 vi.mock('react-i18next', async (importOriginal) => ({
   ...await importOriginal<typeof import('react-i18next')>(),
@@ -93,38 +94,26 @@ describe('TodoWriteDisplay automatic collapse', () => {
   afterEach(() => {
     act(() => root.unmount());
     container.remove();
+    vi.useRealTimers();
     vi.restoreAllMocks();
   });
 
-  it('publishes an auto collapse intent before removing expanded todos', () => {
-    let receivedDetail: Record<string, unknown> | null = null;
-    let hadExpandedBodyWhenIntentFired = false;
-    const handleIntent = (event: Event) => {
-      receivedDetail = (event as CustomEvent<Record<string, unknown>>).detail;
-      hadExpandedBodyWhenIntentFired = Boolean(container.querySelector('.todo-expanded-body'));
-    };
-    window.addEventListener('flowchat:tool-card-collapse-intent', handleIntent);
-
-    try {
-      act(() => {
-        root.render(<TodoWriteDisplay toolItem={createTodoWriteItem('pending')} config={config} />);
-      });
-      expect(container.querySelector('.todo-expanded-body')).not.toBeNull();
-
-      act(() => {
-        root.render(<TodoWriteDisplay toolItem={createTodoWriteItem('in_progress')} config={config} />);
-      });
-
-      expect(hadExpandedBodyWhenIntentFired).toBe(true);
-      expect(receivedDetail).toMatchObject({
-        toolId: 'todo-tool-a',
-        toolName: 'TodoWrite',
-        cardHeight: 320,
-        reason: 'auto',
-      });
-      expect(container.querySelector('.todo-expanded-body')).toBeNull();
-    } finally {
-      window.removeEventListener('flowchat:tool-card-collapse-intent', handleIntent);
-    }
+  it('lets completed todo content collapse through normal layout state', () => {
+    vi.useFakeTimers();
+    act(() => {
+      root.render(<TodoWriteDisplay toolItem={createTodoWriteItem('pending')} config={config} />);
+    });
+    expect(container.querySelector('.todo-expanded-body')).not.toBeNull();
+
+    act(() => {
+      root.render(<TodoWriteDisplay toolItem={createTodoWriteItem('in_progress')} config={config} />);
+    });
+
+    expect(container.querySelector('.todo-expanded-body')).not.toBeNull();
+
+    act(() => {
+      vi.advanceTimersByTime(FLOWCHAT_COLLAPSE_DURATION_MS);
+    });
+    expect(container.querySelector('.todo-expanded-body')).toBeNull();
   });
 });
diff --git a/src/web-ui/src/flow_chat/tool-cards/TodoWriteDisplay.tsx b/src/web-ui/src/flow_chat/tool-cards/TodoWriteDisplay.tsx
index 874e67067f..9b737aaf02 100644
--- a/src/web-ui/src/flow_chat/tool-cards/TodoWriteDisplay.tsx
+++ b/src/web-ui/src/flow_chat/tool-cards/TodoWriteDisplay.tsx
@@ -89,7 +89,6 @@ export const TodoWriteDisplay: React.FC<ToolCardProps> = ({
       automaticExpanded,
       desiredAutomaticExpanded,
       setAutomaticExpanded,
-      { reason: 'auto' },
     );
   }, [
     applyExpandedState,
diff --git a/src/web-ui/src/flow_chat/tool-cards/ToolTimeoutIndicator.scss b/src/web-ui/src/flow_chat/tool-cards/ToolTimeoutIndicator.scss
index 6ac59bbc42..90a17f296f 100644
--- a/src/web-ui/src/flow_chat/tool-cards/ToolTimeoutIndicator.scss
+++ b/src/web-ui/src/flow_chat/tool-cards/ToolTimeoutIndicator.scss
@@ -97,7 +97,12 @@
   font-weight: 500;
   letter-spacing: 0.01em;
   line-height: var(--bf-appearance-token-flowchat-compact-line-height);
-  transition: all 0.15s ease;
+  transition:
+    scale 120ms cubic-bezier(0.23, 1, 0.32, 1),
+    background-color 150ms ease,
+    border-color 150ms ease,
+    color 150ms ease,
+    opacity 150ms ease;
 
   svg {
     width: 12px;
diff --git a/src/web-ui/src/flow_chat/tool-cards/ViewImageToolCard.tsx b/src/web-ui/src/flow_chat/tool-cards/ViewImageToolCard.tsx
index f2d20fd5c1..8a3e2974cd 100644
--- a/src/web-ui/src/flow_chat/tool-cards/ViewImageToolCard.tsx
+++ b/src/web-ui/src/flow_chat/tool-cards/ViewImageToolCard.tsx
@@ -69,7 +69,7 @@ export const ViewImageToolCard: React.FC<ToolCardProps> = ({ toolItem, onExpand
   useLayoutEffect(() => {
     if (!source || didAutoExpand.current) return;
     didAutoExpand.current = true;
-    applyExpandedState(isExpanded, true, setIsExpanded, { reason: 'auto' });
+    applyExpandedState(isExpanded, true, setIsExpanded);
   }, [applyExpandedState, isExpanded, source]);
 
   useEffect(() => {
diff --git a/src/web-ui/src/flow_chat/tool-cards/_tool-card-common.scss b/src/web-ui/src/flow_chat/tool-cards/_tool-card-common.scss
index bfa9e581b5..fadcd1eb75 100644
--- a/src/web-ui/src/flow_chat/tool-cards/_tool-card-common.scss
+++ b/src/web-ui/src/flow_chat/tool-cards/_tool-card-common.scss
@@ -31,7 +31,7 @@
 }
 
 /* Animations */
-@keyframes spin {
+@keyframes tool-card-common-spin {
   from {
     transform: rotate(0deg);
   }
@@ -41,18 +41,7 @@
 }
 
 .animate-spin {
-  animation: spin 1s linear infinite;
-}
-
-@keyframes expandDown {
-  from {
-    opacity: 0;
-    transform: translateY(-8px);
-  }
-  to {
-    opacity: 1;
-    transform: translateY(0);
-  }
+  animation: tool-card-common-spin 1s linear infinite;
 }
 
 /* ========== Shared icon-slot (left rail) ========== */
@@ -197,3 +186,9 @@
     filter: drop-shadow(0 0 4px color-mix(in srgb, var(--bf-appearance-token-color-error) 40%, transparent));
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .animate-spin {
+    animation: none;
+  }
+}
diff --git a/src/web-ui/src/flow_chat/tool-cards/index.test.ts b/src/web-ui/src/flow_chat/tool-cards/index.test.ts
index 9ca9efaa3b..64849fd9f5 100644
--- a/src/web-ui/src/flow_chat/tool-cards/index.test.ts
+++ b/src/web-ui/src/flow_chat/tool-cards/index.test.ts
@@ -2,11 +2,36 @@
 
 import { describe, expect, it } from 'vitest';
 
-import { getToolCardComponent } from './index';
+import {
+  DEDICATED_TOOL_CARD_NAMES,
+  getToolCardComponent,
+  isCollapsibleTool,
+  TOOL_CARD_COMPONENTS,
+  usesDefaultToolCard,
+} from './index';
 import { TaskToolDisplay } from './TaskToolDisplay';
 
 describe('tool card registry', () => {
   it('projects managed Review workers through the unified coverage card', () => {
     expect(getToolCardComponent('LaunchReviewAgent')).toBe(TaskToolDisplay);
   });
+
+  it('keeps lightweight dedicated-card classification aligned with the component registry', () => {
+    expect([...DEDICATED_TOOL_CARD_NAMES].sort()).toEqual(
+      Object.keys(TOOL_CARD_COMPONENTS).sort(),
+    );
+  });
+
+  it.each(['ControlHub', 'FinalizeMiniApp', 'PublishMiniApp', 'PublishAppearance'])(
+    'treats %s as a default-card explore tool',
+    (toolName) => {
+      expect(usesDefaultToolCard(toolName)).toBe(true);
+      expect(isCollapsibleTool(toolName)).toBe(true);
+    },
+  );
+
+  it('does not classify MCP tools as default-card explore tools', () => {
+    expect(usesDefaultToolCard('mcp__server__tool')).toBe(false);
+    expect(isCollapsibleTool('mcp__server__tool')).toBe(false);
+  });
 });
diff --git a/src/web-ui/src/flow_chat/tool-cards/index.ts b/src/web-ui/src/flow_chat/tool-cards/index.ts
index 8521acb990..07eef41fab 100644
--- a/src/web-ui/src/flow_chat/tool-cards/index.ts
+++ b/src/web-ui/src/flow_chat/tool-cards/index.ts
@@ -14,9 +14,11 @@ export {
   READ_TOOL_NAMES,
   SEARCH_TOOL_NAMES,
   COMMAND_TOOL_NAMES,
+  DEDICATED_TOOL_CARD_NAMES,
   isCollapsibleTool,
   isCollapsibleItem,
   isCollapsibleItemWithContext,
+  usesDefaultToolCard,
 } from './toolCardMetadata';
 
 const log = createLogger('ToolCardRegistry');
@@ -41,6 +43,7 @@ import { GitToolDisplay } from './GitToolDisplay';
 import { GetFileDiffDisplay } from './GetFileDiffDisplay';
 import { CreatePlanDisplay } from './CreatePlanDisplay';
 import { TerminalToolCard } from './TerminalToolCard';
+import { RunCodeToolCard } from './RunCodeToolCard';
 import { ExecCommandToolCard } from './ExecCommandToolCard';
 import { WriteStdinToolCard } from './WriteStdinToolCard';
 import { ExecControlToolCard } from './ExecControlToolCard';
@@ -111,6 +114,9 @@ export const TOOL_CARD_COMPONENTS = {
   // Bash tool
   'Bash': TerminalToolCard,
 
+  // Code-mode agents: one program per step instead of one card per action
+  'RunCode': RunCodeToolCard,
+
   // Exec process tools
   'ExecCommand': ExecCommandToolCard,
   'WriteStdin': WriteStdinToolCard,
diff --git a/src/web-ui/src/flow_chat/tool-cards/toolCardMetadata.ts b/src/web-ui/src/flow_chat/tool-cards/toolCardMetadata.ts
index a2419e5845..e80fe217af 100644
--- a/src/web-ui/src/flow_chat/tool-cards/toolCardMetadata.ts
+++ b/src/web-ui/src/flow_chat/tool-cards/toolCardMetadata.ts
@@ -277,6 +277,19 @@ export const TOOL_CARD_CONFIGS: Record<string, ToolCardConfig> = {
     primaryColor: APPEARANCE_DOMAIN_TOKENS.toolIdentity.terminal
   },
 
+  // Code-mode agents (e.g. DeepSeek Harness's PTC preset) answer a step by
+  // writing one program instead of calling one tool per action.
+  'RunCode': {
+    toolName: 'RunCode',
+    displayName: 'Run Code',
+    icon: 'CODE',
+    requiresConfirmation: false,
+    resultDisplayType: 'detailed',
+    description: 'Run a program and show what it printed',
+    displayMode: 'standard',
+    primaryColor: APPEARANCE_DOMAIN_TOKENS.toolIdentity.terminal
+  },
+
   'ExecCommand': {
     toolName: 'ExecCommand',
     displayName: 'Run Command',
@@ -498,13 +511,80 @@ export function getAllToolNames(): string[] {
 
 // ==================== Collapsible explorer tools ====================
 
+/**
+ * Tools with a dedicated FlowChat card renderer.
+ *
+ * Keep this lightweight mirror aligned with TOOL_CARD_COMPONENTS. The registry
+ * test enforces equality so classification callers do not need to import every
+ * card component just to tell dedicated cards from the DefaultToolCard.
+ */
+export const DEDICATED_TOOL_CARD_NAMES = new Set([
+  'Read',
+  'Write',
+  'Edit',
+  'Delete',
+  'Grep',
+  'Glob',
+  'LS',
+  'WebSearch',
+  'WebFetch',
+  'Task',
+  'LaunchReviewAgent',
+  'TodoWrite',
+  'submit_code_review',
+  'ContextCompression',
+  'GetToolSpec',
+  'Skill',
+  'AskUserQuestion',
+  'ReviewSessionSummary',
+  'Git',
+  'GetFileDiff',
+  'CreatePlan',
+  'TerminalControl',
+  'SessionControl',
+  'SessionMessage',
+  'Bash',
+  'RunCode',
+  'ExecCommand',
+  'WriteStdin',
+  'ExecControl',
+  'InitMiniApp',
+  'PageDeploy',
+  'PagePublish',
+  'GenerativeUI',
+  'ComputerUse',
+  'view_image',
+  'CreateCanvas',
+  'ReadCanvas',
+  'UpdateCanvas',
+  'PatchCanvas',
+]);
+
+/** Whether FlowChat renders this tool through DefaultToolCard. */
+export function usesDefaultToolCard(toolName: string): boolean {
+  return !isMcpToolName(toolName) && !DEDICATED_TOOL_CARD_NAMES.has(toolName);
+}
+
 
 /**
- * Collapsible explorer tools.
- * They are auto-collapsed during streaming to reduce visual noise.
+ * Explicit non-critical tools collected into explore groups.
+ * Tools rendered by DefaultToolCard are also collected; see isCollapsibleTool.
  */
 export const COLLAPSIBLE_TOOL_NAMES = new Set([
-  'Read', 'LS', 'Grep', 'Glob', 'WebSearch', 'Bash', 'Git',
+  'Read',
+  'LS',
+  'Grep',
+  'Glob',
+  'WebSearch',
+  'WebFetch',
+  'GetFileDiff',
+  'GetToolSpec',
+  'ReviewSessionSummary',
+  'TerminalControl',
+  'SessionControl',
+  'ExecControl',
+  'view_image',
+  'ReadCanvas',
 ]);
 
 /** Read tools (counted in readCount). */
@@ -514,11 +594,11 @@ export const READ_TOOL_NAMES = new Set(['Read', 'LS']);
 export const SEARCH_TOOL_NAMES = new Set(['Grep', 'Glob', 'WebSearch']);
 
 /** Command tools (counted in commandCount). */
-export const COMMAND_TOOL_NAMES = new Set(['Bash', 'Git']);
+export const COMMAND_TOOL_NAMES = new Set<string>();
 
 /** Check whether a tool is collapsible. */
 export function isCollapsibleTool(toolName: string): boolean {
-  return COLLAPSIBLE_TOOL_NAMES.has(toolName);
+  return COLLAPSIBLE_TOOL_NAMES.has(toolName) || usesDefaultToolCard(toolName);
 }
 
 /**
diff --git a/src/web-ui/src/flow_chat/tool-cards/useToolCardHeightContract.test.tsx b/src/web-ui/src/flow_chat/tool-cards/useToolCardHeightContract.test.tsx
index a2750a17b6..14d6759261 100644
--- a/src/web-ui/src/flow_chat/tool-cards/useToolCardHeightContract.test.tsx
+++ b/src/web-ui/src/flow_chat/tool-cards/useToolCardHeightContract.test.tsx
@@ -1,72 +1,22 @@
 // @vitest-environment jsdom
 
-import React, { useLayoutEffect } from 'react';
-import { act } from 'react';
+import React, { act } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { useToolCardHeightContract } from './useToolCardHeightContract';
 
 globalThis.IS_REACT_ACT_ENVIRONMENT = true;
 
-function Harness({ height, collapse }: { height: number; collapse: boolean }) {
-  const { cardRootRef, dispatchCollapseIntent } = useToolCardHeightContract({
-    toolId: 'tool-a',
+function Harness({ expanded }: { expanded: boolean }) {
+  const [isExpanded, setIsExpanded] = React.useState(true);
+  const { cardRootRef, applyExpandedState } = useToolCardHeightContract({
+    toolId: 'tool-1',
     toolName: 'Write',
   });
-
-  useLayoutEffect(() => {
-    if (collapse) {
-      dispatchCollapseIntent('auto');
-    }
-  }, [collapse, dispatchCollapseIntent]);
-
-  return <div ref={cardRootRef} data-height={height} />;
-}
-
-function CustomAnchorHarness({ collapse }: { collapse: boolean }) {
-  const anchorRef = React.useRef<HTMLDivElement>(null);
-  const { cardRootRef, dispatchCollapseIntent } = useToolCardHeightContract({
-    toolId: 'thinking-a',
-    toolName: 'thinking',
-    getAnchorElement: () => anchorRef.current,
-  });
-
-  useLayoutEffect(() => {
-    if (collapse) {
-      dispatchCollapseIntent('auto');
-    }
-  }, [collapse, dispatchCollapseIntent]);
-
-  return (
-    <div ref={anchorRef} data-testid="custom-anchor">
-      <div ref={cardRootRef} data-height="240" />
-    </div>
-  );
-}
-
-function BoundedScrollableHarness({ collapse }: { collapse: boolean }) {
-  const contentRef = React.useRef<HTMLDivElement>(null);
-  const { cardRootRef, dispatchCollapseIntent } = useToolCardHeightContract({
-    toolId: 'thinking-bounded',
-    toolName: 'thinking',
-  });
-
-  useLayoutEffect(() => {
-    if (!contentRef.current) return;
-    Object.defineProperty(contentRef.current, 'scrollHeight', {
-      configurable: true,
-      value: 4_000,
-    });
-    if (collapse) {
-      dispatchCollapseIntent('auto');
-    }
-  }, [collapse, dispatchCollapseIntent]);
-
-  return (
-    <div ref={cardRootRef} data-height="320">
-      <div ref={contentRef} />
-    </div>
-  );
+  React.useEffect(() => {
+    applyExpandedState(isExpanded, expanded, setIsExpanded);
+  }, [applyExpandedState, expanded, isExpanded]);
+  return <div ref={cardRootRef} data-expanded={String(isExpanded)} />;
 }
 
 describe('useToolCardHeightContract', () => {
@@ -75,91 +25,31 @@ describe('useToolCardHeightContract', () => {
 
   beforeEach(() => {
     container = document.createElement('div');
-    document.body.append(container);
+    document.body.appendChild(container);
     root = createRoot(container);
-    vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function () {
-      const height = Number((this as HTMLElement).dataset.height ?? 0);
-      return {
-        bottom: height,
-        height,
-        left: 0,
-        right: 300,
-        top: 0,
-        width: 300,
-        x: 0,
-        y: 0,
-        toJSON: () => ({}),
-      };
-    });
   });
 
   afterEach(() => {
     act(() => root.unmount());
     container.remove();
-    vi.restoreAllMocks();
   });
 
-  it('reports the pre-collapse height and semantic anchor after a state-driven shrink', () => {
-    let receivedDetail: Record<string, unknown> | null = null;
-    const handleIntent = (event: Event) => {
-      receivedDetail = (event as CustomEvent<Record<string, unknown>>).detail;
-    };
-    window.addEventListener('flowchat:tool-card-collapse-intent', handleIntent);
-
-    try {
-      act(() => root.render(<Harness height={320} collapse={false} />));
-      act(() => root.render(<Harness height={64} collapse />));
-
-      expect(receivedDetail).toMatchObject({
-        toolId: 'tool-a',
-        toolName: 'Write',
-        cardHeight: 320,
-        reason: 'auto',
-      });
-      expect(receivedDetail?.anchorElement).toBe(container.firstElementChild);
-    } finally {
-      window.removeEventListener('flowchat:tool-card-collapse-intent', handleIntent);
-    }
+  it('notifies the virtualizer after an expanded-state change', () => {
+    const handleToggle = vi.fn();
+    window.addEventListener('tool-card-toggle', handleToggle);
+    act(() => root.render(<Harness expanded />));
+    act(() => root.render(<Harness expanded={false} />));
+    expect(handleToggle).toHaveBeenCalledOnce();
+    expect(container.firstElementChild?.getAttribute('data-expanded')).toBe('false');
+    window.removeEventListener('tool-card-toggle', handleToggle);
   });
 
-  it('supports a semantic anchor owned by a non-card wrapper', () => {
-    let receivedDetail: Record<string, unknown> | null = null;
-    const handleIntent = (event: Event) => {
-      receivedDetail = (event as CustomEvent<Record<string, unknown>>).detail;
-    };
-    window.addEventListener('flowchat:tool-card-collapse-intent', handleIntent);
-
-    try {
-      act(() => root.render(<CustomAnchorHarness collapse />));
-      expect(receivedDetail).toMatchObject({
-        toolId: 'thinking-a',
-        toolName: 'thinking',
-        cardHeight: 240,
-      });
-      expect(receivedDetail?.anchorElement).toBe(
-        container.querySelector('[data-testid="custom-anchor"]'),
-      );
-    } finally {
-      window.removeEventListener('flowchat:tool-card-collapse-intent', handleIntent);
-    }
-  });
-
-  it('reports visible card height instead of hidden scroll content height', () => {
-    let receivedDetail: Record<string, unknown> | null = null;
-    const handleIntent = (event: Event) => {
-      receivedDetail = (event as CustomEvent<Record<string, unknown>>).detail;
-    };
-    window.addEventListener('flowchat:tool-card-collapse-intent', handleIntent);
-
-    try {
-      act(() => root.render(<BoundedScrollableHarness collapse />));
-      expect(receivedDetail).toMatchObject({
-        toolId: 'thinking-bounded',
-        toolName: 'thinking',
-        cardHeight: 320,
-      });
-    } finally {
-      window.removeEventListener('flowchat:tool-card-collapse-intent', handleIntent);
-    }
+  it('does not emit a pre-collapse viewport compensation event', () => {
+    const handleCollapseIntent = vi.fn();
+    window.addEventListener('flowchat:tool-card-collapse-intent', handleCollapseIntent);
+    act(() => root.render(<Harness expanded />));
+    act(() => root.render(<Harness expanded={false} />));
+    expect(handleCollapseIntent).not.toHaveBeenCalled();
+    window.removeEventListener('flowchat:tool-card-collapse-intent', handleCollapseIntent);
   });
 });
diff --git a/src/web-ui/src/flow_chat/tool-cards/useToolCardHeightContract.ts b/src/web-ui/src/flow_chat/tool-cards/useToolCardHeightContract.ts
index 18af27d0f2..6f5fc234c4 100644
--- a/src/web-ui/src/flow_chat/tool-cards/useToolCardHeightContract.ts
+++ b/src/web-ui/src/flow_chat/tool-cards/useToolCardHeightContract.ts
@@ -1,6 +1,4 @@
-import { useCallback, useLayoutEffect, useRef } from 'react';
-export type ToolCardCollapseReason = 'manual' | 'auto';
-
+import { useCallback, useRef } from 'react';
 interface UseToolCardHeightContractOptions {
   toolId: string | null | undefined;
   toolName: string;
@@ -8,66 +6,26 @@ interface UseToolCardHeightContractOptions {
 }
 
 interface ApplyHeightContractOptions {
-  reason?: ToolCardCollapseReason;
   onExpand?: () => void;
-  detail?: Record<string, unknown>;
 }
 
 export function useToolCardHeightContract({
-  toolId,
-  toolName,
-  getAnchorElement,
+  toolId: _toolId,
+  toolName: _toolName,
+  getAnchorElement: _getAnchorElement,
 }: UseToolCardHeightContractOptions) {
   const cardRootRef = useRef<HTMLDivElement>(null);
-  const lastMeasuredHeightRef = useRef(0);
-  const previousMeasuredHeightRef = useRef(0);
-
-  useLayoutEffect(() => {
-    const nextHeight = cardRootRef.current?.getBoundingClientRect().height ?? 0;
-    if (nextHeight <= 0) {
-      return;
-    }
-    previousMeasuredHeightRef.current = lastMeasuredHeightRef.current;
-    lastMeasuredHeightRef.current = nextHeight;
-  });
 
   const dispatchToolCardToggle = useCallback(() => {
     window.dispatchEvent(new CustomEvent('tool-card-toggle'));
   }, []);
 
-  const dispatchCollapseIntent = useCallback((
-    reason: ToolCardCollapseReason,
-    detail?: Record<string, unknown>,
-  ) => {
-    const measuredHeight = cardRootRef.current?.getBoundingClientRect().height ?? 0;
-    const cardHeight = Math.max(
-      measuredHeight,
-      lastMeasuredHeightRef.current,
-      previousMeasuredHeightRef.current,
-    ) || null;
-
-    window.dispatchEvent(new CustomEvent('flowchat:tool-card-collapse-intent', {
-      detail: {
-        ...detail,
-        toolId: toolId ?? null,
-        toolName,
-        cardHeight,
-        anchorElement: getAnchorElement?.() ?? cardRootRef.current,
-        reason,
-      },
-    }));
-  }, [getAnchorElement, toolId, toolName]);
-
   const applyExpandedState = useCallback((
     currentExpanded: boolean,
     nextExpanded: boolean,
     setExpanded: (nextExpanded: boolean) => void,
     options?: ApplyHeightContractOptions,
   ) => {
-    if (!nextExpanded && currentExpanded) {
-      dispatchCollapseIntent(options?.reason ?? 'manual', options?.detail);
-    }
-
     if (nextExpanded !== currentExpanded) {
       setExpanded(nextExpanded);
       dispatchToolCardToggle();
@@ -76,12 +34,11 @@ export function useToolCardHeightContract({
     if (nextExpanded) {
       options?.onExpand?.();
     }
-  }, [dispatchCollapseIntent, dispatchToolCardToggle]);
+  }, [dispatchToolCardToggle]);
 
   return {
     cardRootRef,
     dispatchToolCardToggle,
-    dispatchCollapseIntent,
     applyExpandedState,
   };
 }
diff --git a/src/web-ui/src/flow_chat/types/flow-chat.ts b/src/web-ui/src/flow_chat/types/flow-chat.ts
index 55ac8b56ec..b0e1c8b2dc 100644
--- a/src/web-ui/src/flow_chat/types/flow-chat.ts
+++ b/src/web-ui/src/flow_chat/types/flow-chat.ts
@@ -126,10 +126,21 @@ export interface FlowImageAnalysisItem extends FlowItem {
  * `steer_dialog_turn` Tauri command. Rendered inline inside the running
  * model round so the user can see the message they steered the agent with.
  */
+/** One image attached to a steering message, in display shape. */
+export interface SteeringImage {
+  id: string;
+  name?: string;
+  dataUrl?: string;
+  imagePath?: string;
+  mimeType?: string;
+}
+
 export interface FlowUserSteeringItem extends FlowItem {
   type: 'user-steering';
   steeringId: string;
   content: string;
+  /** Images sent with the steering message, rendered under its text. */
+  images?: SteeringImage[];
   /** Round index reported by the backend at injection time. */
   roundIndex: number;
 }
@@ -267,6 +278,14 @@ export interface DialogTurn {
   success?: boolean;
   /** Why the turn finished. */
   finishReason?: string;
+  /** Additive recovery metadata for an intentionally interrupted turn. */
+  recovery?: {
+    status: 'interrupted' | 'recovering';
+    executionGeneration: number;
+    resumeCount: number;
+    interruptedAt?: number;
+    modelId?: string;
+  };
   /** Whether the turn produced a final assistant response visible to the user. */
   hasFinalResponse?: boolean;
 }
diff --git a/src/web-ui/src/flow_chat/utils/acpSessionConfig.test.ts b/src/web-ui/src/flow_chat/utils/acpSessionConfig.test.ts
index debc7dbafd..40cb59360f 100644
--- a/src/web-ui/src/flow_chat/utils/acpSessionConfig.test.ts
+++ b/src/web-ui/src/flow_chat/utils/acpSessionConfig.test.ts
@@ -4,6 +4,7 @@ import type { AcpSessionConfigOption } from '@/infrastructure/api/service-api/AC
 import {
   buildAcpFastModeValue,
   getAcpModelProviderName,
+  resolveAcpModeState,
   resolveAcpReasoningState,
   resolveAcpFastModeState,
 } from './acpSessionConfig';
@@ -83,6 +84,50 @@ describe('ACP reasoning config', () => {
   });
 });
 
+describe('ACP session mode config', () => {
+  const option: AcpSessionConfigOption = {
+    id: 'agent-preset',
+    name: 'Mode',
+    category: 'mode',
+    type: 'select',
+    currentValue: 'standard',
+    options: [
+      { value: 'standard', name: 'Standard' },
+      { value: 'minimal', name: 'Minimal' },
+    ],
+  };
+
+  it('resolves whatever the agent files under the mode category', () => {
+    expect(resolveAcpModeState([option])).toEqual({
+      option,
+      currentValue: 'standard',
+      locked: false,
+    });
+  });
+
+  it('reads one remaining choice as locked', () => {
+    // The only signal ACP gives an agent for "this can no longer change":
+    // nothing left to pick. Agents that keep offering alternatives stay live.
+    const fixed: AcpSessionConfigOption = {
+      ...option,
+      description: 'This conversation has already started, so its mode is fixed.',
+      options: [{ value: 'standard', name: 'Standard' }],
+    };
+
+    expect(resolveAcpModeState([fixed])?.locked).toBe(true);
+  });
+
+  it('fails closed for an uncategorized, empty, or inconsistent option', () => {
+    expect(resolveAcpModeState([])).toBeNull();
+    expect(resolveAcpModeState([{ ...option, category: undefined }])).toBeNull();
+    expect(resolveAcpModeState([{ ...option, options: [] }])).toBeNull();
+    expect(resolveAcpModeState([{ ...option, currentValue: 'gone' }])).toBeNull();
+    expect(resolveAcpModeState([{
+      id: 'agent-preset', name: 'Mode', category: 'mode', type: 'boolean', currentValue: true,
+    }])).toBeNull();
+  });
+});
+
 describe('ACP model provider display', () => {
   it('uses the explicit provider name when the ACP bridge includes one', () => {
     expect(getAcpModelProviderName({
diff --git a/src/web-ui/src/flow_chat/utils/acpSessionConfig.ts b/src/web-ui/src/flow_chat/utils/acpSessionConfig.ts
index e8b644bf9f..1b12c5756f 100644
--- a/src/web-ui/src/flow_chat/utils/acpSessionConfig.ts
+++ b/src/web-ui/src/flow_chat/utils/acpSessionConfig.ts
@@ -14,6 +14,38 @@ export interface AcpFastModeState {
   enabled: boolean;
 }
 
+export interface AcpModeState {
+  option: Extract<AcpSessionConfigOption, { type: 'select' }>;
+  currentValue: string;
+  /**
+   * Nothing left to pick. An agent that fixes a session's mode says so by
+   * publishing only the mode in force — a client cannot know an agent's own
+   * rule, and one that allows switching mid-conversation keeps its full list.
+   */
+  locked: boolean;
+}
+
+/**
+ * The session mode selector, if the agent offers one.
+ *
+ * ACP's `mode` category is exactly "the picker that is not the model picker",
+ * so this stays generic: dsh-acp publishes its agent presets here, claude-code
+ * and codex publish their own permission modes.
+ */
+export function resolveAcpModeState(
+  options: AcpSessionConfigOption[],
+): AcpModeState | null {
+  const option = options.find(candidate => candidate.category === 'mode');
+  if (!option || option.type !== 'select' || option.options.length === 0) return null;
+  if (!option.options.some(candidate => candidate.value === option.currentValue)) return null;
+
+  return {
+    option,
+    currentValue: option.currentValue,
+    locked: option.options.length <= 1,
+  };
+}
+
 export interface AcpReasoningState {
   option: Extract<AcpSessionConfigOption, { type: 'select' }>;
   projection: ReasoningCatalogProjection;
diff --git a/src/web-ui/src/flow_chat/utils/flowChatScrollLayout.test.ts b/src/web-ui/src/flow_chat/utils/flowChatScrollLayout.test.ts
new file mode 100644
index 0000000000..2059217898
--- /dev/null
+++ b/src/web-ui/src/flow_chat/utils/flowChatScrollLayout.test.ts
@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest';
+import {
+  CHAT_INPUT_DROP_ZONE_BOTTOM_PX,
+  computeFlowChatInputStackFooterPx,
+  FLOWCHAT_MESSAGE_TAIL_CLEARANCE_PX,
+} from './flowChatScrollLayout';
+
+describe('computeFlowChatInputStackFooterPx', () => {
+  it('uses the current measured input height without retaining an active height', () => {
+    expect(computeFlowChatInputStackFooterPx(40)).toBe(
+      40 + CHAT_INPUT_DROP_ZONE_BOTTOM_PX + FLOWCHAT_MESSAGE_TAIL_CLEARANCE_PX,
+    );
+  });
+
+  it('uses a safe layout fallback only before an input height is measured', () => {
+    expect(computeFlowChatInputStackFooterPx(0)).toBe(
+      96 + CHAT_INPUT_DROP_ZONE_BOTTOM_PX + FLOWCHAT_MESSAGE_TAIL_CLEARANCE_PX,
+    );
+  });
+});
diff --git a/src/web-ui/src/flow_chat/utils/flowChatScrollLayout.ts b/src/web-ui/src/flow_chat/utils/flowChatScrollLayout.ts
index 06bb42e9c4..82af930d13 100644
--- a/src/web-ui/src/flow_chat/utils/flowChatScrollLayout.ts
+++ b/src/web-ui/src/flow_chat/utils/flowChatScrollLayout.ts
@@ -12,41 +12,20 @@ export const FLOWCHAT_MESSAGE_TAIL_CLEARANCE_PX = 24;
 /** Space above the scroll-to-latest control (tighter than message tail; sits in overlay) */
 export const SCROLL_TO_LATEST_INPUT_CLEARANCE_PX = 6;
 
-const FALLBACK_INPUT_BLOCK_ACTIVE_PX = 96;
 const NORMAL_INPUT_BLOCK_SAFE_PX = 96;
 
 /**
- * Height of the Virtuoso footer spacer needed so the last message clears the floating input.
+ * Height of the footer spacer needed so the last message clears the floating input.
  * `measuredInputHeight` is the drop-zone `offsetHeight` from ChatInput (excluding the viewport bottom inset in `CHAT_INPUT_DROP_ZONE_BOTTOM_PX`).
  *
- * When `isInputActive` transitions from `true` to `false` (user sends a message,
- * input collapses to capsule), the ResizeObserver on the drop-zone fires with the
- * *new* collapsed height on the same microtask. If we use that new height
- * immediately, the Virtuoso footer shrinks by ~40 px in one frame, the browser
- * clamps `scrollTop` downward, and the viewport briefly shows blank space at the
- * top ("white screen"). The user must scroll up to see content again.
- *
- * To avoid this, when the input is *not* active we ignore the measured height
- * and use the active fallback instead. The footer stays large enough to cover
- * the active input block until the next turn's content grows past it, at which
- * point the footer reservation is consumed organically by the grow branch of
- * `measureHeightChange`. The visual cost is a few extra pixels of blank tail
- * space at the bottom — invisible to the user.
+ * The footer reflects only the current layout. It does not retain an earlier
+ * input height or manufacture scroll range to protect a viewport anchor.
  */
 export function computeFlowChatInputStackFooterPx(
   measuredInputHeight: number,
-  isInputActive: boolean,
 ): number {
-  // When the input is collapsed, always use the active fallback so the footer
-  // does not shrink on the same frame as the input collapse transition. This
-  // prevents a scrollTop clamp that would push the viewport above the content.
-  const effectiveInputHeight = isInputActive
+  const inputBlock = measuredInputHeight > 0
     ? measuredInputHeight
-    : FALLBACK_INPUT_BLOCK_ACTIVE_PX;
-
-  const measuredInputBlock = effectiveInputHeight > 0
-    ? effectiveInputHeight
-    : FALLBACK_INPUT_BLOCK_ACTIVE_PX;
-  const inputBlock = Math.max(measuredInputBlock, NORMAL_INPUT_BLOCK_SAFE_PX);
+    : NORMAL_INPUT_BLOCK_SAFE_PX;
   return inputBlock + CHAT_INPUT_DROP_ZONE_BOTTOM_PX + FLOWCHAT_MESSAGE_TAIL_CLEARANCE_PX;
 }
diff --git a/src/web-ui/src/flow_chat/utils/flowChatTailEase.test.ts b/src/web-ui/src/flow_chat/utils/flowChatTailEase.test.ts
new file mode 100644
index 0000000000..011377e4ab
--- /dev/null
+++ b/src/web-ui/src/flow_chat/utils/flowChatTailEase.test.ts
@@ -0,0 +1,124 @@
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  nextEasedScrollTopPx,
+  shouldEaseTailFollow,
+  TAIL_EASE_ALPHA,
+  TAIL_EASE_LANDED_PX,
+  TAIL_EASE_LINE_PX,
+  TAIL_EASE_SNAP_ABOVE_PX,
+} from './flowChatTailEase';
+
+describe('nextEasedScrollTopPx', () => {
+  it('covers a fixed fraction of what is left', () => {
+    const step = nextEasedScrollTopPx(100, 180);
+
+    expect(step.outcome).toBe('eased');
+    expect(step.offsetPx).toBeCloseTo(100 + 80 * TAIL_EASE_ALPHA, 6);
+  });
+
+  it('converges rather than overshooting', () => {
+    let offsetPx = 0;
+    for (let frame = 0; frame < 60; frame += 1) {
+      const step = nextEasedScrollTopPx(offsetPx, 100);
+      expect(step.offsetPx).toBeLessThanOrEqual(100);
+      offsetPx = step.offsetPx;
+    }
+
+    expect(offsetPx).toBe(100);
+  });
+
+  it('writes out the last fraction of a pixel instead of halving it forever', () => {
+    const step = nextEasedScrollTopPx(100 - TAIL_EASE_LANDED_PX, 100);
+
+    expect(step).toEqual({ offsetPx: 100, outcome: 'landed' });
+  });
+
+  it('reports having landed when there is nowhere to go', () => {
+    expect(nextEasedScrollTopPx(100, 100)).toEqual({ offsetPx: 100, outcome: 'landed' });
+  });
+
+  it('jumps rather than animating through content nobody saw', () => {
+    const step = nextEasedScrollTopPx(0, TAIL_EASE_SNAP_ABOVE_PX + 1);
+
+    expect(step).toEqual({ offsetPx: TAIL_EASE_SNAP_ABOVE_PX + 1, outcome: 'snapped' });
+  });
+
+  it('eases right up to the snap threshold', () => {
+    expect(nextEasedScrollTopPx(0, TAIL_EASE_SNAP_ABOVE_PX).outcome).toBe('eased');
+  });
+
+  it('never takes an eased step bigger than the line it exists to break up', () => {
+    // The threshold is derived from this: past it the opening step of an ease
+    // is larger than the jump it replaces, so the follow jumps instead.
+    const worstEasedStepPx = nextEasedScrollTopPx(0, TAIL_EASE_SNAP_ABOVE_PX).offsetPx;
+
+    expect(worstEasedStepPx).toBeLessThanOrEqual(TAIL_EASE_LINE_PX);
+  });
+
+  it('goes straight to a target above it, because a shrink eased reads as a claw-back', () => {
+    const step = nextEasedScrollTopPx(400, 320);
+
+    expect(step).toEqual({ offsetPx: 320, outcome: 'landed' });
+  });
+
+  it('settles on the growth per frame under steady growth, whatever alpha is', () => {
+    // The point of the ease is even motion, not slower motion: at equilibrium
+    // it moves exactly as fast as the content grows.
+    const growthPerFramePx = 8;
+    let offsetPx = 0;
+    let targetPx = 0;
+    let lastStepPx = 0;
+    for (let frame = 0; frame < 200; frame += 1) {
+      targetPx += growthPerFramePx;
+      const step = nextEasedScrollTopPx(offsetPx, targetPx);
+      lastStepPx = step.offsetPx - offsetPx;
+      offsetPx = step.offsetPx;
+    }
+
+    expect(lastStepPx).toBeCloseTo(growthPerFramePx, 3);
+    // And the price of that evenness is riding a fixed distance behind: the
+    // frame's own growth is already in the target when the ease acts on it.
+    expect(targetPx - offsetPx).toBeCloseTo(
+      growthPerFramePx * (1 - TAIL_EASE_ALPHA) / TAIL_EASE_ALPHA,
+      3,
+    );
+  });
+});
+
+describe('shouldEaseTailFollow', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  function stubReducedMotion(matches: boolean): void {
+    vi.stubGlobal('matchMedia', vi.fn(() => ({ matches })));
+  }
+
+  it('refuses while the box is still growing, where a smooth follow would cost a re-measure', () => {
+    stubReducedMotion(false);
+
+    expect(shouldEaseTailFollow({ scrollHeightPx: 200, clientHeightPx: 300 })).toBe(false);
+    expect(shouldEaseTailFollow({ scrollHeightPx: 300, clientHeightPx: 300 })).toBe(false);
+  });
+
+  it('eases once the box overflows and there is an offset to move', () => {
+    stubReducedMotion(false);
+
+    expect(shouldEaseTailFollow({ scrollHeightPx: 301, clientHeightPx: 300 })).toBe(true);
+  });
+
+  it('refuses when the reader asked for less motion', () => {
+    stubReducedMotion(true);
+
+    expect(shouldEaseTailFollow({ scrollHeightPx: 900, clientHeightPx: 300 })).toBe(false);
+  });
+
+  it('eases where matchMedia is unavailable rather than treating that as a preference', () => {
+    vi.stubGlobal('matchMedia', undefined);
+
+    expect(shouldEaseTailFollow({ scrollHeightPx: 900, clientHeightPx: 300 })).toBe(true);
+  });
+});
diff --git a/src/web-ui/src/flow_chat/utils/flowChatTailEase.ts b/src/web-ui/src/flow_chat/utils/flowChatTailEase.ts
new file mode 100644
index 0000000000..3c5a48ceea
--- /dev/null
+++ b/src/web-ui/src/flow_chat/utils/flowChatTailEase.ts
@@ -0,0 +1,105 @@
+/**
+ * Easing a scroll offset towards the bottom of its own content.
+ *
+ * A follow that assigns the tail offset outright moves whenever the content
+ * reflows, which for Markdown means a whole line at a time with nothing in
+ * between. Easing spends the same distance over the frames that were empty.
+ *
+ * Worth being clear about what this can and cannot do, because it bounds what
+ * any tuning is allowed to promise. Under steady growth the eased offset
+ * settles where its per-frame catch-up equals the growth, so the visible step
+ * converges on *the content's growth per frame* whatever `TAIL_EASE_ALPHA` is.
+ * Smoothing does not make the tail move more slowly; it spreads a lumpy motion
+ * evenly across the frames it already had. At eight lines a second that turns
+ * one 24px jump every seven frames into 3px every frame; at thirty lines a
+ * second the frames run out and the step stays around half a line.
+ *
+ * `TAIL_EASE_ALPHA` therefore buys latency, not smoothness: it sets how far
+ * behind the tail the offset rides, which is what has to be given back when the
+ * stream stops.
+ *
+ * This eases an offset, not a height. Offsets are the cheap case — scrolling
+ * inside a box changes no layout outside it — which is why the decision here is
+ * about how it looks and not about what it costs.
+ */
+
+/** Fraction of the remaining distance covered each frame. */
+export const TAIL_EASE_ALPHA = 0.25;
+
+/**
+ * A line of FlowChat body text, near enough.
+ *
+ * Not used to lay anything out — it is the size of the step an unsmoothed
+ * follow makes, and so the bar this one has to stay under to be worth having.
+ */
+export const TAIL_EASE_LINE_PX = 24;
+
+/**
+ * Distance past which the follow gives up on easing and jumps.
+ *
+ * Derived rather than chosen: the first frame of an ease covers `TAIL_EASE_ALPHA`
+ * of the distance, so beyond a line's worth divided by that fraction, the ease's
+ * *opening step* is already bigger than the jump it set out to replace. A
+ * measured burst arriving 238px behind produced a single 59px step — two and a
+ * half lines — before settling, which is worse than having simply jumped.
+ *
+ * So above this the follow jumps and says so. Below it, no step it takes can
+ * exceed a line.
+ */
+export const TAIL_EASE_SNAP_ABOVE_PX = TAIL_EASE_LINE_PX / TAIL_EASE_ALPHA;
+
+/** Below this the remaining distance is written out rather than halved again. */
+export const TAIL_EASE_LANDED_PX = 0.5;
+
+export type TailEaseOutcome =
+  /** Moved part of the way; the follow should keep going next frame. */
+  | 'eased'
+  /** Went the whole way deliberately, because easing was not worth it. */
+  | 'snapped'
+  /** Arrived. Nothing more to do until the content moves again. */
+  | 'landed';
+
+export interface TailEaseStep {
+  offsetPx: number;
+  outcome: TailEaseOutcome;
+}
+
+/**
+ * Where a following scroll offset should be written this frame.
+ *
+ * A target *above* the current offset is not eased. It means the content got
+ * shorter — a fence closing, a table reflowing — and easing down through it
+ * reads as the view being clawed backwards, which is worse than the jump it
+ * replaces.
+ */
+export function nextEasedScrollTopPx(currentPx: number, targetPx: number): TailEaseStep {
+  const distancePx = targetPx - currentPx;
+  if (distancePx <= TAIL_EASE_LANDED_PX) {
+    return { offsetPx: targetPx, outcome: 'landed' };
+  }
+  if (distancePx > TAIL_EASE_SNAP_ABOVE_PX) {
+    return { offsetPx: targetPx, outcome: 'snapped' };
+  }
+  return { offsetPx: currentPx + distancePx * TAIL_EASE_ALPHA, outcome: 'eased' };
+}
+
+/**
+ * Whether this follow should ease at all.
+ *
+ * Two conditions, and both are about cost rather than taste. A box that is not
+ * yet overflowing has no scroll offset to ease — it is still growing, and
+ * moving *that* smoothly would mean animating a height, which every frame
+ * charges to the virtualizer. And a reader who asked for less motion is asking
+ * about exactly this.
+ */
+export function shouldEaseTailFollow(options: {
+  scrollHeightPx: number;
+  clientHeightPx: number;
+}): boolean {
+  if (options.scrollHeightPx <= options.clientHeightPx) return false;
+  return !prefersReducedMotion();
+}
+
+function prefersReducedMotion(): boolean {
+  return globalThis.matchMedia?.('(prefers-reduced-motion: reduce)').matches ?? false;
+}
diff --git a/src/web-ui/src/flow_chat/utils/flowChatTurnIdentity.test.ts b/src/web-ui/src/flow_chat/utils/flowChatTurnIdentity.test.ts
new file mode 100644
index 0000000000..332154a48a
--- /dev/null
+++ b/src/web-ui/src/flow_chat/utils/flowChatTurnIdentity.test.ts
@@ -0,0 +1,85 @@
+import { describe, expect, it } from 'vitest';
+
+import { nextStorageTurnIndex } from './flowChatTurnIdentity';
+import type { DialogTurn } from '../types/flow-chat';
+
+const SESSION_ID = 'acp_dsh_session';
+
+function turn(id: string, storageTurnIndex?: number): DialogTurn {
+  return {
+    id,
+    sessionId: SESSION_ID,
+    userMessage: { id: `user-${id}`, content: 'hi', timestamp: 1 },
+    modelRounds: [],
+    status: 'completed',
+    startTime: 1,
+    storageTurnIndex,
+  };
+}
+
+function session(overrides: Record<string, unknown> = {}): any {
+  return {
+    sessionId: SESSION_ID,
+    dialogTurns: [],
+    ...overrides,
+  };
+}
+
+describe('nextStorageTurnIndex', () => {
+  it('gives the first turn of an empty session slot zero', () => {
+    expect(nextStorageTurnIndex(session())).toBe(0);
+  });
+
+  it('continues after the highest slot already projected', () => {
+    expect(
+      nextStorageTurnIndex(session({ dialogTurns: [turn('a', 0), turn('b', 1)] })),
+    ).toBe(2);
+  });
+
+  it('continues after the catalog when the loaded window is only the tail', () => {
+    expect(
+      nextStorageTurnIndex(session({
+        dialogTurns: [turn('e', 4)],
+        isPartial: true,
+        totalTurnCount: 5,
+        turnCatalog: {
+          sessionId: SESSION_ID,
+          totalTurnCount: 5,
+          entries: [
+            { turnId: 'a', ordinal: 0, storageTurnIndex: 0 },
+            { turnId: 'e', ordinal: 4, storageTurnIndex: 4 },
+          ],
+        },
+      })),
+    ).toBe(5);
+  });
+
+  it('ignores a catalog belonging to another session', () => {
+    expect(
+      nextStorageTurnIndex(session({
+        dialogTurns: [turn('a', 0)],
+        turnCatalog: {
+          sessionId: 'some-other-session',
+          totalTurnCount: 9,
+          entries: [{ turnId: 'x', ordinal: 8, storageTurnIndex: 8 }],
+        },
+      })),
+    ).toBe(1);
+  });
+
+  it('reads the slot of a turn restored under the deprecated field', () => {
+    const restored = turn('a');
+    restored.backendTurnIndex = 3;
+    expect(nextStorageTurnIndex(session({ dialogTurns: [restored] }))).toBe(4);
+  });
+
+  it('refuses to guess while persisted turns are not projected yet', () => {
+    expect(
+      nextStorageTurnIndex(session({
+        dialogTurns: [],
+        isPartial: true,
+        totalTurnCount: 3,
+      })),
+    ).toBeUndefined();
+  });
+});
diff --git a/src/web-ui/src/flow_chat/utils/flowChatTurnIdentity.ts b/src/web-ui/src/flow_chat/utils/flowChatTurnIdentity.ts
index 374c3ae726..f52e81095d 100644
--- a/src/web-ui/src/flow_chat/utils/flowChatTurnIdentity.ts
+++ b/src/web-ui/src/flow_chat/utils/flowChatTurnIdentity.ts
@@ -1,9 +1,13 @@
-import type { LocalCommandMetadata } from '@/shared/types/session-history';
+import type {
+  LocalCommandMetadata,
+  SessionTurnCatalog,
+} from '@/shared/types/session-history';
 import type {
   DialogTurn,
   DialogTurnIdentity,
   LocalTurnIndex,
   Session,
+  SessionHistoryViewState,
   StorageTurnIndex,
   TurnOrdinal,
 } from '../types/flow-chat';
@@ -43,6 +47,57 @@ export function validSessionTurnCatalog(session: TurnIdentitySession) {
     : undefined;
 }
 
+export interface MaterializedSessionTurnIdentity {
+  turn?: DialogTurn;
+  catalog?: SessionTurnCatalog;
+  ordinal?: TurnOrdinal;
+  storageTurnIndex?: StorageTurnIndex;
+}
+
+/**
+ * Resolve a stable Turn identity from either the canonical live tail or an
+ * already-materialized history window. A catalog-only result remains valid
+ * if the rendered range was pruned while a confirmation dialog was open.
+ */
+export function resolveMaterializedSessionTurnIdentity(
+  session: TurnIdentitySession,
+  historyView: Pick<SessionHistoryViewState, 'catalog' | 'loadedRanges'> | undefined,
+  turnId: string,
+): MaterializedSessionTurnIdentity | undefined {
+  const canonicalTurn = session.dialogTurns.find(candidate => candidate.id === turnId);
+  const materializedRange = canonicalTurn
+    ? undefined
+    : historyView?.loadedRanges.find(range =>
+      range.turns.some(candidate => candidate.id === turnId));
+  const materializedTurnIndex = materializedRange?.turns.findIndex(
+    candidate => candidate.id === turnId,
+  ) ?? -1;
+  const turn = canonicalTurn
+    ?? (materializedTurnIndex >= 0 ? materializedRange?.turns[materializedTurnIndex] : undefined);
+  const catalogs = [validSessionTurnCatalog(session), historyView?.catalog]
+    .filter((catalog): catalog is SessionTurnCatalog => catalog?.sessionId === session.sessionId);
+  const catalog = catalogs.find(candidate => candidate.entries.some(entry => entry.turnId === turnId));
+  const entry = catalog?.entries.find(candidate => candidate.turnId === turnId);
+  if (!turn && !entry) {
+    return undefined;
+  }
+  const directStorageTurnIndex = turn?.storageTurnIndex ?? turn?.backendTurnIndex;
+  return {
+    turn,
+    catalog,
+    ordinal: entry
+      ? asTurnOrdinal(entry.ordinal)
+      : materializedRange && materializedTurnIndex >= 0
+        ? asTurnOrdinal(materializedRange.startOrdinal + materializedTurnIndex)
+        : undefined,
+    storageTurnIndex: directStorageTurnIndex !== undefined
+      ? asStorageTurnIndex(directStorageTurnIndex)
+      : entry
+        ? asStorageTurnIndex(entry.storageTurnIndex)
+        : undefined,
+  };
+}
+
 export function projectedSessionTurnCount(session: TurnIdentitySession): number {
   const persistedTurnCount = canonicalSessionTurns(session).length;
   return Math.max(
@@ -83,6 +138,35 @@ export function resolveStorageTurnIndex(
     : undefined;
 }
 
+/**
+ * Storage slot for the next Turn of a Session the frontend persists itself.
+ *
+ * The local runtime hands out that slot through `DialogTurnStarted`, but an
+ * ACP agent runs outside it: nothing on the backend counts those Turns, so the
+ * projection allocates the slot from what it already knows. Returns undefined
+ * when the Session has persisted Turns none of which are projected yet —
+ * guessing there would overwrite history.
+ */
+export function nextStorageTurnIndex(
+  session: TurnIdentitySession,
+): StorageTurnIndex | undefined {
+  let highest = -1;
+  for (const turn of session.dialogTurns) {
+    const storageIndex = turn.storageTurnIndex ?? turn.backendTurnIndex;
+    if (typeof storageIndex === 'number') {
+      highest = Math.max(highest, storageIndex);
+    }
+  }
+  for (const entry of validSessionTurnCatalog(session)?.entries ?? []) {
+    highest = Math.max(highest, entry.storageTurnIndex);
+  }
+
+  if (highest < 0 && projectedSessionTurnCount(session) > 0) {
+    return undefined;
+  }
+  return asStorageTurnIndex(highest + 1);
+}
+
 function buildCatalogOrdinalMaps(session: TurnIdentitySession): {
   ordinalByTurnId: Map<string, TurnOrdinal>;
   ordinalByStorageIndex: Map<number, TurnOrdinal>;
diff --git a/src/web-ui/src/flow_chat/utils/flowChatTurnScrollPolicy.test.ts b/src/web-ui/src/flow_chat/utils/flowChatTurnScrollPolicy.test.ts
index 6777fd6239..438232ac1c 100644
--- a/src/web-ui/src/flow_chat/utils/flowChatTurnScrollPolicy.test.ts
+++ b/src/web-ui/src/flow_chat/utils/flowChatTurnScrollPolicy.test.ts
@@ -4,7 +4,6 @@ import {
   isDialogTurnInFlight,
   isThreadGoalContinuationTurn,
   shouldUseLatestTurnFollowOutput,
-  shouldUseStickyLatestPin,
 } from './flowChatTurnScrollPolicy';
 
 function makeTurn(partial: Partial<DialogTurn>): DialogTurn {
@@ -29,7 +28,7 @@ describe('flowChatTurnScrollPolicy', () => {
     expect(isDialogTurnInFlight(turn)).toBe(false);
   });
 
-  it('skips sticky pin for thread goal continuation turns', () => {
+  it('skips natural tail follow for thread goal continuation turns', () => {
     const turn = makeTurn({
       status: 'processing',
       userMessage: {
@@ -41,10 +40,9 @@ describe('flowChatTurnScrollPolicy', () => {
     });
     expect(isThreadGoalContinuationTurn(turn)).toBe(true);
     expect(shouldUseLatestTurnFollowOutput(turn)).toBe(false);
-    expect(shouldUseStickyLatestPin(turn)).toBe(false);
   });
 
-  it('allows sticky pin for in-flight user turns', () => {
+  it('follows in-flight user turns at the natural tail', () => {
     const turn = makeTurn({
       status: 'processing',
       modelRounds: [{
@@ -56,13 +54,11 @@ describe('flowChatTurnScrollPolicy', () => {
       }],
     } as Partial<DialogTurn>);
     expect(shouldUseLatestTurnFollowOutput(turn)).toBe(true);
-    expect(shouldUseStickyLatestPin(turn)).toBe(true);
   });
 
-  it('lets follow-output own a newly submitted user-only turn before sticky pin starts', () => {
+  it('lets follow-output own a newly submitted user-only turn', () => {
     const turn = makeTurn({ status: 'processing', modelRounds: [] });
     expect(isDialogTurnInFlight(turn)).toBe(true);
     expect(shouldUseLatestTurnFollowOutput(turn)).toBe(true);
-    expect(shouldUseStickyLatestPin(turn)).toBe(false);
   });
 });
diff --git a/src/web-ui/src/flow_chat/utils/flowChatTurnScrollPolicy.ts b/src/web-ui/src/flow_chat/utils/flowChatTurnScrollPolicy.ts
index 1d1ceafd00..5fbe6cae44 100644
--- a/src/web-ui/src/flow_chat/utils/flowChatTurnScrollPolicy.ts
+++ b/src/web-ui/src/flow_chat/utils/flowChatTurnScrollPolicy.ts
@@ -28,14 +28,6 @@ export function shouldUseLatestTurnFollowOutput(turn: DialogTurn | undefined): b
   return isDialogTurnInFlight(turn);
 }
 
-/** Sticky-latest pin starts only after model output exists. */
-export function shouldUseStickyLatestPin(turn: DialogTurn | undefined): boolean {
-  if (!turn || !shouldUseLatestTurnFollowOutput(turn)) {
-    return false;
-  }
-  return turn.modelRounds.length > 0;
-}
-
 export function findDialogTurn(
   dialogTurns: DialogTurn[] | undefined,
   turnId: string | null | undefined,
diff --git a/src/web-ui/src/flow_chat/utils/interruptedTurnRecovery.test.ts b/src/web-ui/src/flow_chat/utils/interruptedTurnRecovery.test.ts
new file mode 100644
index 0000000000..4c4b85dfa1
--- /dev/null
+++ b/src/web-ui/src/flow_chat/utils/interruptedTurnRecovery.test.ts
@@ -0,0 +1,106 @@
+import { describe, expect, it } from 'vitest';
+import type { Session } from '../types/flow-chat';
+import {
+  hasInterruptedTurnHoldingQueue,
+  selectInterruptedTurnRecovery,
+} from './interruptedTurnRecovery';
+
+function interruptedSession(overrides: Partial<Session> = {}): Session {
+  return {
+    sessionId: 'session-1',
+    dialogTurns: [{
+      id: 'turn-1',
+      sessionId: 'session-1',
+      agentType: 'agentic',
+      userMessage: { id: 'user-1', content: 'finish the task', timestamp: 1 },
+      modelRounds: [],
+      status: 'cancelled',
+      finishReason: 'interrupted',
+      recovery: {
+        status: 'interrupted',
+        executionGeneration: 2,
+        resumeCount: 2,
+        modelId: 'model-a',
+      },
+      startTime: 1,
+    }],
+    status: 'idle',
+    config: { agentType: 'agentic', modelName: 'model-a', workspacePath: 'D:/workspace' },
+    createdAt: 1,
+    lastActiveAt: 1,
+    error: null,
+    mode: 'agentic',
+    sessionKind: 'normal',
+    ...overrides,
+  };
+}
+
+const emptyComposer = {
+  draft: '',
+  hasComposerAttachments: false,
+  executionIdle: true,
+  desktopRuntime: true,
+  peerMode: false,
+  acpSession: false,
+  modeChangePending: false,
+  modelChangePending: false,
+};
+
+describe('selectInterruptedTurnRecovery', () => {
+  it('returns the latest interrupted turn and generation for an empty local composer', () => {
+    expect(selectInterruptedTurnRecovery(interruptedSession(), emptyComposer)).toEqual({
+      sessionId: 'session-1',
+      turnId: 'turn-1',
+      executionGeneration: 2,
+    });
+  });
+
+  it.each([
+    ['draft text', { draft: 'new request' }],
+    ['attachments', { hasComposerAttachments: true }],
+    ['remote workspace', {}, { remoteConnectionId: 'remote-1' }],
+    ['peer mode', { peerMode: true }],
+    ['web runtime', { desktopRuntime: false }],
+    ['ACP session', { acpSession: true }],
+    ['active goal', {}, { threadGoal: { goalId: 'goal-1', objective: 'ship', status: 'active' } }],
+    ['mode change', {}, { mode: 'review' }],
+    ['model change', {}, { config: { agentType: 'agentic', modelName: 'model-b' } }],
+    ['pending mode update', { modeChangePending: true }],
+  ])('hides recovery for %s', (_label, optionOverrides, sessionOverrides = {}) => {
+    expect(selectInterruptedTurnRecovery(
+      interruptedSession(sessionOverrides as Partial<Session>),
+      { ...emptyComposer, ...optionOverrides },
+    )).toBeNull();
+  });
+
+  it('rejects stale, non-latest, recovering, and ordinary cancelled turns', () => {
+    const base = interruptedSession();
+    expect(selectInterruptedTurnRecovery({
+      ...base,
+      dialogTurns: [
+        base.dialogTurns[0],
+        { ...base.dialogTurns[0], id: 'turn-2', finishReason: 'cancelled', recovery: undefined },
+      ],
+    }, emptyComposer)).toBeNull();
+    expect(selectInterruptedTurnRecovery({
+      ...base,
+      dialogTurns: [{
+        ...base.dialogTurns[0],
+        status: 'processing',
+        recovery: { ...base.dialogTurns[0].recovery!, status: 'recovering' },
+      }],
+    }, emptyComposer)).toBeNull();
+  });
+
+  it('holds pending input only while the latest turn is awaiting a recovery decision', () => {
+    const session = interruptedSession();
+    expect(hasInterruptedTurnHoldingQueue(session)).toBe(true);
+    expect(hasInterruptedTurnHoldingQueue({
+      ...session,
+      dialogTurns: [{
+        ...session.dialogTurns[0],
+        recovery: { ...session.dialogTurns[0].recovery!, status: 'recovering' },
+      }],
+    })).toBe(false);
+  });
+});
diff --git a/src/web-ui/src/flow_chat/utils/interruptedTurnRecovery.ts b/src/web-ui/src/flow_chat/utils/interruptedTurnRecovery.ts
new file mode 100644
index 0000000000..1b70634b71
--- /dev/null
+++ b/src/web-ui/src/flow_chat/utils/interruptedTurnRecovery.ts
@@ -0,0 +1,94 @@
+import type { Session } from '../types/flow-chat';
+
+export interface InterruptedTurnRecoveryCandidate {
+  sessionId: string;
+  turnId: string;
+  executionGeneration: number;
+}
+
+export interface InterruptedTurnRecoveryComposerState {
+  draft: string;
+  hasComposerAttachments: boolean;
+  executionIdle: boolean;
+  desktopRuntime: boolean;
+  peerMode: boolean;
+  acpSession: boolean;
+  modeChangePending: boolean;
+  modelChangePending: boolean;
+}
+
+/**
+ * Pure capability predicate for the input button. Runtime validation remains
+ * authoritative; this function prevents unsupported or ambiguous states from
+ * presenting a recovery action in the first place.
+ */
+export function selectInterruptedTurnRecovery(
+  session: Session | undefined,
+  composer: InterruptedTurnRecoveryComposerState,
+): InterruptedTurnRecoveryCandidate | null {
+  if (
+    !session
+    || session.sessionKind !== 'normal'
+    || !composer.executionIdle
+    || !composer.desktopRuntime
+    || composer.peerMode
+    || composer.acpSession
+    || composer.modeChangePending
+    || composer.modelChangePending
+    || composer.draft.trim().length > 0
+    || composer.hasComposerAttachments
+    || session.remoteConnectionId
+    || session.remoteSshHost
+    || session.config.remoteConnectionId
+    || session.config.remoteSshHost
+    || session.config.dispatchTarget
+    || session.config.dispatchJobId
+  ) {
+    return null;
+  }
+
+  const goalStatus = session.threadGoal?.status.toLowerCase();
+  if (goalStatus === 'active' || goalStatus === 'paused') {
+    return null;
+  }
+
+  const turn = session.dialogTurns.at(-1);
+  if (
+    !turn
+    || turn.status !== 'cancelled'
+    || turn.finishReason !== 'interrupted'
+    || turn.recovery?.status !== 'interrupted'
+    || !Number.isSafeInteger(turn.recovery.executionGeneration)
+    || turn.recovery.executionGeneration < 0
+  ) {
+    return null;
+  }
+
+  const selectedMode = session.mode || session.config.agentType;
+  if (turn.agentType && selectedMode && turn.agentType !== selectedMode) {
+    return null;
+  }
+  if (
+    turn.recovery.modelId
+    && session.config.modelName
+    && turn.recovery.modelId !== session.config.modelName
+  ) {
+    return null;
+  }
+
+  return {
+    sessionId: session.sessionId,
+    turnId: turn.id,
+    executionGeneration: turn.recovery.executionGeneration,
+  };
+}
+
+export function hasInterruptedTurnHoldingQueue(session: Session | undefined): boolean {
+  const latest = session?.dialogTurns.at(-1);
+  return Boolean(
+    latest
+    && latest.status === 'cancelled'
+    && latest.finishReason === 'interrupted'
+    && latest.recovery?.status === 'interrupted',
+  );
+}
diff --git a/src/web-ui/src/flow_chat/utils/modelSync.ts b/src/web-ui/src/flow_chat/utils/modelSync.ts
index d058311c14..2e46a04897 100644
--- a/src/web-ui/src/flow_chat/utils/modelSync.ts
+++ b/src/web-ui/src/flow_chat/utils/modelSync.ts
@@ -12,6 +12,10 @@ import { createLogger } from '@/shared/utils/logger';
 import type { FlowChatContext } from '../services/flow-chat-manager/types';
 import { getModelMaxTokens } from './modelResolution';
 import { sessionProjectWorkspacePath } from './sessionWorkspace';
+import {
+  getActiveSurfaceScope,
+  type SurfaceScope,
+} from '@/infrastructure/peer-device/deviceSurface';
 
 const log = createLogger('ModelSync');
 
@@ -39,6 +43,7 @@ export async function syncSessionModelSelection(
   context: FlowChatContext,
   sessionId: string,
   agentType: string,
+  surfaceScope: SurfaceScope = getActiveSurfaceScope(),
 ): Promise<void> {
   const session = context.flowChatStore.getState().sessions.get(sessionId);
   if (!session) {
@@ -51,6 +56,7 @@ export async function syncSessionModelSelection(
   // it to the backend in case the restored runtime session lost that state.
   if (sessionModelId) {
     const desiredMaxContextTokens = await getModelMaxTokens(sessionModelId, agentType);
+    surfaceScope.assertCurrent('resolve session model context window');
     if (session.maxContextTokens !== desiredMaxContextTokens) {
       context.flowChatStore.updateSessionMaxContextTokens(sessionId, desiredMaxContextTokens);
     }
@@ -63,6 +69,7 @@ export async function syncSessionModelSelection(
       remoteSshHost: session.remoteSshHost,
       includeInternal: session.sessionKind === 'subagent',
     });
+    surfaceScope.assertCurrent('synchronize session model');
     return;
   }
 
@@ -71,6 +78,7 @@ export async function syncSessionModelSelection(
     'ai.models',
     'ai.default_models',
   ]);
+  surfaceScope.assertCurrent('load session model configuration');
   const agentModelDefaults = configData['ai.agent_model_defaults'] as AgentModelDefaultsConfig | undefined;
   const allModels = (configData['ai.models'] as AIModelConfig[] | undefined) || [];
   const defaultModels = (configData['ai.default_models'] as DefaultModelsConfig | undefined) || {};
@@ -78,6 +86,7 @@ export async function syncSessionModelSelection(
   const desiredModelId = normalizeModelSelection(agentModelDefaults?.mode, allModels, defaultModels);
   const shouldForceAutoSync = desiredModelId === 'auto';
   const desiredMaxContextTokens = await getModelMaxTokens(desiredModelId, agentType);
+  surfaceScope.assertCurrent('resolve session model context window');
   const shouldSyncContextWindow = session.maxContextTokens !== desiredMaxContextTokens;
 
   context.flowChatStore.updateSessionModelName(sessionId, desiredModelId);
@@ -93,6 +102,7 @@ export async function syncSessionModelSelection(
     remoteSshHost: session.remoteSshHost,
     includeInternal: session.sessionKind === 'subagent',
   });
+  surfaceScope.assertCurrent('synchronize session model');
 
   log.info('Session model synchronized before send', {
     sessionId,
diff --git a/src/web-ui/src/flow_chat/utils/motionPreference.ts b/src/web-ui/src/flow_chat/utils/motionPreference.ts
new file mode 100644
index 0000000000..00fc21148b
--- /dev/null
+++ b/src/web-ui/src/flow_chat/utils/motionPreference.ts
@@ -0,0 +1,2 @@
+export { getMotionAwareScrollBehavior } from '@/shared/utils/motionPreference';
+export type { MotionAwareScrollBehavior } from '@/shared/utils/motionPreference';
diff --git a/src/web-ui/src/flow_chat/utils/sessionWorkspace.ts b/src/web-ui/src/flow_chat/utils/sessionWorkspace.ts
index 7d099c4518..6b13865233 100644
--- a/src/web-ui/src/flow_chat/utils/sessionWorkspace.ts
+++ b/src/web-ui/src/flow_chat/utils/sessionWorkspace.ts
@@ -25,7 +25,7 @@ export function isRemoteWorkspaceSession(
 export function sessionExecutionWorkspacePath(
   session: SessionWorkspaceBinding,
 ): string | undefined {
-  return session.workspacePath || session.config.workspacePath;
+  return session.workspacePath || session.config?.workspacePath;
 }
 
 /** Main-project root that owns session persistence and orchestration state. */
@@ -34,7 +34,7 @@ export function sessionProjectWorkspacePath(
 ): string | undefined {
   return (
     session.projectWorkspacePath
-    || session.config.projectWorkspacePath
+    || session.config?.projectWorkspacePath
     || sessionExecutionWorkspacePath(session)
   );
 }
diff --git a/src/web-ui/src/flow_chat/utils/sessionWorktree.test.ts b/src/web-ui/src/flow_chat/utils/sessionWorktree.test.ts
index 02d81bd554..99f1155e95 100644
--- a/src/web-ui/src/flow_chat/utils/sessionWorktree.test.ts
+++ b/src/web-ui/src/flow_chat/utils/sessionWorktree.test.ts
@@ -83,6 +83,19 @@ describe('session worktree control', () => {
     }))).toBeUndefined();
   });
 
+  it('discards a stale pending change once the session has persisted work', () => {
+    expect(sessionWorktreeMaterializationPlan(session({
+      totalTurnCount: 1,
+      config: {
+        executionTarget: {
+          kind: 'local',
+          rootPath: '/repo',
+        },
+        worktreeIsolationRequested: true,
+      },
+    }))).toBeUndefined();
+  });
+
   it('invalidates the composer subscription after hydrate and rebind', () => {
     const initial = sessionWorktreeBindingSubscriptionKey(session());
     const armed = sessionWorktreeBindingSubscriptionKey(session({
diff --git a/src/web-ui/src/flow_chat/utils/sessionWorktree.ts b/src/web-ui/src/flow_chat/utils/sessionWorktree.ts
index 79d76027a2..fdd57ec157 100644
--- a/src/web-ui/src/flow_chat/utils/sessionWorktree.ts
+++ b/src/web-ui/src/flow_chat/utils/sessionWorktree.ts
@@ -47,7 +47,8 @@ export interface SessionWorktreeMaterializationPlan {
 /**
  * Resolve the one transition that must run after a prompt is submitted and
  * before its backend turn starts. `undefined` means the checkbox has not
- * requested a change, or the session is already materialized as requested.
+ * requested a change, the session is already materialized as requested, or
+ * persisted work means it is too late to change the execution root.
  */
 export function sessionWorktreeMaterializationPlan(
   session: SessionWorktreeFacts,
@@ -55,6 +56,7 @@ export function sessionWorktreeMaterializationPlan(
   const requested = session.config.worktreeIsolationRequested;
   if (
     requested === undefined
+    || isSessionWorktreeBindingLocked(session, false)
     || requested === isSessionWorktreeMaterialized(session)
   ) {
     return undefined;
diff --git a/src/web-ui/src/flow_chat/utils/workspaceScope.test.ts b/src/web-ui/src/flow_chat/utils/workspaceScope.test.ts
new file mode 100644
index 0000000000..b8dd5d5c74
--- /dev/null
+++ b/src/web-ui/src/flow_chat/utils/workspaceScope.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+import type { WorkspaceInfo } from '@/shared/types';
+import { findWorkspaceForSession } from './workspaceScope';
+
+function remoteWorkspace(id: string, connectionId: string): WorkspaceInfo {
+  return {
+    id,
+    rootPath: '/workspace',
+    connectionId,
+    sshHost: `${connectionId}.example.test`,
+  } as WorkspaceInfo;
+}
+
+describe('findWorkspaceForSession', () => {
+  it('uses remote identity instead of an ambiguous POSIX path', () => {
+    const first = remoteWorkspace('workspace-a', 'connection-a');
+    const second = remoteWorkspace('workspace-b', 'connection-b');
+
+    expect(findWorkspaceForSession({
+      workspacePath: '/workspace',
+      remoteConnectionId: 'connection-b',
+    }, [first, second])).toBe(second);
+  });
+});
diff --git a/src/web-ui/src/infrastructure/api/adapters/base.ts b/src/web-ui/src/infrastructure/api/adapters/base.ts
index 2af431c7dd..3f12b8dcf0 100644
--- a/src/web-ui/src/infrastructure/api/adapters/base.ts
+++ b/src/web-ui/src/infrastructure/api/adapters/base.ts
@@ -16,6 +16,9 @@ export interface ITransportAdapter {
    * transport have settled. Synchronous transports can keep the default no-op.
    */
   waitForListenerRegistrations?(): Promise<void>;
+
+  /** Whether command-scoped file-search progress events reach this surface. */
+  supportsSearchStreamEvents?(): boolean;
   
    
   disconnect(): Promise<void>;
@@ -58,4 +61,3 @@ export interface ToolEvent extends StreamEvent {
   };
 }
 
-
diff --git a/src/web-ui/src/infrastructure/api/adapters/index.ts b/src/web-ui/src/infrastructure/api/adapters/index.ts
index 86e4b48d27..26514db0b6 100644
--- a/src/web-ui/src/infrastructure/api/adapters/index.ts
+++ b/src/web-ui/src/infrastructure/api/adapters/index.ts
@@ -1,17 +1,24 @@
- 
+
 
 import { ITransportAdapter } from './base';
 import { TauriTransportAdapter } from './tauri-adapter';
 import { WebSocketTransportAdapter } from './websocket-adapter';
+import { PeerDeviceTransportAdapter } from './peer-device-adapter';
+import {
+  LOCAL_SURFACE_ID,
+  SurfaceChangedError,
+  getActiveSurfaceScope,
+  type DeviceSurfaceId,
+} from '@/infrastructure/peer-device/deviceSurface';
 import { isTauriRuntime } from '@/infrastructure/runtime';
 export * from './base';
 export * from './tauri-adapter';
 export * from './websocket-adapter';
 export * from './peer-device-adapter';
 
- 
+
 export function detectEnvironment(): 'tauri' | 'web' {
-  
+
   if (isTauriRuntime()) {
     return 'tauri';
   }
@@ -19,10 +26,10 @@ export function detectEnvironment(): 'tauri' | 'web' {
   return 'web';
 }
 
- 
+
 export function createTransportAdapter(forceEnv?: 'tauri' | 'web'): ITransportAdapter {
   const env = forceEnv || detectEnvironment();
-  
+
   if (env === 'tauri') {
     return new TauriTransportAdapter();
   } else {
@@ -31,27 +38,104 @@ export function createTransportAdapter(forceEnv?: 'tauri' | 'web'): ITransportAd
   }
 }
 
- 
-let globalAdapter: ITransportAdapter | null = null;
+/**
+ * Which device surface the registered transport serves.
+ *
+ * The global adapter is swapped on every device switch, so "the transport" is
+ * only meaningful together with the surface it was bound for. Recording that
+ * here is what lets work issued before a switch be recognised afterwards
+ * instead of resolving into the surface that replaced it.
+ */
+export interface TransportSurfaceBinding {
+  readonly adapter: ITransportAdapter;
+  readonly surfaceId: DeviceSurfaceId;
+  /** Monotonic per registration: every rebind is a new binding. */
+  readonly generation: number;
+  /** `deviceSurface` activation epoch current when the adapter was bound. */
+  readonly surfaceEpoch: number;
+}
+
+let binding: TransportSurfaceBinding | null = null;
+let bindingCounter = 0;
+
+function surfaceIdOf(adapter: ITransportAdapter): DeviceSurfaceId {
+  return adapter instanceof PeerDeviceTransportAdapter
+    ? adapter.surfaceId
+    : LOCAL_SURFACE_ID;
+}
+
+function bind(adapter: ITransportAdapter, surfaceId: DeviceSurfaceId): TransportSurfaceBinding {
+  const previous = binding;
+  binding = {
+    adapter,
+    surfaceId,
+    generation: ++bindingCounter,
+    surfaceEpoch: getActiveSurfaceScope().epoch,
+  };
+  if (previous && previous.adapter !== adapter) {
+    // Retired peers stay attached and keep running our work; only their claim
+    // on the rendered surface ends here.
+    if (previous.adapter instanceof PeerDeviceTransportAdapter) {
+      previous.adapter.markRenderedTransport(false);
+    }
+  }
+  if (adapter instanceof PeerDeviceTransportAdapter) {
+    // Even rebinding the same adapter is a new surface activation. This is the
+    // invalidation seam used when A's hydrate is superseded before B commits.
+    adapter.markRenderedTransport(true, true);
+  }
+  return binding;
+}
+
 
- 
 export function getTransportAdapter(): ITransportAdapter {
-  if (!globalAdapter) {
-    globalAdapter = createTransportAdapter();
+  return getTransportSurfaceBinding().adapter;
+}
+
+/** The active binding, creating the default local transport on first use. */
+export function getTransportSurfaceBinding(): TransportSurfaceBinding {
+  if (!binding) {
+    const adapter = createTransportAdapter();
+    return bind(adapter, surfaceIdOf(adapter));
   }
-  return globalAdapter;
+  return binding;
 }
 
- 
-export async function resetTransportAdapter(): Promise<void> {
-  if (globalAdapter) {
-    await globalAdapter.disconnect();
-    globalAdapter = null;
+export function getTransportSurfaceId(): DeviceSurfaceId {
+  return getTransportSurfaceBinding().surfaceId;
+}
+
+/**
+ * Throw `SurfaceChangedError` unless the rendered transport still serves
+ * `surfaceId`. For callers that captured a surface before an await and would
+ * otherwise write the answer into whichever device replaced it.
+ */
+export function assertTransportSurface(surfaceId: DeviceSurfaceId, action?: string): void {
+  const current = getTransportSurfaceBinding();
+  if (current.surfaceId !== surfaceId) {
+    throw new SurfaceChangedError(surfaceId, current.surfaceEpoch, action);
   }
 }
 
- 
-export function setTransportAdapter(adapter: ITransportAdapter): void {
-  globalAdapter = adapter;
+
+export async function resetTransportAdapter(): Promise<void> {
+  const current = binding;
+  binding = null;
+  if (current) {
+    if (current.adapter instanceof PeerDeviceTransportAdapter) {
+      current.adapter.markRenderedTransport(false);
+    }
+    await current.adapter.disconnect();
+  }
 }
 
+/**
+ * Point product traffic at `adapter`. `surfaceId` defaults to the surface the
+ * adapter itself serves, so existing single-argument callers stay correct.
+ */
+export function setTransportAdapter(
+  adapter: ITransportAdapter,
+  surfaceId: DeviceSurfaceId = surfaceIdOf(adapter),
+): void {
+  bind(adapter, surfaceId);
+}
diff --git a/src/web-ui/src/infrastructure/api/adapters/peer-device-adapter.test.ts b/src/web-ui/src/infrastructure/api/adapters/peer-device-adapter.test.ts
index 8043d80a01..05e69a4597 100644
--- a/src/web-ui/src/infrastructure/api/adapters/peer-device-adapter.test.ts
+++ b/src/web-ui/src/infrastructure/api/adapters/peer-device-adapter.test.ts
@@ -1,4 +1,4 @@
-import { describe, expect, it, vi } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 import {
   PEER_MUTATION_REQUEST_TIMEOUT_MS,
   PEER_READ_MAX_RETRIES,
@@ -6,13 +6,27 @@ import {
   PEER_RETRY_BASE_DELAY_MS,
   PeerDeviceTransportAdapter,
   PeerProductCommandError,
+  PeerTransportClosedError,
   isPeerLocalOnlyCommand,
   isPeerRetryableIdempotentMutation,
   isPeerRetryableReadCommand,
   peerInvokePriorityFor,
 } from './peer-device-adapter';
+import {
+  getTransportSurfaceId,
+  resetTransportAdapter,
+  setTransportAdapter,
+} from './index';
+import { TauriTransportAdapter } from './tauri-adapter';
+import { isSurfaceChangedError } from '@/infrastructure/peer-device/deviceSurface';
 
 describe('isPeerLocalOnlyCommand', () => {
+  it('keeps file-search streaming on the negotiated response path', () => {
+    const adapter = new PeerDeviceTransportAdapter('peer-1', vi.fn());
+    expect(adapter.supportsSearchStreamEvents()).toBe(false);
+    expect(isPeerLocalOnlyCommand('search_filenames')).toBe(false);
+  });
+
   it('keeps local speech capture and model events on the controller device', () => {
     expect(isPeerLocalOnlyCommand('speech_list_models')).toBe(true);
     expect(isPeerLocalOnlyCommand('speech_start_input_session')).toBe(true);
@@ -37,6 +51,7 @@ describe('peerInvokePriorityFor', () => {
     expect(peerInvokePriorityFor('list_persisted_sessions_page')).toBe('high');
     expect(peerInvokePriorityFor('initialize_workspace_startup_state')).toBe('high');
     expect(peerInvokePriorityFor('start_dialog_turn')).toBe('high');
+    expect(peerInvokePriorityFor('rollback_session_to_turn')).toBe('high');
     expect(peerInvokePriorityFor('reload_config')).toBe('high');
     expect(peerInvokePriorityFor('get_config')).toBe('high');
     expect(peerInvokePriorityFor('get_available_modes')).toBe('high');
@@ -281,6 +296,43 @@ describe('PeerDeviceTransportAdapter queue', () => {
     );
   });
 
+  it('rejects targeted rollback when the Peer host lacks the negotiated capability', async () => {
+    const deviceRpc = vi.fn();
+    const adapter = new PeerDeviceTransportAdapter('peer-1', deviceRpc);
+
+    await expect(adapter.request('rollback_session_to_turn', {
+      request: {
+        workspacePath: '/repo',
+        sessionId: 'session-1',
+        targetTurnId: 'turn-7',
+      },
+    })).rejects.toEqual(expect.objectContaining<Partial<PeerProductCommandError>>({
+      name: 'PeerProductCommandError',
+      message: 'The connected Peer host does not support targeted Session rollback',
+    }));
+    expect(deviceRpc).not.toHaveBeenCalled();
+  });
+
+  it('forwards targeted rollback after capability negotiation', async () => {
+    const deviceRpc = vi.fn().mockResolvedValue(JSON.stringify({
+      resp: 'host_invoke_result',
+      ok: true,
+      value: { status: 'completed', sessionId: 'session-1' },
+    }));
+    const adapter = new PeerDeviceTransportAdapter('peer-1', deviceRpc, {
+      supportsTargetedSessionRollback: true,
+    });
+
+    await expect(adapter.request('rollback_session_to_turn', {
+      request: {
+        workspacePath: '/repo',
+        sessionId: 'session-1',
+        targetTurnId: 'turn-7',
+      },
+    })).resolves.toEqual({ status: 'completed', sessionId: 'session-1' });
+    expect(deviceRpc).toHaveBeenCalledTimes(1);
+  });
+
   it('preserves a session conflict returned by the Peer Host without replaying it', async () => {
     const deviceRpc = vi.fn().mockResolvedValue(JSON.stringify({
       resp: 'host_invoke_result',
@@ -368,6 +420,156 @@ describe('PeerDeviceTransportAdapter queue', () => {
   });
 });
 
+describe('PeerDeviceTransportAdapter disposal', () => {
+  it('settles queued requests instead of dropping them', async () => {
+    const gate = createDeferred<string>();
+    const deviceRpc = vi.fn(() => gate.promise);
+    const adapter = new PeerDeviceTransportAdapter('peer-1', deviceRpc, {}, 1);
+    await adapter.connect();
+
+    const inFlight = captureOutcome(adapter.request('get_opened_workspaces', { request: {} }));
+    const queued = captureOutcome(adapter.request('list_persisted_sessions_page', {
+      request: { workspacePath: '/repo' },
+    }));
+    expect(adapter.getQueueDepthsForTest().high).toBe(1);
+
+    await adapter.disconnect();
+    await flushMicrotasks();
+
+    // Both the waiting caller and the one already on the wire must hear back;
+    // a silent drop is what left session/history loads spinning forever.
+    expect(queued.settled).toBe(true);
+    expect(isSurfaceChangedError(queued.value)).toBe(true);
+    expect(queued.value).toBeInstanceOf(PeerTransportClosedError);
+    expect(inFlight.settled).toBe(true);
+    expect(isSurfaceChangedError(inFlight.value)).toBe(true);
+    expect(adapter.getQueueDepthsForTest()).toEqual({ high: 0, normal: 0, low: 0 });
+
+    gate.resolve(hostInvokeOk([]));
+  });
+
+  it('keeps concurrency accounting correct across disposal', async () => {
+    const gate = createDeferred<string>();
+    const deviceRpc = vi.fn(() => gate.promise);
+    const adapter = new PeerDeviceTransportAdapter('peer-1', deviceRpc, {}, 2);
+    await adapter.connect();
+
+    const inFlight = captureOutcome(adapter.request('get_opened_workspaces', { request: {} }));
+    expect(adapter.getActiveCountsForTest()).toMatchObject({ total: 1, high: 1 });
+
+    await adapter.disconnect();
+
+    // The request still occupies its transport slot: rewriting the count to
+    // zero underneath it made its later settle decrement a fresh count, so the
+    // limiter believed it had a free slot it did not have.
+    expect(adapter.getActiveCountsForTest()).toMatchObject({ total: 1, high: 1 });
+
+    gate.resolve(hostInvokeOk([]));
+    await flushMicrotasks();
+
+    expect(adapter.getActiveCountsForTest()).toMatchObject({ total: 0, high: 0 });
+    expect(inFlight.settled).toBe(true);
+  });
+
+  it('refuses to reopen the peer data plane after disposal', async () => {
+    const deviceRpc = vi.fn().mockResolvedValue(hostInvokeOk(true));
+    const adapter = new PeerDeviceTransportAdapter('peer-1', deviceRpc);
+    await adapter.connect();
+    await adapter.disconnect();
+
+    expect(adapter.isDisposed()).toBe(true);
+    expect(adapter.isConnected()).toBe(false);
+    await expect(adapter.request('get_opened_workspaces', { request: {} }))
+      .rejects.toBeInstanceOf(PeerTransportClosedError);
+    expect(deviceRpc).not.toHaveBeenCalled();
+  });
+});
+
+describe('surface-aware transport registry', () => {
+  afterEach(async () => {
+    await resetTransportAdapter();
+  });
+
+  it('records the surface each registered adapter serves', () => {
+    const adapter = new PeerDeviceTransportAdapter('peer-1', vi.fn());
+    setTransportAdapter(adapter);
+    expect(getTransportSurfaceId()).toBe('peer-1');
+
+    setTransportAdapter(new TauriTransportAdapter());
+    expect(getTransportSurfaceId()).toBe('local');
+  });
+
+  it('rejects a request that lands after its surface stopped being rendered', async () => {
+    const gate = createDeferred<string>();
+    const onHostInvokeTransportFailure = vi.fn();
+    const deviceRpc = vi.fn(() => gate.promise);
+    const adapter = new PeerDeviceTransportAdapter('peer-1', deviceRpc, {
+      onHostInvokeTransportFailure,
+    });
+    setTransportAdapter(adapter);
+
+    const pending = captureOutcome(adapter.request('list_persisted_sessions_page', {
+      request: { workspacePath: '/repo' },
+    }));
+
+    setTransportAdapter(new TauriTransportAdapter());
+    await flushMicrotasks();
+
+    // The activation boundary settles the caller; it does not wait for a weak
+    // relay request to answer or exhaust its retry budget.
+    expect(pending.settled).toBe(true);
+    expect(isSurfaceChangedError(pending.value)).toBe(true);
+    expect(onHostInvokeTransportFailure).not.toHaveBeenCalled();
+
+    gate.resolve(hostInvokeOk([{ id: 'peer-session' }]));
+    await flushMicrotasks();
+
+    expect(pending.settled).toBe(true);
+    expect(isSurfaceChangedError(pending.value)).toBe(true);
+    // A switch is not a weak link; counting it as one would degrade a healthy peer.
+    expect(onHostInvokeTransportFailure).not.toHaveBeenCalled();
+  });
+
+  it('invalidates late work when the same adapter is rebound for a new activation', async () => {
+    const gate = createDeferred<string>();
+    const adapter = new PeerDeviceTransportAdapter('peer-1', vi.fn(() => gate.promise));
+    await adapter.connect();
+    setTransportAdapter(adapter);
+
+    const pending = captureOutcome(adapter.request('list_persisted_sessions_page', {
+      request: { workspacePath: '/repo' },
+    }));
+
+    // The surface controller uses a same-adapter rebind to abort A#1 before
+    // the next target can commit. A#1's answer must not survive into A#2.
+    setTransportAdapter(adapter);
+    gate.resolve(hostInvokeOk([{ id: 'stale-session' }]));
+    await flushMicrotasks();
+
+    expect(pending.settled).toBe(true);
+    expect(isSurfaceChangedError(pending.value)).toBe(true);
+  });
+
+  it('rejects requests issued through a retired adapter without calling the peer', async () => {
+    const deviceRpc = vi.fn().mockResolvedValue(hostInvokeOk([]));
+    const adapter = new PeerDeviceTransportAdapter('peer-1', deviceRpc);
+    setTransportAdapter(adapter);
+    setTransportAdapter(new TauriTransportAdapter());
+
+    const error = await adapter
+      .request('list_persisted_sessions_page', { request: { workspacePath: '/repo' } })
+      .then(() => undefined, (rejection: unknown) => rejection);
+
+    expect(isSurfaceChangedError(error)).toBe(true);
+    expect(deviceRpc).not.toHaveBeenCalled();
+    // The attachment survives the switch, so rendering the peer again revives it.
+    setTransportAdapter(adapter);
+    await expect(adapter.request('list_persisted_sessions_page', {
+      request: { workspacePath: '/repo' },
+    })).resolves.toEqual([]);
+  });
+});
+
 function createDeferred<T>() {
   let resolve!: (value: T | PromiseLike<T>) => void;
   const promise = new Promise<T>((res) => {
@@ -375,3 +577,30 @@ function createDeferred<T>() {
   });
   return { promise, resolve };
 }
+
+function hostInvokeOk(value: unknown): string {
+  return JSON.stringify({ resp: 'host_invoke_result', ok: true, value });
+}
+
+/**
+ * Observe a request without awaiting it, so a promise that never settles fails
+ * the assertion instead of hanging the test until its timeout.
+ */
+function captureOutcome<T>(request: Promise<T>) {
+  const outcome: { settled: boolean; value: unknown } = { settled: false, value: undefined };
+  void request.then(
+    (value) => {
+      outcome.settled = true;
+      outcome.value = value;
+    },
+    (error: unknown) => {
+      outcome.settled = true;
+      outcome.value = error;
+    },
+  );
+  return outcome;
+}
+
+function flushMicrotasks(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
diff --git a/src/web-ui/src/infrastructure/api/adapters/peer-device-adapter.ts b/src/web-ui/src/infrastructure/api/adapters/peer-device-adapter.ts
index 5b740bb559..7b744ad3fb 100644
--- a/src/web-ui/src/infrastructure/api/adapters/peer-device-adapter.ts
+++ b/src/web-ui/src/infrastructure/api/adapters/peer-device-adapter.ts
@@ -1,5 +1,12 @@
 import { ITransportAdapter, type TransportRequestTiming } from './base';
 import { TauriTransportAdapter } from './tauri-adapter';
+import {
+  SurfaceChangedError,
+  getActiveSurfaceScope,
+  isSurfaceChangedError,
+  surfaceIdForDevice,
+  type DeviceSurfaceId,
+} from '@/infrastructure/peer-device/deviceSurface';
 import { createLogger } from '@/shared/utils/logger';
 import { elapsedMs, nowMs } from '@/shared/utils/timing';
 
@@ -157,6 +164,7 @@ const HIGH_PRIORITY_COMMANDS = new Set([
   'get_agent_profile_config',
   'start_dialog_turn',
   'cancel_dialog_turn',
+  'rollback_session_to_turn',
   'list_pending_permission_requests',
   'subscribe_permission_requests',
   'respond_permission',
@@ -337,6 +345,8 @@ export interface PeerDeviceTransportHooks {
    * advertises matching execution-side deduplication.
    */
   supportsIdempotentDialogSubmit?: boolean;
+  /** Enables targeted rollback only when the target host owns the transaction. */
+  supportsTargetedSessionRollback?: boolean;
 }
 
 interface HostInvokeResultEnvelope {
@@ -369,10 +379,32 @@ class PeerRpcTimeoutError extends Error {
   }
 }
 
+/**
+ * Raised when a request is abandoned because its adapter was torn down.
+ *
+ * It extends `SurfaceChangedError` so the one boundary that already unwinds
+ * stale-surface work handles disposal too, rather than every call site growing
+ * a second guard. What matters most is that it settles the promise at all:
+ * queued entries used to be dropped without settling, so every caller awaiting
+ * one (session list, session history) hung on a spinner forever.
+ */
+export class PeerTransportClosedError extends SurfaceChangedError {
+  constructor(deviceId: string, epoch: number, action?: string) {
+    super(surfaceIdForDevice(deviceId), epoch, action);
+    this.name = 'PeerTransportClosedError';
+    this.message = action
+      ? `Peer transport for '${deviceId}' closed while '${action}' was pending`
+      : `Peer transport for '${deviceId}' closed`;
+  }
+}
+
 interface QueuedPeerRequest {
   priority: PeerInvokePriority;
+  action: string;
   enqueuedAt: number;
   run: () => Promise<void>;
+  /** Settle the caller without running (or awaiting) the request. */
+  cancel: (error: Error) => void;
 }
 
 /**
@@ -385,8 +417,20 @@ interface QueuedPeerRequest {
  * session hydrate is not starved by background git/SSH/editor RPCs.
  */
 export class PeerDeviceTransportAdapter implements ITransportAdapter {
+  /** Which device surface this adapter's product traffic belongs to. */
+  readonly surfaceId: DeviceSurfaceId;
+
   private readonly local = new TauriTransportAdapter();
   private connected = false;
+  private disposed = false;
+  /**
+   * Whether this adapter is the transport the window currently renders.
+   * Permissive until the registry says otherwise: the guard exists to catch
+   * work outliving a switch *away*, not to gate an adapter nobody rendered yet.
+   */
+  private renderedTransport = true;
+  /** Bumped on every bind/unbind, so a request can detect it outlived one. */
+  private surfaceBindingEpoch = 0;
   private activeCount = 0;
   private readonly activeByPriority: Record<PeerInvokePriority, number> = {
     high: 0,
@@ -398,35 +442,118 @@ export class PeerDeviceTransportAdapter implements ITransportAdapter {
     normal: [],
     low: [],
   };
+  /** Every request whose caller promise has not settled — queued or in flight. */
+  private readonly pending = new Set<QueuedPeerRequest>();
 
   constructor(
     private readonly targetDeviceId: string,
     private readonly deviceRpc: DeviceRpcFn,
-    private readonly hooks: PeerDeviceTransportHooks = {},
+    private hooks: PeerDeviceTransportHooks = {},
     private readonly maxConcurrent: number = PEER_HOST_INVOKE_MAX_CONCURRENT,
-  ) {}
+  ) {
+    this.surfaceId = surfaceIdForDevice(targetDeviceId);
+  }
+
+  /**
+   * Search progress is not part of the negotiated Peer DeviceEvent contract.
+   * Use the response-based search command so older peers remain compatible and
+   * results never fall back to the controller's filesystem.
+   */
+  supportsSearchStreamEvents(): boolean {
+    return false;
+  }
 
   getTargetDeviceId(): string {
     return this.targetDeviceId;
   }
 
+  /**
+   * Adopt the capabilities of the host that answered the latest handshake.
+   * They belong to that host, not to the device id: a peer that restarted on
+   * an older build during a reconnect must not keep the previous contract.
+   */
+  setHostCapabilities(
+    capabilities: Pick<
+      PeerDeviceTransportHooks,
+      'supportsIdempotentDialogSubmit' | 'supportsTargetedSessionRollback'
+    >,
+  ): void {
+    this.hooks = { ...this.hooks, ...capabilities };
+  }
+
+  /**
+   * Registry hook: this adapter has started or stopped being the transport the
+   * window renders. A request issued under an earlier binding fails as a
+   * surface change when it lands, so slow work — a session-list read still
+   * working through its retry budget, say — cannot resolve into the surface
+   * that replaced it.
+   */
+  markRenderedTransport(rendered: boolean, forceNewBinding = false): void {
+    if (rendered === this.renderedTransport && !forceNewBinding) {
+      return;
+    }
+    this.renderedTransport = rendered;
+    this.surfaceBindingEpoch += 1;
+    const error = new SurfaceChangedError(
+      this.surfaceId,
+      getActiveSurfaceScope().epoch,
+      'change peer transport binding',
+    );
+    // Settle callers immediately at the activation boundary. Work already on
+    // the wire may finish on its owning host, but nobody should wait through a
+    // timeout/retry budget before learning that its rendered surface is gone.
+    for (const entry of Array.from(this.pending)) {
+      entry.cancel(error);
+    }
+    for (const priority of ['high', 'normal', 'low'] as const) {
+      for (const entry of this.queues[priority]) {
+        this.pending.delete(entry);
+      }
+      this.queues[priority].length = 0;
+    }
+  }
+
+  isDisposed(): boolean {
+    return this.disposed;
+  }
+
   async connect(): Promise<void> {
+    this.assertUsable('connect');
     await this.local.connect();
     this.connected = true;
   }
 
   async request<T>(action: string, params?: any, timing?: TransportRequestTiming): Promise<T> {
     const transportStartedAt = nowMs();
+    this.assertUsable(action);
     if (!this.connected) {
       await this.connect();
     }
 
     if (isPeerLocalOnlyCommand(action)) {
+      // Local-only commands run on this machine by definition, so they are not
+      // bound to the rendered surface and stay valid on a retired adapter.
       return this.local.request<T>(action, params, timing);
     }
 
+    this.assertRenderedTransport(action);
+
+    if (
+      action === 'rollback_session_to_turn' &&
+      this.hooks.supportsTargetedSessionRollback !== true
+    ) {
+      throw new PeerProductCommandError(
+        'The connected Peer host does not support targeted Session rollback',
+      );
+    }
+
+    const issuedBindingEpoch = this.surfaceBindingEpoch;
     const priority = peerInvokePriorityFor(action);
-    return this.enqueue(priority, () => this.invokeOnPeer<T>(action, params, timing, transportStartedAt));
+    return this.enqueue(
+      priority,
+      action,
+      () => this.invokeOnPeer<T>(action, params, timing, transportStartedAt, issuedBindingEpoch),
+    );
   }
 
   /**
@@ -438,10 +565,18 @@ export class PeerDeviceTransportAdapter implements ITransportAdapter {
     command: Record<string, unknown>,
     priority: PeerInvokePriority = 'normal',
   ): Promise<T> {
+    const action = typeof command.cmd === 'string' ? command.cmd : 'unknown';
+    this.assertUsable(action);
     if (!this.connected) {
       await this.connect();
     }
-    return this.enqueue(priority, () => this.invokePeerCommand<T>(command, priority));
+    this.assertRenderedTransport(action);
+    const issuedBindingEpoch = this.surfaceBindingEpoch;
+    return this.enqueue(
+      priority,
+      action,
+      () => this.invokePeerCommand<T>(command, priority, issuedBindingEpoch),
+    );
   }
 
   listen<T>(event: string, callback: (data: T) => void): () => void {
@@ -452,14 +587,30 @@ export class PeerDeviceTransportAdapter implements ITransportAdapter {
     await this.local.waitForListenerRegistrations?.();
   }
 
+  /**
+   * Dispose this adapter. Terminal on purpose: an adapter dies with its peer
+   * link, and a late request must not silently re-open a data plane to a device
+   * we have detached from.
+   *
+   * Every unsettled caller is rejected. Queued entries used to be discarded
+   * with `queue.length = 0`, which never settled their promises — that is what
+   * left session-list and history loads spinning forever after a teardown.
+   */
   async disconnect(): Promise<void> {
-    await this.local.disconnect();
+    this.disposed = true;
     this.connected = false;
     for (const priority of ['high', 'normal', 'low'] as const) {
       this.queues[priority].length = 0;
-      this.activeByPriority[priority] = 0;
     }
-    this.activeCount = 0;
+    for (const entry of Array.from(this.pending)) {
+      entry.cancel(this.closedError(entry.action));
+    }
+    this.pending.clear();
+    // Concurrency counters are deliberately left alone: requests already handed
+    // to the transport still settle and decrement themselves. Zeroing them here
+    // made each late settle decrement a freshly reset count, so the limiter
+    // afterwards believed it had free slots it did not have.
+    await this.local.disconnect();
   }
 
   isConnected(): boolean {
@@ -475,24 +626,78 @@ export class PeerDeviceTransportAdapter implements ITransportAdapter {
     };
   }
 
-  private enqueue<T>(priority: PeerInvokePriority, task: () => Promise<T>): Promise<T> {
+  /** Test helper: requests currently occupying a concurrency slot. */
+  getActiveCountsForTest(): Record<PeerInvokePriority | 'total', number> {
+    return {
+      total: this.activeCount,
+      high: this.activeByPriority.high,
+      normal: this.activeByPriority.normal,
+      low: this.activeByPriority.low,
+    };
+  }
+
+  private closedError(action?: string): PeerTransportClosedError {
+    return new PeerTransportClosedError(
+      this.targetDeviceId,
+      getActiveSurfaceScope().epoch,
+      action,
+    );
+  }
+
+  private assertUsable(action: string): void {
+    if (this.disposed) {
+      throw this.closedError(action);
+    }
+  }
+
+  private assertRenderedTransport(action: string): void {
+    if (!this.renderedTransport) {
+      throw new SurfaceChangedError(
+        this.surfaceId,
+        getActiveSurfaceScope().epoch,
+        action,
+      );
+    }
+  }
+
+  private enqueue<T>(
+    priority: PeerInvokePriority,
+    action: string,
+    task: () => Promise<T>,
+  ): Promise<T> {
     return new Promise<T>((resolve, reject) => {
-      this.queues[priority].push({
+      let settled = false;
+      const settle = (outcome: () => void): void => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        outcome();
+      };
+      const entry: QueuedPeerRequest = {
         priority,
+        action,
         enqueuedAt: nowMs(),
         run: async () => {
           try {
-            resolve(await task());
+            const value = await task();
+            settle(() => resolve(value));
           } catch (error) {
-            reject(error);
+            settle(() => reject(error));
           }
         },
-      });
+        cancel: (error: Error) => settle(() => reject(error)),
+      };
+      this.pending.add(entry);
+      this.queues[priority].push(entry);
       this.pump();
     });
   }
 
   private pump(): void {
+    if (this.disposed) {
+      return;
+    }
     while (this.activeCount < this.maxConcurrent) {
       const next = this.dequeueNext();
       if (!next) {
@@ -501,6 +706,7 @@ export class PeerDeviceTransportAdapter implements ITransportAdapter {
       this.activeCount += 1;
       this.activeByPriority[next.priority] += 1;
       void next.run().finally(() => {
+        this.pending.delete(next);
         this.activeCount = Math.max(0, this.activeCount - 1);
         this.activeByPriority[next.priority] = Math.max(
           0,
@@ -541,6 +747,7 @@ export class PeerDeviceTransportAdapter implements ITransportAdapter {
   private async invokePeerCommand<T extends PeerDeviceCommandResponse>(
     command: Record<string, unknown>,
     priority: PeerInvokePriority,
+    issuedBindingEpoch: number,
   ): Promise<T> {
     const action = typeof command.cmd === 'string' ? command.cmd : 'unknown';
     try {
@@ -554,7 +761,9 @@ export class PeerDeviceTransportAdapter implements ITransportAdapter {
         action,
         JSON.stringify(command),
         retryable ? READ_RPC_POLICY : MUTATION_RPC_POLICY,
+        issuedBindingEpoch,
       );
+      this.assertBindingUnchanged(issuedBindingEpoch, action);
       const envelope = JSON.parse(raw) as T;
       if (envelope.resp === 'error') {
         throw new PeerProductCommandError(
@@ -571,17 +780,38 @@ export class PeerDeviceTransportAdapter implements ITransportAdapter {
         log.warn('Peer product command failed', { action, error });
         throw error;
       }
+      if (isSurfaceChangedError(error)) {
+        throw error;
+      }
       log.error('Peer direct command transport failed', { action, error });
       this.hooks.onHostInvokeTransportFailure?.(error, { action, priority });
       throw error;
     }
   }
 
+  /**
+   * A request that outlived its surface binding must not resolve: its answer
+   * describes a device this window has stopped rendering, and feeding it to the
+   * current surface is how a peer's session list ended up drawn over the local
+   * one. The peer-side effect of a mutation still stands — the caller's own
+   * generation guard decides what to do about that.
+   */
+  private assertBindingUnchanged(issuedBindingEpoch: number, action: string): void {
+    if (issuedBindingEpoch !== this.surfaceBindingEpoch) {
+      throw new SurfaceChangedError(
+        this.surfaceId,
+        getActiveSurfaceScope().epoch,
+        action,
+      );
+    }
+  }
+
   private async invokeOnPeer<T>(
     action: string,
     params: unknown,
     timing: TransportRequestTiming | undefined,
     transportStartedAt: number,
+    issuedBindingEpoch: number,
   ): Promise<T> {
     const invokeStartedAt = nowMs();
     const priority = peerInvokePriorityFor(action);
@@ -602,7 +832,9 @@ export class PeerDeviceTransportAdapter implements ITransportAdapter {
         action,
         commandJson,
         rpcPolicy,
+        issuedBindingEpoch,
       );
+      this.assertBindingUnchanged(issuedBindingEpoch, action);
       const envelope = JSON.parse(raw) as HostInvokeResultEnvelope;
       if (timing) {
         timing.invokeDurationMs = elapsedMs(invokeStartedAt);
@@ -630,6 +862,11 @@ export class PeerDeviceTransportAdapter implements ITransportAdapter {
         log.warn('Peer product command failed', { action, error });
         throw error;
       }
+      // A surface change is control flow, not a weak link: reporting it as a
+      // transport failure would mark a healthy peer degraded on every switch.
+      if (isSurfaceChangedError(error)) {
+        throw error;
+      }
       log.error('Peer HostInvoke transport failed', { action, error });
       this.hooks.onHostInvokeTransportFailure?.(error, { action, priority });
       throw error;
@@ -640,15 +877,25 @@ export class PeerDeviceTransportAdapter implements ITransportAdapter {
     action: string,
     commandJson: string,
     policy: PeerRpcPolicy,
+    issuedBindingEpoch: number,
   ): Promise<string> {
     for (let attempt = 0; ; attempt += 1) {
+      this.assertBindingUnchanged(issuedBindingEpoch, action);
       try {
-        return await this.withTimeout(
+        const result = await this.withTimeout(
           this.deviceRpc(this.targetDeviceId, commandJson, policy.timeoutMs),
           action,
           policy.timeoutMs,
         );
+        this.assertBindingUnchanged(issuedBindingEpoch, action);
+        return result;
       } catch (error) {
+        if (isSurfaceChangedError(error)) {
+          throw error;
+        }
+        // A retired binding is cancellation, not a weak relay. In particular,
+        // do not keep replaying a read after another device is rendered.
+        this.assertBindingUnchanged(issuedBindingEpoch, action);
         if (attempt >= policy.maxRetries) {
           throw error;
         }
@@ -662,6 +909,7 @@ export class PeerDeviceTransportAdapter implements ITransportAdapter {
           error,
         });
         await new Promise(resolve => setTimeout(resolve, delayMs));
+        this.assertBindingUnchanged(issuedBindingEpoch, action);
       }
     }
   }
diff --git a/src/web-ui/src/infrastructure/api/adapters/tauri-adapter.ts b/src/web-ui/src/infrastructure/api/adapters/tauri-adapter.ts
index 317b5dd4b9..b95fb056a1 100644
--- a/src/web-ui/src/infrastructure/api/adapters/tauri-adapter.ts
+++ b/src/web-ui/src/infrastructure/api/adapters/tauri-adapter.ts
@@ -4,6 +4,7 @@ import { listen, UnlistenFn } from '@tauri-apps/api/event';
 import { elapsedMs, nowMs } from '@/shared/utils/timing';
 import { ITransportAdapter, type TransportRequestTiming } from './base';
 import { createLogger } from '@/shared/utils/logger';
+import { routeSurfaceEvent } from '@/infrastructure/peer-device/deviceSurfaceRouting';
 import { sanitizeErrorForLog } from '../logSanitizer';
 
 const log = createLogger('TauriAdapter');
@@ -34,6 +35,10 @@ export class TauriTransportAdapter implements ITransportAdapter {
   private initPromise: Promise<void> | null = null;
   private listenerRegistrationPromises = new Set<Promise<void>>();
 
+  supportsSearchStreamEvents(): boolean {
+    return true;
+  }
+
   // Lazy initialize Tauri API
   private async ensureInitialized() {
     if (this.invokeFn) return;
@@ -123,8 +128,15 @@ export class TauriTransportAdapter implements ITransportAdapter {
 
     const registration = listen<T>(event, (e) => {
       if (!isUnlistened) {
+        // Peer devices stay attached while the UI renders another device, so
+        // several product event streams share this bus. Only the rendered
+        // device surface may reach product listeners.
+        const route = routeSurfaceEvent(event, e.payload);
+        if (!route.deliver) {
+          return;
+        }
         try {
-          callback(e.payload);
+          callback(route.payload);
         } catch (error) {
       log.error('Error in event listener callback', { event, error: sanitizeErrorForLog(error) });
         }
diff --git a/src/web-ui/src/infrastructure/api/adapters/websocket-adapter.test.ts b/src/web-ui/src/infrastructure/api/adapters/websocket-adapter.test.ts
index b687def46a..f7265bd80c 100644
--- a/src/web-ui/src/infrastructure/api/adapters/websocket-adapter.test.ts
+++ b/src/web-ui/src/infrastructure/api/adapters/websocket-adapter.test.ts
@@ -99,6 +99,9 @@ describe('resolveWsMethod', () => {
       'config/getAgentProfileConfig'
     );
     expect(resolveWsMethod('get_model_configs')).toBe('config/getModelConfigs');
+    expect(resolveWsMethod('project_ai_model_reasoning_catalog')).toBe(
+      'model/projectReasoningCatalog',
+    );
     expect(resolveWsMethod('get_config')).toBe('config/getConfig');
     expect(resolveWsMethod('get_configs')).toBe('config/getConfigs');
     expect(resolveWsMethod('set_agent_profile_config')).toBe(
@@ -139,11 +142,11 @@ describe('resolveWsMethod', () => {
     // covers the schema methods (key count is stable; ordering is not pinned
     // because the table is a plain object). Track B Batch 1 added config write +
     // i18n and the P0 Session/Config control plane. Atomic cloud-speech save
-    // and config validation raise the count to 33.
+    // config validation, and live reasoning projection raise the count to 34.
     expect(AGENT_COMMAND_SCHEMA.start_dialog_turn.method).toBe(
       'agent/submitDialogTurn'
     );
-    expect(Object.keys(AGENT_COMMAND_SCHEMA).length).toBe(33);
+    expect(Object.keys(AGENT_COMMAND_SCHEMA).length).toBe(34);
 
     // Touch the locals so noUnusedLocals does not flag them under vitest's
     // transformed build (tsc --noEmit is the real gate; this is belt-and-suspenders).
@@ -351,6 +354,7 @@ describe('WebSocketTransportAdapter reconnect lifecycle', () => {
     const sockets: MockWebSocket[] = [];
     class MockWebSocket {
       static readonly OPEN = 1;
+      static readonly CLOSING = 2;
 
       readyState = 0;
       onopen: ((event: Event) => void) | null = null;
@@ -396,3 +400,218 @@ describe('WebSocketTransportAdapter reconnect lifecycle', () => {
     expect(sockets).toHaveLength(1);
   });
 });
+
+describe('WebSocketTransportAdapter JSON-RPC lifecycle', () => {
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+  });
+
+  it('fails the connection closed for an ambiguous response envelope', async () => {
+    vi.useFakeTimers();
+    const sockets: RpcMockWebSocket[] = [];
+    RpcMockWebSocket.instances = sockets;
+    vi.stubGlobal('WebSocket', RpcMockWebSocket);
+    const adapter = new WebSocketTransportAdapter('ws://example.test/ws');
+    const connected = adapter.connect();
+    sockets[0].open();
+    await connected;
+
+    const response = adapter.request('ping', {});
+    const request = JSON.parse(sockets[0].sent[0]) as { id: string };
+    sockets[0].receive({
+      jsonrpc: '2.0',
+      id: request.id,
+      result: { ok: true },
+      error: { code: -32000, message: 'ambiguous' },
+    });
+
+    await expect(response).rejects.toThrow(/exactly one result or error/);
+    expect(sockets[0].closeCalls).toBe(1);
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it('keeps a healthy WebSocket reusable after one request deadline', async () => {
+    vi.useFakeTimers();
+    const sockets: RpcMockWebSocket[] = [];
+    RpcMockWebSocket.instances = sockets;
+    vi.stubGlobal('WebSocket', RpcMockWebSocket);
+    const adapter = new WebSocketTransportAdapter('ws://example.test/ws');
+    const connected = adapter.connect();
+    sockets[0].open();
+    await connected;
+
+    const expired = adapter.request('ping', {});
+    const expiredAssertion = expect(expired).rejects.toThrow('Request timeout: ping');
+    await vi.advanceTimersByTimeAsync(30_000);
+    await expiredAssertion;
+    expect(sockets[0].closeCalls).toBe(0);
+
+    const next = adapter.request<{ ok: boolean }>('ping', {});
+    await vi.advanceTimersByTimeAsync(0);
+    const request = JSON.parse(sockets[0].sent[1]) as { id: string };
+    sockets[0].receive({
+      jsonrpc: '2.0',
+      id: request.id,
+      result: { ok: true },
+    });
+    await expect(next).resolves.toEqual({ ok: true });
+    await adapter.disconnect();
+  });
+
+  it('fails closed before the browser WebSocket send buffer grows past its cap', async () => {
+    const sockets: RpcMockWebSocket[] = [];
+    RpcMockWebSocket.instances = sockets;
+    vi.stubGlobal('WebSocket', RpcMockWebSocket);
+    const adapter = new WebSocketTransportAdapter('ws://example.test/ws');
+    const connected = adapter.connect();
+    sockets[0].open();
+    await connected;
+    sockets[0].bufferedAmount = 2 * 1024 * 1024;
+
+    const response = adapter.request('ping', {});
+    const bounded = Promise.race([
+      response,
+      new Promise<never>((_resolve, reject) => {
+        setTimeout(() => reject(new Error('WebSocket send buffer was not bounded')), 50);
+      }),
+    ]);
+    try {
+      const error = await bounded.then(
+        () => undefined,
+        (reason: unknown) => reason,
+      );
+      const cause = (error as { cause?: unknown } | undefined)?.cause;
+      expect(cause).toBeInstanceOf(Error);
+      expect((cause as Error).message).toMatch(/send buffer capacity/);
+      expect(sockets[0].closeCalls).toBe(1);
+    } finally {
+      await adapter.disconnect();
+    }
+  });
+
+  it('closes a connection whose browser send buffer never drains', async () => {
+    vi.useFakeTimers();
+    const sockets: RpcMockWebSocket[] = [];
+    RpcMockWebSocket.instances = sockets;
+    vi.stubGlobal('WebSocket', RpcMockWebSocket);
+    const adapter = new WebSocketTransportAdapter('ws://example.test/ws');
+    const connected = adapter.connect();
+    sockets[0].open();
+    await connected;
+    sockets[0].bufferedAmount = 1;
+    let settled = false;
+    const response = adapter.request('ping', {});
+    void response.catch(() => {
+      settled = true;
+    });
+
+    try {
+      await vi.advanceTimersByTimeAsync(5_100);
+      expect(settled).toBe(true);
+      expect(sockets[0].closeCalls).toBe(1);
+    } finally {
+      await adapter.disconnect();
+    }
+  });
+
+  it('an old socket generation cannot close or settle requests on its replacement', async () => {
+    vi.useFakeTimers();
+    const sockets: RpcMockWebSocket[] = [];
+    RpcMockWebSocket.instances = sockets;
+    vi.stubGlobal('WebSocket', RpcMockWebSocket);
+    const adapter = new WebSocketTransportAdapter('ws://example.test/ws');
+    const connected = adapter.connect();
+    sockets[0].open();
+    await connected;
+    sockets[0].bufferedAmount = 1;
+    let oldSettled = false;
+    const oldRequest = adapter.request('ping', {});
+    void oldRequest.catch(() => {
+      oldSettled = true;
+    });
+    await vi.advanceTimersByTimeAsync(0);
+
+    sockets[0].closeFromServer();
+    await vi.advanceTimersByTimeAsync(1_000);
+    expect(oldSettled).toBe(true);
+    expect(sockets).toHaveLength(2);
+
+    sockets[1].open();
+    const current = adapter.request<{ ok: boolean }>('ping', {});
+    await vi.advanceTimersByTimeAsync(0);
+    const request = JSON.parse(sockets[1].sent[0]) as { id: string };
+    sockets[1].receive({ jsonrpc: '2.0', id: request.id, result: { ok: true } });
+    await expect(current).resolves.toEqual({ ok: true });
+    expect(sockets[1].closeCalls).toBe(0);
+    await adapter.disconnect();
+  });
+
+  it('a request during reconnect joins the one in-flight replacement socket', async () => {
+    vi.useFakeTimers();
+    const sockets: RpcMockWebSocket[] = [];
+    RpcMockWebSocket.instances = sockets;
+    vi.stubGlobal('WebSocket', RpcMockWebSocket);
+    const adapter = new WebSocketTransportAdapter('ws://example.test/ws');
+    const connected = adapter.connect();
+    sockets[0].open();
+    await connected;
+    sockets[0].closeFromServer();
+    await vi.advanceTimersByTimeAsync(1_000);
+    expect(sockets).toHaveLength(2);
+
+    const response = adapter.request<{ ok: boolean }>('ping', {});
+    await vi.advanceTimersByTimeAsync(0);
+    expect(sockets).toHaveLength(2);
+    sockets[1].open();
+    await vi.advanceTimersByTimeAsync(0);
+    const request = JSON.parse(sockets[1].sent[0]) as { id: string };
+    sockets[1].receive({ jsonrpc: '2.0', id: request.id, result: { ok: true } });
+
+    await expect(response).resolves.toEqual({ ok: true });
+    await adapter.disconnect();
+  });
+});
+
+class RpcMockWebSocket {
+  static readonly OPEN = 1;
+  static readonly CLOSING = 2;
+  static instances: RpcMockWebSocket[] = [];
+
+  readyState = 0;
+  readonly sent: string[] = [];
+  bufferedAmount = 0;
+  closeCalls = 0;
+  onopen: ((event: Event) => void) | null = null;
+  onerror: ((event: Event) => void) | null = null;
+  onclose: ((event: CloseEvent) => void) | null = null;
+  onmessage: ((event: MessageEvent) => void) | null = null;
+
+  constructor(readonly url: string) {
+    RpcMockWebSocket.instances.push(this);
+  }
+
+  open(): void {
+    this.readyState = RpcMockWebSocket.OPEN;
+    this.onopen?.({} as Event);
+  }
+
+  send(message: string): void {
+    this.sent.push(message);
+  }
+
+  receive(value: unknown): void {
+    this.onmessage?.({ data: JSON.stringify(value) } as MessageEvent);
+  }
+
+  closeFromServer(): void {
+    this.readyState = 3;
+    this.onclose?.({} as CloseEvent);
+  }
+
+  close(): void {
+    this.closeCalls += 1;
+    this.readyState = 3;
+    this.onclose?.({} as CloseEvent);
+  }
+}
diff --git a/src/web-ui/src/infrastructure/api/adapters/websocket-adapter.ts b/src/web-ui/src/infrastructure/api/adapters/websocket-adapter.ts
index 98194d740e..2d2ff2bd15 100644
--- a/src/web-ui/src/infrastructure/api/adapters/websocket-adapter.ts
+++ b/src/web-ui/src/infrastructure/api/adapters/websocket-adapter.ts
@@ -2,6 +2,15 @@
 
 import { ITransportAdapter } from './base';
 import { createLogger } from '@/shared/utils/logger';
+import {
+  JsonRpcPeer,
+  JsonRpcProtocolError,
+  JsonRpcRemoteError,
+  JsonRpcTimeoutError,
+  JsonRpcTransportError,
+  WebSocketMessageTransport,
+  type JsonRpcNotification,
+} from '../../../../../crates/adapters/transport/typescript/src/index.js';
 import type {
   AgentSessionArchiveStateRequest,
   AgentSessionForkAtTurnRequest,
@@ -27,7 +36,7 @@ const log = createLogger('WebSocketAdapter');
 /**
  * Typed mapping from the frontend's snake_case agent commands to the app-server
  * JSON-RPC method names, carrying the request/response types from the generated
- * schema (`@/generated/api`, source: `bitfun-app-server/src/schema/`).
+ * schema (`@/generated/api`, source: `bitfun-app-server-protocol`).
  *
  * The service layer (`AgentAPI` and friends) speaks Tauri command names
  * (`create_session`, `start_dialog_turn`, ...) because that is the desktop
@@ -158,6 +167,7 @@ export const AGENT_COMMAND_SCHEMA = {
   get_agent_profile_configs: { method: 'config/getAgentProfileConfigs' },
   get_agent_profile_config: { method: 'config/getAgentProfileConfig' },
   get_model_configs: { method: 'config/getModelConfigs' },
+  project_ai_model_reasoning_catalog: { method: 'model/projectReasoningCatalog' },
   get_config: { method: 'config/getConfig' },
   get_configs: { method: 'config/getConfigs' },
   set_agent_profile_config: {
@@ -290,6 +300,8 @@ export function decodeResponseBody(action: string, result: any): any {
       return unwrapArray(result, 'records');
     case 'git_get_branches':
       return unwrapArray(result, 'branches');
+    case 'project_ai_model_reasoning_catalog':
+      return result?.projection ?? result;
     case 'set_agent_profile_config':
       return 'Agent profile configuration updated successfully';
     case 'reset_agent_profile_config':
@@ -339,12 +351,6 @@ function unwrapArray(result: any, key: string): any {
   return result;
 }
 
-interface PendingRequest {
-  resolve: (value: any) => void;
-  reject: (error: any) => void;
-  timeout: NodeJS.Timeout;
-}
-
 export function webSocketResponseError(value: unknown): Error {
   const record = value && typeof value === 'object'
     ? value as { code?: unknown; message?: unknown; data?: unknown }
@@ -380,12 +386,29 @@ export function decodeWsNotification(message: any): DecodedWsNotification | null
   return null;
 }
 
+const WEB_JSON_RPC_LIMITS = {
+  maxMessageBytes: 1024 * 1024,
+  maxPendingRequests: 128,
+  maxPendingBytes: 8 * 1024 * 1024,
+  maxOutboundBytes: 2 * 1024 * 1024,
+};
+
+const WEB_SOCKET_SEND_BUFFER_BYTES = 2 * 1024 * 1024;
+const WEB_SOCKET_DRAIN_TIMEOUT_MS = 5_000;
+
+interface WebSocketRpcGeneration {
+  socket: WebSocket;
+  transport: WebSocketMessageTransport;
+  peer: JsonRpcPeer;
+  allowReconnect: boolean;
+}
+
 export class WebSocketTransportAdapter implements ITransportAdapter {
   private ws: WebSocket | null = null;
   private url: string;
   private eventListeners: Map<string, Set<(data: any) => void>> = new Map();
-  private pendingRequests: Map<string, PendingRequest> = new Map();
   private messageIdCounter = 0;
+  private rpcGeneration: WebSocketRpcGeneration | null = null;
   private reconnectAttempts = 0;
   private maxReconnectAttempts = 5;
   private reconnectDelay = 1000;
@@ -408,9 +431,15 @@ export class WebSocketTransportAdapter implements ITransportAdapter {
         let settled = false;
 
         ws.onopen = () => {
+          if (this.ws !== ws) {
+            ws.close();
+            return;
+          }
           log.info('Connected successfully');
           this.reconnectAttempts = 0;
-          this.setupMessageHandler();
+          const generation = this.createRpcGeneration(ws);
+          this.rpcGeneration = generation;
+          this.setupMessageHandler(generation);
           if (!settled) {
             settled = true;
             resolve();
@@ -431,7 +460,23 @@ export class WebSocketTransportAdapter implements ITransportAdapter {
             settled = true;
             reject(new Error('WebSocket connection closed before open'));
           }
-          this.handleDisconnect();
+          const generation = this.rpcGeneration?.socket === ws
+            ? this.rpcGeneration
+            : null;
+          if (generation !== null) {
+            generation.transport.carrierClosed(
+              new Error('WebSocket connection closed'),
+            );
+            if (this.rpcGeneration === generation) {
+              this.rpcGeneration = null;
+            }
+          }
+          if (this.ws === ws) {
+            this.ws = null;
+          }
+          if (generation?.allowReconnect !== false) {
+            this.handleDisconnect();
+          }
         };
       } catch (error) {
         log.error('Failed to create WebSocket', error);
@@ -472,89 +517,106 @@ export class WebSocketTransportAdapter implements ITransportAdapter {
       this.clearReconnectTimer();
       this.reconnectTimer = setTimeout(() => {
         this.reconnectTimer = null;
-        this.connect().catch(error => {
+        this.ensureConnected().catch(error => {
           log.error('Reconnection failed', error);
         });
       }, delay);
     } else {
       log.error('Max reconnection attempts reached');
-      
-      this.pendingRequests.forEach((pending) => {
-        clearTimeout(pending.timeout);
-        pending.reject(new Error('WebSocket disconnected'));
-      });
-      this.pendingRequests.clear();
     }
   }
   
    
-  private setupMessageHandler(): void {
-    if (!this.ws) return;
+  private setupMessageHandler(generation: WebSocketRpcGeneration): void {
+    const ws = generation.socket;
 
-    this.ws.onmessage = (event) => {
+    ws.onmessage = (event) => {
+      if (this.rpcGeneration !== generation) {
+        return;
+      }
+      if (typeof event.data !== 'string') {
+        void generation.peer.abort(
+          new JsonRpcProtocolError('WebSocket JSON-RPC message must be text'),
+        );
+        return;
+      }
       try {
-        const message = JSON.parse(event.data);
-
-        // JSON-RPC 2.0 response: carries `id` matching a pending request.
-        // Shape: `{ jsonrpc: "2.0", id, result | error }`.
-        if (message.id !== undefined && this.pendingRequests.has(message.id)) {
-          const pending = this.pendingRequests.get(message.id)!;
-          clearTimeout(pending.timeout);
-
-          if (message.error) {
-            pending.reject(webSocketResponseError(message.error));
-          } else {
-            pending.resolve(message.result);
+        const message = JSON.parse(event.data) as Record<string, unknown>;
+        if (message.jsonrpc !== '2.0') {
+          const mappedEventName = this.mapLegacyTypeToEventName(message.type);
+          if (mappedEventName !== null) {
+            this.dispatchEvent(mappedEventName, message, message.type);
+            return;
           }
-
-          this.pendingRequests.delete(message.id);
-          return;
         }
+      } catch {
+        // The shared peer owns parse and strict-envelope failure semantics.
+      }
+      generation.transport.receive(event.data);
+    };
+  }
 
-        // JSON-RPC 2.0 notification: `{ jsonrpc: "2.0", method, params }`.
-        // The server pushes `agent/frontendEvent` notifications carrying the
-        // projected frontend event name and payload, so dispatch on
-        // `params.event` exactly like the legacy `WsMessage::Event{event,payload}`.
-        const notification = decodeWsNotification(message);
-        if (notification) {
-          const eventName = notification.event;
-          const payload = notification.payload;
-          const listeners = this.eventListeners.get(eventName);
-          if (listeners && listeners.size > 0) {
-            listeners.forEach(callback => {
-              try {
-                callback(payload);
-              } catch (error) {
-                log.error('Error in event listener', { event: eventName, error });
-              }
-            });
-          }
-          return;
-        }
+  private createRpcGeneration(socket: WebSocket): WebSocketRpcGeneration {
+    const transport = new WebSocketMessageTransport(socket, {
+      maxBufferedBytes: WEB_SOCKET_SEND_BUFFER_BYTES,
+      drainTimeoutMs: WEB_SOCKET_DRAIN_TIMEOUT_MS,
+    });
+    const generation = {
+      socket,
+      transport,
+      allowReconnect: true,
+    } as WebSocketRpcGeneration;
+    const peer = new JsonRpcPeer(transport, {
+      createRequestId: () => `msg_${Date.now()}_${++this.messageIdCounter}`,
+      requestTimeoutMs: 30_000,
+      limits: WEB_JSON_RPC_LIMITS,
+      onNotificationError: (error, notification) => {
+        log.error('Error in WebSocket notification consumer', {
+          method: notification.method,
+          error,
+        });
+      },
+    });
+    generation.peer = peer;
+    peer.onNotification((notification) => {
+      this.dispatchNotification(notification);
+    });
+    peer.onFailure((error) => {
+      if (error instanceof JsonRpcProtocolError) {
+        generation.allowReconnect = false;
+      }
+      log.error('WebSocket JSON-RPC peer stopped', error);
+    });
+    return generation;
+  }
 
-        // Legacy `agentic://<type>` pass-through (kept for any notification the
-        // server still sends with a bare `type` field in the old shape).
-        const mappedEventName = this.mapLegacyTypeToEventName(message.type);
-        if (mappedEventName) {
-          const listeners = this.eventListeners.get(mappedEventName);
-          if (listeners && listeners.size > 0) {
-            listeners.forEach(callback => {
-              try {
-                callback(message);
-              } catch (error) {
-                log.error('Error in WebSocket type-mapped event listener', {
-                  event: mappedEventName,
-                  rawType: message.type,
-                  error,
-                });
-              }
-            });
-          }
-        }
+  private dispatchNotification(notification: JsonRpcNotification): void {
+    const decoded = decodeWsNotification({
+      jsonrpc: '2.0',
+      method: notification.method,
+      params: notification.params,
+    });
+    if (decoded !== null) {
+      this.dispatchEvent(decoded.event, decoded.payload);
+    }
+  }
+
+  private dispatchEvent(event: string, payload: unknown, rawType?: unknown): void {
+    const listeners = this.eventListeners.get(event);
+    if (listeners === undefined || listeners.size === 0) {
+      return;
+    }
+    listeners.forEach(callback => {
+      try {
+        callback(payload);
       } catch (error) {
-        log.error('Failed to parse message', { data: event.data, error });
+        log.error('Error in WebSocket event listener', {
+          event,
+          rawType,
+          error,
+        });
       }
-    };
+    });
   }
 
   private mapLegacyTypeToEventName(type: unknown): string | null {
@@ -578,7 +640,6 @@ export class WebSocketTransportAdapter implements ITransportAdapter {
       await this.ensureConnected();
     }
 
-    const messageId = `msg_${Date.now()}_${++this.messageIdCounter}`;
     // Translate the frontend snake_case command to the app-server JSON-RPC
     // method so agent-kernel requests reach the app-server surface in web mode.
     const method = resolveWsMethod(action);
@@ -595,31 +656,30 @@ export class WebSocketTransportAdapter implements ITransportAdapter {
     // desktop host does in Rust (`agentic_api.rs`).
     const body = encodeRequestBody(action, envelope);
 
-    return new Promise((resolve, reject) => {
-      const timeout = setTimeout(() => {
-        this.pendingRequests.delete(messageId);
-        reject(new Error(`Request timeout: ${action}`));
-      }, 30000);
-
-      this.pendingRequests.set(messageId, {
-        resolve: (value: any) => resolve(decodeResponseBody(action, value)),
-        reject,
-        timeout,
-      });
-
-      try {
-        this.ws!.send(JSON.stringify({
-          jsonrpc: '2.0',
-          id: messageId,
-          method,
-          params: body,
-        }));
-      } catch (error) {
-        clearTimeout(timeout);
-        this.pendingRequests.delete(messageId);
-        reject(error);
+    try {
+      const generation = this.rpcGeneration;
+      if (generation === null) {
+        throw new JsonRpcTransportError('WebSocket JSON-RPC peer is unavailable');
       }
-    });
+      const result = await generation.peer.request(method, body);
+      return decodeResponseBody(action, result) as T;
+    } catch (error) {
+      if (error instanceof JsonRpcRemoteError) {
+        throw webSocketResponseError({
+          code: error.code,
+          message: error.message,
+          data: error.data,
+        });
+      }
+      if (error instanceof JsonRpcTimeoutError) {
+        const timeout = new Error(`Request timeout: ${action}`) as Error & {
+          cause?: unknown;
+        };
+        timeout.cause = error;
+        throw timeout;
+      }
+      throw error;
+    }
   }
   
    
@@ -650,20 +710,19 @@ export class WebSocketTransportAdapter implements ITransportAdapter {
     // and reopen the socket we are about to close.
     this.clearReconnectTimer();
 
-    this.pendingRequests.forEach((pending) => {
-      clearTimeout(pending.timeout);
-      pending.reject(new Error('WebSocket manually disconnected'));
-    });
-    this.pendingRequests.clear();
-    
-    
     this.eventListeners.clear();
-    
-    
+
+    const generation = this.rpcGeneration;
+    this.rpcGeneration = null;
     if (this.ws) {
       this.ws.onclose = null;
-      this.ws.close();
+      await generation?.peer.close();
+      if (this.ws.readyState < WebSocket.CLOSING) {
+        this.ws.close();
+      }
       this.ws = null;
+    } else {
+      await generation?.peer.close();
     }
     
     
diff --git a/src/web-ui/src/infrastructure/api/index.ts b/src/web-ui/src/infrastructure/api/index.ts
index c440392c72..5740d7c06b 100644
--- a/src/web-ui/src/infrastructure/api/index.ts
+++ b/src/web-ui/src/infrastructure/api/index.ts
@@ -33,7 +33,6 @@ import { pageAPI } from './service-api/PageAPI';
 import { gitAPI } from './service-api/GitAPI';
 import { gitAgentAPI } from './service-api/GitAgentAPI';
 import { gitRepoHistoryAPI, type GitRepoHistory } from './service-api/GitRepoHistoryAPI';
-import { startchatAgentAPI } from './service-api/StartchatAgentAPI';
 import { sessionAPI } from './service-api/SessionAPI';
 import { i18nAPI } from './service-api/I18nAPI';
 import { btwAPI } from './service-api/BtwAPI';
@@ -45,7 +44,7 @@ import { worktreeAPI } from './service-api/WorktreeAPI';
 import { feedbackAPI } from './service-api/FeedbackAPI';
 
 // Export API modules
-export { feedbackAPI, workspaceAPI, configAPI, aiApi, toolAPI, agentAPI, systemAPI, projectAPI, diffAPI, snapshotAPI, globalAPI, contextAPI, cronAPI, permissionAPI, pageAPI, gitAPI, gitAgentAPI, gitRepoHistoryAPI, startchatAgentAPI, sessionAPI, i18nAPI, btwAPI, editorAiAPI, reviewPlatformAPI, insightsApi, speechAPI, worktreeAPI };
+export { feedbackAPI, workspaceAPI, configAPI, aiApi, toolAPI, agentAPI, systemAPI, projectAPI, diffAPI, snapshotAPI, globalAPI, contextAPI, cronAPI, permissionAPI, pageAPI, gitAPI, gitAgentAPI, gitRepoHistoryAPI, sessionAPI, i18nAPI, btwAPI, editorAiAPI, reviewPlatformAPI, insightsApi, speechAPI, worktreeAPI };
 export * from './service-api/ReviewPlatformAPI';
 
 // Export types
@@ -71,7 +70,6 @@ export const bitfunAPI = {
   git: gitAPI,
   gitAgent: gitAgentAPI,
   gitRepoHistory: gitRepoHistoryAPI,
-  startchatAgent: startchatAgentAPI,
   session: sessionAPI,
   i18n: i18nAPI,
   btw: btwAPI,
diff --git a/src/web-ui/src/infrastructure/api/service-api/AIApi.ts b/src/web-ui/src/infrastructure/api/service-api/AIApi.ts
index c5d8bd8ed4..7a8af80032 100644
--- a/src/web-ui/src/infrastructure/api/service-api/AIApi.ts
+++ b/src/web-ui/src/infrastructure/api/service-api/AIApi.ts
@@ -7,6 +7,7 @@ import type { ConnectionTestMessageCode } from '@/shared/utils/aiConnectionTestM
 import type {
   OpenCodePlan,
   ReasoningCatalogProjection,
+  ReasoningConfig,
   SubscriptionProvider,
 } from '@/infrastructure/config/types';
 export type {
@@ -180,6 +181,15 @@ export interface AIModelCatalog {
   session_model_id?: string;
 }
 
+export interface ReasoningCatalogProjectionRequest {
+  provider: string;
+  modelName: string;
+  baseUrl: string;
+  contextWindow?: number;
+  maxTokens?: number;
+  reasoning: ReasoningConfig;
+}
+
 export type SubscriptionLoginStatus = 'pending' | 'authorized' | 'failed' | 'cancelled';
 
 export interface SubscriptionOfferingModel {
@@ -253,6 +263,19 @@ export class AIApi {
     }
   }
 
+  async projectReasoningCatalog(
+    request: ReasoningCatalogProjectionRequest,
+  ): Promise<ReasoningCatalogProjection> {
+    try {
+      return await api.invoke<ReasoningCatalogProjection>(
+        'project_ai_model_reasoning_catalog',
+        { request },
+      );
+    } catch (error) {
+      throw createTauriCommandError('project_ai_model_reasoning_catalog', error);
+    }
+  }
+
   async getModelsDevCatalogStatus(): Promise<ModelsDevCatalogStatus> {
     try {
       return await api.invoke<ModelsDevCatalogStatus>('get_models_dev_catalog_status', {});
diff --git a/src/web-ui/src/infrastructure/api/service-api/AgentAPI.test.ts b/src/web-ui/src/infrastructure/api/service-api/AgentAPI.test.ts
index 82b7b056b4..b843924991 100644
--- a/src/web-ui/src/infrastructure/api/service-api/AgentAPI.test.ts
+++ b/src/web-ui/src/infrastructure/api/service-api/AgentAPI.test.ts
@@ -88,6 +88,42 @@ describe('AgentAPI', () => {
     });
   });
 
+  it('normalizes omitted rollback file and retired-turn arrays', async () => {
+    invokeMock.mockResolvedValueOnce({
+      status: 'completed',
+      sessionId: 'session-1',
+      transcript: { sessionId: 'session-1', messages: [] },
+      composer: { kind: 'preserve' },
+      changed: true,
+      hiddenTurnCount: 1,
+    });
+
+    await expect(agentAPI.rollbackSessionToTurn({
+      workspacePath: 'D:/workspace/BitFun',
+      sessionId: 'session-1',
+      targetTurnId: 'turn-7',
+    })).resolves.toMatchObject({
+      status: 'completed',
+      retiredTurnIds: [],
+      restoredFiles: [],
+    });
+
+    invokeMock.mockResolvedValueOnce({
+      status: 'recovery_required',
+      sessionId: 'session-1',
+      mutationId: 'mutation-1',
+      reason: 'reconcile marker',
+    });
+    await expect(agentAPI.rollbackSessionToTurn({
+      workspacePath: 'D:/workspace/BitFun',
+      sessionId: 'session-1',
+      targetTurnId: 'turn-7',
+    })).resolves.toMatchObject({
+      status: 'recovery_required',
+      affectedFiles: [],
+    });
+  });
+
   it('sends subagent timeout controls with the desktop command request shape', async () => {
     await agentAPI.setSubagentTimeout('subagent-session', { type: 'disable' });
 
diff --git a/src/web-ui/src/infrastructure/api/service-api/AgentAPI.ts b/src/web-ui/src/infrastructure/api/service-api/AgentAPI.ts
index 5a8d5d4a83..aa256bafaf 100644
--- a/src/web-ui/src/infrastructure/api/service-api/AgentAPI.ts
+++ b/src/web-ui/src/infrastructure/api/service-api/AgentAPI.ts
@@ -283,6 +283,56 @@ export type LoadSessionTurnWindowResponse =
       catalog: SessionTurnCatalog;
     };
 
+export interface RollbackSessionToTurnRequest {
+  workspacePath: string;
+  sessionId: string;
+  targetTurnId: string;
+  expectedStorageTurnIndex?: number;
+  expectedCatalogRevision?: string;
+  remoteConnectionId?: string;
+  remoteSshHost?: string;
+}
+
+export type RollbackSessionToTurnOutcome =
+  | {
+      status: 'completed';
+      sessionId: string;
+      transcript: unknown;
+      composer: { kind: 'preserve' } | { kind: 'clear' } | { kind: 'replace'; text: string };
+      retiredTurnIds: string[];
+      changed: boolean;
+      hiddenTurnCount: number;
+      boundaryStorageTurnIndex?: number;
+      targetTurnId?: string;
+      restoredFiles: string[];
+      reloadRequired?: boolean;
+      reloadReason?: string;
+    }
+  | {
+      status: 'recovery_required';
+      sessionId: string;
+      mutationId: string;
+      affectedFiles: string[];
+      reason: string;
+    };
+
+type RollbackSessionToTurnCompletedOutcome = Extract<
+  RollbackSessionToTurnOutcome,
+  { status: 'completed' }
+>;
+type RollbackSessionToTurnRecoveryOutcome = Extract<
+  RollbackSessionToTurnOutcome,
+  { status: 'recovery_required' }
+>;
+type RollbackSessionToTurnWireOutcome =
+  | (Omit<RollbackSessionToTurnCompletedOutcome, 'retiredTurnIds' | 'restoredFiles'> & {
+      retiredTurnIds?: string[];
+      restoredFiles?: string[];
+    })
+  | (Omit<RollbackSessionToTurnRecoveryOutcome, 'affectedFiles'> & {
+      affectedFiles?: string[];
+    });
+
 export interface EnsureAssistantBootstrapRequest {
   sessionId: string;
   workspacePath: string;
@@ -329,6 +379,8 @@ export interface SessionPermissionModeRequest {
   sessionId: string;
   /** Omit or pass null to clear the override and follow the global default. */
   mode?: SessionPermissionMode | null;
+  /** Exact active turn whose temporary override should be read or cleared. */
+  turnId?: string;
   workspacePath?: string;
   remoteConnectionId?: string;
   remoteSshHost?: string;
@@ -337,6 +389,12 @@ export interface SessionPermissionModeRequest {
 
 export interface SessionPermissionModeResponse {
   mode: SessionPermissionMode | null;
+  turnMode?: SessionPermissionMode | null;
+  activeTurnId?: string | null;
+}
+
+export interface ActiveTurnPermissionModeRequest extends SessionPermissionModeRequest {
+  turnId: string;
 }
 
 export interface UpdateSessionModeRequest {
@@ -457,6 +515,27 @@ export interface AgenticEvent {
   [key: string]: any;
 }
 
+export interface InterruptedDialogTurnEvent extends AgenticEvent {
+  turnId: string;
+  executionGeneration: number;
+  modelId?: string;
+}
+
+export interface RecoverInterruptedDialogTurnRequest {
+  sessionId: string;
+  dialogTurnId: string;
+  executionGeneration: number;
+  workspacePath?: string;
+  remoteConnectionId?: string;
+  remoteSshHost?: string;
+}
+
+export interface RecoverInterruptedDialogTurnResponse {
+  sessionId: string;
+  turnId: string;
+  executionGeneration: number;
+}
+
 export type DialogTurnStartedEvent = AgenticEvent;
 
 export interface OpenBuiltInBrowserEvent {
@@ -798,17 +877,44 @@ export class AgentAPI {
     }
   }
 
+  async interruptDialogTurn(sessionId: string, dialogTurnId: string): Promise<void> {
+    try {
+      await api.invoke<void>('interrupt_dialog_turn', { request: { sessionId, dialogTurnId } });
+    } catch (error) {
+      throw createTauriCommandError('interrupt_dialog_turn', error, { sessionId, dialogTurnId });
+    }
+  }
+
+  async recoverInterruptedDialogTurn(
+    request: RecoverInterruptedDialogTurnRequest,
+  ): Promise<RecoverInterruptedDialogTurnResponse> {
+    try {
+      return await api.invoke<RecoverInterruptedDialogTurnResponse>(
+        'recover_interrupted_dialog_turn',
+        { request },
+      );
+    } catch (error) {
+      throw createTauriCommandError('recover_interrupted_dialog_turn', error, request);
+    }
+  }
+
   /**
    * Inject a user "steering" message into the currently running dialog turn.
    * Mirrors Codex CLI's Esc-to-steer behavior: the message is queued on the
    * Rust side and consumed by the execution engine at the next round boundary
    * without ending the current turn.
+   *
+   * Carries the same payload a turn submission does — attachments and message
+   * metadata included — so a message keeps its content whether it is sent at a
+   * turn boundary or injected into a running turn.
    */
   async steerDialogTurn(request: {
     sessionId: string;
     dialogTurnId: string;
     content: string;
     displayContent?: string;
+    imageContexts?: unknown[];
+    userMessageMetadata?: Record<string, unknown>;
   }): Promise<{ success: boolean; steeringId: string }> {
     try {
       return await api.invoke<{ success: boolean; steeringId: string }>(
@@ -935,6 +1041,32 @@ export class AgentAPI {
     }
   }
 
+  async rollbackSessionToTurn(
+    request: RollbackSessionToTurnRequest,
+  ): Promise<RollbackSessionToTurnOutcome> {
+    try {
+      const outcome = await api.invoke<RollbackSessionToTurnWireOutcome>('rollback_session_to_turn', {
+        request,
+      });
+      if (outcome.status === 'completed') {
+        return {
+          ...outcome,
+          retiredTurnIds: outcome.retiredTurnIds ?? [],
+          restoredFiles: outcome.restoredFiles ?? [],
+        };
+      }
+      return {
+        ...outcome,
+        affectedFiles: outcome.affectedFiles ?? [],
+      };
+    } catch (error) {
+      throw createTauriCommandError('rollback_session_to_turn', error, {
+        sessionId: request.sessionId,
+        targetTurnId: request.targetTurnId,
+      });
+    }
+  }
+
   async setSessionMemoryMode(
     request: SetSessionMemoryModeRequest
   ): Promise<SetSessionMemoryModeResponse> {
@@ -1007,6 +1139,20 @@ export class AgentAPI {
     }
   }
 
+  /** Updates the temporary mode for one exact active turn. */
+  async updateActiveTurnPermissionMode(
+    request: ActiveTurnPermissionModeRequest,
+  ): Promise<SessionPermissionModeResponse> {
+    try {
+      return await api.invoke<SessionPermissionModeResponse>(
+        'update_active_turn_permission_mode',
+        { request },
+      );
+    } catch (error) {
+      throw createTauriCommandError('update_active_turn_permission_mode', error, request);
+    }
+  }
+
   /** Reads a session's own permission mode; `null` means it follows the default. */
   async getSessionPermissionMode(
     request: SessionPermissionModeRequest,
@@ -1215,6 +1361,14 @@ export class AgentAPI {
     return api.listen<AgenticEvent>('agentic://dialog-turn-cancelled', callback);
   }
 
+  onDialogTurnInterrupted(callback: (event: InterruptedDialogTurnEvent) => void): () => void {
+    return api.listen<InterruptedDialogTurnEvent>('agentic://dialog-turn-interrupted', callback);
+  }
+
+  onDialogTurnRecovered(callback: (event: InterruptedDialogTurnEvent) => void): () => void {
+    return api.listen<InterruptedDialogTurnEvent>('agentic://dialog-turn-recovered', callback);
+  }
+
    
   onTokenUsageUpdated(callback: (event: AgenticEvent) => void): () => void {
     return api.listen<AgenticEvent>('agentic://token-usage-updated', callback);
diff --git a/src/web-ui/src/infrastructure/api/service-api/ApiClient.test.ts b/src/web-ui/src/infrastructure/api/service-api/ApiClient.test.ts
index df17100587..dd7e6d8c26 100644
--- a/src/web-ui/src/infrastructure/api/service-api/ApiClient.test.ts
+++ b/src/web-ui/src/infrastructure/api/service-api/ApiClient.test.ts
@@ -1,5 +1,11 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { ApiClient } from './ApiClient';
+import { ApiClient, createRetryMiddleware } from './ApiClient';
+import {
+  LOCAL_SURFACE_ID,
+  SurfaceChangedError,
+  activateSurface,
+  isSurfaceChangedError,
+} from '@/infrastructure/peer-device/deviceSurface';
 
 const adapterMocks = vi.hoisted(() => ({
   request: vi.fn(),
@@ -22,6 +28,7 @@ const loggerMocks = vi.hoisted(() => ({
 
 vi.mock('../adapters', () => ({
   getTransportAdapter: () => adapterMocks,
+  isPeerLocalOnlyCommand: (command: string) => command === 'account_status',
 }));
 
 vi.mock('@/shared/utils/logger', () => ({
@@ -36,6 +43,7 @@ vi.mock('@/shared/utils/startupTrace', () => ({
 
 describe('ApiClient', () => {
   beforeEach(() => {
+    activateSurface(LOCAL_SURFACE_ID);
     vi.clearAllMocks();
     delete globalThis.__BITFUN_PERF_TRACE_ENABLED__;
   });
@@ -122,6 +130,96 @@ describe('ApiClient', () => {
     });
   });
 
+  it('preserves a surface change as control flow and never retries it', async () => {
+    adapterMocks.request.mockRejectedValue(
+      new SurfaceChangedError('peer-b', 7, 'load sessions'),
+    );
+    const client = new ApiClient({ enableLogging: true, retries: 3 });
+
+    const error = await client.invoke('list_persisted_sessions_page', {
+      request: { workspacePath: '/repo' },
+    }).catch((caught: unknown) => caught);
+
+    expect(isSurfaceChangedError(error)).toBe(true);
+    expect(adapterMocks.request).toHaveBeenCalledTimes(1);
+    expect(loggerMocks.warn).not.toHaveBeenCalledWith(
+      'Retrying request',
+      expect.anything(),
+    );
+  });
+
+  it('does not let retry middleware replay a stale request on another surface', async () => {
+    adapterMocks.request.mockRejectedValue(
+      new SurfaceChangedError('peer-b', 7, 'load sessions'),
+    );
+    const client = new ApiClient({
+      enableLogging: false,
+      retries: 0,
+      middleware: [createRetryMiddleware(3, 0)],
+    });
+
+    const error = await client.invoke('list_persisted_sessions_page', {
+      request: { workspacePath: '/repo' },
+    }).catch((caught: unknown) => caught);
+
+    expect(isSurfaceChangedError(error)).toBe(true);
+    expect(adapterMocks.request).toHaveBeenCalledTimes(1);
+  });
+
+  it('checks the surface again when delayed middleware reaches the transport', async () => {
+    let continueRequest!: () => void;
+    const middlewareGate = new Promise<void>(resolve => {
+      continueRequest = resolve;
+    });
+    const client = new ApiClient({
+      enableLogging: false,
+      retries: 0,
+      middleware: [async (request, next) => {
+        await middlewareGate;
+        return next(request);
+      }],
+    });
+
+    const pending = client.invoke('list_persisted_sessions_page', {
+      request: { workspacePath: '/repo' },
+    });
+    activateSurface('peer-b');
+    continueRequest();
+
+    await expect(pending).rejects.toSatisfy(isSurfaceChangedError);
+    expect(adapterMocks.request).not.toHaveBeenCalled();
+  });
+
+  it('rejects a product response that lands after the device activation changed', async () => {
+    let resolveRequest!: (value: unknown) => void;
+    adapterMocks.request.mockReturnValueOnce(new Promise(resolve => {
+      resolveRequest = resolve;
+    }));
+    const client = new ApiClient({ enableLogging: false, retries: 0 });
+
+    const pending = client.invoke('list_persisted_sessions_page', {
+      request: { workspacePath: '/repo' },
+    });
+    activateSurface('peer-b');
+    resolveRequest({ sessions: [] });
+
+    await expect(pending).rejects.toSatisfy(isSurfaceChangedError);
+  });
+
+  it('allows controller-plane responses to survive a rendered surface change', async () => {
+    let resolveRequest!: (value: unknown) => void;
+    adapterMocks.request.mockReturnValueOnce(new Promise(resolve => {
+      resolveRequest = resolve;
+    }));
+    const client = new ApiClient({ enableLogging: false, retries: 0 });
+
+    const pending = client.invoke('account_status', {});
+    activateSurface('peer-b');
+    resolveRequest({ loggedIn: true });
+
+    await expect(pending).resolves.toEqual({ loggedIn: true });
+  });
+
   it('uses the message from plain structured Tauri errors', async () => {
     const transportError = {
       code: 'worktree_not_found',
diff --git a/src/web-ui/src/infrastructure/api/service-api/ApiClient.ts b/src/web-ui/src/infrastructure/api/service-api/ApiClient.ts
index ba9ade497f..d16e17c9a7 100644
--- a/src/web-ui/src/infrastructure/api/service-api/ApiClient.ts
+++ b/src/web-ui/src/infrastructure/api/service-api/ApiClient.ts
@@ -1,6 +1,11 @@
  
 
-import { getTransportAdapter, ITransportAdapter, type TransportRequestTiming } from '../adapters';
+import {
+  getTransportAdapter,
+  isPeerLocalOnlyCommand,
+  ITransportAdapter,
+  type TransportRequestTiming,
+} from '../adapters';
 import {
   IApiClient,
   ApiResponse,
@@ -17,6 +22,11 @@ import { createLogger } from '@/shared/utils/logger';
 import { elapsedMs, nowMs } from '@/shared/utils/timing';
 import { estimateJsonBytes, isRemoteTraceRequest, startupTrace } from '@/shared/utils/startupTrace';
 import { sanitizeErrorForLog, sanitizeLogValue, sanitizeTextForLog } from '../logSanitizer';
+import {
+  SurfaceChangedError,
+  getActiveSurfaceScope,
+  isSurfaceChangedError,
+} from '@/infrastructure/peer-device/deviceSurface';
 
 const log = createLogger('ApiClient');
 const sanitizeForLog = sanitizeLogValue;
@@ -286,15 +296,38 @@ export class ApiClient implements IApiClient {
   }
 
   private createRequest(type: 'tauri' | 'http', config: TauriCommandConfig | HttpRequestConfig): ApiRequest {
+    const scope = type === 'tauri' ? getActiveSurfaceScope() : null;
     return {
       id: `${type}-${Date.now()}-${Math.random()}`,
       type,
       config,
       timestamp: new Date(),
-      retryCount: 0
+      retryCount: 0,
+      surfaceId: scope?.surfaceId,
+      surfaceEpoch: scope?.epoch,
     };
   }
 
+  private assertRequestSurface(request: ApiRequest, action: string): void {
+    if (request.type !== 'tauri') {
+      return;
+    }
+    const command = (request.config as TauriCommandConfig).command;
+    // These commands are controller-plane operations even while a peer is
+    // rendered, so a UI surface activation does not change their authority.
+    if (isPeerLocalOnlyCommand(command)) {
+      return;
+    }
+    const scope = getActiveSurfaceScope();
+    if (request.surfaceId !== scope.surfaceId || request.surfaceEpoch !== scope.epoch) {
+      throw new SurfaceChangedError(
+        request.surfaceId ?? scope.surfaceId,
+        request.surfaceEpoch ?? scope.epoch,
+        action,
+      );
+    }
+  }
+
   private async executeRequest<T>(request: ApiRequest): Promise<T> {
     const startedAt = nowMs();
     const estimatePayloadBytes = shouldEstimateApiPayloadBytes();
@@ -322,7 +355,10 @@ export class ApiClient implements IApiClient {
     this.updateStats({ totalRequests: this.stats.totalRequests + 1 });
 
     try {
-      
+      // In particular this stops an ApiClient retry from following a newly
+      // rebound `this.adapter` onto another device.
+      this.assertRequestSurface(request, traceCommand);
+
       const controller = new AbortController();
       activeRequestsAtStart = this.activeRequests.size;
       this.activeRequests.set(request.id, controller);
@@ -340,6 +376,10 @@ export class ApiClient implements IApiClient {
       try {
         
         const response = await this.applyMiddleware(request, async (req) => {
+          // Middleware may delay or replay `next()`. Check at the actual
+          // transport boundary as well as at request entry so it cannot run an
+          // old product request through the adapter bound during that delay.
+          this.assertRequestSurface(req, traceCommand);
           if (req.type === 'tauri') {
             transportTiming = {};
             return this.executeTauriCommand(req.config as TauriCommandConfig, transportTiming);
@@ -347,6 +387,7 @@ export class ApiClient implements IApiClient {
             return this.executeHttpRequest(req.config as HttpRequestConfig, controller.signal);
           }
         });
+        this.assertRequestSurface(request, traceCommand);
 
         clearTimeout(timeoutId);
         maxConcurrentRequests = this.activeRequestPressure.get(request.id)?.maxConcurrentRequests ?? this.activeRequests.size;
@@ -438,7 +479,14 @@ export class ApiClient implements IApiClient {
         remote,
       });
 
-      
+      // A device activation ended. This is typed control flow: wrapping it as
+      // COMMAND_FAILED would turn a normal switch into a product error, and
+      // retrying could send the old request through the newly bound adapter.
+      if (isSurfaceChangedError(error)) {
+        throw error;
+      }
+
+
       if (!optionalConfigNotFound && request.retryCount < (request.config.retries || this.config.retries)) {
         const delay = (request.config.retryDelay || this.config.retryDelay) * Math.pow(2, request.retryCount);
         
@@ -485,8 +533,11 @@ export class ApiClient implements IApiClient {
         timestamp: new Date()
       };
     } catch (error) {
+      if (isSurfaceChangedError(error)) {
+        throw error;
+      }
       const structuredError = preserveStructuredCommandError(error);
-      const errorMessage = structuredError?.message ?? (error instanceof Error ? error.message : String(error));
+      const errorMessage = structuredError?.message ?? transportErrorMessage(error);
       
       
       const isExpectedError = errorMessage.includes('not found') || 
@@ -712,6 +763,12 @@ export function createRetryMiddleware(maxRetries: number = 3, baseDelay: number
       try {
         return await next(request);
       } catch (error) {
+        // Retrying inside middleware bypasses executeRequest's outer surface
+        // assertion. Let the typed cancellation escape immediately so an old
+        // request cannot be replayed through the adapter bound for a new device.
+        if (isSurfaceChangedError(error)) {
+          throw error;
+        }
         lastError = error as Error;
         
         if (attempt < maxRetries) {
diff --git a/src/web-ui/src/infrastructure/api/service-api/ExternalSourcesAPI.test.ts b/src/web-ui/src/infrastructure/api/service-api/ExternalSourcesAPI.test.ts
index c80b1ea376..d1f9002e38 100644
--- a/src/web-ui/src/infrastructure/api/service-api/ExternalSourcesAPI.test.ts
+++ b/src/web-ui/src/infrastructure/api/service-api/ExternalSourcesAPI.test.ts
@@ -457,6 +457,50 @@ describe('ExternalSourcesAPI', () => {
     });
   });
 
+  it('sends exact owner-scoped decision sets for bulk resource changes', async () => {
+    const toolDecisions = [{ approvalKey: 'tool-approval-v1', decisionKey: 'tool-v1' }];
+    const subagentDecisions = [{ candidateId: 'agent-review', decisionKey: 'agent-v1' }];
+    const mcpDecisions = [{ candidateId: 'mcp-docs', decisionKey: 'mcp-v1' }];
+
+    await externalSourcesAPI.setToolTargetsEnabled(
+      'D:/workspace/project', toolDecisions, true, 11, 7,
+    );
+    await externalSourcesAPI.setSubagentsEnabled(
+      'D:/workspace/project', subagentDecisions, false, 12, 8,
+    );
+    await externalSourcesAPI.setMcpServersEnabled(
+      'D:/workspace/project', mcpDecisions, true, 13, 9,
+    );
+
+    expect(invokeMock).toHaveBeenCalledWith('set_external_tool_targets_enabled_command', {
+      request: {
+        workspacePath: 'D:/workspace/project',
+        decisions: toolDecisions,
+        enabled: true,
+        expectedCatalogGeneration: 11,
+        expectedPreferenceRevision: 7,
+      },
+    });
+    expect(invokeMock).toHaveBeenCalledWith('set_external_subagents_enabled_command', {
+      request: {
+        workspacePath: 'D:/workspace/project',
+        decisions: subagentDecisions,
+        enabled: false,
+        expectedSubagentGeneration: 12,
+        expectedPreferenceRevision: 8,
+      },
+    });
+    expect(invokeMock).toHaveBeenCalledWith('set_external_mcp_servers_enabled_command', {
+      request: {
+        workspacePath: 'D:/workspace/project',
+        decisions: mcpDecisions,
+        enabled: true,
+        expectedMcpGeneration: 13,
+        expectedPreferenceRevision: 9,
+      },
+    });
+  });
+
   it('sends policy scope and optimistic revision as one atomic mutation', async () => {
     const catalogUpdated = vi.fn();
     const unsubscribe = globalEventBus.on('mode:config:updated', catalogUpdated);
diff --git a/src/web-ui/src/infrastructure/api/service-api/ExternalSourcesAPI.ts b/src/web-ui/src/infrastructure/api/service-api/ExternalSourcesAPI.ts
index 05e0dd3218..d6a354a9d5 100644
--- a/src/web-ui/src/infrastructure/api/service-api/ExternalSourcesAPI.ts
+++ b/src/web-ui/src/infrastructure/api/service-api/ExternalSourcesAPI.ts
@@ -1549,6 +1549,24 @@ export const externalSourcesAPI = {
     });
   },
 
+  setToolTargetsEnabled(
+    workspacePath: string | undefined,
+    decisions: Array<{ approvalKey: string; decisionKey: string }>,
+    enabled: boolean,
+    expectedCatalogGeneration: number,
+    expectedPreferenceRevision: number,
+  ) {
+    return invokeSnapshot('set_external_tool_targets_enabled_command', {
+      request: {
+        workspacePath: normalizeOptionalWorkspacePath(workspacePath),
+        decisions,
+        enabled,
+        expectedCatalogGeneration,
+        expectedPreferenceRevision,
+      },
+    });
+  },
+
   setToolConflictChoice(
     workspacePath: string | undefined,
     conflictKey: string,
@@ -1587,6 +1605,26 @@ export const externalSourcesAPI = {
     return catalog;
   },
 
+  async setSubagentsEnabled(
+    workspacePath: string | undefined,
+    decisions: Array<{ candidateId: string; decisionKey: string }>,
+    enabled: boolean,
+    expectedSubagentGeneration: number,
+    expectedPreferenceRevision: number,
+  ) {
+    const catalog = await invokeSnapshot('set_external_subagents_enabled_command', {
+      request: {
+        workspacePath: normalizeOptionalWorkspacePath(workspacePath),
+        decisions,
+        enabled,
+        expectedSubagentGeneration,
+        expectedPreferenceRevision,
+      },
+    });
+    emitExternalAgentCatalogUpdated(workspacePath);
+    return catalog;
+  },
+
   async setSubagentModelBinding(
     workspacePath: string | undefined,
     bindingKey: string,
@@ -1649,6 +1687,24 @@ export const externalSourcesAPI = {
     });
   },
 
+  setMcpServersEnabled(
+    workspacePath: string | undefined,
+    decisions: Array<{ candidateId: string; decisionKey: string }>,
+    enabled: boolean,
+    expectedMcpGeneration: number,
+    expectedPreferenceRevision: number,
+  ) {
+    return invokeSnapshot('set_external_mcp_servers_enabled_command', {
+      request: {
+        workspacePath: normalizeOptionalWorkspacePath(workspacePath),
+        decisions,
+        enabled,
+        expectedMcpGeneration,
+        expectedPreferenceRevision,
+      },
+    });
+  },
+
   chooseMcpConflict(
     workspacePath: string | undefined,
     conflictKey: string,
diff --git a/src/web-ui/src/infrastructure/api/service-api/SessionAPI.test.ts b/src/web-ui/src/infrastructure/api/service-api/SessionAPI.test.ts
index 1defb7f010..0704b63e44 100644
--- a/src/web-ui/src/infrastructure/api/service-api/SessionAPI.test.ts
+++ b/src/web-ui/src/infrastructure/api/service-api/SessionAPI.test.ts
@@ -1,6 +1,5 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { SessionAPI } from './SessionAPI';
-import type { DialogTurnData } from '@/shared/types/session-history';
 
 const invokeMock = vi.hoisted(() => vi.fn());
 
@@ -186,56 +185,4 @@ describe('SessionAPI paged metadata reads', () => {
       },
     });
   });
-
-  it('records local command turns through the authoritative catalog command', async () => {
-    const turnData: DialogTurnData = {
-      turnId: 'local-usage-1',
-      turnIndex: 0,
-      sessionId: 'session-1',
-      timestamp: 10,
-      kind: 'local_command',
-      userMessage: {
-        id: 'local-usage-user-1',
-        content: '# Session Usage Report',
-        timestamp: 10,
-        metadata: { localCommandKind: 'usage_report', modelVisible: false },
-      },
-      modelRounds: [],
-      startTime: 10,
-      endTime: 10,
-      status: 'completed',
-    };
-    const response = {
-      turnId: 'local-usage-1',
-      storageTurnIndex: 7,
-      totalTurnCount: 8,
-      turnCatalog: {
-        schemaVersion: 1,
-        sessionId: 'session-1',
-        revision: 'catalog-8',
-        totalTurnCount: 8,
-        complete: true,
-        entries: [{
-          ordinal: 7,
-          storageTurnIndex: 7,
-          turnId: 'local-usage-1',
-          previewTruncated: false,
-        }],
-      },
-    };
-    invokeMock.mockResolvedValueOnce(response);
-
-    await expect(
-      sessionAPI.recordLocalCommandTurn(turnData, '/repo', 'remote-1', 'host'),
-    ).resolves.toBe(response);
-
-    expect(invokeMock).toHaveBeenCalledWith('record_local_command_turn', {
-      request: {
-        turn_data: turnData,
-        workspace_path: '/repo',
-        remote_connection_id: 'remote-1',
-        remote_ssh_host: 'host',
-      },
-    });
-  });
 });
diff --git a/src/web-ui/src/infrastructure/api/service-api/SessionAPI.ts b/src/web-ui/src/infrastructure/api/service-api/SessionAPI.ts
index d9ced04a81..94ad07304e 100644
--- a/src/web-ui/src/infrastructure/api/service-api/SessionAPI.ts
+++ b/src/web-ui/src/infrastructure/api/service-api/SessionAPI.ts
@@ -4,7 +4,6 @@ import { createTauriCommandError } from '../errors/TauriCommandError';
 import type {
   DialogTurnData,
   SessionMetadata,
-  SessionTurnCatalog,
 } from '@/shared/types/session-history';
 import { normalizeRemoteSessionScope } from '@/shared/utils/remoteSessionScope';
 
@@ -222,13 +221,6 @@ export interface SessionUsageReport {
   };
 }
 
-export interface RecordLocalCommandTurnResponse {
-  turnId: string;
-  storageTurnIndex: number;
-  totalTurnCount: number;
-  turnCatalog: SessionTurnCatalog;
-}
-
 function remoteSessionFields(
   remoteConnectionId?: string,
   remoteSshHost?: string
@@ -386,28 +378,6 @@ export class SessionAPI {
     }
   }
 
-  async recordLocalCommandTurn(
-    turnData: DialogTurnData,
-    workspacePath: string,
-    remoteConnectionId?: string,
-    remoteSshHost?: string,
-  ): Promise<RecordLocalCommandTurnResponse> {
-    try {
-      return await api.invoke('record_local_command_turn', {
-        request: {
-          turn_data: turnData,
-          workspace_path: workspacePath,
-          ...remoteSessionFields(remoteConnectionId, remoteSshHost),
-        },
-      });
-    } catch (error) {
-      throw createTauriCommandError('record_local_command_turn', error, {
-        turnData,
-        workspacePath,
-      });
-    }
-  }
-
   async saveSessionMetadata(
     metadata: SessionMetadata,
     workspacePath: string,
diff --git a/src/web-ui/src/infrastructure/api/service-api/SnapshotAPI.ts b/src/web-ui/src/infrastructure/api/service-api/SnapshotAPI.ts
index c9d024eb26..5ac57c4f4d 100644
--- a/src/web-ui/src/infrastructure/api/service-api/SnapshotAPI.ts
+++ b/src/web-ui/src/infrastructure/api/service-api/SnapshotAPI.ts
@@ -494,33 +494,6 @@ export class SnapshotAPI {
   }
 
    
-  async rollbackToTurn(
-    sessionId: string,
-    turnIndex: number,
-    deleteTurns: boolean = false,
-    workspacePath?: string,
-  ): Promise<string[]> {
-    try {
-      const scope = requireSessionSnapshotScope(sessionId, workspacePath);
-      return await api.invoke('rollback_to_turn', {
-        request: {
-          session_id: sessionId,
-          turn_index: turnIndex,
-          delete_turns: deleteTurns,
-          ...scope,
-        }
-      });
-    } catch (error) {
-      throw createTauriCommandError('rollback_to_turn', error, {
-        sessionId,
-        turnIndex,
-        deleteTurns,
-        workspacePath,
-      });
-    }
-  }
-
-   
   async rollbackEntireSession(
     sessionId: string,
     deleteSession: boolean = true,
diff --git a/src/web-ui/src/infrastructure/api/service-api/StartchatAgentAPI.ts b/src/web-ui/src/infrastructure/api/service-api/StartchatAgentAPI.ts
deleted file mode 100644
index 21a6f5acf5..0000000000
--- a/src/web-ui/src/infrastructure/api/service-api/StartchatAgentAPI.ts
+++ /dev/null
@@ -1,212 +0,0 @@
- 
-
-import { api } from './ApiClient';
-import { createTauriCommandError } from '../errors/TauriCommandError';
-
- 
-export interface WorkStateOptions {
-   
-  analyzeGit?: boolean;
-   
-  predictNextActions?: boolean;
-   
-  includeQuickActions?: boolean;
-   
-  language?: 'Chinese' | 'English';
-}
-
- 
-export interface GreetingMessage {
-   
-  title: string;
-   
-  subtitle: string;
-   
-  tagline?: string;
-}
-
- 
-export interface GitWorkState {
-   
-  currentBranch: string;
-   
-  unstagedFiles: number;
-   
-  stagedFiles: number;
-   
-  unpushedCommits: number;
-   
-  aheadBehind?: {
-    ahead: number;
-    behind: number;
-  };
-   
-  modifiedFiles: FileModification[];
-}
-
- 
-export interface FileModification {
-   
-  path: string;
-   
-  changeType: 'Added' | 'Modified' | 'Deleted' | 'Renamed' | 'Untracked';
-   
-  module?: string;
-}
-
- 
-export interface WorkItem {
-   
-  title: string;
-   
-  description: string;
-   
-  relatedFiles: string[];
-   
-  category: 'Backend' | 'Frontend' | 'API' | 'Database' | 'Infrastructure' | 'Testing' | 'Documentation' | 'Other';
-   
-  icon: string;
-}
-
- 
-export interface TimeInfo {
-   
-  minutesSinceLastCommit?: number;
-   
-  lastCommitTimeDesc?: string;
-   
-  timeOfDay: 'Morning' | 'Afternoon' | 'Evening' | 'Night';
-}
-
- 
-export interface CurrentWorkState {
-   
-  summary: string;
-   
-  gitState?: GitWorkState;
-   
-  ongoingWork: WorkItem[];
-   
-  timeInfo: TimeInfo;
-}
-
- 
-export interface PredictedAction {
-   
-  description: string;
-   
-  priority: 'High' | 'Medium' | 'Low';
-   
-  icon: string;
-   
-  isReminder: boolean;
-}
-
- 
-export interface QuickAction {
-   
-  title: string;
-   
-  command: string;
-   
-  icon: string;
-   
-  actionType: 'Continue' | 'ViewStatus' | 'Commit' | 'Visualize' | 'Custom';
-}
-
- 
-export interface WorkStateAnalysis {
-   
-  greeting: GreetingMessage;
-   
-  currentState: CurrentWorkState;
-   
-  predictedActions: PredictedAction[];
-   
-  quickActions: QuickAction[];
-   
-  analyzedAt: string;
-}
-
- 
-export interface WorkStateSummaryResponse {
-   
-  greetingTitle: string;
-   
-  currentStateSummary: string;
-   
-  hasGitChanges: boolean;
-   
-  unstagedFiles: number;
-   
-  unpushedCommits: number;
-   
-  predictedActionsCount: number;
-}
-
- 
-export class StartchatAgentAPI {
-   
-  async analyzeWorkState(
-    repoPath: string,
-    options?: WorkStateOptions
-  ): Promise<WorkStateAnalysis> {
-    try {
-      return await api.invoke('analyze_work_state', {
-        request: {
-          repoPath,
-          options: options || null
-        }
-      });
-    } catch (error) {
-      throw createTauriCommandError('analyze_work_state', error, { repoPath, options });
-    }
-  }
-
-   
-  async quickAnalyzeWorkState(repoPath: string, language?: 'Chinese' | 'English'): Promise<WorkStateAnalysis> {
-    try {
-      
-      return await api.invoke('quick_analyze_work_state', {
-        request: {
-          repoPath,
-          language: language || null
-        }
-      }, {
-        retries: 0
-      });
-    } catch (error) {
-      throw createTauriCommandError('quick_analyze_work_state', error, { repoPath });
-    }
-  }
-
-   
-  async generateGreetingOnly(repoPath: string): Promise<WorkStateAnalysis> {
-    try {
-      return await api.invoke('generate_greeting_only', {
-        request: {
-          repoPath
-        }
-      });
-    } catch (error) {
-      throw createTauriCommandError('generate_greeting_only', error, { repoPath });
-    }
-  }
-
-   
-  async getWorkStateSummary(repoPath: string): Promise<WorkStateSummaryResponse> {
-    try {
-      return await api.invoke('get_work_state_summary', {
-        request: {
-          repoPath
-        }
-      });
-    } catch (error) {
-      throw createTauriCommandError('get_work_state_summary', error, { repoPath });
-    }
-  }
-}
-
-
-export const startchatAgentAPI = new StartchatAgentAPI();
-
diff --git a/src/web-ui/src/infrastructure/api/service-api/WorkspaceAPI.test.ts b/src/web-ui/src/infrastructure/api/service-api/WorkspaceAPI.test.ts
index c667900433..f0b1e37b7c 100644
--- a/src/web-ui/src/infrastructure/api/service-api/WorkspaceAPI.test.ts
+++ b/src/web-ui/src/infrastructure/api/service-api/WorkspaceAPI.test.ts
@@ -2,11 +2,18 @@ import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { workspaceAPI } from './WorkspaceAPI';
 
 const invokeMock = vi.hoisted(() => vi.fn());
+const listenMock = vi.hoisted(() => vi.fn(() => vi.fn()));
+const waitForListenerRegistrationsMock = vi.hoisted(() => vi.fn());
+const streamCapabilityMock = vi.hoisted(() => ({ supported: false }));
 
 vi.mock('./ApiClient', () => ({
   api: {
     invoke: invokeMock,
-    listen: vi.fn(),
+    listen: listenMock,
+    waitForListenerRegistrations: waitForListenerRegistrationsMock,
+    getAdapter: () => ({
+      supportsSearchStreamEvents: () => streamCapabilityMock.supported,
+    }),
   },
 }));
 
@@ -14,6 +21,11 @@ describe('WorkspaceAPI', () => {
   beforeEach(() => {
     invokeMock.mockReset();
     invokeMock.mockResolvedValue('file content');
+    listenMock.mockReset();
+    listenMock.mockImplementation(() => vi.fn());
+    waitForListenerRegistrationsMock.mockReset();
+    waitForListenerRegistrationsMock.mockResolvedValue(undefined);
+    streamCapabilityMock.supported = false;
   });
 
   it('reads text through the registered command with remote routing context', async () => {
@@ -49,4 +61,169 @@ describe('WorkspaceAPI', () => {
       },
     });
   });
+
+  it('browses a directory through the explicit remote workspace scope', async () => {
+    invokeMock.mockResolvedValueOnce([]);
+
+    await workspaceAPI.getDirectoryChildren('/workspace', 'remote-connection-1');
+
+    expect(invokeMock).toHaveBeenCalledWith('get_directory_children', {
+      request: {
+        path: '/workspace',
+        remoteConnectionId: 'remote-connection-1',
+      },
+    });
+  });
+
+  it('searches filenames through the same explicit remote workspace scope', async () => {
+    invokeMock.mockResolvedValueOnce({ results: [], limit: 30, truncated: false });
+
+    await workspaceAPI.searchFilenamesOnlyDetailed(
+      '/workspace',
+      '手写',
+      false,
+      false,
+      false,
+      undefined,
+      30,
+      true,
+      undefined,
+      'remote-connection-1',
+    );
+
+    expect(invokeMock).toHaveBeenCalledWith('search_filenames', {
+      request: expect.objectContaining({
+        rootPath: '/workspace',
+        pattern: '手写',
+        maxResults: 30,
+        includeDirectories: true,
+        remoteConnectionId: 'remote-connection-1',
+      }),
+    });
+  });
+
+  it('uses response-based filename search when transport events are unavailable', async () => {
+    invokeMock.mockResolvedValueOnce({
+      results: [{
+        path: '/workspace/手写笔画标注项目',
+        name: '手写笔画标注项目',
+        isDirectory: true,
+        matchType: 'fileName',
+      }],
+      limit: 30,
+      truncated: false,
+    });
+    const onProgress = vi.fn();
+
+    await workspaceAPI.searchFilenamesOnlyStreamDetailed(
+      '/workspace',
+      '手写',
+      false,
+      false,
+      false,
+      undefined,
+      30,
+      true,
+      { onProgress },
+      undefined,
+      'remote-connection-1',
+    );
+
+    expect(invokeMock).toHaveBeenCalledWith('search_filenames', {
+      request: expect.objectContaining({
+        remoteConnectionId: 'remote-connection-1',
+      }),
+    });
+    expect(invokeMock).not.toHaveBeenCalledWith(
+      'start_search_filenames_stream',
+      expect.anything(),
+    );
+    expect(onProgress).toHaveBeenCalledWith(expect.objectContaining({
+      results: [expect.objectContaining({ name: '手写笔画标注项目' })],
+    }));
+  });
+
+  it('starts scoped streaming only after transport listeners are registered', async () => {
+    streamCapabilityMock.supported = true;
+    const listeners = new Map<string, (event: any) => void>();
+    listenMock.mockImplementation((event: string, callback: (payload: any) => void) => {
+      listeners.set(event, callback);
+      return vi.fn();
+    });
+    invokeMock.mockImplementationOnce(async (command: string, args: {
+      request: { searchId: string };
+    }) => {
+      expect(command).toBe('start_search_filenames_stream');
+      listeners.get('file-search://progress')?.({
+        searchId: args.request.searchId,
+        searchKind: 'filenames',
+        results: [],
+      });
+      listeners.get('file-search://complete')?.({
+        searchId: args.request.searchId,
+        searchKind: 'filenames',
+        limit: 30,
+        truncated: false,
+        totalResults: 0,
+      });
+      return { searchId: args.request.searchId, limit: 30 };
+    });
+
+    await workspaceAPI.searchFilenamesOnlyStreamDetailed(
+      '/workspace',
+      '手写',
+      false,
+      false,
+      false,
+      undefined,
+      30,
+      true,
+      {},
+      undefined,
+      'remote-connection-1',
+    );
+
+    expect(invokeMock).toHaveBeenCalledWith('start_search_filenames_stream', {
+      request: expect.objectContaining({
+        rootPath: '/workspace',
+        remoteConnectionId: 'remote-connection-1',
+      }),
+    });
+    expect(waitForListenerRegistrationsMock).toHaveBeenCalledOnce();
+  });
+
+  it('does not start an orphaned stream when aborted during listener registration', async () => {
+    streamCapabilityMock.supported = true;
+    let finishListenerRegistration: (() => void) | undefined;
+    waitForListenerRegistrationsMock.mockReturnValueOnce(new Promise<void>(resolve => {
+      finishListenerRegistration = resolve;
+    }));
+    const controller = new AbortController();
+
+    const search = workspaceAPI.searchFilenamesOnlyStreamDetailed(
+      '/workspace',
+      '手写',
+      false,
+      false,
+      false,
+      undefined,
+      30,
+      true,
+      {},
+      controller.signal,
+      'remote-connection-1',
+    );
+    await vi.waitFor(() => {
+      expect(waitForListenerRegistrationsMock).toHaveBeenCalledOnce();
+    });
+
+    controller.abort();
+    finishListenerRegistration?.();
+
+    await expect(search).rejects.toMatchObject({ name: 'AbortError' });
+    await Promise.resolve();
+    expect(invokeMock.mock.calls.some(([command]) => (
+      command === 'start_search_filenames_stream'
+    ))).toBe(false);
+  });
 });
diff --git a/src/web-ui/src/infrastructure/api/service-api/WorkspaceAPI.ts b/src/web-ui/src/infrastructure/api/service-api/WorkspaceAPI.ts
index aae362e6ed..815833886c 100644
--- a/src/web-ui/src/infrastructure/api/service-api/WorkspaceAPI.ts
+++ b/src/web-ui/src/infrastructure/api/service-api/WorkspaceAPI.ts
@@ -380,13 +380,19 @@ export class WorkspaceAPI {
   }
 
    
-  async getDirectoryChildren(path: string): Promise<ExplorerNodeDto[]> {
+  async getDirectoryChildren(
+    path: string,
+    remoteConnectionId?: string,
+  ): Promise<ExplorerNodeDto[]> {
     try {
       return await api.invoke('get_directory_children', { 
-        request: { path } 
+        request: { path, remoteConnectionId }
       });
     } catch (error) {
-      throw createTauriCommandError('get_directory_children', error, { path });
+      throw createTauriCommandError('get_directory_children', error, {
+        path,
+        remoteConnectionId,
+      });
     }
   }
 
@@ -541,7 +547,7 @@ export class WorkspaceAPI {
   }
 
   private supportsSearchStreamEvents(): boolean {
-    return typeof window !== 'undefined' && '__TAURI__' in window;
+    return api.getAdapter().supportsSearchStreamEvents?.() === true;
   }
 
   private async runSearchStream(
@@ -556,6 +562,7 @@ export class WorkspaceAPI {
       wholeWord: boolean;
       maxResults?: number;
       includeDirectories?: boolean;
+      remoteConnectionId?: string;
     },
     callbacks: FileSearchStreamCallbacks = {},
     signal?: AbortSignal
@@ -569,8 +576,6 @@ export class WorkspaceAPI {
       throw new DOMException(`${commandName} aborted`, 'AbortError');
     }
 
-    const { listen } = await import('@tauri-apps/api/event');
-
     return await new Promise<FileSearchCompleteEvent>((resolve, reject) => {
       let settled = false;
 
@@ -621,8 +626,7 @@ export class WorkspaceAPI {
       }
 
       void (async () => {
-        cleanupCallbacks.push(await listen<FileSearchProgressEvent>(FILE_SEARCH_PROGRESS_EVENT, (tauriEvent) => {
-          const event = tauriEvent.payload;
+        cleanupCallbacks.push(api.listen<FileSearchProgressEvent>(FILE_SEARCH_PROGRESS_EVENT, (event) => {
           if (event.searchId !== request.searchId || event.searchKind !== searchKind) {
             return;
           }
@@ -630,8 +634,7 @@ export class WorkspaceAPI {
           callbacks.onProgress?.(event);
         }));
 
-        cleanupCallbacks.push(await listen<FileSearchCompleteEvent>(FILE_SEARCH_COMPLETE_EVENT, (tauriEvent) => {
-          const event = tauriEvent.payload;
+        cleanupCallbacks.push(api.listen<FileSearchCompleteEvent>(FILE_SEARCH_COMPLETE_EVENT, (event) => {
           if (event.searchId !== request.searchId || event.searchKind !== searchKind) {
             return;
           }
@@ -639,8 +642,7 @@ export class WorkspaceAPI {
           settleResolve(event);
         }));
 
-        cleanupCallbacks.push(await listen<FileSearchErrorEvent>(FILE_SEARCH_ERROR_EVENT, (tauriEvent) => {
-          const event = tauriEvent.payload;
+        cleanupCallbacks.push(api.listen<FileSearchErrorEvent>(FILE_SEARCH_ERROR_EVENT, (event) => {
           if (event.searchId !== request.searchId || event.searchKind !== searchKind) {
             return;
           }
@@ -648,6 +650,10 @@ export class WorkspaceAPI {
           settleReject(new Error(event.error));
         }));
 
+        await api.waitForListenerRegistrations();
+        if (settled || signal?.aborted) {
+          return;
+        }
         await api.invoke<FileSearchStreamStartResponse>(commandName, { request });
       })().catch((error) => {
         settleReject(
@@ -719,7 +725,8 @@ export class WorkspaceAPI {
     searchIdOrSignal?: string | AbortSignal,
     maxResults?: number,
     includeDirectories: boolean = true,
-    signal?: AbortSignal
+    signal?: AbortSignal,
+    remoteConnectionId?: string,
   ): Promise<FileSearchResult[]> {
     const response = await this.searchFilenamesOnlyDetailed(
       rootPath,
@@ -730,7 +737,8 @@ export class WorkspaceAPI {
       searchIdOrSignal,
       maxResults,
       includeDirectories,
-      signal
+      signal,
+      remoteConnectionId,
     );
     return response.results;
   }
@@ -744,12 +752,17 @@ export class WorkspaceAPI {
     searchIdOrSignal?: string | AbortSignal,
     maxResults?: number,
     includeDirectories: boolean = true,
-    signal?: AbortSignal
+    signal?: AbortSignal,
+    remoteConnectionId?: string,
   ): Promise<FileSearchResponse> {
     const effectiveSignal = searchIdOrSignal instanceof AbortSignal ? searchIdOrSignal : signal;
     const effectiveSearchId =
       typeof searchIdOrSignal === 'string' ? searchIdOrSignal : this.createSearchId('filenames');
 
+    if (effectiveSignal?.aborted) {
+      throw new DOMException('search_filenames aborted', 'AbortError');
+    }
+
     try {
       const resultPromise = api.invoke<FileSearchResponse>('search_filenames', {
         request: {
@@ -761,6 +774,7 @@ export class WorkspaceAPI {
           wholeWord,
           maxResults,
           includeDirectories,
+          remoteConnectionId,
         }
       });
 
@@ -779,6 +793,7 @@ export class WorkspaceAPI {
         wholeWord,
         maxResults,
         includeDirectories,
+        remoteConnectionId,
       });
     }
   }
@@ -793,7 +808,8 @@ export class WorkspaceAPI {
     maxResults?: number,
     includeDirectories: boolean = true,
     callbacks: FileSearchStreamCallbacks = {},
-    signal?: AbortSignal
+    signal?: AbortSignal,
+    remoteConnectionId?: string,
   ): Promise<FileSearchCompleteEvent> {
     const effectiveSignal = searchIdOrSignal instanceof AbortSignal ? searchIdOrSignal : signal;
     const effectiveSearchId =
@@ -809,7 +825,8 @@ export class WorkspaceAPI {
         effectiveSearchId,
         maxResults,
         includeDirectories,
-        effectiveSignal
+        effectiveSignal,
+        remoteConnectionId,
       );
       const groupedResults = groupSearchResultsByFile(response.results);
       const event: FileSearchCompleteEvent = {
@@ -841,6 +858,7 @@ export class WorkspaceAPI {
         wholeWord,
         maxResults,
         includeDirectories,
+        remoteConnectionId,
       },
       callbacks,
       effectiveSignal
diff --git a/src/web-ui/src/infrastructure/api/service-api/tauri-commands.ts b/src/web-ui/src/infrastructure/api/service-api/tauri-commands.ts
index 368eef5b0b..f8c08cd48c 100644
--- a/src/web-ui/src/infrastructure/api/service-api/tauri-commands.ts
+++ b/src/web-ui/src/infrastructure/api/service-api/tauri-commands.ts
@@ -157,6 +157,7 @@ export interface SearchFilesRequest {
 export interface SearchFilenamesRequest {
   rootPath: string;
   pattern: string;
+  remoteConnectionId?: string;
   searchId?: string;
   caseSensitive?: boolean;
   useRegex?: boolean;
diff --git a/src/web-ui/src/infrastructure/api/service-api/types.ts b/src/web-ui/src/infrastructure/api/service-api/types.ts
index b8f7d1dfcc..3871a1fc58 100644
--- a/src/web-ui/src/infrastructure/api/service-api/types.ts
+++ b/src/web-ui/src/infrastructure/api/service-api/types.ts
@@ -71,6 +71,9 @@ export interface ApiRequest {
   config: TauriCommandConfig | HttpRequestConfig;
   timestamp: Date;
   retryCount: number;
+  /** Device activation that owns this request; set only for product invokes. */
+  surfaceId?: string;
+  surfaceEpoch?: number;
 }
 
 
diff --git a/src/web-ui/src/infrastructure/appearance/builtins/appearancePresetOutput.test.ts b/src/web-ui/src/infrastructure/appearance/builtins/appearancePresetOutput.test.ts
index e30a6be56d..ddf262f12d 100644
--- a/src/web-ui/src/infrastructure/appearance/builtins/appearancePresetOutput.test.ts
+++ b/src/web-ui/src/infrastructure/appearance/builtins/appearancePresetOutput.test.ts
@@ -149,42 +149,42 @@ describe('builtin appearance preset output', () => {
     }))).toMatchInlineSnapshot(`
       [
         {
-          "hash": "b70ab1232690e55f3446d84c5c5d4459c508c6cd5f1e0bfe8565eba82e97ea6e",
+          "hash": "954317380f5baa31e8b0155564c72606a76ff6fa6d8a190615120668a8e3d388",
           "id": "bitfun-light",
           "type": "light",
         },
         {
-          "hash": "6c426dc8aacd8095fdf5a69ed80b4d42c0235cf72f61b20186fc14d5ebcb320b",
+          "hash": "89abef6e2224b6fb86ac8bb34578c0d7ef725172ec1f29b29818038288b5dae0",
           "id": "bitfun-slate",
           "type": "dark",
         },
         {
-          "hash": "db937836a31fb02d67f6035f1b3a036b8161f3833fdbe2634f37936ba7ef6357",
+          "hash": "953efa0aa939f0080429972c3c0a7c46131523e106e8135cf543ec073d2e9d70",
           "id": "bitfun-dark",
           "type": "dark",
         },
         {
-          "hash": "e1455a17d5891da49f584ac1da6740a04db152afd6cdd571a9406f86811e6c8b",
+          "hash": "6b3d5817b0bf0568739ddfe2bbc5a7287d3db58761eda61379814f321195b7ed",
           "id": "bitfun-midnight",
           "type": "dark",
         },
         {
-          "hash": "7944cb574fd2b30cd4ed766e1b25e86eabd4c90b4a0e054489231a68de5cc424",
+          "hash": "e2dff5cddb2442779ca59ba92280cc3f01384a732c010f2e3dab8c399402e487",
           "id": "bitfun-china-style",
           "type": "light",
         },
         {
-          "hash": "f66e855842633612ca3aed2c30ff8df057dd0768eeb47e89e049efab8968f227",
+          "hash": "4fb76f4da97bd97213e5f9f1d35dc2e369cffb0d85a076541edbacbec1d85166",
           "id": "bitfun-china-night",
           "type": "dark",
         },
         {
-          "hash": "b72278893e14c1b0cef86449facf7ba61b4f714f077c3923241ebb012a90e3c8",
+          "hash": "a443ee9e0d5fd27e35aaf42fae2de7ba2ebd96841b9380794159ce2306c2c8c6",
           "id": "bitfun-cyber",
           "type": "dark",
         },
         {
-          "hash": "abcd6c91fdc1c03ea66d7d460401351620d672130e4742cce6a8be7f04b22626",
+          "hash": "e6b73a7c2569ffc251d0223f1bc57dc0c750b4ffbc9b1225ac8715b9a1f8fc5d",
           "id": "bitfun-tokyo-night",
           "type": "dark",
         },
diff --git a/src/web-ui/src/infrastructure/appearance/builtins/chinaNight.ts b/src/web-ui/src/infrastructure/appearance/builtins/chinaNight.ts
index 5e92c90f23..27b92cd172 100644
--- a/src/web-ui/src/infrastructure/appearance/builtins/chinaNight.ts
+++ b/src/web-ui/src/infrastructure/appearance/builtins/chinaNight.ts
@@ -123,13 +123,13 @@ export const bitfunChinaNightPalette: AppearancePalette = {
 
   motion: {
     duration: {
-      instant: '0.1s',
-      fast: '0.2s',
-      base: '0.35s',
-      slow: '0.7s',
+      instant: '0.08s',
+      fast: '0.14s',
+      base: '0.24s',
+      slow: '0.44s',
     },
 
-    easing: createStandardEasing('cubic-bezier(0.25, 0.1, 0.25, 1)'),
+    easing: createStandardEasing(),
   },
 
 
diff --git a/src/web-ui/src/infrastructure/appearance/builtins/chinaStyle.ts b/src/web-ui/src/infrastructure/appearance/builtins/chinaStyle.ts
index da3544f68b..1f41f0e6a8 100644
--- a/src/web-ui/src/infrastructure/appearance/builtins/chinaStyle.ts
+++ b/src/web-ui/src/infrastructure/appearance/builtins/chinaStyle.ts
@@ -125,13 +125,13 @@ export const bitfunChinaStylePalette: AppearancePalette = {
 
   motion: {
     duration: {
-      instant: '0.1s',
-      fast: '0.2s',
-      base: '0.35s',
-      slow: '0.7s',
+      instant: '0.08s',
+      fast: '0.14s',
+      base: '0.24s',
+      slow: '0.44s',
     },
 
-    easing: createStandardEasing('cubic-bezier(0.25, 0.1, 0.25, 1)'),
+    easing: createStandardEasing(),
   },
 
 
diff --git a/src/web-ui/src/infrastructure/appearance/builtins/cyber.ts b/src/web-ui/src/infrastructure/appearance/builtins/cyber.ts
index d15c66472c..4513eb4752 100644
--- a/src/web-ui/src/infrastructure/appearance/builtins/cyber.ts
+++ b/src/web-ui/src/infrastructure/appearance/builtins/cyber.ts
@@ -135,11 +135,11 @@ export const bitfunCyberPalette: AppearancePalette = {
     duration: {
       instant: '0.08s',
       fast: '0.12s',
-      base: '0.25s',
-      slow: '0.5s',
+      base: '0.2s',
+      slow: '0.4s',
     },
 
-    easing: createStandardEasing('cubic-bezier(0.25, 0.46, 0.45, 0.94)'),
+    easing: createStandardEasing(),
   },
 
 
@@ -202,4 +202,3 @@ export const bitfunCyberPalette: AppearancePalette = {
     },
   },
 };
-
diff --git a/src/web-ui/src/infrastructure/appearance/builtins/dark.ts b/src/web-ui/src/infrastructure/appearance/builtins/dark.ts
index 2275fbed0b..595fe8f74b 100644
--- a/src/web-ui/src/infrastructure/appearance/builtins/dark.ts
+++ b/src/web-ui/src/infrastructure/appearance/builtins/dark.ts
@@ -117,10 +117,10 @@ export const bitfunDarkPalette: AppearancePalette = {
 
   motion: {
     duration: {
-      instant: '0.1s',
-      fast: '0.15s',
-      base: '0.3s',
-      slow: '0.6s',
+      instant: '0.08s',
+      fast: '0.14s',
+      base: '0.22s',
+      slow: '0.42s',
     },
 
     easing: createStandardEasing(),
@@ -192,4 +192,3 @@ export const bitfunDarkPalette: AppearancePalette = {
 
 
 
-
diff --git a/src/web-ui/src/infrastructure/appearance/builtins/light.ts b/src/web-ui/src/infrastructure/appearance/builtins/light.ts
index 7ecb7f9571..85cbce51b2 100644
--- a/src/web-ui/src/infrastructure/appearance/builtins/light.ts
+++ b/src/web-ui/src/infrastructure/appearance/builtins/light.ts
@@ -159,10 +159,10 @@ export const bitfunLightPalette: AppearancePalette = {
 
   motion: {
     duration: {
-      instant: '0.1s',
-      fast: '0.15s',
-      base: '0.3s',
-      slow: '0.6s',
+      instant: '0.08s',
+      fast: '0.14s',
+      base: '0.22s',
+      slow: '0.42s',
     },
 
     easing: createStandardEasing(),
@@ -255,4 +255,3 @@ export const bitfunLightPalette: AppearancePalette = {
 
 
 
-
diff --git a/src/web-ui/src/infrastructure/appearance/builtins/midnight.ts b/src/web-ui/src/infrastructure/appearance/builtins/midnight.ts
index 6d2947fef2..154384a823 100644
--- a/src/web-ui/src/infrastructure/appearance/builtins/midnight.ts
+++ b/src/web-ui/src/infrastructure/appearance/builtins/midnight.ts
@@ -123,10 +123,10 @@ export const bitfunMidnightPalette: AppearancePalette = {
 
   motion: {
     duration: {
-      instant: '0.1s',
-      fast: '0.15s',
-      base: '0.3s',
-      slow: '0.6s',
+      instant: '0.08s',
+      fast: '0.14s',
+      base: '0.22s',
+      slow: '0.42s',
     },
 
     easing: createStandardEasing(),
diff --git a/src/web-ui/src/infrastructure/appearance/builtins/paletteHelpers.ts b/src/web-ui/src/infrastructure/appearance/builtins/paletteHelpers.ts
index b7d238c481..f2f1b7439b 100644
--- a/src/web-ui/src/infrastructure/appearance/builtins/paletteHelpers.ts
+++ b/src/web-ui/src/infrastructure/appearance/builtins/paletteHelpers.ts
@@ -251,10 +251,10 @@ export function createSlateRadius(): RadiusConfig {
   };
 }
 
-export function createStandardEasing(smooth = 'cubic-bezier(0.4, 0, 0.2, 1)'): AppearancePalette['motion']['easing'] {
+export function createStandardEasing(smooth = 'cubic-bezier(0.77, 0, 0.175, 1)'): AppearancePalette['motion']['easing'] {
   return {
-    standard: 'cubic-bezier(0.4, 0, 0.2, 1)',
-    decelerate: 'cubic-bezier(0, 0, 0.2, 1)',
+    standard: 'cubic-bezier(0.23, 1, 0.32, 1)',
+    decelerate: 'cubic-bezier(0.23, 1, 0.32, 1)',
     smooth,
   };
 }
diff --git a/src/web-ui/src/infrastructure/appearance/builtins/slate.ts b/src/web-ui/src/infrastructure/appearance/builtins/slate.ts
index 46b531be6f..c0e77b7b1f 100644
--- a/src/web-ui/src/infrastructure/appearance/builtins/slate.ts
+++ b/src/web-ui/src/infrastructure/appearance/builtins/slate.ts
@@ -139,8 +139,8 @@ export const bitfunSlatePalette: AppearancePalette = {
     duration: {
       instant: '0.08s',
       fast: '0.12s',
-      base: '0.25s',
-      slow: '0.5s',
+      base: '0.2s',
+      slow: '0.4s',
     },
 
     easing: createStandardEasing(),
diff --git a/src/web-ui/src/infrastructure/appearance/builtins/tokyoNight.ts b/src/web-ui/src/infrastructure/appearance/builtins/tokyoNight.ts
index 34c705205c..66e9386b52 100644
--- a/src/web-ui/src/infrastructure/appearance/builtins/tokyoNight.ts
+++ b/src/web-ui/src/infrastructure/appearance/builtins/tokyoNight.ts
@@ -146,11 +146,11 @@ export const bitfunTokyoNightPalette: AppearancePalette = {
     duration: {
       instant: '0.08s',
       fast: '0.12s',
-      base: '0.25s',
-      slow: '0.5s',
+      base: '0.2s',
+      slow: '0.4s',
     },
 
-    easing: createStandardEasing('cubic-bezier(0.25, 0.46, 0.45, 0.94)'),
+    easing: createStandardEasing(),
   },
 
   typography: createExpressiveTypography(),
diff --git a/src/web-ui/src/infrastructure/appearance/compiler/AppearanceCompiler.test.ts b/src/web-ui/src/infrastructure/appearance/compiler/AppearanceCompiler.test.ts
index 81473f57fb..5e621f5929 100644
--- a/src/web-ui/src/infrastructure/appearance/compiler/AppearanceCompiler.test.ts
+++ b/src/web-ui/src/infrastructure/appearance/compiler/AppearanceCompiler.test.ts
@@ -47,6 +47,17 @@ describe('AppearanceCompiler', () => {
     });
   });
 
+  it('keeps built-in UI motion within the responsive interaction budget', () => {
+    const seconds = (value: string) => Number.parseFloat(value.replace('s', ''));
+
+    builtinAppearancePalettes.forEach((palette) => {
+      expect(seconds(palette.motion.duration.fast)).toBeLessThanOrEqual(0.16);
+      expect(seconds(palette.motion.duration.base)).toBeLessThanOrEqual(0.24);
+      expect(seconds(palette.motion.duration.slow)).toBeLessThanOrEqual(0.45);
+      expect(palette.motion.easing.standard).toBe('cubic-bezier(0.23, 1, 0.32, 1)');
+    });
+  });
+
   it('calculates real contrast diagnostics for structured colors', () => {
     const pkg: AppearancePackage = {
       schema: 'bitfun.appearance',
diff --git a/src/web-ui/src/infrastructure/appearance/compiler/AppearanceCompiler.ts b/src/web-ui/src/infrastructure/appearance/compiler/AppearanceCompiler.ts
index de9d0eff03..97e1d85698 100644
--- a/src/web-ui/src/infrastructure/appearance/compiler/AppearanceCompiler.ts
+++ b/src/web-ui/src/infrastructure/appearance/compiler/AppearanceCompiler.ts
@@ -534,8 +534,8 @@ export class AppearanceCompiler {
     if (value.kind === 'ref') return this.referenceToVariable(value.path);
     const easings = {
       linear: 'linear',
-      standard: 'cubic-bezier(0.2, 0, 0, 1)',
-      decelerate: 'cubic-bezier(0, 0, 0, 1)',
+      standard: 'cubic-bezier(0.23, 1, 0.32, 1)',
+      decelerate: 'cubic-bezier(0.23, 1, 0.32, 1)',
       accelerate: 'cubic-bezier(0.3, 0, 1, 1)',
     } as const;
     return easings[value.value];
diff --git a/src/web-ui/src/infrastructure/appearance/registry/defaultAppearanceRegistry.ts b/src/web-ui/src/infrastructure/appearance/registry/defaultAppearanceRegistry.ts
index 9d12f1dceb..ca086a976e 100644
--- a/src/web-ui/src/infrastructure/appearance/registry/defaultAppearanceRegistry.ts
+++ b/src/web-ui/src/infrastructure/appearance/registry/defaultAppearanceRegistry.ts
@@ -30,6 +30,7 @@ import { textStrokeEffectAppearanceDescriptor } from '@/component-library/compon
 import { windowControlsAppearanceDescriptor } from '@/component-library/components/WindowControls/appearance';
 import { markdownAppearanceDescriptor } from '@/component-library/components/Markdown/appearance';
 import { flowChatCardAppearanceDescriptor } from '@/component-library/components/FlowChatCards/appearance';
+import { viewTransitionBoundaryAppearanceDescriptor } from '@/component-library/components/ViewTransitionBoundary/appearance';
 import { chatInputAppearanceDescriptor } from '@/flow_chat/components/ChatInput.appearance';
 import { composerVoiceInputAppearanceDescriptor } from '@/flow_chat/components/voice/ComposerVoiceInputButton.appearance';
 import { sessionUsagePanelAppearanceDescriptor } from '@/flow_chat/components/usage/appearance';
@@ -66,6 +67,7 @@ import { inlineDiffPreviewAppearanceDescriptor } from '@/flow_chat/components/In
 import { exportImageAppearanceDescriptor } from '@/flow_chat/components/modern/ExportImageButton.appearance';
 import { userMessageItemAppearanceDescriptor } from '@/flow_chat/components/modern/UserMessageItem.appearance';
 import { sessionUsageReportCardAppearanceDescriptor } from '@/flow_chat/components/usage/SessionUsageReportCard.appearance';
+import { sessionUsageModalAppearanceDescriptor } from '@/flow_chat/components/usage/SessionUsageModal.appearance';
 import { askUserQuestionCardAppearanceDescriptor } from '@/flow_chat/tool-cards/AskUserQuestionCard.appearance';
 import { createPlanDisplayAppearanceDescriptor } from '@/flow_chat/tool-cards/CreatePlanDisplay.appearance';
 import { execProcessToolCardAppearanceDescriptor } from '@/flow_chat/tool-cards/ExecProcessToolCardView.appearance';
@@ -120,6 +122,9 @@ import { filesPanelAppearanceDescriptor } from '@/app/components/panels/FilesPan
 import { reviewPlatformAppearanceDescriptor } from '@/app/components/panels/review-platform/appearance';
 import { remoteAccountPanelAppearanceDescriptor, remoteConnectDialogAppearanceDescriptor } from '@/app/components/RemoteConnectDialog/appearance';
 import { scheduledJobsViewAppearanceDescriptor } from '@/app/components/scheduled-jobs/appearance';
+import { localizedDateTimeFieldAppearanceDescriptor } from '@/app/components/scheduled-jobs/LocalizedDateTimeField.appearance';
+import { dateTimePickerAppearanceDescriptor } from '@/app/components/scheduled-jobs/DateTimePickerPopover.appearance';
+import { todosSceneAppearanceDescriptor } from '@/app/scenes/todos/appearance';
 import { flexiblePanelAppearanceDescriptor } from '@/app/components/panels/base/FlexiblePanel.appearance';
 import { btwSessionPanelAppearanceDescriptor } from '@/flow_chat/components/btw/BtwSessionPanel.appearance';
 import { modernFlowChatAppearanceDescriptor, virtualMessageListAppearanceDescriptor } from '@/flow_chat/components/modern/appearance';
@@ -227,7 +232,6 @@ import { reviewSessionSummaryCardAppearanceDescriptor } from '@/flow_chat/tool-c
 import { deepReviewConsentDialogAppearanceDescriptor } from '@/flow_chat/components/DeepReviewConsentDialog.appearance';
 import { flowTextBlockAppearanceDescriptor } from '@/flow_chat/components/FlowTextBlock.appearance';
 import { permissionRequestPanelAppearanceDescriptor } from '@/flow_chat/components/modern/PermissionRequestPanel.appearance';
-import { userMessageAppearanceDescriptor } from '@/flow_chat/components/UserMessage.appearance';
 import { toolCardAppearanceDescriptor } from '@/flow_chat/tool-cards/BaseToolCard.appearance';
 import { canvasToolCardAppearanceDescriptor } from '@/flow_chat/tool-cards/CanvasToolCard.appearance';
 import { computerUseToolCardAppearanceDescriptor } from '@/flow_chat/tool-cards/ComputerUseToolCard.appearance';
@@ -245,6 +249,7 @@ import { acpPermissionActionsAppearanceDescriptor } from '@/flow_chat/tool-cards
 import { contextCompressionDisplayAppearanceDescriptor } from '@/flow_chat/tool-cards/ContextCompressionDisplay.appearance';
 import { getToolSpecCardAppearanceDescriptor } from '@/flow_chat/tool-cards/GetToolSpecCard.appearance';
 import { viewImageToolCardAppearanceDescriptor } from '@/flow_chat/tool-cards/ViewImageToolCard.appearance';
+import { runCodeToolCardAppearanceDescriptor } from '@/flow_chat/tool-cards/RunCodeToolCard.appearance';
 import { acpPlanPanelAppearanceDescriptor } from '@/flow_chat/components/AcpPlanPanel.appearance';
 import { backgroundCommandInputDialogAppearanceDescriptor } from '@/flow_chat/components/background-command/BackgroundCommandInputDialog.appearance';
 import { chatEmptyStateAppearanceDescriptor } from '@/flow_chat/components/ChatEmptyState.appearance';
@@ -258,11 +263,7 @@ import { scrollToLatestBarAppearanceDescriptor } from '@/flow_chat/components/Sc
 import { scrollToTurnHeaderButtonAppearanceDescriptor } from '@/flow_chat/components/ScrollToTurnHeaderButton.appearance';
 import { tokenUsageIndicatorAppearanceDescriptor } from '@/flow_chat/components/TokenUsageIndicator.appearance';
 import { toolApprovalBarAppearanceDescriptor } from '@/flow_chat/components/ToolApprovalBar.appearance';
-import { snapshotRollbackButtonAppearanceDescriptor } from '@/flow_chat/components/SnapshotRollbackButton.appearance';
 import { smartRecommendationsAppearanceDescriptor } from '@/flow_chat/components/smart-recommendations/SmartRecommendations.appearance';
-import { stickyTaskIndicatorAppearanceDescriptor } from '@/flow_chat/components/StickyTaskIndicator.appearance';
-import { turnHistoryPanelAppearanceDescriptor } from '@/flow_chat/components/TurnHistoryPanel.appearance';
-import { turnRollbackButtonAppearanceDescriptor } from '@/flow_chat/components/TurnRollbackButton.appearance';
 import { sessionRuntimeStatusEntryAppearanceDescriptor } from '@/flow_chat/components/usage/SessionRuntimeStatusEntry.appearance';
 import { runtimeStatusSlotAppearanceDescriptor } from '@/flow_chat/components/modern/RuntimeStatusSlot.appearance';
 import { sessionMenuAppearanceDescriptor } from '@/flow_chat/components/session-menu/SessionMenu.appearance';
@@ -312,6 +313,7 @@ export function createDefaultAppearanceRegistry(): AppearanceRegistry {
     .registerComponent(windowControlsAppearanceDescriptor)
     .registerComponent(markdownAppearanceDescriptor)
     .registerComponent(flowChatCardAppearanceDescriptor)
+    .registerComponent(viewTransitionBoundaryAppearanceDescriptor)
     .registerComponent(chatInputAppearanceDescriptor)
     .registerComponent(composerVoiceInputAppearanceDescriptor)
     .registerComponent(sessionUsagePanelAppearanceDescriptor)
@@ -348,6 +350,7 @@ export function createDefaultAppearanceRegistry(): AppearanceRegistry {
     .registerComponent(exportImageAppearanceDescriptor)
     .registerComponent(userMessageItemAppearanceDescriptor)
     .registerComponent(sessionUsageReportCardAppearanceDescriptor)
+    .registerComponent(sessionUsageModalAppearanceDescriptor)
     .registerComponent(askUserQuestionCardAppearanceDescriptor)
     .registerComponent(createPlanDisplayAppearanceDescriptor)
     .registerComponent(execProcessToolCardAppearanceDescriptor)
@@ -412,6 +415,8 @@ export function createDefaultAppearanceRegistry(): AppearanceRegistry {
     .registerComponent(remoteConnectDialogAppearanceDescriptor)
     .registerComponent(remoteAccountPanelAppearanceDescriptor)
     .registerComponent(scheduledJobsViewAppearanceDescriptor)
+    .registerComponent(localizedDateTimeFieldAppearanceDescriptor)
+    .registerComponent(dateTimePickerAppearanceDescriptor)
     .registerComponent(flexiblePanelAppearanceDescriptor)
     .registerComponent(btwSessionPanelAppearanceDescriptor)
     .registerComponent(modernFlowChatAppearanceDescriptor)
@@ -488,7 +493,6 @@ export function createDefaultAppearanceRegistry(): AppearanceRegistry {
     .registerComponent(deepReviewConsentDialogAppearanceDescriptor)
     .registerComponent(flowTextBlockAppearanceDescriptor)
     .registerComponent(permissionRequestPanelAppearanceDescriptor)
-    .registerComponent(userMessageAppearanceDescriptor)
     .registerComponent(toolCardAppearanceDescriptor)
     .registerComponent(canvasToolCardAppearanceDescriptor)
     .registerComponent(computerUseToolCardAppearanceDescriptor)
@@ -506,6 +510,7 @@ export function createDefaultAppearanceRegistry(): AppearanceRegistry {
     .registerComponent(contextCompressionDisplayAppearanceDescriptor)
     .registerComponent(getToolSpecCardAppearanceDescriptor)
     .registerComponent(viewImageToolCardAppearanceDescriptor)
+    .registerComponent(runCodeToolCardAppearanceDescriptor)
     .registerComponent(acpPlanPanelAppearanceDescriptor)
     .registerComponent(backgroundCommandInputDialogAppearanceDescriptor)
     .registerComponent(chatEmptyStateAppearanceDescriptor)
@@ -519,11 +524,7 @@ export function createDefaultAppearanceRegistry(): AppearanceRegistry {
     .registerComponent(scrollToTurnHeaderButtonAppearanceDescriptor)
     .registerComponent(tokenUsageIndicatorAppearanceDescriptor)
     .registerComponent(toolApprovalBarAppearanceDescriptor)
-    .registerComponent(snapshotRollbackButtonAppearanceDescriptor)
     .registerComponent(smartRecommendationsAppearanceDescriptor)
-    .registerComponent(stickyTaskIndicatorAppearanceDescriptor)
-    .registerComponent(turnHistoryPanelAppearanceDescriptor)
-    .registerComponent(turnRollbackButtonAppearanceDescriptor)
     .registerComponent(sessionRuntimeStatusEntryAppearanceDescriptor)
     .registerComponent(runtimeStatusSlotAppearanceDescriptor)
     .registerComponent(sessionMenuAppearanceDescriptor)
@@ -553,6 +554,7 @@ export function createDefaultAppearanceRegistry(): AppearanceRegistry {
     .registerScene(settingsAppearanceDescriptor)
     .registerScene(skillsAppearanceDescriptor)
     .registerScene(terminalAppearanceDescriptor)
+    .registerScene(todosSceneAppearanceDescriptor)
     .registerRenderer(cssTokenAppearanceAdapter)
     .registerRenderer(monacoAppearanceAdapter)
     .registerRenderer(xtermAppearanceAdapter)
diff --git a/src/web-ui/src/infrastructure/config/components/AIFeaturesConfig.scss b/src/web-ui/src/infrastructure/config/components/AIFeaturesConfig.scss
index d83f700783..a617552fa7 100644
--- a/src/web-ui/src/infrastructure/config/components/AIFeaturesConfig.scss
+++ b/src/web-ui/src/infrastructure/config/components/AIFeaturesConfig.scss
@@ -15,61 +15,6 @@
     gap: $size-gap-2;
   }
 
-  &__label-with-tooltip {
-    display: inline-flex;
-    align-items: center;
-    gap: $size-gap-1;
-    min-width: 0;
-  }
-
-  &__label-tooltip-icon {
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
-    color: var(--bf-appearance-token-color-text-muted);
-    cursor: help;
-  }
-
-  &__label-tooltip-icon:hover {
-    color: var(--bf-appearance-token-color-text-secondary);
-  }
-
-  &__inline-label {
-    display: inline-flex;
-    align-items: center;
-    gap: $size-gap-1;
-    min-width: 0;
-  }
-
-  &__inline-info {
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
-    color: var(--bf-appearance-token-color-text-muted);
-    cursor: help;
-    flex-shrink: 0;
-  }
-
-  &__inline-info:hover {
-    color: var(--bf-appearance-token-color-text-secondary);
-  }
-
-  &__policy-tooltip {
-    max-width: min(320px, calc(100vw - 32px));
-    display: grid;
-    gap: 4px;
-    line-height: var(--bf-appearance-token-line-height-relaxed);
-  }
-
-  &__policy-tooltip strong {
-    color: var(--bf-appearance-token-color-text-primary);
-    font-weight: var(--bf-appearance-token-font-weight-medium);
-  }
-
-  &__policy-tooltip strong:not(:first-child) {
-    margin-top: 4px;
-  }
-
   /** Computer use: authorized status label (Granted / 已授权) */
   &__perm-status--granted {
     color: var(--bf-appearance-token-color-text-muted);
diff --git a/src/web-ui/src/infrastructure/config/components/AIModelConfig.scss b/src/web-ui/src/infrastructure/config/components/AIModelConfig.scss
index b3af969b14..6f9c7be620 100644
--- a/src/web-ui/src/infrastructure/config/components/AIModelConfig.scss
+++ b/src/web-ui/src/infrastructure/config/components/AIModelConfig.scss
@@ -489,7 +489,11 @@
     background: transparent;
     border: 1px solid var(--bf-appearance-token-border-base);
     border-radius: var(--bf-appearance-token-size-radius-sm);
-    transition: all var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard);
+    transition:
+      background-color var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+      border-color var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+      box-shadow var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+      color var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard);
     min-height: 36px;
 
     
@@ -719,7 +723,12 @@
     border: none;
     background: var(--bf-appearance-token-element-bg-subtle);
     color: var(--bf-appearance-token-color-text-muted);
-    transition: all $motion-base $easing-standard;
+    transition:
+      background-color $motion-base $easing-standard,
+      border-color $motion-base $easing-standard,
+      color $motion-base $easing-standard,
+      opacity $motion-base $easing-standard,
+      transform $motion-base $easing-standard;
 
     
     &:hover {
@@ -1040,7 +1049,12 @@
       color: var(--bf-appearance-token-color-text-primary);
       font-size: var(--bf-appearance-token-font-size-sm);
       font-family: $font-family-sans;
-      transition: all var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard);
+      transition:
+        background-color var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+        border-color var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+        box-shadow var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+        color var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+        opacity var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard);
       min-height: 36px;
 
       
@@ -1651,7 +1665,10 @@
     background: transparent;
     border-radius: var(--bf-appearance-token-size-radius-sm);
     border: 1px solid var(--bf-appearance-token-border-base);
-    transition: all var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard);
+    transition:
+      background-color var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+      border-color var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard),
+      box-shadow var(--bf-appearance-token-motion-base) var(--bf-appearance-token-easing-standard);
 
     &:hover {
       background: var(--bf-appearance-token-element-bg-subtle);
@@ -1787,10 +1804,10 @@
 
   
   .spinning {
-    animation: spin 1s linear infinite;
+    animation: bitfun-ai-model-config-spin 1s linear infinite;
   }
 
-  @keyframes spin {
+  @keyframes bitfun-ai-model-config-spin {
     to {
       transform: rotate(360deg);
     }
@@ -1951,7 +1968,11 @@
 
   &__custom-option {
     cursor: pointer;
-    transition: all $motion-base $easing-standard;
+    transition:
+      background-color $motion-base $easing-standard,
+      border-color $motion-base $easing-standard,
+      box-shadow $motion-base $easing-standard,
+      color $motion-base $easing-standard;
     border: 1px dashed var(--bf-appearance-token-border-base);
 
     &:hover {
@@ -2439,3 +2460,10 @@
     }
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .bitfun-ai-model-config .spinning {
+    animation: none;
+    transform: none;
+  }
+}
diff --git a/src/web-ui/src/infrastructure/config/components/AIModelConfig.tsx b/src/web-ui/src/infrastructure/config/components/AIModelConfig.tsx
index a69305a44b..7ef95a0f2e 100644
--- a/src/web-ui/src/infrastructure/config/components/AIModelConfig.tsx
+++ b/src/web-ui/src/infrastructure/config/components/AIModelConfig.tsx
@@ -3098,6 +3098,15 @@ const AIModelConfig: React.FC = () => {
     )
     ? resolveDraftCatalogEntry(reasoningPanelDraft)?.reasoning
     : undefined;
+  const reasoningPanelProjectionRequest = reasoningPanelDraft && editingConfig
+    ? {
+        provider: editingConfig.provider || 'openai',
+        modelName: reasoningPanelDraft.modelName,
+        baseUrl: editingConfig.base_url || '',
+        contextWindow: reasoningPanelDraft.contextWindow,
+        maxTokens: reasoningPanelDraft.maxTokens,
+      }
+    : undefined;
   const modelsDevSourceLabel = modelsDevStatus
     ? t(`modelsDevCatalog.source.${modelsDevStatus.active_source}`)
     : t('modelsDevCatalog.loading');
@@ -3737,6 +3746,11 @@ const AIModelConfig: React.FC = () => {
             value={reasoningPanelDraft.reasoning}
             generatedProjection={reasoningPanelProjection}
             modelsDevReasoningCatalog={modelCatalog?.models_dev_reasoning_catalog}
+            projectionRequest={reasoningPanelProjectionRequest}
+            requestFormatLabel={reasoningPanelProjectionRequest
+              ? requestFormatLabelMap[reasoningPanelProjectionRequest.provider]
+                || reasoningPanelProjectionRequest.provider
+              : undefined}
             onCancel={() => setReasoningPanelDraftKey(null)}
             onApply={(reasoning) => {
               updateModelDraft(reasoningPanelDraft.modelName, {
diff --git a/src/web-ui/src/infrastructure/config/components/AcpAgentsConfig.scss b/src/web-ui/src/infrastructure/config/components/AcpAgentsConfig.scss
index 0822e72688..d4e01f2b66 100644
--- a/src/web-ui/src/infrastructure/config/components/AcpAgentsConfig.scss
+++ b/src/web-ui/src/infrastructure/config/components/AcpAgentsConfig.scss
@@ -377,3 +377,10 @@
     transform: rotate(360deg);
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .bitfun-acp-agents__status.is-checking svg {
+    animation: none;
+    transform: none;
+  }
+}
diff --git a/src/web-ui/src/infrastructure/config/components/AcpAgentsConfig.test.tsx b/src/web-ui/src/infrastructure/config/components/AcpAgentsConfig.test.tsx
index 64bb96d2e4..9bbc7318f7 100644
--- a/src/web-ui/src/infrastructure/config/components/AcpAgentsConfig.test.tsx
+++ b/src/web-ui/src/infrastructure/config/components/AcpAgentsConfig.test.tsx
@@ -548,6 +548,88 @@ describe('AcpAgentsConfig', () => {
     expect(notifySuccessMock).toHaveBeenCalledWith('notifications.configAddedManualCliRequired');
   });
 
+  it('offers the one-click installer for DeepSeek Harness and launches the bundled profile', async () => {
+    probeClientRequirementsMock.mockResolvedValue([
+      {
+        id: 'dsh',
+        tool: { name: 'dsh', installed: false },
+        runnable: false,
+        notes: ['dsh is not available on PATH'],
+      },
+    ]);
+
+    await act(async () => {
+      root.render(<AcpAgentsConfig />);
+    });
+    await act(async () => {
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    expect(container.textContent).toContain('DeepSeek Harness');
+    // Unlike omp, the harness is a plain npm global, so BitFun installs it.
+    // The bridge is not a separate adapter — it ships inside BitFun.
+    expect(container.textContent).not.toContain('registry.adapterMissing');
+
+    const installButtons = Array.from(container.querySelectorAll('button'))
+      .filter(button => button.textContent?.includes('actions.installCli'));
+    expect(installButtons.length).toBeGreaterThan(0);
+
+    await act(async () => {
+      installButtons[0].click();
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    expect(installClientCliMock).toHaveBeenCalledWith(
+      expect.objectContaining({ clientId: 'dsh' }),
+    );
+  });
+
+  it('adds DeepSeek Harness as a launch of the profile BitFun materializes', async () => {
+    probeClientRequirementsMock.mockResolvedValue([
+      {
+        id: 'dsh',
+        tool: { name: 'dsh', installed: true, version: '0.1.0-rc.6' },
+        runnable: true,
+        notes: [],
+      },
+    ]);
+
+    await act(async () => {
+      root.render(<AcpAgentsConfig />);
+    });
+    await act(async () => {
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    // Address the harness row by name: row order is whatever the saved config
+    // and the preset list happen to produce, so "the last add button" belongs
+    // to some other agent as often as not.
+    const harnessRow = Array.from(
+      container.querySelectorAll('.bitfun-acp-agents__registry-row'),
+    ).find(row => row.querySelector('.bitfun-acp-agents__registry-name')
+      ?.textContent === 'DeepSeek Harness');
+    expect(harnessRow).toBeTruthy();
+
+    const addButton = Array.from(harnessRow!.querySelectorAll('button'))
+      .find(button => button.textContent?.includes('actions.add'));
+    expect(addButton).toBeTruthy();
+
+    await act(async () => {
+      addButton!.click();
+      await Promise.resolve();
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    // The command has to name the profile BitFun materializes; a bare `dsh`
+    // would drop the user into the harness's own default composition, which
+    // does not speak ACP at all.
+    expect(saveJsonConfigMock).toHaveBeenCalledWith(expect.stringContaining('bitfun-acp'));
+  });
+
   it('does not downgrade enabled agents on transient probe timeouts during refresh', async () => {
     probeClientRequirementsMock
       .mockResolvedValueOnce([
diff --git a/src/web-ui/src/infrastructure/config/components/AcpAgentsConfig.tsx b/src/web-ui/src/infrastructure/config/components/AcpAgentsConfig.tsx
index 6f291eed76..7c78c0fd64 100644
--- a/src/web-ui/src/infrastructure/config/components/AcpAgentsConfig.tsx
+++ b/src/web-ui/src/infrastructure/config/components/AcpAgentsConfig.tsx
@@ -90,7 +90,7 @@ interface AcpClientPreset {
 
 // Presets that speak ACP natively and therefore need no separate adapter
 // package (their CLI binary is launched directly).
-const NATIVE_ACP_PRESET_IDS = new Set(['opencode', 'omp']);
+const NATIVE_ACP_PRESET_IDS = new Set(['opencode', 'dsh', 'omp']);
 
 // Presets BitFun cannot install on the user's behalf — the agent must be
 // installed manually (e.g. omp targets bun and ships via its own installer).
@@ -105,6 +105,16 @@ const PRESETS: AcpClientPreset[] = [
     command: 'opencode',
     args: ['acp'],
   },
+  // BitFun ships the ACP bridge for DeepSeek Harness and installs it into the
+  // user's own dsh as a profile on first launch, so the only setup left is the
+  // harness itself and the model the user picks inside it.
+  {
+    id: 'dsh',
+    name: 'DeepSeek Harness',
+    description: 'DeepSeek Harness with BitFun\'s bundled ACP bridge. Uses the model and API key configured in dsh.',
+    command: 'dsh',
+    args: ['--profile', 'bitfun-acp'],
+  },
   {
     id: 'omp',
     name: 'Oh My Pi',
diff --git a/src/web-ui/src/infrastructure/config/components/ConfigForm.scss b/src/web-ui/src/infrastructure/config/components/ConfigForm.scss
index 1622e21a06..ba28b07616 100644
--- a/src/web-ui/src/infrastructure/config/components/ConfigForm.scss
+++ b/src/web-ui/src/infrastructure/config/components/ConfigForm.scss
@@ -583,9 +583,57 @@ $config-input-height: 32px;
 
 .config-form-section-title {
   @extend .bitfun-config-form__section-title;
+  width: fit-content;
+  padding: 0;
+  border: 0;
+  background: transparent;
+  text-align: left;
+  cursor: pointer;
+  user-select: none;
+
+  &:disabled {
+    cursor: default;
+    opacity: 1;
+  }
+}
+
+.config-form-section-chevron {
+  margin-left: 8px;
+  color: var(--bf-appearance-token-color-text-muted);
+  font-size: 14px;
+  transition: transform 150ms var(--bf-appearance-token-easing-standard);
+}
+
+.config-form-section-title[aria-expanded='false'] .config-form-section-chevron {
+  transform: rotate(-90deg);
+}
+
+.config-form-section-collapse {
+  display: grid;
+  grid-template-rows: 0fr;
+  opacity: 0;
+  transition:
+    grid-template-rows 180ms var(--bf-appearance-token-easing-standard),
+    opacity 120ms ease;
+
+  &[data-open='true'] {
+    grid-template-rows: 1fr;
+    opacity: 1;
+  }
+
+  > .config-form {
+    min-height: 0;
+    overflow: hidden;
+  }
 }
 
 .config-form-section-description {
   @extend .bitfun-config-form__section-description;
 }
 
+@media (prefers-reduced-motion: reduce) {
+  .config-form-section-collapse,
+  .config-form-section-chevron {
+    transition: none;
+  }
+}
diff --git a/src/web-ui/src/infrastructure/config/components/DebugConfig.scss b/src/web-ui/src/infrastructure/config/components/DebugConfig.scss
index 41383db509..6bac4129e9 100644
--- a/src/web-ui/src/infrastructure/config/components/DebugConfig.scss
+++ b/src/web-ui/src/infrastructure/config/components/DebugConfig.scss
@@ -47,7 +47,12 @@
     box-shadow: none;
     background: transparent;
     color: var(--bf-appearance-token-color-text-muted);
-    transition: all 0.2s ease;
+    transition:
+      background-color 0.2s ease,
+      border-color 0.2s ease,
+      color 0.2s ease,
+      opacity 0.2s ease,
+      transform 0.2s ease;
 
     svg {
       width: 12px !important;
diff --git a/src/web-ui/src/infrastructure/config/components/ExternalMcpOverview.appearance.ts b/src/web-ui/src/infrastructure/config/components/ExternalMcpOverview.appearance.ts
index e404e1a9f9..b6810b3ce1 100644
--- a/src/web-ui/src/infrastructure/config/components/ExternalMcpOverview.appearance.ts
+++ b/src/web-ui/src/infrastructure/config/components/ExternalMcpOverview.appearance.ts
@@ -12,5 +12,6 @@ export const externalMcpOverviewAppearanceDescriptor: AppearanceSurfaceDescripto
     { id: 'pending', selector: { kind: 'self', suffix: '[data-bf-state~="pending"]' } },
     { id: 'error', selector: { kind: 'self', suffix: '[data-bf-state~="error"]' } },
     { id: 'muted', selector: { kind: 'self', suffix: '[data-bf-state~="muted"]' } },
+    { id: 'stale', selector: { kind: 'self', suffix: '[data-bf-state~="stale"]' } },
   ],
 };
diff --git a/src/web-ui/src/infrastructure/config/components/ExternalMcpOverview.test.tsx b/src/web-ui/src/infrastructure/config/components/ExternalMcpOverview.test.tsx
index dcf7b23e17..866a1ed09e 100644
--- a/src/web-ui/src/infrastructure/config/components/ExternalMcpOverview.test.tsx
+++ b/src/web-ui/src/infrastructure/config/components/ExternalMcpOverview.test.tsx
@@ -705,7 +705,7 @@ describe('ExternalMcpOverview', () => {
     }
   });
 
-  it('surfaces stale source health ahead of a misleading active status', async () => {
+  it('shows a neutral stale badge when an active server uses the last working content', async () => {
     getSnapshotMock.mockResolvedValue({
       ...snapshot,
       sources: [{
@@ -724,8 +724,10 @@ describe('ExternalMcpOverview', () => {
       await Promise.resolve();
     });
 
-    expect(container.textContent).toContain('external.status.stale');
-    expect(container.textContent).toContain('external.status.active');
+    const stale = container.querySelector('[data-bf-state="stale"]');
+    expect(stale?.textContent).toContain('external.status.stale');
+    expect(stale?.classList.contains('is-error')).toBe(false);
+    expect(stale?.classList.contains('is-pending')).toBe(false);
   });
 
   it('surfaces degraded source diagnostics ahead of a misleading active status', async () => {
@@ -736,7 +738,11 @@ describe('ExternalMcpOverview', () => {
         record: {
           ...snapshot.sources[0].record,
           health: 'degraded',
-          diagnostics: [{ severity: 'warning', code: 'source_stale', message: 'details' }],
+          diagnostics: [{
+            severity: 'warning',
+            code: 'source_stale',
+            message: 'sensitive source diagnostic',
+          }],
         },
       }],
       mcpServers: snapshot.mcpServers,
@@ -750,7 +756,7 @@ describe('ExternalMcpOverview', () => {
 
     expect(container.textContent).toContain('external.status.degraded');
     expect(container.textContent).toContain('external.status.approvalRequired');
-    expect(container.textContent).not.toContain('details');
+    expect(container.textContent).not.toContain('sensitive source diagnostic');
   });
 
   it('summarizes top-level MCP diagnostics without exposing their raw message', async () => {
diff --git a/src/web-ui/src/infrastructure/config/components/ExternalMcpOverview.tsx b/src/web-ui/src/infrastructure/config/components/ExternalMcpOverview.tsx
index 02cbeb7c95..527a7db74b 100644
--- a/src/web-ui/src/infrastructure/config/components/ExternalMcpOverview.tsx
+++ b/src/web-ui/src/infrastructure/config/components/ExternalMcpOverview.tsx
@@ -383,7 +383,7 @@ const ExternalMcpOverview: React.FC = () => {
           {scopeLabel(sourceRecord?.scope)}
         </span>
         {sourceStatus ? (
-          <span className={`bitfun-mcp-tools__status-badge ${sourceStatus === 'stale' ? 'is-pending' : 'is-error'}`} data-bf-component="external-mcp-overview" data-bf-part="statusBadge" data-bf-state={sourceStatus === 'stale' ? 'pending' : 'error'}>
+          <span className={`bitfun-mcp-tools__status-badge ${sourceStatus === 'degraded' ? 'is-error' : ''}`} data-bf-component="external-mcp-overview" data-bf-part="statusBadge" data-bf-state={sourceStatus === 'degraded' ? 'error' : 'stale'}>
             {t(`external.status.${sourceStatus}`)}
           </span>
         ) : null}
diff --git a/src/web-ui/src/infrastructure/config/components/ExternalSourcesConfig.scss b/src/web-ui/src/infrastructure/config/components/ExternalSourcesConfig.scss
index a42f0550c0..2c581ae805 100644
--- a/src/web-ui/src/infrastructure/config/components/ExternalSourcesConfig.scss
+++ b/src/web-ui/src/infrastructure/config/components/ExternalSourcesConfig.scss
@@ -569,7 +569,6 @@
     color: var(--bf-appearance-token-color-text-secondary);
     font-size: 12px;
 
-    &.is-using_last_valid_version,
     &.is-restricted,
     &.is-degraded,
     &.is-unavailable,
diff --git a/src/web-ui/src/infrastructure/config/components/ExternalSourcesConfig.test.tsx b/src/web-ui/src/infrastructure/config/components/ExternalSourcesConfig.test.tsx
index 4514f39678..349f406454 100644
--- a/src/web-ui/src/infrastructure/config/components/ExternalSourcesConfig.test.tsx
+++ b/src/web-ui/src/infrastructure/config/components/ExternalSourcesConfig.test.tsx
@@ -13,11 +13,14 @@ const setSourceEnabledMock = vi.hoisted(() => vi.fn());
 const setSafeModeMock = vi.hoisted(() => vi.fn());
 const setConflictChoiceMock = vi.hoisted(() => vi.fn());
 const setToolTargetDecisionMock = vi.hoisted(() => vi.fn());
+const setToolTargetsEnabledMock = vi.hoisted(() => vi.fn());
 const setToolConflictChoiceMock = vi.hoisted(() => vi.fn());
 const setSubagentActivationMock = vi.hoisted(() => vi.fn());
+const setSubagentsEnabledMock = vi.hoisted(() => vi.fn());
 const setSubagentModelBindingMock = vi.hoisted(() => vi.fn());
 const chooseSubagentConflictMock = vi.hoisted(() => vi.fn());
 const setMcpServerDecisionMock = vi.hoisted(() => vi.fn());
+const setMcpServersEnabledMock = vi.hoisted(() => vi.fn());
 const chooseMcpConflictMock = vi.hoisted(() => vi.fn());
 const updateIntegrationPolicyMock = vi.hoisted(() => vi.fn());
 const revealSourceLocationMock = vi.hoisted(() => vi.fn());
@@ -75,11 +78,14 @@ vi.mock('@/infrastructure/api/service-api/ExternalSourcesAPI', () => ({
     setSafeMode: setSafeModeMock,
     setConflictChoice: setConflictChoiceMock,
     setToolTargetDecision: setToolTargetDecisionMock,
+    setToolTargetsEnabled: setToolTargetsEnabledMock,
     setToolConflictChoice: setToolConflictChoiceMock,
     setSubagentActivation: setSubagentActivationMock,
+    setSubagentsEnabled: setSubagentsEnabledMock,
     setSubagentModelBinding: setSubagentModelBindingMock,
     chooseSubagentConflict: chooseSubagentConflictMock,
     setMcpServerDecision: setMcpServerDecisionMock,
+    setMcpServersEnabled: setMcpServersEnabledMock,
     chooseMcpConflict: chooseMcpConflictMock,
     updateIntegrationPolicy: updateIntegrationPolicyMock,
     revealSourceLocation: revealSourceLocationMock,
@@ -262,11 +268,14 @@ describe('ExternalSourcesConfig', () => {
       }],
     });
     setToolTargetDecisionMock.mockResolvedValue(snapshot);
+    setToolTargetsEnabledMock.mockResolvedValue(snapshot);
     setToolConflictChoiceMock.mockResolvedValue(snapshot);
     setSubagentActivationMock.mockResolvedValue(snapshot);
+    setSubagentsEnabledMock.mockResolvedValue(snapshot);
     setSubagentModelBindingMock.mockResolvedValue(snapshot);
     chooseSubagentConflictMock.mockResolvedValue(snapshot);
     setMcpServerDecisionMock.mockResolvedValue(snapshot);
+    setMcpServersEnabledMock.mockResolvedValue(snapshot);
     chooseMcpConflictMock.mockResolvedValue(snapshot);
     updateIntegrationPolicyMock.mockResolvedValue(snapshot);
     revealSourceLocationMock.mockResolvedValue(undefined);
@@ -1234,6 +1243,7 @@ describe('ExternalSourcesConfig', () => {
         selectedCandidateId: 'native-mcp-github',
       }],
     });
+    setMcpServersEnabledMock.mockResolvedValue(mcpSnapshot);
 
     await act(async () => {
       root.render(<ExternalSourcesConfig />);
@@ -1252,6 +1262,19 @@ describe('ExternalSourcesConfig', () => {
     expect(container.textContent).toContain('mcp.timeoutCatalog');
     expect(container.textContent).toContain('mcp.timeoutExecution');
 
+    const mcpBulkEnable = container.querySelector<HTMLButtonElement>(
+      '[data-bf-bulk-capability="mcp"] button',
+    );
+    await act(async () => mcpBulkEnable?.click());
+    expect(setMcpServersEnabledMock).toHaveBeenCalledWith(
+      'D:/workspace/project',
+      [{ candidateId: 'external-mcp-github', decisionKey: 'mcp-decision-v1' },
+        { candidateId: 'external-mcp-docs', decisionKey: 'mcp-decision-v2' }],
+      true,
+      5,
+      9,
+    );
+
     const approvalCard = Array.from(container.querySelectorAll(
       '.bitfun-external-sources-config__tool-card',
     )).find((candidate) => (
@@ -1332,6 +1355,74 @@ describe('ExternalSourcesConfig', () => {
     );
   });
 
+  it('keeps polling through a transient read failure and beyond the old startup limit', async () => {
+    const server = {
+      candidateId: 'external-mcp-docs',
+      decisionKey: 'mcp-decision-v1',
+      definition: {
+        id: {
+          source: { providerId: 'opencode.mcp', sourceId: 'project' },
+          localId: 'docs',
+        },
+        provenance: [{ providerId: 'opencode.mcp', sourceId: 'project' }],
+        name: 'docs',
+        transport: 'local_stdio',
+        commandPreview: 'missing-docs-command',
+        argumentCount: 0,
+        environmentKeys: [],
+        environmentReferenceNames: [],
+        headerNames: [],
+        sourceEnabled: true,
+        behaviorVersion: 'behavior-v1',
+        staticStatus: { state: 'ready' },
+      },
+      activationState: { state: 'starting' },
+    };
+    const startingSnapshot = {
+      ...snapshot,
+      commandConflicts: [],
+      preferenceRevision: 3,
+      mcpGeneration: 4,
+      mcpServers: [server],
+      mcpApprovalRequests: [],
+      mcpConflicts: [],
+    };
+    let acceptedPolls = 0;
+    getSnapshotMock
+      .mockResolvedValueOnce(startingSnapshot)
+      .mockRejectedValueOnce(new Error('temporary snapshot read failure'))
+      .mockImplementation(async () => {
+        acceptedPolls += 1;
+        if (acceptedPolls <= 11) return startingSnapshot;
+        return {
+        ...startingSnapshot,
+        mcpServers: [{
+          ...server,
+          activationState: {
+            state: 'runtime_unavailable',
+            reason: 'provider.internal D:/private/config.json',
+          },
+        }],
+        };
+      });
+
+    await act(async () => {
+      root.render(<ExternalSourcesConfig />);
+      await Promise.resolve();
+    });
+    expect(container.textContent).toContain('mcpState.starting');
+
+    await act(async () => vi.advanceTimersByTimeAsync(55_250));
+
+    expect(getSnapshotMock).toHaveBeenCalledTimes(14);
+    expect(container.textContent).toContain('mcp.failureReasons.other');
+    expect(container.textContent).not.toContain('D:/private/config.json');
+    const details = Array.from(container.querySelectorAll('button')).find((button) =>
+      button.textContent?.includes('common.details'));
+    await act(async () => details?.click());
+    expect(container.textContent).toContain('mcp.runtimeUnavailableGuidance');
+  });
+
   it('keeps remembered command, tool, and agent choices visible and changeable', async () => {
     const resolvedSnapshot = {
       ...snapshot,
@@ -1850,8 +1941,10 @@ describe('ExternalSourcesConfig', () => {
       pendingSubagentApprovals: [],
     };
     getSnapshotMock
+      .mockResolvedValueOnce(agentSnapshot)
       .mockResolvedValueOnce(agentSnapshot)
       .mockResolvedValue(activatedAgentSnapshot);
+    setSubagentsEnabledMock.mockResolvedValue(agentSnapshot);
     setSubagentActivationMock.mockResolvedValue(activatedAgentSnapshot);
     chooseSubagentConflictMock.mockResolvedValue({
       ...agentSnapshot,
@@ -1866,6 +1959,18 @@ describe('ExternalSourcesConfig', () => {
       await Promise.resolve();
     });
 
+    const agentBulkEnable = container.querySelector<HTMLButtonElement>(
+      '[data-bf-bulk-capability="subagent"] button',
+    );
+    await act(async () => agentBulkEnable?.click());
+    expect(setSubagentsEnabledMock).toHaveBeenCalledWith(
+      'D:/workspace/project',
+      [{ candidateId: 'external-agent-review-v1', decisionKey: 'agent-decision-v1' }],
+      true,
+      4,
+      7,
+    );
+
     const details = Array.from(container.querySelectorAll('button')).find((button) =>
       button.textContent?.includes('common.details'));
     await act(async () => details?.click());
@@ -2257,6 +2362,7 @@ describe('ExternalSourcesConfig', () => {
       ...approvalSnapshot,
       toolApprovalRequests: [],
     });
+    setToolTargetsEnabledMock.mockResolvedValue(approvalSnapshot);
 
     await act(async () => {
       root.render(<ExternalSourcesConfig />);
@@ -2271,6 +2377,17 @@ describe('ExternalSourcesConfig', () => {
     expect(container.textContent).toContain('toolApprovals.workingDirectory');
     expect(container.textContent).toContain('capability.file_system');
     expect(container.textContent).toContain('capability.environment');
+    const toolBulkEnable = container.querySelector<HTMLButtonElement>(
+      '[data-bf-bulk-capability="tool"] button',
+    );
+    await act(async () => toolBulkEnable?.click());
+    expect(setToolTargetsEnabledMock).toHaveBeenCalledWith(
+      'D:/workspace/project',
+      [{ approvalKey: 'approval-1', decisionKey: 'decision-1' }],
+      true,
+      1,
+      0,
+    );
     const enable = Array.from(container.querySelectorAll('button')).find((button) =>
       button.textContent?.includes('toolApprovals.enable'));
     enable?.focus();
diff --git a/src/web-ui/src/infrastructure/config/components/ExternalSourcesConfig.tsx b/src/web-ui/src/infrastructure/config/components/ExternalSourcesConfig.tsx
index 250ff624b7..d33af297b4 100644
--- a/src/web-ui/src/infrastructure/config/components/ExternalSourcesConfig.tsx
+++ b/src/web-ui/src/infrastructure/config/components/ExternalSourcesConfig.tsx
@@ -26,6 +26,7 @@ import { i18nService } from '@/infrastructure/i18n';
 import { usePeerDeviceModeOptional } from '@/infrastructure/peer-device/peerDeviceContextState';
 import { WorkspaceKind } from '@/shared/types';
 import { createLogger } from '@/shared/utils/logger';
+import { getMotionAwareScrollBehavior } from '@/shared/utils/motionPreference';
 
 const logger = createLogger('ExternalSourcesConfig');
 import {
@@ -63,6 +64,7 @@ import {
   ExternalCommandConflicts,
   ExternalSourceSection,
   buildExternalApplicationsView,
+  sourceDiagnosticCategory,
   type ExternalApplicationView,
 } from './external-sources';
 import './ExternalSourcesConfig.scss';
@@ -189,29 +191,29 @@ function agentDiagnosticParams(
     : undefined;
 }
 
-function sourceDiagnosticCategory(code: string): string {
-  if (code.includes('preference_read_failed')) return 'confirmationStateUnavailable';
-  if (code.includes('conflict_history_write_failed')) return 'conflictHistoryUnavailable';
-  if (code.includes('discovery_in_progress')) return 'checkInProgress';
-  if (code.includes('timeout')) return 'checkTimedOut';
-  if (code.includes('trust_required')) return 'confirmationRequired';
-  if (code.includes('too_large') || code.includes('file_limit') || code.includes('bytes_limit')) {
-    return 'sourceTooLarge';
-  }
-  if (code.includes('invalid') || code.includes('parse') || code.includes('definition')
-    || code.includes('export_missing') || code.includes('name_unsupported')) {
-    return 'invalidSettings';
-  }
-  if (code.includes('unreadable') || code.includes('read_failed')
-    || code.includes('metadata_failed') || code.includes('directory_')) {
-    return 'unreadableSource';
-  }
-  if (code.includes('projection_only') || code.includes('unsupported')
-    || code.includes('restricted')) {
-    return 'notSupported';
-  }
-  if (code.includes('failed')) return 'checkFailed';
-  return 'sourceIssue';
+const MCP_START_FAILURE_TRANSLATIONS: Record<string, string> = {
+  'external_mcp.start.authentication': 'mcp.failureReasons.authentication',
+  'external_mcp.start.timeout': 'mcp.failureReasons.timeout',
+  'external_mcp.start.command_unavailable': 'mcp.failureReasons.commandUnavailable',
+  'external_mcp.start.working_directory_unavailable': 'mcp.failureReasons.workingDirectoryUnavailable',
+  'external_mcp.start.connection_failed': 'mcp.failureReasons.connectionFailed',
+  'external_mcp.start.protocol_failed': 'mcp.failureReasons.protocolFailed',
+  'external_mcp.start.other': 'mcp.failureReasons.other',
+  'external_mcp.native_configuration_unavailable': 'mcp.failureReasons.nativeConfigurationUnavailable',
+  'external_mcp.runtime.host_read_only': 'mcp.failureReasons.hostReadOnly',
+  'external_mcp.runtime.configuration_changed': 'mcp.failureReasons.configurationChanged',
+  'external_mcp.runtime.configuration_invalid': 'mcp.failureReasons.configurationInvalid',
+  'external_mcp.runtime.host_unavailable': 'mcp.failureReasons.hostUnavailable',
+  'external_mcp.runtime.install_failed': 'mcp.failureReasons.installFailed',
+  'external_mcp.runtime.preparation_failed': 'mcp.failureReasons.preparationFailed',
+  'external_mcp.runtime.server_missing': 'mcp.failureReasons.serverMissing',
+  'external_mcp.runtime.failed': 'mcp.failureReasons.runtimeFailed',
+  'external_mcp.runtime.stopped': 'mcp.failureReasons.stopped',
+  'external_mcp.runtime.status_unavailable': 'mcp.failureReasons.statusUnavailable',
+};
+
+function localizedMcpFailureReason(reason: string, t: TFunction): string {
+  return t(MCP_START_FAILURE_TRANSLATIONS[reason] ?? 'mcp.failureReasons.other');
 }
 
 function sourceScopeLabel(scope: string, t: TFunction): string {
@@ -640,6 +642,40 @@ const ExternalSourcesConfig: React.FC<ExternalSourcesConfigProps> = ({
     };
   }, [loadSnapshot, snapshot?.discoveryPending]);
 
+  const startingMcpSignature = (snapshot?.mcpServers ?? [])
+    .filter((server) => server.activationState.state === 'starting')
+    .map((server) => server.candidateId)
+    .sort()
+    .join('\u001f');
+
+  useEffect(() => {
+    if (!startingMcpSignature) return undefined;
+    let cancelled = false;
+    let timer: number | undefined;
+    let attempt = 0;
+    const schedulePoll = () => {
+      const delay = DISCOVERY_POLL_DELAYS_MS[
+        Math.min(attempt, DISCOVERY_POLL_DELAYS_MS.length - 1)
+      ];
+      timer = window.setTimeout(async () => {
+        const result = await loadSnapshot(false, false);
+        if (cancelled) return;
+        const finished = result.status === 'accepted'
+          && !(result.snapshot?.mcpServers ?? []).some(
+            (server) => server.activationState.state === 'starting',
+          );
+        if (finished) return;
+        attempt += 1;
+        schedulePoll();
+      }, delay);
+    };
+    schedulePoll();
+    return () => {
+      cancelled = true;
+      if (timer !== undefined) window.clearTimeout(timer);
+    };
+  }, [loadSnapshot, startingMcpSignature]);
+
   const sourceGroups = useMemo(
     () => snapshot ? buildExternalSourcePresentationGroups(snapshot) : [],
     [snapshot],
@@ -1008,6 +1044,83 @@ const ExternalSourcesConfig: React.FC<ExternalSourcesConfigProps> = ({
     return accepted;
   }, [loadSnapshot, runMutation, snapshot, t, workspacePath]);
 
+  const setToolTargetsEnabled = useCallback(async (enabled: boolean) => {
+    const current = snapshotRef.current;
+    if (!current) return;
+    const decisions = enabled
+      ? (current.toolApprovalRequests ?? []).map((request) => ({
+          approvalKey: request.approvalKey,
+          decisionKey: request.decisionKey,
+        }))
+      : Array.from(new Map((current.tools ?? []).map((tool) => [
+          tool.approvalKey,
+          { approvalKey: tool.approvalKey, decisionKey: tool.decisionKey },
+        ])).values());
+    await runMutation(
+      'bulk-tools',
+      () => externalSourcesAPI.setToolTargetsEnabled(
+        workspacePath,
+        decisions,
+        enabled,
+        current.generation,
+        current.preferenceRevision ?? 0,
+      ),
+      true,
+      'all',
+      t(enabled ? 'bulkActions.enabled' : 'bulkActions.disabled'),
+      'canApproveRuntime',
+    );
+  }, [runMutation, t, workspacePath]);
+
+  const setSubagentsEnabled = useCallback(async (enabled: boolean) => {
+    const current = snapshotRef.current;
+    if (!current) return;
+    const decisions = (current.subagents ?? [])
+      .filter((agent) => !enabled || agent.activationState.state === 'approval_required')
+      .map((agent) => ({ candidateId: agent.candidateId, decisionKey: agent.decisionKey }));
+    const accepted = await runMutation(
+      'bulk-subagents',
+      () => externalSourcesAPI.setSubagentsEnabled(
+        workspacePath,
+        decisions,
+        enabled,
+        current.subagentGeneration ?? 0,
+        current.preferenceRevision ?? 0,
+      ),
+      true,
+      'subagents',
+      t(enabled ? 'bulkActions.enabled' : 'bulkActions.disabled'),
+      'canApproveRuntime',
+    );
+    if (accepted) await loadSnapshot(true, false);
+  }, [loadSnapshot, runMutation, t, workspacePath]);
+
+  const setMcpServersEnabled = useCallback(async (enabled: boolean) => {
+    const current = snapshotRef.current;
+    if (!current) return;
+    const decisions = (enabled
+      ? current.mcpApprovalRequests ?? []
+      : current.mcpServers ?? []).map((server) => ({
+        candidateId: server.candidateId,
+        decisionKey: server.decisionKey,
+      }));
+    const accepted = await runMutation(
+      'bulk-mcp',
+      () => externalSourcesAPI.setMcpServersEnabled(
+        workspacePath,
+        decisions,
+        enabled,
+        current.mcpGeneration ?? 0,
+        current.preferenceRevision ?? 0,
+      ),
+      true,
+      'all',
+      t(enabled ? 'bulkActions.enabled' : 'bulkActions.disabled'),
+      'canApproveRuntime',
+    );
+    if (accepted) await loadSnapshot(true, false);
+  }, [loadSnapshot, runMutation, t, workspacePath]);
+
   const isRemote = workspace?.workspaceKind === WorkspaceKind.Remote
     || Boolean(workspace?.connectionId);
   const policy = snapshot?.integrationPolicy;
@@ -1191,7 +1304,10 @@ const ExternalSourcesConfig: React.FC<ExternalSourcesConfigProps> = ({
         ) ?? matchingEcosystemElements[0]
       : document.querySelector<HTMLElement>('[data-external-attention="true"]');
     if (!target) return;
-    target.scrollIntoView({ block: 'center', behavior: 'smooth' });
+    target.scrollIntoView({
+      block: 'center',
+      behavior: getMotionAwareScrollBehavior('smooth'),
+    });
     if (target instanceof HTMLDetailsElement) {
       target.open = true;
       target.querySelector<HTMLElement>('summary')?.focus();
@@ -1217,7 +1333,10 @@ const ExternalSourcesConfig: React.FC<ExternalSourcesConfigProps> = ({
     window.requestAnimationFrame(() => {
       const policyCard = document.querySelector<HTMLElement>('[data-bf-part="policyCard"]');
       if (!policyCard) return;
-      policyCard.scrollIntoView({ block: 'center', behavior: 'smooth' });
+      policyCard.scrollIntoView({
+        block: 'center',
+        behavior: getMotionAwareScrollBehavior('smooth'),
+      });
       policyCard.querySelector<HTMLInputElement>('input[type="checkbox"]')?.focus();
     });
   }, []);
@@ -2247,12 +2366,35 @@ const ExternalSourcesConfig: React.FC<ExternalSourcesConfigProps> = ({
             ) : null}
 
             {(snapshot?.mcpServers?.length ?? 0) > 0 ? (
-              <ConfigPageSection title={t('mcp.title')}>
+              <ConfigPageSection
+                title={t('mcp.title')}
+                extra={(
+                  <div className="bitfun-external-sources-config__tool-actions" data-bf-bulk-capability="mcp">
+                    {(snapshot?.mcpApprovalRequests?.length ?? 0) > 0 ? (
+                      <Button variant="primary" size="small" aria-describedby="external-mcp-bulk-risk" disabled={!policyCompatible || busyKey !== null || !hostCapabilities.canApproveRuntime} onClick={() => void setMcpServersEnabled(true)}>
+                        {t('bulkActions.enablePending', { count: snapshot?.mcpApprovalRequests?.length ?? 0 })}
+                      </Button>
+                    ) : null}
+                    <Button variant="secondary" size="small" disabled={!policyCompatible || busyKey !== null || !hostCapabilities.canApproveRuntime} onClick={() => void setMcpServersEnabled(false)}>
+                      {t('bulkActions.disableAll')}
+                    </Button>
+                  </div>
+                )}
+              >
+                {(snapshot?.mcpApprovalRequests?.length ?? 0) > 0 ? (
+                  <div id="external-mcp-bulk-risk" className="bitfun-external-sources-config__tool-warning">
+                    {t('bulkActions.enableRisk', { count: snapshot?.mcpApprovalRequests?.length ?? 0 })}
+                  </div>
+                ) : null}
                 {snapshot?.mcpServers?.map((server) => {
                   const state = server.activationState.state;
                   const reviewing = reviewingMcpKey === server.candidateId;
                   const canEnable = state === 'declined' || state === 'configuration_changed';
                   const canDisable = ['starting', 'active', 'runtime_unavailable'].includes(state);
+                  const runtimeFailureReason = state === 'runtime_unavailable'
+                    && 'reason' in server.activationState
+                    ? localizedMcpFailureReason(server.activationState.reason, t)
+                    : undefined;
                   const source = snapshot.sources.find((candidate) => (
                     candidate.record.key.providerId === server.definition.id.source.providerId
                     && candidate.record.key.sourceId === server.definition.id.source.sourceId
@@ -2261,7 +2403,11 @@ const ExternalSourcesConfig: React.FC<ExternalSourcesConfigProps> = ({
                     <React.Fragment key={server.candidateId}>
                       <ConfigPageRow
                         label={server.definition.name}
-                        description={`${t(`mcp.transport.${server.definition.transport}`)} · ${t('mcp.externalSource')}`}
+                        description={[
+                          t(`mcp.transport.${server.definition.transport}`),
+                          t('mcp.externalSource'),
+                          runtimeFailureReason,
+                        ].filter(Boolean).join(' · ')}
                         align="center"
                       >
                         <div className="bitfun-external-sources-config__source-control" data-bf-component="external-sources-config" data-bf-part="sourceControl">
@@ -2309,7 +2455,7 @@ const ExternalSourcesConfig: React.FC<ExternalSourcesConfigProps> = ({
                             })}</span>
                             {source ? (
                               <>
-                                <span>{t('mcp.sourceLocation')}: {renderPathLink(
+                                <span>{t('mcp.sourceLocationLabel')}: {renderPathLink(
                                   source.record.location,
                                   source.stableKey,
                                 )}</span>
@@ -2339,9 +2485,17 @@ const ExternalSourcesConfig: React.FC<ExternalSourcesConfigProps> = ({
                               })}</span>
                             ) : null}
                             {'reason' in server.activationState ? (
-                              <span>{t(server.activationState.state === 'runtime_unavailable'
-                                ? 'mcp.runtimeUnavailableGuidance'
-                                : 'mcp.unsupportedGuidance')}</span>
+                              <>
+                                <span>{t('mcp.failureReason', {
+                                  reason: localizedMcpFailureReason(
+                                    server.activationState.reason,
+                                    t,
+                                  ),
+                                })}</span>
+                                <span>{t(server.activationState.state === 'runtime_unavailable'
+                                  ? 'mcp.runtimeUnavailableGuidance'
+                                  : 'mcp.unsupportedGuidance')}</span>
+                              </>
                             ) : null}
                             <span>{t('mcp.changePolicy')}</span>
                           </div>
@@ -2661,7 +2815,26 @@ const ExternalSourcesConfig: React.FC<ExternalSourcesConfigProps> = ({
             ) : null}
 
             {(snapshot?.subagents?.length ?? 0) > 0 ? (
-              <ConfigPageSection title={t('agents.title')}>
+              <ConfigPageSection
+                title={t('agents.title')}
+                extra={(
+                  <div className="bitfun-external-sources-config__tool-actions" data-bf-bulk-capability="subagent">
+                    {(snapshot?.pendingSubagentApprovals?.length ?? 0) > 0 ? (
+                      <Button variant="primary" size="small" aria-describedby="external-subagent-bulk-risk" disabled={!policyCompatible || busyKey !== null || !hostCapabilities.canApproveRuntime} onClick={() => void setSubagentsEnabled(true)}>
+                        {t('bulkActions.enablePending', { count: snapshot?.pendingSubagentApprovals?.length ?? 0 })}
+                      </Button>
+                    ) : null}
+                    <Button variant="secondary" size="small" disabled={!policyCompatible || busyKey !== null || !hostCapabilities.canApproveRuntime} onClick={() => void setSubagentsEnabled(false)}>
+                      {t('bulkActions.disableAll')}
+                    </Button>
+                  </div>
+                )}
+              >
+                {(snapshot?.pendingSubagentApprovals?.length ?? 0) > 0 ? (
+                  <div id="external-subagent-bulk-risk" className="bitfun-external-sources-config__tool-warning">
+                    {t('bulkActions.enableRisk', { count: snapshot?.pendingSubagentApprovals?.length ?? 0 })}
+                  </div>
+                ) : null}
                 {snapshot?.subagents?.map((agent) => {
                   const reviewing = reviewingAgentKey === agent.candidateId;
                   const state = agent.activationState.state;
@@ -3075,7 +3248,26 @@ const ExternalSourcesConfig: React.FC<ExternalSourcesConfigProps> = ({
             />
 
             {(snapshot?.tools?.length ?? 0) > 0 ? (
-              <ConfigPageSection title={t('tools.title')}>
+              <ConfigPageSection
+                title={t('tools.title')}
+                extra={(
+                  <div className="bitfun-external-sources-config__tool-actions" data-bf-bulk-capability="tool">
+                    {(snapshot?.toolApprovalRequests?.length ?? 0) > 0 ? (
+                      <Button variant="primary" size="small" aria-describedby="external-tool-bulk-risk" disabled={!policyCompatible || busyKey !== null || !hostCapabilities.canApproveRuntime} onClick={() => void setToolTargetsEnabled(true)}>
+                        {t('bulkActions.enablePending', { count: snapshot?.toolApprovalRequests?.length ?? 0 })}
+                      </Button>
+                    ) : null}
+                    <Button variant="secondary" size="small" disabled={!policyCompatible || busyKey !== null || !hostCapabilities.canApproveRuntime} onClick={() => void setToolTargetsEnabled(false)}>
+                      {t('bulkActions.disableAll')}
+                    </Button>
+                  </div>
+                )}
+              >
+                {(snapshot?.toolApprovalRequests?.length ?? 0) > 0 ? (
+                  <div id="external-tool-bulk-risk" className="bitfun-external-sources-config__tool-warning">
+                    {t('bulkActions.enableRisk', { count: snapshot?.toolApprovalRequests?.length ?? 0 })}
+                  </div>
+                ) : null}
                 {snapshot?.tools?.map((tool) => {
                   const toolKey = `${tool.definition.id.target.source.providerId}:${tool.definition.id.target.source.sourceId}:${tool.definition.id.target.localId}:${tool.definition.id.exportId}`;
                   const source = snapshot.sources.find((candidate) => matchesToolSource(candidate, tool));
diff --git a/src/web-ui/src/infrastructure/config/components/GlobalPermissionRulesDialog.scss b/src/web-ui/src/infrastructure/config/components/GlobalPermissionRulesDialog.scss
index e09ff8cdeb..4c40e8674d 100644
--- a/src/web-ui/src/infrastructure/config/components/GlobalPermissionRulesDialog.scss
+++ b/src/web-ui/src/infrastructure/config/components/GlobalPermissionRulesDialog.scss
@@ -81,10 +81,22 @@
 
   &__rule-row {
     padding-block: 10px;
+    opacity: 1;
+    transform: translateY(0);
+    transition:
+      opacity 100ms ease-out,
+      transform 120ms cubic-bezier(0.22, 1, 0.36, 1);
 
     + .global-permission-rules-dialog__rule-row {
       border-top: 1px solid var(--bf-appearance-token-border-subtle);
     }
+
+    &[data-exiting='true'] {
+      opacity: 0;
+      transform: translateY(-4px);
+      pointer-events: none;
+      will-change: opacity, transform;
+    }
   }
 
   &__rule-actions {
@@ -137,3 +149,13 @@
     }
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .global-permission-rules-dialog__rule-row {
+    transition: opacity 60ms linear;
+
+    &[data-exiting='true'] {
+      transform: none;
+    }
+  }
+}
diff --git a/src/web-ui/src/infrastructure/config/components/GlobalPermissionRulesDialog.test.tsx b/src/web-ui/src/infrastructure/config/components/GlobalPermissionRulesDialog.test.tsx
index 68a4bfca0e..7efc07b390 100644
--- a/src/web-ui/src/infrastructure/config/components/GlobalPermissionRulesDialog.test.tsx
+++ b/src/web-ui/src/infrastructure/config/components/GlobalPermissionRulesDialog.test.tsx
@@ -81,8 +81,51 @@ vi.mock('@/component-library', () => ({
 describe('GlobalPermissionRulesDialog', () => {
   let container: HTMLDivElement;
   let root: Root;
+  let animateMock: ReturnType<typeof vi.fn>;
+
+  const mockReducedMotion = (matches: boolean) => {
+    vi.stubGlobal('matchMedia', vi.fn(() => ({
+      matches,
+      media: '(prefers-reduced-motion: reduce)',
+      onchange: null,
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    })));
+  };
+
+  const renderDialog = async (
+    rules: Array<{ action: string; resource: string; effect: 'allow' | 'ask' | 'deny' }>,
+    overrides: Partial<React.ComponentProps<typeof GlobalPermissionRulesDialog>> = {},
+  ) => {
+    await act(async () => {
+      root.render(
+        <GlobalPermissionRulesDialog
+          isOpen
+          rules={rules}
+          isSaving={false}
+          onSave={vi.fn(() => Promise.resolve(true))}
+          onClose={vi.fn()}
+          {...overrides}
+        />,
+      );
+    });
+  };
 
   beforeEach(() => {
+    mockReducedMotion(false);
+    animateMock = vi.fn(() => ({
+      cancel: vi.fn(),
+      onfinish: null,
+      oncancel: null,
+    }) as unknown as Animation);
+    Object.defineProperty(HTMLElement.prototype, 'animate', {
+      configurable: true,
+      writable: true,
+      value: animateMock,
+    });
     container = document.createElement('div');
     document.body.appendChild(container);
     root = createRoot(container);
@@ -91,6 +134,9 @@ describe('GlobalPermissionRulesDialog', () => {
   afterEach(() => {
     act(() => root.unmount());
     container.remove();
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+    delete (HTMLElement.prototype as Partial<HTMLElement>).animate;
   });
 
   it('edits and saves ordered global permission rules', async () => {
@@ -134,17 +180,215 @@ describe('GlobalPermissionRulesDialog', () => {
   });
 
   it('adds an editable rule and prevents saving it until complete', async () => {
+    await renderDialog([]);
+
+    const addButton = [...container.querySelectorAll('button')].find(
+      (button) => button.textContent?.includes('Add rule'),
+    );
+    await act(async () => {
+      addButton?.click();
+    });
+
+    expect(container.querySelectorAll('.global-permission-rules-dialog__rule-row')).toHaveLength(1);
+    const saveButton = [...container.querySelectorAll('button')].find(
+      (button) => button.textContent?.includes('Save rules'),
+    );
+    expect(saveButton?.disabled).toBe(true);
+
+    expect(animateMock).toHaveBeenCalledTimes(1);
+    expect(animateMock.mock.calls[0]?.[0]).toEqual([
+      { opacity: 0, transform: 'translateY(4px)' },
+      { opacity: 1, transform: 'translateY(0)' },
+    ]);
+    expect(animateMock.mock.calls[0]?.[1]).toMatchObject({ duration: 150 });
+  });
+
+  it('reorders rows immediately and bridges their changed positions with FLIP', async () => {
+    await renderDialog([
+      { action: 'read', resource: '/first', effect: 'allow' },
+      { action: 'git', resource: '/second', effect: 'ask' },
+    ]);
+
+    const rows = [...container.querySelectorAll<HTMLDivElement>(
+      '.global-permission-rules-dialog__rule-row',
+    )];
+    rows.forEach((row) => {
+      vi.spyOn(row, 'getBoundingClientRect').mockImplementation(() => {
+        const currentRows = [...container.querySelectorAll(
+          '.global-permission-rules-dialog__rule-row',
+        )];
+        const index = currentRows.indexOf(row);
+        return {
+          x: 0,
+          y: index * 40,
+          top: index * 40,
+          right: 400,
+          bottom: (index * 40) + 32,
+          left: 0,
+          width: 400,
+          height: 32,
+          toJSON: () => ({}),
+        };
+      });
+    });
+
+    const firstMoveDown = container.querySelectorAll<HTMLButtonElement>(
+      'button[aria-label="Move rule down"]',
+    )[0];
+    await act(async () => {
+      firstMoveDown.click();
+    });
+
+    expect([...container.querySelectorAll<HTMLSelectElement>('select[aria-label="Action"]')]
+      .map((select) => select.value)).toEqual(['git', 'read']);
+    expect(animateMock).toHaveBeenCalledTimes(2);
+    expect(animateMock.mock.calls.every((call) => (
+      (call[1] as KeyframeAnimationOptions).duration === 160
+    ))).toBe(true);
+    expect(animateMock.mock.calls.map((call) => call[0])).toEqual(expect.arrayContaining([
+      [
+        { transform: 'translate(0px, -40px)' },
+        { transform: 'translate(0, 0)' },
+      ],
+      [
+        { transform: 'translate(0px, 40px)' },
+        { transform: 'translate(0, 0)' },
+      ],
+    ]));
+
+    const firstAnimations = animateMock.mock.results.map(
+      (result) => result.value as Animation & { cancel: ReturnType<typeof vi.fn> },
+    );
+    const originalRuleMoveUp = container.querySelectorAll<HTMLButtonElement>(
+      'button[aria-label="Move rule up"]',
+    )[1];
+    await act(async () => {
+      originalRuleMoveUp.click();
+    });
+
+    expect(firstAnimations.every((animation) => animation.cancel.mock.calls.length === 1)).toBe(true);
+    expect([...container.querySelectorAll<HTMLSelectElement>('select[aria-label="Action"]')]
+      .map((select) => select.value)).toEqual(['read', 'git']);
+  });
+
+  it('retains a removed row for its exit but saves the intended live rules', async () => {
+    vi.useFakeTimers();
+    const onSave = vi.fn(() => Promise.resolve(true));
+    await renderDialog([
+      { action: 'read', resource: '/remove', effect: 'allow' },
+      { action: 'git', resource: '/keep', effect: 'ask' },
+    ], { onSave });
+
+    const firstRemove = container.querySelectorAll<HTMLButtonElement>(
+      'button[aria-label="Remove rule"]',
+    )[0];
+    await act(async () => {
+      firstRemove.focus();
+      firstRemove.click();
+    });
+
+    const exitingRow = container.querySelector<HTMLDivElement>(
+      '.global-permission-rules-dialog__rule-row[data-exiting="true"]',
+    );
+    expect(container.querySelectorAll('.global-permission-rules-dialog__rule-row')).toHaveLength(2);
+    expect(exitingRow?.getAttribute('aria-hidden')).toBe('true');
+    expect(exitingRow?.hasAttribute('inert')).toBe(true);
+    expect(exitingRow?.querySelector('input')?.disabled).toBe(true);
+    expect(document.activeElement).not.toBe(firstRemove);
+
+    const saveButton = [...container.querySelectorAll('button')].find(
+      (button) => button.textContent?.includes('Save rules'),
+    );
+    await act(async () => {
+      saveButton?.click();
+      await Promise.resolve();
+    });
+    expect(onSave).toHaveBeenCalledWith([
+      { action: 'git', resource: '/keep', effect: 'ask' },
+    ]);
+
+    await act(async () => {
+      vi.advanceTimersByTime(119);
+    });
+    expect(container.querySelectorAll('.global-permission-rules-dialog__rule-row')).toHaveLength(2);
+    await act(async () => {
+      vi.advanceTimersByTime(1);
+    });
+    expect(container.querySelectorAll('.global-permission-rules-dialog__rule-row')).toHaveLength(1);
+    expect(container.querySelector<HTMLSelectElement>('select[aria-label="Action"]')?.value).toBe('git');
+  });
+
+  it('cancels an old removal when the dialog closes and opens with new rules', async () => {
+    vi.useFakeTimers();
+    const commonProps = {
+      isSaving: false,
+      onSave: vi.fn(() => Promise.resolve(true)),
+      onClose: vi.fn(),
+    };
+    await renderDialog([
+      { action: 'read', resource: '/old', effect: 'allow' },
+    ], commonProps);
+
+    await act(async () => {
+      container.querySelector<HTMLButtonElement>('button[aria-label="Remove rule"]')?.click();
+    });
     await act(async () => {
       root.render(
         <GlobalPermissionRulesDialog
+          {...commonProps}
+          isOpen={false}
+          rules={[{ action: 'read', resource: '/old', effect: 'allow' }]}
+        />,
+      );
+    });
+    await act(async () => {
+      root.render(
+        <GlobalPermissionRulesDialog
+          {...commonProps}
           isOpen
-          rules={[]}
-          isSaving={false}
-          onSave={vi.fn(() => Promise.resolve(true))}
-          onClose={vi.fn()}
+          rules={[{ action: 'git', resource: '/new', effect: 'deny' }]}
         />,
       );
     });
+    await act(async () => {
+      vi.advanceTimersByTime(200);
+    });
+
+    expect(container.querySelectorAll('.global-permission-rules-dialog__rule-row')).toHaveLength(1);
+    expect(container.querySelector<HTMLSelectElement>('select[aria-label="Action"]')?.value).toBe('git');
+    expect(container.querySelector<HTMLInputElement>('input[aria-label="Resource"]')?.value).toBe('/new');
+  });
+
+  it('handles rapid removals without reviving or skipping a rule', async () => {
+    vi.useFakeTimers();
+    await renderDialog([
+      { action: 'read', resource: '/first', effect: 'allow' },
+      { action: 'git', resource: '/second', effect: 'ask' },
+      { action: 'bash', resource: '/keep', effect: 'deny' },
+    ]);
+
+    const removeButtons = container.querySelectorAll<HTMLButtonElement>(
+      'button[aria-label="Remove rule"]',
+    );
+    await act(async () => {
+      removeButtons[0].click();
+      removeButtons[1].click();
+    });
+    expect(container.querySelectorAll(
+      '.global-permission-rules-dialog__rule-row[data-exiting="true"]',
+    )).toHaveLength(2);
+
+    await act(async () => {
+      vi.advanceTimersByTime(120);
+    });
+    expect(container.querySelectorAll('.global-permission-rules-dialog__rule-row')).toHaveLength(1);
+    expect(container.querySelector<HTMLSelectElement>('select[aria-label="Action"]')?.value).toBe('bash');
+  });
+
+  it('uses opacity-only short feedback when reduced motion is requested', async () => {
+    vi.useFakeTimers();
+    mockReducedMotion(true);
+    await renderDialog([]);
 
     const addButton = [...container.querySelectorAll('button')].find(
       (button) => button.textContent?.includes('Add rule'),
@@ -153,10 +397,18 @@ describe('GlobalPermissionRulesDialog', () => {
       addButton?.click();
     });
 
+    expect(animateMock).toHaveBeenCalledTimes(1);
+    expect(animateMock.mock.calls[0]?.[0]).toEqual([{ opacity: 0 }, { opacity: 1 }]);
+    expect(animateMock.mock.calls[0]?.[1]).toMatchObject({ duration: 70 });
+
+    await act(async () => {
+      container.querySelector<HTMLButtonElement>('button[aria-label="Remove rule"]')?.click();
+      vi.advanceTimersByTime(59);
+    });
     expect(container.querySelectorAll('.global-permission-rules-dialog__rule-row')).toHaveLength(1);
-    const saveButton = [...container.querySelectorAll('button')].find(
-      (button) => button.textContent?.includes('Save rules'),
-    );
-    expect(saveButton?.disabled).toBe(true);
+    await act(async () => {
+      vi.advanceTimersByTime(1);
+    });
+    expect(container.querySelectorAll('.global-permission-rules-dialog__rule-row')).toHaveLength(0);
   });
 });
diff --git a/src/web-ui/src/infrastructure/config/components/GlobalPermissionRulesDialog.tsx b/src/web-ui/src/infrastructure/config/components/GlobalPermissionRulesDialog.tsx
index ae627bdce6..b3f4b2b9f3 100644
--- a/src/web-ui/src/infrastructure/config/components/GlobalPermissionRulesDialog.tsx
+++ b/src/web-ui/src/infrastructure/config/components/GlobalPermissionRulesDialog.tsx
@@ -1,4 +1,11 @@
-import React, { useEffect, useMemo, useState } from 'react';
+import React, {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
 import { ArrowDown, ArrowUp, Plus, Save, ShieldCheck, Trash2 } from 'lucide-react';
 import { useTranslation } from 'react-i18next';
 import { Button, IconButton, Input, Modal, Select, type SelectOption } from '@/component-library';
@@ -22,6 +29,13 @@ const GLOBAL_PERMISSION_ACTION_OPTIONS: SelectOption[] = [
 ];
 
 const EFFECTS: PermissionEffect[] = ['allow', 'ask', 'deny'];
+const RULE_EXIT_DURATION_MS = 120;
+const REDUCED_MOTION_RULE_EXIT_DURATION_MS = 60;
+const RULE_MOVE_DURATION_MS = 160;
+const RULE_ENTER_DURATION_MS = 150;
+const REDUCED_MOTION_ENTER_DURATION_MS = 70;
+const RULE_MOTION_EASING = 'cubic-bezier(0.22, 1, 0.36, 1)';
+const MIN_RULE_SHIFT_PX = 0.5;
 
 interface DraftRule extends PermissionRule {
   localId: string;
@@ -53,6 +67,10 @@ function rulesEqual(left: PermissionRule[], right: PermissionRule[]): boolean {
   });
 }
 
+function prefersReducedMotion(): boolean {
+  return globalThis.matchMedia?.('(prefers-reduced-motion: reduce)').matches ?? false;
+}
+
 export const GlobalPermissionRulesDialog: React.FC<GlobalPermissionRulesDialogProps> = ({
   isOpen,
   rules,
@@ -63,6 +81,15 @@ export const GlobalPermissionRulesDialog: React.FC<GlobalPermissionRulesDialogPr
   const { t } = useTranslation('settings/session-config');
   const [savedRules, setSavedRules] = useState<PermissionRule[]>([]);
   const [draftRules, setDraftRules] = useState<DraftRule[]>([]);
+  const [exitingRuleIds, setExitingRuleIds] = useState<Set<string>>(() => new Set());
+  const dialogRootRef = useRef<HTMLDivElement>(null);
+  const ruleRowsRef = useRef<Map<string, HTMLDivElement>>(new Map());
+  const rowAnimationsRef = useRef<Map<string, Animation>>(new Map());
+  const removalTimersRef = useRef<Map<string, number>>(new Map());
+  const exitingRuleIdsRef = useRef<Set<string>>(new Set());
+  const pendingLayoutRectsRef = useRef<Map<string, DOMRect> | null>(null);
+  const enteringRuleIdsRef = useRef<Set<string>>(new Set());
+  const dialogSessionRef = useRef(0);
   const effectOptions = useMemo<SelectOption[]>(
     () => EFFECTS.map((effect) => ({
       value: effect,
@@ -71,41 +98,236 @@ export const GlobalPermissionRulesDialog: React.FC<GlobalPermissionRulesDialogPr
     [t],
   );
 
+  const cancelRowAnimations = useCallback(() => {
+    rowAnimationsRef.current.forEach((animation) => animation.cancel());
+    rowAnimationsRef.current.clear();
+  }, []);
+
+  const invalidatePendingRuleWork = useCallback(() => {
+    dialogSessionRef.current += 1;
+    removalTimersRef.current.forEach((timer) => window.clearTimeout(timer));
+    removalTimersRef.current.clear();
+    pendingLayoutRectsRef.current = null;
+    enteringRuleIdsRef.current.clear();
+    cancelRowAnimations();
+  }, [cancelRowAnimations]);
+
   useEffect(() => {
+    invalidatePendingRuleWork();
     if (!isOpen) {
+      // Keep the last rendered content stable while Modal retains it for exit.
       return;
     }
+    exitingRuleIdsRef.current = new Set();
+    setExitingRuleIds(new Set());
     setSavedRules(rules);
     setDraftRules(rules.map(toDraftRule));
-  }, [isOpen, rules]);
+  }, [invalidatePendingRuleWork, isOpen, rules]);
+
+  useEffect(() => () => {
+    invalidatePendingRuleWork();
+  }, [invalidatePendingRuleWork]);
 
-  const permissionRules = useMemo(() => toPermissionRules(draftRules), [draftRules]);
+  const activeDraftRules = useMemo(
+    () => draftRules.filter((rule) => !exitingRuleIds.has(rule.localId)),
+    [draftRules, exitingRuleIds],
+  );
+
+  const activeRuleIndexes = useMemo(
+    () => new Map(activeDraftRules.map((rule, index) => [rule.localId, index])),
+    [activeDraftRules],
+  );
+
+  const permissionRules = useMemo(() => toPermissionRules(activeDraftRules), [activeDraftRules]);
   const rulesDirty = !rulesEqual(permissionRules, savedRules);
   const rulesValid = permissionRules.every((rule) => rule.action.trim() && rule.resource.trim());
 
   const updateDraftRule = (localId: string, update: Partial<PermissionRule>) => {
+    if (exitingRuleIdsRef.current.has(localId)) {
+      return;
+    }
     setDraftRules((current) => current.map((rule) => (
       rule.localId === localId ? { ...rule, ...update } : rule
     )));
   };
 
-  const moveDraftRule = (index: number, direction: -1 | 1) => {
-    const nextIndex = index + direction;
-    if (nextIndex < 0 || nextIndex >= draftRules.length) {
+  const captureLayoutRects = useCallback(() => {
+    const nextRects = new Map<string, DOMRect>();
+    ruleRowsRef.current.forEach((row, localId) => {
+      if (!exitingRuleIdsRef.current.has(localId)) {
+        nextRects.set(localId, row.getBoundingClientRect());
+      }
+    });
+    cancelRowAnimations();
+    pendingLayoutRectsRef.current = nextRects;
+  }, [cancelRowAnimations]);
+
+  const animateRow = useCallback((
+    localId: string,
+    row: HTMLDivElement,
+    keyframes: Keyframe[],
+    duration: number,
+  ) => {
+    if (typeof row.animate !== 'function') {
+      return;
+    }
+    rowAnimationsRef.current.get(localId)?.cancel();
+    const animation = row.animate(keyframes, {
+      duration,
+      easing: RULE_MOTION_EASING,
+    });
+    rowAnimationsRef.current.set(localId, animation);
+    const forgetAnimation = () => {
+      if (rowAnimationsRef.current.get(localId) === animation) {
+        rowAnimationsRef.current.delete(localId);
+      }
+    };
+    animation.onfinish = forgetAnimation;
+    animation.oncancel = forgetAnimation;
+  }, []);
+
+  useLayoutEffect(() => {
+    if (!isOpen) {
+      return;
+    }
+
+    const reduceMotion = prefersReducedMotion();
+    const previousRects = pendingLayoutRectsRef.current;
+    pendingLayoutRectsRef.current = null;
+    if (previousRects && !reduceMotion) {
+      previousRects.forEach((previousRect, localId) => {
+        const row = ruleRowsRef.current.get(localId);
+        if (!row || exitingRuleIdsRef.current.has(localId)) {
+          return;
+        }
+        const nextRect = row.getBoundingClientRect();
+        const deltaX = previousRect.left - nextRect.left;
+        const deltaY = previousRect.top - nextRect.top;
+        if (Math.abs(deltaX) < MIN_RULE_SHIFT_PX && Math.abs(deltaY) < MIN_RULE_SHIFT_PX) {
+          return;
+        }
+        animateRow(localId, row, [
+          { transform: `translate(${deltaX}px, ${deltaY}px)` },
+          { transform: 'translate(0, 0)' },
+        ], RULE_MOVE_DURATION_MS);
+      });
+    }
+
+    enteringRuleIdsRef.current.forEach((localId) => {
+      const row = ruleRowsRef.current.get(localId);
+      if (!row) {
+        return;
+      }
+      animateRow(
+        localId,
+        row,
+        reduceMotion
+          ? [{ opacity: 0 }, { opacity: 1 }]
+          : [
+              { opacity: 0, transform: 'translateY(4px)' },
+              { opacity: 1, transform: 'translateY(0)' },
+            ],
+        reduceMotion ? REDUCED_MOTION_ENTER_DURATION_MS : RULE_ENTER_DURATION_MS,
+      );
+    });
+    enteringRuleIdsRef.current.clear();
+  }, [animateRow, draftRules, isOpen]);
+
+  const moveDraftRule = (localId: string, direction: -1 | 1) => {
+    const currentIndex = activeRuleIndexes.get(localId);
+    if (currentIndex === undefined) {
       return;
     }
+    const nextIndex = currentIndex + direction;
+    const targetRule = activeDraftRules[nextIndex];
+    if (!targetRule) {
+      return;
+    }
+    captureLayoutRects();
     setDraftRules((current) => {
       const nextRules = [...current];
-      [nextRules[index], nextRules[nextIndex]] = [nextRules[nextIndex], nextRules[index]];
+      const sourcePosition = nextRules.findIndex((rule) => rule.localId === localId);
+      const targetPosition = nextRules.findIndex((rule) => rule.localId === targetRule.localId);
+      if (sourcePosition < 0 || targetPosition < 0) {
+        return current;
+      }
+      [nextRules[sourcePosition], nextRules[targetPosition]] = [
+        nextRules[targetPosition],
+        nextRules[sourcePosition],
+      ];
       return nextRules;
     });
   };
 
+  const handleAddRule = () => {
+    const nextRule = toDraftRule({ action: '', resource: '', effect: 'ask' });
+    enteringRuleIdsRef.current.add(nextRule.localId);
+    setDraftRules((current) => [...current, nextRule]);
+  };
+
+  const moveFocusAfterRemoval = (localId: string) => {
+    const removedRow = ruleRowsRef.current.get(localId);
+    if (!removedRow?.contains(document.activeElement)) {
+      return;
+    }
+    const liveIds = activeDraftRules.map((rule) => rule.localId);
+    const removedIndex = liveIds.indexOf(localId);
+    const focusTargetId = liveIds[removedIndex + 1] ?? liveIds[removedIndex - 1];
+    const focusTarget = focusTargetId
+      ? ruleRowsRef.current
+        .get(focusTargetId)
+        ?.querySelector<HTMLButtonElement>('.global-permission-rules-dialog__rule-actions button:last-of-type')
+      : dialogRootRef.current?.querySelector<HTMLButtonElement>(
+        '.global-permission-rules-dialog__section-header button',
+      );
+    focusTarget?.focus();
+  };
+
+  const handleRemoveRule = (localId: string) => {
+    if (isSaving || exitingRuleIdsRef.current.has(localId)) {
+      return;
+    }
+    moveFocusAfterRemoval(localId);
+    rowAnimationsRef.current.get(localId)?.cancel();
+    rowAnimationsRef.current.delete(localId);
+
+    const nextExitingIds = new Set(exitingRuleIdsRef.current);
+    nextExitingIds.add(localId);
+    exitingRuleIdsRef.current = nextExitingIds;
+    setExitingRuleIds(nextExitingIds);
+
+    const session = dialogSessionRef.current;
+    const exitDuration = prefersReducedMotion()
+      ? REDUCED_MOTION_RULE_EXIT_DURATION_MS
+      : RULE_EXIT_DURATION_MS;
+    const timer = window.setTimeout(() => {
+      removalTimersRef.current.delete(localId);
+      if (session !== dialogSessionRef.current || !exitingRuleIdsRef.current.has(localId)) {
+        return;
+      }
+      captureLayoutRects();
+      const remainingExitingIds = new Set(exitingRuleIdsRef.current);
+      remainingExitingIds.delete(localId);
+      exitingRuleIdsRef.current = remainingExitingIds;
+      setExitingRuleIds(remainingExitingIds);
+      setDraftRules((current) => current.filter((rule) => rule.localId !== localId));
+    }, exitDuration);
+    removalTimersRef.current.set(localId, timer);
+  };
+
+  const handleDiscard = () => {
+    invalidatePendingRuleWork();
+    exitingRuleIdsRef.current = new Set();
+    setExitingRuleIds(new Set());
+    setDraftRules(savedRules.map(toDraftRule));
+  };
+
   const handleSave = async () => {
     if (!rulesValid || isSaving) {
       return;
     }
-    if (await onSave(permissionRules)) {
+    const session = dialogSessionRef.current;
+    if (await onSave(permissionRules) && session === dialogSessionRef.current) {
       setSavedRules(permissionRules);
     }
   };
@@ -115,6 +337,7 @@ export const GlobalPermissionRulesDialog: React.FC<GlobalPermissionRulesDialogPr
       isOpen={isOpen}
       onClose={() => {
         if (!isSaving) {
+          invalidatePendingRuleWork();
           onClose();
         }
       }}
@@ -124,7 +347,7 @@ export const GlobalPermissionRulesDialog: React.FC<GlobalPermissionRulesDialogPr
       contentClassName="global-permission-rules-dialog__modal"
       overlayClassName="global-permission-rules-dialog-overlay"
     >
-      <div className="global-permission-rules-dialog" data-bf-component="global-permission-rules-dialog" data-bf-part="root">
+      <div ref={dialogRootRef} className="global-permission-rules-dialog" data-bf-component="global-permission-rules-dialog" data-bf-part="root">
         <div data-bf-component="global-permission-rules-dialog" data-bf-part="intro" className="global-permission-rules-dialog__intro">
           <ShieldCheck size={18} aria-hidden="true" />
           <p>{t('permissionPolicy.globalRulesDialogDescription')}</p>
@@ -137,10 +360,7 @@ export const GlobalPermissionRulesDialog: React.FC<GlobalPermissionRulesDialogPr
               size="small"
               variant="secondary"
               disabled={isSaving}
-              onClick={() => setDraftRules((current) => [
-                ...current,
-                toDraftRule({ action: '', resource: '', effect: 'ask' }),
-              ])}
+              onClick={handleAddRule}
             >
               <Plus size={14} />
               {t('permissionPolicy.addGlobalRule')}
@@ -159,74 +379,97 @@ export const GlobalPermissionRulesDialog: React.FC<GlobalPermissionRulesDialogPr
                 <span>{t('permissionPolicy.globalRulesResource')}</span>
                 <span />
               </div>
-              {draftRules.map((rule, index) => (
-                <div data-bf-component="global-permission-rules-dialog" data-bf-part="rule" key={rule.localId} className="global-permission-rules-dialog__rule-row">
-                  <Select
-                    size="small"
-                    value={rule.effect}
-                    options={effectOptions}
-                    aria-label={t('permissionPolicy.globalRulesEffect')}
-                    disabled={isSaving}
-                    onChange={(value) => updateDraftRule(rule.localId, { effect: value as PermissionEffect })}
-                  />
-                  <Select
-                    size="small"
-                    value={rule.action}
-                    options={GLOBAL_PERMISSION_ACTION_OPTIONS}
-                    placeholder={t('permissionPolicy.globalRulesAction')}
-                    aria-label={t('permissionPolicy.globalRulesAction')}
-                    disabled={isSaving}
-                    error={!rule.action.trim()}
-                    onChange={(value) => updateDraftRule(rule.localId, { action: value as string })}
-                  />
-                  <Input
-                    inputSize="small"
-                    value={rule.resource}
-                    placeholder={t('permissionPolicy.globalRulesResourcePlaceholder')}
-                    aria-label={t('permissionPolicy.globalRulesResource')}
-                    disabled={isSaving}
-                    error={!rule.resource.trim()}
-                    onChange={(event) => updateDraftRule(rule.localId, { resource: event.target.value })}
-                  />
-                  <div data-bf-component="global-permission-rules-dialog" data-bf-part="ruleActions" className="global-permission-rules-dialog__rule-actions">
-                    <IconButton
-                      type="button"
-                      size="small"
-                      variant="ghost"
-                      aria-label={t('permissionPolicy.moveGlobalRuleUp')}
-                      tooltip={t('permissionPolicy.moveGlobalRuleUp')}
-                      disabled={isSaving || index === 0}
-                      onClick={() => moveDraftRule(index, -1)}
-                    >
-                      <ArrowUp size={14} />
-                    </IconButton>
-                    <IconButton
-                      type="button"
+              {draftRules.map((rule) => {
+                const exiting = exitingRuleIds.has(rule.localId);
+                const activeIndex = activeRuleIndexes.get(rule.localId);
+                return (
+                  <div
+                    ref={(row) => {
+                      if (row) {
+                        ruleRowsRef.current.set(rule.localId, row);
+                      } else {
+                        ruleRowsRef.current.delete(rule.localId);
+                      }
+                    }}
+                    data-bf-component="global-permission-rules-dialog"
+                    data-bf-part="rule"
+                    data-rule-id={rule.localId}
+                    data-exiting={exiting ? 'true' : 'false'}
+                    aria-hidden={exiting || undefined}
+                    {...(exiting ? { inert: '' } : {})}
+                    key={rule.localId}
+                    className="global-permission-rules-dialog__rule-row"
+                  >
+                    <Select
                       size="small"
-                      variant="ghost"
-                      aria-label={t('permissionPolicy.moveGlobalRuleDown')}
-                      tooltip={t('permissionPolicy.moveGlobalRuleDown')}
-                      disabled={isSaving || index === draftRules.length - 1}
-                      onClick={() => moveDraftRule(index, 1)}
-                    >
-                      <ArrowDown size={14} />
-                    </IconButton>
-                    <IconButton
-                      type="button"
+                      value={rule.effect}
+                      options={effectOptions}
+                      aria-label={t('permissionPolicy.globalRulesEffect')}
+                      disabled={isSaving || exiting}
+                      onChange={(value) => updateDraftRule(rule.localId, { effect: value as PermissionEffect })}
+                    />
+                    <Select
                       size="small"
-                      variant="ghost"
-                      aria-label={t('permissionPolicy.removeGlobalRule')}
-                      tooltip={t('permissionPolicy.removeGlobalRule')}
-                      disabled={isSaving}
-                      onClick={() => setDraftRules((current) => (
-                        current.filter(({ localId }) => localId !== rule.localId)
-                      ))}
-                    >
-                      <Trash2 size={14} />
-                    </IconButton>
+                      value={rule.action}
+                      options={GLOBAL_PERMISSION_ACTION_OPTIONS}
+                      placeholder={t('permissionPolicy.globalRulesAction')}
+                      aria-label={t('permissionPolicy.globalRulesAction')}
+                      disabled={isSaving || exiting}
+                      error={!rule.action.trim()}
+                      onChange={(value) => updateDraftRule(rule.localId, { action: value as string })}
+                    />
+                    <Input
+                      inputSize="small"
+                      value={rule.resource}
+                      placeholder={t('permissionPolicy.globalRulesResourcePlaceholder')}
+                      aria-label={t('permissionPolicy.globalRulesResource')}
+                      disabled={isSaving || exiting}
+                      error={!rule.resource.trim()}
+                      onChange={(event) => updateDraftRule(rule.localId, { resource: event.target.value })}
+                    />
+                    <div data-bf-component="global-permission-rules-dialog" data-bf-part="ruleActions" className="global-permission-rules-dialog__rule-actions">
+                      <IconButton
+                        type="button"
+                        size="small"
+                        variant="ghost"
+                        aria-label={t('permissionPolicy.moveGlobalRuleUp')}
+                        tooltip={t('permissionPolicy.moveGlobalRuleUp')}
+                        disabled={isSaving || exiting || activeIndex === 0}
+                        onClick={() => moveDraftRule(rule.localId, -1)}
+                      >
+                        <ArrowUp size={14} />
+                      </IconButton>
+                      <IconButton
+                        type="button"
+                        size="small"
+                        variant="ghost"
+                        aria-label={t('permissionPolicy.moveGlobalRuleDown')}
+                        tooltip={t('permissionPolicy.moveGlobalRuleDown')}
+                        disabled={
+                          isSaving
+                          || exiting
+                          || activeIndex === undefined
+                          || activeIndex === activeDraftRules.length - 1
+                        }
+                        onClick={() => moveDraftRule(rule.localId, 1)}
+                      >
+                        <ArrowDown size={14} />
+                      </IconButton>
+                      <IconButton
+                        type="button"
+                        size="small"
+                        variant="ghost"
+                        aria-label={t('permissionPolicy.removeGlobalRule')}
+                        tooltip={t('permissionPolicy.removeGlobalRule')}
+                        disabled={isSaving || exiting}
+                        onClick={() => handleRemoveRule(rule.localId)}
+                      >
+                        <Trash2 size={14} />
+                      </IconButton>
+                    </div>
                   </div>
-                </div>
-              ))}
+                );
+              })}
             </div>
           )}
 
@@ -235,7 +478,7 @@ export const GlobalPermissionRulesDialog: React.FC<GlobalPermissionRulesDialogPr
               <Button
                 type="button"
                 variant="ghost"
-                onClick={() => setDraftRules(savedRules.map(toDraftRule))}
+                onClick={handleDiscard}
                 disabled={isSaving}
               >
                 {t('permissionPolicy.discardGlobalRules')}
diff --git a/src/web-ui/src/infrastructure/config/components/MCPResourceBrowser.scss b/src/web-ui/src/infrastructure/config/components/MCPResourceBrowser.scss
index f1d3a0d8df..35e8d42ed1 100644
--- a/src/web-ui/src/infrastructure/config/components/MCPResourceBrowser.scss
+++ b/src/web-ui/src/infrastructure/config/components/MCPResourceBrowser.scss
@@ -94,7 +94,12 @@
         padding: 1rem;
         cursor: pointer;
         border-bottom: 1px solid var(--bf-appearance-token-border-base);
-        transition: all 0.2s ease;
+        transition:
+          background-color 0.2s ease,
+          border-color 0.2s ease,
+          color 0.2s ease,
+          opacity 0.2s ease,
+          transform 0.2s ease;
 
         &:hover {
           background: var(--bf-appearance-token-color-bg-tertiary);
@@ -240,4 +245,3 @@
   }
 }
 
-
diff --git a/src/web-ui/src/infrastructure/config/components/ReasoningConfigPanel.test.tsx b/src/web-ui/src/infrastructure/config/components/ReasoningConfigPanel.test.tsx
index 0d59ec46fb..353dfd71e9 100644
--- a/src/web-ui/src/infrastructure/config/components/ReasoningConfigPanel.test.tsx
+++ b/src/web-ui/src/infrastructure/config/components/ReasoningConfigPanel.test.tsx
@@ -6,6 +6,14 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import type { ReasoningConfig } from '../types';
 import ReasoningConfigPanel from './ReasoningConfigPanel';
 
+const { projectReasoningCatalog } = vi.hoisted(() => ({
+  projectReasoningCatalog: vi.fn(),
+}));
+
+vi.mock('@/infrastructure/api', () => ({
+  aiApi: { projectReasoningCatalog },
+}));
+
 vi.mock('react-i18next', () => ({
   useTranslation: () => ({ t: (key: string) => key }),
 }));
@@ -23,10 +31,12 @@ vi.mock('@/component-library', () => ({
 vi.mock('./ReasoningPresetEditor', () => ({
   default: ({
     value,
+    generatedProjection,
     onChange,
     onValidationChange,
   }: {
     value: ReasoningConfig;
+    generatedProjection?: { presets?: Array<{ id: string }> };
     onChange: (value: ReasoningConfig) => void;
     onValidationChange: (invalid: boolean) => void;
   }) => (
@@ -41,6 +51,19 @@ vi.mock('./ReasoningPresetEditor', () => ({
       >
         change
       </button>
+      <button
+        type="button"
+        data-testid="bind-models-dev"
+        onClick={() => onChange({
+          ...value,
+          catalog: { source: 'models_dev', provider: 'openai', model: 'gpt-test' },
+        })}
+      >
+        bind
+      </button>
+      <span data-testid="generated-presets">
+        {generatedProjection?.presets?.map(preset => preset.id).join(',') ?? ''}
+      </span>
       <button
         type="button"
         data-testid="invalidate-reasoning"
@@ -57,6 +80,7 @@ describe('ReasoningConfigPanel', () => {
   let root: Root;
 
   beforeEach(() => {
+    projectReasoningCatalog.mockReset();
     container = document.createElement('div');
     root = createRoot(container);
   });
@@ -109,4 +133,46 @@ describe('ReasoningConfigPanel', () => {
     expect(onCancel).toHaveBeenCalledOnce();
     expect(onApply).not.toHaveBeenCalled();
   });
+
+  it('refreshes generated presets after an explicit models.dev binding change', async () => {
+    projectReasoningCatalog
+      .mockResolvedValueOnce({ status: 'unknown', presets: [] })
+      .mockResolvedValueOnce({
+        status: 'known',
+        presets: [
+          { id: 'low', label: 'Low', order: 0, source: 'models_dev', actions: [] },
+          { id: 'high', label: 'High', order: 1, source: 'models_dev', actions: [] },
+        ],
+      });
+
+    await act(async () => root.render(
+      <ReasoningConfigPanel
+        value={{ catalog: { source: 'auto' }, presets: [] }}
+        projectionRequest={{
+          provider: 'responses',
+          modelName: 'gateway-alias',
+          baseUrl: 'https://gateway.example.com/v1',
+        }}
+        onCancel={vi.fn()}
+        onApply={vi.fn()}
+      />,
+    ));
+
+    await act(async () => {
+      container.querySelector<HTMLButtonElement>('[data-testid="bind-models-dev"]')?.click();
+      await Promise.resolve();
+    });
+
+    expect(projectReasoningCatalog).toHaveBeenLastCalledWith({
+      provider: 'responses',
+      modelName: 'gateway-alias',
+      baseUrl: 'https://gateway.example.com/v1',
+      reasoning: {
+        catalog: { source: 'models_dev', provider: 'openai', model: 'gpt-test' },
+        presets: [],
+      },
+    });
+    expect(container.querySelector('[data-testid="generated-presets"]')?.textContent)
+      .toBe('low,high');
+  });
 });
diff --git a/src/web-ui/src/infrastructure/config/components/ReasoningConfigPanel.tsx b/src/web-ui/src/infrastructure/config/components/ReasoningConfigPanel.tsx
index c202ee9b44..e10bb21d42 100644
--- a/src/web-ui/src/infrastructure/config/components/ReasoningConfigPanel.tsx
+++ b/src/web-ui/src/infrastructure/config/components/ReasoningConfigPanel.tsx
@@ -1,9 +1,11 @@
-import React, { useMemo, useState } from 'react';
+import React, { useEffect, useMemo, useRef, useState } from 'react';
 import { AlertTriangle } from 'lucide-react';
 import { useTranslation } from 'react-i18next';
 import { Button } from '@/component-library';
 import type { ReasoningCatalogProjection, ReasoningConfig } from '../types';
 import type { ModelsDevReasoningCatalog } from '@/infrastructure/api/service-api/AIApi';
+import { aiApi } from '@/infrastructure/api';
+import type { ReasoningCatalogProjectionRequest } from '@/infrastructure/api/service-api/AIApi';
 import {
   cloneReasoningConfig,
   validateReasoningConfig,
@@ -15,6 +17,8 @@ interface ReasoningConfigPanelProps {
   value: ReasoningConfig;
   generatedProjection?: ReasoningCatalogProjection | null;
   modelsDevReasoningCatalog?: ModelsDevReasoningCatalog | null;
+  projectionRequest?: Omit<ReasoningCatalogProjectionRequest, 'reasoning'>;
+  requestFormatLabel?: string;
   onCancel: () => void;
   onApply: (value: ReasoningConfig) => void;
 }
@@ -23,22 +27,66 @@ export const ReasoningConfigPanel: React.FC<ReasoningConfigPanelProps> = ({
   value,
   generatedProjection,
   modelsDevReasoningCatalog,
+  projectionRequest,
+  requestFormatLabel,
   onCancel,
   onApply,
 }) => {
   const { t } = useTranslation('settings/ai-model');
   const [draft, setDraft] = useState(() => cloneReasoningConfig(value));
   const [editorInvalid, setEditorInvalid] = useState(false);
+  const projectionRequestId = useRef(0);
+  const projectionBindingKey = JSON.stringify({
+    projectionRequest,
+    catalog: draft.catalog,
+  });
+  const [resolvedProjection, setResolvedProjection] = useState<{
+    bindingKey: string;
+    projection?: ReasoningCatalogProjection | null;
+  }>(() => ({
+    bindingKey: projectionBindingKey,
+    projection: generatedProjection,
+  }));
+  const activeGeneratedProjection = resolvedProjection.bindingKey === projectionBindingKey
+    ? resolvedProjection.projection
+    : undefined;
+
+  useEffect(() => {
+    if (!projectionRequest) {
+      setResolvedProjection({
+        bindingKey: projectionBindingKey,
+        projection: generatedProjection,
+      });
+      return;
+    }
+
+    const requestId = ++projectionRequestId.current;
+    void aiApi.projectReasoningCatalog({
+      ...projectionRequest,
+      reasoning: draft,
+    }).then((projection) => {
+      if (projectionRequestId.current !== requestId) return;
+      setResolvedProjection({ bindingKey: projectionBindingKey, projection });
+    }).catch(() => {
+      if (projectionRequestId.current !== requestId) return;
+      setResolvedProjection({ bindingKey: projectionBindingKey, projection: undefined });
+    });
+
+    return () => {
+      if (projectionRequestId.current === requestId) {
+        projectionRequestId.current += 1;
+      }
+    };
+  }, [draft, generatedProjection, projectionBindingKey, projectionRequest]);
+
   const generatedPresetIds = useMemo(() => (
-    generatedProjection?.presets
+    activeGeneratedProjection?.presets
       ?.filter(preset => preset.source !== 'model_config')
       .map(preset => preset.id) ?? []
-  ), [generatedProjection?.presets]);
-  const catalogBindingUnchanged = JSON.stringify(draft.catalog) === JSON.stringify(value.catalog);
-  const activeGeneratedProjection = catalogBindingUnchanged ? generatedProjection : undefined;
+  ), [activeGeneratedProjection?.presets]);
   const validationError = validateReasoningConfig(
     draft,
-    catalogBindingUnchanged ? generatedPresetIds : [],
+    generatedPresetIds,
   );
   const invalid = editorInvalid || validationError !== null;
 
@@ -57,6 +105,7 @@ export const ReasoningConfigPanel: React.FC<ReasoningConfigPanelProps> = ({
           value={draft}
           generatedProjection={activeGeneratedProjection}
           modelsDevReasoningCatalog={modelsDevReasoningCatalog}
+          requestFormatLabel={requestFormatLabel}
           onChange={setDraft}
           onValidationChange={setEditorInvalid}
         />
diff --git a/src/web-ui/src/infrastructure/config/components/ReasoningPresetEditor.appearance.ts b/src/web-ui/src/infrastructure/config/components/ReasoningPresetEditor.appearance.ts
index f84e987385..07a0079dbb 100644
--- a/src/web-ui/src/infrastructure/config/components/ReasoningPresetEditor.appearance.ts
+++ b/src/web-ui/src/infrastructure/config/components/ReasoningPresetEditor.appearance.ts
@@ -7,6 +7,7 @@ export const reasoningPresetEditorAppearanceDescriptor: AppearanceSurfaceDescrip
     { id: 'section' },
     { id: 'primarySettings' },
     { id: 'binding' },
+    { id: 'unavailableWarning' },
     { id: 'generated' },
     { id: 'header' },
     { id: 'empty' },
diff --git a/src/web-ui/src/infrastructure/config/components/ReasoningPresetEditor.scss b/src/web-ui/src/infrastructure/config/components/ReasoningPresetEditor.scss
index d7e22d253a..393c312c4a 100644
--- a/src/web-ui/src/infrastructure/config/components/ReasoningPresetEditor.scss
+++ b/src/web-ui/src/infrastructure/config/components/ReasoningPresetEditor.scss
@@ -53,6 +53,106 @@
     border-top: 1px dashed var(--bf-appearance-token-border-subtle);
   }
 
+  &__models-dev-search {
+    grid-column: 1 / -1;
+  }
+
+  &__models-dev-search-field {
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    align-items: center;
+    gap: $size-gap-5;
+    min-width: 0;
+    color: var(--bf-appearance-token-color-text-secondary);
+    font-size: var(--bf-appearance-token-font-size-xs);
+  }
+
+  &__models-dev-search-input {
+    display: flex;
+    align-items: center;
+    gap: $size-gap-3;
+    min-width: 0;
+
+    > span {
+      flex-shrink: 0;
+      white-space: nowrap;
+    }
+  }
+
+  &__models-dev-search-control {
+    position: relative;
+    flex: 1 1 auto;
+    min-width: 0;
+  }
+
+  &__models-dev-search-hint {
+    color: var(--bf-appearance-token-color-text-muted);
+    font-size: var(--bf-appearance-token-font-size-2xs);
+    line-height: 1.4;
+  }
+
+  &__models-dev-search-results {
+    position: fixed;
+    z-index: $z-popover;
+    box-sizing: border-box;
+    max-width: calc(100vw - 16px);
+    max-height: min(280px, calc(100vh - 16px));
+    overflow-y: auto;
+    padding: $size-gap-1 0;
+    border: 1px solid var(--bf-appearance-token-border-base);
+    border-radius: $size-radius-sm;
+    background: var(--bf-appearance-token-color-bg-secondary);
+    box-shadow: var(--bf-appearance-token-shadow-sm);
+  }
+
+  &__models-dev-search-result {
+    display: flex;
+    width: 100%;
+    flex-direction: column;
+    align-items: flex-start;
+    gap: 2px;
+    padding: $size-gap-2 $size-gap-3;
+    border: 0;
+    background: transparent;
+    color: var(--bf-appearance-token-color-text-primary);
+    text-align: left;
+    cursor: pointer;
+
+    &:hover,
+    &[data-highlighted='true'] {
+      background: var(--bf-appearance-token-element-bg-subtle);
+    }
+
+    strong {
+      overflow: hidden;
+      max-width: 100%;
+      font-size: var(--bf-appearance-token-font-size-xs);
+      font-weight: var(--bf-appearance-token-font-weight-medium);
+      text-overflow: ellipsis;
+      white-space: nowrap;
+    }
+
+    span {
+      overflow: hidden;
+      max-width: 100%;
+      color: var(--bf-appearance-token-color-text-muted);
+      font-size: var(--bf-appearance-token-font-size-2xs);
+      text-overflow: ellipsis;
+      white-space: nowrap;
+    }
+  }
+
+  &__models-dev-search-empty,
+  &__models-dev-search-limit {
+    padding: $size-gap-2 $size-gap-3;
+    color: var(--bf-appearance-token-color-text-muted);
+    font-size: var(--bf-appearance-token-font-size-2xs);
+  }
+
+  &__models-dev-search-limit {
+    border-top: 1px solid var(--bf-appearance-token-border-subtle);
+  }
+
   &__binding-field {
     display: flex;
     align-items: center;
@@ -165,6 +265,42 @@
     font-size: var(--bf-appearance-token-font-size-2xs);
   }
 
+  &__unavailable-warning {
+    display: flex;
+    align-items: flex-start;
+    gap: $size-gap-2;
+    padding: $size-gap-2 $size-gap-3;
+    border: 1px solid var(--bf-appearance-token-color-warning-border);
+    border-radius: $size-radius-sm;
+    background: var(--bf-appearance-token-color-warning-bg);
+    color: var(--bf-appearance-token-color-text-secondary);
+
+    > svg {
+      flex-shrink: 0;
+      margin-top: 1px;
+      color: var(--bf-appearance-token-color-warning);
+    }
+
+    > div {
+      display: flex;
+      flex-direction: column;
+      gap: 2px;
+      min-width: 0;
+    }
+
+    strong {
+      color: var(--bf-appearance-token-color-text-primary);
+      font-size: var(--bf-appearance-token-font-size-xs);
+      font-weight: var(--bf-appearance-token-font-weight-medium);
+    }
+
+    span {
+      color: var(--bf-appearance-token-color-text-secondary);
+      font-size: var(--bf-appearance-token-font-size-2xs);
+      line-height: 1.5;
+    }
+  }
+
   &__list {
     display: flex;
     flex-direction: column;
@@ -193,10 +329,8 @@
 
   &__row-toggle {
     display: flex;
-    flex: 1 1 auto;
+    flex: 0 0 auto;
     align-items: center;
-    gap: $size-gap-2;
-    min-width: 0;
     padding: $size-gap-1;
     border: 0;
     background: transparent;
@@ -216,32 +350,55 @@
     }
   }
 
-  &__row-summary-text {
+  &__row-content {
     display: flex;
     flex: 1 1 auto;
-    flex-direction: column;
-    gap: 2px;
+    align-items: center;
+    gap: $size-gap-3;
     min-width: 0;
+  }
 
-    strong,
-    span {
-      overflow: hidden;
-      text-overflow: ellipsis;
-      white-space: nowrap;
-    }
+  &__row-name {
+    flex: 0 1 auto;
+    min-width: 0;
+    padding: 0;
+    overflow: hidden;
+    border: 0;
+    background: transparent;
+    color: var(--bf-appearance-token-color-text-primary);
+    font-size: var(--bf-appearance-token-font-size-xs);
+    font-weight: var(--bf-appearance-token-font-weight-medium);
+    text-align: left;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    cursor: pointer;
 
-    strong {
-      color: var(--bf-appearance-token-color-text-primary);
-      font-size: var(--bf-appearance-token-font-size-xs);
-      font-weight: var(--bf-appearance-token-font-weight-medium);
+    &:focus-visible {
+      border-radius: $size-radius-sm;
+      outline: 2px solid var(--bf-appearance-token-color-accent-500);
+      outline-offset: 2px;
     }
+  }
 
-    span {
-      color: var(--bf-appearance-token-color-text-muted);
-      font-size: var(--bf-appearance-token-font-size-2xs);
+  &__row-name-editor {
+    flex: 0 1 220px;
+    min-width: 120px;
+
+    > .bitfun-input-wrapper {
+      width: 100%;
     }
   }
 
+  &__row-preview {
+    flex: 1 1 auto;
+    min-width: 0;
+    overflow: hidden;
+    color: var(--bf-appearance-token-color-text-muted);
+    font-size: var(--bf-appearance-token-font-size-2xs);
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
   &__row-badges {
     display: flex;
     flex-shrink: 0;
@@ -265,7 +422,6 @@
     border-top: 1px solid var(--bf-appearance-token-border-subtle);
   }
 
-  &__row-head,
   &__action {
     display: flex;
     align-items: center;
@@ -273,31 +429,6 @@
     min-width: 0;
   }
 
-  &__row-head {
-    display: grid;
-    grid-template-columns: repeat(2, minmax(0, 1fr));
-  }
-
-  &__row-head-field {
-    display: flex;
-    align-items: center;
-    gap: $size-gap-2;
-    min-width: 0;
-
-    > span {
-      flex-shrink: 0;
-      color: var(--bf-appearance-token-color-text-secondary);
-      font-size: var(--bf-appearance-token-font-size-2xs);
-      font-weight: var(--bf-appearance-token-font-weight-medium);
-      white-space: nowrap;
-    }
-
-    > .bitfun-input-wrapper {
-      flex: 1 1 auto;
-      min-width: 0;
-    }
-  }
-
   &__action > .select,
   &__action > .bitfun-input-wrapper,
   &__action > .bitfun-number-input {
@@ -350,8 +481,6 @@
     display: flex;
     flex-direction: column;
     gap: $size-gap-2;
-    padding-left: $size-gap-3;
-    border-left: 2px solid var(--bf-appearance-token-border-subtle);
   }
 
   &__action-controls {
@@ -381,10 +510,6 @@
       flex-wrap: wrap;
     }
 
-    &__row-head {
-      grid-template-columns: 1fr;
-    }
-
     &__primary-settings {
       align-items: stretch;
       flex-direction: column;
@@ -396,6 +521,16 @@
       gap: $size-gap-2;
     }
 
+    &__models-dev-search-field {
+      align-items: stretch;
+      grid-template-columns: 1fr;
+      gap: $size-gap-1;
+    }
+
+    &__models-dev-search-hint {
+      flex-basis: auto;
+    }
+
     &__action > .select:first-child,
     &__action > .bitfun-input-wrapper,
     &__action > .bitfun-number-input,
@@ -418,5 +553,13 @@
       width: 100%;
       padding-left: 22px;
     }
+
+    &__row-content {
+      flex: 1 1 calc(100% - 28px);
+    }
+
+    &__row-name-editor {
+      flex-basis: 180px;
+    }
   }
 }
diff --git a/src/web-ui/src/infrastructure/config/components/ReasoningPresetEditor.test.tsx b/src/web-ui/src/infrastructure/config/components/ReasoningPresetEditor.test.tsx
index 8af02a3034..fe2112e708 100644
--- a/src/web-ui/src/infrastructure/config/components/ReasoningPresetEditor.test.tsx
+++ b/src/web-ui/src/infrastructure/config/components/ReasoningPresetEditor.test.tsx
@@ -10,7 +10,13 @@ import type { ReasoningCatalogProjection, ReasoningConfig } from '../types';
 import ReasoningPresetEditor from './ReasoningPresetEditor';
 
 vi.mock('react-i18next', () => ({
-  useTranslation: () => ({ t: (key: string) => key }),
+  useTranslation: () => ({
+    t: (key: string, options?: Record<string, unknown>) => (
+      typeof options?.presets === 'string'
+        ? `${key}: ${String(options.format)}: ${options.presets}`
+        : key
+    ),
+  }),
 }));
 
 interface SelectSpyProps {
@@ -91,6 +97,7 @@ function renderEditor(
   value?: ReasoningConfig,
   onChange?: ReturnType<typeof vi.fn>,
   generatedProjection?: ReasoningCatalogProjection,
+  requestFormatLabel?: string,
 ) {
   const container = document.createElement('div');
   document.body.appendChild(container);
@@ -101,6 +108,7 @@ function renderEditor(
         value={value ?? { catalog: { source: 'models_dev', provider: '', model: '' }, presets: [] }}
         onChange={onChange ?? vi.fn()}
         generatedProjection={generatedProjection}
+        requestFormatLabel={requestFormatLabel}
         modelsDevReasoningCatalog={modelsDevReasoningCatalog}
       />,
     );
@@ -127,8 +135,14 @@ describe('ReasoningPresetEditor models-dev binding', () => {
     value?: ReasoningConfig,
     onChange?: ReturnType<typeof vi.fn>,
     generatedProjection?: ReasoningCatalogProjection,
+    requestFormatLabel?: string,
   ) {
-    const { container, root } = renderEditor(value, onChange, generatedProjection);
+    const { container, root } = renderEditor(
+      value,
+      onChange,
+      generatedProjection,
+      requestFormatLabel,
+    );
     activeRoot = root;
     activeContainer = container;
   }
@@ -165,6 +179,34 @@ describe('ReasoningPresetEditor models-dev binding', () => {
     expect(model?.options?.map(o => o.value)).toEqual(['gpt-5.1-codex']);
   });
 
+  it('warns about explicitly bound models.dev presets unsupported by the API format', () => {
+    render(
+      {
+        catalog: { source: 'models_dev', provider: 'anthropic', model: 'claude-fable-5' },
+        presets: [],
+      },
+      vi.fn(),
+      {
+        status: 'unknown',
+        presets: [],
+        unavailable_presets: [
+          { id: 'low', label: 'Low', order: 10, source: 'models_dev',
+            actions: [{ type: 'effort', value: 'low' }] },
+          { id: 'high', label: 'High', order: 20, source: 'models_dev',
+            actions: [{ type: 'effort', value: 'high' }] },
+        ],
+      },
+      'OpenAI (chat/completions)',
+    );
+
+    const warning = activeContainer?.querySelector('[data-bf-part="unavailableWarning"]');
+    expect(warning?.textContent).toContain('reasoningPresets.unavailableTitle');
+    expect(warning?.textContent).toContain('OpenAI (chat/completions)');
+    expect(warning?.textContent).toContain('Low, High');
+    expect(selectProps['reasoningPresets.defaultPreset']?.options?.map(option => option.value))
+      .toEqual(['']);
+  });
+
   it('reflects the currently bound provider and model values', () => {
     render({ catalog: { source: 'models_dev', provider: 'github-copilot', model: 'gpt-5.1-codex' }, presets: [] });
     const provider = selectProps['reasoningPresets.catalogProvider'];
diff --git a/src/web-ui/src/infrastructure/config/components/ReasoningPresetEditor.tsx b/src/web-ui/src/infrastructure/config/components/ReasoningPresetEditor.tsx
index 65f7a57b52..aba4adac03 100644
--- a/src/web-ui/src/infrastructure/config/components/ReasoningPresetEditor.tsx
+++ b/src/web-ui/src/infrastructure/config/components/ReasoningPresetEditor.tsx
@@ -1,4 +1,5 @@
 import React, { useMemo, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
 import {
   AlertTriangle,
   ArrowDown,
@@ -28,6 +29,8 @@ import type {
   ReasoningPresetAction,
 } from '../types';
 import type { ModelsDevReasoningCatalog } from '@/infrastructure/api/service-api/AIApi';
+import { getAppearanceOverlayHost } from '@/infrastructure/appearance/runtime/AppearanceOverlayHost';
+import { useAnchoredPopoverPosition } from '@/shared/utils/useAnchoredPopoverPosition';
 import {
   availableReasoningActionTypes,
   cloneReasoningConfig,
@@ -42,10 +45,36 @@ interface ReasoningPresetEditorProps {
   onChange: (value: ReasoningConfig) => void;
   generatedProjection?: ReasoningCatalogProjection | null;
   modelsDevReasoningCatalog?: ModelsDevReasoningCatalog | null;
+  requestFormatLabel?: string;
   disabled?: boolean;
   onValidationChange?: (invalid: boolean) => void;
 }
 
+type ModelsDevReasoningProvider = ModelsDevReasoningCatalog['providers'][number];
+type ModelsDevReasoningModel = ModelsDevReasoningProvider['models'][number];
+
+interface ModelsDevSearchResult {
+  provider: ModelsDevReasoningProvider;
+  model: ModelsDevReasoningModel;
+  rank: number;
+}
+
+const MODELS_DEV_SEARCH_SEPARATOR = /[\s/_.-]+/u;
+
+function normalizeModelsDevSearchText(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .split(MODELS_DEV_SEARCH_SEPARATOR)
+    .filter(Boolean)
+    .join(' ');
+}
+
+function tokenizeModelsDevSearch(value: string): string[] {
+  const normalized = normalizeModelsDevSearchText(value);
+  return normalized ? normalized.split(' ') : [];
+}
+
 function defaultAction(
   type: ReasoningPresetAction['type'],
   defaultEffortValue: string,
@@ -74,12 +103,19 @@ export const ReasoningPresetEditor: React.FC<ReasoningPresetEditorProps> = ({
   onChange,
   generatedProjection,
   modelsDevReasoningCatalog,
+  requestFormatLabel,
   disabled = false,
   onValidationChange,
 }) => {
   const { t } = useTranslation('settings/ai-model');
+  const modelsDevSearchListboxId = React.useId();
   const [jsonDrafts, setJsonDrafts] = useState<Record<string, string>>({});
   const [expandedPresetIndex, setExpandedPresetIndex] = useState<number | null>(null);
+  const [modelsDevSearch, setModelsDevSearch] = useState('');
+  const [modelsDevSearchOpen, setModelsDevSearchOpen] = useState(false);
+  const [modelsDevSearchHighlight, setModelsDevSearchHighlight] = useState(0);
+  const modelsDevSearchAnchorRef = useRef<HTMLDivElement>(null);
+  const modelsDevSearchPopoverRef = useRef<HTMLDivElement>(null);
   const invalidJsonKeysRef = useRef<Set<string>>(new Set());
   const presets = useMemo(() => value.presets ?? [], [value.presets]);
   const catalog = value.catalog ?? { source: 'auto' as const };
@@ -129,6 +165,11 @@ export const ReasoningPresetEditor: React.FC<ReasoningPresetEditorProps> = ({
     () => resolveDefaultReasoningEffortValue(generatedProjection),
     [generatedProjection],
   );
+  const unavailablePresetLabels = useMemo(() => (
+    generatedProjection?.unavailable_presets
+      ?.map(preset => preset.label || preset.id)
+      .filter(Boolean) ?? []
+  ), [generatedProjection?.unavailable_presets]);
 
   const modelsDevProviderOptions = useMemo<SelectOption[]>(() => {
     const options = (modelsDevReasoningCatalog?.providers ?? []).map(provider => ({
@@ -153,6 +194,61 @@ export const ReasoningPresetEditor: React.FC<ReasoningPresetEditorProps> = ({
     }));
   }, [modelsDevReasoningCatalog, modelsDevProviderId]);
 
+  const modelsDevSearchResults = useMemo(() => {
+    const query = normalizeModelsDevSearchText(modelsDevSearch);
+    const queryTokens = tokenizeModelsDevSearch(modelsDevSearch);
+    if (!query) return { items: [] as ModelsDevSearchResult[], total: 0 };
+    const results: ModelsDevSearchResult[] = (modelsDevReasoningCatalog?.providers ?? []).flatMap(provider => (
+      provider.models.map(model => {
+        const providerId = provider.id.toLowerCase();
+        const providerName = provider.name.toLowerCase();
+        const modelId = model.id.toLowerCase();
+        const modelName = (model.display_name ?? '').toLowerCase();
+        const providerFields = [providerId, providerName];
+        const modelFields = [modelId, modelName];
+        const searchableFields = [...providerFields, ...modelFields];
+        if (!queryTokens.every(token => searchableFields.some(field => field.includes(token)))) {
+          return null;
+        }
+
+        const normalizedModelId = normalizeModelsDevSearchText(modelId);
+        const normalizedModelName = normalizeModelsDevSearchText(modelName);
+        const modelExact = normalizedModelId === query || normalizedModelName === query;
+        const modelPrefix = normalizedModelId.startsWith(query) || normalizedModelName.startsWith(query);
+        const providerExactToken = queryTokens.some(token => (
+          token === providerId || token === normalizeModelsDevSearchText(providerName)
+        ));
+        const allTokensMatchModel = queryTokens.every(token => (
+          modelFields.some(field => field.includes(token))
+        ));
+        const rank = modelExact
+          ? 0
+          : modelPrefix
+            ? 1
+            : providerExactToken
+              ? 2
+              : allTokensMatchModel
+                ? 3
+                : 4;
+        return { provider, model, rank };
+      })
+    )).filter((result): result is ModelsDevSearchResult => result !== null);
+    results.sort((left, right) => left.rank - right.rank
+        || left.model.id.localeCompare(right.model.id)
+        || left.provider.id.localeCompare(right.provider.id));
+    return { items: results.slice(0, 50), total: results.length };
+  }, [modelsDevReasoningCatalog, modelsDevSearch]);
+  const showModelsDevSearchResults = modelsDevSearchOpen && Boolean(modelsDevSearch.trim());
+  const modelsDevSearchLayout = useAnchoredPopoverPosition({
+    open: showModelsDevSearchResults,
+    anchorRef: modelsDevSearchAnchorRef,
+    popoverRef: modelsDevSearchPopoverRef,
+    preferredPlacement: 'bottom',
+    gap: 4,
+    matchAnchorWidth: true,
+    layoutRevision: `${modelsDevSearchResults.items.length}:${modelsDevSearchResults.total}`,
+  });
+
   const update = (next: ReasoningConfig) => onChange(cloneReasoningConfig(next));
   const defaultIsCustom = presets.some(preset => (
     preset.id === value.default_preset
@@ -167,6 +263,16 @@ export const ReasoningPresetEditor: React.FC<ReasoningPresetEditorProps> = ({
       catalog: nextCatalog,
     });
   };
+  const selectModelsDevSearchResult = (result: ModelsDevSearchResult) => {
+    rebindCatalog({
+      source: 'models_dev',
+      provider: result.provider.id,
+      model: result.model.id,
+    });
+    setModelsDevSearch('');
+    setModelsDevSearchOpen(false);
+    setModelsDevSearchHighlight(0);
+  };
   const updatePreset = (index: number, changes: Partial<ReasoningPreset>) => {
     const next = [...presets];
     next[index] = { ...next[index], ...changes };
@@ -318,6 +424,109 @@ export const ReasoningPresetEditor: React.FC<ReasoningPresetEditorProps> = ({
             data-bf-component="reasoning-preset-editor"
             data-bf-part="binding"
           >
+            <div className="bitfun-reasoning-preset-editor__models-dev-search">
+              <div className="bitfun-reasoning-preset-editor__models-dev-search-field">
+                <div className="bitfun-reasoning-preset-editor__models-dev-search-input">
+                  <span>{t('reasoningPresets.catalogSearch')}</span>
+                  <div
+                    ref={modelsDevSearchAnchorRef}
+                    className="bitfun-reasoning-preset-editor__models-dev-search-control"
+                  >
+                    <Input
+                      size="small"
+                      value={modelsDevSearch}
+                      disabled={disabled}
+                      placeholder={t('reasoningPresets.catalogSearchPlaceholder')}
+                      aria-label={t('reasoningPresets.catalogSearch')}
+                      role="combobox"
+                      aria-autocomplete="list"
+                      aria-controls={modelsDevSearchListboxId}
+                      aria-expanded={modelsDevSearchOpen && Boolean(modelsDevSearch.trim())}
+                      aria-activedescendant={modelsDevSearchOpen && modelsDevSearchResults.items.length > 0
+                        ? `${modelsDevSearchListboxId}-${modelsDevSearchHighlight}`
+                        : undefined}
+                      autoComplete="off"
+                      onFocus={() => setModelsDevSearchOpen(true)}
+                      onChange={(event) => {
+                        setModelsDevSearch(event.target.value);
+                        setModelsDevSearchOpen(true);
+                        setModelsDevSearchHighlight(0);
+                      }}
+                      onBlur={() => setModelsDevSearchOpen(false)}
+                      onKeyDown={(event) => {
+                        if (event.key === 'Escape') {
+                          setModelsDevSearchOpen(false);
+                          return;
+                        }
+                        if (!modelsDevSearchOpen || modelsDevSearchResults.items.length === 0) return;
+                        if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+                          event.preventDefault();
+                          const direction = event.key === 'ArrowDown' ? 1 : -1;
+                          setModelsDevSearchHighlight(previous => (
+                            (previous + direction + modelsDevSearchResults.items.length)
+                            % modelsDevSearchResults.items.length
+                          ));
+                        } else if (event.key === 'Enter') {
+                          event.preventDefault();
+                          const result = modelsDevSearchResults.items[modelsDevSearchHighlight];
+                          if (result) selectModelsDevSearchResult(result);
+                        }
+                      }}
+                    />
+                    {showModelsDevSearchResults && createPortal(
+                      <div
+                        ref={modelsDevSearchPopoverRef}
+                        id={modelsDevSearchListboxId}
+                        className="bitfun-reasoning-preset-editor__models-dev-search-results"
+                        role="listbox"
+                        aria-label={t('reasoningPresets.catalogSearchResults')}
+                        data-bf-placement={modelsDevSearchLayout?.placement ?? 'bottom'}
+                        style={{
+                          top: `${modelsDevSearchLayout?.top ?? 0}px`,
+                          left: `${modelsDevSearchLayout?.left ?? 0}px`,
+                          width: modelsDevSearchLayout?.width === undefined
+                            ? undefined
+                            : `${modelsDevSearchLayout.width}px`,
+                          visibility: modelsDevSearchLayout ? 'visible' : 'hidden',
+                        }}
+                      >
+                        {modelsDevSearchResults.items.length > 0
+                          ? modelsDevSearchResults.items.map((result, index) => (
+                          <button
+                            type="button"
+                            id={`${modelsDevSearchListboxId}-${index}`}
+                            key={`${result.provider.id}/${result.model.id}`}
+                            className="bitfun-reasoning-preset-editor__models-dev-search-result"
+                            onMouseDown={(event) => event.preventDefault()}
+                            onMouseEnter={() => setModelsDevSearchHighlight(index)}
+                            onClick={() => selectModelsDevSearchResult(result)}
+                            role="option"
+                            aria-selected={index === modelsDevSearchHighlight}
+                            data-highlighted={index === modelsDevSearchHighlight ? 'true' : undefined}
+                          >
+                            <strong>{result.model.display_name || result.model.id}</strong>
+                            <span>{result.provider.id} / {result.model.id}</span>
+                          </button>
+                        )) : (
+                          <div className="bitfun-reasoning-preset-editor__models-dev-search-empty">
+                            {t('reasoningPresets.catalogSearchEmpty')}
+                          </div>
+                        )}
+                        {modelsDevSearchResults.total > modelsDevSearchResults.items.length && (
+                          <div className="bitfun-reasoning-preset-editor__models-dev-search-limit">
+                            {t('reasoningPresets.catalogSearchLimit')}
+                          </div>
+                        )}
+                      </div>,
+                      getAppearanceOverlayHost(),
+                    )}
+                  </div>
+                </div>
+                <span className="bitfun-reasoning-preset-editor__models-dev-search-hint">
+                  {t('reasoningPresets.catalogSearchHint')}
+                </span>
+              </div>
+            </div>
             <div className="bitfun-reasoning-preset-editor__binding-field">
               <span>{t('reasoningPresets.catalogProvider')}</span>
               <Select
@@ -363,6 +572,26 @@ export const ReasoningPresetEditor: React.FC<ReasoningPresetEditorProps> = ({
           </div>
         )}
 
+        {catalog.source === 'models_dev' && unavailablePresetLabels.length > 0 && (
+          <div
+            className="bitfun-reasoning-preset-editor__unavailable-warning"
+            data-bf-component="reasoning-preset-editor"
+            data-bf-part="unavailableWarning"
+            role="status"
+          >
+            <AlertTriangle size={16} aria-hidden="true" />
+            <div>
+              <strong>{t('reasoningPresets.unavailableTitle')}</strong>
+              <span>
+                {t('reasoningPresets.unavailableDescription', {
+                  format: requestFormatLabel || t('reasoningPresets.unknownRequestFormat'),
+                  presets: unavailablePresetLabels.join(', '),
+                })}
+              </span>
+            </div>
+          </div>
+        )}
+
         {generatedProjection?.status === 'known'
           && (generatedProjection.presets?.some(preset => preset.source !== 'model_config') ?? false)
           && (
@@ -451,13 +680,37 @@ export const ReasoningPresetEditor: React.FC<ReasoningPresetEditorProps> = ({
                       className="bitfun-reasoning-preset-editor__row-toggle"
                       onClick={() => setExpandedPresetIndex(expanded ? null : presetIndex)}
                       aria-expanded={expanded}
+                      aria-label={preset.label?.trim() || preset.id}
                     >
                       {expanded ? <ChevronDown size={14} /> : <ChevronRight size={14} />}
-                      <span className="bitfun-reasoning-preset-editor__row-summary-text">
-                        <strong>{preset.label?.trim() || preset.id}</strong>
-                        <span>{formatPresetSummary(preset)}</span>
-                      </span>
                     </button>
+                    <div className="bitfun-reasoning-preset-editor__row-content">
+                      {expanded ? (
+                        <div className="bitfun-reasoning-preset-editor__row-name-editor">
+                          <Input
+                            size="small"
+                            aria-label={t('reasoningPresets.label')}
+                            value={preset.label ?? ''}
+                            disabled={disabled}
+                            placeholder={t('reasoningPresets.labelPlaceholder')}
+                            onChange={(event) => updatePreset(presetIndex, {
+                              label: event.target.value || undefined,
+                            })}
+                          />
+                        </div>
+                      ) : (
+                        <button
+                          type="button"
+                          className="bitfun-reasoning-preset-editor__row-name"
+                          onClick={() => setExpandedPresetIndex(presetIndex)}
+                        >
+                          {preset.label?.trim() || preset.id}
+                        </button>
+                      )}
+                      <span className="bitfun-reasoning-preset-editor__row-preview">
+                        {formatPresetSummary(preset)}
+                      </span>
+                    </div>
                     <div className="bitfun-reasoning-preset-editor__row-badges">
                       {value.default_preset === preset.id && (
                         <span className="bitfun-reasoning-preset-editor__badge">
@@ -508,40 +761,6 @@ export const ReasoningPresetEditor: React.FC<ReasoningPresetEditorProps> = ({
                       data-bf-component="reasoning-preset-editor"
                       data-bf-part="presetEditor"
                     >
-                      <div className="bitfun-reasoning-preset-editor__row-head">
-                        <div className="bitfun-reasoning-preset-editor__row-head-field">
-                          <span>{t('reasoningPresets.id')}</span>
-                          <Input
-                            size="small"
-                            aria-label={t('reasoningPresets.id')}
-                            value={preset.id}
-                            disabled={disabled}
-                            onChange={(event) => {
-                              const nextId = event.target.value;
-                              updatePreset(presetIndex, { id: nextId });
-                              if (value.default_preset === preset.id) {
-                                update({
-                                  ...value,
-                                  default_preset: nextId,
-                                  presets: presets.map((item, index) => index === presetIndex ? { ...item, id: nextId } : item),
-                                });
-                              }
-                            }}
-                          />
-                        </div>
-                        <div className="bitfun-reasoning-preset-editor__row-head-field">
-                          <span>{t('reasoningPresets.label')}</span>
-                          <Input
-                            size="small"
-                            aria-label={t('reasoningPresets.label')}
-                            value={preset.label ?? ''}
-                            disabled={disabled}
-                            placeholder={t('reasoningPresets.labelPlaceholder')}
-                            onChange={(event) => updatePreset(presetIndex, { label: event.target.value || undefined })}
-                          />
-                        </div>
-                      </div>
-
                       <div
                         className="bitfun-reasoning-preset-editor__actions"
                         data-bf-component="reasoning-preset-editor"
diff --git a/src/web-ui/src/infrastructure/config/components/SessionConfig.tsx b/src/web-ui/src/infrastructure/config/components/SessionConfig.tsx
index 30c54d5341..e2ecf2b27b 100644
--- a/src/web-ui/src/infrastructure/config/components/SessionConfig.tsx
+++ b/src/web-ui/src/infrastructure/config/components/SessionConfig.tsx
@@ -13,7 +13,6 @@ import {
   ConfigPageLoading,
   Modal,
   Select,
-  Tooltip,
   confirmDanger,
   type SelectOption,
 } from '@/component-library';
@@ -71,6 +70,7 @@ type BrowserControlLaunchResponse = {
   status: string;
   message: string | null;
   browserKind: string;
+  setupUrl?: string;
 };
 
 type BrowserControlBrowserOption = {
@@ -142,6 +142,10 @@ const SessionSettingsPanels: React.FC<SessionSettingsPanelsProps> = ({ variant }
 
   // ── Browser control state ───────────────────────────────────────────────
   const [browserCdpAvailable, setBrowserCdpAvailable] = useState(false);
+  const [browserReady, setBrowserReady] = useState(false);
+  const [browserAutoConnectOnStartup, setBrowserAutoConnectOnStartup] = useState(false);
+  const [browserDefaultCdpSupported, setBrowserDefaultCdpSupported] = useState(false);
+  const [browserDefaultCdpEnabled, setBrowserDefaultCdpEnabled] = useState(false);
   const [browserKind, setBrowserKind] = useState('');
   const [browserVersion, setBrowserVersion] = useState<string | null>(null);
   const [browserPageCount, setBrowserPageCount] = useState(0);
@@ -186,6 +190,9 @@ const SessionSettingsPanels: React.FC<SessionSettingsPanelsProps> = ({ variant }
       const [s, browsers] = await Promise.all([
         invoke<{
           cdpAvailable: boolean;
+          defaultCdpSupported: boolean;
+          defaultCdpEnabled: boolean;
+          browserReady: boolean;
           browserKind: string;
           browserVersion: string | null;
           port: number;
@@ -194,6 +201,9 @@ const SessionSettingsPanels: React.FC<SessionSettingsPanelsProps> = ({ variant }
         invoke<{ options: BrowserControlBrowserOption[] }>('browser_control_list_browsers'),
       ]);
       setBrowserCdpAvailable(s.cdpAvailable);
+      setBrowserDefaultCdpSupported(s.defaultCdpSupported);
+      setBrowserDefaultCdpEnabled(s.defaultCdpEnabled);
+      setBrowserReady(s.browserReady);
       setBrowserKind(s.browserKind);
       setBrowserVersion(s.browserVersion);
       setBrowserPageCount(s.pageCount);
@@ -234,6 +244,7 @@ const SessionSettingsPanels: React.FC<SessionSettingsPanelsProps> = ({ variant }
         debugConfigData,
         computerUseCfg,
         browserControlPreferredBrowser,
+        browserControlAutoConnect,
         loadedToolPermissionConfig,
         loadedPermissionModeControlVisibility,
         loadedCompanionPets,
@@ -246,6 +257,7 @@ const SessionSettingsPanels: React.FC<SessionSettingsPanelsProps> = ({ variant }
         configManager.getConfig<DebugModeConfig>('ai.debug_mode_config'),
         configManager.getConfig<boolean>('ai.computer_use_enabled'),
         configManager.getConfig<string>('ai.browser_control_preferred_browser'),
+        configManager.getConfig<boolean>('ai.browser_control_auto_connect_on_startup'),
         permissionConfigService.getConfig(),
         configManager.getOptionalConfig<boolean>(SHOW_PERMISSION_MODE_CONTROL_CONFIG_PATH),
         listAgentCompanionPets(),
@@ -261,6 +273,7 @@ const SessionSettingsPanels: React.FC<SessionSettingsPanelsProps> = ({ variant }
       setSubagentBatchExecutionPolicy(normalizeSubagentBatchExecutionPolicy(loadedSubagentBatchExecutionPolicy));
       if (debugConfigData) setDebugConfig(debugConfigData);
       setPreferredBrowser(browserControlPreferredBrowser || DEFAULT_BROWSER_CONTROL_BROWSER);
+      setBrowserAutoConnectOnStartup(browserControlAutoConnect === true);
       setToolPermissionConfig(normalizeToolPermissionConfig(loadedToolPermissionConfig));
       setShowPermissionModeControl(loadedPermissionModeControlVisibility !== false);
 
@@ -473,34 +486,15 @@ const SessionSettingsPanels: React.FC<SessionSettingsPanelsProps> = ({ variant }
     {
       value: 'safe_only',
       label: tTools('config.subagentBatchPolicy.safeOnly'),
+      description: tTools('config.subagentBatchPolicy.safeOnlyDesc'),
     },
     {
       value: 'force_parallel',
       label: tTools('config.subagentBatchPolicy.forceParallel'),
+      description: tTools('config.subagentBatchPolicy.forceParallelDesc'),
     },
   ];
 
-  const subagentBatchPolicyLabel = (
-    <span className="bitfun-func-agent-config__label-with-tooltip">
-      <span>{tTools('config.subagentBatchPolicy.label')}</span>
-      <Tooltip
-        content={
-          <span className="bitfun-func-agent-config__policy-tooltip">
-            <strong>{tTools('config.subagentBatchPolicy.safeOnly')}</strong>
-            <span>{tTools('config.subagentBatchPolicy.safeOnlyDesc')}</span>
-            <strong>{tTools('config.subagentBatchPolicy.forceParallel')}</strong>
-            <span>{tTools('config.subagentBatchPolicy.forceParallelDesc')}</span>
-          </span>
-        }
-        placement="top"
-      >
-        <span className="bitfun-func-agent-config__label-tooltip-icon" aria-label={tTools('config.subagentBatchPolicy.tooltipLabel')}>
-          <Info size={14} />
-        </span>
-      </Tooltip>
-    </span>
-  );
-
   const selectedCompanionPetPackage = settings?.agent_companion_pet
     ? companionPets.find(pet => pet.packagePath === settings.agent_companion_pet?.packagePath) ?? null
     : null;
@@ -639,21 +633,59 @@ const SessionSettingsPanels: React.FC<SessionSettingsPanelsProps> = ({ variant }
     }
   };
 
+  const handleBrowserAutoConnectChange = async (checked: boolean) => {
+    const previousValue = browserAutoConnectOnStartup;
+    setBrowserAutoConnectOnStartup(checked);
+    try {
+      await configManager.setConfig('ai.browser_control_auto_connect_on_startup', checked);
+    } catch (error) {
+      log.error('Failed to save browser_control_auto_connect_on_startup', error);
+      setBrowserAutoConnectOnStartup(previousValue);
+      notificationService.error(
+        `${tTools('messages.saveFailed')}: ` + (error instanceof Error ? error.message : String(error))
+      );
+    }
+  };
+
+  const presentBrowserControlLaunchResult = (result: BrowserControlLaunchResponse) => {
+    if (result.success) {
+      notificationService.success(
+        t('browserControl.connectSuccess', { browser: result.browserKind }),
+        { duration: 3000 }
+      );
+    } else if (result.status === 'requires_user_profile_setup') {
+      notificationService.info(
+        t('browserControl.userProfileSetupRequired', { browser: result.browserKind }),
+        { duration: 12000 }
+      );
+    } else if (result.status === 'requires_manual_user_profile_setup') {
+      // The platform could not open the settings page, so the URL itself is
+      // the actionable part of the message.
+      notificationService.info(
+        t('browserControl.userProfileSetupManual', {
+          browser: result.browserKind,
+          url: result.setupUrl ?? '',
+        }),
+        { duration: 20000 }
+      );
+    } else if (result.status === 'user_profile_connection_failed') {
+      notificationService.info(
+        t('browserControl.userProfileConnectionFailed', { browser: result.browserKind }),
+        { duration: 12000 }
+      );
+    } else if (result.status === 'needs_restart') {
+      setBrowserRestartPrompt(result);
+    } else if (result.message) {
+      notificationService.info(result.message, { duration: 8000 });
+    }
+  };
+
   const handleBrowserControlLaunch = async () => {
     setBrowserControlBusy(true);
     try {
       const { invoke } = await import('@tauri-apps/api/core');
       const result = await invoke<BrowserControlLaunchResponse>('browser_control_launch', { request: { port: 9222 } });
-      if (result.success) {
-        notificationService.success(
-          t('browserControl.connectSuccess', { browser: result.browserKind }),
-          { duration: 3000 }
-        );
-      } else if (result.status === 'needs_restart') {
-        setBrowserRestartPrompt(result);
-      } else if (result.message) {
-        notificationService.info(result.message, { duration: 8000 });
-      }
+      presentBrowserControlLaunchResult(result);
       await refreshBrowserControlStatus();
     } catch (error) {
       log.error('browser_control_launch failed', error);
@@ -663,6 +695,33 @@ const SessionSettingsPanels: React.FC<SessionSettingsPanelsProps> = ({ variant }
     }
   };
 
+  const handleBrowserControlEnableDefaultCdp = async () => {
+    setBrowserControlBusy(true);
+    try {
+      notificationService.info(
+        t(
+          browserDefaultCdpEnabled
+            ? 'browserControl.defaultCdpConnectPrompt'
+            : 'browserControl.defaultCdpEnablePrompt',
+          { browser: browserKind },
+        ),
+        { duration: 12000 },
+      );
+      const { invoke } = await import('@tauri-apps/api/core');
+      const result = await invoke<BrowserControlLaunchResponse>(
+        'browser_control_enable_default_cdp',
+        { request: { port: 9222 } },
+      );
+      presentBrowserControlLaunchResult(result);
+      await refreshBrowserControlStatus();
+    } catch (error) {
+      log.error('browser_control_enable_default_cdp failed', error);
+      notificationService.error(t('browserControl.connectFailed'));
+    } finally {
+      setBrowserControlBusy(false);
+    }
+  };
+
   const handleBrowserControlRestart = async () => {
     if (!browserRestartPrompt) return;
     setBrowserControlBusy(true);
@@ -689,23 +748,6 @@ const SessionSettingsPanels: React.FC<SessionSettingsPanelsProps> = ({ variant }
     }
   };
 
-  const handleBrowserControlCreateLauncher = async () => {
-    setBrowserControlBusy(true);
-    try {
-      const { invoke } = await import('@tauri-apps/api/core');
-      const path = await invoke<string>('browser_control_create_launcher');
-      notificationService.success(
-        t('browserControl.createLauncherSuccess', { path }),
-        { duration: 5000 }
-      );
-    } catch (error) {
-      log.error('browser_control_create_launcher failed', error);
-      notificationService.error(t('browserControl.createLauncherFailed'));
-    } finally {
-      setBrowserControlBusy(false);
-    }
-  };
-
   const handleToolTimeoutChange = async (value: string) => {
     const configKey = 'ai.tool_execution_timeout_secs';
     const trimmedValue = value.trim();
@@ -858,9 +900,24 @@ const SessionSettingsPanels: React.FC<SessionSettingsPanelsProps> = ({ variant }
   const computerUseScreenLabel = computerUseStatusLoading
     ? t('loading.text')
     : computerUseScreen ? t('computerUse.granted') : t('computerUse.notGranted');
+  const computerUsePlatformMessage = computerUsePlatformNote
+    ? platform === 'macos'
+      ? t('computerUse.platformNotes.macos')
+      : platform === 'windows'
+        ? t('computerUse.platformNotes.windows')
+        : platform === 'linux'
+          ? t('computerUse.platformNotes.linux')
+          : t('computerUse.platformNotes.generic')
+    : null;
+  // A ready browser is not a failure state: BitFun attaches to it the moment
+  // something needs it, so say that rather than the bare "not connected".
   const browserStatusLabel = browserCdpAvailable
     ? `${browserKind} · ${browserPageCount} ${t('browserControl.tabs')}`
-    : browserStatusLoading ? t('loading.text') : t('browserControl.notConnected');
+    : browserStatusLoading
+      ? t('loading.text')
+      : browserReady
+        ? t('browserControl.readyNotConnected')
+        : t('browserControl.notConnected');
   const browserSelectOptions: SelectOption[] = browserOptions.map((option) => ({
     value: option.value,
     label: option.installed ? option.label : `${option.label} (${t('browserControl.notInstalled')})`,
@@ -1186,21 +1243,7 @@ const SessionSettingsPanels: React.FC<SessionSettingsPanelsProps> = ({ variant }
           description={t('toolExecution.sectionDescription')}
         >
           <ConfigPageRow
-            label={(
-              <span className="bitfun-func-agent-config__inline-label">
-                <span>{tTools('config.executionTimeout')}</span>
-                <Tooltip content={tTools('config.executionTimeoutHint')} placement="top">
-                  <span
-                    className="bitfun-func-agent-config__inline-info"
-                    role="button"
-                    tabIndex={0}
-                    aria-label={tTools('config.executionTimeoutHint')}
-                  >
-                    <Info size={14} />
-                  </span>
-                </Tooltip>
-              </span>
-            )}
+            label={tTools('config.executionTimeout')}
             description={tTools('config.executionTimeoutDesc')}
             align="center"
           >
@@ -1217,7 +1260,11 @@ const SessionSettingsPanels: React.FC<SessionSettingsPanelsProps> = ({ variant }
               />
             </div>
           </ConfigPageRow>
-          <ConfigPageRow label={subagentBatchPolicyLabel} description={tTools('config.subagentBatchPolicy.desc')} align="center">
+          <ConfigPageRow
+            label={tTools('config.subagentBatchPolicy.label')}
+            description={tTools('config.subagentBatchPolicy.desc')}
+            align="center"
+          >
             <div className="bitfun-func-agent-config__row-control" data-bf-component="session-config" data-bf-part="control">
               <Select
                 value={subagentBatchExecutionPolicy}
@@ -1229,11 +1276,7 @@ const SessionSettingsPanels: React.FC<SessionSettingsPanelsProps> = ({ variant }
             </div>
           </ConfigPageRow>
           <ConfigPageRow
-            label={(
-              <span className="bitfun-func-agent-config__inline-label">
-                <span>{tTools('config.subagentMaxConcurrency')}</span>
-              </span>
-            )}
+            label={tTools('config.subagentMaxConcurrency')}
             description={tTools('config.subagentMaxConcurrencyDesc')}
             align="center"
           >
@@ -1387,7 +1430,7 @@ const SessionSettingsPanels: React.FC<SessionSettingsPanelsProps> = ({ variant }
                   )}
                 </div>
               </ConfigPageRow>
-              {computerUsePlatformNote && (
+              {computerUsePlatformMessage && (
                 <div
                   className="bitfun-func-agent-config__platform-note"
                   data-bf-component="session-config"
@@ -1402,7 +1445,7 @@ const SessionSettingsPanels: React.FC<SessionSettingsPanelsProps> = ({ variant }
                   <Info size={14} style={{ flexShrink: 0, marginTop: 2, opacity: 0.7 }} />
                   <p className="bitfun-config-page-row__description" style={{ margin: 0 }}>
                     <strong>{t('computerUse.platformNote')}: </strong>
-                    {computerUsePlatformNote}
+                    {computerUsePlatformMessage}
                   </p>
                 </div>
               )}
@@ -1442,6 +1485,63 @@ const SessionSettingsPanels: React.FC<SessionSettingsPanelsProps> = ({ variant }
                 </div>
               </ConfigPageRow>
               )}
+              {browserDefaultCdpSupported && (
+                <ConfigPageRow
+                  label={t('browserControl.defaultCdp')}
+                  description={t('browserControl.defaultCdpDesc')}
+                  align="center"
+                  balanced
+                >
+                  <div
+                    className="bitfun-func-agent-config__row-control"
+                    data-bf-component="session-config"
+                    data-bf-part="control"
+                    style={{
+                      display: 'flex',
+                      flexDirection: 'row',
+                      flexWrap: 'nowrap',
+                      alignItems: 'center',
+                      justifyContent: 'flex-end',
+                      gap: 8,
+                    }}
+                  >
+                    <span className={browserDefaultCdpEnabled ? 'bitfun-func-agent-config__perm-status--granted' : undefined}>
+                      {t(browserDefaultCdpEnabled
+                        ? 'browserControl.defaultCdpEnabled'
+                        : 'browserControl.defaultCdpDisabled')}
+                    </span>
+                    {!browserCdpAvailable && (
+                      <Button
+                        className="bitfun-func-agent-config__row-action-btn"
+                        size="small"
+                        variant="secondary"
+                        disabled={browserControlBusy || browserStatusLoading}
+                        onClick={() => void handleBrowserControlEnableDefaultCdp()}
+                      >
+                        {t(browserDefaultCdpEnabled
+                          ? 'browserControl.connect'
+                          : 'browserControl.enableDefaultCdp')}
+                      </Button>
+                    )}
+                  </div>
+                </ConfigPageRow>
+              )}
+              {browserDefaultCdpSupported && (
+                <ConfigPageRow
+                  label={t('browserControl.autoConnectOnStartup')}
+                  description={t('browserControl.autoConnectOnStartupDesc')}
+                  align="center"
+                  balanced
+                >
+                  <div className="bitfun-func-agent-config__row-control" data-bf-component="session-config" data-bf-part="control">
+                    <Switch
+                      checked={browserAutoConnectOnStartup}
+                      onChange={(e) => void handleBrowserAutoConnectChange(e.target.checked)}
+                      size="small"
+                    />
+                  </div>
+                </ConfigPageRow>
+              )}
               <ConfigPageRow
                 label={t('browserControl.status')}
                 description={t('browserControl.statusDesc') || undefined}
@@ -1490,7 +1590,7 @@ const SessionSettingsPanels: React.FC<SessionSettingsPanelsProps> = ({ variant }
                       <RefreshCw size={14} />
                     </IconButton>
                   </span>
-                  {!browserCdpAvailable && (
+                  {!browserCdpAvailable && !browserDefaultCdpSupported && (
                     <Button
                       className="bitfun-func-agent-config__row-action-btn"
                       size="small"
@@ -1503,25 +1603,6 @@ const SessionSettingsPanels: React.FC<SessionSettingsPanelsProps> = ({ variant }
                   )}
                 </div>
               </ConfigPageRow>
-              {platform === 'macos' && (
-                <ConfigPageRow
-                  label={t('browserControl.createLauncher')}
-                  description={t('browserControl.createLauncherDesc')}
-                  align="center"
-                >
-                  <div className="bitfun-func-agent-config__row-control" data-bf-component="session-config" data-bf-part="control">
-                    <Button
-                      className="bitfun-func-agent-config__row-action-btn"
-                      size="small"
-                      variant="secondary"
-                      disabled={browserControlBusy}
-                      onClick={() => void handleBrowserControlCreateLauncher()}
-                    >
-                      {t('browserControl.createLauncher')}
-                    </Button>
-                  </div>
-                </ConfigPageRow>
-              )}
             </>
           ) : null}
         </ConfigPageSection>
diff --git a/src/web-ui/src/infrastructure/config/components/SessionTitleConfig.tsx b/src/web-ui/src/infrastructure/config/components/SessionTitleConfig.tsx
index 8b1242b214..1bf6cc0541 100644
--- a/src/web-ui/src/infrastructure/config/components/SessionTitleConfig.tsx
+++ b/src/web-ui/src/infrastructure/config/components/SessionTitleConfig.tsx
@@ -5,14 +5,24 @@ import { useNotification, notificationService } from '@/shared/notification-syst
 import { createLogger } from '@/shared/utils/logger';
 import { aiExperienceConfigService, type AIExperienceSettings } from '../services/AIExperienceConfigService';
 import { configManager } from '../services/ConfigManager';
-import type { AIModelConfig } from '../types';
+import type { AIModelConfig, TaskModelSelection, TaskModelsConfig } from '../types';
 import { ConfigPageRow, ConfigPageSection } from './common';
 import { type ModelSelectOption, useModelSelectPresentation } from './ModelSelectPresentation';
 import './AIFeaturesConfig.scss';
 
 const log = createLogger('SessionTitleConfig');
 
-const AGENT_SESSION_TITLE = 'session-title-func-agent';
+const DEFAULT_TASK_MODELS: TaskModelsConfig = {
+  session_title: { kind: 'fixed', model_id: 'fast' },
+  git_commit: { kind: 'fixed', model_id: 'fast' },
+};
+
+function normalizeTaskModels(config?: Partial<TaskModelsConfig> | null): TaskModelsConfig {
+  return {
+    session_title: config?.session_title ?? DEFAULT_TASK_MODELS.session_title,
+    git_commit: config?.git_commit ?? DEFAULT_TASK_MODELS.git_commit,
+  };
+}
 
 function normalizeSelectValue(value: string | number | (string | number)[]): string {
   return String(Array.isArray(value) ? (value[0] ?? '') : value);
@@ -24,20 +34,20 @@ export const SessionTitleConfig: React.FC = () => {
   const [isLoading, setIsLoading] = useState(true);
   const [settings, setSettings] = useState<AIExperienceSettings | null>(null);
   const [models, setModels] = useState<AIModelConfig[]>([]);
-  const [funcAgentModels, setFuncAgentModels] = useState<Record<string, string>>({});
+  const [taskModels, setTaskModels] = useState<TaskModelsConfig>(DEFAULT_TASK_MODELS);
   const { buildModelOption, renderModelOption, renderModelValue } = useModelSelectPresentation();
 
   const loadData = useCallback(async () => {
     setIsLoading(true);
     try {
-      const [loadedSettings, allModels, funcAgentModelsData] = await Promise.all([
+      const [loadedSettings, allModels, taskModelsData] = await Promise.all([
         aiExperienceConfigService.getSettingsAsync(),
         configManager.getConfig<AIModelConfig[]>('ai.models') || [],
-        configManager.getConfig<Record<string, string>>('ai.func_agent_models') || {},
+        configManager.getConfig<Partial<TaskModelsConfig>>('ai.task_models'),
       ]);
       setSettings(loadedSettings);
       setModels(allModels ?? []);
-      setFuncAgentModels(funcAgentModelsData ?? {});
+      setTaskModels(normalizeTaskModels(taskModelsData));
     } catch (error) {
       log.error('Failed to load session title config', error);
       notifyError(t('sessionTitle.loadFailed'));
@@ -49,20 +59,24 @@ export const SessionTitleConfig: React.FC = () => {
   useEffect(() => {
     void loadData();
     const unwatchModels = configManager.watch('ai.models', () => void loadData());
-    const unwatchFuncAgentModels = configManager.watch('ai.func_agent_models', () => void loadData());
+    const unwatchTaskModels = configManager.watch('ai.task_models', () => void loadData());
     const unwatchSettings = aiExperienceConfigService.addChangeListener((next) => {
       setSettings(next);
     });
     return () => {
       unwatchModels();
-      unwatchFuncAgentModels();
+      unwatchTaskModels();
       unwatchSettings();
     };
   }, [loadData]);
 
   const enabledModels = models.filter((model) => model.enabled);
-  const sessionTitleModelId = funcAgentModels[AGENT_SESSION_TITLE] || 'fast';
+  const selectionValue = (selection: TaskModelSelection): string => (
+    selection.kind === 'inherit' ? 'inherit' : selection.model_id
+  );
+  const sessionTitleModelId = selectionValue(taskModels.session_title);
   const modelOptions = useMemo<ModelSelectOption[]>(() => [
+    { label: t('sessionTitle.model.inherit'), value: 'inherit' },
     { label: t('sessionTitle.model.fast'), value: 'fast' },
     { label: t('sessionTitle.model.primary'), value: 'primary' },
     ...enabledModels
@@ -94,13 +108,18 @@ export const SessionTitleConfig: React.FC = () => {
 
   const handleModelChange = async (modelId: string) => {
     try {
-      const current = await configManager.getConfig<Record<string, string>>('ai.func_agent_models') || {};
-      const updated = { ...current, [AGENT_SESSION_TITLE]: modelId };
-      await configManager.setConfig('ai.func_agent_models', updated);
-      setFuncAgentModels(updated);
+      const current = await configManager.getConfig<Partial<TaskModelsConfig>>('ai.task_models');
+      const selection: TaskModelSelection = modelId === 'inherit'
+        ? { kind: 'inherit' }
+        : { kind: 'fixed', model_id: modelId };
+      const updated = { ...normalizeTaskModels(current), session_title: selection };
+      await configManager.setConfig('ai.task_models', updated);
+      setTaskModels(updated);
 
       let modelDesc = '';
-      if (modelId === 'primary') {
+      if (modelId === 'inherit') {
+        modelDesc = t('sessionTitle.model.inherit');
+      } else if (modelId === 'primary') {
         modelDesc = t('sessionTitle.model.primary');
       } else if (modelId === 'fast') {
         modelDesc = t('sessionTitle.model.fast');
@@ -122,54 +141,56 @@ export const SessionTitleConfig: React.FC = () => {
   };
 
   return (
-    <ConfigPageSection
-      className="bitfun-func-agent-config"
-      data-bf-component="session-title-config"
-      data-bf-part="root"
-      title={t('sessionTitle.title')}
-      description={t('sessionTitle.subtitle')}
-      extra={(
-        <div
-          className="bitfun-func-agent-config__appearance-host"
-          data-bf-component="session-title-config"
-          data-bf-part="enableControl"
-        >
-          <Switch
-            checked={settings?.enable_session_title_generation ?? false}
-            onChange={(e) => void updateEnabled(e.target.checked)}
-            size="small"
-            disabled={isLoading || !settings}
-            aria-label={t('sessionTitle.title')}
-          />
-        </div>
-      )}
-    >
-      <ConfigPageRow
-        label={t('sessionTitle.model.label')}
-        description={enabledModels.length === 0 ? t('sessionTitle.models.empty') : undefined}
-        align="center"
+    <>
+      <ConfigPageSection
+        className="bitfun-func-agent-config"
+        data-bf-component="session-title-config"
+        data-bf-part="root"
+        title={t('sessionTitle.title')}
+        description={t('sessionTitle.subtitle')}
+        extra={(
+          <div
+            className="bitfun-func-agent-config__appearance-host"
+            data-bf-component="session-title-config"
+            data-bf-part="enableControl"
+          >
+            <Switch
+              checked={settings?.enable_session_title_generation ?? false}
+              onChange={(e) => void updateEnabled(e.target.checked)}
+              size="small"
+              disabled={isLoading || !settings}
+              aria-label={t('sessionTitle.title')}
+            />
+          </div>
+        )}
       >
-        <div
-          className="bitfun-func-agent-config__appearance-host"
-          data-bf-component="session-title-config"
-          data-bf-part="modelControl"
+        <ConfigPageRow
+          label={t('sessionTitle.model.label')}
+          description={enabledModels.length === 0 ? t('sessionTitle.models.empty') : undefined}
+          align="center"
         >
-          <Select
-            size="small"
-            searchable
-            className="model-select-presentation__select"
-            dropdownClassName="model-select-presentation__dropdown"
-            options={modelOptions}
-            value={sessionTitleModelId}
-            onChange={(value) => void handleModelChange(normalizeSelectValue(value))}
-            renderOption={renderModelOption}
-            renderValue={renderModelValue}
-            disabled={isLoading}
-            triggerTestId="settings-session-title-model-select"
-          />
-        </div>
-      </ConfigPageRow>
-    </ConfigPageSection>
+          <div
+            className="bitfun-func-agent-config__appearance-host"
+            data-bf-component="session-title-config"
+            data-bf-part="modelControl"
+          >
+            <Select
+              size="small"
+              searchable
+              className="model-select-presentation__select"
+              dropdownClassName="model-select-presentation__dropdown"
+              options={modelOptions}
+              value={sessionTitleModelId}
+              onChange={(value) => void handleModelChange(normalizeSelectValue(value))}
+              renderOption={renderModelOption}
+              renderValue={renderModelValue}
+              disabled={isLoading}
+              triggerTestId="settings-session-title-model-select"
+            />
+          </div>
+        </ConfigPageRow>
+      </ConfigPageSection>
+    </>
   );
 };
 
diff --git a/src/web-ui/src/infrastructure/config/components/SkillsConfig.scss b/src/web-ui/src/infrastructure/config/components/SkillsConfig.scss
index 61ec21edc2..770eb6e677 100644
--- a/src/web-ui/src/infrastructure/config/components/SkillsConfig.scss
+++ b/src/web-ui/src/infrastructure/config/components/SkillsConfig.scss
@@ -418,3 +418,12 @@
     transform: translateX(100%);
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .bitfun-skills-config__market-skeleton-line::after,
+  .bitfun-skills-config__market-skeleton-chip::after,
+  .bitfun-skills-config__market-skeleton-btn::after {
+    animation: none;
+    transform: none;
+  }
+}
diff --git a/src/web-ui/src/infrastructure/config/components/common/ConfigCollectionItem.scss b/src/web-ui/src/infrastructure/config/components/common/ConfigCollectionItem.scss
index f368424580..cdf8e39150 100644
--- a/src/web-ui/src/infrastructure/config/components/common/ConfigCollectionItem.scss
+++ b/src/web-ui/src/infrastructure/config/components/common/ConfigCollectionItem.scss
@@ -101,7 +101,23 @@
 
 // ─── expandable details ────────────────────────────────────────────────────────
 
+.bitfun-collection-item__details-collapse {
+  display: grid;
+  grid-template-rows: 0fr;
+  opacity: 0;
+  transition:
+    grid-template-rows 180ms $easing-standard,
+    opacity 120ms ease;
+
+  &[data-open='true'] {
+    grid-template-rows: 1fr;
+    opacity: 1;
+  }
+}
+
 .bitfun-collection-item__details {
+  min-height: 0;
+  overflow: hidden;
   padding: $size-gap-4;
   border-top: 1px dashed var(--bitfun-collection-details-border);
   background: var(--bitfun-collection-details-bg);
@@ -109,7 +125,6 @@
   display: flex;
   flex-direction: column;
   gap: $size-gap-3;
-  animation: bitfun-collection-slide-down 0.18s $easing-standard;
 }
 
 // ─── shared action button ──────────────────────────────────────────────────────
@@ -261,6 +276,18 @@
   }
 }
 
+@media (prefers-reduced-motion: reduce) {
+  .bitfun-collection-item__details-collapse,
+  .bitfun-collection-item__details-toggle svg,
+  .bitfun-collection-btn {
+    transition: none;
+  }
+
+  .bitfun-collection-form {
+    animation: none;
+  }
+}
+
 // ─── responsive ────────────────────────────────────────────────────────────────
 
 @container config-panel (max-width: 520px) {
diff --git a/src/web-ui/src/infrastructure/config/components/common/ConfigCollectionItem.test.tsx b/src/web-ui/src/infrastructure/config/components/common/ConfigCollectionItem.test.tsx
index 4b6a80e6fd..c3c34746fd 100644
--- a/src/web-ui/src/infrastructure/config/components/common/ConfigCollectionItem.test.tsx
+++ b/src/web-ui/src/infrastructure/config/components/common/ConfigCollectionItem.test.tsx
@@ -1,7 +1,7 @@
 // @vitest-environment jsdom
 
 import React, { act } from 'react';
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { createRoot, type Root } from 'react-dom/client';
 import ConfigCollectionItem from './ConfigCollectionItem';
 
@@ -18,9 +18,11 @@ describe('ConfigCollectionItem', () => {
   afterEach(() => {
     act(() => root.unmount());
     container.remove();
+    vi.useRealTimers();
   });
 
   it('uses an independent native button for expandable details', () => {
+    vi.useFakeTimers();
     act(() => {
       root.render(
         <ConfigCollectionItem
@@ -43,14 +45,29 @@ describe('ConfigCollectionItem', () => {
     act(() => {
       control?.click();
     });
-    expect(container.textContent).not.toContain('Configuration location');
+    expect(container.querySelector('.bitfun-collection-item__details-collapse')).toBeNull();
 
     act(() => {
       toggle?.click();
     });
 
+    const details = container.querySelector<HTMLElement>('.bitfun-collection-item__details-collapse');
     expect(toggle?.getAttribute('aria-expanded')).toBe('true');
     expect(container.textContent).toContain('Configuration location');
+    expect(details?.dataset.open).toBe('true');
+    expect(details?.getAttribute('aria-hidden')).toBe('false');
+
+    act(() => {
+      toggle?.click();
+    });
+    expect(details?.dataset.open).toBe('false');
+    expect(details?.getAttribute('aria-hidden')).toBe('true');
+    expect(details?.hasAttribute('inert')).toBe(true);
+
+    act(() => {
+      vi.advanceTimersByTime(180);
+    });
+    expect(container.querySelector('.bitfun-collection-item__details-collapse')).toBeNull();
   });
 
   it('does not expose disabled details as an interactive control', () => {
@@ -74,6 +91,6 @@ describe('ConfigCollectionItem', () => {
     });
 
     expect(toggle?.getAttribute('aria-expanded')).toBe('false');
-    expect(container.textContent).not.toContain('Configuration location');
+    expect(container.querySelector('.bitfun-collection-item__details-collapse')).toBeNull();
   });
 });
diff --git a/src/web-ui/src/infrastructure/config/components/common/ConfigCollectionItem.tsx b/src/web-ui/src/infrastructure/config/components/common/ConfigCollectionItem.tsx
index f530f8bcf1..c66573e373 100644
--- a/src/web-ui/src/infrastructure/config/components/common/ConfigCollectionItem.tsx
+++ b/src/web-ui/src/infrastructure/config/components/common/ConfigCollectionItem.tsx
@@ -1,5 +1,6 @@
 import React, { useId, useState } from 'react';
 import { ChevronDown } from 'lucide-react';
+import { PresenceBoundary } from '@/component-library';
 import './ConfigCollectionItem.scss';
 
 export interface ConfigCollectionItemProps extends React.HTMLAttributes<HTMLDivElement> {
@@ -90,9 +91,23 @@ export const ConfigCollectionItem: React.FC<ConfigCollectionItemProps> = ({
         </div>
       </div>
 
-      {isExpanded && details && (
-        <div id={detailsId} className="bitfun-collection-item__details" data-bf-component="config" data-bf-part="collectionDetails">{details}</div>
-      )}
+      {details ? (
+        <PresenceBoundary
+          active={isExpanded}
+          exitDurationMs={180}
+          minimumExitDurationMs={180}
+        >
+          <div
+            id={detailsId}
+            className="bitfun-collection-item__details-collapse"
+            data-open={isExpanded ? 'true' : 'false'}
+            aria-hidden={!isExpanded}
+            {...(!isExpanded ? { inert: '' } : {})}
+          >
+            <div className="bitfun-collection-item__details" data-bf-component="config" data-bf-part="collectionDetails">{details}</div>
+          </div>
+        </PresenceBoundary>
+      ) : null}
     </div>
   );
 };
diff --git a/src/web-ui/src/infrastructure/config/components/common/ConfigPageLayout.scss b/src/web-ui/src/infrastructure/config/components/common/ConfigPageLayout.scss
index f9ec0f5948..373cd0fed1 100644
--- a/src/web-ui/src/infrastructure/config/components/common/ConfigPageLayout.scss
+++ b/src/web-ui/src/infrastructure/config/components/common/ConfigPageLayout.scss
@@ -18,6 +18,8 @@
   --config-page-content-bottom-padding: 48px;
   /* Vertical gap between top-level sections (ConfigPageSection blocks) inside ConfigPageContent. */
   --config-page-section-gap: 32px;
+  /* Keep supporting copy readable and aligned across settings sections and rows. */
+  --config-page-description-max-width: 60ch;
   container-type: inline-size;
   container-name: config-panel;
 }
@@ -96,9 +98,11 @@
 
 .bitfun-config-page-section__description {
   margin: var(--bf-appearance-token-size-gap-1) 0 0;
+  max-inline-size: var(--config-page-description-max-width);
   font-size: var(--bf-appearance-token-font-size-xs);
   color: var(--bf-appearance-token-color-text-secondary);
   line-height: var(--bf-appearance-token-line-height-relaxed);
+  text-wrap: pretty;
 }
 
 .bitfun-config-page-section__extra {
@@ -178,9 +182,11 @@
 
 .bitfun-config-page-row__description {
   margin: var(--bf-appearance-token-size-gap-1) 0 0;
+  max-inline-size: var(--config-page-description-max-width);
   font-size: var(--bf-appearance-token-font-size-xs);
   color: var(--bf-appearance-token-color-text-secondary);
   line-height: var(--bf-appearance-token-line-height-relaxed);
+  text-wrap: pretty;
 }
 
 .bitfun-config-page-row__control {
@@ -208,9 +214,17 @@
   > div:has(> .bitfun-number-input) {
     width: 100%;
     min-width: 0;
+
+    > .select,
+    > .bitfun-input-wrapper,
+    > .bitfun-number-input {
+      width: 100%;
+      min-width: 0;
+    }
   }
 
-  > .bitfun-number-input .bitfun-number-input__input {
+  > .bitfun-number-input .bitfun-number-input__input,
+  > div:has(> .bitfun-number-input) > .bitfun-number-input .bitfun-number-input__input {
     text-align: left;
   }
 }
diff --git a/src/web-ui/src/infrastructure/config/components/external-sources/ExternalSourceSection.test.tsx b/src/web-ui/src/infrastructure/config/components/external-sources/ExternalSourceSection.test.tsx
new file mode 100644
index 0000000000..5c36c96716
--- /dev/null
+++ b/src/web-ui/src/infrastructure/config/components/external-sources/ExternalSourceSection.test.tsx
@@ -0,0 +1,67 @@
+// @vitest-environment jsdom
+
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import enUS from '@/locales/en-US/settings/external-sources.json';
+import type { ExternalSourcePresentationGroup } from '../../externalSourcePresentation';
+import { ExternalSourceSection } from './ExternalSourceSection';
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+function translate(key: string): string {
+  const value = key.split('.').reduce<unknown>((current, segment) => (
+    current && typeof current === 'object'
+      ? (current as Record<string, unknown>)[segment]
+      : undefined
+  ), enUS);
+  return typeof value === 'string' ? value : key;
+}
+
+describe('ExternalSourceSection', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+  });
+
+  it('renders the localized category for an unavailable MCP runtime', async () => {
+    const group: ExternalSourcePresentationGroup = {
+      key: 'opencode:mcp',
+      ecosystemId: 'opencode',
+      scopes: ['user_global'],
+      displayName: 'OpenCode MCP',
+      location: 'opencode.json',
+      lifecycle: 'degraded',
+      members: [],
+      counts: { commands: 0, tools: 0, agents: 0, mcps: 1 },
+      diagnostics: [{
+        severity: 'warning',
+        code: 'external_mcp.runtime_unavailable',
+        message: 'external_mcp.runtime.failed',
+      }],
+    };
+
+    await act(async () => {
+      root.render(
+        <ExternalSourceSection
+          groups={[group]}
+          t={translate as never}
+          renderSourceMembers={() => null}
+        />,
+      );
+    });
+
+    expect(container.textContent).toContain(enUS.diagnostics.category.runtimeUnavailable);
+    expect(container.textContent).not.toContain('diagnostics.category.runtimeUnavailable');
+    expect(container.textContent).not.toContain('external_mcp.runtime.failed');
+  });
+});
diff --git a/src/web-ui/src/infrastructure/config/components/external-sources/ExternalSourceSection.tsx b/src/web-ui/src/infrastructure/config/components/external-sources/ExternalSourceSection.tsx
index b0ada96993..d396416ca7 100644
--- a/src/web-ui/src/infrastructure/config/components/external-sources/ExternalSourceSection.tsx
+++ b/src/web-ui/src/infrastructure/config/components/external-sources/ExternalSourceSection.tsx
@@ -4,7 +4,12 @@ import {
   externalSourceDiagnosticKey,
   type ExternalSourcePresentationGroup,
 } from '../../externalSourcePresentation';
-import { SOURCE_COUNT_LABELS, sourceDiagnosticCategory, sourceScopeLabel } from './presentation';
+import {
+  SOURCE_COUNT_LABELS,
+  isActionableSourceDiagnostic,
+  sourceDiagnosticCategory,
+  sourceScopeLabel,
+} from './presentation';
 import type { ExternalSectionCommonProps } from './types';
 
 export interface ExternalSourceSectionProps
@@ -28,6 +33,7 @@ export const ExternalSourceSection: React.FC<ExternalSourceSectionProps> = ({
   return (
     <ConfigPageSection title={t('sources.title')}>
       {groups.map((group) => {
+        const userDiagnostics = group.diagnostics.filter(isActionableSourceDiagnostic);
         return (
           <React.Fragment key={group.key}>
             <ConfigPageRow
@@ -78,7 +84,7 @@ export const ExternalSourceSection: React.FC<ExternalSourceSectionProps> = ({
             >
               {renderSourceMembers(group)}
             </ConfigPageRow>
-            {group.diagnostics.length > 0 ? (
+            {userDiagnostics.length > 0 ? (
               <details
                 className="bitfun-external-sources-config__notice"
                 data-bf-component="external-sources-config"
@@ -89,11 +95,11 @@ export const ExternalSourceSection: React.FC<ExternalSourceSectionProps> = ({
                 <summary>
                   {t('diagnostics.sourceSummary', {
                     name: group.displayName,
-                    count: group.diagnostics.length,
+                    count: userDiagnostics.length,
                   })}
                 </summary>
                 <ul className="bitfun-external-sources-config__diagnostics" data-bf-component="external-sources-config" data-bf-part="diagnostics">
-                  {group.diagnostics.map((diagnostic) => (
+                  {userDiagnostics.map((diagnostic) => (
                     <li key={externalSourceDiagnosticKey(diagnostic)}>
                       <span>{t(`diagnostics.category.${sourceDiagnosticCategory(diagnostic.code)}`)}</span>
                     </li>
diff --git a/src/web-ui/src/infrastructure/config/components/external-sources/index.ts b/src/web-ui/src/infrastructure/config/components/external-sources/index.ts
index 23314ea833..11fd59902a 100644
--- a/src/web-ui/src/infrastructure/config/components/external-sources/index.ts
+++ b/src/web-ui/src/infrastructure/config/components/external-sources/index.ts
@@ -2,6 +2,7 @@ export type { ExternalHostCapabilities, ExternalSectionCommonProps } from './typ
 export {
   SOURCE_COUNT_LABELS,
   abbreviatedLocation,
+  isActionableSourceDiagnostic,
   sourceDiagnosticCategory,
   sourceScopeLabel,
 } from './presentation';
diff --git a/src/web-ui/src/infrastructure/config/components/external-sources/presentation.test.ts b/src/web-ui/src/infrastructure/config/components/external-sources/presentation.test.ts
new file mode 100644
index 0000000000..d4f6bbf835
--- /dev/null
+++ b/src/web-ui/src/infrastructure/config/components/external-sources/presentation.test.ts
@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import {
+  isActionableSourceDiagnostic,
+  sourceDiagnosticCategory,
+} from './presentation';
+
+describe('external source diagnostic presentation', () => {
+  it('keeps unknown warnings visible through the safe generic category', () => {
+    expect(isActionableSourceDiagnostic({
+      severity: 'warning',
+      code: 'future_provider.unknown_condition',
+      message: 'Opaque provider detail.',
+    })).toBe(true);
+    expect(sourceDiagnosticCategory('future_provider.unknown_condition'))
+      .toBe('sourceIssue');
+  });
+
+  it('hides informational diagnostics that do not require user action', () => {
+    expect(isActionableSourceDiagnostic({
+      severity: 'info',
+      code: 'future_provider.discovered',
+      message: 'Discovery completed.',
+    })).toBe(false);
+  });
+
+  it('gives an unavailable MCP runtime a concrete user category', () => {
+    expect(sourceDiagnosticCategory('external_mcp.runtime_unavailable'))
+      .toBe('runtimeUnavailable');
+  });
+});
diff --git a/src/web-ui/src/infrastructure/config/components/external-sources/presentation.ts b/src/web-ui/src/infrastructure/config/components/external-sources/presentation.ts
index f9a80f033c..3feeddedbe 100644
--- a/src/web-ui/src/infrastructure/config/components/external-sources/presentation.ts
+++ b/src/web-ui/src/infrastructure/config/components/external-sources/presentation.ts
@@ -39,11 +39,16 @@ export const SOURCE_COUNT_LABELS = [
   ['mcps', 'sources.mcpCount'],
 ] as const;
 
+type SourceDiagnostic = NonNullable<
+  ExternalSourceCatalogSnapshot['diagnostics']
+>[number];
+
 /**
  * Maps a raw diagnostic code to a user-facing category. Codes stay in the
  * collapsed technical details; the category is what the user reads first.
  */
 export function sourceDiagnosticCategory(code: string): string {
+  if (code.includes('external_mcp.runtime_unavailable')) return 'runtimeUnavailable';
   if (code.includes('preference_read_failed')) return 'confirmationStateUnavailable';
   if (code.includes('conflict_history_write_failed')) return 'conflictHistoryUnavailable';
   if (code.includes('discovery_in_progress')) return 'checkInProgress';
@@ -67,3 +72,7 @@ export function sourceDiagnosticCategory(code: string): string {
   if (code.includes('failed')) return 'checkFailed';
   return 'sourceIssue';
 }
+
+export function isActionableSourceDiagnostic(diagnostic: SourceDiagnostic): boolean {
+  return diagnostic.severity.toLowerCase() !== 'info';
+}
diff --git a/src/web-ui/src/infrastructure/config/components/form-controls/ConfigSection.tsx b/src/web-ui/src/infrastructure/config/components/form-controls/ConfigSection.tsx
index cf0a108dec..0d2788b3ff 100644
--- a/src/web-ui/src/infrastructure/config/components/form-controls/ConfigSection.tsx
+++ b/src/web-ui/src/infrastructure/config/components/form-controls/ConfigSection.tsx
@@ -51,30 +51,21 @@ export const ConfigSection: React.FC<ConfigSectionProps> = ({
       {(title || description) && (
         <div style={{ flexShrink: 0 }}>
           {title && (
-            <h4 
+            <button
+              type="button"
               className="config-form-section-title"
-              style={{ 
-                cursor: collapsible ? 'pointer' : 'default',
-                userSelect: 'none'
-              }}
+              disabled={!collapsible}
               onClick={handleToggle}
+              aria-expanded={collapsible ? !collapsed : undefined}
             >
               {icon}
               {title}
               {collapsible && (
-                <span 
-                  style={{ 
-                    marginLeft: '8px',
-                    transform: collapsed ? 'rotate(-90deg)' : 'rotate(0deg)',
-                    transition: 'transform 0.2s ease',
-                    fontSize: '14px',
-                    color: 'var(--bf-appearance-token-color-text-muted)'
-                  }}
-                >
+                <span className="config-form-section-chevron" aria-hidden="true">
                   ▼
                 </span>
               )}
-            </h4>
+            </button>
           )}
           {description && (
             <p className="config-form-section-description">
@@ -84,11 +75,16 @@ export const ConfigSection: React.FC<ConfigSectionProps> = ({
         </div>
       )}
       
-      {(!collapsible || !collapsed) && (
+      <div
+        className="config-form-section-collapse"
+        data-open={!collapsible || !collapsed ? 'true' : 'false'}
+        aria-hidden={collapsible && collapsed}
+        {...(collapsible && collapsed ? { inert: '' } : {})}
+      >
         <div className={contentClass} style={contentStyle}>
           {children}
         </div>
-      )}
+      </div>
     </div>
   );
 };
diff --git a/src/web-ui/src/infrastructure/config/services/ConfigManager.test.ts b/src/web-ui/src/infrastructure/config/services/ConfigManager.test.ts
index 9ecfaf70e0..bfc130f529 100644
--- a/src/web-ui/src/infrastructure/config/services/ConfigManager.test.ts
+++ b/src/web-ui/src/infrastructure/config/services/ConfigManager.test.ts
@@ -191,20 +191,23 @@ describe('ConfigManager', () => {
     configApiMocks.getConfigs.mockResolvedValueOnce({
       'ai.models': [{ id: 'model-1' }],
       'ai.default_models': { primary: 'model-1' },
-      'ai.func_agent_models': { title: 'primary' },
+      'ai.task_models': {
+        session_title: { kind: 'inherit' },
+        git_commit: { kind: 'fixed', model_id: 'fast' },
+      },
     });
 
     const configs = await configManager.getConfigs([
       'ai.models',
       'ai.default_models',
-      'ai.func_agent_models',
+      'ai.task_models',
     ]);
 
     expect(configApiMocks.getConfigs).toHaveBeenCalledTimes(1);
     expect(configApiMocks.getConfigs).toHaveBeenCalledWith([
       'ai.models',
       'ai.default_models',
-      'ai.func_agent_models',
+      'ai.task_models',
     ]);
     expect(configApiMocks.getConfig).not.toHaveBeenCalled();
     expect(configs['ai.models']).toMatchObject([{ id: 'model-1' }]);
@@ -298,19 +301,22 @@ describe('ConfigManager', () => {
     configApiMocks.getConfig.mockReturnValueOnce(defaultModels.promise);
     configApiMocks.getConfigs.mockResolvedValueOnce({
       'ai.models': [],
-      'ai.func_agent_models': { title: 'fast' },
+      'ai.task_models': {
+        session_title: { kind: 'fixed', model_id: 'fast' },
+        git_commit: { kind: 'fixed', model_id: 'fast' },
+      },
     });
 
     const singleRead = configManager.getConfig('ai.default_models');
     const batchRead = configManager.getConfigs([
       'ai.models',
       'ai.default_models',
-      'ai.func_agent_models',
+      'ai.task_models',
     ]);
 
     expect(configApiMocks.getConfigs).toHaveBeenCalledWith([
       'ai.models',
-      'ai.func_agent_models',
+      'ai.task_models',
     ]);
     defaultModels.resolve({ primary: 'model-1' });
 
@@ -318,7 +324,10 @@ describe('ConfigManager', () => {
     await expect(batchRead).resolves.toEqual({
       'ai.models': [],
       'ai.default_models': { primary: 'model-1' },
-      'ai.func_agent_models': { title: 'fast' },
+      'ai.task_models': {
+        session_title: { kind: 'fixed', model_id: 'fast' },
+        git_commit: { kind: 'fixed', model_id: 'fast' },
+      },
     });
     expect(configApiMocks.getConfig).toHaveBeenCalledTimes(1);
   });
@@ -353,7 +362,7 @@ describe('ConfigManager', () => {
       'ai.models',
       'ai.default_models',
       'ai.agent_model_defaults',
-      'ai.func_agent_models',
+      'ai.task_models',
     ])).resolves.toEqual({
       'ai.models': [],
       'ai.default_models': {},
@@ -367,7 +376,10 @@ describe('ConfigManager', () => {
           fork: { kind: 'inherit' },
         },
       },
-      'ai.func_agent_models': {},
+      'ai.task_models': {
+        session_title: { kind: 'fixed', model_id: 'fast' },
+        git_commit: { kind: 'fixed', model_id: 'fast' },
+      },
     });
   });
 
@@ -399,7 +411,10 @@ describe('ConfigManager', () => {
           fork: { kind: 'inherit' },
         },
       },
-      'ai.func_agent_models': { title: 'gpt-5-mini' },
+      'ai.task_models': {
+        session_title: { kind: 'fixed', model_id: 'gpt-5-mini' },
+        git_commit: { kind: 'fixed', model_id: 'fast' },
+      },
       'ai.default_models': { chat: 'gpt-5' },
     });
 
@@ -409,7 +424,7 @@ describe('ConfigManager', () => {
     expect(configApiMocks.getConfigs).toHaveBeenCalledWith([
       'ai.models',
       'ai.agent_model_defaults',
-      'ai.func_agent_models',
+      'ai.task_models',
       'ai.default_models',
     ]);
     expect(configApiMocks.getConfig).not.toHaveBeenCalled();
diff --git a/src/web-ui/src/infrastructure/config/services/ConfigManager.ts b/src/web-ui/src/infrastructure/config/services/ConfigManager.ts
index 9d7f17d1cd..bda8d8798b 100644
--- a/src/web-ui/src/infrastructure/config/services/ConfigManager.ts
+++ b/src/web-ui/src/infrastructure/config/services/ConfigManager.ts
@@ -382,9 +382,18 @@ class ConfigManagerImpl implements IConfigManager {
     if (path === 'ai.models') {
       return { hasFallback: true, value: [] };
     }
-    if (path === 'ai.func_agent_models' || path === 'ai.default_models') {
+    if (path === 'ai.default_models') {
       return { hasFallback: true, value: {} };
     }
+    if (path === 'ai.task_models') {
+      return {
+        hasFallback: true,
+        value: {
+          session_title: { kind: 'fixed', model_id: 'fast' },
+          git_commit: { kind: 'fixed', model_id: 'fast' },
+        },
+      };
+    }
     if (path === 'ai.agent_model_defaults') {
       return {
         hasFallback: true,
@@ -443,8 +452,11 @@ class ConfigManagerImpl implements IConfigManager {
       if (path === 'ai.models') {
         return [] as T;
       }
-      if (path === 'ai.func_agent_models') {
-        return {} as T;
+      if (path === 'ai.task_models') {
+        return {
+          session_title: { kind: 'fixed', model_id: 'fast' },
+          git_commit: { kind: 'fixed', model_id: 'fast' },
+        } as T;
       }
       if (path === 'ai.default_models') {
         return {} as T;
@@ -750,7 +762,7 @@ class ConfigManagerImpl implements IConfigManager {
       await this.getConfigs([
         'ai.models',
         'ai.agent_model_defaults',
-        'ai.func_agent_models',
+        'ai.task_models',
         'ai.default_models',
       ]);
     } catch (error) {
diff --git a/src/web-ui/src/infrastructure/config/types/index.ts b/src/web-ui/src/infrastructure/config/types/index.ts
index 677698a149..5b07e1c99f 100644
--- a/src/web-ui/src/infrastructure/config/types/index.ts
+++ b/src/web-ui/src/infrastructure/config/types/index.ts
@@ -229,6 +229,7 @@ export interface ReasoningCatalogProjection {
   status: 'unsupported' | 'known' | 'unknown';
   default_preset?: string;
   presets?: ReasoningPresetDescriptor[];
+  unavailable_presets?: ReasoningPresetDescriptor[];
 }
 
 export interface ModelMetadata {
@@ -320,6 +321,15 @@ export type SubagentModelSelection =
   | { kind: 'fixed'; model_id: string }
   | { kind: 'inherit' };
 
+export type TaskModelSelection =
+  | { kind: 'fixed'; model_id: string }
+  | { kind: 'inherit' };
+
+export interface TaskModelsConfig {
+  session_title: TaskModelSelection;
+  git_commit: TaskModelSelection;
+}
+
 export interface AgentModelDefaultsConfig {
   mode: string;
   subagents: {
@@ -333,7 +343,7 @@ export interface AIConfig {
   models: AIModelConfig[];
   default_models: DefaultModelsConfig;
   agent_model_defaults: AgentModelDefaultsConfig;
-  func_agent_models: Record<string, string>;
+  task_models: TaskModelsConfig;
   agent_profiles: Record<string, StoredAgentProfileConfigItem>;
   proxy: ProxyConfig;
   debug_mode_config: DebugModeConfig;
@@ -351,6 +361,7 @@ export interface AIConfig {
   subagent_batch_execution_policy?: 'safe_only' | 'force_parallel' | 'serial';
   computer_use_enabled?: boolean;
   browser_control_preferred_browser?: string;
+  browser_control_auto_connect_on_startup?: boolean;
 }
 
 export interface StoredAgentProfileConfigItem {
diff --git a/src/web-ui/src/infrastructure/contexts/WorkspaceProvider.tsx b/src/web-ui/src/infrastructure/contexts/WorkspaceProvider.tsx
index c16d640963..016df6156c 100644
--- a/src/web-ui/src/infrastructure/contexts/WorkspaceProvider.tsx
+++ b/src/web-ui/src/infrastructure/contexts/WorkspaceProvider.tsx
@@ -4,6 +4,7 @@ import { WorkspaceInfo, WorkspaceKind } from '../../shared/types';
 import { createLogger } from '@/shared/utils/logger';
 import { startupTrace } from '@/shared/utils/startupTrace';
 import { elapsedMs, nowMs } from '@/shared/utils/timing';
+import { isSurfaceChangedError } from '@/infrastructure/peer-device/deviceSurface';
 import {
   WorkspaceContext,
   type WorkspaceContextValue,
@@ -212,6 +213,13 @@ export const WorkspaceProvider: React.FC<WorkspaceProviderProps> = ({ children }
           hasActiveWorkspace: activeWorkspace !== null,
         });
       } catch (error) {
+        // A newer device surface superseded this initialization. The surface
+        // that replaced it runs its own, and its events drive this state, so
+        // rendering an error here would report a failure the user never had.
+        if (isSurfaceChangedError(error)) {
+          isInitializedRef.current = false;
+          return;
+        }
         startupTrace.markPhase('workspace_provider_initialize_failed', {
           durationMs: elapsedMs(providerStartedAt),
         });
diff --git a/src/web-ui/src/infrastructure/diagnostics/flowChatTailFollowDiagnostics.test.ts b/src/web-ui/src/infrastructure/diagnostics/flowChatTailFollowDiagnostics.test.ts
new file mode 100644
index 0000000000..d4bbf28c75
--- /dev/null
+++ b/src/web-ui/src/infrastructure/diagnostics/flowChatTailFollowDiagnostics.test.ts
@@ -0,0 +1,181 @@
+// @vitest-environment jsdom
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const diagnosticsMocks = vi.hoisted(() => ({
+  trace: vi.fn(),
+  isEnabled: vi.fn(() => true),
+}));
+
+vi.mock('./flowChatDiagnostics', () => ({
+  flowChatDiagnostics: { trace: diagnosticsMocks.trace },
+  isFlowChatDiagnosticsEnabled: diagnosticsMocks.isEnabled,
+}));
+
+import {
+  accumulateTailFollowStep,
+  createTailFollowWindow,
+  FLOWCHAT_TAIL_FOLLOW_PROBE,
+  noteFlowListCommit,
+  noteTailFollowStep,
+  resetTailFollowDiagnosticsForTests,
+  summariseTailFollowWindow,
+  tailFollowStepBucket,
+  TAIL_FOLLOW_WINDOW_MS,
+  type TailFollowStepSample,
+} from './flowChatTailFollowDiagnostics';
+
+function step(overrides: Partial<TailFollowStepSample> = {}): TailFollowStepSample {
+  return { stepPx: 24, lagPx: 24, innerScroll: true, snapped: false, ...overrides };
+}
+
+describe('tailFollowStepBucket', () => {
+  it('puts a whole line in the bucket that means "no better than not smoothing"', () => {
+    expect(tailFollowStepBucket(24)).toBe('to28');
+  });
+
+  it('separates a genuine improvement from an imperceptible one', () => {
+    expect(tailFollowStepBucket(3.9)).toBe('under4');
+    expect(tailFollowStepBucket(4)).toBe('to12');
+    expect(tailFollowStepBucket(11.9)).toBe('to12');
+  });
+
+  it('flags a step worse than a line', () => {
+    expect(tailFollowStepBucket(28)).toBe('over28');
+    expect(tailFollowStepBucket(120)).toBe('over28');
+  });
+
+  it('buckets by magnitude, so a correction upwards is not a separate story', () => {
+    expect(tailFollowStepBucket(-24)).toBe('to28');
+  });
+});
+
+describe('accumulateTailFollowStep', () => {
+  it('keeps the peaks, which is what a mean would hide', () => {
+    let window = createTailFollowWindow(0, 0);
+    window = accumulateTailFollowStep(window, step({ stepPx: 2, lagPx: 2 }));
+    window = accumulateTailFollowStep(window, step({ stepPx: 96, lagPx: 140 }));
+    window = accumulateTailFollowStep(window, step({ stepPx: 2, lagPx: 2 }));
+
+    expect(window.maxStepPx).toBe(96);
+    expect(window.maxLagPx).toBe(140);
+    expect(window.travelPx).toBe(100);
+    expect(window.buckets).toEqual({ under4: 2, to12: 0, to28: 0, over28: 1 });
+  });
+
+  it('counts snaps and inner-scroll steps apart', () => {
+    let window = createTailFollowWindow(0, 0);
+    window = accumulateTailFollowStep(window, step({ snapped: true, innerScroll: false }));
+    window = accumulateTailFollowStep(window, step({ snapped: false, innerScroll: true }));
+
+    expect(window.snaps).toBe(1);
+    expect(window.innerScrollSteps).toBe(1);
+  });
+
+  it('does not mutate the window it is given', () => {
+    const window = createTailFollowWindow(0, 0);
+    accumulateTailFollowStep(window, step());
+
+    expect(window.steps).toBe(0);
+    expect(window.buckets.to28).toBe(0);
+  });
+});
+
+describe('summariseTailFollowWindow', () => {
+  it('reports list commits as the delta over the window, not the running total', () => {
+    const window = createTailFollowWindow(0, 40);
+    const summary = summariseTailFollowWindow(window, 1_000, 55);
+
+    expect(summary.listCommits).toBe(15);
+    expect(summary.listCommitsPerSec).toBe(15);
+  });
+
+  it('scales a short trailing window up so it compares with the full ones', () => {
+    let window = createTailFollowWindow(0, 0);
+    for (let index = 0; index < 5; index += 1) {
+      window = accumulateTailFollowStep(window, step());
+    }
+    const summary = summariseTailFollowWindow(window, 250, 0);
+
+    expect(summary.forMs).toBe(250);
+    expect(summary.steps).toBe(5);
+    expect(summary.stepsPerSec).toBe(20);
+  });
+
+  it('reports no average step for a window that recorded none', () => {
+    const summary = summariseTailFollowWindow(createTailFollowWindow(0, 0), 1_000, 0);
+
+    expect(summary.avgStepPx).toBe(0);
+  });
+});
+
+describe('noteTailFollowStep', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    diagnosticsMocks.trace.mockClear();
+    diagnosticsMocks.isEnabled.mockReturnValue(true);
+    resetTailFollowDiagnosticsForTests();
+  });
+
+  afterEach(() => {
+    resetTailFollowDiagnosticsForTests();
+    vi.useRealTimers();
+  });
+
+  it('records nothing while the diagnostics switch is off', () => {
+    diagnosticsMocks.isEnabled.mockReturnValue(false);
+
+    noteTailFollowStep('thinking', step());
+    vi.advanceTimersByTime(TAIL_FOLLOW_WINDOW_MS * 3);
+
+    expect(diagnosticsMocks.trace).not.toHaveBeenCalled();
+  });
+
+  it('summarises a run of frames into one entry rather than one per frame', () => {
+    for (let frame = 0; frame < 40; frame += 1) {
+      noteTailFollowStep('thinking', step({ stepPx: 6, lagPx: 18 }));
+      vi.advanceTimersByTime(16);
+    }
+    vi.advanceTimersByTime(TAIL_FOLLOW_WINDOW_MS * 2);
+
+    const entries = diagnosticsMocks.trace.mock.calls.map(([probe]) => probe);
+    expect(entries.length).toBeGreaterThan(0);
+    expect(entries.length).toBeLessThan(40);
+    expect(entries[0].hypothesis).toBe(FLOWCHAT_TAIL_FOLLOW_PROBE);
+    expect(entries[0].location).toBe('tailFollow.thinking');
+    const total = entries.reduce((sum, probe) => sum + probe.data().steps, 0);
+    expect(total).toBe(40);
+  });
+
+  it('closes out the last window of a stream, which nothing else would report', () => {
+    noteTailFollowStep('thinking', step());
+    expect(diagnosticsMocks.trace).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(TAIL_FOLLOW_WINDOW_MS * 2);
+
+    expect(diagnosticsMocks.trace).toHaveBeenCalledTimes(1);
+    expect(diagnosticsMocks.trace.mock.calls[0][0].data().steps).toBe(1);
+  });
+
+  it('attributes only the list commits that happened inside the window', () => {
+    noteFlowListCommit();
+    noteFlowListCommit();
+    noteTailFollowStep('thinking', step());
+    noteFlowListCommit();
+    vi.advanceTimersByTime(TAIL_FOLLOW_WINDOW_MS * 2);
+
+    expect(diagnosticsMocks.trace.mock.calls[0][0].data().listCommits).toBe(1);
+  });
+
+  it('ignores list commits while the switch is off, so the count is not backdated', () => {
+    diagnosticsMocks.isEnabled.mockReturnValue(false);
+    noteFlowListCommit();
+    diagnosticsMocks.isEnabled.mockReturnValue(true);
+
+    noteTailFollowStep('thinking', step());
+    noteFlowListCommit();
+    vi.advanceTimersByTime(TAIL_FOLLOW_WINDOW_MS * 2);
+
+    expect(diagnosticsMocks.trace.mock.calls[0][0].data().listCommits).toBe(1);
+  });
+});
diff --git a/src/web-ui/src/infrastructure/diagnostics/flowChatTailFollowDiagnostics.ts b/src/web-ui/src/infrastructure/diagnostics/flowChatTailFollowDiagnostics.ts
new file mode 100644
index 0000000000..6bd2de7553
--- /dev/null
+++ b/src/web-ui/src/infrastructure/diagnostics/flowChatTailFollowDiagnostics.ts
@@ -0,0 +1,279 @@
+/**
+ * What following the tail cost, and how rough it looked.
+ *
+ * Streaming output moves a viewport towards its own bottom, and there are two
+ * such viewports in FlowChat: the message list, and the thinking card's own
+ * scroll box once its content passes `max-height`. Both face the same question,
+ * and the answers differ enough that guessing is not safe:
+ *
+ * - **How rough is it?** Markdown reflows a line at a time, so an unsmoothed
+ *   follow moves in line-sized steps. Whether a smoothing attempt actually
+ *   helped is a question about the *distribution* of step sizes, not the mean:
+ *   a follow that is silky for a second and then jumps a line reads as jumpy.
+ * - **What did it cost?** Changing the height of a list item forces the
+ *   virtualizer to re-measure, which re-renders `VirtualMessageList`. Scrolling
+ *   *inside* an item does not. That difference decides whether smoothing is
+ *   affordable at all, and it is invisible from the outside — the two look
+ *   identical on screen and differ by an order of magnitude in commits.
+ *
+ * So both are recorded together, over the same window, gated on
+ * `app.logging.flow_chat_diagnostics`. Read against each other they answer the
+ * only question worth asking about a smoothing change: did the steps get
+ * smaller, and what did that buy or cost in list commits.
+ *
+ * Nothing here evaluates a payload while the switch is off, and a follow
+ * running at frame rate reports once per window rather than once per frame —
+ * sixty entries a second would bury the transition they exist to show.
+ */
+
+import { flowChatDiagnostics, isFlowChatDiagnosticsEnabled } from './flowChatDiagnostics';
+
+/** Probe tag for everything about tail following in `flowchat.log`. */
+export const FLOWCHAT_TAIL_FOLLOW_PROBE = 'tailFollow';
+
+/**
+ * How much following is summarised into one entry.
+ *
+ * A second is long enough for a rate to mean something and short enough to keep
+ * a burst distinguishable from the steady state around it.
+ */
+export const TAIL_FOLLOW_WINDOW_MS = 1000;
+
+/**
+ * Step-size buckets, cut at fractions of a line rather than round numbers.
+ *
+ * FlowChat body text sits around a 24px line, and a line is the step an
+ * unsmoothed follow produces. So the boundaries say something a reader can act
+ * on: `over28` is worse than not smoothing at all, `to28` is no better than it,
+ * `to12` is a genuine improvement, and `under4` is below what the eye resolves
+ * as a step.
+ */
+export const TAIL_FOLLOW_BUCKET_BOUNDS_PX = [4, 12, 28] as const;
+
+export interface TailFollowStepBuckets {
+  under4: number;
+  to12: number;
+  to28: number;
+  over28: number;
+}
+
+/**
+ * Which follow this is. One window is kept per subject.
+ *
+ * The two are never summed. They face the same question and pay for it
+ * differently, so an average over both would hide exactly the difference the
+ * cost half of this file exists to expose.
+ */
+export type TailFollowSubject = 'list' | 'thinking';
+
+export interface TailFollowStepSample {
+  /** How far the scroll offset actually moved on this write. */
+  stepPx: number;
+  /** How far it was from the tail before the write. Equals `stepPx` when the follow jumps. */
+  lagPx: number;
+  /**
+   * The box was already scrolling internally, so this write changed no layout.
+   * False means the element is still growing and every step costs a re-measure.
+   *
+   * Always true for `list`, whose scroller is a fixed box that only ever
+   * scrolls — which is the trap. That write is free of *layout* and still not
+   * free: the virtualizer re-windows from the scroll events it produces, so the
+   * list's price is `listCommits` and this flag cannot show it.
+   */
+  innerScroll: boolean;
+  /** The write skipped whatever smoothing is in force and went straight to the tail. */
+  snapped: boolean;
+}
+
+export interface TailFollowWindow {
+  startedAtMs: number;
+  listCommitsAtStart: number;
+  steps: number;
+  travelPx: number;
+  maxStepPx: number;
+  maxLagPx: number;
+  snaps: number;
+  innerScrollSteps: number;
+  buckets: TailFollowStepBuckets;
+}
+
+export interface TailFollowWindowSummary {
+  forMs: number;
+  steps: number;
+  stepsPerSec: number;
+  travelPx: number;
+  avgStepPx: number;
+  maxStepPx: number;
+  maxLagPx: number;
+  snaps: number;
+  innerScrollSteps: number;
+  listCommits: number;
+  listCommitsPerSec: number;
+  buckets: TailFollowStepBuckets;
+}
+
+/** Round to a tenth, matching the viewport probes. */
+export function roundTailFollowPx(value: number): number {
+  return Math.round(value * 10) / 10;
+}
+
+/**
+ * Whether a caller should bother measuring.
+ *
+ * Sampling a follow means reading `scrollTop` on both sides of the write, and a
+ * follow runs every frame. `noteTailFollowStep` refuses the same way, but a
+ * caller that would pay for the reads should ask first.
+ */
+export function isTailFollowDiagnosticsEnabled(): boolean {
+  return isFlowChatDiagnosticsEnabled();
+}
+
+export function tailFollowStepBucket(stepPx: number): keyof TailFollowStepBuckets {
+  const [small, medium, large] = TAIL_FOLLOW_BUCKET_BOUNDS_PX;
+  const magnitudePx = Math.abs(stepPx);
+  if (magnitudePx < small) return 'under4';
+  if (magnitudePx < medium) return 'to12';
+  if (magnitudePx < large) return 'to28';
+  return 'over28';
+}
+
+export function createTailFollowWindow(nowMs: number, listCommits: number): TailFollowWindow {
+  return {
+    startedAtMs: nowMs,
+    listCommitsAtStart: listCommits,
+    steps: 0,
+    travelPx: 0,
+    maxStepPx: 0,
+    maxLagPx: 0,
+    snaps: 0,
+    innerScrollSteps: 0,
+    buckets: { under4: 0, to12: 0, to28: 0, over28: 0 },
+  };
+}
+
+export function accumulateTailFollowStep(
+  window: TailFollowWindow,
+  sample: TailFollowStepSample,
+): TailFollowWindow {
+  const bucket = tailFollowStepBucket(sample.stepPx);
+  return {
+    ...window,
+    steps: window.steps + 1,
+    travelPx: window.travelPx + Math.abs(sample.stepPx),
+    maxStepPx: Math.max(window.maxStepPx, Math.abs(sample.stepPx)),
+    maxLagPx: Math.max(window.maxLagPx, Math.abs(sample.lagPx)),
+    snaps: window.snaps + (sample.snapped ? 1 : 0),
+    innerScrollSteps: window.innerScrollSteps + (sample.innerScroll ? 1 : 0),
+    buckets: { ...window.buckets, [bucket]: window.buckets[bucket] + 1 },
+  };
+}
+
+/**
+ * Turn a window into what gets logged.
+ *
+ * Rates are per second rather than per window so that a short trailing window —
+ * the one a stream ends on, which is often the interesting one — is comparable
+ * with the full ones before it.
+ */
+export function summariseTailFollowWindow(
+  window: TailFollowWindow,
+  nowMs: number,
+  listCommits: number,
+): TailFollowWindowSummary {
+  const forMs = Math.max(1, nowMs - window.startedAtMs);
+  const perSec = 1000 / forMs;
+  const windowListCommits = listCommits - window.listCommitsAtStart;
+  return {
+    forMs: Math.round(forMs),
+    steps: window.steps,
+    stepsPerSec: roundTailFollowPx(window.steps * perSec),
+    travelPx: roundTailFollowPx(window.travelPx),
+    avgStepPx: window.steps === 0 ? 0 : roundTailFollowPx(window.travelPx / window.steps),
+    maxStepPx: roundTailFollowPx(window.maxStepPx),
+    maxLagPx: roundTailFollowPx(window.maxLagPx),
+    snaps: window.snaps,
+    innerScrollSteps: window.innerScrollSteps,
+    listCommits: windowListCommits,
+    listCommitsPerSec: roundTailFollowPx(windowListCommits * perSec),
+    buckets: window.buckets,
+  };
+}
+
+let listCommits = 0;
+const windows = new Map<TailFollowSubject, TailFollowWindow>();
+let sweepTimer: number | null = null;
+
+/**
+ * One render of the virtualized message list.
+ *
+ * This is the cost a follow pays for changing an item's height, and the number
+ * a follow that scrolls inside an item is claiming not to move. Counted rather
+ * than logged: it only means something next to a window of steps.
+ */
+export function noteFlowListCommit(): void {
+  if (!isFlowChatDiagnosticsEnabled()) return;
+  listCommits += 1;
+}
+
+function emitTailFollowWindow(
+  subject: TailFollowSubject,
+  window: TailFollowWindow,
+  nowMs: number,
+): void {
+  const summary = summariseTailFollowWindow(window, nowMs, listCommits);
+  flowChatDiagnostics.trace({
+    hypothesis: FLOWCHAT_TAIL_FOLLOW_PROBE,
+    location: `tailFollow.${subject}`,
+    message: 'a window of tail following',
+    data: () => ({ subject, ...summary }),
+  });
+}
+
+/**
+ * Close out windows nothing has written to for a while.
+ *
+ * Without this the last window of a stream is never reported, and the end of a
+ * stream is where a smoothing change is most likely to misbehave.
+ */
+function scheduleTailFollowSweep(): void {
+  if (sweepTimer !== null || typeof globalThis.window === 'undefined') return;
+  sweepTimer = globalThis.window.setTimeout(() => {
+    sweepTimer = null;
+    const nowMs = performance.now();
+    for (const [subject, pending] of [...windows]) {
+      if (nowMs - pending.startedAtMs < TAIL_FOLLOW_WINDOW_MS) continue;
+      emitTailFollowWindow(subject, pending, nowMs);
+      windows.delete(subject);
+    }
+    if (windows.size > 0) scheduleTailFollowSweep();
+  }, TAIL_FOLLOW_WINDOW_MS);
+}
+
+/** Record one write of a following scroll offset. */
+export function noteTailFollowStep(
+  subject: TailFollowSubject,
+  sample: TailFollowStepSample,
+): void {
+  if (!isFlowChatDiagnosticsEnabled()) return;
+
+  const nowMs = performance.now();
+  let pending = windows.get(subject);
+  if (pending && nowMs - pending.startedAtMs >= TAIL_FOLLOW_WINDOW_MS) {
+    emitTailFollowWindow(subject, pending, nowMs);
+    pending = undefined;
+  }
+  windows.set(
+    subject,
+    accumulateTailFollowStep(pending ?? createTailFollowWindow(nowMs, listCommits), sample),
+  );
+  scheduleTailFollowSweep();
+}
+
+export function resetTailFollowDiagnosticsForTests(): void {
+  listCommits = 0;
+  windows.clear();
+  if (sweepTimer !== null && typeof globalThis.window !== 'undefined') {
+    globalThis.window.clearTimeout(sweepTimer);
+  }
+  sweepTimer = null;
+}
diff --git a/src/web-ui/src/infrastructure/diagnostics/flowChatViewportDiagnostics.test.ts b/src/web-ui/src/infrastructure/diagnostics/flowChatViewportDiagnostics.test.ts
new file mode 100644
index 0000000000..6c0099a8c2
--- /dev/null
+++ b/src/web-ui/src/infrastructure/diagnostics/flowChatViewportDiagnostics.test.ts
@@ -0,0 +1,203 @@
+// @vitest-environment jsdom
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const diagnosticsMocks = vi.hoisted(() => ({
+  trace: vi.fn(),
+  isEnabled: vi.fn(() => true),
+}));
+
+vi.mock('./flowChatDiagnostics', () => ({
+  flowChatDiagnostics: { trace: diagnosticsMocks.trace },
+  isFlowChatDiagnosticsEnabled: diagnosticsMocks.isEnabled,
+}));
+
+import {
+  coalesceViewportRepeat,
+  FLOWCHAT_VIEWPORT_PROBE,
+  resetViewportDiagnosticsForTests,
+  traceViewportPlacement,
+  traceViewportRepeating,
+  VIEWPORT_TRACE_REPEAT_INTERVAL_MS,
+} from './flowChatViewportDiagnostics';
+
+describe('coalesceViewportRepeat', () => {
+  it('emits the first sample of a run, which is the transition', () => {
+    const decision = coalesceViewportRepeat(null, { nowMs: 1_000 });
+
+    expect(decision.emit).toEqual({
+      suppressedCount: 0,
+      suppressedTravelPx: 0,
+      suppressedForMs: 0,
+    });
+  });
+
+  it('folds samples inside the interval into the next emission', () => {
+    let state = coalesceViewportRepeat(null, { nowMs: 0 }).state;
+    for (let frame = 1; frame <= 12; frame += 1) {
+      const decision = coalesceViewportRepeat(state, { nowMs: frame * 16, travelPx: -2 });
+      expect(decision.emit).toBeNull();
+      state = decision.state;
+    }
+
+    const emitted = coalesceViewportRepeat(state, {
+      nowMs: VIEWPORT_TRACE_REPEAT_INTERVAL_MS,
+      travelPx: -2,
+    });
+
+    expect(emitted.emit).toEqual({
+      suppressedCount: 12,
+      // Travel is accumulated as distance, so a run that never nets anywhere is
+      // still visible as movement.
+      suppressedTravelPx: 24,
+      suppressedForMs: VIEWPORT_TRACE_REPEAT_INTERVAL_MS - 16,
+    });
+  });
+
+  it('starts the suppression clock at the first suppressed sample, not the last emission', () => {
+    const first = coalesceViewportRepeat(null, { nowMs: 0 });
+    const suppressed = coalesceViewportRepeat(first.state, { nowMs: 400 });
+
+    expect(suppressed.state.firstSuppressedAtMs).toBe(400);
+    expect(coalesceViewportRepeat(suppressed.state, { nowMs: 500 }).emit).toMatchObject({
+      suppressedCount: 1,
+      suppressedForMs: 100,
+    });
+  });
+
+  it('reports nothing suppressed for a run that resumes after a quiet interval', () => {
+    const first = coalesceViewportRepeat(null, { nowMs: 0 });
+
+    expect(coalesceViewportRepeat(first.state, { nowMs: 5_000 }).emit).toEqual({
+      suppressedCount: 0,
+      suppressedTravelPx: 0,
+      suppressedForMs: 0,
+    });
+  });
+});
+
+describe('traceViewportRepeating', () => {
+  beforeEach(() => {
+    diagnosticsMocks.trace.mockReset();
+    diagnosticsMocks.isEnabled.mockReturnValue(true);
+    resetViewportDiagnosticsForTests();
+  });
+
+  it('emits once per key per interval and carries what it stands for', () => {
+    const nowSpy = vi.spyOn(performance, 'now');
+    nowSpy.mockReturnValue(0);
+    traceViewportRepeating('write|follow-output|granted', {
+      location: 'viewportOwner.write',
+      message: 'wrote',
+      travelPx: 10,
+    });
+    nowSpy.mockReturnValue(16);
+    traceViewportRepeating('write|follow-output|granted', {
+      location: 'viewportOwner.write',
+      message: 'wrote',
+      travelPx: 10,
+    });
+
+    expect(diagnosticsMocks.trace).toHaveBeenCalledTimes(1);
+
+    nowSpy.mockReturnValue(600);
+    traceViewportRepeating('write|follow-output|granted', {
+      location: 'viewportOwner.write',
+      message: 'wrote',
+      travelPx: 10,
+      data: () => ({ owner: 'follow-output' }),
+    });
+
+    expect(diagnosticsMocks.trace).toHaveBeenCalledTimes(2);
+    const probe = diagnosticsMocks.trace.mock.calls[1][0];
+    expect(probe.hypothesis).toBe(FLOWCHAT_VIEWPORT_PROBE);
+    expect(probe.data()).toEqual({
+      owner: 'follow-output',
+      repeated: { suppressedCount: 1, suppressedTravelPx: 10, suppressedForMs: 584 },
+    });
+    nowSpy.mockRestore();
+  });
+
+  it('keeps interleaved runs apart, so a change of outcome is never buried', () => {
+    traceViewportRepeating('write|follow-output|granted', {
+      location: 'viewportOwner.write',
+      message: 'wrote',
+    });
+    traceViewportRepeating('write|anchor-correction|refused', {
+      location: 'viewportOwner.write',
+      message: 'refused',
+    });
+
+    expect(diagnosticsMocks.trace).toHaveBeenCalledTimes(2);
+  });
+
+  it('evaluates nothing while diagnostics are off', () => {
+    diagnosticsMocks.isEnabled.mockReturnValue(false);
+    const data = vi.fn(() => ({ scrollTop: 1 }));
+
+    traceViewportRepeating('write|follow-output|granted', {
+      location: 'viewportOwner.write',
+      message: 'wrote',
+      data,
+    });
+
+    expect(data).not.toHaveBeenCalled();
+    expect(diagnosticsMocks.trace).not.toHaveBeenCalled();
+  });
+});
+
+describe('traceViewportPlacement', () => {
+  beforeEach(() => {
+    diagnosticsMocks.trace.mockReset();
+    diagnosticsMocks.isEnabled.mockReturnValue(true);
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('reports the drift a later writer introduced', () => {
+    const scroller = document.createElement('div');
+    Object.defineProperty(scroller, 'scrollTop', { value: 0, writable: true });
+
+    traceViewportPlacement(
+      scroller,
+      { location: 'navigation.scrollIntoView', message: 'placed', targetPx: 900 },
+      () => {
+        scroller.scrollTop = 900;
+      },
+    );
+    // Something else took the viewport back after the placement landed.
+    scroller.scrollTop = 120;
+    vi.runAllTimers();
+
+    expect(diagnosticsMocks.trace).toHaveBeenCalledTimes(2);
+    expect(diagnosticsMocks.trace.mock.calls[0][0].data()).toMatchObject({
+      beforePx: 0,
+      placedPx: 900,
+      targetPx: 900,
+    });
+    expect(diagnosticsMocks.trace.mock.calls[1][0].location)
+      .toBe('navigation.scrollIntoView.outcome');
+    expect(diagnosticsMocks.trace.mock.calls[1][0].data()).toMatchObject({
+      settledPx: 120,
+      driftPx: -780,
+    });
+  });
+
+  it('still performs the placement while diagnostics are off', () => {
+    diagnosticsMocks.isEnabled.mockReturnValue(false);
+    const place = vi.fn();
+
+    traceViewportPlacement(
+      document.createElement('div'),
+      { location: 'navigation.scrollIntoView', message: 'placed' },
+      place,
+    );
+    vi.runAllTimers();
+
+    expect(place).toHaveBeenCalledTimes(1);
+    expect(diagnosticsMocks.trace).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/web-ui/src/infrastructure/diagnostics/flowChatViewportDiagnostics.ts b/src/web-ui/src/infrastructure/diagnostics/flowChatViewportDiagnostics.ts
new file mode 100644
index 0000000000..a7b0e09ce7
--- /dev/null
+++ b/src/web-ui/src/infrastructure/diagnostics/flowChatViewportDiagnostics.ts
@@ -0,0 +1,249 @@
+/**
+ * What moved the FlowChat viewport, recorded for after the fact.
+ *
+ * Every viewport fault this transcript has produced is intermittent, invisible
+ * in the DOM once it is over, and identical in the UI to two or three other
+ * causes: a Turn that lands and is then dragged away looks exactly like a Turn
+ * that never landed. Reproducing one with temporary probes takes a round trip
+ * through the user, and the reproduction is rarely the same twice.
+ *
+ * So the trail is permanent and gated on `app.logging.flow_chat_diagnostics`,
+ * the same switch history paging uses. Nothing here evaluates a payload while
+ * the switch is off.
+ *
+ * Two kinds of thing are worth recording, and they are deliberately different:
+ *
+ * - **Writes**, at the register. Who moved the viewport, where to, and who was
+ *   refused. One place, because every deliberate write goes through one place.
+ * - **Decisions**, at each writer. Why it wanted to move, and — more
+ *   useful — why it did not. A write that never happened leaves nothing at the
+ *   register to find, and "nothing happened" has been the symptom more often
+ *   than a wrong move has.
+ *
+ * Both run at frame rate in the worst case, so repeated identical events
+ * collapse into one entry per interval carrying what it stands for. The point
+ * of the log is the transitions; a thousand copies of a steady state only bury
+ * them.
+ */
+
+import { flowChatDiagnostics, isFlowChatDiagnosticsEnabled } from './flowChatDiagnostics';
+
+/** Probe tag for everything about the viewport in `flowchat.log`. */
+export const FLOWCHAT_VIEWPORT_PROBE = 'viewport';
+
+/** Shortest gap between two emissions of the same repeating event. */
+export const VIEWPORT_TRACE_REPEAT_INTERVAL_MS = 500;
+
+/**
+ * How long after a placement its result is read back.
+ *
+ * Long enough for the writers that undo a placement to have done it — the
+ * anchor's settle window and the virtualizer's re-aim both act within a few
+ * frames — and short enough that the reader's next gesture is not what the
+ * sample ends up describing.
+ */
+export const VIEWPORT_PLACEMENT_SETTLE_MS = 400;
+
+/** Repeat keys tracked at once, past which the least recently seen is dropped. */
+const MAX_TRACKED_REPEAT_KEYS = 64;
+
+export interface ViewportTraceProbe {
+  /** `subject.event`, e.g. `viewportOwner.write` or `followOutput.enter`. */
+  location: string;
+  message: string;
+  data?: () => Record<string, unknown>;
+}
+
+/** Round to a tenth. Anchor corrections that mattered have been 0.7px. */
+export function roundViewportPx(value: number): number {
+  return Math.round(value * 10) / 10;
+}
+
+export function isViewportDiagnosticsEnabled(): boolean {
+  return isFlowChatDiagnosticsEnabled();
+}
+
+export function traceViewport(probe: ViewportTraceProbe): void {
+  flowChatDiagnostics.trace({ hypothesis: FLOWCHAT_VIEWPORT_PROBE, ...probe });
+}
+
+export interface ViewportRepeatState {
+  lastEmitAtMs: number;
+  suppressedCount: number;
+  suppressedTravelPx: number;
+  firstSuppressedAtMs: number;
+}
+
+/** What an emission stands for besides itself. Absent when it stands alone. */
+export interface ViewportRepeatSummary {
+  suppressedCount: number;
+  suppressedTravelPx: number;
+  suppressedForMs: number;
+}
+
+export interface ViewportRepeatDecision {
+  state: ViewportRepeatState;
+  /** Null when this sample is folded into a later emission instead. */
+  emit: ViewportRepeatSummary | null;
+}
+
+/**
+ * Whether a repeating event is emitted now or folded into the next one.
+ *
+ * An event never seen before always emits: the first of a run is the
+ * transition, which is the part worth having. Everything after it waits out the
+ * interval, and what waited is reported when the interval ends — a count and
+ * the travel it accounted for, so that a run of 60 one-pixel corrections is
+ * legible as exactly that rather than as one correction.
+ *
+ * Callers key by the fields that distinguish one run from another, so a change
+ * of owner, or of outcome, is a new key and emits at once.
+ */
+export function coalesceViewportRepeat(
+  state: ViewportRepeatState | null,
+  sample: { nowMs: number; travelPx?: number },
+  intervalMs: number = VIEWPORT_TRACE_REPEAT_INTERVAL_MS,
+): ViewportRepeatDecision {
+  const fresh: ViewportRepeatState = {
+    lastEmitAtMs: sample.nowMs,
+    suppressedCount: 0,
+    suppressedTravelPx: 0,
+    firstSuppressedAtMs: sample.nowMs,
+  };
+
+  if (state === null) {
+    return {
+      state: fresh,
+      emit: { suppressedCount: 0, suppressedTravelPx: 0, suppressedForMs: 0 },
+    };
+  }
+
+  if (sample.nowMs - state.lastEmitAtMs >= intervalMs) {
+    return {
+      state: fresh,
+      emit: {
+        suppressedCount: state.suppressedCount,
+        suppressedTravelPx: roundViewportPx(state.suppressedTravelPx),
+        suppressedForMs: state.suppressedCount === 0
+          ? 0
+          : Math.round(sample.nowMs - state.firstSuppressedAtMs),
+      },
+    };
+  }
+
+  return {
+    state: {
+      lastEmitAtMs: state.lastEmitAtMs,
+      suppressedCount: state.suppressedCount + 1,
+      suppressedTravelPx: state.suppressedTravelPx + Math.abs(sample.travelPx ?? 0),
+      firstSuppressedAtMs: state.suppressedCount === 0
+        ? sample.nowMs
+        : state.firstSuppressedAtMs,
+    },
+    emit: null,
+  };
+}
+
+const repeatStates = new Map<string, ViewportRepeatState>();
+
+/**
+ * Record something that can happen on every frame.
+ *
+ * `key` is the run's identity: include whatever makes one run a different run —
+ * the owner, the outcome, the direction — and leave out the measurements, which
+ * belong in `data`.
+ */
+export function traceViewportRepeating(
+  key: string,
+  probe: ViewportTraceProbe & { travelPx?: number },
+): void {
+  if (!isFlowChatDiagnosticsEnabled()) return;
+
+  const decision = coalesceViewportRepeat(repeatStates.get(key) ?? null, {
+    nowMs: performance.now(),
+    travelPx: probe.travelPx,
+  });
+  // Re-inserted so the map's insertion order is recency order.
+  repeatStates.delete(key);
+  repeatStates.set(key, decision.state);
+  if (repeatStates.size > MAX_TRACKED_REPEAT_KEYS) {
+    const oldest = repeatStates.keys().next().value;
+    if (oldest !== undefined) repeatStates.delete(oldest);
+  }
+
+  const summary = decision.emit;
+  if (!summary) return;
+  traceViewport({
+    location: probe.location,
+    message: probe.message,
+    data: () => ({
+      ...(probe.data?.() ?? {}),
+      ...(summary.suppressedCount > 0 ? { repeated: summary } : {}),
+    }),
+  });
+}
+
+/**
+ * Record a placement together with what became of it.
+ *
+ * A placement that is immediately undone and one that never happened are the
+ * same complaint from the reader's side, and the difference is only visible in
+ * the frames afterwards. So the offset is sampled on the next frame and again
+ * once things have settled, and the drift from the target is reported with it.
+ * Reading that against the register's own writes says who took it away.
+ *
+ * The placement runs whether or not diagnostics are on; only the sampling is
+ * conditional.
+ */
+export function traceViewportPlacement(
+  scroller: HTMLElement | null,
+  probe: ViewportTraceProbe & {
+    /** Where the placement was aiming, when that is known separately. */
+    targetPx?: number;
+    /** Longer for an animated placement, which is still travelling at 400ms. */
+    settleAfterMs?: number;
+  },
+  place: () => void,
+): void {
+  if (!isFlowChatDiagnosticsEnabled() || !scroller) {
+    place();
+    return;
+  }
+
+  const beforePx = scroller.scrollTop;
+  place();
+  const placedPx = scroller.scrollTop;
+  traceViewport({
+    location: probe.location,
+    message: probe.message,
+    data: () => ({
+      ...(probe.data?.() ?? {}),
+      beforePx: roundViewportPx(beforePx),
+      placedPx: roundViewportPx(placedPx),
+      ...(probe.targetPx === undefined ? {} : { targetPx: roundViewportPx(probe.targetPx) }),
+    }),
+  });
+
+  const targetPx = probe.targetPx ?? placedPx;
+  let nextFramePx: number | null = null;
+  requestAnimationFrame(() => {
+    nextFramePx = scroller.scrollTop;
+  });
+  window.setTimeout(() => {
+    const settledPx = scroller.scrollTop;
+    traceViewport({
+      location: `${probe.location}.outcome`,
+      message: 'where the placement ended up',
+      data: () => ({
+        targetPx: roundViewportPx(targetPx),
+        nextFramePx: nextFramePx === null ? null : roundViewportPx(nextFramePx),
+        settledPx: roundViewportPx(settledPx),
+        driftPx: roundViewportPx(settledPx - targetPx),
+      }),
+    });
+  }, probe.settleAfterMs ?? VIEWPORT_PLACEMENT_SETTLE_MS);
+}
+
+export function resetViewportDiagnosticsForTests(): void {
+  repeatStates.clear();
+}
diff --git a/src/web-ui/src/infrastructure/font-preference/components/FontPreferencePanel.scss b/src/web-ui/src/infrastructure/font-preference/components/FontPreferencePanel.scss
index be2a23f0f4..688dadf60d 100644
--- a/src/web-ui/src/infrastructure/font-preference/components/FontPreferencePanel.scss
+++ b/src/web-ui/src/infrastructure/font-preference/components/FontPreferencePanel.scss
@@ -260,7 +260,12 @@
     border-radius: $size-radius-sm;
     color: var(--bf-appearance-token-color-text-secondary);
     cursor: pointer;
-    transition: all $motion-fast $easing-standard;
+    transition:
+      background-color $motion-fast $easing-standard,
+      border-color $motion-fast $easing-standard,
+      color $motion-fast $easing-standard,
+      opacity $motion-fast $easing-standard,
+      transform $motion-fast $easing-standard;
 
     &:hover {
       background: var(--bf-appearance-token-element-bg-subtle);
diff --git a/src/web-ui/src/infrastructure/i18n/components/LanguageSelector.scss b/src/web-ui/src/infrastructure/i18n/components/LanguageSelector.scss
index 418de28f33..bc842b988e 100644
--- a/src/web-ui/src/infrastructure/i18n/components/LanguageSelector.scss
+++ b/src/web-ui/src/infrastructure/i18n/components/LanguageSelector.scss
@@ -16,7 +16,11 @@
       font-size: 13px;
       color: var(--bf-appearance-token-color-text-primary);
       cursor: pointer;
-      transition: all 0.2s ease;
+      transition:
+        background-color 0.2s ease,
+        border-color 0.2s ease,
+        box-shadow 0.2s ease,
+        color 0.2s ease;
       
       
       background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 24 24' fill='none' stroke='%23999' stroke-width='2'%3E%3Cpath d='M6 9l6 6 6-6'/%3E%3C/svg%3E");
@@ -59,7 +63,12 @@
       color: var(--bf-appearance-token-color-text-secondary);
       font-size: 13px;
       cursor: pointer;
-      transition: all 0.2s ease;
+      transition:
+        background-color 0.2s ease,
+        border-color 0.2s ease,
+        color 0.2s ease,
+        opacity 0.2s ease,
+        transform 0.2s ease;
       
       &:hover:not(:disabled) {
         background: var(--bf-appearance-token-element-bg-base);
@@ -96,7 +105,12 @@
       color: var(--bf-appearance-token-color-text-secondary);
       font-size: 13px;
       cursor: pointer;
-      transition: all 0.2s ease;
+      transition:
+        background-color 0.2s ease,
+        border-color 0.2s ease,
+        color 0.2s ease,
+        opacity 0.2s ease,
+        transform 0.2s ease;
       
       &:hover:not(:disabled) {
         background: var(--bf-appearance-token-element-bg-base);
@@ -132,7 +146,10 @@
       opacity: 0;
       visibility: hidden;
       transform: translateY(-4px);
-      transition: all 0.2s ease;
+      transition:
+        opacity 0.2s ease,
+        transform 0.2s ease,
+        visibility 0.2s ease;
       z-index: 1000;
     }
     
@@ -156,7 +173,11 @@
       font-size: 13px;
       text-align: left;
       cursor: pointer;
-      transition: all 0.15s ease;
+      transition:
+        background-color 0.15s ease,
+        color 0.15s ease,
+        opacity 0.15s ease,
+        transform 0.15s ease;
       
       &:hover:not(:disabled) {
         background: var(--bf-appearance-token-element-bg-base);
diff --git a/src/web-ui/src/infrastructure/i18n/presets/namespaceRegistry.ts b/src/web-ui/src/infrastructure/i18n/presets/namespaceRegistry.ts
index 4d07466719..a6f6c8be7f 100644
--- a/src/web-ui/src/infrastructure/i18n/presets/namespaceRegistry.ts
+++ b/src/web-ui/src/infrastructure/i18n/presets/namespaceRegistry.ts
@@ -20,6 +20,7 @@ export const ALL_NAMESPACES = [
   'scenes/pages',
   'scenes/profile',
   'scenes/skills',
+  'scenes/todos',
   'settings',
   'settings/acp-agents',
   'settings/agentic-tools',
diff --git a/src/web-ui/src/infrastructure/peer-device/DeviceSurfaceSwitcher.scss b/src/web-ui/src/infrastructure/peer-device/DeviceSurfaceSwitcher.scss
new file mode 100644
index 0000000000..9580eb285f
--- /dev/null
+++ b/src/web-ui/src/infrastructure/peer-device/DeviceSurfaceSwitcher.scss
@@ -0,0 +1,259 @@
+/**
+ * Device surface switcher row above the NavPanel footer.
+ * Neutral while rendering this machine, warning-tinted while rendering a peer.
+ */
+
+@use '../../component-library/styles/tokens.scss' as *;
+
+.bitfun-device-switcher {
+  display: flex;
+  align-items: center;
+  gap: $size-gap-2;
+  flex-shrink: 0;
+  width: 100%;
+  min-width: 0;
+  box-sizing: border-box;
+  margin: 0;
+  padding: $size-gap-2 $size-gap-3;
+  border: none;
+  border-top: 1px solid var(--bf-appearance-token-border-subtle);
+  background: transparent;
+  color: var(--bf-appearance-token-color-text-secondary);
+  cursor: pointer;
+  font-family: var(--bf-appearance-token-font-family-sans);
+  font-size: 12px;
+  line-height: 1.3;
+  text-align: left;
+  transition: background $motion-fast $easing-standard,
+              color $motion-fast $easing-standard;
+
+  &:hover {
+    color: var(--bf-appearance-token-color-text-primary);
+    background: var(--bf-appearance-token-element-bg-soft);
+  }
+
+  &[data-bf-state='remote'] {
+    background: color-mix(in srgb, var(--bf-appearance-token-color-warning) 14%, transparent);
+    color: var(--bf-appearance-token-color-text-primary);
+
+    .bitfun-device-switcher__icon {
+      color: var(--bf-appearance-token-color-warning);
+    }
+
+    &:hover {
+      background: color-mix(in srgb, var(--bf-appearance-token-color-warning) 20%, transparent);
+    }
+  }
+
+  &__icon {
+    flex-shrink: 0;
+
+    &.is-spinning {
+      animation: bitfun-device-switcher-spin 1s linear infinite;
+    }
+  }
+
+  &__label {
+    flex: 1 1 auto;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  &__elsewhere {
+    display: inline-flex;
+    align-items: center;
+    gap: 3px;
+    flex-shrink: 0;
+    padding: 1px 5px;
+    border-radius: $size-radius-sm;
+    background: color-mix(in srgb, var(--bf-appearance-token-color-success) 18%, transparent);
+    color: var(--bf-appearance-token-color-success);
+    font-size: 10px;
+    font-variant-numeric: tabular-nums;
+  }
+
+  &__chevron {
+    flex-shrink: 0;
+    opacity: 0.6;
+  }
+
+  &__backdrop {
+    position: fixed;
+    inset: 0;
+    z-index: 9998;
+  }
+
+  &__menu {
+    position: fixed;
+    min-width: 216px;
+    max-width: calc(100vw - 16px);
+    max-height: calc(100vh - 16px);
+    overflow-y: auto;
+    padding: $size-gap-1;
+    background: var(--bf-appearance-token-color-bg-elevated);
+    border: 1px solid var(--bf-appearance-token-border-subtle);
+    border-radius: $size-radius-base;
+    box-shadow: 0 4px 12px var(--bf-appearance-token-color-overlay-black-30);
+    z-index: 9999;
+    color: var(--bf-appearance-token-color-text-primary);
+    font-family: var(--bf-appearance-token-font-family-sans);
+    font-size: var(--bf-appearance-token-font-size-sm);
+  }
+
+  &__menu-title {
+    padding: $size-gap-1 $size-gap-2;
+    color: var(--bf-appearance-token-color-text-muted);
+    font-size: 11px;
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+  }
+
+  &__item {
+    display: flex;
+    align-items: center;
+    gap: $size-gap-1;
+    border-radius: $size-radius-sm;
+
+    &:hover {
+      background: var(--bf-appearance-token-element-bg-soft);
+    }
+
+    &.is-offline {
+      opacity: 0.45;
+    }
+  }
+
+  &__item-main {
+    display: flex;
+    align-items: center;
+    gap: $size-gap-2;
+    flex: 1 1 auto;
+    min-width: 0;
+    height: 30px;
+    padding: 0 $size-gap-2;
+    border: none;
+    border-radius: $size-radius-sm;
+    background: transparent;
+    color: var(--bf-appearance-token-color-text-secondary);
+    cursor: pointer;
+    font-size: var(--bf-appearance-token-font-size-sm);
+    text-align: left;
+
+    &:disabled {
+      cursor: default;
+    }
+
+    &:focus-visible {
+      outline: 2px solid var(--bf-appearance-token-color-accent-500);
+      outline-offset: -1px;
+    }
+  }
+
+  &__item.is-current &__item-main {
+    color: var(--bf-appearance-token-color-text-primary);
+  }
+
+  &__item-label {
+    flex: 1 1 auto;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  &__dot {
+    flex-shrink: 0;
+    width: 7px;
+    height: 7px;
+    border-radius: 50%;
+    background: var(--bf-appearance-token-color-success);
+
+    &.is-busy {
+      background: var(--bf-appearance-token-color-warning);
+      animation: bitfun-device-switcher-pulse 1.6s $easing-standard infinite;
+    }
+
+    &.is-offline {
+      background: var(--bf-appearance-token-color-text-muted);
+      animation: none;
+    }
+  }
+
+  &__tag {
+    flex-shrink: 0;
+    padding: 1px 5px;
+    border-radius: $size-radius-sm;
+    background: var(--bf-appearance-token-element-bg-soft);
+    color: var(--bf-appearance-token-color-text-muted);
+    font-size: 10px;
+    white-space: nowrap;
+
+    &.is-busy {
+      background: color-mix(in srgb, var(--bf-appearance-token-color-warning) 18%, transparent);
+      color: var(--bf-appearance-token-color-warning);
+    }
+  }
+
+  &__item-disconnect {
+    flex-shrink: 0;
+    margin-right: $size-gap-1;
+    border: none;
+    background: transparent;
+    color: var(--bf-appearance-token-color-text-muted);
+    cursor: pointer;
+    font-size: 11px;
+    padding: 0 2px;
+    text-decoration: underline;
+
+    &:hover {
+      color: var(--bf-appearance-token-color-warning);
+    }
+
+    &:disabled {
+      cursor: default;
+      opacity: 0.5;
+    }
+  }
+
+  &__empty,
+  &__hint {
+    padding: $size-gap-1 $size-gap-2;
+    color: var(--bf-appearance-token-color-text-muted);
+    font-size: 11px;
+    line-height: 1.4;
+  }
+
+  &__hint {
+    margin-top: $size-gap-1;
+    border-top: 1px solid var(--bf-appearance-token-border-subtle);
+    padding-top: $size-gap-2;
+  }
+}
+
+@keyframes bitfun-device-switcher-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+@keyframes bitfun-device-switcher-pulse {
+  0%,
+  100% {
+    opacity: 1;
+  }
+
+  50% {
+    opacity: 0.35;
+  }
+}
+
+// The spinner and the busy pulse are the only motion here and both loop
+// forever; state stays readable from colour and copy without them.
+@media (prefers-reduced-motion: reduce) {
+  .bitfun-device-switcher__icon.is-spinning,
+  .bitfun-device-switcher__dot.is-busy {
+    animation: none;
+  }
+}
diff --git a/src/web-ui/src/infrastructure/peer-device/DeviceSurfaceSwitcher.tsx b/src/web-ui/src/infrastructure/peer-device/DeviceSurfaceSwitcher.tsx
new file mode 100644
index 0000000000..9a497bef9f
--- /dev/null
+++ b/src/web-ui/src/infrastructure/peer-device/DeviceSurfaceSwitcher.tsx
@@ -0,0 +1,308 @@
+/**
+ * Device surface switcher — the account's devices, one click apart.
+ *
+ * Mounted as a full-width row above the NavPanel footer whenever an account is
+ * signed in. Picking a device only changes which one this window renders:
+ * every attached device keeps executing its own sessions, so work can be
+ * running on several machines at once.
+ */
+
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { Check, ChevronUp, Monitor, MonitorSmartphone, Loader2 } from 'lucide-react';
+import { useI18n } from '@/infrastructure/i18n/hooks/useI18n';
+import { useNotification } from '@/shared/notification-system';
+import { getAppearanceOverlayHost } from '@/infrastructure/appearance/runtime/AppearanceOverlayHost';
+import { useAnchoredPopoverPosition } from '@/shared/utils/useAnchoredPopoverPosition';
+import { usePeerDeviceModeOptional } from './peerDeviceContextState';
+import { useAccountDeviceRoster, type DeviceRosterEntry } from './useAccountDeviceRoster';
+import { isDeviceBusy, subscribeDeviceActivity } from './deviceActivity';
+import './DeviceSurfaceSwitcher.scss';
+
+/** Re-render on any activity change; the roster is small enough to recompute. */
+function useDeviceActivityVersion(): number {
+  const [version, setVersion] = useState(0);
+  useEffect(() => subscribeDeviceActivity(() => setVersion(v => v + 1)), []);
+  return version;
+}
+
+export const DeviceSurfaceSwitcher: React.FC = () => {
+  const { t } = useI18n('common');
+  const { success, warning } = useNotification();
+  const peerDevice = usePeerDeviceModeOptional();
+  const { loggedIn, localDeviceId, devices } = useAccountDeviceRoster();
+  const activityVersion = useDeviceActivityVersion();
+
+  const [open, setOpen] = useState(false);
+  const [switching, setSwitching] = useState(false);
+  const latestSwitchRequestRef = useRef(0);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const popoverRef = useRef<HTMLDivElement>(null);
+  const layout = useAnchoredPopoverPosition({
+    open,
+    anchorRef: triggerRef,
+    popoverRef,
+    preferredPlacement: 'top',
+    alignment: 'start',
+    gap: 6,
+  });
+
+  const peerMode = peerDevice?.peerMode;
+  const attachments = peerDevice?.attachments;
+  const activeDeviceId = peerMode?.active ? peerMode.deviceId : localDeviceId;
+
+  const attachedIds = useMemo(
+    () => new Set((attachments ?? []).map(attachment => attachment.deviceId)),
+    [attachments],
+  );
+
+  /** Activity key: the rendered local device reports under `null`. */
+  const activityKeyFor = useCallback(
+    (device: DeviceRosterEntry) => (device.isLocal ? null : device.deviceId),
+    [],
+  );
+
+  const busyElsewhereCount = useMemo(() => {
+    void activityVersion;
+    return devices.filter(
+      device => device.deviceId !== activeDeviceId && isDeviceBusy(activityKeyFor(device)),
+    ).length;
+  }, [devices, activeDeviceId, activityKeyFor, activityVersion]);
+
+  const currentDevice = useMemo(
+    () => devices.find(device => device.deviceId === activeDeviceId) ?? null,
+    [devices, activeDeviceId],
+  );
+
+  const currentLabel = peerMode?.active
+    ? peerMode.deviceName
+    : currentDevice?.deviceName ?? t('accountLogin.thisDevice');
+
+  const handleSelect = useCallback(async (device: DeviceRosterEntry) => {
+    if (!peerDevice) {
+      return;
+    }
+    setOpen(false);
+    // While another target is still activating, selecting the rendered device
+    // is meaningful: it supersedes that activation (A -> B -> A).
+    if (device.deviceId === activeDeviceId && !switching) {
+      return;
+    }
+    const requestId = ++latestSwitchRequestRef.current;
+    setSwitching(true);
+    try {
+      let outcome: 'activated' | 'superseded';
+      if (device.isLocal) {
+        outcome = await peerDevice.switchToLocal();
+        if (outcome === 'activated' && latestSwitchRequestRef.current === requestId) {
+          success(t('accountLogin.deviceSwitcher.switchedLocal'));
+        }
+      } else {
+        outcome = await peerDevice.switchToDevice(device.deviceId, device.deviceName);
+        if (outcome === 'activated' && latestSwitchRequestRef.current === requestId) {
+          success(t('accountLogin.deviceSwitcher.switched', { name: device.deviceName }));
+        }
+      }
+    } catch (error) {
+      if (latestSwitchRequestRef.current === requestId) {
+        warning(error instanceof Error ? error.message : String(error));
+      }
+    } finally {
+      if (latestSwitchRequestRef.current === requestId) {
+        setSwitching(false);
+      }
+    }
+  }, [peerDevice, switching, activeDeviceId, success, warning, t]);
+
+  const handleDisconnect = useCallback(async (
+    event: React.MouseEvent,
+    device: DeviceRosterEntry,
+  ) => {
+    event.stopPropagation();
+    if (!peerDevice || switching) {
+      return;
+    }
+    setSwitching(true);
+    try {
+      await peerDevice.disconnectDevice(device.deviceId);
+      success(t('accountLogin.deviceSwitcher.disconnected', { name: device.deviceName }));
+    } catch (error) {
+      warning(error instanceof Error ? error.message : String(error));
+    } finally {
+      setSwitching(false);
+    }
+  }, [peerDevice, switching, success, warning, t]);
+
+  useEffect(() => {
+    if (!open) {
+      return;
+    }
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        setOpen(false);
+      }
+    };
+    window.addEventListener('keydown', onKeyDown);
+    return () => window.removeEventListener('keydown', onKeyDown);
+  }, [open]);
+
+  if (!loggedIn || !peerDevice) {
+    return null;
+  }
+
+  const isRemote = peerMode?.active === true;
+
+  return (
+    <>
+      <button
+        ref={triggerRef}
+        type="button"
+        className="bitfun-device-switcher"
+        data-testid="device-surface-switcher"
+        data-bf-component="peer-device"
+        data-bf-part="switcher"
+        data-bf-state={isRemote ? 'remote' : 'local'}
+        aria-expanded={open}
+        aria-label={t('accountLogin.deviceSwitcher.open')}
+        title={t('accountLogin.deviceSwitcher.open')}
+        onClick={() => setOpen(value => !value)}
+      >
+        {switching ? (
+          <Loader2 size={13} className="bitfun-device-switcher__icon is-spinning" aria-hidden="true" />
+        ) : (
+          <Monitor size={13} className="bitfun-device-switcher__icon" aria-hidden="true" />
+        )}
+        <span
+          className="bitfun-device-switcher__label"
+          data-bf-component="peer-device"
+          data-bf-part="switcherLabel"
+        >
+          {currentLabel}
+        </span>
+        {busyElsewhereCount > 0 && (
+          <span
+            className="bitfun-device-switcher__elsewhere"
+            data-bf-component="peer-device"
+            data-bf-part="switcherElsewhere"
+            title={t('accountLogin.deviceSwitcher.othersRunning', { count: busyElsewhereCount })}
+          >
+            <MonitorSmartphone size={11} aria-hidden="true" />
+            {busyElsewhereCount}
+          </span>
+        )}
+        <ChevronUp size={13} className="bitfun-device-switcher__chevron" aria-hidden="true" />
+      </button>
+
+      {open && createPortal(
+        <>
+          <div
+            className="bitfun-device-switcher__backdrop"
+            onClick={() => setOpen(false)}
+          />
+          <div
+            ref={popoverRef}
+            className="bitfun-device-switcher__menu"
+            role="menu"
+            data-testid="device-surface-switcher-menu"
+            data-bf-component="peer-device"
+            data-bf-part="switcherMenu"
+            style={{
+              top: `${layout?.top ?? 0}px`,
+              left: `${layout?.left ?? 0}px`,
+              visibility: layout ? 'visible' : 'hidden',
+            }}
+          >
+            <div className="bitfun-device-switcher__menu-title">
+              {t('accountLogin.deviceSwitcher.title')}
+            </div>
+
+            {devices.map(device => {
+              const isCurrent = device.deviceId === activeDeviceId;
+              const busy = isDeviceBusy(activityKeyFor(device));
+              const attached = attachedIds.has(device.deviceId);
+              const selectable = device.online && (!isCurrent || switching);
+              return (
+                <div
+                  key={device.deviceId}
+                  className={[
+                    'bitfun-device-switcher__item',
+                    isCurrent && 'is-current',
+                    !device.online && 'is-offline',
+                  ].filter(Boolean).join(' ')}
+                  data-bf-component="peer-device"
+                  data-bf-part="switcherItem"
+                >
+                  <button
+                    type="button"
+                    role="menuitem"
+                    className="bitfun-device-switcher__item-main"
+                    disabled={!selectable}
+                    onClick={() => { void handleSelect(device); }}
+                  >
+                    <span
+                      className={[
+                        'bitfun-device-switcher__dot',
+                        busy && 'is-busy',
+                        !device.online && 'is-offline',
+                      ].filter(Boolean).join(' ')}
+                      data-bf-component="peer-device"
+                      data-bf-part="switcherStatusDot"
+                      data-bf-state={[
+                        busy && 'busy',
+                        !device.online && 'offline',
+                      ].filter(Boolean).join(' ') || undefined}
+                      aria-hidden="true"
+                    />
+                    <span className="bitfun-device-switcher__item-label">{device.deviceName}</span>
+                    {device.isLocal && (
+                      <span className="bitfun-device-switcher__tag">
+                        {t('accountLogin.thisDevice')}
+                      </span>
+                    )}
+                    {busy && (
+                      <span className="bitfun-device-switcher__tag is-busy">
+                        {t('accountLogin.deviceSwitcher.running')}
+                      </span>
+                    )}
+                    {!device.online && (
+                      <span className="bitfun-device-switcher__tag">
+                        {t('accountLogin.offline')}
+                      </span>
+                    )}
+                    {isCurrent && <Check size={13} aria-hidden="true" />}
+                  </button>
+                  {attached && (
+                    <button
+                      type="button"
+                      className="bitfun-device-switcher__item-disconnect"
+                      data-bf-component="peer-device"
+                      data-bf-part="switcherDisconnect"
+                      disabled={switching}
+                      title={t('accountLogin.deviceSwitcher.disconnectHint')}
+                      onClick={(event) => { void handleDisconnect(event, device); }}
+                    >
+                      {t('accountLogin.disconnectPeer')}
+                    </button>
+                  )}
+                </div>
+              );
+            })}
+
+            {devices.length <= 1 && (
+              <div className="bitfun-device-switcher__empty">
+                {t('accountLogin.deviceSwitcher.noDevices')}
+              </div>
+            )}
+
+            <div className="bitfun-device-switcher__hint">
+              {t('accountLogin.deviceSwitcher.hint')}
+            </div>
+          </div>
+        </>,
+        getAppearanceOverlayHost(),
+      )}
+    </>
+  );
+};
+
+export default DeviceSurfaceSwitcher;
diff --git a/src/web-ui/src/infrastructure/peer-device/PeerConnectionManager.test.ts b/src/web-ui/src/infrastructure/peer-device/PeerConnectionManager.test.ts
new file mode 100644
index 0000000000..bfc2a7778e
--- /dev/null
+++ b/src/web-ui/src/infrastructure/peer-device/PeerConnectionManager.test.ts
@@ -0,0 +1,398 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  PeerConnectionManager,
+  type PeerConnectionState,
+} from './PeerConnectionManager';
+
+const KEEPALIVE_MS = 20_000;
+const RECONNECT_BASE_MS = 1_000;
+const RECONNECT_MAX_MS = 4_000;
+
+describe('PeerConnectionManager attach', () => {
+  beforeEach(() => vi.useFakeTimers());
+  afterEach(() => vi.useRealTimers());
+
+  it('negotiates capabilities and attaches control in one handshake', async () => {
+    const rpc = createRpc();
+    const manager = createManager(rpc.deviceRpc);
+
+    const connection = await manager.connect('peer-1', 'Studio');
+
+    expect(rpc.commands()).toEqual(['peer_mode_ping', 'peer_control_attach']);
+    expect(rpc.args('peer_control_attach')).toEqual({ controller_device_id: 'controller-1' });
+    expect(connection.surfaceId).toBe('peer-1');
+    expect(connection.getState()).toMatchObject({
+      deviceName: 'Studio',
+      health: 'ready',
+      capabilities: { idempotentDialogSubmit: true, targetedSessionRollback: false },
+    });
+    expect(manager.get('peer-1')).toBe(connection);
+  });
+
+  it('leaves nothing attached when the handshake fails', async () => {
+    const rpc = createRpc({ failCommands: new Set(['peer_control_attach']) });
+    const manager = createManager(rpc.deviceRpc);
+
+    await expect(manager.connect('peer-1', 'Studio')).rejects.toThrow('peer refused');
+
+    expect(manager.get('peer-1')).toBeUndefined();
+    expect(manager.list()).toEqual([]);
+  });
+
+  it('reuses one attachment for concurrent callers', async () => {
+    const rpc = createRpc();
+    const manager = createManager(rpc.deviceRpc);
+
+    const [first, second] = await Promise.all([
+      manager.connect('peer-1', 'Studio'),
+      manager.connect('peer-1', 'Studio'),
+    ]);
+
+    expect(first).toBe(second);
+    expect(rpc.commands().filter(c => c === 'peer_control_attach')).toHaveLength(1);
+  });
+
+  it('orders detach after a handshake that was disposed in flight', async () => {
+    const ping = deferred<string>();
+    const commands: string[] = [];
+    const deviceRpc = vi.fn(async (_target: string, commandJson: string): Promise<string> => {
+      const command = (JSON.parse(commandJson) as { command?: string }).command ?? 'unknown';
+      commands.push(command);
+      if (command === 'peer_mode_ping') {
+        return ping.promise;
+      }
+      return JSON.stringify({ resp: 'host_invoke_result', ok: true, value: null });
+    });
+    const manager = createManager(deviceRpc);
+
+    const connecting = manager.connect('peer-1', 'Studio');
+    await vi.waitFor(() => expect(commands).toEqual(['peer_mode_ping']));
+    const disposing = manager.dispose('peer-1');
+    ping.resolve(JSON.stringify({
+      resp: 'host_invoke_result',
+      ok: true,
+      value: { capabilities: {} },
+    }));
+
+    await expect(connecting).rejects.toThrow('disposed during attachment');
+    await disposing;
+    expect(commands).toEqual(['peer_mode_ping', 'peer_control_detach']);
+    expect(manager.get('peer-1')).toBeUndefined();
+  });
+});
+
+describe('PeerConnectionManager health', () => {
+  beforeEach(() => vi.useFakeTimers());
+  afterEach(() => vi.useRealTimers());
+
+  it('degrades on a single missed ping instead of tearing the peer down', async () => {
+    const rpc = createRpc();
+    const manager = createManager(rpc.deviceRpc);
+    const seen = observe(manager);
+    await manager.connect('peer-1', 'Studio');
+
+    rpc.failNext(1);
+    await vi.advanceTimersByTimeAsync(KEEPALIVE_MS);
+
+    expect(manager.get('peer-1')?.getState()).toMatchObject({
+      health: 'degraded',
+      consecutiveFailures: 1,
+    });
+    expect(seen.healthTimeline()).toEqual(['connecting', 'ready', 'degraded']);
+  });
+
+  it('reconnects with exponential backoff while degraded', async () => {
+    const rpc = createRpc();
+    const manager = createManager(rpc.deviceRpc, { maxKeepaliveFailures: 4 });
+    await manager.connect('peer-1', 'Studio');
+
+    rpc.failNext(2);
+    await vi.advanceTimersByTimeAsync(KEEPALIVE_MS);
+    const afterFirstFailure = rpc.commands().length;
+
+    // 1s, then 2s: nothing is retried before that attempt's delay elapses.
+    await vi.advanceTimersByTimeAsync(RECONNECT_BASE_MS - 1);
+    expect(rpc.commands().length).toBe(afterFirstFailure);
+    await vi.advanceTimersByTimeAsync(1);
+    expect(rpc.commands().length).toBe(afterFirstFailure + 1);
+
+    await vi.advanceTimersByTimeAsync(RECONNECT_BASE_MS * 2 - 1);
+    expect(rpc.commands().length).toBe(afterFirstFailure + 1);
+    await vi.advanceTimersByTimeAsync(1);
+
+    // The third attempt answers, so the peer recovers and the delay resets.
+    expect(manager.get('peer-1')?.getState()).toMatchObject({
+      health: 'ready',
+      consecutiveFailures: 0,
+    });
+    // A recovered peer re-attaches: the host may have pruned us during the gap.
+    expect(rpc.commands().filter(c => c === 'peer_control_attach')).toHaveLength(2);
+  });
+
+  it('caps the reconnect delay', async () => {
+    const rpc = createRpc();
+    const manager = createManager(rpc.deviceRpc, { maxKeepaliveFailures: 6 });
+    await manager.connect('peer-1', 'Studio');
+
+    rpc.failNext(5);
+    await vi.advanceTimersByTimeAsync(KEEPALIVE_MS);
+    // Failures 1..4 back off 1s, 2s, 4s, 4s — the fourth is already capped.
+    await vi.advanceTimersByTimeAsync(RECONNECT_BASE_MS + RECONNECT_BASE_MS * 2 + RECONNECT_MAX_MS);
+    const beforeCappedAttempt = rpc.commands().length;
+
+    await vi.advanceTimersByTimeAsync(RECONNECT_MAX_MS);
+
+    expect(rpc.commands().length).toBe(beforeCappedAttempt + 1);
+    expect(manager.get('peer-1')?.getState().consecutiveFailures).toBe(5);
+  });
+
+  it('loses a peer after repeated failures and stops retrying', async () => {
+    const rpc = createRpc();
+    const manager = createManager(rpc.deviceRpc);
+    await manager.connect('peer-1', 'Studio');
+
+    rpc.failAll();
+    await vi.advanceTimersByTimeAsync(KEEPALIVE_MS + RECONNECT_BASE_MS + RECONNECT_BASE_MS * 2);
+
+    expect(manager.get('peer-1')?.getState()).toMatchObject({
+      health: 'lost',
+      lostReason: 'keepalive',
+      consecutiveFailures: 3,
+    });
+
+    const afterLoss = rpc.commands().length;
+    await vi.advanceTimersByTimeAsync(KEEPALIVE_MS * 5);
+    expect(rpc.commands().length).toBe(afterLoss);
+  });
+
+  it('loses a peer that dropped out of account presence', async () => {
+    const rpc = createRpc();
+    const manager = createManager(rpc.deviceRpc);
+    await manager.connect('peer-1', 'Studio');
+
+    manager.reportPresence(['peer-2']);
+
+    expect(manager.get('peer-1')?.getState()).toMatchObject({
+      health: 'lost',
+      lostReason: 'presence',
+    });
+
+    const afterLoss = rpc.commands().length;
+    await vi.advanceTimersByTimeAsync(KEEPALIVE_MS * 3);
+    expect(rpc.commands().length).toBe(afterLoss);
+  });
+
+  it('treats successful product traffic as proof the link is alive', async () => {
+    const rpc = createRpc();
+    const manager = createManager(rpc.deviceRpc);
+    const connection = await manager.connect('peer-1', 'Studio');
+
+    rpc.failNext(1);
+    await vi.advanceTimersByTimeAsync(KEEPALIVE_MS);
+    expect(connection.getState().health).toBe('degraded');
+
+    await connection.adapter.request('get_opened_workspaces', { request: {} });
+
+    expect(connection.getState()).toMatchObject({ health: 'ready', consecutiveFailures: 0 });
+    await vi.waitFor(() => {
+      expect(rpc.commands().filter(c => c === 'peer_control_attach')).toHaveLength(2);
+    });
+  });
+
+  it('degrades after a product transport failure instead of waiting for keepalive', async () => {
+    const rpc = createRpc();
+    const manager = createManager(rpc.deviceRpc);
+    const connection = await manager.connect('peer-1', 'Studio');
+
+    rpc.failNext(1);
+    await expect(connection.adapter.request('set_config', {
+      request: { path: 'ui.theme', value: 'dark' },
+    })).rejects.toThrow('relay unavailable');
+
+    expect(connection.getState()).toMatchObject({
+      health: 'degraded',
+      consecutiveFailures: 1,
+    });
+  });
+});
+
+describe('PeerConnectionManager disposal', () => {
+  beforeEach(() => vi.useFakeTimers());
+  afterEach(() => vi.useRealTimers());
+
+  it('detaches, disposes the transport, and drops the entry', async () => {
+    const rpc = createRpc();
+    const manager = createManager(rpc.deviceRpc);
+    const connection = await manager.connect('peer-1', 'Studio');
+
+    await manager.dispose('peer-1');
+
+    expect(rpc.commands()).toContain('peer_control_detach');
+    expect(connection.adapter.isDisposed()).toBe(true);
+    expect(manager.get('peer-1')).toBeUndefined();
+    expect(manager.list()).toEqual([]);
+
+    const afterDispose = rpc.commands().length;
+    await vi.advanceTimersByTimeAsync(KEEPALIVE_MS * 3);
+    expect(rpc.commands().length).toBe(afterDispose);
+  });
+
+  it('skips the detach RPC for a peer that is already gone', async () => {
+    const rpc = createRpc();
+    const manager = createManager(rpc.deviceRpc);
+    await manager.connect('peer-1', 'Studio');
+
+    await manager.dispose('peer-1', { notifyPeer: false });
+
+    expect(rpc.commands()).not.toContain('peer_control_detach');
+  });
+
+  it('settles transport work still waiting on a disposed peer', async () => {
+    const rpc = createRpc();
+    const manager = createManager(rpc.deviceRpc);
+    const connection = await manager.connect('peer-1', 'Studio');
+
+    rpc.hangNext();
+    const pending = connection.adapter.request('list_persisted_sessions_page', {
+      request: { workspacePath: '/repo' },
+    });
+    const settled = pending.then(() => 'resolved', () => 'rejected');
+
+    await manager.dispose('peer-1');
+
+    await expect(settled).resolves.toBe('rejected');
+  });
+
+  it('orders detach after a recovery re-attach already in flight', async () => {
+    const reattach = deferred<string>();
+    const commands: string[] = [];
+    let failNextPing = false;
+    let attachCount = 0;
+    const deviceRpc = vi.fn(async (_target: string, commandJson: string): Promise<string> => {
+      const command = (JSON.parse(commandJson) as { command?: string }).command ?? 'unknown';
+      commands.push(command);
+      if (command === 'peer_mode_ping' && failNextPing) {
+        failNextPing = false;
+        throw new Error('relay unavailable');
+      }
+      if (command === 'peer_control_attach' && ++attachCount === 2) {
+        return reattach.promise;
+      }
+      if (command === 'peer_mode_ping') {
+        return JSON.stringify({
+          resp: 'host_invoke_result',
+          ok: true,
+          value: { capabilities: {} },
+        });
+      }
+      return JSON.stringify({ resp: 'host_invoke_result', ok: true, value: null });
+    });
+    const manager = createManager(deviceRpc);
+    const connection = await manager.connect('peer-1', 'Studio');
+
+    failNextPing = true;
+    await vi.advanceTimersByTimeAsync(KEEPALIVE_MS);
+    await connection.adapter.request('get_opened_workspaces', { request: {} });
+    await vi.waitFor(() => {
+      expect(commands.filter(command => command === 'peer_control_attach')).toHaveLength(2);
+    });
+
+    const disposing = manager.dispose('peer-1');
+    await Promise.resolve();
+    expect(commands).not.toContain('peer_control_detach');
+
+    reattach.resolve(JSON.stringify({ resp: 'host_invoke_result', ok: true, value: null }));
+    await disposing;
+    expect(commands.at(-1)).toBe('peer_control_detach');
+  });
+});
+
+function createManager(
+  deviceRpc: ReturnType<typeof createRpc>['deviceRpc'],
+  overrides: { maxKeepaliveFailures?: number } = {},
+): PeerConnectionManager {
+  return new PeerConnectionManager({
+    deviceRpc,
+    getControllerDeviceId: async () => 'controller-1',
+    keepaliveIntervalMs: KEEPALIVE_MS,
+    reconnectBaseDelayMs: RECONNECT_BASE_MS,
+    reconnectMaxDelayMs: RECONNECT_MAX_MS,
+    maxKeepaliveFailures: overrides.maxKeepaliveFailures ?? 3,
+  });
+}
+
+interface RpcCall {
+  command: string;
+  args: Record<string, unknown>;
+}
+
+function createRpc(options: { failCommands?: Set<string> } = {}) {
+  const calls: RpcCall[] = [];
+  let remainingFailures = 0;
+  let hangNext = false;
+
+  const deviceRpc = vi.fn(async (_target: string, commandJson: string): Promise<string> => {
+    const parsed = JSON.parse(commandJson) as {
+      command?: string;
+      args?: Record<string, unknown>;
+    };
+    const command = parsed.command ?? 'unknown';
+    calls.push({ command, args: parsed.args ?? {} });
+
+    if (hangNext) {
+      hangNext = false;
+      return new Promise<string>(() => {
+        // Models a relay request that never settles.
+      });
+    }
+    if (options.failCommands?.has(command)) {
+      throw new Error('peer refused');
+    }
+    if (remainingFailures > 0) {
+      remainingFailures -= 1;
+      throw new Error('relay unavailable');
+    }
+    if (command === 'peer_mode_ping') {
+      return JSON.stringify({
+        resp: 'host_invoke_result',
+        ok: true,
+        value: { capabilities: { idempotent_dialog_submit: true } },
+      });
+    }
+    return JSON.stringify({ resp: 'host_invoke_result', ok: true, value: null });
+  });
+
+  return {
+    deviceRpc,
+    commands: () => calls.map(call => call.command),
+    args: (command: string) => calls.find(call => call.command === command)?.args,
+    failNext: (count: number) => {
+      remainingFailures = count;
+    },
+    failAll: () => {
+      remainingFailures = Number.MAX_SAFE_INTEGER;
+    },
+    hangNext: () => {
+      hangNext = true;
+    },
+  };
+}
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>(res => {
+    resolve = res;
+  });
+  return { promise, resolve };
+}
+
+function observe(manager: PeerConnectionManager) {
+  const updates: PeerConnectionState[][] = [];
+  manager.subscribe(states => updates.push(states.map(state => ({ ...state }))));
+  return {
+    healthTimeline: () => updates
+      .map(states => states[0]?.health)
+      .filter((health, index, all): health is PeerConnectionState['health'] =>
+        health !== undefined && health !== all[index - 1]),
+  };
+}
diff --git a/src/web-ui/src/infrastructure/peer-device/PeerConnectionManager.ts b/src/web-ui/src/infrastructure/peer-device/PeerConnectionManager.ts
new file mode 100644
index 0000000000..0cf567caa3
--- /dev/null
+++ b/src/web-ui/src/infrastructure/peer-device/PeerConnectionManager.ts
@@ -0,0 +1,547 @@
+/**
+ * Peer connection lifecycle, outside React.
+ *
+ * Attaching to a peer is a long-lived state machine — handshake, capability
+ * negotiation, keepalive, backoff, teardown — and it has to outlive whatever is
+ * on screen: attachments survive surface switches, keep running our work, and
+ * must not restart because a provider re-rendered. Expressed as effects it
+ * became several timers and async closures racing over refs, where a switch
+ * during a reconnect could leave a peer attached with no keepalive, or detached
+ * with a timer still firing.
+ *
+ * So the lifecycle lives here as plain state with explicit transitions, and
+ * React only subscribes: `subscribe()` + `list()` feed a component, `get()`
+ * hands back the transport adapter, `dispose()` tears one down deterministically.
+ * Nothing in this file may import React.
+ */
+
+import { PeerDeviceTransportAdapter } from '@/infrastructure/api/adapters/peer-device-adapter';
+import { remoteConnectAPI } from '@/infrastructure/api/service-api/RemoteConnectAPI';
+import { createLogger } from '@/shared/utils/logger';
+import type { DeviceSurfaceId } from './deviceSurface';
+
+const log = createLogger('PeerConnectionManager');
+
+export const PEER_CONTROL_RPC_TIMEOUT_MS = 15_000;
+export const PEER_KEEPALIVE_INTERVAL_MS = 20_000;
+/** Consecutive keepalive/reconnect failures tolerated before a peer is lost. */
+export const PEER_MAX_KEEPALIVE_FAILURES = 3;
+export const PEER_RECONNECT_BASE_DELAY_MS = 1_000;
+export const PEER_RECONNECT_MAX_DELAY_MS = 15_000;
+
+/**
+ * `connecting` → first handshake. `ready` → the peer answers. `degraded` → it
+ * missed at least one ping and we are retrying; the attachment is still valid
+ * and its work still runs. `lost` → terminal, nothing is retried; the consumer
+ * decides whether to dispose.
+ */
+export type PeerConnectionHealth = 'connecting' | 'ready' | 'degraded' | 'lost';
+
+export type PeerConnectionLostReason = 'keepalive' | 'presence';
+
+export interface PeerHostCapabilities {
+  readonly idempotentDialogSubmit: boolean;
+  readonly targetedSessionRollback: boolean;
+}
+
+/** Immutable view of one connection; safe to hold in component state. */
+export interface PeerConnectionState {
+  readonly deviceId: string;
+  readonly deviceName: string;
+  readonly surfaceId: DeviceSurfaceId;
+  readonly health: PeerConnectionHealth;
+  readonly capabilities: PeerHostCapabilities;
+  /** Failures since the last answered ping; drives the backoff schedule. */
+  readonly consecutiveFailures: number;
+  readonly lostReason: PeerConnectionLostReason | null;
+}
+
+/** Live handle. `adapter` is the product transport for this device. */
+export interface PeerConnection {
+  readonly deviceId: string;
+  readonly surfaceId: DeviceSurfaceId;
+  readonly adapter: PeerDeviceTransportAdapter;
+  getState(): PeerConnectionState;
+}
+
+export type PeerConnectionListener = (connections: readonly PeerConnectionState[]) => void;
+
+export type PeerDeviceRpc = (
+  targetDeviceId: string,
+  commandJson: string,
+  timeoutMs?: number,
+) => Promise<string>;
+
+export interface PeerConnectionManagerOptions {
+  deviceRpc?: PeerDeviceRpc;
+  getControllerDeviceId?: () => Promise<string>;
+  controlRpcTimeoutMs?: number;
+  keepaliveIntervalMs?: number;
+  maxKeepaliveFailures?: number;
+  reconnectBaseDelayMs?: number;
+  reconnectMaxDelayMs?: number;
+}
+
+export interface PeerDisposeOptions {
+  /**
+   * Send `peer_control_detach`. Skip it for a peer that is already gone — the
+   * host prunes the stale controller through presence instead.
+   */
+  notifyPeer?: boolean;
+}
+
+interface HostInvokeEnvelope {
+  resp?: string;
+  ok?: boolean;
+  value?: unknown;
+  error?: string;
+  message?: string;
+}
+
+interface PeerModePingResult {
+  capabilities?: {
+    idempotent_dialog_submit?: boolean;
+    targeted_session_rollback?: boolean;
+  };
+}
+
+const NO_CAPABILITIES: PeerHostCapabilities = {
+  idempotentDialogSubmit: false,
+  targetedSessionRollback: false,
+};
+
+interface ConnectionEntry {
+  deviceId: string;
+  deviceName: string;
+  adapter: PeerDeviceTransportAdapter;
+  health: PeerConnectionHealth;
+  capabilities: PeerHostCapabilities;
+  consecutiveFailures: number;
+  lostReason: PeerConnectionLostReason | null;
+  timer: ReturnType<typeof setTimeout> | null;
+  disposed: boolean;
+  reattachInFlight: Promise<void> | null;
+  handle: PeerConnection;
+}
+
+class PeerConnectionDisposedError extends Error {
+  constructor(deviceId: string) {
+    super(`Peer connection '${deviceId}' was disposed during attachment`);
+    this.name = 'PeerConnectionDisposedError';
+  }
+}
+
+export class PeerConnectionManager {
+  private readonly entries = new Map<string, ConnectionEntry>();
+  private readonly attaching = new Map<string, Promise<PeerConnection>>();
+  private readonly listeners = new Set<PeerConnectionListener>();
+  private readonly deviceRpc: PeerDeviceRpc;
+  private readonly resolveControllerDeviceId: () => Promise<string>;
+  private readonly controlRpcTimeoutMs: number;
+  private readonly keepaliveIntervalMs: number;
+  private readonly maxKeepaliveFailures: number;
+  private readonly reconnectBaseDelayMs: number;
+  private readonly reconnectMaxDelayMs: number;
+  private controllerDeviceId: string | null = null;
+  private snapshot: readonly PeerConnectionState[] = [];
+
+  constructor(options: PeerConnectionManagerOptions = {}) {
+    this.deviceRpc = options.deviceRpc
+      ?? ((target, commandJson, timeoutMs) =>
+        remoteConnectAPI.accountDeviceRpc(target, commandJson, timeoutMs));
+    this.resolveControllerDeviceId = options.getControllerDeviceId
+      ?? (async () => (await remoteConnectAPI.getDeviceInfo()).device_id);
+    this.controlRpcTimeoutMs = options.controlRpcTimeoutMs ?? PEER_CONTROL_RPC_TIMEOUT_MS;
+    this.keepaliveIntervalMs = options.keepaliveIntervalMs ?? PEER_KEEPALIVE_INTERVAL_MS;
+    this.maxKeepaliveFailures = options.maxKeepaliveFailures ?? PEER_MAX_KEEPALIVE_FAILURES;
+    this.reconnectBaseDelayMs = options.reconnectBaseDelayMs ?? PEER_RECONNECT_BASE_DELAY_MS;
+    this.reconnectMaxDelayMs = options.reconnectMaxDelayMs ?? PEER_RECONNECT_MAX_DELAY_MS;
+  }
+
+  /**
+   * Attach to `deviceId`, or return the existing connection. Attaching does not
+   * render the device; the caller decides what the window draws.
+   *
+   * Rejects (leaving nothing behind) when the handshake fails, so a caller can
+   * report the failure without first having to clean up a half-attached peer.
+   */
+  connect(deviceId: string, deviceName = ''): Promise<PeerConnection> {
+    if (!deviceId) {
+      return Promise.reject(new Error('deviceId is required'));
+    }
+    const existing = this.entries.get(deviceId);
+    if (existing) {
+      if (existing.health === 'lost') {
+        return Promise.reject(new Error(`Peer device '${deviceId}' is no longer reachable`));
+      }
+      this.renameEntry(existing, deviceName);
+      return Promise.resolve(existing.handle);
+    }
+    const inFlight = this.attaching.get(deviceId);
+    if (inFlight) {
+      return inFlight;
+    }
+    const attach = this.attach(deviceId, deviceName).finally(() => {
+      this.attaching.delete(deviceId);
+    });
+    this.attaching.set(deviceId, attach);
+    return attach;
+  }
+
+  get(deviceId: string): PeerConnection | undefined {
+    return this.entries.get(deviceId)?.handle;
+  }
+
+  has(deviceId: string): boolean {
+    return this.entries.has(deviceId);
+  }
+
+  /** Stable between changes, so a React consumer can compare by reference. */
+  list(): readonly PeerConnectionState[] {
+    return this.snapshot;
+  }
+
+  /** Listeners fire on change only; read `list()` for the current value. */
+  subscribe(listener: PeerConnectionListener): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /**
+   * End a control link for good: stop its timers, settle everything still
+   * waiting on its transport, then tell the peer.
+   *
+   * The detach RPC is last and its failure is re-thrown, because a peer that
+   * did not confirm may still be running our work — the caller decides whether
+   * that is worth surfacing. Local teardown has already completed either way.
+   */
+  async dispose(deviceId: string, options: PeerDisposeOptions = {}): Promise<void> {
+    const entry = this.entries.get(deviceId);
+    if (!entry) {
+      return;
+    }
+    entry.disposed = true;
+    this.entries.delete(deviceId);
+    this.cancelTimer(entry);
+    this.publish();
+
+    try {
+      await entry.adapter.disconnect();
+    } catch (error) {
+      log.warn('Peer transport teardown failed', { deviceId, error });
+    }
+
+    // If disposal raced the handshake, let the attach task observe `disposed`
+    // before the final detach. In particular, when `peer_control_attach` was
+    // already in flight, detach must be ordered after it or the late attach
+    // would resurrect a control link the controller considers closed.
+    await this.attaching.get(deviceId)?.catch(() => undefined);
+    await entry.reattachInFlight?.catch(() => undefined);
+
+    log.info('Peer connection disposed', { deviceId });
+
+    if (options.notifyPeer !== false) {
+      await this.hostInvoke(deviceId, 'peer_control_detach', {
+        controller_device_id: await this.controllerId(),
+      });
+    }
+  }
+
+  async disposeAll(options: PeerDisposeOptions = {}): Promise<void> {
+    for (const deviceId of Array.from(this.entries.keys())) {
+      try {
+        await this.dispose(deviceId, options);
+      } catch (error) {
+        log.warn('Failed to dispose peer connection', { deviceId, error });
+      }
+    }
+  }
+
+  /**
+   * Account presence is the authority on reachability: a peer that dropped off
+   * cannot be running our work, so no amount of backoff will help it.
+   */
+  reportPresence(onlineDeviceIds: Iterable<string>): void {
+    const online = new Set(onlineDeviceIds);
+    for (const entry of this.entries.values()) {
+      if (!online.has(entry.deviceId)) {
+        this.markLost(entry, 'presence');
+      }
+    }
+  }
+
+  private async attach(deviceId: string, deviceName: string): Promise<PeerConnection> {
+    const adapter = new PeerDeviceTransportAdapter(
+      deviceId,
+      (target, commandJson, timeoutMs) => this.deviceRpc(target, commandJson, timeoutMs),
+      {
+        // Successful product traffic proves the link as well as a ping does.
+        onHostInvokeSuccess: () => this.noteHealthy(deviceId),
+        onHostInvokeTransportFailure: error => {
+          const current = this.entries.get(deviceId);
+          if (current) {
+            this.noteFailure(current, error);
+          }
+        },
+      },
+    );
+    const entry: ConnectionEntry = {
+      deviceId,
+      deviceName,
+      adapter,
+      health: 'connecting',
+      capabilities: NO_CAPABILITIES,
+      consecutiveFailures: 0,
+      lostReason: null,
+      timer: null,
+      disposed: false,
+      reattachInFlight: null,
+      handle: {
+        deviceId,
+        surfaceId: adapter.surfaceId,
+        adapter,
+        getState: () => this.stateOf(entry),
+      },
+    };
+    this.entries.set(deviceId, entry);
+    this.publish();
+
+    try {
+      await adapter.connect();
+      this.assertEntryActive(entry);
+      entry.capabilities = await this.probeCapabilities(deviceId);
+      this.assertEntryActive(entry);
+      await this.sendAttach(deviceId);
+      this.assertEntryActive(entry);
+    } catch (error) {
+      if (this.entries.get(deviceId) === entry) {
+        this.entries.delete(deviceId);
+      }
+      await adapter.disconnect().catch(() => undefined);
+      this.publish();
+      throw error;
+    }
+
+    adapter.setHostCapabilities({
+      supportsIdempotentDialogSubmit: entry.capabilities.idempotentDialogSubmit,
+      supportsTargetedSessionRollback: entry.capabilities.targetedSessionRollback,
+    });
+    entry.health = 'ready';
+    this.scheduleKeepalive(entry);
+    this.publish();
+    log.info('Peer connection ready', { deviceId, capabilities: entry.capabilities });
+    return entry.handle;
+  }
+
+  private async probeCapabilities(deviceId: string): Promise<PeerHostCapabilities> {
+    const result = await this.hostInvoke<PeerModePingResult>(deviceId, 'peer_mode_ping', {});
+    return {
+      idempotentDialogSubmit: result?.capabilities?.idempotent_dialog_submit === true,
+      targetedSessionRollback: result?.capabilities?.targeted_session_rollback === true,
+    };
+  }
+
+  private async sendAttach(deviceId: string): Promise<void> {
+    await this.hostInvoke(deviceId, 'peer_control_attach', {
+      controller_device_id: await this.controllerId(),
+    });
+  }
+
+  private scheduleKeepalive(entry: ConnectionEntry): void {
+    this.cancelTimer(entry);
+    entry.timer = setTimeout(() => {
+      entry.timer = null;
+      void this.runHealthCheck(entry);
+    }, this.keepaliveIntervalMs);
+  }
+
+  /**
+   * Backoff is driven by the failure count, so a peer that keeps missing pings
+   * is polled progressively less often instead of hammering a weak relay.
+   */
+  private scheduleReconnect(entry: ConnectionEntry): void {
+    this.cancelTimer(entry);
+    const delayMs = Math.min(
+      this.reconnectBaseDelayMs * (2 ** Math.max(0, entry.consecutiveFailures - 1)),
+      this.reconnectMaxDelayMs,
+    );
+    entry.timer = setTimeout(() => {
+      entry.timer = null;
+      void this.runHealthCheck(entry);
+    }, delayMs);
+  }
+
+  /**
+   * One probe covers both roles: while `ready` it is the keepalive, while
+   * `degraded` it is the reconnect attempt. A degraded peer re-sends
+   * `peer_control_attach` because the host may have pruned this controller
+   * during the gap that made us degraded in the first place.
+   */
+  private async runHealthCheck(entry: ConnectionEntry): Promise<void> {
+    if (this.entries.get(entry.deviceId) !== entry || entry.health === 'lost') {
+      return;
+    }
+    const reconnecting = entry.health === 'degraded';
+    try {
+      const capabilities = await this.probeCapabilities(entry.deviceId);
+      if (reconnecting) {
+        await this.sendAttach(entry.deviceId);
+      }
+      if (this.entries.get(entry.deviceId) !== entry) {
+        return;
+      }
+      entry.capabilities = capabilities;
+      entry.adapter.setHostCapabilities({
+        supportsIdempotentDialogSubmit: capabilities.idempotentDialogSubmit,
+        supportsTargetedSessionRollback: capabilities.targetedSessionRollback,
+      });
+      entry.consecutiveFailures = 0;
+      const recovered = entry.health !== 'ready';
+      entry.health = 'ready';
+      this.scheduleKeepalive(entry);
+      if (recovered) {
+        log.info('Peer connection recovered', { deviceId: entry.deviceId });
+        this.publish();
+      }
+    } catch (error) {
+      this.noteFailure(entry, error);
+    }
+  }
+
+  /**
+   * A single miss on a weak link must not drop a peer that is mid-turn, so the
+   * first failure only degrades the connection. Only repeated failures mean the
+   * peer is really unreachable.
+   */
+  private noteFailure(entry: ConnectionEntry, error: unknown): void {
+    if (this.entries.get(entry.deviceId) !== entry || entry.health === 'lost') {
+      return;
+    }
+    entry.consecutiveFailures += 1;
+    log.warn('Peer keepalive failed', {
+      deviceId: entry.deviceId,
+      consecutiveFailures: entry.consecutiveFailures,
+      error,
+    });
+    if (entry.consecutiveFailures >= this.maxKeepaliveFailures) {
+      this.markLost(entry, 'keepalive');
+      return;
+    }
+    entry.health = 'degraded';
+    this.scheduleReconnect(entry);
+    this.publish();
+  }
+
+  private noteHealthy(deviceId: string): void {
+    const entry = this.entries.get(deviceId);
+    // A lost connection is terminal: it is disposed, not silently revived.
+    if (!entry || entry.health !== 'degraded') {
+      return;
+    }
+    entry.consecutiveFailures = 0;
+    entry.health = 'ready';
+    this.scheduleKeepalive(entry);
+    this.publish();
+
+    // HostInvoke itself does not require an attachment, so successful product
+    // traffic proves reachability but not that DeviceEvents are still fanned
+    // out. Re-attach in the background before treating recovery as durable.
+    if (!entry.reattachInFlight) {
+      const reattach = this.sendAttach(deviceId)
+        .catch(error => this.noteFailure(entry, error))
+        .finally(() => {
+          if (entry.reattachInFlight === reattach) {
+            entry.reattachInFlight = null;
+          }
+        });
+      entry.reattachInFlight = reattach;
+    }
+  }
+
+  private markLost(entry: ConnectionEntry, reason: PeerConnectionLostReason): void {
+    if (entry.health === 'lost') {
+      return;
+    }
+    this.cancelTimer(entry);
+    entry.health = 'lost';
+    entry.lostReason = reason;
+    log.warn('Peer connection lost', { deviceId: entry.deviceId, reason });
+    this.publish();
+  }
+
+  private cancelTimer(entry: ConnectionEntry): void {
+    if (entry.timer !== null) {
+      clearTimeout(entry.timer);
+      entry.timer = null;
+    }
+  }
+
+  private assertEntryActive(entry: ConnectionEntry): void {
+    if (entry.disposed || this.entries.get(entry.deviceId) !== entry) {
+      throw new PeerConnectionDisposedError(entry.deviceId);
+    }
+  }
+
+  private renameEntry(entry: ConnectionEntry, deviceName: string): void {
+    if (!deviceName || entry.deviceName === deviceName) {
+      return;
+    }
+    entry.deviceName = deviceName;
+    this.publish();
+  }
+
+  private async controllerId(): Promise<string> {
+    if (this.controllerDeviceId === null) {
+      this.controllerDeviceId = await this.resolveControllerDeviceId();
+    }
+    return this.controllerDeviceId;
+  }
+
+  private async hostInvoke<T>(
+    deviceId: string,
+    command: string,
+    args: Record<string, unknown>,
+  ): Promise<T | undefined> {
+    const raw = await this.deviceRpc(
+      deviceId,
+      JSON.stringify({ cmd: 'host_invoke', command, args }),
+      this.controlRpcTimeoutMs,
+    );
+    const envelope = JSON.parse(raw) as HostInvokeEnvelope;
+    if (envelope.resp === 'error') {
+      throw new Error(envelope.message || `Peer '${command}' failed`);
+    }
+    if (envelope.resp === 'host_invoke_result' && !envelope.ok) {
+      throw new Error(envelope.error || `Peer '${command}' failed`);
+    }
+    return envelope.value as T | undefined;
+  }
+
+  private stateOf(entry: ConnectionEntry): PeerConnectionState {
+    return {
+      deviceId: entry.deviceId,
+      deviceName: entry.deviceName,
+      surfaceId: entry.handle.surfaceId,
+      health: entry.health,
+      capabilities: entry.capabilities,
+      consecutiveFailures: entry.consecutiveFailures,
+      lostReason: entry.lostReason,
+    };
+  }
+
+  private publish(): void {
+    this.snapshot = Array.from(this.entries.values(), entry => this.stateOf(entry));
+    for (const listener of Array.from(this.listeners)) {
+      try {
+        listener(this.snapshot);
+      } catch (error) {
+        log.warn('Peer connection listener threw', error);
+      }
+    }
+  }
+}
+
+/** Window-wide instance; peer links outlive any component that renders them. */
+export const peerConnectionManager = new PeerConnectionManager();
diff --git a/src/web-ui/src/infrastructure/peer-device/PeerDeviceContext.tsx b/src/web-ui/src/infrastructure/peer-device/PeerDeviceContext.tsx
index b4e7264a9f..40e61639a8 100644
--- a/src/web-ui/src/infrastructure/peer-device/PeerDeviceContext.tsx
+++ b/src/web-ui/src/infrastructure/peer-device/PeerDeviceContext.tsx
@@ -1,378 +1,64 @@
-import React, {
-  useCallback,
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-} from 'react';
-import { setTransportAdapter, createTransportAdapter } from '@/infrastructure/api/adapters';
-import { PeerDeviceTransportAdapter } from '@/infrastructure/api/adapters/peer-device-adapter';
-import { remoteConnectAPI } from '@/infrastructure/api/service-api/RemoteConnectAPI';
-import { configAPI } from '@/infrastructure/api/service-api/ConfigAPI';
-import { api } from '@/infrastructure/api/service-api/ApiClient';
-import { configManager } from '@/infrastructure/config/services/ConfigManager';
-import { FlowChatManager } from '@/flow_chat/services/FlowChatManager';
-import { TerminalService } from '@/tools/terminal/services/TerminalService';
-import { workspaceManager } from '@/infrastructure/services/business/workspaceManager';
-import { editorManager } from '@/tools/editor/services/EditorManager';
-import { useSceneStore } from '@/app/stores/sceneStore';
-import { clearAgentCanvasForPeerSwitch } from '@/app/components/panels/content-canvas/stores';
-import { WorkspaceLspManager } from '@/tools/lsp/services/WorkspaceLspManager';
-import { lspAdapterManager } from '@/tools/lsp/services/LspAdapterManager';
-import { createLogger } from '@/shared/utils/logger';
-import { setPeerDeviceModeActiveFlag } from './peerModeFlag';
-import { shouldSurfacePeerDetachFailure } from './peerDetachPolicy';
+/** Thin React binding for the window-wide device-surface controller. */
+
+import React, { useCallback, useEffect, useMemo, useState } from 'react';
+import type { PeerDeviceSurfaceSnapshot } from './PeerDeviceSurfaceController';
+import { peerDeviceSurfaceController } from './peerDeviceSurfaceRuntime';
 import {
   PeerDeviceContext,
-  type PeerModeState,
+  type SurfaceSwitchOutcome,
 } from './peerDeviceContextState';
 
-const log = createLogger('PeerDeviceMode');
-
-/** Only high/normal HostInvoke transport failures count toward auto-exit. */
-const PEER_RPC_FAILURE_LIMIT = 2147483647;
-const PEER_PING_INTERVAL_MS = 20_000;
-const PEER_CONTROL_RPC_TIMEOUT_MS = 15_000;
-
-function emitPeerModeChanged(detail: { active: boolean; deviceId?: string }): void {
-  setPeerDeviceModeActiveFlag(detail.active);
-  window.dispatchEvent(new CustomEvent('peer-mode:changed', { detail }));
-}
-
-async function resetProductSurface(): Promise<void> {
-  try {
-    FlowChatManager.getInstance().resetForPeerModeSwitch();
-  } catch (error) {
-    log.warn('Failed to reset FlowChat during peer mode switch', error);
-  }
-
-  // Clear before peer flag / emit so SessionModule cannot read a stale
-  // controller workspace while rebootstrap is still running.
-  try {
-    workspaceManager.clearForPeerModeSwitch();
-  } catch (error) {
-    log.warn('Failed to clear workspace during peer mode switch', error);
-  }
-
-  try {
-    await TerminalService.getInstance().shutdownAll();
-  } catch (error) {
-    log.warn('Failed to shutdown terminals during peer mode switch', error);
-  }
-
-  try {
-    await TerminalService.getInstance().disconnect();
-  } catch (error) {
-    log.warn('Failed to disconnect terminal listeners during peer mode switch', error);
-  }
-
-  try {
-    lspAdapterManager.disposeAll();
-    await WorkspaceLspManager.clearAllForPeerSwitch();
-  } catch (error) {
-    log.warn('Failed to reset LSP during peer mode switch', error);
-  }
-
-  try {
-    editorManager.destroy();
-  } catch (error) {
-    log.warn('Failed to clear editor during peer mode switch', error);
-  }
-
-  try {
-    clearAgentCanvasForPeerSwitch();
-  } catch (error) {
-    log.warn('Failed to clear canvas during peer mode switch', error);
-  }
-
-  try {
-    useSceneStore.getState().resetForPeerSwitch();
-  } catch (error) {
-    log.warn('Failed to reset scenes during peer mode switch', error);
-  }
-}
-
-async function rebootstrapWorkspaces(): Promise<void> {
-  try {
-    await workspaceManager.reinitializeForPeerModeSwitch();
-  } catch (error) {
-    log.warn('Peer mode workspace rebootstrap failed', error);
-    throw error;
-  }
-}
-
-async function reloadConfigFromCurrentTransport(): Promise<void> {
-  try {
-    await configAPI.reloadConfig();
-    configManager.clearCache();
-    await configManager.reload();
-  } catch (error) {
-    log.warn('Failed to reload config after peer mode transport switch', error);
-  }
-}
-
-async function setPeerControllerActive(active: boolean, required: boolean): Promise<void> {
-  try {
-    await api.invoke('peer_controller_set_active', { active });
-  } catch (error) {
-    log.warn('Failed to update peer controller active flag', { active, error });
-    if (required) {
-      throw error instanceof Error
-        ? error
-        : new Error(`peer_controller_set_active(${active}) failed`);
-    }
-  }
-}
-
-async function detachPeerControl(deviceId: string, controllerDeviceId: string): Promise<void> {
-  parseHostInvokeResult(
-    await remoteConnectAPI.accountDeviceRpc(
-      deviceId,
-      JSON.stringify({
-        cmd: 'host_invoke',
-        command: 'peer_control_detach',
-        args: { controller_device_id: controllerDeviceId },
-      }),
-      PEER_CONTROL_RPC_TIMEOUT_MS,
-    ),
-  );
-}
-
-function parseHostInvokeResult<T = unknown>(raw: string): T | undefined {
-  const envelope = JSON.parse(raw) as {
-    resp?: string;
-    ok?: boolean;
-    value?: unknown;
-    error?: string;
-    message?: string;
-  };
-  if (envelope.resp === 'error') {
-    throw new Error(envelope.message || 'Peer HostInvoke failed');
-  }
-  if (envelope.resp === 'host_invoke_result' && !envelope.ok) {
-    throw new Error(envelope.error || 'Peer HostInvoke failed');
-  }
-  return envelope.value as T | undefined;
-}
-
 export const PeerDeviceProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
-  const [peerMode, setPeerMode] = useState<PeerModeState>({ active: false });
-  const peerModeRef = useRef(peerMode);
-  peerModeRef.current = peerMode;
-  const exitInFlightRef = useRef(false);
-  const rpcFailuresRef = useRef(0);
-
-  const restoreLocalTransport = useCallback(async () => {
-    const local = createTransportAdapter();
-    await local.connect();
-    setTransportAdapter(local);
-    api.reattachTransportAdapter();
-  }, []);
-
-  const exitPeerMode = useCallback(async (reason?: string) => {
-    if (!peerModeRef.current.active || exitInFlightRef.current) {
-      return;
-    }
-    exitInFlightRef.current = true;
-    const { deviceId, deviceName } = peerModeRef.current;
-    let detachError: unknown;
-    try {
-      try {
-        const localInfo = await remoteConnectAPI.getDeviceInfo();
-        await detachPeerControl(deviceId, localInfo.device_id);
-      } catch (error) {
-        detachError = error;
-        log.warn('Failed to detach peer control subscription', error);
-      }
-
-      await resetProductSurface();
-      await restoreLocalTransport();
-      await setPeerControllerActive(false, false);
-      setPeerMode({ active: false });
-      emitPeerModeChanged({ active: false, deviceId });
-      rpcFailuresRef.current = 0;
-      await reloadConfigFromCurrentTransport();
-      await rebootstrapWorkspaces();
-      log.info('Exited peer device mode', { deviceId, deviceName, reason: reason ?? 'manual' });
-      if (reason && reason !== 'manual') {
-        window.dispatchEvent(
-          new CustomEvent('peer-mode:auto-exit', {
-            detail: { deviceId, deviceName, reason },
-          }),
-        );
-      }
-      if (detachError && shouldSurfacePeerDetachFailure(reason)) {
-        throw detachError instanceof Error
-          ? detachError
-          : new Error('Peer work may still be running after disconnect');
-      }
-    } finally {
-      exitInFlightRef.current = false;
-    }
-  }, [restoreLocalTransport]);
-
-  const notePeerTransportFailure = useCallback((
-    error: unknown,
-    meta?: { action: string; priority: 'high' | 'normal' | 'low' },
-  ) => {
-    if (!peerModeRef.current.active) {
-      return;
-    }
-    // Background git/SSH/editor noise must not force-exit Peer Mode.
-    if (meta?.priority === 'low') {
-      log.warn('Peer transport failure ignored for auto-exit (low priority)', {
-        action: meta.action,
-        error,
-      });
-      return;
-    }
-    rpcFailuresRef.current += 1;
-    log.warn('Peer transport failure counted', {
-      failures: rpcFailuresRef.current,
-      action: meta?.action,
-      priority: meta?.priority,
-      error,
-    });
-    if (rpcFailuresRef.current >= PEER_RPC_FAILURE_LIMIT) {
-      void exitPeerMode('rpc_failures');
-    }
-  }, [exitPeerMode]);
-
-  const notePeerRpcSuccess = useCallback(() => {
-    rpcFailuresRef.current = 0;
-  }, []);
-
-  const enterPeerMode = useCallback(async (deviceId: string, deviceName: string) => {
-    if (!deviceId) {
-      throw new Error('deviceId is required');
-    }
-    if (peerModeRef.current.active) {
-      await exitPeerMode('switch');
-    }
-
-    const peerCapabilities = parseHostInvokeResult<{
-      capabilities?: {
-        idempotent_dialog_submit?: boolean;
-      };
-    }>(
-      await remoteConnectAPI.accountDeviceRpc(
-        deviceId,
-        JSON.stringify({ cmd: 'host_invoke', command: 'peer_mode_ping', args: {} }),
-        PEER_CONTROL_RPC_TIMEOUT_MS,
-      ),
-    );
-
-    const localInfo = await remoteConnectAPI.getDeviceInfo();
-    const controllerDeviceId = localInfo.device_id;
-
-    // Pause cloud pull before clearing local UI so mid-switch reconcile cannot rewrite A.
-    await setPeerControllerActive(true, true);
-
-    let attached = false;
-    try {
-      await resetProductSurface();
-
-      const peerTransport = new PeerDeviceTransportAdapter(
-        deviceId,
-        (target, commandJson, timeoutMs) =>
-          remoteConnectAPI.accountDeviceRpc(target, commandJson, timeoutMs),
-        {
-          onHostInvokeSuccess: notePeerRpcSuccess,
-          onHostInvokeTransportFailure: notePeerTransportFailure,
-          supportsIdempotentDialogSubmit:
-            peerCapabilities?.capabilities?.idempotent_dialog_submit === true,
-        },
-      );
-
-      await peerTransport.connect();
-      setTransportAdapter(peerTransport);
-      api.reattachTransportAdapter();
-
-      parseHostInvokeResult(
-        await remoteConnectAPI.accountDeviceRpc(
-          deviceId,
-          JSON.stringify({
-            cmd: 'host_invoke',
-            command: 'peer_control_attach',
-            args: { controller_device_id: controllerDeviceId },
-          }),
-          PEER_CONTROL_RPC_TIMEOUT_MS,
-        ),
-      );
-      attached = true;
-
-      setPeerMode({ active: true, deviceId, deviceName });
-      emitPeerModeChanged({ active: true, deviceId });
-      rpcFailuresRef.current = 0;
-      await reloadConfigFromCurrentTransport();
-      await rebootstrapWorkspaces();
-      log.info('Entered peer device mode', { deviceId, deviceName });
-    } catch (error) {
-      log.error('enterPeerMode failed; restoring local transport', error);
-      if (attached) {
-        try {
-          await detachPeerControl(deviceId, controllerDeviceId);
-        } catch (detachError) {
-          log.warn('Failed to detach after enterPeerMode failure', detachError);
-        }
-      }
-      try {
-        await restoreLocalTransport();
-        await setPeerControllerActive(false, false);
-        setPeerMode({ active: false });
-        emitPeerModeChanged({ active: false, deviceId });
-        await reloadConfigFromCurrentTransport();
-        await rebootstrapWorkspaces();
-      } catch (rollbackError) {
-        log.error('Failed to roll back after enterPeerMode failure', rollbackError);
-      }
-      throw error;
-    }
-  }, [exitPeerMode, notePeerTransportFailure, notePeerRpcSuccess, restoreLocalTransport]);
+  const [snapshot, setSnapshot] = useState<PeerDeviceSurfaceSnapshot>(
+    () => peerDeviceSurfaceController.getSnapshot(),
+  );
 
-  // Auto-exit when the peer drops from account presence or ping fails.
   useEffect(() => {
-    if (!peerMode.active) {
-      return;
-    }
-    const { deviceId } = peerMode;
-
-    const unlistenPresence = api.listen<{ devices: Array<{ device_id: string; device_name: string }> }>(
-      'account://device-presence',
-      (payload) => {
-        const online = payload?.devices ?? [];
-        if (!online.some((d) => d.device_id === deviceId)) {
-          void exitPeerMode('peer_offline');
-        }
-      },
-    );
-
-    const pingTimer = setInterval(() => {
-      void (async () => {
-        try {
-          parseHostInvokeResult(
-            await remoteConnectAPI.accountDeviceRpc(
-              deviceId,
-              JSON.stringify({ cmd: 'host_invoke', command: 'peer_mode_ping', args: {} }),
-              PEER_CONTROL_RPC_TIMEOUT_MS,
-            ),
-          );
-          notePeerRpcSuccess();
-        } catch (error) {
-          notePeerTransportFailure(error);
-        }
-      })();
-    }, PEER_PING_INTERVAL_MS);
-
+    const unsubscribe = peerDeviceSurfaceController.subscribe(setSnapshot);
+    peerDeviceSurfaceController.start();
     return () => {
-      unlistenPresence();
-      clearInterval(pingTimer);
+      unsubscribe();
+      peerDeviceSurfaceController.stop();
     };
-  }, [peerMode, exitPeerMode, notePeerTransportFailure, notePeerRpcSuccess]);
+  }, []);
+
+  const switchToDevice = useCallback(
+    (deviceId: string, deviceName: string): Promise<SurfaceSwitchOutcome> =>
+      peerDeviceSurfaceController.switchToDevice(deviceId, deviceName),
+    [],
+  );
+  const switchToLocal = useCallback(
+    (reason?: string): Promise<SurfaceSwitchOutcome> =>
+      peerDeviceSurfaceController.switchToLocal(reason),
+    [],
+  );
+  const disconnectDevice = useCallback(
+    (deviceId: string, reason?: string): Promise<void> =>
+      peerDeviceSurfaceController.disconnectDevice(deviceId, reason),
+    [],
+  );
+  const disconnectAllDevices = useCallback(
+    (reason?: string): Promise<void> =>
+      peerDeviceSurfaceController.disconnectAllDevices(reason),
+    [],
+  );
 
   const value = useMemo(
-    () => ({ peerMode, enterPeerMode, exitPeerMode }),
-    [peerMode, enterPeerMode, exitPeerMode],
+    () => ({
+      peerMode: snapshot.peerMode,
+      attachments: [...snapshot.attachments],
+      switchToDevice,
+      switchToLocal,
+      disconnectDevice,
+      disconnectAllDevices,
+    }),
+    [
+      snapshot,
+      switchToDevice,
+      switchToLocal,
+      disconnectDevice,
+      disconnectAllDevices,
+    ],
   );
 
   return (
diff --git a/src/web-ui/src/infrastructure/peer-device/PeerDeviceSurfaceController.test.ts b/src/web-ui/src/infrastructure/peer-device/PeerDeviceSurfaceController.test.ts
new file mode 100644
index 0000000000..f8dfdff89d
--- /dev/null
+++ b/src/web-ui/src/infrastructure/peer-device/PeerDeviceSurfaceController.test.ts
@@ -0,0 +1,357 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { ITransportAdapter } from '@/infrastructure/api/adapters/base';
+import {
+  LOCAL_SURFACE_ID,
+  activateSurface,
+  getActiveSurfaceId,
+  getActiveSurfaceScope,
+  onSurfaceActivated,
+  resetDeviceSurfaceForTest,
+  type SurfaceScope,
+} from './deviceSurface';
+import {
+  PeerDeviceSurfaceController,
+  type PeerDeviceSurfaceSnapshot,
+} from './PeerDeviceSurfaceController';
+import type {
+  PeerConnection,
+  PeerConnectionState,
+} from './PeerConnectionManager';
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (error: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+function adapter(): ITransportAdapter {
+  return {
+    connect: vi.fn(async () => undefined),
+    request: vi.fn(async () => undefined as never),
+    listen: vi.fn(() => () => undefined),
+    disconnect: vi.fn(async () => undefined),
+    isConnected: vi.fn(() => true),
+  };
+}
+
+class FakeConnectionManager {
+  private readonly connections = new Map<string, PeerConnection>();
+  private readonly states = new Map<string, PeerConnectionState>();
+  private readonly listeners = new Set<(
+    connections: readonly PeerConnectionState[],
+  ) => void>();
+  private readonly pendingConnections = new Map<string, ReturnType<typeof deferred<PeerConnection>>>();
+
+  readonly connect = vi.fn((deviceId: string, deviceName = ''): Promise<PeerConnection> => {
+    const pending = this.pendingConnections.get(deviceId);
+    if (pending) {
+      return pending.promise;
+    }
+    return Promise.resolve(this.ensure(deviceId, deviceName));
+  });
+
+  readonly dispose = vi.fn(async (deviceId: string): Promise<void> => {
+    this.connections.delete(deviceId);
+    this.states.delete(deviceId);
+    this.publish();
+  });
+
+  get(deviceId: string): PeerConnection | undefined {
+    return this.connections.get(deviceId);
+  }
+
+  list(): readonly PeerConnectionState[] {
+    return Array.from(this.states.values());
+  }
+
+  subscribe(listener: (connections: readonly PeerConnectionState[]) => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  reportPresence(onlineDeviceIds: Iterable<string>): void {
+    const online = new Set(onlineDeviceIds);
+    for (const state of this.states.values()) {
+      if (!online.has(state.deviceId)) {
+        this.lose(state.deviceId, 'presence');
+      }
+    }
+  }
+
+  delay(deviceId: string): ReturnType<typeof deferred<PeerConnection>> {
+    const pending = deferred<PeerConnection>();
+    this.pendingConnections.set(deviceId, pending);
+    return pending;
+  }
+
+  resolve(deviceId: string, deviceName: string): void {
+    const pending = this.pendingConnections.get(deviceId);
+    if (!pending) {
+      throw new Error(`No pending connection for ${deviceId}`);
+    }
+    this.pendingConnections.delete(deviceId);
+    pending.resolve(this.ensure(deviceId, deviceName));
+  }
+
+  lose(deviceId: string, reason: 'presence' | 'keepalive'): void {
+    const previous = this.states.get(deviceId);
+    if (!previous) {
+      return;
+    }
+    this.states.set(deviceId, {
+      ...previous,
+      health: 'lost',
+      lostReason: reason,
+    });
+    this.publish();
+  }
+
+  private ensure(deviceId: string, deviceName: string): PeerConnection {
+    const existing = this.connections.get(deviceId);
+    if (existing) {
+      return existing;
+    }
+    const peerAdapter = adapter();
+    const connection: PeerConnection = {
+      deviceId,
+      surfaceId: deviceId,
+      adapter: peerAdapter as PeerConnection['adapter'],
+      getState: () => this.states.get(deviceId)!,
+    };
+    this.connections.set(deviceId, connection);
+    this.states.set(deviceId, {
+      deviceId,
+      deviceName,
+      surfaceId: deviceId,
+      health: 'ready',
+      capabilities: {
+        idempotentDialogSubmit: true,
+        targetedSessionRollback: true,
+      },
+      consecutiveFailures: 0,
+      lostReason: null,
+    });
+    this.publish();
+    return connection;
+  }
+
+  private publish(): void {
+    const snapshot = this.list();
+    for (const listener of this.listeners) {
+      listener(snapshot);
+    }
+  }
+}
+
+function createHarness(options: {
+  rebootstrap?: (scope: SurfaceScope) => Promise<void>;
+} = {}) {
+  const manager = new FakeConnectionManager();
+  const commits: string[] = [];
+  const invalidations: string[] = [];
+  const discarded: string[] = [];
+  const autoExits: Array<{ deviceId: string; reason: string }> = [];
+  const peerModeEvents: Array<{ active: boolean; deviceId?: string }> = [];
+  const controllerFlags: boolean[] = [];
+  let latestSnapshot: PeerDeviceSurfaceSnapshot | null = null;
+
+  const controller = new PeerDeviceSurfaceController({
+    connectionManager: manager,
+    getLocalAdapter: async () => adapter(),
+    resetProductSurface: async assertCurrent => assertCurrent(),
+    reloadConfig: async scope => scope.assertCurrent('reload config'),
+    rebootstrapWorkspaces: options.rebootstrap
+      ?? (async scope => scope.assertCurrent('rebootstrap workspaces')),
+    setPeerControllerActive: async active => {
+      controllerFlags.push(active);
+    },
+    commitSurface: target => {
+      commits.push(target.surfaceId);
+      return activateSurface(target.surfaceId);
+    },
+    invalidateCurrentSurface: () => {
+      invalidations.push(getActiveSurfaceId());
+      return activateSurface(getActiveSurfaceId());
+    },
+    emitPeerModeChanged: detail => peerModeEvents.push(detail),
+    markSurfaceSwitched: vi.fn(),
+    discardSurfaceState: surfaceId => discarded.push(surfaceId),
+    clearDeviceActivity: vi.fn(),
+    emitAutoExit: detail => autoExits.push(detail),
+    listenPresence: () => () => undefined,
+    listenLoginState: () => () => undefined,
+  });
+  controller.subscribe(snapshot => {
+    latestSnapshot = snapshot;
+  });
+
+  return {
+    controller,
+    manager,
+    commits,
+    invalidations,
+    discarded,
+    autoExits,
+    peerModeEvents,
+    controllerFlags,
+    snapshot: () => latestSnapshot!,
+  };
+}
+
+describe('PeerDeviceSurfaceController switching', () => {
+  beforeEach(() => {
+    resetDeviceSurfaceForTest();
+  });
+
+  it('commits routing synchronously before surface subscribers run', () => {
+    const previousScope = getActiveSurfaceScope();
+    let routedSurface = LOCAL_SURFACE_ID;
+    const observed: Array<{ surfaceId: string; routedSurface: string }> = [];
+    onSurfaceActivated(scope => {
+      observed.push({ surfaceId: scope.surfaceId, routedSurface });
+    });
+
+    activateSurface('peer-a', () => {
+      routedSurface = 'peer-a';
+    });
+
+    expect(previousScope.signal.aborted).toBe(true);
+    expect(observed).toEqual([{ surfaceId: 'peer-a', routedSurface: 'peer-a' }]);
+  });
+
+  it('coalesces a rapid switch to the last target before the first connection completes', async () => {
+    const harness = createHarness();
+    harness.manager.delay('peer-a');
+
+    const first = harness.controller.switchToDevice('peer-a', 'A');
+    await Promise.resolve();
+    const last = harness.controller.switchToDevice('peer-b', 'B');
+
+    await expect(first).resolves.toBe('superseded');
+    await expect(last).resolves.toBe('activated');
+    expect(harness.commits).toEqual(['peer-b']);
+    expect(harness.snapshot().peerMode).toEqual({
+      active: true,
+      deviceId: 'peer-b',
+      deviceName: 'B',
+    });
+
+    // The abandoned handshake may finish, but it cannot commit its surface.
+    harness.manager.resolve('peer-a', 'A');
+    await Promise.resolve();
+    expect(harness.commits).toEqual(['peer-b']);
+  });
+
+  it('invalidates an already committed hydrate and lets the newer target proceed', async () => {
+    const peerAHydrate = deferred<void>();
+    const harness = createHarness({
+      rebootstrap: async scope => {
+        if (scope.surfaceId === 'peer-a') {
+          await peerAHydrate.promise;
+        }
+        scope.assertCurrent('rebootstrap workspaces');
+      },
+    });
+
+    const first = harness.controller.switchToDevice('peer-a', 'A');
+    await vi.waitFor(() => expect(harness.commits).toEqual(['peer-a']));
+    const last = harness.controller.switchToDevice('peer-b', 'B');
+
+    await expect(first).resolves.toBe('superseded');
+    await expect(last).resolves.toBe('activated');
+    expect(harness.invalidations).toEqual(['peer-a']);
+    expect(harness.commits).toEqual(['peer-a', 'peer-b']);
+    expect(harness.snapshot().peerMode).toMatchObject({
+      active: true,
+      deviceId: 'peer-b',
+    });
+
+    peerAHydrate.resolve();
+  });
+
+  it('rehydrates the last target when rapid A to B to A invalidated A', async () => {
+    const firstPeerAHydrate = deferred<void>();
+    let peerAHydrateCount = 0;
+    const harness = createHarness({
+      rebootstrap: async scope => {
+        if (scope.surfaceId === 'peer-a' && ++peerAHydrateCount === 1) {
+          await firstPeerAHydrate.promise;
+        }
+        scope.assertCurrent('rebootstrap workspaces');
+      },
+    });
+
+    const first = harness.controller.switchToDevice('peer-a', 'A');
+    await vi.waitFor(() => expect(harness.commits).toEqual(['peer-a']));
+
+    const middle = harness.controller.switchToDevice('peer-b', 'B');
+    const last = harness.controller.switchToDevice('peer-a', 'A');
+
+    await expect(first).resolves.toBe('superseded');
+    await expect(middle).resolves.toBe('superseded');
+    await expect(last).resolves.toBe('activated');
+    expect(harness.invalidations).toEqual(['peer-a']);
+    expect(harness.commits).toEqual(['peer-a', 'peer-a']);
+    expect(peerAHydrateCount).toBe(2);
+    expect(harness.snapshot().peerMode).toMatchObject({
+      active: true,
+      deviceId: 'peer-a',
+    });
+
+    firstPeerAHydrate.resolve();
+  });
+
+  it('rolls a real activation failure back to the previous peer, not local', async () => {
+    const harness = createHarness({
+      rebootstrap: async scope => {
+        if (scope.surfaceId === 'peer-b') {
+          throw new Error('peer B workspace failed');
+        }
+        scope.assertCurrent('rebootstrap workspaces');
+      },
+    });
+
+    await expect(harness.controller.switchToDevice('peer-a', 'A'))
+      .resolves.toBe('activated');
+    await expect(harness.controller.switchToDevice('peer-b', 'B'))
+      .rejects.toThrow('peer B workspace failed');
+
+    expect(harness.commits).toEqual(['peer-a', 'peer-b', 'peer-a']);
+    expect(harness.snapshot().peerMode).toEqual({
+      active: true,
+      deviceId: 'peer-a',
+      deviceName: 'A',
+    });
+  });
+});
+
+describe('PeerDeviceSurfaceController connection loss', () => {
+  beforeEach(() => {
+    resetDeviceSurfaceForTest();
+  });
+
+  it('returns to local, disposes a lost peer, and emits one auto-exit', async () => {
+    const harness = createHarness();
+    harness.controller.start();
+    await harness.controller.switchToDevice('peer-a', 'A');
+
+    harness.manager.lose('peer-a', 'presence');
+
+    await vi.waitFor(() => {
+      expect(harness.snapshot().peerMode).toEqual({ active: false });
+      expect(harness.manager.dispose).toHaveBeenCalledWith('peer-a', { notifyPeer: false });
+    });
+    expect(harness.discarded).toEqual(['peer-a']);
+    expect(harness.autoExits).toEqual([{
+      deviceId: 'peer-a',
+      deviceName: 'A',
+      reason: 'peer_offline',
+    }]);
+    expect(getActiveSurfaceId()).toBe(LOCAL_SURFACE_ID);
+    harness.controller.stop();
+  });
+});
diff --git a/src/web-ui/src/infrastructure/peer-device/PeerDeviceSurfaceController.ts b/src/web-ui/src/infrastructure/peer-device/PeerDeviceSurfaceController.ts
new file mode 100644
index 0000000000..435db71a12
--- /dev/null
+++ b/src/web-ui/src/infrastructure/peer-device/PeerDeviceSurfaceController.ts
@@ -0,0 +1,684 @@
+/**
+ * Atomic device-surface switching and peer attachment orchestration.
+ *
+ * React renders a snapshot of this controller; it does not own connection
+ * timers or the switch lifecycle. Rapid requests collapse to the last target,
+ * and a request that supersedes an already committed activation invalidates
+ * that activation immediately so its hydrate cannot write into the next one.
+ */
+
+import type { ITransportAdapter } from '@/infrastructure/api/adapters/base';
+import { createLogger } from '@/shared/utils/logger';
+import {
+  LOCAL_SURFACE_ID,
+  SurfaceChangedError,
+  getActiveSurfaceScope,
+  isSurfaceChangedError,
+  type DeviceSurfaceId,
+  type SurfaceScope,
+} from './deviceSurface';
+import { shouldSurfacePeerDetachFailure } from './peerDetachPolicy';
+import type { PeerConnection, PeerConnectionState } from './PeerConnectionManager';
+import type {
+  PeerAttachmentState,
+  PeerModeState,
+  SurfaceSwitchOutcome,
+} from './peerDeviceContextState';
+
+const log = createLogger('PeerDeviceSurfaceController');
+
+export interface SurfaceTarget {
+  readonly surfaceId: DeviceSurfaceId;
+  readonly deviceId: string | null;
+  readonly deviceName: string;
+}
+
+export interface ResolvedSurfaceTarget extends SurfaceTarget {
+  readonly adapter: ITransportAdapter;
+}
+
+interface SwitchWaiter {
+  resolve: (outcome: SurfaceSwitchOutcome) => void;
+  reject: (error: unknown) => void;
+}
+
+interface SwitchIntent {
+  readonly id: number;
+  readonly target: SurfaceTarget;
+  readonly reason: string;
+  readonly abortController: AbortController;
+  readonly waiters: SwitchWaiter[];
+  phase: 'queued' | 'preparing' | 'hydrating';
+  superseded: boolean;
+  settled: boolean;
+  rollingBack: boolean;
+  fromTarget: SurfaceTarget | null;
+}
+
+export interface PeerConnectionManagerPort {
+  connect(deviceId: string, deviceName?: string): Promise<PeerConnection>;
+  get(deviceId: string): PeerConnection | undefined;
+  list(): readonly PeerConnectionState[];
+  subscribe(listener: (connections: readonly PeerConnectionState[]) => void): () => void;
+  dispose(deviceId: string, options?: { notifyPeer?: boolean }): Promise<void>;
+  reportPresence(onlineDeviceIds: Iterable<string>): void;
+}
+
+export interface PeerDeviceSurfaceControllerDependencies {
+  connectionManager: PeerConnectionManagerPort;
+  getLocalAdapter: () => Promise<ITransportAdapter>;
+  resetProductSurface: (assertCurrent: () => void) => Promise<void>;
+  reloadConfig: (scope: SurfaceScope) => Promise<void>;
+  rebootstrapWorkspaces: (scope: SurfaceScope) => Promise<void>;
+  setPeerControllerActive: (active: boolean, required: boolean) => Promise<void>;
+  commitSurface: (target: ResolvedSurfaceTarget) => SurfaceScope;
+  invalidateCurrentSurface: () => SurfaceScope;
+  emitPeerModeChanged: (detail: { active: boolean; deviceId?: string }) => void;
+  markSurfaceSwitched: () => void;
+  discardSurfaceState: (surfaceId: DeviceSurfaceId) => void;
+  clearDeviceActivity: (deviceId: string) => void;
+  emitAutoExit: (detail: {
+    deviceId: string;
+    deviceName: string;
+    reason: 'peer_offline' | 'rpc_failures';
+  }) => void;
+  listenPresence: (
+    listener: (onlineDeviceIds: readonly string[]) => void,
+  ) => () => void;
+  listenLoginState: (listener: (loggedIn: boolean) => void) => () => void;
+}
+
+export interface PeerDeviceSurfaceSnapshot {
+  readonly peerMode: PeerModeState;
+  readonly attachments: readonly PeerAttachmentState[];
+}
+
+export type PeerDeviceSurfaceListener = (snapshot: PeerDeviceSurfaceSnapshot) => void;
+
+function localTarget(): SurfaceTarget {
+  return {
+    surfaceId: LOCAL_SURFACE_ID,
+    deviceId: null,
+    deviceName: '',
+  };
+}
+
+function sameTarget(left: SurfaceTarget, right: SurfaceTarget): boolean {
+  return left.surfaceId === right.surfaceId;
+}
+
+function peerModeFor(target: SurfaceTarget): PeerModeState {
+  return target.deviceId === null
+    ? { active: false }
+    : {
+        active: true,
+        deviceId: target.deviceId,
+        deviceName: target.deviceName,
+      };
+}
+
+export class PeerDeviceSurfaceController {
+  private readonly dependencies: PeerDeviceSurfaceControllerDependencies;
+  private readonly listeners = new Set<PeerDeviceSurfaceListener>();
+  private readonly lostConnectionsInFlight = new Set<string>();
+  private currentTarget: SurfaceTarget = localTarget();
+  /** False while the committed target still needs (or has lost) its hydrate. */
+  private currentTargetReady = true;
+  private connectionStates: readonly PeerConnectionState[];
+  private pendingIntent: SwitchIntent | null = null;
+  private activeIntent: SwitchIntent | null = null;
+  private drainPromise: Promise<void> | null = null;
+  private nextIntentId = 0;
+  private started = false;
+  private managerUnsubscribe: (() => void) | null = null;
+  private controlPlaneUnsubscribes: Array<() => void> = [];
+
+  constructor(dependencies: PeerDeviceSurfaceControllerDependencies) {
+    this.dependencies = dependencies;
+    this.connectionStates = this.dependencies.connectionManager.list();
+  }
+
+  start(): void {
+    if (this.started) {
+      return;
+    }
+    this.started = true;
+    this.managerUnsubscribe = this.dependencies.connectionManager.subscribe(
+      connections => this.handleConnectionStates(connections),
+    );
+    this.controlPlaneUnsubscribes = [
+      this.dependencies.listenPresence(onlineDeviceIds => {
+        this.dependencies.connectionManager.reportPresence(onlineDeviceIds);
+      }),
+      this.dependencies.listenLoginState(loggedIn => {
+        if (!loggedIn && this.dependencies.connectionManager.list().length > 0) {
+          void this.disconnectAllDevices('account_logout');
+        }
+      }),
+    ];
+    this.handleConnectionStates(this.dependencies.connectionManager.list());
+  }
+
+  stop(): void {
+    if (!this.started) {
+      return;
+    }
+    this.started = false;
+    this.managerUnsubscribe?.();
+    this.managerUnsubscribe = null;
+    for (const unsubscribe of this.controlPlaneUnsubscribes) {
+      unsubscribe();
+    }
+    this.controlPlaneUnsubscribes = [];
+  }
+
+  getSnapshot(): PeerDeviceSurfaceSnapshot {
+    return {
+      peerMode: peerModeFor(this.currentTarget),
+      attachments: this.connectionStates.map(connection => ({
+        deviceId: connection.deviceId,
+        deviceName: connection.deviceName,
+        health: connection.health,
+        lostReason: connection.lostReason,
+      })),
+    };
+  }
+
+  subscribe(listener: PeerDeviceSurfaceListener): () => void {
+    this.listeners.add(listener);
+    listener(this.getSnapshot());
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  switchToDevice(deviceId: string, deviceName: string): Promise<SurfaceSwitchOutcome> {
+    if (!deviceId.trim()) {
+      return Promise.reject(new Error('deviceId is required'));
+    }
+    return this.enqueueSwitch({
+      surfaceId: deviceId.trim(),
+      deviceId: deviceId.trim(),
+      deviceName,
+    }, 'manual');
+  }
+
+  switchToLocal(reason = 'manual'): Promise<SurfaceSwitchOutcome> {
+    return this.enqueueSwitch(localTarget(), reason);
+  }
+
+  async disconnectDevice(deviceId: string, reason?: string): Promise<void> {
+    const connection = this.dependencies.connectionManager.get(deviceId);
+    if (!connection) {
+      return;
+    }
+
+    if (this.currentTarget.deviceId === deviceId) {
+      await this.switchToLocal(reason ?? 'disconnect');
+      await this.waitForIdle();
+      if (this.currentTarget.deviceId === deviceId) {
+        throw new Error('Peer device is still the rendered surface');
+      }
+    }
+
+    let detachError: unknown;
+    try {
+      await this.dependencies.connectionManager.dispose(deviceId, {
+        notifyPeer: reason !== 'peer_offline' && reason !== 'rpc_failures',
+      });
+    } catch (error) {
+      detachError = error;
+    } finally {
+      this.releaseDeviceState(connection.surfaceId, deviceId);
+    }
+
+    if (detachError) {
+      if (shouldSurfacePeerDetachFailure(reason)) {
+        throw detachError;
+      }
+      log.warn('Ignoring detach failure for an unreachable peer', {
+        deviceId,
+        reason,
+        error: detachError,
+      });
+    }
+    log.info('Disconnected peer device', { deviceId, reason: reason ?? 'manual' });
+  }
+
+  async disconnectAllDevices(reason?: string): Promise<void> {
+    if (this.currentTarget.deviceId !== null) {
+      try {
+        await this.switchToLocal(reason ?? 'disconnect_all');
+        await this.waitForIdle();
+      } catch (error) {
+        log.warn('Failed to restore the local surface before disconnecting peers', { error });
+      }
+    }
+
+    for (const connection of [...this.dependencies.connectionManager.list()]) {
+      try {
+        await this.disconnectDevice(connection.deviceId, reason);
+      } catch (error) {
+        log.warn('Failed to disconnect peer device', {
+          deviceId: connection.deviceId,
+          error,
+        });
+      }
+    }
+  }
+
+  /** Test and lifecycle hook: resolves once no queued activation remains. */
+  async waitForIdle(): Promise<void> {
+    while (this.drainPromise) {
+      await this.drainPromise;
+    }
+  }
+
+  private enqueueSwitch(target: SurfaceTarget, reason: string): Promise<SurfaceSwitchOutcome> {
+    return new Promise<SurfaceSwitchOutcome>((resolve, reject) => {
+      const waiter: SwitchWaiter = { resolve, reject };
+      if (
+        this.pendingIntent
+        && !this.pendingIntent.superseded
+        && sameTarget(this.pendingIntent.target, target)
+      ) {
+        this.pendingIntent.waiters.push(waiter);
+        return;
+      }
+      if (
+        this.activeIntent
+        && !this.activeIntent.superseded
+        && !this.activeIntent.rollingBack
+        && sameTarget(this.activeIntent.target, target)
+      ) {
+        this.activeIntent.waiters.push(waiter);
+        return;
+      }
+
+      if (this.pendingIntent) {
+        this.supersedeIntent(this.pendingIntent);
+      }
+      const intent: SwitchIntent = {
+        id: ++this.nextIntentId,
+        target,
+        reason,
+        abortController: new AbortController(),
+        waiters: [waiter],
+        phase: 'queued',
+        superseded: false,
+        settled: false,
+        rollingBack: false,
+        fromTarget: null,
+      };
+      this.pendingIntent = intent;
+
+      if (this.activeIntent && !sameTarget(this.activeIntent.target, target)) {
+        const active = this.activeIntent;
+        this.supersedeIntent(active);
+        if (active.phase === 'hydrating') {
+          // The target transport is already rendered. Invalidate its activation
+          // now so workspace/session hydrates unwind before the next commit.
+          this.currentTargetReady = false;
+          try {
+            this.dependencies.invalidateCurrentSurface();
+          } catch (error) {
+            log.warn('Failed to invalidate a superseded device surface', { error });
+          }
+        }
+      }
+
+      this.ensureDrain();
+    });
+  }
+
+  private ensureDrain(): void {
+    if (this.drainPromise) {
+      return;
+    }
+    this.drainPromise = this.drainSwitches().finally(() => {
+      this.drainPromise = null;
+      if (this.pendingIntent) {
+        this.ensureDrain();
+      }
+    });
+  }
+
+  private async drainSwitches(): Promise<void> {
+    while (this.pendingIntent) {
+      const intent = this.pendingIntent;
+      this.pendingIntent = null;
+      this.activeIntent = intent;
+      intent.fromTarget = this.currentTarget;
+
+      try {
+        await this.transitionTo(intent, intent.target, intent.reason);
+        if (intent.superseded) {
+          this.settleIntent(intent, 'superseded');
+        } else {
+          this.settleIntent(intent, 'activated');
+        }
+      } catch (error) {
+        if (intent.superseded) {
+          log.debug('Abandoned a superseded device surface activation', {
+            targetSurfaceId: intent.target.surfaceId,
+          });
+          this.settleIntent(intent, 'superseded');
+        } else {
+          log.error('Device surface switch failed', {
+            targetSurfaceId: intent.target.surfaceId,
+            error,
+          });
+          await this.rollbackIntent(intent);
+          this.rejectIntent(intent, error);
+        }
+      } finally {
+        if (this.activeIntent === intent) {
+          this.activeIntent = null;
+        }
+      }
+    }
+  }
+
+  private async transitionTo(
+    intent: SwitchIntent,
+    target: SurfaceTarget,
+    reason: string,
+  ): Promise<void> {
+    intent.phase = 'preparing';
+    const preparingScope = getActiveSurfaceScope();
+    const resolved = await this.resolveTarget(intent, target, preparingScope);
+    this.assertIntentCurrent(intent, preparingScope, 'prepare device surface');
+
+    if (sameTarget(this.currentTarget, target) && this.currentTargetReady) {
+      if (target.deviceId === null) {
+        await this.awaitIntent(
+          intent,
+          this.dependencies.setPeerControllerActive(false, false),
+          preparingScope,
+          'resume local controller sync',
+        );
+      } else if (this.currentTarget.deviceName !== target.deviceName) {
+        this.currentTarget = target;
+        this.publish();
+      }
+      return;
+    }
+
+    const fromTarget = this.currentTarget;
+    if (target.deviceId !== null) {
+      await this.awaitIntent(
+        intent,
+        this.dependencies.setPeerControllerActive(true, true),
+        preparingScope,
+        'pause local controller sync',
+      );
+    }
+
+    await this.dependencies.resetProductSurface(() => {
+      this.assertIntentCurrent(intent, preparingScope, 'reset device surface');
+    });
+    this.assertIntentCurrent(intent, preparingScope, 'reset device surface');
+
+    const activationScope = this.dependencies.commitSurface(resolved);
+    intent.phase = 'hydrating';
+    this.currentTarget = target;
+    this.currentTargetReady = false;
+    this.dependencies.markSurfaceSwitched();
+    this.dependencies.emitPeerModeChanged({
+      active: target.deviceId !== null,
+      deviceId: target.deviceId ?? fromTarget.deviceId ?? undefined,
+    });
+    this.publish();
+
+    await this.awaitIntent(
+      intent,
+      this.dependencies.reloadConfig(activationScope),
+      activationScope,
+      'reload device surface config',
+    );
+    await this.awaitIntent(
+      intent,
+      this.dependencies.rebootstrapWorkspaces(activationScope),
+      activationScope,
+      'rebootstrap device surface workspaces',
+    );
+
+    if (target.deviceId === null) {
+      await this.awaitIntent(
+        intent,
+        this.dependencies.setPeerControllerActive(false, false),
+        activationScope,
+        'resume local controller sync',
+      );
+    }
+
+    this.currentTargetReady = true;
+
+    log.info('Device surface switched', {
+      from: fromTarget.deviceId,
+      to: target.deviceId,
+      reason,
+    });
+  }
+
+  private async resolveTarget(
+    intent: SwitchIntent,
+    target: SurfaceTarget,
+    scope: SurfaceScope,
+  ): Promise<ResolvedSurfaceTarget> {
+    if (target.deviceId === null) {
+      const adapter = await this.awaitIntent(
+        intent,
+        this.dependencies.getLocalAdapter(),
+        scope,
+        'connect local device surface',
+      );
+      return { ...target, adapter };
+    }
+
+    const connection = await this.awaitIntent(
+      intent,
+      this.dependencies.connectionManager.connect(target.deviceId, target.deviceName),
+      scope,
+      'connect peer device surface',
+    );
+    if (connection.getState().health === 'lost') {
+      throw new Error(`Peer device '${target.deviceId}' is no longer reachable`);
+    }
+    return { ...target, adapter: connection.adapter };
+  }
+
+  private async rollbackIntent(intent: SwitchIntent): Promise<void> {
+    if (intent.superseded || intent.abortController.signal.aborted || this.pendingIntent) {
+      return;
+    }
+    const original = intent.fromTarget ?? localTarget();
+
+    // A pre-commit failure left the original surface in place. The only state
+    // that may need repair is the controller-side cloud-sync pause.
+    if (sameTarget(this.currentTarget, original)) {
+      if (original.deviceId === null) {
+        await this.dependencies.setPeerControllerActive(false, false);
+      }
+      return;
+    }
+
+    let fallback = original;
+    if (fallback.deviceId !== null) {
+      const connection = this.dependencies.connectionManager.get(fallback.deviceId);
+      if (!connection || connection.getState().health === 'lost') {
+        fallback = localTarget();
+      }
+    }
+
+    try {
+      intent.rollingBack = true;
+      await this.transitionTo(intent, fallback, 'switch_failed');
+    } catch (rollbackError) {
+      if (!intent.superseded && !isSurfaceChangedError(rollbackError)) {
+        log.error('Failed to roll back device surface switch', {
+          fallbackSurfaceId: fallback.surfaceId,
+          error: rollbackError,
+        });
+      }
+    } finally {
+      intent.rollingBack = false;
+    }
+  }
+
+  private async awaitIntent<T>(
+    intent: SwitchIntent,
+    promise: Promise<T>,
+    scope: SurfaceScope,
+    action: string,
+  ): Promise<T> {
+    this.assertIntentCurrent(intent, scope, action);
+    const signal = intent.abortController.signal;
+    return new Promise<T>((resolve, reject) => {
+      const onAbort = () => {
+        reject(new SurfaceChangedError(scope.surfaceId, scope.epoch, action));
+      };
+      signal.addEventListener('abort', onAbort, { once: true });
+      promise.then(
+        value => {
+          signal.removeEventListener('abort', onAbort);
+          try {
+            this.assertIntentCurrent(intent, scope, action);
+            resolve(value);
+          } catch (error) {
+            reject(error);
+          }
+        },
+        error => {
+          signal.removeEventListener('abort', onAbort);
+          reject(error);
+        },
+      );
+    });
+  }
+
+  private assertIntentCurrent(intent: SwitchIntent, scope: SurfaceScope, action: string): void {
+    if (
+      intent.superseded
+      || intent.abortController.signal.aborted
+      || this.activeIntent !== intent
+    ) {
+      throw new SurfaceChangedError(scope.surfaceId, scope.epoch, action);
+    }
+    scope.assertCurrent(action);
+  }
+
+  private supersedeIntent(intent: SwitchIntent): void {
+    if (intent.superseded) {
+      return;
+    }
+    intent.superseded = true;
+    intent.abortController.abort();
+    this.settleIntent(intent, 'superseded');
+  }
+
+  private settleIntent(intent: SwitchIntent, outcome: SurfaceSwitchOutcome): void {
+    if (intent.settled) {
+      return;
+    }
+    intent.settled = true;
+    for (const waiter of intent.waiters.splice(0)) {
+      waiter.resolve(outcome);
+    }
+  }
+
+  private rejectIntent(intent: SwitchIntent, error: unknown): void {
+    if (intent.settled) {
+      return;
+    }
+    intent.settled = true;
+    for (const waiter of intent.waiters.splice(0)) {
+      waiter.reject(error);
+    }
+  }
+
+  private handleConnectionStates(connections: readonly PeerConnectionState[]): void {
+    this.connectionStates = connections;
+    const activeConnection = this.currentTarget.deviceId
+      ? connections.find(connection => connection.deviceId === this.currentTarget.deviceId)
+      : undefined;
+    if (activeConnection?.deviceName && activeConnection.deviceName !== this.currentTarget.deviceName) {
+      this.currentTarget = {
+        ...this.currentTarget,
+        deviceName: activeConnection.deviceName,
+      };
+    }
+    this.publish();
+
+    for (const connection of connections) {
+      if (connection.health === 'lost' && !this.lostConnectionsInFlight.has(connection.deviceId)) {
+        this.lostConnectionsInFlight.add(connection.deviceId);
+        void this.handleLostConnection(connection)
+          .catch(error => {
+            log.warn('Failed to dispose a lost peer connection', {
+              deviceId: connection.deviceId,
+              error,
+            });
+          })
+          .finally(() => {
+            this.lostConnectionsInFlight.delete(connection.deviceId);
+          });
+      }
+    }
+  }
+
+  private async handleLostConnection(connection: PeerConnectionState): Promise<void> {
+    const wasRendered = this.currentTarget.deviceId === connection.deviceId;
+    const reason = connection.lostReason === 'presence'
+      ? 'peer_offline'
+      : 'rpc_failures';
+
+    if (wasRendered) {
+      try {
+        await this.switchToLocal(reason);
+        await this.waitForIdle();
+      } catch (error) {
+        log.warn('Failed to leave a lost peer device surface', {
+          deviceId: connection.deviceId,
+          error,
+        });
+      }
+    }
+
+    if (this.currentTarget.deviceId === connection.deviceId) {
+      return;
+    }
+
+    try {
+      await this.dependencies.connectionManager.dispose(connection.deviceId, {
+        notifyPeer: false,
+      });
+    } finally {
+      this.releaseDeviceState(connection.surfaceId, connection.deviceId);
+    }
+
+    if (wasRendered) {
+      this.dependencies.emitAutoExit({
+        deviceId: connection.deviceId,
+        deviceName: connection.deviceName || connection.deviceId,
+        reason,
+      });
+    }
+  }
+
+  private releaseDeviceState(surfaceId: DeviceSurfaceId, deviceId: string): void {
+    this.dependencies.clearDeviceActivity(deviceId);
+    this.dependencies.discardSurfaceState(surfaceId);
+  }
+
+  private publish(): void {
+    const snapshot = this.getSnapshot();
+    for (const listener of Array.from(this.listeners)) {
+      try {
+        listener(snapshot);
+      } catch (error) {
+        log.warn('Device surface listener threw', { error });
+      }
+    }
+  }
+}
diff --git a/src/web-ui/src/infrastructure/peer-device/PeerDirectoryBrowser.scss b/src/web-ui/src/infrastructure/peer-device/PeerDirectoryBrowser.scss
index 228405b2db..9b6656ce3c 100644
--- a/src/web-ui/src/infrastructure/peer-device/PeerDirectoryBrowser.scss
+++ b/src/web-ui/src/infrastructure/peer-device/PeerDirectoryBrowser.scss
@@ -11,6 +11,14 @@
   background: var(--bf-appearance-token-color-overlay-black-50);
   backdrop-filter: blur(4px);
   z-index: 280;
+  opacity: 1;
+  transition: opacity 160ms cubic-bezier(0.23, 1, 0.32, 1);
+
+  &[data-state='closed'] {
+    opacity: 0;
+    pointer-events: none;
+    transition-duration: 120ms;
+  }
 }
 
 .peer-directory-browser {
@@ -24,6 +32,12 @@
   border-radius: 12px;
   box-shadow: 0 24px 48px var(--bf-appearance-token-color-overlay-black-50);
   overflow: hidden;
+  opacity: 1;
+  transform: translateY(0) scale(1);
+  transform-origin: center;
+  transition:
+    opacity 160ms cubic-bezier(0.23, 1, 0.32, 1),
+    transform 160ms cubic-bezier(0.23, 1, 0.32, 1);
 
   &__header {
     display: flex;
@@ -182,8 +196,42 @@
   }
 }
 
+.peer-directory-browser-overlay[data-state='closed'] .peer-directory-browser {
+  opacity: 0;
+  transform: translateY(4px) scale(0.985);
+  transition-duration: 120ms;
+}
+
+@starting-style {
+  .peer-directory-browser-overlay {
+    opacity: 0;
+  }
+
+  .peer-directory-browser {
+    opacity: 0;
+    transform: translateY(4px) scale(0.985);
+  }
+}
+
 @keyframes peer-directory-spin {
   to {
     transform: rotate(360deg);
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .peer-directory-browser__spinner {
+    animation: none;
+    transform: none;
+  }
+
+  .peer-directory-browser {
+    transform: none;
+    transition: opacity 160ms cubic-bezier(0.23, 1, 0.32, 1);
+  }
+
+  .peer-directory-browser-overlay[data-state='closed'] .peer-directory-browser {
+    transform: none;
+    transition-duration: 120ms;
+  }
+}
diff --git a/src/web-ui/src/infrastructure/peer-device/PeerDirectoryBrowser.tsx b/src/web-ui/src/infrastructure/peer-device/PeerDirectoryBrowser.tsx
index 027043240e..fb1a48d5de 100644
--- a/src/web-ui/src/infrastructure/peer-device/PeerDirectoryBrowser.tsx
+++ b/src/web-ui/src/infrastructure/peer-device/PeerDirectoryBrowser.tsx
@@ -29,6 +29,7 @@ import './PeerDirectoryBrowser.scss';
 const log = createLogger('PeerDirectoryBrowser');
 
 export interface PeerDirectoryBrowserProps {
+  visible?: boolean;
   title: string;
   initialPath?: string;
   onSelect: (path: string) => void;
@@ -67,6 +68,7 @@ async function resolveStartPath(preferred?: string): Promise<string> {
 }
 
 export const PeerDirectoryBrowser: React.FC<PeerDirectoryBrowserProps> = ({
+  visible = true,
   title,
   initialPath,
   onSelect,
@@ -130,6 +132,7 @@ export const PeerDirectoryBrowser: React.FC<PeerDirectoryBrowserProps> = ({
     })();
     return () => {
       cancelled = true;
+      loadSeqRef.current += 1;
     };
   }, [initialPath, loadDirectory]);
 
@@ -183,8 +186,11 @@ export const PeerDirectoryBrowser: React.FC<PeerDirectoryBrowserProps> = ({
   return createPortal(
     <div
       className="peer-directory-browser-overlay"
+      data-state={visible ? 'open' : 'closed'}
       role="dialog"
       aria-modal="true"
+      aria-hidden={!visible}
+      {...(!visible ? { inert: '' } : {})}
       data-bf-component="peer-device"
       data-bf-part="overlay"
     >
diff --git a/src/web-ui/src/infrastructure/peer-device/PeerDirectoryPickerHost.test.tsx b/src/web-ui/src/infrastructure/peer-device/PeerDirectoryPickerHost.test.tsx
new file mode 100644
index 0000000000..771f95e194
--- /dev/null
+++ b/src/web-ui/src/infrastructure/peer-device/PeerDirectoryPickerHost.test.tsx
@@ -0,0 +1,108 @@
+// @vitest-environment jsdom
+
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { PRESENCE_BOUNDARY_MIN_EXIT_MS } from '@/component-library';
+import { PeerDirectoryPickerHost } from './PeerDirectoryPickerHost';
+import { usePeerDirectoryPickerStore } from './peerDirectoryPickerStore';
+
+vi.mock('./PeerDirectoryBrowser', async () => {
+  const ReactModule = await import('react');
+  return {
+    PeerDirectoryBrowser: ({
+      visible,
+      title,
+      initialPath,
+    }: {
+      visible: boolean;
+      title: string;
+      initialPath?: string;
+    }) => {
+      const [mountedPath] = ReactModule.useState(initialPath);
+      return ReactModule.createElement('div', {
+        'data-testid': 'peer-directory-browser-stub',
+        'data-state': visible ? 'open' : 'closed',
+        'data-title': title,
+        'data-initial-path': initialPath,
+        'data-mounted-path': mountedPath,
+      });
+    },
+  };
+});
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+describe('PeerDirectoryPickerHost presence', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    usePeerDirectoryPickerStore.setState({
+      isOpen: false,
+      title: '',
+      defaultPath: undefined,
+      resolve: null,
+    });
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+    act(() => root.render(<PeerDirectoryPickerHost />));
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    usePeerDirectoryPickerStore.setState({
+      isOpen: false,
+      title: '',
+      defaultPath: undefined,
+      resolve: null,
+    });
+    vi.useRealTimers();
+  });
+
+  it('retains the last picker inputs while closing', () => {
+    act(() => {
+      void usePeerDirectoryPickerStore.getState().show({
+        title: 'Choose peer folder',
+        defaultPath: '/peer/project',
+      });
+    });
+
+    const openBrowser = container.querySelector('[data-testid="peer-directory-browser-stub"]');
+    expect(openBrowser?.getAttribute('data-state')).toBe('open');
+
+    act(() => usePeerDirectoryPickerStore.getState().cancel());
+    const closingBrowser = container.querySelector('[data-testid="peer-directory-browser-stub"]');
+    expect(closingBrowser?.getAttribute('data-state')).toBe('closed');
+    expect(closingBrowser?.getAttribute('data-title')).toBe('Choose peer folder');
+    expect(closingBrowser?.getAttribute('data-initial-path')).toBe('/peer/project');
+
+    act(() => vi.advanceTimersByTime(PRESENCE_BOUNDARY_MIN_EXIT_MS));
+    expect(container.querySelector('[data-testid="peer-directory-browser-stub"]')).toBeNull();
+  });
+
+  it('remounts a rapid replacement request with its own initial path', () => {
+    act(() => {
+      void usePeerDirectoryPickerStore.getState().show({
+        title: 'First request',
+        defaultPath: '/peer/first',
+      });
+    });
+    act(() => usePeerDirectoryPickerStore.getState().cancel());
+
+    act(() => {
+      void usePeerDirectoryPickerStore.getState().show({
+        title: 'Second request',
+        defaultPath: '/peer/second',
+      });
+    });
+
+    const replacement = container.querySelector('[data-testid="peer-directory-browser-stub"]');
+    expect(replacement?.getAttribute('data-state')).toBe('open');
+    expect(replacement?.getAttribute('data-title')).toBe('Second request');
+    expect(replacement?.getAttribute('data-mounted-path')).toBe('/peer/second');
+  });
+});
diff --git a/src/web-ui/src/infrastructure/peer-device/PeerDirectoryPickerHost.tsx b/src/web-ui/src/infrastructure/peer-device/PeerDirectoryPickerHost.tsx
index 98419c5587..d3814c382c 100644
--- a/src/web-ui/src/infrastructure/peer-device/PeerDirectoryPickerHost.tsx
+++ b/src/web-ui/src/infrastructure/peer-device/PeerDirectoryPickerHost.tsx
@@ -2,7 +2,8 @@
  * Host for the imperative peer directory picker store.
  */
 
-import React from 'react';
+import React, { useRef } from 'react';
+import { PresenceBoundary } from '@/component-library';
 import { PeerDirectoryBrowser } from './PeerDirectoryBrowser';
 import { usePeerDirectoryPickerStore } from './peerDirectoryPickerStore';
 
@@ -10,20 +11,36 @@ export const PeerDirectoryPickerHost: React.FC = () => {
   const isOpen = usePeerDirectoryPickerStore((s) => s.isOpen);
   const title = usePeerDirectoryPickerStore((s) => s.title);
   const defaultPath = usePeerDirectoryPickerStore((s) => s.defaultPath);
+  const requestResolver = usePeerDirectoryPickerStore((s) => s.resolve);
   const select = usePeerDirectoryPickerStore((s) => s.select);
   const cancel = usePeerDirectoryPickerStore((s) => s.cancel);
+  const retainedPickerRef = useRef({ title, defaultPath });
+  const requestIdentityRef = useRef<{
+    resolver: typeof requestResolver;
+    key: number;
+  }>({ resolver: null, key: 0 });
 
-  if (!isOpen) {
-    return null;
+  if (isOpen) {
+    retainedPickerRef.current = { title, defaultPath };
+    if (requestIdentityRef.current.resolver !== requestResolver) {
+      requestIdentityRef.current = {
+        resolver: requestResolver,
+        key: requestIdentityRef.current.key + 1,
+      };
+    }
   }
 
   return (
-    <PeerDirectoryBrowser
-      title={title}
-      initialPath={defaultPath}
-      onSelect={select}
-      onCancel={cancel}
-    />
+    <PresenceBoundary active={isOpen}>
+      <PeerDirectoryBrowser
+        key={requestIdentityRef.current.key}
+        visible={isOpen}
+        title={retainedPickerRef.current.title}
+        initialPath={retainedPickerRef.current.defaultPath}
+        onSelect={select}
+        onCancel={cancel}
+      />
+    </PresenceBoundary>
   );
 };
 
diff --git a/src/web-ui/src/infrastructure/peer-device/PeerRemoteBadge.scss b/src/web-ui/src/infrastructure/peer-device/PeerRemoteBadge.scss
deleted file mode 100644
index e512407354..0000000000
--- a/src/web-ui/src/infrastructure/peer-device/PeerRemoteBadge.scss
+++ /dev/null
@@ -1,51 +0,0 @@
-/**
- * Peer Remote status row above the NavPanel footer.
- * Uses the full sidebar width so the device name stays readable.
- */
-
-@use '../../component-library/styles/tokens.scss' as *;
-
-.bitfun-peer-remote-badge {
-  display: flex;
-  align-items: center;
-  gap: $size-gap-2;
-  flex-shrink: 0;
-  width: 100%;
-  min-width: 0;
-  box-sizing: border-box;
-  margin: 0;
-  padding: $size-gap-2 $size-gap-3;
-  border-top: 1px solid var(--bf-appearance-token-border-subtle);
-  background: color-mix(in srgb, var(--bf-appearance-token-color-warning) 14%, transparent);
-  color: var(--bf-appearance-token-color-text-primary);
-  font-size: 12px;
-  line-height: 1.3;
-
-  &__icon {
-    flex-shrink: 0;
-    color: var(--bf-appearance-token-color-warning);
-  }
-
-  &__label {
-    flex: 1 1 auto;
-    min-width: 0;
-    overflow: hidden;
-    text-overflow: ellipsis;
-    white-space: nowrap;
-  }
-
-  &__disconnect {
-    flex-shrink: 0;
-    border: none;
-    background: transparent;
-    color: var(--bf-appearance-token-color-warning);
-    cursor: pointer;
-    font-size: 12px;
-    padding: 0;
-    text-decoration: underline;
-
-    &:hover {
-      opacity: 0.85;
-    }
-  }
-}
diff --git a/src/web-ui/src/infrastructure/peer-device/PeerRemoteBadge.tsx b/src/web-ui/src/infrastructure/peer-device/PeerRemoteBadge.tsx
deleted file mode 100644
index a99c149ba1..0000000000
--- a/src/web-ui/src/infrastructure/peer-device/PeerRemoteBadge.tsx
+++ /dev/null
@@ -1,73 +0,0 @@
-/**
- * Peer Remote status row — shown while Peer Device Mode is active.
- * Mounted as a dedicated full-width row above the NavPanel footer.
- */
-
-import React, { useCallback } from 'react';
-import { Monitor } from 'lucide-react';
-import { useI18n } from '@/infrastructure/i18n/hooks/useI18n';
-import { usePeerDeviceModeOptional } from '@/infrastructure/peer-device/peerDeviceContextState';
-import { useNotification } from '@/shared/notification-system';
-import './PeerRemoteBadge.scss';
-
-export const PeerRemoteBadge: React.FC = () => {
-  const { t } = useI18n('common');
-  const { success, warning } = useNotification();
-  const peerDevice = usePeerDeviceModeOptional();
-
-  const handleDisconnect = useCallback(async () => {
-    if (!peerDevice?.peerMode.active) {
-      return;
-    }
-    try {
-      await peerDevice.exitPeerMode();
-      success(t('accountLogin.disconnectPeer'));
-    } catch (e) {
-      warning(e instanceof Error ? e.message : String(e));
-    }
-  }, [peerDevice, success, t, warning]);
-
-  if (!peerDevice?.peerMode.active) {
-    return null;
-  }
-
-  const { deviceName } = peerDevice.peerMode;
-
-  return (
-    <div
-      className="bitfun-peer-remote-badge"
-      data-testid="peer-remote-badge"
-      title={t('accountLogin.peerRemoteBadgeTitle', { name: deviceName })}
-      data-bf-component="peer-device"
-      data-bf-part="badge"
-    >
-      <Monitor
-        size={13}
-        className="bitfun-peer-remote-badge__icon"
-        aria-hidden="true"
-        data-bf-component="peer-device"
-        data-bf-part="badgeIcon"
-      />
-      <span
-        className="bitfun-peer-remote-badge__label"
-        data-bf-component="peer-device"
-        data-bf-part="badgeLabel"
-      >
-        {t('accountLogin.peerRemoteLabel', { name: deviceName })}
-      </span>
-      <button
-        type="button"
-        className="bitfun-peer-remote-badge__disconnect"
-        data-bf-component="peer-device"
-        data-bf-part="disconnectButton"
-        onClick={() => {
-          void handleDisconnect();
-        }}
-      >
-        {t('accountLogin.disconnectPeer')}
-      </button>
-    </div>
-  );
-};
-
-export default PeerRemoteBadge;
diff --git a/src/web-ui/src/infrastructure/peer-device/README.md b/src/web-ui/src/infrastructure/peer-device/README.md
index 264a3bed74..8d4af375f0 100644
--- a/src/web-ui/src/infrastructure/peer-device/README.md
+++ b/src/web-ui/src/infrastructure/peer-device/README.md
@@ -5,6 +5,61 @@ Controller-side React/transport layer for Peer Device Mode. Architecture:
 
 ## Invariants (do not regress)
 
+0. **A surface switch is a view change, not a teardown.** Attachments and the
+   rendered surface are independent: peers stay attached (and keep running our
+   work) after the UI moves elsewhere, and `switchToLocal` is a switch, not a
+   disconnect. Two consequences:
+
+   - Everything in `resetProductSurface()` must be **frontend-only**.
+     `resetProductSurface` runs before the transport swap, so any backend call
+     it makes lands on the device being *left*. `terminal_shutdown_all` and
+     `lsp_close_workspace` were exactly that bug: switching away killed the
+     PTYs and language servers an agent turn there was still using
+     (regression: 2026-08-14 multi-device switch). Use
+     `TerminalService.disconnect()` and
+     `WorkspaceLspManager.detachAllForSurfaceSwitch()`.
+   - **Identity includes the device surface.** Workspace paths and session ids
+     can be equal on different machines. FlowChat/workspace containers,
+     state machines, processing status, pending messages, composer drafts,
+     request dedup and capability caches must therefore use
+     `(DeviceSurfaceId, local identity)`. `activateSurface` commits transport,
+     event routing and container selection before notifying observers. A normal
+     switch preserves every container; only explicit/lost attachment disposal
+     may call `discardSurfaceState`.
+   - **In-flight submissions must survive the switch.** `startTurn` has an
+     async window between adding the projection turn and re-reading the
+     session (state transition, worktree bind, model sync). Clearing the store
+     inside that window made the submission resume against a missing session
+     and throw `Session lost after adding dialog turn` — before
+     `start_dialog_turn`, so the message reached no host at all (regression:
+     2026-08-15). `resetProductSurface` therefore awaits
+     `waitForInFlightSubmissions` first. `sendMessage` and its driver carry one
+     `SurfaceScope`; after every host await, a stale epoch abandons without
+     writing into the newly selected container, and an unaccepted message is
+     re-queued onto its original surface. Any new await inside `startTurn`
+     widens that window and must keep the same scope checkpoint.
+   - **Reconciliation repairs a projection, never guts it.** The wholesale
+     replace path (`replaceRunningSnapshot`) skips the forward-progress
+     comparator so a settled turn can adopt the host's copy. A turn keeps its
+     identity and user message independently of its rounds, so a windowed or
+     not-yet-checkpointed snapshot can name the turn while carrying none of its
+     work — and a first-time surface projection has no state machines, so
+     *every* turn reads as idle and qualifies for replacement.
+     That combination erased the whole response and left only the prompt on
+     screen (regression: 2026-08-15). `snapshotDropsProjectedTurnContent` gates
+     the replace; the refresh loop still re-attaches an executing turn when a
+     snapshot is refused, or a rebuilt surface would render it as static
+     history.
+   - **Surface-scoped events must stay routed by source device.** Background
+     attachments mean several agent streams share one event bus. The
+     controller tags re-emitted peer payloads with `__bitfunSourceDeviceId`
+     and `deviceSurfaceRouting.ts` (applied inside
+     `TauriTransportAdapter.listen`) drops anything not produced by the
+     rendered device. Adding a fanned-out event on the Rust side means adding
+     it to `SURFACE_SCOPED_EVENTS`/prefixes too, or local and peer streams will
+     interleave in one store. Never route control-plane events (`account://…`)
+     — they must always pass.
+
 1. **Cloud session/turn APIs stay on the controller** (`LOCAL_ONLY` in
    `peer-device-adapter.ts`). Peer history comes from HostInvoke
    (`restore_session_view`, list sessions, …), not from
@@ -44,9 +99,12 @@ Controller-side React/transport layer for Peer Device Mode. Architecture:
 8. **`relay_deploy_*` is LOCAL_ONLY.** One-click deploy SSHes from the
    controller to a user-owned host; do not HostInvoke it onto the peer.
 
-9. **Clear workspace before peer flag emit.** `resetProductSurface` must call
-   `workspaceManager.clearForPeerModeSwitch()` so SessionModule cannot prefer
-   a stale controller path while rebootstrap is in flight. Never pass `{}` to
+9. **Select workspace state atomically with transport.** Before commit,
+   `workspaceManager.clearForPeerModeSwitch()` invalidates work still in flight
+   but deliberately preserves the device being left. `activateSurface` then
+   selects the target's cached workspace container in the same synchronous
+   commit that swaps transport, before the peer-mode event. SessionModule must
+   never observe A's path with B's transport. Never pass `{}` to
    `createChatSession` when a live workspace exists — use
    `flowChatSessionConfigForCurrentWorkspace`.
 
@@ -63,8 +121,12 @@ Controller-side React/transport layer for Peer Device Mode. Architecture:
     succeeding without affecting the process.
 
 12. **Active chat has snapshot self-healing.** DeviceEvent has no ACK/replay, so
-    FlowChat reconciles the active Peer session from `restore_session_view`
-    every 3s and immediately after a detected event gap. The Peer Host must
+    FlowChat reconciles the active session from `restore_session_view`
+    every 3s and immediately after a detected event gap. This is gated on
+    `isSurfaceReconcileEnabled()`, **not** on Peer Mode: once a window has
+    switched surface, a turn left running on the local device also needs the
+    repair, because its events were dropped by surface routing while another
+    device was rendered. The Peer Host must
     overlay its live in-memory session state on the persisted view; otherwise
     an in-progress turn is normalized as interrupted history and later chunks
     are dropped by the controller state machine. Reconciliation must not
@@ -90,10 +152,11 @@ Controller-side React/transport layer for Peer Device Mode. Architecture:
     tail; the controller must not follow it with an unconditional full restore.
     `load_session_turn_window` is a high-priority, retryable read and carries
     the same session/workspace scope as restore. Sequential history scrolling
-    and turn-rail navigation request bounded windows. Search, edit, rollback,
-    and an older Host that rejects the window command use the shared explicit
-    full-history ensure fallback. Never include catalog preview text in Peer
-    request/response logs.
+    and turn-rail navigation request bounded windows. Search and older Hosts
+    that reject the window command use the shared explicit full-history ensure
+    fallback. Targeted rollback is separately capability-gated and never falls
+    back to a controller-local or numeric rollback path. Never include catalog
+    preview text in Peer request/response logs.
 
 ## Related account-login guards
 
diff --git a/src/web-ui/src/infrastructure/peer-device/appearance.ts b/src/web-ui/src/infrastructure/peer-device/appearance.ts
index 13b3cfc7ab..30a39a49c1 100644
--- a/src/web-ui/src/infrastructure/peer-device/appearance.ts
+++ b/src/web-ui/src/infrastructure/peer-device/appearance.ts
@@ -20,10 +20,13 @@ export const peerDeviceAppearanceDescriptor: AppearanceSurfaceDescriptor = {
     { id: 'footer' },
     { id: 'selection' },
     { id: 'actions' },
-    { id: 'badge' },
-    { id: 'badgeIcon' },
-    { id: 'badgeLabel' },
-    { id: 'disconnectButton' },
+    { id: 'switcher' },
+    { id: 'switcherLabel' },
+    { id: 'switcherElsewhere' },
+    { id: 'switcherMenu' },
+    { id: 'switcherItem' },
+    { id: 'switcherStatusDot' },
+    { id: 'switcherDisconnect' },
   ],
   states: [
     { id: 'loading', selector: { kind: 'self', suffix: '[data-bf-state~="loading"]' } },
@@ -31,5 +34,9 @@ export const peerDeviceAppearanceDescriptor: AppearanceSurfaceDescriptor = {
     { id: 'empty', selector: { kind: 'self', suffix: '[data-bf-state~="empty"]' } },
     { id: 'selected', selector: { kind: 'self', suffix: '[data-bf-state~="selected"]' } },
     { id: 'disabled', selector: { kind: 'self', suffix: ':disabled' } },
+    { id: 'remote', selector: { kind: 'self', suffix: '[data-bf-state~="remote"]' } },
+    { id: 'local', selector: { kind: 'self', suffix: '[data-bf-state~="local"]' } },
+    { id: 'busy', selector: { kind: 'self', suffix: '[data-bf-state~="busy"]' } },
+    { id: 'offline', selector: { kind: 'self', suffix: '[data-bf-state~="offline"]' } },
   ],
 };
diff --git a/src/web-ui/src/infrastructure/peer-device/deviceActivity.test.ts b/src/web-ui/src/infrastructure/peer-device/deviceActivity.test.ts
new file mode 100644
index 0000000000..ef07684dff
--- /dev/null
+++ b/src/web-ui/src/infrastructure/peer-device/deviceActivity.test.ts
@@ -0,0 +1,80 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import {
+  routeSurfaceEvent,
+  setActiveSurfaceDeviceId,
+} from './deviceSurfaceRouting';
+import {
+  clearDeviceActivity,
+  installDeviceActivityTracking,
+  isDeviceBusy,
+} from './deviceActivity';
+
+let uninstall: (() => void) | null = null;
+
+function track(): void {
+  uninstall = installDeviceActivityTracking();
+}
+
+afterEach(() => {
+  uninstall?.();
+  uninstall = null;
+  setActiveSurfaceDeviceId(null);
+});
+
+function start(deviceId: string | null, sessionId: string): void {
+  routeSurfaceEvent('agentic://dialog-turn-started', {
+    sessionId,
+    ...(deviceId ? { __bitfunSourceDeviceId: deviceId } : {}),
+  });
+}
+
+function finish(deviceId: string | null, sessionId: string): void {
+  routeSurfaceEvent('agentic://dialog-turn-completed', {
+    sessionId,
+    ...(deviceId ? { __bitfunSourceDeviceId: deviceId } : {}),
+  });
+}
+
+describe('deviceActivity', () => {
+  it('tracks work on a device the UI is not rendering', () => {
+    track();
+    setActiveSurfaceDeviceId(null);
+
+    start('device-b', 's1');
+    expect(isDeviceBusy('device-b')).toBe(true);
+    expect(isDeviceBusy(null)).toBe(false);
+
+    finish('device-b', 's1');
+    expect(isDeviceBusy('device-b')).toBe(false);
+  });
+
+  it('tracks local and remote work at the same time', () => {
+    track();
+    setActiveSurfaceDeviceId('device-b');
+
+    start(null, 'local-1');
+    start('device-b', 'peer-1');
+
+    expect(isDeviceBusy(null)).toBe(true);
+    expect(isDeviceBusy('device-b')).toBe(true);
+  });
+
+  it('stays busy until every running session on a device ends', () => {
+    track();
+    start('device-b', 's1');
+    start('device-b', 's2');
+
+    finish('device-b', 's1');
+    expect(isDeviceBusy('device-b')).toBe(true);
+
+    finish('device-b', 's2');
+    expect(isDeviceBusy('device-b')).toBe(false);
+  });
+
+  it('drops tracked work for a disconnected device', () => {
+    track();
+    start('device-b', 's1');
+    clearDeviceActivity('device-b');
+    expect(isDeviceBusy('device-b')).toBe(false);
+  });
+});
diff --git a/src/web-ui/src/infrastructure/peer-device/deviceActivity.ts b/src/web-ui/src/infrastructure/peer-device/deviceActivity.ts
new file mode 100644
index 0000000000..9bac29c76f
--- /dev/null
+++ b/src/web-ui/src/infrastructure/peer-device/deviceActivity.ts
@@ -0,0 +1,125 @@
+/**
+ * Per-device agent activity, derived from the surface event stream.
+ *
+ * Attached peers keep streaming turn lifecycle events even while the UI
+ * renders another device, so the device switcher can show which machines are
+ * still working without polling any of them. Local activity uses the same
+ * events with a `null` source device.
+ *
+ * This is a display hint, not an authority: a device the controller is not
+ * attached to reports nothing, and a turn that started before attach is only
+ * observed once its first lifecycle event arrives.
+ */
+
+import { observeSurfaceEvents } from './deviceSurfaceRouting';
+
+/** `null` is the local device. */
+export type DeviceActivityKey = string | null;
+
+const TURN_STARTED = 'agentic://dialog-turn-started';
+const TURN_ENDED = new Set([
+  'agentic://dialog-turn-completed',
+  'agentic://dialog-turn-failed',
+  'agentic://dialog-turn-cancelled',
+  'agentic://dialog-turn-interrupted',
+]);
+
+/** Device key -> set of session ids known to be running on it. */
+const runningSessionsByDevice = new Map<string, Set<string>>();
+const listeners = new Set<() => void>();
+
+/**
+ * Map key for the local device. Peers are keyed by their device id, which
+ * is always a UUID, so an '@' prefix cannot collide with one.
+ */
+const LOCAL_KEY = '@local';
+
+function keyOf(deviceId: DeviceActivityKey): string {
+  return deviceId === null ? LOCAL_KEY : deviceId;
+}
+
+function readSessionId(payload: unknown): string | null {
+  if (!payload || typeof payload !== 'object') {
+    return null;
+  }
+  const record = payload as Record<string, unknown>;
+  const sessionId = record.sessionId ?? record.session_id;
+  return typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : null;
+}
+
+function notify(): void {
+  for (const listener of listeners) {
+    try {
+      listener();
+    } catch {
+      // A subscriber must never break activity tracking for the others.
+    }
+  }
+}
+
+function setRunning(deviceId: DeviceActivityKey, sessionId: string, running: boolean): void {
+  const key = keyOf(deviceId);
+  const sessions = runningSessionsByDevice.get(key);
+  if (running) {
+    if (sessions?.has(sessionId)) {
+      return;
+    }
+    if (sessions) {
+      sessions.add(sessionId);
+    } else {
+      runningSessionsByDevice.set(key, new Set([sessionId]));
+    }
+    notify();
+    return;
+  }
+  if (!sessions?.delete(sessionId)) {
+    return;
+  }
+  if (sessions.size === 0) {
+    runningSessionsByDevice.delete(key);
+  }
+  notify();
+}
+
+export function isDeviceBusy(deviceId: DeviceActivityKey): boolean {
+  return (runningSessionsByDevice.get(keyOf(deviceId))?.size ?? 0) > 0;
+}
+
+/** Drop tracked work for a device that went offline or was disconnected. */
+export function clearDeviceActivity(deviceId: DeviceActivityKey): void {
+  if (runningSessionsByDevice.delete(keyOf(deviceId))) {
+    notify();
+  }
+}
+
+export function subscribeDeviceActivity(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+let installed: (() => void) | null = null;
+
+/** Start deriving activity from the surface event stream. Idempotent. */
+export function installDeviceActivityTracking(): () => void {
+  if (installed) {
+    return installed;
+  }
+  const dispose = observeSurfaceEvents((event, sourceDeviceId, payload) => {
+    if (event !== TURN_STARTED && !TURN_ENDED.has(event)) {
+      return;
+    }
+    const sessionId = readSessionId(payload);
+    if (!sessionId) {
+      return;
+    }
+    setRunning(sourceDeviceId, sessionId, event === TURN_STARTED);
+  });
+  installed = () => {
+    dispose();
+    installed = null;
+    runningSessionsByDevice.clear();
+  };
+  return installed;
+}
diff --git a/src/web-ui/src/infrastructure/peer-device/deviceSurface.ts b/src/web-ui/src/infrastructure/peer-device/deviceSurface.ts
new file mode 100644
index 0000000000..2d724fc5fc
--- /dev/null
+++ b/src/web-ui/src/infrastructure/peer-device/deviceSurface.ts
@@ -0,0 +1,196 @@
+/**
+ * Device surface identity, activation epochs, and cancellation.
+ *
+ * The frontend was built for exactly one host, and multi-device was retrofitted
+ * by mutating that host underneath it. Nothing carried a device dimension, so
+ * caches keyed by workspace path or session id collided across devices, and
+ * every switch was a destroy-and-rebuild whose in-flight work resumed against a
+ * wiped world.
+ *
+ * This module is the single source of truth for three things every other layer
+ * needs:
+ *
+ * 1. **Identity** — a `DeviceSurfaceId` that names *which device* a piece of
+ *    state, cache entry, or negotiated capability belongs to. Anything keyed by
+ *    path or session id must be scoped by it.
+ * 2. **Epoch** — a monotonic activation number. Switching surfaces activates a
+ *    new epoch and aborts the previous one, so stale work can be recognised
+ *    instead of racing.
+ * 3. **Cancellation** — an `AbortSignal` per activation plus a typed
+ *    `SurfaceChangedError`, so callers unwind through one shared boundary
+ *    rather than a guard at every call site.
+ *
+ * Treat this file as a frozen contract: other layers import it, none of them
+ * reimplement it.
+ */
+
+/** `local` is this machine; any other value is a peer device id. */
+export type DeviceSurfaceId = string;
+
+export const LOCAL_SURFACE_ID: DeviceSurfaceId = 'local';
+
+export function surfaceIdForDevice(deviceId: string | null | undefined): DeviceSurfaceId {
+  const trimmed = deviceId?.trim();
+  return trimmed ? trimmed : LOCAL_SURFACE_ID;
+}
+
+export function isLocalSurface(surfaceId: DeviceSurfaceId): boolean {
+  return surfaceId === LOCAL_SURFACE_ID;
+}
+
+/**
+ * Raised when work started under one surface activation is observed after that
+ * activation ended. It is a control-flow signal, not a failure: callers must
+ * abandon quietly rather than report a product error.
+ */
+export class SurfaceChangedError extends Error {
+  readonly isSurfaceChangedError = true;
+  readonly surfaceId: DeviceSurfaceId;
+  readonly epoch: number;
+
+  constructor(surfaceId: DeviceSurfaceId, epoch: number, action?: string) {
+    super(
+      action
+        ? `Device surface changed while '${action}' was in flight (${surfaceId}#${epoch})`
+        : `Device surface changed (${surfaceId}#${epoch})`,
+    );
+    this.name = 'SurfaceChangedError';
+    this.surfaceId = surfaceId;
+    this.epoch = epoch;
+  }
+}
+
+export function isSurfaceChangedError(error: unknown): error is SurfaceChangedError {
+  return (
+    error instanceof SurfaceChangedError
+    || (typeof error === 'object'
+      && error !== null
+      && (error as { isSurfaceChangedError?: boolean }).isSurfaceChangedError === true)
+  );
+}
+
+/** One activation of one device surface. */
+export interface SurfaceScope {
+  readonly surfaceId: DeviceSurfaceId;
+  /** Monotonic across the whole window, not per surface. */
+  readonly epoch: number;
+  readonly signal: AbortSignal;
+  /** Whether this activation is still the rendered one. */
+  isCurrent(): boolean;
+  /** Throw `SurfaceChangedError` unless this activation is still current. */
+  assertCurrent(action?: string): void;
+  /** Scope a cache/request key to this activation's surface. */
+  key(...parts: Array<string | number | undefined | null>): string;
+}
+
+interface MutableScope extends SurfaceScope {
+  abort(): void;
+}
+
+let epochCounter = 0;
+let activeScope: MutableScope = createScope(LOCAL_SURFACE_ID);
+
+type SurfaceChangeListener = (scope: SurfaceScope) => void;
+const listeners = new Set<SurfaceChangeListener>();
+
+function createScope(surfaceId: DeviceSurfaceId): MutableScope {
+  const epoch = ++epochCounter;
+  const controller = new AbortController();
+  const scope: MutableScope = {
+    surfaceId,
+    epoch,
+    signal: controller.signal,
+    isCurrent: () => activeScope.epoch === epoch,
+    assertCurrent: (action?: string) => {
+      if (activeScope.epoch !== epoch) {
+        throw new SurfaceChangedError(surfaceId, epoch, action);
+      }
+    },
+    key: (...parts) => surfaceScopedKey(surfaceId, ...parts),
+    abort: () => controller.abort(),
+  };
+  return scope;
+}
+
+/**
+ * Key any per-device cache entry, request dedup entry, or capability record.
+ *
+ * Workspace paths and session ids are **not** unique across devices: the same
+ * repository is routinely checked out at the same path on two machines, and a
+ * capability negotiated with one host says nothing about another.
+ */
+export function surfaceScopedKey(
+  surfaceId: DeviceSurfaceId,
+  ...parts: Array<string | number | undefined | null>
+): string {
+  return JSON.stringify([surfaceId, ...parts.map(part => part ?? '')]);
+}
+
+export function getActiveSurfaceScope(): SurfaceScope {
+  return activeScope;
+}
+
+export function getActiveSurfaceId(): DeviceSurfaceId {
+  return activeScope.surfaceId;
+}
+
+/**
+ * Begin rendering `surfaceId`. Aborts the previous activation first, so work
+ * belonging to it fails fast instead of completing into a surface that no
+ * longer wants it. Re-activating the same surface still produces a new epoch.
+ *
+ * `beforeNotify` is the synchronous commit seam for the transport and event
+ * router. The new scope is already current while it runs, but subscribers are
+ * notified only after it returns. This keeps observers from ever seeing a new
+ * state container while product requests still use the previous device.
+ *
+ * The callback must be synchronous and non-throwing: it is the small atomic
+ * assignment portion of a switch, never asynchronous activation work.
+ */
+export function activateSurface(
+  surfaceId: DeviceSurfaceId,
+  beforeNotify?: (scope: SurfaceScope) => void,
+): SurfaceScope {
+  const previous = activeScope;
+  const next = createScope(surfaceId);
+  activeScope = next;
+  previous.abort();
+  beforeNotify?.(next);
+  for (const listener of Array.from(listeners)) {
+    try {
+      listener(next);
+    } catch {
+      // A listener must never prevent activation from completing.
+    }
+  }
+  return next;
+}
+
+export function onSurfaceActivated(listener: SurfaceChangeListener): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/**
+ * Run `task` under the current activation and drop its result if the surface
+ * moved on. Use at boundaries that write shared state after an await.
+ */
+export async function runInSurfaceScope<T>(
+  scope: SurfaceScope,
+  action: string,
+  task: () => Promise<T>,
+): Promise<T> {
+  scope.assertCurrent(action);
+  const result = await task();
+  scope.assertCurrent(action);
+  return result;
+}
+
+/** Test-only: return the registry to a pristine local activation. */
+export function resetDeviceSurfaceForTest(): void {
+  epochCounter = 0;
+  activeScope = createScope(LOCAL_SURFACE_ID);
+  listeners.clear();
+}
diff --git a/src/web-ui/src/infrastructure/peer-device/deviceSurfaceReconcile.ts b/src/web-ui/src/infrastructure/peer-device/deviceSurfaceReconcile.ts
new file mode 100644
index 0000000000..e2d7f174e3
--- /dev/null
+++ b/src/web-ui/src/infrastructure/peer-device/deviceSurfaceReconcile.ts
@@ -0,0 +1,35 @@
+/**
+ * Gate for active-session snapshot reconciliation.
+ *
+ * Reconciliation used to be a Peer Mode concern only, because the local
+ * surface was assumed to never miss an event. That stopped being true once
+ * devices keep working while the UI renders another one: a turn started on
+ * this machine goes on producing events that the routing layer drops for as
+ * long as another device is rendered, and the relay protocol has no
+ * ACK/replay to recover them.
+ *
+ * So once this window has switched surface at least once, the rendered
+ * surface — local included — heals itself from the host snapshot. A window
+ * that never leaves the local device does no extra polling at all.
+ */
+
+import { isPeerDeviceModeActive } from './peerModeFlag';
+
+let hasSwitchedSurface = false;
+
+export function markDeviceSurfaceSwitched(): void {
+  hasSwitchedSurface = true;
+}
+
+export function hasDeviceSurfaceSwitched(): boolean {
+  return hasSwitchedSurface;
+}
+
+/** Test-only reset; production code never returns to the pristine state. */
+export function resetDeviceSurfaceSwitchedForTest(): void {
+  hasSwitchedSurface = false;
+}
+
+export function isSurfaceReconcileEnabled(): boolean {
+  return isPeerDeviceModeActive() || hasSwitchedSurface;
+}
diff --git a/src/web-ui/src/infrastructure/peer-device/deviceSurfaceRouting.test.ts b/src/web-ui/src/infrastructure/peer-device/deviceSurfaceRouting.test.ts
new file mode 100644
index 0000000000..ac47e9edcd
--- /dev/null
+++ b/src/web-ui/src/infrastructure/peer-device/deviceSurfaceRouting.test.ts
@@ -0,0 +1,104 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+  PEER_EVENT_SOURCE_KEY,
+  PEER_EVENT_WRAPPED_PAYLOAD_KEY,
+  isSurfaceScopedEvent,
+  observeSurfaceEvents,
+  routeSurfaceEvent,
+  setActiveSurfaceDeviceId,
+} from './deviceSurfaceRouting';
+
+function peerPayload(deviceId: string, payload: Record<string, unknown>) {
+  return { ...payload, [PEER_EVENT_SOURCE_KEY]: deviceId };
+}
+
+afterEach(() => {
+  setActiveSurfaceDeviceId(null);
+});
+
+describe('isSurfaceScopedEvent', () => {
+  it('scopes agentic, backend and fanned-out product events', () => {
+    expect(isSurfaceScopedEvent('agentic://text-chunk')).toBe(true);
+    expect(isSurfaceScopedEvent('backend-event-toolexecutionstarted')).toBe(true);
+    expect(isSurfaceScopedEvent('terminal_event')).toBe(true);
+    expect(isSurfaceScopedEvent('permission://event')).toBe(true);
+  });
+
+  it('leaves control-plane events unscoped so they always pass', () => {
+    expect(isSurfaceScopedEvent('account://device-presence')).toBe(false);
+    expect(isSurfaceScopedEvent('account://login-state')).toBe(false);
+    expect(isSurfaceScopedEvent('workspace-identity-changed')).toBe(false);
+  });
+});
+
+describe('routeSurfaceEvent', () => {
+  it('delivers local events only while the local surface is rendered', () => {
+    setActiveSurfaceDeviceId(null);
+    expect(routeSurfaceEvent('agentic://text-chunk', { sessionId: 's1' }).deliver).toBe(true);
+
+    setActiveSurfaceDeviceId('device-b');
+    expect(routeSurfaceEvent('agentic://text-chunk', { sessionId: 's1' }).deliver).toBe(false);
+  });
+
+  it('delivers a peer event only to the surface rendering that peer', () => {
+    setActiveSurfaceDeviceId('device-b');
+    expect(
+      routeSurfaceEvent('agentic://text-chunk', peerPayload('device-b', { sessionId: 's1' })).deliver,
+    ).toBe(true);
+    expect(
+      routeSurfaceEvent('agentic://text-chunk', peerPayload('device-c', { sessionId: 's1' })).deliver,
+    ).toBe(false);
+  });
+
+  it('keeps local work out of a rendered peer surface', () => {
+    // The regression this routing exists for: a turn still running on this
+    // machine must not stream into the peer's chat.
+    setActiveSurfaceDeviceId('device-b');
+    const localChunk = routeSurfaceEvent('agentic://text-chunk', { sessionId: 'local-session' });
+    expect(localChunk.deliver).toBe(false);
+  });
+
+  it('strips the routing tag from delivered payloads', () => {
+    setActiveSurfaceDeviceId('device-b');
+    const route = routeSurfaceEvent(
+      'agentic://text-chunk',
+      peerPayload('device-b', { sessionId: 's1', content: 'hi' }),
+    );
+    expect(route.payload).toEqual({ sessionId: 's1', content: 'hi' });
+    expect(PEER_EVENT_SOURCE_KEY in (route.payload as object)).toBe(false);
+  });
+
+  it('unwraps non-object peer payloads', () => {
+    setActiveSurfaceDeviceId('device-b');
+    const route = routeSurfaceEvent('terminal_event', {
+      [PEER_EVENT_SOURCE_KEY]: 'device-b',
+      [PEER_EVENT_WRAPPED_PAYLOAD_KEY]: 'raw-string',
+    });
+    expect(route.deliver).toBe(true);
+    expect(route.payload).toBe('raw-string');
+  });
+
+  it('always delivers control-plane events regardless of surface', () => {
+    setActiveSurfaceDeviceId('device-b');
+    expect(routeSurfaceEvent('account://device-presence', { devices: [] }).deliver).toBe(true);
+  });
+
+  it('reports events from devices that are not rendered to observers', () => {
+    const observer = vi.fn();
+    const dispose = observeSurfaceEvents(observer);
+    try {
+      setActiveSurfaceDeviceId(null);
+      routeSurfaceEvent(
+        'agentic://dialog-turn-started',
+        peerPayload('device-b', { sessionId: 's1' }),
+      );
+      expect(observer).toHaveBeenCalledWith(
+        'agentic://dialog-turn-started',
+        'device-b',
+        { sessionId: 's1' },
+      );
+    } finally {
+      dispose();
+    }
+  });
+});
diff --git a/src/web-ui/src/infrastructure/peer-device/deviceSurfaceRouting.ts b/src/web-ui/src/infrastructure/peer-device/deviceSurfaceRouting.ts
new file mode 100644
index 0000000000..7288c14a29
--- /dev/null
+++ b/src/web-ui/src/infrastructure/peer-device/deviceSurfaceRouting.ts
@@ -0,0 +1,142 @@
+/**
+ * Device surface event routing.
+ *
+ * The controller re-emits Peer DeviceEvents under their original event name so
+ * every existing listener keeps working. That is only safe while exactly one
+ * device is producing product events. Once peers stay attached in the
+ * background — so their work keeps running while the UI looks at another
+ * device — the same bus carries several agent streams at once.
+ *
+ * The desktop controller therefore tags every re-emitted peer payload with the
+ * device that produced it (`remote_connect_api::PEER_EVENT_SOURCE_KEY`), and
+ * this module decides which of those streams the currently rendered surface is
+ * allowed to see. Untagged events are local by definition.
+ *
+ * Only *surface-scoped* events are routed. Control-plane events (account
+ * presence, login state, window chrome, updater, …) always pass through.
+ */
+
+/** Payload key injected by the controller. Keep in sync with the Rust const. */
+export const PEER_EVENT_SOURCE_KEY = '__bitfunSourceDeviceId';
+
+/** Wrapper key used when a peer payload is not a JSON object. */
+export const PEER_EVENT_WRAPPED_PAYLOAD_KEY = '__bitfunSourcePayload';
+
+/**
+ * Product events that belong to one device surface. Mirrors the desktop
+ * fan-out allowlist (`should_fanout_peer_ui_event`) plus the projected
+ * `agentic://*` stream.
+ */
+const SURFACE_SCOPED_EVENTS = new Set<string>([
+  'terminal_event',
+  'file-system-changed',
+  'lsp-event',
+  'permission://event',
+  'account://settings-applied',
+  'ai://model-catalog-updated',
+]);
+
+const SURFACE_SCOPED_PREFIXES = ['agentic://', 'backend-event-'];
+
+export function isSurfaceScopedEvent(event: string): boolean {
+  if (SURFACE_SCOPED_EVENTS.has(event)) {
+    return true;
+  }
+  return SURFACE_SCOPED_PREFIXES.some(prefix => event.startsWith(prefix));
+}
+
+/** `null` means the local device is the rendered surface. */
+let activeSurfaceDeviceId: string | null = null;
+
+export function setActiveSurfaceDeviceId(deviceId: string | null): void {
+  activeSurfaceDeviceId = deviceId;
+}
+
+export function getActiveSurfaceDeviceId(): string | null {
+  return activeSurfaceDeviceId;
+}
+
+/**
+ * Read the source device of an event payload.
+ *
+ * Returns `null` for payloads produced by the local host — they never carry
+ * the tag because the controller only adds it while re-emitting.
+ */
+export function readSourceDeviceId(payload: unknown): string | null {
+  if (!payload || typeof payload !== 'object') {
+    return null;
+  }
+  const source = (payload as Record<string, unknown>)[PEER_EVENT_SOURCE_KEY];
+  return typeof source === 'string' && source.length > 0 ? source : null;
+}
+
+/** Strip the routing tag so product consumers see the original payload shape. */
+export function unwrapSurfacePayload<T>(payload: T): T {
+  if (!payload || typeof payload !== 'object') {
+    return payload;
+  }
+  const record = payload as Record<string, unknown>;
+  if (!(PEER_EVENT_SOURCE_KEY in record)) {
+    return payload;
+  }
+  if (PEER_EVENT_WRAPPED_PAYLOAD_KEY in record) {
+    return record[PEER_EVENT_WRAPPED_PAYLOAD_KEY] as T;
+  }
+  const { [PEER_EVENT_SOURCE_KEY]: _source, ...rest } = record;
+  return rest as T;
+}
+
+/**
+ * Observers see every surface-scoped event, including events from devices the
+ * UI is not currently rendering. That is how background device activity (a
+ * peer still running a turn) stays visible in the device switcher.
+ */
+export type SurfaceEventObserver = (
+  event: string,
+  sourceDeviceId: string | null,
+  payload: unknown,
+) => void;
+
+const observers = new Set<SurfaceEventObserver>();
+
+export function observeSurfaceEvents(observer: SurfaceEventObserver): () => void {
+  observers.add(observer);
+  return () => {
+    observers.delete(observer);
+  };
+}
+
+export interface SurfaceEventRoute<T> {
+  /** Whether the active surface should receive this event. */
+  deliver: boolean;
+  /** Payload with the routing tag removed. */
+  payload: T;
+}
+
+/**
+ * Decide whether an incoming event belongs to the rendered surface.
+ *
+ * Non surface-scoped events always pass. Surface-scoped events are delivered
+ * only when their producing device is the one currently rendered.
+ */
+export function routeSurfaceEvent<T>(event: string, payload: T): SurfaceEventRoute<T> {
+  const sourceDeviceId = readSourceDeviceId(payload);
+
+  if (!isSurfaceScopedEvent(event)) {
+    return { deliver: true, payload: unwrapSurfacePayload(payload) };
+  }
+
+  const unwrapped = unwrapSurfacePayload(payload);
+
+  if (observers.size > 0) {
+    for (const observer of observers) {
+      try {
+        observer(event, sourceDeviceId, unwrapped);
+      } catch {
+        // A misbehaving observer must never drop a product event.
+      }
+    }
+  }
+
+  return { deliver: activeSurfaceDeviceId === sourceDeviceId, payload: unwrapped };
+}
diff --git a/src/web-ui/src/infrastructure/peer-device/peerDeviceContextState.ts b/src/web-ui/src/infrastructure/peer-device/peerDeviceContextState.ts
index 00ed19bc5e..10cc2a9f52 100644
--- a/src/web-ui/src/infrastructure/peer-device/peerDeviceContextState.ts
+++ b/src/web-ui/src/infrastructure/peer-device/peerDeviceContextState.ts
@@ -1,13 +1,47 @@
 import { createContext, useContext } from 'react';
+import type {
+  PeerConnectionHealth,
+  PeerConnectionLostReason,
+} from './PeerConnectionManager';
 
+/**
+ * The device surface currently rendered by this window.
+ *
+ * Exactly one device is rendered at a time; every attached device keeps
+ * executing regardless of which one that is.
+ */
 export type PeerModeState =
   | { active: false }
   | { active: true; deviceId: string; deviceName: string };
 
+/** A peer whose control link is kept alive, rendered or not. */
+export interface PeerAttachmentState {
+  deviceId: string;
+  deviceName: string;
+  health: PeerConnectionHealth;
+  lostReason: PeerConnectionLostReason | null;
+}
+
+/** A newer request may intentionally supersede an earlier rapid switch. */
+export type SurfaceSwitchOutcome = 'activated' | 'superseded';
+
 export interface PeerDeviceContextValue {
+  /** Rendered surface. `active: false` means this machine. */
   peerMode: PeerModeState;
-  enterPeerMode: (deviceId: string, deviceName: string) => Promise<void>;
-  exitPeerMode: (reason?: string) => Promise<void>;
+  /**
+   * Peers this controller holds a live control link to, including the rendered
+   * one. Attachments survive UI switches so their agents keep running and keep
+   * reporting progress.
+   */
+  attachments: PeerAttachmentState[];
+  /** Render another device, attaching it first when needed. */
+  switchToDevice: (deviceId: string, deviceName: string) => Promise<SurfaceSwitchOutcome>;
+  /** Render this machine again. Peer attachments are left running. */
+  switchToLocal: (reason?: string) => Promise<SurfaceSwitchOutcome>;
+  /** Drop the control link to a peer, switching to local when it is rendered. */
+  disconnectDevice: (deviceId: string, reason?: string) => Promise<void>;
+  /** Drop every control link. Used on logout / account change. */
+  disconnectAllDevices: (reason?: string) => Promise<void>;
 }
 
 export const PeerDeviceContext = createContext<PeerDeviceContextValue | null>(null);
diff --git a/src/web-ui/src/infrastructure/peer-device/peerDeviceSurfaceRuntime.ts b/src/web-ui/src/infrastructure/peer-device/peerDeviceSurfaceRuntime.ts
new file mode 100644
index 0000000000..bdbe5a5601
--- /dev/null
+++ b/src/web-ui/src/infrastructure/peer-device/peerDeviceSurfaceRuntime.ts
@@ -0,0 +1,203 @@
+/** Production composition for the window-wide device-surface controller. */
+
+import type { ITransportAdapter } from '@/infrastructure/api/adapters/base';
+import {
+  createTransportAdapter,
+  getTransportAdapter,
+  getTransportSurfaceBinding,
+  setTransportAdapter,
+} from '@/infrastructure/api/adapters';
+import { PeerDeviceTransportAdapter } from '@/infrastructure/api/adapters/peer-device-adapter';
+import { api } from '@/infrastructure/api/service-api/ApiClient';
+import { configAPI } from '@/infrastructure/api/service-api/ConfigAPI';
+import { configManager } from '@/infrastructure/config/services/ConfigManager';
+import { workspaceManager } from '@/infrastructure/services/business/workspaceManager';
+import { FlowChatManager } from '@/flow_chat/services/FlowChatManager';
+import { useSceneStore } from '@/app/stores/sceneStore';
+import { clearAgentCanvasForPeerSwitch } from '@/app/components/panels/content-canvas/stores';
+import { editorManager } from '@/tools/editor/services/EditorManager';
+import { WorkspaceLspManager } from '@/tools/lsp/services/WorkspaceLspManager';
+import { lspAdapterManager } from '@/tools/lsp/services/LspAdapterManager';
+import { TerminalService } from '@/tools/terminal/services/TerminalService';
+import { createLogger } from '@/shared/utils/logger';
+import {
+  activateSurface,
+  isSurfaceChangedError,
+  type SurfaceScope,
+} from './deviceSurface';
+import { setActiveSurfaceDeviceId } from './deviceSurfaceRouting';
+import { markDeviceSurfaceSwitched } from './deviceSurfaceReconcile';
+import { setPeerDeviceModeActiveFlag } from './peerModeFlag';
+import { clearDeviceActivity } from './deviceActivity';
+import { peerConnectionManager } from './PeerConnectionManager';
+import {
+  PeerDeviceSurfaceController,
+  type PeerDeviceSurfaceControllerDependencies,
+} from './PeerDeviceSurfaceController';
+
+const log = createLogger('PeerDeviceSurfaceRuntime');
+
+const SUBMIT_DRAIN_TIMEOUT_MS = 8_000;
+
+async function resetProductSurface(assertCurrent: () => void): Promise<void> {
+  assertCurrent();
+  try {
+    const drained = await FlowChatManager.getInstance()
+      .waitForInFlightSubmissions(SUBMIT_DRAIN_TIMEOUT_MS);
+    if (!drained) {
+      log.warn('Device surface switch proceeded with a submission still in flight');
+    }
+  } catch (error) {
+    if (isSurfaceChangedError(error)) {
+      throw error;
+    }
+    log.warn('Failed to await in-flight submissions before surface switch', { error });
+  }
+  assertCurrent();
+
+  try {
+    FlowChatManager.getInstance().resetForPeerModeSwitch();
+  } catch (error) {
+    log.warn('Failed to reset FlowChat during device surface switch', { error });
+  }
+
+  // Clear before the peer-mode event so session creation cannot reuse a path
+  // owned by the device being left.
+  try {
+    workspaceManager.clearForPeerModeSwitch();
+  } catch (error) {
+    log.warn('Failed to clear workspace during device surface switch', { error });
+  }
+
+  try {
+    await TerminalService.getInstance().disconnect();
+  } catch (error) {
+    log.warn('Failed to disconnect terminal listeners during device surface switch', { error });
+  }
+  assertCurrent();
+
+  try {
+    lspAdapterManager.disposeAll();
+    WorkspaceLspManager.detachAllForSurfaceSwitch();
+  } catch (error) {
+    log.warn('Failed to reset LSP during device surface switch', { error });
+  }
+
+  try {
+    editorManager.destroy();
+  } catch (error) {
+    log.warn('Failed to clear editor during device surface switch', { error });
+  }
+
+  try {
+    clearAgentCanvasForPeerSwitch();
+  } catch (error) {
+    log.warn('Failed to clear canvas during device surface switch', { error });
+  }
+
+  try {
+    useSceneStore.getState().resetForPeerSwitch();
+  } catch (error) {
+    log.warn('Failed to reset scenes during device surface switch', { error });
+  }
+  assertCurrent();
+}
+
+async function reloadConfigFromCurrentTransport(scope: SurfaceScope): Promise<void> {
+  try {
+    await configAPI.reloadConfig();
+    scope.assertCurrent('reload device surface config');
+    configManager.clearCache();
+    await configManager.reload();
+    scope.assertCurrent('reload device surface config');
+  } catch (error) {
+    if (isSurfaceChangedError(error)) {
+      throw error;
+    }
+    log.warn('Failed to reload config after device surface transport switch', { error });
+  }
+}
+
+async function setPeerControllerActive(active: boolean, required: boolean): Promise<void> {
+  try {
+    await api.invoke('peer_controller_set_active', { active });
+  } catch (error) {
+    log.warn('Failed to update peer controller active flag', { active, error });
+    if (required) {
+      throw error instanceof Error
+        ? error
+        : new Error(`peer_controller_set_active(${active}) failed`);
+    }
+  }
+}
+
+function emitPeerModeChanged(detail: { active: boolean; deviceId?: string }): void {
+  setPeerDeviceModeActiveFlag(detail.active);
+  window.dispatchEvent(new CustomEvent('peer-mode:changed', { detail }));
+}
+
+function createDependencies(): PeerDeviceSurfaceControllerDependencies {
+  const bootAdapter = getTransportAdapter();
+  // Preserve the adapter the application booted with before the first peer
+  // commit replaces the registry binding. Otherwise leaving that first peer
+  // creates a second local adapter and strands the original listener owner.
+  let localAdapter: ITransportAdapter | null = bootAdapter instanceof PeerDeviceTransportAdapter
+    ? null
+    : bootAdapter;
+
+  return {
+    connectionManager: peerConnectionManager,
+    getLocalAdapter: async () => {
+      if (!localAdapter) {
+        const booted = getTransportAdapter();
+        localAdapter = booted instanceof PeerDeviceTransportAdapter
+          ? createTransportAdapter()
+          : booted;
+        await localAdapter.connect();
+      }
+      return localAdapter;
+    },
+    resetProductSurface,
+    reloadConfig: reloadConfigFromCurrentTransport,
+    rebootstrapWorkspaces: async (scope) => {
+      await workspaceManager.reinitializeForPeerModeSwitch();
+      scope.assertCurrent('rebootstrap device surface workspaces');
+    },
+    setPeerControllerActive,
+    commitSurface: target => activateSurface(target.surfaceId, () => {
+      setActiveSurfaceDeviceId(target.deviceId);
+      setTransportAdapter(target.adapter, target.surfaceId);
+      api.reattachTransportAdapter();
+    }),
+    invalidateCurrentSurface: () => {
+      const current = getTransportSurfaceBinding();
+      return activateSurface(current.surfaceId, () => {
+        setTransportAdapter(current.adapter, current.surfaceId);
+      });
+    },
+    emitPeerModeChanged,
+    markSurfaceSwitched: markDeviceSurfaceSwitched,
+    discardSurfaceState: surfaceId => {
+      FlowChatManager.getInstance().discardDeviceSurface(surfaceId);
+      workspaceManager.discardDeviceSurface(surfaceId);
+    },
+    clearDeviceActivity,
+    emitAutoExit: detail => {
+      window.dispatchEvent(new CustomEvent('peer-mode:auto-exit', { detail }));
+    },
+    listenPresence: listener => api.listen<{
+      devices: Array<{ device_id: string }>;
+    }>('account://device-presence', payload => {
+      listener((payload?.devices ?? []).map(device => device.device_id));
+    }),
+    listenLoginState: listener => api.listen<{ logged_in: boolean }>(
+      'account://login-state',
+      payload => listener(payload?.logged_in === true),
+    ),
+  };
+}
+
+/** Window-wide controller: connections and activation state outlive React renders. */
+export const peerDeviceSurfaceController = new PeerDeviceSurfaceController(
+  createDependencies(),
+);
diff --git a/src/web-ui/src/infrastructure/peer-device/useAccountDeviceRoster.ts b/src/web-ui/src/infrastructure/peer-device/useAccountDeviceRoster.ts
new file mode 100644
index 0000000000..8fe01e1458
--- /dev/null
+++ b/src/web-ui/src/infrastructure/peer-device/useAccountDeviceRoster.ts
@@ -0,0 +1,143 @@
+/**
+ * Account device roster for the sidebar device switcher.
+ *
+ * A deliberately small read-only view of the account's devices: the account
+ * dialog owns login, sync and device removal, this only needs "who can I hand
+ * work to right now". Device routing is re-established by the host at startup,
+ * so presence flows without opening the dialog.
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { api } from '@/infrastructure/api/service-api/ApiClient';
+import { remoteConnectAPI } from '@/infrastructure/api/service-api/RemoteConnectAPI';
+import { createLogger } from '@/shared/utils/logger';
+import { useAccountLoginState } from '@/infrastructure/account/useAccountLoginState';
+
+const log = createLogger('AccountDeviceRoster');
+
+const ROSTER_POLL_MS = 60_000;
+
+export interface DeviceRosterEntry {
+  deviceId: string;
+  deviceName: string;
+  online: boolean;
+  isLocal: boolean;
+}
+
+export interface AccountDeviceRoster {
+  loggedIn: boolean;
+  localDeviceId: string | null;
+  localDeviceName: string | null;
+  /** Local device first, then online peers, then offline peers. */
+  devices: DeviceRosterEntry[];
+  refresh: () => void;
+}
+
+export function useAccountDeviceRoster(): AccountDeviceRoster {
+  const { loggedIn, deviceName: localDeviceName } = useAccountLoginState();
+  const [localDeviceId, setLocalDeviceId] = useState<string | null>(null);
+  const [peers, setPeers] = useState<DeviceRosterEntry[]>([]);
+  const generationRef = useRef(0);
+
+  const refresh = useCallback(() => {
+    if (!loggedIn) {
+      return;
+    }
+    const generation = ++generationRef.current;
+    void (async () => {
+      try {
+        const [info, list] = await Promise.all([
+          remoteConnectAPI.getDeviceInfo(),
+          remoteConnectAPI.accountListDevices(),
+        ]);
+        if (generationRef.current !== generation) {
+          return;
+        }
+        setLocalDeviceId(info.device_id);
+        setPeers(
+          list
+            .filter(device => device.device_id !== info.device_id)
+            .map(device => ({
+              deviceId: device.device_id,
+              deviceName: device.device_name,
+              online: device.online,
+              isLocal: false,
+            })),
+        );
+      } catch (error) {
+        // A transport hiccup is not evidence that devices went away; keep the
+        // last roster until presence or the next poll corrects it.
+        log.warn('Failed to refresh account device roster', error);
+      }
+    })();
+  }, [loggedIn]);
+
+  useEffect(() => {
+    if (!loggedIn) {
+      generationRef.current += 1;
+      setLocalDeviceId(null);
+      setPeers([]);
+      return;
+    }
+    refresh();
+    const poll = setInterval(refresh, ROSTER_POLL_MS);
+    return () => clearInterval(poll);
+  }, [loggedIn, refresh]);
+
+  useEffect(() => {
+    if (!loggedIn) {
+      return;
+    }
+    return api.listen<{ devices: Array<{ device_id: string; device_name: string }> }>(
+      'account://device-presence',
+      (payload) => {
+        const online = payload?.devices ?? [];
+        const onlineIds = new Set(online.map(device => device.device_id));
+        setPeers(prev => {
+          const byId = new Map(prev.map(device => [device.deviceId, device]));
+          for (const device of online) {
+            if (device.device_id === localDeviceId) {
+              continue;
+            }
+            const existing = byId.get(device.device_id);
+            byId.set(device.device_id, {
+              deviceId: device.device_id,
+              deviceName: device.device_name || existing?.deviceName || device.device_id,
+              online: true,
+              isLocal: false,
+            });
+          }
+          for (const [deviceId, device] of byId) {
+            if (!onlineIds.has(deviceId) && device.online) {
+              byId.set(deviceId, { ...device, online: false });
+            }
+          }
+          return Array.from(byId.values());
+        });
+      },
+    );
+  }, [loggedIn, localDeviceId]);
+
+  const devices = useMemo<DeviceRosterEntry[]>(() => {
+    const sortedPeers = [...peers].sort((a, b) => {
+      if (a.online !== b.online) {
+        return a.online ? -1 : 1;
+      }
+      return a.deviceName.localeCompare(b.deviceName);
+    });
+    if (!localDeviceId) {
+      return sortedPeers;
+    }
+    return [
+      {
+        deviceId: localDeviceId,
+        deviceName: localDeviceName || localDeviceId,
+        online: true,
+        isLocal: true,
+      },
+      ...sortedPeers,
+    ];
+  }, [peers, localDeviceId, localDeviceName]);
+
+  return { loggedIn, localDeviceId, localDeviceName, devices, refresh };
+}
diff --git a/src/web-ui/src/infrastructure/services/business/workspaceManager.test.ts b/src/web-ui/src/infrastructure/services/business/workspaceManager.test.ts
index 4c60c7cdc4..d7f480e5cd 100644
--- a/src/web-ui/src/infrastructure/services/business/workspaceManager.test.ts
+++ b/src/web-ui/src/infrastructure/services/business/workspaceManager.test.ts
@@ -1,4 +1,5 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { isSurfaceChangedError } from '@/infrastructure/peer-device/deviceSurface';
 
 const globalStateMocks = vi.hoisted(() => ({
   initializeWorkspaceStartupState: vi.fn(),
@@ -59,10 +60,20 @@ function configureGlobalState(): void {
 }
 
 async function getFreshWorkspaceManager() {
+  const { manager } = await getFreshWorkspaceHarness();
+  return manager;
+}
+
+async function getFreshWorkspaceHarness() {
   vi.resetModules();
+  const deviceSurface = await import('@/infrastructure/peer-device/deviceSurface');
+  deviceSurface.resetDeviceSurfaceForTest();
   const { WorkspaceManager } = await import('./workspaceManager');
   (WorkspaceManager as unknown as { instance: unknown }).instance = null;
-  return WorkspaceManager.getInstance();
+  return {
+    manager: WorkspaceManager.getInstance(),
+    deviceSurface,
+  };
 }
 
 async function flushAsyncWork(): Promise<void> {
@@ -336,6 +347,224 @@ describe('WorkspaceManager startup initialization', () => {
   });
 });
 
+describe('WorkspaceManager device surface switching', () => {
+  const workspaceA = {
+    id: 'workspace-a',
+    name: 'Device A repo',
+    rootPath: '/repo',
+    workspaceKind: 'normal',
+    identity: null,
+  };
+  const workspaceB = {
+    ...workspaceA,
+    id: 'workspace-b',
+    name: 'Device B repo',
+  };
+
+  function startupSnapshot(workspace: typeof workspaceA) {
+    return {
+      cleanupRemovedCount: 0,
+      recentWorkspaces: [workspace],
+      openedWorkspaces: [workspace],
+      currentWorkspace: workspace,
+      primaryAssistantWorkspaceId: null,
+      legacyRemoteWorkspace: null,
+    };
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    configureGlobalState();
+    listenMock.mockResolvedValue(() => undefined);
+  });
+
+  it('lets a later switch supersede an in-flight rebootstrap instead of running two', async () => {
+    const startupResolvers: Array<(snapshot: ReturnType<typeof startupSnapshot>) => void> = [];
+    globalStateMocks.initializeWorkspaceStartupState.mockImplementation(
+      () => new Promise(resolve => {
+        startupResolvers.push(resolve);
+      }),
+    );
+
+    const manager = await getFreshWorkspaceManager();
+
+    const first = manager.reinitializeForPeerModeSwitch().then(
+      () => null,
+      (error: unknown) => error,
+    );
+    await flushAsyncWork();
+    const second = manager.reinitializeForPeerModeSwitch().then(
+      () => null,
+      (error: unknown) => error,
+    );
+    await flushAsyncWork();
+
+    expect(startupResolvers).toHaveLength(2);
+
+    // The switch that superseded the first one lands first; the abandoned load
+    // then answers late, which is exactly when it used to overwrite state.
+    startupResolvers[1](startupSnapshot(workspaceB));
+    await flushAsyncWork();
+    startupResolvers[0](startupSnapshot(workspaceA));
+
+    expect(isSurfaceChangedError(await first)).toBe(true);
+    expect(await second).toBeNull();
+
+    const state = manager.getState();
+    expect(state.currentWorkspace?.id).toBe('workspace-b');
+    expect(Array.from(state.openedWorkspaces.keys())).toEqual(['workspace-b']);
+    expect(state.error).toBeNull();
+    expect(state.loading).toBe(false);
+  });
+
+  it('makes a concurrent initialize join the in-flight load instead of resolving early', async () => {
+    let resolveStartup: ((snapshot: ReturnType<typeof startupSnapshot>) => void) | null = null;
+    globalStateMocks.initializeWorkspaceStartupState.mockReturnValue(
+      new Promise(resolve => {
+        resolveStartup = resolve;
+      }),
+    );
+
+    const manager = await getFreshWorkspaceManager();
+
+    const first = manager.initialize();
+    let joinedSettled = false;
+    const joined = manager.initialize().then(() => {
+      joinedSettled = true;
+    });
+    await flushAsyncWork();
+
+    expect(globalStateMocks.initializeWorkspaceStartupState).toHaveBeenCalledTimes(1);
+    expect(joinedSettled).toBe(false);
+
+    resolveStartup?.(startupSnapshot(workspaceA));
+    await Promise.all([first, joined]);
+
+    expect(joinedSettled).toBe(true);
+    expect(manager.getState().currentWorkspace?.id).toBe('workspace-a');
+  });
+
+  it('keeps a superseded load from reporting its failure onto the new surface', async () => {
+    const startupOutcomes: Array<{
+      resolve: (snapshot: ReturnType<typeof startupSnapshot>) => void;
+      reject: (error: Error) => void;
+    }> = [];
+    globalStateMocks.initializeWorkspaceStartupState.mockImplementation(
+      () => new Promise((resolve, reject) => {
+        startupOutcomes.push({ resolve, reject });
+      }),
+    );
+
+    const manager = await getFreshWorkspaceManager();
+
+    const first = manager.reinitializeForPeerModeSwitch().then(
+      () => null,
+      (error: unknown) => error,
+    );
+    await flushAsyncWork();
+    const second = manager.reinitializeForPeerModeSwitch().then(
+      () => null,
+      (error: unknown) => error,
+    );
+    await flushAsyncWork();
+
+    startupOutcomes[1].resolve(startupSnapshot(workspaceB));
+    await flushAsyncWork();
+    startupOutcomes[0].reject(new Error('peer request timed out'));
+
+    expect(isSurfaceChangedError(await first)).toBe(true);
+    expect(await second).toBeNull();
+    expect(manager.getState().error).toBeNull();
+    expect(manager.getState().currentWorkspace?.id).toBe('workspace-b');
+  });
+
+  it('selects each device cached workspace state before its refresh completes', async () => {
+    globalStateMocks.initializeWorkspaceStartupState
+      .mockResolvedValueOnce(startupSnapshot(workspaceA))
+      .mockResolvedValueOnce(startupSnapshot(workspaceB));
+    const { manager, deviceSurface } = await getFreshWorkspaceHarness();
+
+    await manager.initialize();
+    expect(manager.getState().currentWorkspace?.id).toBe('workspace-a');
+
+    deviceSurface.activateSurface('peer-b');
+    expect(manager.getState().currentWorkspace).toBeNull();
+    await manager.reinitializeForPeerModeSwitch();
+    expect(manager.getState().currentWorkspace?.id).toBe('workspace-b');
+
+    deviceSurface.activateSurface(deviceSurface.LOCAL_SURFACE_ID);
+    expect(manager.getState().currentWorkspace?.id).toBe('workspace-a');
+    deviceSurface.activateSurface('peer-b');
+    expect(manager.getState().currentWorkspace?.id).toBe('workspace-b');
+  });
+
+  it('keeps a cached surface visible when its refresh fails', async () => {
+    globalStateMocks.initializeWorkspaceStartupState.mockResolvedValue(
+      startupSnapshot(workspaceA),
+    );
+    const manager = await getFreshWorkspaceManager();
+    await manager.initialize();
+
+    globalStateMocks.initializeWorkspaceStartupState.mockRejectedValue(
+      new Error('relay unavailable'),
+    );
+    await expect(manager.reinitializeForPeerModeSwitch()).rejects.toThrow('relay unavailable');
+
+    expect(manager.getState()).toMatchObject({
+      currentWorkspace: workspaceA,
+      loading: false,
+      error: 'relay unavailable',
+    });
+  });
+
+  it('keeps local identity events out of a rendered peer with equal workspace ids', async () => {
+    const localWorkspace = {
+      id: 'shared-workspace-id',
+      name: 'Local repo',
+      rootPath: '/repo',
+      workspaceKind: 'normal',
+      identity: null,
+    };
+    const peerWorkspace = {
+      ...localWorkspace,
+      name: 'Peer repo',
+    };
+    globalStateMocks.initializeWorkspaceStartupState
+      .mockResolvedValueOnce(startupSnapshot(localWorkspace))
+      .mockResolvedValueOnce(startupSnapshot(peerWorkspace));
+    let identityHandler: ((event: { payload: {
+      workspaceId: string;
+      workspacePath: string;
+      name: string;
+      identity: { name: string };
+      changedFields: string[];
+    } }) => void) | null = null;
+    listenMock.mockImplementation((_eventName, handler) => {
+      identityHandler = handler;
+      return Promise.resolve(() => undefined);
+    });
+    const { manager, deviceSurface } = await getFreshWorkspaceHarness();
+
+    await manager.initialize();
+    deviceSurface.activateSurface('peer-b');
+    await manager.reinitializeForPeerModeSwitch();
+
+    identityHandler?.({
+      payload: {
+        workspaceId: 'shared-workspace-id',
+        workspacePath: '/repo',
+        name: 'Local repo renamed',
+        identity: { name: 'Local repo renamed' },
+        changedFields: ['name'],
+      },
+    });
+
+    expect(manager.getState().currentWorkspace?.name).toBe('Peer repo');
+    deviceSurface.activateSurface(deviceSurface.LOCAL_SURFACE_ID);
+    expect(manager.getState().currentWorkspace?.name).toBe('Local repo renamed');
+  });
+});
+
 describe('WorkspaceManager project rename', () => {
   beforeEach(() => {
     vi.clearAllMocks();
diff --git a/src/web-ui/src/infrastructure/services/business/workspaceManager.ts b/src/web-ui/src/infrastructure/services/business/workspaceManager.ts
index 1930fd35e1..fe4fac7d76 100644
--- a/src/web-ui/src/infrastructure/services/business/workspaceManager.ts
+++ b/src/web-ui/src/infrastructure/services/business/workspaceManager.ts
@@ -14,6 +14,16 @@ import { createLogger } from '@/shared/utils/logger';
 import { startupTrace } from '@/shared/utils/startupTrace';
 import { elapsedMs, nowMs } from '@/shared/utils/timing';
 import { listen } from '@tauri-apps/api/event';
+import {
+  LOCAL_SURFACE_ID,
+  SurfaceChangedError,
+  getActiveSurfaceId,
+  getActiveSurfaceScope,
+  isSurfaceChangedError,
+  onSurfaceActivated,
+  type DeviceSurfaceId,
+  type SurfaceScope,
+} from '@/infrastructure/peer-device/deviceSurface';
 import { i18nService } from '@/infrastructure/i18n';
 
 const log = createLogger('WorkspaceManager');
@@ -72,22 +82,35 @@ export interface WorkspaceState {
 export type WorkspaceSection = 'assistants' | 'projects';
 export type WorkspaceReorderPosition = 'before' | 'after';
 
-class WorkspaceManager {
-  private static instance: WorkspaceManager | null = null;
-  private state: WorkspaceState;
-  private listeners: Set<WorkspaceEventListener> = new Set();
-  private isInitialized = false;
-  private isInitializing = false;
-  private identityEventListening = false;
-  private identityListenerReady = false;
-  private identityListenerRegistrationPromise: Promise<void> | null = null;
-  private identityListenerReadyResyncPending = false;
-  private startupLegacyRemoteWorkspaceSnapshotAvailable = false;
-  private startupLegacyRemoteWorkspaceSnapshotConsumed = false;
-  private startupLegacyRemoteWorkspace: RemoteWorkspaceSnapshot | null = null;
+/**
+ * An operation pinned to the device surface it started under.
+ *
+ * Two things invalidate it, and both are needed: `activateSurface` moves the
+ * epoch when the rendered device changes, while `clearForPeerModeSwitch()`
+ * bumps the switch generation even when the same device is re-rendered.
+ */
+interface SurfaceCapture {
+  readonly scope: SurfaceScope;
+  readonly generation: number;
+}
 
-  private constructor() {
-    this.state = {
+/** The single initialization allowed to write state for one surface capture. */
+interface WorkspaceInitializationRun {
+  readonly surface: SurfaceCapture;
+  readonly promise: Promise<void>;
+}
+
+interface WorkspaceSurfaceContainer {
+  state: WorkspaceState;
+  isInitialized: boolean;
+  startupLegacyRemoteWorkspaceSnapshotAvailable: boolean;
+  startupLegacyRemoteWorkspaceSnapshotConsumed: boolean;
+  startupLegacyRemoteWorkspace: RemoteWorkspaceSnapshot | null;
+}
+
+function createWorkspaceSurfaceContainer(): WorkspaceSurfaceContainer {
+  return {
+    state: {
       currentWorkspace: null,
       openedWorkspaces: new Map(),
       activeWorkspaceId: null,
@@ -96,7 +119,97 @@ class WorkspaceManager {
       primaryAssistantWorkspaceId: null,
       loading: true,
       error: null,
-    };
+    },
+    isInitialized: false,
+    startupLegacyRemoteWorkspaceSnapshotAvailable: false,
+    startupLegacyRemoteWorkspaceSnapshotConsumed: false,
+    startupLegacyRemoteWorkspace: null,
+  };
+}
+
+class WorkspaceManager {
+  private static instance: WorkspaceManager | null = null;
+  private readonly surfaceContainers = new Map<DeviceSurfaceId, WorkspaceSurfaceContainer>();
+  private listeners: Set<WorkspaceEventListener> = new Set();
+  private switchGeneration = 0;
+  private activeInitialization: WorkspaceInitializationRun | null = null;
+  private identityEventListening = false;
+  private identityListenerReady = false;
+  private identityListenerRegistrationPromise: Promise<void> | null = null;
+  /** The identity watcher is local-Tauri-only, so its missed-event resync is too. */
+  private localIdentityListenerReadyResyncPending = false;
+
+  private constructor() {
+    // The activation commit swaps transport before listeners run, so consumers
+    // can safely render this surface's cached workspace snapshot immediately.
+    onSurfaceActivated(scope => {
+      this.emit({
+        type: 'workspace:active-changed',
+        workspace: this.state.currentWorkspace,
+      });
+      if (
+        scope.surfaceId === LOCAL_SURFACE_ID
+        && this.localIdentityListenerReadyResyncPending
+        && this.identityListenerReady
+        && this.isInitialized
+      ) {
+        void this.syncWorkspaceStateAfterIdentityListenerReady();
+      }
+    });
+  }
+
+  private surfaceContainer(surfaceId: DeviceSurfaceId): WorkspaceSurfaceContainer {
+    const existing = this.surfaceContainers.get(surfaceId);
+    if (existing) {
+      return existing;
+    }
+    const created = createWorkspaceSurfaceContainer();
+    this.surfaceContainers.set(surfaceId, created);
+    return created;
+  }
+
+  private get activeSurface(): WorkspaceSurfaceContainer {
+    return this.surfaceContainer(getActiveSurfaceId());
+  }
+
+  private get state(): WorkspaceState {
+    return this.activeSurface.state;
+  }
+
+  private set state(state: WorkspaceState) {
+    this.activeSurface.state = state;
+  }
+
+  private get isInitialized(): boolean {
+    return this.activeSurface.isInitialized;
+  }
+
+  private set isInitialized(value: boolean) {
+    this.activeSurface.isInitialized = value;
+  }
+
+  private get startupLegacyRemoteWorkspaceSnapshotAvailable(): boolean {
+    return this.activeSurface.startupLegacyRemoteWorkspaceSnapshotAvailable;
+  }
+
+  private set startupLegacyRemoteWorkspaceSnapshotAvailable(value: boolean) {
+    this.activeSurface.startupLegacyRemoteWorkspaceSnapshotAvailable = value;
+  }
+
+  private get startupLegacyRemoteWorkspaceSnapshotConsumed(): boolean {
+    return this.activeSurface.startupLegacyRemoteWorkspaceSnapshotConsumed;
+  }
+
+  private set startupLegacyRemoteWorkspaceSnapshotConsumed(value: boolean) {
+    this.activeSurface.startupLegacyRemoteWorkspaceSnapshotConsumed = value;
+  }
+
+  private get startupLegacyRemoteWorkspace(): RemoteWorkspaceSnapshot | null {
+    return this.activeSurface.startupLegacyRemoteWorkspace;
+  }
+
+  private set startupLegacyRemoteWorkspace(value: RemoteWorkspaceSnapshot | null) {
+    this.activeSurface.startupLegacyRemoteWorkspace = value;
   }
 
   public static getInstance(): WorkspaceManager {
@@ -357,7 +470,7 @@ class WorkspaceManager {
     const handleRegistrationFailure = (error: unknown): void => {
       this.identityEventListening = false;
       this.identityListenerReady = false;
-      this.identityListenerReadyResyncPending = false;
+      this.localIdentityListenerReadyResyncPending = false;
       startupTrace.markPhase('workspace_identity_listener_failed', {
         durationMs: elapsedMs(registrationStartedAt),
       });
@@ -368,7 +481,10 @@ class WorkspaceManager {
       this.identityListenerRegistrationPromise = listen<WorkspaceIdentityChangedEvent>(
         'workspace-identity-changed',
         event => {
-          this.applyIdentityUpdate(event.payload);
+          // This listener is registered directly with the controller's Tauri
+          // runtime and is not a peer-fanned event. Always update the local
+          // container, even while the window renders a peer with equal ids.
+          this.applyLocalIdentityUpdate(event.payload);
         }
       )
         .then(() => {
@@ -376,7 +492,11 @@ class WorkspaceManager {
           startupTrace.markPhase('workspace_identity_listener_ready', {
             durationMs: elapsedMs(registrationStartedAt),
           });
-          if (this.identityListenerReadyResyncPending && this.isInitialized) {
+          if (
+            this.localIdentityListenerReadyResyncPending
+            && getActiveSurfaceId() === LOCAL_SURFACE_ID
+            && this.isInitialized
+          ) {
             void this.syncWorkspaceStateAfterIdentityListenerReady();
           }
         })
@@ -394,11 +514,17 @@ class WorkspaceManager {
   }
 
   private async syncWorkspaceStateAfterIdentityListenerReady(): Promise<void> {
-    if (!this.identityListenerReadyResyncPending || !this.isInitialized || !this.identityListenerReady) {
+    if (
+      getActiveSurfaceId() !== LOCAL_SURFACE_ID
+      || !this.localIdentityListenerReadyResyncPending
+      || !this.isInitialized
+      || !this.identityListenerReady
+    ) {
       return;
     }
-    this.identityListenerReadyResyncPending = false;
+    this.localIdentityListenerReadyResyncPending = false;
 
+    const surface = this.captureSurface();
     const syncStartedAt = nowMs();
     try {
       const [currentWorkspace, recentWorkspaces, openedWorkspaces] = await Promise.all([
@@ -406,6 +532,9 @@ class WorkspaceManager {
         globalStateAPI.getRecentWorkspaces(),
         globalStateAPI.getOpenedWorkspaces(),
       ]);
+      if (!this.isSurfaceUnchanged(surface)) {
+        return;
+      }
       this.updateWorkspaceState(
         currentWorkspace,
         recentWorkspaces,
@@ -420,6 +549,10 @@ class WorkspaceManager {
         durationMs: elapsedMs(syncStartedAt),
       });
     } catch (error) {
+      if (isSurfaceChangedError(error) || !this.isSurfaceUnchanged(surface)) {
+        log.debug('Abandoned local identity resync after a device surface switch');
+        return;
+      }
       startupTrace.markPhase('workspace_identity_listener_post_ready_sync_failed', {
         durationMs: elapsedMs(syncStartedAt),
       });
@@ -427,7 +560,9 @@ class WorkspaceManager {
     }
   }
 
-  private applyIdentityUpdate(update: WorkspaceIdentityChangedEvent): void {
+  private applyLocalIdentityUpdate(update: WorkspaceIdentityChangedEvent): void {
+    const container = this.surfaceContainer(LOCAL_SURFACE_ID);
+    const state = container.state;
     const updateWorkspace = (workspace: WorkspaceInfo | null): WorkspaceInfo | null => {
       if (!workspace) {
         return null;
@@ -448,14 +583,14 @@ class WorkspaceManager {
       };
     };
 
-    const currentWorkspace = updateWorkspace(this.state.currentWorkspace);
+    const currentWorkspace = updateWorkspace(state.currentWorkspace);
     const openedWorkspaces = new Map(
-      Array.from(this.state.openedWorkspaces.entries()).map(([id, workspace]) => [
+      Array.from(state.openedWorkspaces.entries()).map(([id, workspace]) => [
         id,
         updateWorkspace(workspace) ?? workspace,
       ])
     );
-    const recentWorkspaces = this.state.recentWorkspaces.map(
+    const recentWorkspaces = state.recentWorkspaces.map(
       workspace => updateWorkspace(workspace) ?? workspace
     );
 
@@ -467,32 +602,80 @@ class WorkspaceManager {
           null;
 
     if (!updatedWorkspace) {
-      if (!this.isInitialized) {
-        this.identityListenerReadyResyncPending = true;
+      if (!container.isInitialized) {
+        this.localIdentityListenerReadyResyncPending = true;
       }
       return;
     }
 
-    this.updateState(
-      {
-        currentWorkspace,
-        openedWorkspaces,
-        recentWorkspaces,
-      },
-      { type: 'workspace:updated', workspace: updatedWorkspace }
-    );
+    container.state = {
+      ...state,
+      currentWorkspace,
+      openedWorkspaces,
+      recentWorkspaces,
+    };
+    if (getActiveSurfaceId() === LOCAL_SURFACE_ID) {
+      this.emit({ type: 'workspace:updated', workspace: updatedWorkspace });
+    }
   }
 
+  private captureSurface(): SurfaceCapture {
+    return { scope: getActiveSurfaceScope(), generation: this.switchGeneration };
+  }
+
+  private isSurfaceUnchanged(surface: SurfaceCapture): boolean {
+    return surface.generation === this.switchGeneration && surface.scope.isCurrent();
+  }
+
+  /**
+   * Guard every state write that follows an await. A switch inside that window
+   * means the result describes a device this window no longer renders, so it
+   * must be abandoned rather than written over the surface that replaced it.
+   */
+  private assertSurfaceUnchanged(surface: SurfaceCapture, action: string): void {
+    if (!this.isSurfaceUnchanged(surface)) {
+      throw new SurfaceChangedError(surface.scope.surfaceId, surface.scope.epoch, action);
+    }
+  }
+
+  /**
+   * Load workspace state for the surface this window renders.
+   *
+   * Callers that arrive while a load for the same surface is in flight join it,
+   * so one surface never has two initializations writing the same state. A load
+   * whose surface was superseded rejects with `SurfaceChangedError`.
+   */
   public async initialize(): Promise<void> {
-    if (this.isInitialized || this.isInitializing) {
+    if (this.isInitialized) {
       return;
     }
 
+    const inFlight = this.activeInitialization;
+    if (inFlight && this.isSurfaceUnchanged(inFlight.surface)) {
+      return inFlight.promise;
+    }
+
+    const surface = this.captureSurface();
+    const run: WorkspaceInitializationRun = {
+      surface,
+      promise: this.runInitialization(surface),
+    };
+    this.activeInitialization = run;
+
+    try {
+      await run.promise;
+    } finally {
+      if (this.activeInitialization === run) {
+        this.activeInitialization = null;
+      }
+    }
+  }
+
+  private async runInitialization(surface: SurfaceCapture): Promise<void> {
     const initializeStartedAt = nowMs();
     startupTrace.markPhase('workspace_initialize_start');
 
     try {
-      this.isInitializing = true;
       log.info('Initializing workspace state');
 
       const identityListenerStartedAt = markWorkspaceStartupStepStart('ensure_identity_listener');
@@ -510,8 +693,9 @@ class WorkspaceManager {
         primaryAssistantWorkspaceId,
         legacyRemoteWorkspace,
       } = await globalStateAPI.initializeWorkspaceStartupState();
-      if (!this.identityListenerReady) {
-        this.identityListenerReadyResyncPending = true;
+      this.assertSurfaceUnchanged(surface, 'initialize workspace state');
+      if (surface.scope.surfaceId === LOCAL_SURFACE_ID && !this.identityListenerReady) {
+        this.localIdentityListenerReadyResyncPending = true;
       }
       this.startupLegacyRemoteWorkspace = legacyRemoteWorkspace;
       this.startupLegacyRemoteWorkspaceSnapshotAvailable = true;
@@ -553,7 +737,10 @@ class WorkspaceManager {
 
       this.emit({ type: 'workspace:loading', loading: false });
       this.isInitialized = true;
-      if (this.identityListenerReadyResyncPending) {
+      if (
+        surface.scope.surfaceId === LOCAL_SURFACE_ID
+        && this.localIdentityListenerReadyResyncPending
+      ) {
         void this.syncWorkspaceStateAfterIdentityListenerReady();
       }
       startupTrace.markPhase('workspace_initialize_end', {
@@ -567,40 +754,70 @@ class WorkspaceManager {
         openedWorkspaceCount: openedWorkspaces.length,
       });
     } catch (error) {
+      if (!this.isSurfaceUnchanged(surface)) {
+        // Reporting this failure would blank the surface that superseded it,
+        // and the load it failed at belongs to a device nobody renders now.
+        log.debug('Abandoned workspace initialization for a superseded surface', {
+          surfaceId: surface.scope.surfaceId,
+          epoch: surface.scope.epoch,
+        });
+        throw isSurfaceChangedError(error)
+          ? error
+          : new SurfaceChangedError(
+              surface.scope.surfaceId,
+              surface.scope.epoch,
+              'initialize workspace state',
+            );
+      }
       startupTrace.markPhase('workspace_initialize_failed', {
         durationMs: elapsedMs(initializeStartedAt),
       });
       log.error('Failed to initialize workspace state', { error });
       const errorMessage = error instanceof Error ? error.message : String(error);
-      this.updateWorkspaceState(null, [], [], false, errorMessage);
-      this.updateState({ primaryAssistantWorkspaceId: null });
+      // Keep this surface's last known workspace projection. A weak-link
+      // refresh failure is visible through `error`, but it must not turn a
+      // usable cached device into an empty workspace list.
+      this.updateState({ loading: false, error: errorMessage });
       this.emit({ type: 'workspace:error', error: errorMessage });
-    } finally {
-      this.isInitializing = false;
     }
   }
 
   /**
-   * Drop controller-local workspace pointers before peer transport is live so
-   * create_session / SessionModule cannot prefer a stale controller path while
-   * rebootstrap is still in flight.
+   * Announce that the rendered surface is about to change.
+   *
+   * Frontend-only, and must stay that way: it runs before the transport swap,
+   * so any backend call here would land on the device being left. Bumping the
+   * switch generation is what supersedes an initialization still in flight —
+   * that load abandons at its next checkpoint instead of racing this one. The
+   * current container is deliberately preserved; atomic activation selects the
+   * target container before the peer-mode event can trigger session creation.
    */
   public clearForPeerModeSwitch(): void {
-    this.isInitialized = false;
-    this.isInitializing = false;
-    this.updateWorkspaceState(null, [], [], false, null);
-    this.updateState({ primaryAssistantWorkspaceId: null });
+    this.switchGeneration += 1;
+    this.activeInitialization = null;
   }
 
   /**
    * Tear down local workspace product state and reload opened/recent
    * workspaces from the current transport target (local or peer).
+   *
+   * Rejects with `SurfaceChangedError` when a later switch supersedes this one:
+   * the caller must abandon quietly rather than report a product error or roll
+   * the surface back, because what is on screen now belongs to that later
+   * switch.
    */
   public async reinitializeForPeerModeSwitch(): Promise<void> {
     log.info('Reinitializing workspace state for peer mode switch');
-    this.clearForPeerModeSwitch();
+    // Reconcile the selected surface even when it has a cached snapshot. A
+    // second call on the same surface also supersedes the first one.
+    this.switchGeneration += 1;
+    this.activeInitialization = null;
+    this.isInitialized = false;
+    const surface = this.captureSurface();
+    this.updateState({ loading: true, error: null });
     this.emit({ type: 'workspace:loading', loading: true });
     await this.initialize();
+    this.assertSurfaceUnchanged(surface, 'reinitialize workspace for surface switch');
     if (!this.isInitialized) {
       throw new Error(
         this.state.error || 'Workspace state could not be loaded from the Peer host',
@@ -608,7 +825,13 @@ class WorkspaceManager {
     }
   }
 
+  /** Permanently release one detached peer's cached workspace projection. */
+  public discardDeviceSurface(surfaceId: DeviceSurfaceId): void {
+    this.surfaceContainers.delete(surfaceId);
+  }
+
   public async openWorkspace(path: string): Promise<WorkspaceInfo> {
+    const surface = this.captureSurface();
     try {
       this.setLoading(true);
       this.setError(null);
@@ -620,6 +843,7 @@ class WorkspaceManager {
         globalStateAPI.getRecentWorkspaces(),
         globalStateAPI.getOpenedWorkspaces(),
       ]);
+      this.assertSurfaceUnchanged(surface, 'open workspace');
 
       this.updateWorkspaceState(
         workspace,
@@ -632,6 +856,9 @@ class WorkspaceManager {
 
       return workspace;
     } catch (error) {
+      if (!this.isSurfaceUnchanged(surface)) {
+        throw error;
+      }
       log.error('Failed to open workspace', { path, error });
       const rawMessage = error instanceof Error ? error.message : String(error);
       // Map the common "folder moved/deleted" backend error to a localized
@@ -650,6 +877,7 @@ class WorkspaceManager {
     remotePath: string;
     sshHost?: string;
   }): Promise<WorkspaceInfo> {
+    const surface = this.captureSurface();
     try {
       this.setLoading(true);
       this.setError(null);
@@ -669,6 +897,7 @@ class WorkspaceManager {
         globalStateAPI.getRecentWorkspaces(),
         globalStateAPI.getOpenedWorkspaces(),
       ]);
+      this.assertSurfaceUnchanged(surface, 'open remote workspace');
 
       this.updateWorkspaceState(
         workspace,
@@ -681,6 +910,9 @@ class WorkspaceManager {
 
       return workspace;
     } catch (error) {
+      if (!this.isSurfaceUnchanged(surface)) {
+        throw error;
+      }
       log.error('Failed to open remote workspace', { remoteWorkspace, error });
       const errorMessage = error instanceof Error ? error.message : String(error);
       this.updateState({ loading: false, error: errorMessage }, { type: 'workspace:error', error: errorMessage });
@@ -689,6 +921,7 @@ class WorkspaceManager {
   }
 
   public async removeRemoteWorkspace(connectionId: string, remotePath?: string): Promise<void> {
+    const surface = this.captureSurface();
     try {
       const workspace = this.findRemoteWorkspace(connectionId, remotePath);
       if (!workspace) {
@@ -698,6 +931,9 @@ class WorkspaceManager {
       await this.cancelRunningSessionsForWorkspace(workspace);
       await globalStateAPI.closeWorkspace(workspace.id);
       await globalStateAPI.removeWorkspaceFromRecent(workspace.id).catch(error => {
+        if (isSurfaceChangedError(error)) {
+          throw error;
+        }
         log.warn('Failed to remove remote workspace from recent list', {
           workspaceId: workspace.id,
           error,
@@ -709,6 +945,7 @@ class WorkspaceManager {
         globalStateAPI.getRecentWorkspaces(),
         globalStateAPI.getOpenedWorkspaces(),
       ]);
+      this.assertSurfaceUnchanged(surface, 'remove remote workspace');
 
       this.updateWorkspaceState(
         currentWorkspace,
@@ -721,6 +958,9 @@ class WorkspaceManager {
 
       this.emit({ type: 'workspace:active-changed', workspace: currentWorkspace });
     } catch (error) {
+      if (!this.isSurfaceUnchanged(surface)) {
+        throw error;
+      }
       log.error('Failed to remove remote workspace', { connectionId, remotePath, error });
       const errorMessage = error instanceof Error ? error.message : String(error);
       this.updateState({ error: errorMessage }, { type: 'workspace:error', error: errorMessage });
@@ -746,11 +986,13 @@ class WorkspaceManager {
   }
 
   public async createAssistantWorkspace(): Promise<WorkspaceInfo> {
+    const surface = this.captureSurface();
     try {
       this.setLoading(true);
       this.setError(null);
 
       const workspace = await globalStateAPI.createAssistantWorkspace();
+      this.assertSurfaceUnchanged(surface, 'create assistant workspace');
       if (!this.state.primaryAssistantWorkspaceId) {
         this.updateState({ primaryAssistantWorkspaceId: workspace.id });
       }
@@ -759,6 +1001,7 @@ class WorkspaceManager {
         globalStateAPI.getRecentWorkspaces(),
         globalStateAPI.getOpenedWorkspaces(),
       ]);
+      this.assertSurfaceUnchanged(surface, 'create assistant workspace');
 
       this.updateWorkspaceState(
         currentWorkspace,
@@ -771,6 +1014,9 @@ class WorkspaceManager {
 
       return workspace;
     } catch (error) {
+      if (!this.isSurfaceUnchanged(surface)) {
+        throw error;
+      }
       log.error('Failed to create assistant workspace', { error });
       const errorMessage = error instanceof Error ? error.message : String(error);
       this.updateState({ loading: false, error: errorMessage }, { type: 'workspace:error', error: errorMessage });
@@ -787,6 +1033,7 @@ class WorkspaceManager {
   }
 
   public async closeWorkspaceById(workspaceId: string): Promise<void> {
+    const surface = this.captureSurface();
     try {
       this.setLoading(true);
       this.setError(null);
@@ -805,6 +1052,7 @@ class WorkspaceManager {
         globalStateAPI.getRecentWorkspaces(),
         globalStateAPI.getOpenedWorkspaces(),
       ]);
+      this.assertSurfaceUnchanged(surface, 'close workspace');
 
       this.updateWorkspaceState(
         currentWorkspace,
@@ -817,6 +1065,9 @@ class WorkspaceManager {
 
       this.emit({ type: 'workspace:active-changed', workspace: currentWorkspace });
     } catch (error) {
+      if (!this.isSurfaceUnchanged(surface)) {
+        throw error;
+      }
       log.error('Failed to close workspace', { workspaceId, error });
       const errorMessage = error instanceof Error ? error.message : String(error);
       this.updateState({ loading: false, error: errorMessage }, { type: 'workspace:error', error: errorMessage });
@@ -843,6 +1094,7 @@ class WorkspaceManager {
   }
 
   public async deleteAssistantWorkspace(workspaceId: string): Promise<void> {
+    const surface = this.captureSurface();
     try {
       this.setLoading(true);
       this.setError(null);
@@ -862,6 +1114,7 @@ class WorkspaceManager {
         globalStateAPI.getRecentWorkspaces(),
         globalStateAPI.getOpenedWorkspaces(),
       ]);
+      this.assertSurfaceUnchanged(surface, 'delete assistant workspace');
 
       this.updateWorkspaceState(
         currentWorkspace,
@@ -874,6 +1127,9 @@ class WorkspaceManager {
 
       this.emit({ type: 'workspace:active-changed', workspace: currentWorkspace });
     } catch (error) {
+      if (!this.isSurfaceUnchanged(surface)) {
+        throw error;
+      }
       log.error('Failed to delete assistant workspace', { workspaceId, error });
       const errorMessage = error instanceof Error ? error.message : String(error);
       this.updateState({ loading: false, error: errorMessage }, { type: 'workspace:error', error: errorMessage });
@@ -925,12 +1181,14 @@ class WorkspaceManager {
   }
 
   public async setPrimaryAssistantWorkspace(workspaceId: string): Promise<WorkspaceInfo> {
+    const surface = this.captureSurface();
     try {
       this.setLoading(true);
       this.setError(null);
 
       log.info('Setting primary assistant workspace', { workspaceId });
       const workspace = await globalStateAPI.setPrimaryAssistantWorkspace(workspaceId);
+      this.assertSurfaceUnchanged(surface, 'set primary assistant workspace');
       this.updateState(
         {
           primaryAssistantWorkspaceId: workspace.id,
@@ -941,6 +1199,9 @@ class WorkspaceManager {
       );
       return workspace;
     } catch (error) {
+      if (!this.isSurfaceUnchanged(surface)) {
+        throw error;
+      }
       log.error('Failed to set primary assistant workspace', { workspaceId, error });
       const errorMessage = error instanceof Error ? error.message : String(error);
       this.updateState(
@@ -952,6 +1213,7 @@ class WorkspaceManager {
   }
 
   public async resetAssistantWorkspace(workspaceId: string): Promise<WorkspaceInfo> {
+    const surface = this.captureSurface();
     try {
       this.setLoading(true);
       this.setError(null);
@@ -965,6 +1227,7 @@ class WorkspaceManager {
         globalStateAPI.getRecentWorkspaces(),
         globalStateAPI.getOpenedWorkspaces(),
       ]);
+      this.assertSurfaceUnchanged(surface, 'reset assistant workspace');
 
       this.updateWorkspaceState(
         currentWorkspace,
@@ -978,6 +1241,9 @@ class WorkspaceManager {
       this.emit({ type: 'workspace:active-changed', workspace: currentWorkspace });
       return workspace;
     } catch (error) {
+      if (!this.isSurfaceUnchanged(surface)) {
+        throw error;
+      }
       log.error('Failed to reset assistant workspace', { workspaceId, error });
       const errorMessage = error instanceof Error ? error.message : String(error);
       this.updateState({ loading: false, error: errorMessage }, { type: 'workspace:error', error: errorMessage });
@@ -986,6 +1252,7 @@ class WorkspaceManager {
   }
 
   public async setActiveWorkspace(workspaceId: string): Promise<WorkspaceInfo> {
+    const surface = this.captureSurface();
     try {
       if (this.state.activeWorkspaceId === workspaceId) {
         const currentWorkspace = this.state.currentWorkspace;
@@ -1003,6 +1270,7 @@ class WorkspaceManager {
         globalStateAPI.getRecentWorkspaces(),
         globalStateAPI.getOpenedWorkspaces(),
       ]);
+      this.assertSurfaceUnchanged(surface, 'set active workspace');
       const orderedOpenedWorkspaces = this.preserveOpenedWorkspaceOrder(openedWorkspaces);
 
       this.updateWorkspaceState(
@@ -1017,6 +1285,9 @@ class WorkspaceManager {
       this.emit({ type: 'workspace:active-changed', workspace });
       return workspace;
     } catch (error) {
+      if (!this.isSurfaceUnchanged(surface)) {
+        throw error;
+      }
       log.error('Failed to set active workspace', { workspaceId, error });
       const errorMessage = error instanceof Error ? error.message : String(error);
       this.updateState({ loading: false, error: errorMessage }, { type: 'workspace:error', error: errorMessage });
@@ -1030,6 +1301,7 @@ class WorkspaceManager {
     targetWorkspaceId: string,
     position: WorkspaceReorderPosition
   ): Promise<void> {
+    const surface = this.captureSurface();
     const previousCurrentWorkspace = this.state.currentWorkspace;
     const previousRecentWorkspaces = this.state.recentWorkspaces;
     const previousOpenedWorkspaces = this.getOpenedWorkspacesList();
@@ -1078,6 +1350,9 @@ class WorkspaceManager {
     try {
       await globalStateAPI.reorderOpenedWorkspaces(reorderedOpenedWorkspaceIds);
     } catch (error) {
+      if (!this.isSurfaceUnchanged(surface)) {
+        throw error;
+      }
       const errorMessage = error instanceof Error ? error.message : String(error);
       const rollbackEventWorkspace = previousCurrentWorkspace
         ?? workspaceMap.get(sourceWorkspaceId)
@@ -1123,6 +1398,7 @@ class WorkspaceManager {
   }
 
   public async scanWorkspaceInfo(): Promise<WorkspaceInfo | null> {
+    const surface = this.captureSurface();
     try {
       if (!this.state.currentWorkspace?.rootPath) {
         throw new Error('No current workspace available for scanning');
@@ -1132,6 +1408,7 @@ class WorkspaceManager {
       this.setError(null);
 
       const updatedWorkspace = await globalStateAPI.scanWorkspaceInfo(this.state.currentWorkspace.rootPath);
+      this.assertSurfaceUnchanged(surface, 'scan workspace info');
 
       if (updatedWorkspace) {
         const openedWorkspaces = new Map(this.state.openedWorkspaces);
@@ -1158,6 +1435,9 @@ class WorkspaceManager {
 
       return updatedWorkspace;
     } catch (error) {
+      if (!this.isSurfaceUnchanged(surface)) {
+        throw error;
+      }
       log.error('Failed to scan workspace info', { error });
       const errorMessage = error instanceof Error ? error.message : String(error);
       this.setError(errorMessage);
@@ -1167,8 +1447,12 @@ class WorkspaceManager {
   }
 
   public async refreshRecentWorkspaces(): Promise<void> {
+    const surface = this.captureSurface();
     try {
       const recentWorkspaces = await globalStateAPI.getRecentWorkspaces();
+      if (!this.isSurfaceUnchanged(surface)) {
+        return;
+      }
       this.updateState({ recentWorkspaces }, { type: 'workspace:recent-updated' });
       log.debug('Recent workspaces refreshed', { count: recentWorkspaces.length });
     } catch (error) {
@@ -1185,16 +1469,21 @@ class WorkspaceManager {
     workspaceId: string,
     relatedPaths: WorkspaceInfo['relatedPaths']
   ): Promise<WorkspaceInfo> {
+    const surface = this.captureSurface();
     try {
       this.setError(null);
 
       const updatedWorkspace = await globalStateAPI.updateWorkspaceInfo(workspaceId, {
         relatedPaths,
       });
+      this.assertSurfaceUnchanged(surface, 'update workspace related paths');
 
       this.applyWorkspaceRecordUpdate(updatedWorkspace);
       return updatedWorkspace;
     } catch (error) {
+      if (!this.isSurfaceUnchanged(surface)) {
+        throw error;
+      }
       log.error('Failed to update workspace related paths', { workspaceId, error });
       const errorMessage = error instanceof Error ? error.message : String(error);
       this.updateState({ error: errorMessage }, { type: 'workspace:error', error: errorMessage });
@@ -1203,16 +1492,21 @@ class WorkspaceManager {
   }
 
   public async renameWorkspace(workspaceId: string, name: string): Promise<WorkspaceInfo> {
+    const surface = this.captureSurface();
     try {
       this.setError(null);
 
       const updatedWorkspace = await globalStateAPI.updateWorkspaceInfo(workspaceId, {
         name: name.trim(),
       });
+      this.assertSurfaceUnchanged(surface, 'rename workspace');
 
       this.applyWorkspaceRecordUpdate(updatedWorkspace);
       return updatedWorkspace;
     } catch (error) {
+      if (!this.isSurfaceUnchanged(surface)) {
+        throw error;
+      }
       log.error('Failed to rename workspace', { workspaceId, error });
       const errorMessage = error instanceof Error ? error.message : String(error);
       this.updateState({ error: errorMessage }, { type: 'workspace:error', error: errorMessage });
@@ -1221,6 +1515,7 @@ class WorkspaceManager {
   }
 
   public async cleanupInvalidWorkspaces(): Promise<number> {
+    const surface = this.captureSurface();
     try {
       const removedCount = await globalStateAPI.cleanupInvalidWorkspaces();
 
@@ -1234,6 +1529,7 @@ class WorkspaceManager {
         globalStateAPI.getOpenedWorkspaces(),
         globalStateAPI.getPrimaryAssistantWorkspace(),
       ]);
+      this.assertSurfaceUnchanged(surface, 'cleanup invalid workspaces');
 
       this.updateState({ primaryAssistantWorkspaceId: primaryAssistantWorkspace?.id ?? null });
       this.updateWorkspaceState(
@@ -1248,7 +1544,9 @@ class WorkspaceManager {
       log.info('Invalid workspaces cleaned up', { removedCount });
       return removedCount;
     } catch (error) {
-      log.error('Failed to cleanup invalid workspaces', { error });
+      if (this.isSurfaceUnchanged(surface)) {
+        log.error('Failed to cleanup invalid workspaces', { error });
+      }
       throw error;
     }
   }
diff --git a/src/web-ui/src/infrastructure/update/UpdateAvailableDialog.tsx b/src/web-ui/src/infrastructure/update/UpdateAvailableDialog.tsx
index 2c87076774..7323c4cc1c 100644
--- a/src/web-ui/src/infrastructure/update/UpdateAvailableDialog.tsx
+++ b/src/web-ui/src/infrastructure/update/UpdateAvailableDialog.tsx
@@ -2,7 +2,7 @@
  * Dialog when a remote update is available (daily prompt or manual check).
  */
 
-import React from 'react';
+import React, { useRef } from 'react';
 import { Modal, Button } from '@/component-library';
 import { Download } from 'lucide-react';
 import { useI18n } from '@/infrastructure/i18n';
@@ -27,16 +27,23 @@ export const UpdateAvailableDialog: React.FC<UpdateAvailableDialogProps> = ({
   onInstall
 }) => {
   const { t } = useI18n('common');
-  if (!isOpen || !data?.updateAvailable) {
+  const lastAvailableDataRef = useRef<CheckForUpdatesResponse | null>(null);
+  if (data?.updateAvailable) {
+    lastAvailableDataRef.current = data;
+  }
+  const displayData = data?.updateAvailable ? data : lastAvailableDataRef.current;
+  const modalOpen = isOpen && data?.updateAvailable === true;
+
+  if (!displayData) {
     return null;
   }
 
-  const latest = data.latestVersion ?? '';
-  const notes = data.releaseNotes?.trim();
+  const latest = displayData.latestVersion ?? '';
+  const notes = displayData.releaseNotes?.trim();
 
   return (
     <Modal
-      isOpen={isOpen}
+      isOpen={modalOpen}
       onClose={onLater}
       title={t('update.availableTitle')}
       showCloseButton={true}
@@ -80,7 +87,7 @@ export const UpdateAvailableDialog: React.FC<UpdateAvailableDialogProps> = ({
             data-bf-part="versionRow"
           >
             <span className="bitfun-update-available__label" data-bf-component="update" data-bf-part="versionLabel">{t('update.currentVersion')}</span>
-            <span className="bitfun-update-available__value" data-bf-component="update" data-bf-part="versionValue">{data.currentVersion}</span>
+            <span className="bitfun-update-available__value" data-bf-component="update" data-bf-part="versionValue">{displayData.currentVersion}</span>
           </div>
           <div
             className="bitfun-update-available__row bitfun-update-available__row--highlight"
diff --git a/src/web-ui/src/infrastructure/update/UpdateInstallProgressModal.scss b/src/web-ui/src/infrastructure/update/UpdateInstallProgressModal.scss
index 3ed85eff69..3ed712c174 100644
--- a/src/web-ui/src/infrastructure/update/UpdateInstallProgressModal.scss
+++ b/src/web-ui/src/infrastructure/update/UpdateInstallProgressModal.scss
@@ -14,10 +14,12 @@
 }
 
 .bitfun-update-progress__fill {
+  width: 100%;
   height: 100%;
   border-radius: 4px;
   background: var(--bf-appearance-token-color-accent-500);
-  transition: width 0.15s ease-out;
+  transform-origin: left center;
+  transition: transform 0.15s ease-out;
 }
 
 .bitfun-update-progress__fill--indeterminate {
@@ -57,3 +59,14 @@
   gap: 8px;
   margin-top: 12px;
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .bitfun-update-progress__fill {
+    transition: none;
+  }
+
+  .bitfun-update-progress__fill--indeterminate {
+    animation: none;
+    transform: none;
+  }
+}
diff --git a/src/web-ui/src/infrastructure/update/UpdateInstallProgressModal.tsx b/src/web-ui/src/infrastructure/update/UpdateInstallProgressModal.tsx
index 054e42a5ff..0be04a6258 100644
--- a/src/web-ui/src/infrastructure/update/UpdateInstallProgressModal.tsx
+++ b/src/web-ui/src/infrastructure/update/UpdateInstallProgressModal.tsx
@@ -103,7 +103,7 @@ export const UpdateInstallProgressModal: React.FC<UpdateInstallProgressModalProp
                 ? 'bitfun-update-progress__fill'
                 : 'bitfun-update-progress__fill bitfun-update-progress__fill--indeterminate'
             }
-            style={pct != null ? { width: `${pct}%` } : undefined}
+            style={pct != null ? { transform: `scaleX(${pct / 100})` } : undefined}
             data-bf-component="update"
             data-bf-part="progressFill"
             data-bf-state={pct == null ? 'indeterminate' : undefined}
diff --git a/src/web-ui/src/locales/en-US/common.json b/src/web-ui/src/locales/en-US/common.json
index 5efc7e28b4..ea8e7fb13d 100644
--- a/src/web-ui/src/locales/en-US/common.json
+++ b/src/web-ui/src/locales/en-US/common.json
@@ -224,6 +224,7 @@
       "sessions": "Sessions",
       "project": "Directory",
       "persona": "Assistant",
+      "todos": "Todos",
       "agents": "Agents",
       "skills": "Skills",
       "tools": "Tools",
@@ -234,6 +235,7 @@
     },
     "tooltips": {
       "persona": "Assistant — create and manage all assistant instances",
+      "todos": "Todos — every scheduled task, by list and calendar",
       "agents": "Which agents it can call",
       "skills": "What it knows — specialized knowledge files",
       "tools": "What it can use — built-in tools & MCP services",
@@ -429,7 +431,7 @@
         "enabledHint": "Enable this job",
         "scheduleKind": "Schedule type",
         "at": "Run at",
-        "everyMs": "Interval (minutes)",
+        "everyMs": "Interval",
         "anchorMs": "Anchor time (optional)",
         "cronExpr": "Cron expression",
         "timezone": "Timezone (optional)",
@@ -454,9 +456,13 @@
         "cron": "Cron"
       },
       "scheduleSummary": {
-        "every": "Every {{everyMinutes}} minutes",
         "cron": "Cron: {{expr}}",
-        "cronWithTz": "Cron: {{expr}} · {{tz}}"
+        "cronWithTz": "Cron: {{expr}} · {{tz}}",
+        "everyUnit": {
+          "minute": "Every {{value}} minutes",
+          "hour": "Every {{value}} hours",
+          "day": "Every {{value}} days"
+        }
       },
       "targets": {
         "session": "Session",
@@ -503,6 +509,11 @@
         "promptRequired": "Please enter the job prompt",
         "workspaceRequired": "Please enter a workspace path",
         "sessionRequired": "Please select a session"
+      },
+      "intervalUnits": {
+        "minute": "Minutes",
+        "hour": "Hours",
+        "day": "Days"
       }
     },
     "workspaces": {
@@ -767,6 +778,18 @@
     "peerRemoteLabel": "{{name}}",
     "peerRemoteBadgeTitle": "Remote device: {{name}}",
     "disconnectPeer": "Disconnect",
+    "deviceSwitcher": {
+      "title": "Devices",
+      "open": "Switch device",
+      "running": "$t(shared:statuses.running)",
+      "noDevices": "No other devices signed in to this account.",
+      "hint": "Switching only changes what this window shows. Every device keeps running its own tasks.",
+      "othersRunning": "Other devices are still working ({{count}})",
+      "switched": "Now showing {{name}}",
+      "switchedLocal": "Now showing this device",
+      "disconnected": "Disconnected from {{name}}",
+      "disconnectHint": "Stop controlling this device and cancel work it is running for you"
+    },
     "peerAutoExitOffline": "Remote device \"{{name}}\" went offline — disconnected",
     "peerAutoExitRpc": "Lost connection to remote device \"{{name}}\" — disconnected",
     "syncInProgressHint": "Cloud sync is still running. Please wait before opening a remote device.",
@@ -1346,6 +1369,7 @@
     "browser": "Browser",
     "insights": "Insights",
     "assistant": "Assistant",
+    "todos": "Todos",
     "shell": "Shell",
     "panelView": "Panel View"
   },
@@ -1711,5 +1735,14 @@
   },
   "collapse": "Collapse",
   "expand": "Expand",
-  "retry": "Retry"
+  "retry": "Retry",
+  "dateTimeField": {
+    "label": "Date and time",
+    "openPicker": "Open the date picker",
+    "pickerLabel": "Choose a date",
+    "previousMonth": "Previous month",
+    "nextMonth": "Next month",
+    "now": "Now",
+    "close": "Close"
+  }
 }
diff --git a/src/web-ui/src/locales/en-US/flow-chat.json b/src/web-ui/src/locales/en-US/flow-chat.json
index 6120daec6d..48a573478c 100644
--- a/src/web-ui/src/locales/en-US/flow-chat.json
+++ b/src/web-ui/src/locales/en-US/flow-chat.json
@@ -93,6 +93,7 @@
     "failedDescription": "Retry loading the saved conversation. If it was imported from another device, check your account and connection first.",
     "preparingOlderHistory": "Preparing older history...",
     "olderHistoryNotReady": "Older history is not ready yet.",
+    "newerHistoryNotReady": "Newer history is not ready yet.",
     "remoteSessionMissing": "The backend session data was not found. If you just reconnected an SSH remote workspace, close and reopen the remote project, or create a new session and try again.",
     "retry": "Retry"
   },
@@ -174,7 +175,6 @@
       "tokens": "{{value}} tokens"
     },
     "loading": {
-      "markdown": "Generating usage report...",
       "title": "Generating usage report",
       "description": "Reading local session records and preparing a privacy-safe summary.",
       "steps": {
@@ -315,7 +315,9 @@
     },
     "slowestLabels": {
       "modelCall": "Turn {{turn}} model call",
-      "modelCallUnknown": "Model call"
+      "modelCallUnknown": "Model call",
+      "turn": "Turn {{turn}}",
+      "turnUnknown": "Turn"
     },
     "slowest": {
       "details": {
@@ -452,6 +454,8 @@
     "restoreMain": "Restore Main Window",
     "inUseTitle": "Session open elsewhere",
     "inUseMessage": "This session is open in another BitFun instance. Close it there, then retry.",
+    "surfaceSwitchDroppedTitle": "Message not sent",
+    "surfaceSwitchDropped": "The device switched before this message was sent, and its queue is full. Send it again.",
     "retry": "Retry"
   },
   "scroll": {
@@ -478,23 +482,20 @@
     "clickToCollapse": "Click to collapse",
     "fillToInput": "Fill to input",
     "cannotRollback": "Cannot rollback",
+    "rollbackDisabledBusy": "Wait until the session is idle before rolling back.",
     "rollbackDisabledRemote": "Remote workspaces do not support complete rollback because remote file snapshots are not recorded. No files or messages will be changed.",
     "rollbackTo": "Rollback to before turn {{index}} (delete this and following turns)",
     "rollbackDialogTitle": "Rollback to before turn {{index}}?",
     "rollbackDialogIntro": "This will:",
     "rollbackDialogBulletFiles": "Undo all file modifications from that turn onwards",
     "rollbackDialogBulletHistory": "Delete that turn and all following dialog records (irreversible)",
-    "rollbackPanelDialogTitle": "Roll back to before turn {{index}}?",
-    "rollbackPanelDialogIntro": "This will:",
-    "rollbackPanelBulletRestore": "Restore files to the state before turn {{index}}",
-    "rollbackPanelBulletUndo": "Undo all file changes from that turn onward",
-    "rollbackPanelBulletHistory": "Keep the session history (you can roll forward again anytime)",
     "rollbackSuccess": "Rolled back and deleted subsequent dialog records",
     "rollbackFailed": "Rollback failed",
     "saveEdit": "Save and rerun",
     "cancelEdit": "Cancel",
     "editPlaceholder": "Edit your message...",
     "cannotEdit": "Cannot edit this message",
+    "editDisabledBusy": "Wait until the session is idle before editing and rerunning.",
     "editDisabledImages": "Image messages cannot be edited yet",
     "editDisabledRemote": "Editing and rerunning requires complete rollback, which is unavailable because remote file snapshots are not recorded.",
     "editDisabledLocalCommand": "Local command messages cannot be edited",
@@ -533,6 +534,8 @@
     "sendShortcut": "Send (⏎)",
     "stop": "Stop",
     "stopGeneration": "Stop Generation (Esc)",
+    "continueInterrupted": "Continue interrupted work",
+    "continueInterruptedFailed": "Could not continue the interrupted work. Please try again.",
     "processingCapsule": "Processing",
     "cancelShortcut": "Cancel",
     "clear": "Clear",
@@ -677,7 +680,6 @@
         "sessionUnavailable": "Remote task information is incomplete. Reopen the task or create a new one.",
         "compactWhileRunning": "Wait for the current remote task to finish before compacting the context.",
         "compactRejected": "The target could not start compaction. Try again shortly.",
-        "imagesWhileRunning": "Images will be sent with the next turn. Wait for the current remote task to finish and try again.",
         "sessionNotReady": "The remote task is still being prepared. Try sending again shortly.",
         "submissionUnconfirmed": "BitFun cannot yet confirm whether the target received this task. Check the task status shortly."
       }
@@ -721,9 +723,14 @@
       "noSession": "Open or start a session before changing its permission mode.",
       "turnScope": "Next message only",
       "currentTurnOverride": "Permissions: {{mode}} (next message only)",
+      "activeTurnScope": "This turn",
+      "currentActiveTurnOverride": "Permissions: {{mode}} (this turn only)",
       "nextTurnOnly": "Use {{mode}} for the next message only",
       "nextTurnOnlyShort": "Once",
+      "activeTurnOnly": "Use {{mode}} for the rest of this turn",
+      "activeTurnOnlyShort": "This turn",
       "fullAccessWarningMessageNextTurn": "Full access allows tools by default without asking each time. This applies to the next message only; project and enforced rules still apply.",
+      "fullAccessWarningMessageActiveTurn": "Full access allows tools by default without asking each time. This applies to later model rounds in the current turn; project and enforced rules still apply.",
       "openDefaultSettings": "Open permission settings"
     },
     "addModeTooltip": "Add Plan or Debug",
@@ -881,6 +888,8 @@
   "fileMention": {
     "searchResults": "Search Results",
     "loading": "Loading...",
+    "browseUnavailable": "Workspace files are unavailable. Check the connection and try again.",
+    "searchUnavailable": "Workspace search is unavailable. Check the connection and try again.",
     "noMatchingFiles": "No matching files found",
     "emptyDirectory": "Empty directory",
     "rootDirectory": "Root",
@@ -1325,9 +1334,6 @@
       "failed": "Command failed"
     }
   },
-  "stickyTaskIndicator": {
-    "tooltip": "Jump to current task"
-  },
   "sessionFilesBadge": {
     "files": "files",
     "filesSummaryCount": "{{count}} files",
@@ -1645,6 +1651,20 @@
       "commandInterrupted": "Command interrupted",
       "executionFailed": "Command execution failed"
     },
+    "runCode": {
+      "title": "Run Code",
+      "programLabel": "Program",
+      "outputLabel": "Output",
+      "writing": "Writing the program...",
+      "running": "Running the program...",
+      "completed": "Program finished",
+      "failed": "Program failed",
+      "cancelled": "Program cancelled",
+      "rejected": "Program rejected",
+      "copyCode": "Copy code",
+      "codeCopied": "Code copied",
+      "copyCodeFailed": "Failed to copy code"
+    },
     "approval": {
       "waiting": "Waiting for confirmation",
       "confirm": "Allow",
@@ -2387,6 +2407,9 @@
     "fastModel": "Fast Model",
     "fastMode": "Fast mode",
     "fastModeDescription": "1.5x speed with higher credit usage",
+    "acpMode": "Mode",
+    "acpModeLocked": "This conversation has already started, so its mode is fixed.",
+    "acpModeFailed": "Failed to switch mode",
     "switchFailed": "Failed to switch model",
     "modelNotConfigured": "Not Configured",
     "contextUsage": {
@@ -2514,7 +2537,6 @@
     },
     "errors": {
       "emptyContent": "Message content cannot be empty",
-      "richContentUnsupported": "Messages with attachments or structured metadata can only be sent after the active turn finishes",
       "sendNowFailed": "Send now failed; please try again"
     }
   },
diff --git a/src/web-ui/src/locales/en-US/scenes/todos.json b/src/web-ui/src/locales/en-US/scenes/todos.json
new file mode 100644
index 0000000000..7a3bebbe57
--- /dev/null
+++ b/src/web-ui/src/locales/en-US/scenes/todos.json
@@ -0,0 +1,115 @@
+{
+  "title": "Todos",
+  "header": {
+    "summary": "{{total}} scheduled · {{dueSoon}} due within 24 hours"
+  },
+  "actions": {
+    "newTodo": "New Todo",
+    "refresh": "Refresh",
+    "edit": "Edit Todo",
+    "delete": "Delete Todo",
+    "toggleEnabled": "Toggle enabled state"
+  },
+  "list": {
+    "title": "Next 24 hours",
+    "hint": "Runs due within a day, soonest first.",
+    "empty": "Nothing is due in the next 24 hours."
+  },
+  "calendar": {
+    "title": "Later",
+    "hint": "Every scheduled run, including the next 24 hours.",
+    "previousMonth": "Previous month",
+    "nextMonth": "Next month",
+    "today": "Today",
+    "dayDetailTitle": "Selected day",
+    "dayEmpty": "Nothing scheduled on this day.",
+    "clearDay": "Clear",
+    "dayCount": "Scheduled: {{total}}",
+    "moreCount": "+{{total}} more"
+  },
+  "badges": {
+    "nextRun": "Next run",
+    "overdue": "Overdue"
+  },
+  "relative": {
+    "now": "Any moment",
+    "overdue": "Overdue",
+    "inMinutes": "in {{value}} min",
+    "inHours": "in {{value}} hr",
+    "inOneDay": "in 1 day",
+    "inDays": "in {{value}} days"
+  },
+  "schedule": {
+    "once": "Once at {{at}}",
+    "cron": "Cron: {{expr}}",
+    "cronWithTz": "Cron: {{expr}} · {{tz}}",
+    "kinds": {
+      "at": "One-time",
+      "every": "Interval",
+      "cron": "Cron"
+    },
+    "everyUnit": {
+      "minute": "Every {{value}} minutes",
+      "hour": "Every {{value}} hours",
+      "day": "Every {{value}} days"
+    },
+    "intervalUnits": {
+      "minute": "Minutes",
+      "hour": "Hours",
+      "day": "Days"
+    }
+  },
+  "target": {
+    "existingSession": "Existing session",
+    "newSession": "New {{agentType}} session"
+  },
+  "inactive": {
+    "disabled": "Paused",
+    "invalid": "Invalid schedule",
+    "title": "No upcoming run ({{total}})"
+  },
+  "editor": {
+    "createTitle": "New Todo",
+    "editTitle": "Edit Todo",
+    "noWorkspace": "Open a workspace before creating a Todo — a scheduled run needs somewhere to execute.",
+    "fields": {
+      "name": "Name",
+      "agentType": "Agent type",
+      "scheduleKind": "Schedule",
+      "at": "Run at",
+      "anchor": "Anchor time (optional)",
+      "cronExpr": "Cron expression",
+      "timezone": "Timezone (optional)",
+      "enabled": "Enabled",
+      "prompt": "Prompt",
+      "runsIn": "Runs in",
+      "every": "Interval"
+    },
+    "placeholders": {
+      "name": "For example: Daily standup summary",
+      "workspace": "Select a workspace",
+      "agentType": "For example: agentic or Cowork",
+      "anchor": "Leave blank to use the creation time",
+      "timezone": "For example: Asia/Shanghai",
+      "prompt": "What should the agent do when this Todo fires?"
+    },
+    "hints": {
+      "cronExpr": "Fields are minute hour day month weekday. Weekday runs 1-7 with Sunday as 1, so 0 8 * * 2 is every Monday at 08:00.",
+      "boundSession": "This Todo is bound to an existing session and keeps running there."
+    },
+    "actions": {
+      "create": "Create Todo",
+      "save": "Save changes"
+    }
+  },
+  "deleteDialog": {
+    "title": "Delete \"{{name}}\"?"
+  },
+  "messages": {
+    "loadFailed": "Failed to load Todos: {{error}}",
+    "saveFailed": "Failed to save Todo: {{error}}",
+    "deleteFailed": "Failed to delete Todo: {{error}}",
+    "updateFailed": "Failed to update Todo: {{error}}",
+    "workspaceRequired": "Select a workspace for this Todo first."
+  }
+}
diff --git a/src/web-ui/src/locales/en-US/settings.json b/src/web-ui/src/locales/en-US/settings.json
index 92c344519f..5729c0326b 100644
--- a/src/web-ui/src/locales/en-US/settings.json
+++ b/src/web-ui/src/locales/en-US/settings.json
@@ -21,7 +21,7 @@
       "models": "AI models, API keys, providers, proxy, and session title.",
       "worktrees": "Defaults for isolated Git worktrees and parallel sessions.",
       "sessionPersonalization": "Agent companion.",
-      "sessionPermissions": "Accelerated workspace search, tool confirmation, Computer use, browser, and debug.",
+      "sessionPermissions": "Tool permissions, execution, desktop control, and browser access.",
       "quickActions": "One-click AI actions after coding. Built-in and customizable prompts.",
       "voiceInput": "Local microphone input and speech-to-text model.",
       "review": "Review strategy, coverage depth, capacity, cost, and latency controls.",
diff --git a/src/web-ui/src/locales/en-US/settings/agentic-tools.json b/src/web-ui/src/locales/en-US/settings/agentic-tools.json
index 97872be0f3..366eb72b96 100644
--- a/src/web-ui/src/locales/en-US/settings/agentic-tools.json
+++ b/src/web-ui/src/locales/en-US/settings/agentic-tools.json
@@ -14,22 +14,22 @@
   "config": {
     "autoExecute": "Auto Execute",
     "autoExecuteDesc": "Skip user confirmation before tool execution.",
-    "subagentMaxConcurrency": "Subagent Concurrency Limit",
-    "subagentMaxConcurrencyDesc": "How many subagents may run in parallel at the same time.",
+    "subagentMaxConcurrency": "Concurrent task limit",
+    "subagentMaxConcurrencyDesc": "Maximum number of tasks that can run at the same time.",
     "confirmTimeout": "Confirm Timeout",
     "confirmTimeoutDesc": "Maximum time (seconds) to wait for user confirmation of tool calls.",
     "confirmTimeoutHint": "Set 0 to disable confirmation timeout.",
-    "executionTimeout": "Execution Timeout",
-    "executionTimeoutDesc": "Maximum time (seconds) for tool execution.",
-    "executionTimeoutHint": "Set 0 to disable execution timeout. Subagents and command execution tools manage their own execution limits and are not capped by this setting.",
+    "executionTimeout": "Tool timeout",
+    "executionTimeoutDesc": "Maximum time for a single tool operation. Set 0 for no limit.",
+    "executionTimeoutHint": "Set 0 for no limit.",
     "subagentBatchPolicy": {
-      "label": "Subagent Batch Scheduling",
-      "desc": "Choose how multiple subagent launches from the same model response are scheduled.",
-      "tooltipLabel": "Subagent batch scheduling details",
-      "safeOnly": "Safe only",
-      "safeOnlyDesc": "Parallelize only subagent launches whose target is marked read-only.",
-      "forceParallel": "Force parallel",
-      "forceParallelDesc": "Run multiple subagent launches from the same response in parallel, still respecting subagent capacity limits."
+      "label": "Task concurrency",
+      "desc": "Choose how multiple tasks run when they start together.",
+      "tooltipLabel": "Task concurrency details",
+      "safeOnly": "Safe parallel",
+      "safeOnlyDesc": "Run tasks together only when they do not modify content.",
+      "forceParallel": "Prefer parallel",
+      "forceParallelDesc": "Run multiple tasks together whenever possible."
     },
     "seconds": "sec"
   },
diff --git a/src/web-ui/src/locales/en-US/settings/ai-features.json b/src/web-ui/src/locales/en-US/settings/ai-features.json
index db9298f73a..3c738108b9 100644
--- a/src/web-ui/src/locales/en-US/settings/ai-features.json
+++ b/src/web-ui/src/locales/en-US/settings/ai-features.json
@@ -42,10 +42,6 @@
     "git-func-agent": {
       "displayName": "Git Functions",
       "description": "Commit messages, code review"
-    },
-    "startchat-func-agent": {
-      "displayName": "Session Start",
-      "description": "Work status analysis, welcome messages"
     }
   },
   "loading": {
diff --git a/src/web-ui/src/locales/en-US/settings/ai-model.json b/src/web-ui/src/locales/en-US/settings/ai-model.json
index 038fed194d..cb670c46c5 100644
--- a/src/web-ui/src/locales/en-US/settings/ai-model.json
+++ b/src/web-ui/src/locales/en-US/settings/ai-model.json
@@ -30,6 +30,7 @@
     "loadFailed": "Failed to load session title settings",
     "model": {
       "label": "Session Title Generation Model",
+      "inherit": "Current session model",
       "primary": "Primary Model",
       "fast": "Fast Model"
     },
@@ -341,8 +342,14 @@
       "modelsDev": "Explicit models.dev",
       "disabled": "Custom only"
     },
-    "catalogProvider": "models.dev provider",
-    "catalogModel": "models.dev model",
+    "catalogProvider": "Provider",
+    "catalogModel": "Model",
+    "catalogSearch": "Quick search",
+    "catalogSearchPlaceholder": "Enter provider or model keywords",
+    "catalogSearchHint": "Select a result to fill the provider and model below.",
+    "catalogSearchResults": "models.dev model search results",
+    "catalogSearchEmpty": "No matching models.dev reasoning models",
+    "catalogSearchLimit": "Many results found; keep typing to narrow the list",
     "catalogUnbound": "Not bound",
     "catalogProviderCustomValueHint": "Use custom provider ID",
     "catalogModelCustomValueHint": "Use custom model ID",
@@ -351,12 +358,14 @@
     "auto": "Auto (model default)",
     "autoShort": "Auto",
     "generatedTitle": "Generated presets",
+    "unavailableTitle": "Some models.dev presets are unavailable",
+    "unavailableDescription": "The current API format, {{format}}, cannot reliably apply these presets: {{presets}}. Refer to your provider's official documentation and configure the required fields with Request body patch (JSON Merge Patch) in a custom preset.",
+    "unknownRequestFormat": "Unknown",
     "customTitle": "Custom presets",
-    "customTooltip": "Custom presets save a set of reasoning parameters as a selectable option in the chat input. Give each preset a unique ID and display name, then add the control supported by the model API: reasoning effort, a reasoning toggle, or a token budget. Add a request JSON patch only when provider-specific parameters are needed.",
+    "customTooltip": "Custom presets save a set of reasoning parameters as a selectable option in the chat input. Give each preset a name, then add the control supported by the model API: reasoning effort, a reasoning toggle, or a token budget. Add a request body patch (JSON Merge Patch) only when provider-specific parameters are needed.",
     "add": "Add preset",
     "addAction": "Add action",
     "empty": "No custom presets",
-    "id": "Preset ID",
     "label": "Label",
     "labelPlaceholder": "Display label",
     "default": "Default",
@@ -370,7 +379,7 @@
     "effortCustomWarning": "Custom value; confirm that the model API supports it.",
     "settingToggle": "On / off toggle",
     "settingBudget": "Token budget",
-    "settingPatch": "Request JSON patch",
+    "settingPatch": "Request body patch (JSON Merge Patch)",
     "actionSummaryEffort": "Effort: {{value}}",
     "actionSummaryEnabled": "Reasoning on",
     "actionSummaryDisabled": "Reasoning off",
diff --git a/src/web-ui/src/locales/en-US/settings/default-model.json b/src/web-ui/src/locales/en-US/settings/default-model.json
index cc8d4ab430..d048e6dae8 100644
--- a/src/web-ui/src/locales/en-US/settings/default-model.json
+++ b/src/web-ui/src/locales/en-US/settings/default-model.json
@@ -60,10 +60,6 @@
         "displayName": "Git Functions",
         "description": "Commit messages, code review"
       },
-      "startchat-func-agent": {
-        "displayName": "Chat Startup",
-        "description": "Work status analysis, welcome messages"
-      },
       "arc-func-agent": {
         "displayName": "Architecture Analysis",
         "description": "Dependency graph, Mermaid diagrams"
diff --git a/src/web-ui/src/locales/en-US/settings/external-sources.json b/src/web-ui/src/locales/en-US/settings/external-sources.json
index 671d0bea54..48d7a64b0a 100644
--- a/src/web-ui/src/locales/en-US/settings/external-sources.json
+++ b/src/web-ui/src/locales/en-US/settings/external-sources.json
@@ -121,6 +121,13 @@
     "modelBindingUpdated": "Saved the agent model binding and refreshed affected agents.",
     "mcpUpdated": "Saved the MCP server choice and refreshed its status."
   },
+  "bulkActions": {
+    "enablePending": "Enable all pending ({{count}})",
+    "disableAll": "Disable all",
+    "enableRisk": "This approves exactly the {{count}} items currently shown. If discovery changes, BitFun will ask you to review again.",
+    "enabled": "Enabled the selected pending items.",
+    "disabled": "Disabled the selected items."
+  },
   "recoveryActions": {
     "refresh": "Refresh status",
     "retry": "Retry",
@@ -238,7 +245,8 @@
       "unreadableSource": "BitFun could not read part of a source. Check file access, then refresh.",
       "notSupported": "This type of external content is not supported yet, so BitFun did not load or run it.",
       "checkFailed": "BitFun could not check one source. Other sources remain available; refresh to retry.",
-      "sourceIssue": "BitFun found an issue in one source. The affected content was not enabled. Check the source configuration, then refresh."
+      "runtimeUnavailable": "An MCP server from this source is unavailable. Disable it, fix its configuration or authentication, then enable it again.",
+      "sourceIssue": "BitFun could not finish checking one source. Existing usable content remains available; refresh or review the technical details."
     }
   },
   "sources": {
@@ -414,6 +422,7 @@
     "externalSource": "External AI application",
     "source": "Source: {{source}}",
     "sourceLocation": "Configuration: {{location}}",
+    "sourceLocationLabel": "Configuration",
     "scope": "Applies to: {{scope}}",
     "command": "Command: {{command}}",
     "url": "Address: {{url}}",
@@ -430,6 +439,27 @@
     "timeoutExecution": "execution {{duration}}",
     "timeoutMilliseconds": "{{value}} ms",
     "changePolicy": "BitFun asks again before loading a changed server configuration.",
+    "failureReason": "Reason: {{reason}}",
+    "failureReasons": {
+      "authentication": "Authentication is required for this MCP server.",
+      "timeout": "The MCP server did not finish starting before its timeout.",
+      "commandUnavailable": "The configured MCP command could not be started.",
+      "workingDirectoryUnavailable": "The configured MCP working directory is unavailable.",
+      "connectionFailed": "BitFun could not connect to the MCP server.",
+      "protocolFailed": "The MCP server did not complete the MCP startup handshake.",
+      "nativeConfigurationUnavailable": "BitFun could not read the current MCP configuration.",
+      "hostReadOnly": "This host can discover MCP servers but cannot run them.",
+      "configurationChanged": "The MCP configuration changed before activation. Refresh and confirm it again.",
+      "configurationInvalid": "The MCP configuration cannot be used by the BitFun runtime.",
+      "hostUnavailable": "The MCP runtime is not available in this host.",
+      "installFailed": "BitFun could not register this MCP server with the runtime.",
+      "preparationFailed": "BitFun could not prepare this MCP configuration for activation.",
+      "serverMissing": "The MCP server is no longer registered with the runtime.",
+      "runtimeFailed": "The MCP server failed or stopped unexpectedly.",
+      "stopped": "The MCP server is not currently running.",
+      "statusUnavailable": "BitFun could not read the current MCP server status.",
+      "other": "The MCP server failed to start. Check its source configuration and BitFun logs."
+    },
     "runtimeUnavailableGuidance": "Disable this server, fix the source configuration or authentication, then enable it again. Restarting BitFun is usually not required.",
     "unsupportedGuidance": "Change this setting in the source application, then refresh.",
     "enable": "Enable server",
diff --git a/src/web-ui/src/locales/en-US/settings/session-config.json b/src/web-ui/src/locales/en-US/settings/session-config.json
index 6efa1ef2b6..ca4a606941 100644
--- a/src/web-ui/src/locales/en-US/settings/session-config.json
+++ b/src/web-ui/src/locales/en-US/settings/session-config.json
@@ -5,37 +5,37 @@
   },
   "permissionsPage": {
     "title": "Permission management",
-    "subtitle": "Accelerated workspace search, tool execution, tool definition loading, browser control, and debug mode"
+    "subtitle": "Manage tool permissions, execution, desktop control, and browser access."
   },
   "features": {
     "workspaceSearch": {
       "title": "Accelerated workspace search",
-      "subtitle": "Use flashgrep-backed indexed search for local workspaces. When off, BitFun falls back to legacy search.",
+      "subtitle": "Speed up file search in large workspaces. Standard search remains available when this is off.",
       "enable": "Enable accelerated workspace search"
     }
   },
   "toolExecution": {
-    "sectionTitle": "Tool execution behavior",
-    "sectionDescription": "Confirmation and timeout settings when tools run in a session."
+    "sectionTitle": "Tool execution",
+    "sectionDescription": "Set tool timeouts and concurrent task limits."
   },
   "permissionPolicy": {
     "sectionTitle": "Tool permissions",
-    "sectionDescription": "Choose the default tool access policy for sessions and how permission prompts are handled.",
+    "sectionDescription": "Choose when BitFun asks you to confirm tool actions.",
     "mode": "Default permission mode",
     "ask": "Ask for confirmation",
-    "askDescription": "External access, file changes, and command execution require confirmation.",
+    "askDescription": "Confirm before files change, commands run, or external services are accessed.",
     "fullAccess": "Full access",
-    "fullAccessDescription": "Tools are allowed by default without confirmation.",
+    "fullAccessDescription": "Do not confirm each tool action.",
     "fullAccessWarningTitle": "Enable full access?",
     "fullAccessWarningMessage": "Full access allows tools by default without asking each time.",
     "fullAccessConfirm": "Enable full access",
     "cancel": "Cancel",
     "autoApprove": "Auto approve",
-    "autoApproveDescription": "Automatically approve requests that require confirmation.",
+    "autoApproveDescription": "Automatically allow actions that would normally need confirmation.",
     "showInChatInput": "Show permission mode selector",
-    "showInChatInputDescription": "Show the selector below the chat input, where the mode applies to the current session only. Hiding it does not change any session's permission mode.",
+    "showInChatInputDescription": "Show the permission mode below the chat input so it can be changed for the current session.",
     "globalRules": "Global rules",
-    "globalRulesDescription": "Define user-level rules that apply after the selected mode and before project and Agent rules.",
+    "globalRulesDescription": "Set shared allow, ask, or deny rules for every workspace.",
     "manageGlobalRules": "Manage rules",
     "globalRulesDialogTitle": "Global tool permission rules",
     "globalRulesDialogDescription": "These user-level rules apply to every workspace. Later project and Agent rules can override them; enforced product restrictions remain authoritative.",
@@ -52,7 +52,7 @@
     "discardGlobalRules": "Discard changes",
     "saveGlobalRules": "Save rules",
     "globalRulesEffects": { "allow": "Allow", "ask": "Ask", "deny": "Deny" },
-    "modeDescription": "Applies to sessions that have not chosen their own mode. Each session can override it from the chat input."
+    "modeDescription": "Used for new sessions and can be changed temporarily from the chat input."
   },
   "projectPermissions": {
     "description": "Always allow decisions are saved as remembered grants for the current project; static project rules apply before a tool runs.",
@@ -91,54 +91,69 @@
     "effects": { "allow": "Allow", "ask": "Ask", "deny": "Deny" }
   },
   "deferredToolLoading": {
-    "sectionTitle": "Deferred tool loading",
-    "sectionDescription": "Load detailed schemas for some tools only when needed, including a subset of built-in tools and all MCP tools.",
-    "warning": "Each request now sends full schemas for enabled tools. Configuring many MCP tools uses more tokens."
+    "sectionTitle": "Load tools as needed",
+    "sectionDescription": "Load tool details only when they are needed.",
+    "warning": "Turning this off loads every tool definition and may increase model usage."
   },
   "computerUse": {
-    "sectionTitle": "Computer use (desktop)",
-    "sectionDescription": "In the BitFun desktop app, the assistant can capture the screen and control the mouse and keyboard; requires a multimodal model for vision.",
-    "enable": "Enable Computer use",
-    "enableDesc": "When off, the ComputerUse tool stays disabled in every session mode. Browser control (ControlHub) is not yet gated by this switch.",
+    "sectionTitle": "Desktop control",
+    "sectionDescription": "Allow BitFun to view the screen and use the mouse and keyboard.",
+    "enable": "Allow desktop control",
+    "enableDesc": "When off, BitFun cannot control desktop apps. Browser access is managed separately.",
     "accessibility": "Accessibility",
-    "accessibilityDesc": "macOS: lets BitFun read on-screen UI elements and send mouse/keyboard input to other apps. Not applicable on Windows; on Linux this requires an X11 session.",
+    "accessibilityDesc": "Allows BitFun to identify and interact with controls in other apps.",
     "screenCapture": "Screen recording",
-    "screenCaptureDesc": "Lets BitFun capture screenshots of your screen so the assistant can see what it is controlling.",
+    "screenCaptureDesc": "Allows BitFun to see the contents of your screen.",
     "granted": "Granted",
     "notGranted": "Not granted",
-    "openSettings": "Setting",
+    "openSettings": "System settings",
     "refreshStatus": "Refresh status",
-    "desktopOnly": "Computer use settings are only available in the BitFun desktop app.",
-    "platformNote": "Note"
+    "desktopOnly": "Desktop control is only available in the BitFun desktop app.",
+    "platformNote": "Note",
+    "platformNotes": {
+      "macos": "This build still needs Accessibility permission in System Settings.",
+      "windows": "Some protected windows or remote desktop environments may not be controllable.",
+      "linux": "This desktop environment may not support full mouse, keyboard, or screen control.",
+      "generic": "Full desktop control is not available on this system."
+    }
   },
   "browserControl": {
     "sectionTitle": "Browser control",
-    "sectionDescription": "Choose a browser and start CDP control.",
+    "sectionDescription": "Choose the browser BitFun uses and how it connects.",
     "desktopOnly": "Browser control is only available in the BitFun desktop app.",
     "preferredBrowser": "Browser",
-    "preferredBrowserDesc": "Choose which browser BitFun controls through CDP. Default follows the system default browser.",
+    "preferredBrowserDesc": "The default option follows your system browser.",
     "notInstalled": "not installed",
     "status": "Connection",
     "statusDesc": "",
     "notConnected": "Not connected",
+    "readyNotConnected": "Ready, connects on use",
     "refreshStatus": "Refresh status",
     "connect": "Connect",
+    "defaultCdp": "Use existing browser",
+    "defaultCdpDesc": "Use an open Chrome or Edge window and keep its tabs and signed-in accounts. The browser still confirms each connection.",
+    "autoConnectOnStartup": "Connect on startup",
+    "autoConnectOnStartupDesc": "Connect to an open browser when BitFun starts. The browser may ask again after it restarts.",
+    "defaultCdpEnabled": "Enabled",
+    "defaultCdpDisabled": "Not enabled",
+    "enableDefaultCdp": "Enable and connect",
+    "defaultCdpEnablePrompt": "Opened {{browser}}'s Remote debugging page. Tick “Allow remote debugging for this browser instance”; BitFun will detect it and continue automatically, then choose “Allow” in the browser connection prompt.",
+    "defaultCdpConnectPrompt": "Connecting to your current {{browser}}. Choose “Allow” in the browser prompt.",
     "connectSuccess": "Connected to {{browser}}",
     "connectFailed": "Failed to connect to browser",
-    "restartSuccess": "Restarted {{browser}} with debug mode enabled",
-    "restartFailed": "Failed to restart browser with debug mode enabled",
+    "userProfileSetupRequired": "{{browser}} opened its Remote debugging page, but the switch was not detected before the wait ended. Tick “Allow remote debugging for this browser instance”, then click Enable and connect again; your current tabs and login state are preserved.",
+    "userProfileSetupManual": "Open {{url}} in {{browser}} and tick “Allow remote debugging for this browser instance”, then click Enable and connect again; your current tabs and login state are preserved.",
+    "userProfileConnectionFailed": "{{browser}} did not approve the connection, or the request timed out. Make sure the browser is running and Remote debugging is enabled, then connect again and choose Allow in the browser.",
+    "restartSuccess": "Restarted {{browser}} and enabled browser control",
+    "restartFailed": "Could not restart and connect to {{browser}}",
     "restartModal": {
-      "title": "Enable browser debug mode",
-      "description": "{{browser}} is already running and the current instance was not started with the debug port enabled. BitFun needs to restart the browser in debug mode before it can control it.",
+      "title": "Restart browser",
+      "description": "BitFun needs to restart the current {{browser}} before it can connect.",
       "warning": "This will close the current browser windows.",
       "cancel": "Cancel",
-      "confirm": "Restart and enable debug",
+      "confirm": "Restart and connect",
       "restarting": "Restarting..."
     },
-    "createLauncher": "Create launcher",
-    "createLauncherSuccess": "Launcher created at {{path}}",
-    "createLauncherFailed": "Failed to create launcher",
-    "createLauncherDesc": "Create a browser shortcut with the debug port enabled.",
     "tabs": "tabs"
   },
   "common": {
diff --git a/src/web-ui/src/locales/en-US/tools.json b/src/web-ui/src/locales/en-US/tools.json
index ebdb1f4609..5243b55d35 100644
--- a/src/web-ui/src/locales/en-US/tools.json
+++ b/src/web-ui/src/locales/en-US/tools.json
@@ -80,7 +80,7 @@
       "copiedMarkdown": "Copied Markdown",
       "viewModeLabel": "Markdown and preview mode",
       "notice": {
-        "sourcePreviewFallback": "This document contains HTML fragments that are not safely editable in visual mode. Edit in source mode or switch to preview."
+        "sourcePreviewFallback": "This document contains syntax that is not safely editable in visual mode. Edit in source mode or switch to preview."
       }
     },
     "planViewer": {
@@ -124,6 +124,9 @@
       "rawHtml": {
         "inlineLabel": "HTML"
       },
+      "frontmatter": {
+        "label": "YAML Frontmatter"
+      },
       "details": {
         "summaryPlaceholder": "Summary"
       },
diff --git a/src/web-ui/src/locales/zh-CN/common.json b/src/web-ui/src/locales/zh-CN/common.json
index ce90acf68b..a2695fe44e 100644
--- a/src/web-ui/src/locales/zh-CN/common.json
+++ b/src/web-ui/src/locales/zh-CN/common.json
@@ -224,6 +224,7 @@
       "sessions": "会话",
       "project": "目录",
       "persona": "助理",
+      "todos": "待办事项",
       "agents": "专业智能体",
       "skills": "技能",
       "tools": "工具",
@@ -234,6 +235,7 @@
     },
     "tooltips": {
       "persona": "助理 — 创建与管理所有助理实例",
+      "todos": "待办 — 汇总所有定时任务，列表与日历两层查看",
       "agents": "它能调用哪些 Agent",
       "skills": "它懂什么专项知识 — 技能知识文件",
       "tools": "它能用什么工具 — 内置工具与 MCP 服务",
@@ -429,7 +431,7 @@
         "enabledHint": "启用该任务",
         "scheduleKind": "调度方式",
         "at": "执行时间",
-        "everyMs": "间隔（分钟）",
+        "everyMs": "间隔",
         "anchorMs": "锚点时间（可选）",
         "cronExpr": "Cron 表达式",
         "timezone": "时区（可选）",
@@ -454,9 +456,13 @@
         "cron": "Cron"
       },
       "scheduleSummary": {
-        "every": "每 {{everyMinutes}} 分钟",
         "cron": "Cron: {{expr}}",
-        "cronWithTz": "Cron: {{expr}} · {{tz}}"
+        "cronWithTz": "Cron: {{expr}} · {{tz}}",
+        "everyUnit": {
+          "minute": "每 {{value}} 分钟",
+          "hour": "每 {{value}} 小时",
+          "day": "每 {{value}} 天"
+        }
       },
       "targets": {
         "session": "会话",
@@ -503,6 +509,11 @@
         "promptRequired": "请输入任务内容",
         "workspaceRequired": "请输入工作区路径",
         "sessionRequired": "请选择会话"
+      },
+      "intervalUnits": {
+        "minute": "分钟",
+        "hour": "小时",
+        "day": "天"
       }
     },
     "workspaces": {
@@ -767,6 +778,18 @@
     "peerRemoteLabel": "{{name}}",
     "peerRemoteBadgeTitle": "远程设备：{{name}}",
     "disconnectPeer": "断开",
+    "deviceSwitcher": {
+      "title": "设备",
+      "open": "切换设备",
+      "running": "$t(shared:statuses.running)",
+      "noDevices": "该账号下暂无其他已登录设备。",
+      "hint": "切换只改变当前窗口显示的设备，各设备的任务都会继续执行。",
+      "othersRunning": "其他设备仍在执行任务（{{count}}）",
+      "switched": "已切换到 {{name}}",
+      "switchedLocal": "已切换回本机",
+      "disconnected": "已断开 {{name}}",
+      "disconnectHint": "结束对该设备的控制，并取消它正在为你执行的任务"
+    },
     "peerAutoExitOffline": "远程设备「{{name}}」已离线 — 已断开",
     "peerAutoExitRpc": "与远程设备「{{name}}」连接丢失 — 已断开",
     "syncInProgressHint": "云端同步仍在进行，请稍后再打开远程设备。",
@@ -1346,6 +1369,7 @@
     "browser": "浏览器",
     "insights": "洞察",
     "assistant": "助理",
+    "todos": "待办事项",
     "shell": "Shell",
     "panelView": "面板视图"
   },
@@ -1711,5 +1735,14 @@
   },
   "collapse": "折叠",
   "expand": "展开",
-  "retry": "重试"
+  "retry": "重试",
+  "dateTimeField": {
+    "label": "日期与时间",
+    "openPicker": "打开日期选择器",
+    "pickerLabel": "选择日期",
+    "previousMonth": "上个月",
+    "nextMonth": "下个月",
+    "now": "此刻",
+    "close": "关闭"
+  }
 }
diff --git a/src/web-ui/src/locales/zh-CN/flow-chat.json b/src/web-ui/src/locales/zh-CN/flow-chat.json
index 9be20c459d..b855d354ff 100644
--- a/src/web-ui/src/locales/zh-CN/flow-chat.json
+++ b/src/web-ui/src/locales/zh-CN/flow-chat.json
@@ -93,6 +93,7 @@
     "failedDescription": "可以重新加载已保存的会话内容；若会话来自其他设备，请先检查账号登录与网络连接。",
     "preparingOlderHistory": "正在准备更早的历史记录...",
     "olderHistoryNotReady": "更早的历史记录暂未准备好。",
+    "newerHistoryNotReady": "更新的历史记录暂未准备好。",
     "remoteSessionMissing": "在后端找不到该会话数据。若刚重新连接过 SSH 远程工作区，请关闭并重新打开该远程项目，或新建会话后再试。",
     "retry": "重试"
   },
@@ -174,7 +175,6 @@
       "tokens": "{{value}} Tokens"
     },
     "loading": {
-      "markdown": "正在生成用量报告...",
       "title": "正在生成用量报告",
       "description": "正在读取本地会话记录，并整理隐私安全的统计摘要。",
       "steps": {
@@ -280,7 +280,9 @@
     },
     "slowestLabels": {
       "modelCall": "第 {{turn}} 轮模型调用",
-      "modelCallUnknown": "模型调用"
+      "modelCallUnknown": "模型调用",
+      "turn": "第 {{turn}} 轮",
+      "turnUnknown": "轮次"
     },
     "slowest": {
       "details": {
@@ -453,6 +455,8 @@
     "restoreMain": "恢复主窗口",
     "inUseTitle": "会话已在其他实例中打开",
     "inUseMessage": "该会话已在另一个 BitFun 实例中打开。请先在那里关闭，然后重试。",
+    "surfaceSwitchDroppedTitle": "消息未发送",
+    "surfaceSwitchDropped": "消息尚未发出时设备已切换，且该会话的队列已满。请重新发送。",
     "retry": "重试"
   },
   "scroll": {
@@ -479,23 +483,20 @@
     "clickToCollapse": "点击收起",
     "fillToInput": "填充到输入框",
     "cannotRollback": "无法回滚",
+    "rollbackDisabledBusy": "请等待会话空闲后再回滚。",
     "rollbackDisabledRemote": "远程工作区未记录文件快照，暂不支持文件与消息一致回滚；不会更改任何文件或消息。",
     "rollbackTo": "回滚到第 {{index}} 轮之前（删除该轮及之后）",
     "rollbackDialogTitle": "确定回滚到第 {{index}} 轮之前？",
     "rollbackDialogIntro": "将执行：",
     "rollbackDialogBulletFiles": "撤销从该轮开始的所有文件修改",
     "rollbackDialogBulletHistory": "删除该轮及之后的对话记录（不可恢复）",
-    "rollbackPanelDialogTitle": "回滚到第 {{index}} 轮之前？",
-    "rollbackPanelDialogIntro": "将执行：",
-    "rollbackPanelBulletRestore": "将文件恢复到第 {{index}} 轮之前的状态",
-    "rollbackPanelBulletUndo": "撤销从该轮开始的所有文件变更",
-    "rollbackPanelBulletHistory": "保留会话历史（之后仍可继续对话）",
     "rollbackSuccess": "已回滚并删除后续对话记录",
     "rollbackFailed": "回滚失败",
     "saveEdit": "保存并重跑",
     "cancelEdit": "取消",
     "editPlaceholder": "编辑你的消息...",
     "cannotEdit": "无法编辑该消息",
+    "editDisabledBusy": "请等待会话空闲后再编辑并重跑。",
     "editDisabledImages": "暂不支持编辑图片消息",
     "editDisabledRemote": "编辑并重跑需要完整回滚；远程工作区未记录文件快照，因此暂不支持。",
     "editDisabledLocalCommand": "无法编辑本地命令消息",
@@ -534,6 +535,8 @@
     "sendShortcut": "发送 (⏎)",
     "stop": "停止",
     "stopGeneration": "停止生成 (Esc)",
+    "continueInterrupted": "继续上次中断的工作",
+    "continueInterruptedFailed": "无法继续上次中断的工作，请重试。",
     "processingCapsule": "正在处理",
     "cancelShortcut": "取消",
     "clear": "清空",
@@ -678,7 +681,6 @@
         "sessionUnavailable": "远程任务信息不完整。请重新打开任务，或新建一个任务。",
         "compactWhileRunning": "请等待当前远程任务完成后再压缩上下文。",
         "compactRejected": "目标设备未能开始压缩，请稍后重试。",
-        "imagesWhileRunning": "图片会随下一轮消息发送。请等待当前远程任务完成后再试。",
         "sessionNotReady": "远程任务仍在准备中，请稍后再发送。",
         "submissionUnconfirmed": "暂时无法确认目标是否已接收任务。请稍后检查任务状态。"
       }
@@ -722,9 +724,14 @@
       "noSession": "请先打开或新建会话，再修改其权限模式。",
       "turnScope": "仅下一条消息",
       "currentTurnOverride": "权限：{{mode}}（仅下一条消息）",
+      "activeTurnScope": "当前轮",
+      "currentActiveTurnOverride": "权限：{{mode}}（仅当前轮）",
       "nextTurnOnly": "仅下一条消息使用「{{mode}}」",
       "nextTurnOnlyShort": "仅一次",
+      "activeTurnOnly": "当前轮后续使用「{{mode}}」",
+      "activeTurnOnlyShort": "当前轮",
       "fullAccessWarningMessageNextTurn": "完全访问会默认放行工具调用，不再逐次确认。该设置仅作用于下一条消息，项目规则与强制规则仍然生效。",
+      "fullAccessWarningMessageActiveTurn": "完全访问会默认放行工具调用，不再逐次确认。该设置从当前轮的后续模型轮次生效，项目规则与强制规则仍然生效。",
       "openDefaultSettings": "打开权限设置"
     },
     "addModeTooltip": "附加 Plan 或 Debug",
@@ -882,6 +889,8 @@
   "fileMention": {
     "searchResults": "搜索结果",
     "loading": "加载中...",
+    "browseUnavailable": "无法加载工作区文件，请检查连接后重试。",
+    "searchUnavailable": "无法搜索工作区，请检查连接后重试。",
     "noMatchingFiles": "没有找到匹配的文件",
     "emptyDirectory": "空目录",
     "rootDirectory": "根目录",
@@ -1326,9 +1335,6 @@
       "failed": "命令失败"
     }
   },
-  "stickyTaskIndicator": {
-    "tooltip": "跳转到当前任务"
-  },
   "sessionFilesBadge": {
     "files": "文件",
     "filesSummaryCount": "{{count}} 个文件",
@@ -1646,6 +1652,20 @@
       "commandInterrupted": "命令已被中断",
       "executionFailed": "命令执行失败"
     },
+    "runCode": {
+      "title": "运行代码",
+      "programLabel": "程序",
+      "outputLabel": "输出",
+      "writing": "正在编写程序…",
+      "running": "正在运行程序…",
+      "completed": "程序已结束",
+      "failed": "程序执行失败",
+      "cancelled": "程序已取消",
+      "rejected": "程序已拒绝",
+      "copyCode": "复制代码",
+      "codeCopied": "代码已复制",
+      "copyCodeFailed": "复制代码失败"
+    },
     "approval": {
       "waiting": "等待确认",
       "confirm": "允许",
@@ -2388,6 +2408,9 @@
     "fastModel": "Fast 模型",
     "fastMode": "Fast 模式",
     "fastModeDescription": "1.5 倍速度，消耗更多额度",
+    "acpMode": "模式",
+    "acpModeLocked": "会话已经开始，模式不能再改。",
+    "acpModeFailed": "切换模式失败",
     "switchFailed": "切换模型失败",
     "modelNotConfigured": "未配置",
     "contextUsage": {
@@ -2515,7 +2538,6 @@
     },
     "errors": {
       "emptyContent": "消息内容不能为空",
-      "richContentUnsupported": "包含附件或结构化信息的消息需要等待当前对话完成后发送",
       "sendNowFailed": "立即发送失败，请稍后重试"
     }
   },
diff --git a/src/web-ui/src/locales/zh-CN/scenes/todos.json b/src/web-ui/src/locales/zh-CN/scenes/todos.json
new file mode 100644
index 0000000000..8572221daf
--- /dev/null
+++ b/src/web-ui/src/locales/zh-CN/scenes/todos.json
@@ -0,0 +1,115 @@
+{
+  "title": "待办事项",
+  "header": {
+    "summary": "共 {{total}} 项 · {{dueSoon}} 项将在 24 小时内执行"
+  },
+  "actions": {
+    "newTodo": "新建待办",
+    "refresh": "刷新",
+    "edit": "编辑待办",
+    "delete": "删除待办",
+    "toggleEnabled": "切换启用状态"
+  },
+  "list": {
+    "title": "24 小时内",
+    "hint": "一天内将要执行的任务，按时间先后排列。",
+    "empty": "未来 24 小时内没有待执行的任务。"
+  },
+  "calendar": {
+    "title": "更晚",
+    "hint": "全部计划执行时间，含 24 小时内的任务。",
+    "previousMonth": "上个月",
+    "nextMonth": "下个月",
+    "today": "今天",
+    "dayDetailTitle": "选中日期",
+    "dayEmpty": "这一天没有安排任务。",
+    "clearDay": "清除选择",
+    "dayCount": "已安排 {{total}} 项",
+    "moreCount": "还有 {{total}} 项"
+  },
+  "badges": {
+    "nextRun": "下次执行",
+    "overdue": "已逾期"
+  },
+  "relative": {
+    "now": "即将执行",
+    "overdue": "已逾期",
+    "inMinutes": "{{value}} 分钟后",
+    "inHours": "{{value}} 小时后",
+    "inOneDay": "1 天后",
+    "inDays": "{{value}} 天后"
+  },
+  "schedule": {
+    "once": "单次：{{at}}",
+    "cron": "Cron：{{expr}}",
+    "cronWithTz": "Cron：{{expr}} · {{tz}}",
+    "kinds": {
+      "at": "单次",
+      "every": "间隔",
+      "cron": "Cron"
+    },
+    "everyUnit": {
+      "minute": "每 {{value}} 分钟",
+      "hour": "每 {{value}} 小时",
+      "day": "每 {{value}} 天"
+    },
+    "intervalUnits": {
+      "minute": "分钟",
+      "hour": "小时",
+      "day": "天"
+    }
+  },
+  "target": {
+    "existingSession": "已有会话",
+    "newSession": "新建 {{agentType}} 会话"
+  },
+  "inactive": {
+    "disabled": "已暂停",
+    "invalid": "计划无效",
+    "title": "没有后续执行（{{total}}）"
+  },
+  "editor": {
+    "createTitle": "新建待办",
+    "editTitle": "编辑待办",
+    "noWorkspace": "请先打开一个工作区：定时执行需要有运行的位置。",
+    "fields": {
+      "name": "名称",
+      "agentType": "Agent 类型",
+      "scheduleKind": "计划类型",
+      "at": "执行时间",
+      "anchor": "起算时间（可选）",
+      "cronExpr": "Cron 表达式",
+      "timezone": "时区（可选）",
+      "enabled": "启用",
+      "prompt": "提示词",
+      "runsIn": "运行位置",
+      "every": "间隔"
+    },
+    "placeholders": {
+      "name": "例如：每日站会总结",
+      "workspace": "选择工作区",
+      "agentType": "例如：agentic 或 Cowork",
+      "anchor": "留空则以创建时间为准",
+      "timezone": "例如：Asia/Shanghai",
+      "prompt": "到点时希望 Agent 做什么？"
+    },
+    "hints": {
+      "cronExpr": "字段依次为：分 时 日 月 周。星期取值 1-7，其中 1 表示周日，因此 0 8 * * 2 表示每周一 08:00。",
+      "boundSession": "该待办绑定了已有会话，保存后仍在该会话中执行。"
+    },
+    "actions": {
+      "create": "创建待办",
+      "save": "保存修改"
+    }
+  },
+  "deleteDialog": {
+    "title": "确定删除「{{name}}」？"
+  },
+  "messages": {
+    "loadFailed": "加载待办失败：{{error}}",
+    "saveFailed": "保存待办失败：{{error}}",
+    "deleteFailed": "删除待办失败：{{error}}",
+    "updateFailed": "更新待办失败：{{error}}",
+    "workspaceRequired": "请先为该待办选择一个工作区。"
+  }
+}
diff --git a/src/web-ui/src/locales/zh-CN/settings.json b/src/web-ui/src/locales/zh-CN/settings.json
index fbf3396cc6..3e6e54c748 100644
--- a/src/web-ui/src/locales/zh-CN/settings.json
+++ b/src/web-ui/src/locales/zh-CN/settings.json
@@ -42,7 +42,7 @@
       "models": "AI 模型、API 密钥、供应商、代理与会话标题。",
       "worktrees": "隔离 Git Worktree 与并行会话的默认设置。",
       "sessionPersonalization": "Agent 伙伴。",
-      "sessionPermissions": "加速工作区搜索、工具确认与超时、Computer use、浏览器与调试。",
+      "sessionPermissions": "工具权限、运行方式以及桌面和浏览器控制。",
       "quickActions": "代码完成后的一键 AI 动作，支持内置和自定义指令。",
       "voiceInput": "本地麦克风输入与语音转文字模型。",
       "review": "Review 策略、覆盖深度、容量、成本和耗时控制。",
diff --git a/src/web-ui/src/locales/zh-CN/settings/agentic-tools.json b/src/web-ui/src/locales/zh-CN/settings/agentic-tools.json
index 92d67bebb6..28d7d289b2 100644
--- a/src/web-ui/src/locales/zh-CN/settings/agentic-tools.json
+++ b/src/web-ui/src/locales/zh-CN/settings/agentic-tools.json
@@ -14,22 +14,22 @@
   "config": {
     "autoExecute": "自动执行",
     "autoExecuteDesc": "跳过工具执行前的用户确认步骤。",
-    "subagentMaxConcurrency": "子智能体并发上限",
-    "subagentMaxConcurrencyDesc": "同一时间允许并行运行的子智能体数量。",
+    "subagentMaxConcurrency": "同时运行任务数",
+    "subagentMaxConcurrencyDesc": "可同时运行的任务数量。",
     "confirmTimeout": "确认超时",
     "confirmTimeoutDesc": "等待用户确认工具调用的最长时间（秒）。",
     "confirmTimeoutHint": "设置为 0 可关闭确认超时。",
-    "executionTimeout": "执行超时",
-    "executionTimeoutDesc": "工具执行的最长时间（秒）。",
-    "executionTimeoutHint": "设置为 0 可关闭执行超时。子智能体和命令执行工具有各自的执行限制，不受此项约束。",
+    "executionTimeout": "工具超时",
+    "executionTimeoutDesc": "单次工具操作的最长时间。设置为 0 表示不限制。",
+    "executionTimeoutHint": "设置为 0 表示不限制。",
     "subagentBatchPolicy": {
-      "label": "子智能体批量调度",
-      "desc": "选择同一模型回复中多个子智能体启动请求的调度方式。",
-      "tooltipLabel": "子智能体批量调度说明",
-      "safeOnly": "仅安全并发",
-      "safeOnlyDesc": "只并发运行目标标记为只读的子智能体。",
-      "forceParallel": "强制并行",
-      "forceParallelDesc": "并行运行同一回复中的多个子智能体启动请求，同时仍遵守子智能体容量上限。"
+      "label": "任务并行方式",
+      "desc": "选择多个任务同时开始时的运行方式。",
+      "tooltipLabel": "任务并行方式说明",
+      "safeOnly": "安全并行",
+      "safeOnlyDesc": "只同时运行不会修改内容的任务。",
+      "forceParallel": "尽量并行",
+      "forceParallelDesc": "尽可能同时运行多个任务。"
     },
     "seconds": "秒"
   },
diff --git a/src/web-ui/src/locales/zh-CN/settings/ai-features.json b/src/web-ui/src/locales/zh-CN/settings/ai-features.json
index 65f9b76974..a48189cca0 100644
--- a/src/web-ui/src/locales/zh-CN/settings/ai-features.json
+++ b/src/web-ui/src/locales/zh-CN/settings/ai-features.json
@@ -42,10 +42,6 @@
     "git-func-agent": {
       "displayName": "Git 功能",
       "description": "提交信息、代码审核"
-    },
-    "startchat-func-agent": {
-      "displayName": "会话启动",
-      "description": "工作状态分析、欢迎信息"
     }
   },
   "loading": {
diff --git a/src/web-ui/src/locales/zh-CN/settings/ai-model.json b/src/web-ui/src/locales/zh-CN/settings/ai-model.json
index b1f092bf71..a64ec0becf 100644
--- a/src/web-ui/src/locales/zh-CN/settings/ai-model.json
+++ b/src/web-ui/src/locales/zh-CN/settings/ai-model.json
@@ -30,6 +30,7 @@
     "loadFailed": "加载会话标题配置失败",
     "model": {
       "label": "会话标题生成模型",
+      "inherit": "当前会话模型",
       "primary": "主力模型",
       "fast": "快速模型"
     },
@@ -341,8 +342,14 @@
       "modelsDev": "指定 models.dev",
       "disabled": "仅自定义"
     },
-    "catalogProvider": "models.dev 供应商",
-    "catalogModel": "models.dev 模型",
+    "catalogProvider": "供应商",
+    "catalogModel": "模型",
+    "catalogSearch": "快速查找",
+    "catalogSearchPlaceholder": "输入供应商或模型关键词",
+    "catalogSearchHint": "选择结果后自动填充下方供应商和模型。",
+    "catalogSearchResults": "models.dev 模型搜索结果",
+    "catalogSearchEmpty": "没有匹配的 models.dev 思考模型",
+    "catalogSearchLimit": "结果较多，请继续输入以缩小范围",
     "catalogUnbound": "未绑定",
     "catalogProviderCustomValueHint": "使用自定义供应商 ID",
     "catalogModelCustomValueHint": "使用自定义模型 ID",
@@ -351,12 +358,14 @@
     "auto": "自动（模型默认值）",
     "autoShort": "自动",
     "generatedTitle": "自动生成的预设",
+    "unavailableTitle": "部分 models.dev 预设不可用",
+    "unavailableDescription": "当前 API 格式“{{format}}”无法可靠应用以下预设：{{presets}}。请参考服务提供商的官方文档，并在自定义预设中使用“请求体补丁”配置所需字段。",
+    "unknownRequestFormat": "未知",
     "customTitle": "自定义预设",
-    "customTooltip": "自定义预设会把一组思考参数保存为聊天输入框中的可选项。请为每个预设填写唯一 ID 和显示名称，再按模型 API 支持情况添加推理强度、思考开关或思考预算；仅在需要补充供应商专用参数时添加请求 JSON patch。",
+    "customTooltip": "自定义预设会把一组思考参数保存为聊天输入框中的可选项。请为每个预设填写名称，再按模型 API 支持情况添加推理强度、思考开关或思考预算；仅在需要补充供应商专用参数时添加请求体补丁。",
     "add": "添加预设",
     "addAction": "添加操作",
     "empty": "暂无自定义预设",
-    "id": "预设 ID",
     "label": "名称",
     "labelPlaceholder": "显示名称",
     "default": "默认",
@@ -370,14 +379,14 @@
     "effortCustomWarning": "这是自定义值，请确认模型 API 支持该值。",
     "settingToggle": "开启 / 关闭",
     "settingBudget": "Token 预算",
-    "settingPatch": "请求 JSON Patch",
+    "settingPatch": "请求体补丁",
     "actionSummaryEffort": "推理强度：{{value}}",
     "actionSummaryEnabled": "开启思考",
     "actionSummaryDisabled": "关闭思考",
     "actionSummaryBudget": "Token 预算：{{value}}",
-    "actionSummaryPatches": "{{count}} 个请求 Patch",
+    "actionSummaryPatches": "{{count}} 个请求体补丁",
     "noActions": "未配置操作",
-    "invalidJson": "请求 Patch 需要 JSON 对象。",
+    "invalidJson": "请求体补丁需要 JSON 对象。",
     "summary": "{{source}} · 默认：{{default}}",
     "summaryWithCustom": "{{source}} · 默认：{{default}} · {{count}} 个自定义预设",
     "apply": "应用",
diff --git a/src/web-ui/src/locales/zh-CN/settings/default-model.json b/src/web-ui/src/locales/zh-CN/settings/default-model.json
index 508ab8de71..757394f408 100644
--- a/src/web-ui/src/locales/zh-CN/settings/default-model.json
+++ b/src/web-ui/src/locales/zh-CN/settings/default-model.json
@@ -60,10 +60,6 @@
         "displayName": "Git 功能",
         "description": "提交信息、代码审核"
       },
-      "startchat-func-agent": {
-        "displayName": "会话启动",
-        "description": "工作状态分析、欢迎信息"
-      },
       "arc-func-agent": {
         "displayName": "架构分析",
         "description": "依赖图、Mermaid 图表"
diff --git a/src/web-ui/src/locales/zh-CN/settings/external-sources.json b/src/web-ui/src/locales/zh-CN/settings/external-sources.json
index 8a120a879e..d7bc1ddfb6 100644
--- a/src/web-ui/src/locales/zh-CN/settings/external-sources.json
+++ b/src/web-ui/src/locales/zh-CN/settings/external-sources.json
@@ -121,6 +121,13 @@
     "modelBindingUpdated": "已保存 Agent 模型绑定并刷新受影响的 Agent。",
     "mcpUpdated": "已保存 MCP 服务器选择并刷新状态。"
   },
+  "bulkActions": {
+    "enablePending": "启用全部待确认项（{{count}}）",
+    "disableAll": "全部停用",
+    "enableRisk": "仅批准当前显示的 {{count}} 项；如果发现结果发生变化，BitFun 会要求重新确认。",
+    "enabled": "已启用选中的待确认项。",
+    "disabled": "已停用选中的项目。"
+  },
   "recoveryActions": {
     "refresh": "刷新状态",
     "retry": "重试",
@@ -238,7 +245,8 @@
       "unreadableSource": "BitFun 无法读取来源中的部分内容。请检查文件访问权限后刷新。",
       "notSupported": "BitFun 暂不支持此类外部内容，因此没有加载或运行它。",
       "checkFailed": "BitFun 未能检查一个来源，其他来源仍可使用。请刷新重试。",
-      "sourceIssue": "BitFun 在一个来源中发现问题，受影响的内容未启用。请检查来源配置后刷新。"
+      "runtimeUnavailable": "此来源中的一个 MCP 服务器不可用。请先停用，修复配置或认证后再启用。",
+      "sourceIssue": "BitFun 未能完成一个来源的检查；现有可用内容保持不变。你可以刷新或查看技术详情。"
     }
   },
   "sources": {
@@ -414,6 +422,7 @@
     "externalSource": "外部 AI 应用",
     "source": "来源：{{source}}",
     "sourceLocation": "配置位置：{{location}}",
+    "sourceLocationLabel": "配置位置",
     "scope": "作用范围：{{scope}}",
     "command": "命令：{{command}}",
     "url": "地址：{{url}}",
@@ -430,6 +439,27 @@
     "timeoutExecution": "执行 {{duration}}",
     "timeoutMilliseconds": "{{value}} 毫秒",
     "changePolicy": "服务器配置发生变化后，BitFun 会在再次加载前请你确认。",
+    "failureReason": "原因：{{reason}}",
+    "failureReasons": {
+      "authentication": "此 MCP 服务器需要完成身份认证。",
+      "timeout": "MCP 服务器未能在启动超时前就绪。",
+      "commandUnavailable": "无法启动配置的 MCP 命令，请检查命令或运行环境。",
+      "workingDirectoryUnavailable": "配置的 MCP 工作目录不可用。",
+      "connectionFailed": "BitFun 无法连接到此 MCP 服务器。",
+      "protocolFailed": "MCP 服务器未能完成启动握手。",
+      "nativeConfigurationUnavailable": "BitFun 无法读取当前 MCP 配置。",
+      "hostReadOnly": "当前主机只能发现 MCP 服务器，不能运行它们。",
+      "configurationChanged": "MCP 配置在启用前发生了变化，请刷新后重新确认。",
+      "configurationInvalid": "当前 MCP 配置无法用于 BitFun 运行时。",
+      "hostUnavailable": "当前主机没有可用的 MCP 运行时。",
+      "installFailed": "BitFun 无法将此 MCP 服务器注册到运行时。",
+      "preparationFailed": "BitFun 无法准备此 MCP 配置以供启用。",
+      "serverMissing": "此 MCP 服务器已不在运行时中。",
+      "runtimeFailed": "MCP 服务器运行失败或意外停止。",
+      "stopped": "MCP 服务器当前未运行。",
+      "statusUnavailable": "BitFun 无法读取 MCP 服务器的当前状态。",
+      "other": "MCP 服务器启动失败，请检查来源配置和 BitFun 日志。"
+    },
     "runtimeUnavailableGuidance": "请先停用此服务器，修复来源配置或认证后再启用，通常无需重启 BitFun。",
     "unsupportedGuidance": "请在来源应用中修改此配置，然后刷新。",
     "enable": "启用服务器",
diff --git a/src/web-ui/src/locales/zh-CN/settings/session-config.json b/src/web-ui/src/locales/zh-CN/settings/session-config.json
index 58325fe841..3c31b196d8 100644
--- a/src/web-ui/src/locales/zh-CN/settings/session-config.json
+++ b/src/web-ui/src/locales/zh-CN/settings/session-config.json
@@ -5,37 +5,37 @@
   },
   "permissionsPage": {
     "title": "权限管理",
-    "subtitle": "加速工作区搜索、工具执行、工具定义加载、浏览器控制与调试模式"
+    "subtitle": "管理工具权限、运行方式以及桌面和浏览器控制。"
   },
   "features": {
     "workspaceSearch": {
       "title": "加速工作区搜索",
-      "subtitle": "为本地工作区启用基于 flashgrep 的索引搜索。关闭后 BitFun 会回退到原有搜索。",
+      "subtitle": "提升大型工作区中的文件搜索速度。关闭后仍可正常搜索。",
       "enable": "启用加速工作区搜索"
     }
   },
   "toolExecution": {
-    "sectionTitle": "工具执行行为",
-    "sectionDescription": "本会话中 AI 调用工具时的确认与超时策略。"
+    "sectionTitle": "工具运行",
+    "sectionDescription": "设置工具超时和并行任务数量。"
   },
   "permissionPolicy": {
     "sectionTitle": "工具权限",
-    "sectionDescription": "选择会话的默认工具访问策略，以及权限请求的处理方式。",
+    "sectionDescription": "设置 BitFun 何时需要你确认工具操作。",
     "mode": "默认权限模式",
     "ask": "需要确认",
-    "askDescription": "外部访问，修改文件和执行命令需要确认。",
+    "askDescription": "修改文件、执行命令或访问外部服务时先确认。",
     "fullAccess": "完全访问",
-    "fullAccessDescription": "默认允许工具执行，无需确认。",
+    "fullAccessDescription": "不再逐次确认工具操作。",
     "fullAccessWarningTitle": "启用完全访问？",
     "fullAccessWarningMessage": "完全访问会默认允许工具执行，不再逐次确认。",
     "fullAccessConfirm": "启用完全访问",
     "cancel": "取消",
     "autoApprove": "自动批准",
-    "autoApproveDescription": "自动批准需要确认的请求。",
+    "autoApproveDescription": "自动允许原本需要确认的操作。",
     "showInChatInput": "显示权限模式选择器",
-    "showInChatInputDescription": "在输入框下方显示选择器，在那里切换的模式仅作用于当前会话。隐藏它不会改变任何会话的权限模式。",
+    "showInChatInputDescription": "在输入框下方显示权限模式，可随时为当前会话切换。",
     "globalRules": "全局规则",
-    "globalRulesDescription": "定义用户级规则；它们在所选模式之后、项目和 Agent 规则之前应用。",
+    "globalRulesDescription": "为所有工作区设置通用的允许、询问或拒绝规则。",
     "manageGlobalRules": "管理规则",
     "globalRulesDialogTitle": "全局工具权限规则",
     "globalRulesDialogDescription": "这些用户级规则会应用于所有工作区。后续项目和 Agent 规则可以覆盖它们；产品强制限制始终优先。",
@@ -52,7 +52,7 @@
     "discardGlobalRules": "放弃更改",
     "saveGlobalRules": "保存规则",
     "globalRulesEffects": { "allow": "允许", "ask": "询问", "deny": "拒绝" },
-    "modeDescription": "作用于尚未单独设置的会话。每个会话都可以在输入框中覆盖该默认值。"
+    "modeDescription": "作为新会话的默认设置，可在输入框中临时切换。"
   },
   "projectPermissions": {
     "description": "“始终允许”会保存为当前项目的记忆授权；静态项目规则会在工具执行前直接应用。",
@@ -91,54 +91,69 @@
     "effects": { "allow": "允许", "ask": "询问", "deny": "拒绝" }
   },
   "deferredToolLoading": {
-    "sectionTitle": "工具延迟加载",
-    "sectionDescription": "仅在需要时加载部分工具的完整 Schema（包括部分内置工具及所有 MCP 工具）。",
-    "warning": "当前会在每次请求中发送启用工具的完整 Schema；如果配置了大量 MCP 工具会占用较多 Token。"
+    "sectionTitle": "按需加载工具",
+    "sectionDescription": "仅在需要时加载工具详情。",
+    "warning": "关闭后会加载所有工具详情，可能增加模型用量。"
   },
   "computerUse": {
-    "sectionTitle": "Computer use（桌面自动化）",
-    "sectionDescription": "在 BitFun 桌面端允许助理截取屏幕并控制键鼠；需多模态模型理解画面。",
-    "enable": "启用 Computer use",
-    "enableDesc": "关闭时，任何会话模式都不会启用 ComputerUse 工具；浏览器控制（ControlHub）目前不受此开关约束。",
+    "sectionTitle": "桌面控制",
+    "sectionDescription": "允许 BitFun 查看屏幕并操作鼠标和键盘。",
+    "enable": "允许桌面控制",
+    "enableDesc": "关闭后，BitFun 将不再操作桌面应用。浏览器控制可单独设置。",
     "accessibility": "辅助功能",
-    "accessibilityDesc": "macOS 上用于让 BitFun 读取屏幕上的界面元素并向其他应用发送鼠标/键盘操作；Windows 无需单独授权，Linux 需要 X11 会话。",
+    "accessibilityDesc": "允许 BitFun 识别并操作其他应用中的界面。",
     "screenCapture": "屏幕录制",
-    "screenCaptureDesc": "用于让 BitFun 截取屏幕画面，使助理能看到当前正在操作的内容。",
+    "screenCaptureDesc": "允许 BitFun 查看屏幕内容。",
     "granted": "已授权",
     "notGranted": "未授权",
     "openSettings": "系统设置",
     "refreshStatus": "刷新状态",
-    "desktopOnly": "Computer use 仅在 BitFun 桌面应用中可用。",
-    "platformNote": "说明"
+    "desktopOnly": "桌面控制仅在 BitFun 桌面应用中可用。",
+    "platformNote": "说明",
+    "platformNotes": {
+      "macos": "当前构建仍需在系统设置中授予辅助功能权限。",
+      "windows": "部分受保护的窗口或远程桌面环境可能无法控制。",
+      "linux": "当前桌面环境可能不支持完整的键鼠控制或屏幕查看。",
+      "generic": "当前系统无法使用完整的桌面控制功能。"
+    }
   },
   "browserControl": {
     "sectionTitle": "浏览器控制",
-    "sectionDescription": "选择浏览器并启动 CDP 控制。",
+    "sectionDescription": "选择 BitFun 使用的浏览器和连接方式。",
     "desktopOnly": "浏览器控制仅在 BitFun 桌面应用中可用。",
     "preferredBrowser": "浏览器",
-    "preferredBrowserDesc": "选择要由 BitFun 通过 CDP 控制的浏览器；默认表示跟随系统默认浏览器。",
+    "preferredBrowserDesc": "默认使用系统浏览器。",
     "notInstalled": "未安装",
     "status": "连接状态",
     "statusDesc": "",
     "notConnected": "未连接",
+    "readyNotConnected": "已就绪，使用时自动连接",
     "refreshStatus": "刷新状态",
     "connect": "连接浏览器",
+    "defaultCdp": "使用现有浏览器",
+    "defaultCdpDesc": "使用已打开的 Chrome 或 Edge，并保留标签页和登录状态。连接时仍需在浏览器中确认。",
+    "autoConnectOnStartup": "启动时自动连接",
+    "autoConnectOnStartupDesc": "BitFun 启动后自动连接已打开的浏览器。浏览器重启后可能需要重新确认。",
+    "defaultCdpEnabled": "已启用",
+    "defaultCdpDisabled": "未启用",
+    "enableDefaultCdp": "启用并连接",
+    "defaultCdpEnablePrompt": "已打开 {{browser}} 的 Remote debugging 设置页（该页面仅有英文）。请勾选 “Allow remote debugging for this browser instance”；BitFun 检测到后会自动继续连接，再请在浏览器中选择“允许”。",
+    "defaultCdpConnectPrompt": "正在连接你当前的 {{browser}}；请在浏览器弹窗中选择“允许”。",
     "connectSuccess": "已连接 {{browser}}",
     "connectFailed": "连接浏览器失败",
-    "restartSuccess": "已重启 {{browser}} 并启用调试模式",
-    "restartFailed": "重启浏览器并启用调试失败",
+    "userProfileSetupRequired": "{{browser}} 已打开 Remote debugging 设置页，但等待期间未检测到开关生效。请勾选 “Allow remote debugging for this browser instance” 后再次点击“启用并连接”；当前标签页和登录状态会被保留。",
+    "userProfileSetupManual": "请在 {{browser}} 中打开 {{url}}，勾选 “Allow remote debugging for this browser instance”，然后再次点击“启用并连接”；当前标签页和登录状态会被保留。",
+    "userProfileConnectionFailed": "{{browser}} 未允许连接，或连接请求已超时。请确认浏览器正在运行且已启用远程调试，然后重新连接并在浏览器中选择“允许”。",
+    "restartSuccess": "已重新启动 {{browser}} 并开启浏览器控制",
+    "restartFailed": "无法重新启动并连接 {{browser}}",
     "restartModal": {
-      "title": "启用浏览器调试模式",
-      "description": "检测到 {{browser}} 已在运行，当前实例未启用调试端口。要让 BitFun 控制浏览器，需要先重启浏览器并以调试模式启动。",
+      "title": "重新启动浏览器",
+      "description": "BitFun 需要重新启动当前的 {{browser}} 才能连接。",
       "warning": "此操作会关闭当前浏览器窗口。",
       "cancel": "取消",
-      "confirm": "重启并启用调试",
-      "restarting": "正在重启..."
+      "confirm": "重新启动并连接",
+      "restarting": "正在重新启动..."
     },
-    "createLauncher": "创建启动器",
-    "createLauncherSuccess": "启动器已创建：{{path}}",
-    "createLauncherFailed": "创建启动器失败",
-    "createLauncherDesc": "创建带调试端口的浏览器快捷方式。",
     "tabs": "个标签页"
   },
   "common": {
diff --git a/src/web-ui/src/locales/zh-CN/tools.json b/src/web-ui/src/locales/zh-CN/tools.json
index a4355971c5..f55c19fc85 100644
--- a/src/web-ui/src/locales/zh-CN/tools.json
+++ b/src/web-ui/src/locales/zh-CN/tools.json
@@ -80,7 +80,7 @@
       "copiedMarkdown": "已复制 Markdown",
       "viewModeLabel": "Markdown 与预览模式",
       "notice": {
-        "sourcePreviewFallback": "该文档包含无法在可视化模式中安全编辑的 HTML 片段。请在源码模式中编辑，或切换到预览查看效果。"
+        "sourcePreviewFallback": "该文档包含无法在可视化模式中安全编辑的语法。请在源码模式中编辑，或切换到预览模式查看。"
       }
     },
     "planViewer": {
@@ -124,6 +124,9 @@
       "rawHtml": {
         "inlineLabel": "HTML"
       },
+      "frontmatter": {
+        "label": "YAML Frontmatter"
+      },
       "details": {
         "summaryPlaceholder": "摘要"
       },
diff --git a/src/web-ui/src/locales/zh-TW/common.json b/src/web-ui/src/locales/zh-TW/common.json
index d1ef03a69d..fb3887cd5d 100644
--- a/src/web-ui/src/locales/zh-TW/common.json
+++ b/src/web-ui/src/locales/zh-TW/common.json
@@ -224,6 +224,7 @@
       "sessions": "會話",
       "project": "目錄",
       "persona": "助理",
+      "todos": "待辦事項",
       "agents": "專業智能體",
       "skills": "技能",
       "tools": "工具",
@@ -234,6 +235,7 @@
     },
     "tooltips": {
       "persona": "助理 — 建立與管理所有助理實例",
+      "todos": "待辦 — 匯總所有定時任務，列表與日曆兩層檢視",
       "agents": "它能調用哪些 Agent",
       "skills": "它懂什麼專項知識 — 技能知識檔案",
       "tools": "它能用什麼工具 — 內置工具與 MCP 服務",
@@ -429,7 +431,7 @@
         "enabledHint": "啟用該任務",
         "scheduleKind": "調度方式",
         "at": "執行時間",
-        "everyMs": "間隔（分鐘）",
+        "everyMs": "間隔",
         "anchorMs": "錨點時間（可選）",
         "cronExpr": "Cron 表達式",
         "timezone": "時區（可選）",
@@ -454,9 +456,13 @@
         "cron": "Cron"
       },
       "scheduleSummary": {
-        "every": "每 {{everyMinutes}} 分鐘",
         "cron": "Cron: {{expr}}",
-        "cronWithTz": "Cron: {{expr}} · {{tz}}"
+        "cronWithTz": "Cron: {{expr}} · {{tz}}",
+        "everyUnit": {
+          "minute": "每 {{value}} 分鐘",
+          "hour": "每 {{value}} 小時",
+          "day": "每 {{value}} 天"
+        }
       },
       "targets": {
         "session": "會話",
@@ -503,6 +509,11 @@
         "promptRequired": "請輸入任務內容",
         "workspaceRequired": "請輸入工作區路徑",
         "sessionRequired": "請選擇會話"
+      },
+      "intervalUnits": {
+        "minute": "分鐘",
+        "hour": "小時",
+        "day": "天"
       }
     },
     "workspaces": {
@@ -767,6 +778,18 @@
     "peerRemoteLabel": "{{name}}",
     "peerRemoteBadgeTitle": "遠端裝置：{{name}}",
     "disconnectPeer": "中斷連線",
+    "deviceSwitcher": {
+      "title": "裝置",
+      "open": "切換裝置",
+      "running": "$t(shared:statuses.running)",
+      "noDevices": "此帳號目前沒有其他已登入的裝置。",
+      "hint": "切換只會改變此視窗顯示的裝置，各裝置的工作都會繼續執行。",
+      "othersRunning": "其他裝置仍在執行工作（{{count}}）",
+      "switched": "已切換至 {{name}}",
+      "switchedLocal": "已切換回本機",
+      "disconnected": "已中斷 {{name}} 的連線",
+      "disconnectHint": "結束對該裝置的控制，並取消它正在為你執行的工作"
+    },
     "peerAutoExitOffline": "遠端裝置「{{name}}」已離線 — 已中斷連線",
     "peerAutoExitRpc": "與遠端裝置「{{name}}」連線遺失 — 已中斷連線",
     "syncInProgressHint": "雲端同步仍在進行，請稍後再開啟遠端裝置。",
@@ -1346,6 +1369,7 @@
     "browser": "瀏覽器",
     "insights": "洞察",
     "assistant": "助理",
+    "todos": "待辦事項",
     "shell": "Shell",
     "panelView": "面板視圖"
   },
@@ -1711,5 +1735,14 @@
   },
   "collapse": "收合",
   "expand": "展開",
-  "retry": "重試"
+  "retry": "重試",
+  "dateTimeField": {
+    "label": "日期與時間",
+    "openPicker": "開啟日期選擇器",
+    "pickerLabel": "選擇日期",
+    "previousMonth": "上個月",
+    "nextMonth": "下個月",
+    "now": "此刻",
+    "close": "關閉"
+  }
 }
diff --git a/src/web-ui/src/locales/zh-TW/flow-chat.json b/src/web-ui/src/locales/zh-TW/flow-chat.json
index b21f048167..aa5ccc2a7c 100644
--- a/src/web-ui/src/locales/zh-TW/flow-chat.json
+++ b/src/web-ui/src/locales/zh-TW/flow-chat.json
@@ -93,6 +93,7 @@
     "failedDescription": "可以重新載入已儲存的會話內容；若會話來自其他裝置，請先檢查帳號登入與網路連線。",
     "preparingOlderHistory": "正在準備更早的歷史記錄...",
     "olderHistoryNotReady": "更早的歷史記錄暫未準備好。",
+    "newerHistoryNotReady": "更新的歷史記錄暫未準備好。",
     "remoteSessionMissing": "在後端找不到該會話資料。若剛重新連接過 SSH 遠端工作區，請關閉並重新開啟該遠端項目，或新增會話後再試。",
     "retry": "重試"
   },
@@ -174,7 +175,6 @@
       "tokens": "{{value}} Tokens"
     },
     "loading": {
-      "markdown": "正在產生用量報告...",
       "title": "正在產生用量報告",
       "description": "正在讀取本機工作階段記錄，並整理隱私安全的統計摘要。",
       "steps": {
@@ -280,7 +280,9 @@
     },
     "slowestLabels": {
       "modelCall": "第 {{turn}} 回合模型呼叫",
-      "modelCallUnknown": "模型呼叫"
+      "modelCallUnknown": "模型呼叫",
+      "turn": "第 {{turn}} 回合",
+      "turnUnknown": "回合"
     },
     "slowest": {
       "details": {
@@ -453,6 +455,8 @@
     "restoreMain": "恢復主視窗",
     "inUseTitle": "會話已在其他執行個體中開啟",
     "inUseMessage": "此會話已在另一個 BitFun 執行個體中開啟。請先在該處關閉，然後重試。",
+    "surfaceSwitchDroppedTitle": "訊息未送出",
+    "surfaceSwitchDropped": "訊息尚未送出時裝置已切換，且該會話的佇列已滿。請重新傳送。",
     "retry": "重試"
   },
   "scroll": {
@@ -479,23 +483,20 @@
     "clickToCollapse": "點擊收起",
     "fillToInput": "填充到輸入框",
     "cannotRollback": "無法回滾",
+    "rollbackDisabledBusy": "請等待會話閒置後再回滾。",
     "rollbackDisabledRemote": "遠端工作區未記錄檔案快照，暫不支援檔案與訊息一致回滾；不會變更任何檔案或訊息。",
     "rollbackTo": "回滾到第 {{index}} 輪之前（刪除該輪及之後）",
     "rollbackDialogTitle": "確定回滾到第 {{index}} 輪之前？",
     "rollbackDialogIntro": "將執行：",
     "rollbackDialogBulletFiles": "撤銷從該輪開始的所有檔案修改",
     "rollbackDialogBulletHistory": "刪除該輪及之後的對話記錄（不可恢復）",
-    "rollbackPanelDialogTitle": "回滾到第 {{index}} 輪之前？",
-    "rollbackPanelDialogIntro": "將執行：",
-    "rollbackPanelBulletRestore": "將檔案恢復到第 {{index}} 輪之前的狀態",
-    "rollbackPanelBulletUndo": "撤銷從該輪開始的所有檔案變更",
-    "rollbackPanelBulletHistory": "保留會話歷史（之後仍可繼續對話）",
     "rollbackSuccess": "已回滾並刪除後續對話記錄",
     "rollbackFailed": "回滾失敗",
     "saveEdit": "儲存並重跑",
     "cancelEdit": "取消",
     "editPlaceholder": "編輯你的消息...",
     "cannotEdit": "無法編輯該消息",
+    "editDisabledBusy": "請等待會話閒置後再編輯並重跑。",
     "editDisabledImages": "暫不支援編輯圖片消息",
     "editDisabledRemote": "編輯並重新執行需要完整回滾；遠端工作區未記錄檔案快照，因此暫不支援。",
     "editDisabledLocalCommand": "無法編輯本機命令消息",
@@ -534,6 +535,8 @@
     "sendShortcut": "發送 (⏎)",
     "stop": "停止",
     "stopGeneration": "停止生成 (Esc)",
+    "continueInterrupted": "繼續上次中斷的工作",
+    "continueInterruptedFailed": "無法繼續上次中斷的工作，請重試。",
     "processingCapsule": "正在處理",
     "cancelShortcut": "取消",
     "clear": "清空",
@@ -678,7 +681,6 @@
         "sessionUnavailable": "遠端任務資訊不完整。請重新開啟任務，或建立新任務。",
         "compactWhileRunning": "請等待目前遠端任務完成後再壓縮上下文。",
         "compactRejected": "目標裝置未能開始壓縮，請稍後重試。",
-        "imagesWhileRunning": "圖片會隨下一輪訊息傳送。請等待目前遠端任務完成後再試。",
         "sessionNotReady": "遠端任務仍在準備中，請稍後再傳送。",
         "submissionUnconfirmed": "暫時無法確認目標是否已收到任務。請稍後檢查任務狀態。"
       }
@@ -722,9 +724,14 @@
       "noSession": "請先開啟或新建工作階段，再變更其權限模式。",
       "turnScope": "僅下一則訊息",
       "currentTurnOverride": "權限：{{mode}}（僅下一則訊息）",
+      "activeTurnScope": "目前輪次",
+      "currentActiveTurnOverride": "權限：{{mode}}（僅目前輪次）",
       "nextTurnOnly": "僅下一則訊息使用「{{mode}}」",
       "nextTurnOnlyShort": "僅一次",
+      "activeTurnOnly": "目前輪次後續使用「{{mode}}」",
+      "activeTurnOnlyShort": "目前輪次",
       "fullAccessWarningMessageNextTurn": "完全存取會預設放行工具呼叫，不再逐次確認。此設定僅作用於下一則訊息，專案規則與強制規則仍然生效。",
+      "fullAccessWarningMessageActiveTurn": "完全存取會預設放行工具呼叫，不再逐次確認。此設定從目前輪次的後續模型輪次生效，專案規則與強制規則仍然生效。",
       "openDefaultSettings": "開啟權限設定"
     },
     "addModeTooltip": "附加 Plan 或 Debug",
@@ -882,6 +889,8 @@
   "fileMention": {
     "searchResults": "搜尋結果",
     "loading": "載入中...",
+    "browseUnavailable": "無法載入工作區檔案，請檢查連線後重試。",
+    "searchUnavailable": "無法搜尋工作區，請檢查連線後重試。",
     "noMatchingFiles": "沒有找到匹配的檔案",
     "emptyDirectory": "空目錄",
     "rootDirectory": "根目錄",
@@ -1326,9 +1335,6 @@
       "failed": "命令失敗"
     }
   },
-  "stickyTaskIndicator": {
-    "tooltip": "跳轉到目前任務"
-  },
   "sessionFilesBadge": {
     "files": "檔案",
     "filesSummaryCount": "{{count}} 個檔案",
@@ -1646,6 +1652,20 @@
       "commandInterrupted": "命令已被中斷",
       "executionFailed": "命令執行失敗"
     },
+    "runCode": {
+      "title": "執行程式碼",
+      "programLabel": "程式",
+      "outputLabel": "輸出",
+      "writing": "正在撰寫程式…",
+      "running": "正在執行程式…",
+      "completed": "程式已結束",
+      "failed": "程式執行失敗",
+      "cancelled": "程式已取消",
+      "rejected": "程式已拒絕",
+      "copyCode": "複製程式碼",
+      "codeCopied": "程式碼已複製",
+      "copyCodeFailed": "複製程式碼失敗"
+    },
     "approval": {
       "waiting": "等待確認",
       "confirm": "允許",
@@ -2388,6 +2408,9 @@
     "fastModel": "Fast 模型",
     "fastMode": "Fast 模式",
     "fastModeDescription": "1.5 倍速度，消耗更多額度",
+    "acpMode": "模式",
+    "acpModeLocked": "對話已經開始，模式不能再改。",
+    "acpModeFailed": "切換模式失敗",
     "switchFailed": "切換模型失敗",
     "modelNotConfigured": "未設定",
     "contextUsage": {
@@ -2515,7 +2538,6 @@
     },
     "errors": {
       "emptyContent": "訊息內容不能為空",
-      "richContentUnsupported": "包含附件或結構化資訊的訊息需要等待目前對話完成後傳送",
       "sendNowFailed": "立即發送失敗，請稍後重試"
     }
   },
diff --git a/src/web-ui/src/locales/zh-TW/scenes/todos.json b/src/web-ui/src/locales/zh-TW/scenes/todos.json
new file mode 100644
index 0000000000..6955705aa4
--- /dev/null
+++ b/src/web-ui/src/locales/zh-TW/scenes/todos.json
@@ -0,0 +1,115 @@
+{
+  "title": "待辦事項",
+  "header": {
+    "summary": "共 {{total}} 項 · {{dueSoon}} 項將在 24 小時內執行"
+  },
+  "actions": {
+    "newTodo": "新增待辦",
+    "refresh": "重新整理",
+    "edit": "編輯待辦",
+    "delete": "刪除待辦",
+    "toggleEnabled": "切換啟用狀態"
+  },
+  "list": {
+    "title": "24 小時內",
+    "hint": "一天內即將執行的任務，依時間先後排列。",
+    "empty": "未來 24 小時內沒有待執行的任務。"
+  },
+  "calendar": {
+    "title": "更晚",
+    "hint": "全部排程執行時間，含 24 小時內的任務。",
+    "previousMonth": "上個月",
+    "nextMonth": "下個月",
+    "today": "今天",
+    "dayDetailTitle": "選取日期",
+    "dayEmpty": "這一天沒有安排任務。",
+    "clearDay": "清除選取",
+    "dayCount": "已安排 {{total}} 項",
+    "moreCount": "還有 {{total}} 項"
+  },
+  "badges": {
+    "nextRun": "下次執行",
+    "overdue": "已逾期"
+  },
+  "relative": {
+    "now": "即將執行",
+    "overdue": "已逾期",
+    "inMinutes": "{{value}} 分鐘後",
+    "inHours": "{{value}} 小時後",
+    "inOneDay": "1 天後",
+    "inDays": "{{value}} 天後"
+  },
+  "schedule": {
+    "once": "單次：{{at}}",
+    "cron": "Cron：{{expr}}",
+    "cronWithTz": "Cron：{{expr}} · {{tz}}",
+    "kinds": {
+      "at": "單次",
+      "every": "間隔",
+      "cron": "Cron"
+    },
+    "everyUnit": {
+      "minute": "每 {{value}} 分鐘",
+      "hour": "每 {{value}} 小時",
+      "day": "每 {{value}} 天"
+    },
+    "intervalUnits": {
+      "minute": "分鐘",
+      "hour": "小時",
+      "day": "天"
+    }
+  },
+  "target": {
+    "existingSession": "既有工作階段",
+    "newSession": "新增 {{agentType}} 工作階段"
+  },
+  "inactive": {
+    "disabled": "已暫停",
+    "invalid": "排程無效",
+    "title": "沒有後續執行（{{total}}）"
+  },
+  "editor": {
+    "createTitle": "新增待辦",
+    "editTitle": "編輯待辦",
+    "noWorkspace": "請先開啟一個工作區：定時執行需要有執行的位置。",
+    "fields": {
+      "name": "名稱",
+      "agentType": "Agent 類型",
+      "scheduleKind": "排程類型",
+      "at": "執行時間",
+      "anchor": "起算時間（選填）",
+      "cronExpr": "Cron 運算式",
+      "timezone": "時區（選填）",
+      "enabled": "啟用",
+      "prompt": "提示詞",
+      "runsIn": "執行位置",
+      "every": "間隔"
+    },
+    "placeholders": {
+      "name": "例如：每日站立會議摘要",
+      "workspace": "選擇工作區",
+      "agentType": "例如：agentic 或 Cowork",
+      "anchor": "留空則以建立時間為準",
+      "timezone": "例如：Asia/Taipei",
+      "prompt": "到點時希望 Agent 做什麼？"
+    },
+    "hints": {
+      "cronExpr": "欄位依序為：分 時 日 月 週。星期取值 1-7，其中 1 代表週日，因此 0 8 * * 2 表示每週一 08:00。",
+      "boundSession": "此待辦綁定了既有工作階段，儲存後仍在該工作階段中執行。"
+    },
+    "actions": {
+      "create": "建立待辦",
+      "save": "儲存變更"
+    }
+  },
+  "deleteDialog": {
+    "title": "確定刪除「{{name}}」？"
+  },
+  "messages": {
+    "loadFailed": "載入待辦失敗：{{error}}",
+    "saveFailed": "儲存待辦失敗：{{error}}",
+    "deleteFailed": "刪除待辦失敗：{{error}}",
+    "updateFailed": "更新待辦失敗：{{error}}",
+    "workspaceRequired": "請先為此待辦選擇一個工作區。"
+  }
+}
diff --git a/src/web-ui/src/locales/zh-TW/settings.json b/src/web-ui/src/locales/zh-TW/settings.json
index a3e49b264e..bbe33d7d52 100644
--- a/src/web-ui/src/locales/zh-TW/settings.json
+++ b/src/web-ui/src/locales/zh-TW/settings.json
@@ -42,7 +42,7 @@
       "models": "AI 模型、API 密鑰、供應商、代理與會話標題。",
       "worktrees": "隔離 Git Worktree 與平行工作階段的預設設定。",
       "sessionPersonalization": "Agent 夥伴。",
-      "sessionPermissions": "加速工作區搜尋、工具確認與逾時、Computer use、瀏覽器與偵錯。",
+      "sessionPermissions": "工具權限、執行方式，以及桌面和瀏覽器控制。",
       "review": "Review 策略、覆蓋深度、容量、成本和耗時控制。",
       "memories": "自動記憶生成、注入、整理窗口與記憶模型。",
       "mcpTools": "MCP 伺服器與工具集成。",
diff --git a/src/web-ui/src/locales/zh-TW/settings/agentic-tools.json b/src/web-ui/src/locales/zh-TW/settings/agentic-tools.json
index a0d37abf2d..4324fca1e1 100644
--- a/src/web-ui/src/locales/zh-TW/settings/agentic-tools.json
+++ b/src/web-ui/src/locales/zh-TW/settings/agentic-tools.json
@@ -14,22 +14,22 @@
   "config": {
     "autoExecute": "自動執行",
     "autoExecuteDesc": "跳過工具執行前的用戶確認步驟。",
-    "subagentMaxConcurrency": "子智能體並發上限",
-    "subagentMaxConcurrencyDesc": "同一時間允許並行執行的子智能體數量。",
+    "subagentMaxConcurrency": "同時執行任務數",
+    "subagentMaxConcurrencyDesc": "可同時執行的任務數量。",
     "confirmTimeout": "確認超時",
     "confirmTimeoutDesc": "等待用戶確認工具調用的最長時間（秒）。",
     "confirmTimeoutHint": "設為 0 可關閉確認超時。",
-    "executionTimeout": "執行超時",
-    "executionTimeoutDesc": "工具執行的最長時間（秒）。",
-    "executionTimeoutHint": "設為 0 可關閉執行超時。子智能體和命令執行工具有各自的執行限制，不受此項約束。",
+    "executionTimeout": "工具逾時",
+    "executionTimeoutDesc": "單次工具操作的最長時間。設為 0 表示不限制。",
+    "executionTimeoutHint": "設為 0 表示不限制。",
     "subagentBatchPolicy": {
-      "label": "子智能體批量調度",
-      "desc": "選擇同一模型回覆中多個子智能體啟動請求的調度方式。",
-      "tooltipLabel": "子智能體批量調度說明",
-      "safeOnly": "僅安全併發",
-      "safeOnlyDesc": "只併發執行目標標記為只讀的子智能體。",
-      "forceParallel": "強制並行",
-      "forceParallelDesc": "並行執行同一回覆中的多個子智能體啟動請求，同時仍遵守子智能體容量上限。"
+      "label": "任務並行方式",
+      "desc": "選擇多個任務同時開始時的執行方式。",
+      "tooltipLabel": "任務並行方式說明",
+      "safeOnly": "安全並行",
+      "safeOnlyDesc": "只同時執行不會修改內容的任務。",
+      "forceParallel": "盡量並行",
+      "forceParallelDesc": "盡可能同時執行多個任務。"
     },
     "seconds": "秒"
   },
diff --git a/src/web-ui/src/locales/zh-TW/settings/ai-features.json b/src/web-ui/src/locales/zh-TW/settings/ai-features.json
index ec9e152548..ccb39603c1 100644
--- a/src/web-ui/src/locales/zh-TW/settings/ai-features.json
+++ b/src/web-ui/src/locales/zh-TW/settings/ai-features.json
@@ -42,10 +42,6 @@
     "git-func-agent": {
       "displayName": "Git 功能",
       "description": "提交資訊、代碼審核"
-    },
-    "startchat-func-agent": {
-      "displayName": "會話啟動",
-      "description": "工作狀態分析、歡迎資訊"
     }
   },
   "loading": {
diff --git a/src/web-ui/src/locales/zh-TW/settings/ai-model.json b/src/web-ui/src/locales/zh-TW/settings/ai-model.json
index 040d14fdc6..a562e84e96 100644
--- a/src/web-ui/src/locales/zh-TW/settings/ai-model.json
+++ b/src/web-ui/src/locales/zh-TW/settings/ai-model.json
@@ -30,6 +30,7 @@
     "loadFailed": "載入會話標題設定失敗",
     "model": {
       "label": "會話標題生成模型",
+      "inherit": "目前會話模型",
       "primary": "主力模型",
       "fast": "快速模型"
     },
@@ -341,8 +342,14 @@
       "modelsDev": "指定 models.dev",
       "disabled": "僅自定義"
     },
-    "catalogProvider": "models.dev 供應商",
-    "catalogModel": "models.dev 模型",
+    "catalogProvider": "供應商",
+    "catalogModel": "模型",
+    "catalogSearch": "快速查找",
+    "catalogSearchPlaceholder": "輸入供應商或模型關鍵詞",
+    "catalogSearchHint": "選擇結果後會自動填入下方供應商和模型。",
+    "catalogSearchResults": "models.dev 模型搜尋結果",
+    "catalogSearchEmpty": "沒有符合的 models.dev 思考模型",
+    "catalogSearchLimit": "結果較多，請繼續輸入以縮小範圍",
     "catalogUnbound": "未綁定",
     "catalogProviderCustomValueHint": "使用自訂供應商 ID",
     "catalogModelCustomValueHint": "使用自訂模型 ID",
@@ -351,12 +358,14 @@
     "auto": "自動（模型預設值）",
     "autoShort": "自動",
     "generatedTitle": "自動生成的預設",
+    "unavailableTitle": "部分 models.dev 預設無法使用",
+    "unavailableDescription": "目前的 API 格式「{{format}}」無法可靠套用以下預設：{{presets}}。請參考服務供應商的官方文件，並在自訂預設中使用「請求內容補丁」設定所需欄位。",
+    "unknownRequestFormat": "未知",
     "customTitle": "自定義預設",
-    "customTooltip": "自定義預設會把一組思考參數儲存為聊天輸入框中的可選項。請為每個預設填寫唯一 ID 和顯示名稱，再按模型 API 支援情況新增推理強度、思考開關或思考預算；僅在需要補充供應商專用參數時新增請求 JSON patch。",
+    "customTooltip": "自定義預設會把一組思考參數儲存為聊天輸入框中的可選項。請為每個預設填寫名稱，再按模型 API 支援情況新增推理強度、思考開關或思考預算；僅在需要補充供應商專用參數時新增請求內容補丁。",
     "add": "新增預設",
     "addAction": "新增操作",
     "empty": "暫無自定義預設",
-    "id": "預設 ID",
     "label": "名稱",
     "labelPlaceholder": "顯示名稱",
     "default": "預設",
@@ -370,14 +379,14 @@
     "effortCustomWarning": "這是自定義值，請確認模型 API 支援此值。",
     "settingToggle": "開啟 / 關閉",
     "settingBudget": "Token 預算",
-    "settingPatch": "請求 JSON Patch",
+    "settingPatch": "請求內容補丁",
     "actionSummaryEffort": "推理強度：{{value}}",
     "actionSummaryEnabled": "開啟思考",
     "actionSummaryDisabled": "關閉思考",
     "actionSummaryBudget": "Token 預算：{{value}}",
-    "actionSummaryPatches": "{{count}} 個請求 Patch",
+    "actionSummaryPatches": "{{count}} 個請求內容補丁",
     "noActions": "未設定操作",
-    "invalidJson": "請求 Patch 需要 JSON 物件。",
+    "invalidJson": "請求內容補丁需要 JSON 物件。",
     "summary": "{{source}} · 預設：{{default}}",
     "summaryWithCustom": "{{source}} · 預設：{{default}} · {{count}} 個自定義預設",
     "apply": "應用",
diff --git a/src/web-ui/src/locales/zh-TW/settings/default-model.json b/src/web-ui/src/locales/zh-TW/settings/default-model.json
index 257fc28cfa..0bb133a9f0 100644
--- a/src/web-ui/src/locales/zh-TW/settings/default-model.json
+++ b/src/web-ui/src/locales/zh-TW/settings/default-model.json
@@ -60,10 +60,6 @@
         "displayName": "Git 功能",
         "description": "提交資訊、代碼審核"
       },
-      "startchat-func-agent": {
-        "displayName": "會話啟動",
-        "description": "工作狀態分析、歡迎資訊"
-      },
       "arc-func-agent": {
         "displayName": "架構分析",
         "description": "依賴圖、Mermaid 圖表"
diff --git a/src/web-ui/src/locales/zh-TW/settings/external-sources.json b/src/web-ui/src/locales/zh-TW/settings/external-sources.json
index 86725b02d1..7a386fbba8 100644
--- a/src/web-ui/src/locales/zh-TW/settings/external-sources.json
+++ b/src/web-ui/src/locales/zh-TW/settings/external-sources.json
@@ -121,6 +121,13 @@
     "modelBindingUpdated": "已儲存 Agent 模型綁定並重新整理受影響的 Agent。",
     "mcpUpdated": "已儲存 MCP 伺服器選擇並重新整理狀態。"
   },
+  "bulkActions": {
+    "enablePending": "啟用全部待確認項（{{count}}）",
+    "disableAll": "全部停用",
+    "enableRisk": "僅核准目前顯示的 {{count}} 項；如果探索結果發生變化，BitFun 會要求重新確認。",
+    "enabled": "已啟用選取的待確認項。",
+    "disabled": "已停用選取的項目。"
+  },
   "recoveryActions": {
     "refresh": "重新整理狀態",
     "retry": "重試",
@@ -238,7 +245,8 @@
       "unreadableSource": "BitFun 無法讀取來源中的部分內容。請檢查檔案存取權限後重新整理。",
       "notSupported": "BitFun 暫不支援此類外部內容，因此沒有載入或執行它。",
       "checkFailed": "BitFun 未能檢查一個來源，其他來源仍可使用。請重新整理後重試。",
-      "sourceIssue": "BitFun 在一個來源中發現問題，受影響的內容未啟用。請檢查來源設定後重新整理。"
+      "runtimeUnavailable": "此來源中的一個 MCP 伺服器無法使用。請先停用，修正設定或驗證後再啟用。",
+      "sourceIssue": "BitFun 未能完成一個來源的檢查；現有可用內容保持不變。你可以重新整理或查看技術詳細資料。"
     }
   },
   "sources": {
@@ -414,6 +422,7 @@
     "externalSource": "外部 AI 應用程式",
     "source": "來源：{{source}}",
     "sourceLocation": "設定位置：{{location}}",
+    "sourceLocationLabel": "設定位置",
     "scope": "適用範圍：{{scope}}",
     "command": "命令：{{command}}",
     "url": "位址：{{url}}",
@@ -430,6 +439,27 @@
     "timeoutExecution": "執行 {{duration}}",
     "timeoutMilliseconds": "{{value}} 毫秒",
     "changePolicy": "伺服器設定變更後，BitFun 會在再次載入前請你確認。",
+    "failureReason": "原因：{{reason}}",
+    "failureReasons": {
+      "authentication": "此 MCP 伺服器需要完成身分驗證。",
+      "timeout": "MCP 伺服器未能在啟動逾時前就緒。",
+      "commandUnavailable": "無法啟動設定的 MCP 命令，請檢查命令或執行環境。",
+      "workingDirectoryUnavailable": "設定的 MCP 工作目錄無法使用。",
+      "connectionFailed": "BitFun 無法連線至此 MCP 伺服器。",
+      "protocolFailed": "MCP 伺服器未能完成啟動交握。",
+      "nativeConfigurationUnavailable": "BitFun 無法讀取目前的 MCP 設定。",
+      "hostReadOnly": "目前的主機只能發現 MCP 伺服器，無法執行它們。",
+      "configurationChanged": "MCP 設定在啟用前發生變更，請重新整理後再次確認。",
+      "configurationInvalid": "目前的 MCP 設定無法用於 BitFun 執行階段。",
+      "hostUnavailable": "目前的主機沒有可用的 MCP 執行階段。",
+      "installFailed": "BitFun 無法將此 MCP 伺服器註冊至執行階段。",
+      "preparationFailed": "BitFun 無法準備此 MCP 設定以供啟用。",
+      "serverMissing": "此 MCP 伺服器已不在執行階段中。",
+      "runtimeFailed": "MCP 伺服器執行失敗或意外停止。",
+      "stopped": "MCP 伺服器目前未執行。",
+      "statusUnavailable": "BitFun 無法讀取 MCP 伺服器的目前狀態。",
+      "other": "MCP 伺服器啟動失敗，請檢查來源設定和 BitFun 日誌。"
+    },
     "runtimeUnavailableGuidance": "請先停用此伺服器，修正來源設定或驗證後再啟用，通常不需要重新啟動 BitFun。",
     "unsupportedGuidance": "請在來源應用程式中修改此設定，然後重新整理。",
     "enable": "啟用伺服器",
diff --git a/src/web-ui/src/locales/zh-TW/settings/session-config.json b/src/web-ui/src/locales/zh-TW/settings/session-config.json
index 769fd25eb8..e3a5345165 100644
--- a/src/web-ui/src/locales/zh-TW/settings/session-config.json
+++ b/src/web-ui/src/locales/zh-TW/settings/session-config.json
@@ -5,37 +5,37 @@
   },
   "permissionsPage": {
     "title": "權限管理",
-    "subtitle": "加速工作區搜尋、工具執行、工具定義載入、瀏覽器控制與偵錯模式"
+    "subtitle": "管理工具權限、執行方式，以及桌面和瀏覽器控制。"
   },
   "features": {
     "workspaceSearch": {
       "title": "加速工作區搜尋",
-      "subtitle": "為本地工作區啟用基於 flashgrep 的索引搜尋。關閉後 BitFun 會回退到原有搜尋。",
+      "subtitle": "提升大型工作區中的檔案搜尋速度。關閉後仍可正常搜尋。",
       "enable": "啟用加速工作區搜尋"
     }
   },
   "toolExecution": {
-    "sectionTitle": "工具執行行為",
-    "sectionDescription": "本會話中 AI 調用工具時的確認與超時策略。"
+    "sectionTitle": "工具執行",
+    "sectionDescription": "設定工具逾時和並行任務數量。"
   },
   "permissionPolicy": {
     "sectionTitle": "工具權限",
-    "sectionDescription": "選擇工作階段的預設工具存取原則，以及權限請求的處理方式。",
+    "sectionDescription": "設定 BitFun 何時需要你確認工具操作。",
     "mode": "預設權限模式",
     "ask": "需要確認",
-    "askDescription": "外部存取、修改檔案和執行命令需要確認。",
+    "askDescription": "修改檔案、執行命令或存取外部服務時先確認。",
     "fullAccess": "完全存取",
-    "fullAccessDescription": "預設允許工具執行，無需確認。",
+    "fullAccessDescription": "不再逐次確認工具操作。",
     "fullAccessWarningTitle": "啟用完全存取？",
     "fullAccessWarningMessage": "完全存取會預設允許工具執行，不再逐次確認。",
     "fullAccessConfirm": "啟用完全存取",
     "cancel": "取消",
     "autoApprove": "自動批准",
-    "autoApproveDescription": "自動批准需要確認的請求。",
+    "autoApproveDescription": "自動允許原本需要確認的操作。",
     "showInChatInput": "顯示權限模式選擇器",
-    "showInChatInputDescription": "在輸入框下方顯示選擇器，在該處切換的模式僅作用於目前工作階段。隱藏它不會變更任何工作階段的權限模式。",
+    "showInChatInputDescription": "在輸入框下方顯示權限模式，可隨時為目前工作階段切換。",
     "globalRules": "全域規則",
-    "globalRulesDescription": "定義使用者級規則；它們在所選模式之後、專案和 Agent 規則之前套用。",
+    "globalRulesDescription": "為所有工作區設定通用的允許、詢問或拒絕規則。",
     "manageGlobalRules": "管理規則",
     "globalRulesDialogTitle": "全域工具權限規則",
     "globalRulesDialogDescription": "這些使用者級規則會套用至所有工作區。後續專案和 Agent 規則可以覆蓋它們；產品強制限制始終優先。",
@@ -52,7 +52,7 @@
     "discardGlobalRules": "放棄變更",
     "saveGlobalRules": "儲存規則",
     "globalRulesEffects": { "allow": "允許", "ask": "詢問", "deny": "拒絕" },
-    "modeDescription": "作用於尚未單獨設定的工作階段。每個工作階段都可以在輸入框中覆寫該預設值。"
+    "modeDescription": "作為新工作階段的預設設定，可在輸入框中暫時切換。"
   },
   "projectPermissions": {
     "description": "「始終允許」會儲存為目前專案的記憶授權；靜態專案規則會在工具執行前直接套用。",
@@ -91,54 +91,69 @@
     "effects": { "allow": "允許", "ask": "詢問", "deny": "拒絕" }
   },
   "deferredToolLoading": {
-    "sectionTitle": "工具延遲載入",
-    "sectionDescription": "僅在需要時載入部分工具的完整 Schema（包括部分內建工具及所有 MCP 工具）。",
-    "warning": "目前會在每次請求中傳送啟用工具的完整 Schema；如果設定了大量 MCP 工具會占用較多 Token。"
+    "sectionTitle": "按需載入工具",
+    "sectionDescription": "僅在需要時載入工具詳情。",
+    "warning": "關閉後會載入所有工具詳情，可能增加模型用量。"
   },
   "computerUse": {
-    "sectionTitle": "Computer use（桌面自動化）",
-    "sectionDescription": "在 BitFun 桌面端允許助理截取屏幕並控制鍵鼠；需多模態模型理解畫面。",
-    "enable": "啟用 Computer use",
-    "enableDesc": "關閉時，任何會話模式都不會啟用 ComputerUse 工具；瀏覽器控制（ControlHub）目前不受此開關約束。",
+    "sectionTitle": "桌面控制",
+    "sectionDescription": "允許 BitFun 查看螢幕並操作滑鼠和鍵盤。",
+    "enable": "允許桌面控制",
+    "enableDesc": "關閉後，BitFun 將不再操作桌面應用程式。瀏覽器控制可單獨設定。",
     "accessibility": "輔助功能",
-    "accessibilityDesc": "macOS 上用於讓 BitFun 讀取畫面上的介面元素並向其他應用傳送滑鼠/鍵盤操作；Windows 無需單獨授權，Linux 需要 X11 工作階段。",
-    "screenCapture": "屏幕錄製",
-    "screenCaptureDesc": "用於讓 BitFun 擷取畫面截圖，使助理能看到目前正在操作的內容。",
+    "accessibilityDesc": "允許 BitFun 識別並操作其他應用程式中的介面。",
+    "screenCapture": "螢幕錄製",
+    "screenCaptureDesc": "允許 BitFun 查看螢幕內容。",
     "granted": "已授權",
     "notGranted": "未授權",
     "openSettings": "系統設置",
     "refreshStatus": "重新整理狀態",
-    "desktopOnly": "Computer use 僅在 BitFun 桌面應用中可用。",
-    "platformNote": "說明"
+    "desktopOnly": "桌面控制僅在 BitFun 桌面應用程式中可用。",
+    "platformNote": "說明",
+    "platformNotes": {
+      "macos": "目前版本仍需在系統設定中授予輔助功能權限。",
+      "windows": "部分受保護的視窗或遠端桌面環境可能無法控制。",
+      "linux": "目前桌面環境可能不支援完整的滑鼠、鍵盤或螢幕控制。",
+      "generic": "目前系統無法使用完整的桌面控制功能。"
+    }
   },
   "browserControl": {
     "sectionTitle": "瀏覽器控制",
-    "sectionDescription": "選擇瀏覽器並啟用 CDP 控制。",
+    "sectionDescription": "選擇 BitFun 使用的瀏覽器和連線方式。",
     "desktopOnly": "瀏覽器控制僅在 BitFun 桌面應用中可用。",
     "status": "連接狀態",
     "statusDesc": "",
     "notConnected": "未連接",
+    "readyNotConnected": "已就緒，使用時自動連接",
     "refreshStatus": "重新整理狀態",
     "connect": "連接瀏覽器",
+    "defaultCdp": "使用現有瀏覽器",
+    "defaultCdpDesc": "使用已開啟的 Chrome 或 Edge，並保留分頁和登入狀態。連線時仍需在瀏覽器中確認。",
+    "autoConnectOnStartup": "啟動時自動連接",
+    "autoConnectOnStartupDesc": "BitFun 啟動後自動連線已開啟的瀏覽器。瀏覽器重新啟動後可能需要再次確認。",
+    "defaultCdpEnabled": "已啟用",
+    "defaultCdpDisabled": "未啟用",
+    "enableDefaultCdp": "啟用並連線",
+    "defaultCdpEnablePrompt": "已開啟 {{browser}} 的 Remote debugging 設定頁（該頁面僅有英文）。請勾選 “Allow remote debugging for this browser instance”；BitFun 偵測到後會自動繼續連線，再請在瀏覽器中選擇「允許」。",
+    "defaultCdpConnectPrompt": "正在連接你目前的 {{browser}}；請在瀏覽器彈出視窗中選擇「允許」。",
     "connectSuccess": "已連接 {{browser}}",
     "connectFailed": "連接瀏覽器失敗",
-    "restartSuccess": "已重啟 {{browser}} 並啟用調試模式",
-    "restartFailed": "重啟瀏覽器並啟用調試失敗",
+    "userProfileSetupRequired": "{{browser}} 已開啟 Remote debugging 設定頁，但等待期間未偵測到開關生效。請勾選 “Allow remote debugging for this browser instance” 後再次點擊「啟用並連線」；目前的分頁和登入狀態會被保留。",
+    "userProfileSetupManual": "請在 {{browser}} 中開啟 {{url}}，勾選 “Allow remote debugging for this browser instance”，然後再次點擊「啟用並連線」；目前的分頁和登入狀態會被保留。",
+    "userProfileConnectionFailed": "{{browser}} 未允許連線，或連線要求已逾時。請確認瀏覽器正在執行且已啟用遠端偵錯，然後重新連線並在瀏覽器中選擇「允許」。",
+    "restartSuccess": "已重新啟動 {{browser}} 並開啟瀏覽器控制",
+    "restartFailed": "無法重新啟動並連線 {{browser}}",
     "restartModal": {
-      "title": "啟用瀏覽器調試模式",
-      "description": "檢測到 {{browser}} 已在運行，目前實例未啟用調試端口。要讓 BitFun 控制瀏覽器，需要先重啟瀏覽器並以調試模式啟動。",
+      "title": "重新啟動瀏覽器",
+      "description": "BitFun 需要重新啟動目前的 {{browser}} 才能連線。",
       "warning": "此操作會關閉目前瀏覽器視窗。",
       "cancel": "取消",
-      "confirm": "重啟並啟用調試",
-      "restarting": "正在重啟..."
+      "confirm": "重新啟動並連線",
+      "restarting": "正在重新啟動..."
     },
-    "createLauncher": "建立啟動器",
-    "createLauncherSuccess": "啟動器已建立：{{path}}",
-    "createLauncherFailed": "建立啟動器失敗",
-    "createLauncherDesc": "建立帶調試端口的瀏覽器快捷方式。",
     "tabs": "個標籤頁",
     "preferredBrowser": "瀏覽器",
-    "preferredBrowserDesc": "選擇要由 BitFun 透過 CDP 控制的瀏覽器；預設表示跟隨系統預設瀏覽器。",
+    "preferredBrowserDesc": "預設使用系統瀏覽器。",
     "notInstalled": "未安裝"
   },
   "common": {
diff --git a/src/web-ui/src/locales/zh-TW/tools.json b/src/web-ui/src/locales/zh-TW/tools.json
index d0e6721f82..8dd5f78c6d 100644
--- a/src/web-ui/src/locales/zh-TW/tools.json
+++ b/src/web-ui/src/locales/zh-TW/tools.json
@@ -80,7 +80,7 @@
       "copiedMarkdown": "已複製 Markdown",
       "viewModeLabel": "Markdown 與預覽模式",
       "notice": {
-        "sourcePreviewFallback": "該文檔包含無法在可視化模式中安全編輯的 HTML 片段。請在源碼模式中編輯，或切換到預覽查看效果。"
+        "sourcePreviewFallback": "該文檔包含無法在可視化模式中安全編輯的語法。請在源碼模式中編輯，或切換到預覽模式查看。"
       }
     },
     "planViewer": {
@@ -124,6 +124,9 @@
       "rawHtml": {
         "inlineLabel": "HTML"
       },
+      "frontmatter": {
+        "label": "YAML Frontmatter"
+      },
       "details": {
         "summaryPlaceholder": "摘要"
       },
diff --git a/src/web-ui/src/main.tsx b/src/web-ui/src/main.tsx
index 3ec8c90792..f3c471aa65 100644
--- a/src/web-ui/src/main.tsx
+++ b/src/web-ui/src/main.tsx
@@ -15,6 +15,7 @@ import { bootstrapLogger, createLogger, initLogger } from './shared/utils/logger
 import { elapsedMs, logElapsed, measureAsyncAndLog, nowMs } from './shared/utils/timing';
 import { startupTrace } from './shared/utils/startupTrace';
 import { scheduleAfterStartupSignal } from './shared/utils/startupTaskScheduling';
+import { installInteractionModalityTracking } from './shared/utils/motionPreference';
 import {
   buildReactCrashLogPayload,
   isMinifiedReactErrorMessage,
@@ -185,6 +186,7 @@ function registerGlobalErrorHandlers() {
 }
 
 registerGlobalErrorHandlers();
+installInteractionModalityTracking();
 
 // Disable Tab-key focus traversal globally (IDE-style chrome).
 // Allow Tab where it has semantic meaning: Monaco, xterm, and modal/dialog forms
diff --git a/src/web-ui/src/shared/announcement-system/components/AnnouncementToastItem.tsx b/src/web-ui/src/shared/announcement-system/components/AnnouncementToastItem.tsx
index 6605ad0bfa..3446121def 100644
--- a/src/web-ui/src/shared/announcement-system/components/AnnouncementToastItem.tsx
+++ b/src/web-ui/src/shared/announcement-system/components/AnnouncementToastItem.tsx
@@ -8,6 +8,8 @@ interface Props {
   card: AnnouncementCard;
 }
 
+const ANNOUNCEMENT_TOAST_EXIT_MS = 220;
+
 /**
  * Bottom-left toast: compact fixed-width card.
  * Layout (top → bottom): title row (+ close) → description → action buttons.
@@ -17,6 +19,7 @@ const AnnouncementToastItem: React.FC<Props> = ({ card }) => {
   const { openModalFor, dismissToast } = useAnnouncementStore();
   const [exiting, setExiting] = useState(false);
   const autoDismissTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const exitTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
 
   const { toast, card_type, modal } = card;
   const hasModal = card_type !== 'tip' && modal !== null;
@@ -25,9 +28,10 @@ const AnnouncementToastItem: React.FC<Props> = ({ card }) => {
   const resolve = (key: string) => (key.startsWith('announcements.') ? t(key) : key);
 
   function triggerExit(callback: () => void) {
+    if (exiting) return;
     if (autoDismissTimer.current) clearTimeout(autoDismissTimer.current);
     setExiting(true);
-    setTimeout(callback, 280);
+    exitTimer.current = setTimeout(callback, ANNOUNCEMENT_TOAST_EXIT_MS);
   }
 
   function handleDismiss() {
@@ -48,6 +52,7 @@ const AnnouncementToastItem: React.FC<Props> = ({ card }) => {
     }
     return () => {
       if (autoDismissTimer.current) clearTimeout(autoDismissTimer.current);
+      if (exitTimer.current) clearTimeout(exitTimer.current);
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [card.id]);
@@ -61,6 +66,8 @@ const AnnouncementToastItem: React.FC<Props> = ({ card }) => {
       className={`announcement-toast ${exiting ? 'announcement-toast--exiting' : 'announcement-toast--entering'}`}
       role="alert"
       aria-live="polite"
+      aria-hidden={exiting}
+      {...(exiting ? { inert: '' } : {})}
     >
       {/* Row 1: title + close (with optional countdown ring) */}
       <div className="announcement-toast__header">
diff --git a/src/web-ui/src/shared/announcement-system/components/FeatureModal.tsx b/src/web-ui/src/shared/announcement-system/components/FeatureModal.tsx
index 0111adf1aa..363a0c338a 100644
--- a/src/web-ui/src/shared/announcement-system/components/FeatureModal.tsx
+++ b/src/web-ui/src/shared/announcement-system/components/FeatureModal.tsx
@@ -1,4 +1,4 @@
-import React, { useEffect, useRef } from 'react';
+import React, { useEffect, useLayoutEffect, useRef, useState } from 'react';
 import { X } from 'lucide-react';
 import { useAnnouncementStore } from '../store/announcementStore';
 import FeatureModalPage from './FeatureModalPage';
@@ -6,6 +6,63 @@ import { useAnnouncementI18n } from '../hooks/useAnnouncementI18n';
 import '../styles/FeatureModal.scss';
 import type { ModalConfig } from '../types';
 
+const FEATURE_MODAL_EXIT_MS = 180;
+const FEATURE_MODAL_PAGE_MS = 180;
+
+interface FeatureModalPagesProps {
+  pages: NonNullable<ModalConfig['pages']>;
+  currentPage: number;
+}
+
+const FeatureModalPages: React.FC<FeatureModalPagesProps> = ({ pages, currentPage }) => {
+  const [displayedPage, setDisplayedPage] = useState(currentPage);
+  const [leavingPage, setLeavingPage] = useState<number | null>(null);
+  const [direction, setDirection] = useState<'forward' | 'backward'>('forward');
+  const settleTimerRef = useRef<number | null>(null);
+
+  useLayoutEffect(() => {
+    if (currentPage === displayedPage) return;
+    if (settleTimerRef.current !== null) window.clearTimeout(settleTimerRef.current);
+    setDirection(currentPage > displayedPage ? 'forward' : 'backward');
+    setLeavingPage(displayedPage);
+    setDisplayedPage(currentPage);
+    settleTimerRef.current = window.setTimeout(() => {
+      settleTimerRef.current = null;
+      setLeavingPage(null);
+    }, FEATURE_MODAL_PAGE_MS);
+  }, [currentPage, displayedPage]);
+
+  useEffect(() => () => {
+    if (settleTimerRef.current !== null) window.clearTimeout(settleTimerRef.current);
+  }, []);
+
+  const renderPage = (pageIndex: number, state: 'active' | 'leaving') => {
+    const page = pages[pageIndex];
+    if (!page) return null;
+    return (
+      <div
+        key={`${state}-${pageIndex}`}
+        className="feature-modal__page"
+        data-state={state}
+        data-direction={direction}
+        aria-hidden={state !== 'active'}
+        {...(state !== 'active' ? { inert: '' } : {})}
+      >
+        <FeatureModalPage page={page} active={state === 'active'} />
+      </div>
+    );
+  };
+
+  return (
+    <>
+      {leavingPage !== null && leavingPage !== displayedPage
+        ? renderPage(leavingPage, 'leaving')
+        : null}
+      {renderPage(displayedPage, 'active')}
+    </>
+  );
+};
+
 /**
  * Centre-screen feature demo modal.
  *
@@ -26,12 +83,17 @@ const FeatureModal: React.FC = () => {
 
   const [exiting, setExiting] = React.useState(false);
   const backdropRef = useRef<HTMLDivElement>(null);
+  const closeTimerRef = useRef<number | null>(null);
 
   // When modalVisible becomes false trigger the exit animation.
   useEffect(() => {
     if (!modalVisible) setExiting(false);
   }, [modalVisible]);
 
+  useEffect(() => () => {
+    if (closeTimerRef.current !== null) window.clearTimeout(closeTimerRef.current);
+  }, []);
+
   if (!openModal || !modalVisible) return null;
 
   const modal: ModalConfig = openModal.modal!;
@@ -40,8 +102,12 @@ const FeatureModal: React.FC = () => {
   const isLast = currentPage === pages.length - 1;
 
   function triggerClose(neverShow = false) {
+    if (exiting) return;
     setExiting(true);
-    setTimeout(() => closeModal(neverShow), 280);
+    closeTimerRef.current = window.setTimeout(() => {
+      closeTimerRef.current = null;
+      closeModal(neverShow);
+    }, FEATURE_MODAL_EXIT_MS);
   }
 
   function handleBackdropClick(e: React.MouseEvent) {
@@ -61,6 +127,8 @@ const FeatureModal: React.FC = () => {
       onClick={handleBackdropClick}
       role="dialog"
       aria-modal="true"
+      aria-hidden={exiting}
+      {...(exiting ? { inert: '' } : {})}
     >
       <div className={`feature-modal ${sizeClass}${exiting ? ' feature-modal--exiting' : ''}`} data-bf-component="announcement" data-bf-part="modal">
         {/* Close button */}
@@ -79,14 +147,7 @@ const FeatureModal: React.FC = () => {
 
         {/* Page viewport */}
         <div className="feature-modal__pages" data-bf-component="announcement" data-bf-part="modalPages">
-          {pages.map((page, i) => (
-            <div
-              key={i}
-              style={{ display: i === currentPage ? 'block' : 'none' }}
-            >
-              <FeatureModalPage page={page} active={i === currentPage} />
-            </div>
-          ))}
+          <FeatureModalPages pages={pages} currentPage={currentPage} />
         </div>
 
         {/* Footer navigation */}
diff --git a/src/web-ui/src/shared/announcement-system/styles/AnnouncementToast.scss b/src/web-ui/src/shared/announcement-system/styles/AnnouncementToast.scss
index c43225eb34..ebbaf29bb7 100644
--- a/src/web-ui/src/shared/announcement-system/styles/AnnouncementToast.scss
+++ b/src/web-ui/src/shared/announcement-system/styles/AnnouncementToast.scss
@@ -3,11 +3,11 @@
 $toast-width: 320px;
 
 // ─── Container (fixed bottom-left) ───────────────────────────────────────────
-// Left offset accounts for the fan-out spread (ghost cards translate ±38px).
+// Left offset leaves room for the subtle deck spread.
 .announcement-toast-stack {
   position: fixed;
   bottom: 64px;
-  left: 58px; // 20px margin + ~38px fan-out buffer
+  left: 36px;
   z-index: calc(#{$z-notification} + 1);
   pointer-events: none;
   // Clip nothing — overflow visible so rotated ghosts are always fully shown
@@ -29,7 +29,9 @@ $toast-width: 320px;
   > .announcement-toast {
     position: relative;
     z-index: 3;
-    transition: transform 0.4s ease, box-shadow 0.4s ease;
+    transition:
+      box-shadow 180ms cubic-bezier(0.2, 0.8, 0.2, 1),
+      transform 180ms cubic-bezier(0.2, 0.8, 0.2, 1);
   }
 
   // Ghost layers ─────────────────────────────────────────────────────────────
@@ -41,7 +43,7 @@ $toast-width: 320px;
     bottom: 0;
     border-radius: $size-radius-lg;
     pointer-events: none;
-    transition: transform 0.4s ease;
+    transition: transform 180ms cubic-bezier(0.2, 0.8, 0.2, 1);
 
     // Ghost 1: tilted left  →  fans left on hover
     &--1 {
@@ -62,19 +64,21 @@ $toast-width: 320px;
     }
   }
 
-  // Hover: fan the deck open + lift + slight scale ──────────────────────────
-  &:hover {
-    > .announcement-toast {
-      transform: translateY(-10px) scale(1.025);
-      box-shadow: 0 16px 40px var(--bf-appearance-token-color-overlay-black-20);
-    }
+  // Keep hover feedback subtle and only enable it for precise pointing devices.
+  @media (hover: hover) and (pointer: fine) {
+    &:hover {
+      > .announcement-toast {
+        transform: translateY(-2px) scale(1.005);
+        box-shadow: 0 10px 28px var(--bf-appearance-token-color-overlay-black-20);
+      }
 
-    .announcement-toast-ghost--1 {
-      transform: translateX(-38px) rotate(-15deg);
-    }
+      .announcement-toast-ghost--1 {
+        transform: translateX(-12px) rotate(-10deg);
+      }
 
-    .announcement-toast-ghost--2 {
-      transform: translateX(38px) rotate(15deg);
+      .announcement-toast-ghost--2 {
+        transform: translateX(12px) rotate(10deg);
+      }
     }
   }
 }
@@ -93,13 +97,13 @@ $toast-width: 320px;
   overflow: hidden;
 
   &--entering {
-    animation: toastSlideIn 0.3s cubic-bezier(0.34, 1.56, 0.64, 1) both;
+    animation: bitfun-announcement-toast-in 200ms cubic-bezier(0.2, 0.8, 0.2, 1) both;
     // Disable hover transition while entering so the two don't fight
     transition: none !important;
   }
 
   &--exiting {
-    animation: toastSlideOut 0.25s ease-in both;
+    animation: bitfun-announcement-toast-out 220ms cubic-bezier(0.4, 0, 1, 1) both;
     transition: none !important;
   }
 
@@ -163,7 +167,7 @@ $toast-width: 320px;
     stroke-linecap: round;
     stroke-dasharray: $ring-circumference;
     stroke-dashoffset: 0;
-    animation: ringCountdown linear both;
+    animation: bitfun-announcement-ring-countdown linear both;
     // Smooth opacity fade at the very end
     transition: opacity 0.3s ease;
   }
@@ -181,16 +185,20 @@ $toast-width: 320px;
     border-radius: 50%;
     color: var(--bf-appearance-token-color-text-muted);
     cursor: pointer;
-    transition: background $motion-base $easing-standard, color $motion-base $easing-standard;
+    transition:
+      background-color $motion-base $easing-standard,
+      color $motion-base $easing-standard;
 
     svg {
       width: 13px;
       height: 13px;
     }
 
-    &:hover {
-      background: var(--bf-appearance-token-color-bg-secondary);
-      color: var(--bf-appearance-token-color-text-primary);
+    @media (hover: hover) and (pointer: fine) {
+      &:hover {
+        background: var(--bf-appearance-token-color-bg-secondary);
+        color: var(--bf-appearance-token-color-text-primary);
+      }
     }
   }
 
@@ -225,14 +233,21 @@ $toast-width: 320px;
     font-weight: $font-weight-medium;
     border: none;
     cursor: pointer;
-    transition: all $motion-base $easing-standard;
+    transition:
+      background-color $motion-base $easing-standard,
+      border-color $motion-base $easing-standard,
+      color $motion-base $easing-standard,
+      opacity $motion-base $easing-standard,
+      transform $motion-base $easing-standard;
     white-space: nowrap;
 
     &--primary {
       background: var(--bf-appearance-token-color-accent-500);
       color: var(--bf-appearance-token-color-static-white);
 
-      &:hover { opacity: 0.9; }
+      @media (hover: hover) and (pointer: fine) {
+        &:hover { opacity: 0.9; }
+      }
       &:active { transform: scale(0.98); }
     }
 
@@ -241,19 +256,21 @@ $toast-width: 320px;
       color: var(--bf-appearance-token-color-text-secondary);
       border: 1px solid var(--bf-appearance-token-border-base);
 
-      &:hover {
-        background: var(--bf-appearance-token-color-bg-secondary);
-        color: var(--bf-appearance-token-color-text-primary);
+      @media (hover: hover) and (pointer: fine) {
+        &:hover {
+          background: var(--bf-appearance-token-color-bg-secondary);
+          color: var(--bf-appearance-token-color-text-primary);
+        }
       }
     }
   }
 
 }
 
-@keyframes toastSlideIn {
+@keyframes bitfun-announcement-toast-in {
   from {
     opacity: 0;
-    transform: translateX(-110%) scale(0.97);
+    transform: translateX(-12px) scale(0.985);
   }
   to {
     opacity: 1;
@@ -261,21 +278,36 @@ $toast-width: 320px;
   }
 }
 
-@keyframes toastSlideOut {
+@keyframes bitfun-announcement-toast-out {
   from {
     opacity: 1;
     transform: translateX(0);
-    max-height: 260px;
   }
   to {
     opacity: 0;
-    transform: translateX(-110%);
-    max-height: 0;
-    margin-bottom: -12px;
+    transform: translateX(-12px) scale(0.985);
   }
 }
 
-@keyframes ringCountdown {
+@keyframes bitfun-announcement-ring-countdown {
   from { stroke-dashoffset: 0; }
   to   { stroke-dashoffset: 72.26px; }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .announcement-toast-deck > .announcement-toast,
+  .announcement-toast-deck .announcement-toast-ghost {
+    transition: none;
+  }
+
+  .announcement-toast--entering,
+  .announcement-toast--exiting,
+  .announcement-toast__ring-fill {
+    animation: none;
+    transform: none;
+  }
+
+  .announcement-toast--exiting {
+    opacity: 0;
+  }
+}
diff --git a/src/web-ui/src/shared/announcement-system/styles/FeatureModal.scss b/src/web-ui/src/shared/announcement-system/styles/FeatureModal.scss
index 71c59ab8df..1bd2cb3a18 100644
--- a/src/web-ui/src/shared/announcement-system/styles/FeatureModal.scss
+++ b/src/web-ui/src/shared/announcement-system/styles/FeatureModal.scss
@@ -10,10 +10,10 @@
   align-items: center;
   justify-content: center;
   padding: 24px;
-  animation: backdropIn 0.2s ease both;
+  animation: bitfun-feature-modal-backdrop-in 180ms cubic-bezier(0.2, 0.8, 0.2, 1) both;
 
   &--exiting {
-    animation: backdropOut 0.2s ease both;
+    animation: bitfun-feature-modal-backdrop-out 180ms cubic-bezier(0.4, 0, 1, 1) both;
   }
 }
 
@@ -27,10 +27,10 @@
   display: flex;
   flex-direction: column;
   overflow: hidden;
-  animation: modalIn 0.32s cubic-bezier(0.34, 1.56, 0.64, 1) both;
+  animation: bitfun-feature-modal-in 220ms cubic-bezier(0.2, 0.8, 0.2, 1) both;
 
   &--exiting {
-    animation: modalOut 0.22s ease-in both;
+    animation: bitfun-feature-modal-out 180ms cubic-bezier(0.4, 0, 1, 1) both;
   }
 
   // Fixed portrait sizes
@@ -56,13 +56,20 @@
     color: var(--bf-appearance-token-color-text-muted);
     cursor: pointer;
     z-index: 1;
-    transition: all $motion-base $easing-standard;
+    transition:
+      background-color $motion-base $easing-standard,
+      border-color $motion-base $easing-standard,
+      color $motion-base $easing-standard,
+      opacity $motion-base $easing-standard,
+      transform $motion-base $easing-standard;
 
     svg { flex-shrink: 0; }
 
-    &:hover {
-      background: var(--bf-appearance-token-color-bg-tertiary);
-      color: var(--bf-appearance-token-color-text-primary);
+    @media (hover: hover) and (pointer: fine) {
+      &:hover {
+        background: var(--bf-appearance-token-color-bg-tertiary);
+        color: var(--bf-appearance-token-color-text-primary);
+      }
     }
   }
 
@@ -70,7 +77,7 @@
   &__pages {
     flex: 1;
     min-height: 0;
-    overflow-y: auto;
+    overflow: hidden;
     position: relative;
 
     // Thin scrollbar
@@ -84,6 +91,31 @@
     }
   }
 
+  &__page {
+    position: absolute;
+    inset: 0;
+    overflow-y: auto;
+    will-change: opacity, transform;
+
+    &[data-state='active'][data-direction='forward'] {
+      animation: bitfun-feature-page-forward-in 180ms cubic-bezier(0.2, 0.8, 0.2, 1) both;
+    }
+
+    &[data-state='active'][data-direction='backward'] {
+      animation: bitfun-feature-page-backward-in 180ms cubic-bezier(0.2, 0.8, 0.2, 1) both;
+    }
+
+    &[data-state='leaving'][data-direction='forward'] {
+      animation: bitfun-feature-page-forward-out 140ms ease both;
+      pointer-events: none;
+    }
+
+    &[data-state='leaving'][data-direction='backward'] {
+      animation: bitfun-feature-page-backward-out 140ms ease both;
+      pointer-events: none;
+    }
+  }
+
   // ─── Footer navigation ─────────────────────────────────────────────────────
   &__footer {
     display: flex;
@@ -108,7 +140,10 @@
     background: var(--bf-appearance-token-color-bg-tertiary);
     border: 1px solid var(--bf-appearance-token-border-base);
     cursor: pointer;
-    transition: all $motion-base $easing-standard;
+    transition:
+      background-color $motion-base $easing-standard,
+      border-color $motion-base $easing-standard,
+      width $motion-base $easing-standard;
 
     &--active {
       width: 18px;
@@ -117,8 +152,10 @@
       border-color: var(--bf-appearance-token-color-accent-500);
     }
 
-    &:hover:not(&--active) {
-      background: var(--bf-appearance-token-color-text-muted);
+    @media (hover: hover) and (pointer: fine) {
+      &:hover:not(&--active) {
+        background: var(--bf-appearance-token-color-text-muted);
+      }
     }
   }
 
@@ -135,16 +172,23 @@
     font-weight: $font-weight-medium;
     border: none;
     cursor: pointer;
-    transition: all $motion-base $easing-standard;
+    transition:
+      background-color $motion-base $easing-standard,
+      border-color $motion-base $easing-standard,
+      color $motion-base $easing-standard,
+      opacity $motion-base $easing-standard,
+      transform $motion-base $easing-standard;
 
     &--prev {
       background: transparent;
       color: var(--bf-appearance-token-color-text-secondary);
       border: 1px solid var(--bf-appearance-token-border-base);
 
-      &:hover {
-        background: var(--bf-appearance-token-color-bg-secondary);
-        color: var(--bf-appearance-token-color-text-primary);
+      @media (hover: hover) and (pointer: fine) {
+        &:hover {
+          background: var(--bf-appearance-token-color-bg-secondary);
+          color: var(--bf-appearance-token-color-text-primary);
+        }
       }
     }
 
@@ -154,7 +198,9 @@
       color: var(--bf-appearance-token-color-static-white);
       padding: 6px 22px;
 
-      &:hover { opacity: 0.9; }
+      @media (hover: hover) and (pointer: fine) {
+        &:hover { opacity: 0.9; }
+      }
       &:active { transform: scale(0.97); }
     }
   }
@@ -171,7 +217,9 @@
     text-decoration: underline;
     text-underline-offset: 2px;
 
-    &:hover { color: var(--bf-appearance-token-color-text-secondary); }
+    @media (hover: hover) and (pointer: fine) {
+      &:hover { color: var(--bf-appearance-token-color-text-secondary); }
+    }
   }
 }
 
@@ -361,15 +409,49 @@
 }
 
 // ─── Keyframes ────────────────────────────────────────────────────────────────
-@keyframes backdropIn  { from { opacity: 0; } to { opacity: 1; } }
-@keyframes backdropOut { from { opacity: 1; } to { opacity: 0; } }
+@keyframes bitfun-feature-modal-backdrop-in  { from { opacity: 0; } to { opacity: 1; } }
+@keyframes bitfun-feature-modal-backdrop-out { from { opacity: 1; } to { opacity: 0; } }
 
-@keyframes modalIn {
-  from { opacity: 0; transform: scale(0.9) translateY(16px); }
+@keyframes bitfun-feature-modal-in {
+  from { opacity: 0; transform: scale(0.985) translateY(8px); }
   to   { opacity: 1; transform: scale(1) translateY(0); }
 }
 
-@keyframes modalOut {
+@keyframes bitfun-feature-modal-out {
   from { opacity: 1; transform: scale(1); }
-  to   { opacity: 0; transform: scale(0.93); }
+  to   { opacity: 0; transform: scale(0.985); }
+}
+
+@keyframes bitfun-feature-page-forward-in {
+  from { opacity: 0; transform: translateX(8px); }
+  to { opacity: 1; transform: translateX(0); }
+}
+
+@keyframes bitfun-feature-page-forward-out {
+  from { opacity: 1; transform: translateX(0); }
+  to { opacity: 0; transform: translateX(-6px); }
+}
+
+@keyframes bitfun-feature-page-backward-in {
+  from { opacity: 0; transform: translateX(-8px); }
+  to { opacity: 1; transform: translateX(0); }
+}
+
+@keyframes bitfun-feature-page-backward-out {
+  from { opacity: 1; transform: translateX(0); }
+  to { opacity: 0; transform: translateX(6px); }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .feature-modal-backdrop,
+  .feature-modal,
+  .feature-modal__page {
+    animation: none;
+    transform: none;
+  }
+
+  .feature-modal-backdrop--exiting,
+  .feature-modal--exiting {
+    opacity: 0;
+  }
 }
diff --git a/src/web-ui/src/shared/context-menu-system/components/ContextMenuRenderer.tsx b/src/web-ui/src/shared/context-menu-system/components/ContextMenuRenderer.tsx
index a3965fd5de..5c78ae5072 100644
--- a/src/web-ui/src/shared/context-menu-system/components/ContextMenuRenderer.tsx
+++ b/src/web-ui/src/shared/context-menu-system/components/ContextMenuRenderer.tsx
@@ -105,10 +105,6 @@ export const ContextMenuRenderer: React.FC = () => {
 
   const uiItems = items.map(convertMenuItem);
 
-  if (!visible) {
-    return null;
-  }
-
   return (
     <ContextMenu
       items={uiItems}
@@ -121,4 +117,3 @@ export const ContextMenuRenderer: React.FC = () => {
 };
 
 export default ContextMenuRenderer;
-
diff --git a/src/web-ui/src/shared/context-menu-system/components/ui/ContextMenu.scss b/src/web-ui/src/shared/context-menu-system/components/ui/ContextMenu.scss
index ddebd3545d..d4db2146a7 100644
--- a/src/web-ui/src/shared/context-menu-system/components/ui/ContextMenu.scss
+++ b/src/web-ui/src/shared/context-menu-system/components/ui/ContextMenu.scss
@@ -6,6 +6,8 @@
 
 // Surface + motion aligned with .bitfun-nav-panel__workspace-menu / __workspace-item-menu-popover
 .context-menu {
+  --context-menu-transform-origin: top left;
+
   position: fixed;
   z-index: $z-context-menu;
   min-width: 180px;
@@ -20,11 +22,11 @@
   box-sizing: border-box;
 
   opacity: 0;
-  transform: translateY(6px) scale(0.96);
-  transform-origin: top left;
+  transform: translateY(-4px) scale(0.97);
+  transform-origin: var(--context-menu-transform-origin);
   transition:
-    opacity $motion-fast $easing-decelerate,
-    transform $motion-fast $easing-decelerate;
+    opacity 160ms cubic-bezier(0.23, 1, 0.32, 1),
+    transform 160ms cubic-bezier(0.23, 1, 0.32, 1);
   pointer-events: none;
 
   font-family: var(--bf-appearance-token-font-family-sans);
@@ -43,11 +45,15 @@
       0 10px 28px -8px rgba(var(--bf-appearance-token-color-static-black-rgb), 0.55);
   }
 
-  &.visible {
+  &[data-state='entered'] {
     opacity: 1;
     transform: translateY(0) scale(1);
     pointer-events: all;
   }
+
+  &[data-state='exiting'] {
+    transition-duration: 100ms;
+  }
 }
 
 
@@ -276,7 +282,7 @@
     transform: none;
   }
 
-  .context-menu.visible {
+  .context-menu[data-state='entered'] {
     transform: none;
   }
 
@@ -341,7 +347,11 @@
   border-radius: 50%;
   color: var(--bf-appearance-token-color-text-muted);
   cursor: pointer;
-  transition: all var(--bf-appearance-token-motion-fast) ease;
+  transition:
+    background-color var(--bf-appearance-token-motion-fast) ease,
+    color var(--bf-appearance-token-motion-fast) ease,
+    opacity var(--bf-appearance-token-motion-fast) ease,
+    scale var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
   flex-shrink: 0;
   opacity: 0.5;
   margin-left: auto;
@@ -356,4 +366,3 @@
     opacity: 1;
   }
 }
-
diff --git a/src/web-ui/src/shared/context-menu-system/components/ui/ContextMenu.test.tsx b/src/web-ui/src/shared/context-menu-system/components/ui/ContextMenu.test.tsx
new file mode 100644
index 0000000000..9a893bcb35
--- /dev/null
+++ b/src/web-ui/src/shared/context-menu-system/components/ui/ContextMenu.test.tsx
@@ -0,0 +1,190 @@
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { JSDOM } from 'jsdom';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { ContextMenu } from './ContextMenu';
+import type { ContextMenuItem } from './types';
+
+vi.mock('@/shared/utils/logger', () => ({
+  createLogger: () => ({ error: vi.fn() }),
+}));
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+describe('ContextMenu presence', () => {
+  let dom: JSDOM;
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    dom = new JSDOM('<!doctype html><html><body><div id="root"></div></body></html>');
+    globalThis.window = dom.window as unknown as Window & typeof globalThis;
+    globalThis.document = dom.window.document;
+    window.requestAnimationFrame = callback => window.setTimeout(() => callback(0), 0);
+    window.cancelAnimationFrame = handle => window.clearTimeout(handle);
+    container = document.getElementById('root') as HTMLDivElement;
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    vi.useRealTimers();
+    dom.window.close();
+  });
+
+  it('keeps the menu mounted while its exit transition runs', () => {
+    const trigger = document.createElement('button');
+    document.body.appendChild(trigger);
+    trigger.focus();
+    const props = {
+      items: [{ id: 'copy', label: 'Copy' }],
+      position: { x: 20, y: 20 },
+      context: {},
+      onClose: vi.fn(),
+    };
+
+    act(() => root.render(<ContextMenu {...props} visible />));
+    act(() => vi.runOnlyPendingTimers());
+    act(() => vi.runOnlyPendingTimers());
+    expect(container.querySelector('[role="menu"]')?.getAttribute('data-state')).toBe('entered');
+
+    act(() => root.render(<ContextMenu {...props} visible={false} />));
+    const exitingMenu = container.querySelector('[role="menu"]');
+    expect(exitingMenu?.getAttribute('data-state')).toBe('exiting');
+    expect(exitingMenu?.getAttribute('aria-hidden')).toBe('true');
+    expect(exitingMenu?.hasAttribute('inert')).toBe(true);
+    expect(document.activeElement).toBe(trigger);
+
+    act(() => vi.advanceTimersByTime(100));
+    expect(container.querySelector('[role="menu"]')).toBeNull();
+  });
+
+  it('uses roving focus and skips disabled items and separators', () => {
+    const items: ContextMenuItem[] = [
+      { id: 'disabled', label: 'Disabled', disabled: true },
+      { id: 'separator', label: '', separator: true },
+      { id: 'copy', label: 'Copy' },
+      { id: 'rename', label: 'Rename' },
+      { id: 'delete', label: 'Delete' },
+    ];
+
+    act(() => root.render(
+      <ContextMenu items={items} position={{ x: 0, y: 0 }} visible onClose={vi.fn()} />,
+    ));
+
+    const menuItems = Array.from(container.querySelectorAll<HTMLElement>('[role="menuitem"]'));
+    expect(document.activeElement?.textContent).toContain('Copy');
+    expect(menuItems[0].tabIndex).toBe(-1);
+    expect(menuItems[1].tabIndex).toBe(0);
+
+    act(() => document.dispatchEvent(new window.KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true })));
+    expect(document.activeElement?.textContent).toContain('Rename');
+
+    act(() => document.dispatchEvent(new window.KeyboardEvent('keydown', { key: 'End', bubbles: true })));
+    expect(document.activeElement?.textContent).toContain('Delete');
+
+    act(() => document.dispatchEvent(new window.KeyboardEvent('keydown', { key: 'Home', bubbles: true })));
+    expect(document.activeElement?.textContent).toContain('Copy');
+
+    act(() => document.dispatchEvent(new window.KeyboardEvent('keydown', { key: 'ArrowUp', bubbles: true })));
+    expect(document.activeElement?.textContent).toContain('Delete');
+    expect(container.querySelector('[role="separator"]')).not.toBeNull();
+  });
+
+  it('activates focused items with Enter and Space', async () => {
+    const onCopy = vi.fn();
+    const onDelete = vi.fn();
+    const onItemClick = vi.fn();
+    const onClose = vi.fn();
+    const trigger = document.createElement('button');
+    document.body.appendChild(trigger);
+    trigger.focus();
+    const items: ContextMenuItem[] = [
+      { id: 'copy', label: 'Copy', onClick: onCopy },
+      { id: 'delete', label: 'Delete', onClick: onDelete },
+    ];
+
+    act(() => root.render(
+      <ContextMenu
+        items={items}
+        position={{ x: 0, y: 0 }}
+        visible
+        onClose={onClose}
+        onItemClick={onItemClick}
+      />,
+    ));
+
+    await act(async () => {
+      document.dispatchEvent(new window.KeyboardEvent('keydown', { key: 'Enter', bubbles: true }));
+    });
+    expect(onCopy).toHaveBeenCalledOnce();
+    expect(onItemClick).toHaveBeenCalledWith(items[0], undefined);
+    expect(onClose).toHaveBeenCalledOnce();
+    expect(document.activeElement).toBe(trigger);
+
+    act(() => {
+      const firstItem = container.querySelector<HTMLElement>('[role="menuitem"]');
+      firstItem?.focus();
+      document.dispatchEvent(new window.KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true }));
+    });
+    await act(async () => {
+      document.dispatchEvent(new window.KeyboardEvent('keydown', { key: ' ', bubbles: true }));
+    });
+    expect(onDelete).toHaveBeenCalledOnce();
+  });
+
+  it('restores the pre-open focus snapshot on Escape', () => {
+    const trigger = document.createElement('button');
+    document.body.appendChild(trigger);
+    trigger.focus();
+    const onClose = vi.fn();
+
+    act(() => root.render(
+      <ContextMenu
+        items={[{ id: 'copy', label: 'Copy' }]}
+        position={{ x: 0, y: 0 }}
+        visible
+        onClose={onClose}
+      />,
+    ));
+    expect(document.activeElement?.getAttribute('role')).toBe('menuitem');
+
+    act(() => document.dispatchEvent(new window.KeyboardEvent('keydown', { key: 'Escape', bubbles: true })));
+
+    expect(onClose).toHaveBeenCalledOnce();
+    expect(document.activeElement).toBe(trigger);
+  });
+
+  it('opens a submenu from the keyboard and keeps keyboard handling in the owning menu', () => {
+    const items: ContextMenuItem[] = [{
+      id: 'share',
+      label: 'Share',
+      submenu: [
+        { id: 'unavailable', label: 'Unavailable', disabled: true },
+        { id: 'email', label: 'Email' },
+        { id: 'link', label: 'Copy link' },
+      ],
+    }];
+
+    act(() => root.render(
+      <ContextMenu items={items} position={{ x: 0, y: 0 }} visible onClose={vi.fn()} />,
+    ));
+    const parentItem = container.querySelector<HTMLElement>('[role="menuitem"]');
+    expect(parentItem?.getAttribute('aria-haspopup')).toBe('menu');
+
+    act(() => document.dispatchEvent(new window.KeyboardEvent('keydown', { key: 'Enter', bubbles: true })));
+    act(() => vi.runOnlyPendingTimers());
+
+    expect(parentItem?.getAttribute('aria-expanded')).toBe('true');
+    expect(document.activeElement?.textContent).toContain('Email');
+
+    act(() => document.dispatchEvent(new window.KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true })));
+    expect(document.activeElement?.textContent).toContain('Copy link');
+
+    act(() => document.dispatchEvent(new window.KeyboardEvent('keydown', { key: 'ArrowLeft', bubbles: true })));
+    expect(document.activeElement).toBe(parentItem);
+    expect(parentItem?.getAttribute('aria-expanded')).toBe('false');
+  });
+});
diff --git a/src/web-ui/src/shared/context-menu-system/components/ui/ContextMenu.tsx b/src/web-ui/src/shared/context-menu-system/components/ui/ContextMenu.tsx
index d8eaf2cf0a..5bdfbfe57c 100644
--- a/src/web-ui/src/shared/context-menu-system/components/ui/ContextMenu.tsx
+++ b/src/web-ui/src/shared/context-menu-system/components/ui/ContextMenu.tsx
@@ -1,6 +1,6 @@
  
 
-import React, { useEffect, useRef, useCallback, useState } from 'react';
+import React, { useEffect, useLayoutEffect, useMemo, useRef, useCallback, useState } from 'react';
 import { ContextMenuProps, ContextMenuItem } from './types';
 import { createLogger } from '@/shared/utils/logger';
 import './ContextMenu.scss';
@@ -11,6 +11,12 @@ const log = createLogger('ContextMenu');
 const SUBMENU_OPEN_DELAY = 150;   
 const SUBMENU_CLOSE_DELAY = 300;  
 const SAFE_TRIANGLE_TOLERANCE = 50; 
+const CONTEXT_MENU_EXIT_DURATION_MS = 100;
+
+interface InternalContextMenuProps extends ContextMenuProps {
+  autoFocusOnOpen?: boolean;
+  onKeyboardBack?: () => void;
+}
 
  
 function isPointInTriangle(
@@ -33,21 +39,45 @@ function isPointInTriangle(
   return !(hasNeg && hasPos);
 }
 
-export const ContextMenu: React.FC<ContextMenuProps> = ({
+export const ContextMenu: React.FC<InternalContextMenuProps> = ({
   items,
   position,
   visible,
   context,
   onClose,
-  onItemClick
+  onItemClick,
+  autoFocusOnOpen = true,
+  onKeyboardBack,
 }) => {
   const menuRef = useRef<HTMLDivElement>(null);
-  
+  const itemRefs = useRef(new Map<number, HTMLDivElement>());
+  const previousFocusRef = useRef<HTMLElement | null>(null);
+  const wasVisibleRef = useRef(false);
+  const exitTimerRef = useRef<number | null>(null);
+  const enterFrameRef = useRef<number | null>(null);
+  const submenuFocusFrameRef = useRef<number | null>(null);
+  const [isPresent, setIsPresent] = useState(visible);
+  const [motionPhase, setMotionPhase] = useState<'entering' | 'entered' | 'exiting'>(
+    visible ? 'entering' : 'exiting',
+  );
+
   
   const [activeSubmenuId, setActiveSubmenuId] = useState<string | null>(null);
   const submenuOpenTimerRef = useRef<number | null>(null);
   const submenuCloseTimerRef = useRef<number | null>(null);
-  
+  const focusableItemIndices = useMemo(
+    () => items.reduce<number[]>((indices, item, index) => {
+      if (!item.separator && !item.disabled) {
+        indices.push(index);
+      }
+      return indices;
+    }, []),
+    [items],
+  );
+  const [focusedItemIndex, setFocusedItemIndex] = useState(
+    () => focusableItemIndices[0] ?? -1,
+  );
+
   
   const lastMousePosRef = useRef<{ x: number; y: number } | null>(null);
   const menuItemRectRef = useRef<DOMRect | null>(null);
@@ -65,7 +95,99 @@ export const ContextMenu: React.FC<ContextMenuProps> = ({
     }
   }, []);
 
-  
+  const restorePreviousFocus = useCallback(() => {
+    const previousFocus = previousFocusRef.current;
+    if (previousFocus?.isConnected && !previousFocus.matches(':disabled')) {
+      previousFocus.focus();
+      return;
+    }
+
+    const activeElement = document.activeElement;
+    if (activeElement instanceof window.HTMLElement && menuRef.current?.contains(activeElement)) {
+      activeElement.blur();
+    }
+  }, []);
+
+  const focusItemAtIndex = useCallback((index: number) => {
+    setFocusedItemIndex(index);
+    itemRefs.current.get(index)?.focus();
+  }, []);
+
+  useLayoutEffect(() => {
+    if (visible && !wasVisibleRef.current) {
+      previousFocusRef.current = document.activeElement instanceof window.HTMLElement
+        ? document.activeElement
+        : null;
+      const firstItemIndex = focusableItemIndices[0] ?? -1;
+      setFocusedItemIndex(firstItemIndex);
+
+      if (autoFocusOnOpen) {
+        if (firstItemIndex >= 0) {
+          itemRefs.current.get(firstItemIndex)?.focus();
+        } else {
+          menuRef.current?.focus();
+        }
+      }
+    } else if (!visible && wasVisibleRef.current) {
+      const activeElement = document.activeElement;
+      if (activeElement instanceof window.HTMLElement && menuRef.current?.contains(activeElement)) {
+        restorePreviousFocus();
+      }
+    }
+
+    wasVisibleRef.current = visible;
+  }, [autoFocusOnOpen, focusableItemIndices, restorePreviousFocus, visible]);
+
+  useEffect(() => {
+    if (!focusableItemIndices.includes(focusedItemIndex)) {
+      setFocusedItemIndex(focusableItemIndices[0] ?? -1);
+    }
+  }, [focusableItemIndices, focusedItemIndex]);
+
+  useEffect(() => {
+    if (exitTimerRef.current !== null) {
+      window.clearTimeout(exitTimerRef.current);
+      exitTimerRef.current = null;
+    }
+    if (enterFrameRef.current !== null) {
+      window.cancelAnimationFrame(enterFrameRef.current);
+      enterFrameRef.current = null;
+    }
+
+    if (visible) {
+      setIsPresent(true);
+      setMotionPhase('entering');
+      enterFrameRef.current = window.requestAnimationFrame(() => {
+        enterFrameRef.current = window.requestAnimationFrame(() => {
+          setMotionPhase('entered');
+          enterFrameRef.current = null;
+        });
+      });
+    } else {
+      setMotionPhase('exiting');
+      exitTimerRef.current = window.setTimeout(() => {
+        setIsPresent(false);
+        exitTimerRef.current = null;
+      }, CONTEXT_MENU_EXIT_DURATION_MS);
+    }
+
+    return () => {
+      if (exitTimerRef.current !== null) {
+        window.clearTimeout(exitTimerRef.current);
+        exitTimerRef.current = null;
+      }
+      if (enterFrameRef.current !== null) {
+        window.cancelAnimationFrame(enterFrameRef.current);
+        enterFrameRef.current = null;
+      }
+      if (submenuFocusFrameRef.current !== null) {
+        window.cancelAnimationFrame(submenuFocusFrameRef.current);
+        submenuFocusFrameRef.current = null;
+      }
+    };
+  }, [visible]);
+
+
   const handleMenuItemMouseEnter = useCallback((
     item: ContextMenuItem,
     index: number,
@@ -208,10 +330,7 @@ export const ContextMenu: React.FC<ContextMenuProps> = ({
   }, [activeSubmenuId, visible]);
 
   
-  const handleItemClick = useCallback(async (item: ContextMenuItem, event: React.MouseEvent) => {
-    event.preventDefault();
-    event.stopPropagation();
-
+  const activateItem = useCallback(async (item: ContextMenuItem, restoreFocusAfter = false) => {
     if (item.disabled || item.separator) {
       return;
     }
@@ -237,28 +356,133 @@ export const ContextMenu: React.FC<ContextMenuProps> = ({
     if (onItemClick) {
       onItemClick(item, context);
     }
-  }, [context, onItemClick, onClose]);
+
+    if (restoreFocusAfter) {
+      restorePreviousFocus();
+    }
+    onClose();
+  }, [context, onItemClick, onClose, restorePreviousFocus]);
+
+  const handleItemClick = useCallback((item: ContextMenuItem, event: React.MouseEvent) => {
+    event.preventDefault();
+    event.stopPropagation();
+    void activateItem(item);
+  }, [activateItem]);
+
+  const openSubmenuFromKeyboard = useCallback((item: ContextMenuItem, index: number) => {
+    if (!item.submenu?.length || item.disabled) {
+      return;
+    }
+
+    clearAllTimers();
+    setActiveSubmenuId(item.id || `item-${index}`);
+    if (submenuFocusFrameRef.current !== null) {
+      window.cancelAnimationFrame(submenuFocusFrameRef.current);
+    }
+    submenuFocusFrameRef.current = window.requestAnimationFrame(() => {
+      const firstSubmenuItem = itemRefs.current.get(index)?.querySelector<HTMLElement>(
+        '.context-menu-submenu [role="menu"] > [role="menuitem"]:not([aria-disabled="true"])',
+      );
+      firstSubmenuItem?.focus();
+      submenuFocusFrameRef.current = null;
+    });
+  }, [clearAllTimers]);
 
   
   const handleKeyDown = useCallback((event: KeyboardEvent) => {
     if (!visible) return;
 
+    const activeElement = document.activeElement instanceof window.HTMLElement
+      ? document.activeElement
+      : null;
+    const owningMenu = activeElement?.closest('[role="menu"]');
+    if (owningMenu !== menuRef.current) {
+      return;
+    }
+
+    const currentPosition = focusableItemIndices.indexOf(focusedItemIndex);
+    const currentItem = focusedItemIndex >= 0 ? items[focusedItemIndex] : undefined;
+
     switch (event.key) {
       case 'Escape':
         event.preventDefault();
+        event.stopPropagation();
+        restorePreviousFocus();
         onClose();
         break;
-      case 'ArrowDown':
-        
+      case 'ArrowDown': {
+        event.preventDefault();
+        event.stopPropagation();
+        if (focusableItemIndices.length > 0) {
+          const nextPosition = currentPosition < 0
+            ? 0
+            : (currentPosition + 1) % focusableItemIndices.length;
+          focusItemAtIndex(focusableItemIndices[nextPosition]);
+        }
         break;
-      case 'ArrowUp':
-        
+      }
+      case 'ArrowUp': {
+        event.preventDefault();
+        event.stopPropagation();
+        if (focusableItemIndices.length > 0) {
+          const previousPosition = currentPosition <= 0
+            ? focusableItemIndices.length - 1
+            : currentPosition - 1;
+          focusItemAtIndex(focusableItemIndices[previousPosition]);
+        }
+        break;
+      }
+      case 'Home':
+        event.preventDefault();
+        event.stopPropagation();
+        if (focusableItemIndices.length > 0) {
+          focusItemAtIndex(focusableItemIndices[0]);
+        }
+        break;
+      case 'End':
+        event.preventDefault();
+        event.stopPropagation();
+        if (focusableItemIndices.length > 0) {
+          focusItemAtIndex(focusableItemIndices[focusableItemIndices.length - 1]);
+        }
         break;
       case 'Enter':
-        
+      case ' ':
+        event.preventDefault();
+        event.stopPropagation();
+        if (currentItem?.submenu?.length) {
+          openSubmenuFromKeyboard(currentItem, focusedItemIndex);
+        } else if (currentItem) {
+          void activateItem(currentItem, true);
+        }
+        break;
+      case 'ArrowRight':
+        if (currentItem?.submenu?.length) {
+          event.preventDefault();
+          event.stopPropagation();
+          openSubmenuFromKeyboard(currentItem, focusedItemIndex);
+        }
+        break;
+      case 'ArrowLeft':
+        if (onKeyboardBack) {
+          event.preventDefault();
+          event.stopPropagation();
+          onKeyboardBack();
+        }
         break;
     }
-  }, [visible, onClose]);
+  }, [
+    activateItem,
+    focusItemAtIndex,
+    focusedItemIndex,
+    focusableItemIndices,
+    items,
+    onClose,
+    onKeyboardBack,
+    openSubmenuFromKeyboard,
+    restorePreviousFocus,
+    visible,
+  ]);
 
   
   const handleClickOutside = useCallback((event: MouseEvent) => {
@@ -338,7 +562,7 @@ export const ContextMenu: React.FC<ContextMenuProps> = ({
 
   
   const adjustPosition = useCallback(() => {
-    if (!menuRef.current || !visible) return;
+    if (!menuRef.current || !isPresent) return;
 
     const menu = menuRef.current;
     const rect = menu.getBoundingClientRect();
@@ -371,20 +595,23 @@ export const ContextMenu: React.FC<ContextMenuProps> = ({
 
     menu.style.left = `${x}px`;
     menu.style.top = `${y}px`;
-  }, [position, visible]);
+    const originX = Math.min(Math.max(position.x - x, 8), Math.max(rect.width - 8, 8));
+    const originY = Math.min(Math.max(position.y - y, 8), Math.max(rect.height - 8, 8));
+    menu.style.setProperty('--context-menu-transform-origin', `${originX}px ${originY}px`);
+  }, [position, isPresent]);
 
   
   useEffect(() => {
-    if (visible) {
+    if (isPresent) {
       
-      requestAnimationFrame(adjustPosition);
+      window.requestAnimationFrame(adjustPosition);
     }
-  }, [visible, adjustPosition]);
+  }, [isPresent, adjustPosition]);
 
   
   const renderMenuItem = (item: ContextMenuItem, index: number) => {
     if (item.separator) {
-      return <div key={`separator-${index}`} className="context-menu-separator" data-bf-component="context-menu" data-bf-part="separator" />;
+      return <div key={`separator-${index}`} className="context-menu-separator" data-bf-component="context-menu" data-bf-part="separator" role="separator" />;
     }
 
     const itemId = item.id || `item-${index}`;
@@ -393,6 +620,13 @@ export const ContextMenu: React.FC<ContextMenuProps> = ({
 
     return (
       <div
+        ref={(element) => {
+          if (element) {
+            itemRefs.current.set(index, element);
+          } else {
+            itemRefs.current.delete(index);
+          }
+        }}
         key={itemId}
         className={`context-menu-item ${item.disabled ? 'disabled' : ''} ${isSubmenuActive ? 'submenu-active' : ''}`}
         onClick={(event) => handleItemClick(item, event)}
@@ -402,6 +636,12 @@ export const ContextMenu: React.FC<ContextMenuProps> = ({
         data-bf-component="context-menu"
         data-bf-part="item"
         data-bf-state={[item.disabled && 'disabled', isSubmenuActive && 'submenu-active'].filter(Boolean).join(' ') || undefined}
+        role="menuitem"
+        aria-disabled={item.disabled || undefined}
+        aria-haspopup={hasSubmenu ? 'menu' : undefined}
+        aria-expanded={hasSubmenu ? isSubmenuActive : undefined}
+        tabIndex={!item.disabled && index === focusedItemIndex ? 0 : -1}
+        data-menu-index={index}
       >
         {item.icon && (
           <span className="context-menu-item-icon" data-bf-component="context-menu" data-bf-part="icon">
@@ -433,6 +673,11 @@ export const ContextMenu: React.FC<ContextMenuProps> = ({
                 context={context}
                 onClose={onClose}
                 onItemClick={onItemClick}
+                autoFocusOnOpen={false}
+                onKeyboardBack={() => {
+                  setActiveSubmenuId(null);
+                  focusItemAtIndex(index);
+                }}
               />
             </div>
           </>
@@ -441,14 +686,14 @@ export const ContextMenu: React.FC<ContextMenuProps> = ({
     );
   };
 
-  if (!visible) {
+  if (!isPresent) {
     return null;
   }
 
   return (
     <div
       ref={menuRef}
-      className={`context-menu ${visible ? 'visible' : ''}`}
+      className="context-menu"
       style={{
         left: position.x,
         top: position.y
@@ -456,6 +701,12 @@ export const ContextMenu: React.FC<ContextMenuProps> = ({
       onContextMenu={(event) => event.preventDefault()}
       data-bf-component="context-menu"
       data-bf-part="root"
+      data-motion="presence"
+      data-state={motionPhase}
+      role="menu"
+      tabIndex={-1}
+      aria-hidden={(!visible || motionPhase === 'exiting') || undefined}
+      {...(!visible || motionPhase === 'exiting' ? { inert: '' } : {})}
     >
       {items.map(renderMenuItem)}
     </div>
diff --git a/src/web-ui/src/shared/context-system/components/ContextCard/ContextCard.scss b/src/web-ui/src/shared/context-system/components/ContextCard/ContextCard.scss
index 4301b4480e..a84f66e3f3 100644
--- a/src/web-ui/src/shared/context-system/components/ContextCard/ContextCard.scss
+++ b/src/web-ui/src/shared/context-system/components/ContextCard/ContextCard.scss
@@ -23,7 +23,12 @@
   backdrop-filter: $blur-base;
   -webkit-backdrop-filter: $blur-base;
   
-  transition: all $motion-base $easing-standard;
+  transition:
+    background-color $motion-base $easing-standard,
+    border-color $motion-base $easing-standard,
+    box-shadow $motion-base $easing-standard,
+    opacity $motion-base $easing-standard,
+    transform $motion-base $easing-standard;
   overflow: hidden;
   
   
@@ -190,7 +195,11 @@
     color: var(--bf-appearance-token-color-text-muted);
     border-radius: $size-radius-sm;
     cursor: pointer;
-    transition: all $motion-fast $easing-standard;
+    transition:
+      background-color $motion-fast $easing-standard,
+      color $motion-fast $easing-standard,
+      opacity $motion-fast $easing-standard,
+      transform $motion-fast $easing-standard;
     
     &:hover {
       background: var(--bf-appearance-token-element-bg-medium);
@@ -362,3 +371,9 @@
   }
 }
 
+@media (prefers-reduced-motion: reduce) {
+  .bitfun-context-card__spinner {
+    animation: none;
+    transform: none;
+  }
+}
diff --git a/src/web-ui/src/shared/context-system/components/ContextList/ContextList.scss b/src/web-ui/src/shared/context-system/components/ContextList/ContextList.scss
index c6a3190611..274667ade2 100644
--- a/src/web-ui/src/shared/context-system/components/ContextList/ContextList.scss
+++ b/src/web-ui/src/shared/context-system/components/ContextList/ContextList.scss
@@ -55,17 +55,21 @@
     border: 1px solid var(--bf-appearance-token-border-subtle);
     border-radius: $size-radius-sm;
     cursor: pointer;
-    transition: all $motion-fast $easing-standard;
-    
-    &:hover {
-      background: var(--bf-appearance-token-color-error-bg);
-      border-color: var(--bf-appearance-token-color-error-border);
-      color: var(--bf-appearance-token-color-error);
-    }
+    transition:
+      background-color $motion-fast $easing-standard,
+      border-color $motion-fast $easing-standard,
+      color $motion-fast $easing-standard,
+      opacity $motion-fast $easing-standard,
+      transform $motion-fast $easing-standard;
     
     &:active {
       transform: scale(0.98);
     }
+
+    &:disabled {
+      cursor: default;
+      opacity: 0.45;
+    }
   }
   
   
@@ -73,7 +77,7 @@
   &__items {
     display: flex;
     flex-direction: column;
-    gap: $size-gap-2;
+    gap: 0;
     overflow-y: auto;
     overflow-x: hidden;
     padding: 0 $size-gap-2;
@@ -81,8 +85,40 @@
   }
   
   &__item {
-    
+    display: grid;
+    grid-template-rows: 1fr;
     width: 100%;
+    opacity: 1;
+    transform: translateX(0);
+    transition:
+      grid-template-rows 160ms $easing-decelerate,
+      opacity 110ms $easing-standard,
+      transform 140ms $easing-decelerate;
+
+    @starting-style {
+      opacity: 0;
+      transform: translateY(4px);
+    }
+
+    &[data-exiting='true'] {
+      grid-template-rows: 0fr;
+      opacity: 0;
+      transform: translateX(6px);
+      pointer-events: none;
+    }
+  }
+
+  &__item-inner {
+    min-height: 0;
+    overflow: hidden;
+
+    .bitfun-context-list__item[data-exiting='true'] & {
+      pointer-events: none;
+    }
+
+    > .bitfun-context-card {
+      margin-bottom: $size-gap-2;
+    }
   }
   
   
@@ -121,3 +157,21 @@
   }
 }
 
+@media (hover: hover) and (pointer: fine) {
+  .bitfun-context-list__clear-btn:not(:disabled):hover {
+    background: var(--bf-appearance-token-color-error-bg);
+    border-color: var(--bf-appearance-token-color-error-border);
+    color: var(--bf-appearance-token-color-error);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .bitfun-context-list__item {
+    transition: none;
+
+    @starting-style {
+      opacity: 1;
+      transform: none;
+    }
+  }
+}
diff --git a/src/web-ui/src/shared/context-system/components/ContextList/ContextList.test.tsx b/src/web-ui/src/shared/context-system/components/ContextList/ContextList.test.tsx
new file mode 100644
index 0000000000..990018319d
--- /dev/null
+++ b/src/web-ui/src/shared/context-system/components/ContextList/ContextList.test.tsx
@@ -0,0 +1,132 @@
+// @vitest-environment jsdom
+
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { ContextItem } from '../../../types/context';
+import { useContextStore } from '../../../stores/contextStore';
+import { ContextList } from './ContextList';
+
+const storage = vi.hoisted(() => {
+  const values = new Map<string, string>();
+  const implementation: Storage = {
+    get length() {
+      return values.size;
+    },
+    clear: () => values.clear(),
+    getItem: (key) => values.get(key) ?? null,
+    key: (index) => [...values.keys()][index] ?? null,
+    removeItem: (key) => values.delete(key),
+    setItem: (key, value) => values.set(key, value),
+  };
+  Object.defineProperty(globalThis, 'localStorage', {
+    configurable: true,
+    value: implementation,
+  });
+  return implementation;
+});
+
+vi.mock('@/infrastructure/i18n', () => ({
+  useI18n: () => ({ t: (key: string) => key }),
+}));
+
+vi.mock('../ContextCard/ContextCard', () => ({
+  ContextCard: ({ context, onRemove }: {
+    context: ContextItem;
+    onRemove?: (id: string) => void;
+  }) => (
+    <button
+      type="button"
+      data-context-id={context.id}
+      onClick={() => onRemove?.(context.id)}
+    >
+      {context.id}
+    </button>
+  ),
+}));
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+const context = (id: string): ContextItem => ({
+  id,
+  type: 'file',
+  timestamp: 1,
+  filePath: `/${id}.ts`,
+  fileName: `${id}.ts`,
+});
+
+const contextIds = () => useContextStore.getState().contexts.map(item => item.id);
+
+describe('ContextList removal presence', () => {
+  let container: HTMLDivElement | null;
+  let root: Root | null;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.stubGlobal('matchMedia', vi.fn(() => ({ matches: false })));
+    storage.clear();
+    useContextStore.setState({
+      contexts: [context('a'), context('b'), context('c')],
+      validationStates: new Map(),
+      validatingIds: new Set(),
+    });
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+    act(() => root?.render(<ContextList />));
+  });
+
+  afterEach(() => {
+    if (root) act(() => root?.unmount());
+    container?.remove();
+    useContextStore.setState({
+      contexts: [],
+      validationStates: new Map(),
+      validatingIds: new Set(),
+    });
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+  });
+
+  it('retains sequential removals in stable order until both exits finish', () => {
+    const removeButton = (id: string) => (
+      container?.querySelector<HTMLButtonElement>(`[data-context-id="${id}"]`)
+    );
+
+    act(() => removeButton('b')?.click());
+    act(() => removeButton('c')?.click());
+
+    expect([...(container?.querySelectorAll('[data-context-id]') ?? [])]
+      .map(element => element.getAttribute('data-context-id'))).toEqual(['a', 'b', 'c']);
+    expect(container?.querySelector('[data-context-id="b"]')
+      ?.closest('.bitfun-context-list__item')?.getAttribute('data-exiting')).toBe('true');
+    expect(container?.querySelector('[data-context-id="c"]')
+      ?.closest('.bitfun-context-list__item')?.getAttribute('data-exiting')).toBe('true');
+    expect(contextIds()).toEqual(['a', 'b', 'c']);
+
+    act(() => vi.advanceTimersByTime(159));
+    expect(contextIds()).toEqual(['a', 'b', 'c']);
+
+    act(() => vi.advanceTimersByTime(1));
+    expect(contextIds()).toEqual(['a']);
+  });
+
+  it('commits a requested removal if the list unmounts during its exit', () => {
+    act(() => container?.querySelector<HTMLButtonElement>('[data-context-id="b"]')?.click());
+
+    act(() => root?.unmount());
+    root = null;
+
+    expect(contextIds()).toEqual(['a', 'c']);
+  });
+
+  it('removes immediately when reduced motion is requested', () => {
+    vi.stubGlobal('matchMedia', vi.fn(() => ({ matches: true })));
+
+    act(() => container?.querySelector<HTMLButtonElement>('[data-context-id="b"]')?.click());
+
+    expect(contextIds()).toEqual(['a', 'c']);
+    expect(container?.querySelector('[data-context-id="b"]')).toBeNull();
+  });
+});
diff --git a/src/web-ui/src/shared/context-system/components/ContextList/ContextList.tsx b/src/web-ui/src/shared/context-system/components/ContextList/ContextList.tsx
index 9eabaab8f9..643c3c3f2c 100644
--- a/src/web-ui/src/shared/context-system/components/ContextList/ContextList.tsx
+++ b/src/web-ui/src/shared/context-system/components/ContextList/ContextList.tsx
@@ -1,10 +1,11 @@
  
 
-import React, { useCallback } from 'react';
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { AlertCircle, X } from 'lucide-react';
 import { useContextStore, selectContexts } from '../../../stores/contextStore';
 import { ContextCard } from '../ContextCard/ContextCard';
 import { useI18n } from '@/infrastructure/i18n';
+import { isReducedMotionPreferred } from '@/shared/utils/motionPreference';
 import './ContextList.scss';
 
 export interface ContextListProps {
@@ -16,6 +17,8 @@ export interface ContextListProps {
   onContextClick?: (contextId: string) => void;
 }
 
+const CONTEXT_ROW_EXIT_MS = 160;
+
 export const ContextList: React.FC<ContextListProps> = ({
   compact = false,
   interactive = true,
@@ -27,24 +30,71 @@ export const ContextList: React.FC<ContextListProps> = ({
   const { t } = useI18n('components');
   const contexts = useContextStore(selectContexts);
   const removeContext = useContextStore(state => state.removeContext);
-  const clearContexts = useContextStore(state => state.clearContexts);
+  const [leavingContextIds, setLeavingContextIds] = useState<Set<string>>(new Set());
+  const exitTimersRef = useRef<Map<string, number>>(new Map());
+
+  useEffect(() => () => {
+    const pendingContextIds = [...exitTimersRef.current.keys()];
+    exitTimersRef.current.forEach(timer => window.clearTimeout(timer));
+    exitTimersRef.current.clear();
+    pendingContextIds.forEach(removeContext);
+  }, [removeContext]);
+
+  const removeAfterExit = useCallback((contextIds: string[]) => {
+    if (isReducedMotionPreferred()) {
+      contextIds.forEach(removeContext);
+      return;
+    }
+
+    setLeavingContextIds(previous => {
+      const next = new Set(previous);
+      contextIds.forEach(id => next.add(id));
+      return next;
+    });
+
+    contextIds.forEach((contextId) => {
+      const existingTimer = exitTimersRef.current.get(contextId);
+      if (existingTimer) window.clearTimeout(existingTimer);
+      const timer = window.setTimeout(() => {
+        exitTimersRef.current.delete(contextId);
+        removeContext(contextId);
+        setLeavingContextIds(previous => {
+          const next = new Set(previous);
+          next.delete(contextId);
+          return next;
+        });
+      }, CONTEXT_ROW_EXIT_MS);
+      exitTimersRef.current.set(contextId, timer);
+    });
+  }, [removeContext]);
   
   const handleRemove = useCallback((id: string) => {
-    removeContext(id);
-  }, [removeContext]);
+    if (!contexts.some(item => item.id === id) || leavingContextIds.has(id)) return;
+    removeAfterExit([id]);
+  }, [contexts, leavingContextIds, removeAfterExit]);
   
   const handleClearAll = useCallback(async () => {
     
-    if (await window.confirm(t('contextSystem.contextList.clearAllConfirm', { count: contexts.length }))) {
-      clearContexts();
+    if (
+      leavingContextIds.size === 0
+      && await window.confirm(t('contextSystem.contextList.clearAllConfirm', { count: contexts.length }))
+    ) {
+      removeAfterExit(contexts.map(context => context.id));
     }
-  }, [contexts.length, clearContexts, t]);
+  }, [contexts, leavingContextIds.size, removeAfterExit, t]);
   
   const handleCardClick = useCallback((contextId: string) => {
     onContextClick?.(contextId);
   }, [onContextClick]);
+
+  const renderedContexts = useMemo(() => {
+    return contexts.map(context => ({
+      context,
+      exiting: leavingContextIds.has(context.id),
+    }));
+  }, [contexts, leavingContextIds]);
   
-  if (contexts.length === 0) {
+  if (renderedContexts.length === 0) {
     return (
       <div className={`bitfun-context-list bitfun-context-list--empty ${className}`} data-bf-component="context-list" data-bf-part="root" data-bf-state="empty">
         <div className="bitfun-context-list__empty-state" data-bf-component="context-list" data-bf-part="empty">
@@ -74,6 +124,7 @@ export const ContextList: React.FC<ContextListProps> = ({
         <button
           className="bitfun-context-list__clear-btn"
           onClick={handleClearAll}
+          disabled={leavingContextIds.size > 0}
           title={t('contextSystem.contextList.clearAllTitle')}
           data-bf-component="context-list"
           data-bf-part="clear"
@@ -90,21 +141,26 @@ export const ContextList: React.FC<ContextListProps> = ({
         data-bf-component="context-list"
         data-bf-part="items"
       >
-        {contexts.map((context) => (
+        {renderedContexts.map(({ context, exiting }) => (
           <div
             key={context.id}
             className="bitfun-context-list__item"
-            onClick={() => handleCardClick(context.id)}
+            data-exiting={exiting ? 'true' : 'false'}
+            aria-hidden={exiting || undefined}
+            {...(exiting ? { inert: '' } : {})}
+            onClick={exiting ? undefined : () => handleCardClick(context.id)}
             data-bf-component="context-list"
             data-bf-part="item"
           >
-            <ContextCard
-              context={context}
-              onRemove={handleRemove}
-              compact={compact}
-              interactive={interactive}
-              showPreview={showPreview}
-            />
+            <div className="bitfun-context-list__item-inner">
+              <ContextCard
+                context={context}
+                onRemove={exiting ? undefined : handleRemove}
+                compact={compact}
+                interactive={interactive && !exiting}
+                showPreview={showPreview}
+              />
+            </div>
           </div>
         ))}
       </div>
@@ -113,4 +169,3 @@ export const ContextList: React.FC<ContextListProps> = ({
 };
 
 export default ContextList;
-
diff --git a/src/web-ui/src/shared/context-system/drag-drop/ContextDropZone.scss b/src/web-ui/src/shared/context-system/drag-drop/ContextDropZone.scss
index f7528d06dd..1fe315e57f 100644
--- a/src/web-ui/src/shared/context-system/drag-drop/ContextDropZone.scss
+++ b/src/web-ui/src/shared/context-system/drag-drop/ContextDropZone.scss
@@ -8,9 +8,6 @@
   position: relative;
   width: 100%;
   
-  transition: all $motion-base $easing-standard;
-  
-  
   pointer-events: auto !important;
   
   
@@ -38,7 +35,6 @@
     
     pointer-events: none;
     
-    animation: bitfun-drop-zone-pulse 1.5s ease-in-out infinite;
   }
   
   &__indicator {
@@ -53,12 +49,10 @@
   &__icon {
     color: var(--bf-appearance-token-color-accent-500);
     filter: drop-shadow(0 0 12px color-mix(in srgb, var(--bf-appearance-token-color-accent-500) 60%, transparent));
-    animation: bitfun-drop-zone-scale 1.5s ease-in-out infinite;
     
     &--disabled {
       color: var(--bf-appearance-token-color-text-disabled);
       filter: none;
-      animation: none;
     }
   }
   
@@ -74,29 +68,4 @@
       text-shadow: none;
     }
   }
-  
-  
-  
 }
-
-
-
-@keyframes bitfun-drop-zone-pulse {
-  0%, 100% {
-    opacity: 1;
-  }
-  50% {
-    opacity: 0.85;
-  }
-}
-
-@keyframes bitfun-drop-zone-scale {
-  0%, 100% {
-    transform: scale(1);
-  }
-  50% {
-    transform: scale(1.15);
-  }
-}
-
-
diff --git a/src/web-ui/src/shared/context-system/drag-drop/ContextDropZone.tsx b/src/web-ui/src/shared/context-system/drag-drop/ContextDropZone.tsx
index 99ebbcd724..1db6219af7 100644
--- a/src/web-ui/src/shared/context-system/drag-drop/ContextDropZone.tsx
+++ b/src/web-ui/src/shared/context-system/drag-drop/ContextDropZone.tsx
@@ -13,13 +13,15 @@ export interface ContextDropZoneProps {
   children?: React.ReactNode;
   className?: string;
   onContextAdded?: (context: ContextItem) => void;
+  disabled?: boolean;
 }
 
 export const ContextDropZone: React.FC<ContextDropZoneProps> = ({
   acceptedTypes,
   children,
   className = '',
-  onContextAdded
+  onContextAdded,
+  disabled = false,
 }) => {
   const [isDragOver, setIsDragOver] = useState(false);
   const [canAccept, setCanAccept] = useState(false);
@@ -40,10 +42,11 @@ export const ContextDropZone: React.FC<ContextDropZoneProps> = ({
     acceptedTypes: acceptedTypesArray,
     
     canAccept: (payload: DragPayload<ContextItem>) => {
-      return acceptedTypesArray.includes(payload.dataType);
+      return !disabled && acceptedTypesArray.includes(payload.dataType);
     },
     
     onDrop: async (payload: DragPayload<ContextItem>) => {
+      if (disabled) return;
       const context = payload.data;
       
       
@@ -75,7 +78,7 @@ export const ContextDropZone: React.FC<ContextDropZoneProps> = ({
     onDragOver: () => {
       
     }
-  }), [acceptedTypesArray, addContext, updateValidation, onContextAdded]);
+  }), [acceptedTypesArray, addContext, disabled, updateValidation, onContextAdded]);
   
   
   const dropTargetRef = useRef(dropTarget);
diff --git a/src/web-ui/src/shared/notification-system/appearance.ts b/src/web-ui/src/shared/notification-system/appearance.ts
index 52a850561c..e4f560d7f8 100644
--- a/src/web-ui/src/shared/notification-system/appearance.ts
+++ b/src/web-ui/src/shared/notification-system/appearance.ts
@@ -12,6 +12,7 @@ export const notificationAppearanceDescriptor: AppearanceSurfaceDescriptor = {
     { id: 'itemActions' },
     { id: 'itemClose' },
     { id: 'progressItem' },
+    { id: 'progressIcon' },
     { id: 'progressBar' },
     { id: 'progressFill' },
     { id: 'loadingItem' },
diff --git a/src/web-ui/src/shared/notification-system/components/LoadingNotification.scss b/src/web-ui/src/shared/notification-system/components/LoadingNotification.scss
index 3b98e471f8..c8350e9714 100644
--- a/src/web-ui/src/shared/notification-system/components/LoadingNotification.scss
+++ b/src/web-ui/src/shared/notification-system/components/LoadingNotification.scss
@@ -43,7 +43,7 @@
   
   &__spinner {
     color: var(--bf-appearance-token-color-warning);
-    animation: bitfun-spin 1s linear infinite;
+    animation: bitfun-loading-notification-spin 1s linear infinite;
   }
 
   
@@ -101,7 +101,10 @@
     border-radius: $size-radius-sm;
     color: var(--bf-appearance-token-color-text-muted);
     cursor: pointer;
-    transition: all $motion-base $easing-standard;
+    transition:
+      background-color $motion-base $easing-standard,
+      color $motion-base $easing-standard,
+      transform $motion-base $easing-standard;
 
     &:hover {
       background: var(--bf-appearance-token-element-bg-base);
@@ -115,7 +118,7 @@
 }
 
 
-@keyframes bitfun-spin {
+@keyframes bitfun-loading-notification-spin {
   from {
     transform: rotate(0deg);
   }
@@ -136,3 +139,10 @@
   }
 }
 
+@media (prefers-reduced-motion: reduce) {
+  .loading-notification,
+  .loading-notification__spinner {
+    animation: none;
+    transform: none;
+  }
+}
diff --git a/src/web-ui/src/shared/notification-system/components/NotificationCenter.scss b/src/web-ui/src/shared/notification-system/components/NotificationCenter.scss
index 4d03510964..407e0c9b59 100644
--- a/src/web-ui/src/shared/notification-system/components/NotificationCenter.scss
+++ b/src/web-ui/src/shared/notification-system/components/NotificationCenter.scss
@@ -53,7 +53,10 @@
     border-radius: $size-radius-sm;
     color: var(--bf-appearance-token-color-text-secondary);
     cursor: pointer;
-    transition: all $motion-base $easing-standard;
+    transition:
+      background-color $motion-base $easing-standard,
+      color $motion-base $easing-standard,
+      transform $motion-base $easing-standard;
 
     &:hover {
       background: var(--bf-appearance-token-element-bg-base);
@@ -94,7 +97,10 @@
     font-weight: $font-weight-medium;
     color: var(--bf-appearance-token-color-text-secondary);
     cursor: pointer;
-    transition: all $motion-base $easing-standard;
+    transition:
+      background-color $motion-base $easing-standard,
+      border-color $motion-base $easing-standard,
+      color $motion-base $easing-standard;
     white-space: nowrap;
     border-radius: $size-radius-sm $size-radius-sm 0 0;
 
@@ -169,7 +175,10 @@
     gap: $size-gap-3;
     padding: $size-gap-3 $size-gap-4;
     cursor: pointer;
-    transition: all $motion-base $easing-standard;
+    transition:
+      background-color $motion-base $easing-standard,
+      border-color $motion-base $easing-standard,
+      transform $motion-base $easing-standard;
     border-bottom: 1px solid transparent;
 
     &:hover {
@@ -357,10 +366,12 @@
   }
 
   &__item-progress-fill {
+    width: 100%;
     height: 100%;
     background: linear-gradient(90deg, var(--bf-appearance-token-color-accent-600), var(--bf-appearance-token-color-purple-500));
     border-radius: 2px;
-    transition: width 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+    transform-origin: left center;
+    transition: transform 0.3s cubic-bezier(0.4, 0, 0.2, 1);
 
     &.is-completed {
       background: var(--bf-appearance-token-color-success);
@@ -409,7 +420,11 @@
     color: var(--bf-appearance-token-color-text-muted);
     cursor: pointer;
     opacity: 0;
-    transition: all $motion-base $easing-standard;
+    transition:
+      background-color $motion-base $easing-standard,
+      color $motion-base $easing-standard,
+      opacity $motion-base $easing-standard,
+      transform $motion-base $easing-standard;
 
     &:hover {
       background: var(--bf-appearance-token-element-bg-base);
@@ -436,7 +451,11 @@
     color: var(--bf-appearance-token-color-text-muted);
     cursor: pointer;
     opacity: 0;
-    transition: all $motion-base $easing-standard;
+    transition:
+      background-color $motion-base $easing-standard,
+      color $motion-base $easing-standard,
+      opacity $motion-base $easing-standard,
+      transform $motion-base $easing-standard;
 
     &:hover {
       background: var(--bf-appearance-token-element-bg-base);
@@ -564,10 +583,12 @@
   }
 
   &__active-task-progress-fill {
+    width: 100%;
     height: 100%;
     background: linear-gradient(90deg, var(--bf-appearance-token-color-accent-600), var(--bf-appearance-token-color-purple-500));
     border-radius: 1px;
-    transition: width 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+    transform-origin: left center;
+    transition: transform 0.3s cubic-bezier(0.4, 0, 0.2, 1);
   }
 
   
@@ -637,3 +658,14 @@
   }
 }
 
+@media (prefers-reduced-motion: reduce) {
+  .notification-center__spinner {
+    animation: none;
+    transform: none;
+  }
+
+  .notification-center__item-progress-fill,
+  .notification-center__active-task-progress-fill {
+    transition: none;
+  }
+}
diff --git a/src/web-ui/src/shared/notification-system/components/NotificationCenter.tsx b/src/web-ui/src/shared/notification-system/components/NotificationCenter.tsx
index 906a95f4d0..5b5b68e76e 100644
--- a/src/web-ui/src/shared/notification-system/components/NotificationCenter.tsx
+++ b/src/web-ui/src/shared/notification-system/components/NotificationCenter.tsx
@@ -227,7 +227,7 @@ export const NotificationCenter: React.FC = () => {
               <div className="notification-center__active-task-progress-bar">
                 <div
                   className="notification-center__active-task-progress-fill"
-                  style={{ width: `${notification.progress || 0}%` }}
+                  style={{ transform: `scaleX(${Math.max(0, Math.min(100, notification.progress || 0)) / 100})` }}
                 />
               </div>
             );
@@ -311,7 +311,7 @@ export const NotificationCenter: React.FC = () => {
               <div className="notification-center__item-progress-bar">
                 <div
                   className={`notification-center__item-progress-fill ${notification.status ? `is-${notification.status}` : ''}`}
-                  style={{ width: `${notification.progress || 0}%` }}
+                  style={{ transform: `scaleX(${Math.max(0, Math.min(100, notification.progress || 0)) / 100})` }}
                 />
               </div>
             );
diff --git a/src/web-ui/src/shared/notification-system/components/NotificationContainer.scss b/src/web-ui/src/shared/notification-system/components/NotificationContainer.scss
index e4879cdb09..0ad2c5f87f 100644
--- a/src/web-ui/src/shared/notification-system/components/NotificationContainer.scss
+++ b/src/web-ui/src/shared/notification-system/components/NotificationContainer.scss
@@ -17,6 +17,22 @@
     pointer-events: auto;
   }
 
+  &__presence {
+    display: grid;
+    grid-template-rows: 1fr;
+    overflow: hidden;
+    transition: grid-template-rows 140ms cubic-bezier(0.23, 1, 0.32, 1);
+
+    > * {
+      min-height: 0;
+    }
+
+    &--exiting {
+      grid-template-rows: 0fr;
+      pointer-events: none;
+    }
+  }
+
   
   max-height: calc(100vh - 120px); 
   overflow-y: auto;
@@ -43,4 +59,3 @@
     }
   }
 }
-
diff --git a/src/web-ui/src/shared/notification-system/components/NotificationContainer.test.tsx b/src/web-ui/src/shared/notification-system/components/NotificationContainer.test.tsx
index 418c1f2249..c9abb556c7 100644
--- a/src/web-ui/src/shared/notification-system/components/NotificationContainer.test.tsx
+++ b/src/web-ui/src/shared/notification-system/components/NotificationContainer.test.tsx
@@ -11,10 +11,12 @@ vi.mock('../hooks/useNotificationState', () => ({
   useActiveNotifications: vi.fn(),
 }));
 
-vi.mock('./NotificationItem', () => ({
-  NotificationItem: ({ notification }: { notification: Notification }) => (
-    <div data-variant="toast">{notification.message}</div>
-  ),
+vi.mock('@/infrastructure/i18n', () => ({
+  useI18n: () => ({ t: (key: string) => key }),
+}));
+
+vi.mock('../services/NotificationService', () => ({
+  notificationService: { dismiss: vi.fn() },
 }));
 
 vi.mock('./ProgressNotification', () => ({
@@ -56,6 +58,7 @@ describe('NotificationContainer', () => {
 
   afterEach(() => {
     act(() => root.unmount());
+    vi.useRealTimers();
     vi.clearAllMocks();
     dom.window.close();
   });
@@ -69,7 +72,7 @@ describe('NotificationContainer', () => {
 
     act(() => root.render(<NotificationContainer />));
 
-    expect(container.querySelector('[data-variant="toast"]')?.textContent).toBe('Saved');
+    expect(container.querySelector('.notification-item')?.textContent).toContain('Saved');
     expect(container.querySelector('[data-variant="progress"]')).toBeNull();
     expect(container.querySelector('[data-variant="loading"]')).toBeNull();
   });
@@ -81,4 +84,44 @@ describe('NotificationContainer', () => {
 
     expect(container.querySelector('.notification-container')).toBeNull();
   });
+
+  it('retains a dismissed toast until its exit motion completes', () => {
+    vi.useFakeTimers();
+    vi.mocked(useActiveNotifications).mockReturnValue([notification('toast', 'Saved')]);
+
+    act(() => root.render(<NotificationContainer />));
+    expect(container.querySelector('.notification-item')?.textContent).toContain('Saved');
+
+    vi.mocked(useActiveNotifications).mockReturnValue([]);
+    act(() => root.render(<NotificationContainer />));
+
+    expect(container.querySelector('.notification-container__presence--exiting')).not.toBeNull();
+    expect(container.querySelector('.notification-item')?.textContent).toContain('Saved');
+
+    act(() => vi.advanceTimersByTime(140));
+    expect(container.querySelector('.notification-container')).toBeNull();
+  });
+
+  it('removes focus before making an exiting real notification item inert', () => {
+    vi.useFakeTimers();
+    vi.mocked(useActiveNotifications).mockReturnValue([{
+      ...notification('toast', 'Action required'),
+      closable: true,
+      actions: [{ label: 'Retry', onClick: vi.fn() }],
+    }]);
+
+    act(() => root.render(<NotificationContainer />));
+    const action = container.querySelector('.notification-item__action') as HTMLButtonElement;
+    action.focus();
+    expect(document.activeElement).toBe(action);
+
+    vi.mocked(useActiveNotifications).mockReturnValue([]);
+    act(() => root.render(<NotificationContainer />));
+
+    const presence = container.querySelector('.notification-container__presence--exiting');
+    expect(document.activeElement).not.toBe(action);
+    expect(presence?.getAttribute('aria-hidden')).toBe('true');
+    expect(presence?.hasAttribute('inert')).toBe(true);
+    expect(presence?.querySelector('.notification-item')).not.toBeNull();
+  });
 });
diff --git a/src/web-ui/src/shared/notification-system/components/NotificationContainer.tsx b/src/web-ui/src/shared/notification-system/components/NotificationContainer.tsx
index a949aec116..96127e8ba6 100644
--- a/src/web-ui/src/shared/notification-system/components/NotificationContainer.tsx
+++ b/src/web-ui/src/shared/notification-system/components/NotificationContainer.tsx
@@ -1,28 +1,127 @@
  
 
-import React from 'react';
+import React, { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import type { Notification } from '../types';
 import { useActiveNotifications } from '../hooks/useNotificationState';
 import { NotificationItem } from './NotificationItem';
 import { ProgressNotification } from './ProgressNotification';
 import { LoadingNotification } from './LoadingNotification';
 import './NotificationContainer.scss';
 
+const NOTIFICATION_EXIT_DURATION_MS = 140;
+
+interface NotificationPresenceProps {
+  notification: Notification;
+  isExiting: boolean;
+}
+
+const NotificationPresence: React.FC<NotificationPresenceProps> = ({ notification, isExiting }) => {
+  const presenceRef = useRef<HTMLDivElement>(null);
+  const [exitAccessibilityApplied, setExitAccessibilityApplied] = useState(false);
+
+  useLayoutEffect(() => {
+    if (!isExiting) {
+      setExitAccessibilityApplied(false);
+      return;
+    }
+
+    const activeElement = document.activeElement;
+    if (activeElement instanceof window.HTMLElement && presenceRef.current?.contains(activeElement)) {
+      activeElement.blur();
+    }
+    setExitAccessibilityApplied(true);
+  }, [isExiting]);
+
+  const isAccessibilityHidden = isExiting && exitAccessibilityApplied;
+
+  return (
+    <div
+      ref={presenceRef}
+      className={`notification-container__presence${isExiting ? ' notification-container__presence--exiting' : ''}`}
+      aria-hidden={isAccessibilityHidden || undefined}
+      {...(isAccessibilityHidden ? { inert: '' } : {})}
+    >
+      <NotificationItem
+        notification={notification}
+        isExiting={isExiting}
+      />
+    </div>
+  );
+};
+
 export const NotificationContainer: React.FC = () => {
   const activeNotifications = useActiveNotifications();
 
   
   
-  const visibleNotifications = activeNotifications.filter(
+  const visibleNotifications = useMemo(() => activeNotifications.filter(
     n => n.variant !== 'silent' && n.variant !== 'progress' && n.variant !== 'loading'
+  ), [activeNotifications]);
+  const [presentedNotifications, setPresentedNotifications] = useState<Notification[]>(visibleNotifications);
+  const exitTimersRef = useRef(new Map<string, number>());
+  const visibleIds = useMemo(
+    () => new Set(visibleNotifications.map(notification => notification.id)),
+    [visibleNotifications],
   );
 
-  if (visibleNotifications.length === 0) {
+  useEffect(() => {
+    setPresentedNotifications(current => {
+      const nextById = new Map(visibleNotifications.map(notification => [notification.id, notification]));
+      let changed = false;
+      const merged = current.map(notification => {
+        const next = nextById.get(notification.id) ?? notification;
+        changed ||= next !== notification;
+        return next;
+      });
+      const currentIds = new Set(current.map(notification => notification.id));
+
+      visibleNotifications.forEach(notification => {
+        if (!currentIds.has(notification.id)) {
+          merged.push(notification);
+          changed = true;
+        }
+      });
+
+      return changed ? merged : current;
+    });
+  }, [visibleNotifications]);
+
+  useEffect(() => {
+    visibleIds.forEach(id => {
+      const timer = exitTimersRef.current.get(id);
+      if (timer !== undefined) {
+        window.clearTimeout(timer);
+        exitTimersRef.current.delete(id);
+      }
+    });
+
+    presentedNotifications.forEach(notification => {
+      if (visibleIds.has(notification.id) || exitTimersRef.current.has(notification.id)) {
+        return;
+      }
+
+      const timer = window.setTimeout(() => {
+        setPresentedNotifications(current => current.filter(item => item.id !== notification.id));
+        exitTimersRef.current.delete(notification.id);
+      }, NOTIFICATION_EXIT_DURATION_MS);
+      exitTimersRef.current.set(notification.id, timer);
+    });
+  }, [presentedNotifications, visibleIds]);
+
+  useEffect(() => () => {
+    exitTimersRef.current.forEach(timer => window.clearTimeout(timer));
+    exitTimersRef.current.clear();
+  }, []);
+
+  if (presentedNotifications.length === 0) {
     return null;
   }
 
   return (
     <div className="notification-container" data-bf-component="notification" data-bf-part="container">
-      {visibleNotifications.map((notification) => {
+      {presentedNotifications.map((notification) => {
+        const isExiting = !visibleIds.has(notification.id);
+
         
         if (notification.variant === 'progress') {
           return (
@@ -43,13 +142,13 @@ export const NotificationContainer: React.FC = () => {
         }
 
         return (
-          <NotificationItem
+          <NotificationPresence
             key={notification.id}
             notification={notification}
+            isExiting={isExiting}
           />
         );
       })}
     </div>
   );
 };
-
diff --git a/src/web-ui/src/shared/notification-system/components/NotificationItem.scss b/src/web-ui/src/shared/notification-system/components/NotificationItem.scss
index f6381cc294..7dd2db4d59 100644
--- a/src/web-ui/src/shared/notification-system/components/NotificationItem.scss
+++ b/src/web-ui/src/shared/notification-system/components/NotificationItem.scss
@@ -13,7 +13,7 @@
   border: 1px solid var(--bf-appearance-token-border-base);
   min-width: 280px;
   max-width: 320px;
-  animation: slideIn 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+  animation: bitfun-notification-enter 180ms cubic-bezier(0.23, 1, 0.32, 1) both;
   font-family: $font-family-sans;
 
   
@@ -114,7 +114,10 @@
     font-weight: $font-weight-medium;
     border: none;
     cursor: pointer;
-    transition: all $motion-base $easing-standard;
+    transition:
+      background-color $motion-fast $easing-standard,
+      color $motion-fast $easing-standard,
+      scale $motion-fast $easing-standard;
 
     &--primary {
       background: var(--bf-appearance-token-color-accent-600);
@@ -170,7 +173,10 @@
     border-radius: $size-radius-sm;
     color: var(--bf-appearance-token-color-text-muted);
     cursor: pointer;
-    transition: all $motion-base $easing-standard;
+    transition:
+      background-color $motion-fast $easing-standard,
+      color $motion-fast $easing-standard,
+      scale $motion-fast $easing-standard;
 
     &:hover {
       background: var(--bf-appearance-token-element-bg-base);
@@ -181,29 +187,40 @@
       transform: scale(0.95);
     }
   }
+
+  &--exiting {
+    animation: bitfun-notification-exit 120ms cubic-bezier(0.23, 1, 0.32, 1) both;
+    pointer-events: none;
+  }
 }
 
 
-@keyframes slideIn {
+@keyframes bitfun-notification-enter {
   from {
     opacity: 0;
-    transform: translateX(-100%);
+    transform: translateX(-12px) scale(0.985);
   }
   to {
     opacity: 1;
-    transform: translateX(0);
+    transform: translateX(0) scale(1);
   }
 }
 
 
-@keyframes slideOut {
+@keyframes bitfun-notification-exit {
   from {
     opacity: 1;
-    transform: translateX(0);
+    transform: translateX(0) scale(1);
   }
   to {
     opacity: 0;
-    transform: translateX(-100%);
+    transform: translateX(-8px) scale(0.99);
   }
 }
 
+@media (prefers-reduced-motion: reduce) {
+  .notification-item,
+  .notification-item--exiting {
+    transform: none;
+  }
+}
diff --git a/src/web-ui/src/shared/notification-system/components/NotificationItem.tsx b/src/web-ui/src/shared/notification-system/components/NotificationItem.tsx
index 57435bd934..91d02a85c1 100644
--- a/src/web-ui/src/shared/notification-system/components/NotificationItem.tsx
+++ b/src/web-ui/src/shared/notification-system/components/NotificationItem.tsx
@@ -9,9 +9,10 @@ import './NotificationItem.scss';
 
 export interface NotificationItemProps {
   notification: Notification;
+  isExiting?: boolean;
 }
 
-export const NotificationItem: React.FC<NotificationItemProps> = ({ notification }) => {
+export const NotificationItem: React.FC<NotificationItemProps> = ({ notification, isExiting = false }) => {
   const { id, type, title, message, messageNode, closable, actions } = notification;
   const isAssertive = type === 'error' || type === 'warning';
   const { t } = useI18n('common');
@@ -47,7 +48,7 @@ export const NotificationItem: React.FC<NotificationItemProps> = ({ notification
 
   return (
     <div
-      className={`notification-item notification-item--${type}`}
+      className={`notification-item notification-item--${type}${isExiting ? ' notification-item--exiting' : ''}`}
       data-bf-component="notification"
       data-bf-part="item"
       role={isAssertive ? 'alert' : 'status'}
@@ -95,4 +96,3 @@ export const NotificationItem: React.FC<NotificationItemProps> = ({ notification
     </div>
   );
 };
-
diff --git a/src/web-ui/src/shared/notification-system/components/ProgressNotification.scss b/src/web-ui/src/shared/notification-system/components/ProgressNotification.scss
index 9ef91b135c..f5442442dc 100644
--- a/src/web-ui/src/shared/notification-system/components/ProgressNotification.scss
+++ b/src/web-ui/src/shared/notification-system/components/ProgressNotification.scss
@@ -13,7 +13,7 @@
   border: 1px solid var(--bf-appearance-token-border-base);
   min-width: 280px;
   max-width: 320px;
-  animation: slideIn 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+  animation: bitfun-progress-notification-slide-in 0.3s cubic-bezier(0.4, 0, 0.2, 1);
   font-family: $font-family-sans;
 
   
@@ -50,7 +50,7 @@
   }
 
   &__spinner {
-    animation: spin 1s linear infinite;
+    animation: bitfun-progress-notification-spin 1s linear infinite;
   }
 
   &__status-icon {
@@ -122,10 +122,12 @@
   }
 
   &__progress-fill {
+    width: 100%;
     height: 100%;
     background: linear-gradient(90deg, var(--bf-appearance-token-color-accent-600), var(--bf-appearance-token-color-purple-500));
     border-radius: 2px;
-    transition: width 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+    transform-origin: left center;
+    transition: transform 0.3s cubic-bezier(0.4, 0, 0.2, 1);
   }
 
   
@@ -151,7 +153,10 @@
     border-radius: $size-radius-sm;
     color: var(--bf-appearance-token-color-text-muted);
     cursor: pointer;
-    transition: all $motion-base $easing-standard;
+    transition:
+      background-color $motion-base $easing-standard,
+      color $motion-base $easing-standard,
+      transform $motion-base $easing-standard;
 
     &:hover {
       background: var(--bf-appearance-token-element-bg-base);
@@ -165,7 +170,7 @@
 }
 
 
-@keyframes spin {
+@keyframes bitfun-progress-notification-spin {
   from {
     transform: rotate(0deg);
   }
@@ -175,7 +180,7 @@
 }
 
 
-@keyframes slideIn {
+@keyframes bitfun-progress-notification-slide-in {
   from {
     opacity: 0;
     transform: translateX(-100%);
@@ -186,3 +191,14 @@
   }
 }
 
+@media (prefers-reduced-motion: reduce) {
+  .progress-notification,
+  .progress-notification__spinner {
+    animation: none;
+    transform: none;
+  }
+
+  .progress-notification__progress-fill {
+    transition: none;
+  }
+}
diff --git a/src/web-ui/src/shared/notification-system/components/ProgressNotification.tsx b/src/web-ui/src/shared/notification-system/components/ProgressNotification.tsx
index 1aa27a5bda..5074f67d2c 100644
--- a/src/web-ui/src/shared/notification-system/components/ProgressNotification.tsx
+++ b/src/web-ui/src/shared/notification-system/components/ProgressNotification.tsx
@@ -58,7 +58,11 @@ export const ProgressNotification: React.FC<ProgressNotificationProps> = ({ noti
       data-bf-state={status || undefined}
     >
       
-      <div className="progress-notification__icon">
+      <div
+        className="progress-notification__icon"
+        data-bf-component="notification"
+        data-bf-part="progressIcon"
+      >
         {getStatusIcon()}
       </div>
 
@@ -83,7 +87,7 @@ export const ProgressNotification: React.FC<ProgressNotificationProps> = ({ noti
               className="progress-notification__progress-fill"
               data-bf-component="notification"
               data-bf-part="progressFill"
-              style={{ width: `${progress}%` }}
+              style={{ transform: `scaleX(${Math.max(0, Math.min(100, progress)) / 100})` }}
             />
           </div>
         )}
@@ -102,4 +106,3 @@ export const ProgressNotification: React.FC<ProgressNotificationProps> = ({ noti
     </div>
   );
 };
-
diff --git a/src/web-ui/src/shared/types/session-history.ts b/src/web-ui/src/shared/types/session-history.ts
index 810492e95c..a56379d82a 100644
--- a/src/web-ui/src/shared/types/session-history.ts
+++ b/src/web-ui/src/shared/types/session-history.ts
@@ -204,6 +204,13 @@ export interface DialogTurnData {
   tokenUsage?: DialogTurnTokenUsageData;
   status: TurnStatus;
   finishReason?: string;
+  recovery?: {
+    status: 'interrupted' | 'recovering';
+    executionGeneration: number;
+    resumeCount: number;
+    interruptedAt?: number;
+    modelId?: string;
+  };
   hasFinalResponse?: boolean;
   error?: string;
   errorDetail?: AiErrorDetail;
diff --git a/src/web-ui/src/shared/types/version.ts b/src/web-ui/src/shared/types/version.ts
index 2ddf3358d7..2b06c23e53 100644
--- a/src/web-ui/src/shared/types/version.ts
+++ b/src/web-ui/src/shared/types/version.ts
@@ -20,6 +20,8 @@ export interface VersionInfo {
   isDev: boolean;
    
   buildEnv: 'development' | 'production' | 'preview';
+
+  releaseChannel?: 'stable' | 'beta' | 'nightly';
 }
 
  
@@ -47,4 +49,3 @@ export interface AboutInfo {
     issues?: string;
   };
 }
-
diff --git a/src/web-ui/src/shared/utils/index.ts b/src/web-ui/src/shared/utils/index.ts
index 53ebc1d800..546e64a8c7 100644
--- a/src/web-ui/src/shared/utils/index.ts
+++ b/src/web-ui/src/shared/utils/index.ts
@@ -7,6 +7,7 @@ export * from './validation';
 
 export * from './logger';
 export * from './timing';
+export * from './motionPreference';
 export * from './debugProbe';
 
 
diff --git a/src/web-ui/src/shared/utils/motionPreference.test.ts b/src/web-ui/src/shared/utils/motionPreference.test.ts
new file mode 100644
index 0000000000..c195954cca
--- /dev/null
+++ b/src/web-ui/src/shared/utils/motionPreference.test.ts
@@ -0,0 +1,69 @@
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+  getInteractionMotion,
+  getMotionAwareScrollBehavior,
+  installInteractionModalityTracking,
+  isReducedMotionPreferred,
+  recordInteractionModality,
+} from './motionPreference';
+
+describe('getMotionAwareScrollBehavior', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    recordInteractionModality('programmatic');
+  });
+
+  it('keeps smooth scrolling when reduced motion is not requested', () => {
+    vi.stubGlobal('matchMedia', vi.fn(() => ({ matches: false })));
+
+    expect(getMotionAwareScrollBehavior('smooth')).toBe('smooth');
+  });
+
+  it('uses immediate scrolling when reduced motion is requested', () => {
+    vi.stubGlobal('matchMedia', vi.fn(() => ({ matches: true })));
+
+    expect(getMotionAwareScrollBehavior('smooth')).toBe('auto');
+  });
+
+  it('does not query motion preferences for an immediate scroll', () => {
+    const matchMedia = vi.fn(() => ({ matches: true }));
+    vi.stubGlobal('matchMedia', matchMedia);
+
+    expect(getMotionAwareScrollBehavior('auto')).toBe('auto');
+    expect(matchMedia).not.toHaveBeenCalled();
+  });
+
+  it('reports the current reduced-motion preference', () => {
+    vi.stubGlobal('matchMedia', vi.fn(() => ({ matches: true })));
+
+    expect(isReducedMotionPreferred()).toBe(true);
+  });
+
+  it('defaults to full motion when matchMedia is unavailable', () => {
+    vi.stubGlobal('matchMedia', undefined);
+
+    expect(isReducedMotionPreferred()).toBe(false);
+  });
+
+  it('exposes pointer motion only for the current pointer interaction', () => {
+    recordInteractionModality('pointer');
+    expect(getInteractionMotion()).toBe('pointer');
+
+    recordInteractionModality('keyboard');
+    expect(getInteractionMotion()).toBe('instant');
+  });
+
+  it('tracks pointer and keyboard modality in the capture phase', () => {
+    const target = document.implementation.createHTMLDocument();
+    const remove = installInteractionModalityTracking(target);
+
+    target.dispatchEvent(new Event('pointerdown', { bubbles: true }));
+    expect(getInteractionMotion()).toBe('pointer');
+
+    target.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }));
+    expect(getInteractionMotion()).toBe('instant');
+    remove();
+  });
+});
diff --git a/src/web-ui/src/shared/utils/motionPreference.ts b/src/web-ui/src/shared/utils/motionPreference.ts
new file mode 100644
index 0000000000..62a730c4ca
--- /dev/null
+++ b/src/web-ui/src/shared/utils/motionPreference.ts
@@ -0,0 +1,77 @@
+const REDUCED_MOTION_QUERY = '(prefers-reduced-motion: reduce)';
+const POINTER_INTENT_WINDOW_MS = 1500;
+
+export type MotionAwareScrollBehavior = 'auto' | 'smooth';
+export type InteractionModality = 'keyboard' | 'pointer' | 'programmatic';
+export type InteractionMotion = 'instant' | 'pointer';
+
+let lastInteractionModality: InteractionModality = 'programmatic';
+let lastInteractionAt = Number.NEGATIVE_INFINITY;
+let removeInteractionModalityListeners: (() => void) | null = null;
+
+function interactionNow(): number {
+  return globalThis.performance?.now() ?? Date.now();
+}
+
+/**
+ * Records the input source that should own the next state transition.
+ *
+ * Pointer intent is deliberately short-lived: a click-triggered async preload
+ * may resolve on a later task, while unrelated background updates must not
+ * inherit motion from an old click.
+ */
+export function recordInteractionModality(modality: InteractionModality): void {
+  lastInteractionModality = modality;
+  lastInteractionAt = interactionNow();
+}
+
+export function getInteractionMotion(): InteractionMotion {
+  const pointerIsCurrent = lastInteractionModality === 'pointer'
+    && interactionNow() - lastInteractionAt <= POINTER_INTENT_WINDOW_MS;
+  return pointerIsCurrent ? 'pointer' : 'instant';
+}
+
+/**
+ * Installs one capture-phase modality tracker for the application shell.
+ * Keyboard activation stays instant; mouse, pen, and touch clicks can opt into
+ * the subtle spatial transitions exposed by `getInteractionMotion`.
+ */
+export function installInteractionModalityTracking(
+  target: Document | undefined = globalThis.document,
+): () => void {
+  if (!target) return () => {};
+  if (removeInteractionModalityListeners) return removeInteractionModalityListeners;
+
+  const handlePointerDown = () => recordInteractionModality('pointer');
+  const handleKeyDown = () => recordInteractionModality('keyboard');
+  target.addEventListener('pointerdown', handlePointerDown, true);
+  target.addEventListener('keydown', handleKeyDown, true);
+
+  removeInteractionModalityListeners = () => {
+    target.removeEventListener('pointerdown', handlePointerDown, true);
+    target.removeEventListener('keydown', handleKeyDown, true);
+    removeInteractionModalityListeners = null;
+  };
+  return removeInteractionModalityListeners;
+}
+
+export function isReducedMotionPreferred(): boolean {
+  return globalThis.matchMedia?.(REDUCED_MOTION_QUERY).matches ?? false;
+}
+
+/**
+ * Preserve occasional spatial navigation while respecting reduced motion.
+ * Automatic, keyboard-repeated, and other high-frequency paths should pass
+ * `auto` directly instead of opting into smooth scrolling.
+ */
+export function getMotionAwareScrollBehavior(
+  preferredBehavior: MotionAwareScrollBehavior,
+): MotionAwareScrollBehavior {
+  if (preferredBehavior !== 'smooth') {
+    return preferredBehavior;
+  }
+
+  return isReducedMotionPreferred()
+    ? 'auto'
+    : preferredBehavior;
+}
diff --git a/src/web-ui/src/shared/utils/version.test.ts b/src/web-ui/src/shared/utils/version.test.ts
index 3ae507ebc5..74bbc08897 100644
--- a/src/web-ui/src/shared/utils/version.test.ts
+++ b/src/web-ui/src/shared/utils/version.test.ts
@@ -8,6 +8,7 @@ const productionInfo: VersionInfo = {
   buildDate: '2026-08-06T00:00:00Z',
   buildTimestamp: 0,
   buildEnv: 'production',
+  releaseChannel: 'stable',
   isDev: false,
 };
 
diff --git a/src/web-ui/src/shared/utils/version.ts b/src/web-ui/src/shared/utils/version.ts
index 809ccb3ffe..5e5350008e 100644
--- a/src/web-ui/src/shared/utils/version.ts
+++ b/src/web-ui/src/shared/utils/version.ts
@@ -10,7 +10,8 @@ const DEFAULT_VERSION_INFO: VersionInfo = {
   buildDate: new Date(0).toISOString(),
   buildTimestamp: 0,
   isDev: import.meta.env.DEV,
-  buildEnv: import.meta.env.MODE as VersionInfo['buildEnv']
+  buildEnv: import.meta.env.MODE as VersionInfo['buildEnv'],
+  releaseChannel: 'stable'
 };
 
 
diff --git a/src/web-ui/src/tools/bitfun-canvas/BitfunCanvasPanel.scss b/src/web-ui/src/tools/bitfun-canvas/BitfunCanvasPanel.scss
index e9361f2a9a..465daf4642 100644
--- a/src/web-ui/src/tools/bitfun-canvas/BitfunCanvasPanel.scss
+++ b/src/web-ui/src/tools/bitfun-canvas/BitfunCanvasPanel.scss
@@ -62,6 +62,12 @@
   }
 }
 
+@media (prefers-reduced-motion: reduce) {
+  .bitfun-canvas-panel__toolbar-icon--spin {
+    animation: none;
+  }
+}
+
 .bitfun-canvas-panel--empty {
   flex-direction: column;
   gap: var(--bf-appearance-token-size-gap-4);
diff --git a/src/web-ui/src/tools/editor/appearance.ts b/src/web-ui/src/tools/editor/appearance.ts
index 88031868b4..3efde15284 100644
--- a/src/web-ui/src/tools/editor/appearance.ts
+++ b/src/web-ui/src/tools/editor/appearance.ts
@@ -10,6 +10,7 @@ export const editorToolAppearanceDescriptor: AppearanceSurfaceDescriptor = {
     { id: 'saving' },
     { id: 'readOnlyCodeBlock' },
     { id: 'meditorPreview' },
+    { id: 'meditorFrontmatter' },
     { id: 'meditorEditArea' },
   ],
   states: [
diff --git a/src/web-ui/src/tools/editor/components/CodeEditor.scss b/src/web-ui/src/tools/editor/components/CodeEditor.scss
index abbb31afd6..fdddad78b2 100644
--- a/src/web-ui/src/tools/editor/components/CodeEditor.scss
+++ b/src/web-ui/src/tools/editor/components/CodeEditor.scss
@@ -273,6 +273,18 @@ $_editor-padding-desktop: 32px;
   }
 }
 
+@media (prefers-reduced-motion: reduce) {
+  .code-editor-tool {
+    &__loading-spinner,
+    &__loading-text,
+    &__loading-overlay,
+    &__error-overlay,
+    &__saving-indicator {
+      animation: none;
+    }
+  }
+}
+
 // Responsive
 @media (max-width: 768px) {
   .code-editor-tool {
diff --git a/src/web-ui/src/tools/editor/components/DiffEditor.scss b/src/web-ui/src/tools/editor/components/DiffEditor.scss
index 252105ed82..6cbd3c6189 100644
--- a/src/web-ui/src/tools/editor/components/DiffEditor.scss
+++ b/src/web-ui/src/tools/editor/components/DiffEditor.scss
@@ -366,7 +366,7 @@ $_diff-error-max-width: 400px;
       background-color: var(--bf-appearance-token-color-overlay-white-04) !important;
       border-left: 1px dashed var(--bf-appearance-token-border-medium) !important;
       border-right: 1px dashed var(--bf-appearance-token-border-medium) !important;
-      transition: all 0.2s ease;
+      transition: background-color 0.2s ease;
       
       &:hover {
         background-color: var(--bf-appearance-token-color-overlay-white-08) !important;
diff --git a/src/web-ui/src/tools/editor/components/EditorBreadcrumb.scss b/src/web-ui/src/tools/editor/components/EditorBreadcrumb.scss
index 0a5c4cc290..96dea7667e 100644
--- a/src/web-ui/src/tools/editor/components/EditorBreadcrumb.scss
+++ b/src/web-ui/src/tools/editor/components/EditorBreadcrumb.scss
@@ -240,3 +240,10 @@ $_dropdown-width: 220px;
 @keyframes breadcrumb-spin {
   to { transform: rotate(360deg); }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .editor-breadcrumb-dropdown,
+  .editor-breadcrumb-dropdown__spinner {
+    animation: none;
+  }
+}
diff --git a/src/web-ui/src/tools/editor/components/EditorStatusBar.scss b/src/web-ui/src/tools/editor/components/EditorStatusBar.scss
index 88f3d965ad..47dd9a85fd 100644
--- a/src/web-ui/src/tools/editor/components/EditorStatusBar.scss
+++ b/src/web-ui/src/tools/editor/components/EditorStatusBar.scss
@@ -122,6 +122,12 @@ $_section-gap: 12px;
   }
 }
 
+@media (prefers-reduced-motion: reduce) {
+  .editor-status-bar__lsp-spinner {
+    animation: none;
+  }
+}
+
 // Responsive
 @media (max-width: 640px) {
   .editor-status-bar {
diff --git a/src/web-ui/src/tools/editor/components/ImageViewer.scss b/src/web-ui/src/tools/editor/components/ImageViewer.scss
index c01c582c38..c02e359125 100644
--- a/src/web-ui/src/tools/editor/components/ImageViewer.scss
+++ b/src/web-ui/src/tools/editor/components/ImageViewer.scss
@@ -195,15 +195,21 @@
     border: 3px solid var(--bf-appearance-token-border-medium);
     border-top-color: var(--bf-appearance-token-color-accent-500);
     border-radius: 50%;
-    animation: spin 0.8s linear infinite;
+    animation: bitfun-image-viewer-spin 0.8s linear infinite;
   }
 
-  @keyframes spin {
+  @keyframes bitfun-image-viewer-spin {
     to {
       transform: rotate(360deg);
     }
   }
 
+  @media (prefers-reduced-motion: reduce) {
+    .bitfun-image-viewer__spinner {
+      animation: none;
+    }
+  }
+
   // Error State
   &__error {
     display: flex;
diff --git a/src/web-ui/src/tools/editor/components/MarkdownEditor.appearance.ts b/src/web-ui/src/tools/editor/components/MarkdownEditor.appearance.ts
index 3a76b81f7c..01e21b474f 100644
--- a/src/web-ui/src/tools/editor/components/MarkdownEditor.appearance.ts
+++ b/src/web-ui/src/tools/editor/components/MarkdownEditor.appearance.ts
@@ -3,7 +3,7 @@ import type { AppearanceSurfaceDescriptor } from '@/infrastructure/appearance';
 export const markdownEditorAppearanceDescriptor: AppearanceSurfaceDescriptor = {
   id: 'markdown-editor',
   parts: [
-    { id: 'root' }, { id: 'loading' }, { id: 'error' }, { id: 'notice' },
+    { id: 'root' }, { id: 'loading' }, { id: 'error' },
     { id: 'toolbar' }, { id: 'modeToggle' }, { id: 'actions' }, { id: 'body' },
   ],
   facets: [{ id: 'view', attribute: 'data-bf-view', values: ['preview', 'markdown', 'source'] }],
diff --git a/src/web-ui/src/tools/editor/components/MarkdownEditor.scss b/src/web-ui/src/tools/editor/components/MarkdownEditor.scss
index 1c5e68ff3d..6cff29a0ce 100644
--- a/src/web-ui/src/tools/editor/components/MarkdownEditor.scss
+++ b/src/web-ui/src/tools/editor/components/MarkdownEditor.scss
@@ -13,37 +13,6 @@
   overflow: hidden;
 }
 
-.bitfun-markdown-editor__notice-bar {
-  display: flex;
-  align-items: flex-start;
-  gap: $size-gap-3;
-  padding: $size-gap-3 $size-gap-4;
-  border-bottom: 1px solid color-mix(in srgb, var(--bf-appearance-token-color-warning) 22%, transparent);
-  background: color-mix(in srgb, var(--bf-appearance-token-color-warning) 8%, var(--bf-appearance-token-color-bg-scene));
-  color: var(--bf-appearance-token-color-text-secondary);
-  flex-shrink: 0;
-}
-
-.bitfun-markdown-editor__notice-icon {
-  width: 16px;
-  height: 16px;
-  margin-top: 2px;
-  color: var(--bf-appearance-token-color-warning);
-  flex-shrink: 0;
-}
-
-.bitfun-markdown-editor__notice-copy {
-  display: flex;
-  flex-direction: column;
-  gap: 2px;
-
-  p {
-    margin: 0;
-    font-size: var(--bf-appearance-token-font-size-xs);
-    line-height: $line-height-relaxed;
-  }
-}
-
 .bitfun-markdown-editor__mode-toolbar {
   display: flex;
   align-items: center;
diff --git a/src/web-ui/src/tools/editor/components/MarkdownEditor.test.tsx b/src/web-ui/src/tools/editor/components/MarkdownEditor.test.tsx
index 928e617342..0517c5fa91 100644
--- a/src/web-ui/src/tools/editor/components/MarkdownEditor.test.tsx
+++ b/src/web-ui/src/tools/editor/components/MarkdownEditor.test.tsx
@@ -56,6 +56,7 @@ vi.mock('../meditor/utils/tiptapMarkdown', () => ({
 const messages: Record<string, string> = {
   'editor.markdownEditor.copiedMarkdown': 'Copied Markdown',
   'editor.markdownEditor.copyMarkdown': 'Copy Markdown',
+  'editor.markdownEditor.notice.sourcePreviewFallback': 'IR fallback warning',
 };
 
 vi.mock('@/infrastructure/i18n', () => ({
@@ -109,6 +110,14 @@ describe('MarkdownEditor', () => {
     expect(html).toContain('data-mode="preview"');
   });
 
+  it('does not show the IR fallback warning in the preview/source file UI', () => {
+    const html = renderToStaticMarkup(
+      <MarkdownEditor initialContent="# Ordinary Markdown" />,
+    );
+
+    expect(html).not.toContain('IR fallback warning');
+  });
+
   it('uses source mode at and above the rich markdown size limit', () => {
     expect(shouldUseLargeMarkdownSourceMode(MARKDOWN_RICH_EDITOR_MAX_BYTES - 1)).toBe(false);
     expect(shouldUseLargeMarkdownSourceMode(MARKDOWN_RICH_EDITOR_MAX_BYTES)).toBe(true);
diff --git a/src/web-ui/src/tools/editor/components/MarkdownEditor.tsx b/src/web-ui/src/tools/editor/components/MarkdownEditor.tsx
index 4c0aba3479..4a81fd8c27 100644
--- a/src/web-ui/src/tools/editor/components/MarkdownEditor.tsx
+++ b/src/web-ui/src/tools/editor/components/MarkdownEditor.tsx
@@ -5,7 +5,7 @@
  * @module components/MarkdownEditor
  */
 
-import React, { useEffect, useState, useCallback, useMemo, useRef } from 'react';
+import React, { useEffect, useState, useCallback, useRef } from 'react';
 import { MEditor } from '../meditor';
 import type { EditorInstance } from '../meditor';
 import { analyzeMarkdownEditability, type MarkdownEditabilityAnalysis } from '../meditor/utils/tiptapMarkdown';
@@ -678,20 +678,6 @@ const MarkdownEditor: React.FC<MarkdownEditorProps> = ({
     return () => clearTimeout(timer);
   }, [jumpToLine, jumpToColumn, filePath, loading, content]);
 
-  const notices = useMemo(() => {
-    const nextNotices: string[] = [];
-
-    if (filePath && (
-      editability.mode === 'unsafe' ||
-      editability.containsRenderOnlyBlocks ||
-      editability.containsRawHtmlInlines
-    )) {
-      nextNotices.push(t('editor.markdownEditor.notice.sourcePreviewFallback'));
-    }
-
-    return nextNotices;
-  }, [editability, filePath, t]);
-
   const shouldUseSourcePreviewFallback = !!filePath && (
     editability.mode === 'unsafe' ||
     editability.containsRenderOnlyBlocks ||
@@ -725,16 +711,6 @@ const MarkdownEditor: React.FC<MarkdownEditorProps> = ({
   if (shouldUseSourcePreviewFallback) {
     return (
       <div className={`bitfun-markdown-editor ${className}`} data-bf-component="markdown-editor" data-bf-part="root" data-bf-view={unsafeViewMode}>
-        {notices.length > 0 && (
-          <div className="bitfun-markdown-editor__notice-bar" data-bf-component="markdown-editor" data-bf-part="notice">
-            <AlertCircle className="bitfun-markdown-editor__notice-icon" />
-            <div className="bitfun-markdown-editor__notice-copy">
-              {notices.map(notice => (
-                <p key={notice}>{notice}</p>
-              ))}
-            </div>
-          </div>
-        )}
         <div className="bitfun-markdown-editor__mode-toolbar" data-bf-component="markdown-editor" data-bf-part="toolbar">
           <div className="bitfun-markdown-editor__mode-toggle" role="tablist" aria-label={t('editor.markdownEditor.viewModeLabel')} data-bf-component="markdown-editor" data-bf-part="modeToggle">
             <Button
@@ -841,16 +817,6 @@ const MarkdownEditor: React.FC<MarkdownEditorProps> = ({
 
   return (
     <div className={`bitfun-markdown-editor ${className}`} data-bf-component="markdown-editor" data-bf-part="root" data-bf-view={viewMode}>
-      {notices.length > 0 && (
-        <div className="bitfun-markdown-editor__notice-bar" data-bf-component="markdown-editor" data-bf-part="notice">
-          <AlertCircle className="bitfun-markdown-editor__notice-icon" />
-          <div className="bitfun-markdown-editor__notice-copy">
-            {notices.map(notice => (
-              <p key={notice}>{notice}</p>
-            ))}
-          </div>
-        </div>
-      )}
       <div className="bitfun-markdown-editor__mode-toolbar" data-bf-component="markdown-editor" data-bf-part="toolbar">
         <div className="bitfun-markdown-editor__mode-toggle" role="tablist" aria-label={t('editor.markdownEditor.viewModeLabel')} data-bf-component="markdown-editor" data-bf-part="modeToggle">
           <Button
diff --git a/src/web-ui/src/tools/editor/components/PlanViewer.scss b/src/web-ui/src/tools/editor/components/PlanViewer.scss
index 7512824230..abc7f17f40 100644
--- a/src/web-ui/src/tools/editor/components/PlanViewer.scss
+++ b/src/web-ui/src/tools/editor/components/PlanViewer.scss
@@ -100,7 +100,10 @@
         color: var(--bf-appearance-token-color-text-muted);
         border-radius: 4px;
         background: var(--bf-appearance-token-color-overlay-white-04);
-        transition: all 0.15s ease;
+        transition:
+          background-color 0.15s ease,
+          color 0.15s ease,
+          opacity 0.15s ease;
 
         svg {
           transition: transform 0.15s ease;
@@ -208,7 +211,11 @@
     border: none;
     border-radius: 4px;
     cursor: pointer;
-    transition: all 0.15s ease;
+    transition:
+      transform 0.15s ease,
+      background-color 0.15s ease,
+      box-shadow 0.15s ease,
+      opacity 0.15s ease;
     box-shadow: 0 1px 2px var(--bf-appearance-token-color-overlay-black-12);
 
     &:hover:not(:disabled) {
@@ -493,7 +500,7 @@
 }
 
 // Spin animation
-@keyframes spin {
+@keyframes bitfun-plan-viewer-spin {
   from {
     transform: rotate(0deg);
   }
@@ -503,5 +510,19 @@
 }
 
 .animate-spin {
-  animation: spin 1s linear infinite;
+  animation: bitfun-plan-viewer-spin 1s linear infinite;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .bitfun-plan-viewer {
+    .header-expand-indicator,
+    .header-expand-indicator svg,
+    .build-btn {
+      transition: none;
+    }
+
+    .animate-spin {
+      animation: none;
+    }
+  }
 }
diff --git a/src/web-ui/src/tools/editor/meditor/components/MEditor.appearance.ts b/src/web-ui/src/tools/editor/meditor/components/MEditor.appearance.ts
index a3bbeb57d0..7407fc004e 100644
--- a/src/web-ui/src/tools/editor/meditor/components/MEditor.appearance.ts
+++ b/src/web-ui/src/tools/editor/meditor/components/MEditor.appearance.ts
@@ -4,6 +4,6 @@ export const mEditorAppearanceDescriptor: AppearanceSurfaceDescriptor = {
   id: 'm-editor',
   parts: [
     { id: 'root' }, { id: 'toolbar' }, { id: 'content' },
-    { id: 'editPanel' }, { id: 'previewPanel' }, { id: 'irPanel' },
+    { id: 'notice' }, { id: 'editPanel' }, { id: 'previewPanel' }, { id: 'irPanel' },
   ],
 };
diff --git a/src/web-ui/src/tools/editor/meditor/components/MEditor.scss b/src/web-ui/src/tools/editor/meditor/components/MEditor.scss
index 9da13641e4..403515cacb 100644
--- a/src/web-ui/src/tools/editor/meditor/components/MEditor.scss
+++ b/src/web-ui/src/tools/editor/meditor/components/MEditor.scss
@@ -12,6 +12,26 @@
     background: var(--bf-appearance-token-element-bg-soft);
     backdrop-filter: blur(8px);
   }
+
+  &-notice {
+    display: flex;
+    align-items: flex-start;
+    gap: $size-gap-2;
+    padding: $size-gap-2 $size-gap-3;
+    border-bottom: 1px solid color-mix(in srgb, var(--bf-appearance-token-color-warning) 30%, transparent);
+    background: color-mix(in srgb, var(--bf-appearance-token-color-warning) 8%, transparent);
+    color: var(--bf-appearance-token-color-text-secondary);
+    font-size: var(--bf-appearance-token-font-size-sm);
+    line-height: 1.45;
+
+    &__icon {
+      flex: 0 0 auto;
+      width: 16px;
+      height: 16px;
+      margin-top: 2px;
+      color: var(--bf-appearance-token-color-warning);
+    }
+  }
   
   &-content {
     flex: 1;
@@ -19,6 +39,28 @@
     overflow: hidden;
     border-radius: 0;
   }
+
+  &-source-fallback {
+    width: 100%;
+    // Grow to fill a container with a definite height; fall back to the
+    // content-sized `rows` when the host passes `height="auto"` (PlanViewer),
+    // where a percentage height would resolve to the default two rows.
+    flex: 1 1 auto;
+    min-width: 0;
+    min-height: 0;
+    resize: none;
+    border: 0;
+    outline: 0;
+    padding: $size-gap-3;
+    box-sizing: border-box;
+    background: var(--bf-appearance-token-color-bg-scene);
+    color: var(--bf-appearance-token-color-text-primary);
+    font: inherit;
+    font-family: var(--bf-appearance-token-font-family-mono);
+    line-height: 1.6;
+    white-space: pre-wrap;
+    overflow: auto;
+  }
   
   &-edit-panel,
   &-preview-panel,
diff --git a/src/web-ui/src/tools/editor/meditor/components/MEditor.test.tsx b/src/web-ui/src/tools/editor/meditor/components/MEditor.test.tsx
index 418582e527..c9a55c44ec 100644
--- a/src/web-ui/src/tools/editor/meditor/components/MEditor.test.tsx
+++ b/src/web-ui/src/tools/editor/meditor/components/MEditor.test.tsx
@@ -1,48 +1,97 @@
-import React from 'react';
-import { renderToStaticMarkup } from 'react-dom/server';
-import { describe, expect, it, vi } from 'vitest';
-import { MEditor } from './MEditor';
+// @vitest-environment jsdom
+
+import React, { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  logError: vi.fn(),
+}))
 
 vi.mock('@/shared/utils/logger', () => ({
-  createLogger: vi.fn(),
-}));
-
-vi.mock('@/tools/editor/services/ActiveEditTargetService', () => ({
-  activeEditTargetService: {
-    bindTarget: vi.fn(),
-    clearActiveTarget: vi.fn(),
-    setActiveTarget: vi.fn(),
-  },
-}));
+  createLogger: () => ({
+    error: mocks.logError,
+    warn: vi.fn(),
+    info: vi.fn(),
+    debug: vi.fn(),
+  }),
+}))
+
+import { MEditor, MEditorErrorBoundary } from './MEditor'
+
+function UnsupportedMarkdownRenderer(): never {
+  throw new SyntaxError('Invalid regular expression: invalid group specifier name')
+}
+
+describe('MEditorErrorBoundary', () => {
+  let container: HTMLDivElement
+  let root: Root
+  let consoleError: ReturnType<typeof vi.spyOn>
+
+  beforeEach(() => {
+    globalThis.IS_REACT_ACT_ENVIRONMENT = true
+    container = document.createElement('div')
+    document.body.appendChild(container)
+    root = createRoot(container)
+    consoleError = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+    mocks.logError.mockReset()
+  })
+
+  afterEach(() => {
+    act(() => root.unmount())
+    container.remove()
+    consoleError.mockRestore()
+  })
+
+  it('keeps the original markdown visible when the rich editor cannot render', () => {
+    act(() => {
+      root.render(
+        <MEditorErrorBoundary
+          editorProps={{ value: '# Recovery plan', readonly: true }}
+          forwardedRef={null}
+        >
+          <UnsupportedMarkdownRenderer />
+        </MEditorErrorBoundary>
+      )
+    })
+
+    const fallback = container.querySelector<HTMLTextAreaElement>(
+      '[data-bf-component="m-editor"][data-m-editor-fallback="true"] textarea'
+    )
+    expect(fallback?.value).toBe('# Recovery plan')
+    expect(fallback?.readOnly).toBe(true)
+    expect(mocks.logError).toHaveBeenCalledWith(
+      'Markdown editor render failed, showing source fallback',
+      expect.objectContaining({
+        message: 'Invalid regular expression: invalid group specifier name',
+      })
+    )
+  })
+
+  it('shows the compatibility warning only when IR mode requests a fallback', () => {
+    act(() => {
+      root.render(
+        <MEditor value={'Mix <span data-x="1">inline</span> HTML.'} mode="preview" />
+      )
+    })
+    expect(container.textContent).not.toContain('IR fallback warning')
+
+    act(() => {
+      root.render(
+        <MEditor value={'Mix <span data-x="1">inline</span> HTML.'} mode="ir" />
+      )
+    })
+    expect(container.textContent).toContain('IR fallback warning')
+  })
+})
 
 vi.mock('@/infrastructure/i18n', () => ({
-  useI18n: () => ({ t: (key: string) => key }),
-}));
-
-vi.mock('../utils/tiptapMarkdown', () => ({
-  analyzeMarkdownEditability: () => ({ containsRenderOnlyBlocks: false }),
-}));
-
-vi.mock('./Preview', () => ({
-  Preview: ({ value }: { value: string }) => <div data-testid="preview">{value.length}</div>,
-}));
-
-vi.mock('./TiptapEditor', () => ({
-  TiptapEditor: () => <div data-testid="tiptap" />,
-}));
-
-vi.mock('./EditArea', () => ({
-  EditArea: () => <textarea data-testid="edit-area" />,
-}));
-
-describe('MEditor initial mode', () => {
-  it('renders a large preview directly without mounting Tiptap on the first frame', () => {
-    const markdown = 'x'.repeat(2 * 1024 * 1024);
-    const html = renderToStaticMarkup(
-      <MEditor value={markdown} mode="preview" progressivePreview readonly />,
-    );
-
-    expect(html).toContain('data-testid="preview"');
-    expect(html).not.toContain('data-testid="tiptap"');
-  });
-});
\ No newline at end of file
+  i18nService: {
+    t: (key: string) => key,
+  },
+  useI18n: () => ({
+    t: (key: string) => key === 'editor.markdownEditor.notice.sourcePreviewFallback'
+      ? 'IR fallback warning'
+      : key,
+  }),
+}))
diff --git a/src/web-ui/src/tools/editor/meditor/components/MEditor.tsx b/src/web-ui/src/tools/editor/meditor/components/MEditor.tsx
index e8bc13c536..7bef7a5cdd 100644
--- a/src/web-ui/src/tools/editor/meditor/components/MEditor.tsx
+++ b/src/web-ui/src/tools/editor/meditor/components/MEditor.tsx
@@ -1,4 +1,16 @@
-import React, { useCallback, useEffect, useImperativeHandle, forwardRef, useMemo, useRef } from 'react'
+import React, {
+  Component,
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+  type ErrorInfo,
+  type ForwardedRef,
+  type ReactNode,
+} from 'react'
 import { createLogger } from '@/shared/utils/logger'
 import { activeEditTargetService } from '@/tools/editor/services/ActiveEditTargetService'
 import { useEditor } from '../hooks/useEditor'
@@ -8,9 +20,10 @@ import { Preview } from './Preview'
 import type { EditorOptions, EditorInstance } from '../types'
 import { useI18n } from '@/infrastructure/i18n'
 import { analyzeMarkdownEditability } from '../utils/tiptapMarkdown'
+import { AlertCircle } from 'lucide-react'
 import './MEditor.scss'
 
-void createLogger('MEditor')
+const log = createLogger('MEditor')
 let markdownTextareaTargetCounter = 0
 
 export type MEditorProps = EditorOptions;
@@ -37,7 +50,177 @@ function executeTextareaAction(
   return document.execCommand(action)
 }
 
-export const MEditor = forwardRef<EditorInstance, MEditorProps>((props, ref) => {
+const MEditorSourceFallback = forwardRef<EditorInstance, MEditorProps>((props, ref) => {
+  const {
+    value: controlledValue,
+    defaultValue = '',
+    height = '500px',
+    width = '100%',
+    readonly = false,
+    autofocus = false,
+    placeholder,
+    onChange,
+    onSave,
+    onFocus,
+    onBlur,
+    onDirtyChange,
+    className = '',
+    style = {},
+  } = props
+  const [uncontrolledValue, setUncontrolledValue] = useState(defaultValue)
+  const textareaRef = useRef<HTMLTextAreaElement>(null)
+  const savedValueRef = useRef(controlledValue ?? defaultValue)
+  const currentValue = controlledValue ?? uncontrolledValue
+  const currentValueRef = useRef(currentValue)
+  currentValueRef.current = currentValue
+
+  const updateValue = useCallback((nextValue: string) => {
+    currentValueRef.current = nextValue
+    if (controlledValue === undefined) {
+      setUncontrolledValue(nextValue)
+    }
+    onChange?.(nextValue)
+    onDirtyChange?.(nextValue !== savedValueRef.current)
+  }, [controlledValue, onChange, onDirtyChange])
+
+  useImperativeHandle(ref, () => ({
+    getValue: () => currentValueRef.current,
+    setValue: updateValue,
+    insertValue: (nextValue: string, start?: number, end?: number) => {
+      const selectionStart = start ?? textareaRef.current?.selectionStart ?? currentValueRef.current.length
+      const selectionEnd = end ?? textareaRef.current?.selectionEnd ?? selectionStart
+      updateValue(
+        currentValueRef.current.slice(0, selectionStart) +
+          nextValue +
+          currentValueRef.current.slice(selectionEnd)
+      )
+    },
+    focus: () => textareaRef.current?.focus(),
+    blur: () => textareaRef.current?.blur(),
+    setMode: () => undefined,
+    getSelection: () => {
+      const start = textareaRef.current?.selectionStart ?? 0
+      const end = textareaRef.current?.selectionEnd ?? start
+      return { start, end, text: currentValueRef.current.slice(start, end) }
+    },
+    destroy: () => undefined,
+    undo: () => executeTextareaAction(textareaRef.current, 'undo'),
+    redo: () => executeTextareaAction(textareaRef.current, 'redo'),
+    canUndo: false,
+    canRedo: false,
+    markSaved: () => {
+      savedValueRef.current = currentValueRef.current
+      onDirtyChange?.(false)
+    },
+    setInitialContent: (content: string) => {
+      savedValueRef.current = content
+      updateValue(content)
+      onDirtyChange?.(false)
+    },
+    get isDirty() {
+      return currentValueRef.current !== savedValueRef.current
+    },
+  }), [onDirtyChange, updateValue])
+
+  const containerStyle: React.CSSProperties = {
+    ...style,
+    height: typeof height === 'number' ? `${height}px` : height,
+    width: typeof width === 'number' ? `${width}px` : width,
+  }
+
+  // Sizes the textarea when the container has no definite height, where a CSS
+  // height cannot resolve and the element would collapse to the default two rows.
+  const rows = Math.max(currentValue.split('\n').length + 1, 4)
+
+  return (
+    <div
+      className={`m-editor m-editor-mode-source-fallback ${className}`}
+      data-bf-component="m-editor"
+      data-bf-part="root"
+      data-m-editor-fallback="true"
+      style={containerStyle}
+      onKeyDown={(event) => {
+        if ((event.ctrlKey || event.metaKey) && event.key === 's') {
+          event.preventDefault()
+          event.stopPropagation()
+          onSave?.(currentValueRef.current)
+        }
+      }}
+    >
+      <textarea
+        ref={textareaRef}
+        className="m-editor-source-fallback"
+        value={currentValue}
+        rows={rows}
+        readOnly={readonly}
+        autoFocus={autofocus}
+        placeholder={placeholder}
+        onChange={(event) => updateValue(event.target.value)}
+        onFocus={onFocus}
+        onBlur={onBlur}
+        spellCheck={false}
+      />
+    </div>
+  )
+})
+
+MEditorSourceFallback.displayName = 'MEditorSourceFallback'
+
+interface MEditorErrorBoundaryProps {
+  children: ReactNode
+  editorProps: MEditorProps
+  forwardedRef: ForwardedRef<EditorInstance>
+}
+
+interface MEditorErrorBoundaryState {
+  error: Error | null
+}
+
+export class MEditorErrorBoundary extends Component<
+  MEditorErrorBoundaryProps,
+  MEditorErrorBoundaryState
+> {
+  state: MEditorErrorBoundaryState = { error: null }
+
+  static getDerivedStateFromError(error: Error): MEditorErrorBoundaryState {
+    return { error }
+  }
+
+  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+    log.error('Markdown editor render failed, showing source fallback', {
+      message: error.message,
+      componentStack: errorInfo.componentStack,
+      filePath: this.props.editorProps.filePath,
+    })
+  }
+
+  // Only a new document clears the error. Retrying on every prop change would
+  // re-mount the editor that just threw and loop, because the failures this
+  // guards against (unsupported engine features) are deterministic.
+  componentDidUpdate(previousProps: MEditorErrorBoundaryProps) {
+    if (
+      this.state.error &&
+      previousProps.editorProps.filePath !== this.props.editorProps.filePath
+    ) {
+      this.setState({ error: null })
+    }
+  }
+
+  render() {
+    if (this.state.error) {
+      return (
+        <MEditorSourceFallback
+          {...this.props.editorProps}
+          ref={this.props.forwardedRef}
+        />
+      )
+    }
+
+    return this.props.children
+  }
+}
+
+const MEditorInner = forwardRef<EditorInstance, MEditorProps>((props, ref) => {
   const {
     value: controlledValue,
     defaultValue = '',
@@ -82,7 +265,12 @@ export const MEditor = forwardRef<EditorInstance, MEditorProps>((props, ref) =>
     () => progressivePreview ? analyzeMarkdownEditability('') : analyzeMarkdownEditability(value),
     [progressivePreview, value],
   )
-  const effectiveMode = mode === 'ir' && editability.containsRenderOnlyBlocks
+  const irNeedsSourceFallback = mode === 'ir' && (
+    editability.mode === 'unsafe' ||
+    editability.containsRenderOnlyBlocks ||
+    editability.containsRawHtmlInlines
+  )
+  const effectiveMode = irNeedsSourceFallback
     ? (readonly ? 'preview' : 'split')
     : mode
 
@@ -259,7 +447,13 @@ export const MEditor = forwardRef<EditorInstance, MEditorProps>((props, ref) =>
       tabIndex={-1}
     >
       {toolbar && <div data-bf-component="m-editor" data-bf-part="toolbar" className="m-editor-toolbar">{t('editor.meditor.toolbarPlaceholder')}</div>}
-      
+      {irNeedsSourceFallback && (
+        <div className="m-editor-notice" data-bf-component="m-editor" data-bf-part="notice">
+          <AlertCircle className="m-editor-notice__icon" />
+          <span>{t('editor.markdownEditor.notice.sourcePreviewFallback')}</span>
+        </div>
+      )}
+
       <div data-bf-component="m-editor" data-bf-part="content" className="m-editor-content">
         {effectiveMode === 'preview' && (
           <Preview value={value} basePath={basePath} progressive={progressivePreview} />
@@ -322,4 +516,12 @@ export const MEditor = forwardRef<EditorInstance, MEditorProps>((props, ref) =>
   )
 })
 
+MEditorInner.displayName = 'MEditorInner'
+
+export const MEditor = forwardRef<EditorInstance, MEditorProps>((props, ref) => (
+  <MEditorErrorBoundary editorProps={props} forwardedRef={ref}>
+    <MEditorInner {...props} ref={ref} />
+  </MEditorErrorBoundary>
+))
+
 MEditor.displayName = 'MEditor'
diff --git a/src/web-ui/src/tools/editor/meditor/components/Preview.scss b/src/web-ui/src/tools/editor/meditor/components/Preview.scss
index 447e265b1c..99f9f9bea6 100644
--- a/src/web-ui/src/tools/editor/meditor/components/Preview.scss
+++ b/src/web-ui/src/tools/editor/meditor/components/Preview.scss
@@ -9,4 +9,36 @@
     padding: $size-gap-4;
     overflow-x: auto;
   }
+
+  &-frontmatter {
+    margin: 0 0 $size-gap-4;
+    overflow: hidden;
+    border: 1px solid var(--bf-appearance-token-border-base);
+    border-radius: $size-radius-base;
+    background: var(--bf-appearance-token-element-bg-soft);
+
+    &__header {
+      display: flex;
+      align-items: center;
+      padding: $size-gap-2 $size-gap-3;
+      border-bottom: 1px solid var(--bf-appearance-token-border-base);
+    }
+
+    &__label {
+      color: var(--bf-appearance-token-color-text-secondary);
+      font-size: var(--bf-appearance-token-font-size-xs);
+      font-weight: $font-weight-semibold;
+    }
+
+    &__source {
+      margin: 0;
+      padding: $size-gap-3;
+      overflow-x: auto;
+      color: var(--bf-appearance-token-color-text-secondary);
+      font-family: var(--bf-appearance-token-font-family-mono);
+      font-size: var(--bf-appearance-token-font-size-sm);
+      line-height: 1.55;
+      white-space: pre;
+    }
+  }
 }
diff --git a/src/web-ui/src/tools/editor/meditor/components/Preview.test.tsx b/src/web-ui/src/tools/editor/meditor/components/Preview.test.tsx
new file mode 100644
index 0000000000..c58f24057a
--- /dev/null
+++ b/src/web-ui/src/tools/editor/meditor/components/Preview.test.tsx
@@ -0,0 +1,33 @@
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it, vi } from 'vitest';
+import { Preview } from './Preview';
+
+vi.mock('@/infrastructure/i18n', () => ({
+  useI18n: () => ({
+    t: (key: string) => key === 'editor.meditor.frontmatter.label'
+      ? 'YAML Frontmatter'
+      : key,
+  }),
+}));
+
+vi.mock('@/component-library', () => ({
+  MarkdownRenderer: ({ content }: { content: string }) => (
+    <div data-testid="markdown-renderer">{content}</div>
+  ),
+}));
+
+describe('Preview', () => {
+  it('shows frontmatter separately and renders only the markdown body', () => {
+    const html = renderToStaticMarkup(
+      <Preview value={'---\nname: Demo\n---\n\n# Body'} />,
+    );
+
+    expect(html).toContain('m-editor-preview-frontmatter');
+    expect(html).toContain('YAML Frontmatter');
+    expect(html).toContain('name: Demo');
+    expect(html).not.toContain('---');
+    expect(html).toContain('data-testid="markdown-renderer"');
+    expect(html).toContain('# Body');
+  });
+});
diff --git a/src/web-ui/src/tools/editor/meditor/components/Preview.tsx b/src/web-ui/src/tools/editor/meditor/components/Preview.tsx
index 34e662f391..7ccc6d36b5 100644
--- a/src/web-ui/src/tools/editor/meditor/components/Preview.tsx
+++ b/src/web-ui/src/tools/editor/meditor/components/Preview.tsx
@@ -1,5 +1,7 @@
 import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { MarkdownRenderer } from '@/component-library';
+import { useI18n } from '@/infrastructure/i18n';
+import { splitMarkdownFrontmatter } from '../utils/markdownFrontmatter';
 import './Preview.scss';
 
 interface PreviewProps {
@@ -58,23 +60,28 @@ export function shouldFillPreviewViewport(scrollHeight: number, clientHeight: nu
 }
 
 export const Preview: React.FC<PreviewProps> = ({ value, basePath, progressive = false }) => {
+  const { t } = useI18n('tools');
+  const frontmatter = useMemo(() => splitMarkdownFrontmatter(value), [value]);
+  const markdownValue = frontmatter?.body ?? value;
   const scrollContainerRef = useRef<HTMLDivElement>(null);
   const contentRef = useRef<HTMLDivElement>(null);
   const loadMoreScheduledRef = useRef(false);
   const loadMoreTimerRef = useRef<number | null>(null);
   const nextOffsetRef = useRef(0);
-  const hasMoreRef = useRef(progressive && value.length > 0);
+  const hasMoreRef = useRef(progressive && markdownValue.length > 0);
   const initialChunk = useMemo(
-    () => progressive ? takeNextMarkdownChunk(value, 0) : { content: value, nextOffset: value.length },
-    [progressive, value],
+    () => progressive
+      ? takeNextMarkdownChunk(markdownValue, 0)
+      : { content: markdownValue, nextOffset: markdownValue.length },
+    [markdownValue, progressive],
   );
   const [renderedChunks, setRenderedChunks] = useState<string[]>([initialChunk.content]);
 
   useEffect(() => {
     nextOffsetRef.current = initialChunk.nextOffset;
-    hasMoreRef.current = progressive && initialChunk.nextOffset < value.length;
+    hasMoreRef.current = progressive && initialChunk.nextOffset < markdownValue.length;
     setRenderedChunks(initialChunk.content ? [initialChunk.content] : []);
-  }, [initialChunk, progressive, value.length]);
+  }, [initialChunk, markdownValue.length, progressive]);
 
   const loadMore = useCallback(() => {
     if (loadMoreScheduledRef.current || !hasMoreRef.current) {
@@ -87,17 +94,17 @@ export const Preview: React.FC<PreviewProps> = ({ value, basePath, progressive =
       setRenderedChunks(current => {
         const additions: string[] = [];
         let offset = nextOffsetRef.current;
-        for (let index = 0; index < PROGRESSIVE_CHUNK_BATCH && offset < value.length; index += 1) {
-          const chunk = takeNextMarkdownChunk(value, offset);
+        for (let index = 0; index < PROGRESSIVE_CHUNK_BATCH && offset < markdownValue.length; index += 1) {
+          const chunk = takeNextMarkdownChunk(markdownValue, offset);
           additions.push(chunk.content);
           offset = chunk.nextOffset;
         }
         nextOffsetRef.current = offset;
-        hasMoreRef.current = offset < value.length;
+        hasMoreRef.current = offset < markdownValue.length;
         return additions.length > 0 ? [...current, ...additions] : current;
       });
     }, 0);
-  }, [value]);
+  }, [markdownValue]);
 
   useEffect(() => () => {
     if (loadMoreTimerRef.current !== null) {
@@ -149,6 +156,18 @@ export const Preview: React.FC<PreviewProps> = ({ value, basePath, progressive =
   return (
     <div ref={scrollContainerRef} className="m-editor-preview" data-bf-component="editor-tool" data-bf-part="meditorPreview">
       <div ref={contentRef} className="m-editor-preview-content">
+        {frontmatter && (
+          <section className="m-editor-preview-frontmatter" data-bf-component="editor-tool" data-bf-part="meditorFrontmatter">
+            <header className="m-editor-preview-frontmatter__header">
+              <span className="m-editor-preview-frontmatter__label">
+                {t('editor.meditor.frontmatter.label')}
+              </span>
+            </header>
+            <pre className="m-editor-preview-frontmatter__source">
+              <code>{frontmatter.yaml}</code>
+            </pre>
+          </section>
+        )}
         {renderedChunks.map((chunk, index) => (
           <div className="m-editor-preview-chunk" key={index} style={{ contentVisibility: 'auto', containIntrinsicSize: '800px' }}>
             <MarkdownRenderer content={chunk} basePath={basePath} />
diff --git a/src/web-ui/src/tools/editor/meditor/components/TiptapEditor.scss b/src/web-ui/src/tools/editor/meditor/components/TiptapEditor.scss
index ab07d7c20d..31873d380e 100644
--- a/src/web-ui/src/tools/editor/meditor/components/TiptapEditor.scss
+++ b/src/web-ui/src/tools/editor/meditor/components/TiptapEditor.scss
@@ -945,9 +945,28 @@
   }
 
   .m-editor-render-only-block,
-  .m-editor-raw-html-block {
+  .m-editor-raw-html-block,
+  .m-editor-frontmatter {
     margin: $size-gap-3 0;
+    overflow: hidden;
+    border: 1px solid var(--bf-appearance-token-border-base);
+    border-radius: $size-radius-base;
+    background: var(--bf-appearance-token-element-bg-soft);
+    color: var(--bf-appearance-token-color-text-secondary);
+  }
+
+  .m-editor-frontmatter__header {
+    display: flex;
+    align-items: center;
+    padding: $size-gap-2 $size-gap-3;
+    border-bottom: 1px solid var(--bf-appearance-token-border-base);
+    user-select: none;
+  }
+
+  .m-editor-frontmatter__label {
     color: var(--bf-appearance-token-color-text-secondary);
+    font-size: var(--bf-appearance-token-font-size-xs);
+    font-weight: $font-weight-semibold;
   }
 
   .m-editor-raw-html-inline {
@@ -980,12 +999,14 @@
   }
 
   .m-editor-render-only-block__body,
-  .m-editor-raw-html-block__body {
+  .m-editor-raw-html-block__body,
+  .m-editor-frontmatter__body {
     min-width: 0;
   }
 
   .m-editor-render-only-block__pane,
-  .m-editor-raw-html-block__pane {
+  .m-editor-raw-html-block__pane,
+  .m-editor-frontmatter__pane {
     min-width: 0;
     min-height: 0;
   }
@@ -993,22 +1014,27 @@
   .m-editor-render-only-block__pane--editor,
   .m-editor-render-only-block__pane--preview,
   .m-editor-raw-html-block__pane--editor,
-  .m-editor-raw-html-block__pane--preview {
+  .m-editor-raw-html-block__pane--preview,
+  .m-editor-frontmatter__pane--editor,
+  .m-editor-frontmatter__pane--preview {
     padding: 0;
   }
 
   .m-editor-render-only-block[data-editing='true'] .m-editor-render-only-block__pane--preview,
-  .m-editor-raw-html-block[data-editing='true'] .m-editor-raw-html-block__pane--preview {
+  .m-editor-raw-html-block[data-editing='true'] .m-editor-raw-html-block__pane--preview,
+  .m-editor-frontmatter[data-editing='true'] .m-editor-frontmatter__pane--preview {
     display: none;
   }
 
   .m-editor-render-only-block[data-editing='false'] .m-editor-render-only-block__pane--editor,
-  .m-editor-raw-html-block[data-editing='false'] .m-editor-raw-html-block__pane--editor {
+  .m-editor-raw-html-block[data-editing='false'] .m-editor-raw-html-block__pane--editor,
+  .m-editor-frontmatter[data-editing='false'] .m-editor-frontmatter__pane--editor {
     display: none;
   }
 
   .m-editor-render-only-block__textarea,
-  .m-editor-raw-html-block__textarea {
+  .m-editor-raw-html-block__textarea,
+  .m-editor-frontmatter__textarea {
     margin: 0;
     font-family: var(--bf-appearance-token-font-family-mono);
     font-size: var(--bf-appearance-token-font-size-sm);
@@ -1035,7 +1061,8 @@
   }
 
   .m-editor-render-only-block__preview,
-  .m-editor-raw-html-block__preview {
+  .m-editor-raw-html-block__preview,
+  .m-editor-frontmatter__preview {
     min-height: 180px;
     cursor: text;
     user-select: text;
@@ -1043,6 +1070,46 @@
     -webkit-user-drag: none;
   }
 
+  .m-editor-frontmatter__textarea {
+    min-height: 0;
+    box-sizing: border-box;
+    resize: none;
+    overflow-y: hidden;
+    border: 0;
+    border-radius: 0;
+    background: transparent;
+
+    &:focus {
+      border-color: transparent;
+      box-shadow: inset 0 0 0 1px var(--bf-appearance-token-border-base);
+    }
+  }
+
+  .m-editor-frontmatter__preview {
+    min-height: 0;
+  }
+
+  .m-editor-frontmatter__preview > .m-editor-frontmatter__source {
+    margin: 0;
+    padding: $size-gap-3;
+    overflow-x: auto;
+    border: 0;
+    border-radius: 0;
+    background: transparent;
+    box-shadow: none;
+    color: var(--bf-appearance-token-color-text-secondary);
+    font-family: var(--bf-appearance-token-font-family-mono);
+    font-size: var(--bf-appearance-token-font-size-sm);
+    line-height: 1.55;
+    white-space: pre;
+
+    &:hover {
+      border: 0;
+      background: transparent;
+      box-shadow: none;
+    }
+  }
+
   .m-editor-render-only-block__preview .m-editor-render-only-block__markdown,
   .m-editor-raw-html-block__preview .m-editor-raw-html-block__markdown {
     color: var(--bf-appearance-token-color-text-primary);
@@ -1069,7 +1136,8 @@
   }
 
   .m-editor-render-only-block__source-fallback,
-  .m-editor-raw-html-block__source-fallback {
+  .m-editor-raw-html-block__source-fallback,
+  .m-editor-frontmatter__source-fallback {
     display: none;
     margin: 0;
     font-family: var(--bf-appearance-token-font-family-mono);
diff --git a/src/web-ui/src/tools/editor/meditor/components/TiptapEditor.tsx b/src/web-ui/src/tools/editor/meditor/components/TiptapEditor.tsx
index 45404c3011..4d78cbd202 100644
--- a/src/web-ui/src/tools/editor/meditor/components/TiptapEditor.tsx
+++ b/src/web-ui/src/tools/editor/meditor/components/TiptapEditor.tsx
@@ -22,6 +22,7 @@ import { Input } from '@/component-library';
 import { editorAiAPI } from '@/infrastructure/api/service-api/EditorAiAPI';
 import { notificationService } from '@/shared/notification-system';
 import { createLogger } from '@/shared/utils/logger';
+import { getMotionAwareScrollBehavior } from '@/shared/utils/motionPreference';
 import { activeEditTargetService } from '@/tools/editor/services/ActiveEditTargetService';
 import { MarkdownAlignmentExtension } from '../extensions/MarkdownAlignmentExtension';
 import { BlockIdExtension } from '../extensions/BlockIdExtension';
@@ -36,7 +37,7 @@ import {
   InlineAiPreviewExtension,
 } from '../extensions/InlineAiPreviewExtension';
 import { inlineAiPreviewPluginKey } from '../extensions/InlineAiPreviewPluginKey';
-import { RawHtmlBlock, RawHtmlInline, RenderOnlyBlock } from '../extensions/RawHtmlExtensions';
+import { Frontmatter, RawHtmlBlock, RawHtmlInline, RenderOnlyBlock } from '../extensions/RawHtmlExtensions';
 import { getBlockIndexForLine } from '../utils/markdownBlocks';
 import {
   buildInlineContinuePrompt,
@@ -600,6 +601,9 @@ export const TiptapEditor = React.forwardRef<TiptapEditorHandle, TiptapEditorPro
       }),
       DetailsSummary,
       DetailsContent,
+      Frontmatter.configure({
+        label: t('editor.meditor.frontmatter.label'),
+      }),
       // Keep raw/render-only fallbacks for HTML we still can't round-trip safely.
       RenderOnlyBlock.configure({
         basePath,
@@ -886,7 +890,10 @@ export const TiptapEditor = React.forwardRef<TiptapEditorHandle, TiptapEditorPro
       return;
     }
 
-    element.scrollIntoView({ behavior: 'smooth', block: 'center' });
+    element.scrollIntoView({
+      behavior: getMotionAwareScrollBehavior('smooth'),
+      block: 'center',
+    });
 
     if (highlight) {
       element.classList.add('m-editor-tiptap-block-highlighted');
diff --git a/src/web-ui/src/tools/editor/meditor/extensions/BlockIdExtension.ts b/src/web-ui/src/tools/editor/meditor/extensions/BlockIdExtension.ts
index 2347f5fda3..60de1dde29 100644
--- a/src/web-ui/src/tools/editor/meditor/extensions/BlockIdExtension.ts
+++ b/src/web-ui/src/tools/editor/meditor/extensions/BlockIdExtension.ts
@@ -15,6 +15,7 @@ const TOP_LEVEL_TYPES = [
   'horizontalRule',
   'markdownTable',
   'details',
+  'frontmatter',
   'renderOnlyBlock',
   'rawHtmlBlock',
 ];
diff --git a/src/web-ui/src/tools/editor/meditor/extensions/RawHtmlExtensions.ts b/src/web-ui/src/tools/editor/meditor/extensions/RawHtmlExtensions.ts
index e7950d321d..3985fef903 100644
--- a/src/web-ui/src/tools/editor/meditor/extensions/RawHtmlExtensions.ts
+++ b/src/web-ui/src/tools/editor/meditor/extensions/RawHtmlExtensions.ts
@@ -6,6 +6,7 @@ import { activeEditTargetService } from '@/tools/editor/services/ActiveEditTarge
 
 type SourceBackedBlockOptions = {
   basePath?: string;
+  label?: string;
 };
 
 type RawHtmlInlineOptions = {
@@ -205,8 +206,9 @@ function executeTextareaAction(
 
 function createSourceBackedBlock(
   name: string,
-  valueAttr: 'html' | 'markdown',
+  valueAttr: 'html' | 'markdown' | 'yaml',
   className: string,
+  metadataAttrs: readonly string[] = [],
 ) {
   return Node.create<SourceBackedBlockOptions>({
     name,
@@ -220,6 +222,7 @@ function createSourceBackedBlock(
     addOptions() {
       return {
         basePath: undefined,
+        label: undefined,
       };
     },
 
@@ -228,6 +231,7 @@ function createSourceBackedBlock(
         [valueAttr]: {
           default: '',
         },
+        ...Object.fromEntries(metadataAttrs.map(attr => [attr, { default: '' }])),
         kind: {
           default: null,
         },
@@ -239,6 +243,10 @@ function createSourceBackedBlock(
         tag: `div[data-type="${name}"]`,
         getAttrs: element => ({
           [valueAttr]: element.getAttribute(`data-${valueAttr}`) ?? '',
+          ...Object.fromEntries(metadataAttrs.map(attr => [
+            attr,
+            element.getAttribute(`data-${attr.replace(/[A-Z]/g, letter => `-${letter.toLowerCase()}`)}`) ?? '',
+          ])),
           kind: element.getAttribute('data-kind'),
         }),
       }];
@@ -255,6 +263,10 @@ function createSourceBackedBlock(
         {
           'data-type': name,
           [`data-${valueAttr}`]: value,
+          ...Object.fromEntries(metadataAttrs.map(attr => [
+            `data-${attr.replace(/[A-Z]/g, letter => `-${letter.toLowerCase()}`)}`,
+            String(node.attrs[attr] ?? ''),
+          ])),
           ...(kind ? { 'data-kind': kind } : {}),
         },
       ];
@@ -268,6 +280,7 @@ function createSourceBackedBlock(
         let lastEditableState = editor.isEditable;
         let previewRoot: Root | null = null;
         let previewCheckTimer: number | null = null;
+        let frontmatterEditingMinHeight = 0;
         const textareaTargetId = `${name}-textarea-${++sourceBackedBlockTextareaTargetCounter}`;
         let unbindEditTarget: (() => void) | null = null;
 
@@ -291,6 +304,15 @@ function createSourceBackedBlock(
         textarea.draggable = false;
         textarea.setAttribute('draggable', 'false');
 
+        const syncFrontmatterTextareaHeight = () => {
+          if (name !== 'frontmatter' || !isEditing) {
+            return;
+          }
+
+          textarea.style.height = '0px';
+          textarea.style.height = `${Math.max(textarea.scrollHeight, frontmatterEditingMinHeight)}px`;
+        };
+
         editorPane.append(textarea);
 
         const previewPane = document.createElement('div');
@@ -308,6 +330,19 @@ function createSourceBackedBlock(
 
         previewPane.append(preview, sourceFallback);
         body.append(editorPane, previewPane);
+
+        if (this.options.label) {
+          const header = document.createElement('div');
+          header.className = `${className}__header`;
+
+          const label = document.createElement('span');
+          label.className = `${className}__label`;
+          label.textContent = this.options.label;
+
+          header.append(label);
+          dom.append(header);
+        }
+
         dom.append(body);
 
         const applyAttrs = (attrs: Record<string, unknown>) => {
@@ -338,12 +373,25 @@ function createSourceBackedBlock(
             return;
           }
 
+          if (name === 'frontmatter' && resolvedEditing) {
+            frontmatterEditingMinHeight = previewPane.getBoundingClientRect().height;
+          }
+
           isEditing = resolvedEditing;
           syncEditingState();
 
+          // Measure only after the editor pane has become visible. Measuring
+          // while CSS still hides it returns an incomplete scroll height.
+          syncFrontmatterTextareaHeight();
+
           if (resolvedEditing && options?.focus) {
             focusElementWithoutScroll(textarea);
           }
+
+          if (!resolvedEditing) {
+            frontmatterEditingMinHeight = 0;
+            textarea.style.height = '';
+          }
         };
 
         const exitEditing = () => {
@@ -351,6 +399,19 @@ function createSourceBackedBlock(
         };
 
         const renderPreview = (markdown: string) => {
+          if (name === 'frontmatter') {
+            previewRoot?.render(
+              React.createElement(
+                'pre',
+                { className: `${className}__source` },
+                React.createElement('code', null, markdown),
+              ),
+            );
+            sourceFallback.textContent = markdown;
+            dom.setAttribute('data-preview-empty', 'false');
+            return;
+          }
+
           const kind = typeof currentNode.attrs.kind === 'string' ? currentNode.attrs.kind : null;
           const detailsSource = kind === 'details' ? parseDetailsSource(markdown) : null;
           const shouldCheckPreviewVisibility = name === 'rawHtmlBlock' || kind === 'details';
@@ -456,6 +517,8 @@ function createSourceBackedBlock(
             textarea.value = value;
           }
 
+          syncFrontmatterTextareaHeight();
+
           textarea.readOnly = !editable;
           if (!editable && isEditing) {
             isEditing = false;
@@ -574,6 +637,7 @@ function createSourceBackedBlock(
         textarea.addEventListener('input', () => {
           const nextValue = textarea.value;
           lastSyncedValue = nextValue;
+          syncFrontmatterTextareaHeight();
           applyAttrs({ [valueAttr]: nextValue });
           void renderPreview(nextValue);
         });
@@ -654,6 +718,19 @@ export const RawHtmlBlock = createSourceBackedBlock(
   'm-editor-raw-html-block',
 );
 
+export const Frontmatter = createSourceBackedBlock(
+  'frontmatter',
+  'yaml',
+  'm-editor-frontmatter',
+  [
+    'delimiter',
+    'openingLineEnding',
+    'contentLineEnding',
+    'closingLineEnding',
+    'bodyPrefix',
+  ],
+);
+
 export const RawHtmlInline = Node.create<RawHtmlInlineOptions>({
   name: 'rawHtmlInline',
   group: 'inline',
diff --git a/src/web-ui/src/tools/editor/meditor/utils/markdownFrontmatter.test.ts b/src/web-ui/src/tools/editor/meditor/utils/markdownFrontmatter.test.ts
new file mode 100644
index 0000000000..056d0f6711
--- /dev/null
+++ b/src/web-ui/src/tools/editor/meditor/utils/markdownFrontmatter.test.ts
@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+import { splitMarkdownFrontmatter } from './markdownFrontmatter';
+
+describe('splitMarkdownFrontmatter', () => {
+  it('keeps the complete frontmatter envelope and body boundary', () => {
+    const markdown = '---\nname: Demo\n---\n\n# Body';
+
+    expect(splitMarkdownFrontmatter(markdown)).toEqual({
+      raw: '---\nname: Demo\n---\n',
+      body: '\n# Body',
+      delimiter: '---',
+      yaml: 'name: Demo',
+      openingLineEnding: '\n',
+      contentLineEnding: '\n',
+      closingLineEnding: '\n',
+    });
+  });
+
+  it('does not treat a thematic break in the body as frontmatter', () => {
+    expect(splitMarkdownFrontmatter('---\n\n# Body')).toBeNull();
+  });
+
+  it('supports an empty frontmatter envelope', () => {
+    expect(splitMarkdownFrontmatter('---\n---\n# Body')).toEqual({
+      raw: '---\n---\n',
+      body: '# Body',
+      delimiter: '---',
+      yaml: '',
+      openingLineEnding: '\n',
+      contentLineEnding: '',
+      closingLineEnding: '\n',
+    });
+  });
+
+  it('keeps every line ending after the closing delimiter in the body', () => {
+    expect(splitMarkdownFrontmatter('---\r\nname: Demo\r\n---\r\n\r\n\r\n# Body')).toMatchObject({
+      raw: '---\r\nname: Demo\r\n---\r\n',
+      body: '\r\n\r\n# Body',
+      yaml: 'name: Demo',
+      openingLineEnding: '\r\n',
+      contentLineEnding: '\r\n',
+      closingLineEnding: '\r\n',
+    });
+  });
+});
diff --git a/src/web-ui/src/tools/editor/meditor/utils/markdownFrontmatter.ts b/src/web-ui/src/tools/editor/meditor/utils/markdownFrontmatter.ts
new file mode 100644
index 0000000000..79fa602ed7
--- /dev/null
+++ b/src/web-ui/src/tools/editor/meditor/utils/markdownFrontmatter.ts
@@ -0,0 +1,72 @@
+export interface MarkdownFrontmatterSplit {
+  raw: string;
+  body: string;
+  delimiter: '---' | '+++';
+  yaml: string;
+  openingLineEnding: '\n' | '\r\n';
+  contentLineEnding: '' | '\n' | '\r\n';
+  closingLineEnding: '' | '\n' | '\r\n';
+}
+
+/**
+ * Split leading YAML/TOML-style frontmatter without parsing or normalizing it.
+ * `raw` ends after the first line ending following the closing delimiter. Any
+ * additional blank lines belong to `body`, so joining `raw + body` preserves
+ * the source document byte-for-byte.
+ */
+export function splitMarkdownFrontmatter(markdown: string): MarkdownFrontmatterSplit | null {
+  const openingMatch = markdown.match(/^(---|\+\+\+)(\r?\n)/);
+  if (!openingMatch) {
+    return null;
+  }
+
+  const delimiter = openingMatch[1] as MarkdownFrontmatterSplit['delimiter'];
+  const openingLineEnding = openingMatch[2] as MarkdownFrontmatterSplit['openingLineEnding'];
+  const afterOpening = markdown.slice(openingMatch[0].length);
+  const escapedDelimiter = delimiter.replace(/\+/g, '\\+');
+  const closingPattern = new RegExp(`^${escapedDelimiter}(?:((?:\\r?\\n))|$)`, 'm');
+  const closingMatch = closingPattern.exec(afterOpening);
+  if (!closingMatch) {
+    return null;
+  }
+
+  const yamlWithStructuralEnding = afterOpening.slice(0, closingMatch.index);
+  const contentLineEndingMatch = yamlWithStructuralEnding.match(/(\r?\n)$/);
+  const contentLineEnding = (contentLineEndingMatch?.[1] ?? '') as MarkdownFrontmatterSplit['contentLineEnding'];
+  const yaml = contentLineEnding
+    ? yamlWithStructuralEnding.slice(0, -contentLineEnding.length)
+    : yamlWithStructuralEnding;
+  const closingLineEnding = (closingMatch[1] ?? '') as MarkdownFrontmatterSplit['closingLineEnding'];
+  const rawLength = openingMatch[0].length + closingMatch.index + closingMatch[0].length;
+  const raw = markdown.slice(0, rawLength);
+
+  return {
+    raw,
+    body: markdown.slice(raw.length),
+    delimiter,
+    yaml,
+    openingLineEnding,
+    contentLineEnding,
+    closingLineEnding,
+  };
+}
+
+export function serializeMarkdownFrontmatter(
+  frontmatter: Pick<
+    MarkdownFrontmatterSplit,
+    'delimiter' | 'yaml' | 'openingLineEnding' | 'contentLineEnding' | 'closingLineEnding'
+  >,
+): string {
+  const contentLineEnding = frontmatter.contentLineEnding || (
+    frontmatter.yaml ? frontmatter.openingLineEnding : ''
+  );
+
+  return [
+    frontmatter.delimiter,
+    frontmatter.openingLineEnding,
+    frontmatter.yaml,
+    contentLineEnding,
+    frontmatter.delimiter,
+    frontmatter.closingLineEnding,
+  ].join('');
+}
diff --git a/src/web-ui/src/tools/editor/meditor/utils/tiptapMarkdown.test.ts b/src/web-ui/src/tools/editor/meditor/utils/tiptapMarkdown.test.ts
index 0b18a501ba..35ab3716b5 100644
--- a/src/web-ui/src/tools/editor/meditor/utils/tiptapMarkdown.test.ts
+++ b/src/web-ui/src/tools/editor/meditor/utils/tiptapMarkdown.test.ts
@@ -5,6 +5,7 @@ import {
   getUnsupportedTiptapMarkdownFeatures,
   markdownToTiptapDoc,
   tiptapDocToMarkdown,
+  tiptapDocToTopLevelMarkdownBlocks,
 } from './tiptapMarkdown';
 
 describe('tiptap markdown compatibility', () => {
@@ -55,6 +56,29 @@ describe('tiptap markdown compatibility', () => {
     expect(getUnsupportedTiptapMarkdownFeatures(markdown)).toEqual([]);
   });
 
+  it('parses gfm email autolinks without lookbehind-dependent behavior', () => {
+    const markdown = 'Contact support@example.com or see /admin@example.com.';
+
+    const doc = markdownToTiptapDoc(markdown);
+    const paragraph = doc.content?.[0];
+    const emailNode = paragraph?.content?.find(node =>
+      node.marks?.some(mark =>
+        mark.type === 'link' && mark.attrs?.href === 'mailto:support@example.com'
+      )
+    );
+    const slashEmailNode = paragraph?.content?.find(node =>
+      node.marks?.some(mark =>
+        mark.type === 'link' && mark.attrs?.href === 'mailto:admin@example.com'
+      )
+    );
+
+    expect(emailNode?.text).toBe('support@example.com');
+    expect(slashEmailNode).toBeUndefined();
+    expect(tiptapDocToMarkdown(doc)).toBe(
+      'Contact [support@example.com](mailto:support@example.com) or see /admin@example.com.'
+    );
+  });
+
   it('supports deep heading levels', () => {
     const markdown = '#### Deep heading';
 
@@ -123,7 +147,7 @@ describe('tiptap markdown compatibility', () => {
     expect(getUnsupportedTiptapMarkdownFeatures(markdown)).toContain('roundTripMismatch');
   });
 
-  it('treats frontmatter as unsafe for the IR editor', () => {
+  it('preserves frontmatter as an editable IR block', () => {
     const markdown = [
       '---',
       'name: Demo',
@@ -137,11 +161,52 @@ describe('tiptap markdown compatibility', () => {
 
     const analysis = analyzeMarkdownEditability(markdown);
 
-    expect(analysis.mode).toBe('unsafe');
-    expect(analysis.hardIssues).toContain('frontmatter');
-    expect(analysis.hardIssues).toContain('semanticMismatch');
-    expect(analysis.softIssues).toContain('roundTripMismatch');
-    expect(analysis.canonicalMarkdown).toContain('## name: Demo');
+    const doc = markdownToTiptapDoc(markdown);
+
+    expect(analysis.mode).toBe('lossless');
+    expect(analysis.hardIssues).toEqual([]);
+    expect(analysis.softIssues).toEqual([]);
+    expect(analysis.canonicalMarkdown).toBe(markdown);
+    expect(doc.content?.[0]).toMatchObject({
+      type: 'frontmatter',
+      attrs: {
+        yaml: expect.stringContaining('name: Demo'),
+        delimiter: '---',
+        bodyPrefix: '\n',
+      },
+    });
+    expect(tiptapDocToMarkdown(doc)).toBe(markdown);
+    expect(tiptapDocToTopLevelMarkdownBlocks(doc)).toEqual([
+      expect.objectContaining({ markdown: '# Body' }),
+    ]);
+  });
+
+  it('preserves TOML-style frontmatter delimiters and CRLF inside the envelope', () => {
+    const markdown = '+++\r\ntitle = "Demo"\r\n+++\r\n\r\n# Body\r\n';
+    const doc = markdownToTiptapDoc(markdown);
+
+    expect(doc.content?.[0]?.type).toBe('frontmatter');
+    expect(doc.content?.[0]?.attrs).toMatchObject({
+      yaml: 'title = "Demo"',
+      delimiter: '+++',
+      openingLineEnding: '\r\n',
+      contentLineEnding: '\r\n',
+      closingLineEnding: '\r\n',
+      bodyPrefix: '\r\n',
+    });
+    expect(tiptapDocToMarkdown(doc, { preserveTrailingNewline: true })).toBe(
+      '+++\r\ntitle = "Demo"\r\n+++\r\n\r\n# Body\n',
+    );
+  });
+
+  it('rebuilds structural delimiters around edited frontmatter content', () => {
+    const doc = markdownToTiptapDoc('---\nname: Demo\n---\n\n# Body');
+    const frontmatter = doc.content?.[0];
+
+    expect(frontmatter?.attrs).toBeDefined();
+    frontmatter!.attrs!.yaml = 'name: Updated';
+
+    expect(tiptapDocToMarkdown(doc)).toBe('---\nname: Updated\n---\n\n# Body');
   });
 
   it('upgrades simple details regions into structured details nodes', () => {
diff --git a/src/web-ui/src/tools/editor/meditor/utils/tiptapMarkdown.ts b/src/web-ui/src/tools/editor/meditor/utils/tiptapMarkdown.ts
index 3eb85f1b82..bc244796a1 100644
--- a/src/web-ui/src/tools/editor/meditor/utils/tiptapMarkdown.ts
+++ b/src/web-ui/src/tools/editor/meditor/utils/tiptapMarkdown.ts
@@ -5,6 +5,7 @@ import remarkRehype from 'remark-rehype';
 import rehypeRaw from 'rehype-raw';
 import type { JSONContent } from '@tiptap/core';
 import { createBlockId } from './blockId';
+import { serializeMarkdownFrontmatter, splitMarkdownFrontmatter } from './markdownFrontmatter';
 
 type MdastNode = {
   type?: string;
@@ -108,6 +109,7 @@ const TOP_LEVEL_BLOCK_TYPES = new Set([
   'horizontalRule',
   'markdownTable',
   'details',
+  'frontmatter',
   'renderOnlyBlock',
   'rawHtmlBlock',
 ]);
@@ -196,6 +198,45 @@ function createRenderOnlyBlock(markdown: string, kind: string): JSONContent {
   };
 }
 
+function createFrontmatterBlock(
+  frontmatter: NonNullable<ReturnType<typeof splitMarkdownFrontmatter>>,
+  bodyPrefix: string,
+): JSONContent {
+  return {
+    type: 'frontmatter',
+    attrs: {
+      yaml: frontmatter.yaml,
+      delimiter: frontmatter.delimiter,
+      openingLineEnding: frontmatter.openingLineEnding,
+      contentLineEnding: frontmatter.contentLineEnding,
+      closingLineEnding: frontmatter.closingLineEnding,
+      bodyPrefix,
+    },
+  };
+}
+
+function getLeadingBlankLines(markdown: string): string {
+  return markdown.match(/^(?:[\t ]*\r?\n)+/)?.[0] ?? '';
+}
+
+function serializeFrontmatterNode(node: JSONContent): string {
+  return serializeMarkdownFrontmatter({
+    delimiter: node.attrs?.delimiter === '+++' ? '+++' : '---',
+    yaml: String(node.attrs?.yaml ?? ''),
+    openingLineEnding: node.attrs?.openingLineEnding === '\r\n' ? '\r\n' : '\n',
+    contentLineEnding: node.attrs?.contentLineEnding === '\r\n'
+      ? '\r\n'
+      : node.attrs?.contentLineEnding === '\n'
+        ? '\n'
+        : '',
+    closingLineEnding: node.attrs?.closingLineEnding === '\r\n'
+      ? '\r\n'
+      : node.attrs?.closingLineEnding === '\n'
+        ? '\n'
+        : '',
+  });
+}
+
 function withBlockAttrs(node: JSONContent, align: string | null, alignGroup: number | null): JSONContent {
   if (!node.type || !TOP_LEVEL_BLOCK_TYPES.has(node.type)) {
     return node;
@@ -708,10 +749,6 @@ function parseMarkdownTree(markdown: string): MdastNode {
     .parse(markdown) as MdastNode;
 }
 
-function hasMarkdownFrontmatter(markdown: string): boolean {
-  return /^(---|\+\+\+)\r?\n[\s\S]*?\r?\n\1(?:\r?\n|$)/.test(markdown);
-}
-
 function normalizeComparableJson(
   value: ComparableJsonValue,
   keysToStrip: Set<string>,
@@ -1224,11 +1261,8 @@ export function analyzeMarkdownEditability(markdown: string): MarkdownEditabilit
     softIssues.add('multipleTrailingBlankLines');
   }
 
-  if (hasMarkdownFrontmatter(markdown)) {
-    hardIssues.add('frontmatter');
-  }
-
-  const tree = parseMarkdownTree(markdown);
+  const frontmatter = splitMarkdownFrontmatter(markdown);
+  const tree = parseMarkdownTree(frontmatter?.body ?? markdown);
 
   walkMdast(tree, (node) => {
     if (node.type === 'footnoteDefinition' || node.type === 'footnoteReference') {
@@ -1614,6 +1648,8 @@ function renderBlock(node: JSONContent, depth = 0): string {
     }
     case 'horizontalRule':
       return '---';
+    case 'frontmatter':
+      return serializeFrontmatterNode(node);
     case 'details': {
       const summaryNode = getDetailsChild(node, 'detailsSummary');
       const detailsContentNode = getDetailsChild(node, 'detailsContent');
@@ -1673,9 +1709,16 @@ function wrapAlignedMarkdownBlocks(markdownBlocks: string[], align: string | nul
 }
 
 export function markdownToTiptapDoc(markdown: string): JSONContent {
-  const tree = parseMarkdownTree(markdown);
+  const frontmatter = splitMarkdownFrontmatter(markdown);
+  const bodyPrefix = frontmatter ? getLeadingBlankLines(frontmatter.body) : '';
+  const markdownBody = frontmatter ? frontmatter.body.slice(bodyPrefix.length) : markdown;
+  const tree = parseMarkdownTree(markdownBody);
 
-  const content = withTopLevelBlockIds(convertRootMarkdownChildren(tree.children ?? [], markdown));
+  const bodyContent = convertRootMarkdownChildren(tree.children ?? [], markdownBody);
+  const content = withTopLevelBlockIds([
+    ...(frontmatter ? [createFrontmatterBlock(frontmatter, bodyPrefix)] : []),
+    ...bodyContent,
+  ]);
 
   return {
     type: 'doc',
@@ -1688,6 +1731,8 @@ export function tiptapDocToMarkdown(
   options: TiptapMarkdownOptions = {},
 ): string {
   const content = doc?.content ?? [];
+  const frontmatterNode = content[0]?.type === 'frontmatter' ? content[0] : null;
+  const renderableContent = frontmatterNode ? content.slice(1) : content;
   const chunks: string[] = [];
   let group: string[] = [];
   let groupAlign: string | null = null;
@@ -1704,7 +1749,7 @@ export function tiptapDocToMarkdown(
     groupAlignId = null;
   };
 
-  content.forEach((node: JSONContent) => {
+  renderableContent.forEach((node: JSONContent) => {
     const rendered = renderBlock(node);
     if (!rendered) {
       return;
@@ -1742,18 +1787,31 @@ export function tiptapDocToMarkdown(
     .join('\n\n')
     .replace(/<\/div>\n\n<div\b/g, '</div>\n<div');
 
+  const frontmatterRaw = frontmatterNode ? serializeFrontmatterNode(frontmatterNode) : '';
+  const frontmatterBodyPrefix = frontmatterNode ? String(frontmatterNode.attrs?.bodyPrefix ?? '') : '';
+  const frontmatterEnvelope = `${frontmatterRaw}${frontmatterBodyPrefix}`;
   if (!markdown) {
-    return '';
+    if (!frontmatterEnvelope) {
+      return '';
+    }
+    return options.preserveTrailingNewline && !frontmatterEnvelope.endsWith('\n')
+      ? `${frontmatterEnvelope}\n`
+      : frontmatterEnvelope;
   }
 
-  return options.preserveTrailingNewline ? `${markdown}\n` : markdown;
+  const combinedMarkdown = `${frontmatterEnvelope}${markdown}`;
+  return options.preserveTrailingNewline && !combinedMarkdown.endsWith('\n')
+    ? `${combinedMarkdown}\n`
+    : combinedMarkdown;
 }
 
 export function tiptapDocToTopLevelMarkdownBlocks(
   doc: JSONContent | null | undefined,
 ): TiptapTopLevelMarkdownBlock[] {
-  return (doc?.content ?? []).map((node: JSONContent) => ({
-    blockId: typeof node.attrs?.blockId === 'string' ? node.attrs.blockId : undefined,
-    markdown: renderBlock(node).trim(),
-  }));
+  return (doc?.content ?? [])
+    .filter((node: JSONContent) => node.type !== 'frontmatter')
+    .map((node: JSONContent) => ({
+      blockId: typeof node.attrs?.blockId === 'string' ? node.attrs.blockId : undefined,
+      markdown: renderBlock(node).trim(),
+    }));
 }
diff --git a/src/web-ui/src/tools/editor/services/EditorManager.test.ts b/src/web-ui/src/tools/editor/services/EditorManager.test.ts
new file mode 100644
index 0000000000..dea5b71117
--- /dev/null
+++ b/src/web-ui/src/tools/editor/services/EditorManager.test.ts
@@ -0,0 +1,73 @@
+// @vitest-environment jsdom
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const invokeMock = vi.hoisted(() => vi.fn());
+const tauriInvokeMock = vi.hoisted(() => vi.fn());
+
+vi.mock('@/infrastructure/api/service-api/ApiClient', () => ({
+  api: {
+    invoke: invokeMock,
+    listen: vi.fn(() => () => {}),
+  },
+}));
+
+vi.mock('@tauri-apps/api/core', () => ({
+  invoke: tauriInvokeMock,
+}));
+
+vi.mock('@/shared/utils/logger', () => ({
+  createLogger: () => ({
+    debug: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+  }),
+}));
+
+import { EditorManager } from './EditorManager';
+import { resetDeviceSurfaceForTest } from '@/infrastructure/peer-device/deviceSurface';
+
+function fileContent(name: string, content: string) {
+  return { name, content, path: `/repo/${name}`, language: 'typescript' } as never;
+}
+
+describe('EditorManager device surface teardown', () => {
+  beforeEach(() => {
+    invokeMock.mockReset();
+    tauriInvokeMock.mockReset();
+    resetDeviceSurfaceForTest();
+  });
+
+  afterEach(() => {
+    resetDeviceSurfaceForTest();
+  });
+
+  it('sends nothing to the device being left when a switch destroys editor state', async () => {
+    const editor = new EditorManager({ autoSave: 'off' });
+    const index = await editor.openFile(fileContent('main.ts', 'const a = 1;'));
+    editor.updateFileContent(index, 'const a = 2;');
+    expect(editor.isFileDirty(index)).toBe(true);
+    invokeMock.mockClear();
+    tauriInvokeMock.mockClear();
+
+    editor.destroy();
+
+    expect(invokeMock).not.toHaveBeenCalled();
+    expect(tauriInvokeMock).not.toHaveBeenCalled();
+    expect(editor.getAllFiles()).toEqual([]);
+  });
+
+  it('abandons a close whose file list was torn down mid-prompt', async () => {
+    const editor = new EditorManager({ autoSave: 'off' });
+    const index = await editor.openFile(fileContent('main.ts', 'const a = 1;'));
+    editor.updateFileContent(index, 'const a = 2;');
+
+    const closing = editor.closeFile(index);
+    editor.destroy();
+    await editor.openFile(fileContent('peer.ts', 'export {};'));
+    await closing;
+
+    expect(editor.getAllFiles().map(file => file.name)).toEqual(['peer.ts']);
+  });
+});
diff --git a/src/web-ui/src/tools/editor/services/EditorManager.ts b/src/web-ui/src/tools/editor/services/EditorManager.ts
index 7b8d02a04f..6281b832a7 100644
--- a/src/web-ui/src/tools/editor/services/EditorManager.ts
+++ b/src/web-ui/src/tools/editor/services/EditorManager.ts
@@ -13,6 +13,7 @@ import {
 import { globalEventBus } from '../../../infrastructure/event-bus';
 import { getMonacoLanguage } from '@/infrastructure/language-detection';
 import { createLogger } from '@/shared/utils/logger';
+import { getActiveSurfaceScope } from '@/infrastructure/peer-device/deviceSurface';
 import { storage } from '@/shared/utils/storageAdapter';
 
 const log = createLogger('EditorManager');
@@ -90,6 +91,8 @@ export class EditorManager implements IEditorManager {
   private config: EditorConfig;
   private listeners = new Set<(event: EditorEvent) => void>();
   private autoSaveTimers = new Map<number, ReturnType<typeof setTimeout>>();
+  /** Bumped by `destroy()`; identifies the file list an async edit started on. */
+  private fileSetGeneration = 0;
 
   constructor(initialConfig?: Partial<EditorConfig>) {
     this.config = { ...DEFAULT_CONFIG, ...initialConfig };
@@ -141,7 +144,9 @@ export class EditorManager implements IEditorManager {
     }
 
     const file = this.openFiles[index];
-    
+    const scope = getActiveSurfaceScope();
+    const generation = this.fileSetGeneration;
+
     if (file.isDirty) {
       const shouldSave = await this.promptSave(file);
       if (shouldSave) {
@@ -149,6 +154,13 @@ export class EditorManager implements IEditorManager {
       }
     }
 
+    // The save prompt is an await window wide enough for a device surface
+    // switch. Indices are positions in a file list that no longer exists, so
+    // splicing one here would close an unrelated file on the new surface.
+    if (this.fileSetGeneration !== generation || !scope.isCurrent()) {
+      return;
+    }
+
     this.clearAutoSave(index);
 
     this.openFiles.splice(index, 1);
@@ -434,7 +446,14 @@ export class EditorManager implements IEditorManager {
     }
   }
 
+  /**
+   * Drop editor state. Frontend-only, and must stay that way: a device surface
+   * switch calls this before the transport swaps, so flushing dirty buffers or
+   * any other backend write here would land on the device being left.
+   */
   destroy(): void {
+    this.fileSetGeneration += 1;
+
     this.autoSaveTimers.forEach(timer => clearTimeout(timer));
     this.autoSaveTimers.clear();
     
diff --git a/src/web-ui/src/tools/file-system/components/FileExplorer.rendering.test.ts b/src/web-ui/src/tools/file-system/components/FileExplorer.rendering.test.ts
new file mode 100644
index 0000000000..51f60d38bd
--- /dev/null
+++ b/src/web-ui/src/tools/file-system/components/FileExplorer.rendering.test.ts
@@ -0,0 +1,27 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+function readSource(relativePath: string): string {
+  return readFileSync(fileURLToPath(new URL(relativePath, import.meta.url)), 'utf8')
+    .replace(/\r\n/g, '\n');
+}
+
+describe('FileExplorer rendering contract', () => {
+  it('keeps one virtual tree renderer as the visible node count changes', () => {
+    const source = readSource('./FileExplorer.tsx');
+
+    expect(source).toContain("import { VirtualFileTree } from './VirtualFileTree';");
+    expect(source).toContain('<VirtualFileTree');
+    expect(source).not.toContain('VIRTUAL_SCROLL_THRESHOLD');
+    expect(source).not.toContain("import { FileTree } from './FileTree';");
+    expect(source).not.toContain('useVirtualScroll ?');
+  });
+
+  it('reserves the virtual scroller gutter so row width stays stable', () => {
+    const stylesheet = readSource('../styles/FileExplorer.scss');
+
+    expect(stylesheet).toContain('.bitfun-file-explorer__tree--virtual > div');
+    expect(stylesheet).toContain('scrollbar-gutter: stable;');
+  });
+});
diff --git a/src/web-ui/src/tools/file-system/components/FileExplorer.tsx b/src/web-ui/src/tools/file-system/components/FileExplorer.tsx
index 7190fbe3c6..612a851bab 100644
--- a/src/web-ui/src/tools/file-system/components/FileExplorer.tsx
+++ b/src/web-ui/src/tools/file-system/components/FileExplorer.tsx
@@ -2,8 +2,7 @@ import React, { useState, useCallback, useMemo, useRef, useEffect } from 'react'
 import { useShortcut } from '@/infrastructure/hooks/useShortcut';
 import { shortcutManager } from '@/infrastructure/services/ShortcutManager';
 import { FILETREE_SHORTCUTS } from '@/shared/constants/shortcuts';
-import { Folder, ChevronRight, FilePlus, FolderPlus, RefreshCw } from 'lucide-react';
-import { FileTree } from './FileTree';
+import { Folder, FilePlus, FolderPlus, RefreshCw } from 'lucide-react';
 import { VirtualFileTree } from './VirtualFileTree';
 import { FileExplorerProps, FileSystemNode, FlatFileNode } from '../types';
 import { flattenFileTree } from '../utils/treeFlattening';
@@ -47,7 +46,6 @@ function buildFileNodeContext(node: FileSystemNode, workspacePath?: string): Fil
   };
 }
 
-const VIRTUAL_SCROLL_THRESHOLD = 100;
 const getShortcutConfig = (id: string) => {
   const defaultConfig = FILETREE_SHORTCUTS.find((shortcut) => shortcut.id === id)?.config;
   if (!defaultConfig) {
@@ -63,132 +61,6 @@ function withShortcut(label: string, config: typeof NEW_FILE_SHORTCUT): string {
   return `${label} (${shortcutManager.formatShortcut(config)})`;
 }
 
-interface ScrollBreadcrumbProps {
-  containerRef: React.RefObject<HTMLDivElement>;
-  workspacePath?: string;
-  onNavigate?: (path: string) => void;
-}
-
-const ScrollBreadcrumb: React.FC<ScrollBreadcrumbProps> = ({ containerRef, workspacePath, onNavigate }) => {
-  const [visiblePath, setVisiblePath] = useState<string | null>(null);
-  
-  useEffect(() => {
-    const container = containerRef.current;
-    if (!container) return;
-    
-    const detectCurrentDirectory = () => {
-      const treeContainer = container.querySelector('.bitfun-file-explorer__tree');
-      if (!treeContainer) return;
-      
-      const containerRect = treeContainer.getBoundingClientRect();
-      
-      const expandedDirNodes = treeContainer.querySelectorAll('[data-is-directory="true"][data-is-expanded="true"]');
-      
-      const activeDirs: { path: string; top: number }[] = [];
-      
-      expandedDirNodes.forEach((node) => {
-        const rect = node.getBoundingClientRect();
-        const relativeTop = rect.top - containerRect.top;
-        const path = node.getAttribute('data-file-path');
-        
-        if (!path) return;
-        
-        if (relativeTop >= 0) return;
-        
-        const nodeElement = node.closest('.bitfun-file-explorer__node');
-        const childrenContainer = nodeElement?.querySelector(':scope > .bitfun-file-explorer__node-children');
-        
-        if (childrenContainer) {
-          const childrenRect = childrenContainer.getBoundingClientRect();
-          const childrenBottom = childrenRect.bottom - containerRect.top;
-          
-          if (childrenBottom > 0) {
-            activeDirs.push({ path, top: relativeTop });
-          }
-        }
-      });
-      
-      if (activeDirs.length > 0) {
-        activeDirs.sort((a, b) => b.top - a.top);
-        setVisiblePath(activeDirs[0].path);
-      } else {
-        setVisiblePath(null);
-      }
-    };
-
-    detectCurrentDirectory();
-
-    // rAF-merge the raw scroll events: the detection walks every expanded
-    // directory node and reads two rects per node, so run it at most once
-    // per frame instead of per scroll event.
-    let frameId: number | null = null;
-    const handleScroll = () => {
-      if (frameId !== null) return;
-      frameId = requestAnimationFrame(() => {
-        frameId = null;
-        detectCurrentDirectory();
-      });
-    };
-
-    const treeContainer = container.querySelector('.bitfun-file-explorer__tree');
-    if (treeContainer) {
-      treeContainer.addEventListener('scroll', handleScroll, { passive: true });
-      return () => {
-        treeContainer.removeEventListener('scroll', handleScroll);
-        if (frameId !== null) {
-          cancelAnimationFrame(frameId);
-        }
-      };
-    }
-    return () => {
-      if (frameId !== null) {
-        cancelAnimationFrame(frameId);
-      }
-    };
-  }, [containerRef]);
-  
-  if (!visiblePath) return null;
-  
-  let relativePath = visiblePath;
-  if (workspacePath && visiblePath.startsWith(workspacePath)) {
-    relativePath = visiblePath.slice(workspacePath.length).replace(/^[/\\]/, '');
-  }
-  
-  const parts = relativePath.split(/[/\\]/).filter(Boolean);
-  if (parts.length === 0) return null;
-  
-  const pathSegments: { name: string; fullPath: string }[] = [];
-  let currentPath = workspacePath || '';
-  
-  for (const part of parts) {
-    currentPath = currentPath ? `${currentPath}/${part}` : part;
-    pathSegments.push({ name: part, fullPath: currentPath });
-  }
-  
-  const displaySegments = pathSegments.length > 4 
-    ? [{ name: '…', fullPath: '' }, ...pathSegments.slice(-4)]
-    : pathSegments;
-  
-  return (
-    <div className="bitfun-file-explorer__breadcrumb">
-      {displaySegments.map((segment, index) => (
-        <React.Fragment key={segment.fullPath || index}>
-          {index > 0 && (
-            <ChevronRight size={10} className="bitfun-file-explorer__breadcrumb-separator" />
-          )}
-          <span 
-            className={`bitfun-file-explorer__breadcrumb-item ${segment.fullPath ? 'bitfun-file-explorer__breadcrumb-item--clickable' : ''}`}
-            onClick={() => segment.fullPath && onNavigate?.(segment.fullPath)}
-            title={segment.fullPath || undefined}
-          >
-            {segment.name}
-          </span>
-        </React.Fragment>
-      ))}
-    </div>
-  );
-};
-
 export const FileExplorer: React.FC<FileExplorerProps> = ({
   fileTree,
   selectedFile,
@@ -255,7 +127,8 @@ export const FileExplorer: React.FC<FileExplorerProps> = ({
     return flattenFileTree(filteredFileTree, expandedFolders, loadingPaths);
   }, [filteredFileTree, expandedFolders, loadingPaths]);
 
-  const useVirtualScroll = flatNodes.length > VIRTUAL_SCROLL_THRESHOLD;
+  // Keep hooks before any early returns (React Hooks rules).
+  const containerRef = useRef<HTMLDivElement>(null);
   
   const toggleExpandedState = useCallback((path: string) => {
     const isCurrentlyExpanded = expandedFoldersContains(expandedFolders, path);
@@ -284,9 +157,6 @@ export const FileExplorer: React.FC<FileExplorerProps> = ({
     );
   }, [showFileSize, showLastModified]);
 
-  // Keep hooks before any early returns (React Hooks rules).
-  const containerRef = useRef<HTMLDivElement>(null);
-  
   const [isToolbarVisible, setIsToolbarVisible] = useState(false);
   const [isFocused, setIsFocused] = useState(false);
   
@@ -391,18 +261,6 @@ export const FileExplorer: React.FC<FileExplorerProps> = ({
     await commandExecutor.execute('file.delete', buildFileNodeContext(node, workspacePath));
   }, [selectedFile, fileTree, workspacePath]);
 
-  const handleBreadcrumbNavigate = useCallback((path: string) => {
-    if (externalOnNodeExpand) {
-      externalOnNodeExpand(path, true);
-    } else {
-      setInternalExpandedFolders(prev => {
-        const newSet = new Set(prev);
-        newSet.add(path);
-        return newSet;
-      });
-    }
-  }, [externalOnNodeExpand]);
-
   useShortcut(
     'filetree.refresh',
     REFRESH_SHORTCUT,
@@ -518,46 +376,20 @@ export const FileExplorer: React.FC<FileExplorerProps> = ({
         </div>
       )}
       
-      {!useVirtualScroll && (
-        <ScrollBreadcrumb 
-          containerRef={containerRef}
-          workspacePath={workspacePath}
-          onNavigate={handleBreadcrumbNavigate}
-        />
-      )}
-      
-      {useVirtualScroll ? (
-        <VirtualFileTree
-          flatNodes={flatNodes}
-          selectedFile={selectedFile}
-          expandedFolders={expandedFolders}
-          onNodeSelect={(node: FlatFileNode) => emitFileSelect(node.path, node.name)}
-          onToggleExpand={toggleExpandedState}
-          className="bitfun-file-explorer__tree"
-          workspacePath={workspacePath}
-          renamingPath={renamingPath}
-          onRename={onRename}
-          onCancelRename={onCancelRename}
-          renderNodeContent={renderNodeContent}
-          isRemoteWorkspace={isRemoteWorkspace}
-        />
-      ) : (
-        <FileTree
-          nodes={filteredFileTree}
-          selectedFile={selectedFile}
-          expandedFolders={expandedFolders}
-          loadingPaths={loadingPaths}
-          onNodeSelect={(node: FileSystemNode) => emitFileSelect(node.path, node.name)}
-          onNodeExpand={setExpandedState}
-          renderNodeContent={renderNodeContent}
-          className="bitfun-file-explorer__tree"
-          renamingPath={renamingPath}
-          onRename={onRename}
-          onCancelRename={onCancelRename}
-          workspacePath={workspacePath}
-          isRemoteWorkspace={isRemoteWorkspace}
-        />
-      )}
+      <VirtualFileTree
+        flatNodes={flatNodes}
+        selectedFile={selectedFile}
+        expandedFolders={expandedFolders}
+        onNodeSelect={(node: FlatFileNode) => emitFileSelect(node.path, node.name)}
+        onToggleExpand={toggleExpandedState}
+        className="bitfun-file-explorer__tree"
+        workspacePath={workspacePath}
+        renamingPath={renamingPath}
+        onRename={onRename}
+        onCancelRename={onCancelRename}
+        renderNodeContent={renderNodeContent}
+        isRemoteWorkspace={isRemoteWorkspace}
+      />
     </div>
   );
 };
diff --git a/src/web-ui/src/tools/file-system/components/FileSearchResults.scss b/src/web-ui/src/tools/file-system/components/FileSearchResults.scss
index 9d6b239be0..4794a0270b 100644
--- a/src/web-ui/src/tools/file-system/components/FileSearchResults.scss
+++ b/src/web-ui/src/tools/file-system/components/FileSearchResults.scss
@@ -84,7 +84,9 @@ $_icon-size: 16px;
     border: none;
     border-radius: $size-radius-sm;
     background: transparent;
-    transition: all $motion-base $easing-standard;
+    transition:
+      background-color $motion-base $easing-standard,
+      color $motion-base $easing-standard;
     color: var(--bf-appearance-token-color-text-secondary);
     text-align: left;
     font: inherit;
diff --git a/src/web-ui/src/tools/file-system/components/FileTreeItem.tsx b/src/web-ui/src/tools/file-system/components/FileTreeItem.tsx
index 4f4710a2d5..eea3a54d75 100644
--- a/src/web-ui/src/tools/file-system/components/FileTreeItem.tsx
+++ b/src/web-ui/src/tools/file-system/components/FileTreeItem.tsx
@@ -1,7 +1,7 @@
 import React, { useEffect, useLayoutEffect, useRef, useState } from 'react';
 import { createPortal } from 'react-dom';
 import { getAppearanceOverlayHost } from '@/infrastructure/appearance/runtime/AppearanceOverlayHost';
-import { ChevronRight, ChevronDown, FolderOpen, FileText } from 'lucide-react';
+import { ChevronRight, ChevronDown, FolderOpen, FileText, Loader2 } from 'lucide-react';
 import { Input } from '../../../component-library/components/Input';
 import { dragManager } from '../../../shared/services/DragManager';
 import { fileTreeDragSource } from '../../../shared/context-system/drag-drop/FileTreeDragSource';
@@ -233,6 +233,7 @@ export const FileTreeItem: React.FC<FileTreeItemProps> = ({
   indentPx,
   isSelected = false,
   isExpanded = false,
+  isLoading = false,
   className = '',
   renamingPath,
   onRename,
@@ -322,7 +323,9 @@ export const FileTreeItem: React.FC<FileTreeItemProps> = ({
     >
       {node.isDirectory ? (
         <span className={`bitfun-file-explorer__expand-icon ${isExpanded ? 'bitfun-file-explorer__expand-icon--expanded' : ''}`} onClick={handleExpandClick}>
-          {isExpanded ? (
+          {isLoading ? (
+            <Loader2 size={16} className="bitfun-file-explorer__loading-icon" />
+          ) : isExpanded ? (
             <ChevronDown size={16} />
           ) : (
             <ChevronRight size={16} />
diff --git a/src/web-ui/src/tools/file-system/styles/FileExplorer.scss b/src/web-ui/src/tools/file-system/styles/FileExplorer.scss
index cec0545326..487fedb6b3 100644
--- a/src/web-ui/src/tools/file-system/styles/FileExplorer.scss
+++ b/src/web-ui/src/tools/file-system/styles/FileExplorer.scss
@@ -129,10 +129,13 @@ $_indent-width: 8px;
   overflow-x: hidden;
   padding: $size-gap-2 0;
   -webkit-overflow-scrolling: touch;
-  scroll-behavior: smooth;
 
 }
 
+.bitfun-file-explorer__tree--virtual > div {
+  scrollbar-gutter: stable;
+}
+
 .bitfun-file-explorer__node {
   user-select: none;
 }
@@ -147,7 +150,9 @@ $_indent-width: 8px;
   position: relative;
   
   background: transparent;
-  transition: all $motion-base $easing-standard;
+  transition:
+    background-color $motion-base $easing-standard,
+    color $motion-base $easing-standard;
   color: var(--bf-appearance-token-color-text-secondary);
   
   &:focus {
@@ -190,8 +195,21 @@ $_indent-width: 8px;
   }
 
   &--highlighted {
-    background: var(--bf-appearance-token-git-color-branch-bg) !important;
-    animation: file-node-highlight-fade 2s ease-out forwards;
+    &::after {
+      content: '';
+      position: absolute;
+      inset: 0;
+      z-index: 0;
+      border-radius: inherit;
+      background: var(--bf-appearance-token-git-color-branch-bg);
+      pointer-events: none;
+      animation: file-node-highlight-fade 240ms cubic-bezier(0.23, 1, 0.32, 1) forwards;
+    }
+
+    > * {
+      position: relative;
+      z-index: 1;
+    }
     
     .bitfun-file-explorer__node-name {
       color: var(--bf-appearance-token-git-color-branch);
@@ -201,24 +219,35 @@ $_indent-width: 8px;
 }
 
 @keyframes file-node-highlight-fade {
-  0% {
-    background: rgba(var(--bf-appearance-token-color-accent-500-rgb) / 0.2);
-  }
-  30% {
-    background: var(--bf-appearance-token-git-color-branch-bg);
-  }
-  100% {
-    background: transparent;
-  }
+  from { opacity: 1; }
+  to { opacity: 0; }
 }
 
 .bitfun-file-explorer__expand-icon {
   @include mixins.flex-layout(row, center, center, 0);
   @include mixins.size($_icon-size);
-  transition: transform $motion-fast $easing-standard;
   color: var(--bf-appearance-token-color-text-muted);
   flex-shrink: 0;
   min-width: $_icon-size;
+
+  > svg:not(.bitfun-file-explorer__loading-icon) {
+    transition: transform 120ms cubic-bezier(0.23, 1, 0.32, 1);
+  }
+
+  &--expanded > svg:not(.bitfun-file-explorer__loading-icon) {
+    transform: rotate(90deg);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .bitfun-file-explorer__node-content--highlighted::after {
+    opacity: 0.2;
+    animation: none;
+  }
+
+  .bitfun-file-explorer__expand-icon > svg {
+    transition: none;
+  }
 }
 
 .bitfun-file-explorer__icon {
diff --git a/src/web-ui/src/tools/generative-widget/GenerativeWidgetFrame.scss b/src/web-ui/src/tools/generative-widget/GenerativeWidgetFrame.scss
index c06d17b4e2..968c864127 100644
--- a/src/web-ui/src/tools/generative-widget/GenerativeWidgetFrame.scss
+++ b/src/web-ui/src/tools/generative-widget/GenerativeWidgetFrame.scss
@@ -13,4 +13,16 @@
   border: 0;
   background: transparent;
   display: block;
+  opacity: 0;
+  transition: opacity 160ms cubic-bezier(0.23, 1, 0.32, 1);
+}
+
+.bitfun-generative-widget-frame__iframe--loaded {
+  opacity: 1;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .bitfun-generative-widget-frame__iframe {
+    transition: none;
+  }
 }
diff --git a/src/web-ui/src/tools/generative-widget/GenerativeWidgetFrame.tsx b/src/web-ui/src/tools/generative-widget/GenerativeWidgetFrame.tsx
index 2b934d48aa..30c0839cad 100644
--- a/src/web-ui/src/tools/generative-widget/GenerativeWidgetFrame.tsx
+++ b/src/web-ui/src/tools/generative-widget/GenerativeWidgetFrame.tsx
@@ -359,7 +359,12 @@ ${createWidgetAppearanceStaticShellCss()}
       color: var(--bf-appearance-token-color-text-secondary);
       text-decoration: none;
       white-space: nowrap;
-      transition: all var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
+      transition:
+        transform 120ms cubic-bezier(0.23, 1, 0.32, 1),
+        background-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+        border-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+        color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+        box-shadow var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
     }
     .bf-button:hover {
       background: var(--bf-appearance-token-element-bg-medium);
@@ -388,7 +393,11 @@ ${createWidgetAppearanceStaticShellCss()}
       border: 1px solid var(--bf-appearance-token-border-base);
       background: var(--bf-appearance-token-element-bg-subtle);
       color: var(--bf-appearance-token-color-text-primary);
-      transition: all var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
+      transition:
+        background-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+        border-color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+        color var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard),
+        box-shadow var(--bf-appearance-token-motion-fast) var(--bf-appearance-token-easing-standard);
     }
     .bf-input,
     .bf-select {
@@ -508,9 +517,15 @@ ${createWidgetAppearanceStaticShellCss()}
         font-size: var(--bf-appearance-token-font-size-base);
       }
     }
-    @keyframes bitfunWidgetFadeIn {
-      from { opacity: 0; transform: translateY(4px); }
-      to { opacity: 1; transform: translateY(0); }
+    @media (prefers-reduced-motion: reduce) {
+      .bf-button,
+      .bf-input,
+      .bf-textarea,
+      .bf-select,
+      [data-bitfun-prompt-selected="true"],
+      [data-bitfun-context-selected="true"] {
+        transition: none;
+      }
     }
   </style>
   <script>${morphdomRuntime}</script>
@@ -709,17 +724,6 @@ ${createWidgetAppearanceStaticShellCss()}
                 return false;
               }
               return true;
-            },
-            onNodeAdded: function (node) {
-              if (
-                node &&
-                node.nodeType === 1 &&
-                node.tagName !== 'SCRIPT' &&
-                node.tagName !== 'STYLE'
-              ) {
-                node.style.animation = 'bitfunWidgetFadeIn 0.18s ease both';
-              }
-              return node;
             }
           });
         } else {
@@ -1044,7 +1048,7 @@ export const GenerativeWidgetFrame: React.FC<GenerativeWidgetFrameProps> = ({
       <iframe
         ref={iframeRef}
         title={title || 'Generative widget'}
-        className="bitfun-generative-widget-frame__iframe"
+        className={`bitfun-generative-widget-frame__iframe${isLoaded ? ' bitfun-generative-widget-frame__iframe--loaded' : ''}`}
         data-bf-component="generative-widget"
         data-bf-part="iframe"
         style={{ width: '100%', minWidth: '100%' }}
diff --git a/src/web-ui/src/tools/git/components/CreateBranchDialog/CreateBranchDialog.scss b/src/web-ui/src/tools/git/components/CreateBranchDialog/CreateBranchDialog.scss
index 2dff0e1809..1bad05dceb 100644
--- a/src/web-ui/src/tools/git/components/CreateBranchDialog/CreateBranchDialog.scss
+++ b/src/web-ui/src/tools/git/components/CreateBranchDialog/CreateBranchDialog.scss
@@ -1,19 +1,5 @@
 @use '@/component-library/styles/tokens.scss' as *;
 
-.bitfun-create-branch-dialog-overlay {
-  position: fixed;
-  top: 0;
-  left: 0;
-  right: 0;
-  bottom: 0;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  background: var(--bf-appearance-token-color-overlay-black-50);
-  z-index: $z-modal;
-  animation: bitfun-create-branch-dialog-fade-in 0.2s ease-out;
-}
-
 .bitfun-create-branch-dialog {
   background: var(--bf-appearance-token-color-bg-primary);
   border: 1px solid var(--bf-appearance-token-border-base);
@@ -24,7 +10,6 @@
   max-height: 90vh;
   overflow-y: auto;
   box-shadow: 0 8px 16px var(--bf-appearance-token-color-overlay-black-30);
-  animation: bitfun-create-branch-dialog-scale-in 0.2s ease-out;
 
   &__header {
     display: flex;
@@ -139,7 +124,11 @@
     color: var(--bf-appearance-token-color-text-primary);
     font-family: $font-family-mono;
     font-size: var(--bf-appearance-token-font-size-sm);
-    transition: all $motion-base $easing-standard;
+    transition:
+      background-color $motion-base $easing-standard,
+      border-color $motion-base $easing-standard,
+      box-shadow $motion-base $easing-standard,
+      opacity $motion-base $easing-standard;
 
     &:focus {
       outline: none;
@@ -250,26 +239,6 @@
 
 }
 
-@keyframes bitfun-create-branch-dialog-fade-in {
-  from {
-    opacity: 0;
-  }
-  to {
-    opacity: 1;
-  }
-}
-
-@keyframes bitfun-create-branch-dialog-scale-in {
-  from {
-    opacity: 0;
-    transform: scale(0.95) translateY(-10px);
-  }
-  to {
-    opacity: 1;
-    transform: scale(1) translateY(0);
-  }
-}
-
 @keyframes bitfun-create-branch-dialog-shake {
   0%, 100% {
     transform: translateX(0);
diff --git a/src/web-ui/src/tools/git/components/GitBranchHistoryView/GitBranchHistoryView.scss b/src/web-ui/src/tools/git/components/GitBranchHistoryView/GitBranchHistoryView.scss
index b7c6d5af24..69b37780b3 100644
--- a/src/web-ui/src/tools/git/components/GitBranchHistoryView/GitBranchHistoryView.scss
+++ b/src/web-ui/src/tools/git/components/GitBranchHistoryView/GitBranchHistoryView.scss
@@ -431,6 +431,12 @@
   }
 }
 
+@media (prefers-reduced-motion: reduce) {
+  .git-branch-history-view__spinner {
+    animation: none;
+  }
+}
+
 
 .bitfun-right-panel[data-mode="compact"] {
   .git-branch-history-view {
diff --git a/src/web-ui/src/tools/git/components/GitDiffEditor/GitDiffEditor.scss b/src/web-ui/src/tools/git/components/GitDiffEditor/GitDiffEditor.scss
index 9d3e91b418..0df27a2b79 100644
--- a/src/web-ui/src/tools/git/components/GitDiffEditor/GitDiffEditor.scss
+++ b/src/web-ui/src/tools/git/components/GitDiffEditor/GitDiffEditor.scss
@@ -168,7 +168,7 @@ $_diff-padding-desktop: 32px;
           width: 1px;
           background: var(--bf-appearance-token-border-medium);
           border-left: 1px dashed var(--bf-appearance-token-border-medium);
-          transition: all 0.2s ease;
+          transition: border-left-color 0.2s ease;
         }
         
         &:hover::before {
@@ -445,6 +445,25 @@ $_diff-padding-desktop: 32px;
   }
 }
 
+@media (prefers-reduced-motion: reduce) {
+  .git-diff-editor {
+    &__error,
+    &__saving-indicator,
+    &__processing-overlay,
+    &__spinner,
+    &__completed-message,
+    &__completed-icon,
+    &__completed-title,
+    &__completed-details {
+      animation: none;
+    }
+
+    &__processing-overlay p {
+      animation: none;
+    }
+  }
+}
+
 @media (prefers-contrast: high) {
   .git-diff-editor {
     &__spinner {
diff --git a/src/web-ui/src/tools/git/components/GitDiffView/GitDiffView.scss b/src/web-ui/src/tools/git/components/GitDiffView/GitDiffView.scss
index dcff7ed03b..73b4fbe8ef 100644
--- a/src/web-ui/src/tools/git/components/GitDiffView/GitDiffView.scss
+++ b/src/web-ui/src/tools/git/components/GitDiffView/GitDiffView.scss
@@ -671,6 +671,17 @@ $opacity-high: 0.8 !default;
   }
 }
 
+@media (prefers-reduced-motion: reduce) {
+  .bitfun-git-diff-view__loading-spinner,
+  .bitfun-git-diff-view__ai-spinner,
+  .bitfun-git-diff-view__commit-dialog-overlay,
+  .bitfun-git-diff-view__commit-dialog,
+  .bitfun-git-diff-view__ai-error,
+  .bitfun-git-diff-view__ai-info {
+    animation: none;
+  }
+}
+
 @media (max-width: 768px) {
   .bitfun-git-diff-view {
     &__header {
diff --git a/src/web-ui/src/tools/git/components/GitGraphView/GitGraphView.scss b/src/web-ui/src/tools/git/components/GitGraphView/GitGraphView.scss
index 16152e221d..b5c4695d4a 100644
--- a/src/web-ui/src/tools/git/components/GitGraphView/GitGraphView.scss
+++ b/src/web-ui/src/tools/git/components/GitGraphView/GitGraphView.scss
@@ -48,7 +48,7 @@
     border: 3px solid var(--bf-appearance-token-color-overlay-white-12);
     border-top-color: var(--bf-appearance-token-color-accent-500);
     border-radius: 50%;
-    animation: spin 0.8s linear infinite;
+    animation: bitfun-git-graph-spin 0.8s linear infinite;
   }
 
   &__header {
@@ -186,7 +186,6 @@
       background: color-mix(in srgb, var(--bf-appearance-token-color-warning) 15%, transparent);
       border-left: 3px solid var(--bf-appearance-token-color-warning);
       box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--bf-appearance-token-color-warning) 30%, transparent);
-      animation: search-highlight 0.4s ease-out;
       z-index: 3;
 
       &:hover {
@@ -264,12 +263,6 @@
     font-weight: 500;
     white-space: nowrap;
     cursor: help;
-    transition: transform 0.15s, box-shadow 0.15s;
-
-    &:hover {
-      transform: scale(1.05);
-      box-shadow: 0 2px 4px var(--bf-appearance-token-color-overlay-black-20);
-    }
 
     &--branch {
       background: var(--bf-appearance-token-color-accent-600);
@@ -289,7 +282,6 @@
     &--current {
       box-shadow: 0 0 0 2px var(--bf-appearance-token-color-bg-primary),
                   0 0 0 4px currentColor;
-      animation: pulse 2s ease-in-out infinite;
     }
   }
 
@@ -363,28 +355,14 @@
   }
 }
 
-@keyframes spin {
+@keyframes bitfun-git-graph-spin {
   to {
     transform: rotate(360deg);
   }
 }
 
-@keyframes pulse {
-  0%, 100% {
-    opacity: 1;
-  }
-  50% {
-    opacity: 0.8;
-  }
-}
-
-@keyframes search-highlight {
-  0% {
-    background: color-mix(in srgb, var(--bf-appearance-token-color-warning) 40%, transparent);
-    transform: scaleY(1.05);
-  }
-  100% {
-    background: color-mix(in srgb, var(--bf-appearance-token-color-warning) 15%, transparent);
-    transform: scaleY(1);
+@media (prefers-reduced-motion: reduce) {
+  .git-graph-view__spinner {
+    animation: none;
   }
 }
diff --git a/src/web-ui/src/tools/git/components/GitGraphView/GitGraphView.tsx b/src/web-ui/src/tools/git/components/GitGraphView/GitGraphView.tsx
index 0f9f5bc707..c171de8ace 100644
--- a/src/web-ui/src/tools/git/components/GitGraphView/GitGraphView.tsx
+++ b/src/web-ui/src/tools/git/components/GitGraphView/GitGraphView.tsx
@@ -205,7 +205,7 @@ export const GitGraphView: React.FC<GitGraphViewProps> = ({
     
     containerRef.current.scrollTo({
       top: Math.max(0, centeredScrollTop),
-      behavior: 'smooth'
+      behavior: 'auto'
     });
 
 
diff --git a/src/web-ui/src/tools/git/components/GitSettingsView/GitSettingsView.css b/src/web-ui/src/tools/git/components/GitSettingsView/GitSettingsView.css
index f02c8be24d..b2e9e7ffd6 100644
--- a/src/web-ui/src/tools/git/components/GitSettingsView/GitSettingsView.css
+++ b/src/web-ui/src/tools/git/components/GitSettingsView/GitSettingsView.css
@@ -46,7 +46,10 @@
   border-radius: 4px;
   color: var(--bf-appearance-token-color-text-secondary);
   cursor: pointer;
-  transition: all 0.2s ease;
+  transition:
+    background-color 0.2s ease,
+    color 0.2s ease,
+    opacity 0.2s ease;
 }
 
 .refresh-btn:hover:not(:disabled) {
@@ -71,7 +74,10 @@
   font-size: 12px;
   font-weight: 500;
   cursor: pointer;
-  transition: all 0.2s ease;
+  transition:
+    background-color 0.2s ease,
+    color 0.2s ease,
+    opacity 0.2s ease;
 }
 
 .save-btn:hover:not(:disabled) {
@@ -133,7 +139,10 @@
   font-size: 13px;
   font-weight: 500;
   cursor: pointer;
-  transition: all 0.2s ease;
+  transition:
+    background-color 0.2s ease,
+    border-bottom-color 0.2s ease,
+    color 0.2s ease;
 }
 
 .tab-btn:hover {
@@ -211,7 +220,10 @@
   border-radius: 4px;
   color: var(--bf-appearance-token-color-text-primary);
   font-size: 12px;
-  transition: all 0.2s ease;
+  transition:
+    background-color 0.2s ease,
+    border-color 0.2s ease,
+    color 0.2s ease;
 }
 
 .form-group input:focus,
@@ -310,11 +322,11 @@
 }
 
 .loading-spinner {
-  animation: spin 1s linear infinite;
+  animation: bitfun-git-settings-legacy-spin 1s linear infinite;
   margin-bottom: 12px;
 }
 
-@keyframes spin {
+@keyframes bitfun-git-settings-legacy-spin {
   0% { transform: rotate(0deg); }
   100% { transform: rotate(360deg); }
 }
@@ -344,7 +356,13 @@
   color: white;
   font-size: 12px;
   cursor: pointer;
-  transition: all 0.2s ease;
+  transition: background-color 0.2s ease;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .loading-spinner {
+    animation: none;
+  }
 }
 
 .retry-btn:hover {
diff --git a/src/web-ui/src/tools/git/components/GitSettingsView/GitSettingsView.scss b/src/web-ui/src/tools/git/components/GitSettingsView/GitSettingsView.scss
index 8a1996ad90..fe62cd2189 100644
--- a/src/web-ui/src/tools/git/components/GitSettingsView/GitSettingsView.scss
+++ b/src/web-ui/src/tools/git/components/GitSettingsView/GitSettingsView.scss
@@ -342,6 +342,12 @@ $opacity-high: 0.8 !default;
   }
 }
 
+@media (prefers-reduced-motion: reduce) {
+  .bitfun-git-settings-view__loading-spinner {
+    animation: none;
+  }
+}
+
 @media (max-width: 768px) {
   .bitfun-git-settings-view {
     &__header {
diff --git a/src/web-ui/src/tools/lsp/components/LspPluginList/LspPluginList.scss b/src/web-ui/src/tools/lsp/components/LspPluginList/LspPluginList.scss
index 0225051357..bd24310625 100644
--- a/src/web-ui/src/tools/lsp/components/LspPluginList/LspPluginList.scss
+++ b/src/web-ui/src/tools/lsp/components/LspPluginList/LspPluginList.scss
@@ -270,7 +270,7 @@
     font-size: var(--bf-appearance-token-font-size-xs);
     font-family: $font-family-mono;
     color: var(--bf-appearance-token-color-text-primary);
-    transition: all $motion-fast $easing-standard;
+    transition: background-color $motion-fast $easing-standard;
 
     &:hover {
       background: var(--bf-appearance-token-element-bg-medium);
@@ -335,6 +335,14 @@
   }
 }
 
+@media (prefers-reduced-motion: reduce) {
+  .lsp-plugin-list__spinning,
+  .lsp-plugin-list .spinner,
+  .lsp-plugin-item__details {
+    animation: none;
+  }
+}
+
 // Responsive
 @container config-panel (max-width: 520px) {
   .lsp-plugin-list {
diff --git a/src/web-ui/src/tools/lsp/components/ReferencesPanel/ReferencesPanel.scss b/src/web-ui/src/tools/lsp/components/ReferencesPanel/ReferencesPanel.scss
index 4affbc9758..213cfb5da3 100644
--- a/src/web-ui/src/tools/lsp/components/ReferencesPanel/ReferencesPanel.scss
+++ b/src/web-ui/src/tools/lsp/components/ReferencesPanel/ReferencesPanel.scss
@@ -311,15 +311,15 @@
 
 @media (prefers-reduced-motion: reduce) {
   .references-panel {
-    transition: opacity $motion-instant ease;
     transform: none;
+    animation: references-panel-reduced-fade-in $motion-instant ease forwards;
   }
   
   .references-panel__reference-item {
     transition: background-color $motion-instant ease;
   }
   
-  @keyframes references-panel-fade-in {
+  @keyframes references-panel-reduced-fade-in {
     from { opacity: 0; }
     to { opacity: 1; }
   }
diff --git a/src/web-ui/src/tools/lsp/services/WorkspaceLspInitializer.ts b/src/web-ui/src/tools/lsp/services/WorkspaceLspInitializer.ts
index 1fd05cf327..e843f7de3e 100644
--- a/src/web-ui/src/tools/lsp/services/WorkspaceLspInitializer.ts
+++ b/src/web-ui/src/tools/lsp/services/WorkspaceLspInitializer.ts
@@ -10,6 +10,7 @@ import { WorkspaceLspManager } from './WorkspaceLspManager';
 import { lspConfigService } from './LspConfigService';
 import { api } from '@/infrastructure/api/service-api/ApiClient';
 import { createLogger } from '@/shared/utils/logger';
+import { isSurfaceChangedError } from '@/infrastructure/peer-device/deviceSurface';
 
 const log = createLogger('WorkspaceLspInitializer');
 
@@ -94,7 +95,7 @@ class WorkspaceLspInitializer {
       });
       
     } catch (error) {
-      log.error('Failed to initialize LSP', { workspacePath, error });
+      logLspInitializationFailure(workspacePath, error);
     }
   }
 
@@ -155,10 +156,23 @@ class WorkspaceLspInitializer {
       
       log.info('LSP initialized for switched workspace', { workspacePath });
     } catch (error) {
-      log.error('Failed to initialize LSP', { workspacePath, error });
+      logLspInitializationFailure(workspacePath, error);
     }
   }
 }
 
 // Singleton export
 export const workspaceLspInitializer = WorkspaceLspInitializer.getInstance();
+
+/**
+ * A device surface switch supersedes an in-flight LSP bootstrap. The manager
+ * belongs to the device we left, so abandoning is the correct outcome and must
+ * not be reported as a broken workspace.
+ */
+function logLspInitializationFailure(workspacePath: string, error: unknown): void {
+  if (isSurfaceChangedError(error)) {
+    log.debug('LSP bootstrap abandoned after a device surface switch', { workspacePath });
+    return;
+  }
+  log.error('Failed to initialize LSP', { workspacePath, error });
+}
diff --git a/src/web-ui/src/tools/lsp/services/WorkspaceLspManager.test.ts b/src/web-ui/src/tools/lsp/services/WorkspaceLspManager.test.ts
index 876c93953d..f73cac9377 100644
--- a/src/web-ui/src/tools/lsp/services/WorkspaceLspManager.test.ts
+++ b/src/web-ui/src/tools/lsp/services/WorkspaceLspManager.test.ts
@@ -28,6 +28,11 @@ vi.mock('@/infrastructure/i18n', () => ({
 }));
 
 import { WorkspaceLspManager } from './WorkspaceLspManager';
+import {
+  activateSurface,
+  isSurfaceChangedError,
+  resetDeviceSurfaceForTest,
+} from '@/infrastructure/peer-device/deviceSurface';
 
 function serverState(status: 'stopped' | 'starting' | 'running' | 'failed' | 'restarting') {
   return {
@@ -48,6 +53,7 @@ describe('WorkspaceLspManager', () => {
     (WorkspaceLspManager as unknown as {
       instances: Map<string, WorkspaceLspManager>;
     }).instances.clear();
+    resetDeviceSurfaceForTest();
   });
 
   it('skips didOpen when the language server is stopped', async () => {
@@ -146,3 +152,97 @@ describe('WorkspaceLspManager', () => {
     expect(invokeMock).not.toHaveBeenCalledWith('lsp_open_document', expect.anything());
   });
 });
+
+describe('WorkspaceLspManager device surface scoping', () => {
+  afterEach(() => {
+    invokeMock.mockReset();
+    listenMock.mockReset();
+    listenMock.mockReturnValue(() => {});
+    (WorkspaceLspManager as unknown as {
+      instances: Map<string, WorkspaceLspManager>;
+    }).instances.clear();
+    resetDeviceSurfaceForTest();
+  });
+
+  it('does not share a manager for the same workspace path across devices', () => {
+    const localManager = WorkspaceLspManager.getOrCreate('/Users/dev/BitFun');
+
+    activateSurface('peer-device-b');
+    const peerManager = WorkspaceLspManager.getOrCreate('/Users/dev/BitFun');
+
+    expect(peerManager).not.toBe(localManager);
+    expect(peerManager.getSurfaceId()).toBe('peer-device-b');
+    expect(WorkspaceLspManager.get('/Users/dev/BitFun')).toBe(peerManager);
+  });
+
+  it('detaches for a surface switch without sending anything to the device being left', async () => {
+    const unlisten = vi.fn();
+    listenMock.mockReturnValue(unlisten);
+    invokeMock.mockResolvedValue(undefined);
+
+    const manager = WorkspaceLspManager.getOrCreate('/Users/dev/BitFun');
+    await manager.initialize();
+    invokeMock.mockClear();
+
+    WorkspaceLspManager.detachAllForSurfaceSwitch();
+
+    expect(invokeMock).not.toHaveBeenCalled();
+    expect(unlisten).toHaveBeenCalledTimes(1);
+  });
+
+  it('refuses to re-open a detached workspace on the device switched to', async () => {
+    invokeMock.mockResolvedValue(undefined);
+
+    const manager = WorkspaceLspManager.getOrCreate('/Users/dev/BitFun');
+    await manager.initialize();
+    WorkspaceLspManager.detachAllForSurfaceSwitch();
+    activateSurface('peer-device-b');
+    invokeMock.mockClear();
+
+    const error = await manager.initialize().then(() => null, (reason: unknown) => reason);
+
+    expect(isSurfaceChangedError(error)).toBe(true);
+    expect(invokeMock).not.toHaveBeenCalled();
+  });
+
+  it('prevents every detached manager operation from reaching the next device', async () => {
+    invokeMock.mockResolvedValue(undefined);
+
+    const manager = WorkspaceLspManager.getOrCreate('/Users/dev/BitFun');
+    await manager.initialize();
+    WorkspaceLspManager.detachAllForSurfaceSwitch();
+    activateSurface('peer-device-b');
+    invokeMock.mockClear();
+
+    await manager.changeDocument('file:///Users/dev/BitFun/src/main.rs', 'fn main() {}');
+
+    expect(invokeMock).not.toHaveBeenCalled();
+  });
+
+  it('drops events that reach a manager after its surface was left', async () => {
+    let emitLspEvent: ((payload: unknown) => void) | null = null;
+    listenMock.mockImplementation((_event: string, callback: (payload: unknown) => void) => {
+      emitLspEvent = callback;
+      return () => {};
+    });
+    invokeMock.mockResolvedValue(undefined);
+
+    const manager = WorkspaceLspManager.getOrCreate('/Users/dev/BitFun');
+    await manager.initialize();
+
+    const diagnostics = vi.fn();
+    manager.onDiagnostics('file:///Users/dev/BitFun/src/main.rs', diagnostics);
+    manager.detachForSurfaceSwitch();
+
+    emitLspEvent?.({
+      type: 'Diagnostics',
+      data: {
+        workspace_path: '/Users/dev/BitFun',
+        uri: 'file:///Users/dev/BitFun/src/main.rs',
+        diagnostics: [{ message: 'from the device we left' }],
+      },
+    });
+
+    expect(diagnostics).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/web-ui/src/tools/lsp/services/WorkspaceLspManager.ts b/src/web-ui/src/tools/lsp/services/WorkspaceLspManager.ts
index cd4b5560c9..bbed580ad0 100644
--- a/src/web-ui/src/tools/lsp/services/WorkspaceLspManager.ts
+++ b/src/web-ui/src/tools/lsp/services/WorkspaceLspManager.ts
@@ -9,6 +9,15 @@ import { api } from '@/infrastructure/api/service-api/ApiClient';
 import { notificationService } from '@/shared/notification-system';
 import { createLogger } from '@/shared/utils/logger';
 import { i18nService } from '@/infrastructure/i18n';
+import {
+  SurfaceChangedError,
+  getActiveSurfaceId,
+  getActiveSurfaceScope,
+  isSurfaceChangedError,
+  surfaceScopedKey,
+  type DeviceSurfaceId,
+  type SurfaceScope,
+} from '@/infrastructure/peer-device/deviceSurface';
 
 const log = createLogger('WorkspaceLspManager');
 
@@ -52,9 +61,16 @@ interface CachedServerStatus {
 }
 
 export class WorkspaceLspManager {
+  /**
+   * Keyed by device surface **and** workspace path. The same repository is
+   * routinely checked out at the same path on two machines, so a path alone
+   * would hand a manager negotiated with one host to the other.
+   */
   private static instances = new Map<string, WorkspaceLspManager>();
   
   private workspacePath: string;
+  private readonly surfaceId: DeviceSurfaceId;
+  private detached = false;
   private eventUnlisten?: () => void;
   private isInitialized = false;
   private serverStatusByLanguage = new Map<string, CachedServerStatus>();
@@ -70,8 +86,9 @@ export class WorkspaceLspManager {
     complete: (message?: string) => void;
   }>();
   
-  private constructor(workspacePath: string) {
+  private constructor(workspacePath: string, surfaceId: DeviceSurfaceId) {
     this.workspacePath = workspacePath;
+    this.surfaceId = surfaceId;
   }
   
   
@@ -79,33 +96,52 @@ export class WorkspaceLspManager {
     return this.workspacePath;
   }
   
-  
+  getSurfaceId(): DeviceSurfaceId {
+    return this.surfaceId;
+  }
+
+  private static instanceKey(workspacePath: string): string {
+    return surfaceScopedKey(getActiveSurfaceId(), workspacePath);
+  }
+
+
   static getOrCreate(workspacePath: string): WorkspaceLspManager {
-    if (!this.instances.has(workspacePath)) {
-      const manager = new WorkspaceLspManager(workspacePath);
-      this.instances.set(workspacePath, manager);
+    const key = this.instanceKey(workspacePath);
+    if (!this.instances.has(key)) {
+      const manager = new WorkspaceLspManager(workspacePath, getActiveSurfaceId());
+      this.instances.set(key, manager);
     }
-    return this.instances.get(workspacePath)!;
+    return this.instances.get(key)!;
   }
   
   
   static get(workspacePath: string): WorkspaceLspManager | undefined {
-    return this.instances.get(workspacePath);
+    return this.instances.get(this.instanceKey(workspacePath));
   }
   
   
   static async remove(workspacePath: string): Promise<void> {
-    const manager = this.instances.get(workspacePath);
+    const key = this.instanceKey(workspacePath);
+    const manager = this.instances.get(key);
     if (manager) {
       await manager.dispose();
-      this.instances.delete(workspacePath);
+      this.instances.delete(key);
     }
   }
 
-  /** Drop all workspace LSP managers when entering/exiting Peer Device Mode. */
-  static async clearAllForPeerSwitch(): Promise<void> {
-    const paths = Array.from(this.instances.keys());
-    await Promise.all(paths.map((path) => this.remove(path)));
+  /**
+   * Drop all workspace LSP managers when the rendered device surface changes.
+   *
+   * Deliberately does **not** call `lsp_close_workspace`: that request would be
+   * sent to the device being left, shutting down language servers an agent
+   * turn there may still be using. Managers are recreated against the new
+   * transport on the next workspace bootstrap.
+   */
+  static detachAllForSurfaceSwitch(): void {
+    for (const manager of this.instances.values()) {
+      manager.detachForSurfaceSwitch();
+    }
+    this.instances.clear();
   }
   
   
@@ -114,13 +150,20 @@ export class WorkspaceLspManager {
       return;
     }
 
+    const scope = getActiveSurfaceScope();
+    this.assertRendersActiveSurface(scope, 'lsp_open_workspace');
+
     try {
 
-      await api.invoke('lsp_open_workspace', {
+      await this.invokeForActiveSurface('lsp_open_workspace', {
         request: { workspacePath: this.workspacePath }
       });
       
 
+      // The transport may have swapped during the round trip. Binding the event
+      // listener now would attach this manager to the device that replaced ours.
+      this.assertRendersActiveSurface(scope, 'lsp_open_workspace');
+
       this.eventUnlisten = api.listen<LspEvent>('lsp-event', (payload) => {
         this.handleLspEvent(payload);
       });
@@ -128,15 +171,50 @@ export class WorkspaceLspManager {
       this.isInitialized = true;
       log.info('LSP initialized', { workspacePath: this.workspacePath });
     } catch (error) {
-      log.error('LSP initialization failed', { workspacePath: this.workspacePath, error });
+      if (isSurfaceChangedError(error)) {
+        log.debug('LSP initialization abandoned after a device surface switch', {
+          workspacePath: this.workspacePath,
+        });
+      } else {
+        log.error('LSP initialization failed', { workspacePath: this.workspacePath, error });
+      }
       throw error;
     }
   }
+
+  /**
+   * A manager belongs to the device it was created for. Once the window renders
+   * another one, this manager must issue nothing further: its language servers
+   * keep serving the device we left, and its requests would otherwise be
+   * answered by the device we moved to.
+   */
+  private assertRendersActiveSurface(scope: SurfaceScope, action: string): void {
+    if (this.detached || this.surfaceId !== scope.surfaceId || !scope.isCurrent()) {
+      throw new SurfaceChangedError(this.surfaceId, scope.epoch, action);
+    }
+  }
+
+  /**
+   * The manager itself owns a surface, so checking only ApiClient's request
+   * epoch is insufficient: an old component can call a detached manager after
+   * the new surface is already active. All LSP traffic passes this ownership
+   * boundary before and after its await.
+   */
+  private async invokeForActiveSurface<T = any>(
+    action: string,
+    args?: Record<string, unknown>,
+  ): Promise<T> {
+    const scope = getActiveSurfaceScope();
+    this.assertRendersActiveSurface(scope, action);
+    const result = await api.invoke<T>(action, args);
+    this.assertRendersActiveSurface(scope, action);
+    return result;
+  }
   
   
   private handleLspEvent(event: LspEvent) {
 
-    if (event.data.workspace_path !== this.workspacePath) {
+    if (this.detached || event.data.workspace_path !== this.workspacePath) {
       return;
     }
 
@@ -385,7 +463,9 @@ export class WorkspaceLspManager {
       try {
         await this.initialize();
       } catch (initError) {
-        log.error('Failed to initialize manager', { workspacePath: this.workspacePath, error: initError });
+        if (!isSurfaceChangedError(initError)) {
+          log.error('Failed to initialize manager', { workspacePath: this.workspacePath, error: initError });
+        }
         throw initError;
       }
     }
@@ -419,7 +499,7 @@ export class WorkspaceLspManager {
         setTimeout(() => reject(new Error('LSP open document timeout after 30s')), 30000);
       });
       
-      const openPromise = api.invoke('lsp_open_document', {
+      const openPromise = this.invokeForActiveSurface('lsp_open_document', {
         request: {
           workspacePath: this.workspacePath,
           uri,
@@ -443,7 +523,7 @@ export class WorkspaceLspManager {
   
   async changeDocument(uri: string, content: string): Promise<void> {
     try {
-      await api.invoke('lsp_change_document', {
+      await this.invokeForActiveSurface('lsp_change_document', {
         request: {
           workspacePath: this.workspacePath,
           uri,
@@ -458,7 +538,7 @@ export class WorkspaceLspManager {
   
   async saveDocument(uri: string): Promise<void> {
     try {
-      await api.invoke('lsp_save_document', {
+      await this.invokeForActiveSurface('lsp_save_document', {
         request: {
           workspacePath: this.workspacePath,
           uri
@@ -472,7 +552,7 @@ export class WorkspaceLspManager {
   
   async closeDocument(uri: string): Promise<void> {
     try {
-      await api.invoke('lsp_close_document', {
+      await this.invokeForActiveSurface('lsp_close_document', {
         request: {
           workspacePath: this.workspacePath,
           uri
@@ -486,7 +566,7 @@ export class WorkspaceLspManager {
   
   async getCompletions(language: string, uri: string, line: number, character: number): Promise<any[]> {
     try {
-      const result = await api.invoke<any[]>('lsp_get_completions_workspace', {
+      const result = await this.invokeForActiveSurface<any[]>('lsp_get_completions_workspace', {
         request: {
           workspacePath: this.workspacePath,
           language,
@@ -505,7 +585,7 @@ export class WorkspaceLspManager {
   
   async getHover(language: string, uri: string, line: number, character: number): Promise<any> {
     try {
-      return await api.invoke('lsp_get_hover_workspace', {
+      return await this.invokeForActiveSurface('lsp_get_hover_workspace', {
         request: {
           workspacePath: this.workspacePath,
           language,
@@ -530,7 +610,7 @@ export class WorkspaceLspManager {
   
   async gotoDefinition(language: string, uri: string, line: number, character: number): Promise<any> {
     try {
-      return await api.invoke('lsp_goto_definition_workspace', {
+      return await this.invokeForActiveSurface('lsp_goto_definition_workspace', {
         request: {
           workspacePath: this.workspacePath,
           language,
@@ -548,7 +628,7 @@ export class WorkspaceLspManager {
   
   async findReferences(language: string, uri: string, line: number, character: number): Promise<any> {
     try {
-      return await api.invoke('lsp_find_references_workspace', {
+      return await this.invokeForActiveSurface('lsp_find_references_workspace', {
         request: {
           workspacePath: this.workspacePath,
           language,
@@ -566,7 +646,7 @@ export class WorkspaceLspManager {
   
   async getSignatureHelp(language: string, uri: string, line: number, character: number): Promise<any> {
     try {
-      const result = await api.invoke('lsp_get_signature_help_workspace', {
+      const result = await this.invokeForActiveSurface('lsp_get_signature_help_workspace', {
         request: {
           workspacePath: this.workspacePath,
           language,
@@ -601,7 +681,7 @@ export class WorkspaceLspManager {
   
   private async requestDiagnostics(uri: string): Promise<void> {
     try {
-      const diagnostics = await api.invoke<any[]>('lsp_get_diagnostics', {
+      const diagnostics = await this.invokeForActiveSurface<any[]>('lsp_get_diagnostics', {
         request: {
           workspacePath: this.workspacePath,
           uri
@@ -621,7 +701,7 @@ export class WorkspaceLspManager {
   
   async formatDocument(language: string, uri: string, tabSize: number = 2, insertSpaces: boolean = true): Promise<any> {
     try {
-      return await api.invoke('lsp_format_document_workspace', {
+      return await this.invokeForActiveSurface('lsp_format_document_workspace', {
         request: {
           workspacePath: this.workspacePath,
           language,
@@ -646,7 +726,7 @@ export class WorkspaceLspManager {
     endCharacter: number
   ): Promise<any[]> {
     try {
-      return await api.invoke('lsp_get_inlay_hints_workspace', {
+      return await this.invokeForActiveSurface('lsp_get_inlay_hints_workspace', {
         request: {
           workspacePath: this.workspacePath,
           language,
@@ -666,7 +746,7 @@ export class WorkspaceLspManager {
   
   async rename(language: string, uri: string, line: number, character: number, newName: string): Promise<any> {
     try {
-      return await api.invoke('lsp_rename_workspace', {
+      return await this.invokeForActiveSurface('lsp_rename_workspace', {
         request: {
           workspacePath: this.workspacePath,
           language,
@@ -685,7 +765,7 @@ export class WorkspaceLspManager {
   
   async getCodeActions(language: string, uri: string, range: any, context: any): Promise<any> {
     try {
-      return await api.invoke('lsp_get_code_actions_workspace', {
+      return await this.invokeForActiveSurface('lsp_get_code_actions_workspace', {
         request: {
           workspacePath: this.workspacePath,
           language,
@@ -703,7 +783,7 @@ export class WorkspaceLspManager {
   
   async getDocumentSymbols(language: string, uri: string): Promise<any> {
     try {
-      return await api.invoke('lsp_get_document_symbols_workspace', {
+      return await this.invokeForActiveSurface('lsp_get_document_symbols_workspace', {
         request: {
           workspacePath: this.workspacePath,
           language,
@@ -719,7 +799,7 @@ export class WorkspaceLspManager {
   
   async getWorkspaceSymbols(query: string): Promise<any> {
     try {
-      return await api.invoke('lsp_get_workspace_symbols', {
+      return await this.invokeForActiveSurface('lsp_get_workspace_symbols', {
         request: {
           workspacePath: this.workspacePath,
           query
@@ -734,7 +814,7 @@ export class WorkspaceLspManager {
   
   async getDocumentHighlight(language: string, uri: string, line: number, character: number): Promise<any> {
     try {
-      return await api.invoke('lsp_get_document_highlight_workspace', {
+      return await this.invokeForActiveSurface('lsp_get_document_highlight_workspace', {
         request: {
           workspacePath: this.workspacePath,
           language,
@@ -752,7 +832,7 @@ export class WorkspaceLspManager {
   
   async getSemanticTokens(language: string, uri: string): Promise<any> {
     try {
-      return await api.invoke('lsp_get_semantic_tokens_workspace', {
+      return await this.invokeForActiveSurface('lsp_get_semantic_tokens_workspace', {
         request: {
           workspacePath: this.workspacePath,
           language,
@@ -775,7 +855,7 @@ export class WorkspaceLspManager {
     endCharacter: number
   ): Promise<any> {
     try {
-      return await api.invoke('lsp_get_semantic_tokens_range_workspace', {
+      return await this.invokeForActiveSurface('lsp_get_semantic_tokens_range_workspace', {
         request: {
           workspacePath: this.workspacePath,
           language,
@@ -795,7 +875,7 @@ export class WorkspaceLspManager {
   
   async getServerState(language: string): Promise<ServerState | null> {
     try {
-      return await api.invoke<ServerState>('lsp_get_server_state', {
+      return await this.invokeForActiveSurface<ServerState>('lsp_get_server_state', {
         request: {
           workspacePath: this.workspacePath,
           language
@@ -810,7 +890,7 @@ export class WorkspaceLspManager {
   
   async getAllServerStates(): Promise<Record<string, ServerState>> {
     try {
-      return await api.invoke<Record<string, ServerState>>('lsp_get_all_server_states', {
+      return await this.invokeForActiveSurface<Record<string, ServerState>>('lsp_get_all_server_states', {
         request: {
           workspacePath: this.workspacePath
         }
@@ -822,6 +902,12 @@ export class WorkspaceLspManager {
   }
   
   
+  /**
+   * Close the workspace on its host. Only for a real workspace close — a device
+   * surface switch must use `detachForSurfaceSwitch()`, because this runs before
+   * the transport swap and would shut down the language servers of the device
+   * being left.
+   */
   async dispose(): Promise<void> {
     try {
 
@@ -831,13 +917,30 @@ export class WorkspaceLspManager {
       }
 
 
-      await api.invoke('lsp_close_workspace', {
+      await this.invokeForActiveSurface('lsp_close_workspace', {
         request: { workspacePath: this.workspacePath }
       });
-      
+
       this.isInitialized = false;
     } catch (error) {
       log.error('Error during dispose', { workspacePath: this.workspacePath, error });
     }
   }
+
+  /**
+   * Release this manager's frontend state without touching the host. Used when
+   * the rendered device surface changes: the language servers belong to the
+   * device we are leaving and must keep running for its agent.
+   *
+   * `detached` is what stops a component that still holds this instance from
+   * re-initializing it onto the transport of the device we switched to.
+   */
+  detachForSurfaceSwitch(): void {
+    this.detached = true;
+    if (this.eventUnlisten) {
+      this.eventUnlisten();
+      this.eventUnlisten = undefined;
+    }
+    this.isInitialized = false;
+  }
 }
diff --git a/src/web-ui/src/tools/terminal/components/Terminal.scss b/src/web-ui/src/tools/terminal/components/Terminal.scss
index 203ea9bbea..2262399060 100644
--- a/src/web-ui/src/tools/terminal/components/Terminal.scss
+++ b/src/web-ui/src/tools/terminal/components/Terminal.scss
@@ -212,6 +212,17 @@
   }
 }
 
+@media (prefers-reduced-motion: reduce) {
+  .bitfun-terminal__loading-spinner {
+    animation: none;
+  }
+
+  .xterm .xterm-cursor-layer .xterm-cursor {
+    animation: none !important;
+    opacity: 1 !important;
+  }
+}
+
 // xterm.js theme overrides
 .xterm {
   .xterm-screen {
diff --git a/src/web-ui/src/tools/terminal/services/TerminalService.test.ts b/src/web-ui/src/tools/terminal/services/TerminalService.test.ts
new file mode 100644
index 0000000000..c79aaaa2ef
--- /dev/null
+++ b/src/web-ui/src/tools/terminal/services/TerminalService.test.ts
@@ -0,0 +1,102 @@
+// @vitest-environment jsdom
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const invokeMock = vi.hoisted(() => vi.fn());
+const listenMock = vi.hoisted(() => vi.fn(() => () => {}));
+
+vi.mock('@/infrastructure/api/service-api/ApiClient', () => ({
+  api: {
+    invoke: invokeMock,
+    listen: listenMock,
+  },
+}));
+
+vi.mock('@/shared/utils/logger', () => ({
+  createLogger: () => ({
+    debug: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+  }),
+}));
+
+import { TerminalService } from './TerminalService';
+import {
+  activateSurface,
+  resetDeviceSurfaceForTest,
+} from '@/infrastructure/peer-device/deviceSurface';
+
+function freshTerminalService(): TerminalService {
+  (TerminalService as unknown as { instance: TerminalService | null }).instance = null;
+  return TerminalService.getInstance();
+}
+
+describe('TerminalService device surface switching', () => {
+  beforeEach(() => {
+    invokeMock.mockReset();
+    invokeMock.mockResolvedValue(undefined);
+    listenMock.mockReset();
+    listenMock.mockReturnValue(() => {});
+    resetDeviceSurfaceForTest();
+  });
+
+  afterEach(() => {
+    resetDeviceSurfaceForTest();
+  });
+
+  it('leaves the device being left untouched when a switch disconnects', async () => {
+    const unlisten = vi.fn();
+    listenMock.mockReturnValue(unlisten);
+
+    const service = freshTerminalService();
+    await service.connect();
+    invokeMock.mockClear();
+
+    await service.disconnect();
+
+    expect(invokeMock).not.toHaveBeenCalled();
+    expect(unlisten).toHaveBeenCalledTimes(1);
+    expect(service.isConnected()).toBe(false);
+  });
+
+  it('drops terminal events produced by the device the window left', async () => {
+    let emitTerminalEvent: ((payload: unknown) => void) | null = null;
+    listenMock.mockImplementation((_event: string, callback: (payload: unknown) => void) => {
+      emitTerminalEvent = callback;
+      return () => {};
+    });
+
+    const service = freshTerminalService();
+    await service.connect();
+
+    const events = vi.fn();
+    service.onEvent(events);
+    activateSurface('peer-device-b');
+
+    emitTerminalEvent?.({
+      type: 'Data',
+      payload: { session_id: 'pty-on-device-a', data: 'still running there' },
+    });
+
+    expect(events).not.toHaveBeenCalled();
+  });
+
+  it('rebinds the event stream when connect is called on a new surface', async () => {
+    const firstUnlisten = vi.fn();
+    const secondUnlisten = vi.fn();
+    listenMock
+      .mockReturnValueOnce(firstUnlisten)
+      .mockReturnValueOnce(secondUnlisten);
+
+    const service = freshTerminalService();
+    await service.connect();
+    activateSurface('peer-device-b');
+    await service.connect();
+
+    expect(listenMock).toHaveBeenCalledTimes(2);
+    expect(firstUnlisten).toHaveBeenCalledTimes(1);
+    expect(service.isConnected()).toBe(true);
+    expect(invokeMock).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/web-ui/src/tools/terminal/services/TerminalService.ts b/src/web-ui/src/tools/terminal/services/TerminalService.ts
index 486880b9d3..e0720b29af 100644
--- a/src/web-ui/src/tools/terminal/services/TerminalService.ts
+++ b/src/web-ui/src/tools/terminal/services/TerminalService.ts
@@ -4,6 +4,10 @@
 
 import { api } from '@/infrastructure/api/service-api/ApiClient';
 import { createLogger } from '@/shared/utils/logger';
+import {
+  getActiveSurfaceScope,
+  type SurfaceScope,
+} from '@/infrastructure/peer-device/deviceSurface';
 import type {
   CreateSessionRequest,
   SessionResponse,
@@ -38,6 +42,9 @@ export class TerminalService {
 
   private connected: boolean = false;
 
+  /** The surface the current event stream is bound to. */
+  private streamScope: SurfaceScope | null = null;
+
   private connectingPromise: Promise<void> | null = null;
 
   private constructor() {
@@ -51,39 +58,67 @@ export class TerminalService {
   }
 
   async connect(): Promise<void> {
-    if (this.connected) return;
+    if (this.connected) {
+      if (this.isStreamCurrent()) return;
+      // The stream belongs to a device this window no longer renders. Drop the
+      // listener only — the PTYs on that device stay up for its agent.
+      this.detachEventStream();
+    }
     if (this.connectingPromise) return this.connectingPromise;
 
-    this.connectingPromise = (async () => {
-      try {
-        this.unlistenFn = api.listen<any>('terminal_event', (payload) => {
-          this.handleTerminalEvent(payload);
-        });
-        this.connected = true;
-        log.debug('Connected to terminal event stream');
-      } catch (error) {
-        log.error('Failed to connect', error);
-        throw error;
-      } finally {
-        this.connectingPromise = null;
-      }
+    const scope = getActiveSurfaceScope();
+    const connecting = (async () => {
+      this.unlistenFn = api.listen<any>('terminal_event', (payload) => {
+        this.handleTerminalEvent(payload);
+      });
+      this.streamScope = scope;
+      this.connected = true;
+      log.debug('Connected to terminal event stream');
     })();
 
-    return this.connectingPromise;
+    // Cleared only after the attempt settles. Clearing it inside the task ran
+    // before this assignment and latched a stale promise, so a reconnect after
+    // a surface switch was answered by a connect that had already finished.
+    this.connectingPromise = connecting;
+    try {
+      await connecting;
+    } catch (error) {
+      log.error('Failed to connect', error);
+      throw error;
+    } finally {
+      if (this.connectingPromise === connecting) {
+        this.connectingPromise = null;
+      }
+    }
   }
 
+  /**
+   * Leave the terminal event stream. Frontend-only, and must stay that way:
+   * this is what a device surface switch calls, it runs before the transport
+   * swaps, so a `terminal_shutdown_all` here would kill the PTYs of the device
+   * being left — including the one an agent turn is running in.
+   */
   async disconnect(): Promise<void> {
+    this.detachEventStream();
+    this.eventListeners.clear();
+    this.globalListeners.clear();
+  }
+
+  private detachEventStream(): void {
     if (this.unlistenFn) {
       this.unlistenFn();
       this.unlistenFn = null;
     }
+    this.streamScope = null;
     this.connected = false;
-    this.eventListeners.clear();
-    this.globalListeners.clear();
+  }
+
+  private isStreamCurrent(): boolean {
+    return this.streamScope?.isCurrent() ?? false;
   }
 
   isConnected(): boolean {
-    return this.connected;
+    return this.connected && this.isStreamCurrent();
   }
 
   /**
@@ -92,6 +127,12 @@ export class TerminalService {
    * Frontend format: { type, sessionId, ... }
    */
   private handleTerminalEvent(rawEvent: any): void {
+    // An event that raced the switch describes a PTY on the device we left;
+    // delivering it here would close tabs and scenes of the one we render now.
+    if (!this.isStreamCurrent()) {
+      return;
+    }
+
     const eventType = rawEvent.type;
     const payload = rawEvent.payload || {};
     const sessionId = payload.session_id;
@@ -242,6 +283,10 @@ export class TerminalService {
     }
   }
 
+  /**
+   * Kill every PTY on the host. Never part of a device surface switch — use
+   * `disconnect()` there; see the comment on it.
+   */
   async shutdownAll(): Promise<void> {
     try {
       await api.invoke('terminal_shutdown_all');
diff --git a/src/web-ui/src/tools/workspace/components/WorkspaceManager.css b/src/web-ui/src/tools/workspace/components/WorkspaceManager.css
index d15c5358fc..46532d9ab9 100644
--- a/src/web-ui/src/tools/workspace/components/WorkspaceManager.css
+++ b/src/web-ui/src/tools/workspace/components/WorkspaceManager.css
@@ -55,7 +55,11 @@
     0 4px 16px var(--bf-appearance-token-color-overlay-black-08),
     inset 0 1px 0 var(--bf-appearance-token-color-overlay-white-12),
     inset 0 -1px 0 var(--bf-appearance-token-color-overlay-white-08);
-  transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+  transition:
+    transform 0.3s cubic-bezier(0.4, 0, 0.2, 1),
+    background-color 0.3s cubic-bezier(0.4, 0, 0.2, 1),
+    border-color 0.3s cubic-bezier(0.4, 0, 0.2, 1),
+    box-shadow 0.3s cubic-bezier(0.4, 0, 0.2, 1);
   animation: slideInUp 0.4s ease-out;
 }
 
@@ -127,7 +131,9 @@
   box-shadow:
     0 4px 16px var(--bf-appearance-token-color-accent-300),
     inset 0 1px 0 var(--bf-appearance-token-color-overlay-white-20);
-  transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+  transition:
+    transform 0.3s cubic-bezier(0.4, 0, 0.2, 1),
+    box-shadow 0.3s cubic-bezier(0.4, 0, 0.2, 1);
 }
 
 .workspace-icon:hover {
@@ -322,7 +328,10 @@
     color-mix(in srgb, var(--bf-appearance-token-color-accent-600) 2%, transparent) 100%);
   border-radius: 8px;
   border: 1px solid var(--bf-appearance-token-color-accent-100);
-  transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+  transition:
+    transform 0.3s cubic-bezier(0.4, 0, 0.2, 1),
+    background-color 0.3s cubic-bezier(0.4, 0, 0.2, 1),
+    border-color 0.3s cubic-bezier(0.4, 0, 0.2, 1);
 }
 
 .stat-item:hover {
@@ -412,7 +421,19 @@
 }
 
 @media (prefers-reduced-motion: reduce) {
-  .workspace-card {
+  .workspace-card,
+  .workspace-icon,
+  .stat-item {
     transition: none;
   }
+
+  .workspace-card {
+    animation: none;
+  }
+
+  .workspace-card.recent:hover,
+  .workspace-icon:hover,
+  .stat-item:hover {
+    transform: none;
+  }
 }
diff --git a/tests/e2e/specs/l1-chat-scroll-whitespace.spec.ts b/tests/e2e/specs/l1-chat-scroll-whitespace.spec.ts
index 6f4361380e..22bf40d7fe 100644
--- a/tests/e2e/specs/l1-chat-scroll-whitespace.spec.ts
+++ b/tests/e2e/specs/l1-chat-scroll-whitespace.spec.ts
@@ -33,8 +33,8 @@ async function dumpDomDiagnostics(): Promise<void> {
       if (tid && (tid.includes('chat') || tid.includes('session') || tid.includes('message'))) {
         testIdSet.add(tid);
       }
-      if (el.hasAttribute('data-virtuoso-scroller')) {
-        classSet.add('[data-virtuoso-scroller]');
+      if (el.hasAttribute('data-flowchat-scroller')) {
+        classSet.add('[data-flowchat-scroller]');
       }
     }
     // Read data attributes from the messages container
@@ -43,7 +43,7 @@ async function dumpDomDiagnostics(): Promise<void> {
       relevantClasses: Array.from(classSet).sort(),
       relevantTestIds: Array.from(testIdSet).sort(),
       virtualMessageList: !!document.querySelector('.virtual-message-list'),
-      virtuosoScroller: !!document.querySelector('[data-virtuoso-scroller]'),
+      flowChatScroller: !!document.querySelector('[data-flowchat-scroller]'),
       messageListFooter: !!document.querySelector('.message-list-footer'),
       chatInputContainer: !!document.querySelector('[data-testid="chat-input-container"]'),
       sessionScene: !!document.querySelector('.bitfun-session-scene'),
@@ -409,7 +409,7 @@ describe('L1 Chat Scroll Whitespace (#1176)', () => {
   }> {
     return browser.execute(() => {
       // Find the scroller DOM element
-      const scrollerEl = document.querySelector('[data-virtuoso-scroller]') as HTMLElement | null;
+      const scrollerEl = document.querySelector('[data-flowchat-scroller]') as HTMLElement | null;
       const footer = document.querySelector('.message-list-footer') as HTMLElement | null;
 
       // Try to find the React component instance via fiber
@@ -491,7 +491,7 @@ describe('L1 Chat Scroll Whitespace (#1176)', () => {
       // Strategy: Walk the fiber tree from DOM elements inside VirtualMessageList,
       // then traverse the hooks chain to find bottomReservationStateRef.
       const rootCandidates = [
-        document.querySelector('[data-virtuoso-scroller]'),
+        document.querySelector('[data-flowchat-scroller]'),
         document.querySelector('.virtual-message-list'),
         document.querySelector('.message-list-footer'),
       ];
@@ -569,7 +569,7 @@ describe('L1 Chat Scroll Whitespace (#1176)', () => {
       // Force layout reflow
       void footer.offsetHeight;
 
-      const scroller = document.querySelector('[data-virtuoso-scroller]') as HTMLElement | null;
+      const scroller = document.querySelector('[data-flowchat-scroller]') as HTMLElement | null;
       if (scroller) void scroller.scrollHeight;
 
       return true;
@@ -587,7 +587,7 @@ describe('L1 Chat Scroll Whitespace (#1176)', () => {
   }> {
     return browser.execute(() => {
       const el = (
-        document.querySelector('[data-virtuoso-scroller]') ||
+        document.querySelector('[data-flowchat-scroller]') ||
         document.querySelector('.virtual-message-list__static-scroller') ||
         document.querySelector('.virtual-message-list')
       ) as HTMLElement | null;
@@ -634,7 +634,7 @@ describe('L1 Chat Scroll Whitespace (#1176)', () => {
 
     // Verify scroller exists
     const scrollerExists = await browser.execute(() => {
-      return !!document.querySelector('[data-virtuoso-scroller]');
+      return !!document.querySelector('[data-flowchat-scroller]');
     });
     expect(scrollerExists).toBe(true);
 
diff --git a/tests/e2e/specs/l1-chat-turn-navigation-release.spec.ts b/tests/e2e/specs/l1-chat-turn-navigation-release.spec.ts
index 9728bf79f0..dd416a5c67 100644
--- a/tests/e2e/specs/l1-chat-turn-navigation-release.spec.ts
+++ b/tests/e2e/specs/l1-chat-turn-navigation-release.spec.ts
@@ -153,7 +153,7 @@ async function readTurnViewportMetrics(targetTurnId: string): Promise<TurnViewpo
       '.modern-flowchat-container__messages .virtual-message-list',
     );
     const scroller = root?.querySelector<HTMLElement>(
-      '[data-virtuoso-scroller="true"], [data-virtuoso-scroller], .virtual-message-list__static-scroller',
+      '[data-flowchat-scroller], .virtual-message-list__static-scroller',
     ) ?? null;
     const wrappers = Array.from(root?.querySelectorAll<HTMLElement>(
       '.virtual-item-wrapper[data-turn-id]',
@@ -237,7 +237,7 @@ async function waitForSessionHydrated(): Promise<void> {
         '.modern-flowchat-container__messages .virtual-message-list',
       );
       const scroller = root?.querySelector<HTMLElement>(
-        '[data-virtuoso-scroller="true"], [data-virtuoso-scroller], .virtual-message-list__static-scroller',
+        '[data-flowchat-scroller], .virtual-message-list__static-scroller',
       ) ?? null;
       const items = root?.querySelectorAll('.virtual-item-wrapper[data-turn-id]') ?? [];
       return {
@@ -298,8 +298,7 @@ async function readHeaderTurnListTexts(): Promise<string[]> {
 async function scrollToPreviousHistoryBoundary(): Promise<void> {
   await browser.execute(() => {
     const scroller = document.querySelector<HTMLElement>(
-      '.modern-flowchat-container__messages .virtual-message-list [data-virtuoso-scroller="true"], ' +
-      '.modern-flowchat-container__messages .virtual-message-list [data-virtuoso-scroller], ' +
+      '.modern-flowchat-container__messages .virtual-message-list [data-flowchat-scroller], ' +
       '.modern-flowchat-container__messages .virtual-message-list .virtual-message-list__static-scroller',
     );
     if (!scroller) {
@@ -362,8 +361,7 @@ async function revealHistoryUntilTurnListContains(targetTitle: string): Promise<
 async function scrollToLatest(targetTurnId: string): Promise<TurnViewportMetrics> {
   await browser.execute(() => {
     const scroller = document.querySelector<HTMLElement>(
-      '.modern-flowchat-container__messages .virtual-message-list [data-virtuoso-scroller="true"], ' +
-      '.modern-flowchat-container__messages .virtual-message-list [data-virtuoso-scroller], ' +
+      '.modern-flowchat-container__messages .virtual-message-list [data-flowchat-scroller], ' +
       '.modern-flowchat-container__messages .virtual-message-list .virtual-message-list__static-scroller',
     );
     if (!scroller) {
diff --git a/tests/e2e/specs/performance/startup-session-perf.spec.ts b/tests/e2e/specs/performance/startup-session-perf.spec.ts
index 673504ba41..201ab2f218 100644
--- a/tests/e2e/specs/performance/startup-session-perf.spec.ts
+++ b/tests/e2e/specs/performance/startup-session-perf.spec.ts
@@ -1013,7 +1013,7 @@ async function readLongSessionViewportState(expectedLatestTurnId?: string | null
       '.modern-flowchat-container__messages .virtual-message-list',
     );
     const scroller = root?.querySelector<HTMLElement>(
-      '[data-virtuoso-scroller="true"], [data-virtuoso-scroller]',
+      '[data-flowchat-scroller]',
     ) ?? null;
     const staticScroller = root?.querySelector<HTMLElement>('.virtual-message-list__static-scroller') ?? null;
     const staticItems = root?.querySelector<HTMLElement>('.virtual-message-list__static-items') ?? null;
@@ -1642,7 +1642,7 @@ async function startLongSessionViewportTimelineRecorder(
         };
       }
 
-      if (element.closest('[data-virtuoso-scroller], .virtual-message-list')) {
+      if (element.closest('[data-flowchat-scroller], .virtual-message-list')) {
         return {
           category: 'list-blank',
           itemType: null,
@@ -1839,7 +1839,7 @@ async function startLongSessionViewportTimelineRecorder(
         messages?.querySelectorAll<HTMLElement>('.virtual-message-list') ?? []
       );
       const scroller = messages?.querySelector<HTMLElement>(
-        '[data-virtuoso-scroller="true"], [data-virtuoso-scroller]',
+        '[data-flowchat-scroller]',
       ) ?? null;
       const virtualItems = Array.from(
         scroller?.querySelectorAll<HTMLElement>('.virtual-item-wrapper[data-turn-id]') ?? []
@@ -1946,7 +1946,7 @@ async function startLongSessionViewportTimelineRecorder(
         '.modern-flowchat-container__messages .virtual-message-list',
       );
       const scroller = root?.querySelector<HTMLElement>(
-        '[data-virtuoso-scroller="true"], [data-virtuoso-scroller]',
+        '[data-flowchat-scroller]',
       ) ?? null;
       const footer = scroller?.querySelector<HTMLElement>('.message-list-footer') ?? null;
       const footerRect = footer?.getBoundingClientRect() ?? null;
@@ -2351,7 +2351,7 @@ async function startLongSessionViewportTimelineRecorder(
         '.modern-flowchat-container__messages .virtual-message-list',
       );
       const scroller = root?.querySelector<HTMLElement>(
-        '[data-virtuoso-scroller="true"], [data-virtuoso-scroller]',
+        '[data-flowchat-scroller]',
       ) ?? null;
       const inputOverlay = document.querySelector<HTMLElement>('.bitfun-chat-input-drop-zone');
       const scrollerRect = scroller?.getBoundingClientRect() ?? null;
@@ -3809,8 +3809,7 @@ async function readLongSessionScrollerMetrics(): Promise<{
 }> {
   return browser.execute(() => {
     const scroller = document.querySelector<HTMLElement>(
-      '.modern-flowchat-container__messages [data-virtuoso-scroller="true"], ' +
-      '.modern-flowchat-container__messages [data-virtuoso-scroller]',
+      '.modern-flowchat-container__messages [data-flowchat-scroller]',
     );
     if (!scroller) {
       throw new Error('Could not find long-session scroller for post-visible interaction');
@@ -3882,8 +3881,7 @@ async function performLongSessionPostVisibleInteraction(
 
   return browser.execute((interactionType) => {
     const scroller = document.querySelector<HTMLElement>(
-      '.modern-flowchat-container__messages [data-virtuoso-scroller="true"], ' +
-      '.modern-flowchat-container__messages [data-virtuoso-scroller]',
+      '.modern-flowchat-container__messages [data-flowchat-scroller]',
     );
     if (!scroller) {
       throw new Error('Could not find long-session scroller for first-scroll interaction');